A newer version of Hazelcast Platform is available.

View latest

Serialization Configuration Wrap-Up

This section summarizes the configuration of serialization options, explained in the above sections, into all-in-one examples. The following are example serialization configurations.

  • XML

  • YAML

  • Java

<hazelcast>
    <serialization>
        <allow-override-default-serializers>true</allow-override-default-serializers>
    </serialization>
</hazelcast>
hazelcast:
    serialization:
        allow-override-default-serializers: true
SerializationConfig{
  boolean isAllowOverrideDefaultSerializers();

  SerializationConfig setAllowOverrideDefaultSerializers(final boolean allowOverrideDefaultSerializers);}

Configuration Options

Use these configuration options to configure serialization:

Deprecation Notice for Portable Serialization

Portable Serialization has been deprecated. We recommend you use Compact Serialization as Portable Serialization will be removed as of version 7.0.

Table 1. Serialization configuration options
Option Description Default

portable-version

Defines the version of a portable serialization implementation. A portable version differentiates two of the same classes that have differ such as those that have different fields or different field types.

0

use-native-byte-order

Whether to use the native byte order of the underlying platform.

false

byte-order

Defines the byte order that the serialization uses: BIG_ENDIAN or LITTLE_ENDIAN.

BIG_ENDIAN

enable-compression

Enables compression if the default Java serialization is used.

false

enable-shared-object

Enables shared object if the default Java serialization is used.

false

allow-unsafe

Whether to allow unsafe to be used.

false

allow-override-default-serializers

Whether to allow built-in serializers to be overridden.

false

data-serializable-factory

Registers a class that implements com.hazelcast.nio.serialization.DataSerializableFactory. See Registering EmployeeDataSerializableFactory

portable-factory

Registers a PortableFactory class. See Registering the Portable Factory

global-serializer

Registers a global serializer class to be used when no other serializer is available. This element has the optional boolean attribute override-java-serialization. When set to true, the Java serialization step is assumed to be handled by the global serializer. Default: false. See Global Serializer.

serializer

The class name of the custom serializer implementation. See Custom Serialization

check-class-def-errors

Whether to check for class definition errors at startup and throw a serialization exception with an error definition.

java-serialization-filter

Provides deserialization protection based on whitelisting and blacklisting the class/package names.

compact-serialization-config

Provides ways to enable Compact serialization and register explicit or reflective compact serializers for classes. See CompactSerializationConfig section for details.

Full Example of Serialization Configuration

The following are example configuration settings for various serializers.

  • XML

  • YAML

<hazelcast>
    <serialization>
        <portable-version>0</portable-version>
        <use-native-byte-order>false</use-native-byte-order>
        <byte-order>BIG_ENDIAN</byte-order>
        <data-serializable-factories>
            <data-serializable-factory factory-id="1">com.hazelcast.examples.DataSerializableFactory
            </data-serializable-factory>
        </data-serializable-factories>
        <portable-factories>
            <portable-factory factory-id="1">com.hazelcast.examples.PortableFactory</portable-factory>
        </portable-factories>
        <serializers>
            <global-serializer>com.hazelcast.examples.GlobalSerializerFactory</global-serializer>
            <serializer type-class="com.hazelcast.examples.DummyType"
                        class-name="com.hazelcast.examples.SerializerFactory"/>
        </serializers>
        <check-class-def-errors>true</check-class-def-errors>
        <java-serialization-filter defaults-disabled="true">
            <blacklist>
                <class>com.acme.app.BeanComparator</class>
            </blacklist>
            <whitelist>
                <class>java.lang.String</class>
                <class>example.Foo</class>
                <package>com.acme.app</package>
                <package>com.acme.app.subpkg</package>
                <prefix>com.hazelcast.</prefix>
                <prefix>java</prefix>
            </whitelist>
        </java-serialization-filter>
    </serialization>
</hazelcast>
hazelcast:
  serialization:
    portable-version: 0
    use-native-byte-order: false
    byte-order: BIG_ENDIAN
    data-serializable-factories:
      - factory-id: 1
        class-name: com.hazelcast.examples.DataSerializableFactory
    portable-factories:
      - factory-id: 1
        class-name: com.hazelcast.examples.PortableFactory
    global-serializer:
      class-name: com.hazelcast.examples.GlobalSerializerFactory
    serializers:
      - type-class: com.hazelcast.examples.DummyType
        class-name: com.hazelcast.examples.SerializerFactory
    check-class-def-errors: true
    java-serialization-filter:
      defaults-disabled: true
      blacklist:
        class:
          - com.acme.app.BeanComparator
      whitelist:
        class:
          - java.lang.String
          - example.Foo
        package:
          - com.acme.app
          - com.acme.app.subpkg
        prefix:
          - com.hazelcast.
          - java

Programmatic Configuration:

Config config = new Config();
SerializationConfig srzConfig = config.getSerializationConfig();
srzConfig.setPortableVersion( "2" ).setUseNativeByteOrder( true );
srzConfig.setAllowUnsafe( true ).setEnableCompression( true );
srzConfig.setCheckClassDefErrors( true );

GlobalSerializerConfig globSrzConfig = srzConfig.getGlobalSerializerConfig();
globSrzConfig.setClassName( "abc.Class" );

SerializerConfig serializerConfig = srzConfig.getSerializerConfig();
serializerConfig.setTypeClass( "Employee" )
                .setClassName( "com.EmployeeSerializer" );

Serialization configuration has the following elements.

  • portable-version: Defines versioning of the portable serialization. Portable version differentiates two of the same classes that have changes, such as adding/removing field or changing a type of a field.

  • use-native-byte-order: Set to true to use native byte order for the underlying platform. Its default value is false.

  • byte-order: Defines the byte order that the serialization uses: BIG_ENDIAN or LITTLE_ENDIAN. Its default value is BIG_ENDIAN.

  • enable-compression: Enables compression if default Java serialization is used. Its default value is false.

  • enable-shared-object: Enables shared object if default Java serialization is used. Its default value is false.

  • allow-unsafe: Set to true to allow unsafe to be used. Its default value is false.

  • data-serializable-factory: Custom classes implementing com.hazelcast.nio.serialization.DataSerializableFactory to be registered. These can be used to speed up serialization/deserialization of objects.

  • portable-factory: The PortableFactory class to be registered.

  • global-serializer: The global serializer class to be registered if no other serializer is applicable. This element has the optional boolean attribute override-java-serialization. If set to true, the Java serialization step is assumed to be handled by the global serializer. Java Serializable and Externalizable is prior to global serializer by default (false).

  • serializer: The class name of the serializer implementation.

  • check-class-def-errors: When set to true, the serialization system checks for class definitions error at start and throws a Serialization Exception with an error definition.

  • java-serialization-filter: Provides deserialization protection based on whitelisting and blacklisting the class/package names.

  • compact-serialization-config: (BETA) Provides ways to enable Compact serialization, register explicit or reflective Compact serializers for classes. See CompactSerializationConfig section for details.