Package org.joda.beans.ser.bin

Class JodaBeanBinWriter

java.lang.Object

org.joda.beans.ser.bin.JodaBeanBinWriter

public class JodaBeanBinWriter
extends Object

Provides the ability for a Joda-Bean to be written to a binary format.

This class is immutable and may be used from multiple threads.

Standard format

The binary format is based on MessagePack v2.0. Each bean is output as a map using the property name.

Most simple types, defined by Joda-Convert, are output as MessagePack strings. However, MessagePack nil, boolean, float, integral and bin types are also used for null, byte[] and the Java numeric primitive types (excluding char).

Beans are output using MessagePack maps where the key is the property name. Collections are output using MessagePack maps or arrays. Multisets are output as a map of value to count.

If a collection contains a collection then addition meta-type information is written to aid with deserialization. At this level, the data read back may not be identical to that written.

Where necessary, the Java type is sent using an 'ext' entity. Three 'ext' types are used, one each for beans, meta-type and simple. The class name is passed as the 'ext' data. The 'ext' value is sent as an additional key-value pair for beans, with the 'ext' as the key and 'nil' as the value. Where the additional type information is not about a bean, a tuple is written using a size 1 map where the key is the 'ext' data and the value is the data being annotated.

Type names are shortened by the package of the root type if possible. Certain basic types are also handled, such as String, Integer, File and URI.

Referencing format

The referencing format is based on the standard format. As a more complex format, it is intended to be consumed only by Joda-Beans (whereas the standard format could be consumed by any consumer using MsgPack). Thus this format is not fully documented and may change over time.

The referencing format only supports serialization of instances of ImmutableBean and other basic types. If any mutable beans are encountered during traversal an exception will be thrown.

An initial pass of the bean is used to build up a map of unique immutable beans and unique immutable instances of other classes (based on an equality check). Then the class and property names for each bean class is serialized up front as a map of class name to list of property names, along with class information for any class where type information would be required when parsing and is not available on the metabean for the enclosing bean object.

Each unique immutable bean is output as a list of each property value using the fixed property order previously serialized. Subsequent instances of unique objects (defined by an equality check) are replaced by references to the first serialized instance.

The Java type names are sent using an 'ext' entity. Five 'ext' types are used, one each for beans, meta-type and simple, reference keys and reference lookups. The class name is passed as the 'ext' data. The 'ext' value is sent as the first item in an array of property values for beans, an integer referring to the location in the initial class mapping. Where the additional type information is not about a bean, a tuple is written using a size 1 map where the key is the 'ext' data and the value is the data being annotated.

For references, when an object will be referred back to it is written as a map of size one with 'ext' as the key and the object that should be referred to as the value. When that same object is referred back to it is written as 'ext' with the data from the initial 'ext'.

Constructor Summary

Constructors

Constructor	Description
JodaBeanBinWriter(JodaBeanSer settings)	Creates an instance.
JodaBeanBinWriter(JodaBeanSer settings, boolean referencing)	Creates an instance.

Method Summary

Modifier and Type	Method	Description
byte[]	write(Bean bean)	Writes the bean to an array of bytes.
byte[]	write(Bean bean, boolean rootType)	Writes the bean to an array of bytes.
void	write(Bean bean, boolean rootType, OutputStream output)	Writes the bean to the OutputStream.
void	write(Bean bean, OutputStream output)	Writes the bean to the OutputStream.

Methods inherited from class java.lang.Object

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

Constructor Detail

JodaBeanBinWriter

public JodaBeanBinWriter(JodaBeanSer settings)

Creates an instance.

Parameters:

settings - the settings to use, not null

JodaBeanBinWriter

public JodaBeanBinWriter(JodaBeanSer settings,
                         boolean referencing)

Creates an instance.

Parameters:

settings - the settings to use, not null

referencing - whether to use referencing

Method Detail

write

public byte[] write(Bean bean)

Writes the bean to an array of bytes.

The type of the bean will be set in the message.

Parameters:

bean - the bean to output, not null

Returns:

the binary data, not null

write

public byte[] write(Bean bean,
                    boolean rootType)

Writes the bean to an array of bytes.

Parameters:

bean - the bean to output, not null

rootType - true to output the root type

Returns:

the binary data, not null

write

public void write(Bean bean,
                  OutputStream output)
           throws IOException

Writes the bean to the OutputStream.

The type of the bean will be set in the message.

Parameters:

bean - the bean to output, not null

output - the output stream, not null

Throws:

IOException - if an error occurs

write

public void write(Bean bean,
                  boolean rootType,
                  OutputStream output)
           throws IOException

Writes the bean to the OutputStream.

Parameters:

bean - the bean to output, not null

rootType - true to output the root type

output - the output stream, not null

Throws:

IOException - if an error occurs