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

SGF-305: Move to Asciidoctor for reference documentation

Browse Source 
First cut at migrating reference docs to asciidoctor.
This commit is contained in:
Greg Turnquist
2014-08-11 23:07:50 -05:00
committed by Oliver Gierke
parent eb9ebec574
commit d11bf5ce0e
48 changed files with 2538 additions and 3896 deletions
Download Patch File Download Diff File Expand all files Collapse all files

41
build.gradle
View File

@@ -3,7 +3,8 @@ buildscript {
maven { url 'http://repo.spring.io/plugins-release' }
}
dependencies {
classpath 'org.springframework.build.gradle:docbook-reference-plugin:0.2.4'
classpath('org.asciidoctor:asciidoctor-gradle-plugin:0.7.0')
classpath('org.asciidoctor:asciidoctor-java-integration:0.1.4.preview.1')
classpath 'org.springframework.build.gradle:spring-io-plugin:0.0.3.RELEASE'
}
}
@@ -24,8 +25,8 @@ apply plugin: "java"
apply plugin: 'eclipse'
apply plugin: 'idea'
apply from: "$rootDir/maven.gradle"
apply plugin: 'docbook-reference'
//apply plugin: 'bundlor'
apply plugin: 'asciidoctor'
if (project.hasProperty('platformVersion')) {
apply plugin: 'spring-io'
@@ -47,6 +48,31 @@ tasks.withType(Test).all {
systemProperties['org.springframework.data.gemfire.test.GemfireTestRunner.nomock'] = System.getProperty('org.springframework.data.gemfire.test.GemfireTestRunner.nomock')
}
asciidoctor {
sourceDocumentName = new File("$sourceDir/index.adoc")
outputDir = new File("$buildDir/reference/htmlsingle")
options = [
eruby: 'erubis',
attributes: [
linkcss: 'true',
copycss : 'spring.css',
icons : 'font',
'source-highlighter': 'prettify',
sectanchors : '',
toc: '',
toclevels: '4',
idprefix: '',
idseparator: '-',
doctype: 'book',
numbered: '',
version: project.version,
baseDir: "$sourceDir",
stylesheet: "spring.css",
referenceDir: "$sourceDir/reference"
]
]
}
// Common dependencies
dependencies {
// Spring Framework
@@ -151,10 +177,6 @@ task javadocJar(type: Jar) {
from javadoc
}
reference {
sourceDir = file('docs/src/reference/docbook')
}
task docsZip(type: Zip) {
group = 'Distribution'
classifier = 'docs'
@@ -168,9 +190,12 @@ task docsZip(type: Zip) {
into 'api'
}
from (reference) {
into 'reference'
from (asciidoctor.outputDir) {
include "index.html"
include "spring.css"
into 'reference/htmlsingle'
}
}
task schemaZip(type: Zip) {

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

@@ -1,20 +0,0 @@
<?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 Data GemFire Schema</title>
<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.3.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.3.xsd" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude">
<xi:fallback>
<para><emphasis>FIXME: SGF SCHEMA LOCATION/NAME CHANGED</emphasis></para>
</xi:fallback>
</xi:include>
</programlisting>
</appendix>

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

@@ -1,90 +0,0 @@
<?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">
<bookinfo>
<title>Spring Data GemFire Reference Guide</title>
<releaseinfo>${version}</releaseinfo>
<titleabbrev>Spring Data GemFire ${version}</titleabbrev>
<productname>Spring Data GemFire</productname>
<authorgroup>
<author>
<firstname>Costin</firstname>
<surname>Leau</surname>
<affiliation>SpringSource, a division of Pivotal</affiliation>
</author>
<author>
<firstname>David</firstname>
<surname>Turanski</surname>
<affiliation>SpringSource, a division of Pivotal</affiliation>
</author>
<author>
<firstname>John</firstname>
<surname>Blum</surname>
<affiliation>SpringSource, a division of Pivotal</affiliation>
</author>
<author>
<firstname>Oliver</firstname>
<surname>Gierke</surname>
<affiliation>SpringSource, a division of Pivotal</affiliation>
</author>
</authorgroup>
<legalnotice>
<para>Copies of this document may be made for your own use and for
distribution to others, provided that you do not charge any fee for such
copies and further provided that each copy contains this Copyright
Notice, whether distributed in print or electronically.</para>
</legalnotice>
<releaseinfo>
<note>
As of the 1.2.0 release, this project, formerly known as Spring GemFire, has been renamed to Spring Data GemFire to reflect that
it is now a component of the <ulink url="http://www.springsource.org/spring-data">Spring Data</ulink> project.
</note>
</releaseinfo>
</bookinfo>
<toc />
<xi:include href="preface.xml"/>
<part id="introduction">
<title>Introduction</title>
<xi:include href="introduction/introduction.xml"/>
<xi:include href="introduction/requirements.xml"/>
<xi:include href="introduction/new-features.xml"/>
</part>
<part id="reference">
<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="reference/repositories.xml"/>
<xi:include href="reference/function-annotations.xml"/>
<xi:include href="reference/gemfire-bootstrap.xml"/>
<xi:include href="reference/samples.xml"/>
</part>
<part id="resources">
<title>Other Resources</title>
<partintro>
<para>
In addition to this reference documentation, there are a number of
other resources that may help you learn how to use GemFire and Spring framework.
These additional, third-party resources are enumerated in this section.
</para>
</partintro>
<xi:include href="links.xml"/>
</part>
<part id="appendices">
<title>Appendices</title>
<xi:include href="appendix/appendix-schema.xml"/>
</part>
</book>

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

@@ -1,16 +0,0 @@
<?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 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>
</chapter>

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

@@ -1,258 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<chapter id="new-features" version="5.0" xmlns="http://docbook.org/ns/docbook">
<title>New Features</title>
<note>
As of the 1.2.0 release, this project, formerly known as Spring GemFire, has been renamed to Spring Data GemFire
to reflect that it is now a component of the
<ulink url="http://www.springsource.org/spring-data">Spring Data</ulink> project.
</note>
<section id="new-in-1-2-0">
<title>New in the 1.2.0 Release</title>
<itemizedlist>
<listitem>
<para>
Full support for GemFire configuration via 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-2-1">
<title>New in the 1.2.1 Release</title>
<itemizedlist>
<listitem>
<para>Support for the re-designed WAN Gateway in GemFire 7.0.</para>
</listitem>
</itemizedlist>
</section>
<section id="new-in-1-3-0">
<title>New in the 1.3.0 Release</title>
<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>
<section id="new-in-1-3-1">
<title>New in the 1.3.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>
<section id="new-in-1-3-2">
<title>New in the 1.3.2 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>
<section id="new-in-1-3-3">
<title>New in the 1.3.3 Release</title>
<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>
<section id="new-in-1-3-4">
<title>New in the 1.3.4 Release</title>
<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>
<section id="new-in-1-4-0">
<title>New in the 1.4.0 Release</title>
<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.
See <xref linkend="gemfire-bootstrap"/>.
</para>
</listitem>
<listitem>
<para>
Support for persisting application domain object/entities to multiple GemFire Cache Regions.
See <xref linkend="mapping.entities"/> for more details.
</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.
See <xref linkend="mapping.entities"/> for more details.
</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.
See <link linkend="bootstrap:region:common:attributes">Common Region Attributes</link>
and <xref linkend="bootstrap:region:common:regions-subregions-lookups-caution"/>
for more details.
</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>
</chapter>

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

@@ -1,11 +0,0 @@
<chapter xml:id="requirements" xmlns="http://docbook.org/ns/docbook" version="5.0">
<title>Requirements</title>
<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>

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

@@ -1,23 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<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>
</chapter>

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

@@ -1,20 +0,0 @@
<?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 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 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>

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

@@ -1,210 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<chapter id="bootstrap" version="5.0"
xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink">
<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>
<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>
</note>
<section id="bootstrap:region:spring:config">
<title>Advantages of using Spring over GemFire <literal>cache.xml</literal></title>
<para xmlns="">As of release 1.2.0, Spring Data GemFire's XML namespace
supports full configuration of the data grid. In fact, the Spring Data
GemFire namespace is considered the preferred way to configure GemFire.
GemFire will continue to support native <filename>
<literal xmlns="http://docbook.org/ns/docbook">cache.xml</literal>
</filename> for legacy reasons, but you can now do everything in Spring
XML and take advantage of the many wonderful things Spring has to offer
such as modular XML configuration, property placeholders, SpEL, and
environment profiles. Behind the namespace, Spring Data GemFire makes
extensive use of Spring's <interfacename>FactoryBean</interfacename>
pattern to simplify the creation and initialization of GemFire
components.</para>
<para xmlns=""> For example, GemFire provides several callback interfaces
such as <interfacename>
<literal xmlns="http://docbook.org/ns/docbook">CacheListener, </literal>
</interfacename><interfacename>
<literal xmlns="http://docbook.org/ns/docbook">CacheWriter, </literal>
</interfacename>and<interfacename>
<literal xmlns="http://docbook.org/ns/docbook">CacheLoader</literal>
</interfacename> to allow developers to add custom event handlers. Using
the Spring IoC container, these may configured as normal Spring beans and
injected into GemFire components. This is a significant improvement over
native <literal xmlns="http://docbook.org/ns/docbook">cache.xml</literal>
which provides relatively limited configuration options and requires
callbacks to implement GemFire's <literal>
<literal xmlns="http://docbook.org/ns/docbook">Declarable</literal>
</literal> interface (see <xref linkend="apis:declarable"
xmlns="http://docbook.org/ns/docbook"/> to see how you can still use
<literal xmlns="http://docbook.org/ns/docbook">Declarables</literal>
within Spring's DI container).</para>
<para xmlns=""> In addition, IDEs such as the Spring Tool Suite (STS)
provide excellent support for Spring XML namespaces, such as code
completion, pop-up annotations, and real time validation, making them easy
to use.</para>
</section>
<section id="bootstrap:namespace">
<title>Using the Core Spring Data GemFire Namespace</title>
<para>To simplify configuration, Spring Data GemFire provides a dedicated
XML namespace for configuring core GemFire components. It is also possible
to configure the beans directly through Spring's standard &lt;bean&gt;
definition. However, as of Spring Data GemFire 1.2.0, all bean properties
are exposed via the namespace so there is little benefit to using raw bean
definitions. For more information about XML Schema-based configuration in
Spring, see <ulink
url="http://static.springsource.org/spring/docs/current/spring-framework-reference/html/xsd-config.html">this</ulink>
appendix in the Spring Framework reference documentation.</para>
<note>
<para>Spring Data Repository support uses a separate XML namespace. See
<xref linkend="gemfire-repositories"/> for more information on how to
configure GemFire Repositories.</para>
</note>
<para>To use the Spring Data GemFire namespace, simply declare it in your
Spring XML configuration meta-data:</para>
<programlisting language="xml">&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;beans xmlns="http://www.springframework.org/schema/beans"
xmlxsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:<co id="gfe#ns#prefix"/>gfe="http://www.springframework.org/schema/gemfire"<co
id="gfe#ns#uri"/>
xsi:schemaLocation="
http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
<co id="gfe#ns#uri#loc"/>http://www.springframework.org/schema/gemfire http://www.springframework.org/schema/gemfire/spring-gemfire.xsd"&gt;
&lt;bean id ... &gt;
<co id="gfe#ns#example"/>&lt;gfe:cache ...&gt;
&lt;/beans&gt;</programlisting>
<calloutlist>
<callout arearefs="gfe#ns#prefix">
<para>Spring GemFire namespace prefix. Any name will do but through
out the reference documentation, <literal>gfe</literal> will be
used.</para>
</callout>
<callout arearefs="gfe#ns#uri">
<para>The namespace URI.</para>
</callout>
<callout arearefs="gfe#ns#uri#loc">
<para>The namespace URI location. Note that even though the location
points to an external address (which exists and is valid), Spring will
resolve the schema locally as it is included in the Spring Data
GemFire library.</para>
</callout>
<callout arearefs="gfe#ns#example">
<para>Declaration example for the GemFire namespace. Notice the prefix
usage.</para>
</callout>
</calloutlist>
<para>Once declared, the namespace elements can be declared simply by
appending the aforementioned prefix.</para>
<note>
<para>It is possible to change the default namespace, for example from
<literal>beans</literal> to <literal>gfe</literal>. This is useful for
configuration composed mainly of GemFire components as it avoids
declaring the prefix. To achieve this, simply swap the namespace prefix
declaration above:</para>
<programlisting language="xml">&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;beans xmlns="<co id="gfe#default-ns#prefix"/>http://www.springframework.org/schema/gemfire"
xmlxsi="http://www.w3.org/2001/XMLSchema-instance"
<co id="gfe#default-ns#beans-prefix"/>
xmlns:beans="http://www.springframework.org/schema/beans"
xsi:schemaLocation="
http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
http://www.springframework.org/schema/gemfire http://www.springframework.org/schema/gemfire/spring-gemfire.xsd"&gt;
<co id="gfe#default-ns#beans-example"/>&lt;beans:bean id ... &gt;
<co id="gfe#default-ns#gfe-example"/>&lt;cache ...&gt;
&lt;/beans&gt;</programlisting>
<calloutlist>
<callout arearefs="gfe#default-ns#prefix">
<para>The default namespace declaration for this XML file points to
the Spring Data GemFire namespace.</para>
</callout>
<callout arearefs="gfe#default-ns#beans-prefix">
<para>The beans namespace prefix declaration.</para>
</callout>
<callout arearefs="gfe#default-ns#beans-example">
<para>Bean declaration using the <literal>beans</literal> namespace.
Notice the prefix.</para>
</callout>
<callout arearefs="gfe#default-ns#gfe-example">
<para>Bean declaration using the <literal>gfe</literal> namespace.
Notice the lack of prefix (as the default namespace is used).</para>
</callout>
</calloutlist>
</note>
</section>
<xi:include href="cache.xml"/>
<xi:include href="data-access.xml"/>
<xi:include href="region.xml"/>
<section id="bootstrap:indicies">
<title>Creating an Index</title>
<para>GemFire allows creation on indexes (or indices) to improve the
performance of (common) queries. Spring Data GemFire allows indecies to be
declared through the <literal>index</literal> element:</para>
<programlisting language="xml">&lt;gfe:index id="myIndex" expression="someField" from="/someRegion"/&gt;</programlisting>
<para>Before creating an index, Spring Data GemFire will verify whether
one with the same name already exists. If it does, it will compare the
properties and if they don't match, will remove the old one to create a
new one. If the properties match, Spring Data GemFire will simply return
the index (in case it does not exist it will simply create one). To
prevent the update of the index, even if the properties do not match, set
the property <literal>override</literal> to false.</para>
<para>Note that index declaration are not bound to a region but rather are
top-level elements (just like <literal>gfe:cache</literal>). This allows
one to declare any number of indecies on any region whether they are just
created or already exist - an improvement versus the GemFire
<literal>cache.xml</literal>. By default the index relies on the default
cache declaration but one can customize it accordingly or use a pool (if
need be) - see the namespace schema for the full set of options.</para>
</section>
<xi:include href="diskstore.xml"/>
<xi:include href="function.xml"/>
<xi:include href="gateway.xml"/>
</chapter>

324
docs/src/reference/docbook/reference/cache.xml
View File

@@ -1,324 +0,0 @@
<?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/vfabricNoSuite/topic/com.vmware.vfabric.gemfire.7.0/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"
close="false"
lazy-init="true"
&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>
<para>The <literal>close</literal> attribute determines if the cache should be closed when the Spring application context is closed.
The default is <literal>true</literal> however for cases in which multiple application contexts use the cache (common in web applications), set this value to <literal>false</literal>.</para>
<para>The <literal>lazy-init</literal> attribute determines if the cache should be initialized before another bean references it.
The default is <literal>true</literal> however in some cases it may be convenient to set this value to <literal>false</literal>.</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/700-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/700-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/700-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.vmware.com/support/developer/vfabric-gemfire/700-api/com/gemstone/gemfire/cache/server/CacheServer.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 after 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/700-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> 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>The &lt;client-cache&gt; tag also includes a <literal>ready-for-events</literal>
attribute. If set to <literal>true</literal>, the client cache initialization will include
<ulink url="http://www.vmware.com/support/developer/vfabric-gemfire/700-api/com/gemstone/gemfire/cache/client/ClientCache.html#readyForEvents()">ClientCache.readyForEvents()</ulink>. </para>
<para>Client side configuration is covered in more detail in <xref
linkend="bootstrap:region:client"/>.</para>
</section>

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

@@ -1,134 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<section xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="apis:cq-container">
<title>GemFire Continuous Query Container</title>
<para>A powerful functionality offered by GemFire is
<ulink url="http://community.gemstone.com/display/gemfire/Continuous+Querying">continuous querying</ulink> (or CQ).
In short, CQ allows one to create a query and automatically be notified when new data that gets added to GemFire matches the query.
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 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>
<para>Currently, continuous queries are supported by GemFire only in client/server topologies. Additionally the pool used is required to have the
<literal>subscription</literal> property enabled. Please refer to the documentation for more information.</para>
</note>
<section id="apis:cq-container:containers">
<title>Continuous Query Listener Container</title>
<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>
<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 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 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>
</section>
<section id="apis:cq-container:adapter">
<title>The <classname>ContinuousQueryListenerAdapter</classname> and <interfacename>ContinuousQueryListener</interfacename></title>
<para>The <classname>ContinuousQueryListenerAdapter</classname> class is the
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="https://www.vmware.com/support/developer/vfabric-gemfire/700-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>
<programlisting language="java">public interface EventDelegate {
void handleEvent(CqEvent event);
void handleEvent(Operation baseOp);
void handleEvent(Object key);
void handleEvent(Object key, Object newValue);
void handleEvent(Throwable th);
void handleQuery(CqQuery cq);
void handleEvent(CqEvent event, Operation baseOp, byte[] deltaValue);
void handleEvent(CqEvent event, Operation baseOp, Operation queryOp, Object key, Object newValue);
}</programlisting>
<programlisting language="java">public class DefaultEventDelegate implements EventDelegate {
<lineannotation>// implementation elided for clarity...</lineannotation>
}</programlisting>
<para>In particular, note how the above implementation of the
<interfacename>EventDelegate</interfacename> interface (the above
<classname>DefaultEventDelegate</classname> class) has
<emphasis>no</emphasis> GemFire dependencies at all. It truly is a POJO that
we will make into an EDP via the following configuration (note that the class doesn't have to implement an interface,
one is present only to better show case the decoupling between contract and implementation).</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"
<lineannotation>xmlns:gfe="http://www.springframework.org/schema/gemfire"</lineannotation>
xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
<lineannotation>http://www.springframework.org/schema/gemfire http://www.springframework.org/schema/gemfire/spring-gemfire.xsd"</lineannotation>&gt;
<!-- create a client-pool that uses a pool with subscription enabled -->
&lt;gfe:client-cache pool-name="client"/&gt;
&lt;gfe:pool id="client" subscription-enabled="true"&gt;
&lt;gfe:server host="localhost" port="40404"/&gt;
&lt;/gfe:pool&gt;
&lt;gfe:cq-listener-container&gt;
&lt;!-- default handle method --&gt;
&lt;gfe:listener ref="listener" query="SELECT * from /region"/ &gt;
&lt;gfe:listener ref="another-listener" query="SELECT * from /another-region" name="my-query" method="handleQuery"/&gt;
&lt;/gfe:cq-listener-container&gt;
&lt;bean id="listener" class="gemfireexample.DefaultMessageDelegate"/&gt;
&lt;bean id="another-listener" class="gemfireexample.DefaultMessageDelegate"/&gt;
...
&lt;beans&gt;</programlisting>
<note>The example above shows some of the various forms that a listener can have; at its minimum the listener reference and the actual query definition are required. It's possible however to specify
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 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>
<emphasis role="bold">&lt;bean id="eventListener" class="org.springframework.data.gemfire.listener.adapter.ContinuousQueryListenerAdapter"&gt;</emphasis>
&lt;constructor-arg&gt;
&lt;bean class="gemfireexample.DefaultEventDelegate"/&gt;
&lt;/constructor-arg&gt;
&lt;/bean&gt;
<lineannotation>&lt;!-- and this is the event listener container... --&gt;</lineannotation>
&lt;bean id="gemfireListenerContainer" class="org.springframework.data.gemfire.listener.ContinuousQueryListenerContainer"&gt;
&lt;property name="cache" ref="gemfireCache"/&gt;
&lt;property name="queryListeners"&gt;
<lineannotation>&lt;!-- set of listeners --&gt;</lineannotation>
&lt;set&gt;
&lt;bean class="org.springframework.data.gemfire.listener.ContinuousQueryDefinition" &gt;
&lt;constructor-arg value="SELECT * from /region" /&gt;
&lt;constructor-arg ref="eventListener" /&gt;
&lt;/bean&gt;
&lt;/set&gt;
&lt;/property&gt;
&lt;/bean&gt;</programlisting>
<para>Each time an event is received, the adapter automatically performs
type translation between the GemFire event and the required method argument(s) transparently. Any exception caused by the method invocation
is caught and handled by the container (by default, being logged).
</para>
</section>
</section>

52
docs/src/reference/docbook/reference/data-access.xml
View File

@@ -1,52 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<section id="data-access" 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">
<title>Using the GemFire Data Access Namespace</title>
<para>In addition to the core <literal>gfe</literal> namespace, Spring Data
GemFire provides a <literal>gfe-data</literal> namespace intended primarily
to simplify the development of GemFire client applications. This namespace
currently supports for GemFire <link
linkend="gemfire-repositories">repositories</link> and function <link
linkend="function-execution">execution</link> and a
<tag>&lt;datasource&gt;</tag> tag that offers a convenient way to connect to
the data grid. </para>
<section id="data-access:datasource">
<title>An Easy Way to Connect to GemFire </title>
<para>For many applications, A basic connection to a GemFire grid, using
default values is sufficient. Spring Data GemFire's <tag>&lt;datasource&gt;</tag> tag
provides a simple way to access data. The data source creates a client
cache and connection pool. In addition, it will query the member servers
for all existing root regions and create a proxy (empty) client region for
each one. </para>
<programlisting language="xml">&lt;gfe-data:datasource&gt;
&lt;locator host="somehost" port="1234"/&gt;
&lt;/gfe-data:datasource&gt;</programlisting>
<para>The datasource tag is synactically similar to <tag>&lt;gfe:pool&gt;</tag>.
It may be configured with one or more locator or server tags to connect to
an existing data grid. Additionally, all attributes available to configure
a pool are supported. This configuration will automatically create
ClientRegion beans for each region defined on members connected to the
locator, so they may be seamlessly referenced by Spring Data mapping
annotations, GemfireTemplate, and wired into application
classes.</para>
<para>Of course, you can explicitly configure client regions. For
example, if you want to cache data in local memory:
<programlisting
language="xml">&lt;gfe-data:datasource&gt;
&lt;locator host="somehost" port="1234"/&gt;
&lt;/gfe-data:datasource&gt;
&lt;gfe:client-region id="Customer" shortcut="CACHING_PROXY"/&gt;</programlisting></para>
</section>
</section>

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

@@ -1,355 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<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 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>
<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>
The template class requires a GemFire <interfacename>Region</interfacename> instance and once configured is
thread-safe and should be reused across multiple classes:
</para>
<programlisting language="xml">&lt;bean id="gemfireTemplate" class="org.springframework.data.gemfire.GemfireTemplate" p:region-ref="someRegion"/&gt;</programlisting>
<para>
Once the template is configured, one can use it alongside <interfacename>GemfireCallback</interfacename>
to work directly with the GemFire <interfacename>Region</interfacename>, without having to deal with
checked exceptions, threading or resource management concerns:
</para>
<programlisting language="java">template.execute(new GemfireCallback&lt;Iterable&lt;String&gt;&gt;() {
public Iterable&lt;String&gt; doInGemfire(Region reg) throws GemFireCheckedException, GemFireException {
// working against a Region of String
Region&lt;String, String&gt; region = reg;
region.put("1", "one");
region.put("3", "three");
return region.query("length &lt; 5");
}
});</programlisting>
<para>
For accessing the full power of the GemFire query language, one can use the <methodname>find</methodname>
and <methodname>findUnique</methodname> which, as 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 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">
<!-- turn on declarative caching -->
<cache:annotation-driven/>
<gfe:cache id="gemfire-cache"/>
<!-- declare GemFire Cache Manager -->
<bean id="cacheManager" class="org.springframework.data.gemfire.support.GemfireCacheManager" p:cache-ref="gemfire-cache">
</beans>]]></programlisting>
</section>
<section id="apis:tx-mgmt">
<title>Transaction Management</title>
<para>
One of the most popular features of Spring Framework is
<ulink url="http://static.springsource.org/spring/docs/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>
<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 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>
<para>GemFire XML configuration (usually named
<literal>cache.xml</literal> allows <emphasis>user</emphasis> objects to
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 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 objects.</para>
<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
presented in this section. See the following sidebar for more information
on this approach.</para>
<sidebar>
<title>Eliminate <interfacename>Declarable</interfacename>
components</title>
<para>One can configure custom types entirely through Spring as
mentioned in <xref linkend="bootstrap:region" />. That way, one does not
have to implement the <interfacename>Declarable</interfacename>
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>
<para>As an example of configuring a
<interfacename>Declarable</interfacename> component using Spring, consider
the following declaration (taken from the
<interfacename>Declarable</interfacename> javadoc):</para>
<programlisting language="xml">&lt;cache-loader&gt;
&lt;class-name&gt;com.company.app.DBLoader&lt;/class-name&gt;
&lt;parameter name="URL"&gt;
&lt;string&gt;jdbc://12.34.56.78/mydb&lt;/string&gt;
&lt;/parameter&gt;
&lt;/cache-loader&gt;</programlisting>
<para>To simplify the task of parsing, converting the parameters and
initializing the object, 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
Spring container. To take advantage of this feature, the user objects need
to extend <classname>WiringDeclarableSupport</classname> which
automatically locates the declaring
<interfacename>BeanFactory</interfacename> and performs wiring as part of
the initialization process.</para>
<sidebar>
<title>Why is a base class needed?</title>
<para>In the current GemFire release there is no concept of an
<emphasis>object factory</emphasis> and the types declared are
instantiated and used as is. 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
first locate an existing bean definition and use that as wiring
template. Unless specified, the component class name will be used as an
implicit bean definition name. Let's see how our
<classname>DBLoader</classname> declaration would look in that
case:</para>
<programlisting language="java">public class DBLoader extends WiringDeclarableSupport implements CacheLoader {
private DataSource dataSource;
public void setDataSource(DataSource ds){
this.dataSource = ds;
}
public Object load(LoaderHelper helper) { ... }
}</programlisting>
<programlisting language="xml">&lt;cache-loader&gt;
&lt;class-name&gt;com.company.app.DBLoader&lt;/class-name&gt;
&lt;!-- no parameter is passed (use the bean implicit name
that is the class name) --&gt;
&lt;/cache-loader&gt;</programlisting>
<programlisting language="xml">&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:p="http://www.springframework.org/schema/p"
xsi:schemaLocation="http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans.xsd"&gt;
&lt;bean id="dataSource" ... /&gt;
&lt;!-- template bean definition --&gt;
&lt;bean id="com.company.app.DBLoader" abstract="true" p:dataSource-ref="dataSource"/&gt;
&lt;/beans&gt;</programlisting>
<para>In the scenario above, as no parameter was specified, a bean with
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>
<programlisting language="xml">&lt;cache-loader&gt;
&lt;class-name&gt;com.company.app.DBLoader&lt;/class-name&gt;
&lt;!-- pass the bean definition template name
as parameter --&gt;
&lt;parameter name="bean-name"&gt;
&lt;string&gt;template-bean&lt;/string&gt;
&lt;/parameter&gt;
&lt;/cache-loader&gt;</programlisting>
<programlisting language="xml">&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:p="http://www.springframework.org/schema/p"
xsi:schemaLocation="http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans.xsd"&gt;
&lt;bean id="dataSource" ... /&gt;
&lt;!-- template bean definition --&gt;
&lt;bean id="template-bean" abstract="true" p:dataSource-ref="dataSource"/&gt;
&lt;/beans&gt;</programlisting>
<note>
<para>The <emphasis>template</emphasis> bean definitions do not have
to be declared in XML - any format is allowed (Groovy, annotations,
etc..).</para>
</note>
</section>
<section id="apis:declarable:autowiring">
<title>Configuration using auto-wiring and annotations</title>
<para>If no bean definition is found, by default,
<classname>WiringDeclarableSupport</classname> will <ulink
url="http://static.springsource.org/spring/docs/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/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>
<para>For example, the hypothetical <literal>DBLoader</literal>
declaration above can be injected with a Spring-configured
<interface>DataSource</interface> in the following way:</para>
<programlisting language="java">public class DBLoader extends WiringDeclarableSupport implements CacheLoader {
// use annotations to 'mark' the needed dependencies
@javax.inject.Inject
private DataSource dataSource;
public Object load(LoaderHelper helper) { ... }
}</programlisting>
<programlisting language="xml">&lt;cache-loader&gt;
&lt;class-name&gt;com.company.app.DBLoader&lt;/class-name&gt;
&lt;!-- no need to declare any parameters anymore
since the class is auto-wired --&gt;
&lt;/cache-loader&gt;</programlisting>
<programlisting language="xml">&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:context="http://www.springframework.org/schema/context"
xsi:schemaLocation="http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans.xsd
http://www.springframework.org/schema/context
http://www.springframework.org/schema/context/spring-context.xsd"&gt;
&lt;!-- enable annotation processing --&gt;
&lt;context:annotation-config/&gt;
&lt;/beans&gt;</programlisting>
<para>By using the JSR-330 annotations, the cache loader code has been
simplified since the location and creation of the DataSource has been
externalized and the user code is concerned only with the loading
process. The <interfacename>DataSource</interfacename> might be
transactional, created lazily, shared between multiple objects or
retrieved from JNDI - these aspects can be easily configured and changed
through the Spring container without touching the
<classname>DBLoader</classname> code.</para>
</section>
</section>
</chapter>

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

@@ -1,38 +0,0 @@
<?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>

318
docs/src/reference/docbook/reference/function-annotations.xml
View File

@@ -1,318 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<chapter id="function-annotations">
<title>Annotation Support for Function Execution</title>
<section>
<title>Introduction</title>
<para>Spring Data GemFire 1.3.0 introduces annotation support to simplify
working with <ulink
url="http://pubs.vmware.com/vfabricNoSuite/index.jsp?topic=/com.vmware.vfabric.gemfire.7.0/developing/function_exec/chapter_overview.html??">GemFire
function execution</ulink>. The GemFire API provides classes to implement
and register <ulink
url="https://www.vmware.com/support/developer/vfabric-gemfire/700-api/com/gemstone/gemfire/cache/execute/Function.html">Functions</ulink>
deployed to cache servers that may be invoked remotely by member
applications, typically cache clients. Functions may execute in parallel,
distributed among multiple servers, combining results in a map-reduce
pattern, or may be targeted to a single server. A Function execution may
be also be targeted to a specific region. </para>
<para>GemFire's also provides APIs to support remote execution of
functions targeted to various defined scopes (region, member groups,
servers, etc.) and the ability to aggregate results. The API also provides
certain runtime options. The implementation and execution of remote
functions, as with any RPC protocol, requires some boilerplate code.
Spring Data GemFire, true to Spring's core value proposition, aims to hide
the mechanics of remote function execution and allow developers to focus
on POJO programming and business logic. To this end, Spring Data GemFire
introduces annotations to declaratively register public methods as
functions, and the ability to invoke registered functions remotely via
annotated interfaces.</para>
</section>
<section>
<title>Implementation vs Execution</title>
<para>There are two separate concerns to address. First is the function
implementation (server) which must interact with the <ulink
url="https://www.vmware.com/support/developer/vfabric-gemfire/700-api/com/gemstone/gemfire/cache/execute/FunctionContext.html">FunctionContext</ulink>
to obtain the invocation arguments, the <ulink
url="https://www.vmware.com/support/developer/vfabric-gemfire/700-api/com/gemstone/gemfire/cache/execute/ResultSender.html">ResultsSender</ulink>
and other execution context information. The function implementation
typically accesses the Cache and or Region and is typically registered
with the <ulink
url="https://www.vmware.com/support/developer/vfabric-gemfire/700-api/com/gemstone/gemfire/cache/execute/FunctionService.html">FunctionService</ulink>
under a unique Id. The application invoking a function (the client) does
not depend on the implementation. To invoke a function remotely, the
application instantiates an <ulink
url="https://www.vmware.com/support/developer/vfabric-gemfire/700-api/com/gemstone/gemfire/cache/execute/Execution.html">Execution</ulink>
providing the function ID, invocation arguments, the function target or
scope (region, server, servers, member, members). If the function produces
a result, the invoker uses a <ulink
url="https://www.vmware.com/support/developer/vfabric-gemfire/700-api/com/gemstone/gemfire/cache/execute/ResultCollector.html">ResultCollector</ulink>
to aggregate and acquire the execution results. In certain scenarios, a
custom ResultCollector implementation is required and may be registered
with the Execution. </para>
<note>
<para>'Client' and 'Server' are used here in the context of function
execution which may have a different meaning then client and server in a
client-server cache topology. While it is common for a member with a
Client Cache to invoke a function on one or more Cache Server members it
is also possible to execute functions in a peer-to-peer
configuration</para>
</note>
</section>
<section>
<title>Implementing a Function</title>
<para>Using GemFire APIs, the FunctionContext provides a runtime
invocation context including the client's calling arguments and a
ResultSender interface to send results back to the client. Additionally,
if the function is executed on a Region, the FunctionContext is an
instance of RegionFunctionContext which provides additional context such
as the target Region and any Filter (set of specific keys) associated with
the Execution. If the Region is a Partition Region, the function should
use the PartitonRegionHelper to extract only the local data. </para>
<para>Using Spring, one can write a simple POJO and enable the Spring
container bind one or more of it's public methods to a Function. The
signature for a POJO method intended to be used as a function must
generally conform to the the client's execution arguments. However, in the
case of a region execution, the region data must also be provided
(presumably the data held in the local partition if the region is a
partition region). Additionally the function may require the filter that
was applied, if any. This suggests that the client and server may share a
contract for the calling arguments but that the method signature may
include additional parameters to pass values provided by the
FunctionContext. One possibility is that the client and server share a
common interface, but this is not required. The only constraint is that
the method signature includes the same sequence of calling arguments with
which the function was invoked after the additional parameters are
resolved. For example, suppose the client provides a String and int as the
calling arguments. These are provided by the FunctionContext as an
array:</para>
<para><code language="java">Object[] args = new Object[]{"hello",
123}</code></para>
<para>Then the Spring container should be able to bind to any method
signature similar to the following. Let's ignore the return type for the
moment:</para>
<para><programlisting language="java">public Object method1(String s1, int i2) {...}
public Object method2(Map&lt;?,?&gt; data, String s1, int i2) {...}
public Object method3(String s1, Map&lt;?,?&gt;data, int i2) {...}
public Object method4(String s1, Map&lt;?,?&gt; data, Set&lt;?&gt; filter, int i2) {...}
public void method4(String s1, Set&lt;?&gt; filter, int i2, Region&lt;?,?&gt; data) {...}
public void method5(String s1, ResultSender rs, int i2);
public void method6(FunctionContest fc);</programlisting>The general rule is
that once any additional arguments, i.e., region data and filter, are
resolved the remaining arguments must correspond exactly, in order and
type, to the expected calling parameters. The method's return type must be
void or a type that may be serialized (either java.io.Serializable,
DataSerializable, or PDX serializable). The latter is also a requirement
for the calling arguments. The Region data should normally be defined as a
Map, to facilitate unit testing, but may also be of type Region if
necessary. As shown in the example above, it is also valid to pass the
FunctionContext itself, or the ResultSender, if you need to control how
the results are returned to the client.</para>
<section>
<title>Annotations for Function Implementation</title>
<para>The following example illustrates how annotations are used to
expose a POJO as a GemFire function:</para>
<para><programlisting language="java">@Component
public class MyFunctions {
@GemfireFunction
public String function1(String s1, @RegionData Map&lt;?,?&gt; data, int i2) { ... }
@GemfireFunction("myFunction", HA=true, optimizedForWrite=true, batchSize=100)
public List&lt;String&gt; function2(String s1, @RegionData Map&lt;?,?&gt; data, int i2, @Filter Set&lt;?&gt; keys) { ... }
@GemfireFunction(hasResult=true)
public void functionWithContext(FunctionContext functionContext) { ... }
} </programlisting>Note that the class itself must be registered as a Spring
bean. Here the <literal>@Component</literal> annotation is used, but you
may register the bean by any method provided by Spring (e.g. XML
configuration or Java configuration class). This allows the Spring
container to create an instance of this class and wrap it in a <ulink
url="https://github.com/SpringSource/spring-gemfire/blob/master/src/main/java/org/springframework/data/gemfire/function/PojoFunctionWrapper.java">PojoFunctionWrapper</ulink>(PFW).
Spring creates one PFW instance for each method annotated with
<literal>@GemfireFunction</literal>. Each will all share the same target
object instance to invoke the corresponding method. </para>
<note>
<para>The fact that the function class is a Spring bean may offer
other benefits since it shares the application context with GemFire
components such as a Cache and Regions. These may be injected into the
class if necessary.</para>
</note>
<para>Spring creates the wrapper class, and registers the function with
GemFire's Function Service. The function id used to register the
functions must be unique. By convention it defaults to the simple
(unqualified) method name. Note that this annotation also provides
configuration attributes, <literal>HA</literal> and
<literal>optimizedForWrite</literal> which correspond to properties
defined by GemFire's Function interface. If the method's return type is
void, then the <literal>hasResult</literal> property is automatically
set to <literal>false</literal>; otherwise it is
<literal>true</literal>. </para>
<para>For <literal>void</literal> return types, the annotation provides
a <literal>hasResult</literal> attribute that can be set to true to
override this convention, as shown in the
<literal>functionWithContext</literal> method above. Presumably, the
intention is to use the ResultSender directly to send results to the
caller. </para>
<para>The PFW implements GemFire's Function interface, binds the method
parameters, and invokes the target method in its
<literal>execute()</literal> method. It also sends the method's return
value using the ResultSender. </para>
<section>
<title>Batching Results</title>
<para>If the return type is a Collection or Array, then some
consideration must be given to how the results are returned. By
default, the PFW returns the entire collection at once. If the number
of items is large, this may incur a performance penalty. To divide the
payload into small sections (sometimes called chunking), you can set
the <literal>batchSize</literal> attribute, as illustrated in
<literal>function2</literal>, above. <note>
<para>If you need more control of the ResultSender, especially if
the method itself would use too much memory to create the
collection, you can pass the ResultSender, or access it via the
FunctionContext, to use it directly within the method.</para>
</note></para>
</section>
<section>
<title>Enabling Annotation Processing</title>
<para>In accordance with Spring standards, you must explicitly
activate annotation processing for @GemfireFunction using XML: </para>
<programlisting language="xml"> &lt;gfe:annotation-driven/&gt;</programlisting>
<para>or by annotating a Java configuration class:</para>
<programlisting language="java"> @EnableGemfireFunctions</programlisting>
</section>
</section>
</section>
<section id="function-execution">
<title>Executing a Function</title>
<para>A process invoking a remote function needs to provide calling
arguments, a function id, the execution target (onRegion, onServers,
onServer, onMember, onMembers) and optionally a Filter set. All you need
to do is define an interface supported by annotations. Spring will create
a dynamic proxy the interface which will use the FunctionService to create
an Execution, invoke the execution and coerce the results to a defined
return type, if necessary. This technique is very similar to the way
Spring Data repositories work, thus some of the configuration and concepts
should be familiar. Generally a single interface definition maps to
multiple function executions, one corresponding to each method defined in
the interface.</para>
<section>
<title>Annotations for Function Execution</title>
<para>To support client side function execution, the following
annotations are provided: <literal>@OnRegion</literal>,
<literal>@OnServer</literal>, <literal>@OnServers</literal>,
<literal>@OnMember</literal>, <literal>@OnMembers</literal>. These
correspond to the Execution implementations GemFire's FunctionService
provides. Each annotation exposes the appropriate attributes. These
annotations also provide an optional <literal>resultCollector</literal>
attribute whose value is the name of a Spring bean implementing <ulink
url="https://www.vmware.com/support/developer/vfabric-gemfire/700-api/com/gemstone/gemfire/cache/execute/ResultCollector.html">ResultCollector</ulink>
to use for the execution. </para>
<note>
<para>The proxy interface binds all declared methods to the same
execution configuration. Although it is expected that single method
interfaces will be common, all methods in the interface are backed by
the same proxy instance and therefore are all share the same
configuration.</para>
</note>
<para>Here are some examples:</para>
<programlisting language="java">@OnRegion(region="someRegion", resultCollector="myCollector")
public interface FunctionExecution {
@FunctionId("function1")
public String doIt(String s1, int i2);
public String getString(Object arg1, @Filter Set&lt;Object&gt; keys) ;
}</programlisting>
<para>By default, the function id is the simple (unqualified) method
name. <literal>@FunctionId</literal> is used to bind this invocation to
a different function id. </para>
<section>
<title>Enabling Annotation Processing</title>
<para>The client side uses Spring's component scanning capability to
discover annotated interfaces. To enable function execution annotation
processing, you can use XML:</para>
<programlisting language="xml">&lt;gfe-data:function-executions base-package="org.example.myapp.functions"/&gt;</programlisting>
<para>Note that the <literal>function-executions</literal> tag is
provided in the <literal>gfe-data</literal> namespace. The
<literal>base-package</literal> attribute is required to avoid
scanning the entiire class path. Additional filters are provided as
described in the Spring <ulink
url="http://static.springsource.org/spring/docs/current/spring-framework-reference/html/beans.html#beans-scanning-filters">reference</ulink>.</para>
<para>Or annotate your Java configuration class:</para>
<programlisting language="java"> @EnableGemfireFunctionExecutions(basePackages = "org.example.myapp.functions")</programlisting>
</section>
</section>
</section>
<section>
<title>Programmatic Function Execution</title>
<para>Using the annotated interface as described in the previous section,
simply wire your interface into a bean that will invoke the function:
</para>
<programlisting language="java">@Component
public class MyApp {
@Autowired FunctionExecution functionExecution;
public void doSomething() {
functionExecution.doIt("hello", 123);
}
}</programlisting>
<para>Alternately, you can use a Function Execution template directly. For
example GemfireOnRegionFunctionTemplate creates an onRegion execution. For
example:</para>
<para><programlisting language="java">Set&lt;?,?&gt; myFilter = getFilter();
Region&lt;?,?&gt; myRegion = getRegion();
GemfireOnRegionOperations template = new GemfireOnRegionFunctionTemplate(myRegion);
String result = template.executeAndExtract("someFunction",myFilter,"hello","world",1234);</programlisting>Internally,
function executions always return a List.
<literal>executeAndExtract</literal> assumes a singleton list containing
the result and will attempt to coerce that value into the requested type.
There is also an <literal>execute</literal> method that returns the List
itself. The first parameter is the function id. The filter argument is
optional. The following arguments are a variable argument list. </para>
</section>
</chapter>

33
docs/src/reference/docbook/reference/function.xml
View File

@@ -1,33 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<section id="bootstrap:function" 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">
<title>Configuring GemFire's Function Service</title>
<para>As of Release 1.3.0, Spring Data GemFire provides <link linkend="function-annotations">annotation</link> support
for implementing and registering functions. Spring Data GemFire also provides
namespace support for registering GemFire <ulink
url="https://www.vmware.com/support/developer/vfabric-gemfire/700-api/com/gemstone/gemfire/cache/execute/Function.html">Functions</ulink>
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>

119
docs/src/reference/docbook/reference/gateway.xml
View File

@@ -1,119 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<section id="bootstrap:gateway" 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">
<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 examples:</para>
<section><title>WAN Configuration in GemFire 7.0</title>
<para>
GemFire 7.0 introduces new APIs for WAN configuration. While the original APIs provided
in GemFire 6 are still supported, it is recommended that you use the new
APIs if you are using GemFire 7.0. The Spring Data GemFire namespace
supports either. In the example below, <literal>GatewaySender</literal>s are configured for a
partitioned region by adding child elements to the region (<literal>gateway-sender</literal>
and <literal>gateway-sender-ref</literal>). The <literal>GatewaySender</literal> may register
<literal>EventFilter</literal>s and
<literal>TransportFilters</literal>. Also shown below is an example configuration of an
<literal>AsyncEventQueue</literal> which must also be wired into a region (not shown).
</para>
<programlisting language="xml">&lt;gfe:partitioned-region id="region-inner-gateway-sender" &gt;
&lt;gfe:gateway-sender
remote-distributed-system-id="1"&gt;
&lt;gfe:event-filter&gt;
&lt;bean class="org.springframework.data.gemfire.example.SomeEventFilter"/&gt;
&lt;/gfe:event-filter&gt;
&lt;gfe:transport-filter&gt;
&lt;bean class="org.springframework.data.gemfire.example.SomeTransportFilter"/&gt;
&lt;/gfe:transport-filter&gt;
&lt;/gfe:gateway-sender&gt;
&lt;gfe:gateway-sender-ref bean="gateway-sender"/&gt;
&lt;/gfe:partitioned-region&gt;
&lt;gfe:async-event-queue id="async-event-queue" batch-size="10" persistent="true" disk-store-ref="diskstore"
maximum-queue-memory="50"&gt;
&lt;gfe:async-event-listener&gt;
&lt;bean class="org.springframework.data.gemfire.example.SomeAsyncEventListener"/&gt;
&lt;/gfe:async-event-listener&gt;
&lt;/gfe:async-event-queue&gt;
&lt;gfe:gateway-sender id="gateway-sender" remote-distributed-system-id="2"&gt;
&lt;gfe:event-filter&gt;
&lt;ref bean="event-filter"/&gt;
&lt;bean class="org.springframework.data.gemfire.example.SomeEventFilter"/&gt;
&lt;/gfe:event-filter&gt;
&lt;gfe:transport-filter&gt;
&lt;ref bean="transport-filter"/&gt;
&lt;bean class="org.springframework.data.gemfire.example.SomeTransportFilter"/&gt;
&lt;/gfe:transport-filter&gt;
&lt;/gfe:gateway-sender&gt;
&lt;bean id="event-filter" class="org.springframework.data.gemfire.example.AnotherEventFilter"/&gt;
&lt;bean id="transport-filter" class="org.springframework.data.gemfire.example.AnotherTransportFilter"/&gt;
</programlisting>
<para>On the other end of a <literal>GatewaySender</literal> is a corresponding
<literal>GatewayReceiver</literal>
to receive gateway events. The <literal>GatewayReceiver</literal> may also be configured with
<literal>EventFilter</literal>s and <literal>TransportFilter</literal>s.</para>
<programlisting language="xml">&lt;gfe:gateway-receiver id="gateway-receiver"
start-port="12345" end-port="23456" bind-address="192.168.0.1"&gt;
&lt;gfe:transport-filter&gt;
&lt;bean class="org.springframework.data.gemfire.example.SomeTransportFilter"/&gt;
&lt;/gfe:transport-filter&gt;
&lt;/gfe:gateway-receiver&gt;</programlisting>
<para>Please refer to the GemFire product document for a detailed
explanation of all the configuration options.</para>
</section>
<section>
<title>WAN Configuration in GemFire 6.6</title>
<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>
</section>

196
docs/src/reference/docbook/reference/gemfire-bootstrap.xml
View File

@@ -1,196 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<chapter id="gemfire-bootstrap" version="5.0" xmlns="http://docbook.org/ns/docbook">
<title>Bootstrapping a Spring ApplicationContext in GemFire</title>
<section>
<title id="gemfire-bootstrap:intro">Introduction</title>
<para>
Normally, a Spring-based application will <link linkend="bootstrap">bootstrap GemFire</link> using
Spring Data GemFire's XML namespace. Just by specifying a <literal>&lt;gfe:cache/&gt;</literal> element
in Spring Data GemFire configuration meta-data, a single, peer GemFire Cache instance will be created
and initialized with 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 provided 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>.
Using <emphasis>Gfsh</emphasis>, even though the application and GemFire will share the same JVM process,
GemFire will 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 occurs after all the other GemFire components
and configuration have 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>
In order for your GemFire application component to be auto-wired by the Spring container, create a
application class that extends the <classname>LazyWiringDeclarableSupport</classname> and annotate
any class member that needs to be provided as a Spring bean dependency, similar to:
</para>
<programlisting language="java"><![CDATA[
public static final class UserDataSourceCacheLoader extends LazyWiringDeclarableSupport implements CacheLoader<String, User> {
@Autowired
private DataSource userDataSource;
...
}
]]></programlisting>
<para>
As implied by the CacheLoader example above, 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>

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

@@ -1,46 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<chapter id="ref-introduction" version="5.0" 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>
<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="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="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 annotations.
</para>
<para>
<xref linkend="gemfire-bootstrap"/> describes how to bootstrap a Spring ApplicationContext running
in a GemFire Server using Gfsh.
</para>
<para>
<xref linkend="samples"/> describes the samples provided with the distribution to illustrate
the various features available in Spring Data GemFire.
</para>
</chapter>

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

@@ -1,126 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<chapter id="mapping" version="5.0" xmlns="http://docbook.org/ns/docbook">
<title>POJO mapping</title>
<section xml:id="mapping.entities">
<title>Entity Mapping</title>
<para>
Spring Data GemFire provides support to map entities that will be stored in a GemFire data grid.
The mapping metadata is defined using annotations at the domain classes just like this:
</para>
<example>
<title>Mapping a domain class to a GemFire Region</title>
<programlisting language="java">@Region("People")
public class Person {
@Id Long id;
String firstname;
String lastname;
@PersistenceConstructor
public Person(String firstname, String lastname) {
// …
}
…
}
</programlisting>
</example>
<para>
The first thing you see here is the <interfacename>@Region</interfacename> annotation that can be used to
customize the Region in which the <classname>Person</classname> class is stored in. The
<interfacename>@Id</interfacename> annotation can be used to annotate the property that shall be used as
the Cache key. The <interfacename>@PersistenceConstructor</interfacename> annotation actually 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>
<para>
In addition to storing entities in top-level Regions, entities can be stored in GemFire Sub-Regions, as so:
</para>
<programlisting language="java">@Region("/Users/Admin")
public class Admin extends User {
…
}
@Region("/Users/Guest")
public class Guest extends User {
...
}
</programlisting>
<para>
Be sure to use the full-path of the GemFire Region, as defined in Spring Data GemFire XML namespace
configuration meta-data, as specified in the <literal>id</literal> or <literal>name</literal> attributes
of the <literal>&lt;*-region&gt;</literal> bean definition.
</para>
<para>
As alternative to specifying the Region in which the entity will be stored using the
<interfacename>@Region</interfacename> annotation on the entity class, you can also specify the
<interfacename>@Region</interfacename> annotation on the entity's <interfacename>Repository</interfacename>
abstraction. See <xref linkend="gemfire-repositories"/> for more details.
</para>
<para>
However, let's say you want to store a Person in multiple GemFire Regions (e.g. <literal>People</literal>
and <literal>Customers</literal>), then you can define your corresponding <interfacename>Repository</interfacename>
interface abstractions like so:
</para>
<programlisting language="java"><![CDATA[@Region("People")
public interface PersonRepository extends GemfireRepository<Person, String> {
…
}
@Region("Customers")
public interface CustomerRepository extends GemfireRepository<Person, String> {
...
}
]]></programlisting>
</section>
<section xml:id="mapping.pdx-serializer">
<title>Mapping PDX Serializer</title>
<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
<interfacename>EntityInstantiator</interfacename> abstraction. By default
the serializer uses a <classname>ReflectionEntityInstantiator</classname>
that will use the persistence constructor of the mapped entity (either the
single declared one or explicitly annoted with
<interfacename>@PersistenceConstructor</interfacename>). To provide values
for constructor parameters it will read fields with name of the
constructor parameters from the <interfacename>PDXReader</interfacename>
supplied.</para>
<example>
<title>Using @Value on entity constructor parameters</title>
<programlisting language="java">public class Person {
public Person(@Value("#root.foo") String firstname, @Value("bean") String lastname) {
// …
}
} </programlisting>
</example>
<para>The entity annotated as such will get the field <code>foo</code>
read from the <interfacename>PDXReader</interfacename> and handed as
constructor parameter value for <code>firstname</code>. The value for
<code>lastname</code> will be the Spring bean with name
<code>bean</code>.</para>
</section>
</chapter>

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

File diff suppressed because it is too large Load Diff

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

@@ -1,229 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<chapter version="5.0" xml:id="gemfire-repositories"
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/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>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 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
namespace:</para>
<example>
<title>Bootstrap GemFire repositories</title>
<programlisting language="xml">&lt;beans xmlns="http://www.springframework.org/schema/beans"
xmlns:gfe-data="http://www.springframework.org/schema/data/gemfire"
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/data/gemfire
http://www.springframework.org/schema/data/gemfire/spring-data-gemfire.xsd&gt;
&lt;gfe-data:repositories base-package="com.acme.repository" /&gt;
&lt;/beans&gt;</programlisting>
</example>
<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>.
Note that you have to have your domain classes correctly mapped to
configured regions as the bottstrap process will fail otherwise.</para>
</section>
<section xml:id="gemfire-repositories.executing-queries">
<title>Executing OQL queries</title>
<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>
<example>
<title>Sample repository</title>
<programlisting language="java">@Region("myRegion")
public class Person { … }</programlisting>
<programlisting language="java">public interface PersonRepository extends CrudRepository&lt;Person, Long&gt; {
Person findByEmailAddress(String emailAddress);
Collection&lt;Person&gt; findByFirstname(String firstname);
@Query("SELECT * FROM /Person p WHERE p.firstname = $1")
Collection&lt;Person&gt; findByFirstnameAnnotated(String firstname);
@Query("SELECT * FROM /Person p WHERE p.firstname IN SET $1")
Collection&lt;Person&gt; findByFirstnamesAnnotated(Collection&lt;String&gt; firstnames);
}</programlisting>
</example>
<para>The first method listed here will cause the following query to be
derived: <code>SELECT x FROM /myRegion x WHERE x.emailAddress = $1</code>.
The second method works the same way except it's returning all entities
found whereas the first one expects a single result value. In case the
supported keywords are not sufficient to declare your query or the method
name gets to verbose you can annotate the query methods with
<interfacename>@Query</interfacename> as seen for methods 3 and 4.</para>
<para><table>
<title>Supported keywords for query methods</title>
<tgroup cols="3">
<colspec colwidth="1*"/>
<colspec colwidth="2*"/>
<colspec colwidth="2*"/>
<thead>
<row>
<entry>Keyword</entry>
<entry>Sample</entry>
<entry>Logical result</entry>
</row>
</thead>
<tbody>
<row>
<entry><literal>GreaterThan</literal></entry>
<entry><methodname>findByAgeGreaterThan(int
age)</methodname></entry>
<entry><code>x.age &gt; $1</code></entry>
</row>
<row>
<entry><literal>GreaterThanEqual</literal></entry>
<entry><methodname>findByAgeGreaterThanEqual(int
age)</methodname></entry>
<entry><code>x.age &gt;= $1</code></entry>
</row>
<row>
<entry><literal>LessThan</literal></entry>
<entry><methodname>findByAgeLessThan(int
age)</methodname></entry>
<entry><code>x.age &lt; $1</code></entry>
</row>
<row>
<entry><literal>LessThanEqual</literal></entry>
<entry><methodname>findByAgeLessThanEqual(int
age)</methodname></entry>
<entry><code>x.age &lt;= $1</code></entry>
</row>
<row>
<entry><literal>IsNotNull</literal>,
<literal>NotNull</literal></entry>
<entry><methodname>findByFirstnameNotNull()</methodname></entry>
<entry><code>x.firstname =! NULL</code></entry>
</row>
<row>
<entry><literal>IsNull</literal>,
<literal>Null</literal></entry>
<entry><methodname>findByFirstnameNull()</methodname></entry>
<entry><code>x.firstname = NULL</code></entry>
</row>
<row>
<entry><literal>In</literal></entry>
<entry><methodname>findByFirstnameIn(Collection&lt;String&gt;
x)</methodname></entry>
<entry><code>x.firstname IN SET $1</code></entry>
</row>
<row>
<entry><literal>NotIn</literal></entry>
<entry><methodname>findByFirstnameNotIn(Collection&lt;String&gt;
x)</methodname></entry>
<entry><code>x.firstname NOT IN SET $1</code></entry>
</row>
<row>
<entry>(No keyword)</entry>
<entry><methodname>findByFirstname(String
name)</methodname></entry>
<entry><code>x.firstname = $1</code></entry>
</row>
<row>
<entry><literal>Like</literal></entry>
<entry><methodname>findByFirstnameLike(String
name)</methodname></entry>
<entry><code>x.firstname LIKE $1</code></entry>
</row>
<row>
<entry><literal>Not</literal></entry>
<entry><methodname>findByFirstnameNot(String
name)</methodname></entry>
<entry><code>x.firstname != $1</code></entry>
</row>
<row>
<entry><literal>IsTrue</literal>,
<literal>True</literal></entry>
<entry><code>findByActiveIsTrue()</code></entry>
<entry><code>x.active = true</code></entry>
</row>
<row>
<entry><literal>IsFalse</literal>,
<literal>False</literal></entry>
<entry><code>findByActiveIsFalse()</code></entry>
<entry><code>x.active = false</code></entry>
</row>
</tbody>
</tgroup>
</table></para>
</section>
</chapter>

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

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

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

@@ -1,87 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude" xml:id="serialization">
<title>Working with GemFire Serialization</title>
<para>To improve overall performance of the data 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>
(such as <ulink
url="http://community.gemstone.com/display/gemfire/Serialization+in+Java">Java</ulink>,
<ulink
url="http://community.gemstone.com/display/gemfire/Serialization+in+.NET">.NET</ulink>
and C++). This chapter discusses the various ways in which Spring Data GemFire simplifies
and improves GemFire custom serialization in Java.</para>
<section id="serialization:wiring">
<title>Wiring deserialized instances</title>
<para>It is fairly common for serialized objects to have transient data.
Transient data is often dependent on the node or environment where it
lives at a certain point in time, for example a DataSource. Serializing
such information is useless (and potentially even dangerous) since it is
local to a certain VM/machine. For such cases, Spring Data GemFire offers a special <ulink
url="https://www.vmware.com/support/developer/vfabric-gemfire/700-api/com/gemstone/gemfire/Instantiator.html"><classname>Instantiator</classname></ulink>
that performs wiring for each new instance created by GemFire during
deserialization.</para>
<para>Through such a mechanism, one can rely on the Spring container to
inject (and manage) certain dependencies making it easy to split transient
from persistent data and have <emphasis>rich domain objects</emphasis> in
a transparent manner (Spring users might find this approach similar to
that of <ulink
url="http://static.springsource.org/spring/docs/current/spring-framework-reference/html/aop.html#aop-atconfigurable"><literal>@Configurable</literal></ulink>).
The <classname>WiringInstantiator</classname> works just like
<classname>WiringDeclarableSupport</classname>, trying to first locate a
bean definition as a wiring template and following to autowiring
otherwise. Please refer to the previous section (<xref
linkend="apis:declarable"/>) for more details on wiring
functionality.</para>
<para>To use this <classname>Instantiator</classname>, simply declare it
as a usual bean:</para>
<programlisting language="xml">&lt;bean id="instantiator" class="org.springframework.data.gemfire.serialization.WiringInstantiator"&gt;
&lt;!-- DataSerializable type --&gt;
&lt;constructor-arg&gt;org.pkg.SomeDataSerializableClass&lt;/constructor-arg&gt;
&lt;!-- type id --&gt;
&lt;constructor-arg&gt;95&lt;/constructor-arg&gt;
&lt;/bean&gt;</programlisting>
<para>During the container startup, once it is being initialized, the
<literal>instantiator</literal> will, by default, register itself with the
GemFire system and perform wiring on all instances of
<classname>SomeDataSerializableClass</classname> created by GemFire during
deserialization.</para>
</section>
<section id="serialization:instance-generator">
<title>Auto-generating custom <classname>Instantiator</classname>s</title>
<para>For data intensive applications, a large number of instances might
be created on each machine as data flows in. Out of the box, GemFire uses
reflection to create new types but for some scenarios, this might prove to
be expensive. As always, it is good to perform profiling to quantify
whether this is the case or not. For such cases, 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>
<programlisting language="xml">&lt;bean id="instantiator-factory" class="org.springframework.data.gemfire.serialization.InstantiatorFactoryBean"&gt;
&lt;property name="customTypes"&gt;
&lt;map&gt;
&lt;entry key="org.pkg.CustomTypeA" value="1025"/&gt;
&lt;entry key="org.pkg.CustomTypeB" value="1026"/&gt;
&lt;/map&gt;
&lt;/property&gt;
&lt;/bean&gt;</programlisting>
<para>The definition above, automatically generated two
<classname>Instantiator</classname>s for two classes, namely
<classname>CustomTypeA</classname> and <classname>CustomTypeB</classname>
and registers them with GemFire, under user id <literal>1025</literal> and
<literal>1026</literal>. The two instantiators avoid the use of reflection
and create the instances directly through Java code.</para>
</section>
</chapter>

19
src/asciidoc/appendix/appendix-schema.adoc Normal file
View File

@@ -0,0 +1,19 @@
[[appendix-schema]]
= Spring Data GemFire Schema
:resourcesDir: ../../main/resources
Spring Data GemFire Core Schema (gfe)
[source,xml]
----
include::{resourcesDir}/org/springframework/data/gemfire/config/spring-gemfire-1.3.xsd[]
----
Spring Data GemFire Data Access Schema (gfe-data)
[source,xml]
----
include::{resourcesDir}/org/springframework/data/gemfire/config/spring-data-gemfire-1.3.xsd[]
----

63
src/asciidoc/index.adoc Normal file
View File

@@ -0,0 +1,63 @@
= Spring Data GemFire Reference Guide
Costin Leau , David Turanski , John Blum , Oliver Gierke
:baseDir: .
:toc:
:spring-data-commons-docs: https://raw.githubusercontent.com/spring-projects/spring-data-commons/master/src/main/asciidoc
{version}
(C) 2011-2014 The original authors
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 Spring Data project.
NOTE: _Copies of this document may be made for your own use and for distribution to others, provided that you do not charge any fee for such copies and further provided that each copy contains this Copyright Notice, whether distributed in print or electronically._
[[spring-gemfire-reference]]
include::{baseDir}/preface.adoc[]
:numbered:
:leveloffset: 0
[[introduction]]
= Introduction
:leveloffset: 2
include::{baseDir}/introduction/introduction.adoc[]
include::{baseDir}/introduction/requirements.adoc[]
include::{baseDir}/introduction/new-features.adoc[]
:leveloffset: 0
[[reference]]
= Reference Guide
:leveloffset: 1
include::{baseDir}/reference/introduction.adoc[]
include::{baseDir}/reference/bootstrap.adoc[]
:leveloffset: 1
include::{baseDir}/reference/data.adoc[]
include::{baseDir}/reference/serialization.adoc[]
include::{baseDir}/reference/mapping.adoc[]
include::{baseDir}/reference/repositories.adoc[]
include::{baseDir}/reference/function-annotations.adoc[]
include::{baseDir}/reference/gemfire-bootstrap.adoc[]
include::{baseDir}/reference/samples.adoc[]
:leveloffset: 0
[[resources]]
= Other Resources
In addition to this reference documentation, there are a number of other resources that may help you learn how to use GemFire and Spring framework. These additional, third-party resources are enumerated in this section.
:leveloffset: 1
include::{baseDir}/links.adoc[]
:leveloffset: 0
[[appendices]]
= Appendices
:numbered!:
:leveloffset: 1
[appendix]
include::{baseDir}/appendix/appendix-schema.adoc[]

7
src/asciidoc/introduction/introduction.adoc Normal file
View File

@@ -0,0 +1,7 @@
[[intro-introduction]]
= Introduction
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.
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.

83
src/asciidoc/introduction/new-features.adoc Normal file
View File

@@ -0,0 +1,83 @@
[[new-features]]
= New Features
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 http://www.springsource.org/spring-data[Spring Data] project.
[[new-in-1-2-0]]
== New in the 1.2.0 Release
* Full support for GemFire configuration via the SDG *gfe* namespace. Now GemFire components may be configured completely without requiring a native *cache.xml* file.
* WAN Gateway support for GemFire 6.6.x. See <<bootstrap:gateway>>.
* Spring Data Repository support using a dedicated SDG namespace, *gfe-data*. See <<gemfire-repositories>>
* Namespace support for registering GemFire Functions. See <<bootstrap:function>>
* A top-level `<disk-store>` element has been added to the SDG *gfe* namespace to allow sharing of persist stores among Regions,
and other components that support persistent backup or overflow. See <<bootstrap-diskstore>>
+
WARNING: The `<*-region>` elements no longer allow a nested `<disk-store>`
+
* GemFire Sub-Regions are supported via nested `<*-region>` elements.
* A `<local-region>` element has been added to configure a Local Region.
[[new-in-1-2-1]]
== New in the 1.2.1 Release
* Support for the re-designed WAN Gateway in GemFire 7.0.
[[new-in-1-3-0]]
== New in the 1.3.0 Release
* 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 <<function-annotations>>.
* Added a `<datasource>` element to the SDG *gfe-data* namespace to simplify establishing a basic <<data-access:datasource,client connection>> to a GemFire data grid.
* Added a `<json-region-autoproxy>` element to the SDG *gfe-data* namespace to <<bootstrap:region:json,support JSON>> features introduced
in GemFire 7.0, enabling Spring AOP to perform the necessary conversions automatically on Region operations.
* Upgraded to GemFire 7.0.1 and added namespace support for new AsyncEventQueue attributes.
* Added support for setting subscription interest policy on Regions.
[[new-in-1-3-1]]
== New in the 1.3.1 Release
* Support for void returns on Function executions. See <<function-annotations>> for complete details.
[[new-in-1-3-2]]
== New in the 1.3.2 Release
* Support for persisting Local Regions. See <<bootstrap:region:local>> and <<bootstrap:region:common:attributes>>.
* Support for entry time-to-live and entry idle-time on a GemFire Client Cache. See <<bootstrap:cache:client>>.
* Support for multiple Spring Data GemFire web-based applications using a single GemFire cluster, operating concurrently inside tc Server.
[[new-in-1-3-3]]
== New in the 1.3.3 Release
* Support for concurrency-checks-enabled on all GemFire Cache Region definitions using the SDG *gfe* namespace. See <<bootstrap:region:common:attributes>>.
* Support for Cache Loaders and Cache Writers on Client, Local Regions. See <<bootstrap:region:common:loaders-writers>>.
* Support for registering CacheListeners, AsyncEventQueues and Gateway Senders on GemFire Cache Sub-Regions.
* Support for PDX persistent keys in GemFire Regions.
* Support for correct Partition Region bean creation in a Spring context when collocation is specified with the *colocated-with* attribute.
* Full support for GemFire Cache Sub-Regions using proper, nested `<*-region>` element syntax in the SDG *gfe* namespace.
[[new-in-1-3-4]]
== New in the 1.3.4 Release
* Upgraded Spring Data GemFire to Spring Framework 3.2.8.
* Upgraded Spring Data GemFire to Spring Data Commons 1.7.1.
[[new-in-1-4-0]]
== New in the 1.4.0 Release
* Upgrades Spring Data GemFire to GemFire 7.0.2.
* Upgrades Spring Data GemFire to Spring Data Commons 1.8.0.
* Integrates Spring Data GemFire with Spring Boot, which includes both a *spring-boot-starter-data-gemfire* POM along with a Spring Boot Sample
application demonstrating GemFire Cache Transactions configured with SDG bootstrapped with Spring Boot.
* Support for bootstrapping a Spring Context in a GemFire Server when started from Gfsh. See <<gemfire-bootstrap>>.
* Support for persisting application domain object/entities to multiple GemFire Cache Regions. See <<mapping.entities>> for more details.
* Support for persisting application domain object/entities to GemFire Cache Sub-Regions, avoiding collisions when Sub-Regions are uniquely identifiable, but identically named.
See <<mapping.entities>> for more details.
* Adds strict XSD type rules to, and full support for, Data Policies and Region Shortcuts on all GemFire Cache Region types.
* Changed the default behavior of SDG `<*-region>` elements from lookup to always create a new Region along with an option to restore old behavior using the
*ignore-if-exists* attribute. See <<bootstrap:region:common:attributes,Common Region Attributes>> and <<bootstrap:region:common:regions-subregions-lookups-caution>>
for more details.
* 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 http://pubs.vmware.com/vfabric53/topic/com.vmware.vfabric.gemfire.7.0/getting_started/system_requirements/supported_configurations.html[GemFire User Guide]
for additional details.

5
src/asciidoc/introduction/requirements.adoc Normal file
View File

@@ -0,0 +1,5 @@
[[requirements]]
= Requirements
Spring Data GemFire requires JDK 6.0 or above, http://www.springsource.org/about[Spring Framework] 3 and http://www.vmware.com/support/pubs/vfabric-gemfire.html[Pivotal GemFire] 6.6 or above (version 7 or above is recommended).

8
src/asciidoc/links.adoc Normal file
View File

@@ -0,0 +1,8 @@
[[sgf-links]]
= Useful Links
* http://projects.spring.io/spring-data-gemfire[Spring Data GemFire Home Page]
* http://www.vmware.com/products/application-platform/vfabric-gemfire/overview.html[Pivotal GemFire Home Page]
* https://www.vmware.com/support/pubs/vfabric-gemfire.html[Pivotal GemFire Documentation]
* http://communities.vmware.com/community/vmtn/appplatform/vfabric_gemfire[Pivotal GemFire Community Home Page]
* http://forum.spring.io/forum/spring-projects/data/gemfire[Spring Data GemFire Forum<]

7
src/asciidoc/preface.adoc Normal file
View File

@@ -0,0 +1,7 @@
[preface]
= Preface
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.
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 https://jira.spring.io/browse/SGF[issue]. Thank you.

100
src/asciidoc/reference/bootstrap.adoc Normal file
View File

@@ -0,0 +1,100 @@
[[bootstrap]]
= Bootstrapping GemFire through the Spring Container
:referenceDir: .
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.
NOTE: This section assumes basic familiarity with GemFire. For more information see the http://www.vmware.com/products/application-platform/vfabric-gemfire[product] documentation.
[[bootstrap:region:spring:config]]
== Advantages of using Spring over GemFire `cache.xml`
As of release 1.2.0, Spring Data GemFire's XML namespace supports full configuration of the data grid. In fact, the Spring Data GemFire namespace is considered the preferred way to configure GemFire. GemFire will continue to support native `cache.xml` for legacy reasons, but you can now do everything in Spring XML and take advantage of the many wonderful things Spring has to offer such as modular XML configuration, property placeholders, SpEL, and environment profiles. Behind the namespace, Spring Data GemFire makes extensive use of Spring's `FactoryBean` pattern to simplify the creation and initialization of GemFire components.
For example, GemFire provides several callback interfaces such as `CacheListener`, `CacheWriter`, and `CacheLoader` to allow developers to add custom event handlers. Using the Spring IoC container, these may configured as normal Spring beans and injected into GemFire components. This is a significant improvement over native `cache.xml` which provides relatively limited configuration options and requires callbacks to implement GemFire's `Declarable` interface (see <<apis:declarable>> to see how you can still use `Declarables` within Spring's DI container).
In addition, IDEs such as the Spring Tool Suite (STS) provide excellent support for Spring XML namespaces, such as code completion, pop-up annotations, and real time validation, making them easy to use.
[[bootstrap:namespace]]
== Using the Core Spring Data GemFire Namespace
To simplify configuration, Spring Data GemFire provides a dedicated XML namespace for configuring core GemFire components. It is also possible to configure the beans directly through Spring's standard <bean> definition. However, as of Spring Data GemFire 1.2.0, all bean properties are exposed via the namespace so there is little benefit to using raw bean definitions. For more information about XML Schema-based configuration in Spring, see http://static.springsource.org/spring/docs/current/spring-framework-reference/html/xsd-config.html[this] appendix in the Spring Framework reference documentation.
NOTE: Spring Data Repository support uses a separate XML namespace. See <<gemfire-repositories>> for more information on how to configure GemFire Repositories.
To use the Spring Data GemFire namespace, simply declare it in your Spring XML configuration meta-data:
[source,xml]
----
<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
xmlxsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:<!--1-->
gfe="http://www.springframework.org/schema/gemfire"<!--2-->
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"> <!--3-->
<bean id ... >
<gfe:cache ...> <!--4-->
</beans>
----
<1> Spring GemFire namespace prefix. Any name will do but through out the reference documentation, `gfe` will be used.
<2> The namespace URI.
<3> The namespace URI location. Note that even though the location points to an external address (which exists and is valid), Spring will resolve the schema locally as it is included in the Spring Data GemFire library.
<4> Declaration example for the GemFire namespace. Notice the prefix usage.
[NOTE]
====
It is possible to change the default namespace, for example from `beans` to `gfe`. This is useful for configuration composed mainly of GemFire components as it avoids declaring the prefix. To achieve this, simply swap the namespace prefix declaration above:
[source,xml]
----
<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns= <!--1-->
"http://www.springframework.org/schema/gemfire"
xmlxsi="http://www.w3.org/2001/XMLSchema-instance"
<!--2-->
xmlns:beans="http://www.springframework.org/schema/beans"
xsi:schemaLocation="
http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
http://www.springframework.org/schema/gemfire http://www.springframework.org/schema/gemfire/spring-gemfire.xsd">
<beans:bean id ... > <!--3-->
<cache ...> <!--4-->
</beans>
----
<1> The default namespace declaration for this XML file points to the Spring Data GemFire namespace.
<2> The `beans` namespace prefix declaration.
<3> Bean declaration using the `beans` namespace. Notice the prefix.
<4> Bean declaration using the `gfe` namespace. Notice the lack of prefix (as the default namespace is used).
====
:leveloffset: 2
include::{referenceDir}/cache.adoc[]
include::{referenceDir}/data-access.adoc[]
include::{referenceDir}/region.adoc[]
:leveloffset: 1
[[bootstrap:indicies]]
== Creating an Index
GemFire allows creation on indexes (or indices) to improve the performance of (common) queries. Spring Data GemFire allows indecies to be declared through the `index` element:
[source,xml]
----
<gfe:index id="myIndex" expression="someField" from="/someRegion"/>
----
Before creating an index, Spring Data GemFire will verify whether one with the same name already exists. If it does, it will compare the properties and if they don't match, will remove the old one to create a new one. If the properties match, Spring Data GemFire will simply return the index (in case it does not exist it will simply create one). To prevent the update of the index, even if the properties do not match, set the property `override` to false.
Note that index declaration are not bound to a region but rather are top-level elements (just like `gfe:cache`). This allows one to declare any number of indecies on any region whether they are just created or already exist - an improvement versus the GemFire `cache.xml`. By default the index relies on the default cache declaration but one can customize it accordingly or use a pool (if need be) - see the namespace schema for the full set of options.
:leveloffset: 2
include::{referenceDir}/diskstore.adoc[]
include::{referenceDir}/function.adoc[]
include::{referenceDir}/gateway.adoc[]

182
src/asciidoc/reference/cache.adoc Normal file
View File

@@ -0,0 +1,182 @@
[[bootstrap:cache]]
= Configuring the GemFire Cache
In order to use GemFire, one needs to either create a new `Cache` 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.
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 <<bootstrap:cache:client>> and <<bootstrap:region:client>>
A cache with default configuration can be created with a very simple declaration:
[source,xml]
----
<gfe:cache/>
----
A Spring application context containing this definition will, upon initialization, will register a `CacheFactoryBean` to create a Spring bean named `gemfireCache` referencing a GemFire `Cache` 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.
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 `cache-ref` attribute provided by various namespace elements. Also you can easily override the Cache's bean name:
[source,xml]
----
<gfe:cache id="my-cache"/>
----
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 `cache-xml-location` attribute:
[source,xml]
----
<gfe:cache id="cache-with-xml" cache-xml-location="classpath:cache.xml"/>
----
In this example, if the cache needs to be created, it will use the file named `cache.xml` located in the classpath root.
NOTE: Note that the configuration makes use of Spring's http://static.springsource.org/spring/docs/current/spring-framework-reference/html/resources.html[`Resource`] 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.
In addition to referencing an external configuration file one can specify GemFire http://pubs.vmware.com/vfabricNoSuite/topic/com.vmware.vfabric.gemfire.7.0/reference/topics/gemfire_properties.html[properties] using any of Spring's common properties support features. For example, one can use the `properties` element defined in the `util` namespace to define properties directly or load properties from properties files. The latter is recommended for externalizing environment specific settings outside the application configuration:
[source,xml]
----
<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:gfe="http://www.springframework.org/schema/gemfire"
xmlns:util="http://www.springframework.org/schema/util"
xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
http://www.springframework.org/schema/gemfire http://www.springframework.org/schema/gemfire/spring-gemfire.xsd
http://www.springframework.org/schema/util http://www.springframework.org/schema/util/spring-util.xsd">
<gfe:cache properties-ref="props"/>
<util:properties id="props" location="file:/vfabric/gemfire/gemfire.properties"/>
</beans>
----
NOTE: 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.
[[bootstrap:cache:advanced]]
== Advanced Cache Configuration
For advanced cache configuration, the `cache` element provides a number of configuration options exposed as attributes or child elements
[source,xml]
----
<!--1-->
<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"
close="false"
lazy-init="true"
>
<gfe:transaction-listener ref="myTransactionListener"/><!--2-->
<gfe:transaction-writer> <!--3-->
<bean class="org.springframework.data.gemfire.example.TransactionListener"/>
</gfe:transaction-writer>
<gfe:dynamic-region-factory/> <!--4-->
<gfe:jndi-binding jndi-name="myDataSource" type="ManagedDataSource"/> <!--5-->
</gfe:cache>
----
<1> Various cache options are supported by attributes. For further information regarding anything shown in this example, please consult the GemFire product http://www.vmware.com/support/pubs/vfabric-gemfire.html[documentation]
The `close` attribute determines if the cache should be closed when the Spring application context is closed. The default is `true` however for cases in which multiple application contexts use the cache (common in web applications), set this value to `false`.
The `lazy-init` attribute determines if the cache should be initialized before another bean references it. The default is `true` however in some cases it may be convenient to set this value to `false`.
<2> An example of a `TransactionListener` callback declaration using a bean reference. The referenced bean must implement http://www.vmware.com/support/developer/vfabric-gemfire/700-api/com/gemstone/gemfire/cache/TransactionListener.html[TransactionListener]
<3> An example of a `TransactionWriter` callback declaration using an inner bean declaration this time. The bean must implement http://www.vmware.com/support/developer/vfabric-gemfire/700-api/com/gemstone/gemfire/cache/TransactionWriter.html[TransactionWriter]
<4> Enable GemFire's http://www.vmware.com/support/developer/vfabric-gemfire/700-api/com/gemstone/gemfire/cache/DynamicRegionFactory.html[DynamicRegionFactory]
<5> Declares a JNDI binding to enlist an external datasource in a GemFire transaction
NOTE: The `use-bean-factory-locator` attribute (not shown) deserves a mention. The factory bean responsible for creating the cache uses an internal Spring type called a
`BeanFactoryLocator` to enable user classes declared in GemFire's native `cache.xml` to be registered as Spring beans. The `BeanFactoryLocator` 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 `BeanFactoryLocator` by setting this value to false 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 `<forkmode>always</forkmode>`) . Generally there is no harm in setting this
value to false.
=== Enabling PDX Serialization
The example above includes a number of attributes related to GemFire'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 `pdx-serializer` attribute. GemFire provides an implementation class `com.gemstone.gemfire.pdx.ReflectionBasedAutoSerializer`, 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 <<serialization>>
[[bootstrap:cache:server]]
== Configuring a GemFire Cache Server
In Spring Data GemFire 1.1 dedicated support for configuring a http://www.vmware.com/support/developer/vfabric-gemfire/700-api/com/gemstone/gemfire/cache/server/CacheServer.html[CacheServer] was added, allowing complete configuration through the Spring container:
[source,xml]
----
<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:gfe="http://www.springframework.org/schema/gemfire"
xmlns: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">
<gfe:cache />
<!-- Advanced example depicting various cache server configuration options -->
<gfe:cache-server id="advanced-config" auto-startup="true"
bind-address="localhost" port="${gfe.port.6}" host-name-for-clients="localhost"
load-poll-interval="2000" max-connections="22" max-threads="16"
max-message-count="1000" max-time-between-pings="30000"
groups="test-server">
<gfe:subscription-config eviction-type="ENTRY" capacity="1000" disk-store="file://${java.io.tmpdir}"/>
</gfe:cache-server>
<context:property-placeholder location="classpath:cache-server.properties"/>
</beans>
----
The configuration above illustrates the `cache-server` element and the many options available.
NOTE: Rather than hard-coding the port, this configuration uses Spring's http://static.springsource.org/spring/docs/current/spring-framework-reference/html/xsd-config.html#xsd-config-body-schemas-context[context] namespace to declare a `property-placeholder`. The http://static.springsource.org/spring/docs/current/spring-framework-reference/html/beans.html#beans-factory-placeholderconfigurer[property placeholder] 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 http://static.springsource.org/spring/docs/current/spring-framework-reference/html/new-in-3.0.html#new-feature-el[SpEL] and the http://static.springsource.org/spring/docs/current/spring-framework-reference/html/new-in-3.1.html#new-in-3.1-environment-abstraction[environment abstraction] one to support externalization of environment specific properties from the main code base, easing the deployment across multiple machines.
NOTE: To avoid initialization problems, the `CacheServer`s started by Spring Data GemFire will start *after* 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 after your components and thus not be seen by the clients connecting right away.
[[bootstrap:cache:client]]
== Configuring a GemFire Client Cache
Another configuration addition in Spring Data GemFire 1.1 is the dedicated support for configuring http://www.vmware.com/support/developer/vfabric-gemfire/700-api/com/gemstone/gemfire/cache/client/ClientCache.html[ClientCache]. This is similar to a <<bootstrap:cache,cache>> in both usage and definition and supported by `org.springframework.data.gemfire.clientClientCacheFactoryBean`.
[source,xml]
----
<beans>
<gfe:client-cache />
</beans>
----
`client-cache` supports much of the same options as the *cache* element. However as opposed to a *full* 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 `localhost` port `40404`. The the default pool is used by all client regions unless the region is configured to use a different pool.
Pools can be defined through the `pool` element; The client side `pool` 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 `client-cache`, one needs to define a pool and wire it to cache definition:
[source,xml]
----
<beans>
<gfe:client-cache id="simple" pool-name="my-pool"/>
<gfe:pool id="my-pool" subscription-enabled="true">
<gfe:locator host="${locatorHost}" port="${locatorPort}"/>
</gfe:pool>
</beans>
----
The <client-cache> tag also includes a `ready-for-events` attribute. If set to `true`, the client cache initialization will include http://www.vmware.com/support/developer/vfabric-gemfire/700-api/com/gemstone/gemfire/cache/client/ClientCache.html#readyForEvents()[ClientCache.readyForEvents()].
Client side configuration is covered in more detail in <<bootstrap:region:client>>.

104
src/asciidoc/reference/cq-container.adoc Normal file
View File

@@ -0,0 +1,104 @@
[[apis:cq-container]]
= GemFire Continuous Query Container
A powerful functionality offered by GemFire is http://community.gemstone.com/display/gemfire/Continuous+Querying[continuous querying] (or CQ). In short, CQ allows one to create a query and automatically be notified when new data that gets added to GemFire matches the query. Spring GemFire provides dedicated support for CQs through the `org.springframework.data.gemfire.listener` package and its *listener container*; 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 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.
NOTE: Currently, continuous queries are supported by GemFire only in client/server topologies. Additionally the pool used is required to have the `subscription` property enabled. Please refer to the documentation for more information.
[[apis:cq-container:containers]]
== Continuous Query Listener Container
Spring Data GemFire simplifies the creation, registration, life-cycle and dispatch of CQs by taking care of the infrastructure around them through `ContinuousQueryListenerContainer` 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)
`ContinuousQueryListenerContainer` 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 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.
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 asynchronous approach by defining the suitable `java.util.concurrent.Executor` (or Spring's `TaskExecutor`). 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 `TaskExecutor` to take advantage of its runtime.
[[apis:cq-container:adapter]]
== The `ContinuousQueryListenerAdapter` and `ContinuousQueryListener`
The `ContinuousQueryListenerAdapter` class is the final component in Spring Data GemFire CQ support: in a nutshell, it allows you to expose almost *any* class as a EDP (there are of course some constraints) - it implements `ContinuousQueryListener`, a simpler listener interface similar to GemFire https://www.vmware.com/support/developer/vfabric-gemfire/700-api/com/gemstone/gemfire/cache/query/CqListener.html[CqListener].
Consider the following interface definition. Notice the various event handling methods and their parameters:
[source,java]
----
public interface EventDelegate {
void handleEvent(CqEvent event);
void handleEvent(Operation baseOp);
void handleEvent(Object key);
void handleEvent(Object key, Object newValue);
void handleEvent(Throwable th);
void handleQuery(CqQuery cq);
void handleEvent(CqEvent event, Operation baseOp, byte[] deltaValue);
void handleEvent(CqEvent event, Operation baseOp, Operation queryOp, Object key, Object newValue);
}
----
[source,java]
----
public class DefaultEventDelegate implements EventDelegate {
// implementation elided for clarity...
}
----
In particular, note how the above implementation of the `EventDelegate` interface (the above `DefaultEventDelegate` class) has *no* GemFire dependencies at all. It truly is a POJO that we will make into an EDP via the following configuration (note that the class doesn't have to implement an interface, one is present only to better show case the decoupling between contract and implementation).
[source,xml]
----
<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:gfe="http://www.springframework.org/schema/gemfire"
xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
http://www.springframework.org/schema/gemfire http://www.springframework.org/schema/gemfire/spring-gemfire.xsd">
<gfe:client-cache pool-name="client"/>
<gfe:pool id="client" subscription-enabled="true">
<gfe:server host="localhost" port="40404"/>
</gfe:pool>
<gfe:cq-listener-container>
<!-- default handle method -->
<gfe:listener ref="listener" query="SELECT * from /region"/ >
<gfe:listener ref="another-listener" query="SELECT * from /another-region" name="my-query" method="handleQuery"/>
</gfe:cq-listener-container>
<bean id="listener" class="gemfireexample.DefaultMessageDelegate"/>
<bean id="another-listener" class="gemfireexample.DefaultMessageDelegate"/>
...
<beans>
----
NOTE: The example above shows some of the various forms that a listener can have; at its minimum the listener reference and the actual query definition are required. It's possible however to specify a name for the resulting continuous query (useful for monitoring) but also the name of the method (the default is `handleEvent`). The specified method can have various argument types, the `EventDelegate` interface lists the allowed types.
The example above uses the Spring Data GemFire namespace to declare the event listener container and automatically register the listeners. The full blown, *beans* definition is displayed below:
[source,xml]
----
<!-- this is the Event Driven POJO (MDP) -->
<bean id="eventListener" class="org.springframework.data.gemfire.listener.adapter.ContinuousQueryListenerAdapter">
<constructor-arg>
<bean class="gemfireexample.DefaultEventDelegate"/>
</constructor-arg>
</bean>
<!-- and this is the event listener container... -->
<bean id="gemfireListenerContainer" class="org.springframework.data.gemfire.listener.ContinuousQueryListenerContainer">
<property name="cache" ref="gemfireCache"/>
<property name="queryListeners">
<!-- set of listeners -->
<set>
<bean class="org.springframework.data.gemfire.listener.ContinuousQueryDefinition" >
<constructor-arg value="SELECT * from /region" />
<constructor-arg ref="eventListener" />
</bean>
</set>
</property>
</bean>
----
Each time an event is received, the adapter automatically performs type translation between the GemFire event and the required method argument(s) transparently. Any exception caused by the method invocation is caught and handled by the container (by default, being logged).

30
src/asciidoc/reference/data-access.adoc Normal file
View File

@@ -0,0 +1,30 @@
[[data-access]]
= Using the GemFire Data Access Namespace
In addition to the core `gfe` namespace, Spring Data GemFire provides a `gfe-data` namespace intended primarily to simplify the development of GemFire client applications. This namespace currently supports for GemFire <<gemfire-repositories,repositories>> and function <<function-execution,execution>> and a `<datasource>` tag that offers a convenient way to connect to the data grid.
[[data-access:datasource]]
== An Easy Way to Connect to GemFire
For many applications, A basic connection to a GemFire grid, using default values is sufficient. Spring Data GemFire's `<datasource>` tag provides a simple way to access data. The data source creates a client cache and connection pool. In addition, it will query the member servers for all existing root regions and create a proxy (empty) client region for each one.
[source,xml]
----
<gfe-data:datasource>
<locator host="somehost" port="1234"/>
</gfe-data:datasource>
----
The datasource tag is syntactically similar to `<gfe:pool>`. It may be configured with one or more locator or server tags to connect to an existing data grid. Additionally, all attributes available to configure a pool are supported. This configuration will automatically create ClientRegion beans for each region defined on members connected to the locator, so they may be seamlessly referenced by Spring Data mapping annotations, GemfireTemplate, and wired into application classes.
Of course, you can explicitly configure client regions. For example, if you want to cache data in local memory:
[source,xml]
----
<gfe-data:datasource>
<locator host="somehost" port="1234"/>
</gfe-data:datasource>
<gfe:client-region id="Customer" shortcut="CACHING_PROXY"/>
----

243
src/asciidoc/reference/data.adoc Normal file
View File

@@ -0,0 +1,243 @@
[[apis]]
= Working with the GemFire APIs
:referenceDir:
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 `DaoException` hierarchy. It also covers support for dependency injection of GemFire managed objects.
[[apis:exception-translation]]
== Exception Translation
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 http://static.springsource.org/spring/docs/3.0.x/spring-framework-reference/html/dao.html#dao-exceptions[exception hierarchy] that abstracts the application from proprietary (and usually checked) exceptions to a set of focused runtime exceptions. As mentioned in the Spring Framework documentation, http://static.springsource.org/spring/docs/3.0.x/spring-framework-reference/html/orm.html#orm-exception-translation[exception translation] can be applied transparently to your data access objects through the use of the `@Repository` annotation and AOP by defining a `PersistenceExceptionTranslationPostProcessor` bean. The same exception translation functionality is enabled when using GemFire as long as at least a `CacheFactoryBean` is declared, e.g. using a `<gfe:cache/>` declaration, as it acts as an exception translator which is automatically detected by the Spring infrastructure and used accordingly.
[[apis:template]]
== GemfireTemplate
As with many other high-level abstractions provided by the Spring projects, Spring Data GemFire provides a *template* that simplifies GemFire data access. The class provides several *one-line* methods, for common region operations but also the ability to *execute* code against the native GemFire API without having to deal with GemFire checked exceptions for example through the `GemfireCallback`.
The template class requires a GemFire `Region` instance and once configured is thread-safe and should be reused across multiple classes:
[source,xml]
----
<bean id="gemfireTemplate" class="org.springframework.data.gemfire.GemfireTemplate" p:region-ref="someRegion"/>
----
Once the template is configured, one can use it alongside `GemfireCallback` to work directly with the GemFire `Region`, without having to deal with checked exceptions, threading or resource management concerns:
[source,java]
----
template.execute(new GemfireCallback<Iterable<String>>() {
public Iterable<String> doInGemfire(Region reg) throws GemFireCheckedException, GemFireException {
// working against a Region of String
Region<String, String> region = reg;
region.put("1", "one");
region.put("3", "three");
return region.query("length < 5");
}
});
----
For accessing the full power of the GemFire query language, one can use the `find` and `findUnique` which, as opposed to the `query` method, can execute queries across multiple regions, execute projections, and the like. The `find` method should be used when the query selects multiple items (through`SelectResults`) and the latter, `findUnique`, as the name suggests, when only one object is returned.
[[apis:spring-cache-abstraction]]
== Support for Spring Cache Abstraction
Since 1.1, Spring Data GemFire provides an implementation of the Spring 3.1 http://static.springsource.org/spring/docs/current/spring-framework-reference/htmlsingle/spring-framework-reference.html#cache[cache abstraction]. To use GemFire as a backing implementation, simply add `GemfireCacheManager` to your configuration:
[source,xml]
----
<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">
<!-- turn on declarative caching -->
<cache:annotation-driven/>
<gfe:cache id="gemfire-cache"/>
<!-- declare GemFire Cache Manager -->
<bean id="cacheManager" class="org.springframework.data.gemfire.support.GemfireCacheManager" p:cache-ref="gemfire-cache">
</beans>
----
[[apis:tx-mgmt]]
== Transaction Management
One of the most popular features of Spring Framework is http://static.springsource.org/spring/docs/current/spring-framework-reference/htmlsingle/spring-framework-reference.html#transaction[transaction management]. If you are not familiar with it, we strongly recommend http://static.springsource.org/spring/docs/current/spring-framework-reference/htmlsingle/spring-framework-reference.html#transaction-motivation[reading] 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).
For GemFire, Spring Data GemFire provides a dedicated, per-cache, transaction manager that, once declared, allows Region operations to be executed atomically through Spring:
[source,xml]
----
<gfe:transaction-manager id="tx-manager" cache-ref="cache"/>
----
NOTE: The example above can be simplified even more by eliminating the `cache-ref` attribute if the GemFire Cache is defined under the default name`gemfireCache`. 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`gemfireTransactionManager` if not explicitly specified.
Currently, GemFire supports optimistic transactions with *read committed* isolation. Furthermore, to guarantee this isolation, developers should avoid making *in-place* changes that manually modify values present in the Cache. To prevent this from happening, the transaction manager configures the Cache to use *copy on read* 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 `copyOnRead` property. For more information on the semantics of the underlying GemFire transaction manager, see the GemFire https://www.vmware.com/support/developer/vfabric-gemfire/700-api/com/gemstone/gemfire/cache/CacheTransactionManager.html[documentation].
:leveloffset: 2
include::{referenceDir}/cq-container.adoc[]
:leveloffset: 1
[[apis:declarable]]
== Wiring `Declarable` components
GemFire XML configuration (usually named `cache.xml` allows *user* objects to be declared as part of the configuration. Usually these objects are `CacheLoader`s or other pluggable callback components supported by GemFire. Using native GemFire configuration, each user type declared through XML must implement the `Declarable` interface which allows arbitrary parameters to be passed to the declared class through a `Properties` instance.
In this section we describe how you can configure these pluggable components defined in `cache.xml` using Spring while keeping your Cache/Region configuration defined in `cache.xml` This allows your pluggable components to focus on the application logic and not the location or creation of DataSources or other collaboration objects.
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 `Declarable` interface or the base class presented in this section. See the following sidebar for more information on this approach.
.Eliminate `Declarable` components
****
One can configure custom types entirely through Spring as mentioned in <<bootstrap:region>>. That way, one does not have to implement the `Declarable` interface and also benefits from all the features of the Spring IoC container (not just dependency injection but also life-cycle and instance management).
****
As an example of configuring a `Declarable` component using Spring, consider the following declaration (taken from the `Declarable` javadoc):
[source,xml]
----
<cache-loader>
<class-name>com.company.app.DBLoader</class-name>
<parameter name="URL">
<string>jdbc://12.34.56.78/mydb</string>
</parameter>
</cache-loader>
----
To simplify the task of parsing, converting the parameters and initializing the object, Spring Data GemFire offers a base class (`WiringDeclarableSupport`) that allows GemFire user objects to be wired through a *template* bean definition or, in case that is missing, perform autowiring through the Spring container. To take advantage of this feature, the user objects need to extend `WiringDeclarableSupport` which automatically locates the declaring `BeanFactory` and performs wiring as part of the initialization process.
.Why is a base class needed?
****
In the current GemFire release there is no concept of an *object factory* and the types declared are instantiated and used as is. In other words, there is no easy way to manage object creation outside GemFire.
****
[[apis:declarable:template-wiring]]
=== Configuration using *template* definitions
When used, `WiringDeclarableSupport` 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 `DBLoader` declaration would look in that case:
[source,java]
----
public class DBLoader extends WiringDeclarableSupport implements CacheLoader {
private DataSource dataSource;
public void setDataSource(DataSource ds){
this.dataSource = ds;
}
public Object load(LoaderHelper helper) { ... }
}
----
[source,xml]
----
<cache-loader>
<class-name>com.company.app.DBLoader</class-name>
<!-- no parameter is passed (use the bean implicit name
that is the class name) -->
</cache-loader>
----
[source,xml]
----
<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:p="http://www.springframework.org/schema/p"
xsi:schemaLocation="http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans.xsd">
<bean id="dataSource" ... />
<!-- template bean definition -->
<bean id="com.company.app.DBLoader" abstract="true" p:dataSource-ref="dataSource"/>
</beans>
----
In the scenario above, as no parameter was specified, a bean with the id/name `com.company.app.DBLoader` 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 `bean-name` parameter in the GemFire configuration:
[source,xml]
----
<cache-loader>
<class-name>com.company.app.DBLoader</class-name>
<!-- pass the bean definition template name
as parameter -->
<parameter name="bean-name">
<string>template-bean</string>
</parameter>
</cache-loader>
----
[source,xml]
----
<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:p="http://www.springframework.org/schema/p"
xsi:schemaLocation="http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans.xsd">
<bean id="dataSource" ... />
<!-- template bean definition -->
<bean id="template-bean" abstract="true" p:dataSource-ref="dataSource"/>
</beans>
----
NOTE: The *template* bean definitions do not have to be declared in XML - any format is allowed (Groovy, annotations, etc..).
[[apis:declarable:autowiring]]
=== Configuration using auto-wiring and annotations
If no bean definition is found, by default, `WiringDeclarableSupport` will http://static.springsource.org/spring/docs/current/spring-framework-reference/htmlsingle/spring-framework-reference.html#beans-factory-autowire[autowire] the declaring instance. This means that unless any dependency injection *metadata* 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 http://static.springsource.org/spring/docs/current/spring-framework-reference/htmlsingle/spring-framework-reference.html#beans-annotation-config[chapter] in the Spring documentation for more information on the supported annotations and enabling factors.
For example, the hypothetical `DBLoader` declaration above can be injected with a Spring-configured `DataSource` in the following way:
[source,java]
----
public class DBLoader extends WiringDeclarableSupport implements CacheLoader {
// use annotations to 'mark' the needed dependencies
@javax.inject.Inject
private DataSource dataSource;
public Object load(LoaderHelper helper) { ... }
}
----
[source,xml]
----
<cache-loader>
<class-name>com.company.app.DBLoader</class-name>
<!-- no need to declare any parameters anymore
since the class is auto-wired -->
</cache-loader>
----
[source,xml]
----
<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:context="http://www.springframework.org/schema/context"
xsi:schemaLocation="http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans.xsd
http://www.springframework.org/schema/context
http://www.springframework.org/schema/context/spring-context.xsd">
<!-- enable annotation processing -->
<context:annotation-config/>
</beans>
----
By using the JSR-330 annotations, the cache loader code has been simplified since the location and creation of the DataSource has been externalized and the user code is concerned only with the loading process. The `DataSource` might be transactional, created lazily, shared between multiple objects or retrieved from JNDI - these aspects can be easily configured and changed through the Spring container without touching the `DBLoader` code.

18
src/asciidoc/reference/diskstore.adoc Normal file
View File

@@ -0,0 +1,18 @@
[[bootstrap-diskstore]]
= Configuring a Disk Store
As of Release 1.2.0, Spring Data GemFire supports disk store configuration via a top level `disk-store` element.
NOTE: Prior to Release 1.2.0, `disk-store` was a child element of `*-region`. 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 `disk-store-ref` attribute. Also, `disk-synchronous` is now a region level attribute.
[source,xml]
----
<gfe:disk-store id="diskStore1" queue-size="50" auto-compact="true"
max-oplog-size="10" time-interval="9999">
<gfe:disk-dir location="/gemfire/store1/" max-size="20"/>
<gfe:disk-dir location="/gemfire/store2/" max-size="20"/>
</gfe:disk-store>
----
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.

160
src/asciidoc/reference/function-annotations.adoc Normal file
View File

@@ -0,0 +1,160 @@
[[function-annotations]]
= Annotation Support for Function Execution
== Introduction
Spring Data GemFire 1.3.0 introduces annotation support to simplify working with http://pubs.vmware.com/vfabricNoSuite/index.jsp?topic=/com.vmware.vfabric.gemfire.7.0/developing/function_exec/chapter_overview.html??[GemFire function execution]. The GemFire API provides classes to implement and register https://www.vmware.com/support/developer/vfabric-gemfire/700-api/com/gemstone/gemfire/cache/execute/Function.html[Functions] deployed to cache servers that may be invoked remotely by member applications, typically cache clients. Functions may execute in parallel, distributed among multiple servers, combining results in a map-reduce pattern, or may be targeted to a single server. A Function execution may be also be targeted to a specific region.
GemFire's also provides APIs to support remote execution of functions targeted to various defined scopes (region, member groups, servers, etc.) and the ability to aggregate results. The API also provides certain runtime options. The implementation and execution of remote functions, as with any RPC protocol, requires some boilerplate code. Spring Data GemFire, true to Spring's core value proposition, aims to hide the mechanics of remote function execution and allow developers to focus on POJO programming and business logic. To this end, Spring Data GemFire introduces annotations to declaratively register public methods as functions, and the ability to invoke registered functions remotely via annotated interfaces.
== Implementation vs Execution
There are two separate concerns to address. First is the function implementation (server) which must interact with the https://www.vmware.com/support/developer/vfabric-gemfire/700-api/com/gemstone/gemfire/cache/execute/FunctionContext.html[FunctionContext] to obtain the invocation arguments, the https://www.vmware.com/support/developer/vfabric-gemfire/700-api/com/gemstone/gemfire/cache/execute/ResultSender.html[ResultsSender] and other execution context information. The function implementation typically accesses the Cache and or Region and is typically registered with the https://www.vmware.com/support/developer/vfabric-gemfire/700-api/com/gemstone/gemfire/cache/execute/FunctionService.html[FunctionService] under a unique Id. The application invoking a function (the client) does not depend on the implementation. To invoke a function remotely, the application instantiates an https://www.vmware.com/support/developer/vfabric-gemfire/700-api/com/gemstone/gemfire/cache/execute/Execution.html[Execution] providing the function ID, invocation arguments, the function target or scope (region, server, servers, member, members). If the function produces a result, the invoker uses a https://www.vmware.com/support/developer/vfabric-gemfire/700-api/com/gemstone/gemfire/cache/execute/ResultCollector.html[ResultCollector] to aggregate and acquire the execution results. In certain scenarios, a custom ResultCollector implementation is required and may be registered with the Execution.
NOTE: 'Client' and 'Server' are used here in the context of function execution which may have a different meaning then client and server in a client-server cache topology. While it is common for a member with a Client Cache to invoke a function on one or more Cache Server members it is also possible to execute functions in a peer-to-peer configuration
== Implementing a Function
Using GemFire APIs, the FunctionContext provides a runtime invocation context including the client's calling arguments and a ResultSender interface to send results back to the client. Additionally, if the function is executed on a Region, the FunctionContext is an instance of RegionFunctionContext which provides additional context such as the target Region and any Filter (set of specific keys) associated with the Execution. If the Region is a Partition Region, the function should use the PartitionRegionHelper to extract only the local data.
Using Spring, one can write a simple POJO and enable the Spring container bind one or more of it's public methods to a Function. The signature for a POJO method intended to be used as a function must generally conform to the the client's execution arguments. However, in the case of a region execution, the region data must also be provided (presumably the data held in the local partition if the region is a partition region). Additionally the function may require the filter that was applied, if any. This suggests that the client and server may share a contract for the calling arguments but that the method signature may include additional parameters to pass values provided by the FunctionContext. One possibility is that the client and server share a common interface, but this is not required. The only constraint is that the method signature includes the same sequence of calling arguments with which the function was invoked after the additional parameters are resolved. For example, suppose the client provides a String and int as the calling arguments. These are provided by the FunctionContext as an array:
`Object[] args = new Object[]{"hello", 123}`
Then the Spring container should be able to bind to any method signature similar to the following. Let's ignore the return type for the moment:
[source,java]
----
public Object method1(String s1, int i2) {...}
public Object method2(Map<?,?> data, String s1, int i2) {...}
public Object method3(String s1, Map<?,?>data, int i2) {...}
public Object method4(String s1, Map<?,?> data, Set<?> filter, int i2) {...}
public void method4(String s1, Set<?> filter, int i2, Region<?,?> data) {...}
public void method5(String s1, ResultSender rs, int i2);
public void method6(FunctionContest fc);
----
The general rule is that once any additional arguments, i.e., region data and filter, are resolved the remaining arguments must correspond exactly, in order and type, to the expected calling parameters. The method's return type must be void or a type that may be serialized (either java.io.Serializable, DataSerializable, or PDX serializable). The latter is also a requirement for the calling arguments. The Region data should normally be defined as a Map, to facilitate unit testing, but may also be of type Region if necessary. As shown in the example above, it is also valid to pass the FunctionContext itself, or the ResultSender, if you need to control how the results are returned to the client.
=== Annotations for Function Implementation
The following example illustrates how annotations are used to expose a POJO as a GemFire function:
[source,java]
----
@Component
public class MyFunctions {
@GemfireFunction
public String function1(String s1, @RegionData Map<?,?> data, int i2) { ... }
@GemfireFunction("myFunction", HA=true, optimizedForWrite=true, batchSize=100)
public List<String> function2(String s1, @RegionData Map<?,?> data, int i2, @Filter Set<?> keys) { ... }
@GemfireFunction(hasResult=true)
public void functionWithContext(FunctionContext functionContext) { ... }
}
----
Note that the class itself must be registered as a Spring bean. Here the `@Component` annotation is used, but you may register the bean by any method provided by Spring (e.g. XML configuration or Java configuration class). This allows the Spring container to create an instance of this class and wrap it in a https://github.com/SpringSource/spring-gemfire/blob/master/src/main/java/org/springframework/data/gemfire/function/PojoFunctionWrapper.java[PojoFunctionWrapper](PFW). Spring creates one PFW instance for each method annotated with `@GemfireFunction`. Each will all share the same target object instance to invoke the corresponding method.
NOTE: The fact that the function class is a Spring bean may offer other benefits since it shares the application context with GemFire components such as a Cache and Regions. These may be injected into the class if necessary.
Spring creates the wrapper class, and registers the function with GemFire's Function Service. The function id used to register the functions must be unique. By convention it defaults to the simple (unqualified) method name. Note that this annotation also provides configuration attributes, `HA` and `optimizedForWrite` which correspond to properties defined by GemFire's Function interface. If the method's return type is void, then the `hasResult` property is automatically set to `false`; otherwise it is `true`.
For `void` return types, the annotation provides a `hasResult` attribute that can be set to true to override this convention, as shown in the `functionWithContext` method above. Presumably, the intention is to use the ResultSender directly to send results to the caller.
The PFW implements GemFire's Function interface, binds the method parameters, and invokes the target method in its `execute()` method. It also sends the method's return value using the ResultSender.
==== Batching Results
If the return type is a Collection or Array, then some consideration must be given to how the results are returned. By default, the PFW returns the entire collection at once. If the number of items is large, this may incur a performance penalty. To divide the payload into small sections (sometimes called chunking), you can set the `batchSize` attribute, as illustrated in `function2`, above. NOTE: If you need more control of the ResultSender, especially if the method itself would use too much memory to create the collection, you can pass the ResultSender, or access it via the FunctionContext, to use it directly within the method.
==== Enabling Annotation Processing
In accordance with Spring standards, you must explicitly activate annotation processing for @GemfireFunction using XML:
[source,xml]
----
<gfe:annotation-driven/>
----
or by annotating a Java configuration class:
[source,java]
----
@EnableGemfireFunctions
----
[[function-execution]]
== Executing a Function
A process invoking a remote function needs to provide calling arguments, a function id, the execution target (onRegion, onServers, onServer, onMember, onMembers) and optionally a Filter set. All you need to do is define an interface supported by annotations. Spring will create a dynamic proxy the interface which will use the FunctionService to create an Execution, invoke the execution and coerce the results to a defined return type, if necessary. This technique is very similar to the way Spring Data repositories work, thus some of the configuration and concepts should be familiar. Generally a single interface definition maps to multiple function executions, one corresponding to each method defined in the interface.
=== Annotations for Function Execution
To support client side function execution, the following annotations are provided: `@OnRegion`, `@OnServer`, `@OnServers`, `@OnMember`, `@OnMembers`. These correspond to the Execution implementations GemFire's FunctionService provides. Each annotation exposes the appropriate attributes. These annotations also provide an optional `resultCollector` attribute whose value is the name of a Spring bean implementing https://www.vmware.com/support/developer/vfabric-gemfire/700-api/com/gemstone/gemfire/cache/execute/ResultCollector.html[ResultCollector] to use for the execution.
NOTE: The proxy interface binds all declared methods to the same execution configuration. Although it is expected that single method interfaces will be common, all methods in the interface are backed by the same proxy instance and therefore are all share the same configuration.
Here are some examples:
[source,java]
----
@OnRegion(region="someRegion", resultCollector="myCollector")
public interface FunctionExecution {
@FunctionId("function1")
public String doIt(String s1, int i2);
public String getString(Object arg1, @Filter Set<Object> keys) ;
}
----
By default, the function id is the simple (unqualified) method name. `@FunctionId` is used to bind this invocation to a different function id.
==== Enabling Annotation Processing
The client side uses Spring's component scanning capability to discover annotated interfaces. To enable function execution annotation processing, you can use XML:
[source,xml]
----
<gfe-data:function-executions base-package="org.example.myapp.functions"/>
----
Note that the `function-executions` tag is provided in the `gfe-data` namespace. The `base-package` attribute is required to avoid scanning the entiire class path. Additional filters are provided as described in the Spring http://static.springsource.org/spring/docs/current/spring-framework-reference/html/beans.html#beans-scanning-filters[reference].
Or annotate your Java configuration class:
[source,java]
----
@EnableGemfireFunctionExecutions(basePackages = "org.example.myapp.functions")
----
== Programmatic Function Execution
Using the annotated interface as described in the previous section, simply wire your interface into a bean that will invoke the function:
[source,java]
----
@Component
public class MyApp {
@Autowired FunctionExecution functionExecution;
public void doSomething() {
functionExecution.doIt("hello", 123);
}
}
----
Alternately, you can use a Function Execution template directly. For example GemfireOnRegionFunctionTemplate creates an onRegion execution. For example:
[source,java]
----
Set<?,?> myFilter = getFilter();
Region<?,?> myRegion = getRegion();
GemfireOnRegionOperations template = new GemfireOnRegionFunctionTemplate(myRegion);
String result = template.executeAndExtract("someFunction",myFilter,"hello","world",1234);
----
Internally, function executions always return a List. `executeAndExtract` assumes a singleton list containing the result and will attempt to coerce that value into the requested type. There is also an `execute` method that returns the List itself. The first parameter is the function id. The filter argument is optional. The following arguments are a variable argument list.

17
src/asciidoc/reference/function.adoc Normal file
View File

@@ -0,0 +1,17 @@
[[bootstrap:function]]
= Configuring GemFire's Function Service
As of Release 1.3.0, Spring Data GemFire provides <<function-annotations,annotation>> support for implementing and registering functions. Spring Data GemFire also provides namespace support for registering GemFire https://www.vmware.com/support/developer/vfabric-gemfire/700-api/com/gemstone/gemfire/cache/execute/Function.html[Functions] 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 `com.gemstone.gemfire.cache.execute.Function` interface or extend `com.gemstone.gemfire.cache.execute.FunctionAdapter`. The namespace uses a familiar pattern to declare functions:
[source,xml]
----
<gfe:function-service>
<gfe:function>
<bean class="com.company.example.Function1"/>
<ref bean="function2"/>
</gfe:function>
</gfe:function-service>
<bean id="function2" class="com.company.example.Function2"/>
----

91
src/asciidoc/reference/gateway.adoc Normal file
View File

@@ -0,0 +1,91 @@
[[bootstrap:gateway]]
= Configuring WAN Gateways
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 examples:
== WAN Configuration in GemFire 7.0
GemFire 7.0 introduces new APIs for WAN configuration. While the original APIs provided in GemFire 6 are still supported, it is recommended that you use the new APIs if you are using GemFire 7.0. The Spring Data GemFire namespace supports either. In the example below, `GatewaySender`s are configured for a partitioned region by adding child elements to the region (`gateway-sender` and `gateway-sender-ref`). The `GatewaySender` may register `EventFilter`s and `TransportFilters`. Also shown below is an example configuration of an `AsyncEventQueue` which must also be wired into a region (not shown).
[source,xml]
----
<gfe:partitioned-region id="region-inner-gateway-sender" >
<gfe:gateway-sender
remote-distributed-system-id="1">
<gfe:event-filter>
<bean class="org.springframework.data.gemfire.example.SomeEventFilter"/>
</gfe:event-filter>
<gfe:transport-filter>
<bean class="org.springframework.data.gemfire.example.SomeTransportFilter"/>
</gfe:transport-filter>
</gfe:gateway-sender>
<gfe:gateway-sender-ref bean="gateway-sender"/>
</gfe:partitioned-region>
<gfe:async-event-queue id="async-event-queue" batch-size="10" persistent="true" disk-store-ref="diskstore"
maximum-queue-memory="50">
<gfe:async-event-listener>
<bean class="org.springframework.data.gemfire.example.SomeAsyncEventListener"/>
</gfe:async-event-listener>
</gfe:async-event-queue>
<gfe:gateway-sender id="gateway-sender" remote-distributed-system-id="2">
<gfe:event-filter>
<ref bean="event-filter"/>
<bean class="org.springframework.data.gemfire.example.SomeEventFilter"/>
</gfe:event-filter>
<gfe:transport-filter>
<ref bean="transport-filter"/>
<bean class="org.springframework.data.gemfire.example.SomeTransportFilter"/>
</gfe:transport-filter>
</gfe:gateway-sender>
<bean id="event-filter" class="org.springframework.data.gemfire.example.AnotherEventFilter"/>
<bean id="transport-filter" class="org.springframework.data.gemfire.example.AnotherTransportFilter"/>
----
On the other end of a `GatewaySender` is a corresponding `GatewayReceiver` to receive gateway events. The `GatewayReceiver` may also be configured with `EventFilter`s and `TransportFilter`s.
[source,xml]
----
<gfe:gateway-receiver id="gateway-receiver"
start-port="12345" end-port="23456" bind-address="192.168.0.1">
<gfe:transport-filter>
<bean class="org.springframework.data.gemfire.example.SomeTransportFilter"/>
</gfe:transport-filter>
</gfe:gateway-receiver>
----
Please refer to the GemFire product document for a detailed explanation of all the configuration options.
== WAN Configuration in GemFire 6.6
[source,xml]
----
<gfe:cache/>
<gfe:replicated-region id="region-with-gateway" enable-gateway="true" hub-id="gateway-hub"/>
<gfe:gateway-hub id="gateway-hub" manual-start="true">
<gfe:gateway gateway-id="gateway">
<gfe:gateway-listener>
<bean class="com.company.example.MyGatewayListener"/>
</gfe:gateway-listener>
<gfe:gateway-queue maximum-queue-memory="5" batch-size="3"
batch-time-interval="10" />
</gfe:gateway>
<gfe:gateway gateway-id="gateway2">
<gfe:gateway-endpoint port="1234" host="host1" endpoint-id="endpoint1"/>
<gfe:gateway-endpoint port="2345" host="host2" endpoint-id="endpoint2"/>
</gfe:gateway>
</gfe:gateway-hub>
----
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 `enable-gateway` to `true` and specify the `hub-id`.
NOTE: If just a hub-id is specified, Spring Data GemFire automatically assumes that the gateway should be enabled.
Please refer to the GemFire product document for a detailed explanation of all the configuration options.

110
src/asciidoc/reference/gemfire-bootstrap.adoc Normal file
View File

@@ -0,0 +1,110 @@
[[gemfire-bootstrap]]
= Bootstrapping a Spring ApplicationContext in GemFire
== Introduction
Normally, a Spring-based application will <<bootstrap,bootstrap GemFire>> using Spring Data GemFire's XML namespace. Just by specifying a `<gfe:cache/>` element in Spring Data GemFire configuration meta-data, a single, peer GemFire Cache instance will be created and initialized with default settings in the same JVM process as your application.
However, sometimes it is a requirement, perhaps imposed by your IT operations team, that GemFire must be fully managed and operated using the provided GemFire tool suite, such as with http://pubs.vmware.com/vfabric53/topic/com.vmware.vfabric.gemfire.7.0/tools_modules/gfsh/chapter_overview.html[Gfsh]. Using *Gfsh*, even though the application and GemFire will share the same JVM process, GemFire will 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.
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.
== Using GemFire to Bootstrap a Spring Context Started with Gfsh
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 http://pubs.vmware.com/vfabric53/topic/com.vmware.vfabric.gemfire.7.0/basic_config/the_cache/setting_cache_initializer.html[Initalizer] functionality. An *Initializer* can be used to specify a callback application that is launched after the Cache is initialized by GemFire.
An *Initializer* is specified within an 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] element using a minimal snippet of GemFire's native configuration meta-data inside a `cache.xml` file. The `cache.xml` 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. `<context:component-scan base-packages="..."/>`)
As of Spring Data GemFire 1.4, such an *Initializer* is already conveniently provided by the framework, the `org.springframework.data.gemfire.support.SpringContextBootstrappingInitializer`. The typical, yet minimal configuration for this class inside GemFire's `cache.xml` file will look like the following:
[source,xml]
----
<?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>
----
The `SpringContextBootstrappingInitializer` 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 `contextConfigLocations` Servlet Context Parameter. In addition, the `SpringContextBootstrappingInitializer` class can also be used with a `basePackages` 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:
[source,xml]
----
<?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>
----
Then, with a properly configured and constructed `CLASSPATH` along with the `cache.xml` file shown above specified as a command-line option when starting a GemFire Server in Gfsh, the command-line would be:
[source]
----
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"
----
The `application-context.xml` 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 `<gfe:cache/>` element attributes, such as `cache-xml-location`, `properties-ref`, `critical-heap-percentage`, `pdx-serializer-ref`, `lock-lease`, 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 *Initializer* 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.
== Lazy-Wiring GemFire Components
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 `cache.xml` using the `WiringDeclarableSupport` class as described in <<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 *Initializer*, which occurs after all the other GemFire components and configuration have already been created and initialized.
So, in order to solve this problem, a new `LazyWiringDeclarableSupport` 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 *Initializer* 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.
In order for your GemFire application component to be auto-wired by the Spring container, create a application class that extends the `LazyWiringDeclarableSupport` and annotate any class member that needs to be provided as a Spring bean dependency, similar to:
[source,java]
----
public static final class UserDataSourceCacheLoader extends LazyWiringDeclarableSupport implements CacheLoader<String, User> {
@Autowired
private DataSource userDataSource;
...
}
----
As implied by the CacheLoader example above, you might necessarily (although, rare) have defined both a Region and CacheListener component in GemFire `cache.xml`. 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 `REPLICATE` 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 `cache.xml` configuration would be similar to the following (which comes from SDG's test suite):
[source,xml]
----
<?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>
----

21
src/asciidoc/reference/introduction.adoc Normal file
View File

@@ -0,0 +1,21 @@
[[ref-introduction]]
= Document Structure
The following chapters explain the core functionality offered by Spring Data GemFire.
<<bootstrap>> describes the configuration support provided for bootstrapping, configuring, initializing and accessing GemFire Caches, Cache Servers, Regions, and related Distributed System components.
<<apis>> explains the integration between the GemFire APIs and the various data access features available in Spring, such as transaction management and exception translation.
<<serialization>> describes the enhancements for GemFire (de)serialization and management of associated objects.
<<mapping>> describes persistence mapping for POJOs stored in GemFire using Spring Data.
<<gemfire-repositories>> describes how to create and use GemFire Repositories using Spring Data.
<<function-annotations>> describes how to create and use GemFire Functions using annotations.
<<gemfire-bootstrap>> describes how to bootstrap a Spring ApplicationContext running in a GemFire Server using Gfsh.
<<samples>> describes the samples provided with the distribution to illustrate the various features available in Spring Data GemFire.

86
src/asciidoc/reference/mapping.adoc Normal file
View File

@@ -0,0 +1,86 @@
[[mapping]]
= POJO mapping
[[mapping.entities]]
== Entity Mapping
Spring Data GemFire provides support to map entities that will be stored in a GemFire data grid. The mapping metadata is defined using annotations at the domain classes just like this:
.Mapping a domain class to a GemFire Region
====
[source,java]
----
@Region("People")
public class Person {
@Id Long id;
String firstname;
String lastname;
@PersistenceConstructor
public Person(String firstname, String lastname) {
// …
}
…
}
----
====
The first thing you see here is the `@Region` annotation that can be used to customize the Region in which the `Person` class is stored in. The `@Id` annotation can be used to annotate the property that shall be used as the Cache key. The `@PersistenceConstructor` annotation actually 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.
In addition to storing entities in top-level Regions, entities can be stored in GemFire Sub-Regions, as so:
[source,java]
----
@Region("/Users/Admin")
public class Admin extends User {
…
}
@Region("/Users/Guest")
public class Guest extends User {
...
}
----
Be sure to use the full-path of the GemFire Region, as defined in Spring Data GemFire XML namespace configuration meta-data, as specified in the `id` or `name` attributes of the `<*-region>` bean definition.
As alternative to specifying the Region in which the entity will be stored using the `@Region` annotation on the entity class, you can also specify the `@Region` annotation on the entity's `Repository` abstraction. See <<gemfire-repositories>> for more details.
However, let's say you want to store a Person in multiple GemFire Regions (e.g. `People` and `Customers`), then you can define your corresponding `Repository` interface abstractions like so:
[source,java]
----
@Region("People")
public interface PersonRepository extends GemfireRepository<Person, String> {
…
}
@Region("Customers")
public interface CustomerRepository extends GemfireRepository<Person, String> {
...
}
----
[[mapping.pdx-serializer]]
== Mapping PDX Serializer
Spring Data GemFire provides a custom `PDXSerializer` implementation that uses the mapping information to customize entity serialization. Beyond that it allows customizing the entity instantiation by using the Spring Data `EntityInstantiator` abstraction. By default the serializer uses a `ReflectionEntityInstantiator` that will use the persistence constructor of the mapped entity (either the single declared one or explicitly annoted with `@PersistenceConstructor`). To provide values for constructor parameters it will read fields with name of the constructor parameters from the `PDXReader` supplied.
.Using @Value on entity constructor parameters
====
[source,java]
----
public class Person {
public Person(@Value("#root.foo") String firstname, @Value("bean") String lastname) {
// …
}
}
----
====
The entity annotated as such will get the field `foo` read from the `PDXReader` and handed as constructor parameter value for `firstname`. The value for `lastname` will be the Spring bean with name `bean`.

539
src/asciidoc/reference/region.adoc Normal file
View File

@@ -0,0 +1,539 @@
[[bootstrap:region]]
= Configuring a GemFire Region
A region is required to store and retrieve data from the cache. `Region` is an interface extending `java.util.Map` and enables basic data access using familiar key-value semantics. The `Region` 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.
GemFire implements the following types of regions:
* *Replicated* - 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.
* *Partioned* - 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.
* *Local* - Data only exists on the local node.
* *Client* - 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.
For more information about the various region types and their capabilities as well as configuration options, please refer to the GemFire Developer's http://pubs.vmware.com/vfabricNoSuite/index.jsp?topic=/com.vmware.vfabric.gemfire.7.0/developing/book_intro.html[Guide] and community http://communities.vmware.com/community/vmtn/appplatform/vfabric_gemfire[site].
[[bootstrap:region:lookup]]
== Using an externally configured Region
For referencing regions already configured through GemFire native configuration, e.g. a `cache.xml` file, use the `lookup-region` element. Simply declare the target region name with the`name` attribute; for example, to declare a bean definition named `region-bean` for an existing region named `Orders` one can use the following bean definition:
[source,xml]
----
<gfe:lookup-region id="region-bean" name="Orders"/>
----
If the `name` is not specified, the bean's `id` will be used. The example above becomes:
[source,xml]
----
<!-- lookup for a region called 'Orders' -->
<gfe:lookup-region id="Orders"/>
----
NOTE: If the region does not exist, an initialization exception will be thrown. For configuring new GemFire regions, proceed to the appropriate sections below.
Note, in the previous examples, since no cache name was defined, the default naming convention (`gemfireCache`) was used. Alternately, one can reference the cache bean through the `cache-ref` attribute:
[source,xml]
----
<gfe:cache id="cache"/>
<gfe:lookup-region id="region-bean" name="Orders" cache-ref="cache"/>
----
The `lookup-region` provides a simple way of retrieving existing, pre-configured regions without exposing the region semantics or setup infrastructure.
[[bootstrap:region:overview]]
== Configuring Regions
Spring Data GemFire provides comprehensive support for configuring any type of GemFire Region via the following elements:
* Local Region `<local-region>`
* Replicated Region `<replicated-region>`
* Partitioned Region `<partitioned-region>`
* Client Region `<client-region>`
For a comprehensive description of http://pubs.vmware.com/vfabricNoSuite/topic/com.vmware.vfabric.gemfire.7.0/developing/region_options/region_types.html[Region types] please consult the GemFire product documentation.
[[bootstrap:region:common:attributes]]
=== Common Region Attributes
The following table(s) list attributes available for various region types:
[cols="1,2,2", options="header"]
.Common Region Attributes
|===
| Name
| Values
| Description
| cache-ref
| *GemFire Cache bean name*
| The name of the bean defining the GemFire Cache (by default 'gemfireCache').
| close
| *boolean, default:false (Note: The default was true prior to 1.3.0)*
| Indicates whether the Region should be closed at shutdown.
| concurrency-checks-enables
| *boolean, default:true*
| Determines whether members perform checks to provide consistent handling for concurrent or out-of-order updates to distributed Regions.
| data-policy
| *See GemFire's http://www.vmware.com/support/developer/vfabric-gemfire/700-api/com/gemstone/gemfire/cache/DataPolicy.html[Data Policy]*
| The Region's Data Policy. Note, not all Data Policies are supported for every Region type.
| destroy
| *boolean, default:false*
| Indicates whether the Region should be destroyed at shutdown.
| disk-store-ref
| *The name of a configured Disk Store.*
| A reference to a bean created via the `disk-store` element.
| disk-synchronous
| *boolean, default:false*
| Indicates whether Disk Store writes are synchronous.
| enable-gateway
| *boolean, default:false*
| Indicates whether the Region will synchronize entries over a WAN Gateway.
| hub-id
| *The name of the Gateway Hub.*
| This will automatically set enable-gateway to true. If enable-gateway is explicitly set to false, an exception will be thrown.
| id
| *Any valid bean name.*
| Will also be the Region name by default.
| ignore-if-exists
| *boolean, default:false*
| Ignores this bean definition configuration if the Region already exists in the GemFire Cache, resulting in a lookup instead.
| ignore-jta
| *boolean, default:false*
| Indicates whether the Region participates in JTA transactions.
| index-update-type
| *synchronous or asynchronous, default:asynchronous*
| Indicates whether indices will be updated synchronously or asynchronously on entry creation.
| initial-capacity
| *integer, default:16*
| The initial memory allocation for number of Region entries.
| key-constraint
| *Any valid, fully-qualified Java class name.*
| The expected key type.
| name
| *Any valid Region name.*
| The name of the Region definition. If not specified, it will assume the value of the id attribute (the bean name).
| persistent
| *boolean, default:false*
| Indicates whether the Region persists entries to a Disk Store (disk).
| statistics
| *boolean, default:false*
| Indicates whether the Region reports statistics.
| value-constraint
| *Any valid, fully-qualified Java class name.*
| The expected value type.
|===
[[bootstrap:region:common:cache-listener]]
=== Cache Listeners
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 http://www.vmware.com/support/developer/vfabric-gemfire/700-api/com/gemstone/gemfire/cache/CacheListener.html[`CacheListener`] interface. A region may have multiple listeners, declared using the `cache-listener` element enclosed in a `*-region` element. In the example below, there are two `CacheListener`s declared. The first references a top-level named Spring bean; the second is an anonymous inner bean definition.
[source,xml]
----
<gfe:replicated-region id="region-with-listeners">
<gfe:cache-listener>
<!-- nested cache listener reference -->
<ref bean="c-listener"/>
<!-- nested cache listener declaration -->
<bean class="some.pkg.AnotherSimpleCacheListener"/>
</gfe:cache-listener>
<bean id="c-listener" class="some.pkg.SimpleCacheListener"/>
</gfe:replicated-region>
----
The following example uses an alternate form of the `cache-listener` element with a `ref` attribute. This allows for more concise configuration for a single cache listener. Note that the namespace only allows a single `cache-listener` element so either the style above or below must be used.
WARNING: Using `ref` and a nested declaration in a `cache-listener`, or similar element, is illegal. The two options are mutually exclusive and using both on the same element will result in an exception.
[source,xml]
----
<beans>
<gfe:replicated-region id="region-with-one listener">
<gfe:cache-listener ref="c-listener"/>
</gfe:replicated-region>
<bean id="c-listener" class="some.pkg.SimpleCacheListener"/>
</beans>
----
.Bean Reference Conventions
[NOTE]
====
The `cache-listener` 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 `cache-listener` 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., `cache-listener` vs `cache-listeners`) reflecting that the most common scenario will in fact be a single instance. We have already seen examples of this pattern in the <<null,advanced cache>> configuration example.
====
[[bootstrap:region:common:loaders-writers]]
=== Cache Loaders and Cache Writers
Similar to `cache-listener`, the namespace provides `cache-loader` and `cache-writer` elements to register these respective components for a region. A `CacheLoader` is invoked on a cache miss to allow an entry to be loaded from an external data source, a database for example. A `CacheWriter` is invoked after 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 http://www.vmware.com/support/developer/vfabric-gemfire/700-api/com/gemstone/gemfire/cache/CacheLoader.html[`CacheLoader`] and http://www.vmware.com/support/developer/vfabric-gemfire/700-api/com/gemstone/gemfire/cache/CacheWriter.html[`CacheWriter`] for more details.
[[bootstrap:region:common:subregions]]
=== Subregions
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 */Customer/Address* region and a different */Employee/Address* 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: [source,xml]
----
<beans>
<gfe:replicated-region name="Customer">
<gfe:replicated-region name="Address"/>
</gfe:replicated-region>
<gfe:replicated-region name="Employee">
<gfe:replicated-region name="Address"/>
</gfe:replicated-region>
</beans>
----
Note that the `Monospaced ([id])` attribute is not permitted for a subregion. The subregions will be created with bean names */Customer/Address* and */Employee/Address*, respectively. So they may be injected using the full path name into other beans that use them, such as `GemfireTemplate`. The full path should also be used in OQL query strings.
[[bootstrap:region:common:regions-subregions-lookups-caution]]
== A Word of Caution on Regions, Subregions and Lookups
Prior to Spring Data GemFire 1.4, one of the underlying properties of the high-level `replicated-region`, `partitioned-region`, `local-region` and `client-region` elements in Spring Data GemFire's XML namespace, which correspond to GemFire's Region types based on Data Policy, is that these elements perform a lookup first before attempting to create the region. This is done in case the region already exists, which might be the case if the region was defined in GemFire's native configuration, e.g. `cache.xml`, thereby avoiding any errors. This was by design, though subject to change.
WARNING: The Spring team highly recommends that the `replicated-region`, `partitioned-region`, `local-region` and `client-region` elements be strictly used only for defining new regions. One of the problems with these elements doing a lookup first is, if the developer assumed that defining a bean definition for a REPLICATE region would create a new region, however, consequently a region with the same name already exists having different semantics for eviction, expiration, subscription and/or other attributes, this could adversely affect application logic and/or expectations thereby violating application requirements.
IMPORTANT: Recommended Practice - Only use the `replicated-region`, `partitioned-region`, `local-region` and `client-region` XML namespace elements for defining new regions.
However, because the high-level region elements perform a lookup first, this can cause problems for dependency injected region resources to application code, like DAOs or Repositories.
Take for instance the following native GemFire configuration file (e.g. `cachel.xml`)...
[source,xml]
----
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE cache PUBLIC "-//GemStone Systems, Inc.//GemFire Declarative Caching 7.0//EN"
"http://www.gemstone.com/dtd/cache7_0.dtd">
<cache>
<region name="Customers" refid="REPLICATE">
<region name="Accounts" refid="REPLICATE">
<region name="Orders" refid="REPLICATE">
<region name="Items" refid="REPLICATE"/>
</region>
</region>
</region>
</cache>
----
Also, consider that you might have defined a DAO as follows...
[source,java]
----
public class CustomerAccountDao extends GemDaoSupport {
@Resource(name = "Customers/Accounts")
private Region customersAccounts;
...
}
----
Here, we are injecting a reference to the `Customers/Accounts` GemFire Region in our DAO. As such, it is not uncommon for a developer to define beans for all or some of these regions in Spring XML configuration meta-data as follows...
[source,xml]
----
<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:gfe="http://www.springframework.org/schema/gemfire"
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">
<gfe:cache cache-xml-location="classpath:cache.xml"/>
<gfe:lookup-region name="Customers/Accounts"/>
<gfe:lookup-region name="Customers/Accounts/Orders"/>
</beans>
----
Here the `Customers/Accounts` and `Customers/Accounts/Orders` GemFire Regions are referenced as beans in the Spring context as "Customers/Accounts" and "Customers/Accounts/Orders", respectively. The nice thing about using the `lookup-region` element and the corresponding syntax above is that it allows a developer to reference a subregion directly without unnecessarily defining a bean for the parent region (e.g. `Customers`).
However, if now the developer changes his/her configuration meta-data syntax to using the nested format, like so...
[source,xml]
----
<gfe:lookup-region name="Customers">
<gfe:lookup-region name="Accounts">
<gfe:lookup-region name="Orders"/>
</gfe:lookup-region>
</gfe:lookup-region>
----
Or, perhaps the developer erroneously chooses to use the high-level `replicated-region` element, which will do a lookup first, as in...
[source,xml]
----
<gfe:replicated-region name="Customers" persistent="true">
<gfe:replicated-region name="Accounts" persistent="true">
<gfe:replicated-region name="Orders" persistent="true"/>
</gfe:replicated-region>
</gfe:replicated-region>
----
Then the region beans defined in the Spring context will consist of the following: `{ "Customers", "/Customers/Accounts", "/Customers/Accounts/Orders" }.` This means the dependency injected reference (i.e. `@Resource(name = "Customers/Accounts"))` is now broken since no bean with name "Customers/Accounts" is defined.
GemFire is flexible in referencing both parent regions and subregions. The parent can be referenced as "/Customers" or "Customers" and the child as "/Customers/Accounts" or just "Customers/Accounts". However, Spring Data GemFire is very specific when it comes to naming beans after regions, typically always using the forward slash (/) to represents subregions (e.g. "/Customers/Accounts").
Therefore, it is recommended that users use either the nested `lookup-region` syntax as illustrated above, or define direct references with a leading forward slash (/) like so...
[source,xml]
----
<gfe:lookup-region name="/Customers/Accounts"/>
<gfe:lookup-region name="/Customers/Accounts/Orders"/>
----
The example above where the nested `replicated-region` elements were used to reference the subregions serves to illustrate the problem stated earlier. Are the Customers, Accounts and Orders Regions/Subregions persistent or not? Not, since the regions were defined in native GemFire configuration (i.e. `cache.xml`) and will exist by the time the cache is initialized, or once the `<gfe:cache>` bean is created. Since the high-level region XML namespace abstractions, like `replicated-region`, perform the lookup first, it uses the regions as defined in the `cache.xml` configuration file.
[[bootstrap:region:persistence]]
== Data Persistence
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.
To enable persistence with Spring Data GemFire, simply set the `persistent` attribute to true:
[source,xml]
----
<gfe:partitioned-region id="persitent-partition" persistent="true"/>
----
IMPORTANT: Persistence for partitioned regions is supported from GemFire 6.5 onwards - configuring this option on a previous release will trigger an initialization exception.
Persistence may also be configured using the `data-policy` attribute, set to one of https://www.vmware.com/support/developer/vfabric-gemfire/700-api/com/gemstone/gemfire/cache/DataPolicy.html[GemFire's data policy settings]. For instance...
[source,xml]
----
<gfe:partitioned-region id="persitent-partition" data-policy="PERSISTENT_PARTITION"/>
----
The data policy must match the region type and must also agree with the `persistent` attribute if explicitly set. An initialization exception will be thrown if, for instance, the `persistent` attribute is set to false, yet a persistent data policy was specified.
When persisting regions, it is recommended to configure the storage through the `disk-store` element for maximum efficiency. The diskstore is referenced using the disk-store-ref attribute. Additionally, the region may perform disk writes synchronously or asynchronously:
[source,xml]
----
<gfe:partitioned-region id="persitent-partition" persistent="true" disk-store-ref="myDiskStore" disk-synchronous="true"/>
----
This is discussed further in <<bootstrap-diskstore>>
[[bootstrap:region:subscription]]
== Subscription Interest Policy
GemFire allows configuration of subscriptions to control http://pubs.vmware.com//vfabricNoSuite/topic/com.vmware.vfabric.gemfire.7.0/developing/events/configure_p2p_event_messaging.html[peer to peer event handling]. Spring Data GemFire provides a `<gfe:subscription/>` to set the interest policy on replicated and partitioned regions to either `ALL` or `CACHE_CONTENT`.
[source,xml]
----
<gfe:partitioned-region id="subscription-partition">
<gfe:subscription type="CACHE_CONTENT"/>
</gfe:partitioned-region>
----
[[bootstrap:region:eviction]]
== Data Eviction and Overflowing
Based on various constraints, each region can have an eviction policy in place for evicting data from memory. Currently, in GemFire, eviction applies to the least recently used entry (also known as http://en.wikipedia.org/wiki/Cache_algorithms#Least_Recently_Used[LRU]). Evicted entries are either destroyed or paged to disk (also known as *overflow*).
Spring Data GemFire supports all eviction policies (entry count, memory and heap usage) for both `partitioned-region` and `replicated-region` as well as `client-region`, through the nested `eviction` 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:
[source,xml]
----
<gfe:partitioned-region id="overflow-partition">
<gfe:eviction type="MEMORY_SIZE" threshold="512" action="OVERFLOW_TO_DISK"/>
</gfe:partitioned-region>
----
IMPORTANT: Replicas cannot use a `local destroy` eviction since that would invalidate them. See the GemFire docs for more information.
When configuring regions for overflow, it is recommended to configure the storage through the `disk-store` element for maximum efficiency.
For a detailed description of eviction policies, see the GemFire documentation (such as http://pubs.vmware.com/vfabricNoSuite/topic/com.vmware.vfabric.gemfire.7.0/developing/eviction/how_eviction_works.html[this] page).
== Data Expiration
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:
* *Time to live (TTL)* - 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.
* *Idle timeout* - 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.
Each of these may be applied to the region itself or entries in the region. Spring Data GemFire provides `<region-ttl>`, `<region-tti>`, `<entry-ttl>` and `<entry-tti>` region child elements to specify timeout values and expiration actions.
[[bootstrap:region:local]]
== Local Region
Spring Data GemFire offers a dedicated `local-region` 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):
[source,xml]
----
<gfe:local-region id="myLocalRegion" />
----
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 `gemfireCache`.
[[bootstrap:region:replicate]]
== Replicated Region
One of the common region types is a *replicated region* or *replica*. 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
Spring Data GemFire offers a `replicated-region` element. A minimal declaration looks as follows. All common configuration options are available for replicated regions.
[source,xml]
----
<gfe:replicated-region id="simpleReplica" />
----
[[bootstrap:region:partition]]
== Partitioned Region
Another region type supported out of the box by the Spring Data GemFire namespace is the partitioned region. To quote the GemFire docs:
"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."
A partition is created using the `partitioned-region` element. Its configuration options are similar to that of the `replicated-region` 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:
[source,xml]
----
<!-- bean definition named 'distributed-partition' backed by a region named 'redundant' with 2 copies
and a nested resolver declaration -->
<gfe:partitioned-region id="distributed-partition" copies="2" total-buckets="4" name="redundant">
<gfe:partition-resolver>
<bean class="some.pkg.SimplePartitionResolver"/>
</gfe:partition-resolver>
</gfe:partitioned-region>
----
[[bootstrap:region:partition:options]]
=== `partitioned-region` Options
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.
[cols="1,2,2", options="header"]
.partitioned-region options
|===
| Name
| Values
| Description
| partition-resolver
| *bean name*
| The name of the partitioned resolver used by this region, for custom partitioning.
| partition-listener
| *bean name*
| The name of the partitioned listener used by this region, for handling partition events.
| copies
| 0..4
| 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.
| colocated-with
| *valid region name*
| The name of the partitioned region with which this newly created partitioned region is colocated.
| local-max-memory
| *positive integer*
| The maximum amount of memory, in megabytes, to be used by the region in *this* process.
| total-max-memory
| *any integer value*
| The maximum amount of memory, in megabytes, to be used by the region in *all* processes.
| recovery-delay
| *any long value*
| 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.
| startup-recovery-delay
| *any long value*
| 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.
|===
[[bootstrap:region:client]]
== Client Region
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 *client* regions which connect to a cache server. Spring Data GemFire offers dedicated support for such configuration through <<bootstrap:cache:client>>, `client-region` and `pool` 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.
Below is a typical client region configuration:
[source,xml]
----
<!-- client region using the default client-cache pool -->
<gfe:client-region id="simple">
<gfe:cache-listener ref="c-listener"/>
</gfe:client-region>
<!-- region using its own dedicated pool -->
<gfe:client-region id="complex" pool-name="gemfire-pool">
<gfe:cache-listener ref="c-listener"/>
</gfe:client-region>
<bean id="c-listener" class="some.pkg.SimpleCacheListener"/>
<!-- pool declaration -->
<gfe:pool id="gemfire-pool" subscription-enabled="true">
<gfe:locator host="someHost" port="40403"/>
</gfe:pool>
----
As with the other region types, `client-region` supports `CacheListener``s` as well as a single `CacheLoader` or `CacheWriter`. It also requires a connection `pool` for connecting to a server. Each client can have its own pool or they can share the same one.
NOTE: In the above example, the pool is configured with a `locator`. 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 `server` element.
For a full list of options to set on the client and especially on the pool, please refer to the Spring Data GemFire schema (<<appendix-schema>>) and the GemFire documentation.
[[bootstrap:region:client:interests]]
=== Client Interests
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:
[source,xml]
----
<gfe:client-region id="complex" pool-name="gemfire-pool">
<gfe:key-interest durable="true" result-policy="KEYS">
<bean id="key" class="java.lang.String">
<constructor-arg value="someKey" />
</bean>
</gfe:key-interest>
<gfe:regex-interest pattern=".*" receive-values="false"/>
</gfe:client-region>
----
A special key `ALL_KEYS` means interest is registered for all keys (identical to a regex interest of `.*`). The `receive-values` 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.
[[bootstrap:region:json]]
== JSON Support
Gemfire 7.0 introduced support for caching JSON documents with OQL query support. These are stored internally as http://www.vmware.com/support/developer/vfabric-gemfire/700-api/com/gemstone/gemfire/pdx/PdxInstance.html[PdxInstance] types using the http://www.vmware.com/support/developer/vfabric-gemfire/700-api/com/gemstone/gemfire/pdx/JSONFormatter.html[JSONFormatter] to perform conversion to and from JSON strings. Spring Data GemFire provides a `<gfe-data:json-region-autoproxy/>` tag to enable a http://static.springsource.org/spring/docs/current/spring-framework-reference/htmlsingle/#aop-introduction[Spring AOP] component to advise appropropriate region operations, effectively encapsulating the JSONFormatter, allowing your application to work directly with JSON strings. In addition, Java objects written to JSON configured regions will be automatically converted to JSON using the Jackson ObjectMapper. Reading these values will return a JSON string.
By default, `<gfe-data:json-region-autoproxy/>` will perform the conversion on all regions. To apply this feature to selected regions, provide a comma delimited list of their ids via the `region-refs` attribute. Other attributes include a `pretty-print` flag (false by default) and `convert-returned-collections`. By default the results of region operations getAll() and values() will be converted for configured regions. This is done by creating a parallel structure in local memory. This can incur significant overhead for large collections. Set this flag to false to disable automatic conversion for these operation. NOTE: Certain region operations, specifically those that use GemFire's proprietary Region.Entry such as entries(boolean), entrySet(boolean) and getEntry() type are not targeted for AOP advice. In addition, the entrySet() method which returns a Set<java.util.Map.Entry<?,?>> is not affected.
[source,xml]
----
<gfe-data:json-region-autoproxy pretty-print="true" region-refs="myJsonRegion" convert-returned-collections="true"/>
----
This feature also works with seamlessly with GemfireTemplate operations, provided that the template is declared as a Spring bean. Currently native QueryService operations are not supported.

123
src/asciidoc/reference/repositories.adoc Normal file
View File

@@ -0,0 +1,123 @@
[[gemfire-repositories]]
= GemFire Repositories
== Introduction
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 http://static.springsource.org/spring-data/data-commons/docs/current/reference/html/#repositories[here].
[[gemfire-repositories.spring-configuration]]
== Spring configuration
To bootstrap Spring Data repositories you use the `<repositories />` element from the GemFire namespace:
.Bootstrap GemFire repositories
====
[source,xml]
----
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:gfe-data="http://www.springframework.org/schema/data/gemfire"
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/data/gemfire
http://www.springframework.org/schema/data/gemfire/spring-data-gemfire.xsd>
<gfe-data:repositories base-package="com.acme.repository" />
</beans>
----
====
This configuration snippet will look for interfaces below the configured base package and create repository instances for those interfaces backed by a `SimpleGemFireRepository`. Note that you have to have your domain classes correctly mapped to configured regions as the bottstrap process will fail otherwise.
[[gemfire-repositories.executing-queries]]
== Executing OQL queries
The GemFire repositories allow the definition of query methods to easily execute OQL queries against the Region the managed entity is mapped to.
.Sample repository
====
[source,java]
----
@Region("myRegion")
public class Person { … }
----
[source,java]
----
public interface PersonRepository extends CrudRepository<Person, Long> {
Person findByEmailAddress(String emailAddress);
Collection<Person> findByFirstname(String firstname);
@Query("SELECT * FROM /Person p WHERE p.firstname = $1")
Collection<Person> findByFirstnameAnnotated(String firstname);
@Query("SELECT * FROM /Person p WHERE p.firstname IN SET $1")
Collection<Person> findByFirstnamesAnnotated(Collection<String> firstnames);
}
----
====
The first method listed here will cause the following query to be derived: `SELECT x FROM /myRegion x WHERE x.emailAddress = $1`. The second method works the same way except it's returning all entities found whereas the first one expects a single result value. In case the supported keywords are not sufficient to declare your query or the method name gets to verbose you can annotate the query methods with `@Query` as seen for methods 3 and 4.
[cols="1,2,2", options="header"]
.Supported keywords for query methods
|===
| Keyword
| Sample
| Logical result
| `GreaterThan`
| `findByAgeGreaterThan(int age)`
| `x.age > $1`
| `GreaterThanEqual`
| `findByAgeGreaterThanEqual(int age)`
| `x.age >= $1`
| `LessThan`
| `findByAgeLessThan(int age)`
| `x.age < $1`
| `LessThanEqual`
| `findByAgeLessThanEqual(int age)`
| `x.age <= $1`
| `IsNotNull`, `NotNull`
| `findByFirstnameNotNull()`
| `x.firstname =! NULL`
| `IsNull`, `Null`
| `findByFirstnameNull()`
| `x.firstname = NULL`
| `In`
| `findByFirstnameIn(Collection<String> x)`
| `x.firstname IN SET $1`
| `NotIn`
| `findByFirstnameNotIn(Collection<String> x)`
| `x.firstname NOT IN SET $1`
| (No keyword)
| `findByFirstname(String name)`
| `x.firstname = $1`
| `Like`
| `findByFirstnameLike(String name)`
| `x.firstname LIKE $1`
| `Not`
| `findByFirstnameNot(String name)`
| `x.firstname != $1`
| `IsTrue`, `True`
| `findByActiveIsTrue()`
| `x.active = true`
| `IsFalse`, `False`
| `findByActiveIsFalse()`
| `x.active = false`
|===

88
src/asciidoc/reference/samples.adoc Normal file
View File

@@ -0,0 +1,88 @@
[[samples]]
= Sample Applications
NOTE: Sample applications are now maintained in the https://github.com/SpringSource/spring-gemfire-examples[Spring Data GemFire Examples] repository.
The Spring Data GemFire project also 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 *shell* 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.
The sample is bundled with the distribution and is Maven-based. One can easily import them into any Maven-aware IDE (such as SpringSource http://www.springsource.com/products/sts[Tool Suite]) or run them from the command-line.
[[samples:hello-world]]
== Hello World
The Hello World sample demonstrates the core functionality of the Spring GemFire project. It bootstraps GemFire, configures it, executes arbitrary commands against it and shuts it down when the application exits. Multiple instances can be started at the same time as they will work with each other sharing data without any user intervention.
.Running under Linux
NOTE: If you experience networking problems when starting GemFire or the samples, try adding the following system property `java.net.preferIPv4Stack=true` to the command line (insert `-Djava.net.preferIPv4Stack=true`). For an alternative (global) fix especially on Ubuntu see this https://jira.springsource.org/browse/SGF-28[link]
[[samples:hello-world:start-stop]]
=== Starting and stopping the sample
Hello World is designed as a stand-alone java application. It features a `Main` class which can be started either from your IDE of choice (in Eclipse/STS through `Run As/Java Application`) or from the command line through Maven using `mvn exec:java`. One can also use `java` directly on the resulting artifact if the classpath is properly set.
To stop the sample, simply type `exit` at the command line or press `Ctrl+C` to stop the VM and shutdown the Spring container.
[[samples:hello-world:run]]
=== Using the sample
Once started, the sample will create a shared data grid and allow the user to issue commands against it. The output will likely look as follows:
[source]
----
INFO: Created GemFire Cache [Spring GemFire World] v. X.Y.Z
INFO: Created new cache region [myWorld]
INFO: Member xxxxxx:50694/51611 connecting to region [myWorld]
Hello World!
Want to interact with the world ? ...
Supported commands are:
get <key> - retrieves an entry (by key) from the grid
put <key> <value> - puts a new entry into the grid
remove <key> - removes an entry (by key) from the grid
...
----
For example to add new items to the grid one can use:
[source]
----
-> Bold Section qName:emphasis level:5, chunks:[put 1 unu] attrs:[role:bold]
INFO: Added [1=unu] to the cache
null
-> Bold Section qName:emphasis level:5, chunks:[put 1 one] attrs:[role:bold]
INFO: Updated [1] from [unu] to [one]
unu
-> Bold Section qName:emphasis level:5, chunks:[size] attrs:[role:bold]
1
-> Bold Section qName:emphasis level:5, chunks:[put 2 two] attrs:[role:bold]
INFO: Added [2=two] to the cache
null
-> Bold Section qName:emphasis level:5, chunks:[size] attrs:[role:bold]
2
----
Multiple instances can be created at the same time. Once started, the new VMs automatically see the existing region and its information:
[source]
----
INFO: Connected to Distributed System ['Spring GemFire World'=xxxx:56218/49320@yyyyy]
Hello World!
...
-> Bold Section qName:emphasis level:5, chunks:[size] attrs:[role:bold]
2
-> Bold Section qName:emphasis level:5, chunks:[map] attrs:[role:bold]
[2=two] [1=one]
-> Bold Section qName:emphasis level:5, chunks:[query length = 3] attrs:[role:bold]
[one, two]
----
Experiment with the example, start (and stop) as many instances as you want, run various commands in one instance and see how the others react. To preserve data, at least one instance needs to be alive all times - if all instances are shutdown, the grid data is completely destroyed (in this example - to preserve data between runs, see the GemFire documentations).
[[samples:hello-world:explained]]
=== Hello World Sample Explained
Hello World uses both Spring XML and annotations for its configuration. The initial boostrapping configuration is `app-context.xml` which includes the cache configuration, defined under `cache-context.xml` file and performs classpath http://static.springsource.org/spring/docs/3.0.x/spring-framework-reference/html/beans.html#beans-classpath-scanning[scanning] for Spring http://static.springsource.org/spring/docs/3.0.x/spring-framework-reference/html/beans.html#beans-factorybeans-annotations[components]. The cache configuration defines the GemFire cache, region and for illustrative purposes a simple cache listener that acts as a logger.
The main *beans* are `HelloWorld` and `CommandProcessor` which rely on the `GemfireTemplate` to interact with the distributed fabric. Both classes use annotations to define their dependency and life-cycle callbacks.

45
src/asciidoc/reference/serialization.adoc Normal file
View File

@@ -0,0 +1,45 @@
[[serialization]]
= Working with GemFire Serialization
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 http://community.gemstone.com/display/gemfire/Interoperability[platforms] (such as http://community.gemstone.com/display/gemfire/Serialization+in+Java[Java], http://community.gemstone.com/display/gemfire/Serialization+in+.NET[.NET] and C++). This chapter discusses the various ways in which Spring Data GemFire simplifies and improves GemFire custom serialization in Java.
[[serialization:wiring]]
== Wiring deserialized instances
It is fairly common for serialized objects to have transient data. Transient data is often dependent on the node or environment where it lives at a certain point in time, for example a DataSource. Serializing such information is useless (and potentially even dangerous) since it is local to a certain VM/machine. For such cases, Spring Data GemFire offers a special https://www.vmware.com/support/developer/vfabric-gemfire/700-api/com/gemstone/gemfire/Instantiator.html[`Instantiator`] that performs wiring for each new instance created by GemFire during deserialization.
Through such a mechanism, one can rely on the Spring container to inject (and manage) certain dependencies making it easy to split transient from persistent data and have *rich domain objects* in a transparent manner (Spring users might find this approach similar to that of http://static.springsource.org/spring/docs/current/spring-framework-reference/html/aop.html#aop-atconfigurable[`@Configurable`]). The `WiringInstantiator` works just like `WiringDeclarableSupport`, trying to first locate a bean definition as a wiring template and following to autowiring otherwise. Please refer to the previous section (<<apis:declarable>>) for more details on wiring functionality.
To use this `Instantiator`, simply declare it as a usual bean:
[source,xml]
----
<bean id="instantiator" class="org.springframework.data.gemfire.serialization.WiringInstantiator">
<!-- DataSerializable type -->
<constructor-arg>org.pkg.SomeDataSerializableClass</constructor-arg>
<!-- type id -->
<constructor-arg>95</constructor-arg>
</bean>
----
During the container startup, once it is being initialized, the `instantiator` will, by default, register itself with the GemFire system and perform wiring on all instances of `SomeDataSerializableClass` created by GemFire during deserialization.
[[serialization:instance-generator]]
== Auto-generating custom `Instantiator`s
For data intensive applications, a large number of instances might be created on each machine as data flows in. Out of the box, GemFire uses reflection to create new types but for some scenarios, this might prove to be expensive. As always, it is good to perform profiling to quantify whether this is the case or not. For such cases, Spring Data GemFire allows the automatic generation of `Instatiator` classes which instantiate a new type (using the default constructor) without the use of reflection:
[source,xml]
----
<bean id="instantiator-factory" class="org.springframework.data.gemfire.serialization.InstantiatorFactoryBean">
<property name="customTypes">
<map>
<entry key="org.pkg.CustomTypeA" value="1025"/>
<entry key="org.pkg.CustomTypeB" value="1026"/>
</map>
</property>
</bean>
----
The definition above, automatically generated two `Instantiator`s for two classes, namely `CustomTypeA` and `CustomTypeB` and registers them with GemFire, under user id `1025` and `1026`. The two instantiators avoid the use of reflection and create the instances directly through Java code.

356
src/asciidoc/spring.css Normal file
View File

@@ -0,0 +1,356 @@
/* Asciidoctor default stylesheet | MIT License | http://asciidoctor.org */
article, aside, details, figcaption, figure, footer, header, hgroup, main, nav, section, summary { display: block; }
audio, canvas, video { display: inline-block; }
audio:not([controls]) { display: none; height: 0; }
[hidden] { display: none; }
html { background: #fff; color: #000; font-family: sans-serif; -ms-text-size-adjust: 100%; -webkit-text-size-adjust: 100%; }
body { margin: 0; }
a:focus { outline: thin dotted; }
a:active, a:hover { outline: 0; }
h1 { font-size: 2em; margin: 0.67em 0; }
abbr[title] { border-bottom: 1px dotted; }
b, strong { font-weight: bold; }
dfn { font-style: italic; }
hr { -moz-box-sizing: content-box; box-sizing: content-box; height: 0; }
mark { background: #ff0; color: #000; }
code, kbd, pre, samp { font-family: monospace, serif; font-size: 1em; }
pre { white-space: pre-wrap; }
q { quotes: "\201C" "\201D" "\2018" "\2019"; }
small { font-size: 80%; }
sub, sup { font-size: 75%; line-height: 0; position: relative; vertical-align: baseline; }
sup { top: -0.5em; }
sub { bottom: -0.25em; }
img { border: 0; }
svg:not(:root) { overflow: hidden; }
figure { margin: 0; }
fieldset { border: 1px solid #c0c0c0; margin: 0 2px; padding: 0.35em 0.625em 0.75em; }
legend { border: 0; padding: 0; }
button, input, select, textarea { font-family: inherit; font-size: 100%; margin: 0; }
button, input { line-height: normal; }
button, select { text-transform: none; }
button, html input[type="button"], input[type="reset"], input[type="submit"] { -webkit-appearance: button; cursor: pointer; }
button[disabled], html input[disabled] { cursor: default; }
input[type="checkbox"], input[type="radio"] { box-sizing: border-box; padding: 0; }
input[type="search"] { -webkit-appearance: textfield; -moz-box-sizing: content-box; -webkit-box-sizing: content-box; box-sizing: content-box; }
input[type="search"]::-webkit-search-cancel-button, input[type="search"]::-webkit-search-decoration { -webkit-appearance: none; }
button::-moz-focus-inner, input::-moz-focus-inner { border: 0; padding: 0; }
textarea { overflow: auto; vertical-align: top; }
table { border-collapse: collapse; border-spacing: 0; }
*, *:before, *:after { -moz-box-sizing: border-box; -webkit-box-sizing: border-box; box-sizing: border-box; }
html, body { font-size: 100%; }
body { background: white; color: #222222; padding: 0; margin: 0; font-family: "Helvetica Neue", "Helvetica", Helvetica, Arial, sans-serif; font-weight: normal; font-style: normal; line-height: 1; position: relative; cursor: auto; }
a:hover { cursor: pointer; }
a:focus { outline: none; }
img, object, embed { max-width: 100%; height: auto; }
object, embed { height: 100%; }
img { -ms-interpolation-mode: bicubic; }
#map_canvas img, #map_canvas embed, #map_canvas object, .map_canvas img, .map_canvas embed, .map_canvas object { max-width: none !important; }
.left { float: left !important; }
.right { float: right !important; }
.text-left { text-align: left !important; }
.text-right { text-align: right !important; }
.text-center { text-align: center !important; }
.text-justify { text-align: justify !important; }
.hide { display: none; }
.antialiased, body { -webkit-font-smoothing: antialiased; }
img { display: inline-block; vertical-align: middle; }
textarea { height: auto; min-height: 50px; }
select { width: 100%; }
p.lead, .paragraph.lead > p, #preamble > .sectionbody > .paragraph:first-of-type p { font-size: 1.21875em; line-height: 1.6; }
.subheader, #content #toctitle, .admonitionblock td.content > .title, .exampleblock > .title, .imageblock > .title, .videoblock > .title, .listingblock > .title, .literalblock > .title, .openblock > .title, .paragraph > .title, .quoteblock > .title, .sidebarblock > .title, .tableblock > .title, .verseblock > .title, .dlist > .title, .olist > .title, .ulist > .title, .qlist > .title, .hdlist > .title, .tableblock > caption { line-height: 1.4; color: #7a2518; font-weight: 300; margin-top: 0.2em; margin-bottom: 0.5em; }
div, dl, dt, dd, ul, ol, li, h1, h2, h3, #toctitle, .sidebarblock > .content > .title, h4, h5, h6, pre, form, p, blockquote, th, td { margin: 0; padding: 0; direction: ltr; }
a { color: #060; text-decoration: underline; line-height: inherit; }
a:hover, a:focus { color: #040; }
a img { border: none; }
p { font-family: inherit; font-weight: normal; font-size: 1em; line-height: 1.6; margin-bottom: 1.25em; text-rendering: optimizeLegibility; }
p aside { font-size: 0.875em; line-height: 1.35; font-style: italic; }
h1, h2, h3, #toctitle, .sidebarblock > .content > .title, h4, h5, h6 { font-family: Georgia, "URW Bookman L", Helvetica, Arial, sans-serif; font-weight: normal; font-style: normal; color: #ba3925; text-rendering: optimizeLegibility; margin-top: 1em; margin-bottom: 0.5em; line-height: 1.2125em; }
h1 small, h2 small, h3 small, #toctitle small, .sidebarblock > .content > .title small, h4 small, h5 small, h6 small { font-size: 60%; color: #e99b8f; line-height: 0; }
h1 { font-size: 2.125em; }
h2 { font-size: 1.6875em; }
h3, #toctitle, .sidebarblock > .content > .title { font-size: 1.375em; }
h4 { font-size: 1.125em; }
h5 { font-size: 1.125em; }
h6 { font-size: 1em; }
hr { border: solid #dddddd; border-width: 1px 0 0; clear: both; margin: 1.25em 0 1.1875em; height: 0; }
em, i { font-style: italic; line-height: inherit; }
strong, b { font-weight: bold; line-height: inherit; }
small { font-size: 60%; line-height: inherit; }
code { font-family: Consolas, "Liberation Mono", Courier, monospace; font-weight: normal; color: #060; }
ul, ol, dl { font-size: 1em; line-height: 1.6; margin-bottom: 1.25em; list-style-position: outside; font-family: inherit; }
ul, ol { margin-left: 1.5em; }
ul li ul, ul li ol { margin-left: 1.25em; margin-bottom: 0; font-size: 1em; }
ul.square li ul, ul.circle li ul, ul.disc li ul { list-style: inherit; }
ul.square { list-style-type: square; }
ul.circle { list-style-type: circle; }
ul.disc { list-style-type: disc; }
ul.no-bullet { list-style: none; }
ol li ul, ol li ol { margin-left: 1.25em; margin-bottom: 0; }
dl dt { margin-bottom: 0.3125em; font-weight: bold; }
dl dd { margin-bottom: 1.25em; }
abbr, acronym { text-transform: uppercase; font-size: 90%; color: #222222; border-bottom: 1px dotted #dddddd; cursor: help; }
abbr { text-transform: none; }
blockquote { margin: 0 0 1.25em; padding: 0.5625em 1.25em 0 1.1875em; border-left: 1px solid #dddddd; }
blockquote cite { display: block; font-size: inherit; color: #555555; }
blockquote cite:before { content: "\2014 \0020"; }
blockquote cite a, blockquote cite a:visited { color: #555555; }
blockquote, blockquote p { line-height: 1.6; color: #6f6f6f; }
.vcard { display: inline-block; margin: 0 0 1.25em 0; border: 1px solid #dddddd; padding: 0.625em 0.75em; }
.vcard li { margin: 0; display: block; }
.vcard .fn { font-weight: bold; font-size: 0.9375em; }
.vevent .summary { font-weight: bold; }
.vevent abbr { cursor: auto; text-decoration: none; font-weight: bold; border: none; padding: 0 0.0625em; }
@media only screen and (min-width: 768px) { h1, h2, h3, #toctitle, .sidebarblock > .content > .title, h4, h5, h6 { line-height: 1.4; }
h1 { font-size: 2.75em; }
h2 { font-size: 2.3125em; }
h3, #toctitle, .sidebarblock > .content > .title { font-size: 1.6875em; }
h4 { font-size: 1.4375em; } }
.print-only { display: none !important; }
@media print { * { background: transparent !important; color: #000 !important; box-shadow: none !important; text-shadow: none !important; }
a, a:visited { text-decoration: underline; }
a[href]:after { content: " (" attr(href) ")"; }
abbr[title]:after { content: " (" attr(title) ")"; }
.ir a:after, a[href^="javascript:"]:after, a[href^="#"]:after { content: ""; }
pre, blockquote { border: 1px solid #999; page-break-inside: avoid; }
thead { display: table-header-group; }
tr, img { page-break-inside: avoid; }
img { max-width: 100% !important; }
@page { margin: 0.5cm; }
p, h2, h3, #toctitle, .sidebarblock > .content > .title { orphans: 3; widows: 3; }
h2, h3, #toctitle, .sidebarblock > .content > .title { page-break-after: avoid; }
.hide-on-print { display: none !important; }
.print-only { display: block !important; }
.hide-for-print { display: none !important; }
.show-for-print { display: inherit !important; } }
table { background: white; margin-bottom: 1.25em; border: solid 1px #dddddd; }
table thead, table tfoot { background: whitesmoke; font-weight: bold; }
table thead tr th, table thead tr td, table tfoot tr th, table tfoot tr td { padding: 0.5em 0.625em 0.625em; font-size: inherit; color: #222222; text-align: left; }
table tr th, table tr td { padding: 0.5625em 0.625em; font-size: inherit; color: #222222; }
table tr.even, table tr.alt, table tr:nth-of-type(even) { background: #f9f9f9; }
table thead tr th, table tfoot tr th, table tbody tr td, table tr td, table tfoot tr td { display: table-cell; line-height: 1.6; }
.clearfix:before, .clearfix:after, .float-group:before, .float-group:after { content: " "; display: table; }
.clearfix:after, .float-group:after { clear: both; }
*:not(pre) > code { font-size: 0.9375em; padding: 1px 3px 0; white-space: nowrap; background-color: #f2f2f2; border: 1px solid #cccccc; -webkit-border-radius: 4px; border-radius: 4px; text-shadow: none; }
pre, pre > code { line-height: 1.4; color: inherit; font-family: Consolas, "Liberation Mono", Courier, monospace; font-weight: normal; }
kbd.keyseq { color: #555555; }
kbd:not(.keyseq) { display: inline-block; color: #222222; font-size: 0.75em; line-height: 1.4; background-color: #F7F7F7; border: 1px solid #ccc; -webkit-border-radius: 3px; border-radius: 3px; -webkit-box-shadow: 0 1px 0 rgba(0, 0, 0, 0.2), 0 0 0 2px white inset; box-shadow: 0 1px 0 rgba(0, 0, 0, 0.2), 0 0 0 2px white inset; margin: -0.15em 0.15em 0 0.15em; padding: 0.2em 0.6em 0.2em 0.5em; vertical-align: middle; white-space: nowrap; }
kbd kbd:first-child { margin-left: 0; }
kbd kbd:last-child { margin-right: 0; }
.menuseq, .menu { color: #090909; }
p a > code:hover { color: #561309; }
#header, #content, #footnotes, #footer { width: 100%; margin-left: auto; margin-right: auto; margin-top: 0; margin-bottom: 0; max-width: 62.5em; *zoom: 1; position: relative; padding-left: 0.9375em; padding-right: 0.9375em; }
#header:before, #header:after, #content:before, #content:after, #footnotes:before, #footnotes:after, #footer:before, #footer:after { content: " "; display: table; }
#header:after, #content:after, #footnotes:after, #footer:after { clear: both; }
#header { margin-bottom: 2.5em; }
#header > h1 { color: black; font-weight: normal; border-bottom: 1px solid #dddddd; margin-bottom: -28px; padding-bottom: 32px; }
#header span { color: #6f6f6f; }
#header #revnumber { text-transform: capitalize; }
#header br { display: none; }
#header br + span { padding-left: 3px; }
#header br + span:before { content: "\2013 \0020"; }
#header br + span.author { padding-left: 0; }
#header br + span.author:before { content: ", "; }
#toc { border-bottom: 3px double #ebebeb; padding-bottom: 1.25em; }
#toc > ul { margin-left: 0.25em; }
#toc ul.sectlevel0 > li > a { font-style: italic; }
#toc ul.sectlevel0 ul.sectlevel1 { margin-left: 0; margin-top: 0.5em; margin-bottom: 0.5em; }
#toc ul { list-style-type: none; }
#toctitle { color: #7a2518; }
@media only screen and (min-width: 1280px) { body.toc2 { padding-left: 20em; }
#toc.toc2 { position: fixed; width: 20em; left: 0; top: 0; border-right: 1px solid #ebebeb; border-bottom: 0; z-index: 1000; padding: 1em; height: 100%; overflow: auto; }
#toc.toc2 #toctitle { margin-top: 0; }
#toc.toc2 > ul { font-size: .95em; }
#toc.toc2 ul ul { margin-left: 0; padding-left: 1.25em; }
#toc.toc2 ul.sectlevel0 ul.sectlevel1 { padding-left: 0; margin-top: 0.5em; margin-bottom: 0.5em; }
body.toc2.toc-right { padding-left: 0; padding-right: 20em; }
body.toc2.toc-right #toc.toc2 { border-right: 0; border-left: 1px solid #ebebeb; left: auto; right: 0; } }
#content #toc { border-style: solid; border-width: 1px; border-color: #d9d9d9; margin-bottom: 1.25em; padding: 1.25em; background: #f2f2f2; border-width: 0; -webkit-border-radius: 4px; border-radius: 4px; }
#content #toc > :first-child { margin-top: 0; }
#content #toc > :last-child { margin-bottom: 0; }
#content #toc a { text-decoration: none; }
#content #toctitle { font-weight: bold; font-family: "Helvetica Neue", "Helvetica", Helvetica, Arial, sans-serif; font-size: 1em; padding-left: 0.125em; }
#footer { max-width: 100%; background-color: #222222; padding: 1.25em; }
#footer-text { color: #dddddd; line-height: 1.44; }
.sect1 { padding-bottom: 1.25em; }
.sect1 + .sect1 { border-top: 3px double #ebebeb; }
#content h1 > a.anchor, h2 > a.anchor, h3 > a.anchor, #toctitle > a.anchor, .sidebarblock > .content > .title > a.anchor, h4 > a.anchor, h5 > a.anchor, h6 > a.anchor { position: absolute; width: 1em; margin-left: -1em; display: block; text-decoration: none; visibility: hidden; text-align: center; font-weight: normal; }
#content h1 > a.anchor:before, h2 > a.anchor:before, h3 > a.anchor:before, #toctitle > a.anchor:before, .sidebarblock > .content > .title > a.anchor:before, h4 > a.anchor:before, h5 > a.anchor:before, h6 > a.anchor:before { content: '\00A7'; font-size: .85em; vertical-align: text-top; display: block; margin-top: 0.05em; }
#content h1:hover > a.anchor, #content h1 > a.anchor:hover, h2:hover > a.anchor, h2 > a.anchor:hover, h3:hover > a.anchor, #toctitle:hover > a.anchor, .sidebarblock > .content > .title:hover > a.anchor, h3 > a.anchor:hover, #toctitle > a.anchor:hover, .sidebarblock > .content > .title > a.anchor:hover, h4:hover > a.anchor, h4 > a.anchor:hover, h5:hover > a.anchor, h5 > a.anchor:hover, h6:hover > a.anchor, h6 > a.anchor:hover { visibility: visible; }
#content h1 > a.link, h2 > a.link, h3 > a.link, #toctitle > a.link, .sidebarblock > .content > .title > a.link, h4 > a.link, h5 > a.link, h6 > a.link { color: #ba3925; text-decoration: none; }
#content h1 > a.link:hover, h2 > a.link:hover, h3 > a.link:hover, #toctitle > a.link:hover, .sidebarblock > .content > .title > a.link:hover, h4 > a.link:hover, h5 > a.link:hover, h6 > a.link:hover { color: #a53221; }
.imageblock, .literalblock, .listingblock, .verseblock, .videoblock { margin-bottom: 1.25em; }
.admonitionblock td.content > .title, .exampleblock > .title, .imageblock > .title, .videoblock > .title, .listingblock > .title, .literalblock > .title, .openblock > .title, .paragraph > .title, .quoteblock > .title, .sidebarblock > .title, .tableblock > .title, .verseblock > .title, .dlist > .title, .olist > .title, .ulist > .title, .qlist > .title, .hdlist > .title { text-align: left; font-weight: bold; }
.tableblock > caption { text-align: left; font-weight: bold; white-space: nowrap; overflow: visible; max-width: 0; }
table.tableblock #preamble > .sectionbody > .paragraph:first-of-type p { font-size: inherit; }
.admonitionblock > table { border: 0; background: none; width: 100%; }
.admonitionblock > table td.icon { text-align: center; width: 80px; }
.admonitionblock > table td.icon img { max-width: none; }
.admonitionblock > table td.icon .title { font-weight: bold; text-transform: uppercase; }
.admonitionblock > table td.content { padding-left: 1.125em; padding-right: 1.25em; border-left: 1px solid #dddddd; color: #6f6f6f; }
.admonitionblock > table td.content > :last-child > :last-child { margin-bottom: 0; }
.exampleblock > .content { border-style: solid; border-width: 1px; border-color: #e6e6e6; margin-bottom: 1.25em; padding: 1.25em; background: white; -webkit-border-radius: 4px; border-radius: 4px; }
.exampleblock > .content > :first-child { margin-top: 0; }
.exampleblock > .content > :last-child { margin-bottom: 0; }
.exampleblock > .content h1, .exampleblock > .content h2, .exampleblock > .content h3, .exampleblock > .content #toctitle, .sidebarblock.exampleblock > .content > .title, .exampleblock > .content h4, .exampleblock > .content h5, .exampleblock > .content h6, .exampleblock > .content p { color: #333333; }
.exampleblock > .content h1, .exampleblock > .content h2, .exampleblock > .content h3, .exampleblock > .content #toctitle, .sidebarblock.exampleblock > .content > .title, .exampleblock > .content h4, .exampleblock > .content h5, .exampleblock > .content h6 { line-height: 1; margin-bottom: 0.625em; }
.exampleblock > .content h1.subheader, .exampleblock > .content h2.subheader, .exampleblock > .content h3.subheader, .exampleblock > .content .subheader#toctitle, .sidebarblock.exampleblock > .content > .subheader.title, .exampleblock > .content h4.subheader, .exampleblock > .content h5.subheader, .exampleblock > .content h6.subheader { line-height: 1.4; }
.exampleblock.result > .content { -webkit-box-shadow: 0 1px 8px #d9d9d9; box-shadow: 0 1px 8px #d9d9d9; }
.sidebarblock { border-style: solid; border-width: 1px; border-color: #d9d9d9; margin-bottom: 1.25em; padding: 1.25em; background: #f2f2f2; -webkit-border-radius: 4px; border-radius: 4px; }
.sidebarblock > :first-child { margin-top: 0; }
.sidebarblock > :last-child { margin-bottom: 0; }
.sidebarblock h1, .sidebarblock h2, .sidebarblock h3, .sidebarblock #toctitle, .sidebarblock > .content > .title, .sidebarblock h4, .sidebarblock h5, .sidebarblock h6, .sidebarblock p { color: #333333; }
.sidebarblock h1, .sidebarblock h2, .sidebarblock h3, .sidebarblock #toctitle, .sidebarblock > .content > .title, .sidebarblock h4, .sidebarblock h5, .sidebarblock h6 { line-height: 1; margin-bottom: 0.625em; }
.sidebarblock h1.subheader, .sidebarblock h2.subheader, .sidebarblock h3.subheader, .sidebarblock .subheader#toctitle, .sidebarblock > .content > .subheader.title, .sidebarblock h4.subheader, .sidebarblock h5.subheader, .sidebarblock h6.subheader { line-height: 1.4; }
.sidebarblock > .content > .title { color: #7a2518; margin-top: 0; line-height: 1.6; }
.exampleblock > .content > :last-child > :last-child, .exampleblock > .content .olist > ol > li:last-child > :last-child, .exampleblock > .content .ulist > ul > li:last-child > :last-child, .exampleblock > .content .qlist > ol > li:last-child > :last-child, .sidebarblock > .content > :last-child > :last-child, .sidebarblock > .content .olist > ol > li:last-child > :last-child, .sidebarblock > .content .ulist > ul > li:last-child > :last-child, .sidebarblock > .content .qlist > ol > li:last-child > :last-child { margin-bottom: 0; }
.literalblock > .content pre, .listingblock > .content pre { background: none; border-width: 1px 0; border-style: dotted; border-color: #bfbfbf; -webkit-border-radius: 4px; border-radius: 4px; padding: 0.75em 0.75em 0.5em 0.75em; word-wrap: break-word; }
.literalblock > .content pre.nowrap, .listingblock > .content pre.nowrap { overflow-x: auto; white-space: pre; word-wrap: normal; }
.literalblock > .content pre > code, .listingblock > .content pre > code { display: block; }
@media only screen { .literalblock > .content pre, .listingblock > .content pre { font-size: 0.8em; } }
@media only screen and (min-width: 768px) { .literalblock > .content pre, .listingblock > .content pre { font-size: 0.9em; } }
@media only screen and (min-width: 1280px) { .literalblock > .content pre, .listingblock > .content pre { font-size: 1em; } }
.listingblock > .content { position: relative; }
.listingblock:hover code[class*=" language-"]:before { text-transform: uppercase; font-size: 0.9em; color: #999; position: absolute; top: 0.375em; right: 0.375em; }
.listingblock:hover code.asciidoc:before { content: "asciidoc"; }
.listingblock:hover code.clojure:before { content: "clojure"; }
.listingblock:hover code.css:before { content: "css"; }
.listingblock:hover code.groovy:before { content: "groovy"; }
.listingblock:hover code.html:before { content: "html"; }
.listingblock:hover code.java:before { content: "java"; }
.listingblock:hover code.javascript:before { content: "javascript"; }
.listingblock:hover code.python:before { content: "python"; }
.listingblock:hover code.ruby:before { content: "ruby"; }
.listingblock:hover code.scss:before { content: "scss"; }
.listingblock:hover code.xml:before { content: "xml"; }
.listingblock:hover code.yaml:before { content: "yaml"; }
.listingblock.terminal pre .command:before { content: attr(data-prompt); padding-right: 0.5em; color: #999; }
.listingblock.terminal pre .command:not([data-prompt]):before { content: '$'; }
table.pyhltable { border: 0; margin-bottom: 0; }
table.pyhltable td { vertical-align: top; padding-top: 0; padding-bottom: 0; }
table.pyhltable td.code { padding-left: .75em; padding-right: 0; }
.highlight.pygments .lineno, table.pyhltable td:not(.code) { color: #999; padding-left: 0; padding-right: .5em; border-right: 1px solid #dddddd; }
.highlight.pygments .lineno { display: inline-block; margin-right: .25em; }
table.pyhltable .linenodiv { background-color: transparent !important; padding-right: 0 !important; }
.quoteblock { margin: 0 0 1.25em; padding: 0.5625em 1.25em 0 1.1875em; border-left: 1px solid #dddddd; }
.quoteblock blockquote { margin: 0 0 1.25em 0; padding: 0 0 0.5625em 0; border: 0; }
.quoteblock blockquote > .paragraph:last-child p { margin-bottom: 0; }
.quoteblock .attribution { margin-top: -.25em; padding-bottom: 0.5625em; font-size: inherit; color: #555555; }
.quoteblock .attribution br { display: none; }
.quoteblock .attribution cite { display: block; margin-bottom: 0.625em; }
table thead th, table tfoot th { font-weight: bold; }
table.tableblock.grid-all { border-collapse: separate; border-spacing: 1px; -webkit-border-radius: 4px; border-radius: 4px; border-top: 1px solid #dddddd; border-bottom: 1px solid #dddddd; }
table.tableblock.frame-topbot, table.tableblock.frame-none { border-left: 0; border-right: 0; }
table.tableblock.frame-sides, table.tableblock.frame-none { border-top: 0; border-bottom: 0; }
table.tableblock td .paragraph:last-child p, table.tableblock td > p:last-child { margin-bottom: 0; }
th.tableblock.halign-left, td.tableblock.halign-left { text-align: left; }
th.tableblock.halign-right, td.tableblock.halign-right { text-align: right; }
th.tableblock.halign-center, td.tableblock.halign-center { text-align: center; }
th.tableblock.valign-top, td.tableblock.valign-top { vertical-align: top; }
th.tableblock.valign-bottom, td.tableblock.valign-bottom { vertical-align: bottom; }
th.tableblock.valign-middle, td.tableblock.valign-middle { vertical-align: middle; }
p.tableblock.header { color: #222222; font-weight: bold; }
td > div.verse { white-space: pre; }
ol { margin-left: 1.75em; }
ul li ol { margin-left: 1.5em; }
dl dd { margin-left: 1.125em; }
dl dd:last-child, dl dd:last-child > :last-child { margin-bottom: 0; }
ol > li p, ul > li p, ul dd, ol dd, .olist .olist, .ulist .ulist, .ulist .olist, .olist .ulist { margin-bottom: 0.625em; }
ul.unstyled, ol.unnumbered, ul.checklist, ul.none { list-style-type: none; }
ul.unstyled, ol.unnumbered, ul.checklist { margin-left: 0.625em; }
ul.checklist li > p:first-child > i[class^="icon-check"]:first-child, ul.checklist li > p:first-child > input[type="checkbox"]:first-child { margin-right: 0.25em; }
ul.checklist li > p:first-child > input[type="checkbox"]:first-child { position: relative; top: 1px; }
ul.inline { margin: 0 auto 0.625em auto; margin-left: -1.375em; margin-right: 0; padding: 0; list-style: none; overflow: hidden; }
ul.inline > li { list-style: none; float: left; margin-left: 1.375em; display: block; }
ul.inline > li > * { display: block; }
.unstyled dl dt { font-weight: normal; font-style: normal; }
ol.arabic { list-style-type: decimal; }
ol.decimal { list-style-type: decimal-leading-zero; }
ol.loweralpha { list-style-type: lower-alpha; }
ol.upperalpha { list-style-type: upper-alpha; }
ol.lowerroman { list-style-type: lower-roman; }
ol.upperroman { list-style-type: upper-roman; }
ol.lowergreek { list-style-type: lower-greek; }
.hdlist > table, .colist > table { border: 0; background: none; }
.hdlist > table > tbody > tr, .colist > table > tbody > tr { background: none; }
td.hdlist1 { padding-right: .8em; font-weight: bold; }
td.hdlist1, td.hdlist2 { vertical-align: top; }
.literalblock + .colist, .listingblock + .colist { margin-top: -0.5em; }
.colist > table tr > td:first-of-type { padding: 0 .8em; line-height: 1; }
.colist > table tr > td:last-of-type { padding: 0.25em 0; }
.qanda > ol > li > p > em:only-child { color: #00467f; }
.thumb, .th { line-height: 0; display: inline-block; border: solid 4px white; -webkit-box-shadow: 0 0 0 1px #dddddd; box-shadow: 0 0 0 1px #dddddd; }
.imageblock.left, .imageblock[style*="float: left"] { margin: 0.25em 0.625em 1.25em 0; }
.imageblock.right, .imageblock[style*="float: right"] { margin: 0.25em 0 1.25em 0.625em; }
.imageblock > .title { margin-bottom: 0; }
.imageblock.thumb, .imageblock.th { border-width: 6px; }
.imageblock.thumb > .title, .imageblock.th > .title { padding: 0 0.125em; }
.image.left, .image.right { margin-top: 0.25em; margin-bottom: 0.25em; display: inline-block; line-height: 0; }
.image.left { margin-right: 0.625em; }
.image.right { margin-left: 0.625em; }
a.image { text-decoration: none; }
span.footnote, span.footnoteref { vertical-align: super; font-size: 0.875em; }
span.footnote a, span.footnoteref a { text-decoration: none; }
#footnotes { padding-top: 0.75em; padding-bottom: 0.75em; margin-bottom: 0.625em; }
#footnotes hr { width: 20%; min-width: 6.25em; margin: -.25em 0 .75em 0; border-width: 1px 0 0 0; }
#footnotes .footnote { padding: 0 0.375em; line-height: 1.3; font-size: 0.875em; margin-left: 1.2em; text-indent: -1.2em; margin-bottom: .2em; }
#footnotes .footnote a:first-of-type { font-weight: bold; text-decoration: none; }
#footnotes .footnote:last-of-type { margin-bottom: 0; }
#content #footnotes { margin-top: -0.625em; margin-bottom: 0; padding: 0.75em 0; }
.gist .file-data > table { border: none; background: #fff; width: 100%; margin-bottom: 0; }
.gist .file-data > table td.line-data { width: 99%; }
div.unbreakable { page-break-inside: avoid; }
.big { font-size: larger; }
.small { font-size: smaller; }
.underline { text-decoration: underline; }
.overline { text-decoration: overline; }
.line-through { text-decoration: line-through; }
.aqua { color: #00bfbf; }
.aqua-background { background-color: #00fafa; }
.black { color: black; }
.black-background { background-color: black; }
.blue { color: #0000bf; }
.blue-background { background-color: #0000fa; }
.fuchsia { color: #bf00bf; }
.fuchsia-background { background-color: #fa00fa; }
.gray { color: #606060; }
.gray-background { background-color: #7d7d7d; }
.green { color: #006000; }
.green-background { background-color: #007d00; }
.lime { color: #00bf00; }
.lime-background { background-color: #00fa00; }
.maroon { color: #600000; }
.maroon-background { background-color: #7d0000; }
.navy { color: #000060; }
.navy-background { background-color: #00007d; }
.olive { color: #606000; }
.olive-background { background-color: #7d7d00; }
.purple { color: #600060; }
.purple-background { background-color: #7d007d; }
.red { color: #bf0000; }
.red-background { background-color: #fa0000; }
.silver { color: #909090; }
.silver-background { background-color: #bcbcbc; }
.teal { color: #006060; }
.teal-background { background-color: #007d7d; }
.white { color: #bfbfbf; }
.white-background { background-color: #fafafa; }
.yellow { color: #bfbf00; }
.yellow-background { background-color: #fafa00; }
span.icon > [class^="icon-"], span.icon > [class*=" icon-"] { cursor: default; }
.admonitionblock td.icon [class^="icon-"]:before { font-size: 2.5em; text-shadow: 1px 1px 2px rgba(0, 0, 0, 0.5); cursor: default; }
.admonitionblock td.icon .icon-note:before { content: "\f05a"; color: #005498; color: #003f72; }
.admonitionblock td.icon .icon-tip:before { content: "\f0eb"; text-shadow: 1px 1px 2px rgba(155, 155, 0, 0.8); color: #111; }
.admonitionblock td.icon .icon-warning:before { content: "\f071"; color: #bf6900; }
.admonitionblock td.icon .icon-caution:before { content: "\f06d"; color: #bf3400; }
.admonitionblock td.icon .icon-important:before { content: "\f06a"; color: #bf0000; }
.conum { display: inline-block; color: white !important; background-color: #222222; -webkit-border-radius: 100px; border-radius: 100px; text-align: center; width: 20px; height: 20px; font-size: 12px; font-weight: bold; line-height: 20px; font-family: Arial, sans-serif; font-style: normal; position: relative; top: -2px; letter-spacing: -1px; }
.conum * { color: white !important; }
.conum + b { display: none; }
.conum:after { content: attr(data-value); }
.conum:not([data-value]):empty { display: none; }
.literalblock > .content > pre, .listingblock > .content > pre { -webkit-border-radius: 0; border-radius: 0; }
/** Spring IO customizations **/
h1, h2, h3, #toctitle, .sidebarblock > .content > .title, h4, h5, h6 { color: #060; }
.subheader, #content #toctitle, .admonitionblock td.content > .title, .exampleblock > .title, .imageblock > .title, .videoblock > .title, .listingblock > .title, .literalblock > .title, .openblock > .title, .paragraph > .title, .quoteblock > .title, .sidebarblock > .title, .tableblock > .title, .verseblock > .title, .dlist > .title, .olist > .title, .ulist > .title, .qlist > .title, .hdlist > .title, .tableblock > caption { color: #080; }