# Class Codec

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

public abstract class Codec extends 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(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 final Codec`
`BOOLEAN`
Codec for byte-serialized boolean values, null handled.
`static final Codec`
`BYTE`
Codec for 8-bit byte, no null handling.
`static final Codec`
`BYTE_ARRAY`
Codec for variable-length array of 8-bit bytes.
`static final Codec`
`CHAR`
Codec for 16-bit character, no null handling.
`static final Codec`
`DOUBLE`
Codec for 64-bit floating point, nulls treated like NaN.
`static final Codec`
`DOUBLE_ARRAY`
Codec for variable-length array of 64-bit doubles.
`static final Codec`
`FLOAT`
Codec for 32-bit floating point, nulls treated like NaN.
`static final Codec`
`FLOAT_ARRAY`
Codec for variable-length array of 32-bit floats.
`static final Codec`
`INT`
Codec for 32-bit integer, no null handling.
`static final Codec`
`INT_ARRAY`
Codec for variable-length array of 32-bit integers.
`static final Codec`
`LONG`
Codec for 64-bit integer, no null handling.
`static final Codec`
`LONG_ARRAY`
Codec for variable-length array of 64-bit integers.
`static final Codec`
`SHORT`
Codec for 16-bit integer, no null handling.
`static final Codec`
`SHORT_ARRAY`
Codec for variable-length array of 16-bit integers.
`static final Codec`
`STRING`
Codec for variable-length string.

## Constructor Summary

Constructors
Constructor
Description
`Codec()`

## Method Summary

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 Object`
`decodeObject(ByteStoreAccess in)`
Deserializes an item from a stream.
`abstract int`
`encode(Object value, 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 Object

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

## Field Details

### 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 Details

### Codec

public Codec()

## Method Details

### encode

public abstract int encode(Object value, DataOutput out) throws 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:
  `IOException`

### decodeObject

public abstract Object decodeObject(ByteStoreAccess in) throws IOException
Deserializes an item from a stream.

Parameters:
  `in` - source stream, positioned at start of item
Returns:
  deserialized item
Throws:
  `IOException`

### decodeInt

public abstract int decodeInt(ByteStoreAccess in) throws 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:
  `IOException`

### decodeLong

public abstract long decodeLong(ByteStoreAccess in) throws 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:
  `IOException`

### decodeDouble

public abstract double decodeDouble(ByteStoreAccess in) throws 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:
  `IOException`

### decodeBoolean

public abstract boolean decodeBoolean(ByteStoreAccess in) throws 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:
  `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.