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

updated documentation; build upgraded to jdk 1.6. Schema clean up

Browse Source
This commit is contained in:
David Turanski
2012-08-22 08:08:13 -04:00
parent 1cee21b9e5
commit 3b793686bd
26 changed files with 1689 additions and 1520 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
docs/src/api/overview.html
View File

@@ -1,6 +1,6 @@
<html>
<body>
This document is the API specification for the Spring GemFire project.
This document is the API specification for the Spring Data GemFire project.
<hr/>
<div id="overviewBody">
@@ -15,7 +15,7 @@ This document is the API specification for the Spring GemFire project.
-->
<p>
If you are interested in commercial training, consultancy and
support for the Spring GemFire project,
support for the Spring Data GemFire project,
<a href="http://www.SpringSource.com/" target="_top">SpringSource</a> provides
such commercial support.
</p>

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

@@ -5,27 +5,34 @@ http://www.springsource.org/spring-gemfire
Changes in version 1.2.0.RELEASE (2012-08-15)
---------------------------------------------
General
* Added support for Spring Data repositories
* 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
* The XML namespace supports everything that can be configured with Cache XML
* A separate namespace for Spring Data Repository support
* The XML namespace provides support for everything that can be configured natively with Cache XML
* A separate XML namespace has been created for Spring Data Repository support
Enhancements
* [SGF-53] - Add "enable-gateway" to replicated and partitioned region namespace config
* [SGF-75] - Ability to define gateways in the Spring Gemfire namespace
* [SGF-76] - Disk store should be its own bean
* [SGF-79] - Missing gateway attributes for regions
* [SGF-86] - Make instance variables protected in CacheFactoryBean
* [SGF-95] - Add namespace support for subregions
* [SGF-98] - Provide namespace support for all cache and region properties
* [SGF-53] - Add "enable-gateway" to replicated and partitioned region namespace config
* [SGF-75] - Ability to define gateways in the Spring GemFire namespace
* [SGF-76] - Disk store should be its own bean
* [SGF-79] - Missing gateway attributes for regions
* [SGF-86] - Make instance variables protected in CacheFactoryBean
* [SGF-95] - Add namespace support for subregions
* [SGF-98] - Provide namespace support for all cache and region properties
* [SGF-102] - Add support for JavaConfig for repositories
* [SGF-103] - Replace xsd:id type with xsd:string to support Spring environment profiles
* [SGF-104] - The repository deleteAll() method only works for replicated regions
* [SGF-109] - Separate repository support into its own namespace
* [SGF-111] - Change default bean names from hyphenated to camel case to support @Autowired
* [SGF-112] - Repositories should reject PagingAndSorting and Pageable parameters
* [SGF-113] - Repositories should support single entities returned from a query method
* [SGF-115] - Add support for 'Like', 'StartsWith','EndsWith', and 'Containing' repository queries
Bug Fixes
* [SGF-85] - Pdx disk store does not work when trying to references a disk store created in cache.xml
* [SGF-89] - Continuous query container fails when implementing the ContinuousQueryListener interface
* [SGF-101] - The repository deleteAll() method only works for replicated regions
Changes in version 1.1.2.RELEASE (2012-07-04)
---------------------------------------------

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

@@ -1,5 +1,5 @@
SPRING GEMFIRE INTEGRATION
--------------------------
SPRING DATA GEMFIRE
-------------------
http://www.springsource.org/spring-gemfire
1. INTRODUCTION
@@ -13,15 +13,12 @@ build Spring-powered highly scalable applications using vFabric GemFire as distr
This release comes with complete reference documentation. For further
details, consult the provided javadoc for specific packages and classes.
3. DISTRIBUTION JAR FILES
The Spring Data GemFire jars files can be found in the 'dist' directory.
4. GETTING STARTED
3. GETTING STARTED
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
VMWare vFabric GemFire Homepage: http://www.vmware.com/products/application-platform/vfabric-gemfire/overview.html
Spring Data GemFire Homepage : http://www.springsource.org/spring-gemfire
VMware vFabric GemFire Documentation: http://www.vmware.com/products/application-platform/vfabric-gemfire/overview.html
VMware vFabric GemFire product page: http://www.vmware.com/products/application-platform/vfabric-gemfire

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

@@ -1,9 +1,16 @@
<?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>
<title>Spring Data GemFire Schema</title>
<para>Spring GemFire Schema</para>
<programlisting language="xml"><xi:include href="../../../src/main/resources/org/springframework/data/gemfire/config/spring-gemfire-1.1.xsd" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude">
<para>Spring Data GemFire Core Schema (gfe)</para>
<programlisting language="xml"><xi:include href="../../../src/main/resources/org/springframework/data/gemfire/config/spring-gemfire-1.2.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>
<para>Spring Data GemFire Data Access Schema (gfe-data)</para>
<programlisting language="xml"><xi:include href="../../../src/main/resources/org/springframework/data/gemfire/config/spring-data-gemfire-1.2.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>

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

@@ -55,18 +55,18 @@
</part>
<part id="reference">
<title>Reference Documentation</title>
<title>Reference Guide</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/mapping.xml"/>
<!--
<!--
<xi:include href="https://github.com/SpringSource/spring-data-commons/raw/master/src/docbkx/repositories.xml">
<xi:fallback href="../../../../../../spring-data-commons/src/docbkx/repositories.xml" />
</xi:include>
-->
-->
<xi:include href="reference/repositories.xml"/>
<xi:include href="reference/samples.xml"/>
</part>

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

@@ -1,20 +1,14 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE part PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<part>
<chapter xml:id="intro-introduction" xmlns="http://docbook.org/ns/docbook" version="5.0">
<title>Introduction</title>
<chapter>
<section>
<para>This reference guide for the Spring Data GemFire project (SGF)
explains how to use Spring framework to configure and develop
applications with vFabric GemFire. It presents the basic concepts,
semantics and provides numerous examples to help you get started.
<para>This reference guide for the Spring Data GemFire project explains how to use Spring framework to
configure and develop applications with vFabric GemFire.
It presents the basic concepts, semantics and provides numerous examples to help you get started.
</para>
<note>Spring Data GemFire started as a top level Spring project called
Spring GemFire and has sinced moved under the Spring Data umbrella
project and has been renamed accordingly.</note>
</section>
</chapter>
</part>
Spring GemFire (SGF) and has since moved under the Spring Data umbrella project
and has been renamed accordingly.</note>
</chapter>

