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

10
docs/src/docbkx/preface.xml
View File

@@ -4,10 +4,10 @@
<preface id="preface">
<title>Preface</title>
<para>
Spring GemFire Integration focuses on integrating Spring Framework powerful, non-invasive programming model
and concepts with GemFire Enterprise Fabric, providing easier configuration, use and high-level abstractions.
This document assumes the reader is already familiar with the Spring Framework and GemFire concepts
(at least at basic level) and APIs.
Spring GemFire Integration focuses on integrating Spring Framework's powerful, non-invasive programming model
and concepts with Gemstone's GemFire Enterprise Fabric, providing easier configuration, use and high-level abstractions.
This document assumes the reader is already has a basic familiarity with the Spring Framework and GemFire concepts
and APIs.
</para>
<para>
@@ -18,4 +18,4 @@
<ulink url="http://jira.springframework.org">issue</ulink>. Thank you.
</para>
</preface>
</preface>

299
docs/src/docbkx/reference/bootstrap.xml
View File

@@ -1,152 +1,189 @@
<?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="bootstrap">
<title>Bootstrapping GemFire through the Spring container</title>
<para>
One of the earlier tasks when using GemFire ad Spring framework is configuring the data grid through the IoC container. While this is
<ulink url="http://community.gemstone.com/display/gemfire/Integrating+GemFire+with+the+Spring+IoC+Container">possible</ulink>
out of the box, the configuration tends to be verbose and address only the basic cases. To address this problem, the Spring/GemFire project
provides several classes that allow configuration of distributed caches or regions in a variaty of scenarios with minimal effort.
</para>
<para>One of the first tasks when using GemFire and Spring is to configure
the data grid through the IoC container. While this is <ulink
url="http://community.gemstone.com/display/gemfire/Integrating+GemFire+with+the+Spring+IoC+Container">possible</ulink>
out of the box, the configuration tends to be verbose and only address basic
cases. To address this problem, the Spring GemFire project provides several
classes that enable the configuration of distributed caches or regions to
support a variety of scenarios with minimal effort.</para>
<section id="bootstrap:cache">
<title>Configuring the GemFire <interfacename>Cache</interfacename></title>
<para>In order to use the GemFire Fabric, one needs to either create a new <interfacename>Cache</interfacename> or connect to an existing one.
As in the current version of GemFire, there can be only one opened cache per VM (or classloader to be technically correct), in most cases the
cache is created once and then all other consumers connect to it.
</para>
<para>In its simplest form, a cache can be defined in one line:</para>
<programlisting language="xml"><![CDATA[<bean id="default-cache" class="org.springframework.data.gemfire.CacheFactoryBean"/>]]></programlisting>
<para>Here, the <emphasis>default-cache</emphasis>, using the defaults, will try to connect to an existing cache and, in case one does not exist,
create it.</para>
<para>Especially in environments with opened caches, this basic configuration can go a long way. For scenarios where the cache needs to be configured,
the user can pass in a GemFire configuration:</para>
<programlisting language="xml"><![CDATA[<bean id="cache-with-xml" class="org.springframework.data.gemfire.CacheFactoryBean">
<property name="cacheXml" value="classpath:cache.xml"/>
</bean>]]></programlisting>
<para>In this example, if the cache needs to be created, it will use the file named <literal>cache.xml</literal> located in the classpath root. Note that
the configuration makes use of Spring's
<ulink url="http://static.springsource.org/spring/docs/3.0.x/spring-framework-reference/html/resources.html"><interfacename>Resource</interfacename></ulink>
abstraction to locate the file. This allows various search patterns to be used, depending on the running environment or the prefix specified (if any) by the value.
Additionally to an external configuration, one can specify GemFire settings directly through Java <classname>Properties</classname>. This can be quite handy when
just a certain setting or default needs to be changed:
</para>
<section id="bootstrap:cache">
<title>Configuring the GemFire
<interfacename>Cache</interfacename></title>
<programlisting language="xml"><![CDATA[<bean id="cache-with-props" class="org.springframework.data.gemfire.CacheFactoryBean">
<property name="properties">
<props>
<prop key="bind-address">127.0.0.1</prop>
</props>
</property>
</bean>]]></programlisting>
<para>So far our examples relied on the primary Spring names (<literal>beans</literal>). However one is free to add other namespaces to simplify or enhance the configuration.
Let's do the same thing to the configuration above by using the <literal>util</literal> namespace and externalize the properties from the configuration (a best practice).</para>
<programlisting language="xml"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
<para>In order to use the GemFire Fabric, one needs to either create a new
<interfacename>Cache</interfacename> or connect to an existing one. As in
the current version of GemFire, there can be only one opened cache per VM
(or classloader to be technically correct). In most cases the cache is
created once and then all other consumers connect to it.</para>
<para>In its simplest form, a cache can be defined in one line:</para>
<programlisting language="xml">&lt;bean id="default-cache" class="org.springframework.data.gemfire.CacheFactoryBean"/&gt;</programlisting>
<para>Here, the <emphasis>default-cache</emphasis> will try to connect to
an existing cache and, in case one does not exist, create it. Since no
additional properties were specified the created cache uses the default
cache configuration.</para>
<para>Especially in environments with opened caches, this basic
configuration can go a long way. For scenarios where the cache needs to be
configured, the user can pass in a reference the GemFire configuration
file:</para>
<programlisting language="xml">&lt;bean id="cache-with-xml" class="org.springframework.data.gemfire.CacheFactoryBean"&gt;
&lt;property name="cacheXml" value="classpath:cache.xml"/&gt;
&lt;/bean&gt;</programlisting>
<para>In this example, if the cache needs to be created, it will use the
file named <literal>cache.xml</literal> located in the classpath root.
Only if the cache is created will the configuration file be used. <note>
<para>Note that the configuration makes use of Spring's <ulink
url="http://static.springsource.org/spring/docs/3.0.x/spring-framework-reference/html/resources.html"><interfacename>Resource</interfacename></ulink>
abstraction to locate the file. This allows various search patterns to
be used, depending on the running environment or the prefix specified
(if any) by the value.</para>
</note>In addition to referencing an external configuration file one can
specify GemFire settings directly through Java
<classname>Properties</classname>. This can be quite handy when just a few
settings need to be changed:</para>
<programlisting language="xml">&lt;bean id="cache-with-props" class="org.springframework.data.gemfire.CacheFactoryBean"&gt;
&lt;property name="properties"&gt;
&lt;props&gt;
&lt;prop key="bind-address"&gt;127.0.0.1&lt;/prop&gt;
&lt;/props&gt;
&lt;/property&gt;
&lt;/bean&gt;</programlisting>
<para>So far our examples relied on the primary Spring namespace
(<literal>beans</literal>). However one is free to add other namespaces to
simplify or enhance the configuration. Let's do the same thing to the
configuration above by using the <literal>util</literal> namespace and
externalize the properties from the configuration which is a best
practice.</para>
<programlisting language="xml">&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:util="http://www.springframework.org/schema/util"
xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
http://www.springframework.org/schema/util http://www.springframework.org/schema/util/spring-util.xsd">
http://www.springframework.org/schema/util http://www.springframework.org/schema/util/spring-util.xsd"&gt;
<bean id="cache-with-props" class="org.springframework.data.gemfire.CacheFactoryBean">
<property name="properties">
<util:properties location="classpath:/deployment/env.properties"/>
</property>
</bean>
</beans>]]></programlisting>
<para>It is worth pointing out again, that the cache settings apply only if the cache needs to be created, there is no opened cache in existence otherwise the existing cache
will be used (and the configuration will simply be discarded).</para>
</section>
<section id="bootstrap:region">
<title>Configuring a GemFire <interfacename>Region</interfacename></title>
<para>Once the <interfacename>Cache</interfacename> is configured, one needs to configure one or more <interfacename>Region</interfacename>s for interacting with the data
fabric. In a similar manner to the <classname>CacheFactoryBean</classname>, the <classname>RegionFactoryBean</classname> allows existing <interfacename>Region</interfacename>s
to retrieved or, in case they don't exist, created using various settings. One can specify the <interfacename>Region</interfacename> name, whether it will be destroyed on shutdown
(acting as a temporary cache), the associated <interfacename>CacheLoader</interfacename>s, <interfacename>CacheListener</interfacename>s and <interfacename>CacheWriter</interfacename>s
and if needed, the <interfacename>RegionAttributes</interfacename> for full customization.
</para>
<para>Let us start with a simple region declaration, named <emphasis>basic</emphasis> using a nested cache declaration:</para>
&lt;bean id="cache-with-props" class="org.springframework.data.gemfire.CacheFactoryBean"&gt;
&lt;property name="properties"&gt;
&lt;util:properties location="classpath:/deployment/env.properties"/&gt;
&lt;/property&gt;
&lt;/bean&gt;
&lt;/beans&gt;</programlisting>
<programlisting language="xml"><![CDATA[<bean id="basic" class="org.springframework.data.gemfire.RegionFactoryBean">
<property name="cache">
<bean class="org.springframework.data.gemfire.CacheFactoryBean"/>
</property>
<property name="name" value="basic"/>
</bean>]]></programlisting>
<para>It is worth pointing out again, that the cache settings apply only
if the cache needs to be created, there is no opened cache in existence
otherwise the existing cache will be used and the configuration will
simply be discarded.</para>
</section>
<para>Since the region bean definition name is usually the same with that of the cache, the <literal>name</literal> property can be omitted (the bean name will be used automatically).
Additionally by using the name the <literal><ulink url="http://static.springsource.org/spring/docs/2.5.x/reference/beans.html#beans-p-namespace">p</ulink></literal> namespace,
the configuration can be simplified even more:</para>
<section id="bootstrap:region">
<title>Configuring a GemFire <interfacename>Region</interfacename></title>
<programlisting language="xml"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
<para>Once the <interfacename>Cache</interfacename> is configured, one
needs to configure one or more <interfacename>Region</interfacename>s to
interact with the data fabric. In a similar manner to the
<classname>CacheFactoryBean</classname>, the
<classname>RegionFactoryBean</classname> allows existing
<interfacename>Region</interfacename>s to retrieved or, in case they don't
exist, created using various settings. One can specify the
<interfacename>Region</interfacename> name, whether it will be destroyed
on shutdown (thereby acting as a temporary cache), the associated
<interfacename>CacheLoader</interfacename>s,
<interfacename>CacheListener</interfacename>s and
<interfacename>CacheWriter</interfacename>s and if needed, the
<interfacename>RegionAttributes</interfacename> for full
customization.</para>
<para>Let us start with a simple region declaration, named
<emphasis>basic</emphasis> using a nested cache declaration:</para>
<programlisting language="xml">&lt;bean id="basic" class="org.springframework.data.gemfire.RegionFactoryBean"&gt;
&lt;property name="cache"&gt;
&lt;bean class="org.springframework.data.gemfire.CacheFactoryBean"/&gt;
&lt;/property&gt;
&lt;property name="name" value="basic"/&gt;
&lt;/bean&gt;</programlisting>
<para>Since the region bean definition name is usually the same with that
of the cache, the <literal>name</literal> property can be omitted (the
bean name will be used automatically). Additionally by using the name the
<literal><ulink
url="http://static.springsource.org/spring/docs/2.5.x/reference/beans.html#beans-p-namespace">p</ulink></literal>
namespace, the configuration can be simplified even more:</para>
<programlisting language="xml">&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:p="http://www.springframework.org/schema/p"
xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd">
xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd"&gt;
<!-- shared cache across regions -->
<bean id="cache" class="org.springframework.data.gemfire.CacheFactoryBean"/>
&lt;!-- shared cache across regions --&gt;
&lt;bean id="cache" class="org.springframework.data.gemfire.CacheFactoryBean"/&gt;
<!-- region named 'basic' -->
<bean id="basic" class="org.springframework.data.gemfire.RegionFactoryBean" p:cache-ref="cache"/>
&lt;!-- region named 'basic' --&gt;
&lt;bean id="basic" class="org.springframework.data.gemfire.RegionFactoryBean" p:cache-ref="cache"/&gt;
<!-- region with a name different then the bean definition -->
<bean id="root-region" class="org.springframework.data.gemfire.RegionFactoryBean" p:cache-ref="cache" p:name="default-region"/>
</beans>]]></programlisting>
<para>It is worth pointing out, that for the vast majority of cases configuring the cache loader, listener and writer through the Spring container is preferred since the same instances
can be reused across multiple regions and additionally, the instances themselves can benefit from the container rich feature set:</para>
<programlisting language="xml"><![CDATA[<bean id="cacheLogger" class="org.some.pkg.CacheLogger"/>
<bean id="customized-region" class="org.springframework.data.gemfire.RegionFactoryBean" p:cache-ref="cache">
<property name="cacheListeners">
<array>
<ref name="cacheLogger"/>
<bean class="org.some.other.pkg.SysoutLogger"/>
</array>
</property>
<property name="cacheLoader"><bean class="org.some.pkg.CacheLoad"/></property>
<property name="cacheWriter"><bean class="org.some.pkg.CacheWrite"/></property>
</bean>
<bean id="local-region" class="org.springframework.data.gemfire.RegionFactoryBean" p:cache-ref="cache">
<property name="cacheListeners" ref="cacheLogger"/>
</bean>]]></programlisting>
&lt;!-- region with a name different then the bean definition --&gt;
&lt;bean id="root-region" class="org.springframework.data.gemfire.RegionFactoryBean" p:cache-ref="cache" p:name="default-region"/&gt;
&lt;/beans&gt;</programlisting>
<section id="bootstrap:region:client">
<title>Configuring a <emphasis>client</emphasis> <interfacename>Region</interfacename> </title>
<para>For scenarios where a <emphasis>CacheServer</emphasis> is used and <emphasis>clients</emphasis> need to be configured, SGI offers a dedicated configuration class named:
<classname>ClientRegionFactoryBean</classname>. This allows client <emphasis>interests</emphasis> to be registered in both key and regex form through <classname>Interest</classname>
and <classname>RegexInterest</classname> classes in the <literal>org.springframework.data.gemfire</literal> package:</para>
<programlisting language="xml"><![CDATA[<bean id="interested-client" class="org.springframework.data.gemfire.ClientRegionFactoryBean" p:cache-ref="cache" p:name="client-region">
<property name="interests">
<array>
<!-- key-based interest -->
<bean class="org.springframework.data.gemfire.Interest" p:key="Vlaicu" p:policy="NONE"/>
<!-- regex-based interest -->
<bean class="org.springframework.data.gemfire.RegexInterest" p:key=".*" p:policy="KEYS" p:durable="true"/>
</array>
</property>
</bean>]]></programlisting>
</section>
</section>
<para>It is worth pointing out, that for the vast majority of cases
configuring the cache loader, listener and writer through the Spring
container is preferred since the same instances can be reused across
multiple regions and additionally, the instances themselves can benefit
from the container's rich feature set:</para>
<programlisting language="xml">&lt;bean id="cacheLogger" class="org.some.pkg.CacheLogger"/&gt;
&lt;bean id="customized-region" class="org.springframework.data.gemfire.RegionFactoryBean" p:cache-ref="cache"&gt;
&lt;property name="cacheListeners"&gt;
&lt;array&gt;
&lt;ref name="cacheLogger"/&gt;
&lt;bean class="org.some.other.pkg.SysoutLogger"/&gt;
&lt;/array&gt;
&lt;/property&gt;
&lt;property name="cacheLoader"&gt;&lt;bean class="org.some.pkg.CacheLoad"/&gt;&lt;/property&gt;
&lt;property name="cacheWriter"&gt;&lt;bean class="org.some.pkg.CacheWrite"/&gt;&lt;/property&gt;
&lt;/bean&gt;
</chapter>
&lt;bean id="local-region" class="org.springframework.data.gemfire.RegionFactoryBean" p:cache-ref="cache"&gt;
&lt;property name="cacheListeners" ref="cacheLogger"/&gt;
&lt;/bean&gt;</programlisting>
<section id="bootstrap:region:client">
<title>Configuring a <emphasis>client</emphasis>
<interfacename>Region</interfacename></title>
<para>For scenarios where a <emphasis>CacheServer</emphasis> is used and
<emphasis>clients</emphasis> need to be configured, SGI offers a
dedicated configuration class named:
<classname>ClientRegionFactoryBean</classname>. This allows client
<emphasis>interests</emphasis> to be registered in both key and regex
form through <classname>Interest</classname> and
<classname>RegexInterest</classname> classes in the
<literal>org.springframework.data.gemfire</literal> package:</para>
<programlisting language="xml">&lt;bean id="interested-client" class="org.springframework.data.gemfire.ClientRegionFactoryBean" p:cache-ref="cache" p:name="client-region"&gt;
&lt;property name="interests"&gt;
&lt;array&gt;
&lt;!-- key-based interest --&gt;
&lt;bean class="org.springframework.data.gemfire.Interest" p:key="Vlaicu" p:policy="NONE"/&gt;
&lt;!-- regex-based interest --&gt;
&lt;bean class="org.springframework.data.gemfire.RegexInterest" p:key=".*" p:policy="KEYS" p:durable="true"/&gt;
&lt;/array&gt;
&lt;/property&gt;
&lt;/bean&gt;</programlisting>
</section>
</section>
</chapter>

