-->Java Native I/O

Documentation

Overview

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.

Struct Type Declaration

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).

General Visibility

All declared structs and its fields have to be accessible (i.e. public). Fields with access restrictions and fields or nested structs (see below) which are declared 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;
    }
    

Fields of Scalar Type

All primitive Java types are mapped to a corresponding C type.

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

Fields of Structured Type

Structs can contain fields of structured type. For example struct A has a field of type B:

	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;
	}
	

Fields of Array Types

Arrays have to be of certain length, which is declared in an annotation of type @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.

Fields of Special Type

There are certain special types, not supported by the code generator. Special are those types, which do not have a corresponding C type. For example immutable types, such as all Java classes corresponding to Java primitive types (e.g. 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.

Data Views

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.

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).