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

Updating docs in progress and changed default bean names to camelCase

Browse Source
This commit is contained in:
David Turanski
2012-08-05 14:07:28 -04:00
parent a067ddbf48
commit 5bf6e2f15a
54 changed files with 763 additions and 311 deletions
Download Patch File Download Diff File Expand all files Collapse all files

5
docs/src/info/changelog.txt
View File

@@ -1,13 +1,16 @@
SPRING DATA GEMFIRE CHANGELOG
=============================
http://www.springsource.org/spring-gemfire
Changes in version 1.2.0.RELEASE (2012-08-15)
---------------------------------------------
General
* The Spring Data GemFire project, formerly Spring GemFire, is now a component of the Spring Data project
* Upgraded to GemFire 7.0
* Upgraded to Spring 3.1.2.RELEASE
* Upgraded to Spring Data Commons 1.4.0.RELEASE
* XML namespace supports everything that can be configured with Cache XML
* The XML namespace supports everything that can be configured with Cache XML
* A separate namespace for Spring Data Repository support
Enhancements
* [SGF-53] - Add "enable-gateway" to replicated and partitioned region namespace config

15
docs/src/info/readme.txt
View File

@@ -4,9 +4,9 @@ http://www.springsource.org/spring-gemfire
1. INTRODUCTION
Spring GemFire Integration is a top-level Spring project who's purpose is
to make it easier to build Spring-powered highly scalable applications using
GemFire as distributed data management platform.
Spring Data GemFire started as a top level Spring project, formerly known as Spring GemFire,
and is now a component of the Spring Data project. The project's purpose is to make it easier to
build Spring-powered highly scalable applications using vFabric GemFire as distributed data management platform.
2. RELEASE NOTES
@@ -15,14 +15,13 @@ details, consult the provided javadoc for specific packages and classes.
3. DISTRIBUTION JAR FILES
The Spring GemFire jars files can be found in the 'dist' directory.
The Spring Data GemFire jars files can be found in the 'dist' directory.
4. GETTING STARTED
Please see the reference documentation and the sample application (hello-world).
Additionally the blog at http://blog.springsource.com as well
as sections of interest in the reference documentation.
Please see the reference documentation at http://www.springsource.org/spring-gemfire/
and the Spring GemFire Examples at https://github.com/SpringSource/spring-gemfire-examples
ADDITIONAL RESOURCES
Spring GemFire Homepage : http://www.springsource.org/spring-gemfire
GemStone Gemfire Homepage: http://www.gemstone.com/products/gemfire
VMWare vFabric GemFire Homepage: http://www.vmware.com/products/application-platform/vfabric-gemfire/overview.html

15
docs/src/reference/docbook/index.xml
View File

@@ -4,11 +4,10 @@
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink">
<bookinfo>
<title>Spring Gemfire Integration Reference Guide</title>
<title>Spring Data Gemfire Reference Guide</title>
<releaseinfo>${version}</releaseinfo>
<titleabbrev>Spring GemFire ${version}</titleabbrev>
<productname>Spring GemFire</productname>
<titleabbrev>Spring Data GemFire ${version}</titleabbrev>
<productname>Spring Data GemFire</productname>
<authorgroup>
<author>
@@ -35,6 +34,13 @@
copies and further provided that each copy contains this Copyright
Notice, whether distributed in print or electronically.</para>
</legalnotice>
<releaseinfo>
<note>
As of the 1.2.0 release, this project, formerly known as Spring GemFire, has been renamed to Spring Data GemFire to reflect that
it is now a component of the <ulink url="http://www.springsource.org/spring-data">Spring Data</ulink> project.
</note>
</releaseinfo>
</bookinfo>
<toc />
@@ -45,6 +51,7 @@
<xi:include href="introduction/introduction.xml"/>
<xi:include href="introduction/requirements.xml"/>
<xi:include href="introduction/new-features.xml"/>
</part>
<part id="reference">

8
docs/src/reference/docbook/introduction/introduction.xml
View File

@@ -1,10 +1,8 @@
<?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>This document is the reference guide for Spring Data GemFire project (SGF). It explains the relationship
between Spring framework and <ulink url="http://www.vmware.com/products/application-platform/vfabric-gemfire/overview.html">vFabric GemFire</ulink>
and defines the basic concepts, semantics, and effect use of Spring's support for GemFire.
</para>
</para>
</partintro>

46
docs/src/reference/docbook/introduction/new-features.xml Normal file
View File

