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

Refactored and performed cleanup in the Spring Data GemFire Reference Guide. Added chapter on Bootstrapping a Spring ApplicationContext from GemFire using Gfsh.

Browse Source
This commit is contained in:
John Blum
2014-05-19 18:58:37 -07:00
parent edb0432987
commit 88e2b2b60e
11 changed files with 830 additions and 528 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -1,8 +1,7 @@
<?xml version="1.0" encoding="UTF-8"?>
<book xmlns="http://docbook.org/ns/docbook" version="5.0"
xml:id="spring-gemfire-reference"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink">
xmlns:xi="http://www.w3.org/2001/XInclude">
<bookinfo>
<title>Spring Data GemFire Reference Guide</title>
<releaseinfo>${version}</releaseinfo>
@@ -30,11 +29,6 @@
<surname>Gierke</surname>
<affiliation>SpringSource, a division of Pivotal</affiliation>
</author>
<author>
<firstname>Lyndon</firstname>
<surname>Adams</surname>
<affiliation>Pivotal</affiliation>
</author>
</authorgroup>
@@ -74,6 +68,7 @@
<xi:include href="reference/mapping.xml"/>
<xi:include href="reference/repositories.xml"/>
<xi:include href="reference/function-annotations.xml"/>
<xi:include href="reference/gemfire-bootstrap.xml"/>
<xi:include href="reference/samples.xml"/>
</part>

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

@@ -1,14 +1,16 @@
<?xml version="1.0" encoding="UTF-8"?>
<chapter xml:id="intro-introduction" xmlns="http://docbook.org/ns/docbook" version="5.0">
<title>Introduction</title>
<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>
<title>Introduction</title>
<para>
This reference guide for Spring Data GemFire explains how to use the Spring Framework to configure
and develop applications with Pivotal 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 (SGF) and since then
has been moved under the Spring Data umbrella project and renamed accordingly.
</note>
<note>Spring Data GemFire started as a top level Spring project called
Spring GemFire (SGF) and has since moved under the Spring Data umbrella project
and has been renamed accordingly.</note>
</chapter>

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

