The package org.cakelab.nio.view
provides tools and a method to
access structured data stored in a
java.nio.ByteBuffer
.
The data is considered to be structured in terms of a C struct
,
but its declaration is provided in terms of a Java class with
annotations, if required (see Section Struct Type Declaration).
For each considered struct type exists a view class, which
provides read/write access to the structured data in the buffer.
The view class is either received from the code generator or provided by the user.
A struct type is declared in terms of a corresponding Java class but considered as a C struct. Thus, all declared fields are considered to be values (not references) and have to have a declared size (especially arrays).
static
, final
or
transient
will be ignored. The following example
demonstrates the declaration of a basic struct with two integer values a and b.
public class MyStruct { public int a,b; }
Java | C | size [byte] |
---|---|---|
byte | char | 1 |
boolean | byte | 1 |
char | short | 2 |
short | short | 2 |
int | int | 4 |
long | long | 8 |
float | float | 4 |
double | double | 8 |
public class B { public int a,c; } public class A { public B b; }If B is a member class of A, than it has to be accessible (i.e.
public static
) as shown in the following example:
public class A { public static class B { public int a,c; } public B b; }
@nio
(see org.cakelab.nio.view.annotations.nio).
The following example declares a field b
with type
integer array of length 4 and a field with a two-dimensional array of structs:
public class A { @nio(length=4) public int[] b; @nio(length={2,2}) public MyStruct[][] c; }See the
length
attribute in annotation @nio
for more information.
java.lang.Integer
,
java.lang.Double
, etc.) and especially java.lang.String
,
which is actually an array of 2 byte size char values. Support of those types can be
integrated by user implemented views, which will be explained in a Section below.
The view class provides methods to access the data in a byte buffer. A view class is supposed to be created with the code generator (see org.cakelab.nio.view.generator), but can be provided by the user as well.
There are generally no view classes for scalar types, since those are usually directly mapped to Java primitive types. For other purposes, there are interfaces for for all Java primitive types (see org.cakelab.nio.view.scalar) to implement different views on primitives if needed.
There are standard implementations for views on arrays. Arrays with elements of structured type and multidimensional arrays will get a view of the generic type org.cakelab.nio.array.CArrayView. One-dimensional arrays with scalar element type will get a view for that specific array type.
At first, a view class implements all basic methods declared in DataView
to attach/detach
(open/close) a buffer to a view, adjust the offset and access (read/write, i.e. get/set)
the whole structure. The getter method of the basic interface requires to instantiate a new
Java object, which is initialised with the data read from the buffer. If a type is reusable,
which basically means, that it is not immutable and not of scalar type, then the view
will also provide a method to retrieve data into an object, which already exists
(see org.cakelab.nio.view.ReusableDataView#get(T result)). The same applies to fields of classes
or elements of arrays which have an reusable data type (more on that below).
public MyStructView implements ReusableDataView<MyStruct> { public void open(ByteBuffer buffer); public void open(ByteBuffer buffer, int at_offset); public void close(); public int sizeof(); // size of entire struct public MyStruct get(); // returns a new instance with copy of buffer public MyStruct get(MyStruct result); // copies content of buffer in result public void set(MyStruct value); // writes value to buffer // .. followed by member access methods }
Beyond that, a generated view class has methods to access each individual member and members of members or elements of arrays. The following table provides an overview of generated member access methods.
Kind of Field | Example | Methods |
---|---|---|
Primitive | public int abc; | void setAbc(int value) |
Structured | public T abc; | void setAbc(T value) |
Array<Primitive> | public int[] abc; | void setAbc(int[] value) |
Array<Structured> | public T[] abc; | void setAbc(T[] value) |
Furthermore each view on structured types provide methods to retrieve views on fields of compound type or elements of arrays.
The following table lists view*
methods generated for fields and array elements. In this table V
denotes
the type of view (i.e. a class derived from DataView<T> if T
is the Java type).
Kind of Field | Example | Methods |
---|---|---|
Structured | public T abc; | V viewAbc() |
Array<Primitive> | public int[] abc; | intArrayView viewAbc() |
Array<Structured> | public T[] abc; | CArrayView<T,V> viewAbc() |