Serializer

EclipseStore’s serialization engine, which is used by the storage, can also be used standalone. It is usable as a replacement for the default Java serialization to convert objects to a binary format and vice versa. This API is part of the persistence-binary module:

Prerequisites

pom.xml
<dependencies>
	<dependency>
		<groupId>org.eclipse.serializer</groupId>
		<artifactId>serializer</artifactId>
		<version>1.4.0</version>
	</dependency>
</dependencies>

Usage

You can use any medium type, but for most purposes, the byte array version should be sufficient to transfer the serialized form over the transport layer of your choice. Simply create a serializer instance, optionally based on a foundation, and call the serialize and deserialize methods.

final SerializerFoundation<?> foundation = SerializerFoundation.New()
	.registerEntityTypes(Customer.class);
final Serializer<byte[]> serializer = Serializer.Bytes(foundation);
byte[] data = serializer.serialize(customer);
Customer restored = serializer.deserialize(data);

Type handling

The serializer uses the EclipseStore’s type handling system. This includes registration of new types on demand during serialization and legacy type mapping when deserializing. The SerializerFoundation provides an API like the MicroStream storage to configure the type handling behavior.

The default Serializer implementation does not include type information in the serialized output! If you want to deserialize that with another serializer instance, you must register all classes using the SerializerFoundation before you create the serializer or use a TypedSerializer!

TypeDictionary

The serializer internally generates a dictionary that describes all serialized types. This dictionary can be exported and imported to exchange those type informations between different serializer instances.

Exporting the type dictionary

The current type information can be obtained as Sting using the serializers exportTypeDictionay() method:

final String typeDictionaryString = serializer.exportTypeDictionay();

Importing the type dictionary

To import an initial type dictionary, it must be supplied as a String. The SerializerFoundation offers methods to import that type dictionary string before the serializer instance is generated:

Using the static New(String typeDictionaryString) Method:
final SerializerFoundation<?> foundation = SerializerFoundation.New(typeDictionaryString);
Using the setInitialTypeDictionary(String typeDictionaryString) method:
final SerializerFoundation<?> foundation = SerializerFoundation.New();
foundation.setInitialTypeDictionary(typeDictionaryString);

TypedSerializer

The TypedSerializer implementation includes type information into the serialized output. By default, the complete set of type information is included in all serialized output.

final Serializer<byte[]> serializer = TypedSerializer.Bytes(foundation);
byte[] data = serializer.serialize(customer);
Customer restored = serializer.deserialize(data);

Configuring the included type information

To reduce the serialized data, it is possible to configure the included type information by supplying a SerializerTypeInfoStrategyCreator to the SerializerFoundation.

final SerializerFoundation<?> foundation = SerializerFoundation.New()
	.setSerializerTypeInfoStrategyCreator(
		new SerializerTypeInfoStrategyCreator.IncrementalDiff(false));
return TypedSerializer.Bytes(foundation);

Available options are:

Property Description

TypeDictionary

Includes type information for all types currently known to the serializer, including those registered during the setup.

Diff

Includes type information for all types currently known to the serializer, including those registered during the setup.

IncrementalDiff

Includes only type information for types added to the serializers type registry in the current serialization. Types that are registered during the serializer’s setup are never included.

The includeTypeInfoOnce parameter:

All three serializer type handling strategies allow specifying that the type information gets included only once if it has not changed by setting the parameter includeTypeInfoOnce = true. If so, the type information is only included if new types are registered during the current serialization.