11
docs/src/reference/docbook/introduction/new-features.xml
View File

@@ -10,25 +10,26 @@ it is now a component of the <ulink url="http://www.springsource.org/spring-data
<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.
Full support for GemFire configuration via the <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
WAN Gateway support for both GemFire 6.6.x. See <xref linkend="bootstrap:gateway"/>
</para>
</listitem>
<listitem><para>
Spring Data Repository support with a dedicated namespace: <emphasis>gfe-data</emphasis>
Spring Data Repository support with a dedicated namespace, <emphasis>gfe-data</emphasis>. See <xref linkend="gemfire-repositories"/>
</para>
</listitem>
<listitem><para>
Namespace support for registering GemFire functions
Namespace support for registering GemFire functions. See <xref linkend="bootstrap:function"/>
</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.
and other components that support persistent backup. See <xref linkend="bootstrap-diskstore"/>
<caution>The <literal>&lt;*-region&gt;</literal> elements no longer allow a nested <literal>&lt;disk-store&gt;</literal>
</caution>
</para>

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

@@ -1,7 +1,7 @@
<chapter xml:id="requirements" xmlns="http://docbook.org/ns/docbook" version="5.0">
<title>Requirements</title>
<para>Spring Data GemFire requires JDK level 5.0 and above, Spring
<para>Spring Data GemFire requires JDK level 6.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>

18
docs/src/reference/docbook/links.xml
View File

@@ -9,15 +9,19 @@
<itemizedlist>
<listitem>
<para>Spring Data GemFire Home Page</para>
<ulink url="http://www.springsource.org/spring-gemfire">Spring Data GemFire Home Page</ulink>
</listitem>
<listitem>
<ulink url="http://www.vmware.com/products/application-platform/vfabric-gemfire/overview.html">vFabric GemFire Home Page</ulink>
</listitem>
<listitem>
<ulink url="https://www.vmware.com/support/pubs/vfabric-gemfire.html">vFabric GemFire Documentation</ulink>
</listitem>
<listitem>
<para>SpringSource Blog</para>
<ulink url="http://communities.vmware.com/community/vmtn/appplatform/vfabric_gemfire">GemFire Community Home Page</ulink>
</listitem>
<listitem>
<ulink url="http://forum.springsource.org/forumdisplay.php?77-GemFire">Spring Data GemFire Forum</ulink>
</listitem>
</itemizedlist>
<para>New para</para>
<para/>
</chapter>

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

File diff suppressed because it is too large Load Diff

312
docs/src/reference/docbook/reference/cache.xml Normal file
View File

