Struct (soss-jnc-5.10 API)

java.lang.Object
- com.scaleoutsoftware.soss.client.util.Struct

Direct Known Subclasses:

SossStruct, Union
```
public class Struct
extends java.lang.Object
```
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 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:
```
 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<Student> next =  new Reference32<Student>();
 }
```
Struct's members are directly accessible:
```
 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();
```
Applications may also work with the raw bytes directly. The following illustrate how Struct can be used to decode/encode UDP messages directly:
```
 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.
 }
 }
```
It is relatively easy to map instances of this class to any physical address using JNI. Here is an example:
```
 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();
 }
```
Below is the nativeBuffer() implementation (Clock.c):
```
 #include <jni.h>
 #include "Clock.h" // Generated using javah
 JNIEXPORT jobject JNICALL Java_Clock_nativeBuffer (JNIEnv *env, jclass) {
 return (*env)->NewDirectByteBuffer(env, clock_address, buffer_size)
 }
```
Bit-fields are supported (see Clock example above). Bit-fields allocation order is defined by the Struct byteOrder() return value (leftmost bit to rightmost bit if BIG_ENDIAN and rightmost bit to leftmost bit if LITTLE_ENDIAN). Unless the Struct 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 ByteBuffer and/or the Struct 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.

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`class`	`Struct.Bool` This class represents a 8 bits boolean with `true` represented by `1` and `false` represented by `0`.
`class`	`Struct.Enum16` This class represents a 16 bits `Enum`.
`class`	`Struct.Enum32` This class represents a 32 bits `Enum`.
`class`	`Struct.Enum64` This class represents a 64 bits `Enum`.
`class`	`Struct.Enum8` This class represents a 8 bits `Enum`.
`class`	`Struct.Float32` This class represents a 32 bits float (C/C++/Java `float`).
`class`	`Struct.Float64` This class represents a 64 bits float (C/C++/Java `double`).
`static interface`	`Struct.InstanceFactory<S>` A factory callback that may be supplied to the `array(Struct[], com.scaleoutsoftware.soss.client.util.Struct.InstanceFactory)` method to allow callers to construct their own `Struct` and `Struct.Member` instances as needed.
`protected class`	`Struct.Member` This inner class represents the base class for all `Struct` members.
`class`	`Struct.Reference32<S extends Struct>` This class represents a 32 bits reference (C/C++ pointer) to a `Struct` object (other types may require a `Struct` wrapper).
`class`	`Struct.Reference64<S extends Struct>` This class represents a 64 bits reference (C/C++ pointer) to a `Struct` object (other types may require a `Struct` wrapper).
`class`	`Struct.Signed16` This class represents a 16 bits signed integer.
`class`	`Struct.Signed32` This class represents a 32 bits signed integer.
`class`	`Struct.Signed64` This class represents a 64 bits signed integer.
`class`	`Struct.Signed8` This class represents a 8 bits signed integer.
`class`	`Struct.Unsigned16` This class represents a 16 bits unsigned integer.
`class`	`Struct.Unsigned32` This class represents a 32 bits unsigned integer.
`class`	`Struct.Unsigned8` This class represents a 8 bits unsigned integer.
`class`	`Struct.UTF8String` This class represents a UTF-8 character string, null terminated (for C/C++ compatibility)

Constructor Summary

Constructors
Constructor and Description

Struct()
Default constructor.

