net.kuujo.catalyst.serializer

Class Serializer

java.lang.Object

net.kuujo.catalyst.serializer.Serializer

All Implemented Interfaces:

Cloneable

public class Serializer
extends Object
implements Cloneable

Catalyst serializer.

This class provides an interface for efficient serialization of Java objects. Serialization is performed by TypeSerializer instances. Objects that can be serialized by Serializer must be registered. When objects are serialized, Catalyst will write the object's type as an 16-bit unsigned integer. When reading objects, the 16-bit identifier is used to construct a new object.

Serializable objects must either provide a TypeSerializer. implement CatalystSerializable, or implement Externalizable. For efficiency, serializable objects may implement ReferenceCounted or provide a PooledSerializer that reuses objects during deserialization. Catalyst will automatically deserialize ReferenceCounted types using an object pool.

Serialization via this class is not thread safe.

Author:

Jordan Halterman

Constructor Summary

Constructors

Constructor and Description
Serializer() Creates a new serializer instance with a default UnpooledHeapAllocator.
Serializer(BufferAllocator allocator) Creates a new serializer instance with a buffer allocator.
Serializer(BufferAllocator allocator, Collection<SerializableTypeResolver> resolvers) Creates a new serializer instance with a buffer allocator and type resolver(s).
Serializer(BufferAllocator allocator, SerializableTypeResolver... resolvers) Creates a new serializer instance with a buffer allocator and type resolver(s).
Serializer(Collection<SerializableTypeResolver> resolvers) Creates a new serializer instance with a default UnpooledHeapAllocator.
Serializer(SerializableTypeResolver... resolvers) Creates a new serializer instance with a default UnpooledHeapAllocator.

Method Summary

Modifier and Type	Method and Description
Buffer	allocate() Allocates a new buffer with an arbitrary initial capacity and unlimited maximum capacity.
Buffer	allocate(long capacity) Allocates a new buffer with an initial and an unlimited maximum capacity.
Buffer	allocate(long initialCapacity, long maxCapacity) Allocates a new buffer with a dynamic capacity.
BufferAllocator	allocator() Returns the underlying buffer allocator.
Serializer	clone()
<T> T	copy(T object) Copies the given object.
<T> T	readObject(Buffer buffer) Reads an object from the given buffer.
<T> T	readObject(BufferInput buffer) Reads an object from the given buffer.
<T> T	readObject(InputStream inputStream) Reads an object from the given input stream.
Serializer	register(Class<?> type) Registers a serializable type.
Serializer	register(Class<?> type, Class<? extends TypeSerializer<?>> serializer) Registers a type serializer.
Serializer	register(Class<?> type, Class<? extends TypeSerializer<?>> serializer, int id) Registers a type serializer with an identifier.
Serializer	register(Class<?> type, int id) Registers a serializable type with an identifier.
Serializer	register(Class<?> type, TypeSerializerFactory factory) Registers a type serializer factory.
Serializer	register(Class<?> type, TypeSerializerFactory factory, int id) Registers a type serializer with an identifier.
Serializer	resolve(Collection<SerializableTypeResolver> resolvers) Resolves serializable types with the given resolver.
Serializer	resolve(SerializableTypeResolver... resolvers) Resolves serializable types with the given resolver.
<T> Buffer	writeObject(T object) Writes an object to a buffer.
<T> Buffer	writeObject(T object, Buffer buffer) Writes an object to the given buffer.
<T> BufferOutput	writeObject(T object, BufferOutput buffer) Writes an object to the given buffer.
<T> OutputStream	writeObject(T object, OutputStream outputStream) Writes an object to the given output stream.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Serializer

public Serializer()

Creates a new serializer instance with a default UnpooledHeapAllocator.

Catalyst will use a UnpooledHeapAllocator to allocate buffers for serialization. Users can explicitly allocate buffers with the heap allocator via allocate(long).

   
      Serializer serializer = new Serializer(new PooledHeapAllocator());
      Buffer buffer = serializer.allocate(1024);
   
 

Serializer

public Serializer(BufferAllocator allocator)

Creates a new serializer instance with a buffer allocator.

The given BufferAllocator will be used to allocate buffers during serialization. Users can explicitly allocate buffers with the given allocator via allocate(long).

   
      Serializer serializer = new Serializer(new PooledHeapAllocator());
      Buffer buffer = serializer.allocate(1024);
   
 

If a PooledAllocator is used, users must be careful to release buffers back to the pool by calling ReferenceCounted.release() or Buffer.close().