@@ -0,0 +1,312 @@
<?xml version="1.0" encoding="UTF-8"?>
<section id="bootstrap:cache" version="5.0"
xmlns="http://docbook.org/ns/docbook"
xmlns:ns52="http://www.w3.org/1998/Math/MathML"
xmlns:ns5="http://www.w3.org/1999/xlink"
xmlns:ns4="http://www.w3.org/2000/svg"
xmlns:ns3="http://www.w3.org/1999/xhtml"
xmlns:ns="http://docbook.org/ns/docbook">
<title>Configuring the GemFire Cache</title>
<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
per classloader to be technically correct). In most cases the cache is
created once.</para>
<note>This section describes the creation and configuration of a full cache
member, appropriate for peer to peer cache topologies and cache servers. A
full cache is also commonly used for standalone applications, integration
tests and proofs of concept. In a typical production system, most
application processes will act as cache clients and will create a
ClientCache instance instead. This is described in the sections <xref
linkend="bootstrap:cache:client"/> and <xref
linkend="bootstrap:region:client"/></note>
<para>A cache with default configuration can be created with a very simple
declaration:</para>
<programlisting language="xml">&lt;gfe:cache/&gt;</programlisting>
<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">&lt;gfe:cache id="my-cache"/&gt;</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">&lt;gfe:cache id="cache-with-xml" cache-xml-location="classpath:cache.xml"/&gt;</programlisting>
<para>In this example, if the cache needs to be created, it will use the
file named <literal>cache.xml</literal> located in the classpath
root.</para>
<note>
<para>Note that the configuration makes use of Spring's <ulink
url="http://static.springsource.org/spring/docs/current/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 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 <ulink
url="http://pubs.vmware.com/vfabric51/topic/com.vmware.vfabric.gemfire.6.6/reference/topics/gemfire_properties.html">properties</ulink>
using any of Spring's common properties support features. For example, one
can use the <literal>properties</literal> element defined in the
<literal>util</literal> namespace to define properties directly or load
properties from properties files. The latter is recommended for
externalizing environment specific settings outside the application
configuration:</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: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"&gt;
&lt;gfe:cache properties-ref="props"/&gt;
&lt;util:properties id="props" location="file:/vfabric/gemfire/gemfire.properties"/&gt;
&lt;/beans&gt;</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>
<section id="bootstrap:cache:advanced">
<title>Advanced Cache Configuration</title>
<para>For advanced cache configuration, the <literal>cache</literal>
element provides a number of configuration options exposed as attributes
or child elements</para>
<programlisting language="xml"><co id="gfe#cache-element#attributes"/>
&lt;gfe:cache
copy-on-read="true"
critical-heap-percentage="70"
eviction-heap-percentage="60"
lock-lease="120"
lock-timeout="60"
pdx-serializer="myPdxSerializer"
pdx-disk-store="diskStore"
pdx-ignore-unread-fields="true"
pdx-persistent="true"
pdx-read-serialized="false"
message-sync-interval="1"
search-timeout="300"
&gt;
<co id="gfe#transaction#listener"/>&lt;gfe:transaction-listener ref="myTransactionListener"/&gt;
<co id="gfe#transaction#writer"/>&lt;gfe:transaction-writer&gt;
&lt;bean class="org.springframework.data.gemfire.example.TransactionListener"/&gt;
&lt;/gfe:transaction-writer&gt;
<co id="gfe#dynamic#region"/>&lt;gfe:dynamic-region-factory/&gt;
<co id="gfe#jndi#binding"/>&lt;gfe:jndi-binding jndi-name="myDataSource" type="ManagedDataSource"/&gt;
&lt;/gfe:cache&gt;
</programlisting>
<calloutlist>
<callout arearefs="gfe#cache-element#attributes">
<para>Various cache options are supported by attributes. For further
information regarding anything shown in this example, 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> callback
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></para>
</callout>
<callout arearefs="gfe#transaction#writer">
<para>An example of a <interfacename>TransactionWriter</interfacename>
callback 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#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 external datasource in a
GemFire transaction</para>
</callout>
</calloutlist>
<note>The <literal xmlns="">use-bean-factory-locator</literal> attribute
(not shown) deserves a mention. The factory bean responsible for creating
the cache uses an internal Spring type called a <interfacename
xmlns="">BeanFactoryLocator</interfacename> to enable user classes
declared in GemFire's native <literal xmlns="">cache.xml</literal> to be
registered as Spring beans. The <interfacename
xmlns="">BeanFactoryLocator</interfacename> implementation also permits
only one bean definition for a cache with a given id. In certain
situations, such as running JUnit integration tests from within Eclipse,
it is necessary to disable the <interfacename
xmlns="">BeanFactoryLocator</interfacename> by setting this value to
<literal xmlns="">false</literal> to prevent an exception. This exception
may also arise during JUnit tests running from a build script. In this
case the test runner should be configured to fork a new JVM for each test
(in maven, set <literal
xmlns="">&lt;forkmode&gt;always&lt;/forkmode&gt;</literal>) . Generally
there is no harm in setting this value to false.</note>
<section>
<title>Enabling PDX Serialization</title>
<para>The example above includes a number of attributes related to
GemGire's enhanced serialization framework, PDX. While a complete
discussion of PDX is beyond the scope of this reference guide, it is
important to note that PDX is enabled by registering a PDX serializer
which is done via the <literal>pdx-serializer</literal> attribute.
GemFire provides an implementation class <classname>
com.gemstone.gemfire.pdx.ReflectionBasedAutoSerializer</classname>,
however it is common for developers to provide their own implementation.
The value of the attribute is simply a reference to a Spring bean that
implements the required interface. More information on serialization support can be found in <xref linkend="serialization"/> </para>
<para/>
</section>
</section>
<section id="bootstrap:cache:server">
<title>Configuring a GemFire Cache Server</title>
<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">&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:gfe="http://www.springframework.org/schema/gemfire"
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"&gt;
&lt;gfe:cache /&gt;
&lt;!-- Advanced example depicting various cache server configuration options --&gt;
&lt;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"&gt;
&lt;gfe:subscription-config eviction-type="ENTRY" capacity="1000" disk-store="file://${java.io.tmpdir}"/&gt;
&lt;/gfe:cache-server&gt;
&lt;context:property-placeholder location="classpath:cache-server.properties"/&gt;
&lt;/beans&gt;</programlisting>
<para>The configuration above illustrates the
<literal>cache-server</literal> element and the many options
available.</para>
<note>
<para>Rather than hard-coding the port, this configuration uses Spring's
<literal>
<ulink
url="http://static.springsource.org/spring/docs/current/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/current/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/current/spring-framework-reference/html/new-in-3.0.html#new-feature-el">SpEL</ulink>
and the <ulink
url="http://static.springsource.org/spring/docs/current/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, listeners, writers or
instantiators defined declaratively to be fully initialized and
registered before the server starts accepting connections. Keep this in
mind when programmatically configuring these items 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 Client Cache</title>
<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
<classname>org.springframework.data.gemfire.clientClientCacheFactoryBean</classname>.</para>
<programlisting language="xml">&lt;beans&gt;
&lt;gfe:client-cache /&gt;
&lt;/beans&gt;</programlisting>
<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> 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">&lt;beans&gt;
&lt;gfe:client-cache id="simple" pool-name="my-pool"/&gt;
&lt;gfe:pool id="my-pool" subscription-enabled="true"&gt;
&lt;gfe:locator host="${locatorHost}" port="${locatorPort}"/&gt;
&lt;/gfe:pool&gt;
&lt;/beans&gt;</programlisting>
</section>
<para>Client side configuration is covered in more detail in <xref
linkend="bootstrap:client"/>.</para>
</section>

4
docs/src/reference/docbook/reference/client.xml Normal file
View File

@@ -0,0 +1,4 @@
<?xml version="1.0" encoding="UTF-8"?>
<section id="bootstrap:client" 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">
<title>Cache Client Configuration</title>
</section>

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