@@ -0,0 +1,46 @@
<chapter xml:id="new-features" xmlns="http://docbook.org/ns/docbook" version="5.0">
<title>New Features</title>
<note>
As of the 1.2.0 release, this project, formerly known as Spring GemFire, has been renamed to Spring Data GemFire to reflect that
it is now a component of the <ulink url="http://www.springsource.org/spring-data">Spring Data</ulink> project.
</note>
<section id="new-in-1-2-0">
<title>New in the 1.2.0 Release</title>
<itemizedlist>
<listitem><para>
Full support for GemFire configuration via <emphasis>gfe</emphasis> namespace. Now GemFire components may be configured completely without requiring a native cache.xml file.
</para>
</listitem>
<listitem><para>
WAN Gateway support for both GemFire 6.6.x and GemFire 7.0
</para>
</listitem>
<listitem><para>
Spring Data Repository support with a dedicated namespace: <emphasis>gfe-data</emphasis>
</para>
</listitem>
<listitem><para>
Namespace support for registering GemFire functions
</para>
</listitem>
<listitem>
<para>
A top level <literal>&lt;disk-store&gt;</literal> element has been added to the <emphasis>gfe</emphasis> namespace to allow sharing of persist stores among regions,
and other components that support persistent backup.
<caution>The <literal>&lt;*-region&gt;</literal> elements no longer allow a nested <literal>&lt;disk-store&gt;</literal>
</caution>
</para>
</listitem>
<listitem><para>
GemFire subregions are supported via nested <literal>&lt;*-region&gt;</literal> elements
</para>
</listitem>
<listitem><para>
A <literal>&lt;local-region&gt;</literal> element has been added to configure a local region
</para>
</listitem>
</itemizedlist>
</section>
</chapter>

6
docs/src/reference/docbook/introduction/requirements.xml
View File

@@ -1,8 +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.5 and above.
<para>Spring Data GemFire requires JDK level 5.0 and above, Spring
<ulink url="http://www.springsource.org/about">Framework</ulink> 3 and
<ulink url="http://www.vmware.com/support/pubs/vfabric-gemfire.html">vFabric GemFire</ulink> 6.6 and above.
</para>
</chapter>

13
docs/src/reference/docbook/preface.xml
View File

@@ -2,18 +2,17 @@
<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.
Spring Data GemFire focuses on integrating Spring Framework's powerful, non-invasive programming model
and concepts with vFabric GemFire, simplifying configuration, development and providing high-level abstractions.
This document assumes the reader already has a basic familiarity with the Spring Framework and vFabric 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
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
to the attention of the Spring Data GemFire team by raising an
<ulink url="http://jira.springframework.org">issue</ulink>. Thank you.
</para>
</preface>

557
docs/src/reference/docbook/reference/bootstrap.xml
View File

