Package uk.ac.starlink.table.storage

Class 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
    Author:
    Mark Taylor (Starlink)

    • Field Summary

      Fields 
      Modifier and Type Field 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 Description
      Codec()  

    • Method Summary

      All Methods Static Methods Instance Methods Abstract Methods Concrete Methods 
      Modifier and Type Method 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.