uk.ac.starlink.table.storage

## Class Codec

- java.lang.Object
- - uk.ac.starlink.table.storage.Codec

-     public abstract class Codec
      extends java.lang.Object

  Serializes and deserializes objects to/from a data stream. A given instance of this class is only able to de/serialize an object of one class. Obtain an instance from the static `getCodec(uk.ac.starlink.table.ValueInfo)` method, or use one of the static members. The static members are all safe for concurrent use from multiple threads.

  This is (supposed to be) considerably more lightweight than all the `Serializable` business - for one thing there's no way to tell from the stream what kind of item has been serialized, you have to make sure the right Codec instance is on hand. In general it deals with primitive wrapper objects and arrays of same, but new Codec instances for different classes can be added.

  Since:
    3 Aug 2004

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static Codec` | `BOOLEAN` Codec for byte-serialized boolean values, null handled.
    `static Codec` | `BYTE` Codec for 8-bit byte, no null handling.
    `static Codec` | `BYTE_ARRAY` Codec for variable-length array of 8-bit bytes.
    `static Codec` | `CHAR` Codec for 16-bit character, no null handling.
    `static Codec` | `DOUBLE` Codec for 64-bit floating point, nulls treated like NaN.
    `static Codec` | `DOUBLE_ARRAY` Codec for variable-length array of 64-bit doubles.
    `static Codec` | `FLOAT` Codec for 32-bit floating point, nulls treated like NaN.
    `static Codec` | `FLOAT_ARRAY` Codec for variable-length array of 32-bit floats.
    `static Codec` | `INT` Codec for 32-bit integer, no null handling.
    `static Codec` | `INT_ARRAY` Codec for variable-length array of 32-bit integers.
    `static Codec` | `LONG` Codec for 64-bit integer, no null handling.
    `static Codec` | `LONG_ARRAY` Codec for variable-length array of 64-bit integers.
    `static Codec` | `SHORT` Codec for 16-bit integer, no null handling.
    `static Codec` | `SHORT_ARRAY` Codec for variable-length array of 16-bit integers.
    `static Codec` | `STRING` Codec for variable-length string.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `Codec()`

  - ### Method Summary

    All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `abstract boolean` | `decodeBoolean(ByteStoreAccess in)` Deserialises an item from a stream, and presents it as a boolean if possible.
    `abstract double` | `decodeDouble(ByteStoreAccess in)` Deserialises an item from a stream, and presents it as a double if possible.
    `abstract int` | `decodeInt(ByteStoreAccess in)` Deserialises an item from a stream, and presents it as an integer if possible.
    `abstract long` | `decodeLong(ByteStoreAccess in)` Deserialises an item from a stream, and presents it as a long integer if possible.
    `abstract java.lang.Object` | `decodeObject(ByteStoreAccess in)` Deserializes an item from a stream.
    `abstract int` | `encode(java.lang.Object value, java.io.DataOutput out)` Serializes an object to a stream.
    `static Codec` | `getCodec(ValueInfo info)` Returns a codec suitable for serializing/deserializing the contents of a given ValueInfo.
    `abstract int` | `getItemSize()` Returns the number of bytes a call to `encode` will write.
    `protected void` | `warnCorrupt()` Logs a warning that unexpected data has been found in the stream during decoding.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### BYTE

          public static final Codec BYTE

      Codec for 8-bit byte, no null handling.

    - #### SHORT

          public static final Codec SHORT

      Codec for 16-bit integer, no null handling.

    - #### INT

          public static final Codec INT

      Codec for 32-bit integer, no null handling.

    - #### LONG

          public static final Codec LONG

      Codec for 64-bit integer, no null handling.

    - #### FLOAT

          public static final Codec FLOAT

      Codec for 32-bit floating point, nulls treated like NaN.

    - #### DOUBLE

          public static final Codec DOUBLE

      Codec for 64-bit floating point, nulls treated like NaN.

    - #### CHAR

          public static final Codec CHAR

      Codec for 16-bit character, no null handling.

    - #### BOOLEAN

          public static final Codec BOOLEAN

      Codec for byte-serialized boolean values, null handled.

    - #### BYTE_ARRAY

          public static final Codec BYTE_ARRAY

      Codec for variable-length array of 8-bit bytes.

    - #### SHORT_ARRAY

          public static final Codec SHORT_ARRAY

      Codec for variable-length array of 16-bit integers.

    - #### INT_ARRAY

          public static final Codec INT_ARRAY

      Codec for variable-length array of 32-bit integers.

    - #### LONG_ARRAY

          public static final Codec LONG_ARRAY

      Codec for variable-length array of 64-bit integers.

    - #### FLOAT_ARRAY

          public static final Codec FLOAT_ARRAY

      Codec for variable-length array of 32-bit floats.

    - #### DOUBLE_ARRAY

          public static final Codec DOUBLE_ARRAY

      Codec for variable-length array of 64-bit doubles.

    - #### STRING

          public static final Codec STRING

      Codec for variable-length string.

  - ### Constructor Detail

    - #### Codec

          public Codec()

  - ### Method Detail

    - #### encode

          public abstract int encode(java.lang.Object value,
                                     java.io.DataOutput out)
                              throws java.io.IOException

      Serializes an object to a stream.
      Parameters:
        `value` - object to serialize
        `out` - destination stream, positioned at place to write
      Returns:
        number of bytes written
      Throws:
        `java.io.IOException`

    - #### decodeObject

          public abstract java.lang.Object decodeObject(ByteStoreAccess in)
                                                 throws java.io.IOException

      Deserializes an item from a stream.
      Parameters:
        `in` - source stream, positioned at start of item
      Returns:
        deserialized item
      Throws:
        `java.io.IOException`

    - #### decodeInt

          public abstract int decodeInt(ByteStoreAccess in)
                                 throws java.io.IOException

      Deserialises an item from a stream, and presents it as an integer if possible. If the stream does not contain integer-like items, the result may not be useful.
      Parameters:
        `in` - source stream, positioned at start of item
      Returns:
        best-effort integer equivalent of deserialised item
      Throws:
        `java.io.IOException`

    - #### decodeLong

          public abstract long decodeLong(ByteStoreAccess in)
                                   throws java.io.IOException

      Deserialises an item from a stream, and presents it as a long integer if possible. If the stream does not contain integer-like items, the result may not be useful.
      Parameters:
        `in` - source stream, positioned at start of item
      Returns:
        best-effort long equivalent of deserialised item
      Throws:
        `java.io.IOException`

    - #### decodeDouble

          public abstract double decodeDouble(ByteStoreAccess in)
                                       throws java.io.IOException

      Deserialises an item from a stream, and presents it as a double if possible. If the stream does not contain numeric items, the result may not be useful.
      Parameters:
        `in` - source stream, positioned at start of item
      Returns:
        best-effort double equivalent of deserialised item
      Throws:
        `java.io.IOException`

    - #### decodeBoolean

          public abstract boolean decodeBoolean(ByteStoreAccess in)
                                         throws java.io.IOException

      Deserialises an item from a stream, and presents it as a boolean if possible. If the stream does not contain boolean-like items, the result may not be useful.
      Parameters:
        `in` - source stream, positioned at start of item
      Returns:
        best-effort boolean equivalent of deserialised item
      Throws:
        `java.io.IOException`

    - #### getItemSize

          public abstract int getItemSize()

      Returns the number of bytes a call to `encode` will write. If this value may vary, -1 is returned.
      Returns:
        size in bytes of serialized items, or -1

    - #### getCodec

          public static Codec getCodec(ValueInfo info)

      Returns a codec suitable for serializing/deserializing the contents of a given ValueInfo. If no codec can be supplied to match `info`, `null` is returned.
      Parameters:
        `info` - object describing the kind of item which is required to be de/serialized
      Returns:
        codec for the job

    - #### warnCorrupt

          protected void warnCorrupt()

      Logs a warning that unexpected data has been found in the stream during decoding.