com.devexperts.io

Class Marshaller<T>

java.lang.Object

com.devexperts.io.Marshaller<T>

Type Parameters:

T - the marshalled object's type.

Direct Known Subclasses:

Marshaller.Typed

public abstract class Marshaller<T>
extends Object

A strategy that defines how an object is represented in a byte array inside of a Marshalled object. Marshallers should write some magic number at the beginning of their byte array as a fail-safe check, so if, by mistake, an array of bytes that was created by one marshaller is given the different marshaller to deserialize it fails quickly and cleanly.

There is a number of built-in marshallers provided:

• SERIALIZATION marshaller uses Java Object Serialization to convert object to/from bytes. Its type-safe version that also performs run-time type check is available via serialization(Class) method. The corresponding byte array always starts with two bytes 0xAC and 0xED or with ZLIB compression header.
• Typed marshaller that uses compact serialization of primitive data types and arrays is available via forClasses(Class[]) and forTypes(String) methods. The corresponding byte array always starts with 0xE8 byte or with ZLIB compression header.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Marshaller.Typed<T> Typed marshaller that marshals instances of a single type or an array of types.

Field Summary

Fields

Modifier and Type	Field and Description
static Marshaller<Object>	SERIALIZATION Converts object to/from bytes using Java Object Serialization.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	Marshaller()

Method Summary

Modifier and Type	Method and Description
boolean	equals(Object obj) Indicates whether some other object is "equal to" this one.
static <T> Marshaller.Typed<T>	forClass(Class<? extends T> clazz) Returns typed marshaller for the given class.
static <T> Marshaller.Typed<T[]>	forClasses(Class<? extends T>... classes) Returns typed marshaller for the given array of classes.
static Marshaller.Typed<?>	forType(String type) Returns typed marshaller for the given type name.
static Marshaller.Typed<Object[]>	forTypes(String types) Returns typed marshaller for the given comma-separated list of type names.
int	hashCode() Returns a hash code value for the object.
int	readMarshalledLength(BufferedInput in) Reads the length of an object in serialized form from the input according to this marshalling strategy.
abstract T	readObjectFrom(BufferedInput in, int length, SerialClassContext serialContext) Reads object representation according to this marshalling strategy from the specified input.
boolean	representsNullObjectAsNullBytes() Returns true if this marshaller represents null object with null byte array.
static Marshaller<Object>	serialization() Returns marshaller that converts object to/from bytes using Java Object Serialization.
static <T> Marshaller<T>	serialization(Class<T> clazz) Returns marshaller that converts object to/from bytes using Java Object Serialization.
boolean	supportsNullObject() Returns true if this marshaller support marshalling of null objects in writeObjectTo method.
void	writeMarshalledLength(BufferedOutput out, int length) Writes the length of an object in serialized form to the output according to this marshalling strategy.
abstract void	writeObjectTo(BufferedOutput out, T object) Writes byte representation of the object according to this marshalling strategy into the specified output.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Field Detail

SERIALIZATION

public static final Marshaller<Object> SERIALIZATION

Converts object to/from bytes using Java Object Serialization. The marshaller works via IOUtil.objectToBytes and IOUtil.bytesToObject methods. For a type-safe generic version of this marshaller, use serialization(Class).

Constructor Detail

Marshaller

protected Marshaller()

Method Detail

serialization

public static <T> Marshaller<T> serialization(Class<T> clazz)

Returns marshaller that converts object to/from bytes using Java Object Serialization. The marshaller works via IOUtil.objectToBytes and IOUtil.bytesToObject methods. It performs run-time check that serialized and deserialized object is of a specified type. Serialization marshallers with different types produce the same byte arrays which are binary compatible.

Parameters:

clazz - the type of the object to serialize and to expect after deserialization.

Returns:

marshaller that converts object to bytes using Java Object Serialization.

serialization

public static Marshaller<Object> serialization()

Returns marshaller that converts object to/from bytes using Java Object Serialization. The marshaller works via IOUtil.objectToBytes, IOUtil.bytesToObject and IOUtil.bytesToObject methods. It performs run-time check that serialized and deserialized object is of a specified type. Serialization marshallers with different types produce the same byte arrays which are binary compatible.

Returns:

marshaller that converts object to bytes using Java Object Serialization.

forClass

public static <T> Marshaller.Typed<T> forClass(Class<? extends T> clazz)

Returns typed marshaller for the given class. If the class corresponds to primitive type or array, then the object is converted to byte array in the compact form described in IOUtil. Otherwise, Java Object Serialization is used. Unlike serialization(Class) serialization} marshallers, typed marshallers for different types are not the same and are not compatible on a byte-array level even if the actual serialized objects are the same. The same exact marshaller shall be used for writing and for reading.