@@ -9,8 +9,8 @@
Spring GemFire provides dedicated support for CQs through the <literal>org.springframework.data.gemfire.listener</literal> package and
its <emphasis>listener container</emphasis>; very similar in functionality
and naming to the JMS integration in Spring Framework; in fact, users familiar with the JMS support in Spring, should
feel right at home. Basically SGF allows methods on POJOs to become end-points for CQ - simply define the query and indicate the method
that should be notified when there is a match - SGF takes care of the rest. This of Java EE's message-driven bean style, but without any
feel right at home. Basically Spring Data GemFire allows methods on POJOs to become end-points for CQ - simply define the query and indicate the method
that should be notified when there is a match - Spring Data GemFire takes care of the rest. This is similar Java EE's message-driven bean style, but without any
requirement for base class or interface implementations, based on GemFire.</para>
<note>
@@ -21,7 +21,7 @@
<section id="apis:cq-container:containers">
<title>Continuous Query Listener Container</title>
<para>SGF simplifies the creation, registration, life-cycle and dispatch of CQs by taking care of the infrastructure around them through
<para>Spring Data GemFire simplifies the creation, registration, life-cycle and dispatch of CQs by taking care of the infrastructure around them through
<classname>ContinuousQueryListenerContainer</classname> which does all the heavy lifting on behalf of the user -
users familiar with EJB and JMS should find the concepts familiar as it is designed as close as possible to the
support in Spring Framework and its message-driven POJOs (MDPs)</para>
@@ -29,13 +29,13 @@
<para><classname>ContinuousQueryListenerContainer</classname> acts as an event (or message) listener container; it is used to receive the events
from the registered CQs and drive the POJOs that are injected into it. The listener container is responsible for all threading of message
reception and dispatches into the listener for processing. It acts as the intermediary between an EDP (Event Driven POJO) and the event provider
and takes care of creation and registration of CQs (to receive events), resource acquisition and release, exception conversion and suchlike.
and takes care of creation and registration of CQs (to receive events), resource acquisition and release, exception conversion and the like.
This allows you as an application developer to write the (possibly complex) business logic associated with receiving an event (and reacting to it),
and delegates boilerplate GemFire infrastructure concerns to the framework.
</para>
<para>The container is fully customizable - one can chose either to use the CQ thread to perform the dispatch (synchronous delivery) or a new thread
(from an existing pool for examples) for an asynch approach by defining the suitable <interfacename>java.util.concurrent.Executor</interfacename>
(from an existing pool for examples) for an asynchronous approach by defining the suitable <interfacename>java.util.concurrent.Executor</interfacename>
(or Spring's <interfacename>TaskExecutor</interfacename>). Depending on the load, the number of listeners or the runtime
environment, one should change or tweak the executor to better serve her needs - in particular in managed environments (such as app servers), it is
highly recommended to pick a a proper <interfacename>TaskExecutor</interfacename> to take advantage of its runtime.</para>
@@ -45,9 +45,9 @@
<title>The <classname>ContinuousQueryListenerAdapter</classname> and <interfacename>ContinuousQueryListener</interfacename></title>
<para>The <classname>ContinuousQueryListenerAdapter</classname> class is the
final component in SGF CQ support: in a nutshell, it allows you to expose almost <emphasis>any</emphasis> class
final component in Spring Data GemFire CQ support: in a nutshell, it allows you to expose almost <emphasis>any</emphasis> class
as a EDP (there are of course some constraints) - it implements <interfacename>ContinuousQueryListener</interfacename>, a simpler listener interface
similar to GemFire <ulink url="http://www.gemstone.com/docs/6.5.1/product/docs/japi/com/gemstone/gemfire/cache/query/CqListener.html">CqListener</ulink>.</para>
similar to GemFire <ulink url="https://www.vmware.com/support/developer/vfabric-gemfire/663-api/com/gemstone/gemfire/cache/query/CqListener.html">CqListener</ulink>.</para>
<para>Consider the following interface definition. Notice the
various event handling methods and their parameters:</para>
@@ -102,7 +102,7 @@
a name for the resulting continuous query (useful for monitoring) but also the name of the method (the default is <literal>handleEvent</literal>). The specified method can have various
argument types, the <interfacename>EventDelegate</interfacename> interface lists the allowed types.</note>
<para>The example above uses the SGF namespace to declare the event listener container and automatically register the POJOs as listeners. The full blown, <emphasis>beans</emphasis> definition
<para>The example above uses the Spring Data GemFire namespace to declare the event listener container and automatically register the listeners. The full blown, <emphasis>beans</emphasis> definition
is displayed below:</para>
<programlisting language="xml"><lineannotation>&lt;!-- this is the Event Driven POJO (MDP) --&gt;</lineannotation>

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

@@ -22,25 +22,21 @@
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 AOP by defining a <classname>PersistenceExceptionTranslationPostProcessor</classname> bean.
The same exception translation functionality is enabled when using GemFire
as long as at least a <classname>CacheFactoryBean</classname> is declared, e.g., using a <literal>&lt;gfe:cache/&gt;</literal> declaration)
as it 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>
<title>GemfireTemplate</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
<para>As with many other high-level abstractions provided by the Spring projects, Spring Data GemFire provides a
<emphasis>template</emphasis> that simplifies GemFire data access. The class provides several <emphasis>one-line</emphasis>
methods, for common region 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>
having to deal with GemFire checked exceptions for example through the <interfacename>GemfireCallback</interfacename>.</para>
<para>The template class requires a GemFire
<interfacename>Region</interfacename> instance and once configured is
@@ -65,9 +61,9 @@
}
});</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>For accessing the full power of the GemFire query language, one can use the <methodname>find</methodname> and <methodname>findUnique</methodname> which, as opposed to the
<methodname>query</methodname> method, can execute queries across multiple regions, execute projections, and the like. The <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>
@@ -75,9 +71,8 @@
<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>
<ulink url="http://static.springsource.org/spring/docs/current/spring-framework-reference/htmlsingle/spring-framework-reference.html#cache">cache abstraction</ulink>.
To use GemFire as a backing implementation, simply add <classname>GemfireCacheManager</classname> 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"
@@ -102,25 +97,17 @@
<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>
url="http://static.springsource.org/spring/docs/current/spring-framework-reference/htmlsingle/spring-framework-reference.html#transaction">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>
url="http://static.springsource.org/spring/docs/current/spring-framework-reference/htmlsingle/spring-framework-reference.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>
<para>For GemFire, Spring Data GemFire provides a dedicated, per-cache, transaction manager that once declared, allows region operations to be 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>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>
<programlisting language="xml">&lt;bean id="tx-manager" class="org.springframework.data.gemfire.GemfireTransactionManager" p:cache-ref="cache"/&gt;</programlisting>
name <literal>gemfireCache</literal>. As with the other Spring Data GemFire 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>gemfireTransactionManager</literal>.</note>
<para>Note that currently GemFire supports optimistic transactions with
<emphasis>read committed</emphasis> isolation. Furthermore, to guarantee
@@ -129,11 +116,11 @@
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
each time a read is performed. This behavior 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>
url="https://www.vmware.com/support/developer/vfabric-gemfire/663-api/com/gemstone/gemfire/cache/CacheTransactionManager.html">documentation</ulink>.</para>
</section>
<xi:include href="cq-container.xml"/>
@@ -143,21 +130,21 @@
<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
be declared as part of the configuration. Usually these objects are
<interfacename>CacheLoader</interfacename>s or other pluggable callback components
supported by GemFire. Using native GemFire configuration, each user 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
<para>In this section we describe how you can configure these 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>
DataSources or other collaboration objects.</para>
<para>However, if you are starting on a green-field project, it is
<para>However, if you are starting 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
@@ -168,11 +155,11 @@
<title>Eliminate <interfacename>Declarable</interfacename>
components</title>
<para>One can configure custom types entirely inside through Spring as
<para>One can configure custom types entirely 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
interface and also benefits from all the features of the Spring IoC
container (not just dependency injection but also life-cycle
and instance management).</para>
</sidebar>
@@ -189,10 +176,10 @@
&lt;/cache-loader&gt;</programlisting>
<para>To simplify the task of parsing, converting the parameters and
initializing the object, SGF offers a base class
initializing the object, Spring Data GemFire 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
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
@@ -204,17 +191,16 @@
<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>
instantiated and used as is. In other words, there is no easy way
to manage object creation outside GemFire.
</para>
</sidebar>
<section id="apis:declarable:template-wiring">
<title>Configuration using <emphasis>template</emphasis>
definitions</title>
<para>When used <classname>WiringDeclarableSupport</classname> tries to
<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
@@ -251,9 +237,8 @@
&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
the id/name <literal>com.company.app.DBLoader</literal> was 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>
@@ -292,14 +277,14 @@
<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>
url="http://static.springsource.org/spring/docs/current/spring-framework-reference/htmlsingle/spring-framework-reference.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>
url="http://static.springsource.org/spring/docs/current/spring-framework-reference/htmlsingle/spring-framework-reference.html#beans-annotation-config">chapter</ulink>
in the Spring documentation for more information on the supported
annotations and enabling factors.</para>

