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

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.