Parameters:

allocator - The serializer buffer allocator.

Serializer

public Serializer(SerializableTypeResolver... resolvers)

Creates a new serializer instance with a default UnpooledHeapAllocator.

The given SerializableTypeResolvers will be used to locate serializable types on the classpath. By default, the PrimitiveTypeResolver and JdkTypeResolver will be used to register common serializable types, and any additional types will be registered via provided type resolvers thereafter.

Parameters:

resolvers - A collection of serializable type resolvers with which to register serializable types.

Serializer

public Serializer(Collection<SerializableTypeResolver> resolvers)

Creates a new serializer instance with a default UnpooledHeapAllocator.

The given SerializableTypeResolvers will be used to locate serializable types on the classpath. By default, the PrimitiveTypeResolver and JdkTypeResolver will be used to register common serializable types, and any additional types will be registered via provided type resolvers thereafter.

Parameters:

resolvers - A collection of serializable type resolvers with which to register serializable types.

Serializer

public Serializer(BufferAllocator allocator,
                  SerializableTypeResolver... resolvers)

Creates a new serializer instance with a buffer allocator and type resolver(s).

The given BufferAllocator will be used to allocate buffers during serialization. Users can explicitly allocate buffers with the given allocator via allocate(long).

   
      Serializer serializer = new Serializer(new PooledHeapAllocator());
      Buffer buffer = serializer.allocate(1024);
   
 

If a PooledAllocator is used, users must be careful to release buffers back to the pool by calling ReferenceCounted.release() or Buffer.close().

The given SerializableTypeResolvers will be used to locate serializable types on the classpath. By default, the PrimitiveTypeResolver and JdkTypeResolver will be used to register common serializable types, and any additional types will be registered via provided type resolvers thereafter.

Parameters:

allocator - The serializer buffer allocator.

resolvers - A collection of serializable type resolvers with which to register serializable types.

Serializer

public Serializer(BufferAllocator allocator,
                  Collection<SerializableTypeResolver> resolvers)

Creates a new serializer instance with a buffer allocator and type resolver(s).

The given BufferAllocator will be used to allocate buffers during serialization. Users can explicitly allocate buffers with the given allocator via allocate(long).

   
      Serializer serializer = new Serializer(new PooledHeapAllocator());
      Buffer buffer = serializer.allocate(1024);
   
 

If a PooledAllocator is used, users must be careful to release buffers back to the pool by calling ReferenceCounted.release() or Buffer.close().

The given SerializableTypeResolvers will be used to locate serializable types on the classpath. By default, the PrimitiveTypeResolver and JdkTypeResolver will be used to register common serializable types, and any additional types will be registered via provided type resolvers thereafter.

Parameters:

allocator - The serializer buffer allocator.

resolvers - A collection of serializable type resolvers with which to register serializable types.

Method Detail

resolve

public Serializer resolve(SerializableTypeResolver... resolvers)

Resolves serializable types with the given resolver.

This allows users to modify the serializable types registered to an existing Serializer instance. Types resolved by the provided resolver(s) will be added to existing types resolved by any type resolvers provided to this object's constructor or by previous calls to this method.

Parameters:

resolvers - The resolvers with which to resolve serializable types.

Returns:

The serializer instance.

resolve

public Serializer resolve(Collection<SerializableTypeResolver> resolvers)

Resolves serializable types with the given resolver.

This allows users to modify the serializable types registered to an existing Serializer instance. Types resolved by the provided resolver(s) will be added to existing types resolved by any type resolvers provided to this object's constructor or by previous calls to this method.

Parameters:

resolvers - The resolvers with which to resolve serializable types.

Returns:

The serializer instance.

register

public Serializer register(Class<?> type)

Registers a serializable type.

The serializable type must be assignable from CatalystSerializable or Externalizable. Users can specify a serialization type ID and/or TypeSerializer for the registered type by annotating it with SerializeWith. If the SerializeWith annotation provides a type ID, the given type will be registered with that ID. If the SerializeWith annotation provides a TypeSerializer class, the given type will be registered with that serializer.

Parameters:

type - The serializable type. This type must be assignable from CatalystSerializable or Externalizable.

Returns:

The serializer instance.

Throws:

IllegalArgumentException - If the serializable type ID is within the reserved range `128` to `255`

register

public Serializer register(Class<?> type,
                           int id)

Registers a serializable type with an identifier.