@@ -1,112 +1,248 @@
<?xml version="1.0" encoding="UTF-8"?>
<chapter version="5.0" xml:id="new-features"
xmlns="http://docbook.org/ns/docbook"
xmlns:ns6="http://www.w3.org/1999/xlink"
xmlns:ns5="http://www.w3.org/1999/xhtml"
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>New Features</title>
<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
<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>
<ulink url="http://www.springsource.org/spring-data">Spring Data</ulink>
<section id="new-in-1-2-0">
<title>New in the 1.2.0 Release</title>
project.
</note>
<itemizedlist>
<listitem>
<para>
Full support for GemFire configuration via the SDG <emphasis>gfe</emphasis> namespace. Now GemFire
components may be configured completely without requiring a native <emphasis>cache.xml</emphasis>
file.
</para>
</listitem>
<listitem>
<para>WAN Gateway support for GemFire 6.6.x. See <xref linkend="bootstrap:gateway"/>.</para>
</listitem>
<listitem>
<para>
Spring Data Repository support using a dedicated SDG namespace, <emphasis>gfe-data</emphasis>.
See <xref linkend="gemfire-repositories"/>
</para>
</listitem>
<listitem>
<para>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 SDG
<emphasis>gfe</emphasis> namespace to allow sharing of persist stores among Regions,
and other components that support persistent backup or overflow.
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>
</listitem>
<listitem>
<para>GemFire Sub-Regions 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>
<section id="new-in-1-3-0">
<title>New in the 1.3.0 Release</title>
<section id="new-in-1-2-1">
<title>New in the 1.2.1 Release</title>
<itemizedlist>
<listitem>
<para>Annotation support for GemFire functions. It is now possible to
declare and register functions written as POJOs with annotations. In
addition function executions are defined as annotated interfaces,
similar to the way Spring Data repositories work. See <xref
linkend="function-annotations"/></para>
</listitem>
<itemizedlist>
<listitem>
<para>Support for the re-designed WAN Gateway in GemFire 7.0.</para>
</listitem>
</itemizedlist>
</section>
<listitem>
<para>We have added a <tag>&lt;datasource&gt;</tag> tag to the
<emphasis>gfe-data</emphasis> XML namespace. This simplifies
establishing a basic client <link
linkend="data-access:datasource">connection</link> to a GemFire data
grid.</para>
</listitem>
<section id="new-in-1-3-0">
<title>New in the 1.3.0 Release</title>
<listitem>
<para>To <link linkend="bootstrap:region:json">support JSON</link> features introduced in GemFire 7.0, we have
added a ,<tag>&lt;json-region-autoproxy&gt;</tag> tag to the <emphasis>gfe-data</emphasis> XML
namespace, enabling Spring AOP to perform the necessary conversions
automatically on region operations.</para>
</listitem>
<itemizedlist>
<listitem>
<para>
Annotation support for GemFire Functions. It is now possible to declare and register Functions
written as POJOs using annotations. In addition, Function executions are defined as
annotated interfaces, similar to the way Spring Data Repositories work.
See <xref linkend="function-annotations"/>.
</para>
</listitem>
<listitem>
<para>
Added a <tag>&lt;datasource&gt;</tag> element to the SDG <emphasis>gfe-data</emphasis> namespace to
simplify establishing a basic <link linkend="data-access:datasource">client connection</link>
to a GemFire data grid.
</para>
</listitem>
<listitem>
<para>
Added a <tag>&lt;json-region-autoproxy&gt;</tag> element to the SDG <emphasis>gfe-data</emphasis>
namespace to <link linkend="bootstrap:region:json">support JSON</link> features introduced
in GemFire 7.0, enabling Spring AOP to perform the necessary conversions automatically
on Region operations.
</para>
</listitem>
<listitem>
<para>Upgraded to GemFire 7.0.1 and added namespace support for new AsyncEventQueue attributes.</para>
</listitem>
<listitem>
<para>Added support for setting subscription interest policy on Regions.</para>
</listitem>
</itemizedlist>
</section>
<listitem>
<para>Upgraded to GemFire 7.0.1 and added namespace support for new AsyncEventQueue attributes</para>
</listitem>
<listitem>
<para>Added support for setting subscription interest policy on regions</para>
</listitem>
</itemizedlist>
</section>
<section id="new-in-1-3-1">
<title>New in the 1.3.1 Release</title>
<section id="new-in-1-2-1">
<title>New in the 1.2.1 Release</title>
<itemizedlist>
<listitem>
<para>
Support for void returns on Function executions. See <xref linkend="function-annotations"/>
for complete details.
</para>
</listitem>
</itemizedlist>
</section>
<itemizedlist>
<listitem>
<para>WAN Gateway Support for GemFire 7.0</para>
</listitem>
</itemizedlist>
</section>
<section id="new-in-1-3-2">
<title>New in the 1.3.2 Release</title>
<section id="new-in-1-2-0">
<title>New in the 1.2.0 Release</title>
<itemizedlist>
<listitem>
<para>
Support for persisting Local Regions. See <xref linkend="bootstrap:region:local"/> and
<xref linkend="bootstrap:region:common:attributes"/>.
</para>
</listitem>
<listitem>
<para>
Support for entry time-to-live and entry idle-time on a GemFire Client Cache.
See <xref linkend="bootstrap:cache:client"/>
</para>
</listitem>
<listitem>
<para>
Support for multiple Spring Data GemFire web-based applications using a single GemFire cluster,
operating concurrently inside tc Server.
</para>
</listitem>
</itemizedlist>
</section>
<itemizedlist>
<listitem>
<para>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>
<section id="new-in-1-3-3">
<title>New in the 1.3.3 Release</title>
<listitem>
<para>WAN Gateway support for GemFire 6.6.x. See <xref
linkend="bootstrap:gateway"/></para>
</listitem>
<itemizedlist>
<listitem>
<para>
Support for concurrency-checks-enabled on all GemFire Cache Region definitions using the SDG
<emphasis>gfe</emphasis> namespace. See <xref linkend="bootstrap:region:common:attributes"/>.
</para>
</listitem>
<listitem>
<para>
Support for Cache Loaders and Cache Writers on Client, Local Regions.
See <xref linkend="bootstrap:region:common:loaders-writers"/>.
</para>
</listitem>
<listitem>
<para>
Support for registering CacheListeners, AsyncEventQueues and Gateway Senders
on GemFire Cache Sub-Regions.
</para>
</listitem>
<listitem>
<para>
Support for PDX persistent keys in GemFire Regions.
</para>
</listitem>
<listitem>
<para>
Support for correct Partition Region bean creation in a Spring context when collocation
is specified with the <emphasis>colocated-with</emphasis> attribute.
</para>
</listitem>
<listitem>
<para>
Full support for GemFire Cache Sub-Regions using proper, nested <literal>&lt;*-region&gt;</literal>
element syntax in the SDG <emphasis>gfe</emphasis> namespace.
</para>
</listitem>
</itemizedlist>
</section>
<listitem>
<para>Spring Data Repository support with a dedicated namespace,
<emphasis>gfe-data</emphasis>. See <xref
linkend="gemfire-repositories"/></para>
</listitem>
<section id="new-in-1-3-4">
<title>New in the 1.3.4 Release</title>
<listitem>
<para>Namespace support for registering GemFire functions. See <xref
linkend="bootstrap:function"/></para>
</listitem>
<itemizedlist>
<listitem>
<para>Upgraded Spring Data GemFire to Spring Framework 3.2.8.</para>
</listitem>
<listitem>
<para>Upgraded Spring Data GemFire to Spring Data Commons 1.7.1.</para>
</listitem>
</itemizedlist>
</section>
<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. 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>
</listitem>
<section id="new-in-1-4-0">
<title>New in the 1.4.0 Release</title>
<listitem>
<para>GemFire subregions are supported via nested
<literal>&lt;*-region&gt;</literal> elements</para>
</listitem>
<itemizedlist>
<listitem>
<para>Upgrades Spring Data GemFire to GemFire 7.0.2.</para>
</listitem>
<listitem>
<para>Upgrades Spring Data GemFire to Spring Data Commons 1.8.0.</para>
</listitem>
<listitem>
<para>
Integrates Spring Data GemFire with Spring Boot, which includes both a
<emphasis>spring-boot-starter-data-gemfire </emphasis> POM along with a Spring Boot Sample
application demonstrating GemFire Cache Transactions configured with SDG bootstrapped
with Spring Boot.
</para>
</listitem>
<listitem>
<para>Support for bootstrapping a Spring Context in a GemFire Server when started from Gfsh.</para>
</listitem>
<listitem>
<para>Support for persisting application domain object/entities to multiple GemFire Cache Regions.</para>
</listitem>
<listitem>
<para>
Support for persisting application domain object/entities to GemFire Cache Sub-Regions, avoiding
collisions when Sub-Regions are uniquely identifiable, but identically named.
</para>
</listitem>
<listitem>
<para>
Adds strict XSD type rules to, and full support for, Data Policies and Region Shortcuts on all
GemFire Cache Region types.
</para>
</listitem>
<listitem>
<para>
Changed the default behavior of SDG <literal>&lt;*-region&gt;</literal> elements from lookup
to always create a new Region along with an option to restore old behavior using the
<emphasis>ignore-if-exists</emphasis> attribute.
</para>
</listitem>
<listitem>
<para>
Enables Spring Data GemFire to be fully built and ran on JDK 7 and JDK 8 (Note, however, GemFire
has not yet been fully tested and supported on JDK 8;
See <ulink url="http://pubs.vmware.com/vfabric53/topic/com.vmware.vfabric.gemfire.7.0/getting_started/system_requirements/supported_configurations.html">GemFire User Guide</ulink>
for additional details.
</para>
</listitem>
</itemizedlist>
</section>
<listitem>
<para>A <literal>&lt;local-region&gt;</literal> element has been added
to configure a local region</para>
</listitem>
</itemizedlist>
</section>
</chapter>

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

@@ -1,9 +1,11 @@
<chapter xml:id="requirements" xmlns="http://docbook.org/ns/docbook" version="5.0">
<title>Requirements</title>
<chapter xml:id="requirements" xmlns="http://docbook.org/ns/docbook" version="5.0">
<title>Requirements</title>
<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
(version 7 or above is recommended).
</para>
</chapter>
<para>
Spring Data GemFire requires JDK 6.0 or above,
<ulink url="http://www.springsource.org/about">Spring Framework</ulink> 3 and
<ulink url="http://www.vmware.com/support/pubs/vfabric-gemfire.html">Pivotal GemFire</ulink>
6.6 or above (version 7 or above is recommended).
</para>
</chapter>

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

@@ -1,27 +1,23 @@
<?xml version="1.0" encoding="UTF-8"?>
<chapter xml:id="sgf-links" xmlns="http://docbook.org/ns/docbook"
xmlns:ns52="http://www.w3.org/1999/xhtml"
xmlns:ns5="http://www.w3.org/1999/xlink"
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>Useful Links</title>
<chapter xml:id="sgf-links" xmlns="http://docbook.org/ns/docbook">
<title>Useful Links</title>
<itemizedlist>
<listitem>
<ulink url="http://projects.spring.io/spring-data-gemfire/">Spring Data GemFire Home Page</ulink>
</listitem>
<listitem>
<ulink url="http://www.vmware.com/products/application-platform/vfabric-gemfire/overview.html">Pivotal GemFire Home Page</ulink>
</listitem>
<listitem>
<ulink url="https://www.vmware.com/support/pubs/vfabric-gemfire.html">Pivotal GemFire Documentation</ulink>
</listitem>
<listitem>
<ulink url="http://communities.vmware.com/community/vmtn/appplatform/vfabric_gemfire">Pivotal GemFire Community Home Page</ulink>
</listitem>
<listitem>
<ulink url="http://forum.spring.io/forum/spring-projects/data/gemfire">Spring Data GemFire Forum</ulink>
</listitem>
</itemizedlist>
<itemizedlist>
<listitem>
<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>
<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>
</chapter>

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

@@ -1,18 +1,20 @@
<?xml version="1.0" encoding="UTF-8"?>
<preface xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="preface">
<title>Preface</title>
<para>
Spring 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.
Spring Data GemFire focuses on integrating the Spring Framework's powerful, non-invasive programming model
and concepts with Pivotal GemFire, simplifying configuration, development and providing high-level abstractions.
This document assumes the reader already has a basic familiarity with the Spring Framework and Pivotal GemFire
concepts and APIs.
</para>
<para>
While every effort has been made to ensure that this documentation is comprehensive and there are no errors,
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 Data GemFire team by raising an
<ulink url="http://jira.springframework.org">issue</ulink>. Thank you.
While every effort has been made to ensure this documentation is comprehensive and there are no errors,
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, please do bring the errors to the attention
of the Spring Data GemFire team by raising an <ulink url="https://jira.spring.io/browse/SGF">issue</ulink>.
Thank you.
</para>
</preface>

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

@@ -2,25 +2,22 @@
<chapter version="5.0" xml:id="bootstrap"
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/2000/svg"
xmlns:ns4="http://www.w3.org/1998/Math/MathML"
xmlns:ns3="http://www.w3.org/1999/xhtml"
xmlns:ns="http://docbook.org/ns/docbook">
xmlns:xi="http://www.w3.org/2001/XInclude">
<title>Bootstrapping GemFire through the Spring Container</title>
<para>Spring Data GemFire provides full configuration and initialization of
the GemFire data grid through Spring's IoC container and 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>
<para>
Spring Data GemFire provides full configuration and initialization of the GemFire data grid through
Spring's IoC container and 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>
<note>
<para>This section assumes basic familiarity with GemFire. For more
information see the <link
xlink:href="http://www.vmware.com/products/application-platform/vfabric-gemfire">product</link>
documentation.</para>
<para>
This section assumes basic familiarity with GemFire. For more information see the
<link xlink:href="http://www.vmware.com/products/application-platform/vfabric-gemfire">product</link>
documentation.
</para>
</note>
<section id="bootstrap:region:spring:config">

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

@@ -1,130 +1,151 @@
<?xml version="1.0" encoding="UTF-8"?>
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude" xml:id="apis">
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0"
xmlns:xi="http://www.w3.org/2001/XInclude"
xml:id="apis">
<title>Working with the GemFire APIs</title>
<para>Once the GemFire cache and regions have been configured they can
injected and used inside application objects. This chapter describes the
integration with Spring's transaction management functionality and
<classname>DaoException</classname> hierarchy. It also covers support for
dependency injection of GemFire managed objects.</para>
<para>
Once the GemFire Cache and Regions have been configured they can be injected and used inside application objects.
This chapter describes the integration with Spring's Transaction Management functionality
and <classname>DaoException</classname> hierarchy. It also covers support for dependency injection
of GemFire managed objects.
</para>
<section id="apis:exception-translation">
<title>Exception translation</title>
<title>Exception Translation</title>
<para>Using a new data access technology requires not just accommodating
to a new API but also handling exceptions specific to that technology. To
accommodate this case, Spring Framework provides a technology agnostic,
consistent exception <ulink
url="http://static.springsource.org/spring/docs/3.0.x/spring-framework-reference/html/dao.html#dao-exceptions">hierarchy</ulink>
that abstracts one from proprietary (and usually checked) exceptions to a
set of focused runtime exceptions. As mentioned in the Spring Framework
documentation, <ulink
url="http://static.springsource.org/spring/docs/3.0.x/spring-framework-reference/html/orm.html#orm-exception-translation">exception
translation</ulink> can be applied transparently to your data access
objects through the use of the <literal>@Repository</literal> annotation
and AOP by defining a <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>
<para>
Using a new data access technology requires not only accommodating a new API but also handling exceptions
specific to that technology. To accommodate this case, Spring Framework provides a technology agnostic,
consistent <ulink url="http://static.springsource.org/spring/docs/3.0.x/spring-framework-reference/html/dao.html#dao-exceptions">exception hierarchy</ulink>
that abstracts the application from proprietary (and usually checked) exceptions to a set of focused
runtime exceptions. As mentioned in the Spring Framework documentation,
<ulink url="http://static.springsource.org/spring/docs/3.0.x/spring-framework-reference/html/orm.html#orm-exception-translation">exception translation</ulink>
can be applied transparently to your data access objects through the use of the <literal>@Repository</literal>
annotation and AOP by defining a <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>GemfireTemplate</title>
<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 GemFire checked exceptions for example through the <interfacename>GemfireCallback</interfacename>.</para>
<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 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
thread-safe and should be reused across multiple classes:</para>
<para>
The template class requires a GemFire <interfacename>Region</interfacename> instance and once configured is
thread-safe and should be reused across multiple classes:
</para>
<programlisting language="xml">&lt;bean id="gemfireTemplate" class="org.springframework.data.gemfire.GemfireTemplate" p:region-ref="someRegion"/&gt;</programlisting>
<programlisting language="xml">&lt;bean id="gemfireTemplate" class="org.springframework.data.gemfire.GemfireTemplate" p:region-ref="someRegion"/&gt;</programlisting>
<para>Once the template is configured, one can use it alongside
<interfacename>GemfireCallback</interfacename> to work directly with the
GemFire <interfacename>Region</interfacename>, without having to deal with
checked exceptions, threading or resource management concerns:</para>
<para>
Once the template is configured, one can use it alongside <interfacename>GemfireCallback</interfacename>
to work directly with the GemFire <interfacename>Region</interfacename>, without having to deal with
checked exceptions, threading or resource management concerns:
</para>
<programlisting language="java">template.execute(new GemfireCallback&lt;Iterable&lt;String&gt;&gt;() {
public Iterable&lt;String&gt; doInGemfire(Region reg) throws GemFireCheckedException, GemFireException {
// working against a Region of String
Region&lt;String, String&gt; region = reg;
<programlisting language="java">template.execute(new GemfireCallback&lt;Iterable&lt;String&gt;&gt;() {
public Iterable&lt;String&gt; doInGemfire(Region reg) throws GemFireCheckedException, GemFireException {
// working against a Region of String
Region&lt;String, String&gt; region = reg;
region.put("1", "one");
region.put("3", "three");
region.put("1", "one");
region.put("3", "three");
return region.query("length &lt; 5");
}
return region.query("length &lt; 5");
}
});</programlisting>
<para>For accessing the full power of the GemFire query language, one can use the <methodname>find</methodname> and <methodname>findUnique</methodname> which, as 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>
<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>
<section id="apis:spring-cache-abstraction">
<title>Support for Spring Cache Abstraction</title>
<para>Since 1.1, Spring GemFire provides an implementation for Spring 3.1
<ulink url="http://static.springsource.org/spring/docs/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"
<title>Support for Spring Cache Abstraction</title>
<para>
Since 1.1, Spring Data GemFire provides an implementation of the Spring 3.1
<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:cache="http://www.springframework.org/schema/cache"
xmlns:gfe="http://www.springframework.org/schema/gemfire"
xmlns:p="http://www.springframework.org/schema/p"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
http://www.springframework.org/schema/gemfire http://www.springframework.org/schema/gemfire/spring-gemfire.xsd
http://www.springframework.org/schema/cache http://www.springframework.org/schema/cache/spring-cache.xsd">
http://www.springframework.org/schema/gemfire http://www.springframework.org/schema/gemfire/spring-gemfire.xsd
http://www.springframework.org/schema/cache http://www.springframework.org/schema/cache/spring-cache.xsd">
<!-- turn on declarative caching -->
<cache:annotation-driven />
<gfe:cache id="gemfire-cache" />
<cache:annotation-driven/>
<gfe:cache id="gemfire-cache"/>
<!-- declare GemFire Cache Manager -->
<bean id="cacheManager" class="org.springframework.data.gemfire.support.GemfireCacheManager" p:cache-ref="gemfire-cache">
</beans>]]>
</programlisting>
</beans>]]></programlisting>
</section>
<section id="apis:tx-mgmt">
<title>Transaction Management</title>
<title>Transaction Management</title>
<para>One of the most popular features of Spring Framework is <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/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>
One of the most popular features of Spring Framework is
<ulink url="http://static.springsource.org/spring/docs/current/spring-framework-reference/htmlsingle/spring-framework-reference.html#transaction">transaction management</ulink>.
If you are not familiar with it, we strongly recommend
<ulink url="http://static.springsource.org/spring/docs/current/spring-framework-reference/htmlsingle/spring-framework-reference.html#transaction-motivation">reading</ulink>
about it as it offers a consistent programming model that works transparently across multiple APIs and can be
configured either programmatically or declaratively (the most popular choice).
</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>
<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 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>
<programlisting language="xml">&lt;gfe:transaction-manager id="tx-manager" cache-ref="cache"/&gt;</programlisting>
<para>Note that currently GemFire supports optimistic transactions with
<emphasis>read committed</emphasis> isolation. Furthermore, to guarantee
this isolation, developers should avoid making
<emphasis>in-place</emphasis> changes, that is manually modifying the
values present in the cache. To prevent this from happening, the
transaction manager configured the cache to use <emphasis>copy on
read</emphasis> semantics, meaning a clone of the actual value is created,
each time a read is performed. This 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="https://www.vmware.com/support/developer/vfabric-gemfire/700-api/com/gemstone/gemfire/cache/CacheTransactionManager.html">documentation</ulink>.</para>
<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
Spring Data GemFire namespace elements, if the Cache bean name is not configured, the aforementioned naming
convention will used. Additionally, the transaction manager name is<literal>gemfireTransactionManager</literal>
if not explicitly specified.
</note>
<para>
Currently, GemFire supports optimistic transactions with <emphasis>read committed</emphasis> isolation.
Furthermore, to guarantee this isolation, developers should avoid making <emphasis>in-place</emphasis> changes
that manually modify values present in the Cache. To prevent this from happening, the transaction manager
configures 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 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="https://www.vmware.com/support/developer/vfabric-gemfire/700-api/com/gemstone/gemfire/cache/CacheTransactionManager.html">documentation</ulink>.
</para>
</section>
<xi:include href="cq-container.xml"/>
<section id="apis:declarable">
<title>Wiring <interfacename>Declarable</interfacename> components</title>
@@ -330,4 +351,5 @@
<classname>DBLoader</classname> code.</para>
</section>
</section>
</chapter>
</chapter>

