diff --git a/docs/modules/serialization/pages/implementing-dataserializable.adoc b/docs/modules/serialization/pages/implementing-dataserializable.adoc index cb7564686..df28f4413 100644 --- a/docs/modules/serialization/pages/implementing-dataserializable.adoc +++ b/docs/modules/serialization/pages/implementing-dataserializable.adoc @@ -61,159 +61,5 @@ NOTE: Since Hazelcast needs to create an instance during the deserialization, `D NOTE: `DataSerializable` is a good option if serialization is only needed for in-cluster communication. NOTE: `DataSerializable` is not supported by non-Java clients as it uses Java reflection. -If you need non-Java clients, please use <>, +If you need non-Java clients, please use xref:implementing-identifieddataserializable.adoc[IdentifiedDataSerializable], xref:implementing-portable-serialization.adoc[Portable], or xref:compact-serialization.adoc[Compact]. - -== IdentifiedDataSerializable - -For a faster serialization of objects, avoiding reflection and long class names, -Hazelcast recommends you implement `com.hazelcast.nio.serialization.IdentifiedDataSerializable` -which is a slightly better version of `DataSerializable`. - -`DataSerializable` uses reflection to create a class instance, as mentioned in -<>. -But `IdentifiedDataSerializable` uses a factory for this purpose and -it is faster during deserialization, which requires new instance creations. - -=== getClassId and getFactoryId Methods - -`IdentifiedDataSerializable` extends `DataSerializable` and introduces the following methods: - -* `int getClassId();` -* `int getFactoryId();` - -`IdentifiedDataSerializable` uses `getClassId()` instead of class name and it uses -`getFactoryId()` to load the class when given the id. To complete the implementation, -you should also implement `com.hazelcast.nio.serialization.DataSerializableFactory` and -register it into `SerializationConfig`, which can be accessed from `Config.getSerializationConfig()`. -Factory's responsibility is to return an instance of the right `IdentifiedDataSerializable` object, given the id. -This is currently the most efficient way of Serialization that Hazelcast supports off the shelf. - -=== Implementing IdentifiedDataSerializable - -Let's take a look at the following example code and configuration to see `IdentifiedDataSerializable` in action. - -[source,java] ----- -public class Employee - implements IdentifiedDataSerializable { - - private String surname; - - public Employee() {} - - public Employee( String surname ) { - this.surname = surname; - } - - @Override - public void readData( ObjectDataInput in ) - throws IOException { - this.surname = in.readString(); - } - - @Override - public void writeData( ObjectDataOutput out ) - throws IOException { - out.writeString( surname ); - } - - @Override - public int getFactoryId() { - return EmployeeDataSerializableFactory.FACTORY_ID; - } - - @Override - public int getClassId() { - return EmployeeDataSerializableFactory.EMPLOYEE_TYPE; - } - - @Override - public String toString() { - return String.format( "Employee(surname=%s)", surname ); - } -} ----- - -The methods `getClassId` and `getFactoryId` return a unique positive number within -the `EmployeeDataSerializableFactory`. -Now, let's create an instance of this `EmployeeDataSerializableFactory`. - -[source,java] ----- -public class EmployeeDataSerializableFactory - implements DataSerializableFactory{ - - public static final int FACTORY_ID = 1; - - public static final int EMPLOYEE_TYPE = 1; - - @Override - public IdentifiedDataSerializable create(int typeId) { - if ( typeId == EMPLOYEE_TYPE ) { - return new Employee(); - } else { - return null; - } - } -} ----- - -The only method you should implement is `create`, as seen in the above example. -It is recommended that you use a `switch-case` statement instead of -multiple `if-else` blocks if you have a lot of subclasses. -Hazelcast throws an exception if null is returned for `typeId`. - -[[register]] -=== Registering EmployeeDataSerializableFactory - -As the last step, you need to register `EmployeeDataSerializableFactory` declaratively -(declare in the configuration file `hazelcast.xml/yaml`) as shown below. -Note that `factory-id` has the same value of `FACTORY_ID` in the above code. -This is crucial to enable Hazelcast to find the correct factory. - -[tabs] -==== -XML:: -+ --- -[source,xml] ----- - - ... - - - - com.company.package.EmployeeDataSerializableFactory - - - - ... - ----- --- - -YAML:: -+ -[source,yaml] ----- -hazelcast: - serialization: - data-serializable-factories: - - factory-id: 1 - class-name: com.company.package.EmployeeDataSerializableFactory ----- -==== - -== Hazelcast Clients - -When using a client/server deployment, you also need to register the implemented factory on -the client side. For a Java client, the process is the same as described above to be performed -in the client configuration, e.g., `hazelcast-client.xml/yaml`. -For the other Hazelcast clients, see the following for details: - -* https://github.com/hazelcast/hazelcast-csharp-client#41-identifieddataserializable-serialization[.NET^] -* https://github.com/hazelcast/hazelcast-cpp-client#41-identifieddataserializable-serialization[C++^] -* https://github.com/hazelcast/hazelcast-nodejs-client#41-identifieddataserializable-serialization[Node.js^] -* https://github.com/hazelcast/hazelcast-python-client#41-identifieddataserializable-serialization[Python^] -* https://github.com/hazelcast/hazelcast-go-client#41-identifieddataserializable-serialization[Go^] diff --git a/docs/modules/serialization/pages/implementing-identifieddataserializable.adoc b/docs/modules/serialization/pages/implementing-identifieddataserializable.adoc new file mode 100644 index 000000000..699d2e380 --- /dev/null +++ b/docs/modules/serialization/pages/implementing-identifieddataserializable.adoc @@ -0,0 +1,150 @@ += IdentifiedDataSerializable + +For a faster serialization of objects, avoiding reflection and long class names, +Hazelcast recommends you to implement `com.hazelcast.nio.serialization.IdentifiedDataSerializable`. + +`IdentifiedDataSerializable` uses a factory to create a class instance (with reflection) and +it is fast during deserialization, which requires new instance creations. + +== getClassId and getFactoryId Methods + +`IdentifiedDataSerializable` extends xref:implementing-dataserializable.adoc[`DataSerializable`] and introduces the following methods: + +* `int getClassId();` +* `int getFactoryId();` + +`IdentifiedDataSerializable` uses `getClassId()` instead of class name and it uses +`getFactoryId()` to load the class when given the id. To complete the implementation, +you should also implement `com.hazelcast.nio.serialization.DataSerializableFactory` and +register it into `SerializationConfig`, which can be accessed from `Config.getSerializationConfig()`. +Factory's responsibility is to return an instance of the right `IdentifiedDataSerializable` object, given the id. +This is currently the most efficient way of Serialization that Hazelcast supports off the shelf. + +== Implementing IdentifiedDataSerializable + +Let's take a look at the following example code and configuration to see `IdentifiedDataSerializable` in action. + +[source,java] +---- +public class Employee + implements IdentifiedDataSerializable { + + private String surname; + + public Employee() {} + + public Employee( String surname ) { + this.surname = surname; + } + + @Override + public void readData( ObjectDataInput in ) + throws IOException { + this.surname = in.readString(); + } + + @Override + public void writeData( ObjectDataOutput out ) + throws IOException { + out.writeString( surname ); + } + + @Override + public int getFactoryId() { + return EmployeeDataSerializableFactory.FACTORY_ID; + } + + @Override + public int getClassId() { + return EmployeeDataSerializableFactory.EMPLOYEE_TYPE; + } + + @Override + public String toString() { + return String.format( "Employee(surname=%s)", surname ); + } +} +---- + +The methods `getClassId` and `getFactoryId` return a unique positive number within +the `EmployeeDataSerializableFactory`. +Now, let's create an instance of this `EmployeeDataSerializableFactory`. + +[source,java] +---- +public class EmployeeDataSerializableFactory + implements DataSerializableFactory{ + + public static final int FACTORY_ID = 1; + + public static final int EMPLOYEE_TYPE = 1; + + @Override + public IdentifiedDataSerializable create(int typeId) { + if ( typeId == EMPLOYEE_TYPE ) { + return new Employee(); + } else { + return null; + } + } +} +---- + +The only method you should implement is `create`, as seen in the above example. +It is recommended that you use a `switch-case` statement instead of +multiple `if-else` blocks if you have a lot of subclasses. +Hazelcast throws an exception if null is returned for `typeId`. + +[[register]] +== Registering EmployeeDataSerializableFactory + +As the last step, you need to register `EmployeeDataSerializableFactory` declaratively +(declare in the configuration file `hazelcast.xml/yaml`) as shown below. +Note that `factory-id` has the same value of `FACTORY_ID` in the above code. +This is crucial to enable Hazelcast to find the correct factory. + +[tabs] +==== +XML:: ++ +-- +[source,xml] +---- + + ... + + + + com.company.package.EmployeeDataSerializableFactory + + + + ... + +---- +-- + +YAML:: ++ +[source,yaml] +---- +hazelcast: + serialization: + data-serializable-factories: + - factory-id: 1 + class-name: com.company.package.EmployeeDataSerializableFactory +---- +==== + +== Hazelcast Clients + +When using a client/server deployment, you also need to register the implemented factory on +the client side. For a Java client, the process is the same as described above to be performed +in the client configuration, e.g., `hazelcast-client.xml/yaml`. +For the other Hazelcast clients, see the following for details: + +* https://github.com/hazelcast/hazelcast-csharp-client#41-identifieddataserializable-serialization[.NET^] +* https://github.com/hazelcast/hazelcast-cpp-client#41-identifieddataserializable-serialization[C++^] +* https://github.com/hazelcast/hazelcast-nodejs-client#41-identifieddataserializable-serialization[Node.js^] +* https://github.com/hazelcast/hazelcast-python-client#41-identifieddataserializable-serialization[Python^] +* https://github.com/hazelcast/hazelcast-go-client#41-identifieddataserializable-serialization[Go^] diff --git a/docs/modules/serialization/pages/serialization.adoc b/docs/modules/serialization/pages/serialization.adoc index d26eb0155..e2ad6fa95 100644 --- a/docs/modules/serialization/pages/serialization.adoc +++ b/docs/modules/serialization/pages/serialization.adoc @@ -20,6 +20,54 @@ Hazelcast offers the following serialization options: |=== | Serialization interface| Advantages| Disadvantages|Client support +| xref:compact-serialization.adoc[Compact Serialization] +| * More memory usage efficient than `Portable` + +* Convenient, flexible, and can be used with no configuration + +* Does not require class to implement an interface + +* Supports schema evolution + +* Partial deserialization is supported during queries and indexing + +|* Specific to Hazelcast + +* Schema is not part of the data but schema distribution +may incur costs on short-lived use cases + +|All clients + +| xref:serializing-json.adoc[`HazelcastJsonValue`] +| * No member-side coding required + +|* Specific to Hazelcast + +* Requires extra metadata to be stored on members. + +|All clients + +| xref:implementing-dataserializable.adoc[`IdentifiedDataSerializable`] +| * More CPU and memory usage efficient than `Serializable` + +* Reflection is not used during deserialization + +| * Specific to Hazelcast + +* Serialization interface must be implemented + +* A factory and configuration must be implemented + +|All clients +|=== + +.Other alternative serialization options +[%collapsible] +==== +[cols="3,3a,4a,1a"] +|=== +| Serialization interface| Advantages| Disadvantages|Client support + | xref:implementing-java-serializable.adoc[`Serializable`] | * A standard and basic Java interface @@ -44,19 +92,6 @@ Hazelcast offers the following serialization options: |Java only -| xref:implementing-dataserializable.adoc[`IdentifiedDataSerializable`] -| * More CPU and memory usage efficient than `Serializable` - -* Reflection is not used during deserialization - -| * Specific to Hazelcast - -* Serialization interface must be implemented - -* A Factory and configuration must be implemented - -|All clients - | xref:implementing-portable-serialization.adoc[`Portable`] | * More CPU and memory usage efficient than `Serializable` @@ -87,35 +122,9 @@ Hazelcast offers the following serialization options: * Plug in and configuration is required -|All clients - -| xref:compact-serialization.adoc[Compact Serialization] -| * More memory usage efficient than `Portable` - -* Convenient, flexible, and can be used with no configuration - -* Does not require class to implement an interface - -* Supports schema evolution - -* Partial deserialization is supported during queries and indexing - -|* Specific to Hazelcast - -* Schema is not part of the data but schema distribution -may incur costs on short-lived use cases - -|All clients - -| xref:serializing-json.adoc[`HazelcastJsonValue`] -| * No member-side coding required - -|* Specific to Hazelcast - -* Requires extra metadata to be stored on members. - |All clients |=== +==== [[steps]] == How Hazelcast Serializes Objects diff --git a/docs/modules/serialization/partials/nav.adoc b/docs/modules/serialization/partials/nav.adoc index 0ad422ed0..76d7854f9 100644 --- a/docs/modules/serialization/partials/nav.adoc +++ b/docs/modules/serialization/partials/nav.adoc @@ -1,11 +1,13 @@ * Serialization ** xref:serialization:serialization.adoc[Overview] -** xref:serialization:implementing-java-serializable.adoc[Java Serializable and Externalizable] -** xref:serialization:implementing-dataserializable.adoc[DataSerializable] -** xref:serialization:implementing-portable-serialization.adoc[Portable] -** xref:serialization:serializing-json.adoc[HazelcastJsonValue] ** xref:serialization:compact-serialization.adoc[] -** xref:serialization:custom-serialization.adoc[] -** xref:serialization:global-serializer.adoc[] -** xref:serialization:implementing-hazelcastinstanceaware.adoc[HazelcastInstanceAware] +** xref:serialization:serializing-json.adoc[HazelcastJsonValue] +** xref:serialization:implementing-identifieddataserializable.adoc[IdentifiedDataSerializable] +** Other Serialization Options +*** xref:serialization:implementing-java-serializable.adoc[Java Serializable and Externalizable] +*** xref:serialization:implementing-dataserializable.adoc[DataSerializable] +*** xref:serialization:implementing-portable-serialization.adoc[Portable] +*** xref:serialization:custom-serialization.adoc[] +*** xref:serialization:global-serializer.adoc[] +*** xref:serialization:implementing-hazelcastinstanceaware.adoc[HazelcastInstanceAware] ** xref:serialization:serialization-configuration.adoc[]