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

Additional Spring Data GemFire Reference Guide changes and additions to round out the new feature documentation in Spring Data GemFire 1.4.

Browse Source
This commit is contained in:
John Blum
2014-05-19 23:34:42 -07:00
parent 88e2b2b60e
commit 9aab9ac79e
6 changed files with 149 additions and 76 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="UTF-8"?>
<chapter xml:id="new-features" xmlns="http://docbook.org/ns/docbook" version="5.0">
<chapter id="new-features" version="5.0" xmlns="http://docbook.org/ns/docbook">
<title>New Features</title>
<note>
@@ -210,15 +210,22 @@
</para>
</listitem>
<listitem>
<para>Support for bootstrapping a Spring Context in a GemFire Server when started from Gfsh.</para>
<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.</para>
<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>
@@ -232,6 +239,9 @@
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>

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

@@ -1,8 +1,8 @@
<?xml version="1.0" encoding="UTF-8"?>
<chapter version="5.0" xml:id="bootstrap"
<chapter id="bootstrap" 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:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink">
<title>Bootstrapping GemFire through the Spring Container</title>
<para>
@@ -21,8 +21,7 @@
</note>
<section id="bootstrap:region:spring:config">
<title>Advantages of using Spring over GemFire
<literal>cache.xml</literal></title>
<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

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

@@ -1,25 +1,25 @@
<?xml version="1.0" encoding="UTF-8"?>
<chapter xml:id="gemfire-bootstrap" xmlns="http://docbook.org/ns/docbook" version="5.0">
<title>GemFire Bootstrapping a Spring ApplicationContext with Gfsh</title>
<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 is used to <link linkend="bootstrap">bootstrap GemFire</link>
using Spring Data GemFire's XML namespace elements. Just by specifying a <literal>&lt;gfe:cache/&gt;</literal>
element in Spring Data GemFire configuration meta-data, a Singleton GemFire, peer Cache instance will be
created and initialized, using default settings, in the same JVM process as your application.
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 GemFire tool suite, such as with
<ulink url="http://pubs.vmware.com/vfabric53/topic/com.vmware.vfabric.gemfire.7.0/tools_modules/gfsh/chapter_overview.html">Gfsh</ulink>
for instance. Using <emphasis>Gfsh</emphasis>, even though the application and GemFire will share the same
JVM process, GemFire will instead bootstrap your Spring application context rather than the other way around.
So, using this approach GemFire, instead of an application server, or a Java main class using Spring Boot,
will bootstrap and host your application.
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>
@@ -129,8 +129,8 @@
However, this only works when Spring does the bootstrapping (i.e. bootstraps GemFire). When your Spring
application context is the one bootstrapped by GemFire, then these GemFire components go unnoticed since
the Spring application context does not even exist yet! The Spring application context will not get created
until GemFire calls the <emphasis>Initializer</emphasis>, which is after all the other GemFire components
and configuration has already been created and initialized.
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>
@@ -143,13 +143,29 @@
</para>
<para>
For instance, you might necessarily (although, rare) have defined both a Region and CacheListener component
in GemFire <literal>cache.xml</literal>. The CacheLoader may need access to an application DAO, or perhaps
Spring application context defined JDBC Data Source for loading "Users" into a GemFire Cache
<literal>REPLICATE</literal> Region on start. Of course, one should be careful in mixing the different
life-cycles of GemFire and the Spring Container together in this manner as not all use cases and scenarios
are supported. The GemFire <literal>cache.xml</literal> configuration would be similar to the following
(which comes from SDG's test suite):
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"?>

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

@@ -1,6 +1,5 @@
<?xml version="1.0" encoding="UTF-8"?>
<chapter version="5.0" xml:id="ref-introduction"
xmlns="http://docbook.org/ns/docbook">
<chapter id="ref-introduction" version="5.0" xmlns="http://docbook.org/ns/docbook">
<title>Document Structure</title>
<para>
@@ -34,6 +33,11 @@
<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.

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

@@ -1,24 +1,19 @@
<?xml version="1.0" encoding="UTF-8"?>
<chapter version="5.0" xml:id="mapping" 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">
<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>
<section xml:id="mapping.entities">
<title>Entity Mapping</title>
<para>Spring Data GemFire provides support to map entities to be stored in
a GemFire grid. The mapping metadata is define by using annotations at the
domain classes just like this: </para>
<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 GemFire</title>
<example>
<title>Mapping a domain class to a GemFire Region</title>
<programlisting language="java">@Region("myRegion")
<programlisting language="java">@Region("People")
public class Person {
@Id Long id;
@@ -31,24 +26,69 @@ public class Person {
}
…
} </programlisting>
}
</programlisting>
</example>
</example>
<para>The first thing you see here is the
<interfacename>@Region</interfacename> annotation that can be used to
customize the region instances of the <classname>Person</classname> class
are stored in. The <interfacename>@Id</interfacename> annotation can be
used to annotate the property that shall be used as cache key. The
<interfacename>@PersistenceConstructor</interfacename> annotation actually
helps 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>
</section>
<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>
<section xml:id="mapping.pdx-serializer">
<title>Mapping PDX serializer</title>
<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
@@ -82,4 +122,5 @@ public class Person {
<code>lastname</code> will be the Spring bean with name
<code>bean</code>.</para>
</section>
</chapter>
</chapter>

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

@@ -1,12 +1,5 @@
<?xml version="1.0" encoding="UTF-8"?>
<section id="bootstrap:region" version="5.0"
xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:ns5="http://www.w3.org/1998/Math/MathML"
xmlns:ns4="http://www.w3.org/2000/svg"
xmlns:ns3="http://www.w3.org/1999/xhtml"
xmlns:ns="http://docbook.org/ns/docbook">
<section id="bootstrap:region" version="5.0" xmlns="http://docbook.org/ns/docbook">
<title>Configuring a GemFire Region</title>
<para xmlns="">A region is required to store and retrieve data from the
@@ -238,6 +231,16 @@
Will also be the Region name by default.
</entry>
</row>
<row>
<entry>ignore-if-exists</entry>
<entry spanname="values">
<emphasis>boolean, default:false</emphasis>
</entry>
<entry spanname="description">
Ignores this bean definition configuration if the Region already exists
in the GemFire Cache, resulting in a lookup instead.
</entry>
</row>
<row>
<entry>ignore-jta</entry>
<entry spanname="values">
@@ -437,12 +440,12 @@
<section id="bootstrap:region:common:regions-subregions-lookups-caution">
<title>A Word of Caution on Regions, Subregions and Lookups</title>
<para>One of the underlying properties of the high-level <literal>replicated-region</literal>,
<literal>partitioned-region</literal>, <literal>local-region</literal> and <literal>client-region</literal>
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. <literal>cache.xml</literal>, thereby avoiding any errors.
<para>Prior to Spring Data GemFire 1.4, one of the underlying properties of the high-level
<literal>replicated-region</literal>, <literal>partitioned-region</literal>, <literal>local-region</literal>
and <literal>client-region</literal> 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. <literal>cache.xml</literal>, thereby avoiding any errors.
This was by design, though subject to change.</para>
<caution>