Parameters:

clazz - the class.

Returns:

typed marshaller.

forClasses

@SafeVarargs
public static <T> Marshaller.Typed<T[]> forClasses(Class<? extends T>... classes)

Returns typed marshaller for the given array of classes. If the class corresponds to primitive type or array, then the object is converted to byte array in the compact form described in IOUtil. Otherwise, Java Object Serialization is used. Unlike serialization(Class) serialization} marshallers, typed marshallers for different types are not the same and are not compatible on a byte-array level even if the actual serialized objects are the same. The same exact marshaller shall be used for writing and for reading.

Parameters:

classes - the array of classes.

Returns:

typed marshaller.

forType

public static Marshaller.Typed<?> forType(String type)

Returns typed marshaller for the given type name. If the type corresponds to primitive type or array, then the object is converted to byte array in the compact form described in IOUtil. Otherwise, Java Object Serialization is used. Unlike serialization(Class) serialization} marshallers, typed marshallers for different types are not the same and are not compatible on a byte-array level even if the actual serialized objects are the same. The same exact marshaller shall be used for writing and for reading.

Parameters:

type - the type name.

Returns:

typed marshaller.

forTypes

public static Marshaller.Typed<Object[]> forTypes(String types)

Returns typed marshaller for the given comma-separated list of type names. If the type corresponds to primitive type or array, then the object is converted to byte array in the compact form described in IOUtil. Otherwise, Java Object Serialization is used. Unlike serialization(Class) serialization} marshallers, typed marshallers for different types are not the same and are not compatible on a byte-array level even if the actual serialized objects are the same. The same exact marshaller shall be used for writing and for reading.

Parameters:

types - the comma-separated list of type names.

Returns:

typed marshaller.

writeMarshalledLength

public void writeMarshalledLength(BufferedOutput out,
                                  int length)
                           throws IOException

Writes the length of an object in serialized form to the output according to this marshalling strategy. This implementation uses writeCompactInt.

Parameters:

out - the destination to write to.

length - of an object in serialized form to be written or -1 when the object is null.

Throws:

IOException - if an I/O error occurs.

readMarshalledLength

public int readMarshalledLength(BufferedInput in)
                         throws IOException

Reads the length of an object in serialized form from the input according to this marshalling strategy. This implementation uses readCompactInt.

Parameters:

in - the source to read from.

Returns:

the length of an object in serialized form or -1 if the marshalled object is null.

Throws:

IOException - if an I/O error occurs.

writeObjectTo

public abstract void writeObjectTo(BufferedOutput out,
                                   T object)
                            throws IOException

Writes byte representation of the object according to this marshalling strategy into the specified output. This method should not write a length of the representation at the beginning, but should write some kind of a magic signature so that readObjectFrom can fail fast when trying to read wrong representation that was created with different marshaller.

Parameters:

out - the output.

object - the object to be serialized.

Throws:

NullPointerException - if object is null.

IllegalArgumentException - if this marshaller does not support the specified object.

IOException - if object cannot be serialized.

readObjectFrom

public abstract T readObjectFrom(BufferedInput in,
                                 int length,
                                 SerialClassContext serialContext)
                          throws IOException

Reads object representation according to this marshalling strategy from the specified input.

Parameters:

in - the input.

length - the length in bytes of object representation.

serialContext - the serial class context.

Returns:

the deserialized object.

Throws:

IllegalArgumentException - if length is negative.

IOException - if object cannot be deserialized.

supportsNullObject

public boolean supportsNullObject()

Returns true if this marshaller support marshalling of null objects in writeObjectTo method. If this method returns false, then an attempt to create marshalled object with Marshalled.forObject(null, this) throws NullPointerException.

This implementation returns true.

Returns:

true if this marshaller support marshalling of null objects in

representsNullObjectAsNullBytes

public boolean representsNullObjectAsNullBytes()

Returns true if this marshaller represents null object with null byte array. This method is never called if supportsNullObject() returns false. If this method returns true, then writeObjectTo is never invoked for null object.

This implementation returns true.

Returns:

true if this marshaller represents null object with null byte array.

equals

public boolean equals(Object obj)

Indicates whether some other object is "equal to" this one. This implementation return true when the other object's class is equal to this one.

Overrides:

equals in class Object

Returns:

true if this object is the same as the obj argument; false otherwise.

hashCode

public int hashCode()

Returns a hash code value for the object. This implementation return hashCode of this object's class name.

Overrides:

hashCode in class Object

Returns:

a hash code value for this object.