The serializable type must be assignable from CatalystSerializable or Externalizable. Users can specify a TypeSerializer for the registered type by annotating it with SerializeWith. Even if the SerializeWith annotation provides a type ID, the annotated ID will be ignored and the provided type ID will be used. If the SerializeWith annotation provides a TypeSerializer class, the given type will be registered with that serializer.

Parameters:

type - The serializable type. This type must be assignable from CatalystSerializable or Externalizable.

id - The type ID. This ID must be a number between `0` and `65535`. Serialization IDs between `128` and `255` are reserved and will result in an IllegalArgumentException

Returns:

The serializer instance.

Throws:

IllegalArgumentException - If the serializable type ID is within the reserved range `128` to `255`

register

public Serializer register(Class<?> type,
                           Class<? extends TypeSerializer<?>> serializer)

Registers a type serializer.

Because a custom TypeSerializer is provided, the registered type can be any class and does not have to implement any particular interface.

Internally, the provided class will be wrapped in a DefaultTypeSerializerFactory. The serializer class can be registered for more than one type class. The factory will instantiate a new TypeSerializer instance once for each type for which the serializer is registered per Serializer instance. If the Serializer instance is cloned, the serializer factory will be copied and a new TypeSerializer will be instantiated for the clone.

Parameters:

type - The serializable type.

serializer - The serializer to register.

Returns:

The serializer instance.

register

public Serializer register(Class<?> type,
                           TypeSerializerFactory factory)

Registers a type serializer factory.

Because a custom TypeSerializerFactory is provided, the registered type can be any class and does not have to implement any particular interface.

The serializer factory can be registered for more than one type class. The factory will be called on to create a new TypeSerializer instance once for each type for which the serializer is registered per Serializer instance. If the Serializer instance is cloned, the serializer factory will be copied and a new TypeSerializer will be instantiated for the clone.

Parameters:

type - The serializable type.

factory - The serializer factory to register.

Returns:

The serializer instance.

register

public Serializer register(Class<?> type,
                           Class<? extends TypeSerializer<?>> serializer,
                           int id)

Registers a type serializer with an identifier.

The provided serializable type ID will be used to identify the serializable type during serialization and deserialization. When objects of the given type are serialized to a Buffer, the given type id will be written to the buffer in lieu of its class name. When the object is deserialized, the type id will be used to look up the class. It is essential that the given type be registered with the same id on all Serializer instances.

Because a custom TypeSerializer is provided, the registered type can be any class and does not have to implement any particular interface.

Internally, the provided class will be wrapped in a DefaultTypeSerializerFactory. The serializer class can be registered for more than one type class. The factory will instantiate a new TypeSerializer instance once for each type for which the serializer is registered per Serializer instance. If the Serializer instance is cloned, the serializer factory will be copied and a new TypeSerializer will be instantiated for the clone.

Parameters:

type - The serializable type.

serializer - The serializer to register.

id - The type ID.

Returns:

The serializer instance.

register

public Serializer register(Class<?> type,
                           TypeSerializerFactory factory,
                           int id)

Registers a type serializer with an identifier.

The provided serializable type ID will be used to identify the serializable type during serialization and deserialization. When objects of the given type are serialized to a Buffer, the given type id will be written to the buffer in lieu of its class name. When the object is deserialized, the type id will be used to look up the class. It is essential that the given type be registered with the same id on all Serializer instances.

Because a custom TypeSerializerFactory is provided, the registered type can be any class and does not have to implement any particular interface.

The serializer factory can be registered for more than one type class. The factory will be called on to create a new TypeSerializer instance once for each type for which the serializer is registered per Serializer instance. If the Serializer instance is cloned, the serializer factory will be copied and a new TypeSerializer will be instantiated for the clone.

Parameters:

type - The serializable type.

factory - The serializer factory to register.

id - The type ID.

Returns:

The serializer instance.

allocator

public BufferAllocator allocator()

Returns the underlying buffer allocator.

Returns:

The underlying buffer allocator.

allocate

public Buffer allocate()

Allocates a new buffer with an arbitrary initial capacity and unlimited maximum capacity.

The buffer will be allocated via the BufferAllocator provided to this instance's constructor. If no BufferAllocator was provided, the default UnpooledHeapAllocator will be used.

Returns:

The allocated buffer. This will have an initial capacity that is dependent on the underlying BufferAllocator.

allocate

public Buffer allocate(long capacity)

Allocates a new buffer with an initial and an unlimited maximum capacity.

The buffer will be allocated via the BufferAllocator provided to this instance's constructor. If no BufferAllocator was provided, the default UnpooledHeapAllocator will be used.