180
docs/src/reference/docbook/reference/gemfire-bootstrap.xml Normal file
View File

@@ -0,0 +1,180 @@
<?xml version="1.0" encoding="UTF-8"?>
<chapter xml:id="gemfire-bootstrap" xmlns="http://docbook.org/ns/docbook" version="5.0">
<title>GemFire Bootstrapping a Spring ApplicationContext with Gfsh</title>
<section>
<title id="gemfire-bootstrap:intro">Introduction</title>
<para>
Normally, a Spring-based application is used to <link linkend="bootstrap">bootstrap GemFire</link>
using Spring Data GemFire's XML namespace elements. Just by specifying a <literal>&lt;gfe:cache/&gt;</literal>
element in Spring Data GemFire configuration meta-data, a Singleton GemFire, peer Cache instance will be
created and initialized, using default settings, in the same JVM process as your application.
</para>
<para>
However, sometimes it is a requirement, perhaps imposed by your IT operations team, that GemFire must be
fully managed and operated using the GemFire tool suite, such as with
<ulink url="http://pubs.vmware.com/vfabric53/topic/com.vmware.vfabric.gemfire.7.0/tools_modules/gfsh/chapter_overview.html">Gfsh</ulink>
for instance. Using <emphasis>Gfsh</emphasis>, even though the application and GemFire will share the same
JVM process, GemFire will instead bootstrap your Spring application context rather than the other way around.
So, using this approach GemFire, instead of an application server, or a Java main class using Spring Boot,
will bootstrap and host your application.
</para>
<para>
Keep in mind, however, that GemFire is not an application server. In addition, there are limitations
to using this approach where GemFire Cache configuration is concerned.
</para>
</section>
<section>
<title id="gemfire-bootstrap:initializer">Using GemFire to Bootstrap a Spring Context Started with Gfsh</title>
<para>
In order to bootstrap a Spring application context in GemFire when starting a GemFire Server process
using Gfsh, a user must make use of GemFire's
<ulink url="http://pubs.vmware.com/vfabric53/topic/com.vmware.vfabric.gemfire.7.0/basic_config/the_cache/setting_cache_initializer.html">Initalizer</ulink>
functionality. An <emphasis>Initializer</emphasis> can be used to specify a callback application that
is launched after the Cache is initialized by GemFire.
</para>
<para>
An <emphasis>Initializer</emphasis> is specified within an
<ulink url="http://pubs.vmware.com/vfabric53/topic/com.vmware.vfabric.gemfire.7.0/reference/topics/cache_xml.html?path=4_1_9_1_2_21#initializer">initializer</ulink>
element using a minimal snippet of GemFire's native configuration meta-data inside
a <literal>cache.xml</literal> file. The <literal>cache.xml</literal> file is required in order to
bootstrap the Spring application context, much like a minimal snippet of Spring XML config is needed to
bootstrap a Spring application context configured with component scanning
(e.g. <literal>&lt;context:component-scan base-packages="..."/&gt;</literal>)
</para>
<para>
As of Spring Data GemFire 1.4, such an <emphasis>Initializer</emphasis> is already conveniently provided
by the framework, the <classname>org.springframework.data.gemfire.support.SpringContextBootstrappingInitializer</classname>.
The typical, yet minimal configuration for this class inside GemFire's <literal>cache.xml</literal> file
will look like the following:
</para>
<programlisting language="xml"><![CDATA[<?xml version="1.0"?>
<!DOCTYPE cache PUBLIC "-//GemStone Systems, Inc.//GemFire Declarative Caching 7.0//EN"
"http://www.gemstone.com/dtd/cache7_0.dtd">
<cache>
<initializer>
<class-name>org.springframework.data.gemfire.support.SpringContextBootstrappingInitializer</class-name>
<parameter name="contextConfigLocations">
<string>classpath:application-context.xml</string>
</parameter>
</initializer>
</cache>]]>
</programlisting>
<para>
The <classname>SpringContextBootstrappingInitializer</classname> class follows similar conventions as
Spring's ContextLoaderListener class for bootstrapping a Spring context inside a Web Application, where
application context configuration files are specified with the <literal>contextConfigLocations</literal>
Servlet Context Parameter. In addition, the <classname>SpringContextBootstrappingInitializer</classname>
class can also be used with a <literal>basePackages</literal> parameter to specify a comma-separated list
of base package containing the appropriately annotated application components that the Spring container
will search using component scanning and create Spring beans for:
</para>
<programlisting language="xml"><![CDATA[<?xml version="1.0"?>
<!DOCTYPE cache PUBLIC "-//GemStone Systems, Inc.//GemFire Declarative Caching 7.0//EN"
"http://www.gemstone.com/dtd/cache7_0.dtd">
<cache>
<initializer>
<class-name>org.springframework.data.gemfire.support.SpringContextBootstrappingInitializer</class-name>
<parameter name="basePackages">
<string>org.mycompany.myapp.services,org.mycompany.myapp.dao,...</string>
</parameter>
</initializer>
</cache>]]>
</programlisting>
<para>
Then, with a properly configured and constructed <literal>CLASSPATH</literal> along with the
<literal>cache.xml</literal> file shown above specified as a command-line option when starting
a GemFire Server in Gfsh, the command-line would be:
</para>
<programlisting>gfsh>start server --name=Server1 --log-level=config ...
--classpath="/path/to/spring-data-gemfire-1.4.0.jar:/path/to/application/classes.jar"
--cache-xml-file="/path/to/gemfire/cache.xml"
</programlisting>
<para>
The <literal>application-context.xml</literal> can be any valid Spring context configuration meta-data
including all the SDG namespace elements. The only limitation with this approach is that the GemFire
Cache cannot be configured using the Spring Data GemFire namespace. In other words, none of the
<literal>&lt;gfe:cache/&gt;</literal> element attributes, such as <literal>cache-xml-location</literal>,
<literal>properties-ref</literal>, <literal>critical-heap-percentage</literal>, <literal>pdx-serializer-ref</literal>,
<literal>lock-lease</literal>, etc can be specified. If used, these attributes will be ignored.
The main reason for this is that GemFire itself has already created an initialized the Cache before
the <emphasis>Initializer</emphasis> gets invoked. As such, the Cache will already exist and since it is
a "Singleton", it cannot be re-initialized or have any of it's configuration augmented.
</para>
</section>
<section>
<title id="gemfire-bootstrap:lazy-wiring">Lazy-Wiring GemFire Components</title>
<para>
Spring Data GemFire already provides existing support for wiring GemFire components (such as CacheListeners,
CacheLoaders or CacheWriters) that are declared and created by GemFire in <literal>cache.xml</literal>
using the <classname>WiringDeclarableSupport</classname> class as described in
<xref linkend="apis:declarable:autowiring"/>.
However, this only works when Spring does the bootstrapping (i.e. bootstraps GemFire). When your Spring
application context is the one bootstrapped by GemFire, then these GemFire components go unnoticed since
the Spring application context does not even exist yet! The Spring application context will not get created
until GemFire calls the <emphasis>Initializer</emphasis>, which is after all the other GemFire components
and configuration has already been created and initialized.
</para>
<para>
So, in order to solve this problem, a new <classname>LazyWiringDeclarableSupport</classname> class was
introduced, that is, in a sense, Spring application context aware. The intention of this abstract
base class is that any implementing class will register itself to be configured by the Spring
application context created by GemFire after the <emphasis>Initializer</emphasis> is called. In essence,
this give your GemFire managed component a chance to be configured and auto-wired with Spring beans defined
in the Spring application context.
</para>
<para>
For instance, you might necessarily (although, rare) have defined both a Region and CacheListener component
in GemFire <literal>cache.xml</literal>. The CacheLoader may need access to an application DAO, or perhaps
Spring application context defined JDBC Data Source for loading "Users" into a GemFire Cache
<literal>REPLICATE</literal> Region on start. Of course, one should be careful in mixing the different
life-cycles of GemFire and the Spring Container together in this manner as not all use cases and scenarios
are supported. The GemFire <literal>cache.xml</literal> configuration would be similar to the following
(which comes from SDG's test suite):
</para>
<programlisting language="xml"><![CDATA[<?xml version="1.0"?>
<!DOCTYPE cache PUBLIC "-//GemStone Systems, Inc.//GemFire Declarative Caching 7.0//EN"
"http://www.gemstone.com/dtd/cache7_0.dtd">
<cache>
<region name="Users" refid="REPLICATE">
<region-attributes initial-capacity="101" load-factor="0.85">
<key-constraint>java.lang.String</key-constraint>
<value-constraint>org.springframework.data.gemfire.repository.sample.User</value-constraint>
<cache-loader>
<class-name>org.springframework.data.gemfire.support.SpringContextBootstrappingInitializerIntegrationTest$UserDataStoreCacheLoader</class-name>
</cache-loader>
</region-attributes>
</region>
<initializer>
<class-name>org.springframework.data.gemfire.support.SpringContextBootstrappingInitializer</class-name>
<parameter name="basePackages">
<string>org.springframework.data.gemfire.support.sample</string>
</parameter>
</initializer>
</cache>]]>
</programlisting>
</section>
</chapter>

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

@@ -1,39 +1,42 @@
<?xml version="1.0" encoding="UTF-8"?>
<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"
xmlns:ns5="http://www.w3.org/2000/svg"
xmlns:ns4="http://www.w3.org/1998/Math/MathML"
xmlns:ns3="http://www.w3.org/1999/xhtml"
xmlns:ns="http://docbook.org/ns/docbook">
<title>Document structure</title>
xmlns="http://docbook.org/ns/docbook">
<title>Document Structure</title>
<para>The following chapters explain the core functionality offered by
Spring Data GemFire.</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, configuring, and accessing GemFire
caches, cache servers, regions, and related distributed system
components</para>
<para>
<xref linkend="bootstrap"/> describes the configuration support provided for bootstrapping, configuring,
initializing and accessing 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
transaction management and exception translation.</para>
<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 and management of associated objects.</para>
<para>
<xref linkend="serialization"/> describes the enhancements for GemFire (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="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="gemfire-repositories"/> describes how to create and use GemFire Repositories using Spring Data.
</para>
<para><xref linkend="function-annotations"/> describes how to create and use
GemFire Functions using Spring Data</para>
<para>
<xref linkend="function-annotations"/> describes how to create and use GemFire Functions using annotations.
</para>
<para>
<xref linkend="samples"/> describes the samples provided with the distribution to illustrate
the various features available in Spring Data GemFire.
</para>
<para><xref linkend="samples"/> describes the samples provided with the
distribution to illustrate the various features available in Spring Data
GemFire.</para>
</chapter>

459
docs/src/reference/docbook/reference/region.xml
View File

@@ -95,259 +95,226 @@
semantics or setup infrastructure.</para>
</section>
<section id="bootstrap:region:overview">
<title>Configuring Regions</title>
<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>
<para>
Spring Data GemFire provides comprehensive support for configuring any type of GemFire Region
via the following elements:
<listitem>
<para>Replicated Region
<literal>&lt;replicated-region&gt;</literal></para>
</listitem>
<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>
<listitem>
<para>Partitioned Region
<literal>&lt;partitioned-region&gt;</literal></para>
</listitem>
For a comprehensive description of
<ulink url="http://pubs.vmware.com/vfabricNoSuite/topic/com.vmware.vfabric.gemfire.7.0/developing/region_options/region_types.html">
Region types
</ulink>
please consult the GemFire product documentation.
</para>
<listitem>
<para>Client Region <literal>&lt;client-region&gt;</literal></para>
</listitem>
</itemizedlist>For a comprehensive description of <ulink
url="http://pubs.vmware.com/vfabricNoSuite/topic/com.vmware.vfabric.gemfire.7.0/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>
<section id="bootstrap:region:common:attributes">
<title>Common Region Attributes</title>
<para>
The following table(s) list attributes available for various region types:
<para>The following table(s) list attributes available for various
region types: <table id="bootstrap:region:common:attributes:table">
<title>Common Region Attributes</title>
<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:false (Note: The default was true prior to 1.3.0)</emphasis>
</entry>
<entry spanname="description">
Indicates whether the Region should be closed at shutdown.
</entry>
</row>
<row>
<entry>concurrency-checks-enables</entry>
<entry spanname="values">
<emphasis>boolean, default:true</emphasis>
</entry>
<entry spanname="description">
Determines whether members perform checks to provide consistent handling
for concurrent or out-of-order updates to distributed Regions.
</entry>
</row>
<row>
<entry>data-policy</entry>
<entry spanname="values">
<emphasis>See GemFire's
<ulink url="http://www.vmware.com/support/developer/vfabric-gemfire/700-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.
</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.
</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 Region entries.
</entry>
</row>
<row>
<entry>key-constraint</entry>
<entry spanname="values">
<emphasis>Any valid, fully-qualified 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 not 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 (disk).
</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, fully-qualified Java class name.</emphasis>
</entry>
<entry spanname="description">The expected value type.</entry>
</row>
</tbody>
</tgroup>
</table>
</para>
</section>
<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:false (Note: The default was true
prior to 1.3.0)</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/700-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">
<section id="bootstrap:region:common:cache-listener">
<title>Cache Listeners</title>
<para>Cache Listeners are registered with a region to handle region