Constructors
Constructor and Description
`Struct()` Default constructor.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`long`	`address()` Returns this struct address.
`protected <M extends Struct.Member> M[]`	`array(M[] arrayMember)` Defines the specified array member.
`protected <M extends Struct.Member> M[][]`	`array(M[][] arrayMember)` Defines the specified two-dimensional array member.
`protected <M extends Struct.Member> M[][][]`	`array(M[][][] arrayMember)` Defines the specified three-dimensional array member.
`protected <M extends Struct.Member> M[]`	`array(M[] arrayMember, Struct.InstanceFactory<M> factory)` Defines the specified array member.
`protected <S extends Struct> S[]`	`array(S[] structs)` Defines the specified array of structs as inner structs.
`protected <S extends Struct> S[][]`	`array(S[][] structs)` Defines the specified two-dimensional array of structs as inner structs.
`protected <S extends Struct> S[][][]`	`array(S[][][] structs)` Defines the specified three dimensional array of structs as inner structs.
`protected <S extends Struct> S[]`	`array(S[] structs, Struct.InstanceFactory<S> factory)`
`protected Struct.UTF8String[]`	`array(Struct.UTF8String[] array, int stringLength)` Defines the specified array of UTF-8 strings, all strings having the specified length (convenience method).
`java.nio.ByteOrder`	`byteOrder()` Returns the byte order for this struct (configurable).
`protected <M extends Struct.Member> void`	`fillArray(M[] arrayMember)` Fill the parameter arrayMember with values of type M.
`protected <M extends Struct.Member> void`	`fillArray(M[] arrayMember, Struct.InstanceFactory<M> factory)` Fill the array `arrayMember` with instances of type M created by the instance factory `factory`.
`protected <S extends Struct> void`	`fillArray(S[] structs)` Fill the array, structs, with instances so that space in the struct is appropriately consumed.
`protected <S extends Struct> void`	`fillArray(S[] structs, Struct.InstanceFactory<S> factory)` Fill the array `factory` with instances of type S created by the instance factory `factory`.
`java.nio.ByteBuffer`	`getByteBuffer()` Returns the byte buffer for this struct.
`int`	`getByteBufferPosition()` Returns the absolute position of this struct within its associated `byte buffer`.
`protected <S extends Struct> S`	`inner(S struct)` Defines the specified struct as inner of this struct.
`boolean`	`isPacked()` Indicates if this struct is packed (configurable).
`boolean`	`isUnion()` Indicates if this struct's members are mapped to the same location in memory (default `false`).
`protected java.nio.ByteBuffer`	`newBuffer(int capacity)`
`protected Struct`	`outerStruct()` Returns the outer struct if any.
`int`	`read(java.io.InputStream in)` Reads this struct from the specified input stream (convenience method when using Stream I/O).
`Struct`	`setByteBuffer(java.nio.ByteBuffer byteBuffer, int position)` Sets the current byte buffer for this struct.
`Struct`	`setByteBufferPosition(int position)` Sets the position of this struct within its byte buffer.
`int`	`size()` Returns the size in bytes of this struct.
`java.lang.String`	`toString()` Returns the `String` representation of this struct in the form of its constituing bytes (hexadecimal).
`void`	`write(java.io.OutputStream out)` Writes this struct to the specified output stream (convenience method when using Stream I/O).

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Constructor Detail
  - Struct
```
public Struct()
```
    Default constructor.
- Method Detail
  - size
```
public final int size()
```
    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 members).
    
    Returns:
    
    the C/C++ sizeof(this).
  - outerStruct
```
protected final Struct outerStruct()
```
    Returns the outer struct if any.
    
    Returns:
    
    the outer struct
  - getByteBuffer
```
public final java.nio.ByteBuffer getByteBuffer()
```
    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's member within the byte buffer is given by member.position()
    
    Returns:
    
    the current byte buffer or a new direct buffer if none set.
    
    See Also:
    
    setByteBuffer(java.nio.ByteBuffer, int)
  - newBuffer
```
protected java.nio.ByteBuffer newBuffer(int capacity)
```
  - setByteBuffer
```
public final Struct setByteBuffer(java.nio.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. DatagramPacket).
    
    Parameters:
    
    byteBuffer - the new byte buffer.
    
    position - the position of this struct in the specified byte buffer.
    
    Returns:
    
    this
    
    Throws:
    
    java.lang.IllegalArgumentException - if the specified byteBuffer has a different byte order than this struct.
    
    java.lang.UnsupportedOperationException - if this struct is an inner struct.
    
    See Also:
    
    byteOrder()
  - setByteBufferPosition
```
public final 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.
    
    Returns:
    
    this
    
    Throws:
    
    java.lang.UnsupportedOperationException - if this struct is an inner struct.
  - getByteBufferPosition