426
docs/src/docbkx/reference/data.xml
View File

@@ -1,119 +1,190 @@
<?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="apis">
<title>Working with the GemFire APIs</title>
<para>
Once the GemFire cache and regions have been configured, these can injected and used inside application objects. This chapter describes the integration with the
Spring transaction management, <classname>DaoException</classname> hierarchy and wiring of GemFire managed objects.
</para>
<para>Once the GemFire cache and regions have been configured they can
injected and used inside application objects. This chapter describes the
integration with Spring's transaction management functionality and
<classname>DaoException</classname> hierarchy. It also covers support for
dependency injection of GemFire managed objects.</para>
<section id="apis:exception-translation">
<title>Exception translation</title>
<section id="apis:exception-translation">
<title>Exception translation</title>
<para>Using a new API requires not just accommodating to the new semantics but also handling its particular exception set. To accommodate this case, Spring Framework provides a
generic, consistent exception <ulink url="http://static.springsource.org/spring/docs/3.0.x/spring-framework-reference/html/dao.html#dao-exceptions">hierarchy</ulink> that
abstracts one from proprietary (and usually checked) exceptions to a set of focused runtime exceptions. As mentioned in the Spring Framework documentation, by using annotations
(<literal>@Repository</literal>) or AOP, exception translations happens automatically without any code changes. The same holds true for GemFire as long as at least a
<classname>CacheFactoryBean</classname> is declared. The <interfacename>Cache</interfacename> factory acts as an exception translator which is automatically detected by the
Spring infrastructure and used accordingly.
</para>
</section>
<para>Using a new data access technology requires not just accommodating
to a new API but also handling exceptions specific to that technology. To
accommodate this case, Spring Framework provides a technology agnostic,
consistent exception <ulink
url="http://static.springsource.org/spring/docs/3.0.x/spring-framework-reference/html/dao.html#dao-exceptions">hierarchy</ulink>
that abstracts one from proprietary (and usually checked) exceptions to a
set of focused runtime exceptions. As mentioned in the Spring Framework
documentation, <ulink
url="http://static.springsource.org/spring/docs/3.0.x/spring-framework-reference/html/orm.html#orm-exception-translation">exception
translation</ulink> can be applied transparently to your data access
objects through the use of the <literal>@Repository</literal> annotation
and AOP by defining a PersistenceExceptionTranslationPostProcessor bean.
The same exception translation functionality is enabled when using Gemfire
as long as at least a <classname>CacheFactoryBean</classname> is declared.
The <interfacename>Cache</interfacename> factory acts as an exception
translator which is automatically detected by the Spring infrastructure
and used accordingly.</para>
</section>
<section id="apis:template">
<title><classname>GemfireTemplate</classname></title>
<para>As with many other high-level abstractions provided by the Spring Framework and related projects, Spring GemFire provides a <emphasis>template</emphasis> that plays a central role
when working with the GemFire API. The class provides several <emphasis>one-liner</emphasis> methods, for popular operations but also the ability to <emphasis>execute</emphasis> code
against the native GemFire API without having to deal with exceptions for example through the <interfacename>GemfireCallback</interfacename>.</para>
<para>The template class requires a GemFire <interfacename>Region</interfacename> instance and once configured is thread-safe and should be reused across multiple classes:</para>
<section id="apis:template">
<title><classname>GemfireTemplate</classname></title>
<programlisting language="xml"><![CDATA[<bean id="gemfireTemplate" class="org.springframework.data.gemfire.GemfireTemplate" p:region-ref="someRegion"/>]]></programlisting>
<para>Once the template is configured, one can use it alongside <interfacename>GemfireCallback</interfacename> to work directly with the GemFire <interfacename>Region</interfacename>,
without having to deal with exceptions, threading or resource management:
</para>
<programlisting language="java"><![CDATA[template.execute(new GemfireCallback<Iterable<String>>() {
public Iterable<String> doInGemfire(Region reg) throws GemFireCheckedException, GemFireException {
<para>As with many other high-level abstractions provided by the Spring
Framework and related projects, Spring GemFire provides a
<emphasis>template</emphasis> that plays a central role when working with
the GemFire API. The class provides several <emphasis>one-liner</emphasis>
methods, for popular operations but also the ability to
<emphasis>execute</emphasis> code against the native GemFire API without
having to deal with exceptions for example through the
<interfacename>GemfireCallback</interfacename>.</para>
<para>The template class requires a GemFire
<interfacename>Region</interfacename> instance and once configured is
thread-safe and should be reused across multiple classes:</para>
<programlisting language="xml">&lt;bean id="gemfireTemplate" class="org.springframework.data.gemfire.GemfireTemplate" p:region-ref="someRegion"/&gt;</programlisting>
<para>Once the template is configured, one can use it alongside
<interfacename>GemfireCallback</interfacename> to work directly with the
GemFire <interfacename>Region</interfacename>, without having to deal with
checked exceptions, threading or resource management concerns:</para>
<programlisting language="java">template.execute(new GemfireCallback&lt;Iterable&lt;String&gt;&gt;() {
public Iterable&lt;String&gt; doInGemfire(Region reg) throws GemFireCheckedException, GemFireException {
// working against a Region of String
Region<String, String> region = reg;
Region&lt;String, String&gt; region = reg;
region.put("1", "one");
region.put("3", "three");
// should return 1
return region.query("length < 5).size();
return region.query("length &lt; 5).size();
}
});]]></programlisting>
});</programlisting>
</section>
</section>
<section id="apis:tx-mgmt">
<title>Transaction Management</title>
<section id="apis:tx-mgmt">
<title>Transaction Management</title>
<para>One of the most popular features of Spring Framework is <ulink url="http://static.springsource.org/spring/docs/3.0.x/spring-framework-reference/html/transaction.html">transaction</ulink>
management. If you are not familiar with it, we strongly recommend
<ulink url="http://static.springsource.org/spring/docs/3.0.x/spring-framework-reference/html/transaction.html#transaction-motivation">looking</ulink> into it as it offers a consistent programming
model that works transparently across multiple API that can be configured either programmatically or declaratively (the most popular choice).</para>
<para>For Gemfire, SGI provides a dedicated, per-cache, transaction manager that once declared, allows actions on the <interfacename>Region</interfacename>s to be grouped and executed atomically through
Spring:</para>
<programlisting language="xml"><![CDATA[<bean id="transaction-manager" class="org.springframework.data.gemfire.GemfireTransactionManager" p:cache-ref="cache"/>]]></programlisting>
<para>Note that currently GemFire supports optimistic transactions with <emphasis>read committed</emphasis> isolation. Further more to guarantee this isolation, developers should
avoid making <emphasis>in-place</emphasis> changes, that is manually modifying the values present in the cache. To prevent this from happening, the transaction manager configured the cache
to use <emphasis>copy on read</emphasis> semantics, meaning a clone of the actual value is created, each time a read is performed. This behaviour can be disabled if needed through the
<literal>copyOnRead</literal> property. For more information on the semantics of the underlying GemFire transaction manager, see the GemFire
<ulink url="http://www.gemstone.com/docs/6.0.1/product/docs/japi/com/gemstone/gemfire/cache/CacheTransactionManager.html">documentation</ulink>.</para>
</section>
<section id="apis:declarable">
<title>Wiring <interfacename>Declarable</interfacename> components</title>
<sidebar>
<title>Eliminate <interfacename>Declarable</interfacename> components</title>
<para>One can configure custom types entirely inside through Spring as mentioned in <xref linkend="bootstrap:region"/>. That way, one does not have to implement the
<interfacename>Declarable</interfacename> interface and gets access to all the features of the Spring IoC container (including not just dependency injection but also
life-cycle and instance management).</para>
</sidebar>
<para>One of the most popular features of Spring Framework is <ulink
url="http://static.springsource.org/spring/docs/3.0.x/spring-framework-reference/html/transaction.html">transaction</ulink>
management. If you are not familiar with it, we strongly recommend <ulink
url="http://static.springsource.org/spring/docs/3.0.x/spring-framework-reference/html/transaction.html#transaction-motivation">looking</ulink>
into it as it offers a consistent programming model that works
transparently across multiple APIs that can be configured either
programmatically or declaratively (the most popular choice).</para>
<para>GemFire XML configuration (usually named <literal>cache.xml</literal> allows <emphasis>user</emphasis> objects to be declared as part of the fabric config. Usually these objects
are <interfacename>CacheLoader</interfacename>s or other pluggable components into GemFire. Out of the box, each such type declared through XML must implement the <interfacename>Declarable</interfacename>
interface which allows arbitrary parameters to be passed to the declared class through a <classname>Properties</classname> instance.</para>
<para>Consider the following declaration (taken from the <interfacename>Declarable</interfacename> javadoc):</para>
<programlisting language="xml"><![CDATA[<cache-loader>
<class-name>com.company.app.DBLoader</class-name>
<parameter name="URL">
<string>jdbc://12.34.56.78/mydb</string>
</parameter>
</cache-loader>]]></programlisting>
<para>For Gemfire, SGI provides a dedicated, per-cache, transaction
manager that once declared, allows actions on the
<interfacename>Region</interfacename>s to be grouped and executed
atomically through Spring:</para>
<para>To simplify the task of parsing, converting the parameters and initializing the object, SGI offers a base class (<classname>WiringDeclarableSupport</classname>) that allows GemFire
user objects to be wired through a <emphasis>template</emphasis> bean definition or, in case that is missing perform autowiring through the Spring container. To take advantage of this feature,
the user objects need to extends <classname>WiringDeclarableSupport</classname> which automatically locates the declaring <interfacename>BeanFactory</interfacename> and performs wiring as
part of the initialization process.
</para>
<sidebar>
<title>Why is a base class needed?</title>
<para>Unfortunately, in the current GemFire release there is no concept of an <emphasis>object factory</emphasis> and the types declared are instantiated and used as is - that is
there are no other ways in which third parties can take care of the object creation outside GemFire. This feature is planned for the up-coming GemFire release (6.5)</para>
</sidebar>
<section id="apis:declarable:template-wiring">
<title>Using <emphasis>template</emphasis> definitions</title>
<para>When used <classname>WiringDeclarableSupport</classname> tries to first locate an existing bean definition and use that as wiring template. Unless specified, the component
class name will be used as an implicit bean definition name.
Let's see how our <classname>DBLoader</classname> declaration would look in that case:</para>
<programlisting language="java" ><![CDATA[public class DBLoader extends WiringDeclarableSupport implements CacheLoader {
<programlisting language="xml">&lt;bean id="transaction-manager" class="org.springframework.data.gemfire.GemfireTransactionManager" p:cache-ref="cache"/&gt;</programlisting>
<para>Note that currently GemFire supports optimistic transactions with
<emphasis>read committed</emphasis> isolation. Furthermore, to guarantee
this isolation, developers should avoid making
<emphasis>in-place</emphasis> changes, that is manually modifying the
values present in the cache. To prevent this from happening, the
transaction manager configured the cache to use <emphasis>copy on
read</emphasis> semantics, meaning a clone of the actual value is created,
each time a read is performed. This behaviour can be disabled if needed
through the <literal>copyOnRead</literal> property. For more information
on the semantics of the underlying GemFire transaction manager, see the
GemFire <ulink
url="http://www.gemstone.com/docs/6.0.1/product/docs/japi/com/gemstone/gemfire/cache/CacheTransactionManager.html">documentation</ulink>.</para>
</section>
<section id="apis:declarable">
<title>Wiring <interfacename>Declarable</interfacename> components</title>
<para>GemFire XML configuration (usually named
<literal>cache.xml</literal> allows <emphasis>user</emphasis> objects to
be declared as part of the fabric configuration. Usually these objects are
<interfacename>CacheLoader</interfacename>s or other pluggable components
into GemFire. Out of the box in GemFire, each such type declared through
XML must implement the <interfacename>Declarable</interfacename> interface
which allows arbitrary parameters to be passed to the declared class
through a <classname>Properties</classname> instance.</para>
<para>In this section we describe how you can configure the pluggable
components defined in <literal>cache.xml</literal> using Spring while
keeping your Cache/Region configuration defined in
<literal>cache.xml</literal> This allows your pluggable components to
focus on the application logic and not the location or creation of
DataSources or other collaboration object.</para>
<para>However, if you are starting on a green-field project, it is
recommended that you configure Cache, Region, and other pluggable
components directly in Spring. This avoids inheriting from the
<interfacename>Declarable</interfacename> interface or the base class
presented in this section. See the following sidebar for more information
on this approach.</para>
<sidebar>
<title>Eliminate <interfacename>Declarable</interfacename>
components</title>
<para>One can configure custom types entirely inside through Spring as
mentioned in <xref linkend="bootstrap:region" />. That way, one does not
have to implement the <interfacename>Declarable</interfacename>
interface and gets access to all the features of the Spring IoC
container (including not just dependency injection but also life-cycle
and instance management).</para>
</sidebar>
<para>As an example of configuring a
<interfacename>Declarable</interfacename> component using Spring, consider
the following declaration (taken from the
<interfacename>Declarable</interfacename> javadoc):</para>
<programlisting language="xml">&lt;cache-loader&gt;
&lt;class-name&gt;com.company.app.DBLoader&lt;/class-name&gt;
&lt;parameter name="URL"&gt;
&lt;string&gt;jdbc://12.34.56.78/mydb&lt;/string&gt;
&lt;/parameter&gt;
&lt;/cache-loader&gt;</programlisting>
<para>To simplify the task of parsing, converting the parameters and
initializing the object, SGI offers a base class
(<classname>WiringDeclarableSupport</classname>) that allows GemFire user
objects to be wired through a <emphasis>template</emphasis> bean
definition or, in case that is missing perform autowiring through the
Spring container. To take advantage of this feature, the user objects need
to extend <classname>WiringDeclarableSupport</classname> which
automatically locates the declaring
<interfacename>BeanFactory</interfacename> and performs wiring as part of
the initialization process.</para>
<sidebar>
<title>Why is a base class needed?</title>
<para>In the current GemFire release there is no concept of an
<emphasis>object factory</emphasis> and the types declared are
instantiated and used as is - that is there are no other ways in which
third parties can take care of the object creation outside GemFire.
Support for this feature is planned for the up-coming GemFire release
(6.5)</para>
</sidebar>
<section id="apis:declarable:template-wiring">
<title>Configuration using <emphasis>template</emphasis>
definitions</title>
<para>When used <classname>WiringDeclarableSupport</classname> tries to
first locate an existing bean definition and use that as wiring
template. Unless specified, the component class name will be used as an
implicit bean definition name. Let's see how our
<classname>DBLoader</classname> declaration would look in that
case:</para>
<programlisting language="java">public class DBLoader extends WiringDeclarableSupport implements CacheLoader {
private DataSource dataSource;
public void setDataSource(DataSource ds){
@@ -121,103 +192,120 @@
}
public Object load(LoaderHelper helper) { ... }
}]]></programlisting>
<programlisting language="xml"><![CDATA[<cache-loader>
<class-name>com.company.app.DBLoader</class-name>
<!-- no parameter is passed (use the bean implicit name
that is the class name) -->
</cache-loader>]]></programlisting>
<programlisting language="xml"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
}</programlisting>
<programlisting language="xml">&lt;cache-loader&gt;
&lt;class-name&gt;com.company.app.DBLoader&lt;/class-name&gt;
&lt;!-- no parameter is passed (use the bean implicit name
that is the class name) --&gt;
&lt;/cache-loader&gt;</programlisting>
<programlisting language="xml">&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:p="http://www.springframework.org/schema/p"
xsi:schemaLocation="http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans.xsd">
http://www.springframework.org/schema/beans/spring-beans.xsd"&gt;
<bean id="dataSource" ... />
&lt;bean id="dataSource" ... /&gt;
<!-- template bean definition -->
<bean id="com.company.app.DBLoader" abstract="true" p:dataSource-ref="dataSource"/>
</beans>]]></programlisting>
<para>In the scenario above, as no parameter was specified, a bean with id/name <literal>com.company.app.DBLoader</literal> was searched for. The found bean definition is used
as a template for wiring the instance created by GemFire. For cases where the bean name uses a different convention, one can pass in the <literal>bean-name</literal> parameter
in the GemFire configuration:</para>
<programlisting language="xml"><![CDATA[<cache-loader>
<class-name>com.company.app.DBLoader</class-name>
<!-- pass the bean definition template name
as parameter -->
<parameter name="bean-name">
<string>template-bean</string>
</parameter>
</cache-loader>]]></programlisting>
<programlisting language="xml"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
&lt;!-- template bean definition --&gt;
&lt;bean id="com.company.app.DBLoader" abstract="true" p:dataSource-ref="dataSource"/&gt;
&lt;/beans&gt;</programlisting>
<para>In the scenario above, as no parameter was specified, a bean with
id/name <literal>com.company.app.DBLoader</literal> was searched for.
The found bean definition is used as a template for wiring the instance
created by GemFire. For cases where the bean name uses a different
convention, one can pass in the <literal>bean-name</literal> parameter
in the GemFire configuration:</para>
<programlisting language="xml">&lt;cache-loader&gt;
&lt;class-name&gt;com.company.app.DBLoader&lt;/class-name&gt;
&lt;!-- pass the bean definition template name
as parameter --&gt;
&lt;parameter name="bean-name"&gt;
&lt;string&gt;template-bean&lt;/string&gt;
&lt;/parameter&gt;
&lt;/cache-loader&gt;</programlisting>
<programlisting language="xml">&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:p="http://www.springframework.org/schema/p"
xsi:schemaLocation="http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans.xsd">
http://www.springframework.org/schema/beans/spring-beans.xsd"&gt;
<bean id="dataSource" ... />
&lt;bean id="dataSource" ... /&gt;
<!-- template bean definition -->
<bean id="template-bean" abstract="true" p:dataSource-ref="dataSource"/>
&lt;!-- template bean definition --&gt;
&lt;bean id="template-bean" abstract="true" p:dataSource-ref="dataSource"/&gt;
</beans>]]></programlisting>
&lt;/beans&gt;</programlisting>
<note><para>The <emphasis>template</emphasis> bean definitions do not have to be declared in XML - any format is allowed (Groovy, annotations, etc..).</para></note>
<note>
<para>The <emphasis>template</emphasis> bean definitions do not have
to be declared in XML - any format is allowed (Groovy, annotations,
etc..).</para>
</note>
</section>
</section>
<section id="apis:declarable:autowiring">
<title>Configuration using auto-wiring and annotations</title>
<section id="apis:declarable:autowiring">
<title>Using Auto/Annotation-wiring</title>
<para>If no bean definition is found, by default, <classname>WiringDeclarableSupport</classname> will
<ulink url="http://static.springsource.org/spring/docs/3.0.x/spring-framework-reference/html/beans.html#beans-factory-autowire">autowire</ulink>
the declaring instance. In short, this means that unless any <emphasis>metadata</emphasis> is offered by the instance, the container will find the object setters and try to automatically
satisfy these dependencies. However, one can also use JDK 5 annotations to provide additional information to the auto-wiring process. We strongly recommend reading the dedicated
<ulink url="http://static.springsource.org/spring/docs/3.0.x/spring-framework-reference/html/beans.html#beans-annotation-config">chapter</ulink> in the Spring documentation for more information
on the supported annotations and enabling factors.
</para>
<para>For example, the hypothetical <literal>DBLoader</literal> declaration above can be injected with a Spring-configured <interface>DataSource</interface> in the following way:</para>
<programlisting language="java" ><![CDATA[public class DBLoader extends WiringDeclarableSupport implements CacheLoader {
<para>If no bean definition is found, by default,
<classname>WiringDeclarableSupport</classname> will <ulink
url="http://static.springsource.org/spring/docs/3.0.x/spring-framework-reference/html/beans.html#beans-factory-autowire">autowire</ulink>
the declaring instance. This means that unless any dependency injection
<emphasis>metadata</emphasis> is offered by the instance, the container
will find the object setters and try to automatically satisfy these
dependencies. However, one can also use JDK 5 annotations to provide
additional information to the auto-wiring process. We strongly recommend
reading the dedicated <ulink
url="http://static.springsource.org/spring/docs/3.0.x/spring-framework-reference/html/beans.html#beans-annotation-config">chapter</ulink>
in the Spring documentation for more information on the supported
annotations and enabling factors.</para>
<para>For example, the hypothetical <literal>DBLoader</literal>
declaration above can be injected with a Spring-configured
<interface>DataSource</interface> in the following way:</para>
<programlisting language="java">public class DBLoader extends WiringDeclarableSupport implements CacheLoader {
// use annotations to 'mark' the needed dependencies
@javax.inject.Inject
private DataSource dataSource;
public Object load(LoaderHelper helper) { ... }
}]]></programlisting>
}</programlisting>
<programlisting language="xml"><![CDATA[<cache-loader>
<class-name>com.company.app.DBLoader</class-name>
<!-- no need to declare any parameters anymore
since the class is auto-wired -->
</cache-loader>]]></programlisting>
<programlisting language="xml"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
<programlisting language="xml">&lt;cache-loader&gt;
&lt;class-name&gt;com.company.app.DBLoader&lt;/class-name&gt;
&lt;!-- no need to declare any parameters anymore
since the class is auto-wired --&gt;
&lt;/cache-loader&gt;</programlisting>
<programlisting language="xml">&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:context="http://www.springframework.org/schema/context"
xsi:schemaLocation="http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans.xsd
http://www.springframework.org/schema/context
http://www.springframework.org/schema/context/spring-context.xsd">
http://www.springframework.org/schema/context/spring-context.xsd"&gt;
<!-- enable annotation processing -->
<context:annotation-config/>
&lt;!-- enable annotation processing --&gt;
&lt;context:annotation-config/&gt;
</beans>]]></programlisting>
<para>By using the JSR-330 annotations, the cache loader code has been simplified since the location and creation of the DataSource has been externalized and the user code is concerned
only with the loading process. The <interfacename>DataSource</interfacename> might be transactional, created lazily, shared between multiple objects or retrieved from JNDI - these aspects
can be easily configured and changed through the Spring container without touching the <classname>DBLoader</classname> code.</para>
</section>
</section>
</chapter>
&lt;/beans&gt;</programlisting>
<para>By using the JSR-330 annotations, the cache loader code has been
simplified since the location and creation of the DataSource has been
externalized and the user code is concerned only with the loading
process. The <interfacename>DataSource</interfacename> might be
transactional, created lazily, shared between multiple objects or
retrieved from JNDI - these aspects can be easily configured and changed
through the Spring container without touching the
<classname>DBLoader</classname> code.</para>
</section>
</section>
</chapter>

