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

+ rearrange the folder

Browse Source
This commit is contained in:
Costin Leau
2011-07-19 20:06:37 +03:00
parent 6459592c34
commit 098996c867
16 changed files with 8 additions and 73 deletions
Download Patch File Download Diff File Expand all files Collapse all files

13
docs/src/reference/docbook/appendix/appendix-schema.xml Normal file
View File

@@ -0,0 +1,13 @@
<?xml version="1.0" encoding="UTF-8"?>
<appendix xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="appendix-schema" xmlns:xi="http://www.w3.org/2001/XInclude">
<title>Spring GemFire Integration Schema</title>
<para>Spring GemFire Schema</para>
<programlisting language="xml"><xi:include href="../../../../../src/main/resources/org/springframework/data/gemfire/config/spring-gemfire-1.0.xsd" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude">
<xi:fallback>
<para><emphasis>FIXME: SGF SCHEMA LOCATION/NAME CHANGED</emphasis></para>
</xi:fallback>
</xi:include>
</programlisting>
</appendix>

67
docs/src/reference/docbook/index.xml Normal file
View File

@@ -0,0 +1,67 @@
<?xml version="1.0" encoding="UTF-8"?>
<book xmlns="http://docbook.org/ns/docbook" version="5.0"
xml:id="spring-gemfire-reference"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink">
<bookinfo>
<title>Spring Gemfire Integration Reference Guide</title>
<releaseinfo>@version@</releaseinfo>
<authorgroup>
<author>
<firstname>Costin</firstname>
<surname>Leau</surname>
<affiliation>SpringSource, a division of VMware</affiliation>
</author>
</authorgroup>
<legalnotice>
<para>Copies of this document may be made for your own use and for
distribution to others, provided that you do not charge any fee for such
copies and further provided that each copy contains this Copyright
Notice, whether distributed in print or electronically.</para>
</legalnotice>
</bookinfo>
<toc />
<xi:include href="preface.xml"/>
<part id="introduction">
<title>Introduction</title>
<xi:include href="introduction/introduction.xml"/>
</part>
<part id="reference">
<title>Reference Documentation</title>
<xi:include href="reference/introduction.xml"/>
<xi:include href="reference/bootstrap.xml"/>
<!--
<xi:include href="reference/data.xml"/>
<xi:include href="reference/serialization.xml"/>
<xi:include href="reference/samples.xml"/>
-->
</part>
<!--
<part id="resources">
<title>Other Resources</title>
<partintro>
<para>
In addition to this reference documentation, there are a number of
other resources that may help you learn how to use GemFire and Spring framework.
These additional, third-party resources are enumerated in this section.
</para>
</partintro>
<xi:include href="links.xml"/>
</part>
<part id="appendices">
<title>Appendices</title>
<xi:include href="appendix/appendix-schema.xml"/>
</part>
-->
</book>

10
docs/src/reference/docbook/introduction/introduction.xml Normal file
View File

@@ -0,0 +1,10 @@
<?xml version="1.0" encoding="UTF-8"?>
<partintro xmlns="http://docbook.org/ns/docbook" version="5.0">
<para>
<para>This document is the reference guide for Spring GemFire project (SGF). It explains the relationship
between Spring framework and GemFire Enterprise Fabric (GEF) 6.0.x, defines the basic concepts and semantics of the integration
and how these can be used effectively.
</para>
</para>
</partintro>

8
docs/src/reference/docbook/introduction/requirements.xml Normal file
View File

@@ -0,0 +1,8 @@
<chapter xml:id="requirements" xmlns="http://docbook.org/ns/docbook" version="5.0">
<title>Requirements</title>
<para>Spring GemFire integration requires JDK level 5.0 and above, Spring
<ulink url="http://www.springsource.org/about">Framework</ulink> 3 and
<ulink url="http://www.gemstone.com/products/gemfire">GemFire</ulink> 6 and above.
</para>
</chapter>

12
docs/src/reference/docbook/links.xml Normal file
View File

@@ -0,0 +1,12 @@
<?xml version="1.0" encoding="UTF-8"?>
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="links">
<title>Useful Links</title>
<itemizedlist>
<listitem><emphasis>Spring GemFire Integration Home Page</emphasis> - <ulink url="http://www.springframework.org/spring-gemfire/">here</ulink></listitem>
<listitem><emphasis>SpringSource blog</emphasis> - <ulink url="http://blog.springsource.com/">here</ulink></listitem>
<listitem><emphasis>GemFire Community</emphasis> - <ulink url="http://community.gemstone.com/display/gemfire/GemFire+Enterprise">here</ulink></listitem>
</itemizedlist>
</chapter>

19
docs/src/reference/docbook/preface.xml Normal file
View File

@@ -0,0 +1,19 @@
<?xml version="1.0" encoding="UTF-8"?>
<preface xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="preface">
<title>Preface</title>
<para>
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 already has a basic familiarity with the Spring Framework and GemFire concepts
and APIs.
</para>
<para>
While every effort has been made to ensure that this documentation is comprehensive and there are no errors,
nevertheless some topics might require more explanation and some typos might have crept in. If you do spot any
mistakes or even more serious errors and you can spare a few cycles during lunch, please do bring the error
to the attention of the Spring GemFire Integration team by raising an
<ulink url="http://jira.springframework.org">issue</ulink>. Thank you.
</para>
</preface>