38
docs/src/reference/docbook/reference/diskstore.xml Normal file
View File

@@ -0,0 +1,38 @@
<?xml version="1.0" encoding="UTF-8"?>
<section version="5.0" xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:svg="http://www.w3.org/2000/svg"
xmlns:m="http://www.w3.org/1998/Math/MathML"
xmlns:html="http://www.w3.org/1999/xhtml"
xmlns:db="http://docbook.org/ns/docbook"
id="bootstrap-diskstore">
<title>Configuring a Disk Store</title>
<para>As of Release 1.2.0, Spring Data GemFire supports disk store
configuration via a top level <literal>disk-store</literal> element.</para>
<note>
<para>Prior to Release 1.2.0,
<literal>disk-store</literal> was a child element of
<literal>*-region</literal>. If you have regions configured with disk
storage using a prior release of Spring Data GemFire and want to upgrade
to the latest release, move the disk-store element to the top level,
assign an id and use the region's <literal>disk-store-ref</literal>
attribute. Also, <literal>disk-synchronous</literal> is now a region level
attribute. </para>
</note>
<programlisting language="xml" xml:lang="xml">&lt;gfe:disk-store id="diskStore1" queue-size="50" auto-compact="true"
max-oplog-size="10" time-interval="9999"&gt;
&lt;gfe:disk-dir location="/gemfire/store1/" max-size="20"/&gt;
&lt;gfe:disk-dir location="/gemfire/store2/" max-size="20"/&gt;
&lt;/gfe:disk-store&gt;</programlisting>
<para>Disk stores are used by regions for file system persistent backup or
overflow storage of evicted entries, and persistent backup of WAN gateways.
Note that multiple components may share the same disk store. Also multiple
directories may be defined for a single disk store. Please refer to the
GemFire documentation for an explanation of the configuration
options.</para>
</section>

30
docs/src/reference/docbook/reference/function.xml Normal file
View File

@@ -0,0 +1,30 @@
<?xml version="1.0" encoding="UTF-8"?>
<section version="5.0" id="bootstrap:function"
xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:svg="http://www.w3.org/2000/svg"
xmlns:m="http://www.w3.org/1998/Math/MathML"
xmlns:html="http://www.w3.org/1999/xhtml"
xmlns:db="http://docbook.org/ns/docbook">
<title>Configuring GemFire's Function Service</title>
<para>As of Release 1.2.0, Spring Data GemFire provides namespace support
for registering GemFire <interfacename>Function</interfacename>s for remote
function execution. Please refer to the GemFire documentation for more
information on the function execution framework. Functions are declared as
Spring beans and must implement the
<interfacename>com.gemstone.gemfire.cache.execute.Function</interfacename>
interface or extend
<interfacename>com.gemstone.gemfire.cache.execute.FunctionAdapter</interfacename>.
The namespace uses a familiar pattern to declare functions:</para>
<programlisting language="xml">&lt;gfe:function-service&gt;
&lt;gfe:function&gt;
&lt;bean class="com.company.example.Function1"/&gt;
&lt;ref bean="function2"/&gt;
&lt;/gfe:function&gt;
&lt;/gfe:function-service&gt;
&lt;bean id="function2" class="com.company.example.Function2"/&gt;</programlisting>
</section>

48
docs/src/reference/docbook/reference/gateway.xml Normal file
View File

@@ -0,0 +1,48 @@
<?xml version="1.0" encoding="UTF-8"?>
<section version="5.0" id="bootstrap:gateway"
xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:svg="http://www.w3.org/2000/svg"
xmlns:m="http://www.w3.org/1998/Math/MathML"
xmlns:html="http://www.w3.org/1999/xhtml"
xmlns:db="http://docbook.org/ns/docbook">
<title>Configuring WAN Gateways</title>
<para>WAN gateways provide a way to synchronize GemFire distributed systems
across geographic distributed areas. As of Release 1.2.0, Spring Data
GemFire provides namespace support for configuring WAN gateways as
illustrated in the following example:</para>
<programlisting language="xml">&lt;gfe:cache/&gt;
&lt;gfe:replicated-region id="region-with-gateway" enable-gateway="true" hub-id="gateway-hub"/&gt;
&lt;gfe:gateway-hub id="gateway-hub" manual-start="true"&gt;
&lt;gfe:gateway gateway-id="gateway"&gt;
&lt;gfe:gateway-listener&gt;
&lt;bean class="com.company.example.MyGatewayListener"/&gt;
&lt;/gfe:gateway-listener&gt;
&lt;gfe:gateway-queue maximum-queue-memory="5" batch-size="3"
batch-time-interval="10" /&gt;
&lt;/gfe:gateway&gt;
&lt;gfe:gateway gateway-id="gateway2"&gt;
&lt;gfe:gateway-endpoint port="1234" host="host1" endpoint-id="endpoint1"/&gt;
&lt;gfe:gateway-endpoint port="2345" host="host2" endpoint-id="endpoint2"/&gt;
&lt;/gfe:gateway&gt;
&lt;/gfe:gateway-hub&gt;</programlisting>
<para>A region may synchronize all or part of its contents to a gateway hub
used to access one or more remote systems. The region must set
<literal>enable-gateway</literal> to <literal>true</literal> and specify the
<literal>hub-id</literal>. </para>
<para><note>
<para>If just a hub-id is specified, Spring Data GemFire automatically
assumes that the gateway should be enabled. </para>
</note></para>
<para>Please refer to the GemFire product document for a detailed
explanation of all the configuration options.</para>
</section>

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