@@ -1,24 +1,26 @@
<?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>
<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
<para>Spring Data GemFire provides full configuration and initialization of the GemFire
data grid through Spring's IoC container. Spring Data GemFire provides several
classes that simplify the configuration of GemFire components including caches, regions, WAN gateways, persistence backup, and other distributed system components to
support a variety of scenarios with minimal effort.</para>
<section id="bootstrap:namespace">
<title>Using the Spring GemFire Namespace</title>
<title>Using the Core Spring Data 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
<para>To simplify configuration, Spring Data Gemfire provides a dedicated namespace for configuring core GemFire components.
It is also possible to configure the beans directly through Springs usual &lt;bean&gt; definition. However, as of Spring Data GemFire 1.2.0, the namespace provides full
support and is much easier to use. For more information about XML Schema-based configuration in Spring, see
<ulink url="http://static.springsource.org/spring/docs/3.1.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>
<note><para>
Spring Data Repository support uses a separate dedicated namespace. See <xref linkend="gemfire-repositories"/> for more information on how to configure GemFire Repositories.
</para></note>
<para>To use the Spring Data GemFire namespace, simply declare it in your Spring XML configuration:</para>
<programlisting language="xml"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
@@ -48,9 +50,11 @@
</callout>
</calloutlist>
<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
<para>Once declared, the namespace elements can be declared simply by appending the aforementioned prefix.</para>
<note><para>It is possible to change the default namespace,
for example from <literal>beans</literal> to <literal>gfe</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>
<programlisting language="xml"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="]]><co id="gfe#default-ns#prefix"/><![CDATA[http://www.springframework.org/schema/gemfire"
@@ -67,71 +71,71 @@
</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>
<para>The default namespace declaration for this XML file points to the Spring Data 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>
<para>Bean declaration using the <literal>beans</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>
<para>Bean declaration using the <literal>gfe</literal> namespace. Notice the lack of prefix (as the default namespace is used).</para>
</callout>
</calloutlist>
<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>
</note>
</section>
<section id="bootstrap:cache">
<title>Configuring the GemFire
<interfacename>Cache</interfacename></title>
<title>Configuring the GemFire Cache</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
<para>In order to use GemFire, one needs to either create a new
<interfacename>Cache</interfacename> or connect to an existing one. 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>
(or per classloader to be technically correct). In most cases the cache is created once.
</para>
<para>In its simplest form, a cache can be defined in one line:</para>
<para>A cache with default configuration can be created with a very simple declaration:</para>
<programlisting language="xml"><![CDATA[<gfe:cache />]]></programlisting>
<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>
<para>
A Spring application context containing this definition will, upon initialization, will register a <literal>CacheFactoryBean</literal>
to create a Spring bean named <literal>gemfireCache</literal> referencing a GemFire <interfacename>Cache</interfacename> instance.
This will be either an existing cache, or if one does not exist, a newly created one. Since no additional properties were specified, a newly created
cache will apply the default cache configuration.</para>
<para>
All Spring Data GemFire components which depend on
the Cache respect this naming convention so that there is no need to explicitly declare the Cache dependency. If you prefer, you can make the dependence explicit via the
<literal>cache-ref</literal> attribute provided by various namespace elements. Also you can easily override the Cache's bean name:
</para>
<programlisting language="xml"><![CDATA[<gfe:cache id="my-cache"/>]]></programlisting>
<para>
Starting with Spring Data GemFire 1.2.0, The GemFire Cache may be fully configured using Spring. However, GemFire's native XML
configuration file (e.g., cache.xml) is also supported. For scenarios in which the GemFire cache needs to be
configured natively, simply provide a reference the GemFire configuration
file using the <literal>cache-xml-location</literal> attribute:</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>
</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>
url="http://static.springsource.org/spring/docs/3.1.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>
be used, depending on the runtime environment or the prefix specified
(if any) in the resource location.</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>
specify GemFire <ulink url="http://pubs.vmware.com/vfabric51/topic/com.vmware.vfabric.gemfire.6.6/reference/topics/gemfire_properties.html">properties</ulink>
using one of Spring's common properties configuration methods. For example, one can use the <literal>properties</literal> element defined in the <literal>util</literal> namespace
to define properties directly 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"
@@ -142,47 +146,90 @@
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"/>
<gfe:cache properties-ref="props"/>
<util:properties id="props" location="classpath:/deployment/env.properties"/>
<util:properties id="props" location="file:/vfabric/gemfire/gemfire.properties"/>
</beans>]]></programlisting>
<note>
<para>
The cache settings apply only if a new cache needs to be created. If an open cache already exists in the JVM, these settings will
be ignored.
</para>
</note>
<para>Or can use fallback to a <emphasis>raw</emphasis> <literal>&lt;beans&gt;</literal> declaration:</para>
<section id="bootstrap:cache:advanced"><title>Advanced Cache Configuration</title>
<para>For advanced cache configuration, the <literal>cache</literal> element provides several attributes and child elements:</para>
<programlisting language="xml">
<co id="gfe#cache-element#attributes"/><![CDATA[
<gfe:cache
copy-on-read="true"
critical-heap-percentage="70"
eviction-heap-percentage="60"
lock-lease="120"
lock-timeout="60"
pdx-disk-store="diskStore"
pdx-ignore-unread-fields="true"
pdx-persistent="true"
pdx-read-serialized="false"
message-sync-interval="1"
search-timeout="300"
>]]>
<co id="gfe#transaction#listener"/><![CDATA[<gfe:transaction-listener ref="myTransactionListener"/>]]>
<co id="gfe#transaction#writer"/><![CDATA[<gfe:transaction-writer>
<bean class="org.springframework.data.gemfire.example.TransactionListener"/>
</gfe:transaction-writer>]]>
<co id="gfe#gateway#resolver"/><![CDATA[<gfe:gateway-conflict-resolver>
<bean class="org.springframework.data.gemfire.example.GatewayConflictResolver"/>
</gfe:gateway-conflict-resolver>]]>
<co id="gfe#dynamic#region"/><![CDATA[<gfe:dynamic-region-factory/>]]>
<co id="gfe#jndi#binding"/><![CDATA[<gfe:jndi-binding jndi-name="myDataSource" type="ManagedDataSource"/>
</gfe:cache>]]>
</programlisting>
<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>
<calloutlist>
<callout arearefs="gfe#cache-element#attributes">
<para>Various cache options are provided via these attributes. For a detailed explanation of any of these attributes, please consult
the GemFire product <ulink url="http://www.vmware.com/support/pubs/vfabric-gemfire.html">documentation</ulink></para>
</callout>
<callout arearefs="gfe#transaction#listener">
<para>An example of a <interfacename>TransactionListener</interfacename> declaration using a bean reference. The referenced bean must implement
<ulink url="http://www.vmware.com/support/developer/vfabric-gemfire/663-api/com/gemstone/gemfire/cache/TransactionListener.html">TransactionListener</ulink>.
For a detailed explanation of the functionality provided by this
and any of the following elements, please consult the GemFire product <ulink url="http://www.vmware.com/support/pubs/vfabric-gemfire.html">documentation</ulink></para>
</callout>
<callout arearefs="gfe#transaction#writer">
<para>An example of a <interfacename>TransactionWriter</interfacename> declaration using an inner bean declaration this time. The bean must implement
<ulink url="http://www.vmware.com/support/developer/vfabric-gemfire/663-api/com/gemstone/gemfire/cache/TransactionWriter.html">TransactionWriter</ulink></para>
</callout>
<callout arearefs="gfe#gateway#resolver">com.gemstone.gemfire.cache.util.GatewayConflictResolver
<para>An example of a <interfacename>GatewayConflictResolver</interfacename> declaration. The bean must implement
<interfacename>com.gemstone.gemfire.cache.util.GatewayConflictResolver</interfacename>. This requires GemFire 7.0</para>
</callout>
<callout arearefs="gfe#dynamic#region">
<para>Enable GemFire's <ulink url="http://www.vmware.com/support/developer/vfabric-gemfire/663-api/com/gemstone/gemfire/cache/DynamicRegionFactory.html">DynamicRegionFactory</ulink></para>
</callout>
<callout arearefs="gfe#jndi#binding">
<para>Declares a JNDI binding to enlist an extenal datasource in a GemFire transaction</para>
</callout>
</calloutlist>
</section>
<section id="bootstrap:cache:server">
<title>Configuring a GemFire <literal>CacheServer</literal></title>
<title>Configuring a GemFire Cache Server</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>
<para>In Spring Data 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,
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"
xmlns:context="http://www.springframework.org/schema/context"
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">
http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context.xsd">
<gfe:cache />
@@ -196,99 +243,87 @@
<gfe:subscription-config eviction-type="ENTRY" capacity="1000" disk-store="file://${java.io.tmpdir}"/>
</gfe:cache-server>
<context:property-placeholder location="classpath:port.properties" />
<context:property-placeholder location="classpath:cache-server.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>
<para>The configuration above illustrates the <literal>cache-server</literal> element and the many options available.</para>
<note><para>To avoid initialization problems, the <interfacename>CacheServer</interfacename>s started by SGF will start <emphasis>after</emphasis> the container has been fully initialized. This
<note><para>Rather than hard-coding the port, this configuration uses Spring <literal><ulink url="http://static.springsource.org/spring/docs/3.1.x/spring-framework-reference/html/xsd-config.html#xsd-config-body-schemas-context">context</ulink></literal>
namespace to declare a <literal>property-placeholder</literal>. The <ulink url="http://static.springsource.org/spring/docs/3.1.x/spring-framework-reference/html/beans.html#beans-factory-placeholderconfigurer">property placeholder</ulink>
reads one or more properties file and then replaces property placeholders with values at runtime. This allows administrators to change such values without having to touch the main application configuration. Spring
also provides
<ulink url="http://static.springsource.org/spring/docs/3.1.x/spring-framework-reference/html/new-in-3.0.html#new-feature-el">SpEL</ulink> and the <ulink url="http://static.springsource.org/spring/docs/3.1.x/spring-framework-reference/html/new-in-3.1.html#new-in-3.1-environment-abstraction">environment abstraction</ulink> one
to support externalization of environment specific properties from the main code base, easing the deployment across multiple machines.
</para>
</note>
<note><para>To avoid initialization problems, the <interfacename>CacheServer</interfacename>s started by Spring Data GemFire will start <emphasis>after</emphasis> the container has been fully initialized. This
allows potential regions, listener, writers or instantiators defined declaratively to be fully initialized and registered before the server starts accepting connections. Keep this in mind
when doing programmatic configuration of the items above as the server might start before your components and thus not be seen by the clients connecting right away.</para></note>
</section>
<section id="bootstrap:cache:client">
<title>Configuring a GemFire <literal>ClientCache</literal></title>
<title>Configuring a GemFire Client Cache</title>
<para>Another configuration addition in SGF 1.1 is the dedicated support for configuring
<ulink url="http://www.gemstone.com/docs/6.5.1/product/docs/japi/com/gemstone/gemfire/cache/client/ClientCache.html">ClientCache</ulink> -
similar to a <link linkend="bootstrap:cache">cache</link> (in both usage and definition) - through the <literal>org.springframework.data.gemfire.client</literal> package and in particular
<classname>ClientCacheFactoryBean</classname>.
<para>Another configuration addition in Spring Data GemFire 1.1 is the dedicated support for configuring
<ulink url="http://www.vmware.com/support/developer/vfabric-gemfire/663-api/com/gemstone/gemfire/cache/client/ClientCache.html">ClientCache</ulink>.
This is similar to a <link linkend="bootstrap:cache">cache</link> in both usage and definition and supported by the
the <classname>ClientCacheFactoryBean</classname> in the <literal>org.springframework.data.gemfire.client</literal> package.
</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"
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">
<gfe:client-cache />
<programlisting language="xml"><![CDATA[<beans>
<gfe:client-cache />
</beans>]]></programlisting>
<para><literal>client-cache</literal> supports much of the same options as the <emphasis>cache</emphasis> element. However as oppose to a <emphasis>vanilla</emphasis> cache,
a client cache connects to a server through a pool (by default a pool is created to connect to a server on <literal>localhost</literal> and <literal>40404</literal> -
the default pool is used by all client cache regions (unless configured to use a different pool)).</para>
<para><literal>client-cache</literal> supports much of the same options as the <emphasis>cache</emphasis> element. However as opposed to a <emphasis>full</emphasis> cache,
a client cache connects to a remote cache server through a pool. By default a pool is created to connect to a server on <literal>localhost</literal> port <literal>40404</literal>. The
the default pool is used by all client regions unless the region is configured to use a different pool.</para>
<para>Pools can be defined through the <literal>pool</literal>; in case of client caches and regions <literal>pool</literal>s can be used to customize the connectivity to the server for
individual entities or for the entire cache. For example, to custommize the default pool used by <literal>client-cache</literal>, one needs to define a pool and wire it to cache definition:</para>
<para>Pools can be defined through the <literal>pool</literal> element; The client side <literal>pool</literal>s can be used to configure connectivity to the server for
individual entities or for the entire cache. For example, to customize the default pool used by <literal>client-cache</literal>, one needs to define a pool and wire it to cache definition:</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"
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">
<programlisting language="xml">
<![CDATA[<beans>
<gfe:client-cache id="simple" pool-name="my-pool"/>
<gfe:pool id="my-pool" subscription-enabled="true">
<gfe:locator host="someHost" port="43210"/>
<gfe:locator host="${locatorHost}" port="${locatorPort}"/>
</gfe:pool>
</beans>]]></programlisting>
</section>
</section>
<section id="bootstrap:region">
<title>Configuring a GemFire <interfacename>Region</interfacename></title>
<title>Configuring a GemFire Region</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>Once the Cache is configured, one needs to configure one or more Regions to
access cached data. Spring Data GemFire allows regions to be configured and created directly in Spring or,
if they are already created natively in GemFire, registered in the Spring context.</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>
refer to the GemFire Developer's <ulink url="http://pubs.vmware.com/vfabric51/index.jsp?topic=/com.vmware.vfabric.gemfire.6.6/developing/book_intro.html">Guide</ulink> and community
<ulink url="http://communities.vmware.com/community/vmtn/appplatform/vfabric_gemfire">site</ulink>.</para>
<section id="bootstrap:region:lookup">
<title>Using an externaly configured <interfacename>Region</interfacename></title>
<title>Using an externaly configured Region</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>
<para>For referencing Regions already configured through GemFire native configuration, e.g., a <literal>cache.xml</literal> file,
use the <literal>lookup-region</literal> element. Simply declare the target region name with 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
<para>If the <literal>name</literal> is not specified, the bean's <literal>id</literal> will be used. 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>
<note><para>If the region does not exist, an initialization exception will be thrown. For configuring new GemFire regions,
proceed to the appropriate sections below.</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>Note that in the previous examples, since no cache name was defined, the default naming convention (<literal>gemfireCache</literal>)
was used. If that is not an option, one can reference the cache bean through the <literal>cache-ref</literal> attribute:
</para>
<programlisting language="xml"><![CDATA[<gfe:cache id="cache"/>
@@ -298,6 +333,208 @@
<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:overview">
<title>Configuring Regions</title>
<para>Spring Data GemFire provides comprehensive support for configuring any type of Region GemFire provides. Currently these include:
<itemizedlist>
<listitem><para>Local Region <literal>&lt;local-region&gt;</literal> - The region is only visible to the defining member</para></listitem>
<listitem><para>Replicated Region <literal>&lt;replicated-region&gt;</literal> - Holds all data from the distributed region</para></listitem>
<listitem><para>Partitioned Region <literal>&lt;partitioned-region&gt;</literal> - Data is divided into buckets across members</para></listitem>
<listitem><para>Client Region <literal>&lt;client-region&gt;</literal> - A local region used with a client cache</para></listitem>
</itemizedlist>
For a comprehensive description of <ulink url="http://pubs.vmware.com/vfabric51/topic/com.vmware.vfabric.gemfire.6.6/developing/region_options/region_types.html">region types</ulink> please
consult the GemFire product documentation.
</para>
<section id="bootstrap:region:common:attributes">
<title>Common Region Attributes</title>
<para>The following table(s) list attributes available for all region types:
<table id="bootstrap:region:common:attributes:table" pgwide="1" align="left" rowsep="1">
<title>Common Region Attributes</title>
<tgroup cols="3">
<colspec colname="c1" colwidth="15%"/>
<colspec colname="c2"/>
<colspec colname="c3"/>
<thead>
<row>
<entry>Name</entry>
<entry spanname="values">Values</entry>
<entry spanname="description">Description</entry>
</row>
</thead>
<tbody>
<row>
<entry>cache-ref</entry>
<entry spanname="values"><emphasis>GemFire cache bean name</emphasis></entry>
<entry spanname="description">The name of the bean defining the GemFire cache (by default 'gemfireCache').</entry>
</row>
<row>
<entry>close</entry>
<entry spanname="values"><emphasis>boolean, default:true</emphasis></entry>
<entry spanname="description">Indicates whether the region should be closed at shutdown</entry>
</row>
<row>
<entry>data-policy</entry>
<entry spanname="values"><emphasis>See GemFire's <ulink url="http://www.vmware.com/support/developer/vfabric-gemfire/663-api/com/gemstone/gemfire/cache/DataPolicy.html">Data Policy</ulink></emphasis></entry>
<entry spanname="description">The region's data policy. Note not all data policies are supported for every region type</entry>
</row>
<row>
<entry>destroy</entry>
<entry spanname="values"><emphasis>boolean, default:false</emphasis></entry>
<entry spanname="description">Indicates whether the region should be destroyed at shutdown</entry>
</row>
<row>
<entry>disk-store-ref</entry>
<entry spanname="values"><emphasis>The name of a configured disk store</emphasis></entry>
<entry spanname="description">A reference to a bean created via the <literal>disk-store</literal> element. Note: This will automatically enable persistence. If persistent is explicitly set to false, an exception will be thrown.</entry>
</row>
<row>
<entry>disk-synchronous</entry>
<entry spanname="values"><emphasis>boolean, default:false</emphasis></entry>
<entry spanname="description">Indicates whether disk store writes are synchronous. Note: This will automatically enable persistence. If persistent is explicitly set to false, an exception will be thrown.</entry>
</row>
<row>
<entry>enable-gateway</entry>
<entry spanname="values"><emphasis>boolean, default:false</emphasis></entry>
<entry spanname="description">Indicates whether the region will synchronize entries over a WAN gateway. Note: This is deprecated in GemFire 7.0</entry>
</row>
<row>
<entry>hub-id</entry>
<entry spanname="values"><emphasis>The name of the Gateway Hub</emphasis></entry>
<entry spanname="description">Note: This is deprecated in GemFire 7.0. Also this will automatically set enable-gateway to true. If enable-gateway is explicitly set to false, an exception will be thrown.</entry>
</row>
<row>
<entry>id</entry>
<entry spanname="values"><emphasis>any valid bean name</emphasis></entry>
<entry spanname="description">Will also be the region name by default</entry>
</row>
<row>
<entry>ignore-jta</entry>
<entry spanname="values"><emphasis>boolean, default:false</emphasis></entry>
<entry spanname="description">Indicates whether the region participates in JTA transactions</entry>
</row>
<row>
<entry>index-update-type</entry>
<entry spanname="values"><emphasis>synchronous or asynchronous, default:asynchronous</emphasis></entry>
<entry spanname="description">Indicates whether indices will be updated synchronously or asynchronously on entry creation</entry>
</row>
<row>
<entry>initial-capacity</entry>
<entry spanname="values"><emphasis>integer, default:16</emphasis></entry>
<entry spanname="description">The initial memory allocation for number of entries</entry>
</row>
<row>
<entry>key-constraint</entry>
<entry spanname="values"><emphasis>any valid java class name</emphasis></entry>
<entry spanname="description">The expected key type</entry>
</row>
<row>
<entry>name</entry>
<entry spanname="values"><emphasis>any valid region name</emphasis></entry>
<entry spanname="description">The name of the region definition. If no specified, it will assume the value of the id attribute (the bean name).</entry>
</row>
<row>
<entry>persistent</entry>
<entry spanname="values"><emphasis>boolean, default:false</emphasis></entry>
<entry spanname="description">Indicates whether the region persists entries to a disk store</entry>
</row>
<row>
<entry>statistics</entry>
<entry spanname="values"><emphasis>boolean, default:false</emphasis></entry>
<entry spanname="description">Indicates whether the region reports statistics</entry>
</row>
<row>
<entry>value-constraint</entry>
<entry spanname="values"><emphasis>any valid java class name</emphasis></entry>
<entry spanname="description">The expected value type</entry>
</row>
</tbody>
</tgroup>
</table>
</para>
</section>
<section id="bootstrap:region:common:cache-listener">
<title>Cache Listeners</title>
<para>Cache Listeners are registered with a region to handle region events such as entries being created, updated, destroyed, etc. A Cache Listener can be any bean that
implements the <ulink url="http://www.vmware.com/support/developer/vfabric-gemfire/663-api/com/gemstone/gemfire/cache/CacheListener.html"><interfacename>CacheListener</interfacename></ulink>
interface. A region may have multiple listeners, declared using the <literal>cache-listener</literal> element enclosed in a <literal>*-region</literal> element.
In the example below, there are two <interfacename>CacheListener</interfacename>s declared. The first references a top level named Spring bean; the second is an
anonymous inner bean definition.
<programlisting language="xml"><![CDATA[
<gfe:replicated-region id="region-with-listeners">
<gfe:cache-listener>
<!-- nested cache listener reference -->
<ref bean="c-listener"/>
<!-- nested cache listener declaration -->
<bean class="some.pkg.AnotherSimpleCacheListener"/>
</gfe:cache-listener>
<bean id="c-listener" class="some.pkg.SimpleCacheListener"/>
</gfe:replicated-region>]]>
</programlisting>
The following example uses an alternate form of the <literal>cache-listener</literal> element with a <literal>ref</literal> attribute. This allows for more concise configuration
for a single cache listener. Note that the namespace only allows a single <literal>cache-listener</literal> element so either the style above or below must be used.
<caution><para>Using <literal>ref</literal> and a nested declaration in a <literal>cache-listener</literal>, or similar element,
is illegal. The two options are mutually exclusive and using both on the same element will result in an exception.</para></caution>
<programlisting language="xml"><![CDATA[<beans>
<gfe:replicated-region id="region-with-one listener">
<gfe:cache-listener ref="c-listener"/>
</gfe:replicated-region>
<bean id="c-listener" class="some.pkg.SimpleCacheListener"/>
</beans>]]>
</programlisting>
</para>
<note><title>Note:Bean Reference Conventions</title><para>
The <literal>cache-listener</literal> element is an example of a common pattern used in the namespace anywhere GemFire provides an interface that may be
implemented to invoke custom Java code. In order to simplify the configuration, a single occurance of the element is all that is required,
but may contain nested bean references and inner bean definitions in any combination if multiple instances are permitted.
The element name always takes the singular form (i.e., <literal>cache-listener</literal> vs <literal>cache-listeners</literal>) because it is assumed that
the most common scenario will in fact be a single instance.
We have already seen some examples of this pattern in the <link linkend="bootstrap:cache:advanced">advanced cache</link> configuration example.
</para>
</note>
</section>
<section id="bootstrap:region:common:loaders-writers">
<title>Cache Loaders and Cache Writers</title>
<para>Similar to <literal>cache-listener</literal>, the namespace provides <literal>cache-loader</literal> and <literal>cache-writer</literal> elements to register these
respective components for a region. A <interfacename>CacheLoader</interfacename> is invoked on a cache miss to allow an entry to be loaded from an external source, a database
for example. A <interfacename>CacheWriter</interfacename> is invoked afer an entry is created or updated,intended for synchronizing to an external data source.
The difference is GemFire only supports at most a single instance of each for each region. However, either declaration style may be
used. See <ulink url="http://www.vmware.com/support/developer/vfabric-gemfire/663-api/com/gemstone/gemfire/cache/CacheLoader.html"><interfacename>CacheLoader</interfacename></ulink> and
<ulink url="http://www.vmware.com/support/developer/vfabric-gemfire/663-api/com/gemstone/gemfire/cache/CacheWriter.html"><interfacename>CacheWriter</interfacename></ulink> for more details.</para>
</section>
<section id="bootstrap:region:common:subregions">
<title>Subregions</title>
<para>In Release 1.2.0, Spring Data GemFire added support for subregions, allowing regions to be arranged in a hierarchical relationship. For example, GemFire allows for
a <emphasis>/Customer/Address</emphasis> region and a different <emphasis>/Employee/Address</emphasis> region. Additionally, a subregion may have it's own subregions
and its own configuration. A subregion does not inherit attributes from the parent region. Regions types may be mixed and matched subject to GemFire constraints.
A subregion is naturally declared as a child element of a region. A subregion's name attribute is the simple name. The above example might be configured as:
<programlisting language="xml"><![CDATA[<beans>
<gfe:replicated-region name="Customer">
<gfe:replicated-region name="Address"/>
</gfe:replicated-region>
<gfe:replicated-region name="Employee">
<gfe:replicated-region name="Address"/>
</gfe:replicated-region>
</beans>]]>
</programlisting>
The subregions will be created with bean names <emphasis>/Customer/Address</emphasis> and <emphasis>/Employee/Address</emphasis>, respectively. So they may be referenced
directly by other beans that use them, such as <classname>GemfireTemplate</classname>.
</para>
</section>
</section>
<section id="bootstrap:region:replicate">
<title>Replicated Region</title>
@@ -310,21 +547,23 @@
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>
<para>Spring Data GemFire 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 relies on the Spring Data GemFire namespace naming conventions to wire the cache):</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>Here, a replicated region is created (if one doesn't exist already). The name of the region is the same as the bean id (<literal>simple-replica</literal>) and
the bean assumes the existence of a GemFire cache named <literal>gemfireCache</literal>.</para>
<para>When setting a region, it's fairly common to associate various <interfacename>CacheLoader</interfacename>s, <interfacename>CacheListener</interfacename>s and
<para>When setting up a region, it is 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>
Following the GemFire API, the namespace allows multiple cache listeners but only one
cache writer and cache loader for each region.</para>
</note>
<para>Below is an example, showing both styles:</para>
@@ -341,8 +580,8 @@
<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>
<caution><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 both on the same element will result in an exception.</para></caution>
<section id="bootstrap:region:replicate:options">
<title><literal>replicated-region</literal> Options</title>
@@ -350,7 +589,7 @@
<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">
<table id="bootstrap:region:replicate:attrs:table" pgwide="1" align="left">
<title><![CDATA[replicated-region]]> options</title>
<tgroup cols="3">
<colspec colname="c1"/>
@@ -377,7 +616,7 @@
<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>
<entry>The name of the bean defining the GemFire cache (by default 'gemfireCache').</entry>
</row>
<row>
<entry>cache-listener</entry>
@@ -404,7 +643,7 @@
<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>
<para>Another region type supported out of the box by the Spring Data GemFire 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.
@@ -413,7 +652,7 @@
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
<para>A partition can be created by Spring Data GemFire 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>
@@ -459,7 +698,7 @@ and a nested resolver declaration -->
<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>
<entry>The name of the bean defining the GemFire cache (by default 'gemfireCache').</entry>
</row>
<row>
@@ -527,7 +766,7 @@ redundancy. Each copy provides extra backup at the expense of extra storages.</e
<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
to declare <emphasis>client</emphasis> regions which connect to a backing cache server (or super peer). Spring Data GemFire offers dedicated support for such configuration through
<xref linkend="bootstrap:cache:client"/>, <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>
@@ -555,12 +794,12 @@ redundancy. Each copy provides extra backup at the expense of extra storages.</e
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>
<para>For a full list of options to set on the client and especially on the pool, please refer to the Spring Data GemFire 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
<para>To minimize network traffic, each client can define its own 'interest', pointing out to GemFire, the data it actually needs. In Spring Data GemFire, 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">
@@ -581,7 +820,7 @@ redundancy. Each copy provides extra backup at the expense of extra storages.</e
<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
<para>GemFire can use disk as a secondary storage for persisting regions or/and overflow (known as data pagination or eviction to disk). Spring Data GemFire 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:
@@ -613,7 +852,7 @@ redundancy. Each copy provides extra backup at the expense of extra storages.</e
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>,
<para>With Spring Data GemFire, 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>
@@ -631,7 +870,7 @@ redundancy. Each copy provides extra backup at the expense of extra storages.</e
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>
<para>Spring Data GemFire 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>
@@ -651,8 +890,8 @@ redundancy. Each copy provides extra backup at the expense of extra storages.</e
<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
<para>Spring Data GemFire 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 Spring Data GemFire <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>
@@ -714,7 +953,7 @@ redundancy. Each copy provides extra backup at the expense of extra storages.</e
&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
<emphasis>clients</emphasis> need to be configured and the namespace is not an option, Spring Data GemFire offers a
dedicated configuration class named:
<classname>ClientRegionFactoryBean</classname>. This allows client
<emphasis>interests</emphasis> to be registered in both key and regex
@@ -734,7 +973,7 @@ redundancy. Each copy provides extra backup at the expense of extra storages.</e
&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>,
Spring Data GemFire 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>
@@ -755,25 +994,25 @@ redundancy. Each copy provides extra backup at the expense of extra storages.</e
<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
<para>With Spring Data GemFire, 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>
<para>Whatever route one chooses to go, Spring Data GemFire supports both approaches allowing for easy migrate between them without forcing an upfront decision.</para>
</section>
<section id="bootstrap:indecies">
<title>Creating Indecies</title>
<para>GemFire allows creation on indices (or indexes) to improve the performance of (common) queries. SGF allows indecies to be declared through the <literal>index</literal> element:</para>
<para>GemFire allows creation on indices (or indexes) to improve the performance of (common) queries. Spring Data GemFire allows indecies to be declared through the <literal>index</literal> element:</para>
<programlisting language="xml"><![CDATA[<gfe:index id="myIndex" expression="someField" from="/someRegion"/>]]></programlisting>
<para>Before creating an index, SGF will verify whether one with the same name already exists. If it does, it will compare the properties and if they don't match, will remove the old one to create
a new one. If the properties match, SGF will simply return the index (in case it does not exist it will simply create one). To prevent the update of the index, even if the properties do not match,
<para>Before creating an index, Spring Data GemFire will verify whether one with the same name already exists. If it does, it will compare the properties and if they don't match, will remove the old one to create
a new one. If the properties match, Spring Data GemFire will simply return the index (in case it does not exist it will simply create one). To prevent the update of the index, even if the properties do not match,
set the property <literal>override</literal> to false.</para>
<para>

2
docs/src/reference/docbook/reference/cq-container.xml
View File

@@ -114,7 +114,7 @@
<lineannotation>&lt;!-- and this is the event listener container... --&gt;</lineannotation>
&lt;bean id="gemfireListenerContainer" class="org.springframework.data.gemfire.listener.ContinuousQueryListenerContainer"&gt;
&lt;property name="cache" ref="gemfire-cache"/&gt;
&lt;property name="cache" ref="gemfireCache"/&gt;
&lt;property name="queryListeners"&gt;
<lineannotation>&lt;!-- set of listeners --&gt;</lineannotation>
&lt;set&gt;

2
docs/src/reference/docbook/reference/data.xml
View File

@@ -116,7 +116,7 @@
<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.
name <literal>gemfireCache</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>

19
docs/src/reference/docbook/reference/introduction.xml
View File

@@ -1,23 +1,28 @@
<partintro>
<title>Document structure</title>
<para>This part of the reference documentation explains the core functionality
offered by Spring GemFire integration.</para>
<para>The following chapters explain the core functionality offered by Spring Data GemFire.</para>
<para><xref linkend="bootstrap"/> describes the configuration support provided for
bootstrapping, initializing and accessing a GemFire cache or region.</para>
bootstrapping, initializing, configuring, and accessing GemFire caches, regions and distributed system components.</para>
<para><xref linkend="apis"/> explains the integration between GemFire API and
the various "data" features available in Spring, such as transaction management
<para><xref linkend="apis"/> explains the integration between the GemFire APIs and
the various data access 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.
(de)serialization and management of associated objects.
</para>
<para><xref linkend="mapping"/> describes persistence mapping for POJOs stored in GemFire using Spring Data
</para>
<para><xref linkend="gemfire-repositories"/> describes how to create and use GemFire Repositories using Spring Data
</para>
<para><xref linkend="samples"/> describes the samples provided with the distribution
for showcasing the various features available in Spring GemFire.
to illustrate the various features available in Spring GemFire.
</para>
<!--