724
docs/src/reference/docbook/reference/bootstrap.xml Normal file
View File

@@ -0,0 +1,724 @@
<?xml version="1.0" encoding="UTF-8"?>
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude" xml:id="bootstrap">
<title>Bootstrapping GemFire through the Spring container</title>
<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:namespace">
<title>Using the Spring GemFire Namespace</title>
<para>To simplify configuration, SGF provides a dedicated namespace for most of its components. However, one can opt to configure the beans
directly through the usual &lt;bean&gt; definition. For more information about XML Schema-based configuration in Spring, see
<ulink url="http://static.springsource.org/spring/docs/3.0.x/spring-framework-reference/html/xsd-config.html">this</ulink> appendix in the
Spring Framework reference documentation.</para>
<para>To use the SGF namespace, one just needs to import it inside the configuration:</para>
<programlistingco>
<areaspec>
<area id="gfe#ns#prefix" coords="4 11"/>
<area id="gfe#ns#uri" coords="4 58"/>
<area id="gfe#ns#uri#loc" coords="7 119"/>
<area id="gfe#ns#example" coords="10 9"/>
</areaspec>
<programlisting language="xml"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:gfe="http://www.springframework.org/schema/gemfire"
xsi:schemaLocation="
http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
http://www.springframework.org/schema/gemfire http://www.springframework.org/schema/gemfire/spring-gemfire.xsd">
<bean id ... >
<gfe:cache ...>
</beans>]]></programlisting>
<calloutlist>
<callout arearefs="gfe#ns#prefix">
<para>Spring GemFire namespace prefix. Any name can do but through out the reference documentation, the <literal>gfe</literal> will be used.</para>
</callout>
<callout arearefs="gfe#ns#uri">
<para>The namespace URI.</para>
</callout>
<callout arearefs="gfe#ns#uri#loc">
<para>The namespace URI location. Note that even though the location points to an external address (which exists and is valid), Spring will resolve
the schema locally as it is included in the Spring GemFire library.</para>
</callout>
<callout arearefs="gfe#ns#example">
<para>Declaration example for the GemFire namespace. Notice the prefix usage.</para>
</callout>
</calloutlist>
</programlistingco>
<para>Once declared, the namespace elements can be declared simply by appending the aforementioned prefix. Note that is possible to change the default namespace,
for example from <literal>&lt;beans&gt;</literal> to <literal>&lt;gfe&gt;</literal>. This is useful for configuration composed mainly of GemFire components as
it avoids declaring the prefix. To achieve this, simply swap the namespace prefix declaration above:</para>
<programlistingco>
<areaspec>
<area id="gfe#default-ns#prefix" coords="2 64"/>
<area id="gfe#default-ns#beans-prefix" coords="3 64"/>
<area id="gfe#default-ns#beans-example" coords="9 64"/>
<area id="gfe#default-ns#gfe-example" coords="11 64"/>
</areaspec>
<programlisting language="xml"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/gemfire"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:beans="http://www.springframework.org/schema/beans"
xsi:schemaLocation="
http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
http://www.springframework.org/schema/gemfire http://www.springframework.org/schema/gemfire/spring-gemfire.xsd">
<beans:bean id ... >
<cache ...>
</beans>]]></programlisting>
<calloutlist>
<callout arearefs="gfe#default-ns#prefix">
<para>The default namespace declaration for this XML file points to the Spring GemFire namespace.</para>
</callout>
<callout arearefs="gfe#default-ns#beans-prefix">
<para>The beans namespace prefix declaration.</para>
</callout>
<callout arearefs="gfe#default-ns#beans-example">
<para>Bean declaration using the <literal>&lt;beans&gt;</literal> namespace. Notice the prefix.</para>
</callout>
<callout arearefs="gfe#default-ns#gfe-example">
<para>Bean declaration using the <literal>&lt;gfe&gt;</literal> namespace. Notice the lack of prefix (as the default namespace is used).</para>
</callout>
</calloutlist>
</programlistingco>
<para>For the remainder of this doc, to improve readability, the XML examples will simply refer to the <literal>&lt;gfe&gt;</literal> namespace
without the namespace declaration, where possible.</para>
</section>
<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[<gfe:cache />]]></programlisting>
<para>The declaration above declares a bean(<literal>CacheFactoryBean</literal>)
for the GemFire Cache, named <literal>gemfire-cache</literal>. All the other SGF components use this
naming convention if no name is specified, allowing for very concise configurations. The definition above 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.Especially in environments with opened caches, this basic
configuration can go a long way.</para>
<para>For scenarios where the cache needs to be
configured, the user can pass in a reference the GemFire configuration
file:</para>
<programlisting language="xml"><![CDATA[<gfe:cache id="cache-with-xml" cache-xml-location="classpath:cache.xml"/>]]></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.</para>
<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>
<para>
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>
<para>To setup properties one can either use the <literal>properties</literal> element inside the <literal>util</literal> namespace
to declare or load properties files (the latter is recommended for externalizing environment specific settings outside the application
configuration):</para>
<programlisting language="xml"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:gfe="http://www.springframework.org/schema/gemfire"
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/gemfire http://www.springframework.org/schema/gemfire/spring-gemfire.xsd
http://www.springframework.org/schema/util http://www.springframework.org/schema/util/spring-util.xsd">
<gfe:cache id="cache-with-xml" cache-xml-location="classpath:cache.xml" properties-ref="props"/>
<util:properties id="props" location="classpath:/deployment/env.properties"/>
</beans>]]></programlisting>
<para>Or can use fallback to a <emphasis>raw</emphasis> <literal>&lt;beans&gt;</literal> declaration:</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>In this last example, the SGF classes are declared and configured directly without relying on the namespace. As one can tell,
this approach is a generic one, exposing more of the backing infrastructure.</para>
<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 id="bootstrap:cache:server">
<title>Configuring a GemFire <literal>CacheServer</literal></title>
<para>In Spring GemFire 1.1 dedicated support for configuring a
<ulink url="http://www.gemstone.com/docs/6.5.1/product/docs/japi/com/gemstone/gemfire/cache/server/package-summary.html">CacheServer</ulink> was added through
the <literal>org.springframework.data.gemfire.server</literal> package allowing complete configuration through the Spring container:</para>
<programlisting language="xml"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:gfe="http://www.springframework.org/schema/gemfire"
xmlns:p="http://www.springframework.org/schema/p"
xmlns:context="http://www.springframework.org/schema/context"
xmlns:util="http://www.springframework.org/schema/util"
xsi:schemaLocation="http://www.springframework.org/schema/gemfire http://www.springframework.org/schema/gemfire/spring-gemfire.xsd
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/util http://www.springframework.org/schema/util/spring-util.xsd">
<gfe:cache />
<!-- Advanced example depicting various cache server configuration options -->
<gfe:cache-server id="advanced-config" auto-startup="true"
bind-address="localhost" port="${gfe.port.6}" host-name-for-clients="localhost"
load-poll-interval="2000" max-connections="22" max-threads="16"
max-message-count="1000" max-time-between-pings="30000"
groups="test-server">
<gfe:subscription-config eviction-type="ENTRY" capacity="1000" disk-store="file://${java.io.tmpdir}"/>
</gfe:cache-server>
<context:property-placeholder location="classpath:port.properties" />
</beans>]]></programlisting>
<para>The configuration above shows the dedicated namespace support (through the <literal>cache-server</literal> element) and the pleothera of options available. Note that rather
then just hard-coding the port, this config uses Spring <literal><ulink url="http://static.springsource.org/spring/docs/3.0.x/reference/xsd-config.html">util</ulink></literal> namespace
to read it from a properties file and then replace it at runtime allowing administrators to change it without having to touch the main application config. Through Spring's property placeholder
<ulink url="http://static.springsource.org/spring/docs/3.0.x/reference/beans.html#beans-factory-placeholderconfigurer">support</ulink>,
<ulink url="http://static.springsource.org/spring/docs/3.0.x/reference/expressions.html">SpEL</ulink> and the <ulink url="http://blog.springsource.com/2011/06/09/spring-framework-3-1-m2-released/">environment abstraction</ulink> one
can externalize environment specific properties from the main code base easing the deployment across multiple machines.</para>
</section>
</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 to
interact with the data fabric. SGF allows various region types to be configured and created directly from Spring or
in case they are created directly in GemFire, retrieved as such.</para>
<para>For more information about the various region types and their capabilities as well as configuration options, please
refer to the GemFire Developer's <ulink url="http://www.gemstone.com/documentation">Guide</ulink> and community
<ulink url="http://community.gemstone.com/display/gemfire/GemFire+Enterprise">site</ulink>.</para>
<section id="bootstrap:region:lookup">
<title>Using an externaly configured <interfacename>Region</interfacename></title>
<para>For consuming but not creating <interfacename>Region</interfacename>s (for example in case,
the regions are already configured through GemFire native configuration, the <literal>cache.xml</literal>),
one can use the <literal>lookup-region</literal> element. Simply declare the target region name the <literal>
name</literal> attribute; for example to declare a bean definition, named <literal>region-bean</literal>
for an existing region named <literal>orders</literal> one can use the following definition:</para>
<programlisting language="xml"><![CDATA[<gfe:lookup-region id="region-bean" name="orders"/>]]></programlisting>
<para>If the <literal>name</literal> is not specified, the bean name will be used automatically. The example above
becomes:</para>
<programlisting language="xml"><![CDATA[<!-- lookup for a region called 'orders' -->
<gfe:lookup-region id="orders"/>]]></programlisting>
<note><para>If the region does not exist, an initialization exception will be thrown. For configuring new GemFire regions
proceed to the sections below for replicated, partitioned, client or advanced region configuration.</para></note>
<para>Note that in the previous examples, since no cache name was defined, the default SGF naming convention (<literal>gemfire-cache</literal>)
was used. If that is not an option, one can point to the cache bean through the <literal>cache-ref</literal> attribute:
</para>
<programlisting language="xml"><![CDATA[<gfe:cache id="cache"/>
<gfe:lookup-region id="region-bean" name="orders" cache-ref="cache"/>]]></programlisting>
<para>The <literal>lookup-region</literal> provides a simple way of retrieving existing, pre-configured regions without exposing
the region semantics or setup infrastructure.</para>
</section>
<section id="bootstrap:region:replicate">
<title>Replicated Region</title>
<para>One of the common region types supported by GemFire is <emphasis>replicated region</emphasis> or <emphasis>replica</emphasis>. In short:</para>
<note><title>What is a replica?</title>
When a region is configured to be a replicated region, every member that hosts that region stores a copy of the contents of the region locally.
Any update to a replicated region is distributed to all copies of the region. [...] When a replica is created, it goes through an initialization stage
in which it discovers other replicas and automatically copies all the entries. While one replica is initializing you can still continue to use the other replicas.
</note>
<para>SGF offers a dedicated element for creating replicas in the form of <literal>replicated-region</literal> element. A minimal declaration looks as follows
(again, the example will not setup the cache wiring, relying on the SGF namespace naming conventions):</para>
<programlisting language="xml"><![CDATA[<gfe:replicated-region id="simple-replica" />]]></programlisting>
<para>Here, a replicated region is created (if one doesn't exist already). The name of the region is the same as the bean name (<literal>simple-replica</literal>) and
the bean assumes the existence of a GemFire cache named <literal>gemfire-cache</literal>.</para>
<para>When setting a region, it's fairly common to associate various <interfacename>CacheLoader</interfacename>s, <interfacename>CacheListener</interfacename>s and
<interfacename>CacheWriter</interfacename>s with it. These components can be either referrenced or declared inlined by the region declaration.</para>
<note><para>
Following the GemFire recommandations, the namespace allows for each region created multiple listeners but only one
cache writer and cache loader. This restriction can be relaxed, for advanced usages by using the <literal>beans</literal> declaration (see the next section).
</para></note>
<para>Below is an example, showing both styles:</para>
<programlisting language="xml"><![CDATA[<gfe:replicated-region id="mixed">
<gfe:cache-listener>
<!-- nested cache listener reference -->
<ref bean="c-listener"/>
<!-- nested cache listener declaration -->
<bean class="some.pkg.SimpleCacheListener"/>
</gfe:cache-listener>
<!-- loader reference -->
<gfe:cache-loader ref="c-loader"/>
<!-- writer reference -->
<gfe:cache-writer ref="c-writer"/>
</gfe:replicated-region>]]></programlisting>
<warning><para>Using <literal>ref</literal> and a nested declaration on <literal>cache-listener</literal>, <literal>cache-loader</literal> or <literal>cache-writer</literal>
is illegal. The two options are mutually exclusive and using them at the same time, on the same element will throw an exception.</para></warning>
<section id="bootstrap:region:replicate:options">
<title><literal>replicated-region</literal> Options</title>
<para>The following table offers a quick overview of the most important configuration options names, possible values and short descriptions for each of settings supported by the
<literal>replicated-region</literal> element. Please see the storage and eviction section for the relevant configuration.</para>
<table id="bootstrap:region:replicate:attrs:table" pgwide="1" align="center">
<title><![CDATA[replicated-region]]> options</title>
<tgroup cols="3">
<colspec colname="c1"/>
<colspec colname="c2"/>
<colspec colname="c3"/>
<thead>
<row>
<entry>Name</entry>
<entry spanname="values">Values</entry>
<entry align="center">Description</entry>
</row>
</thead>
<tbody>
<row>
<entry>id</entry>
<entry spanname="values"><emphasis>any valid bean name</emphasis></entry>
<entry>The id of the region bean definition.</entry>
</row>
<row>
<entry>name</entry>
<entry spanname="values"><emphasis>any valid region name</emphasis></entry>
<entry>The name of the region definition. If no specified, it will have the value of the id attribute (that is, the bean name).</entry>
</row>
<row>
<entry>cache-ref</entry>
<entry spanname="values"><emphasis>GemFire cache bean name</emphasis></entry>
<entry>The name of the bean defining the GemFire cache (by default 'gemfire-cache').</entry>
</row>
<row>
<entry>cache-listener</entry>
<entry spanname="values"><emphasis>valid bean name or definition</emphasis></entry>
<entry>The name or nested bean declaration of a GemFire <interfacename>CacheListener</interfacename>.</entry>
</row>
<row>
<entry>cache-loader</entry>
<entry spanname="values"><emphasis>valid bean name or definition</emphasis></entry>
<entry>The name or nested bean declaration of a GemFire <interfacename>CacheLoader</interfacename>.</entry>
</row>
<row>
<entry>cache-writer</entry>
<entry spanname="values"><emphasis>valid bean name or definition</emphasis></entry>
<entry>The name or nested bean declaration of a GemFire <interfacename>CacheWriter</interfacename>.</entry>
</row>
</tbody>
</tgroup>
</table>
</section>
</section>
<section id="bootstrap:region:partition">
<title>Partition(ed) Region</title>
<para>Another region type supported out of the box by the SGF namespace, is the partitioned region. To quote again the GemFire docs:</para>
<note><title>What is a partition?</title>
<para>A partitioned region is a region where data is divided between peer servers hosting the region so that each peer stores a subset of the data.
When using a partitioned region, applications are presented with a logical view of the region that looks like a single map containing all of the data in the region.
Reads or writes to this map are transparently routed to the peer that hosts the entry that is the target of the operation. [...]
GemFire divides the domain of hashcodes into buckets. Each bucket is assigned to a specific peer, but may be relocated at any time to another peer in
order to improve the utilization of resources across the cluster.</para></note>
<para>A partition can be created by SGF through the <literal>partitioned-region</literal> element. Its configuration options are similar to that of the
<literal>replicated-region</literal> plus the partion specific features such as the number of redundant copies, total maximum memory, number of buckets, partition
resolver and so on.
Below is a quick example on setting up a partition region with 2 redundant copies:</para>
<programlisting language="xml"><![CDATA[<!-- bean definition named 'distributed-partition' backed by a region named 'redundant' with 2 copies
and a nested resolver declaration -->
<gfe:partitioned-region id="distributed-partition" copies="2" total-buckets="4" name="redundant">
<gfe:partition-resolver>
<bean class="some.pkg.SimplePartitionResolver"/>
</gfe:partition-resolver>
</gfe:partitioned-region>]]></programlisting>
<section id="bootstrap:region:partition:options">
<title><literal>partitioned-region</literal> Options</title>
<para>The following table offers a quick overview of the most important configuration options names, possible values and short descriptions for each of settings supported by the
partition element. Please see the storage and eviction section for the relevant configuration.</para>
<table id="bootstrap:region:partition:attrs:table" pgwide="1" align="center">
<title><![CDATA[partitioned-region]]> options</title>
<tgroup cols="3">
<colspec colname="c1"/>
<colspec colname="c2"/>
<colspec colname="c3"/>
<thead>
<row>
<entry>Name</entry>
<entry spanname="values">Values</entry>
<entry align="center">Description</entry>
</row>
</thead>
<tbody>
<row>
<entry>id</entry>
<entry spanname="values"><emphasis>any valid bean name</emphasis></entry>
<entry>The id of the region bean definition.</entry>
</row>
<row>
<entry>name</entry>
<entry spanname="values"><emphasis>any valid region name</emphasis></entry>
<entry>The name of the region definition. If no specified, it will have the value of the id attribute (that is, the bean name).</entry>
</row>
<row>
<entry>cache-ref</entry>
<entry spanname="values"><emphasis>GemFire cache bean name</emphasis></entry>
<entry>The name of the bean defining the GemFire cache (by default 'gemfire-cache').</entry>
</row>
<row>
<entry>cache-listener</entry>
<entry spanname="values"><emphasis>valid bean name or definition</emphasis></entry>
<entry>The name or nested bean declaration of a GemFire <interfacename>CacheListener</interfacename>.</entry>
</row>
<row>
<entry>cache-loader</entry>
<entry spanname="values"><emphasis>valid bean name or definition</emphasis></entry>
<entry>The name or nested bean declaration of a GemFire <interfacename>CacheLoader</interfacename>.</entry>
</row>
<row>
<entry>cache-writer</entry>
<entry spanname="values"><emphasis>valid bean name or definition</emphasis></entry>
<entry>The name or nested bean declaration of a GemFire <interfacename>CacheWriter</interfacename>.</entry>
</row>
<row>
<entry>partition-resolver</entry>
<entry spanname="values"><emphasis>bean name</emphasis></entry>
<entry>The name of the partitioned resolver used by this region, for custom partitioning.</entry>
</row>
<row>
<entry>copies</entry>
<entry spanname="values">0..4</entry>
<entry>The number of copies for each partition for high-availability. By default, no copies are created meaning there is no
redundancy. Each copy provides extra backup at the expense of extra storages.</entry>
</row>
<row>
<entry>colocated-with</entry>
<entry spanname="values"><emphasis>valid region name</emphasis></entry>
<entry>The name of the partitioned region with which this newly created partitioned region is colocated.</entry>
</row>
<row>
<entry>local-max-memory</entry>
<entry spanname="values"><emphasis>positive integer</emphasis></entry>
<entry>The maximum amount of memory, in megabytes, to be used by the region in <emphasis>this</emphasis> process.</entry>
</row>
<row>
<entry>total-max-memory</entry>
<entry spanname="values"><emphasis>any integer value</emphasis></entry>
<entry>The maximum amount of memory, in megabytes, to be used by the region in <emphasis>all</emphasis> processes.</entry>
</row>
<row>
<entry>recovery-delay</entry>
<entry spanname="values"><emphasis>any long value</emphasis></entry>
<entry>The delay in milliseconds that existing members will wait before satisfying redundancy after another member crashes.
-1 (the default) indicates that redundancy will not be recovered after a failure.</entry>
</row>
<row>
<entry>startup-recovery-delay</entry>
<entry spanname="values"><emphasis>any long value</emphasis></entry>
<entry>The delay in milliseconds that new members will wait before satisfying redundancy. -1 indicates that adding new members
will not trigger redundancy recovery. The default is to recover redundancy immediately when a new member is added.</entry>
</row>
</tbody>
</tgroup>
</table>
</section>
</section>
<section id="bootstrap:region:client">
<title>Client Region</title>
<para>GemFire supports various deployment topologies for managing and distributing data. The topic is outside the scope of this documentation however to quickly recap, they
can be categoried in short in: peer-to-peer (p2p), client-server (or super-peer cache network) and wide area cache network (or WAN). In the last two scenarios, it is common
to declare <emphasis>client</emphasis> regions which connect to a backing cache server (or super peer). SGF offers dedicated support for such configuration through the
<literal>client-region</literal> and <literal>pool</literal> elements.
As the name imply, the former defines a client region while the latter connection pools to be used/shared by the various client regions.</para>
<para>Below is a usual configuration for a client region:</para>
<programlisting language="xml"><![CDATA[<!-- client region declaration -->
<gfe:client-region id="complex" pool-name="gemfire-pool">
<gfe:cache-listener ref="c-listener"/>
</gfe:client-region>
<bean id="c-listener" class="some.pkg.SimpleCacheListener"/>
<!-- pool declaration -->
<gfe:pool id="gemfire-pool" subscription-enabled="false">
<gfe:locator host="localhost" port="40403"/>
</gfe:pool>]]></programlisting>
<para>Just as the other region types, <literal>client-region</literal> allows defining <interfacename>CacheListener</interfacename>s. It also relies on the same naming conventions
in case the region name or the cache are not set explicitely. However, it also requires a connection <literal>pool</literal> to be specified for connecting to the server. Each client
can have its own pool or they can share the same one.</para>
<para>For a full list of options to set on the client and especially on the pool, please refer to the SGF schema (<xref linkend="appendix-schema"/>) and the GemFire documentation.</para>
<section id="bootstrap:region:client:interests">
<title>Client Interests</title>
<para>To minimize network traffic, each client can define its own 'interest', pointing out to GemFire, the data it actually needs. In SGF, interests can be defined for each client, both
key-based and regular-expression-based types being supported; for example:</para>
<programlisting language="xml"><![CDATA[<gfe:client-region id="complex" pool-name="gemfire-pool">
<gfe:key-interest durable="true" result-policy="KEYS">
<bean id="key" class="java.lang.String"/>
</gfe:key-interest>
<gfe:regex-interest pattern=".*"/>
</gfe:client-region>]]></programlisting>
</section>
</section>
<section id="bootstrap:region:disk-storage">
<title>Configurating Disk Storage</title>
<para>GemFire can use disk as a secondary storage for persisting regions or/and overflow (known as data pagination or eviction to disk). SGF allows such options to be configured
directly from Spring through <literal>disk-store</literal> element available on both <literal>replicated-region</literal> and <literal>partitioned-region</literal> as well as
<literal>client-region</literal>.
A disk store defines how that particular region can use the disk and how much space it has available. Multiple directories can be defined in a disk store such as in our example below:
</para>
<programlisting language="xml"><![CDATA[<gfe:partitioned-region id="partition-data">
<gfe:disk-store queue-size="50" auto-compact="true" max-oplog-size="10" synchronous-write="false" time-interval="9999">
<gfe:disk-dir location="/mainbackup/partition" max-size="999"/>
<gfe:disk-dir location="/backup2/partition" max-size="999"/>
</gfe:disk-store>
</gfe:replicated-region>]]></programlisting>
<para>In general, for maximum efficiency, it is recommended that each region that accesses the disk uses a disk store configuration.</para>
<para>
For the full set of options and their meaning please refer to the <xref linkend="appendix-schema"/> and GemFire documentation.
</para>
</section>
<section id="bootstrap:region:persistence">
<title>Data Persistence</title>
<para>Both partitioned and replicated regions can be made persistent. That is:</para>
<note><title>What is region persistence?</title>
<para>GemFire ensures that all the data you put into a region that is configured for persistence will be written to disk in a way that it can be
recovered the next time you create the region. This allows data to be recovered after a machine or process failure or after an orderly shutdown and
restart of GemFire.</para>
</note>
<para>With SGF, to enable persistence, simply set to true the <literal>persistent</literal> attribute on <literal>replicated-region</literal>,
<literal>partitioned-region</literal> or <literal>client-region</literal>:</para>
<programlisting language="xml"><![CDATA[<gfe:partitioned-region id="persitent-partition" persistent="true"/>]]></programlisting>
<important><para>Persistence for partitioned regions is supported from GemFire 6.5 onwards - configuring this option on a previous release will trigger
an initialization exception.</para></important>
<para>When persisting regions, it is recommended to configure the storage through the <literal>disk-store</literal> element for maximum efficiency.</para>
</section>
<section id="bootstrap:region:eviction">
<title>Data Eviction and Overflowing</title>
<para>Based on various constraints, each region can have an eviction policy in place for <literal>evicting</literal> data from memory. Currently, in GemFire
eviction applies on the least recently used entry (also known as <ulink url="http://en.wikipedia.org/wiki/Cache_algorithms#Least_Recently_Used">LRU</ulink>).
Evicted entries are either destroyed or paged to disk (also known as <emphasis>overflow</emphasis>).</para>
<para>SGF supports all eviction policies (entry count, memory and heap usage) for both <literal>partitioned-region</literal> and <literal>replicated-region</literal>
as well as <literal>client-region</literal>, through the nested <literal>eviction</literal> element.
For example, to configure a partition to overflow to disk if its size is more then 512 MB, one could use
the following configuration:</para>
<programlisting language="xml"><![CDATA[<gfe:partitioned-region id="overflow-partition">
<gfe:eviction type="MEMORY_SIZE" threshold="512" action="OVERFLOW_TO_DISK"/>
</gfe:partitioned-region>]]></programlisting>
<important><para>Replicas cannot use a <literal>local destroy</literal> eviction since that would invalidate them. See the GemFire docs for more information.</para></important>
<para>When configuring regions for oveflow, it is recommended to configure the storage through the <literal>disk-store</literal> element for maximum efficiency.</para>
<para>For a detailed description of eviction policies, see the GemFire documentation (such as <ulink url="http://community.gemstone.com/display/gemfire/Data+Eviction">this</ulink>
page).</para>
</section>
<section id="bootstrap:region:beans:config">
<title>Advanced Region Configuration</title>
<para>SGF namespaces allow short and easy configuration of the major GemFire regions and associated entities. However, there might be corner cases where the namespaces are not enough, where
a certain combination or set of attributes needs to be used. For such situations, using directly the SGF <interfacename>FactoryBean</interfacename>s is a possible alternative as it gives
access to the full set of options at the expense of conciseness.</para>
<para>As a warm up, below are some common configurations, declared through raw <literal>beans</literal> definitions.</para>
<para>A basic configuration looks as follows:</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>Notice how the GemFire cache definition has been nested into the declaring region definition. Let's add more regions
and make the cache a top level bean.</para>
<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"&gt;
&lt;!-- shared cache across regions --&gt;
&lt;bean id="cache" class="org.springframework.data.gemfire.CacheFactoryBean"/&gt;
&lt;!-- region named 'basic' --&gt;
&lt;bean id="basic" class="org.springframework.data.gemfire.RegionFactoryBean" p:cache-ref="cache"/&gt;
&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>
<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;
&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>
<para>For scenarios where a <emphasis>CacheServer</emphasis> is used and
<emphasis>clients</emphasis> need to be configured and the namespace is not an option, SGF 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.client</literal> package:</para>
<programlisting language="xml">&lt;bean id="interested-client" class="org.springframework.data.gemfire.client.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.client.Interest" p:key="Vlaicu" p:policy="NONE"/&gt;
&lt;!-- regex-based interest --&gt;
&lt;bean class="org.springframework.data.gemfire.client.RegexInterest" p:key=".*" p:policy="KEYS" p:durable="true"/&gt;
&lt;/array&gt;
&lt;/property&gt;
&lt;/bean&gt;</programlisting>
<para>Users that need fine control over a region, can configure it in Spring by using the <literal>attributes</literal> property. To ease declarative configuration in Spring,
SGF provides two <interfacename>FactoryBean</interfacename>s for creating <interfacename>RegionAttributes</interfacename> and <interfacename>PartitionAttributes</interfacename>,
namely <classname>RegionAttributesFactory</classname> and <classname>PartitionAttributesFactory</classname>. See below an example of configuring a partitioned region through Spring
XML:</para>
<programlisting language="xml"><![CDATA[<bean id="partitioned-region" class="org.springframework.data.gemfire.RegionFactoryBean" p:cache-ref="cache">
<property name="attributes">
<bean class="org.springframework.data.gemfire.RegionAttributesFactory" p:initial-capacity="1024">
<property name="partitionAttributes">
<bean class="org.springframework.data.gemfire.PartitionAttributesFactory" p:redundant-copies="2" p:local-max-memory="512"/>
</property>
</bean>
</property>
</bean>]]></programlisting>
<para>By using the attribute factories above, one can reduce the size of the <literal>cache.xml</literal> or even eliminate it all together.</para>
</section>
</section>
<section id="bootstrap:region:spring:config">
<title>Advantages of using Spring over GemFire <literal>cache.xml</literal></title>
<para>With SGF, GemFire regions, pools and cache can be configured either through Spring or directly inside GemFire, native, <literal>cache.xml</literal> file. While both are valid
approaches, it's worth pointing out that Spring's powerful DI container and AOP functionality makes it very easy to wire GemFire into an application. For example configuring a region
cache loader, listener and writer through the Spring container is preferred since the same instances can be reused across multiple regions and additionally are either to configure
due to the presence of the DI and eliminates the need of implementing GemFire's <interfacename>Declarable</interfacename> interface (see <xref linkend="apis:declarable"/> on chapter
on how you can still use them yet benefit from Spring's DI container).</para>
<para>Whatever route one chooses to go, SGF supports both approaches allowing for easy migrate between them without forcing an upfront decision.</para>
</section>
</chapter>

346
docs/src/reference/docbook/reference/data.xml Normal file
View File

@@ -0,0 +1,346 @@
<?xml version="1.0" encoding="UTF-8"?>
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude" xml:id="apis">
<title>Working with the GemFire APIs</title>
<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>
<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>
<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&lt;String, String&gt; region = reg;
region.put("1", "one");
region.put("3", "three");
return region.query("length &lt; 5");
}
});</programlisting>
<para>For accessing the full power of the GemFire query language, one can use the <methodname>find</methodname> and <methodname>findUnique</methodname> which, as oppose to the
<methodname>query</methodname> method, can execute queries inside across multiple regions, execute projections just to name a few features. <methodname>find</methodname> method should be
used when the query selects multiple items (through <literal>SelectResults</literal>) and the latter, <methodname>findUnique</methodname>, as the name suggests when only one object is returned.
</para>
</section>
<section id="apis:spring-cache-abstraction">
<title>Support for Spring Cache Abstraction</title>
<para>Since 1.1, Spring GemFire provides an implementation for Spring 3.1
<ulink url="http://static.springsource.org/spring/docs/3.1.0.M2/spring-framework-reference/html/cache.html">cache abstraction</ulink> through the
<literal>org.springframework.data.gemfire.support</literal> package. To use GemFire
as a backing implementation, simply add <literal>GemfireCacheManager</literal> to your configuration:</para>
<programlisting language="xml"><![CDATA[<beans xmlns="http://www.springframework.org/schema/beans" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:cache="http://www.springframework.org/schema/cache"
xmlns:gfe="http://www.springframework.org/schema/gemfire"
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/gemfire http://www.springframework.org/schema/gemfire/spring-gemfire.xsd
http://www.springframework.org/schema/cache http://www.springframework.org/schema/cache/spring-cache.xsd">
<!-- turn on declarative caching -->
<cache:annotation-driven />
<gfe:cache id="gemfire-cache" />
<!-- declare GemFire Cache Manager -->
<bean id="cacheManager" class="org.springframework.data.gemfire.support.GemfireCacheManager" p:cache-ref="gemfire-cache">
</beans>]]>
</programlisting>
</section>
<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 APIs that can be configured either
programmatically or declaratively (the most popular choice).</para>
<para>For GemFire, SGF 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">&lt;gfe:transaction-manager id="tx-manager" cache-ref="cache"/&gt;</programlisting>
<note>The example above can be simplified even more by eliminating the <literal>cache-ref</literal> attribute if the GemFire cache is defined under the default
name <literal>gemfire-cache</literal>. As with the other SGF namespace elements, if the cache name is not configured, the aforementioned naming convention will used.
Additionally, the transaction manager name, if not specified is <literal>gemfire-transaction-manager</literal>.</note>
<para>or if you prefer <literal>bean</literal> declarations:</para>
<programlisting language="xml">&lt;bean id="tx-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, SGF 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){
this.dataSource = ds;
}
public Object load(LoaderHelper helper) { ... }
}</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"&gt;
&lt;bean id="dataSource" ... /&gt;
&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"&gt;
&lt;bean id="dataSource" ... /&gt;
&lt;!-- template bean definition --&gt;
&lt;bean id="template-bean" abstract="true" p:dataSource-ref="dataSource"/&gt;
&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>
</section>
<section id="apis:declarable:autowiring">
<title>Configuration using auto-wiring and annotations</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. 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 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"&gt;
&lt;!-- enable annotation processing --&gt;
&lt;context:annotation-config/&gt;
&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>

