spring-data-gemfire/docs/src/docbkx/reference/serialization.xml

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE preface PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
<chapter id="serialization">
  <title>Working with GemFire Serialization</title>

  <para>To improve overall performance of the data fabric, GemFire supports a
  dedicated serialization protocol that is both faster and offers more compact
  results over the standard Java serialization and works transparently across
  various language <ulink
  url="http://community.gemstone.com/display/gemfire/Interoperability">platforms</ulink>
  (such as <ulink
  url="http://community.gemstone.com/display/gemfire/Serialization+in+Java">Java</ulink>,
  <ulink
  url="http://community.gemstone.com/display/gemfire/Serialization+in+.NET">.NET</ulink>
  and C++). This chapter discusses the various ways in which SGF simplifies
  and improves GemFire custom serialization in Java.</para>

  <section id="serialization:wiring">
    <title>Wiring deserialized instances</title>

    <para>It is fairly common for serialized objects to have transient data.
    Transient data is often dependent on the node or environment where it
    lives at a certain point in time, for example a DataSource. Serializing
    such information is useless (and potentially even dangerous) since it is
    local to a certain VM/machine. For such cases, SGF offers a special <ulink
    url="http://www.gemstone.com/docs/6.0.1/product/docs/japi/com/gemstone/gemfire/Instantiator.html"><classname>Instantiator</classname></ulink>
    that performs wiring for each new instance created by GemFire during
    deserialization.</para>

    <para>Through such a mechanism, one can rely on the Spring container to
    inject (and manage) certain dependencies making it easy to split transient
    from persistent data and have <emphasis>rich domain objects</emphasis> in
    a transparent manner (Spring users might find this approach similar to
    that of <ulink
    url="http://static.springsource.org/spring/docs/3.0.x/spring-framework-reference/html/aop.html#aop-atconfigurable"><literal>@Configurable</literal></ulink>).
    The <classname>WiringInstantiator</classname> works just like
    <classname>WiringDeclarableSupport</classname>, trying to first locate a
    bean definition as a wiring template and following to autowiring
    otherwise. Please refer to the previous section (<xref
    linkend="apis:declarable"/>) for more details on wiring
    functionality.</para>

    <para>To use this <classname>Instantiator</classname>, simply declare it
    as a usual bean:</para>

    <programlisting language="xml">&lt;bean id="instantiator" class="org.springframework.data.gemfire.serialization.WiringInstantiator"&gt;
  &lt;!-- DataSerializable type --&gt;
  &lt;constructor-arg&gt;org.pkg.SomeDataSerializableClass&lt;/constructor-arg&gt;
  &lt;!-- type id --&gt;
  &lt;constructor-arg&gt;95&lt;/constructor-arg&gt;
&lt;/bean&gt;</programlisting>

    <para>During the container startup, once it is being initialized, the
    <literal>instantiator</literal> will, by default, register itself with the
    GemFire system and perform wiring on all instances of
    <classname>SomeDataSerializableClass</classname> created by GemFire during
    deserialization.</para>
  </section>

  <section id="serialization:instance-generator">
    <title>Auto-generating custom <classname>Instantiator</classname>s</title>

    <para>For data intensive applications, a large number of instances might
    be created on each machine as data flows in. Out of the box, GemFire uses
    reflection to create new types but for some scenarios, this might prove to
    be expensive. As always, it is good to perform profiling to quantify
    whether this is the case or not. For such cases, SGF allows the automatic
    generation of <classname>Instatiator</classname> classes which instantiate
    a new type (using the default constructor) without the use of
    reflection:</para>

    <programlisting language="xml">&lt;bean id="instantiator-factory" class="org.springframework.data.gemfire.serialization.InstantiatorFactoryBean"&gt;
  &lt;property name="customTypes"&gt;
    &lt;map&gt;
      &lt;entry key="org.pkg.CustomTypeA" value="1025"/&gt;
      &lt;entry key="org.pkg.CustomTypeB" value="1026"/&gt;
    &lt;/map&gt;
  &lt;/property&gt;
&lt;/bean&gt;</programlisting>

    <para>The definition above, automatically generated two
    <classname>Instantiator</classname>s for two classes, namely
    <classname>CustomTypeA</classname> and <classname>CustomTypeB</classname>
    and registers them with GemFire, under user id <literal>1025</literal> and
    <literal>1026</literal>. The two instantiators avoid the use of reflection
    and create the instances directly through Java code.</para>
  </section>
</chapter>