|
| |
|
| java.lang.Object
 javolution.io.Struct
All known Subclasses: javolution.io.Union,
| Struct | | public class Struct (Code) | | This class represents a C/C++ struct; it confers
interoperability between Java classes and C/C++ struct.
Unlike C/C++, the storage layout of Java objects is not
determined by the compiler. The layout of objects in memory is deferred
to run time and determined by the interpreter (or just-in-time compiler).
This approach allows for dynamic loading and binding; but also makes
interfacing with C/C++ code difficult. Hence, this class for
which the memory layout is defined by the initialization order of the
Struct 's
Member members and follows the same alignment
rules as C/C++ structs.
This class (as well as the
Union sub-class) facilitates:
- Memory sharing between Java applications and native libraries.
- Direct encoding/decoding of streams for which the structure
is defined by legacy C/C++ code.
- Serialization/deserialization of Java objects (complete control,
e.g. no class header)
- Mapping of Java objects to physical addresses (with JNI).
Because of its one-to-one mapping, it is relatively easy to convert C
header files (e.g. OpenGL bindings) to Java
Struct /
Union using simple text macros. Here is an example of C struct: struct Date {
unsigned short year;
unsigned byte month;
unsigned byte day;
};
struct Student {
char name[64];
struct Date birth;
float grades[10];
Student* next;
};
and here is the Java equivalent using this class:[code]
public static class Date extends Struct {
public final Unsigned16 year = new Unsigned16();
public final Unsigned8 month = new Unsigned8();
public final Unsigned8 day = new Unsigned8();
}
public static class Student extends Struct {
public final Utf8String name = new UTF8String(64);
public final Date birth = inner(new Date());
public final Float32[] grades = array(new Float32[10]);
public final Reference32 next = new Reference32();
}[/code]
Struct's members are directly accessible:[code]
Student student = new Student();
student.name.set("John Doe"); // Null terminated (C compatible)
int age = 2003 - student.birth.year.get();
student.grades[2].set(12.5f);
student = student.next.get();[/code]
Applications may also work with the raw
Struct.getByteBuffer() bytes directly. The following illustrate how
Struct can be used to
decode/encode UDP messages directly:[code]
class UDPMessage extends Struct {
Unsigned16 xxx = new Unsigned16();
...
}
public void run() {
byte[] bytes = new byte[1024];
DatagramPacket packet = new DatagramPacket(bytes, bytes.length);
UDPMessage message = new UDPMessage();
message.setByteBuffer(ByteBuffer.wrap(bytes), 0);
// packet and message are now two different views of the same data.
while (isListening) {
multicastSocket.receive(packet);
int xxx = message.xxx.get();
... // Process message fields directly.
}
}[/code]
It is relatively easy to map instances of this class to any physical
address using
JNI. Here is an example:[code]
import java.nio.ByteBuffer;
class Clock extends Struct { // Hardware clock mapped to memory.
Unsigned16 seconds = new Unsigned16(5); // unsigned short seconds:5
Unsigned16 minutes = new Unsigned16(5); // unsigned short minutes:5
Unsigned16 hours = new Unsigned16(4); // unsigned short hours:4
Clock() {
setByteBuffer(Clock.nativeBuffer(), 0);
}
private static native ByteBuffer nativeBuffer();
}[/code]
Below is the nativeBuffer() implementation
(Clock.c):[code]
#include
#include "Clock.h" // Generated using javah
JNIEXPORT jobject JNICALL Java_Clock_nativeBuffer (JNIEnv *env, jclass) {
return (*env)->NewDirectByteBuffer(env, clock_address, buffer_size)
}[/code]
Bit-fields are supported (see Clock example above).
Bit-fields allocation order is defined by the Struct
Struct.byteOrder return value (leftmost bit to rightmost bit if
BIG_ENDIAN and rightmost bit to leftmost bit if
LITTLE_ENDIAN).
Unless the Struct
Struct.isPacked packing directive is overriden,
bit-fields cannot straddle the storage-unit boundary as defined by their
base type (padding is inserted at the end of the first bit-field
and the second bit-field is put into the next storage unit).
Finally, it is possible to change the
Struct.setByteBuffer ByteBuffer
and/or the Struct
Struct.setByteBufferPosition position in its
ByteBuffer to allow for a single
Struct object to
encode/decode multiple memory mapped instances.
Note: Because Struct/Union are basically wrappers around
java.nio.ByteBuffer, tutorials/usages for
the Java NIO package are directly applicable to Struct.
author:
Jean-Marie Dautelle
version:
5.1, July 17, 2007 |
| Inner Class :protected class Member | |
| Inner Class :public class UTF8String extends Member | |
| Inner Class :public class Bool extends Member | |
| Inner Class :public class Signed8 extends Member | |
| Inner Class :public class Unsigned8 extends Member | |
| Inner Class :public class Signed16 extends Member | |
| Inner Class :public class Unsigned16 extends Member | |
| Inner Class :public class Signed32 extends Member | |
| Inner Class :public class Unsigned32 extends Member | |
| Inner Class :public class Signed64 extends Member | |
| Inner Class :public class Float32 extends Member | |
| Inner Class :public class Float64 extends Member | |
| Inner Class :public class Reference32 extends Member | |
| Inner Class :public class Reference64 extends Member | |
| Inner Class :public class Enum8 extends Member | |
| Inner Class :public class Enum16 extends Member | |
| Inner Class :public class Enum32 extends Member | |
| Inner Class :public class Enum64 extends Member | |
| Constructor Summary | |
| public | Struct()
Default constructor. |
| Method Summary | |
| final public long | address()
Returns this struct address. | | protected Struct[] | array(Struct[] structs)
Defines the specified array of structs as inner structs. | | protected Struct[][] | array(Struct[][] structs)
Defines the specified two-dimensional array of structs as inner
structs. | | protected Struct[][][] | array(Struct[][][] structs)
Defines the specified three dimensional array of structs as inner
structs. | | protected Member[] | array(Member[] arrayMember)
Defines the specified array member. | | protected Member[][] | array(Member[][] arrayMember)
Defines the specified two-dimensional array member. | | protected Member[][][] | array(Member[][][] arrayMember)
Defines the specified three-dimensional array member. | | protected UTF8String[] | array(UTF8String[] array, int stringLength)
Defines the specified array of UTF-8 strings, all strings having the
specified length (convenience method).
Parameters:
array - the string array.
Parameters:
stringLength - the length of the string elements. | | public ByteOrder | byteOrder()
Returns the byte order for this struct (configurable). | | final public ByteBuffer | getByteBuffer()
Returns the byte buffer for this struct. | | final public int | getByteBufferPosition()
Returns the absolute position of this struct within its associated
Struct.getByteBuffer byte buffer .
the absolute position of this struct in the byte buffer. | | protected Struct | inner(Struct struct)
Defines the specified struct as inner of this struct.
Parameters:
struct - the inner struct. | | public boolean | isPacked()
Indicates if this struct is packed (configurable).
By default,
Member members of a struct are aligned on the
boundary corresponding to the member base type; padding is performed
if necessary. | | public boolean | isUnion()
Indicates if this struct's members are mapped to the same location
in memory (default false). | | public int | read(InputStream in)
Reads this struct from the specified input stream
(convenience method when using Stream I/O). | | final public Struct | setByteBuffer(ByteBuffer byteBuffer, int position)
Sets the current byte buffer for this struct.
The specified byte buffer can be mapped to memory for direct memory
access or can wrap a shared byte array for I/O purpose
(e.g. | | final public Struct | setByteBufferPosition(int position)
Sets the position of this struct within its byte buffer.
Parameters:
position - the position of this struct in its byte buffer. | | final public int | size()
Returns the size in bytes of this struct. | | public String | toString()
Returns the String representation of this struct
in the form of its constituing bytes (hexadecimal). | | public void | write(OutputStream out)
Writes this struct to the specified output stream
(convenience method when using Stream I/O). |
| MAXIMUM_ALIGNMENT | | final public static Configurable MAXIMUM_ALIGNMENT(Code) | | Configurable holding the maximum alignment in bytes
(default 4).
|
| Struct | | public Struct()(Code) | | Default constructor.
|
| address | | final public long address()(Code) | | Returns this struct address. This method allows for structs
to be referenced (e.g. pointer) from other structs.
the struct memory address.
throws:
UnsupportedOperationException - if the struct buffer is not a direct buffer.
See Also: Reference32
See Also: Reference64 |
| array | | protected Struct[] array(Struct[] structs)(Code) | | Defines the specified array of structs as inner structs.
The array is populated if necessary using the struct component
default constructor (which must be public).
Parameters:
structs - the struct array. the specified struct array.
throws:
IllegalArgumentException - if the specified array contains inner structs. |
| array | | protected Struct[][] array(Struct[][] structs)(Code) | | Defines the specified two-dimensional array of structs as inner
structs. The array is populated if necessary using the struct component
default constructor (which must be public).
Parameters:
structs - the two dimensional struct array. the specified struct array.
throws:
IllegalArgumentException - if the specified array contains inner structs. |
| array | | protected Struct[][][] array(Struct[][][] structs)(Code) | | Defines the specified three dimensional array of structs as inner
structs. The array is populated if necessary using the struct component
default constructor (which must be public).
Parameters:
structs - the three dimensional struct array. the specified struct array.
throws:
IllegalArgumentException - if the specified array contains inner structs. |
| array | | protected Member[] array(Member[] arrayMember)(Code) | | Defines the specified array member. For predefined members,
the array is populated when empty; custom members should use
literal (populated) arrays.
Parameters:
arrayMember - the array member. the specified array member.
throws:
UnsupportedOperationException - if the specified array is empty and the member type is unknown. |
| array | | protected Member[][] array(Member[][] arrayMember)(Code) | | Defines the specified two-dimensional array member. For predefined
members, the array is populated when empty; custom members should use
literal (populated) arrays.
Parameters:
arrayMember - the two-dimensional array member. the specified array member.
throws:
UnsupportedOperationException - if the specified array is empty and the member type is unknown. |
| array | | protected Member[][][] array(Member[][][] arrayMember)(Code) | | Defines the specified three-dimensional array member. For predefined
members, the array is populated when empty; custom members should use
literal (populated) arrays.
Parameters:
arrayMember - the three-dimensional array member. the specified array member.
throws:
UnsupportedOperationException - if the specified array is empty and the member type is unknown. |
| array | | protected UTF8String[] array(UTF8String[] array, int stringLength)(Code) | | Defines the specified array of UTF-8 strings, all strings having the
specified length (convenience method).
Parameters:
array - the string array.
Parameters:
stringLength - the length of the string elements. the specified string array. |
| byteOrder | | public ByteOrder byteOrder()(Code) | | Returns the byte order for this struct (configurable).
The byte order is inherited by inner structs. Sub-classes may change
the byte order by overriding this method. For example:[code]
public class TopStruct extends Struct {
... // Members initialization.
public ByteOrder byteOrder() {
// TopStruct and its inner structs use hardware byte order.
return ByteOrder.nativeOrder();
}
}}[/code]
the byte order when reading/writing multibyte values(default: network byte order, BIG_ENDIAN). |
| getByteBuffer | | final public ByteBuffer getByteBuffer()(Code) | | Returns the byte buffer for this struct. This method will allocate
a new direct buffer if none has been set.
Changes to the buffer's content are visible in this struct,
and vice versa.
The buffer of an inner struct is the same as its parent struct.
The position of a
Struct.Member struct's member within the
byte buffer is given by
Struct.Member.positionmember.position()
the current byte buffer or a new direct buffer if none set.
See Also: Struct.setByteBuffer |
| getByteBufferPosition | | final public int getByteBufferPosition()(Code) | | Returns the absolute position of this struct within its associated
Struct.getByteBuffer byte buffer .
the absolute position of this struct in the byte buffer. |
| inner | | protected Struct inner(Struct struct)(Code) | | Defines the specified struct as inner of this struct.
Parameters:
struct - the inner struct. the specified struct.
throws:
IllegalArgumentException - if the specified struct is already an inner struct. |
| isPacked | | public boolean isPacked()(Code) | | Indicates if this struct is packed (configurable).
By default,
Member members of a struct are aligned on the
boundary corresponding to the member base type; padding is performed
if necessary. This directive is inherited by inner structs.
Sub-classes may change the packing directive by overriding this method.
For example:[code]
public class TopStruct extends Struct {
... // Members initialization.
public boolean isPacked() {
// TopStruct and its inner structs are packed.
return true;
}
}}[/code]
true if alignment requirements are ignored.false otherwise (default). |
| isUnion | | public boolean isUnion()(Code) | | Indicates if this struct's members are mapped to the same location
in memory (default false). This method is useful for
applications extending
Struct with new member types in order to
create unions from these new structs. For example:[code]
public abstract class FortranStruct extends Struct {
public class FortranString extends Member {...}
protected FortranString[] array(FortranString[] array, int stringLength) { ... }
}
public abstract class FortranUnion extends FortranStruct {
// Inherits new members and methods.
public final isUnion() {
return true;
}
}[/code]
true if this struct's members are mapped to to the same location in memory; false otherwise.
See Also: Union |
| read | | public int read(InputStream in) throws IOException(Code) | | Reads this struct from the specified input stream
(convenience method when using Stream I/O). For better performance,
use of Block I/O (e.g. java.nio.channels.*) is recommended.
Parameters:
in - the input stream being read from. the number of bytes read (typically the Struct.size() sizeof this struct.
throws:
IOException - if an I/O error occurs. |
| setByteBuffer | | final public Struct setByteBuffer(ByteBuffer byteBuffer, int position)(Code) | | Sets the current byte buffer for this struct.
The specified byte buffer can be mapped to memory for direct memory
access or can wrap a shared byte array for I/O purpose
(e.g. DatagramPacket).
Parameters:
byteBuffer - the new byte buffer.
Parameters:
position - the position of this struct in the specified byte buffer. this
throws:
IllegalArgumentException - if the specified byteBuffer has a different byte order than this struct.
throws:
UnsupportedOperationException - if this struct is an inner struct.
See Also: Struct.byteOrder()
See Also: |
| setByteBufferPosition | | final public Struct setByteBufferPosition(int position)(Code) | | Sets the position of this struct within its byte buffer.
Parameters:
position - the position of this struct in its byte buffer. this
throws:
UnsupportedOperationException - if this struct is an inner struct. |
| size | | final public int size()(Code) | | Returns the size in bytes of this struct. The size includes
tail padding to satisfy the struct alignment requirement
(defined by the largest alignment of its
Member members ).
the C/C++ sizeof(this). |
| toString | | public String toString()(Code) | | Returns the String representation of this struct
in the form of its constituing bytes (hexadecimal). For example:[code]
public static class Student extends Struct {
Utf8String name = new Utf8String(16);
Unsigned16 year = new Unsigned16();
Float32 grade = new Float32();
}
Student student = new Student();
student.name.set("John Doe");
student.year.set(2003);
student.grade.set(12.5f);
System.out.println(student);
4A 6F 68 6E 20 44 6F 65 00 00 00 00 00 00 00 00
07 D3 00 00 41 48 00 00[/code]
a hexadecimal representation of the bytes content for this struct. |
| write | | public void write(OutputStream out) throws IOException(Code) | | Writes this struct to the specified output stream
(convenience method when using Stream I/O). For better performance,
use of Block I/O (e.g. java.nio.channels.*) is recommended.
Parameters:
out - the output stream to write to.
throws:
IOException - if an I/O error occurs. |
|
|
|