@@ -1,10 +1,9 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE part PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<part>
<title>Reference Guide</title>
<partintro>
<chapter version="5.0" xml:id="ref-introduction"
xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
>
<title>Document structure</title>
<para>The following chapters explain the core functionality offered by
@@ -12,7 +11,8 @@
<para><xref linkend="bootstrap"/> describes the configuration support
provided for bootstrapping, initializing, configuring, and accessing
GemFire caches, regions and distributed system components.</para>
GemFire caches, cache servers, regions, and related distributed system
components</para>
<para><xref linkend="apis"/> explains the integration between the GemFire
APIs and the various data access features available in Spring, such as
@@ -30,10 +30,5 @@
<para><xref linkend="samples"/> describes the samples provided with the
distribution to illustrate the various features available in Spring
GemFire.</para>
<!--
<para><xref linkend="testing"/> showcases various ways of testing GemFire inside
Spring framework.</para>
-->
</partintro>
</part>
</chapter>

12
docs/src/reference/docbook/reference/mapping.xml
View File

@@ -11,12 +11,12 @@
<section xml:id="mapping.entities">
<title>Entity mapping</title>
<para>Spring Data Gemfire provides support to map entities to be stored in
a Gemfire grid. The mapping metadata is define by using annotations at the
<para>Spring Data GemFire provides support to map entities to be stored in
a GemFire grid. The mapping metadata is define by using annotations at the
domain classes just like this: </para>
<example>
<title>Mapping a domain class to Gemfire</title>
<title>Mapping a domain class to GemFire</title>
<programlisting language="java">@Region("myRegion")
public class Person {
@@ -41,7 +41,7 @@ public class Person {
are stored in. The <interfacename>@Id</interfacename> annotation can be
used to annotate the property that shall be used as cache key. The
<interfacename>@PersistenceConstructor</interfacename> annotation actually
helps disambiguing multiple potentially available constructors taking
helps disambiguating multiple potentially available constructors taking
parameters and explicitly marking the one annotated as the one to be used
to create entities. With none or only a single constructor you can omit
the annotation.</para>
@@ -50,7 +50,7 @@ public class Person {
<section xml:id="mapping.pdx-serializer">
<title>Mapping PDX serializer</title>
<para>Spring Data Gemfire provides a custom
<para>Spring Data GemFire provides a custom
<interfacename>PDXSerializer</interfacename> implementation that uses the
mapping information to customize entity serialization. Beyond that it
allows customizing the entity instantiation by using the Spring Data
@@ -82,4 +82,4 @@ public class Person {
<code>lastname</code> will be the Spring bean with name
<code>bean</code>.</para>
</section>
</chapter>
</chapter>

850
docs/src/reference/docbook/reference/region.xml Normal file
View File

@@ -0,0 +1,850 @@
<?xml version="1.0" encoding="UTF-8"?>
<section id="bootstrap:region" version="5.0"
xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:ns5="http://www.w3.org/1998/Math/MathML"
xmlns:ns4="http://www.w3.org/2000/svg"
xmlns:ns3="http://www.w3.org/1999/xhtml"
xmlns:ns="http://docbook.org/ns/docbook">
<title>Configuring a GemFire Region</title>
<para xmlns="">A region is required to store and retrieve data from the
cache. <interfacename>Region</interfacename> is an interface extends
<interfacename>java.util.map</interfacename> used to perform basic data
access using familiar key-value semantics. The
<interfacename>Region</interfacename> interface is wired into classes that
require it so the actual region type is decoupled from the programming model
. Typically each region is associated with one domain object, similar to a
table in a relational database.</para>
<para>GemFire implements the following types of regions:</para>
<itemizedlist>
<listitem>
<para><emphasis>Replicated</emphasis> - Data is replicated across all
cache members that define the region. This provides very high read
performance but writes take longer to perform the replication.</para>
</listitem>
<listitem>
<para><emphasis>Partioned</emphasis> - Data is partitioned into buckets
among cache members that define the region. This provides high read and
write performance and is suitable for very large data sets that are too
big for a single node.</para>
</listitem>
<listitem>
<para><emphasis>Local</emphasis> - Data only exists on the local
node.</para>
</listitem>
<listitem>
<para><emphasis>Client</emphasis> - Technically a client region is a
local region that acts as a proxy to a replicated or partitioned region
hosted on cache servers. It may hold data created or fetched locally,
alternately it can be empty. Local updates are synchronized to the cache
server. Also, a client region may subscribe to events in order to stay
synchronized with changes originating from remote processes that access
the same region.</para>
</listitem>
</itemizedlist>
<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://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 externally configured Region</title>
<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">&lt;gfe:lookup-region id="region-bean" name="orders"/&gt;</programlisting>
<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">&lt;!-- lookup for a region called 'orders' --&gt;
&lt;gfe:lookup-region id="orders"/&gt;</programlisting>
<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 naming convention (<literal>gemfireCache</literal>) was used.
Alternately, one can reference the cache bean through the
<literal>cache-ref</literal> attribute:</para>
<programlisting language="xml">&lt;gfe:cache id="cache"/&gt;
&lt;gfe:lookup-region id="region-bean" name="orders" cache-ref="cache"/&gt;</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:overview">
<title>Configuring Regions</title>
<para>Spring Data GemFire provides comprehensive support for configuring
any type of GemFire Region via the following elements: <itemizedlist>
<listitem>
<para>Local Region <literal>&lt;local-region&gt;</literal></para>
</listitem>
<listitem>
<para>Replicated Region
<literal>&lt;replicated-region&gt;</literal></para>
</listitem>
<listitem>
<para>Partitioned Region
<literal>&lt;partitioned-region&gt;</literal></para>
</listitem>
<listitem>
<para>Client Region <literal>&lt;client-region&gt;</literal></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 various
region types:
<table
id="bootstrap:region:common:attributes:table">
<title>Common Region Attributes</title>
<tgroup cols="3">
<colspec colwidth="1*"/>
<colspec colwidth="2*"/>
<colspec colwidth="2*"/>
<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.</entry>
</row>
<row>
<entry>hub-id</entry>
<entry spanname="values">
<emphasis>The name of the Gateway Hub</emphasis>
</entry>
<entry spanname="description">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">
&lt;gfe:replicated-region id="region-with-listeners"&gt;
&lt;gfe:cache-listener&gt;
&lt;!-- nested cache listener reference --&gt;
&lt;ref bean="c-listener"/&gt;
&lt;!-- nested cache listener declaration --&gt;
&lt;bean class="some.pkg.AnotherSimpleCacheListener"/&gt;
&lt;/gfe:cache-listener&gt;
&lt;bean id="c-listener" class="some.pkg.SimpleCacheListener"/&gt;
&lt;/gfe:replicated-region&gt;
</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">&lt;beans&gt;
&lt;gfe:replicated-region id="region-with-one listener"&gt;
&lt;gfe:cache-listener ref="c-listener"/&gt;
&lt;/gfe:replicated-region&gt;
&lt;bean id="c-listener" class="some.pkg.SimpleCacheListener"/&gt;
&lt;/beans&gt;
</programlisting></para>
<note>
<title>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 a
callback interface to be implemented in order to invoke custom code in
response to cache or region events. Using Spring's IoC container, the
implementation is a standard Spring bean. In order to simplify the
configuration, the schema allows a single occurrence of the
<literal>cache-listener</literal> element, but it may contain nested
bean references and inner bean definitions in any combination if
multiple instances are permitted. The convention is to use the
singular form (i.e., <literal>cache-listener</literal> vs
<literal>cache-listeners</literal>) reflecting that the most common
scenario will in fact be a single instance. We have already seen
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. The subregion's name
attribute is the simple name. The above example might be configured as:
<programlisting language="xml">&lt;beans&gt;
&lt;gfe:replicated-region name="Customer"&gt;
&lt;gfe:replicated-region name="Address"/&gt;
&lt;/gfe:replicated-region&gt;
&lt;gfe:replicated-region name="Employee"&gt;
&lt;gfe:replicated-region name="Address"/&gt;
&lt;/gfe:replicated-region&gt;
&lt;/beans&gt;</programlisting>Note that the <literal>
<literal>id</literal>
</literal> attribute is not permitted for a subregion. The subregions
will be created with bean names <emphasis>/Customer/Address</emphasis>
and <emphasis>/Employee/Address</emphasis>, respectively. So they may be
injected using the full path name into other beans that use them, such
as <classname>GemfireTemplate</classname>. The full path should also be
used in OQL query strings.</para>
</section>
</section>
<section id="bootstrap:region:persistence">
<title>Data Persistence</title>
<para>Regions can be made persistent. 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>
<para>With Spring Data GemFire, to enable persistence, simply set the
<literal>persistent</literal> attribute to true:</para>
<programlisting language="xml">&lt;gfe:partitioned-region id="persitent-partition" persistent="true"/&gt;</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.
The diskstore is referenced using the disk-store-ref attribute.
Additionally, the region may perform disk writes synchronously or
asynchronously:</para>
<programlisting language="xml">&lt;gfe:partitioned-region id="persitent-partition" persistent="true" disk-store-ref="myDiskStore" disk-synchronous="true"/&gt;</programlisting>
<para>This is discussed further in <xref
linkend="bootstrap-diskstore"/></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 to 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>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>
<programlisting language="xml">&lt;gfe:partitioned-region id="overflow-partition"&gt;
&lt;gfe:eviction type="MEMORY_SIZE" threshold="512" action="OVERFLOW_TO_DISK"/&gt;
&lt;/gfe:partitioned-region&gt;</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://pubs.vmware.com/vfabric51/topic/com.vmware.vfabric.gemfire.6.6/developing/eviction/how_eviction_works.html">this</ulink>
page).</para>
</section>
<section><title>Data Expiration</title>GemFire allows you to control how
long entries exist in the cache. Eviction is driven by elapsed time, as
opposed to eviction which is driven by memory usage. Once an entry expires
it may no longer be accessed from the cache. GemFire supports the following
expiration types: <itemizedlist>
<listitem>
<para><emphasis>Time to live (TTL)</emphasis> - The amount of time, in
seconds, the object may remain in the cache after the last creation or
update. For entries, the counter is set to zero for create and put
operations. Region counters are reset when the region is created and
when an entry has its counter reset.</para>
</listitem>
<listitem>
<para><emphasis>Idle timeout</emphasis> - The amount of time, in
seconds, the object may remain in the cache after the last access. The
idle timeout counter for an object is reset any time its TTL counter
is reset. In addition, an entry’s idle timeout counter is reset any
time the entry is accessed through a get operation or a netSearch .
The idle timeout counter for a region is reset whenever the idle
timeout is reset for one of its entries.</para>
</listitem>
</itemizedlist> <para> Each of these may be applied to the region itself
or entries in the region. Spring Data GemFire provides
<literal>&lt;region-ttl&gt;</literal>,
<literal>&lt;region-tti&gt;</literal>, <literal>&lt;entry-ttl&gt;</literal>
and <literal>&lt;entry-tti&gt;</literal> region child elements to specify
timeout values and expiration actions.</para></section>
<section id="bootstrap:region:local">
<title>Local Region</title>
<para>Spring Data GemFire offers a dedicated
<literal>local-region</literal> element for creating local regions. Local
regions, as the name implies, are standalone meaning they do not share
data with any other distributed system member. Other than that, all common
region configuration options are supported. 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">&lt;gfe:local-region id="myLocalRegion" /&gt;</programlisting>
<para>Here, a local region is created (if one doesn't exist already). The
name of the region is the same as the bean id (myLocalRegion) and the bean
assumes the existence of a GemFire cache named
<literal>gemfireCache</literal>.</para>
</section>
<section id="bootstrap:region:replicate">
<title>Replicated Region</title>
<para>One of the common region types is a <emphasis>replicated
region</emphasis> or <emphasis>replica</emphasis>. In short, when a region
is configured to be a replicated region, every member that hosts that
region stores a copy of the region's entries 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
rep</para>
<para>Spring Data GemFire offers a <literal>replicated-region</literal>
element. A minimal declaration looks as follows. All common configuration
options are available for replicated regions.</para>
<programlisting language="xml">&lt;gfe:replicated-region id="simpleReplica" /&gt;</programlisting>
</section>
<section id="bootstrap:region:partition">
<title>Partitioned Region</title>
<para>Another region type supported out of the box by the Spring Data
GemFire namespace, is the partitioned region. To quote the GemFire
docs:</para>
<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>
<para>A partition is created using 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">&lt;!-- bean definition named 'distributed-partition' backed by a region named 'redundant' with 2 copies
and a nested resolver declaration --&gt;
&lt;gfe:partitioned-region id="distributed-partition" copies="2" total-buckets="4" name="redundant"&gt;
&lt;gfe:partition-resolver&gt;
&lt;bean class="some.pkg.SimplePartitionResolver"/&gt;
&lt;/gfe:partition-resolver&gt;
&lt;/gfe:partitioned-region&gt;</programlisting>
<section id="bootstrap:region:partition:options">
<title><literal>partitioned-region</literal> Options</title>
<para>The following table offers a quick overview of configuration
options specific to partitioned regions. These are in addition to the
common region configuration options described above.</para>
<table id="bootstrap:region:partition:attrs:table">
<title>partitioned-region options</title>
<tgroup cols="3">
<colspec colwidth="1*"/>
<colspec colwidth="2*"/>
<colspec colwidth="2*"/>
<thead>
<row>
<entry>Name</entry>
<entry spanname="values">Values</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<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>partition-listener</entry>
<entry spanname="values">
<emphasis>bean name</emphasis>
</entry>
<entry>The name of the partitioned listener used by this region,
for handling partition events.</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 storage.</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 classified in short in: peer-to-peer
(p2p), client-server, 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 cache server. 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 names imply, the former defines a
client region while the latter defines connection pools to be used/shared
by the various client regions.</para>
<para>Below is a typical client region configuration:</para>
<programlisting language="xml">&lt;!-- client region using the default client-cache pool --&gt;
&lt;gfe:client-region id="simple"&gt;
&lt;gfe:cache-listener ref="c-listener"/&gt;
&lt;/gfe:client-region&gt;
&lt;!-- region using its own dedicated pool --&gt;
&lt;gfe:client-region id="complex" pool-name="gemfire-pool"&gt;
&lt;gfe:cache-listener ref="c-listener"/&gt;
&lt;/gfe:client-region&gt;
&lt;bean id="c-listener" class="some.pkg.SimpleCacheListener"/&gt;
&lt;!-- pool declaration --&gt;
&lt;gfe:pool id="gemfire-pool" subscription-enabled="true"&gt;
&lt;gfe:locator host="someHost" port="40403"/&gt;
&lt;/gfe:pool&gt;</programlisting>
<para>As with the other region types, <literal>client-region</literal>
supports <interfacename>CacheListener</interfacename>s (but not
CacheLoaders or CacheWriters). It also requires a connection
<literal>pool</literal> for connecting to a server. Each client can have
its own pool or they can share the same one.</para>
<para/>
<note>In the above example, the pool is configured with a
<literal>locator</literal>. The locator is a separate process used to
discover cache servers in the distributed system and are recommended for
production systems. It is also possible to configure the pool to connect
directly to one or more cache servers using the <literal>server</literal>
element.</note>
<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
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">&lt;gfe:client-region id="complex" pool-name="gemfire-pool"&gt;
&lt;gfe:key-interest durable="true" result-policy="KEYS"&gt;
&lt;bean id="key" class="java.lang.String"&gt;
&lt;constructor-arg value="someKey" /&gt;
&lt;/bean&gt;
&lt;/gfe:key-interest&gt;
&lt;gfe:regex-interest pattern=".*" receive-values="false"/&gt;
&lt;/gfe:client-region&gt;</programlisting>
<para>A special key <literal>ALL_KEYS</literal> means interest is
registered for all keys (identical to a regex interest of
<literal>.*</literal>). The <literal>receive-values</literal> attribute
indicates whether or not the values are received for create and update
events. If true, values are received; if false, only invalidation events
are received - refer to the GemFire documentation for more
details.</para>
</section>
</section>
</section>

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

@@ -7,26 +7,27 @@
xmlns:ns4="http://www.w3.org/2000/svg"
xmlns:ns3="http://www.w3.org/1998/Math/MathML"
xmlns:ns="http://docbook.org/ns/docbook">
<title>Gemfire Repositories</title>
<title>GemFire Repositories</title>
<section>
<title xml:id="gemfire-repositories.intro">Introduction</title>
<para>Spring Data Gemfire provides support to use the Spring Data
repository abstraction to easily persist entities into Gemfire and execute
queries. A general introduction into the repository programming model has
been provided in <xref linkend="repositories" />.</para>
<para>Spring Data GemFire provides support to use the Spring Data
repository abstraction to easily persist entities into GemFire and execute
queries. A general introduction into the repository programming model is
been provided <ulink url="http://static.springsource.org/spring-data/data-commons/docs/current/reference/html/#repositories">here
</ulink>.</para>
</section>
<section xml:id="gemfire-repositories.spring-configuration">
<title>Spring configuration</title>
<para>To bootstrap Spring Data repositories you use the
<code>&lt;repositories /&gt;</code> element from the Gemfire
<code>&lt;repositories /&gt;</code> element from the GemFire
namespace:</para>
<example>
<title>Bootstrap Gemfire repositories</title>
<title>Bootstrap GemFire repositories</title>
<programlisting language="xml">&lt;beans xmlns="http://www.springframework.org/schema/beans"
xmlns:gf="http://www.springframework.org/schema/gemfire"
@@ -43,7 +44,7 @@
<para>This configuration snippet will look for interfaces below the
configured base package and create repository instances for those
interfaces backed by a <classname>SimpleGemfireRepository</classname>.
interfaces backed by a <classname>SimpleGemFireRepository</classname>.
Note that you have to have your domain classes correctly mapped to
configured regions as the bottstrap process will fail otherwise.</para>
</section>
@@ -51,7 +52,7 @@
<section xml:id="gemfire-repositories.executing-queries">
<title>Executing OQL queries</title>
<para>The Gemfire repositories allow the definition of query methods to
<para>The GemFire repositories allow the definition of query methods to
easily execute OQL queries against the Region the managed entity is mapped
to.</para>

6
docs/src/reference/docbook/reference/samples.xml
View File

@@ -2,13 +2,17 @@
<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
<para>The Spring Data 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>
Additional sample applications may be found in the <ulink url="https://github.com/SpringSource/spring-gemfire-examples">Spring Data GemFire Examples</ulink> repository.
</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

10
docs/src/reference/docbook/reference/serialization.xml
View File

@@ -2,8 +2,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
<para>To improve overall performance of the data grid, GemFire supports a
dedicated serialization protocol (PDX) 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>
@@ -11,7 +11,7 @@
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 C++). This chapter discusses the various ways in which Spring Data GemFire simplifies
and improves GemFire custom serialization in Java.</para>
<section id="serialization:wiring">
@@ -21,7 +21,7 @@
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
local to a certain VM/machine. For such cases, Spring Data GemFire 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>
@@ -63,7 +63,7 @@
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
whether this is the case or not. For such cases, Spring Data GemFire allows the automatic
generation of <classname>Instatiator</classname> classes which instantiate
a new type (using the default constructor) without the use of
reflection:</para>