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

SGF-342 - Update Spring Data GemFire Reference Guide with GemFire 8 functional support.

Browse Source
This commit is contained in:
John Blum
2014-10-17 15:51:13 -07:00
parent 3d08dc1eaa
commit 043b2fdee2
6 changed files with 244 additions and 116 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
src/asciidoc/introduction/introduction.adoc
View File

@@ -1,7 +1,9 @@
[[intro-introduction]]
= Introduction
This reference guide for Spring Data GemFire explains how to use the Spring Framework to configure and develop applications with Pivotal GemFire. It presents the basic concepts, semantics and provides numerous examples to help you get started.
NOTE: Spring Data GemFire started as a top-level Spring project called Spring GemFire (SGF) and since then has been moved under the Spring Data umbrella project and renamed accordingly.
This reference guide for Spring Data GemFire explains how to use the Spring Framework to configure
and develop applications with Pivotal GemFire. It presents the basic concepts, semantics and provides numerous examples
to help you get started.
NOTE: Spring Data GemFire started as a top-level Spring project called Spring GemFire (SGF) and since then
has been moved under the Spring Data umbrella project and renamed accordingly.

41
src/asciidoc/introduction/new-features.adoc
View File

@@ -5,7 +5,7 @@ NOTE: As of the 1.2.0 release, this project, formerly known as Spring GemFire, h
to reflect that it is now a component of the http://projects.spring.io/spring-data/[Spring Data] project.
[[new-in-1-2-0]]
== New in the 1.2.0 Release
== New in the 1.2 Release
* Full support for GemFire configuration via the SDG *gfe* namespace. Now GemFire components may be configured completely without requiring a native *cache.xml* file.
* WAN Gateway support for GemFire 6.6.x. See <<bootstrap:gateway>>.
@@ -14,18 +14,14 @@ to reflect that it is now a component of the http://projects.spring.io/spring-da
* A top-level `<disk-store>` element has been added to the SDG *gfe* namespace to allow sharing of persist stores among Regions,
and other components that support persistent backup or overflow. See <<bootstrap-diskstore>>
+
WARNING: The `<*-region>` elements no longer allow a nested `<disk-store>`
WARNING: The `<*-region>` elements no longer allow a nested `<disk-store>` element.
+
* GemFire Sub-Regions are supported via nested `<*-region>` elements.
* A `<local-region>` element has been added to configure a Local Region.
[[new-in-1-2-1]]
== New in the 1.2.1 Release
* Support for the re-designed WAN Gateway in GemFire 7.0.
[[new-in-1-3-0]]
== New in the 1.3.0 Release
== New in the 1.3 Release
* Annotation support for GemFire Functions. It is now possible to declare and register Functions written as POJOs using annotations. In addition, Function executions are defined as
annotated interfaces, similar to the way Spring Data Repositories work. See <<function-annotations>>.
@@ -34,37 +30,21 @@ annotated interfaces, similar to the way Spring Data Repositories work. See <<fu
in GemFire 7.0, enabling Spring AOP to perform the necessary conversions automatically on Region operations.
* Upgraded to GemFire 7.0.1 and added namespace support for new AsyncEventQueue attributes.
* Added support for setting subscription interest policy on Regions.
[[new-in-1-3-1]]
== New in the 1.3.1 Release
* Support for void returns on Function executions. See <<function-annotations>> for complete details.
[[new-in-1-3-2]]
== New in the 1.3.2 Release
* Support for persisting Local Regions. See <<bootstrap:region:local>> and <<bootstrap:region:common:attributes>>.
* Support for entry time-to-live and entry idle-time on a GemFire Client Cache. See <<bootstrap:cache:client>>.
* Support for multiple Spring Data GemFire web-based applications using a single GemFire cluster, operating concurrently inside tc Server.
[[new-in-1-3-3]]
== New in the 1.3.3 Release
* Support for concurrency-checks-enabled on all GemFire Cache Region definitions using the SDG *gfe* namespace. See <<bootstrap:region:common:attributes>>.
* Support for Cache Loaders and Cache Writers on Client, Local Regions. See <<bootstrap:region:common:loaders-writers>>.
* Support for registering CacheListeners, AsyncEventQueues and Gateway Senders on GemFire Cache Sub-Regions.
* Support for PDX persistent keys in GemFire Regions.
* Support for correct Partition Region bean creation in a Spring context when collocation is specified with the *colocated-with* attribute.
* Full support for GemFire Cache Sub-Regions using proper, nested `<*-region>` element syntax in the SDG *gfe* namespace.
[[new-in-1-3-4]]
== New in the 1.3.4 Release
* Upgraded Spring Data GemFire to Spring Framework 3.2.8.
* Upgraded Spring Data GemFire to Spring Data Commons 1.7.1.
[[new-in-1-4-0]]
== New in the 1.4.0 Release
== New in the 1.4 Release
* Upgrades Spring Data GemFire to GemFire 7.0.2.
* Upgrades Spring Data GemFire to Spring Data Commons 1.8.0.
@@ -91,7 +71,7 @@ See http://gemfire.docs.pivotal.io/latest/userguide/index.html#supported_configs
for additional details.
[[new-in-1-5-0]]
== New in the 1.5.0 Release
== New in the 1.5 Release
* Upgrades Spring Data GemFire to Spring Data Commons 1.9.0
* Upgrades Spring Data GemFire to Spring Framework 4.0.7
@@ -105,3 +85,14 @@ as required by GemFire.
* Enable GemFire GatewayReceivers to be started manually.
* Support for Auto Region Lookups. See <<bootstrap:region:auto-lookup>> for further details.
* Support for Region Templates See <<bootstrap:region:common:region-templates>> for further details.
[[new-in-1-6-0]]
== New in the 1.6 Release
* Upgrades Spring Data GemFire to GemFire 8.0.
* Adds support for GemFire 8's new Cluster-based Configuration.
* Enables 'auto-reconnect' functionality to be employed in Spring-configured GemFire Servers.
* Allows the creation of concurrent and parallel Async Event Queues and Gateway Senders.
* Adds support for GemFire 8's Region data compression.
* Adds attributes to set both critical and warning percentages on Disk Store usage.
* Supports the capability to add the new EventSubstitutionFilters to GatewaySenders.

