A newer version of Platform is available.

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.