Spring/spring-data-gemfire
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

misc doc edits.

Browse Source
This commit is contained in:
markpollack
2010-07-27 10:34:16 -04:00
parent f209660e37
commit cdf4c57dcf
5 changed files with 608 additions and 431 deletions
Download Patch File Download Diff File Expand all files Collapse all files

135
docs/src/docbkx/reference/serialization.xml
View File

@@ -1,62 +1,89 @@
<?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">
"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 SGI simplifies and improves GemFire custom serialization in Java.
</para>
<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 SGI simplifies
and improves GemFire custom serialization in Java.</para>
<section id="serialization:wiring">
<title>Wiring deserialized instances</title>
<para>It is fairly common for objects serialized to have transient data, that is dependent on the node or environment where it lives at a certain point in time.
Serializing such information is useless (and potentially even dangerous) since it is local to a certain VM/machine. For such cases, SGI 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 (<link 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"><![CDATA[<bean id="instantiator" class="org.springframework.data.gemfire.serialization.WiringInstantiator">
<!-- DataSerializable type -->
<constructor-arg>org.pkg.SomeDataSerializableClass</constructor-arg>
<!-- type id -->
<constructor-arg>95</constructor-arg>
</bean>]]></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:wiring">
<title>Wiring deserialized instances</title>
<section id="serialization:instance-generator">
<title>Auto-generating custom <classname>Instantiator</classname>s</title>
<para>For data intensive applications, a big 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 (it's always good to perform profiling to quantify whether this is the case or not). For such cases, SGI 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"><![CDATA[<bean id="instantiator-factory" class="org.springframework.data.gemfire.serialization.InstantiatorFactoryBean">
<property name="customTypes">
<map>
<entry key="org.pkg.CustomTypeA" value="1025"/>
<entry key="org.pkg.CustomTypeB" value="1026"/>
</map>
</property>
</bean>]]></programlisting>
<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, SGI 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>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>
<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 (<link
linkend="apis:declarable"></link>) 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, SGI 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>