Skip to content
Switch branches/tags
Go to file


Failed to load latest commit information.

SubZero - Fast Serialization for Hazelcast

Maven Central Build Status Join the chat at

SubZero provides dead easy Hazelcast - Kryo integration. No coding required.


Kryo is a popular serialization library. It's super-fast yet easy-to-use. It does not pollute your domain model and it can even serialize classes which are not marked as Serializable.

Hazelcast has no out-of-the box support for Kryo. It's rather easy to integrate it, however it means everyone has to write the same code and face the same bugs.

SubZero aims to make Kryo - Hazelcast integration as simple as possible.

How to Use SubZero?

Use SubZero for all classes

SubZero will completely replace Java serialization. Hazelcast internal serializers will still take precedence.

Declarative Configuration:

Insert this snippet into your Hazelcast configuration XML:

        <global-serializer override-java-serialization="true">

Programmatic Configuration:

Config config = new Config();
HazelcastInstance hz = Hazelcast.newHazelcastInstance(config);

Use SubZero for selected classes only

In this mode Hazelcast will use SubZero for selected classes only.

Declarative Configuration:

        <serializer type-class="some.package.Foo"
        <serializer type-class="some.package.Bar"

Programmatic Configuration:

Config config = new Config();
SubZero.useForClasses(config, Foo.class, Bar.class);
HazelcastInstance hz = Hazelcast.newHazelcastInstance(config);

All cluster members have to use SubZero for the same types and the types have to be declared in the same order.

Maven Coordinates

SubZero is available in Maven Central. Just insert this snippet into pom.xml and you are ready to roll!


This version has all dependencies packaged inside. You can also use a version with regular dependencies:


Configuration Options

  • System property subzero.buffer.size.kb sets buffer size for Kryo. Default value: 16KB
  • System property sets base for auto-generated type id
  • System property subzero.referenceresolver.class sets the ReferenceResolver implementation. Default value: com.esotericsoftware.kryo.util.MapReferenceResolver

Custom Kryo Serializers

SubZero can use custom Kryo serializers.

Simple Registration

Just create a file and have it on a classpath of your project. SubZero expects the property file to have the following format:


Advanced Registration

The simple approach works fine in most cases, but sometimes you do not know domain classnames up front - for example when the class is created by a factory - think of Collections::unmodifiableList

In this case it's OK to have just the Kryo serializers in property file. For example:


Subzero expects the serializer to have a method registerSerializers which accepts an instance of Kryo as its only argument.

It's up to the serializer to register itself into Kryo. This approach works for most serializer from this project. Actually serializers from this project are considered to be well-known and it's ok to use just a classname without package in the property file. For example:


Default Kryo Serializer

Kryo uses FieldSerializer by default. Sometimes you want to change it.

For example when you want support adding new fields then you have to use CompatibleFieldSerializer. You can do this by using the key defaultSerializer in the property file.

Example: defaultSerializer=com.esotericsoftware.kryo.serializers.CompatibleFieldSerializer

This mechanism also understands the concept of well-known packages: Serializers from the Kryo project itself and Magro serializers can be referenced just by a simple classname, no need to specify package. This is handy when using the Subzero-all version which has the Kryo serializers relocated into another package.


SubZero aims to provide the simplest possible way to hook Kryo serialization into Hazelcast.

Default SubZero serializer implementation uses auto-generated class type IDs and relies on a serializer registration order. This means all your cluster members have to use the same order in Hazelcast serializer configuration. This can be somewhat fragile. You can make it more robust by subclassing Serializer and returning a fixed class ID:

public class HashMapSerializerExample extends AbstractTypeSpecificUserSerializer<HashMap> {

    public HashMapSerializerExample() {

     * TypeId has to be a unique for each registered serializer.
     * @return TypeId of the class serialized by this serializer
    public int getTypeId() {
        return 10000;

Hazelcast Compatibility

SubZero is continuously tested with Hazelcast 3.6, 3.7, 3.8, 3.9, 3.10, 3.11, 3.12 and 4.0

Further Ideas

  • More serialization strategies. Currently Kryo is the only supported strategy. I would like to add Fast Serialization
  • Serializer Generator - SubZero could generate highly-optimized serializer for simple classes
  • AutoPortable - serialize an ordinary class as it implemented Portable interface

Notable Contributors


This is a community project not affiliated with the Hazelcast project.