Parameters:

capacity - The buffer capacity.

Returns:

The allocated buffer. This will have an initial capacity of the given capacity

allocate

public Buffer allocate(long initialCapacity,
                       long maxCapacity)

Allocates a new buffer with a dynamic capacity.

The buffer will be allocated via the BufferAllocator provided to this instance's constructor. If no BufferAllocator was provided, the default UnpooledHeapAllocator will be used.

Parameters:

initialCapacity - The initial buffer capacity.

maxCapacity - The maximum buffer capacity.

Returns:

The allocated buffer. This will have an initial capacity of initialCapacity and a maximum capacity of maxCapacity

copy

public <T> T copy(T object)

Copies the given object.

Type Parameters:

T - The object type.

Parameters:

object - The object to copy.

Returns:

The copied object.

writeObject

public <T> Buffer writeObject(T object)

Writes an object to a buffer.

Serialized bytes will be written to a Buffer allocated via the BufferAllocator provided to this instance's constructor. Note that for consistency with writeObject(Object, Buffer) the returned buffer will not be flipped, so users should Buffer.flip() the buffer prior to reading.

The given object must have a registered serializer or implement Serializable. If a serializable type ID was provided during registration, the type ID will be written to the returned Buffer in lieu of the class name. Types with no associated type ID will be written to the buffer with a full class name for reference during serialization.

Types that implement Serializable will be serialized using Java's ObjectOutputStream. Types that implement Externalizable will be serialized via that interface's methods unless a custom TypeSerializer has been registered for the type. Externalizable types can, however, still take advantage of faster serialization of type IDs.

Type Parameters:

T - The object type.

Parameters:

object - The object to write.

Returns:

The serialized object.

Throws:

SerializationException - If no serializer is registered for the object.

See Also:

writeObject(Object, Buffer)

writeObject

public <T> OutputStream writeObject(T object,
                                    OutputStream outputStream)

Writes an object to the given output stream.

The given object must have a registered serializer or implement Serializable. If a serializable type ID was provided during registration, the type ID will be written to the given Buffer in lieu of the class name. Types with no associated type ID will be written to the buffer with a full class name for reference during serialization.

Types that implement CatalystSerializable will be serialized via CatalystSerializable.writeObject(BufferOutput, Serializer) unless a TypeSerializer was explicitly registered for the type.

Types that implement Serializable will be serialized using Java's ObjectOutputStream. Types that implement Externalizable will be serialized via that interface's methods unless a custom TypeSerializer has been registered for the type. Externalizable types can, however, still take advantage of faster serialization of type IDs.

Type Parameters:

T - The object type.

Parameters:

object - The object to write.

outputStream - The output stream to which to write the object.

Returns:

The serialized object.

Throws:

SerializationException - If no serializer is registered for the object.

See Also:

writeObject(Object)

writeObject

public <T> Buffer writeObject(T object,
                              Buffer buffer)

Writes an object to the given buffer.

Serialized bytes will be written to the given Buffer starting at its current Buffer.position(). If the bytes Buffer.remaining() in the buffer are not great enough to hold the serialized bytes, the buffer will be automatically expanded up to the buffer's Buffer.maxCapacity().

The given object must have a registered serializer or implement Serializable. If a serializable type ID was provided during registration, the type ID will be written to the given Buffer in lieu of the class name. Types with no associated type ID will be written to the buffer with a full class name for reference during serialization.

Types that implement CatalystSerializable will be serialized via CatalystSerializable.writeObject(BufferOutput, Serializer) unless a TypeSerializer was explicitly registered for the type.

Types that implement Serializable will be serialized using Java's ObjectOutputStream. Types that implement Externalizable will be serialized via that interface's methods unless a custom TypeSerializer has been registered for the type. Externalizable types can, however, still take advantage of faster serialization of type IDs.

Type Parameters:

T - The object type.

Parameters:

object - The object to write.

buffer - The buffer to which to write the object.

Returns:

The serialized object.

Throws:

SerializationException - If no serializer is registered for the object.

See Also:

writeObject(Object)

writeObject

public <T> BufferOutput writeObject(T object,
                                    BufferOutput buffer)

Writes an object to the given buffer.

Serialized bytes will be written to the given Buffer starting at its current Buffer.position(). If the bytes Buffer.remaining() in the buffer are not great enough to hold the serialized bytes, the buffer will be automatically expanded up to the buffer's Buffer.maxCapacity().

