From 3b793686bd70e3afde40d54c1ff734a2163e74ab Mon Sep 17 00:00:00 2001 From: David Turanski Date: Wed, 22 Aug 2012 08:08:13 -0400 Subject: [PATCH] updated documentation; build upgraded to jdk 1.6. Schema clean up --- README.md | 27 +- build.gradle | 4 +- docs/src/api/overview.html | 4 +- docs/src/info/changelog.txt | 29 +- docs/src/info/readme.txt | 15 +- .../docbook/appendix/appendix-schema.xml | 13 +- docs/src/reference/docbook/index.xml | 6 +- .../docbook/introduction/introduction.xml | 24 +- .../docbook/introduction/new-features.xml | 11 +- .../docbook/introduction/requirements.xml | 2 +- docs/src/reference/docbook/links.xml | 18 +- .../reference/docbook/reference/bootstrap.xml | 1174 +++-------------- .../src/reference/docbook/reference/cache.xml | 312 +++++ .../reference/docbook/reference/client.xml | 4 + .../docbook/reference/cq-container.xml | 16 +- docs/src/reference/docbook/reference/data.xml | 97 +- .../reference/docbook/reference/diskstore.xml | 38 + .../reference/docbook/reference/function.xml | 30 + .../reference/docbook/reference/gateway.xml | 48 + .../docbook/reference/introduction.xml | 23 +- .../reference/docbook/reference/mapping.xml | 12 +- .../reference/docbook/reference/region.xml | 850 ++++++++++++ .../docbook/reference/repositories.xml | 19 +- .../reference/docbook/reference/samples.xml | 6 +- .../docbook/reference/serialization.xml | 10 +- .../gemfire/config/spring-gemfire-1.2.xsd | 417 +----- 26 files changed, 1689 insertions(+), 1520 deletions(-) create mode 100644 docs/src/reference/docbook/reference/cache.xml create mode 100644 docs/src/reference/docbook/reference/client.xml create mode 100644 docs/src/reference/docbook/reference/diskstore.xml create mode 100644 docs/src/reference/docbook/reference/function.xml create mode 100644 docs/src/reference/docbook/reference/gateway.xml create mode 100644 docs/src/reference/docbook/reference/region.xml diff --git a/README.md b/README.md index 9589ca1e..8d639267 100644 --- a/README.md +++ b/README.md @@ -1,17 +1,19 @@ Spring Data GemFire =================== -The primary goal of the [Spring GemFire](http://www.springsource.org/spring-gemfire) project is to make it easier to build highly scalable Spring-powered applications using -[GemFire](http://www.gemstone.com/products/gemfire) as a distributed [data management](http://www.springsource.com/products/data-management) platform. +The primary goal of the [Spring Data GemFire](http://www.springsource.org/spring-gemfire) project is to make it easier to build highly scalable Spring-powered applications using +[vFabric GemFire](http://www.vmware.com/products/application-platform/vfabric-gemfire) as a distributed [data management](http://www.springsource.com/products/data-management) platform. # Examples -For examples on using the Spring GemFire, see the samples project. +For examples on using the Spring Data GemFire, see the [spring-gemfire-examples](https://github.com/SpringSource/spring-gemfire-examples) project. # Getting Help - -Read the main project [website](http://www.springsource.org/spring-gemfire) and the [User Guide](http://static.springsource.org/spring-gemfire/docs/current/reference/html/). Look at the source code and the [JavaDocs](http://static.springsource.org/spring-gemfire/docs/current/api/). For more detailed questions, use the [forum](http://forum.springsource.org/forumdisplay.php?f=80). If you are new to Spring as well as to Spring GemFire, look for information about [Spring projects](http://www.springsource.org/projects). +Read the main project [website](http://www.springsource.org/spring-gemfire) and the [User Guide](http://static.springsource.org/spring-gemfire/docs/current/reference/html/). +Look at the source code and the [JavaDocs](http://static.springsource.org/spring-gemfire/docs/current/api/). +For more detailed questions, use the [forum](http://forum.springsource.org/forumdisplay.php?f=80). +If you are new to Spring as well as to Spring Data GemFire, look for information about [Spring projects](http://www.springsource.org/projects). Quick Start ----------- @@ -34,14 +36,21 @@ For those in a hurry: spring-maven-snapshot true Springframework Maven SNAPSHOT Repository - http://maven.springframework.org/snapshot + http://repo.springsource.org/snapshot spring-maven-milestone Springframework Maven Milestone Repository - http://maven.springframework.org/milestone + http://repo.springsource.org/milestone + + + + + spring-maven-plugins-release + Springframework Maven Plugins Release Repository + http://repo.springsource.org/plugins-release ~~~~~ @@ -49,8 +58,8 @@ For those in a hurry: ~~~~~ groovy repositories { - mavenRepo name: "spring-snapshot", urls: "http://maven.springframework.org/snapshot" - mavenRepo name: "spring-milestone", urls: "http://maven.springframework.org/milestone" + mavenRepo name: "spring-snapshot", urls: "http://repo.springsource.org/snapshot" + mavenRepo name: "spring-milestone", urls: "http://repo.springsource.org/milestone" } dependencies { diff --git a/build.gradle b/build.gradle index 41be5fb1..602a8b5b 100644 --- a/build.gradle +++ b/build.gradle @@ -64,8 +64,8 @@ dependencies { testCompile "org.apache.derby:derbyLocale_zh_TW:10.9.1.0" } -sourceCompatibility = 1.5 -targetCompatibility = 1.5 +sourceCompatibility = 1.6 +targetCompatibility = 1.6 javadoc { ext.srcDir = file("${projectDir}/docs/src/api") diff --git a/docs/src/api/overview.html b/docs/src/api/overview.html index 7c18e2f3..d09ca646 100644 --- a/docs/src/api/overview.html +++ b/docs/src/api/overview.html @@ -1,6 +1,6 @@ -This document is the API specification for the Spring GemFire project. +This document is the API specification for the Spring Data GemFire project.
@@ -15,7 +15,7 @@ This document is the API specification for the Spring GemFire project. -->

If you are interested in commercial training, consultancy and - support for the Spring GemFire project, + support for the Spring Data GemFire project, SpringSource provides such commercial support.

diff --git a/docs/src/info/changelog.txt b/docs/src/info/changelog.txt index b9cc40c3..9313930b 100644 --- a/docs/src/info/changelog.txt +++ b/docs/src/info/changelog.txt @@ -5,27 +5,34 @@ http://www.springsource.org/spring-gemfire Changes in version 1.2.0.RELEASE (2012-08-15) --------------------------------------------- General +* Added support for Spring Data repositories * The Spring Data GemFire project, formerly Spring GemFire, is now a component of the Spring Data project -* Upgraded to GemFire 7.0 * Upgraded to Spring 3.1.2.RELEASE * Upgraded to Spring Data Commons 1.4.0.RELEASE -* The XML namespace supports everything that can be configured with Cache XML -* A separate namespace for Spring Data Repository support +* The XML namespace provides support for everything that can be configured natively with Cache XML +* A separate XML namespace has been created for Spring Data Repository support Enhancements -* [SGF-53] - Add "enable-gateway" to replicated and partitioned region namespace config -* [SGF-75] - Ability to define gateways in the Spring Gemfire namespace -* [SGF-76] - Disk store should be its own bean -* [SGF-79] - Missing gateway attributes for regions -* [SGF-86] - Make instance variables protected in CacheFactoryBean -* [SGF-95] - Add namespace support for subregions -* [SGF-98] - Provide namespace support for all cache and region properties +* [SGF-53] - Add "enable-gateway" to replicated and partitioned region namespace config +* [SGF-75] - Ability to define gateways in the Spring GemFire namespace +* [SGF-76] - Disk store should be its own bean +* [SGF-79] - Missing gateway attributes for regions +* [SGF-86] - Make instance variables protected in CacheFactoryBean +* [SGF-95] - Add namespace support for subregions +* [SGF-98] - Provide namespace support for all cache and region properties * [SGF-102] - Add support for JavaConfig for repositories +* [SGF-103] - Replace xsd:id type with xsd:string to support Spring environment profiles * [SGF-104] - The repository deleteAll() method only works for replicated regions * [SGF-109] - Separate repository support into its own namespace +* [SGF-111] - Change default bean names from hyphenated to camel case to support @Autowired +* [SGF-112] - Repositories should reject PagingAndSorting and Pageable parameters +* [SGF-113] - Repositories should support single entities returned from a query method +* [SGF-115] - Add support for 'Like', 'StartsWith','EndsWith', and 'Containing' repository queries Bug Fixes - +* [SGF-85] - Pdx disk store does not work when trying to references a disk store created in cache.xml +* [SGF-89] - Continuous query container fails when implementing the ContinuousQueryListener interface +* [SGF-101] - The repository deleteAll() method only works for replicated regions Changes in version 1.1.2.RELEASE (2012-07-04) --------------------------------------------- diff --git a/docs/src/info/readme.txt b/docs/src/info/readme.txt index 75bdc995..de82da73 100644 --- a/docs/src/info/readme.txt +++ b/docs/src/info/readme.txt @@ -1,5 +1,5 @@ -SPRING GEMFIRE INTEGRATION --------------------------- +SPRING DATA GEMFIRE +------------------- http://www.springsource.org/spring-gemfire 1. INTRODUCTION @@ -13,15 +13,12 @@ build Spring-powered highly scalable applications using vFabric GemFire as distr This release comes with complete reference documentation. For further details, consult the provided javadoc for specific packages and classes. -3. DISTRIBUTION JAR FILES - -The Spring Data GemFire jars files can be found in the 'dist' directory. - -4. GETTING STARTED +3. GETTING STARTED Please see the reference documentation at http://www.springsource.org/spring-gemfire/ and the Spring GemFire Examples at https://github.com/SpringSource/spring-gemfire-examples ADDITIONAL RESOURCES -Spring GemFire Homepage : http://www.springsource.org/spring-gemfire -VMWare vFabric GemFire Homepage: http://www.vmware.com/products/application-platform/vfabric-gemfire/overview.html \ No newline at end of file +Spring Data GemFire Homepage : http://www.springsource.org/spring-gemfire +VMware vFabric GemFire Documentation: http://www.vmware.com/products/application-platform/vfabric-gemfire/overview.html +VMware vFabric GemFire product page: http://www.vmware.com/products/application-platform/vfabric-gemfire \ No newline at end of file diff --git a/docs/src/reference/docbook/appendix/appendix-schema.xml b/docs/src/reference/docbook/appendix/appendix-schema.xml index f0735c13..34209e03 100644 --- a/docs/src/reference/docbook/appendix/appendix-schema.xml +++ b/docs/src/reference/docbook/appendix/appendix-schema.xml @@ -1,9 +1,16 @@ - Spring GemFire Integration Schema + Spring Data GemFire Schema - Spring GemFire Schema - + Spring Data GemFire Core Schema (gfe) + + + FIXME: SGF SCHEMA LOCATION/NAME CHANGED + + + + Spring Data GemFire Data Access Schema (gfe-data) + FIXME: SGF SCHEMA LOCATION/NAME CHANGED diff --git a/docs/src/reference/docbook/index.xml b/docs/src/reference/docbook/index.xml index 8e693278..18da379f 100644 --- a/docs/src/reference/docbook/index.xml +++ b/docs/src/reference/docbook/index.xml @@ -55,18 +55,18 @@ - Reference Documentation + Reference Guide - + --> diff --git a/docs/src/reference/docbook/introduction/introduction.xml b/docs/src/reference/docbook/introduction/introduction.xml index 5e565b39..a717c170 100644 --- a/docs/src/reference/docbook/introduction/introduction.xml +++ b/docs/src/reference/docbook/introduction/introduction.xml @@ -1,20 +1,14 @@ - - + Introduction - - -
- This reference guide for the Spring Data GemFire project (SGF) - explains how to use Spring framework to configure and develop - applications with vFabric GemFire. It presents the basic concepts, - semantics and provides numerous examples to help you get started. + + This reference guide for the Spring Data GemFire project explains how to use Spring framework to + configure and develop applications with vFabric GemFire. + It presents the basic concepts, semantics and provides numerous examples to help you get started. Spring Data GemFire started as a top level Spring project called - Spring GemFire and has sinced moved under the Spring Data umbrella - project and has been renamed accordingly. -
- - + Spring GemFire (SGF) and has since moved under the Spring Data umbrella project + and has been renamed accordingly. + + diff --git a/docs/src/reference/docbook/introduction/new-features.xml b/docs/src/reference/docbook/introduction/new-features.xml index a070aaec..5232f5ff 100644 --- a/docs/src/reference/docbook/introduction/new-features.xml +++ b/docs/src/reference/docbook/introduction/new-features.xml @@ -10,25 +10,26 @@ it is now a component of the -Spring Data Repository support with a dedicated namespace: gfe-data +Spring Data Repository support with a dedicated namespace, gfe-data. See -Namespace support for registering GemFire functions +Namespace support for registering GemFire functions. See A top level <disk-store> element has been added to the gfe namespace to allow sharing of persist stores among regions, -and other components that support persistent backup. +and other components that support persistent backup. See The <*-region> elements no longer allow a nested <disk-store> diff --git a/docs/src/reference/docbook/introduction/requirements.xml b/docs/src/reference/docbook/introduction/requirements.xml index e5e22e49..894f640b 100644 --- a/docs/src/reference/docbook/introduction/requirements.xml +++ b/docs/src/reference/docbook/introduction/requirements.xml @@ -1,7 +1,7 @@ Requirements - Spring Data GemFire requires JDK level 5.0 and above, Spring + Spring Data GemFire requires JDK level 6.0 and above, Spring Framework 3 and vFabric GemFire 6.6 and above. diff --git a/docs/src/reference/docbook/links.xml b/docs/src/reference/docbook/links.xml index 2e4cb562..02701117 100644 --- a/docs/src/reference/docbook/links.xml +++ b/docs/src/reference/docbook/links.xml @@ -9,15 +9,19 @@ - Spring Data GemFire Home Page + Spring Data GemFire Home Page + + + vFabric GemFire Home Page + + + vFabric GemFire Documentation - - SpringSource Blog + GemFire Community Home Page + + + Spring Data GemFire Forum - - New para - - diff --git a/docs/src/reference/docbook/reference/bootstrap.xml b/docs/src/reference/docbook/reference/bootstrap.xml index 233c3769..86de6a5a 100644 --- a/docs/src/reference/docbook/reference/bootstrap.xml +++ b/docs/src/reference/docbook/reference/bootstrap.xml @@ -1,1024 +1,196 @@ - + Bootstrapping GemFire through the Spring Container - Spring Data GemFire provides full configuration and initialization of the GemFire - data grid through Spring's IoC container. Spring Data GemFire 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. + 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. + + + This section assumes basic familiarity with GemFire. For more + information see the product + documentation. + + +
+ 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 + namespace is considered the preferred way to configure GemFire. GemFire + will continue to support 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, + 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 cache.xml which provides relatively + limited configuration options and requires callbacks to implement + GemFire's Declarable interface (see 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. +
- Using the Core Spring Data GemFire Namespace - - To simplify configuration, Spring Data Gemfire provides a dedicated namespace for configuring core GemFire components. - It is also possible to configure the beans directly through Springs usual <bean> definition. However, as of Spring Data GemFire 1.2.0, the namespace provides full - support and is much easier to use. For more information about XML Schema-based configuration in Spring, see - this appendix in the - Spring Framework reference documentation. - - - Spring Data Repository support uses a separate dedicated namespace. See for more information on how to configure GemFire Repositories. - - - To use the Spring Data GemFire namespace, simply declare it in your Spring XML configuration: + Using the Core Spring Data GemFire Namespace - - - - - ]]> - -]]> - - - Spring GemFire namespace prefix. Any name can do but through out the reference documentation, the gfe will be used. - - - The namespace URI. - - - 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 GemFire library. - - - Declaration example for the GemFire namespace. Notice the prefix usage. - - - - Once declared, the namespace elements can be declared simply by appending the aforementioned prefix. - 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: - + 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 Springs 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 this + appendix in the Spring Framework reference documentation. - - - - ]]> - - ]]> - -]]> - - - The default namespace declaration for this XML file points to the Spring Data GemFire namespace. - - - The beans namespace prefix declaration. - - - Bean declaration using the beans namespace. Notice the prefix. - - - Bean declaration using the gfe namespace. Notice the lack of prefix (as the default namespace is used). - - - -
- -
- 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. - - - A cache with default configuration can be created with a very simple declaration: - - ]]> - - - 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: - - ]]> - - - 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: - - ]]> - - In this example, if the cache needs to be created, it will use the - file named cache.xml located in the classpath root. - - - Note that the configuration makes use of Spring's 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 properties - using one of Spring's common properties configuration methods. For example, one can use the properties element defined in the util namespace - to define properties directly or load properties files. The latter is recommended for externalizing environment specific settings outside the application configuration: - - - - - - - -]]> - - - - 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. - + Spring Data Repository support uses a separate XML namespace. See + for more information on how to + configure GemFire Repositories. - -
Advanced Cache Configuration - For advanced cache configuration, the cache element provides several attributes and child elements: - - ]]> - ]]> - - - ]]> - - - ]]> - ]]> - - ]]> - - - - - Various cache options are provided via these attributes. For a detailed explanation of any of these attributes, please consult - the GemFire product documentation - - - An example of a TransactionListener declaration using a bean reference. The referenced bean must implement - TransactionListener. - For a detailed explanation of the functionality provided by this - and any of the following elements, please consult the GemFire product documentation - - - An example of a TransactionWriter declaration using an inner bean declaration this time. The bean must implement - TransactionWriter - - com.gemstone.gemfire.cache.util.GatewayConflictResolver - An example of a GatewayConflictResolver declaration. The bean must implement - com.gemstone.gemfire.cache.util.GatewayConflictResolver. This requires GemFire 7.0 - - - Enable GemFire's DynamicRegionFactory - - - Declares a JNDI binding to enlist an extenal datasource in a GemFire transaction - - -
- -
- Configuring a GemFire Cache Server - - In Spring Data GemFire 1.1 dedicated support for configuring a - CacheServer was added, - allowing complete configuration through the Spring container: - - - - - - - - - - - - -]]> - - The configuration above illustrates the cache-server element and the many options available. - - Rather than hard-coding the port, this configuration uses Spring context - namespace to declare a property-placeholder. The 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 - SpEL and the environment abstraction one - to support externalization of environment specific properties from the main code base, easing the deployment across multiple machines. - - - To avoid initialization problems, the CacheServers started by Spring Data GemFire will start after the container has been fully initialized. This - allows potential regions, listener, writers or instantiators defined declaratively to be fully initialized and registered before the server starts accepting connections. Keep this in mind - when doing programmatic configuration of the items above as the server might start before your components and thus not be seen by the clients connecting right away. -
- -
- Configuring a GemFire Client Cache - - Another configuration addition in Spring Data GemFire 1.1 is the dedicated support for configuring - ClientCache. - This is similar to a cache in both usage and definition and supported by the - the ClientCacheFactoryBean in the org.springframework.data.gemfire.client package. - - - - -]]> - - 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 pools 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: - - - - - - - - -]]> -
-
- -
- Configuring a GemFire Region - - Once the Cache is configured, one needs to configure one or more Regions to - access cached data. Spring Data GemFire allows regions to be configured and created directly in Spring or, - if they are already created natively in GemFire, registered in the Spring context. - - For more information about the various region types and their capabilities as well as configuration options, please - refer to the GemFire Developer's Guide and community - site. - -
- Using an externaly 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 definition: - - ]]> - - If the name is not specified, the bean's id will be used. The example above - becomes: - - -]]> - - If the region does not exist, an initialization exception will be thrown. For configuring new GemFire regions, - proceed to the appropriate sections below. - - Note that in the previous examples, since no cache name was defined, the default naming convention (gemfireCache) - was used. If that is not an option, one can reference the cache bean through the cache-ref attribute: - - - - -]]> - - The lookup-region provides a simple way of retrieving existing, pre-configured regions without exposing - the region semantics or setup infrastructure. -
- -
- Configuring Regions - Spring Data GemFire provides comprehensive support for configuring any type of Region GemFire provides. Currently these include: - - Local Region <local-region> - The region is only visible to the defining member - Replicated Region <replicated-region> - Holds all data from the distributed region - Partitioned Region <partitioned-region> - Data is divided into buckets across members - Client Region <client-region> - A local region used with a client cache - - For a comprehensive description of region types please - consult the GemFire product documentation. - - -
- Common Region Attributes - The following table(s) list attributes available for all region types: - - 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:true - Indicates whether the region should be closed at shutdown - - - data-policy - See GemFire's 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. Note: This will automatically enable persistence. If persistent is explicitly set to false, an exception will be thrown. - - - disk-synchronous - boolean, default:false - Indicates whether disk store writes are synchronous. Note: This will automatically enable persistence. If persistent is explicitly set to false, an exception will be thrown. - - - enable-gateway - boolean, default:false - Indicates whether the region will synchronize entries over a WAN gateway. Note: This is deprecated in GemFire 7.0 - - - hub-id - The name of the Gateway Hub - Note: This is deprecated in GemFire 7.0. Also 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-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 entries - - - key-constraint - any valid java class name - The expected key type - - - name - any valid region name - The name of the region definition. If no 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 - - - statistics - boolean, default:false - Indicates whether the region reports statistics - - - value-constraint - any valid java class name - The expected value type - - - -
- -
-
- 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 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 CacheListeners declared. The first references a top level named Spring bean; the second is an - anonymous inner bean definition. - - - - - - - - - - - ]]> - - -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. - 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. - - - - - - - - ]]> - - - - Note:Bean Reference Conventions - The cache-listener element is an example of a common pattern used in the namespace anywhere GemFire provides an interface that may be - implemented to invoke custom Java code. In order to simplify the configuration, a single occurance of the element is all that is required, - but may contain nested bean references and inner bean definitions in any combination if multiple instances are permitted. - The element name always takes the singular form (i.e., cache-listener vs cache-listeners) because it is assumed that - the most common scenario will in fact be a single instance. - We have already seen some examples of this pattern in the advanced cache configuration example. - - -
- -
- 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 source, a database - for example. A CacheWriter is invoked afer an entry is created or updated,intended for synchronizing to an external data source. - The difference is GemFire only supports at most a single instance of each for each region. However, either declaration style may be - used. See CacheLoader and - CacheWriter for more details. -
- -
- 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. A subregion's name attribute is the simple name. The above example might be configured as: - - - - - - - - - - -]]> - - The subregions will be created with bean names /Customer/Address and /Employee/Address, respectively. So they may be referenced - directly by other beans that use them, such as GemfireTemplate. - -
-
- -
- Replicated Region - - One of the common region types supported by GemFire is replicated region or replica. In short: - - What is a replica? - When a region is configured to be a replicated region, every member that hosts that region stores a copy of the contents of the region 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 replicas. - - - Spring Data GemFire offers a dedicated element for creating replicas in the form of replicated-region element. A minimal declaration looks as follows - (again, the example relies on the Spring Data GemFire namespace naming conventions to wire the cache): - - ]]> - - Here, a replicated region is created (if one doesn't exist already). The name of the region is the same as the bean id (simple-replica) and - the bean assumes the existence of a GemFire cache named gemfireCache. - - When setting up a region, it is fairly common to associate various CacheLoaders, CacheListeners and - CacheWriters with it. These components can be either referrenced or declared inlined by the region declaration. - - - Following the GemFire API, the namespace allows multiple cache listeners but only one - cache writer and cache loader for each region. - - - - - Below is an example, showing both styles: - - - - - - - - - - - - -]]> - - Using ref and a nested declaration on cache-listener, cache-loader or cache-writer - is illegal. The two options are mutually exclusive and using both on the same element will result in an exception. - -
- <literal>replicated-region</literal> Options - - The following table offers a quick overview of the most important configuration options names, possible values and short descriptions for each of settings supported by the - replicated-region element. Please see the storage and eviction section for the relevant configuration. - - - <![CDATA[replicated-region]]> options - - - - - - - Name - Values - Description - - - - - id - any valid bean name - The id of the region bean definition. - - - name - any valid region name - The name of the region definition. If no specified, it will have the value of the id attribute (that is, the bean name). - - - cache-ref - GemFire cache bean name - The name of the bean defining the GemFire cache (by default 'gemfireCache'). - - - cache-listener - valid bean name or definition - The name or nested bean declaration of a GemFire CacheListener. - - - cache-loader - valid bean name or definition - The name or nested bean declaration of a GemFire CacheLoader. - - - cache-writer - valid bean name or definition - The name or nested bean declaration of a GemFire CacheWriter. - - - -
-
- -
- -
- Partition(ed) Region - - Another region type supported out of the box by the Spring Data GemFire namespace, is the partitioned region. To quote again the GemFire docs: - - What is a partition? - 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 can be created by Spring Data GemFire through 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: - - - - - - -]]> - -
- <literal>partitioned-region</literal> Options - - The following table offers a quick overview of the most important configuration options names, possible values and short descriptions for each of settings supported by the - partition element. Please see the storage and eviction section for the relevant configuration. - - - <![CDATA[partitioned-region]]> options - - - - - - - Name - Values - Description - - - - - id - any valid bean name - The id of the region bean definition. - - - name - any valid region name - The name of the region definition. If no specified, it will have the value of the id attribute (that is, the bean name). - - - cache-ref - GemFire cache bean name - The name of the bean defining the GemFire cache (by default 'gemfireCache'). - - - - cache-listener - valid bean name or definition - The name or nested bean declaration of a GemFire CacheListener. - - - cache-loader - valid bean name or definition - The name or nested bean declaration of a GemFire CacheLoader. - - - cache-writer - valid bean name or definition - The name or nested bean declaration of a GemFire CacheWriter. - - - - partition-resolver - bean name - The name of the partitioned resolver used by this region, for custom partitioning. - - - 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 storages. - - - 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. - - - -
-
-
- -
- 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 categoried in short in: peer-to-peer (p2p), client-server (or super-peer cache network) and wide area cache network (or WAN). In the last two scenarios, it is common - to declare client regions which connect to a backing cache server (or super peer). Spring Data GemFire offers dedicated support for such configuration through - , client-region and pool elements. - As the name imply, the former defines a client region while the latter connection pools to be used/shared by the various client regions. - - Below is a usual configuration for a client region: - - - - - - - - - - - - - - - - - -]]> - - Just as the other region types, client-region allows defining CacheListeners. It also relies on the same naming conventions - in case the region name or the cache are not set explicitely. However, it also requires a connection pool to be specified for connecting to the server. Each client - can have its own pool or they can share the same one. - - For a full list of options to set on the client and especially on the pool, please refer to the Spring Data GemFire schema () and the GemFire documentation. - -
- 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: - - - - - - - - -]]> - - 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. -
-
- -
- Configurating Disk Storage - - GemFire can use disk as a secondary storage for persisting regions or/and overflow (known as data pagination or eviction to disk). Spring Data GemFire allows such options to be configured - directly from Spring through disk-store element available on both replicated-region and partitioned-region as well as - client-region. - A disk store defines how that particular region can use the disk and how much space it has available. Multiple directories can be defined in a disk store such as in our example below: - - - - - - - -]]> - - In general, for maximum efficiency, it is recommended that each region that accesses the disk uses a disk store configuration. - - - For the full set of options and their meaning please refer to the and GemFire documentation. - - -
- -
- Data Persistence - - Both partitioned and replicated regions can be made persistent. That is: - - What is region persistence? - 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. - - - With Spring Data GemFire, to enable persistence, simply set to true the persistent attribute on replicated-region, - partitioned-region or client-region: - - ]]> - - Persistence for partitioned regions is supported from GemFire 6.5 onwards - configuring this option on a previous release will trigger - an initialization exception. - - When persisting regions, it is recommended to configure the storage through the disk-store element for maximum efficiency. -
- -
- 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 on the least recently used entry (also known as 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: - - - -]]> - - Replicas cannot use a local destroy eviction since that would invalidate them. See the GemFire docs for more information. - - When configuring regions for oveflow, 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 this - page). -
- -
- Advanced Region Configuration - - Spring Data GemFire namespaces allow short and easy configuration of the major GemFire regions and associated entities. However, there might be corner cases where the namespaces are not enough, where - a certain combination or set of attributes needs to be used. For such situations, using directly the Spring Data GemFire FactoryBeans is a possible alternative as it gives - access to the full set of options at the expense of conciseness. - - As a warm up, below are some common configurations, declared through raw beans definitions. - - A basic configuration looks as follows: - - <bean id="basic" class="org.springframework.data.gemfire.RegionFactoryBean"> - <property name="cache"> - <bean class="org.springframework.data.gemfire.CacheFactoryBean"/> - </property> - <property name="name" value="basic"/> -</bean> - - Notice how the GemFire cache definition has been nested into the declaring region definition. Let's add more regions - and make the cache a top level bean. - Since the region bean definition name is usually the same with that - of the cache, the name property can be omitted (the - bean name will be used automatically). Additionally by using the name the - p - namespace, the configuration can be simplified even more: + To use the Spring Data GemFire namespace, simply declare it in your + Spring XML configuration: <?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"> - - <!-- shared cache across regions --> - <bean id="cache" class="org.springframework.data.gemfire.CacheFactoryBean"/> + xmlxsi="http://www.w3.org/2001/XMLSchema-instance" + xmlgfe="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"> + + <bean id ... > - <!-- region named 'basic' --> - <bean id="basic" class="org.springframework.data.gemfire.RegionFactoryBean" p:cache-ref="cache"/> + <gfe:cache ...> - <!-- region with a name different then the bean definition --> - <bean id="root-region" class="org.springframework.data.gemfire.RegionFactoryBean" p:cache-ref="cache" p:name="default-region"/> </beans> - It is worth pointing out, that for the vast majority of cases - configuring the cache loader, listener and writer through the Spring - container is preferred since the same instances can be reused across - multiple regions and additionally, the instances themselves can benefit - from the container's rich feature set: + + + Spring GemFire namespace prefix. Any name will do but through + out the reference documentation, gfe will be + used. + - <bean id="cacheLogger" class="org.some.pkg.CacheLogger"/> -<bean id="customized-region" class="org.springframework.data.gemfire.RegionFactoryBean" p:cache-ref="cache"> - <property name="cacheListeners"> - <array> - <ref name="cacheLogger"/> - <bean class="org.some.other.pkg.SysoutLogger"/> - </array> - </property> - <property name="cacheLoader"><bean class="org.some.pkg.CacheLoad"/></property> - <property name="cacheWriter"><bean class="org.some.pkg.CacheWrite"/></property> -</bean> + + The namespace URI. + -<bean id="local-region" class="org.springframework.data.gemfire.RegionFactoryBean" p:cache-ref="cache"> - <property name="cacheListeners" ref="cacheLogger"/> -</bean> + + 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. + - For scenarios where a CacheServer is used and - clients need to be configured and the namespace is not an option, Spring Data GemFire offers a - dedicated configuration class named: - ClientRegionFactoryBean. This allows client - interests to be registered in both key and regex - form through Interest and - RegexInterest classes in the - org.springframework.data.gemfire.client package: + + Declaration example for the GemFire namespace. Notice the prefix + usage. + + - <bean id="interested-client" class="org.springframework.data.gemfire.client.ClientRegionFactoryBean" p:cache-ref="cache" p:name="client-region"> - <property name="interests"> - <array> - <!-- key-based interest --> - <bean class="org.springframework.data.gemfire.client.Interest" p:key="Vlaicu" p:policy="NONE"/> - <!-- regex-based interest --> - <bean class="org.springframework.data.gemfire.client.RegexInterest" p:key=".*" p:policy="KEYS" p:durable="true"/> - </array> - </property> -</bean> - - Users that need fine control over a region, can configure it in Spring by using the attributes property. To ease declarative configuration in Spring, - Spring Data GemFire provides two FactoryBeans for creating RegionAttributes and PartitionAttributes, - namely RegionAttributesFactory and PartitionAttributesFactory. See below an example of configuring a partitioned region through Spring - XML: + Once declared, the namespace elements can be declared simply by + appending the aforementioned prefix. + + + 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: + + <?xml version="1.0" encoding="UTF-8"?> +<beans xmlns="http://www.springframework.org/schema/gemfire" + xmlxsi="http://www.w3.org/2001/XMLSchema-instance" + xmlbeans="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"> + + <beabean id ... > - - - - - - - - -]]> - - By using the attribute factories above, one can reduce the size of the cache.xml or even eliminate it all together. -
-
- -
- Advantages of using Spring over GemFire <literal>cache.xml</literal> - - With Spring Data GemFire, GemFire regions, pools and cache can be configured either through Spring or directly inside GemFire, native, cache.xml file. While both are valid - approaches, it's worth pointing out that Spring's powerful DI container and AOP functionality makes it very easy to wire GemFire into an application. For example configuring a region - cache loader, listener and writer through the Spring container is preferred since the same instances can be reused across multiple regions and additionally are either to configure - due to the presence of the DI and eliminates the need of implementing GemFire's Declarable interface (see on chapter - on how you can still use them yet benefit from Spring's DI container). - - Whatever route one chooses to go, Spring Data GemFire supports both approaches allowing for easy migrate between them without forcing an upfront decision. -
- -
- Creating Indecies - - GemFire allows creation on indices (or indexes) to improve the performance of (common) queries. Spring Data GemFire allows indecies to be declared through the index element: - - - ]]> - - 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. -
+ <cache ...> - \ No newline at end of file +</beans> + + + + The default namespace declaration for this XML file points to + the Spring Data GemFire namespace. + + + + The beans namespace prefix declaration. + + + + Bean declaration using the beans namespace. + Notice the prefix. + + + + Bean declaration using the gfe namespace. + Notice the lack of prefix (as the default namespace is used). + + + + + + + + + +
+ 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: + + <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. +
+ + + + diff --git a/docs/src/reference/docbook/reference/cache.xml b/docs/src/reference/docbook/reference/cache.xml new file mode 100644 index 00000000..1247b4b0 --- /dev/null +++ b/docs/src/reference/docbook/reference/cache.xml @@ -0,0 +1,312 @@ + +
+ 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. + + 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 and + + A cache with default configuration can be created with a very simple + declaration: + + <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: + + <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: + + <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 that the configuration makes use of Spring's + 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 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: + + <?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> + + + 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. + + +
+ Advanced Cache Configuration + + For advanced cache configuration, the cache + element provides a number of configuration options exposed as attributes + or child elements + + +<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" + > + <gfe:transaction-listener ref="myTransactionListener"/> + + <gfe:transaction-writer> + <bean class="org.springframework.data.gemfire.example.TransactionListener"/> + </gfe:transaction-writer> + + <gfe:dynamic-region-factory/> + <gfe:jndi-binding jndi-name="myDataSource" type="ManagedDataSource"/> +</gfe:cache> + + + + + Various cache options are supported by attributes. For further + information regarding anything shown in this example, please consult + the GemFire product documentation + + + + An example of a + TransactionListener callback + declaration using a bean reference. The referenced bean must implement + TransactionListener + + + + An example of a TransactionWriter + callback declaration using an inner bean declaration this time. The + bean must implement TransactionWriter + + + + Enable GemFire's DynamicRegionFactory + + + + Declares a JNDI binding to enlist an external datasource in a + GemFire transaction + + + + 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 + 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 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 + +
+
+ +
+ Configuring a GemFire Cache Server + + In Spring Data GemFire 1.1 dedicated support for configuring a + CacheServer + was added, allowing complete configuration through the Spring + container: + + <?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. + + + Rather than hard-coding the port, this configuration uses Spring's + + context + namespace to declare a + property-placeholder. The 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 SpEL + and the environment + abstraction one to support externalization of environment + specific properties from the main code base, easing the deployment + across multiple machines. + + + + To avoid initialization problems, the + CacheServers 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 before your components and thus not be seen by the clients + connecting right away. + +
+ +
+ Configuring a GemFire Client Cache + + Another configuration addition in Spring Data GemFire 1.1 is the + dedicated support for configuring ClientCache. + This is similar to a cache in both + usage and definition and supported by + org.springframework.data.gemfire.clientClientCacheFactoryBean. + + <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 pools 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: + + <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> +
+ + Client side configuration is covered in more detail in . +
diff --git a/docs/src/reference/docbook/reference/client.xml b/docs/src/reference/docbook/reference/client.xml new file mode 100644 index 00000000..2014771e --- /dev/null +++ b/docs/src/reference/docbook/reference/client.xml @@ -0,0 +1,4 @@ + +
+ Cache Client Configuration +
\ No newline at end of file diff --git a/docs/src/reference/docbook/reference/cq-container.xml b/docs/src/reference/docbook/reference/cq-container.xml index 33d14484..024767de 100644 --- a/docs/src/reference/docbook/reference/cq-container.xml +++ b/docs/src/reference/docbook/reference/cq-container.xml @@ -9,8 +9,8 @@ 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 SGF allows methods on POJOs to become end-points for CQ - simply define the query and indicate the method - that should be notified when there is a match - SGF takes care of the rest. This of Java EE's message-driven bean style, but without any + feel right at home. Basically Spring Data GemFire allows methods on POJOs to become end-points for CQ - simply define the query and indicate the method + that should be notified when there is a match - Spring Data GemFire takes care of the rest. This is similar Java EE's message-driven bean style, but without any requirement for base class or interface implementations, based on GemFire. @@ -21,7 +21,7 @@
Continuous Query Listener Container - SGF simplifies the creation, registration, life-cycle and dispatch of CQs by taking care of the infrastructure around them through + 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) @@ -29,13 +29,13 @@ 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 suchlike. + and takes care of creation and registration of CQs (to receive events), resource acquisition and release, exception conversion and the like. This allows you as an application developer to write the (possibly complex) business logic associated with receiving an event (and reacting to it), and delegates boilerplate GemFire infrastructure concerns to the framework. The container is fully customizable - one can chose either to use the CQ thread to perform the dispatch (synchronous delivery) or a new thread - (from an existing pool for examples) for an asynch approach by defining the suitable java.util.concurrent.Executor + (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. @@ -45,9 +45,9 @@ The <classname>ContinuousQueryListenerAdapter</classname> and <interfacename>ContinuousQueryListener</interfacename> The ContinuousQueryListenerAdapter class is the - final component in SGF CQ support: in a nutshell, it allows you to expose almost any class + 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 CqListener. + similar to GemFire CqListener. Consider the following interface definition. Notice the various event handling methods and their parameters: @@ -102,7 +102,7 @@ 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 SGF namespace to declare the event listener container and automatically register the POJOs as listeners. The full blown, beans definition + 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: <!-- this is the Event Driven POJO (MDP) --> diff --git a/docs/src/reference/docbook/reference/data.xml b/docs/src/reference/docbook/reference/data.xml index a7d37c39..607a9b1e 100644 --- a/docs/src/reference/docbook/reference/data.xml +++ b/docs/src/reference/docbook/reference/data.xml @@ -22,25 +22,21 @@ url="http://static.springsource.org/spring/docs/3.0.x/spring-framework-reference/html/orm.html#orm-exception-translation">exception translation 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. - The Cache factory acts as an exception - translator which is automatically detected by the Spring infrastructure + 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.
- <classname>GemfireTemplate</classname> + GemfireTemplate - As with many other high-level abstractions provided by the Spring - Framework and related projects, Spring GemFire provides a - template that plays a central role when working with - the GemFire API. The class provides several one-liner - methods, for popular operations but also the ability to + 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 exceptions for example through the - GemfireCallback. + having to deal with GemFire checked exceptions for example through the GemfireCallback. The template class requires a GemFire Region instance and once configured is @@ -65,9 +61,9 @@ } }); - For accessing the full power of the GemFire query language, one can use the find and findUnique which, as oppose to the - query method, can execute queries inside across multiple regions, execute projections just to name a few features. 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. + 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.
@@ -75,9 +71,8 @@ Support for Spring Cache Abstraction Since 1.1, Spring GemFire provides an implementation for Spring 3.1 - cache abstraction through the -org.springframework.data.gemfire.support package. To use GemFire - as a backing implementation, simply add GemfireCacheManager to your configuration: + cache abstraction. + To use GemFire as a backing implementation, simply add GemfireCacheManager to your configuration: Transaction Management One of the most popular features of Spring Framework is transaction + url="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 looking - into it as it offers a consistent programming model that works - transparently across multiple APIs that can be configured either - programmatically or declaratively (the most popular choice). + url="http://static.springsource.org/spring/docs/current/spring-framework-reference/htmlsingle/spring-framework-reference.html#transaction-motivation">looking + into it as it offers a consistent programming model that works transparently across multiple APIs that can be configured either programmatically or declaratively (the most popular choice). - For GemFire, SGF provides a dedicated, per-cache, transaction - manager that once declared, allows actions on the - Regions to be grouped and executed - atomically through Spring: + For GemFire, Spring Data GemFire provides a dedicated, per-cache, transaction manager that once declared, allows region operations to be executed atomically through Spring: <gfe:transaction-manager id="tx-manager" cache-ref="cache"/> 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 SGF namespace elements, if the cache name is not configured, the aforementioned naming convention will used. - Additionally, the transaction manager name, if not specified is gemfire-transaction-manager. - - or if you prefer bean declarations: - <bean id="tx-manager" class="org.springframework.data.gemfire.GemfireTransactionManager" p:cache-ref="cache"/> + name gemfireCache. As with the other Spring Data GemFire namespace elements, if the cache name is not configured, the aforementioned naming convention will used. + Additionally, the transaction manager name, if not specified is gemfireTransactionManager. Note that currently GemFire supports optimistic transactions with read committed isolation. Furthermore, to guarantee @@ -129,11 +116,11 @@ values present in the cache. To prevent this from happening, the transaction manager configured the cache to use copy on read semantics, meaning a clone of the actual value is created, - each time a read is performed. This behaviour can be disabled if needed + each time a read is performed. This behavior can be disabled if needed through the copyOnRead property. For more information on the semantics of the underlying GemFire transaction manager, see the GemFire documentation. + url="https://www.vmware.com/support/developer/vfabric-gemfire/663-api/com/gemstone/gemfire/cache/CacheTransactionManager.html">documentation. @@ -143,21 +130,21 @@ GemFire XML configuration (usually named cache.xml allows user objects to - be declared as part of the fabric configuration. Usually these objects are - CacheLoaders or other pluggable components - into GemFire. Out of the box in GemFire, each such type declared through + be declared as part of the configuration. Usually these objects are + CacheLoaders 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 the pluggable + 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 object. + DataSources or other collaboration objects. - However, if you are starting on a green-field project, it is + 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 @@ -168,11 +155,11 @@ Eliminate <interfacename>Declarable</interfacename> components - One can configure custom types entirely inside through Spring as + One can configure custom types entirely through Spring as mentioned in . That way, one does not have to implement the Declarable - interface and gets access to all the features of the Spring IoC - container (including not just dependency injection but also life-cycle + interface and also benefits from all the features of the Spring IoC + container (not just dependency injection but also life-cycle and instance management). @@ -189,10 +176,10 @@ </cache-loader> To simplify the task of parsing, converting the parameters and - initializing the object, SGF offers a base class + initializing the object, Spring Data GemFire offers a base class (WiringDeclarableSupport) that allows GemFire user objects to be wired through a template bean - definition or, in case that is missing perform autowiring through the + definition or, in case that is missing, perform autowiring through the Spring container. To take advantage of this feature, the user objects need to extend WiringDeclarableSupport which automatically locates the declaring @@ -204,17 +191,16 @@ In the current GemFire release there is no concept of an object factory and the types declared are - instantiated and used as is - that is there are no other ways in which - third parties can take care of the object creation outside GemFire. - Support for this feature is planned for the up-coming GemFire release - (6.5) + instantiated and used as is. In other words, there is no easy way + to manage object creation outside GemFire. +
Configuration using <emphasis>template</emphasis> definitions - When used WiringDeclarableSupport tries to + 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 @@ -251,9 +237,8 @@ </beans> In the scenario above, as no parameter was specified, a bean with - id/name com.company.app.DBLoader was searched for. - The found bean definition is used as a template for wiring the instance - created by GemFire. For cases where the bean name uses a different + the id/name 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: @@ -292,14 +277,14 @@ If no bean definition is found, by default, WiringDeclarableSupport will autowire + url="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 chapter + url="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. diff --git a/docs/src/reference/docbook/reference/diskstore.xml b/docs/src/reference/docbook/reference/diskstore.xml new file mode 100644 index 00000000..b6c8f9d7 --- /dev/null +++ b/docs/src/reference/docbook/reference/diskstore.xml @@ -0,0 +1,38 @@ + +
+ Configuring a Disk Store + + As of Release 1.2.0, Spring Data GemFire supports disk store + configuration via a top level disk-store element. + + + 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. + + + <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. +
diff --git a/docs/src/reference/docbook/reference/function.xml b/docs/src/reference/docbook/reference/function.xml new file mode 100644 index 00000000..ec78afcd --- /dev/null +++ b/docs/src/reference/docbook/reference/function.xml @@ -0,0 +1,30 @@ + +
+ Configuring GemFire's Function Service + + As of Release 1.2.0, Spring Data GemFire provides namespace support + for registering GemFire 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: + + <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"/> +
diff --git a/docs/src/reference/docbook/reference/gateway.xml b/docs/src/reference/docbook/reference/gateway.xml new file mode 100644 index 00000000..4d5ee306 --- /dev/null +++ b/docs/src/reference/docbook/reference/gateway.xml @@ -0,0 +1,48 @@ + +
+ 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 example: + + <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. + + + 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. +
diff --git a/docs/src/reference/docbook/reference/introduction.xml b/docs/src/reference/docbook/reference/introduction.xml index 09a2a068..f66e9a94 100644 --- a/docs/src/reference/docbook/reference/introduction.xml +++ b/docs/src/reference/docbook/reference/introduction.xml @@ -1,10 +1,9 @@ - - - Reference Guide - - + Document structure The following chapters explain the core functionality offered by @@ -12,7 +11,8 @@ describes the configuration support provided for bootstrapping, initializing, configuring, and accessing - GemFire caches, regions and distributed system components. + GemFire caches, cache servers, regions, and related distributed system + components explains the integration between the GemFire APIs and the various data access features available in Spring, such as @@ -30,10 +30,5 @@ describes the samples provided with the distribution to illustrate the various features available in Spring GemFire. - - - - + + diff --git a/docs/src/reference/docbook/reference/mapping.xml b/docs/src/reference/docbook/reference/mapping.xml index 266d7b48..a9280697 100644 --- a/docs/src/reference/docbook/reference/mapping.xml +++ b/docs/src/reference/docbook/reference/mapping.xml @@ -11,12 +11,12 @@
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 + 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: - Mapping a domain class to Gemfire + Mapping a domain class to GemFire @Region("myRegion") public class Person { @@ -41,7 +41,7 @@ public class Person { 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 disambiguing multiple potentially available constructors taking + helps disambiguating multiple potentially available constructors taking parameters and explicitly marking the one annotated as the one to be used to create entities. With none or only a single constructor you can omit the annotation. @@ -50,7 +50,7 @@ public class Person {
Mapping PDX serializer - Spring Data Gemfire provides a custom + 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 @@ -82,4 +82,4 @@ 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 new file mode 100644 index 00000000..e3af4793 --- /dev/null +++ b/docs/src/reference/docbook/reference/region.xml @@ -0,0 +1,850 @@ + +
+ Configuring a GemFire Region + + A region is required to store and retrieve data from the + cache. Region is an interface extends + java.util.map used to perform 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 Guide + and community site. + +
+ 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 + definition: + + <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: + + <!-- lookup for a region called 'orders' --> +<gfe:lookup-region id="orders"/> + + + If the region does not exist, an initialization exception will be + thrown. For configuring new GemFire regions, proceed to the appropriate + sections below. + + + Note that 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: + + <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. +
+ +
+ 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 region + types please consult the GemFire product documentation. + +
+ Common Region Attributes + + The following table(s) list attributes available for various + region types: + + 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:true + + + Indicates whether the region + should be closed at shutdown + + + + data-policy + + + See GemFire's 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. Note: This will + automatically enable persistence. If persistent is explicitly + set to false, an exception will be thrown. + + + + disk-synchronous + + + boolean, default:false + + + Indicates whether disk store + writes are synchronous. Note: This will automatically enable + persistence. If persistent is explicitly set to false, an + exception will be thrown. + + + + 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-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 entries + + + + key-constraint + + + any valid java class name + + + The expected key type + + + + name + + + any valid region name + + + The name of the region + definition. If no 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 + + + + statistics + + + boolean, default:false + + + Indicates whether the region + reports statistics + + + + value-constraint + + + any valid java class name + + + The expected value type + + + +
+
+ +
+ 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 + 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 + CacheListeners declared. The first + references a top level named Spring bean; the second is an anonymous + inner bean definition. +<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. + 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. + <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 + + 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 advanced cache configuration + example. + +
+ +
+ 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 + source, a database for example. A + CacheWriter is invoked afer an entry is + created or updated,intended for synchronizing to an external data + source. The difference is GemFire only supports at most a single + instance of each for each region. However, either declaration style may + be used. See + CacheLoader + and + CacheWriter + for more details. +
+ +
+ 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: + <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 + 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. +
+
+ +
+ 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. + + With Spring Data GemFire, to enable persistence, simply set the + persistent attribute to true: + + <gfe:partitioned-region id="persitent-partition" persistent="true"/> + + + Persistence for partitioned regions is supported from GemFire 6.5 + onwards - configuring this option on a previous release will trigger an + initialization exception. + + + 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: + + <gfe:partitioned-region id="persitent-partition" persistent="true" disk-store-ref="myDiskStore" disk-synchronous="true"/> + + This is discussed further in +
+ +
+ 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 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: + + <gfe:partitioned-region id="overflow-partition"> + <gfe:eviction type="MEMORY_SIZE" threshold="512" action="OVERFLOW_TO_DISK"/> +</gfe:partitioned-region> + + + Replicas cannot use a local destroy eviction + since that would invalidate them. See the GemFire docs for more + information. + + + When configuring regions for oveflow, 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 this + page). +
+ +
Data ExpirationGemFire 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.
+ +
+ 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): + + <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. +
+ +
+ 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. + + <gfe:replicated-region id="simpleReplica" /> +
+ +
+ 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: + + <!-- 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> + +
+ <literal>partitioned-region</literal> 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. + + + 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. + + + +
+
+
+ +
+ 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 , 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: + + <!-- 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 CacheListeners (but not + CacheLoaders or CacheWriters). 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. + + + + 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 () and the GemFire documentation. + +
+ 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: + + <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. +
+
+
diff --git a/docs/src/reference/docbook/reference/repositories.xml b/docs/src/reference/docbook/reference/repositories.xml index 557adae3..a2992777 100644 --- a/docs/src/reference/docbook/reference/repositories.xml +++ b/docs/src/reference/docbook/reference/repositories.xml @@ -7,26 +7,27 @@ xmlns:ns4="http://www.w3.org/2000/svg" xmlns:ns3="http://www.w3.org/1998/Math/MathML" xmlns:ns="http://docbook.org/ns/docbook"> - 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 has - been provided in . + 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 here + .
Spring configuration To bootstrap Spring Data repositories you use the - <repositories /> element from the Gemfire + <repositories /> element from the GemFire namespace: - Bootstrap Gemfire repositories + Bootstrap GemFire repositories <beans xmlns="http://www.springframework.org/schema/beans" xmlns:gf="http://www.springframework.org/schema/gemfire" @@ -43,7 +44,7 @@ This configuration snippet will look for interfaces below the configured base package and create repository instances for those - interfaces backed by a SimpleGemfireRepository. + 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.
@@ -51,7 +52,7 @@
Executing OQL queries - The Gemfire repositories allow the definition of query methods to + The GemFire repositories allow the definition of query methods to easily execute OQL queries against the Region the managed entity is mapped to. diff --git a/docs/src/reference/docbook/reference/samples.xml b/docs/src/reference/docbook/reference/samples.xml index c33566c1..b1421cfe 100644 --- a/docs/src/reference/docbook/reference/samples.xml +++ b/docs/src/reference/docbook/reference/samples.xml @@ -2,13 +2,17 @@ Sample Applications - The Spring GemFire project includes one sample application. Named + The Spring Data GemFire project includes one sample application. Named "Hello World", the sample demonstrates how to configure and use GemFire inside a Spring application. At runtime, the sample offers a 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. + + + Additional sample applications may be found in the Spring Data GemFire Examples repository. + The sample is bundled with the distribution and is Maven-based. One can easily import them into any Maven-aware IDE (such as SpringSource Working with GemFire Serialization - To improve overall performance of the data fabric, GemFire supports a - dedicated serialization protocol that is both faster and offers more compact + 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 platforms @@ -11,7 +11,7 @@ url="http://community.gemstone.com/display/gemfire/Serialization+in+Java">Java, .NET - and C++). This chapter discusses the various ways in which SGF simplifies + and C++). This chapter discusses the various ways in which Spring Data GemFire simplifies and improves GemFire custom serialization in Java.
@@ -21,7 +21,7 @@ Transient data is often dependent on the node or environment where it lives at a certain point in time, for example a DataSource. Serializing such information is useless (and potentially even dangerous) since it is - local to a certain VM/machine. For such cases, SGF offers a special Instantiator that performs wiring for each new instance created by GemFire during deserialization. @@ -63,7 +63,7 @@ be created on each machine as data flows in. Out of the box, GemFire uses reflection to create new types but for some scenarios, this might prove to be expensive. As always, it is good to perform profiling to quantify - whether this is the case or not. For such cases, SGF allows the automatic + whether this is the case or not. For such cases, Spring Data GemFire allows the automatic generation of Instatiator classes which instantiate a new type (using the default constructor) without the use of reflection: diff --git a/src/main/resources/org/springframework/data/gemfire/config/spring-gemfire-1.2.xsd b/src/main/resources/org/springframework/data/gemfire/config/spring-gemfire-1.2.xsd index b844f45b..7a115dbc 100755 --- a/src/main/resources/org/springframework/data/gemfire/config/spring-gemfire-1.2.xsd +++ b/src/main/resources/org/springframework/data/gemfire/config/spring-gemfire-1.2.xsd @@ -35,45 +35,7 @@ and may be nested or referenced. ]]> - - - - - - - - - - - - - - - - - - - - - - - - - + @@ -506,40 +468,6 @@ when one or more missing required roles is restored to the distributed membershi - - - - - - - - - - - - - - - - - - - - - - - - @@ -631,7 +559,9 @@ The fully qualified class name of the expected value type use="optional" default="false"> @@ -661,7 +591,7 @@ The fully qualified class name of the expected value type use="optional"> @@ -669,7 +599,7 @@ The fully qualified class name of the expected value type use="optional"> @@ -692,7 +622,8 @@ The fully qualified class name of the expected value type use="required"> +The name of the region definition.]]> + @@ -774,7 +705,8 @@ Time to idle (or idle timeout) configuration for the region entries. Default: no default="0.75"> @@ -782,7 +714,8 @@ Together with the initial-capacity region attribute, sets the initial parameters type="xsd:string" default="true"> @@ -827,7 +760,7 @@ Determines how fromDelta applies deltas to the local cache for delta propagation use="required"> @@ -863,7 +796,8 @@ The name of the bean defining the GemFire cache (by default 'gemfireCache'). @@ -874,7 +808,7 @@ The name of the region definition. If no specified, it will have the value of th type="xsd:string" default="false"> @@ -882,14 +816,16 @@ The name of the region definition. If no specified, it will have the value of th type="xsd:string" default="false"> @@ -943,7 +879,9 @@ The action to take when performing eviction. @@ -965,7 +903,7 @@ Specifies the data policy for this region type="xsd:string" use="optional" default="false"> @@ -988,7 +926,7 @@ Specifies the data policy for this region use="required"> @@ -1042,14 +980,16 @@ The action to take when performing eviction. default="NORMAL"> @@ -1072,7 +1012,7 @@ Provides an estimate of the maximum number of application threads that will conc use="required"> @@ -1123,7 +1063,8 @@ colocate data based on custom criterias (such as colocating trades by month and @@ -1230,7 +1171,7 @@ The delay in milliseconds that existing members will wait before satisfying redu @@ -1254,7 +1195,7 @@ The delay in milliseconds that new members will wait before satisfying redundanc use="required"> @@ -1457,12 +1398,12 @@ Considered only for asynchronous writing. - + @@ -1502,7 +1443,9 @@ The name of the disk store bean definition. This is also used as the disk store - + @@ -1837,7 +1780,9 @@ The client subscription configuration that is used to control a clients use of s - + - + - + - + @@ -2019,7 +1970,8 @@ Defines a GemFire index. +The name of the index bean definition. If property 'name' is not set, it will be used as the index name as well. + ]]> +The name of the index. + ]]> use="optional" default="true"> +Indicates whether the index is created even if there is an index with the same name (default) or not. + ]]> - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - @@ -2552,7 +2268,8 @@ The id of the function service (optional) @@ -2590,7 +2307,7 @@ Inner bean definition of the transport filter. + ]]> @@ -2598,7 +2315,6 @@ use inner bean declarations. @@ -2606,7 +2322,6 @@ Deprecated as of Gemfire 7 minOccurs="0" maxOccurs="unbounded"> @@ -2670,7 +2385,6 @@ Specifies the startup policy (primary,secondary, none) for the gateway hub @@ -2685,7 +2399,6 @@ Deprecated as of Gemfire 7 @@ -2846,7 +2558,6 @@ Specifies the number of parallel threads