27
docs/src/reference/docbook/reference/introduction.xml Normal file
View File

@@ -0,0 +1,27 @@
<partintro>
<title>Document structure</title>
<para>This part of the reference documentation explains the core functionality
offered by Spring GemFire integration.</para>
<para><xref linkend="bootstrap"/> describes the configuration support provided for
bootstrapping, initializing and accessing a GemFire cache or region.</para>
<para><xref linkend="apis"/> explains the integration between GemFire API and
the various "data" features available in Spring, such as transaction management
and exception translation.
</para>
<para><xref linkend="serialization"/> describes the enhancements for GemFire
(de)serialization process and management of associated objects.
</para>
<para><xref linkend="samples"/> describes the samples provided with the distribution
for showcasing the various features available in Spring GemFire.
</para>
<!--
<para><xref linkend="testing"/> showcases various ways of testing GemFire inside
Spring framework.</para>
-->
</partintro>

132
docs/src/reference/docbook/reference/samples.xml Normal file
View File

@@ -0,0 +1,132 @@
<?xml version="1.0" encoding="UTF-8"?>
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude" xml: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 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">
<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>
<note>
<title>Running under Linux</title>
<para>If you experience networking problems when starting GemFire or the samples,
try adding the following system property <literal>java.net.preferIPv4Stack=true</literal>
to the command line (insert <literal>-Djava.net.preferIPv4Stack=true</literal>).
For an alternative (global) fix especially on Ubuntu see
this <ulink url="https://jira.springsource.org/browse/SGF-28">link</ulink></para>
</note>
<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 &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
-&gt; <emphasis role="bold">put 1 one</emphasis>
INFO: Updated [1] from [unu] to [one]
unu
-&gt; <emphasis role="bold">size</emphasis>
1
-&gt; <emphasis role="bold">put 2 two</emphasis>
INFO: Added [2=two] to the cache
null
-&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]
Hello World!
...
-&gt; <emphasis role="bold">size</emphasis>
2
-&gt; <emphasis role="bold">map</emphasis>
[2=two] [1=one]
-&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>

87
docs/src/reference/docbook/reference/serialization.xml Normal file
View File

@@ -0,0 +1,87 @@
<?xml version="1.0" encoding="UTF-8"?>
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude" xml: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>