The given object must have a registered serializer or implement Serializable. If a serializable type ID was provided during registration, the type ID will be written to the given Buffer in lieu of the class name. Types with no associated type ID will be written to the buffer with a full class name for reference during serialization.

Types that implement CatalystSerializable will be serialized via CatalystSerializable.writeObject(BufferOutput, Serializer) unless a TypeSerializer was explicitly registered for the type.

Types that implement Serializable will be serialized using Java's ObjectOutputStream. Types that implement Externalizable will be serialized via that interface's methods unless a custom TypeSerializer has been registered for the type. Externalizable types can, however, still take advantage of faster serialization of type IDs.

Type Parameters:

T - The object type.

Parameters:

object - The object to write.

buffer - The buffer to which to write the object.

Returns:

The serialized object.

Throws:

SerializationException - If no serializer is registered for the object.

See Also:

writeObject(Object)

readObject

public <T> T readObject(InputStream inputStream)

Reads an object from the given input stream.

During deserialization, the buffer will first be read to determine the type to be deserialized. If the object was written using a serializable type ID, the given ID will be used to locate the serialized type. The type must have been registered with this Serializer instance in order to perform a reverse lookup.

If the type was written to the buffer with a fully qualified class name, the class name will be used to load the object class via Class.forName(String). Serializable types must implement a no-argument constructor to be properly deserialized.

If the serialized type is an instance of CatalystSerializable, CatalystSerializable.readObject(BufferInput, Serializer) will be used to read the object attributes from the buffer.

If the type is a Serializable type serialized with native Java serialization, it will be read from the buffer via ObjectInputStream.

For types that implement ReferenceCounted, the serializer will use an internal object pool to automatically pool and reuse reference counted types for deserialization. This means that users must release ReferenceCounted types back to the object pool via ReferenceCounted.release() or ReferenceCounted.close() once complete.

Type Parameters:

T - The object type.

Parameters:

inputStream - The input stream from which to read the object.

Returns:

The read object.

Throws:

SerializationException - If no type could be read from the provided buffer.

readObject

public <T> T readObject(Buffer buffer)

Reads an object from the given buffer.

The object will be read from the given buffer starting at the current Buffer.position().

During deserialization, the buffer will first be read to determine the type to be deserialized. If the object was written using a serializable type ID, the given ID will be used to locate the serialized type. The type must have been registered with this Serializer instance in order to perform a reverse lookup.

If the type was written to the buffer with a fully qualified class name, the class name will be used to load the object class via Class.forName(String). Serializable types must implement a no-argument constructor to be properly deserialized.

If the serialized type is an instance of CatalystSerializable, CatalystSerializable.readObject(BufferInput, Serializer) will be used to read the object attributes from the buffer.

If the type is a Serializable type serialized with native Java serialization, it will be read from the buffer via ObjectInputStream.

For types that implement ReferenceCounted, the serializer will use an internal object pool to automatically pool and reuse reference counted types for deserialization. This means that users must release ReferenceCounted types back to the object pool via ReferenceCounted.release() or ReferenceCounted.close() once complete.

Type Parameters:

T - The object type.

Parameters:

buffer - The buffer from which to read the object.

Returns:

The read object.

Throws:

SerializationException - If no type could be read from the provided buffer.

readObject

public <T> T readObject(BufferInput buffer)

Reads an object from the given buffer.

The object will be read from the given buffer starting at the current Buffer.position().

During deserialization, the buffer will first be read to determine the type to be deserialized. If the object was written using a serializable type ID, the given ID will be used to locate the serialized type. The type must have been registered with this Serializer instance in order to perform a reverse lookup.

If the type was written to the buffer with a fully qualified class name, the class name will be used to load the object class via Class.forName(String). Serializable types must implement a no-argument constructor to be properly deserialized.

If the serialized type is an instance of CatalystSerializable, CatalystSerializable.readObject(BufferInput, Serializer) will be used to read the object attributes from the buffer.

If the type is a Serializable type serialized with native Java serialization, it will be read from the buffer via ObjectInputStream.

For types that implement ReferenceCounted, the serializer will use an internal object pool to automatically pool and reuse reference counted types for deserialization. This means that users must release ReferenceCounted types back to the object pool via ReferenceCounted.release() or ReferenceCounted.close() once complete.

Type Parameters:

T - The object type.

Parameters:

buffer - The buffer from which to read the object.

Returns:

The read object.

Throws:

SerializationException - If no type could be read from the provided buffer.

clone

public final Serializer clone()

Overrides:

clone in class Object