com.twitter.common.io
Class CompatibilityCodec<T>

java.lang.Object
  extended by com.twitter.common.io.CompatibilityCodec<T>
Type Parameters:
T - the type of objects this codec is for.
All Implemented Interfaces:
Codec<T>

public class CompatibilityCodec<T>
extends Object
implements Codec<T>

A codec that composes two codecs: a primary and a compatibility codec. It always serializes with the primary codec, but can make a decision on deserialization based on the first few bytes of the serialized format whether to use the compatibility codec. This allows for easier transition between storage formats as the codec remains able to read the old serialized format.


Method Summary
static
<T> CompatibilityCodec<T>
create(Codec<T> primaryCodec, Codec<T> secondaryCodec, int prefixLength, Predicate<byte[]> discriminator)
          Creates a new compatibility codec instance.
 T deserialize(InputStream source)
          Reads an item from the source stream that was written by Codec.serialize(Object, java.io.OutputStream).
 void serialize(T item, OutputStream sink)
          Writes a representation of item to the sink that can be read back by Codec.deserialize(java.io.InputStream).
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

create

public static <T> CompatibilityCodec<T> create(Codec<T> primaryCodec,
                                               Codec<T> secondaryCodec,
                                               int prefixLength,
                                               Predicate<byte[]> discriminator)
Creates a new compatibility codec instance.

Parameters:
primaryCodec - the codec used to serialize objects, as well as deserialize them when the first byte of the serialized format matches the discriminator.
secondaryCodec - the codec used to deserialize objects when the first byte of the serialized format does not match the discriminator.
prefixLength - the length, in bytes, of the prefix of the message that is inspected for determining the format.
discriminator - a predicate that will receive an array of at most prefixLength bytes (it can receive less if the serialized format is shorter) and has to return true if the primary codec should be used for deserialization, otherwise false.

deserialize

public T deserialize(InputStream source)
              throws IOException
Description copied from interface: Codec
Reads an item from the source stream that was written by Codec.serialize(Object, java.io.OutputStream).

Specified by:
deserialize in interface Codec<T>
Parameters:
source - the stream to read an item from
Returns:
the deserialized item
Throws:
IOException - if there is a problem reading an item

serialize

public void serialize(T item,
                      OutputStream sink)
               throws IOException
Description copied from interface: Codec
Writes a representation of item to the sink that can be read back by Codec.deserialize(java.io.InputStream).

Specified by:
serialize in interface Codec<T>
Parameters:
item - the item to serialize
sink - the stream to write the item out to
Throws:
IOException - if there is a problem serializing the item