3
src/asciidoc/introduction/requirements.adoc
View File

@@ -1,4 +1,5 @@
[[requirements]]
= Requirements
Spring Data GemFire requires JDK 6.0 or above, http://projects.spring.io/spring-framework[Spring Framework] 3 and http://www.pivotal.io/big-data/pivotal-gemfire[Pivotal GemFire] 6.6 or above (version 7 or above is recommended).
Spring Data GemFire requires JDK 6.0 or above, http://projects.spring.io/spring-framework[Spring Framework] 3
and http://www.pivotal.io/big-data/pivotal-gemfire[Pivotal GemFire] 6.6 or above (version 7 or above is recommended).

76
src/asciidoc/reference/bootstrap.adoc
View File

@@ -3,39 +3,56 @@
Spring Data GemFire provides full configuration and initialization of the GemFire data grid through Spring's IoC container and provides several classes that simplify the configuration of GemFire components including Caches, Regions, WAN Gateways, Persistence Backup, and other Distributed System components to support a variety of scenarios with minimal effort.
NOTE: This section assumes basic familiarity with GemFire. For more information see the http://www.pivotal.io/big-data/pivotal-gemfire[product] documentation.
NOTE: This section assumes basic familiarity with GemFire. For more information see the http://www.pivotal.io/big-data/pivotal-gemfire[product documentation].
[[bootstrap:region:spring:config]]
== Advantages of using Spring over GemFire `cache.xml`
As of release 1.2.0, Spring Data GemFire's XML namespace supports full configuration of the data grid. In fact, the Spring Data GemFire namespace is considered the preferred way to configure GemFire. GemFire will continue to support native `cache.xml` for legacy reasons, but you can now do everything in Spring XML and take advantage of the many wonderful things Spring has to offer such as modular XML configuration, property placeholders, SpEL, and environment profiles. Behind the namespace, Spring Data GemFire makes extensive use of Spring's `FactoryBean` pattern to simplify the creation and initialization of GemFire components.
As of release 1.2.0, Spring Data GemFire's XML namespace supports full configuration of the GemFire in-memory data grid.
In fact, Spring Data GemFire's XML namespace is considered to be the preferred way to configure GemFire.
GemFire will continue to support native `cache.xml` for legacy reasons, but GemFire application developers 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 and overrides, SpEL, and environment profiles. Behind the
XML namespace, Spring Data GemFire makes extensive use of Spring's `FactoryBean` pattern to simplify the creation,
configuration and initialization of GemFire components.
For example, GemFire provides several callback interfaces such as `CacheListener`, `CacheWriter`, and `CacheLoader` to allow developers to add custom event handlers. Using the Spring IoC container, these may configured as normal Spring beans and injected into GemFire components. This is a significant improvement over native `cache.xml` which provides relatively limited configuration options and requires callbacks to implement GemFire's `Declarable` interface (see <<apis:declarable>> to see how you can still use `Declarables` within Spring's DI container).
For example, GemFire provides several callback interfaces, such as `CacheListener`, `CacheWriter`, and `CacheLoader`,
that allow developers to add custom event handlers. Using Spring's IoC container, these callbacks may be configured
as normal Spring beans and injected into GemFire components. This is a significant improvement over native `cache.xml`,
which provides relatively limited configuration options and requires callbacks to implement GemFire's `Declarable` interface
(see <<apis:declarable>> to see how you can still use `Declarables` within Spring's IoC/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.
In addition, IDEs such as the Spring Tool Suite (STS) provide excellent support for Spring XML namespaces, such as
code completion, pop-up annotations, and real time validation, making them easy to use.
[[bootstrap:namespace]]
== Using the Core Spring Data GemFire Namespace
To simplify configuration, Spring Data GemFire provides a dedicated XML namespace for configuring core GemFire components. It is also possible to configure the beans directly through Spring's standard <bean> definition. However, as of Spring Data GemFire 1.2.0, all bean properties are exposed via the namespace so there is little benefit to using raw bean definitions. For more information about XML Schema-based configuration in Spring, see http://docs.spring.io/spring/docs/current/spring-framework-reference/htmlsingle/#xsd-config[this] appendix in the Spring Framework reference documentation.
To simplify configuration, Spring Data GemFire provides a dedicated XML namespace for configuring core GemFire components.
It is also possible to configure beans directly using Spring's standard <bean> definition. However, as of
Spring Data GemFire 1.2.0, all bean properties are exposed via the XML namespace so there is little benefit to using
raw bean definitions. For more information about XML Schema-based configuration in Spring, see
http://docs.spring.io/spring/docs/current/spring-framework-reference/htmlsingle/#xsd-config[this] appendix
in the Spring Framework reference documentation.
NOTE: Spring Data Repository support uses a separate XML namespace. See <<gemfire-repositories>> for more information on how to configure GemFire Repositories.
NOTE: Spring Data Repository support uses a separate XML namespace. See <<gemfire-repositories>> for more information
on how to configure Spring Data GemFire Repositories.
To use the Spring Data GemFire namespace, simply declare it in your Spring XML configuration meta-data:
To use the Spring Data GemFire XML namespace, simply declare it in your Spring XML configuration meta-data:
[source,xml]
----
<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
xmlxsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:gfe="http://www.springframework.org/schema/gemfire"<!--1--><!--2-->
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="
http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
http://www.springframework.org/schema/gemfire http://www.springframework.org/schema/gemfire/spring-gemfire.xsd"> <!--3-->
http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
http://www.springframework.org/schema/gemfire http://www.springframework.org/schema/gemfire/spring-gemfire.xsd"> <!--3-->
<bean id ... >
<bean id ... >
<gfe:cache ...> <!--4-->
<gfe:cache ...> <!--4-->
</beans>
----
@@ -46,22 +63,23 @@ To use the Spring Data GemFire namespace, simply declare it in your Spring XML c
[NOTE]
====
It is possible to change the default namespace, for example from `beans` to `gfe`. This is useful for configuration composed mainly of GemFire components as it avoids declaring the prefix. To achieve this, simply swap the namespace prefix declaration above:
It is possible to change the default namespace, for example from `beans` to `gfe`. This is useful for configuration
composed mainly of GemFire components as it avoids declaring the prefix. To achieve this, simply swap the namespace
prefix declaration above:
[source,xml]
----
<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/gemfire" <!--1-->
xmlxsi="http://www.w3.org/2001/XMLSchema-instance"
<!--2-->
xmlns:beans="http://www.springframework.org/schema/beans"
xsi:schemaLocation="
http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
http://www.springframework.org/schema/gemfire http://www.springframework.org/schema/gemfire/spring-gemfire.xsd">
xmlns:beans="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"<!--2-->
xsi:schemaLocation="
http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
http://www.springframework.org/schema/gemfire http://www.springframework.org/schema/gemfire/spring-gemfire.xsd">
<beans:bean id ... > <!--3-->
<beans:bean id ... > <!--3-->
<cache ...> <!--4-->
<cache ...> <!--4-->
</beans>
----
@@ -80,16 +98,24 @@ include::region.adoc[]
[[bootstrap:indicies]]
== Creating an Index
GemFire allows creation on indexes (or indices) to improve the performance of (common) queries. Spring Data GemFire allows indecies to be declared through the `index` element:
GemFire allows the creation of indexes (or indices) to improve the performance of (common) queries.
Spring Data GemFire allows indices to be declared through the `index` element:
[source,xml]
----
<gfe:index id="myIndex" expression="someField" from="/someRegion" />
<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.
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.
Note that index declarations are not bound to a Region but rather are top-level elements (just like `gfe:cache`).
This allows one to declare any number of indices on any Region whether they are just created or already exist
- an improvement over GemFire's native `cache.xml`. By default, the index relies on the default cache declaration
but one can customize it accordingly or use a pool (if need be) - see the namespace schema for the full set of options.
:leveloffset: +1
include::diskstore.adoc[]

214
src/asciidoc/reference/cache.adoc
View File

@@ -1,9 +1,15 @@
[[bootstrap:cache]]
= Configuring the GemFire Cache
In order to use GemFire, one needs to either create a new `Cache` or connect to an existing one. In the current version of GemFire, there can be only one opened cache per VM (or per classloader to be technically correct). In most cases the cache is created once.
In order to use GemFire, a developer 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 only created once.
NOTE: This section describes the creation and configuration of a full cache member, appropriate for peer to peer cache topologies and cache servers. A full cache is also commonly used for standalone applications, integration tests and proofs of concept. In a typical production system, most application processes will act as cache clients and will create a ClientCache instance instead. This is described in the sections <<bootstrap:cache:client>> and <<bootstrap:region:client>>
NOTE: This section describes the creation and configuration of a full Cache member, appropriate for peer-to-peer
cache topologies and cache servers. A full cache is also commonly used for standalone applications, integration tests
and proofs of concept. In a typical production system, most application processes will act as cache clients
and will create a `ClientCache` instance instead. This is described in the sections <<bootstrap:cache:client>>
and <<bootstrap:region:client>>
A cache with default configuration can be created with a very simple declaration:
@@ -12,103 +18,211 @@ 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.
Upon initialization, a Spring application context containing this cache definition will register a `CacheFactoryBean`
to create a Spring bean named `gemfireCache` referencing a GemFire `Cache` instance. This will either be 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:
All Spring Data GemFire components that depend on the cache respect this naming convention so that there is no need
to explicitly declare the cache dependency. If you prefer, you can make the dependence explicit via the `cache-ref`
attribute provided by various namespace elements. Also, you can easily override the cache's bean name:
[source,xml]
----
<gfe:cache id="my-cache"/>
----
Starting with Spring Data GemFire 1.2.0, The GemFire Cache may be fully configured using Spring. However, GemFire's native XML configuration file (e.g., cache.xml) is also supported. For scenarios in which the GemFire cache needs to be configured natively, simply provide a reference the GemFire configuration file using the `cache-xml-location` attribute:
Starting with Spring Data GemFire 1.2.0, the GemFire `Cache` may be fully configured using Spring. However, GemFire's
native XML configuration file, `cache.xml`, is also supported. For scenarios in which the GemFire cache needs to be
configured natively, simply provide a reference to the GemFire configuration file using the `cache-xml-location`
attribute:
[source,xml]
----
<gfe:cache id="cache-with-xml" cache-xml-location="classpath:cache.xml"/>
<gfe:cache id="cache-using-native-xml" cache-xml-location="classpath:cache.xml"/>
----
In this example, if the cache needs to be created, it will use the file named `cache.xml` located in the classpath root.
NOTE: Note that the configuration makes use of Spring's http://docs.spring.io/spring/docs/current/spring-framework-reference/htmlsingle/#resources[`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.
NOTE: Note that the configuration makes use of Spring's http://docs.spring.io/spring/docs/current/spring-framework-reference/htmlsingle/#resources[`Resource`]
abstraction to locate the file. This allows various search patterns to be used, depending on the runtime environment
or the prefix specified (if any) in the resource location.
In addition to referencing an external configuration file one can specify GemFire http://gemfire.docs.pivotal.io/latest/userguide/index.html#reference/topics/gemfire_properties.html[properties] using any of Spring's common properties support features. For example, one can use the `properties` element defined in the `util` namespace to define properties directly or load properties from properties files. The latter is recommended for externalizing environment specific settings outside the application configuration:
In addition to referencing an external configuration file one can specify GemFire http://gemfire.docs.pivotal.io/latest/userguide/index.html#reference/topics/gemfire_properties.html[properties]
using any of Spring's common properties support features. For example, one can use the `properties` element
defined in the `util` namespace to define properties directly or load properties from a properties files. The latter is
recommended for externalizing environment specific settings outside the application configuration:
[source,xml]
----
<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:gfe="http://www.springframework.org/schema/gemfire"
xmlns:util="http://www.springframework.org/schema/util"
xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
http://www.springframework.org/schema/gemfire http://www.springframework.org/schema/gemfire/spring-gemfire.xsd
http://www.springframework.org/schema/util http://www.springframework.org/schema/util/spring-util.xsd">
xmlns:gfe="http://www.springframework.org/schema/gemfire"
xmlns:util="http://www.springframework.org/schema/util"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
http://www.springframework.org/schema/gemfire http://www.springframework.org/schema/gemfire/spring-gemfire.xsd
http://www.springframework.org/schema/util http://www.springframework.org/schema/util/spring-util.xsd">
<gfe:cache properties-ref="props"/>
<util:properties id="gemfireProperties" location="file:/pivotal/gemfire/gemfire.properties"/>
<gfe:cache properties-ref="gemfireProperties"/>
<util:properties id="props" location="file:/vfabric/gemfire/gemfire.properties"/>
</beans>
----
NOTE: The cache settings apply only if a new cache needs to be created. If an open cache already exists in the JVM, these settings will be ignored.
NOTE: The cache settings apply only if a new cache needs to be created. If an open cache already exists in the VM,
these settings will be ignored.
[[bootstrap:cache:advanced]]
== Advanced Cache Configuration
For advanced cache configuration, the `cache` element provides a number of configuration options exposed as attributes or child elements
For advanced cache configuration, the `cache` element provides a number of configuration options exposed as attributes
or child elements:
[source,xml]
----
<!--1-->
<gfe:cache
copy-on-read="true"
critical-heap-percentage="70"
eviction-heap-percentage="60"
lock-lease="120"
lock-timeout="60"
pdx-serializer="myPdxSerializer"
pdx-disk-store="diskStore"
pdx-ignore-unread-fields="true"
pdx-persistent="true"
pdx-read-serialized="false"
message-sync-interval="1"
search-timeout="300"
close="false"
lazy-init="true">
close="false"
copy-on-read="true"
critical-heap-percentage="70"
eviction-heap-percentage="60"
enable-auto-reconnect="false" <!--2-->
lock-lease="120"
lock-timeout="60"
message-sync-interval="1"
pdx-serializer-ref="myPdxSerializer"
pdx-persistent="true"
pdx-disk-store="diskStore"
pdx-read-serialized="false"
pdx-ignore-unread-fields="true"
search-timeout="300"
use-cluster-configuration="false" <!--3-->
lazy-init="true">
<gfe:transaction-listener ref="myTransactionListener"/><!--2-->
<gfe:transaction-listener ref="myTransactionListener"/> <!--4-->
<gfe:transaction-writer> <!--3-->
<bean class="org.springframework.data.gemfire.example.TransactionListener"/>
</gfe:transaction-writer>
<gfe:transaction-writer> <!--5-->
<bean class="org.springframework.data.gemfire.example.TransactionListener"/>
</gfe:transaction-writer>
<gfe:gateway-conflict-resolver ref="myGatewayConflictResolver"/> <!--6-->
<gfe:dynamic-region-factory/> <!--7-->
<gfe:jndi-binding jndi-name="myDataSource" type="ManagedDataSource"/> <!--8-->
<gfe:dynamic-region-factory/> <!--4-->
<gfe:jndi-binding jndi-name="myDataSource" type="ManagedDataSource"/> <!--5-->
</gfe:cache>
----
<1> Various cache options are supported by attributes. For further information regarding anything shown in this example, please consult the GemFire product http://gemfire.docs.pivotal.io/index.html[documentation]
<1> Various cache options are supported by attributes. For further information regarding anything shown in this example, please consult the GemFire http://gemfire.docs.pivotal.io/index.html[product documentation].
The `close` attribute determines if the cache should be closed when the Spring application context is closed. The default is `true` however for cases in which multiple application contexts use the cache (common in web applications), set this value to `false`.
The `lazy-init` attribute determines if the cache should be initialized before another bean references it. The default is `true` however in some cases it may be convenient to set this value to `false`.
<2> An example of a `TransactionListener` callback declaration using a bean reference. The referenced bean must implement http://gemfire.docs.pivotal.io/latest/javadocs/japi/com/gemstone/gemfire/cache/TransactionListener.html[TransactionListener]
<3> An example of a `TransactionWriter` callback declaration using an inner bean declaration this time. The bean must implement http://gemfire.docs.pivotal.io/latest/javadocs/japi/com/gemstone/gemfire/cache/TransactionWriter.html[TransactionWriter]
<4> Enable GemFire's http://gemfire.docs.pivotal.io/latest/javadocs/japi/com/gemstone/gemfire/cache/DynamicRegionFactory.html[DynamicRegionFactory]
<5> Declares a JNDI binding to enlist an external datasource in a GemFire transaction
<2> Setting the `enable-auto-reconnect` attribute to true (default is false), allows a disconnected GemFire member to automatically reconnect and rejoin a GemFire cluster.
See the GemFire http://gemfire.docs.pivotal.io/latest/userguide/index.html#relnotes/release_notes.html#topic_5mbwjl__section_wxb_v35_v4[product documentation] for more details.
<3> Setting the `use-cluster-configuration` attribute to true (default is false) to enable a GemFire member to retrieve the common, shared Cluster-based configuration from a Locator.
See the GemFire http://gemfire.docs.pivotal.io/latest/userguide/index.html#relnotes/release_notes.html#topic_5mbwjl__section_zk2_p35_v4[product documentation] for more details.
<4> An example of a `TransactionListener` callback declaration using a bean reference. The referenced bean must implement
http://gemfire.docs.pivotal.io/latest/javadocs/japi/com/gemstone/gemfire/cache/TransactionListener.html[TransactionListener].
`TransactionListener(s)` can be implemented to handle transaction related events.
<5> An example of a `TransactionWriter` callback declaration using an inner bean declaration this time. The bean must implement
http://gemfire.docs.pivotal.io/latest/javadocs/japi/com/gemstone/gemfire/cache/TransactionWriter.html[TransactionWriter].
`TransactionWriter` is a callback that is allowed to veto a transaction.
<6> An example of a `GatewayConflictResolver` declaration using a bean reference. The referenced bean must implement
http://gemfire.docs.pivotal.io/latest/javadocs/japi/com/gemstone/gemfire/cache/util/GatewayConflictResolver.html[GatewayConflictResolver].
GatewayConflictResolver is a Cache-level plugin that is called upon to decide what to do with events that originate in other systems and arrive through the WAN Gateway.
<7> Enable GemFire's http://gemfire.docs.pivotal.io/latest/javadocs/japi/com/gemstone/gemfire/cache/DynamicRegionFactory.html[DynamicRegionFactory],
which provides a distributed region creation service.
<8> Declares a JNDI binding to enlist an external DataSource in a GemFire transaction.
NOTE: The `use-bean-factory-locator` attribute (not shown) deserves a mention. The factory bean responsible for creating the cache uses an internal Spring type called a
`BeanFactoryLocator` to enable user classes declared in GemFire's native `cache.xml` to be registered as Spring beans. The `BeanFactoryLocator` implementation also permits
only one bean definition for a cache with a given id. In certain situations, such as running JUnit integration tests from within Eclipse, it is necessary to disable
the `BeanFactoryLocator` by setting this value to false to prevent an exception. This exception may also arise during JUnit tests running from a build script. In this
case the test runner should be configured to fork a new JVM for each test (in maven, set `<forkmode>always</forkmode>`) . Generally there is no harm in setting this
value to false.
NOTE: The `use-bean-factory-locator` attribute (not shown) deserves a mention. The factory bean responsible for
creating the cache uses an internal Spring type called a `BeanFactoryLocator` to enable user classes declared in
GemFire's native `cache.xml` to be registered as Spring beans. The `BeanFactoryLocator` implementation also permits
only one bean definition for a cache with a given id. In certain situations, such as running JUnit integration tests
from within Eclipse, it is necessary to disable the `BeanFactoryLocator` by setting this value to false to prevent
an exception. This exception may also arise during JUnit tests running from a build script. In this case the test runner
should be configured to fork a new JVM for each test (in maven, set `<forkmode>always</forkmode>`) . Generally, there is
no harm in setting this value to false.
=== Enabling PDX Serialization
The example above includes a number of attributes related to GemFire's enhanced serialization framework, PDX. While a complete discussion of PDX is beyond the scope of this reference guide, it is important to note that PDX is enabled by registering a PDX serializer which is done via the `pdx-serializer` attribute. GemFire provides an implementation class `com.gemstone.gemfire.pdx.ReflectionBasedAutoSerializer`, however it is common for developers to provide their own implementation. The value of the attribute is simply a reference to a Spring bean that implements the required interface. More information on serialization support can be found in <<serialization>>
The example above includes a number of attributes related to GemFire's enhanced serialization framework, PDX.
While a complete discussion of PDX is beyond the scope of this reference guide, it is important to note that PDX
is enabled by registering a PDX serializer which is done via the `pdx-serializer` attribute. GemFire provides
an implementation class `com.gemstone.gemfire.pdx.ReflectionBasedAutoSerializer`, however it is common for developers
to provide their own implementation. The value of the attribute is simply a reference to a Spring bean that implements
the required interface. More information on serialization support can be found in <<serialization>>
[[boostrap:cache:auto-reconnect]]
=== Enabling auto-reconnect
Setting the `<gfe:cache enable-auto-reconnect="[true|false*]>` attribute to true should be done with care.
Generally, enabling 'auto-reconnect' should only be done in cases where Spring Data GemFire's XML namespace is used to
configure and bootstrap a new GemFire Server data node to add to the cluster. In other words, 'auto-reconnect'
should not be used when Spring Data GemFire is used to develop and build an GemFire application that also happens
to be a peer cache member of the GemFire cluster.
The main reason is most GemFire applications use references to the GemFire cache or regions in order to perform
data access operations. The references are "injected" by the Spring container into application components (e.g. DAOs
or Repositories) for use by the application. When a member (such as the application) is forcefully disconnected
from the rest of the cluster, presumably because the member (the application) has become unresponsive for
a period of time, or network partition separates one or more members (along with the application peer cache member) into
a group that is too small to act as the distributed system, the member will shutdown and all GemFire component references
(e.g. Cache, Regions, etc) become invalid.
Essentially, the current forced-disconnect processing in each member dismantles the system from the ground up.
It shuts down the JGroups stack, puts the Distributed System in a shut-down state and then closes the Cache.
This effectively loses all in-memory information.
After being disconnected from a distributed system and successfully shutting down, the GemFire member then restarts in a
"reconnecting" state, while periodically attempting to rejoin the distributed system. If the member succeeds in reconnecting,
the member rebuilds its "view" of the distributed system from existing members and receives a new distributed system ID.
This means the cache, regions and other GemFire components are reconstructed and all old references that may have been
injected into application are now stale and no longer valid.
GemFire makes no guarantee, even when using the GemFire public Java API, that application cache, region or other
component references will be automatically refreshed by the reconnect operation. As such, applications must take care
to refresh their own references.
Unfortunately there is no way to be "notified" of a disconnect and subsequently a reconnect event. If so, the application
developer would then have a clean way to know when to call ConfigurableApplicationContext.refresh(), if even applicable
for an application to do so, which is why this "feature" of GemFire 8 is not recommended for peer cache GemFire applications.
For more information about 'auto-reconnect', see GemFire's http://gemfire.docs.pivotal.io/latest/userguide/index.html#managing/autoreconnect/member-reconnect.html#concept_22EE6DDE677F4E8CAF5786E17B4183A9[product documentation].
[[bootstrap:cache:cluster-configuration]]
=== Using Cluster-based Configuration
GemFire 8's new Cluster-based Configuration Service is a convenient way for a member joining the cluster to get a
"consistent view" of the cluster, by using the shared, persistent configuration maintained by a Locator, ensuring
the member's configuration will be compatible with the GemFire distributed system when the member joins.
This feature of Spring Data GemFire (setting the `use-cluster-configuration` attribute to true) works in the same way
as the `cache-xml-location` attribute, except the source of the GemFire configuration meta-data comes from a network
Locator as opposed to a native `cache.xml` file.
All GemFire native configuration meta-data, whether from `cache.xml` or from the Cluster Configuration Service,
gets applied before any Spring XML configuration meta-data. As such, Spring's config serves to "augment" the
native GemFire configuration meta-data, which would most likely be specific to the application.
Again, to enable this feature, just specify the following in the Spring XML config:
[source,xml]
----
<gfe:cache use-cluster-configuration="true"/>
----
NOTE: While certain GemFire tools, like Gfsh, have their actions "recorded" when any schema-like change is made
(e.g. `gfsh>create region --name=Example --type=PARTITION`) to the cluster, Spring Data GemFire's configuration meta-data
specified with the XML namespace is not recorded. The same is true when using GemFire's public Java API directly;
it too is not recorded.
For more information on GemFire's Cluster Configuration Service, see the
http://gemfire.docs.pivotal.io/latest/userguide/index.html#deploying/gfsh/gfsh_persist.html[product documentation].
[[bootstrap:cache:server]]
== Configuring a GemFire Cache Server

18
src/main/resources/org/springframework/data/gemfire/config/spring-gemfire-1.6.xsd
View File

@@ -21,8 +21,7 @@
<!-- -->
<xsd:complexType name="cacheBaseType">
<xsd:sequence>
<xsd:element name="transaction-listener" type="beanDeclarationType"
minOccurs="0" maxOccurs="unbounded">
<xsd:element name="transaction-listener" type="beanDeclarationType" minOccurs="0" maxOccurs="unbounded">
<xsd:annotation>
<xsd:documentation><![CDATA[
Registers a bean as a TransactionListener with the CacheTransactionManager. The bean must implement com.gemstone.gemfire.cache.TransactionListener
@@ -30,8 +29,7 @@ and may be nested or referenced.
]]></xsd:documentation>
</xsd:annotation>
</xsd:element>
<xsd:element name="transaction-writer" type="beanDeclarationType"
minOccurs="0" maxOccurs="1">
<xsd:element name="transaction-writer" type="beanDeclarationType" minOccurs="0" maxOccurs="1">
<xsd:annotation>
<xsd:documentation><![CDATA[
Registers a bean as a TransactionWriter with the CacheTransactionManager. The bean must implement com.gemstone.gemfire.cache.TransactionWriter
@@ -39,8 +37,7 @@ and may be nested or referenced.
]]></xsd:documentation>
</xsd:annotation>
</xsd:element>
<xsd:element name="gateway-conflict-resolver" minOccurs="0"
maxOccurs="1">
<xsd:element name="gateway-conflict-resolver" minOccurs="0" maxOccurs="1">
<xsd:annotation>
<xsd:documentation
source="com.gemstone.gemfire.cache.util.GatewayConflictResolver"><![CDATA[
@@ -56,8 +53,7 @@ must implement com.gemstone.gemfire.cache.util.GatewayConflictResolver. Requires
</xsd:annotation>
<xsd:complexType>
<xsd:sequence>
<xsd:any namespace="##other" processContents="skip"
minOccurs="0" maxOccurs="unbounded">
<xsd:any namespace="##other" processContents="skip" minOccurs="0" maxOccurs="unbounded">
<xsd:annotation>
<xsd:documentation><![CDATA[
Inner bean definition of the gateway conflict resolver.
@@ -75,8 +71,7 @@ use inner bean declarations.
</xsd:attribute>
</xsd:complexType>
</xsd:element>
<xsd:element name="dynamic-region-factory" minOccurs="0"
maxOccurs="1">
<xsd:element name="dynamic-region-factory" minOccurs="0" maxOccurs="1">
<xsd:annotation>
<xsd:documentation><![CDATA[
Enables Dynamic Regions and specifies their configuration.
@@ -108,8 +103,7 @@ Specifies whether dynamic regions register interest in all keys in a correspondi
</xsd:attribute>
</xsd:complexType>
</xsd:element>
<xsd:element name="jndi-binding" type="jndiBindingType"
minOccurs="0" maxOccurs="unbounded">
<xsd:element name="jndi-binding" type="jndiBindingType" minOccurs="0" maxOccurs="unbounded">
<xsd:annotation>
<xsd:documentation><![CDATA[
Configures a data source to be bound to a JNDI context for use with Gemfire transactions