From 9aab9ac79e6ff62b363e742efa34d9d2aea64f62 Mon Sep 17 00:00:00 2001 From: John Blum Date: Mon, 19 May 2014 23:34:42 -0700 Subject: [PATCH] Additional Spring Data GemFire Reference Guide changes and additions to round out the new feature documentation in Spring Data GemFire 1.4. --- .../docbook/introduction/new-features.xml | 16 ++- .../reference/docbook/reference/bootstrap.xml | 9 +- .../docbook/reference/gemfire-bootstrap.xml | 58 ++++++---- .../docbook/reference/introduction.xml | 8 +- .../reference/docbook/reference/mapping.xml | 103 ++++++++++++------ .../reference/docbook/reference/region.xml | 31 +++--- 6 files changed, 149 insertions(+), 76 deletions(-) diff --git a/docs/src/reference/docbook/introduction/new-features.xml b/docs/src/reference/docbook/introduction/new-features.xml index 6ea22ac5..de5ec85b 100644 --- a/docs/src/reference/docbook/introduction/new-features.xml +++ b/docs/src/reference/docbook/introduction/new-features.xml @@ -1,5 +1,5 @@ - + New Features @@ -210,15 +210,22 @@ - Support for bootstrapping a Spring Context in a GemFire Server when started from Gfsh. + + Support for bootstrapping a Spring Context in a GemFire Server when started from Gfsh. + See . + - Support for persisting application domain object/entities to multiple GemFire Cache Regions. + + Support for persisting application domain object/entities to multiple GemFire Cache Regions. + See 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 for more details. @@ -232,6 +239,9 @@ 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 Common Region Attributes + and + for more details. diff --git a/docs/src/reference/docbook/reference/bootstrap.xml b/docs/src/reference/docbook/reference/bootstrap.xml index f3239a94..dc69c635 100644 --- a/docs/src/reference/docbook/reference/bootstrap.xml +++ b/docs/src/reference/docbook/reference/bootstrap.xml @@ -1,8 +1,8 @@ - + xmlns:xi="http://www.w3.org/2001/XInclude" + xmlns:xlink="http://www.w3.org/1999/xlink"> Bootstrapping GemFire through the Spring Container @@ -21,8 +21,7 @@
- Advantages of using Spring over GemFire - <literal>cache.xml</literal> + Advantages of using Spring over GemFire <literal>cache.xml</literal> As of release 1.2.0, Spring Data GemFire's XML namespace supports full configuration of the data grid. In fact, the Spring Data diff --git a/docs/src/reference/docbook/reference/gemfire-bootstrap.xml b/docs/src/reference/docbook/reference/gemfire-bootstrap.xml index 323a524f..5590d701 100644 --- a/docs/src/reference/docbook/reference/gemfire-bootstrap.xml +++ b/docs/src/reference/docbook/reference/gemfire-bootstrap.xml @@ -1,25 +1,25 @@ - - GemFire Bootstrapping a Spring ApplicationContext with Gfsh + + Bootstrapping a Spring ApplicationContext in GemFire
Introduction - Normally, a Spring-based application is used to bootstrap GemFire - using Spring Data GemFire's XML namespace elements. Just by specifying a <gfe:cache/> - 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 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 GemFire tool suite, such as with - Gfsh - for instance. Using Gfsh, 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 + 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. @@ -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 Initializer, which is after all the other GemFire components - and configuration has already been created and initialized. + until GemFire calls the Initializer, which occurs after all the other GemFire components + and configuration have already been created and initialized. @@ -143,13 +143,29 @@ - For instance, 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): + 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: + + + { + + @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): diff --git a/docs/src/reference/docbook/reference/introduction.xml b/docs/src/reference/docbook/reference/introduction.xml index edb0a938..7483eeab 100644 --- a/docs/src/reference/docbook/reference/introduction.xml +++ b/docs/src/reference/docbook/reference/introduction.xml @@ -1,6 +1,5 @@ - + Document Structure @@ -34,6 +33,11 @@ describes how to create and use GemFire Functions using annotations. + + describes how to bootstrap a Spring ApplicationContext running + in a GemFire Server using Gfsh. + + describes the samples provided with the distribution to illustrate the various features available in Spring Data GemFire. diff --git a/docs/src/reference/docbook/reference/mapping.xml b/docs/src/reference/docbook/reference/mapping.xml index a9280697..f3445378 100644 --- a/docs/src/reference/docbook/reference/mapping.xml +++ b/docs/src/reference/docbook/reference/mapping.xml @@ -1,24 +1,19 @@ - + POJO mapping -
- Entity mapping +
+ Entity Mapping - 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: + + 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 GemFire + + Mapping a domain class to a GemFire Region - @Region("myRegion") + @Region("People") public class Person { @Id Long id; @@ -31,24 +26,69 @@ public class Person { } … -} +} + - + - The first thing you see here is the - @Region annotation that can be used to - customize the region instances of the Person class - are stored in. The @Id annotation can be - used to annotate the property that shall be used as 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. -
+ + 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. + -
- Mapping PDX serializer + + In addition to storing entities in top-level Regions, entities can be stored in GemFire Sub-Regions, as so: + + + @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 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: + + + { +… +} + +@Region("Customers") +public interface CustomerRepository extends GemfireRepository { +... +} + ]]> +
+ +
+ Mapping PDX Serializer Spring Data GemFire provides a custom PDXSerializer implementation that uses the @@ -82,4 +122,5 @@ public class Person { lastname will be the Spring bean with name bean.
- \ No newline at end of file + + diff --git a/docs/src/reference/docbook/reference/region.xml b/docs/src/reference/docbook/reference/region.xml index 91b50745..ed8459fd 100644 --- a/docs/src/reference/docbook/reference/region.xml +++ b/docs/src/reference/docbook/reference/region.xml @@ -1,12 +1,5 @@ -
+
Configuring a GemFire Region A region is required to store and retrieve data from the @@ -238,6 +231,16 @@ 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 @@ -437,12 +440,12 @@
A Word of Caution on Regions, Subregions and Lookups - 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. + 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.