169
docs/src/docbkx/reference/samples.xml
View File

@@ -1,101 +1,126 @@
<?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="samples">
<title>Sample Applications</title>
<para>
The Spring GemFire project includes one sample application. Named "Hello World", the sample demonstrates how to configure and use GemFire inside a
Spring application. At runtime, the sample offers a <emphasis>shell</emphasis> to the user allowing him to run various commands against the grid.
It provides an excellent starting point for users unfamiliar with the essential components or the Spring and GemFire concepts.
</para>
<para>THe samples are available with the distribution and are both Maven-based. One can easily import them into any Maven-aware IDE (such as SpringSource
<ulink url="http://www.springsource.com/products/sts">Tool Suite</ulink>) or run them from the command-line.</para>
<para>The Spring GemFire project includes one sample application. Named
"Hello World", the sample demonstrates how to configure and use GemFire
inside a Spring application. At runtime, the sample offers a
<emphasis>shell</emphasis> to the user allowing him to run various commands
against the grid. It provides an excellent starting point for users
unfamiliar with the essential components or the Spring and GemFire
concepts.</para>
<section id="samples:hello-world">
<title>Hello World</title>
<para>The Hello World sample demonstrates the core functionality of the Spring GemFire project. It bootstraps GemFire, configures it, executes arbitrary
commands against it and shuts it down with the application. Multiple instances can be started at the same time - they will seemingly work with each other
sharing data without any user intervention.
</para>
<section id="samples:hello-world:start-stop">
<title>Starting and stopping the sample</title>
<para>Hello World is designed as a stand-alone java application. It features a <classname>Main</classname> class which can be started either from your
IDE of choice (in Eclipse/STS through <literal>Run As/Java Application</literal>) or from the command line through Maven using <literal>mvn exec:java</literal>.
One can also use <literal>java</literal> directly on the resulting artifact if the classpath is properly set.
</para>
<para>To stop the sample, simply type <literal>exit</literal> at the command line or press <literal>Ctrl+C</literal> to stop the VM and shutdown the Spring container.</para>
</section>
<para>The sample is bundled with the distribution and is Maven-based. One
can easily import them into any Maven-aware IDE (such as SpringSource <ulink
url="http://www.springsource.com/products/sts">Tool Suite</ulink>) or run
them from the command-line.</para>
<section id="samples:hello-world:run">
<title>Using the sample</title>
<para>Once started, the sample will create a shared data grid and allow the user to issue commands against it. The output will likely look as follows:</para>
<programlisting><![CDATA[INFO: Created GemFire Cache [Spring GemFire World] v. X.Y.Z
<section id="samples:hello-world">
<title>Hello World</title>
<para>The Hello World sample demonstrates the core functionality of the
Spring GemFire project. It bootstraps GemFire, configures it, executes
arbitrary commands against it and shuts it down when the application
exits. Multiple instances can be started at the same time as they will
work with each other sharing data without any user intervention.</para>
<section id="samples:hello-world:start-stop">
<title>Starting and stopping the sample</title>
<para>Hello World is designed as a stand-alone java application. It
features a <classname>Main</classname> class which can be started either
from your IDE of choice (in Eclipse/STS through <literal>Run As/Java
Application</literal>) or from the command line through Maven using
<literal>mvn exec:java</literal>. One can also use
<literal>java</literal> directly on the resulting artifact if the
classpath is properly set.</para>
<para>To stop the sample, simply type <literal>exit</literal> at the
command line or press <literal>Ctrl+C</literal> to stop the VM and
shutdown the Spring container.</para>
</section>
<section id="samples:hello-world:run">
<title>Using the sample</title>
<para>Once started, the sample will create a shared data grid and allow
the user to issue commands against it. The output will likely look as
follows:</para>
<programlisting>INFO: Created GemFire Cache [Spring GemFire World] v. X.Y.Z
INFO: Created new cache region [myWorld]
INFO: Member xxxxxx:50694/51611 connecting to region [myWorld]
Hello World!
Want to interact with the world ? ...
Supported commands are:
get <key> - retrieves an entry (by key) from the grid
put <key> <value> - puts a new entry into the grid
remove <key> - removes an entry (by key) from the grid
...]]></programlisting>
<para>For example to add new items to the grid one can use:</para>
<programlisting>-> <emphasis role="bold">put 1 unu</emphasis>
get &lt;key&gt; - retrieves an entry (by key) from the grid
put &lt;key&gt; &lt;value&gt; - puts a new entry into the grid
remove &lt;key&gt; - removes an entry (by key) from the grid
...</programlisting>
<para>For example to add new items to the grid one can use:</para>
<programlisting>-&gt; <emphasis role="bold">put 1 unu</emphasis>
INFO: Added [1=unu] to the cache
null
-> <emphasis role="bold">put 1 one</emphasis>
-&gt; <emphasis role="bold">put 1 one</emphasis>
INFO: Updated [1] from [unu] to [one]
unu
-> <emphasis role="bold">size</emphasis>
-&gt; <emphasis role="bold">size</emphasis>
1
-> <emphasis role="bold">put 2 two</emphasis>
-&gt; <emphasis role="bold">put 2 two</emphasis>
INFO: Added [2=two] to the cache
null
-> <emphasis role="bold">size</emphasis>
-&gt; <emphasis role="bold">size</emphasis>
2</programlisting>
<para>Multiple instances can be created at the same time. Once started, the new VMs automatically see the existing region and its information:</para>
<programlisting>INFO: Connected to Distributed System ['Spring GemFire World'=xxxx:56218/49320@yyyyy]
<para>Multiple instances can be created at the same time. Once started,
the new VMs automatically see the existing region and its
information:</para>
<programlisting>INFO: Connected to Distributed System ['Spring GemFire World'=xxxx:56218/49320@yyyyy]
Hello World!
...
-> <emphasis role="bold">size</emphasis>
-&gt; <emphasis role="bold">size</emphasis>
2
-> <emphasis role="bold">map</emphasis>
-&gt; <emphasis role="bold">map</emphasis>
[2=two] [1=one]
-> <emphasis role="bold">query length = 3</emphasis>
-&gt; <emphasis role="bold">query length = 3</emphasis>
[one, two]
</programlisting>
<para>Experiment with the example, start (and stop) as many instances as you want, run various commands in one instance and see how the others react.
To preserve data, at least one instance needs to be alive all times - if all instances are shutdown, the grid data is completely destroyed (in this example
- to preserve data between runs, see the GemFire documentations).</para>
</section>
<section id="samples:hello-world:explained">
<title>Hello World Sample Explained</title>
<para>Hello World uses both Spring XML and annotations for its configuration. The initial boostrapping configuration is <literal>app-context.xml</literal> which
includes the cache configuration, defined under <literal>cache-context.xml</literal> file and performs classpath
<ulink url="http://static.springsource.org/spring/docs/3.0.x/spring-framework-reference/html/beans.html#beans-classpath-scanning">scanning</ulink> for Spring
<ulink url="http://static.springsource.org/spring/docs/3.0.x/spring-framework-reference/html/beans.html#beans-factorybeans-annotations">components</ulink>.
The cache configuration defines the GemFire cache, region and for illustrative purposes a simple cache listener that acts as a logger.
</para>
<para>The main <emphasis>beans</emphasis> are <literal>HelloWorld</literal> and <literal>CommandProcessor</literal> which rely on the <classname>GemfireTemplate</classname>
to interact with the distributed fabric. Both classes use annotations to define their dependency and life-cycle callbacks.
</para>
</section>
</section>
</chapter>
<para>Experiment with the example, start (and stop) as many instances as
you want, run various commands in one instance and see how the others
react. To preserve data, at least one instance needs to be alive all
times - if all instances are shutdown, the grid data is completely
destroyed (in this example - to preserve data between runs, see the
GemFire documentations).</para>
</section>
<section id="samples:hello-world:explained">
<title>Hello World Sample Explained</title>
<para>Hello World uses both Spring XML and annotations for its
configuration. The initial boostrapping configuration is
<literal>app-context.xml</literal> which includes the cache
configuration, defined under <literal>cache-context.xml</literal> file
and performs classpath <ulink
url="http://static.springsource.org/spring/docs/3.0.x/spring-framework-reference/html/beans.html#beans-classpath-scanning">scanning</ulink>
for Spring <ulink
url="http://static.springsource.org/spring/docs/3.0.x/spring-framework-reference/html/beans.html#beans-factorybeans-annotations">components</ulink>.
The cache configuration defines the GemFire cache, region and for
illustrative purposes a simple cache listener that acts as a
logger.</para>
<para>The main <emphasis>beans</emphasis> are
<literal>HelloWorld</literal> and <literal>CommandProcessor</literal>
which rely on the <classname>GemfireTemplate</classname> to interact
with the distributed fabric. Both classes use annotations to define
their dependency and life-cycle callbacks.</para>
</section>
</section>
</chapter>

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>