Package de.gsi.serializer.spi

Class BinarySerialiser

  • All Implemented Interfaces:
    IoSerialiser
    public class BinarySerialiser
extends java.lang.Object
implements IoSerialiser
    YaS -- Yet another Serialiser implementation Generic binary serialiser aimed at efficiently transferring data between server/client and in particular between Java/C++/web-based programs. For rationale see IoSerialiser.md description.

    There are two default backing buffer implementations (FastByteBuffer and ByteBuffer), but can be extended/replaced with any other buffer is also possible provided it implements the IoBuffer interface.

    The default serialisable data types are defined in DataType and include definitions for

    • primitives (byte, short, ..., float, double, and String), and
    • arrays thereof (ie. byte[], short[], ..., float[], double[], and String[]), as well as
    • complex objects implementing Collections (ie. Set, List, Queues), Enums or Maps.
    Any other complex data objects can be stored/extended using the OTHER sub-type. N.B. Multi-dimensional arrays are handled through one-dimensional striding arrays with the additional infos on number of dimensions and size for each individual dimension.

    raw-byte level protocol: above data items are stored as follows: 

    
 * header info:   [ 4 bytes (int) = 0x0000002A] // magic number used as coarse protocol identifier - precise protocol refined by further fields below
                  [ clear text serialiser name: String ] + // ie. "YaS" for 'Yet another Serialiser'
                  [ 1 byte - major protocol version ] +
                  [ 1 byte - minor protocol version ] +
                  [ 1 byte - micro protocol version ] // micro: non API-changing bug fixes in implementation
                  [ field header for 'start marker' ] [ 1 byte - uniqueType (0x00) ]
 * String:        [ 4 bytes (int) - length (including termination) ][ n bytes based on ISO-8859 or UTF-8 encoding ]
 * field header:  # start field header 'p0'
                  [ 1 byte - uniqueType ]
                  [ 4 bytes - field name hash code] // enables faster field matching
                  [ 4 bytes - dataStart = n bytes until data start] // counted w.r.t. field header start
                  [ 4 bytes - dataSize = n bytes for data size]
                  [ String (ISO-8859) - field name ]             // optional, if there are no field name hash code collisions
                  N.B. following fields are optional (detectable if buffer position smaller than 'p0' + dataStart)
                  [ String (UTF-8)    - field unit ]
                  [ String (UTF-8)    - field in/out direction ]
                  [ String (UTF-8)    - field groups ]
                  # start data = 'p0' + dataStart
                  ... type specific and/or custom data serialisation
                  # end data = 'p0' + dataStart + dataSize
 * primitives:    [ field header for 'primitive type ID'] + [ 1-8 bytes depending on DataType ]
 * prim. arrays:  [ array header for 'prim. type array ID'] + [   ]=1-8 bytes x N_i or more - array data depending on variable DataType ]
 * boxed arrays:  as above but each element cast to corresponding primitive type
 * array header:  [ field header (as above) ] +
                      [4 bytes - number of dimensions N_d ] +
                      [4 bytes x N_d - vector sizes for each dimension N_i ]  
 * Collection[E]:
 * List[]:
 * Queue[E]:
 * Set[E]:        [ array header (uniqueType= one of the Collection type IDs) ] + 
                      [ 1 byte - uniqueType of E ] + [  n bytes - array of E cast to primitive type and/or string ]
 * Map[K,V]:      [ array header (uniqueType=0xCB) ] + [ 1 byte - uniqueType of K ] +  [ 1 byte - uniqueType of V ] +
                      [ n bytes - array of K cast to primitive type and/or string ] + 
                      [ n bytes - array of V cast to primitive type and/or string ]
 * OTHER          [ field header - uniqueByte = 0xFD ] +
                      [ 1 byte - uniqueType -- custom class type definition ]
                      [ String (ISO-8859) - class type name ]
                      [ n bytes - custom serialisation definition ]
 * start marker:  [ field header for '0x00' ] // dataSize == # bytes until the corresponding end-marker start
 * end marker:    [ field header for '0xFE' ]
 
 * nesting or sub-structures (ie. POJOs with sub-classes) can be achieved via:
 [  start marker - field name == nesting context1 ] 
   [  start marker - field name == nesting context2 ]
    ... 
   [  end marker - field name == nesting context2 (optional name) ]
 [  end marker - field name == nesting context1 (optional name) ]
 
 with
 T: being a generic list parameter outlined in DataType
 K: being a generic key parameter outlined in DataType
 V: being a generic value parameter outlined in DataType
    Author:
    rstein

    • Method Detail

      • checkHeaderInfo

        public ProtocolInfo checkHeaderInfo()
        Description copied from interface: IoSerialiser
        Reads and checks protocol header information.
        Specified by:
        checkHeaderInfo in interface IoSerialiser
        Returns:
        ProtocolInfo info Object (extends FieldHeader)

      • setQueryFieldName

        public void setQueryFieldName​(java.lang.String fieldName,
                              int dataStartPosition)
        Specified by:
        setQueryFieldName in interface IoSerialiser

      • getBooleanArray

        public boolean[] getBooleanArray​(boolean[] dst,
                                 int length)
        Specified by:
        getBooleanArray in interface IoSerialiser

      • getBufferIncrements

        public int getBufferIncrements()

      • setBufferIncrements

        public void setBufferIncrements​(int bufferIncrements)

      • getByteArray

        public byte[] getByteArray​(byte[] dst,
                           int length)
        Specified by:
        getByteArray in interface IoSerialiser

      • getCharArray

        public char[] getCharArray​(char[] dst,
                           int length)
        Specified by:
        getCharArray in interface IoSerialiser

      • getCollection

        public <E> java.util.Collection<E> getCollection​(java.util.Collection<E> collection)
        Specified by:
        getCollection in interface IoSerialiser

      • getDoubleArray

        public double[] getDoubleArray​(double[] dst,
                               int length)
        Specified by:
        getDoubleArray in interface IoSerialiser

      • getEnum

        public <E extends java.lang.Enum<E>> java.lang.Enum<E> getEnum​(java.lang.Enum<E> enumeration)
        Specified by:
        getEnum in interface IoSerialiser

      • getFloatArray

        public float[] getFloatArray​(float[] dst,
                             int length)
        Specified by:
        getFloatArray in interface IoSerialiser

      • getIntArray

        public int[] getIntArray​(int[] dst,
                         int length)
        Specified by:
        getIntArray in interface IoSerialiser

      • getList

        public <E> java.util.List<E> getList​(java.util.List<E> collection)
        Specified by:
        getList in interface IoSerialiser

      • getLongArray

        public long[] getLongArray​(long[] dst,
                           int length)
        Specified by:
        getLongArray in interface IoSerialiser

      • getMap

        public <K,​V,​E> java.util.Map<K,​V> getMap​(java.util.Map<K,​V> map)
        Specified by:
        getMap in interface IoSerialiser

      • getQueue

        public <E> java.util.Queue<E> getQueue​(java.util.Queue<E> collection)
        Specified by:
        getQueue in interface IoSerialiser

      • getSet

        public <E> java.util.Set<E> getSet​(java.util.Set<E> collection)
        Specified by:
        getSet in interface IoSerialiser

      • getShortArray

        public short[] getShortArray​(short[] dst,
                             int length)
        Specified by:
        getShortArray in interface IoSerialiser

      • getStringArray

        public java.lang.String[] getStringArray​(java.lang.String[] dst,
                                         int length)
        Specified by:
        getStringArray in interface IoSerialiser

      • isEnforceSimpleStringEncoding

        public boolean isEnforceSimpleStringEncoding()
        Returns:
        true the ISO-8859-1 character encoding is being enforced for data fields (better performance), otherwise UTF-8 is being used (more generic encoding)

      • setEnforceSimpleStringEncoding

        public void setEnforceSimpleStringEncoding​(boolean state)
        Parameters:
        state - true the ISO-8859-1 character encoding is being enforced for data fields (better performance), otherwise UTF-8 is being used (more generic encoding)

      • put

        public <E> void put​(FieldDescription fieldDescription,
                    java.util.Collection<E> collection,
                    java.lang.reflect.Type valueType)
        Specified by:
        put in interface IoSerialiser

      • put

        public <K,​V,​E> void put​(FieldDescription fieldDescription,
                                    java.util.Map<K,​V> map,
                                    java.lang.reflect.Type keyType,
                                    java.lang.reflect.Type valueType)
        Specified by:
        put in interface IoSerialiser

      • put

        public <E> void put​(java.lang.String fieldName,
                    java.util.Collection<E> collection,
                    java.lang.reflect.Type valueType)
        Specified by:
        put in interface IoSerialiser

      • put

        public void put​(java.lang.String fieldName,
                java.lang.Enum<?> enumeration)
        Specified by:
        put in interface IoSerialiser

      • put

        public <K,​V,​E> void put​(java.lang.String fieldName,
                                    java.util.Map<K,​V> map,
                                    java.lang.reflect.Type keyType,
                                    java.lang.reflect.Type valueType)
        Specified by:
        put in interface IoSerialiser

      • put

        public void put​(java.lang.String fieldName,
                boolean value)
        Specified by:
        put in interface IoSerialiser

      • put

        public void put​(java.lang.String fieldName,
                boolean[] values,
                int n)
        Specified by:
        put in interface IoSerialiser

      • put

        public void put​(java.lang.String fieldName,
                boolean[] values,
                int[] dims)
        Specified by:
        put in interface IoSerialiser

      • put

        public void put​(java.lang.String fieldName,
                byte value)
        Specified by:
        put in interface IoSerialiser

      • put

        public void put​(java.lang.String fieldName,
                byte[] values,
                int n)
        Specified by:
        put in interface IoSerialiser

      • put

        public void put​(java.lang.String fieldName,
                byte[] values,
                int[] dims)
        Specified by:
        put in interface IoSerialiser

      • put

        public void put​(java.lang.String fieldName,
                char value)
        Specified by:
        put in interface IoSerialiser

      • put

        public void put​(java.lang.String fieldName,
                char[] values,
                int n)
        Specified by:
        put in interface IoSerialiser

      • put

        public void put​(java.lang.String fieldName,
                char[] values,
                int[] dims)
        Specified by:
        put in interface IoSerialiser

      • put

        public void put​(java.lang.String fieldName,
                double value)
        Specified by:
        put in interface IoSerialiser

      • put

        public void put​(java.lang.String fieldName,
                double[] values,
                int n)
        Specified by:
        put in interface IoSerialiser

      • put

        public void put​(java.lang.String fieldName,
                double[] values,
                int[] dims)
        Specified by:
        put in interface IoSerialiser

      • put

        public void put​(java.lang.String fieldName,
                float value)
        Specified by:
        put in interface IoSerialiser

      • put

        public void put​(java.lang.String fieldName,
                float[] values,
                int n)
        Specified by:
        put in interface IoSerialiser

      • put

        public void put​(java.lang.String fieldName,
                float[] values,
                int[] dims)
        Specified by:
        put in interface IoSerialiser

      • put

        public void put​(java.lang.String fieldName,
                int value)
        Specified by:
        put in interface IoSerialiser

      • put

        public void put​(java.lang.String fieldName,
                int[] values,
                int n)
        Specified by:
        put in interface IoSerialiser

      • put

        public void put​(java.lang.String fieldName,
                int[] values,
                int[] dims)
        Specified by:
        put in interface IoSerialiser

      • put

        public void put​(java.lang.String fieldName,
                long value)
        Specified by:
        put in interface IoSerialiser

      • put

        public void put​(java.lang.String fieldName,
                long[] values,
                int n)
        Specified by:
        put in interface IoSerialiser

      • put

        public void put​(java.lang.String fieldName,
                long[] values,
                int[] dims)
        Specified by:
        put in interface IoSerialiser

      • put

        public void put​(java.lang.String fieldName,
                short value)
        Specified by:
        put in interface IoSerialiser

      • put

        public void put​(java.lang.String fieldName,
                short[] values,
                int n)
        Specified by:
        put in interface IoSerialiser

      • put

        public void put​(java.lang.String fieldName,
                short[] values,
                int[] dims)
        Specified by:
        put in interface IoSerialiser

      • put

        public void put​(java.lang.String fieldName,
                java.lang.String string)
        Specified by:
        put in interface IoSerialiser

      • put

        public void put​(java.lang.String fieldName,
                java.lang.String[] values,
                int n)
        Specified by:
        put in interface IoSerialiser

      • put

        public void put​(java.lang.String fieldName,
                java.lang.String[] values,
                int[] dims)
        Specified by:
        put in interface IoSerialiser

      • putGenericArrayAsPrimitive

        public void putGenericArrayAsPrimitive​(DataType dataType,
                                       java.lang.Object[] data,
                                       int nToCopy)

      • putHeaderInfo

        public void putHeaderInfo​(FieldDescription... field)
        Description copied from interface: IoSerialiser
        Adds header and version information
        Specified by:
        putHeaderInfo in interface IoSerialiser
        Parameters:
        field - optional FieldDescription (ie. to allow to attach MetaData to the start/stop marker)

      • setFieldSerialiserLookupFunction

        public void setFieldSerialiserLookupFunction​(java.util.function.BiFunction<java.lang.reflect.Type,​java.lang.reflect.Type[],​FieldSerialiser<java.lang.Object>> serialiserLookupFunction)
        Specified by:
        setFieldSerialiserLookupFunction in interface IoSerialiser

      • getGenericArrayAsBoxedPrimitive

        protected <E> E[] getGenericArrayAsBoxedPrimitive​(DataType dataType)

      • getDataType

        public static byte getDataType​(DataType dataType)

      • getDataType

        public static DataType getDataType​(byte byteValue)