Class BinaryFieldInterpreter<T>

java.lang.Object
cds.savot.model.interpreter.BinaryFieldInterpreter<T>
Type Parameters:
T - Type this interpreter can encode into and decode from binary data.
Direct Known Subclasses:
BooleanInterpreter, CharInterpreter, DoubleComplexInterpreter, DoubleInterpreter, FloatComplexInterpreter, FloatInterpreter, IntegerInterpreter, LongInterpreter, ShortInterpreter, UnsignedByteInterpreter

public abstract class BinaryFieldInterpreter<T> extends Object
A BinaryFieldInterpreter is able to encode and to decode a given type of data in binary.
Since:
09/2011
Author:
Gregory Mantelet
  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    protected String
    Separator of items in the string representation of an array.
    protected final IntegerInterpreter
    Interpreter used only to encode or to decode the array size.
    protected final int[]
    Indicates the dimension(s) of the data to encode/decode.
    protected final int
    Number of bytes occupied by the type managed in this BinaryFieldInterpreter.
    protected final int
    Total number of items to encode/decode, all dimensions confounded.
    protected String
    String representation of a null value.
    protected final String
    Name/Label of the type managed by this BinaryFieldInterpreter.
  • Constructor Summary

    Constructors
    Constructor
    Description
    BinaryFieldInterpreter(int[] arraysizes, String typeLabel, int nbBytes)
    Builds a BinaryFieldInterpreter.
  • Method Summary

    Modifier and Type
    Method
    Description
    static final String
    arraySizeToString(int[] arraysize)
    Lets serialize the given array size in String.
    protected ArrayList<T>
    Converts the given value (single value or multidimensional array) into one array of one dimension.
    protected abstract T
    Converts/Casts the given object into an object of type T.
    Serializes the given cell value.
    protected T[]
    createEmptyArray(int arraysize)
    Creates an array (1 dimension) of type T with the given length.
    static final BinaryFieldInterpreter<?>
    Creates the BinaryFieldInterpreter corresponding to the given SavotField.
    T[]
    Decodes the binary data coming from the given input stream.
    abstract T
    decodePrimary(byte[] bytes, int offset)
    Decodes only one data of type T from the given bytes array.
    void
    encode(OutputStream output, Object value)
    Encodes the given value in binary and writes it in the given output stream.
    abstract byte[]
    Encodes a single value of type T in binary.
    protected abstract Class<T[]>
    Gets the precise array type.
    protected int
    Gets the number of data of type T to get currently.
    final byte[]
    Creates an array of the length of the type T (NB_BYTES) with padding values (0x00).
    byte[]
    getPadding(int length)
    Creates an array of the given length with padding values (0x00).
    protected byte[]
    readBytes(InputStream input, int length)
    Reads length data of type T from the given input stream considering the number of bytes one data of this type is supposed to occupied (see NB_BYTES).

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
  • Field Details

    • TYPE_LABEL

      protected final String TYPE_LABEL
      Name/Label of the type managed by this BinaryFieldInterpreter.
    • NB_BYTES

      protected final int NB_BYTES
      Number of bytes occupied by the type managed in this BinaryFieldInterpreter.
    • arraySizeInterpreter

      protected final IntegerInterpreter arraySizeInterpreter
      Interpreter used only to encode or to decode the array size.
    • fixArraySizes

      protected final int[] fixArraySizes
      Indicates the dimension(s) of the data to encode/decode.
    • nbItems

      protected final int nbItems
      Total number of items to encode/decode, all dimensions confounded.
    • strNullValue

      protected String strNullValue
      String representation of a null value.
    • arraySeparator

      protected String arraySeparator
      Separator of items in the string representation of an array.
  • Constructor Details

    • BinaryFieldInterpreter

      public BinaryFieldInterpreter(int[] arraysizes, String typeLabel, int nbBytes) throws BinaryInterpreterException
      Builds a BinaryFieldInterpreter.
      Parameters:
      arraysizes - Dimensions of the primary data type to encode/decode.
      typeLabel - Name/Label of the type to manage.
      nbBytes - Number of bytes of a primary data type.
      Throws:
      BinaryInterpreterException - If the dimensions are not valid or if there is a problem while creating the array size interpreter.
  • Method Details

    • decode

      public T[] decode(InputStream input) throws IOException

      Decodes the binary data coming from the given input stream.

      Basically, this method gets the array-size (particularly if variable), creates an empty array of the good dimension(s) and fills it by decoding one by one data of type T.

      Parameters:
      input - Data to decode.
      Returns:
      null if EOF, else the decoded data of type T.
      Throws:
      IOException - If the EOF has been reached in an unexpected manner or if an error occurs while reading bytes from the given input stream.
      See Also:
    • getArraySize

      protected int getArraySize(InputStream input) throws IOException

      Gets the number of data of type T to get currently.

      Either the array-size is defined at the creation, or it is variable. In one hand the given array-size is just returned. In another hand the array-size is an integer value which prefixes the data to read. In that case, we must read one integer from the given input stream. This integer corresponds to the length of the data of type T to get.

      Parameters:
      input - The data to decode.
      Returns:
      -1 if EOF, else the length of data of type T to return.
      Throws:
      IOException - If an error occurs while decoding the array-size from the given input stream.
    • readBytes

      protected byte[] readBytes(InputStream input, int length) throws IOException

      Reads length data of type T from the given input stream considering the number of bytes one data of this type is supposed to occupied (see NB_BYTES).

      Parameters:
      input - Input stream from which bytes must be read.
      length -
      Returns:
      null if EOF, else the read bytes (the length of this array is a multiple of NB_BYTES).
      Throws:
      IOException - If the end of file has been reached before getting length full items of type T or if there is an error while reading bytes from the given input stream.
    • convertToString

      public String convertToString(Object cellValue)

      Serializes the given cell value.

      NOTE: The given value can be a single value or a multidimensional array. In this last case all items (whatever is their dimension) are written in a String separated by arraySeparator (which depends of the type managed by the BinaryFieldInterpreter ; by default ' ').

      Parameters:
      cellValue - Value (single value or array) of a column/cell/field. (may be null)
      Returns:
      The String serialization of the given value.
    • createEmptyArray

      protected T[] createEmptyArray(int arraysize) throws ClassCastException, NegativeArraySizeException
      Creates an array (1 dimension) of type T with the given length.
      Parameters:
      arraysize - Length of the array to create. (MUST BE >= 0)
      Returns:
      An empty array of type T and of length arraysize.
      Throws:
      ClassCastException - If it is impossible to create an array of T.
      NegativeArraySizeException - If the given array size is negative.
      See Also:
    • getArrayClass

      protected abstract Class<T[]> getArrayClass()

      Gets the precise array type.

      Generally: T[].class, where T must be a concrete class.

      Returns:
      The class of an array of type T.
    • decodePrimary

      public abstract T decodePrimary(byte[] bytes, int offset) throws BinaryInterpreterException

      Decodes only one data of type T from the given bytes array.

      WARNING: bytes is supposed to contain enough bytes (>= NB_BYTES) from the given offset.

      Parameters:
      bytes - Array to use to extract enough bytes so that decoding one data of type T.
      offset - Position from which bytes must be read.
      Returns:
      The decoded value.
      Throws:
      BinaryInterpreterException - If an error occurs while decoding bytes.
    • encode

      public void encode(OutputStream output, Object value) throws IOException, BinaryInterpreterException
      Encodes the given value in binary and writes it in the given output stream.
      Parameters:
      output - Stream in which the encoded value must be written.
      value - The value to write once encoded in binary.
      Throws:
      IOException - If there is an error while writing in the given stream.
      BinaryInterpreterException - If there is an error while encoding the given value.
      See Also:
    • getPadding

      public byte[] getPadding(int length)
      Creates an array of the given length with padding values (0x00). param length
      Returns:
      Array of the given length of padding values.
    • getPadding

      public final byte[] getPadding()
      Creates an array of the length of the type T (NB_BYTES) with padding values (0x00).
      Returns:
      Bytes of one padding value of type T.
      See Also:
    • convertIntoArray

      protected ArrayList<T> convertIntoArray(Object value) throws BinaryInterpreterException

      Converts the given value (single value or multidimensional array) into one array of one dimension.

      NOTE: A String value will be considered as an array whose items are separated by arraySeparator. Another type (except an array) must be understandable by convertPrimary(Object).

      Parameters:
      value - Value to convert (single value or multidimensional array).
      Returns:
      A list of all values included into the given object.
      Throws:
      BinaryInterpreterException - If convertPrimary(Object) fails.
      See Also:
    • convertPrimary

      protected abstract T convertPrimary(Object value) throws BinaryInterpreterException
      Converts/Casts the given object into an object of type T.
      Parameters:
      value - The value to cast. (MAY BE NULL)
      Returns:
      The casted value.
      Throws:
      BinaryInterpreterException - If there is an error while converting the given value.
    • encodePrimary

      public abstract byte[] encodePrimary(T value) throws BinaryInterpreterException

      Encodes a single value of type T in binary.

      NOTE: If the given value is null, getPadding() will be returned.

      Parameters:
      value - The value to encode. (MAY BE NULL).
      Returns:
      The value encoded in binary.
      Throws:
      BinaryInterpreterException - If there is an error while encoding the given value.
    • createInterpreter

      public static final BinaryFieldInterpreter<?> createInterpreter(SavotField field) throws BinaryInterpreterException

      Creates the BinaryFieldInterpreter corresponding to the given SavotField.

      Data type

      • Accepted data-types are: boolean, bit, unsignedByte, char, unicode char, short, int, long, float, double, floatComplex, doubleComplex.
      • Another data-type will be considered as: char[*].

      Array size

      • The array-size can be multi-dimensional (each dimension separated by a 'x' character) and variable (specified by a '*' character) on the last dimension.
      • Delimited dimension (i.e. 12*) will be considered as variable dimension (so 12* => *).
      • A negative, null or non-numeric value will be considered as variable (*).

      Values

      Only the null attribute is managed. It indicates the string representation of a null value. It is used to identify a nulls and to write them while converting a cell value in string (see convertToString(Object)).

      Parameters:
      field - A SavotField.
      Returns:
      Its corresponding BinaryFieldInterpreter.
      Throws:
      BinaryInterpreterException - If there is an error while creating the interpreter.
    • arraySizeToString

      public static final String arraySizeToString(int[] arraysize)
      Lets serialize the given array size in String.
      Parameters:
      arraysize - Array-size to serialize.
      Returns:
      Its serialization.