```
public final int getByteBufferPosition()
```
    Returns the absolute position of this struct within its associated byte buffer.
    
    Returns:
    
    the absolute position of this struct in the byte buffer.
  - read
```
public int read(java.io.InputStream in)
         throws java.io.IOException
```
    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.
    
    Returns:
    
    the number of bytes read (typically the size of this struct.
    
    Throws:
    
    java.io.IOException - if an I/O error occurs.
  - write
```
public void write(java.io.OutputStream out)
           throws java.io.IOException
```
    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:
    
    java.io.IOException - if an I/O error occurs.
  - address
```
public final long address()
```
    Returns this struct address. This method allows for structs to be referenced (e.g. pointer) from other structs.
    
    Returns:
    
    the struct memory address.
    
    Throws:
    
    java.lang.UnsupportedOperationException - if the struct buffer is not a direct buffer.
    
    See Also:
    
    Struct.Reference32, Struct.Reference64
  - toString
```
public java.lang.String toString()
```
    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]
    
    Overrides:
    
    toString in class java.lang.Object
    
    Returns:
    
    a hexadecimal representation of the bytes content for this struct.
  - isUnion
```
public boolean isUnion()
```
    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]
    
    Returns:
    
    true if this struct's members are mapped to to the same location in memory; false otherwise.
    
    See Also:
    
    Union
  - byteOrder
```
public java.nio.ByteOrder byteOrder()
```
    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]
    
    Returns:
    
    the byte order when reading/writing multibyte values (default: network byte order, BIG_ENDIAN).
  - isPacked
```
public boolean isPacked()
```
    Indicates if this struct is packed (configurable). By default, 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]
    
    Returns:
    
    true if alignment requirements are ignored. false otherwise (default).
  - inner
```
protected <S extends Struct> S inner(S struct)
```
    Defines the specified struct as inner of this struct.
    
    Type Parameters:
    
    S - the type of the inner struct.
    
    Parameters:
    
    struct - the inner struct.
    
    Returns:
    
    the specified struct.
    
    Throws:
    
    java.lang.IllegalArgumentException - if the specified struct is already an inner struct.
  - array
```
protected <S extends Struct> S[] array(S[] structs)
```
    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).
    
    Type Parameters:
    
    S - the type of the struct array.
    
    Parameters:
    
    structs - the struct array.
    
    Returns:
    
    the specified struct array.
    
    Throws:
    
    java.lang.IllegalArgumentException - if the specified array contains inner structs.
  - array
```
protected <S extends Struct> S[] array(S[] structs,
                                       Struct.InstanceFactory<S> factory)
```
  - array
```
protected <S extends Struct> S[][] array(S[][] structs)
```
    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).
    
    Type Parameters:
    
    S - the type of the structs.
    
    Parameters:
    
    structs - the two dimensional struct array.
    
    Returns:
    
    the specified struct array.
    
    Throws:
    
    java.lang.IllegalArgumentException - if the specified array contains inner structs.
  - array
```
protected <S extends Struct> S[][][] array(S[][][] structs)
```
    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).
    
    Type Parameters:
    
    S - the type of the structs.
    
    Parameters:
    
    structs - the three dimensional struct array.
    
    Returns:
    
    the specified struct array.
    
    Throws:
    
    java.lang.IllegalArgumentException - if the specified array contains inner structs.
  - array
```
protected <M extends Struct.Member> M[] array(M[] arrayMember)
```
    Defines the specified array member. For predefined members, the array is populated when empty; custom members should use literal (populated) arrays.
    
    Type Parameters:
    
    M - the type of the member.
    
    Parameters:
    
    arrayMember - the array member.
    
    Returns:
    
    the specified array member.
    
    Throws:
    
    java.lang.UnsupportedOperationException - if the specified array is empty and the member type is unknown.
  - array
```
protected <M extends Struct.Member> M[] array(M[] arrayMember,
                                              Struct.InstanceFactory<M> factory)
```
    Defines the specified array member. For predefined members, the array is populated when empty; custom members should use literal (populated) arrays.
    
    Type Parameters:
    
    M - the type of the member array.
    
    Parameters:
    
    arrayMember - the array member.
    
    factory - an InstanceFactory callback for creating instances with which to fill the array
    
    Returns:
    
    the specified array member.
    
    Throws:
    
    java.lang.UnsupportedOperationException - if the specified array is empty and the member type is unknown.
  - fillArray
```
protected <S extends Struct> void fillArray(S[] structs)
```
    Fill the array, structs, with instances so that space in the struct is appropriately consumed.
    
    Type Parameters:
    
    S - the type of the struct
    
    Parameters:
    
    structs - the array to fill
  - fillArray
```
protected <S extends Struct> void fillArray(S[] structs,
                                            Struct.InstanceFactory<S> factory)
```
    Fill the array factory with instances of type S created by the instance factory factory.
    
    Type Parameters:
    
    S - the type of the Struct to create
    
    Parameters:
    
    structs - an array of type S structs
    
    factory - a factory that can generate new instances of type S.
  - fillArray
```
protected <M extends Struct.Member> void fillArray(M[] arrayMember)
```
    Fill the parameter arrayMember with values of type M.
    If you add a Struct.Member subclass that isn't covered here, you should override this method (not array(com.scaleoutsoftware.soss.client.util.Struct.Member[])), providing support for your Struct.Member subclass and then delegating to the super class for everything else.
    
    Type Parameters:
    
    M - the type of the array member
    
    Parameters:
    
    arrayMember - the array member.
  - fillArray
```
protected <M extends Struct.Member> void fillArray(M[] arrayMember,
                                                   Struct.InstanceFactory<M> factory)
```
    Fill the array arrayMember with instances of type M created by the instance factory factory.
    
    Type Parameters:
    
    M - the subtype of Member
    
    Parameters:
    
    arrayMember - the array of type M
    
    factory - a factory callback that can create instances of type M
  - array
```
protected <M extends Struct.Member> M[][] array(M[][] arrayMember)
```
    Defines the specified two-dimensional array member. For predefined members, the array is populated when empty; custom members should use literal (populated) arrays.
    
    Type Parameters:
    
    M - the type of the array member.
    
    Parameters:
    
    arrayMember - the two-dimensional array member.
    
    Returns:
    
    the specified array member.
    
    Throws:
    
    java.lang.UnsupportedOperationException - if the specified array is empty and the member type is unknown.
  - array
```
protected <M extends Struct.Member> M[][][] array(M[][][] arrayMember)
```
    Defines the specified three-dimensional array member. For predefined members, the array is populated when empty; custom members should use literal (populated) arrays.
    
    Type Parameters:
    
    M - the type of the array member.
    
    Parameters:
    
    arrayMember - the three-dimensional array member.
    
    Returns:
    
    the specified array member.
    
    Throws:
    
    java.lang.UnsupportedOperationException - if the specified array is empty and the member type is unknown.
  - array
```
protected Struct.UTF8String[] array(Struct.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.
    
    stringLength - the length of the string elements.
    
    Returns:
    
    the specified string array.

Class Struct

Nested Class Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

Struct

Method Detail

size

outerStruct

getByteBuffer

newBuffer

setByteBuffer

setByteBufferPosition

getByteBufferPosition

read

write

address

toString

isUnion

byteOrder

isPacked

inner

array

array

array

array

array

array

fillArray

fillArray

fillArray

fillArray

array

array

array