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

SGF-768 - Edit Reference Guide for spelling, grammar and content.

Browse Source
This commit is contained in:
John Blum
2018-07-24 11:01:52 -07:00
parent cf4b4d6cd3
commit 4288c680c9
27 changed files with 1787 additions and 1715 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
src/main/asciidoc/appendix/appendix-schema.adoc
View File

@@ -1,6 +1,6 @@
[[appendix-schema]]
[appendix]
= Spring Data for {data-store-name} Schema
= {sdg-name} Schema
* {spring-data-schema-location}[Spring Data for {data-store-name} Core Schema (`gfe` namespace)]
* {spring-data-access-schema-location}[Spring Data for {data-store-name} Data Access Schema (`gfe-data` namespace)]
* {spring-data-schema-location}[{sdg-name} Core Schema (`gfe` XML namespace)]
* {spring-data-access-schema-location}[{sdg-name} Data Access Schema (`gfe-data` XML namespace)]

7
src/main/asciidoc/index.adoc
View File

@@ -15,12 +15,17 @@ Costin Leau; David Turanski; John Blum; Oliver Gierke; Jay Bryant
:apache-geode-javadoc: http://geode.apache.org/releases/latest/javadoc
:apache-geode-website: http://geode.apache.org
:apache-geode-wiki: https://cwiki.apache.org/confluence/display/GEODE
:data-store-name: Pivotal GemFire
:data-store-name-symbolic: gemfire
:data-store-name-simple: GemFire
:data-store-name: Pivotal {data-store-name-simple}
:data-store-version: 9.5.1
:pivotal-gemfire-version: 95
:pivotal-gemfire-docs: http://gemfire.docs.pivotal.io/{pivotal-gemfire-version}
:pivotal-gemfire-javadoc: http://gemfire-{pivotal-gemfire-version}-javadocs.docs.pivotal.io/
:pivotal-gemfire-website: https://pivotal.io/pivotal-gemfire
:pivotal-gemfire-wiki: https://cwiki.apache.org/confluence/display/GEODE
:sdg-acronym: SDG
:sdg-javadoc: https://docs.spring.io/spring-data/{data-store-name-symbolic}/docs/current/api
:sdg-name: Spring Data for {data-store-name}
:spring-data-access-schema-location: http://www.springframework.org/schema/data/gemfire/spring-data-gemfire.xsd
:spring-data-access-schema-namespace: http://www.springframework.org/schema/data/gemfire

2
src/main/asciidoc/introduction/introduction.adoc
View File

@@ -1,6 +1,6 @@
[[introduction]]
= Introduction
The Spring Data for {data-store-name} reference guide explains how to use the Spring Framework
The {sdg-name} reference guide explains how to use the Spring Framework
to configure and develop applications with {data-store-name}. It presents the basic concepts
and provides numerous examples to help you get started quickly.

171
src/main/asciidoc/introduction/new-features.adoc
View File

@@ -1,22 +1,23 @@
[[new-features]]
= New Features
NOTE: As of the 1.2.0.RELEASE, this project, formerly known as Spring GemFire, has been renamed to
Spring Data for {data-store-name} to reflect that it is now a module of the
http://projects.spring.io/spring-data/[Spring Data] project
and built on {x-data-store-website}[{data-store-name}].
NOTE: As of the 1.2.0.RELEASE, this project, formerly known as Spring GemFire, has been renamed to {sdg-name}
to reflect that it is now a module of the {spring-data-website}[Spring Data] project and built on
{x-data-store-website}[{data-store-name}].
[[new-in-1-2-0]]
== New in the 1.2 Release
* Full support for {data-store-name} configuration through the SDG *gfe* namespace. Now {data-store-name} components may be configured completely without requiring a native cache.xml file.
* WAN Gateway support for {data-store-name} 6.6.x. See <<bootstrap:gateway>>.
* Spring Data Repository support using a dedicated SDG namespace, *gfe-data*. See <<gemfire-repositories>>
* Namespace support for registering {data-store-name} Functions. See <<bootstrap:function>>
* A top-level `<disk-store>` element has been added to the SDG *gfe* namespace to allow sharing of persist stores among regions
as well as other components that support persistent backup or overflow. See <<bootstrap-diskstore>>
* Full support for {data-store-name} configuration through the SDG `gfe` XML namespace. Now {data-store-name} components
may be configured completely without requiring a native `cache.xml` file.
* WAN Gateway support for {data-store-name} 6.6.x. See <<bootstrap:gateway>>
* Spring Data Repository support using a dedicated SDG XML namespace, *gfe-data*. See <<gemfire-repositories>>
* `gfe-data` XML Namespace support for registering {data-store-name} Functions. See <<bootstrap:function>>
* A top-level `<disk-store>` element has been added to the SDG `gfe` XML namespace to allow sharing of persist stores
among regions as well as other {data-store-name} components that support persistent backup or overflow.
See <<bootstrap-diskstore>>
+
WARNING: The `<*-region>` elements no longer allow a nested `<disk-store>` element.
WARNING: `<*-region>` elements no longer allow a nested `<disk-store>` element.
+
* {data-store-name} Sub-Regions are supported by nested `<*-region>` elements.
* A `<local-region>` element has been added to configure a Local Region.
@@ -25,89 +26,93 @@ WARNING: The `<*-region>` elements no longer allow a nested `<disk-store>` eleme
[[new-in-1-3-0]]
== New in the 1.3 Release
* Annotation support for {data-store-name} Functions. It is now possible to declare and register Functions written as POJOs by using annotations. In addition, function executions are defined as
* Upgraded to Spring Framework 3.2.8.
* Upgraded to Spring Data Commons 1.7.1.
* Annotation support for {data-store-name} Functions. It is now possible to declare and register Functions
written as POJOs by using annotations. In addition, Function executions are defined as
annotated interfaces, similar to the way Spring Data Repositories work. See <<function-annotations>>.
* Added a `<datasource>` element to the SDG `gfe-data` namespace to simplify establishing a basic <<data-access:datasource,client connection>> to a {data-store-name} data grid.
* Added a `<json-region-autoproxy>` element to the SDG `gfe-data` namespace to <<bootstrap:region:json,support JSON>> features introduced
in {data-store-name} 7.0, enabling Spring AOP to perform the necessary conversions automatically on Region operations.
* Upgraded to {data-store-name} 7.0.1 and added namespace support for new AsyncEventQueue attributes.
* Added a `<datasource>` element to the SDG XML namespace to simplify establishing a basic <<data-access:datasource,client connection>>
to a {data-store-name} data grid.
* Added a `<json-region-autoproxy>` element to the SDG `gfe-data` XML namespace to <<bootstrap:region:json,support JSON>>
features introduced in {data-store-name} 7.0, enabling Spring AOP to perform the necessary conversions automatically
on Region data access operations.
* Upgraded to {data-store-name} 7.0.1 and added XML namespace support for new `AsyncEventQueue` attributes.
* Added support for setting subscription interest policy on Regions.
* Support for void returns on Function executions. See <<function-annotations>> for complete details.
* Support for persisting Local Regions. See <<bootstrap:region:local>>.
* Support for entry time-to-live and entry idle-time on a {data-store-name} Client Cache. See <<bootstrap:cache:client>>.
* Support for multiple Spring Data for {data-store-name} web-based applications by using a single {data-store-name} cluster, operating concurrently inside tc Server.
* Support for `concurrency-checks-enabled` on all {data-store-name} Cache Region definitions by using the SDG `gfe` namespace. See <<bootstrap:region:common:attributes>>.
* Support for Cache Loaders and Cache Writers on the Client for Local Regions.
* Support for registering CacheListeners, AsyncEventQueues, and Gateway Senders on {data-store-name} Cache Sub-Regions.
* Support for PDX persistent keys in {data-store-name} Regions.
* Support for correct Partition Region bean creation in a Spring context when collocation is specified with the `colocated-with` attribute.
* Full support for {data-store-name} Cache Sub-Regions using proper, nested `<*-region>` element syntax in the SDG `gfe` namespace.
* Upgraded Spring Data for {data-store-name} to Spring Framework 3.2.8.
* Upgraded Spring Data for {data-store-name} to Spring Data Commons 1.7.1.
* Support for entry time-to-live (TTL) and entry idle-time (TTI) on a {data-store-name} Client Cache. See <<bootstrap:cache:client>>
* Support for multiple {sdg-name} web-based applications by using a single {data-store-name} cluster,
operating concurrently inside tc Server.
* Support for `concurrency-checks-enabled` on all Cache Region definitions by using the SDG `gfe` XML namespace.
See <<bootstrap:region:common:attributes>>
* Support for `CacheLoaders` and `CacheWriters` on client, Local Regions.
* Support for registering `CacheListeners`, `AsyncEventQueues`, and `GatewaySenders` on {data-store-name} Cache Sub-Regions.
* Support for PDX persistent keys in Regions.
* Support for correct Partition Region bean creation in a Spring context when collocation is specified with
the `colocated-with` attribute.
* Full support for Cache Sub-Regions using proper, nested `<*-region>` element syntax in the SDG `gfe` XML namespace.
[[new-in-1-4-0]]
== New in the 1.4 Release
* Upgraded to {data-store-name} 7.0.2.
* Upgraded to Spring Data Commons 1.8.x.RELEASE.
* Upgraded to Spring Framework 3.2.x.RELEASE.
* Integrated Spring Data for {data-store-name} with Spring Boot, which includes both a `spring-boot-starter-data-gemfire` POM
* Upgraded to Spring Framework 3.2.13.RELEASE.
* Upgraded to Spring Data Commons 1.8.6.RELEASE.
* Integrated {sdg-name} with Spring Boot, which includes both a `spring-boot-starter-data-gemfire` POM
and a Spring Boot sample application that demonstrates {data-store-name} Cache Transactions configured with SDG
and bootstrapped with Spring Boot.
* Added support for bootstrapping a Spring `ApplicationContext` in a {data-store-name} Server when started from `Gfsh`.
See <<gemfire-bootstrap>> for more details.
See <<gemfire-bootstrap>>
* Added support for persisting application domain object and entities to multiple {data-store-name} Cache Regions.
See <<mapping.entities>> for more details.
* Added support for persisting application domain object and entities to {data-store-name} Cache Sub-Regions, avoiding collisions
when Sub-Regions are uniquely identifiable but identically named.
See <<mapping.entities>> for more details.
* Added strict XSD type rules to and full support for Data Policies and Region Shortcuts
on all {data-store-name} Cache Region types.
See <<mapping.entities>>
* Added support for persisting application domain object and entities to {data-store-name} Cache Sub-Regions,
avoiding collisions when Sub-Regions are uniquely identifiable, but identically named.
See <<mapping.entities>>
* Added strict XSD type rules to Data Policies and Region Shortcuts on all {data-store-name} Cache Region types.
* Changed the default behavior of SDG `<*-region>` elements from lookup to always create a new Region
along with an option to restore the old behavior (by using the `ignore-if-exists` attribute).
with an option to restore the old behavior using the `ignore-if-exists` attribute.
See <<bootstrap:region:common:attributes, Common Region Attributes>>
and <<bootstrap:region:common:regions-subregions-lookups-caution>>
for more details.
* Spring Data for {data-store-name} can now be fully built and ran on JDK 7 and JDK 8.
* {sdg-name} can now be fully built and run on JDK 7 and JDK 8.
[[new-in-1-5-0]]
== New in the 1.5 Release
* Maintained support for {data-store-name} 7.0.2.
* Upgraded to _Spring Data Commons_ 1.9.x.RELEASE.
* Upgraded to _Spring Framework_ 4.0.x.RELEASE.
* Migrated the Reference Guide to Asciidoc.
* Renewed support for deploying Spring Data for {data-store-name} in an OSGi container.
* Removed all default values in the Spring Data for {data-store-name} XML namespace Region-type elements to
rely on {data-store-name} defaults instead.
* Added convenience to automatically create Disk Store directory locations.
* Maintained compatibility with {data-store-name} 7.0.2.
* Upgraded to _Spring Framework_ 4.0.9.RELEASE.
* Upgraded to _Spring Data Commons_ 1.9.4.RELEASE.
* Converted Reference Guide to Asciidoc.
* Renewed support for deploying {sdg-name} in an OSGi container.
* Removed all default values specified in {sdg-name} XML namespace Region-type elements
to rely on {data-store-name} defaults instead.
* Added convenience to automatically create `DiskStore` directory locations.
* SDG annotated Function implementations can now be executed from `Gfsh`.
* Enabled {data-store-name} `GatewayReceivers` to be started manually.
* Added support for Auto Region Lookups. See <<bootstrap:region:auto-lookup>> for further details.
* Added support for Region Templates. See <<bootstrap:region:common:region-templates>> for further details.
* Added support for Auto Region Lookups. See <<bootstrap:region:auto-lookup>>
* Added support for Region Templates. See <<bootstrap:region:common:region-templates>>
[[new-in-1-6-0]]
== New in the 1.6 Release
* Upgraded to {data-store-name} 8.0.0.
* Upgraded to Spring Data Commons 1.10.x.RELEASE.
* Maintained support for Spring Framework 4.0.x.RELEASE.
* Added support for {data-store-name} 8's new Cluster-based Configuration.
* Maintained compatibility with Spring Framework 4.0.9.RELEASE.
* Upgraded to Spring Data Commons 1.10.2.RELEASE.
* Added support for {data-store-name} 8's new Cluster-based Configuration Service.
* Enabled 'auto-reconnect' functionality to be employed in Spring-configured {data-store-name} Servers.
* Allowed the creation of concurrent and parallel Async Event Queues and Gateway Senders.
* Allowed the creation of concurrent and parallel `AsyncEventQueues` and `GatewaySenders`.
* Added support for {data-store-name} 8's Region data compression.
* Added attributes to set both critical and warning percentages on Disk Store usage.
* Supported the capability to add the new EventSubstitutionFilters to GatewaySenders.
* Added attributes to set both critical and warning percentages on `DiskStore` usage.
* Supported the capability to add `EventSubstitutionFilters` to `GatewaySenders`.
[[new-in-1-7-0]]
== New in the 1.7 Release
* Upgraded to {data-store-name} 8.1.0.
* Upgraded to Spring Data Commons 1.11.x.RELEASE.
* Upgraded to Spring Framework 4.1.x.RELEASE.
* Added early access support for {data-store-name}.
* Added support for adding Spring-defined Cache Listeners, Loaders, and Writers on "existing" {data-store-name} Regions
configured in Spring XML, `cache.xml`, or even with {data-store-name}'s Cluster Config.
* Upgraded to Spring Framework 4.1.9.RELEASE.
* Upgraded to Spring Data Commons 1.11.6.RELEASE.
* Added early access support for Apache Geode.
* Added support for adding Spring-defined `CacheListeners`, `CacheLoaders`, and `CacheWriters` on existing Regions
configured in Spring XML, `cache.xml`, or even with {data-store-name}'s Cluster Configuration Service.
* Added Spring JavaConfig support to `SpringContextBootstrappingInitializer`.
* Added support for custom `ClassLoaders` in `SpringContextBootstrappingInitializer` to load Spring-defined bean classes.
* Added support for `LazyWiringDeclarableSupport` re-initialization and complete replacement for `WiringDeclarableSupport`.
@@ -117,50 +122,51 @@ endpoint lists configured with Spring's property placeholders.
* Added multi-index definition and creation support.
* <<bootstrap:region:expiration:annotation>>
* <<gemfire-repositories:oql-extensions>>
* <<bootstrap:snapshot>>
* Added support for Cache and Region data snapshots. See <<bootstrap:snapshot>>
[[new-in-1-8-0]]
== New in the 1.8 Release
* Upgraded to {data-store-name} 8.2.0.
* Upgraded to Spring Data Commons 1.12.x.RELEASE.
* Upgraded to Spring Framework 4.2.x.RELEASE.
* Upgraded to Spring Framework 4.2.9.RELEASE.
* Upgraded to Spring Data Commons 1.12.11.RELEASE.
* Added Maven POM to build SDG with Maven.
* Addsed support for CDI.
* Added support for CDI.
* Enabled a `ClientCache` to be configured without a `Pool`.
* Made `<gfe:cache>` and `<gfe:client-cache>` elements `use-bean-factory-locator` attributes default to *false*.
* Defaulted `<gfe:cache>` and `<gfe:client-cache>` elements `use-bean-factory-locator` attribute to *false*.
* Added `durable-client-id` and `durable-client-timeout` attributes to `<gfe:client-cache>`.
* Made GemfirePersistentProperty now properly handle other non-entity, scalar-like types (such as `BigDecimal` and `BigInteger`).
* Made `GemfirePersistentProperty` now properly handle other non-entity, scalar-like types
(e.g. `BigDecimal` and `BigInteger`).
* Prevented SDG-defined `Pools` from being destroyed before `Regions` that use those `Pools`.
* Handled case-insensitive {data-store-name} OQL queries defined as Repository query methods.
* Changed `GemFireCache.evict(key)` to call `Region.remove(key)` in SDG's Spring Cache Abstraction support.
* Changed `GemFireCache.evict(key)` to call `Region.remove(key)` in SDG's Spring _Cache Abstraction_ support.
* Fixed `RegionNotFoundException` with Repository queries on a client `Region` associated with a specific `Pool`
configured for {data-store-name} server groups.
* Changed `Gateway Senders/Receivers` to no longer be tied to the Spring container.
* Changed `GatewaySenders/Receivers` to no longer be tied to the Spring container.
[[new-in-1-9-0]]
== New in the 1.9 Release
* Upgraded to {data-store-name} 8.2.4.
* Upgraded to Spring Data Commons 1.13.x.RELEASE.
* Upgraded to Spring Framework 4.3.x.RELEASE.
* Upgraded to {data-store-name} 8.2.11.
* Upgraded to Spring Framework 4.3.18.RELEASE.
* Upgraded to Spring Data Commons 1.13.13.RELEASE.
* Introduced an entirely new Annotation-based configuration model inspired by Spring Boot.
* Added support for suspend and resume in the `GemfireTransactionManager`.
* Added support in Repositories to use the bean `id` property as the Region key when the `@Id` annotation
is not present.
* Used `MappingPdxSerializer` as the default {data-store-name} serialization strategy when `@EnablePdx` is used.
* Enabled `GemfireCacheManager` to explicitly list Region names to be used in the Spring's Caching Abstraction.
* Enabled `GemfireCacheManager` to explicitly list Region names to be used in the Spring's _Caching Abstraction_.
* Configured {data-store-name} Caches, CacheServers, Locators, Pools, Regions, Indexes, DiskStores, Expiration, Eviction,
Statistics, Mcast, HttpService, Auth, SSL, Logging, System Properties.
* Added repository support with multiple Spring Data modules on the classpath.
* Added Repository support with multiple Spring Data modules on the classpath.
[[new-in-2-0-0]]
== New in the 2.0 Release
* Upgraded to {data-store-name} 9.0.x.
* Upgraded to Spring Data Commons 2.0.x.RELEASE.
* Upgraded to Spring Framework 5.0.x.RELEASE.
* Reorganized the SDG codebase by better packaging different classes and components by concern.
* Upgraded to {data-store-name} 9.1.1.
* Upgraded to Spring Data Commons 2.0.8.RELEASE.
* Upgraded to Spring Framework 5.0.7.RELEASE.
* Reorganized the SDG codebase by packaging different classes and components by concern.
* Added extensive support for Java 8 types, particularly in the SD Repository abstraction.
* Changed to the Repository interface and abstraction, e.g. IDs are no longer required to be `java.io.Serializable`.
* Set `@EnableEntityDefinedRegions` annotation `ignoreIfExists` attribute to `true` by default.
@@ -168,4 +174,13 @@ Statistics, Mcast, HttpService, Auth, SSL, Logging, System Properties.
* Renamed `@EnableIndexes` to `@EnableIndexing`.
* Introduced a `InterestsBuilder` class to easily and conveniently express Interests in keys and values between client
and server when using JavaConfig.
* Added support for Off-Heap, Redis Adapter, and {data-store-name}'s new Security framework to the Annotation configuration model.
* Added support in the Annotation configuration model for Off-Heap, Redis Adapter,
and {data-store-name}'s new Security framework.
[[new-in-2-1-0]
== New in the 2.1 Release
* Upgraded to {data-store-name} 9.5.1.
* Upgraded to Spring Framework 5.1.0.RELEASE.
* Upgraded to Spring Data Commons 2.1.0.RELEASE.
*

2
src/main/asciidoc/introduction/requirements.adoc
View File

@@ -1,5 +1,5 @@
[[requirements]]
= Requirements
Spring Data for {data-store-name} requires Java 8.0, {spring-framework-website}[Spring Framework] 5
{sdg-name} requires Java 8.0, {spring-framework-website}[Spring Framework] 5
and {x-data-store-website}[{data-store-name}] {data-store-version}.

10
src/main/asciidoc/links.adoc
View File

@@ -1,11 +1,11 @@
[[sgf-links]]
= Useful Links
* http://projects.spring.io/spring-data-gemfire[Spring Data for {data-store-name} Project Page]
* https://github.com/spring-projects/spring-data-gemfire[Spring Data for {data-store-name} source code]
* https://jira.spring.io/browse/SGF[Spring Data for {data-store-name} JIRA]
* http://stackoverflow.com/questions/tagged/spring-data-gemfire[Spring Data for {data-store-name} on StackOverflow]
* http://forum.spring.io/forum/spring-projects/data/gemfire[Archive of the Spring Data for {data-store-name} Forum on Spring IO]
* http://projects.spring.io/spring-data-gemfire[{sdg-name} Project Page]
* https://github.com/spring-projects/spring-data-gemfire[{sdg-name} source code]
* https://jira.spring.io/browse/SGF[{sdg-name} JIRA]
* http://stackoverflow.com/questions/tagged/spring-data-gemfire[{sdg-name} on StackOverflow]
* http://forum.spring.io/forum/spring-projects/data/gemfire[Archive of the {sdg-name} Forum on Spring IO]
* {x-data-store-website}[{data-store-name} Home Page]
* {x-data-store-docs}/getting_started/book_intro.html[{data-store-name} Documentation]
* {apache-geode-website}/community/[Apache Geode Community]

14
src/main/asciidoc/preface.adoc
View File

@@ -1,14 +1,14 @@
= Preface
Spring Data for {data-store-name} focuses on integrating the Spring Framework's powerful, non-invasive programming model
and concepts with {data-store-name} to simplify configuration and development of Java applications when you use {data-store-name}.
{sdg-name} focuses on integrating the Spring Framework's powerful, non-invasive programming model
and concepts with {data-store-name} to simplify configuration and development of Java applications
when using {data-store-name} as you data management solution.
This document assumes you already have a basic understanding of and some familiarity with the core Spring Framework
and {data-store-name} concepts and APIs.
This document assumes you already have a basic understanding of, and some familiarity with, the core Spring Framework
and {data-store-name} concepts.
While every effort has been made to ensure this documentation is comprehensive and complete without errors,
some topics are beyond the scope of this document and may require more explanation (for example, data distribution management
using partitioning with HA while still preserving consistency). Additionally, some typographical errors might have crept in.
If you do spot mistakes or even more serious errors, please bring these issues
to the attention of the Spring Data team by raising an appropriate
https://jira.spring.io/browse/SGF[issue in JIRA].
If you do spot mistakes or even more serious errors, please bring these issues to the attention of the Spring Data team
by raising an appropriate https://jira.spring.io/browse/SGF[issue in JIRA].

1195
src/main/asciidoc/reference/bootstrap-annotations.adoc
View File

File diff suppressed because it is too large Load Diff

60
src/main/asciidoc/reference/bootstrap.adoc
View File

@@ -1,53 +1,54 @@
[[bootstrap]]
= Bootstrapping {data-store-name} with the Spring container
Spring Data for {data-store-name} provides full configuration and initialization of the {data-store-name} In-Memory Data Grid (IMDG)
using the Spring IoC container. The framework includes several classes to help simplify the configuration of {data-store-name} components,
including: Caches, Regions, Indexes, DiskStores, Functions, WAN Gateways, persistence backup, and several other Distributed System components
to support a variety of application use cases with minimal effort.
{sdg-name} provides full configuration and initialization of the {data-store-name} In-Memory Data Grid (IMDG)
using the Spring IoC container. The framework includes several classes to help simplify the configuration of
{data-store-name} components, including: Caches, Regions, Indexes, DiskStores, Functions, WAN Gateways,
persistence backup, and several other Distributed System components to support a variety of application use cases
with minimal effort.
NOTE: This section assumes basic familiarity with {data-store-name}. For more information,
see the {data-store-name} {x-data-store-docs}/gemfire/about_gemfire.html[product documentation].
NOTE: This section assumes basic familiarity with {data-store-name}. For more information, see the {data-store-name}
{x-data-store-docs}/gemfire/about_gemfire.html[product documentation].
[[bootstrap:namespace:xml]]
== Advantages of using Spring over {data-store-name} `cache.xml`
Spring Data for {data-store-name}'s XML namespace supports full configuration of the {data-store-name} In-Memory Data Grid (IMDG).
The XML namespace is one of two ways to configure {data-store-name} in a Spring context in order to properly
manage {data-store-name}'s lifecycle inside the Spring container. The other way to configure Pivotal Gemfire
in a Spring context is by using <<bootstrap-annotation-config,annotation-based configuration>>. While support for
{data-store-name}'s native `cache.xml` persists for legacy reasons, {data-store-name} application developers
{sdg-name}'s XML namespace supports full configuration of the {data-store-name} In-Memory Data Grid (IMDG).
The XML namespace is one of two ways to configure {data-store-name} in a Spring context in order to properly manage
{data-store-name}'s lifecycle inside the Spring container. The other way to configure {data-store-name} in a Spring
context is by using <<bootstrap-annotation-config,annotation-based configuration>>.
While support for {data-store-name}'s native `cache.xml` persists for legacy reasons, {data-store-name} application developers
who use XML configuration are encouraged to do everything in Spring XML to take advantage of the many wonderful things
Spring has to offer, such as modular XML configuration, property placeholders and overrides,
SpEL ({spring-framework-docs}/core.html#expressions[Spring Expression Language]), and environment profiles.
Behind the XML namespace, Spring Data for {data-store-name} makes extensive use of Spring's `FactoryBean` pattern
to simplify the creation, configuration, and initialization of {data-store-name} components.
Behind the XML namespace, {sdg-name} makes extensive use of Spring's `FactoryBean` pattern to simplify the creation,
configuration, and initialization of {data-store-name} components.
{data-store-name} provides several callback interfaces, such as `CacheListener`, `CacheLoader`, and `CacheWriter`,
that let developers add custom event handlers. Using Spring's IoC container, you can configure these callbacks
as normal Spring beans and inject them into {data-store-name} components. This is a significant improvement
over native `cache.xml`, which provides relatively limited configuration options and requires callbacks to implement
as normal Spring beans and inject them into {data-store-name} components. This is a significant improvement over
native `cache.xml`, which provides relatively limited configuration options and requires callbacks to implement
{data-store-name}'s `Declarable` interface (see <<apis:declarable>> to see how you can still use `Declarables`
within Spring's IoC/DI container).
within Spring's container).
In addition, IDEs, such as the Spring Tool Suite (STS), provide excellent support for Spring XML namespaces,
including code completion, pop-up annotations, and real-time validation.
including code completion, pop-up annotations, and real time validation.
[[bootstrap:namespace]]
== Using the Core Namespace
To simplify configuration, Spring Data for {data-store-name} provides a dedicated XML namespace for configuring
core {data-store-name} components. It is possible to configure beans directly by using Spring's standard
`<bean>` definition. However, all bean properties are exposed through the XML namespace, so there is little benefit
to using raw bean definitions.
To simplify configuration, {sdg-name} provides a dedicated XML namespace for configuring core {data-store-name}
components. It is possible to configure beans directly by using Spring's standard `<bean>` definition. However,
all bean properties are exposed through the XML namespace, so there is little benefit to using raw bean definitions.
NOTE: For more information about XML Schema-based configuration in Spring, see the
{spring-framework-docs}/core.html#appendix[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 Spring Data for {data-store-name} Repositories.
on how to configure {sdg-name} Repositories.
To use the Spring Data for {data-store-name} XML namespace, declare it in your Spring XML configuration meta-data,
To use the {sdg-name} XML namespace, declare it in your Spring XML configuration meta-data,
as the following example shows:
[source,xml]
@@ -68,18 +69,17 @@ as the following example shows:
</beans>
----
<1> Spring Data for {data-store-name} XML namespace prefix. Any name works, but, throughout this reference documentation,
`gfe` is used.
<1> {sdg-name} XML namespace prefix. Any name works, but, throughout this reference documentation, `gfe` is used.
<2> The XML namespace prefix is mapped to the URI.
<3> The XML namespace URI location. Note that, even though the location points to an external address (which does exist
and is valid), Spring resolves the schema locally, as it is included in the Spring Data for {data-store-name} library.
and is valid), Spring resolves the schema locally, as it is included in the {sdg-name} library.
<4> Example declaration using the XML namespace with the `gfe` prefix.
[NOTE]
====
You can change the default namespace from `beans` to `gfe`. This is useful for XML configuration
composed mainly of {data-store-name} components, as it avoids declaring the prefix. To do so, swap the namespace
prefix declaration shown earlier, as the following example shows:
You can change the default namespace from `beans` to `gfe`. This is useful for XML configuration composed mainly of
{data-store-name} components, as it avoids declaring the prefix. To do so, swap the namespace prefix declaration
shown earlier, as the following example shows:
[source,xml]
[subs="verbatim,attributes"]
@@ -99,7 +99,7 @@ prefix declaration shown earlier, as the following example shows:
</beans>
----
<1> The default namespace declaration for this XML document points to the Spring Data for {data-store-name} XML namespace.
<1> The default namespace declaration for this XML document points to the {sdg-name} XML namespace.
<2> The `beans` namespace prefix declaration for Spring's raw bean definitions.
<3> Bean declaration using the `beans` namespace. Notice the prefix.
<4> Bean declaration using the `gfe` namespace. Notice the lack of prefix since `gfe` is the default namespace.

218
src/main/asciidoc/reference/cache.adoc
View File

@@ -1,45 +1,45 @@
[[bootstrap:cache]]
= Configuring a Cache
To use {data-store-name}, you need to either create a new `Cache` or connect to an existing one.
With the current version of {data-store-name}, you can have only one open Cache per VM (more strictly, per `ClassLoader`).
In most cases, the `Cache` should only be created once.
To use {data-store-name}, you need to either create a new cache or connect to an existing one. With the current version
of {data-store-name}, you can have only one open cache per VM (more strictly speaking, per `ClassLoader`). In most cases,
the cache should only be created once.
NOTE: This section describes the creation and configuration of a peer cache member, appropriate in
peer-to-peer (P2P) topologies and cache servers. A cache member can also be used in stand-alone applications
and integration tests. However, in most typical production systems, most application processes act as
cache clients, creating a `ClientCache` instance instead. This is described in the <<bootstrap:cache:client>>
and <<bootstrap:region:client>> sections.
NOTE: This section describes the creation and configuration of a peer `Cache` member, appropriate in peer-to-peer (P2P)
topologies and cache servers. A `Cache` member can also be used in stand-alone applications and integration tests.
However, in typical production systems, most application processes act as cache clients, creating a `ClientCache`
instance instead. This is described in the <<bootstrap:cache:client>> and <<bootstrap:region:client>> sections.
A peer cache with default configuration can be created with the following simple declaration:
A peer `Cache` with default configuration can be created with the following simple declaration:
[source,xml]
----
<gfe:cache/>
----
During Spring container initialization, any application context containing this cache definition registers
a `CacheFactoryBean` that creates a Spring bean named `gemfireCache`, which references a {data-store-name} `Cache` instance.
This bean refers to either an existing cache or, if one does not already exist, a newly created one. Since no
additional properties were specified, a newly created cache applies the default cache configuration.
During Spring container initialization, any `ApplicationContext` containing this cache definition registers a
`CacheFactoryBean` that creates a Spring bean named `gemfireCache`, which references a {data-store-name} `Cache` instance.
This bean refers to either an existing `Cache` or, if one does not already exist, a newly created one. Since no
additional properties were specified, a newly created `Cache` applies the default cache configuration.
All Spring Data for {data-store-name} components that depend on the cache respect this naming convention, so you need not
explicitly declare the cache dependency. If you prefer, you can make the dependency explicit by using the `cache-ref`
attribute provided by various SDG XML namespace elements. Also, you can override the cache's bean name using
the `id` attribute, as follows:
All {sdg-name} components that depend on the `Cache` respect this naming convention, so you need not explicitly declare
the `Cache` dependency. If you prefer, you can make the dependency explicit by using the `cache-ref` attribute provided
by various {sdg-acronym} XML namespace elements. Also, you can override the cache's bean name using the `id` attribute,
as follows:
[source,xml]
----
<gfe:cache id="myCache"/>
----
A {data-store-name} `Cache` can be fully configured using Spring. However, {data-store-name}'s native XML configuration file, `cache.xml`,
is also supported. For situations where the {data-store-name} cache needs to be configured natively, you can provide a reference
to the {data-store-name} XML configuration file by using the `cache-xml-location` attribute, as follows:
A {data-store-name} `Cache` can be fully configured using Spring. However, {data-store-name}'s native XML configuration
file, `cache.xml`, is also supported. For situations where the {data-store-name} cache needs to be configured natively,
you can provide a reference to the {data-store-name} XML configuration file by using the `cache-xml-location` attribute,
as follows:
[source,xml]
----
<gfe:cache id="cacheConfiguredWithNativeXml" cache-xml-location="classpath:cache.xml"/>
<gfe:cache id="cacheConfiguredWithNativeCacheXml" cache-xml-location="classpath:cache.xml"/>
----
In this example, if a cache needs to be created, it uses a file named `cache.xml` located in the classpath root
@@ -50,11 +50,11 @@ abstraction to locate the file. The `Resource` abstraction lets various search p
or the prefix specified (if any) in the resource location.
In addition to referencing an external XML configuration file, you can also specify {data-store-name} System
{x-data-store-docs}/reference/topics/gemfire_properties.html[properties]
that use any of Spring's `Properties` support features.
{x-data-store-docs}/reference/topics/gemfire_properties.html[properties] that use any of Spring's `Properties`
support features.
For example, you can use the `properties` element defined in the `util` namespace to define `Properties`
directly or load properties from a properties file, as follows:
For example, you can use the `properties` element defined in the `util` namespace to define `Properties` directly
or load properties from a properties file, as follows:
[source,xml]
[subs="verbatim,attributes"]
@@ -77,8 +77,8 @@ directly or load properties from a properties file, as follows:
</beans>
----
Using a properties file is recommended for externalizing environment-specific settings outside
the application configuration.
Using a properties file is recommended for externalizing environment-specific settings
outside the application configuration.
NOTE: Cache settings apply only when a new cache needs to be created. If an open cache already exists in the VM,
these settings are ignored.
@@ -155,8 +155,8 @@ The `TransactionWriter` is a callback that can veto a transaction.
<7> Example of a `GatewayConflictResolver` callback declaration using a bean reference. The referenced bean
must implement {x-data-store-javadoc}/org/apache/geode/cache/util/GatewayConflictResolver.html
[GatewayConflictResolver].
A `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.
A `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.
<8> Enables {data-store-name}'s {x-data-store-docs}/developing/region_options/dynamic_region_creation.html[DynamicRegionFactory],
which provides a distributed Region creation service.
<9> Declares a JNDI binding to enlist an external DataSource in a {data-store-name} transaction.
@@ -166,48 +166,50 @@ which provides a distributed Region creation service.
The preceding example includes a number of attributes related to {data-store-name}'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 `PdxSerializer`, which is specified by setting the `pdx-serializer` attribute. {data-store-name} provides
an implementing class (`org.apache.geode.pdx.ReflectionBasedAutoSerializer`) that uses Java Reflection. 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 `PdxSerializer` interface.
is enabled by registering a `PdxSerializer`, which is specified by setting the `pdx-serializer` attribute.
More information on serialization support can be found in <<serialization>>
{data-store-name} provides an implementing class (`org.apache.geode.pdx.ReflectionBasedAutoSerializer`) that uses
Java Reflection. 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 `PdxSerializer` interface.
More information on serialization support can be found in <<serialization>>.
[[boostrap:cache:auto-reconnect]]
=== Enabling Auto-reconnect
You should be careful when setting the `<gfe:cache enable-auto-reconnect="[true|false*]>` attribute to `true`.
Generally, 'auto-reconnect' should only be enabled in cases where Spring Data for {data-store-name}'s XML namespace is used to
configure and bootstrap a new, non-application {data-store-name} Server to add to a cluster. In other words, 'auto-reconnect'
should not be enabled when Spring Data for {data-store-name} is used to develop and build a {data-store-name} application that also happens
to be a peer cache member of the {data-store-name} cluster.
Generally, 'auto-reconnect' should only be enabled in cases where {sdg-name}'s XML namespace is used to configure
and bootstrap a new, non-application {data-store-name} server added to a cluster. In other words, 'auto-reconnect'
should not be enabled when {sdg-name} is used to develop and build a {data-store-name} application that also happens
to be a peer `Cache` member of the {data-store-name} cluster.
The main reason for this restriction is that most {data-store-name} applications use references to the {data-store-name} cache or Regions in order to
perform data access operations. These references are "`injected`" by the Spring container into application components
(such as DAOs or Repositories) for use by the application. When a peer member is forcefully disconnected from the rest
of the cluster, presumably because the peer member has become unresponsive or a network partition separates one or more
peer members into a group too small to function as an independent distributed system, the peer member shuts down
and all {data-store-name} component references (caches, regions, and others) become invalid.
The main reason for this restriction is that most {data-store-name} applications use references to the {data-store-name}
`Cache` or Regions in order to perform data access operations. These references are "`injected`" by the Spring container
into application components (such as Repositories) for use by the application. When a peer member is forcefully
disconnected from the rest of the cluster, presumably because the peer member has become unresponsive or a
network partition separates one or more peer members into a group too small to function as an independent
distributed system, the peer member shuts down and all {data-store-name} component references (caches, Regions,
and others) become invalid.
Essentially, the current forced-disconnect processing logic in each peer member dismantles the system from the ground up.
Essentially, the current forced disconnect processing logic in each peer member dismantles the system from the ground up.
The JGroups stack shuts down, the distributed system is put in a shutdown state and, finally, the cache is closed.
Effectively, all memory references become stale and are lost.
After being disconnected from the distributed system, a peer member enters a "`reconnecting`" state and periodically
attempts to rejoin the distributed system. If the peer member succeeds in reconnecting, the member rebuilds
its "`view`" of the distributed system from existing members and receives a new distributed system ID. Additionally, all
caches, regions, and other {data-store-name} components are reconstructed. Therefore, all old references, which may have been
attempts to rejoin the distributed system. If the peer member succeeds in reconnecting, the member rebuilds its "`view`"
of the distributed system from existing members and receives a new distributed system ID. Additionally, all caches,
Regions, and other {data-store-name} components are reconstructed. Therefore, all old references, which may have been
injected into application by the Spring container, are now stale and no longer valid.
{data-store-name} makes no guarantee (even when using the {data-store-name} public Java API) that application cache, region, or other
component references are automatically refreshed by the reconnect operation. As such, {data-store-name} applications
must take care to refresh their own references.
{data-store-name} makes no guarantee (even when using the {data-store-name} public Java API) that application cache,
Regions, or other component references are automatically refreshed by the reconnect operation. As such, {data-store-name}
applications must take care to refresh their own references.
Unfortunately, there is no way to be notified of a disconnect event and, subsequently, a reconnect event.
If that were the case, you would have a clean way to know when to call
`ConfigurableApplicationContext.refresh()`, if it were even applicable for an application to do so, which is why
this "`feature`" of {data-store-name} is not recommended for peer cache {data-store-name} applications.
Unfortunately, there is no way to be notified of a disconnect event and, subsequently, a reconnect event either.
If that were the case, you would have a clean way to know when to call `ConfigurableApplicationContext.refresh()`,
if it were even applicable for an application to do so, which is why this "`feature`" of {data-store-name} is not
recommended for peer `Cache` applications.
For more information about 'auto-reconnect', see {data-store-name}'s
{x-data-store-docs}/managing/autoreconnect/member-reconnect.html[product documentation].
@@ -216,13 +218,13 @@ For more information about 'auto-reconnect', see {data-store-name}'s
=== Using Cluster-based Configuration
{data-store-name}'s Cluster Configuration Service is a convenient way for any peer member joining the cluster to get
a "`consistent view`" of the cluster by using the shared, persistent configuration maintained by a locator.
Using the cluster-based Configuration ensures the peer member's configuration is compatible with
the {data-store-name} Distributed System when the member joins.
a "`consistent view`" of the cluster by using the shared, persistent configuration maintained by a Locator.
Using the cluster-based configuration ensures the peer member's configuration is compatible with the {data-store-name}
Distributed System when the member joins.
This feature of Spring Data for {data-store-name} (setting the `use-cluster-configuration` attribute to `true`) works in the same way
as the `cache-xml-location` attribute, except the source of the {data-store-name} configuration meta-data comes from the network
through a locator, as opposed to a native `cache.xml` file residing in the local file system.
This feature of {sdg-name} (setting the `use-cluster-configuration` attribute to `true`) works in the same way
as the `cache-xml-location` attribute, except the source of the {data-store-name} configuration meta-data comes
from the network through a Locator, as opposed to a native `cache.xml` file residing in the local file system.
All {data-store-name} native configuration metadata, whether from `cache.xml` or from the Cluster Configuration Service,
gets applied before any Spring (XML) configuration metadata. As a result, Spring's config serves to "`augment`" the
@@ -235,8 +237,8 @@ Again, to enable this feature, specify the following in the Spring XML config:
<gfe:cache use-cluster-configuration="true"/>
----
NOTE: While certain {data-store-name} tools, such as `Gfsh`, have their actions "`recorded`" when schema-like changes are made
(for example, `gfsh>create region --name=Example --type=PARTITION`), Spring Data for {data-store-name}'s configuration metadata
NOTE: While certain {data-store-name} tools, such as _Gfsh_, have their actions "`recorded`" when schema-like changes
are made (for example, `gfsh>create region --name=Example --type=PARTITION`), {sdg-name}'s configuration metadata
is not recorded. The same is true when using {data-store-name}'s public Java API directly. It, too, is not recorded.
For more information on {data-store-name}'s Cluster Configuration Service, see the
@@ -245,7 +247,7 @@ For more information on {data-store-name}'s Cluster Configuration Service, see t
[[bootstrap:cache:server]]
== Configuring a {data-store-name} CacheServer
Spring Data for {data-store-name} includes dedicated support for configuring a
{sdg-name} includes dedicated support for configuring a
{x-data-store-javadoc}/org/apache/geode/cache/server/CacheServer.html[CacheServer],
allowing complete configuration through the Spring container, as the following example shows:
@@ -290,22 +292,21 @@ reads one or more properties files and then replaces property placeholders with
change values without having to touch the main application configuration. Spring also provides
http://docs.spring.io/spring/docs/current/spring-framework-reference/htmlsingle/#expressions[SpEL]
and an http://docs.spring.io/spring/docs/current/spring-framework-reference/htmlsingle/#beans-environment[environment abstraction]
to support externalization of environment-specific properties from the main codebase, easing deployment
across multiple machines.
to support externalization of environment-specific properties from the main codebase, easing deployment across multiple machines.
NOTE: To avoid initialization problems, the `CacheServer` started by Spring Data for {data-store-name} starts *after*
the Spring container has been fully initialized. Doing so lets potential regions, listeners, writers or instantiators that are
defined declaratively be fully initialized and registered before the server starts accepting connections.
Keep this in mind when programmatically configuring these elements, as the server might start after your components
and thus not be seen by the clients connecting right away.
NOTE: To avoid initialization problems, the `CacheServer` started by {sdg-name} starts *after* the Spring container
has been fully initialized. Doing so lets potential Regions, listeners, writers or instantiators that are defined
declaratively be fully initialized and registered before the server starts accepting connections. Keep this in mind
when programmatically configuring these elements, as the server might start after your components and thus not be seen
by the clients connecting right away.
[[bootstrap:cache:client]]
== Configuring a {data-store-name} ClientCache
In addition to defining a {data-store-name} peer {x-data-store-javadoc}/org/apache/geode/cache/Cache.html[cache],
Spring Data for {data-store-name} also supports the definition of a {data-store-name} {x-data-store-javadoc}/org/apache/geode/cache/client/ClientCache.html[`ClientCache`]
in a Spring context. A `ClientCache` definition is similar in configuration and use to
the {data-store-name} peer <<bootstrap:cache,cache>> and is supported by the `org.springframework.data.gemfire.client.ClientCacheFactoryBean`.
In addition to defining a {data-store-name} peer {x-data-store-javadoc}/org/apache/geode/cache/Cache.html[`Cache`],
{sdg-name} also supports the definition of a {data-store-name} {x-data-store-javadoc}/org/apache/geode/cache/client/ClientCache.html[`ClientCache`]
in a Spring container. A `ClientCache` definition is similar in configuration and use to the {data-store-name} peer <<bootstrap:cache,Cache>>
and is supported by the `org.springframework.data.gemfire.client.ClientCacheFactoryBean`.
The simplest definition of a {data-store-name} cache client using default configuration follows:
@@ -316,21 +317,21 @@ The simplest definition of a {data-store-name} cache client using default config
</beans>
----
`client-cache` supports many of the same options as the <<bootstrap:cache:advanced,cache>> element. However, as opposed
to a full-fledged peer cache member, a cache client connects to a remote cache server through a pool. By default,
a pool is created to connect to a server running on `localhost` and listening to port `40404`. The default pool is used
by all client regions unless the region is configured to use a specific pool.
`client-cache` supports many of the same options as the <<bootstrap:cache:advanced,Cache>> element. However, as opposed
to a full-fledged peer `Cache` member, a cache client connects to a remote cache server through a Pool. By default,
a Pool is created to connect to a server running on `localhost` and listening to port `40404`. The default Pool is used
by all client Regions unless the Region is configured to use a specific Pool.
Pools can be defined with the `pool` element. This client-side pool can be used to configure connectivity directly to
a server for individual entities or for the entire cache through one or more locators.
Pools can be defined with the `pool` element. This client-side Pool can be used to configure connectivity directly to
a server for individual entities or for the entire cache through one or more Locators.
For example, to customize the default pool used by the `client-cache`, the developer needs to define a Pool and wire it
For example, to customize the default Pool used by the `client-cache`, the developer needs to define a Pool and wire it
to the cache definition, as the following example shows:
[source,xml]
----
<beans>
<gfe:client-cache id="my-cache" pool-name="myPool"/>
<gfe:client-cache id="myCache" pool-name="myPool"/>
<gfe:pool id="myPool" subscription-enabled="true">
<gfe:locator host="${gemfire.locator.host}" port="${gemfire.locator.port}"/>
@@ -344,9 +345,10 @@ initialization includes a call to {x-data-store-javadoc}/org/apache/geode/cache/
<<bootstrap:region:client>> covers client-side configuration in more detail.
[[bootstrap:cache:client:pool]]
=== {data-store-name}'s DEFAULT Pool and Spring Data for {data-store-name} Pool Definitions
=== {data-store-name}'s DEFAULT Pool and {sdg-name} Pool Definitions
If a {data-store-name} `ClientCache` is local-only, then no Pool definition is required. For instance, you can define the following:
If a {data-store-name} `ClientCache` is local-only, then no Pool definition is required. For instance, you can define
the following:
[source,xml]
----
@@ -355,15 +357,15 @@ If a {data-store-name} `ClientCache` is local-only, then no Pool definition is r
<gfe:client-region id="Example" shortcut="LOCAL"/>
----
In this case, the `Example` Region is `LOCAL` and no data is distributed between the client and a server. Therefore,
no pool is necessary. This is true for any client-side, local-only region, as defined by the {data-store-name}'s
In this case, the "`Example`" Region is `LOCAL` and no data is distributed between the client and a server. Therefore,
no Pool is necessary. This is true for any client-side, local-only Region, as defined by the {data-store-name}'s
{x-data-store-javadoc}/org/apache/geode/cache/client/ClientRegionShortcut.html[`ClientRegionShortcut`]
(all `LOCAL_*` shortcuts).
However, if a client Region is a (caching) proxy to a server-side Region, a pool is required. In that case, there are several
ways to define and use a Pool.
However, if a client Region is a (caching) proxy to a server-side Region, a Pool is required. In that case,
there are several ways to define and use a Pool.
When a client cache, a pool, and a proxy-based region are all defined but not explicitly identified, Spring Data for {data-store-name}
When a `ClientCache`, a Pool, and a proxy-based Region are all defined but not explicitly identified, {sdg-name}
resolves the references automatically, as the following example shows:
[source,xml]
@@ -377,11 +379,12 @@ resolves the references automatically, as the following example shows:
<gfe:client-region id="Example" shortcut="PROXY"/>
----
In the preceding example, the client cache is identified as `gemfireCache`, the Pool as `gemfirePool`, and the client region
as `Example`. However, the client cache initializes {data-store-name}'s `DEFAULT` pool from `gemfirePool`, and the client Region
uses the `gemfirePool` when distributing data between the client and the server.
In the preceding example, the `ClientCache` is identified as `gemfireCache`, the Pool as `gemfirePool`,
and the client Region as "`Example`". However, the `ClientCache` initializes {data-store-name}'s `DEFAULT` Pool
from `gemfirePool`, and the client Region uses the `gemfirePool` when distributing data between the client
and the server.
Basically, Spring Data for {data-store-name} resolves the preceding configuration to the following:
Basically, {sdg-name} resolves the preceding configuration to the following:
[source,xml]
----
@@ -394,9 +397,9 @@ Basically, Spring Data for {data-store-name} resolves the preceding configuratio
<gfe:client-region id="Example" cache-ref="gemfireCache" pool-name="gemfirePool" shortcut="PROXY"/>
----
{data-store-name} still creates a pool called `DEFAULT`. Spring Data for {data-store-name} causes the `DEFAULT` pool to be
initialized from the `gemfirePool`. Doing so is useful in situations where multiple pools are defined and client regions
are using separate Pools.
{data-store-name} still creates a Pool called `DEFAULT`. {sdg-name} causes the `DEFAULT` Pool to be initialized
from the `gemfirePool`. Doing so is useful in situations where multiple Pools are defined and client Regions
are using separate Pools, or do not declare a Pool at all.
Consider the following:
@@ -419,18 +422,19 @@ Consider the following:
<gfe:client-region id="YetAnotherExample" shortcut="LOCAL"/>
----
In this setup, the {data-store-name} client cache's `DEFAULT` pool is initialized from `locatorPool`, as specified by the
`pool-name` attribute. There is no Spring Data for {data-store-name}-defined `gemfirePool`, since both pools were explicitly
identified (named) -- `locatorPool` and `serverPool`, respectively.
In this setup, the {data-store-name} `client-cache` `DEFAULT` pool is initialized from `locatorPool`,
as specified by the `pool-name` attribute. There is no {sdg-name}-defined `gemfirePool`, since both Pools
were explicitly identified (named) -- `locatorPool` and `serverPool`, respectively.
The `Example` region explicitly refers to and exclusively uses the `serverPool`. The `AnotherExample` region uses
{data-store-name}'s `DEFAULT` pool, which was configured from the `locatorPool` based on the client cache bean definition's
`pool-name` attribute.
The "`Example`" Region explicitly refers to and exclusively uses the `serverPool`. The `AnotherExample` Region uses
{data-store-name}'s `DEFAULT` Pool, which, again, was configured from the `locatorPool` based on the client cache
bean definition's `pool-name` attribute.
Finally, the `YetAnotherExample` egion does not use a Pool, because it is `LOCAL`.
Finally, the `YetAnotherExample` Region does not use a Pool, because it is `LOCAL`.
NOTE: The `AnotherExample` region would first look for a pool bean named `gemfirePool`, but that would require
the definition of an anonymous Pool bean (that is, `<gfe:pool/>`) or a pool bean explicitly named `gemfirePool`
NOTE: The `AnotherExample` Region would first look for a Pool bean named `gemfirePool`, but that would require
the definition of an anonymous Pool bean (that is, `<gfe:pool/>`) or a Pool bean explicitly named `gemfirePool`
(for example, `<gfe:pool id="gemfirePool"/>`).
NOTE: If we either changed the name of `locatorPool` to `gemfirePool` or made the pool bean definition be anonymous, it would have the same effect as the preceding configuration.
NOTE: If we either changed the name of `locatorPool` to `gemfirePool` or made the Pool bean definition be anonymous,
it would have the same effect as the preceding configuration.

12
src/main/asciidoc/reference/cq-container.adoc
View File

@@ -5,13 +5,13 @@ A powerful functionality offered by {data-store-name} is
{x-data-store-docs}/developing/continuous_querying/chapter_overview.html[Continuous Query] (or CQ).
In short, CQ allows a developer to create and register an OQL query, and then automatically be notified when new data
that gets added to {data-store-name} matches the query predicate. Spring Data for {data-store-name} provides dedicated
that gets added to {data-store-name} matches the query predicate. {sdg-name} 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 the _Spring Framework_; in fact, users familiar with
the JMS support in Spring, should feel right at home.
Basically Spring Data for {data-store-name} allows methods on POJOs to become end-points for CQ. Simply define the query
and indicate the method that should be called to be notified when there is a match. Spring Data for {data-store-name} takes care
Basically {sdg-name} allows methods on POJOs to become end-points for CQ. Simply define the query
and indicate the method that should be called to be notified when there is a match. {sdg-name} takes care
of the rest. This is very similar to Java EE's message-driven bean style, but without any requirement for base class
or interface implementations, based on {data-store-name}.
@@ -23,7 +23,7 @@ for more information.
[[apis:continuous-query:container]]
== Continuous Query Listener Container
Spring Data for {data-store-name} simplifies creation, registration, life-cycle and dispatch of CQ events by taking care of
{sdg-name} simplifies creation, registration, life-cycle and dispatch of CQ events by taking care of
the infrastructure around CQ with the use of SDG's `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 provided in the _Spring Framework_ with its Message-driven POJOs (MDPs).
@@ -46,7 +46,7 @@ to take advantage of its runtime.
[[apis:continuous-query:adapter]]
== The `ContinuousQueryListener` and `ContinuousQueryListenerAdapter`
The `ContinuousQueryListenerAdapter` class is the final component in Spring Data for {data-store-name} CQ support. In a nutshell,
The `ContinuousQueryListenerAdapter` class is the final component in {sdg-name} CQ support. In a nutshell,
class allows you to expose almost *any* implementing class as an EDP with minimal constraints.
`ContinuousQueryListenerAdapter` implements the `ContinuousQueryListener` interface, a simple listener interface
similar to {data-store-name}'s {x-data-store-javadoc}/org/apache/geode/cache/query/CqListener.html[CqListener].
@@ -117,7 +117,7 @@ reference and the actual query definition are required. It's possible, however,
the resulting Continuous Query (useful for monitoring) but also the name of the method (the default is `handleEvent`).
The specified method can have various argument types, the `EventDelegate` interface lists the allowed types.
The example above uses the Spring Data for {data-store-name} namespace to declare the event listener container
The example above uses the {sdg-name} namespace to declare the event listener container
and automatically register the listeners. The full blown, *beans* definition is displayed below:
[source,xml]

26
src/main/asciidoc/reference/data-access.adoc
View File

@@ -1,18 +1,19 @@
[[data-access]]
= Using the Data Access Namespace
In addition to the core XML namespace (`gfe`), Spring Data for {data-store-name} provides a data access XML namespace (`gfe-data`),
which is primarily intended to simplify the development of {data-store-name} client applications. This namespace currently contains
support for {data-store-name} <<gemfire-repositories, Repositories>> and function <<function-execution, execution>>,
as well as a `<datasource>` tag that offers a convenient way to connect to a {data-store-name} cluster.
In addition to the core XML namespace (`gfe`), {sdg-name} provides a data access XML namespace (`gfe-data`),
which is primarily intended to simplify the development of {data-store-name} client applications. This namespace
currently contains support for {data-store-name} <<gemfire-repositories, Repositories>> and Function
<<function-execution, execution>>, as well as a `<datasource>` tag that offers a convenient way to connect to
a {data-store-name} cluster.
[[data-access:datasource]]
== An Easy Way to Connect to {data-store-name}
For many applications, a basic connection to a {data-store-name} data grid using default values is sufficient.
Spring Data for {data-store-name}'s `<datasource>` tag provides a simple way to access data. The data source creates
a `ClientCache` and connection `Pool`. In addition, it queries the cluster servers for all existing root Regions
and creates an (empty) client Region proxy for each one.
{sdg-name}'s `<datasource>` tag provides a simple way to access data. The data source creates a `ClientCache`
and connection `Pool`. In addition, it queries the cluster servers for all existing root Regions and creates
an (empty) client Region proxy for each one.
[source,xml]
----
@@ -22,12 +23,13 @@ and creates an (empty) client Region proxy for each one.
----
The `<datasource>` tag is syntactically similar to `<gfe:pool>`. It may be configured with one or more nested `locator`
or `server` tags to connect to an existing data grid. Additionally, all attributes available to configure a pool
are supported. This configuration automatically creates client region beans for each region defined on
cluster members connected to the locator, so they can be seamlessly referenced by Spring Data mapping annotations
(`GemfireTemplate`) and wired into application classes.
or `server` elements to connect to an existing data grid. Additionally, all attributes available to configure a Pool
are supported. This configuration automatically creates client Region beans for each Region defined on cluster members
connected to the Locator, so they can be seamlessly referenced by Spring Data mapping annotations (`GemfireTemplate`)
and autowired into application classes.
Of course, you can explicitly configure client regions. For example, if you want to cache data in local memory, as the following example shows:
Of course, you can explicitly configure client Regions. For example, if you want to cache data in local memory,
as the following example shows:
[source,xml]
----

22
src/main/asciidoc/reference/data.adoc
View File

@@ -8,7 +8,7 @@ This chapter also covers support for dependency injection of {data-store-name} m
[[apis:template]]
== GemfireTemplate
As with many other high-level abstractions provided by Spring, Spring Data for {data-store-name} provides a *template*
As with many other high-level abstractions provided by Spring, {sdg-name} provides a *template*
to simplify {data-store-name} data access operations. The class provides several methods containing common Region operations,
but also provides the capability to *execute* code against native {data-store-name} APIs without having to deal with
{data-store-name} checked exceptions by using a `GemfireCallback`.
@@ -79,7 +79,7 @@ about _Spring's Transaction Management_ infrastructure as it offers a consistent
transparently across multiple APIs and can be configured either programmatically or declaratively
(the most popular choice).
For {data-store-name}, Spring Data for {data-store-name} provides a dedicated, per-cache, `PlatformTransactionManager` that,
For {data-store-name}, {sdg-name} provides a dedicated, per-cache, `PlatformTransactionManager` that,
once declared, allows Region operations to be executed atomically through Spring:
[source,xml]
@@ -88,7 +88,7 @@ once declared, allows Region operations to be executed atomically through Spring
----
NOTE: The example above can be simplified even further by eliminating the `cache-ref` attribute if the {data-store-name} cache
is defined under the default name, `gemfireCache`. As with the other Spring Data for {data-store-name} namespace elements,
is defined under the default name, `gemfireCache`. As with the other {sdg-name} namespace elements,
if the cache bean name is not configured, the aforementioned naming convention will be used.
Additionally, the transaction manager name is "`gemfireTransactionManager`" if not explicitly specified.
@@ -136,7 +136,7 @@ NOTE: #1 above is independent of your Spring [Boot] and/or [Data for {data-store
and must be completed successfully.
2) Referring to Step 5 in {data-store-name}'s http://gemfire90.docs.pivotal.io/geode/developing/transactions/JTA_transactions.html#concept_csy_vfb_wk[documentation],
Spring Data for {data-store-name}'s Annotation support will attempt to set the `GemFireCache`, {x-data-store-javadoc}/org/apache/geode/cache/GemFireCache.html#setCopyOnRead-boolean-[`copyOnRead`]
{sdg-name}'s Annotation support will attempt to set the `GemFireCache`, {x-data-store-javadoc}/org/apache/geode/cache/GemFireCache.html#setCopyOnRead-boolean-[`copyOnRead`]
property for you when using the `@EnableGemFireAsLastResource` annotation.
However, if SDG's auto-configuration is unsuccessful then you must explicitly set the `copy-on-read` attribute on the
@@ -194,9 +194,9 @@ really should not be necessary.
3) At this point, you *skip* Steps 6-8 in {data-store-name}'s http://gemfire90.docs.pivotal.io/geode/developing/transactions/JTA_transactions.html#concept_csy_vfb_wk[documentation]
and let _Spring Data Geode_ work its magic. All you need do is annotate your Spring `@Configuration` class
with Spring Data for {data-store-name}'s *new* `@EnableGemFireAsLastResource` annotation and a combination of Spring's
with {sdg-name}'s *new* `@EnableGemFireAsLastResource` annotation and a combination of Spring's
http://docs.spring.io/spring/docs/current/spring-framework-reference/htmlsingle/#transaction[Transaction Management]
infrastructure and Spring Data for {data-store-name}'s `@EnableGemFireAsLastResource` configuration does the trick.
infrastructure and {sdg-name}'s `@EnableGemFireAsLastResource` configuration does the trick.
The configuration looks like this...
@@ -236,14 +236,14 @@ public JtaTransactionManager transactionManager(UserTransaction userTransaction)
----
NOTE: The configuration in section <<apis:transaction-management>> does *not* apply here.
The use of Spring Data for {data-store-name}'s `GemfireTransactionManager` is applicable only in "Local", Cache Transactions,
The use of {sdg-name}'s `GemfireTransactionManager` is applicable only in "Local", Cache Transactions,
*not* "Global", JTA Transactions. Therefore, you do *not* configure the SDG `GemfireTransactionManager` in this case.
You configure Spring's `JtaTransactionManager` as shown above.
For more details on using _Spring's Transaction Management_ with JTA,
see http://docs.spring.io/spring/docs/current/spring-framework-reference/htmlsingle/#transaction-application-server-integration[here].
Effectively, Spring Data for {data-store-name}'s `@EnableGemFireAsLastResource` annotation imports configuration containing 2 Aspect
Effectively, {sdg-name}'s `@EnableGemFireAsLastResource` annotation imports configuration containing 2 Aspect
bean definitions that handles the {data-store-name} `o.a.g.ra.GFConnectionFactory.getConnection()`
and `o.a.g.ra.GFConnection.close()` operations at the appropriate points during the transactional operation.
@@ -284,7 +284,7 @@ class MyTransactionalService ... {
`@Transactional` boundary is entered by your application (i.e. when the `MyTransactionSerivce.someTransactionalServiceMethod()`
is called).
#2 & #3 are handled by Spring Data for {data-store-name}'s new Aspects enabled with the `@EnableGemFireAsLastResource` annotation.
#2 & #3 are handled by {sdg-name}'s new Aspects enabled with the `@EnableGemFireAsLastResource` annotation.
#3 of course is the responsibility of your application.
@@ -359,7 +359,7 @@ As an example of configuring a `Declarable` component using Spring, consider the
</cache-loader>
----
To simplify the task of parsing, converting the parameters and initializing the object, Spring Data for {data-store-name} offers
To simplify the task of parsing, converting the parameters and initializing the object, {sdg-name} offers
a base class (`WiringDeclarableSupport`) that allows {data-store-name} user objects to be wired through a *template* bean definition
or, in case that is missing, perform auto-wiring through the Spring IoC container. To take advantage of this feature,
the user objects need to extend `WiringDeclarableSupport`, which automatically locates the declaring `BeanFactory`
@@ -516,7 +516,7 @@ the `DBLoader` code.
[[apis:spring-cache-abstraction]]
== Support for the Spring Cache Abstraction
Spring Data for {data-store-name} provides an implementation of the Spring
{sdg-name} provides an implementation of the Spring
http://docs.spring.io/spring/docs/current/spring-framework-reference/htmlsingle/#cache[Cache Abstraction]
to position {data-store-name} as a _caching provider_ in Spring's caching infrastructure.

10
src/main/asciidoc/reference/diskstore.adoc
View File

@@ -1,20 +1,22 @@
[[bootstrap:diskstore]]
= Configuring a DiskStore
Spring Data for {data-store-name} supports `DiskStore` configuration and creation through the `disk-store` element, as the following example shows:
{sdg-name} supports `DiskStore` configuration and creation through the `disk-store` element,
as the following example shows:
[source,xml]
----
<gfe:disk-store id="Example" auto-compact="true" max-oplog-size="10"
queue-size="50" time-interval="9999">
queue-size="50" time-interval="9999">
<gfe:disk-dir location="/disk/location/one" max-size="20"/>
<gfe:disk-dir location="/disk/location/two" max-size="20"/>
</gfe:disk-store>
----
`DiskStore` instances are used by regions for file system persistent backup and overflow of evicted entries
`DiskStore` instances are used by Regions for file system persistent backup and overflow of evicted entries
as well as persistent backup for WAN Gateways. Multiple {data-store-name} components may share the same `DiskStore`.
Additionally, multiple file system directories may be defined for a single `DiskStore`, as shown in the preceding example.
Additionally, multiple file system directories may be defined for a single `DiskStore`, as shown in
the preceding example.
See {data-store-name}'s documentation for a complete explanation of
{x-data-store-docs}/developing/storing_data_on_disk/chapter_overview.html[Persistence and Overflow]

308
src/main/asciidoc/reference/function-annotations.adoc
View File

@@ -1,104 +1,105 @@
[[function-annotations]]
= Annotation Support for Function Execution
Spring Data for {data-store-name} includes annotation support to simplify working with {data-store-name}
{x-data-store-docs}/developing/function_exec/chapter_overview.html[function execution].
Under the hood, the {data-store-name} API provides classes to implement and register {data-store-name}
{x-data-store-javadoc}/org/apache/geode/cache/execute/Function.html[functions]
that are deployed on {data-store-name} servers, which may then be invoked by other peer member applications
or remotely from cache clients.
{sdg-name} includes annotation support to simplify working with {data-store-name}
{x-data-store-docs}/developing/function_exec/chapter_overview.html[Function execution].
Functions can execute in parallel, distributed among multiple {data-store-name} servers in the cluster, aggregating results
with the map-reduce pattern that are sent back to the caller. Functions can also be targeted to run on a single server
or region. The {data-store-name} API supports remote execution of functions targeted by using various predefined scopes:
on region, on members (in groups), on servers, and others. The implementation and execution of remote functions,
Under the hood, the {data-store-name} API provides classes to implement and register {data-store-name}
{x-data-store-javadoc}/org/apache/geode/cache/execute/Function.html[Functions] that are deployed on {data-store-name}
servers, which may then be invoked by other peer member applications or remotely from cache clients.
Functions can execute in parallel, distributed among multiple {data-store-name} servers in the cluster, aggregating the
results using the map-reduce pattern and sent back to the caller. Functions can also be targeted to run on a single
server or Region. The {data-store-name} API supports remote execution of Functions targeted by using various predefined
scopes: on Region, on members (in groups), on servers, and others. The implementation and execution of remote Functions,
as with any RPC protocol, requires some boilerplate code.
Spring Data for {data-store-name}, true to Spring's core value proposition, aims to hide the mechanics of remote function execution
and let you focus on core POJO programming and business logic. To this end, Spring Data for {data-store-name} introduces
annotations to declaratively register the public methods of a POJO class as {data-store-name} functions along with the ability to
invoke registered functions (including remotely) by using annotated interfaces.
{sdg-name}, true to Spring's core value proposition, aims to hide the mechanics of remote Function execution and let you
focus on core POJO programming and business logic. To this end, {sdg-name} introduces annotations to declaratively
register the public methods of a POJO class as {data-store-name} Functions along with the ability to invoke registered
Functions (including remotely) by using annotated interfaces.
== Implementation Versus Execution
There are two separate concerns to address implementation and execution.
There are two separate concerns to address: implementation and execution.
The first is function implementation (server-side), which must interact with the
The first is Function implementation (server-side), which must interact with the
{x-data-store-javadoc}/org/apache/geode/cache/execute/FunctionContext.html[`FunctionContext`]
to access the invocation arguments,
{x-data-store-javadoc}/org/apache/geode/cache/execute/ResultSender.html[`ResultsSender`],
and other execution context information. The function implementation typically accesses the cache and regions
{x-data-store-javadoc}/org/apache/geode/cache/execute/ResultSender.html[`ResultsSender`] to send results,
and other execution context information. The Function implementation typically accesses the cache and Regions
and is registered with the
{x-data-store-javadoc}/org/apache/geode/cache/execute/FunctionService.html[`FunctionService`]
under a unique ID.
{x-data-store-javadoc}/org/apache/geode/cache/execute/FunctionService.html[`FunctionService`] under a unique ID.
A cache client application invoking a function does not depend on the implementation. To invoke a function,
A cache client application invoking a Function does not depend on the implementation. To invoke a Function,
the application instantiates an
{x-data-store-javadoc}/org/apache/geode/cache/execute/Execution.html[`Execution`]
providing the function ID, invocation arguments, and the function target, which defines its scope:
region, server, servers, member, or members. If the function produces a result, the invoker uses a
providing the Function ID, invocation arguments, and the Function target, which defines its scope:
Region, server, servers, member, or members. If the Function produces a result, the invoker uses a
{x-data-store-javadoc}/org/apache/geode/cache/execute/ResultCollector.html[`ResultCollector`]
to aggregate and acquire the execution results. In certain cases, a custom `ResultCollector` implementation
is required and may be registered with the `Execution`.
NOTE: 'Client' and 'Server' are used here in the context of function execution, which may have a different meaning
than client and server in {data-store-name}'s client-server topology. While it is common for an application using a `ClientCache`
to invoke a function on one or more {data-store-name} servers in a cluster, it is also possible to execute functions
in a peer-to-peer (P2P) configuration, where the application is a member of the cluster hosting a peer `Cache`.
Keep in mind that a peer member cache application is subject to all the constraints of being a peer member
of the cluster.
NOTE: 'Client' and 'Server' are used here in the context of Function execution, which may have a different meaning
than client and server in {data-store-name}'s client-server topology. While it is common for an application using
a `ClientCache` instance to invoke a Function on one or more {data-store-name} servers in a cluster, it is also
possible to execute Functions in a peer-to-peer (P2P) configuration, where the application is a member of the cluster
hosting a peer `Cache` instance. Keep in mind that a peer member cache application is subject to all the constraints
of being a peer member of the cluster.
[[function-implementation]]
== Implementing a Function
Using {data-store-name} APIs, the `FunctionContext` provides a runtime invocation context that includes the client's
calling arguments and a `ResultSender` implementation to send results back to the client. Additionally,
if the function is executed on a region, the `FunctionContext` is actually an instance of `RegionFunctionContext`,
which provides additional information, such as the target region on which the function was invoked,
any filter (a set of specific keys) associated with the `Execution`, and so on. If the region is a `PARTITION` region,
the function should use the `PartitionRegionHelper` to extract only the local data.
calling arguments and a `ResultSender` implementation to send results back to the client. Additionally, if the Function
is executed on a Region, the `FunctionContext` is actually an instance of `RegionFunctionContext`, which provides
additional information, such as the target Region on which the Function was invoked, any filter (a set of specific keys)
associated with the `Execution`, and so on. If the Region is a `PARTITION` Region, the Function should use
the `PartitionRegionHelper` to extract the local data set.
By using Spring, you can write a simple POJO and use the Spring container to bind one or more of your POJO's
public methods to a function. The signature for a POJO method intended to be used as a function must generally
conform to the client's execution arguments. However, in the case of a region execution, the region data
may also be provided (presumably the data is held in the local partition if the region is a `PARTITION` region).
Additionally, the function may require the filter that was applied, if any. This suggests that the client and server
share a contract for the calling arguments but that the method signature may include additional parameters
to pass values provided by the `FunctionContext`. One possibility is for the client and server to share
a common interface, but this is not strictly required. The only constraint is that the method signature includes
the same sequence of calling arguments with which the function was invoked after the additional parameters
are resolved.
public methods to a Function. The signature for a POJO method intended to be used as a Function must generally conform
to the client's execution arguments. However, in the case of a Region execution, the Region data may also be provided
(presumably the data is held in the local partition if the Region is a `PARTITION` Region).
Additionally, the Function may require the filter that was applied, if any. This suggests that the client and server
share a contract for the calling arguments but that the method signature may include additional parameters to pass values
provided by the `FunctionContext`. One possibility is for the client and server to share a common interface, but this
is not strictly required. The only constraint is that the method signature includes the same sequence of calling arguments
with which the Function was invoked after the additional parameters are resolved.
For example, suppose the client provides a `String` and an `int` as the calling arguments. These are provided
in the `FunctionContext` as an array, as the following example shows:
`Object[] args = new Object[] { "test", 123 };`
The Spring container should be able to bind to any method signature similar to the following (ignoring the return type for the moment):
The Spring container should be able to bind to any method signature similar to the following (ignoring the return type
for the moment):
[source,java]
----
public Object method1(String s1, int i2) {...}
public Object method2(Map<?, ?> data, String s1, int i2) {...}
public Object method3(String s1, Map<?, ?> data, int i2) {...}
public Object method4(String s1, Map<?, ?> data, Set<?> filter, int i2) {...}
public void method4(String s1, Set<?> filter, int i2, Region<?,?> data) {...}
public void method5(String s1, ResultSender rs, int i2);
public void method6(FunctionContest context);
public Object method1(String s1, int i2) { ... }
public Object method2(Map<?, ?> data, String s1, int i2) { ... }
public Object method3(String s1, Map<?, ?> data, int i2) { ... }
public Object method4(String s1, Map<?, ?> data, Set<?> filter, int i2) { ... }
public void method4(String s1, Set<?> filter, int i2, Region<?,?> data) { ... }
public void method5(String s1, ResultSender rs, int i2) { ... }
public void method6(FunctionContest context) { ... }
----
The general rule is that once any additional arguments (that is, region data and filter) are resolved,
the remaining arguments must correspond exactly, in order and type, to the expected function method parameters.
The method's return type must be void or a type that may be serialized (as a `java.io.Serializable`,
`DataSerializable`, or `PdxSerializable`). The latter is also a requirement for the calling arguments.
The region data should normally be defined as a `Map`, to facilitate unit testing, but may also be of type region,
The general rule is that once any additional arguments (that is, Region data and filter) are resolved,
the remaining arguments must correspond exactly, in order and type, to the expected Function method parameters.
The method's return type must be void or a type that may be serialized (as a `java.io.Serializable`, `DataSerializable`,
or `PdxSerializable`). The latter is also a requirement for the calling arguments.
The Region data should normally be defined as a `Map`, to facilitate unit testing, but may also be of type Region,
if necessary. As shown in the preceding example, it is also valid to pass the `FunctionContext` itself
or the `ResultSender` if you need to control how the results are returned to the client.
or the `ResultSender` if you need to control over how the results are returned to the client.
=== Annotations for Function Implementation
The following example shows how SDG's function annotations are used to expose POJO methods
as {data-store-name} functions:
The following example shows how {sdg-acronym}'s Function annotations are used to expose POJO methods
as {data-store-name} Functions:
[source,java]
----
@@ -117,33 +118,35 @@ public class ApplicationFunctions {
}
----
Note that the class itself must be registered as a Spring bean and each {data-store-name} Function is annotated
with `@GemfireFunction`. In the preceding example, Spring's `@Component` annotation was used, but you can register the bean
by using any method supported by Spring (such as XML configuration or with a Java configuration class when using Spring Boot).
This lets the Spring container create an instance of this class and wrap it in a
Note that the class itself must be registered as a Spring bean and each {data-store-name} Function is annotated with
`@GemfireFunction`. In the preceding example, Spring's `@Component` annotation was used, but you can register the bean
by using any method supported by Spring (such as XML configuration or with a Java configuration class when using
Spring Boot). This lets the Spring container create an instance of this class and wrap it in a
http://docs.spring.io/spring-data-gemfire/docs/current/api/org/springframework/data/gemfire/function/PojoFunctionWrapper.html[`PojoFunctionWrapper`].
Spring creates a wrapper instance for each method annotated with `@GemfireFunction`. Each wrapper instance shares
the same target object instance to invoke the corresponding method.
TIP: The fact that the POJO Function class is a Spring bean may offer other benefits, since it shares
the `ApplicationContext` with {data-store-name} components, such as the cache and regions. These may be injected into the class
if necessary.
the `ApplicationContext` with {data-store-name} components, such as the cache and Regions. These may be injected into
the class if necessary.
Spring creates the wrapper class and registers the functions with {data-store-name}'s function service. The function ID used
to register each function must be unique. By using convention, it defaults to the simple (unqualified) method name.
Spring creates the wrapper class and registers the Functions with {data-store-name}'s `FunctionService`. The Function ID
used to register each Function must be unique. By using convention, it defaults to the simple (unqualified) method name.
The name can be explicitly defined by using the `id` attribute of the `@GemfireFunction` annotation.
The `@GemfireFunction` annotation also provides other configuration attributes, `HA` and `optimizedForWrite`,
which correspond to properties defined by {data-store-name}'s
{x-data-store-javadoc}/org/apache/geode/cache/execute/Function.html[`Function`] interface.
If the method's return type is `void`, then the `hasResult` property is automatically set to `false`.
If the POJO method's return type is `void`, then the `hasResult` attribute is automatically set to `false`.
Otherwise, if the method returns a value, the `hasResult` attributes is set to `true`.
Even for `void` return types, the annotation's `hasResult` attribute can be set to `true` to override this convention,
as shown in the `functionWithContext` method show previously. Presumably, the intention is to use the `ResultSender` directly
to send results to the caller.
Even for `void` method return types, the annotation's `hasResult` attribute can be set to `true` to override
this convention, as shown in the `functionWithContext` method shown previously. Presumably, the intention is
to use the `ResultSender` directly to send results to the caller.
The `PojoFunctionWrapper` implements {data-store-name}'s `Function` interface, binds method parameters, and invokes the target method
in its `execute()` method. It also sends the method's return value by using the `ResultSender`.
The `PojoFunctionWrapper` implements {data-store-name}'s `Function` interface, binds method parameters, and invokes
the target method in its `execute()` method. It also sends the method's return value back to the caller
by using the `ResultSender`.
=== Batching Results
@@ -153,8 +156,8 @@ in the array or `Collection` is quite large, it may incur a performance penalty.
more manageable chunks, you can set the `batchSize` attribute, as illustrated in `function2`, shown earlier.
TIP: If you need more control of the `ResultSender`, especially if the method itself would use too much memory
to create the `Collection`, you can pass the `ResultSender` or access it through the `FunctionContext` and use it directly
within the method to sends results back to the caller.
to create the `Collection`, you can pass in the `ResultSender` or access it through the `FunctionContext`
and use it directly within the method to sends results back to the caller.
=== Enabling Annotation Processing
@@ -166,36 +169,38 @@ annotations. The following example activates annotation processing with XML:
<gfe:annotation-driven/>
----
The following example activates annotations by annotating a Java configuration class:
The following example activates annotation processing by annotating a Java configuration class:
[source,java]
----
@Configuration
@EnableGemfireFunctions
class ApplicationConfiguration { .. }
class ApplicationConfiguration { ... }
----
[[function-execution]]
== Executing a Function
A process that invokes a remote function needs to provide the function's ID, calling arguments, the execution target
(`onRegion`, `onServers`, `onServer`, `onMember`, or `onMembers`) and (optionally) a filter set. By using Spring Data for {data-store-name},
all you need do is define an interface supported by annotations. Spring creates a dynamic proxy
for the interface, which uses the `FunctionService` to create an `Execution`, invoke the `Execution`, and (if necessary) coerce
the results to the defined return type. This technique is similar to the way
Spring Data for {data-store-name}'s repository extension works. Thus, some of the configuration and concepts should be familiar.
Generally, a single interface definition maps to multiple function executions, one corresponding to each method
A process that invokes a remote Function needs to provide the Function's ID, calling arguments, the execution target
(`onRegion`, `onServers`, `onServer`, `onMember`, or `onMembers`) and (optionally) a filter set. By using {sdg-name},
all you need do is define an interface supported by annotations. Spring creates a dynamic proxy for the interface,
which uses the `FunctionService` to create an `Execution`, invoke the `Execution`, and (if necessary) coerce
the results to the defined return type. This technique is similar to the way {sdg-name}'s Repository extension works.
Thus, some of the configuration and concepts should be familiar.
Generally, a single interface definition maps to multiple Function executions, one corresponding to each method
defined in the interface.
=== Annotations for Function Execution
To support client-side Function execution, the following SDG Function annotations are provided: `@OnRegion`,
`@OnServer`, `@OnServers`, `@OnMember`, and `@OnMembers`. These annotations correspond to the `Execution` implementations
provided by {data-store-name}'s
{x-data-store-javadoc}/org/apache/geode/cache/execute/FunctionService.html[`FunctionService`].
Each annotation exposes the appropriate attributes. These annotations also provide an optional
`resultCollector` attribute whose value is the name of a Spring bean implementing the
{x-data-store-javadoc}/org/apache/geode/cache/execute/ResultCollector.html[`ResultCollector`]
To support client-side Function execution, the following {sdg-acronym} Function annotations are provided: `@OnRegion`,
`@OnServer`, `@OnServers`, `@OnMember`, and `@OnMembers`. These annotations correspond to the `Execution`
implementations provided by {data-store-name}'s
{x-data-store-javadoc}/org/apache/geode/cache/execute/FunctionService.html[`FunctionService`] class.
Each annotation exposes the appropriate attributes. These annotations also provide an optional `resultCollector` attribute
whose value is the name of a Spring bean implementing the
{x-data-store-javadoc}/org/apache/geode/cache/execute/ResultCollector.html[`ResultCollector`] interface
to use for the execution.
CAUTION: The proxy interface binds all declared methods to the same execution configuration. Although it is expected
@@ -217,21 +222,21 @@ public interface FunctionExecution {
}
----
By default, the function ID is the simple (unqualified) method name. The `@FunctionId` annotation can be used
to bind this invocation to a different function ID.
By default, the Function ID is the simple (unqualified) method name. The `@FunctionId` annotation can be used
to bind this invocation to a different Function ID.
=== Enabling Annotation Processing
The client-side uses Spring's classpath component scanning capability to discover annotated interfaces. To enable
function execution annotation processing in XML, insert the following element in your XML configuration:
Function execution annotation processing in XML, insert the following element in your XML configuration:
[source,xml]
----
<gfe-data:function-executions base-package="org.example.myapp.gemfire.functions"/>
----
The `function-executions` element is provided in the `gfe-data` namespace. The `base-package` attribute is required,
to avoid scanning the entire classpath. Additional filters are provided as described in the Spring
The `function-executions` element is provided in the `gfe-data` XML namespace. The `base-package` attribute is required
to avoid scanning the entire classpath. Additional filters can be provided as described in the Spring
http://docs.spring.io/spring/docs/current/spring-framework-reference/htmlsingle/#beans-scanning-filters[reference documentation].
Optionally, you can annotate your Java configuration class as follows:
@@ -261,8 +266,8 @@ public class MyApplication {
}
----
Alternately, you can use a function execution template directly. In the following example, the `GemfireOnRegionFunctionTemplate`
creates an `onRegion` function `Execution`:
Alternately, you can use a Function execution template directly. In the following example,
the `GemfireOnRegionFunctionTemplate` creates an `onRegion` Function `Execution`:
.Using the `GemfireOnRegionFunctionTemplate`
====
@@ -275,21 +280,21 @@ String result = template.executeAndExtract("someFunction", myFilter, "hello", "w
----
====
Internally, function `Executions` always return a `List`. `executeAndExtract` assumes a singleton `List`
containing the result and attempts to coerce that value into the requested type. There is also
an `execute` method that returns the `List` as is. The first parameter is the function ID.
The filter argument is optional. The remaining arguments are a variable argument `List`.
Internally, Function `Executions` always return a `List`. `executeAndExtract` assumes a singleton `List`
containing the result and attempts to coerce that value into the requested type. There is also an `execute` method
that returns the `List` as is. The first parameter is the Function ID. The filter argument is optional. The remaining
arguments are a variable argument `List`.
[[function-execution-pdx]]
== Function Execution with PDX
When using Spring Data for {data-store-name}'s function annotation support combined with {data-store-name}'s
When using {sdg-name}'s Function annotation support combined with {data-store-name}'s
{x-data-store-docs}/developing/data_serialization/gemfire_pdx_serialization.html[PDX Serialization],
there are a few logistical things to keep in mind.
As explained earlier in this section, and by way of example, you should typically define {data-store-name} functions by using POJO classes
annotated with Spring Data for {data-store-name}
http://docs.spring.io/spring-data-gemfire/docs/current/api/org/springframework/data/gemfire/function/annotation/package-summary.html[function annotations],
As explained earlier in this section, and by way of example, you should typically define {data-store-name} Functions
by using POJO classes annotated with {sdg-name}
http://docs.spring.io/spring-data-gemfire/docs/current/api/org/springframework/data/gemfire/function/annotation/package-summary.html[Function annotations],
as follows:
[source,java]
@@ -302,18 +307,18 @@ public class OrderFunctions {
}
----
NOTE: The `Integer` type `count` parameter is arbitrary, as is the separation of the `Order` class and `OrderSource` enum,
which might be logical to combine. However, the arguments were setup this way to demonstrate the problem with
function executions in the context of PDX.
NOTE: The `Integer` typed `count` parameter is arbitrary, as is the separation of the `Order` class
and the `OrderSource` enum, which might be logical to combine. However, the arguments were setup this way
to demonstrate the problem with Function executions in the context of PDX.
Your `Order` and `OrderSource` enum might be as follows:
Your `Order` class and `OrderSource` enum might be defined as follows:
[source,java]
----
public class Order ... {
private Long orderNumber;
private Calendar orderDateTime;
private LocalDateTime orderDateTime;
private Customer customer;
private List<Item> items
@@ -329,7 +334,8 @@ public enum OrderSource {
}
----
Of course, you can define a function `Execution` interface to call the 'process' {data-store-name} server function, as follows:
Of course, you can define a Function `Execution` interface to call the 'process' {data-store-name} server Function,
as follows:
[source,java]
----
@@ -339,78 +345,78 @@ public interface OrderProcessingFunctions {
}
----
Clearly, this `process(..)` `Order` Function is being called from a client-side with an application based on `ClientCache`
(that is `<gfe:client-cache/>`). This implies that the function arguments must also be serializable.
The same is true when invoking peer-to-peer member functions (such as `@OnMember(s)) between peers in the cluster.
Any form of `distribution` requires the data transmitted between client and server (or peers) to be serialized.
Clearly, this `process(..)` `Order` Function is being called from the client-side with a `ClientCache` instance
(that is `<gfe:client-cache/>`). This implies that the Function arguments must also be serializable. The same is true
when invoking peer-to-peer member Functions (such as `@OnMember(s)`) between peers in the cluster. Any form of
`distribution` requires the data transmitted between client and server (or peers) to be serialized.
Now, if you have configured {data-store-name} to use PDX for serialization (instead of Java serialization, for instance)
you can also set the `pdx-read-serialized` attribute to `true` in your configuration
of the {data-store-name} server(s), as follows:
you can also set the `pdx-read-serialized` attribute to `true` in your configuration of the {data-store-name} server(s),
as follows:
[source,xml]
----
<gfe:cache ... pdx-read-serialized="true"/>
----
Alternatively, you can set the `pdx-read-serialized` attribute to `true` for a {data-store-name} cache client application, as follows:
Alternatively, you can set the `pdx-read-serialized` attribute to `true` for a {data-store-name} cache client application,
as follows:
[source,xml]
----
<gfe:client-cache ... pdx-read-serialized="true"/>
----
Doing so causes all values read from the cache (that is, regions) as well as information passed between client and servers
(or peers) to remain in serialized form, including, but not limited to, function arguments.
Doing so causes all values read from the cache (that is, Regions) as well as information passed between client and servers
(or peers) to remain in serialized form, including, but not limited to, Function arguments.
{data-store-name} serializes only application domain object types that you have specifically configured (registered)
either by using {data-store-name}'s
{x-data-store-javadoc}/org/apache/geode/pdx/ReflectionBasedAutoSerializer.html[`ReflectionBasedAutoSerializer`],
or specifically (and recommended) by using a "`custom`" {data-store-name}
{x-data-store-javadoc}/org/apache/geode/pdx/PdxSerializer.html[`PdxSerializer`]. If you use
Spring Data for {data-store-name}'s repository extension to Spring Data Common's repository abstraction and infrastructure,
you might even want to consider using Spring Data for {data-store-name}'s
http://docs.spring.io/spring-data-gemfire/docs/current/api/org/springframework/data/gemfire/mapping/MappingPdxSerializer.html[`MappingPdxSerializer`],
which uses an entity's mapping meta-data to determine data from the application domain object that are serialized
{x-data-store-javadoc}/org/apache/geode/pdx/PdxSerializer.html[`PdxSerializer`].
If you use {sdg-name}'s Repository extension, you might even want to consider using {sdg-name}'s
{sdg-javadoc}/org/springframework/data/gemfire/mapping/MappingPdxSerializer.html[`MappingPdxSerializer`],
which uses an entity's mapping metadata to determine data from the application domain object that is serialized
to the PDX instance.
What is less than apparent, though, is that {data-store-name} automatically handles Java `Enum` types regardless of whether they are
explicitly configured (that is, registered with a `ReflectionBasedAutoSerializer` using a regex pattern
and the `classes` parameter or are handled by a "`custom`" {data-store-name} `PdxSerializer`), despite the fact that Java enumerations
implement `java.io.Serializable`.
What is less than apparent, though, is that {data-store-name} automatically handles Java `Enum` types regardless
of whether they are explicitly configured (that is, registered with a `ReflectionBasedAutoSerializer`,
using a regex pattern and the `classes` parameter or are handled by a "`custom`" {data-store-name} `PdxSerializer`),
despite the fact that Java enumerations implement `java.io.Serializable`.
So, when you set `pdx-read-serialized` to `true` on {data-store-name} servers where the {data-store-name} functions
(including Spring Data for {data-store-name} function-annotated POJO classes) are registered, then you
may encounter surprising behavior when invoking the function `Execution`.
So, when you set `pdx-read-serialized` to `true` on {data-store-name} servers where the {data-store-name} Functions
(including {sdg-name} Function-annotated POJO classes) are registered, then you may encounter surprising behavior
when invoking the Function `Execution`.
You might pass the following arguments when invoking the function:
You might pass the following arguments when invoking the Function:
[source,java]
----
orderProcessingFunctions.process(new Order(123, customer, Calendar.getInstance(), items), OrderSource.ONLINE, 400);
orderProcessingFunctions.process(new Order(123, customer, LocalDateTime.now(), items), OrderSource.ONLINE, 400);
----
However, the {data-store-name} function on the server gets the following:
However, the {data-store-name} Function on the server gets the following:
[source,java]
----
process(regionData, order:PdxInstance, :PdxInstanceEnum, 400);
----
The `Order` and `OrderSource` have been passed to the function as
The `Order` and `OrderSource` have been passed to the Function as
{x-data-store-javadoc}/org/apache/geode/pdx/PdxInstance.html[PDX instances].
Again, this all happens because `pdx-read-serialized` is set to `true`, which may be necessary in cases where
the {data-store-name} servers interact with multiple different clients (for example, a combination of Java clients and native clients, such as C++, C#, and others).
the {data-store-name} servers interact with multiple different clients (for example, a combination of Java clients
and native clients, such as C/C++, C#, and others).
This flies in the face of Spring Data for {data-store-name}'s strongly-typed function-annotated POJO class method signatures,
as you should reasonably expect application domain object types, not PDX serialized instances.
This flies in the face of {sdg-name}'s strongly-typed Function-annotated POJO class method signatures, where you would
reasonably expect application domain object types instead, not PDX serialized instances.
Consequently, Spring Data for {data-store-name} includes enhanced function support to automatically convert method arguments
type PDX to the desired application domain object types defined by the function method's
parameter types.
Consequently, {sdg-name} includes enhanced Function support to automatically convert PDX typed method arguments
to the desired application domain object types defined by the Function method's signature (parameter types).
However, this also requires you to explicitly register a {data-store-name} `PdxSerializer` on the {data-store-name} Servers
where Spring Data for {data-store-name} function-annotated POJOs are registered and used, as the following example shows:
However, this also requires you to explicitly register a {data-store-name} `PdxSerializer` on {data-store-name} servers
where {sdg-name} Function-annotated POJOs are registered and used, as the following example shows:
[source,java]
----
@@ -424,8 +430,8 @@ Alternatively, you can use {data-store-name}'s
for convenience. Of course, we recommend that, where possible, you use a custom `PdxSerializer` to maintain
finer-grained control over your serialization strategy.
Finally, Spring Data for {data-store-name} is careful not to convert your function arguments if you treat your function arguments
generically or as one of {data-store-name}'s PDX types, as follows:
Finally, {sdg-name} is careful not to convert your Function arguments if you treat your Function arguments generically
or as one of {data-store-name}'s PDX types, as follows:
[source,java]
----
@@ -435,9 +441,9 @@ public Object genericFunction(String value, Object domainObject, PdxInstanceEnum
}
----
Spring Data for {data-store-name} converts PDX type data to the corresponding application domain types if and only if
the corresponding application domain types are on the classpath and the function-annotated POJO method expects it.
{sdg-name} converts PDX typed data to the corresponding application domain types if and only if the corresponding
application domain types are on the classpath and the Function-annotated POJO method expects it.
For a good example of custom, composed application-specific {data-store-name} `PdxSerializers` as well as appropriate
POJO function parameter type handling based on the method signatures, see Spring Data for {data-store-name}'s
https://github.com/spring-projects/spring-data-gemfire/blob/2.0.0.M2/src/test/java/org/springframework/data/gemfire/function/ClientCacheFunctionExecutionWithPdxIntegrationTest.java[`ClientCacheFunctionExecutionWithPdxIntegrationTest`] class.
POJO Function parameter type handling based on the method signatures, see {sdg-name}'s
https://github.com/spring-projects/spring-data-gemfire/blob/{revnumber}/src/test/java/org/springframework/data/gemfire/function/ClientCacheFunctionExecutionWithPdxIntegrationTest.java[`ClientCacheFunctionExecutionWithPdxIntegrationTest`] class.

10
src/main/asciidoc/reference/function.adoc
View File

@@ -1,20 +1,20 @@
[[bootstrap:function]]
= Configuring the Function Service
Spring Data for {data-store-name} provides <<function-annotations,annotation>> support for implementing and registering
{sdg-name} provides <<function-annotations,annotation>> support for implementing, registering and executing
{data-store-name} Functions.
Spring Data for {data-store-name} also provides namespace support for registering {data-store-name}
{x-data-store-javadoc}/org/apache/geode/cache/execute/Function.html[functions]
{sdg-name} also provides XML namespace support for registering {data-store-name}
{x-data-store-javadoc}/org/apache/geode/cache/execute/Function.html[Functions]
for remote function execution.
See {data-store-name}'s {x-data-store-docs}/developing/function_exec/chapter_overview.html[documentation]
for more information on the function execution framework.
for more information on the Function execution framework.
{data-store-name} Functions are declared as Spring beans and must implement the `org.apache.geode.cache.execute.Function`
interface or extend `org.apache.geode.cache.execute.FunctionAdapter`.
The namespace uses a familiar pattern to declare functions, as the following example shows:
The namespace uses a familiar pattern to declare Functions, as the following example shows:
[source,xml]
----

15
src/main/asciidoc/reference/gateway.adoc
View File

@@ -1,16 +1,17 @@
[[bootstrap:gateway]]
= Configuring WAN Gateways
WAN Gateways provide a way to synchronize {data-store-name} Distributed Systems across geographic areas.
Spring Data for {data-store-name} provides namespace support for configuring WAN Gateways as illustrated in the following examples.
WAN Gateways provides a way to synchronize {data-store-name} Distributed Systems across geographic locations.
{sdg-name} provides XML namespace support for configuring WAN Gateways as illustrated in the following examples.
== WAN Configuration in {data-store-name} 7.0
In the following example, `GatewaySenders` are configured for a `PARTITION` region by adding child elements
(`gateway-sender` and `gateway-sender-ref`) to the region.
In the following example, `GatewaySenders` are configured for a `PARTITION` Region by adding child elements
(`gateway-sender` and `gateway-sender-ref`) to the Region. A `GatewaySender` may register `EventFilters`
and `TransportFilters`.
A `GatewaySender` may register `EventFilters` and `TransportFilters`. The following example also shows a sample configuration
of an `AsyncEventQueue`, which must also be wired into a region (not shown):
The following example also shows a sample configuration of an `AsyncEventQueue`, which must also be auto-wired
into a Region (not shown):
[source,xml]
----
@@ -48,7 +49,7 @@ of an `AsyncEventQueue`, which must also be wired into a region (not shown):
<bean id="transport-filter" class="org.springframework.data.gemfire.example.AnotherTransportFilter"/>
----
On the other end of a `GatewaySender` is a corresponding `GatewayReceiver` to receive gateway events.
On the other end of a `GatewaySender` is a corresponding `GatewayReceiver` to receive Gateway events.
The `GatewayReceiver` may also be configured with `EventFilters` and `TransportFilters`, as follows:
[source,xml]

106
src/main/asciidoc/reference/gemfire-bootstrap.adoc
View File

@@ -1,37 +1,39 @@
[[gemfire-bootstrap]]
= Bootstrapping a Spring ApplicationContext in {data-store-name}
Normally, a Spring based application <<bootstrap,bootstraps {data-store-name}>> by using Spring Data for {data-store-name}'s caching features.
By specifying a `<gfe:cache/>` element that uses the Spring Data for {data-store-name} XML namespace, a single embedded {data-store-name}
Normally, a Spring-based application <<bootstrap,bootstraps {data-store-name}>> by using {sdg-name}'s features.
By specifying a `<gfe:cache/>` element that uses the {sdg-name} XML namespace, a single embedded {data-store-name}
peer `Cache` instance is created and initialized with default settings in the same JVM process as your application.
However, it is sometimes necessary (perhaps as a requirement imposed by your IT organization) that {data-store-name} be fully managed
and operated by the provided {data-store-name} tool suite, perhaps with
{x-data-store-docs}/tools_modules/gfsh/chapter_overview.html[Gfsh]. By using Gfsh,
{data-store-name} bootstraps your Spring application context rather than the other way around. Instead of
an application server or a Java main class that uses Spring Boot, {data-store-name} does the bootstrapping and
hosts your application.
However, it is sometimes necessary (perhaps as a requirement imposed by your IT organization) that {data-store-name}
be fully managed and operated by the provided {data-store-name} tool suite, perhaps using
{x-data-store-docs}/tools_modules/gfsh/chapter_overview.html[Gfsh]. By using _Gfsh_, {data-store-name} bootstraps
your Spring `ApplicationContext` rather than the other way around. Instead of an application server or a Java main class
that uses Spring Boot, {data-store-name} does the bootstrapping and hosts your application.
NOTE: {data-store-name} is not an application server. In addition, there are limitations to using
this approach where the {data-store-name} cache configuration is concerned.
NOTE: {data-store-name} is not an application server. In addition, there are limitations to using this approach
where the {data-store-name} cache configuration is concerned.
[[gemfire-bootstrap-gfsh]]
== Using {data-store-name} to Bootstrap a Spring Context Started with Gfsh
In order to bootstrap a Spring application context in {data-store-name} when starting a {data-store-name} Server process by using Gfsh,
you must use {data-store-name}'s
{x-data-store-docs}/basic_config/the_cache/setting_cache_initializer.html[initalizer].
An initializer block can declare a callback application that is launched after the cache is initialized by {data-store-name}.
In order to bootstrap a Spring `ApplicationContext` in {data-store-name} when starting a {data-store-name} server
using _Gfsh_, you must use {data-store-name}'s
{x-data-store-docs}/basic_config/the_cache/setting_cache_initializer.html[initalizer] capability.
An initializer block can declare a application callback that is launched after the cache is initialized
by {data-store-name}.
An initializer is declared within an
{x-data-store-docs}/reference/topics/cache_xml.html#initializer[initializer] element by
using a minimal snippet of {data-store-name}'s native `cache.xml`. To bootstrap the Spring application context,
the `cache.xml` file is required, in much the same way as a minimal snippet of Spring XML config is needed to bootstrap
a Spring application context configured with component scanning (for example `<context:component-scan base-packages="..."/>`).
An initializer is declared within an {x-data-store-docs}/reference/topics/cache_xml.html#initializer[initializer] element
by using a minimal snippet of {data-store-name}'s native `cache.xml`. To bootstrap the Spring `ApplicationContext`,
a `cache.xml` file is required, in much the same way as a minimal snippet of Spring XML config is needed to bootstrap
a Spring `ApplicationContext` configured with component scanning
(for example `<context:component-scan base-packages="..."/>`).
Fortunately, such an initializer is already conveniently provided by the framework: the
http://docs.spring.io/spring-data-gemfire/docs/current/api/org/springframework/data/gemfire/support/SpringContextBootstrappingInitializer.html[`SpringContextBootstrappingInitializer`].
The following example shows a typical yet minimal configuration for this class inside {data-store-name}'s `cache.xml` file:
{sdg-javadoc}/org/springframework/data/gemfire/support/SpringContextBootstrappingInitializer.html[`SpringContextBootstrappingInitializer`].
The following example shows a typical, yet minimal, configuration for this class inside {data-store-name}'s
`cache.xml` file:
[source,xml]
----
@@ -52,13 +54,13 @@ The following example shows a typical yet minimal configuration for this class i
----
The `SpringContextBootstrappingInitializer` class follows conventions similar to Spring's `ContextLoaderListener`
class, which is used to bootstrap a Spring application context inside a web application, where application context
configuration files are specified with the `contextConfigLocations` servlet context parameter.
class, which is used to bootstrap a Spring `ApplicationContext` inside a web application, where `ApplicationContext`
configuration files are specified with the `contextConfigLocations` Servlet context parameter.
In addition, the `SpringContextBootstrappingInitializer` class can also be used with a `basePackages` parameter
to specify a comma-separated list of base packages that contain appropriately annotated application components.
The Spring container searches these components to find and create Spring beans and other application components
on the classpath, as the following example shows:
in the classpath, as the following example shows:
[source,xml]
----
@@ -79,20 +81,20 @@ on the classpath, as the following example shows:
----
Then, with a properly configured and constructed `CLASSPATH` and `cache.xml` file (shown earlier) specified as
a command-line option when starting a {data-store-name} Server in Gfsh, the command-line would be as follows:
a command-line option when starting a {data-store-name} server in _Gfsh_, the command-line would be as follows:
[source]
----
gfsh>start server --name=Server1 --log-level=config ...
gfsh>start server --name=ExampleServer --log-level=config ...
--classpath="/path/to/application/classes.jar:/path/to/spring-data-geode-<major>.<minor>.<maint>.RELEASE.jar"
--cache-xml-file="/path/to/geode/cache.xml"
----
The `application-context.xml` can be any valid Spring context configuration metadata, including all of the SDG namespace
elements. The only limitation with this approach is that a {data-store-name} cache cannot be configured by using
the Spring Data for {data-store-name} namespace. In other words, none of the `<gfe:cache/>` element attributes
(such as `cache-xml-location`, `properties-ref`, `critical-heap-percentage`, `pdx-serializer-ref`, `lock-lease`, and others)
can be specified. If used, these attributes are ignored.
The `application-context.xml` can be any valid Spring configuration metadata, including all of the {sdg-acronym}
XML namespace elements. The only limitation with this approach is that a {data-store-name} cache cannot be configured
by using the {sdg-acronym} XML namespace. In other words, none of the `<gfe:cache/>` element attributes
(such as `cache-xml-location`, `properties-ref`, `critical-heap-percentage`, `pdx-serializer-ref`, `lock-lease`,
and others) can be specified. If used, these attributes are ignored.
The reason for this is that {data-store-name} itself has already created and initialized the cache before the initializer
gets invoked. As a result, the cache already exists and, since it is a "`singleton`", it cannot be re-initialized
@@ -101,25 +103,25 @@ or have any of its configuration augmented.
[[gemfire-bootstrap-lazywiring]]
== Lazy-wiring {data-store-name} Components
Spring Data for {data-store-name} already provides support for wiring {data-store-name} components (such as `CacheListeners`,
{sdg-name} already provides support for auto-wiring {data-store-name} components (such as `CacheListeners`,
`CacheLoaders`, `CacheWriters` and so on) that are declared and created by {data-store-name} in `cache.xml` by using
SDG's `WiringDeclarableSupport` class, as described in <<apis:declarable:autowiring>>. However, this works only
when Spring is the one doing the bootstrapping (that is, when Spring bootstraps {data-store-name}).
{sdg-acronym}'s `WiringDeclarableSupport` class, as described in <<apis:declarable:autowiring>>. However, this works
only when Spring is the one doing the bootstrapping (that is, when Spring bootstraps {data-store-name}).
When your Spring application context is bootstrapped by {data-store-name}, these {data-store-name} application components go unnoticed,
because the Spring application context does not yet exist. The Spring application context does not get created
until {data-store-name} calls the initializer block, which only occurs after all the other {data-store-name} components and configuration
have already been created and initialized.
When your Spring `ApplicationContext` is bootstrapped by {data-store-name}, these {data-store-name} application components
go unnoticed, because the Spring `ApplicationContext` does not exist yet. The Spring `ApplicationContext` does not get
created until {data-store-name} calls the initializer block, which only occurs after all the other {data-store-name}
components (cache, Regions, and others) have already been created and initialized.
To solve this problem, a new `LazyWiringDeclarableSupport` class was introduced. This new class is aware of the
Spring application context. The intention of this abstract base class is that any implementing class
register itself to be configured by the Spring container that is eventually be created by {data-store-name}
once the initializer is called. In essence, this gives your {data-store-name} application components a chance
to be configured and auto-wired with Spring beans defined in the Spring application context.
Spring `ApplicationContext`. The intention behind this abstract base class is that any implementing class registers
itself to be configured by the Spring container that is eventually created by {data-store-name} once the initializer
is called. In essence, this gives your {data-store-name} application components a chance to be configured and auto-wired
with Spring beans defined in the Spring container.
In order for your {data-store-name} application components to be auto-wired by the Spring container, you should create an application class
that extends the `LazyWiringDeclarableSupport` and annotate any class member that needs to be provided as
a Spring bean dependency, similar to the following example:
In order for your {data-store-name} application components to be auto-wired by the Spring container, you should create
an application class that extends the `LazyWiringDeclarableSupport` and annotate any class member that needs to be
provided as a Spring bean dependency, similar to the following example:
[source,java]
----
@@ -133,16 +135,16 @@ public class UserDataSourceCacheLoader extends LazyWiringDeclarableSupport
}
----
As implied in the `CacheLoader` example above, you might necessarily (though rarely) have defined both
a region and a `CacheListener` component in {data-store-name} `cache.xml`. The `CacheLoader` may need access to an application DAO
(or perhaps a JDBC `DataSource` defined in the Spring application context) for loading `Users` into a {data-store-name} `REPLICATE` region
on start.
As implied in the `CacheLoader` example above, you might necessarily (though rarely) have defined both a Region
and a `CacheListener` component in {data-store-name} `cache.xml`. The `CacheLoader` may need access to an application
Repository (or perhaps a JDBC `DataSource` defined in the Spring `ApplicationContext`) for loading `Users` into a
{data-store-name} `REPLICATE` Region on startup.
CAUTION
====
Be careful when mixing the different life-cycles of {data-store-name} and the Spring Container together
in this manner. Not all use cases and scenarios are supported. The {data-store-name} `cache.xml` configuration would be
similar to the following (which comes from SDG's test suite):
Be careful when mixing the different life-cycles of {data-store-name} and the Spring container together in this manner.
Not all use cases and scenarios are supported. The {data-store-name} `cache.xml` configuration would be similar to
the following (which comes from {sdg-acronym}'s test suite):
[source,xml]
----

186
src/main/asciidoc/reference/indexing.adoc
View File

@@ -1,29 +1,29 @@
[[bootstrap:indexing]]
= Configuring an Index
{data-store-name} allows indexes (also sometimes pluralized as indices) to be created on region data to improve the performance of OQL (Object Query Language) queries.
{data-store-name} allows indexes (also sometimes pluralized as indices) to be created on Region data
to improve the performance of OQL (Object Query Language) queries.
In Spring Data for {data-store-name} (SDG), indexes are declared with the `index` element, as the following example shows:
In {sdg-name}, indexes are declared with the `index` element, as the following example shows:
[source,xml]
----
<gfe:index id="myIndex" expression="someField" from="/SomeRegion" type="HASH"/>
----
In Spring Data for {data-store-name}'s XML schema (also called the SDG namespace), `index` bean declarations are not bound to a region,
unlike {data-store-name}'s native `cache.xml`. Rather, they are top-level elements similar to `&lt;gfe:cache&gt;`. This lets
you declare any number of indexes on any Region, whether they were just created or already exist -- a
significant improvement over {data-store-name}'s native `cache.xml` format.
In {sdg-name}'s XML schema (also called the {sdg-acronym} XML namespace), `index` bean declarations are not bound
to a Region, unlike {data-store-name}'s native `cache.xml`. Rather, they are top-level elements similar to
`&lt;gfe:cache&gt;` element. This lets you declare any number of indexes on any Region, whether they were just created
or already exist -- a significant improvement over {data-store-name}'s native `cache.xml` format.
An `Index` must have a name. You can give the `Index` an explicit name by using the `name` attribute.
Otherwise, the bean name (that is, the value of the `id` attribute) of the `index` bean definition is used as
the `index` name.
the `Index` name.
The `expression` and `from` clause form the main components of an `index`, identifying the data to index
(that is, the region identified in the `from` clause) along with what criteria (that is, `expression`) is used
to index the data. The `expression` should be based on what application domain object fields are used
in the predicate of application-defined OQL queries used to query and look up the objects stored
in the Region.
The `expression` and `from` clause form the main components of an `Index`, identifying the data to index
(that is, the Region identified in the `from` clause) along with what criteria (that is, `expression`) is used
to index the data. The `expression` should be based on what application domain object fields are used in the predicate
of application-defined OQL queries used to query and look up the objects stored in the Region.
Consider the following example, which has a `lastName` property:
@@ -42,7 +42,8 @@ class Customer {
}
----
Now consider the following example, which has an application-defined SDG repository to query for `Customer` objects:
Now consider the following example, which has an application-defined {sdg-acronym} Repository
to query for `Customer` objects:
[source,java]
----
@@ -54,7 +55,7 @@ interface CustomerRepository extends GemfireRepository<Customer, Long> {
}
----
The SDG repository finder/query method results in the following OQL statement being run:
The {sdg-acronym} Repository finder/query method results in the following OQL statement being generated and ran:
[source,java]
----
@@ -68,32 +69,30 @@ Therefore, you might want to create an `Index` with a statement similar to the f
<gfe:index id="myIndex" name="CustomersLastNameIndex" expression="lastName" from="/Customers" type="HASH"/>
----
The `from` clause must refer to a valid, existing region and is how an `index` gets applied to a region.
This is not specific to Spring Data Pivotal GemFir. It is a feature of {data-store-name}.
The `from` clause must refer to a valid, existing Region and is how an `Index` gets applied to a Region.
This is not specific to {sdg-name}. It is a feature of {data-store-name}.
The `index` `type` may be one of three enumerated values defined by Spring Data for {data-store-name}'s
http://docs.spring.io/spring-data-gemfire/docs/current/api/org/springframework/data/gemfire/IndexType.html[`IndexType`]
enumeration: `FUNCTIONAL`, `HASH`, and `PRIMARY_KEY`.
The `Index` `type` may be one of three enumerated values defined by {sdg-name}'s
{sdg-javadoc}/org/springframework/data/gemfire/IndexType.html[`IndexType`] enumeration:
`FUNCTIONAL`, `HASH`, and `PRIMARY_KEY`.
Each of the enumerated values corresponds to one of the {x-data-store-javadoc}/org/apache/geode/cache/query/QueryService.html[`QueryService`]
`create[|Key|Hash]Index` methods invoked when the actual `index` is to be created (or "`defined`" -- you can find more on "`defining`"
indexes in the next section). For instance, if the `IndexType` is `PRIMARY_KEY`, then the
`create[|Key|Hash]Index` methods invoked when the actual `Index` is to be created (or "`defined`" -- you can find
more on "`defining`" indexes in the next section). For instance, if the `IndexType` is `PRIMARY_KEY`, then the
{x-data-store-javadoc}/org/apache/geode/cache/query/QueryService.html#createKeyIndex-java.lang.String-java.lang.String-java.lang.String-[QueryService.createKeyIndex(..)]
is invoked to create a `KEY` `Index`.
The default is `FUNCTIONAL` and results in one of the `QueryService.createIndex(..)` methods
being invoked.
See the Spring Data for {data-store-name} XML schema for a full set of options.
The default is `FUNCTIONAL` and results in one of the `QueryService.createIndex(..)` methods being invoked. See the
{sdg-name} XML schema for a full set of options.
For more information on indexing in {data-store-name}, see "`http://gemfire90.docs.pivotal.io/geode/developing/query_index/query_index.html[Working with Indexes]`"
in {data-store-name}'s User Guide.
== Defining Indexes
In addition to creating Indexes up front as `ndex` bean definitions are processed by Spring Data for {data-store-name}
on Spring container initialization, you may also define all of your application indexes prior to creating
them by using the `define` attribute, as follows:
In addition to creating indexes up front as `Index` bean definitions are processed by {sdg-name} on Spring container
initialization, you may also define all of your application indexes prior to creating them by using the `define`
attribute, as follows:
[source,xml]
----
@@ -101,9 +100,9 @@ them by using the `define` attribute, as follows:
----
When `define` is set to `true` (it defaults to `false`), it does not actually create the `Index` at that moment.
All "`defined`" Indexes are created all at once, when the Spring `ApplicationContext` is "`refreshed`" or, to put it differently,
when a `ContextRefreshedEvent` is published by the Spring container. Spring Data for {data-store-name} registers itself as
an `ApplicationListener` listening for the `ContextRefreshedEvent`. When fired, Spring Data for {data-store-name} calls
All "`defined`" Indexes are created all at once, when the Spring `ApplicationContext` is "`refreshed`" or, to put it
differently, when a `ContextRefreshedEvent` is published by the Spring container. {sdg-name} registers itself as
an `ApplicationListener` listening for the `ContextRefreshedEvent`. When fired, {sdg-name} calls
{x-data-store-javadoc}/org/apache/geode/cache/query/QueryService.html#createDefinedIndexes[`QueryService.createDefinedIndexes()`].
Defining indexes and creating them all at once boosts speed and efficiency when creating indexes.
@@ -113,22 +112,22 @@ for more details.
== `IgnoreIfExists` and `Override`
Two Spring Data for {data-store-name} `Index` configuration options warrant special mention: `ignoreIfExists` and `override`.
Two {sdg-name} `Index` configuration options warrant special mention: `ignoreIfExists` and `override`.
These options correspond to the `ignore-if-exists` and `override` attributes on the `&lt;gfe:index&gt;` element
in Spring Data for {data-store-name}'s XML schema, respectively.
in {sdg-name}'s XML namespace, respectively.
WARNING: Make sure you absolutely understand what you are doing before using either of these options. These options can
affect the performance and resources (such as memory) consumed by your application at runtime. As a result, both of
these options are disabled (set to `false`) in SDG by default.
these options are disabled (set to `false`) in {sdg-acronym} by default.
NOTE: These options are only available in Spring Data for {data-store-name} and exist to workaround known limitations
with {data-store-name}. {data-store-name} has no equivalent options or functionality.
NOTE: These options are only available in {sdg-name} and exist to workaround known limitations with {data-store-name}.
{data-store-name} has no equivalent options or functionality.
Each option significantly differs in behavior and entirely depends on the type of {data-store-name} `Index` exception thrown.
This also means that neither option has any effect if a {data-store-name} Index-type exception is not thrown. These options
are meant to specifically handle {data-store-name} `IndexExistsException` and `IndexNameConflictException` instances, which can occur
for various, sometimes obscure reasons. The exceptions have the following causes:
Each option significantly differs in behavior and entirely depends on the type of {data-store-name} `Index` exception
thrown. This also means that neither option has any effect if a {data-store-name} Index-type exception is not thrown.
These options are meant to specifically handle {data-store-name} `IndexExistsException` and `IndexNameConflictException`
instances, which can occur for various, sometimes obscure reasons. The exceptions have the following causes:
* An {x-data-store-javadoc}/org/apache/geode/cache/query/IndexExistsException.html[`IndexExistsException`]
is thrown when there exists another `Index` with the same definition but a different name when attempting to
@@ -138,42 +137,42 @@ create an `Index`.
is thrown when there exists another `Index` with the same name but possibly different definition when attempting to
create an `Index`.
Spring Data for {data-store-name}'s default behavior is to fail-fast, always. So, neither `Index` _Exception_ are "`handled`"
by default. These `Index` exceptions are wrapped in a SDG `GemfireIndexException` and rethrown. If you wish
for Spring Data for {data-store-name} to handle them for you, you can set either of these `Index` bean definition options to `true`.
{sdg-name}'s default behavior is to fail-fast, always. So, neither `Index` _Exception_ are "`handled`" by default.
These `Index` exceptions are wrapped in a {sdg-acronym} `GemfireIndexException` and rethrown. If you wish for {sdg-name}
to handle them for you, you can set either of these `Index` bean definition options to `true`.
`IgnoreIfExists` always takes precedence over `Override`, primarily because it uses fewer resources (because it returns
the "`existing`" `index` in both exceptional cases).
`IgnoreIfExists` always takes precedence over `Override`, primarily because it uses fewer resources, simply because
it returns the "`existing`" `Index` in both exceptional cases.
=== `IgnoreIfExists` Behavior
When an `IndexExistsException` is thrown and `ignoreIfExists` is set to `true` (or `&lt;gfe:index ignore-if-exists="true"&gt;`),
then the `index` that would have been created by this `index` bean definition or declaration is ignored,
then the `Index` that would have been created by this `index` bean definition or declaration is simply ignored,
and the existing `Index` is returned.
There is little consequence in returning the existing `index`, since the `Index` definition is the same,
as determined by {data-store-name} itself, not SDG.
There is little consequence in returning the existing `Index`, since the `index` bean definition is the same,
as determined by {data-store-name} itself, not {sdg-acronym}.
However, this also means that no `index` with the "`name`" specified in your `Index` bean definition or declaration
However, this also means that no `Index` with the "`name`" specified in your `index` bean definition or declaration
actually exists from {data-store-name}'s perspective (that is, with
{x-data-store-javadoc}/org/apache/geode/cache/query/QueryService.html#getIndexes[`QueryService.getIndexes()`]).
Therefore, you should be careful when writing OQL query statements that use query hints, especially hints that refer
to the application `Index` being ignored. Those query hints need to be changed.
Therefore, you should be careful when writing OQL query statements that use query hints, especially query hints
that refer to the application `Index` being ignored. Those query hints need to be changed.
When an `IndexNameConflictException` is thrown and `ignoreIfExists` is set to `true` (or `&lt;gfe:index ignore-if-exists="true"&gt;`),
the `index` that would have been created by this `index` bean definition or declaration is also ignored,
and the "existing" Index is returned, as when an `IndexExistsException` is thrown.
the `Index` that would have been created by this `index` bean definition or declaration is also ignored,
and the "existing" `Index` is again returned, as when an `IndexExistsException` is thrown.
However, there is more risk in returning the existing `index` and ignoring the application's definition
of the `Index` when an `IndexNameConflictException` is thrown. For a `IndexNameConflictException`, while the names
of the conflicting indexes are the same, the definitions could be different. This situation could have
implications for OQL queries specific to the application, where you would presume the indexes were defined specifically
with the application data access patterns and queries in mind. However, if like-named indexes differ in definition,
this might not be the case. Consequently, you should verify your index names.
However, there is more risk in returning the existing `Index` and ignoring the application's definition of the `Index`
when an `IndexNameConflictException` is thrown. For a `IndexNameConflictException`, while the names of the conflicting
indexes are the same, the definitions could be different. This situation could have implications for OQL queries
specific to the application, where you would presume the indexes were defined specifically with the application
data access patterns and queries in mind. However, if like-named indexes differ in definition, this might not be
the case. Consequently, you should verify your `Index` names.
NOTE: SDG makes a best effort to inform the user when the `Index` being ignored is significantly different
in its definition from the existing `Index`. However, in order for SDG to accomplish this, it must be able to find
the existing `Index`, which is looked up by using the {data-store-name} API (the only means available).
NOTE: {sdg-acronym} makes a best effort to inform the user when the `Index` being ignored is significantly different
in its definition from the existing `Index`. However, in order for {sdg-acronym} to accomplish this, it must be able to
find the existing `Index`, which is looked up by using the {data-store-name} API (the only means available).
=== `Override` Behavior
@@ -182,56 +181,55 @@ When an `IndexExistsException` is thrown and `override` is set to `true` (or `&l
the `Index` is effectively renamed. Remember, `IndexExistsExceptions` are thrown when multiple indexes exist that
have the same definition but different names.
Spring Data for {data-store-name} can only accomplish this by using {data-store-name}'s API, by first removing the existing `Index`
and then recreating the `index` with the new name. It is possible that either the remove or subsequent
create invocation could fail. There is no way to execute both actions atomically and rollback this joint operation
if either fails.
{sdg-name} can only accomplish this by using {data-store-name}'s API, by first removing the existing `Index`
and then recreating the `Index` with the new name. It is possible that either the remove or subsequent create invocation
could fail. There is no way to execute both actions atomically and rollback this joint operation if either fails.
However, if it succeeds, then you have the same problem as before with the `ignoreIfExists` option. Any existing OQL
query statement using query hints that refer to the old `Index` by name must be changed.
When an `IndexNameConflictException` is thrown and `override` is set to `true` (or `&lt;gfe:index override="true"&gt;`),
the existing `Index` can potentially be re-defined. We say "`potentially`" because it is possible for the
like-named, existing `Index` to have exactly the same definition and name when an `IndexNameConflictException`
is thrown.
the existing `Index` can potentially be re-defined. We say "`potentially`" because it is possible for the like-named,
existing `Index` to have exactly the same definition and name when an `IndexNameConflictException` is thrown.
If so, SDG is smart and returns the existing Index as is, even on `override`. There is no harm in this behavior,
since both the name and the definition are exactly the same. Of course, SDG can only accomplish this when
SDG is able to find the existing `Index`, which is dependent on {data-store-name}'s APIs. If it cannot be found,
nothing happens and a SDG `GemfireIndexException` is thrown that wraps the `IndexNameConflictException`.
If so, {sdg-acronym} is smart and returns the existing `Index` as is, even on `override`. There is no harm
in this behavior, since both the name and the definition are exactly the same. Of course, {sdg-acronym} can only
accomplish this when {sdg-acronym} is able to find the existing `Index`, which is dependent on {data-store-name}'s APIs.
If it cannot be found, nothing happens and a {sdg-acronym} `GemfireIndexException` is thrown that wraps the
`IndexNameConflictException`.
However, when the definition of the existing `Index` is different, SDG attempts to re-create the `Index` by
using the `Index` definition specified in the `Index` bean definition or declaration. Make sure this is what you want
and make sure the `Index` definition matches your expectations and application requirements.
However, when the definition of the existing `Index` is different, {sdg-acronym} attempts to re-create the `Index`
by using the `Index` definition specified in the `index` bean definition. Make sure this is what you want and make sure
the `index` bean definition matches your expectations and application requirements.
=== How Does `IndexNameConflictExceptions` Actually Happen?
It is probably not all that uncommon for `IndexExistsExceptions` to be thrown, especially when
multiple configuration sources are used to configure {data-store-name} (Spring Data for {data-store-name}, {data-store-name} Cluster Config,
{data-store-name} native `cache.xml`, the API, and so on). You should definitely prefer one configuration method
and stick with it.
It is probably not all that uncommon for `IndexExistsExceptions` to be thrown, especially when multiple configuration
sources are used to configure {data-store-name} ({sdg-name}, {data-store-name} Cluster Config, {data-store-name} native
`cache.xml`, the API, and so on). You should definitely prefer one configuration method and stick with it.
However, when does an `IndexNameConflictException` get thrown?
One particular case is an `Index` defined on a `PARTITION` region (PR). When an `Index` is defined on
a `PARTITION` region (for example, `X`), {data-store-name} distributes the `Index` definition (and name) to other peer members
in the cluster that also host the same `PARTITION` region (that is, "X"). The distribution of this `Index` definition
to and subsequent creation of this `Index` by peer members on a need-to-know basis (that is, those hosting the same PR)
is performed asynchronously.
One particular case is an `Index` defined on a `PARTITION` Region (PR). When an `Index` is defined on a `PARTITION` Region
(for example, `X`), {data-store-name} distributes the `Index` definition (and name) to other peer members
in the cluster that also host the same `PARTITION` Region (that is, "X"). The distribution of this `Index` definition
to, and subsequent creation of, this `Index` by peer members is on a need-to-know basis (that is, by peer member hosting
the same PR) is performed asynchronously.
During this window of time, it is possible that these pending PR `Indexes` cannot be identified by {data-store-name} --
such as with a call to {x-data-store-javadoc}/org/apache/geode/cache/query/QueryService.html#getIndexes[`QueryService.getIndexes()`]
with {x-data-store-javadoc}/org/apache/geode/cache/query/QueryService.html#getIndexes-org.apache.geode.cache.Region[`QueryService.getIndexes(:Region)`],
or even with {x-data-store-javadoc}/org/apache/geode/cache/query/QueryService.html#getIndex-org.apache.geode.cache.Region-java.lang.String[`QueryService.getIndex(:Region, indexName:String)`].
As a result, the only way for SDG or other {data-store-name} cache client applications (not involving Spring) to know for sure
is to attempt to create the `Index`. If it fails with either an `IndexNameConflictException`
or even an `IndexExistsException`, the application knows there is a problem. This is because the `QueryService` `Index` creation waits on
pending `Index` definitions, whereas the other {data-store-name} API calls do not.
As a result, the only way for {sdg-acronym} or other {data-store-name} cache client applications (not involving Spring)
to know for sure is to attempt to create the `Index`. If it fails with either an `IndexNameConflictException` or even
an `IndexExistsException`, the application knows there is a problem. This is because the `QueryService` `Index` creation
waits on pending `Index` definitions, whereas the other {data-store-name} API calls do not.
In any case, SDG makes a best effort and attempts to inform you what has happened or is happening and tell you
the corrective action. Given that all {data-store-name} `QueryService.createIndex(..)` methods are synchronous, blocking operations,
the state of {data-store-name} should be consistent and accessible after either of these index-type exceptions are thrown.
Consequently, SDG can inspect the state of the system and act accordingly, based on your configuration.
In any case, {sdg-acronym} makes a best effort and attempts to inform you what has happened or is happening and tell you
the corrective action. Given that all {data-store-name} `QueryService.createIndex(..)` methods are synchronous,
blocking operations, the state of {data-store-name} should be consistent and accessible after either of these index-type
exceptions are thrown. Consequently, {sdg-acronym} can inspect the state of the system and act accordingly,
based on your configuration.
In all other cases, SDG embraces a fail-fast strategy.
In all other cases, {sdg-acronym} embraces a fail-fast strategy.

4
src/main/asciidoc/reference/introduction.adoc
View File

@@ -1,7 +1,7 @@
[[ref-introduction]]
= Document Structure
The following chapters explain the core functionality offered by Spring Data for {data-store-name}:
The following chapters explain the core functionality offered by {sdg-name}:
* <<bootstrap>> describes the configuration support provided for configuring, initializing, and accessing
{data-store-name} Caches, Regions, and related distributed system components.
@@ -27,4 +27,4 @@ OQL (Object Query Language) query.
using `Gfsh`.
* <<samples>> describes the examples provided with the distribution to illustrate the various features
available in Spring Data for {data-store-name}.
available in {sdg-name}.

100
src/main/asciidoc/reference/lucene.adoc
View File

@@ -5,9 +5,8 @@
index and search on data stored in {data-store-name} by using Lucene queries. Search-based queries also include
the ability to page through query results.
Additionally, Spring Data for {data-store-name} adds support for query projections based on the Spring Data Commons
projection infrastructure. This feature lets the query results be projected into first-class
application domain types as needed by the application use case.
Additionally, {sdg-name} adds support for query projections based on the Spring Data Commons projection infrastructure.
This feature lets the query results be projected into first-class application domain types as needed by the application.
A Lucene `Index` must be created before any Lucene search-based query can be run. A `LuceneIndex`
can be created in Spring (Data for {data-store-name}) XML config as follows:
@@ -18,8 +17,8 @@ can be created in Spring (Data for {data-store-name}) XML config as follows:
----
Additionally, Apache Lucene allows the specification of
http://lucene.apache.org/core/6_5_0/core/org/apache/lucene/analysis/Analyzer.html[analyzers] per field
and can be configured as shown in the following example:
http://lucene.apache.org/core/6_5_0/core/org/apache/lucene/analysis/Analyzer.html[analyzers]
per field and can be configured as shown in the following example:
[source,xml]
----
@@ -38,12 +37,13 @@ and can be configured as shown in the following example:
----
The `Map` can be specified as a top-level bean definition and referenced by using the `ref` attribute
in the nested `<gfe:field-analyzers>` element, as follows: `<gfe-field-analyzers ref="refToTopLevelMapBeanDefinition"/>`.
in the nested `<gfe:field-analyzers>` element, as follows:
`<gfe-field-analyzers ref="refToTopLevelMapBeanDefinition"/>`.
Spring Data for {data-store-name}'s `LuceneIndexFactoryBean` API and SDG's XML namespace also let a
{sdg-name}'s `LuceneIndexFactoryBean` API and {sdg-acronym}'s XML namespace also lets a
{x-data-store-javadoc}/org/apache/geode/cache/lucene/LuceneSerializer.html[`org.apache.geode.cache.lucene.LuceneSerializer`]
be specified when you create the `LuceneIndex`. The `LuceneSerializer` lets you configure the way objects
are converted to Lucene documents for the index when the object is indexed.
be specified when you create the `LuceneIndex`. The `LuceneSerializer` lets you configure the way objects are converted
to Lucene documents for the index when the object is indexed.
The following example shows how to add an `LuceneSerializer` to the `LuceneIndex`:
@@ -67,8 +67,8 @@ You can specify the `LuceneSerializer` as an anonymous, nested bean definition a
</gfe:lucene-index>
----
Alternatively, you can declare or define a `LuceneIndex` in Spring Java config,
inside a `@Configuration` class, as the following example shows:
Alternatively, you can declare or define a `LuceneIndex` in Spring Java config, inside a `@Configuration` class,
as the following example shows:
[source,java]
----
@@ -110,37 +110,38 @@ There are a few limitations of {data-store-name}'s, Apache Lucene integration an
First, a `LuceneIndex` can only be created on a {data-store-name} `PARTITION` Region.
Second, all `LuceneIndexes` must be created before the region to which the `LuceneIndex` applies.
Second, all `LuceneIndexes` must be created before the Region to which the `LuceneIndex` applies.
NOTE: To help ensure that all declared `LuceneIndexes` defined in a Spring context are created before the regions
on which they apply, SDG includes the `org.springframework.data.gemfire.config.support.LuceneIndexRegionBeanFactoryPostProcessor`.
NOTE: To help ensure that all declared `LuceneIndexes` defined in a Spring container are created before the Regions
on which they apply, {sdg-acronym} includes the `org.springframework.data.gemfire.config.support.LuceneIndexRegionBeanFactoryPostProcessor`.
You may register this Spring {spring-framework-javadoc}/org/springframework/beans/factory/config/BeanFactoryPostProcessor.html[`BeanFactoryPostProcessor`]
in XML config by using `<bean class="org.springframework.data.gemfire.config.support.LuceneIndexRegionBeanFactoryPostProcessor"/>`
The `o.s.d.g.config.support.LuceneIndexRegionBeanFactoryPostProcessor` may only be used when using SDG XML config.
in XML config by using `<bean class="org.springframework.data.gemfire.config.support.LuceneIndexRegionBeanFactoryPostProcessor"/>`.
The `o.s.d.g.config.support.LuceneIndexRegionBeanFactoryPostProcessor` may only be used when using {sdg-acronym} XML config.
More details about Spring's `BeanFactoryPostProcessors` can be found {spring-framework-docs}/core.html#beans-factory-extension-factory-postprocessors[here].
It is possible that these {data-store-name} restrictions will not apply in a future release which is why
the SDG `LuceneIndexFactoryBean` API takes a reference to the region directly as well, rather than just the region path.
the {sdg-acronym} `LuceneIndexFactoryBean` API takes a reference to the Region directly as well,
rather than just the Region path.
This is more ideal when you want to define a `LuceneIndex` on an existing region
with data at a later point during the application's lifecycle and as requirements demand. Where possible, SDG strives
to adhere to strongly-typed objects. However, for the time being, you must use the `regionPath` property
to specify the region to which the `LuceneIndex` is applied.
This is more ideal when you want to define a `LuceneIndex` on an existing Region with data at a later point
during the application's lifecycle and as requirements demand. Where possible, {sdg-acronym} strives to adhere to
strongly-typed objects. However, for the time being, you must use the `regionPath` property to specify the Region
to which the `LuceneIndex` is applied.
NOTE: Additionally, in the preceding example, note the presence of Spring's `@DependsOn` annotation
on the `Books` region bean definition. This creates a dependency from the `Books` region bean
to the `bookTitleIndex` `LuceneIndex` bean definition, ensuring that the `LuceneIndex` is created before
the region on which it applies.
on the `Books` Region bean definition. This creates a dependency from the `Books` Region bean to the `bookTitleIndex`
`LuceneIndex` bean definition, ensuring that the `LuceneIndex` is created before the Region on which it applies.
Now that we have a `LuceneIndex`, we can perform Lucene-based data access operations, such as queries.
Now that once we have a `LuceneIndex`, we can perform Lucene-based data access operations, such as queries.
== Lucene Template Data Accessors
Spring Data for {data-store-name} provides two primary templates for Lucene data access operations, depending on
how low of a level your application is prepared to deal with.
{sdg-name} provides two primary templates for Lucene data access operations, depending on how low of a level
your application is prepared to deal with.
The `LuceneOperations` interface defines query operations by using {data-store-name}
{x-data-store-javadoc}/org/apache/geode/cache/lucene/package-summary.html[Lucene types], which are defined in the following interface definition:
{x-data-store-javadoc}/org/apache/geode/cache/lucene/package-summary.html[Lucene types],
which are defined in the following interface definition:
[source,java]
----
@@ -172,18 +173,18 @@ NOTE: The `[, int resultLimit]` indicates that the `resultLimit` parameter is op
The operations in the `LuceneOperations` interface match the operations provided by the {data-store-name}'s
{x-data-store-javadoc}/org/apache/geode/cache/lucene/LuceneQuery.html[LuceneQuery] interface.
However, SDG has the added value of translating proprietary {data-store-name} or Apache Lucene `Exceptions`
However, {sdg-acronym} has the added value of translating proprietary {data-store-name} or Apache Lucene `Exceptions`
into Spring's highly consistent and expressive DAO
http://docs.spring.io/spring/docs/current/spring-framework-reference/htmlsingle/#dao-exceptions[exception hierarchy],
particularly as many modern data access operations involve more than one store or repository.
Additionally, SDG's `LuceneOperations` interface can shield your application from interface-breaking changes
Additionally, {sdg-acronym}'s `LuceneOperations` interface can shield your application from interface-breaking changes
introduced by the underlying {data-store-name} or Apache Lucene APIs when they occur.
However, it would be sad to offer a Lucene Data Access Object (DAO) that only uses {data-store-name}
and Apache Lucene data types (such as {data-store-name}'s `LuceneResultStruct`). Therefore, SDG gives you the
`ProjectingLuceneOperations` interface to remedy these important application concerns.
The following listing shows the `ProjectingLuceneOperations` interface definition:
However, it would be sad to offer a Lucene Data Access Object (DAO) that only uses {data-store-name} and Apache Lucene
data types (such as {data-store-name}'s `LuceneResultStruct`). Therefore, {sdg-acronym} gives you the
`ProjectingLuceneOperations` interface to remedy these important application concerns. The following listing shows
the `ProjectingLuceneOperations` interface definition:
[source,java]
----
@@ -228,7 +229,8 @@ class Person {
}
----
Additionally, you might have a single interface to represent people as `Customers`, depending on your application view, as follows:
Additionally, you might have a single interface to represent people as `Customers`, depending on your application view,
as follows:
[source,java]
----
@@ -281,9 +283,8 @@ List<Customer> firstPage = customers.getContent();
Conveniently, the Spring Data Commons `Page` interface also implements `java.lang.Iterable<T>`, making it easy
to iterate over the contents.
The only restriction to the Spring Data Commons projection infrastructure is that the projection type
must be an interface. However, it is possible to extend the provided
SDC Projection infrastructure and provide a custom
The only restriction to the Spring Data Commons Projection infrastructure is that the projection type must be
an interface. However, it is possible to extend the provided SDC Projection infrastructure and provide a custom
http://docs.spring.io/spring-data/commons/docs/current/api/org/springframework/data/projection/ProjectionFactory.html[`ProjectionFactory`]
that uses https://github.com/cglib/cglib[CGLIB] to generate proxy classes as the projected entity.
@@ -291,11 +292,11 @@ You can use `setProjectionFactory(:ProjectionFactory)` to set a custom `Projecti
== Annotation Configuration Support
Finally, Spring Data for {data-store-name} provides annotation configuration support for `LuceneIndexes`.
Eventually, the SDG Lucene support finds its way into the repository infrastructure extension for {data-store-name}
so that Lucene queries can be expressed as methods on an application `Repository` interface, in much the same way as the
http://docs.spring.io/spring-data-gemfire/docs/current/reference/html/#gemfire-repositories.executing-queries[OQL support]
works today.
Finally, {sdg-name} provides annotation configuration support for `LuceneIndexes`.
Eventually, the {sdg-acronym} Lucene support will finds its way into the Repository infrastructure extension for
{data-store-name} so that Lucene queries can be expressed as methods on an application `Repository` interface,
in much the same way as the <<gemfire-repositories.queries.executing,OQL support>> works today.
However, in the meantime, if you want to conveniently express `LuceneIndexes`, you can do so directly on
your application domain objects, as the following example shows:
@@ -319,8 +320,8 @@ class Person {
}
----
To enable this feature, you must use SDG's Annotation configuration support and the `@EnableEntityDefineRegions` and `@EnableIndexing`
Annotations, as follows:
To enable this feature, you must use {sdg-acronym}'s annotation configuration support specifically with the
`@EnableEntityDefineRegions` and `@EnableIndexing` annotations, as follows:
[source,java]
----
@@ -333,10 +334,9 @@ class ApplicationConfiguration {
}
----
NOTE: `LuceneIndexes` can be created only on {data-store-name} Servers since `LuceneIndexes` only apply
NOTE: `LuceneIndexes` can only be created on {data-store-name} servers since `LuceneIndexes` only apply
to `PARTITION` Regions.
Given our earlier definition of the `Person` class, the SDG annotation configuration support
finds the `Person` entity class definition and determines that people are stored in
a `PARTITION` region called `People` and that the `Person` has an OQL `Index` on `birthDate`
along with a `LuceneIndex` on `lastName`.
Given our earlier definition of the `Person` class, the {sdg-acronym} annotation configuration support finds
the `Person` entity class definition and determines that people are stored in a `PARTITION` Region called "`People`"
and that the `Person` has an OQL `Index` on `birthDate` along with a `LuceneIndex` on `lastName`.

137
src/main/asciidoc/reference/mapping.adoc
View File

@@ -10,8 +10,8 @@ This section covers:
[[mapping.entities]]
== Entity Mapping
Spring Data for {data-store-name} provides support to map entities that are stored in a region in the Geode In-Memory Data Grid.
The mapping metadata is defined by using annotations on application domain classes, as the following example shows:
{sdg-name} provides support to map entities that are stored in a Region. The mapping metadata is defined by
using annotations on application domain classes, as the following example shows:
.Mapping a domain class to a {data-store-name} Region
====
@@ -35,14 +35,14 @@ public class Person {
----
====
The `@Region` annotation can be used to customize the region
in which an instance of the `Person` class is stored. The `@Id` annotation can be used to annotate the property
that should be used as the cache (region) key, identifying the region entry. The `@PersistenceConstructor` annotation
helps to disambiguate multiple potentially available constructors, taking parameters and explicitly marking
the constructor annotated as the constructor to be used to construct entities. In an application domain class with no
or only a single constructor, you can omit the annotation.
The `@Region` annotation can be used to customize the Region in which an instance of the `Person` class is stored.
The `@Id` annotation can be used to annotate the property that should be used as the cache Region key, identifying
the Region entry. The `@PersistenceConstructor` annotation helps to disambiguate multiple potentially available
constructors, taking parameters and explicitly marking the constructor annotated as the constructor to be used to
construct entities. In an application domain class with no or only a single constructor, you can omit the annotation.
In addition to storing entities in top-level regions, entities can be stored in Sub-Regions as well, as the following example shows:
In addition to storing entities in top-level Regions, entities can be stored in Sub-Regions as well,
as the following example shows:
[source,java]
----
@@ -57,37 +57,37 @@ public class Guest extends User {
}
----
Be sure to use the full path of the {data-store-name} region, as defined with the Spring Data for {data-store-name} XML namespace by
using the `id` or `name` attributes of the `<*-region>` element.
Be sure to use the full path of the {data-store-name} Region, as defined with the {sdg-name} XML namespace
by using the `id` or `name` attributes of the `<*-region>` element.
[[mapping.entities.region]]
=== Entity Mapping by Region Type
In addition to the `@Region` annotation, Spring Data for {data-store-name} also recognizes the region type-specific
mapping annotations: `@ClientRegion`, `@LocalRegion`, `@PartitionRegion`, and `@ReplicateRegion`.
In addition to the `@Region` annotation, {sdg-name} also recognizes type-specific Region mapping annotations:
`@ClientRegion`, `@LocalRegion`, `@PartitionRegion`, and `@ReplicateRegion`.
Functionally, these annotations are treated exactly the same as the generic `@Region` annotation in the SDG
mapping infrastructure. However, these additional mapping annotations are useful in Spring Data for {data-store-name}'s
Functionally, these annotations are treated exactly the same as the generic `@Region` annotation in the {sdg-acronym}
mapping infrastructure. However, these additional mapping annotations are useful in {sdg-name}'s
annotation configuration model. When combined with the `@EnableEntityDefinedRegions` configuration annotation
on a Spring `@Configuration` annotated class, it is possible to generate regions in the local cache, whether
on a Spring `@Configuration` annotated class, it is possible to generate Regions in the local cache, whether
the application is a client or peer.
These annotations let you be more specific about what type of region your application
entity class should be mapped to and also have an impact on the data management policies of the region
(for example, partition -- also known as sharding -- versus replicating data).
These annotations let you be more specific about what type of Region your application entity class should be mapped to
and also has an impact on the data management policies of the Region (for example, partition -- also known as sharding
-- versus replicating data).
Using these region type-specific mapping annotations with the SDG Annotation config model saves you from having to
explicitly define these regions in configuration.
Using these type-specific Region mapping annotations with the {sdg-acronym} annotation configuration model saves you
from having to explicitly define these Regions in configuration.
[[mapping.repositories]]
== Repository Mapping
As an alternative to specifying the region in which the entity is stored by using the `@Region` annotation
on the entity class, you can also specify the `@Region` annotation on the entity's `Repository`.
As an alternative to specifying the Region in which the entity is stored by using the `@Region` annotation
on the entity class, you can also specify the `@Region` annotation on the entity's `Repository` interface.
See <<gemfire-repositories>> for more details.
However, suppose you want to store a `Person` record in multiple {data-store-name} Regions (for example, `People` and `Customers`).
Then you can define your corresponding `Repository` interface extensions as follows:
However, suppose you want to store a `Person` record in multiple {data-store-name} Regions (for example, `People`
and `Customers`). Then you can define your corresponding `Repository` interface extensions as follows:
[source,java]
----
@@ -102,7 +102,8 @@ public interface CustomerRepository extends GemfireRepository<Person, String> {
}
----
Then, using each Repository individually, you can store the entity in multiple {data-store-name} Regions, as the following example shows:
Then, using each Repository individually, you can store the entity in multiple {data-store-name} Regions,
as the following example shows:
[source,java]
----
@@ -120,24 +121,24 @@ class CustomerService {
}
----
You can wrap the `update` service method in a Spring managed transaction,
either as a local cache transaction or a global transaction.
You can even wrap the `update` service method in a Spring managed transaction, either as a local cache transaction
or a global transaction.
[[mapping.pdx-serializer]]
== Mapping PDX Serializer
Spring Data for {data-store-name} provides a custom
{x-data-store-javadoc}/org/apache/geode/pdx/PdxSerializer.html[`PdxSerializer`] implementation
that uses the mapping information to customize entity serialization.
{sdg-name} provides a custom {x-data-store-javadoc}/org/apache/geode/pdx/PdxSerializer.html[`PdxSerializer`]
implementation that uses the mapping information to customize entity serialization.
It also lets you customize entity instantiation by using the Spring Data `EntityInstantiator` abstraction.
By default, the serializer uses a `ReflectionEntityInstantiator` that uses the persistence constructor of
the mapped entity (the default constructor, a singly declared constructor, or a constructor
explicitly annotated with `@PersistenceConstructor`).
the mapped entity (the default constructor, a singly declared constructor, or a constructor explicitly
annotated with `@PersistenceConstructor`).
To provide arguments for constructor parameters, the serializer reads fields with the named constructor parameter,
explicitly specified using Spring's `@Value` annotation, from the supplied
{x-data-store-javadoc}/org/apache/geode/pdx/PdxReader.html[`PdxReader`], as shown in the following example:
{x-data-store-javadoc}/org/apache/geode/pdx/PdxReader.html[`PdxReader`],
as shown in the following example:
.Using `@Value` on entity constructor parameters
====
@@ -153,21 +154,22 @@ public class Person {
====
An entity class annotated in this way has the `thing` field read from the `PdxReader` and passed as the value
for the constructor parameter, `firstname`. The value for `lastName` is a Spring bean with the name `bean`.
for the constructor parameter, `firstname`. The value for `lastName` is a Spring bean with the name "`bean`".
In addition to the custom instantiation logic and strategy provided by `EntityInstantiators`,
the `MappingPdxSerializer` also provides capabilities beyond {data-store-name}'s own
the `MappingPdxSerializer` also provides capabilities well beyond {data-store-name}'s own
{x-data-store-javadoc}/org/apache/geode/pdx/ReflectionBasedAutoSerializer.html[`ReflectionBasedAutoSerializer`].
While {data-store-name}'s `ReflectionBasedAutoSerializer` conveniently uses Java reflection to populate entities and
uses regular expressions to identify types that should be handled (serialized and deserialized) by the `ReflectionBasedAutoSerializer`,
it cannot, unlike `MappingPdxSerializer`, perform the following:
While {data-store-name}'s `ReflectionBasedAutoSerializer` conveniently uses Java reflection to populate entities
and uses regular expressions to identify types that should be handled (serialized and deserialized) by
the `ReflectionBasedAutoSerializer`, it cannot, unlike `MappingPdxSerializer`, perform the following:
* Register custom `PdxSerializer` objects per entity field and property names and types.
* Conveniently identifies ID properties.
* Automatically handles read-only properties.
* Automatically handles transient properties.
* Allows more robust type filtering in a `null`-safe manner (for example, not limited to only expressing types with regex).
* Allows more robust type filtering in a `null`-safe manner (for example, not limited to
only expressing types using regex).
We now explore each feature of the `MappingPdxSerializer` in a bit more detail.
@@ -193,8 +195,8 @@ public class User {
}
----
While the user's name probably does not require any special logic to serialize the value, serializing
the password might require additional logic to handle the sensitive nature of the field or property.
While the user's name probably does not require any special logic to serialize the value, serializing the password
might require additional logic to handle the sensitive nature of the field or property.
Perhaps you want to protect the password when sending the value over the network, between a client and a server,
and you only want to store the salted hash. When using the `MappingPdxSerializer`, you can register
@@ -212,12 +214,12 @@ mappingPdxSerializer.setCustomPdxSerializers(customPdxSerializers);
----
After registering the application-defined `SaltedHashPasswordPdxSerializer` instance with the `Password`
application domain model type, the `MappingPdxSerializer` consults the custom `PdxSerializer` to
serialize and deserialize all `Password` objects regardless of the containing object (for example, `User`).
application domain model type, the `MappingPdxSerializer` consults the custom `PdxSerializer` to serialize
and deserialize all `Password` objects regardless of the containing object (for example, `User`).
However, suppose you want to customize the serialization of only `Passwords` on `User` objects.
To do so, you can register the custom `PdxSerializer` for the `User` type by specifying only the fully qualified
name of the `Class's` field or property, as the following example shows:
To do so, you can register the custom `PdxSerializer` for the `User` type by specifying the fully qualified name
of the `Class's` field or property, as the following example shows:
.Registering custom `PdxSerializers` by POJO field/property name
====
@@ -230,19 +232,19 @@ customPdxSerializers.put("example.app.auth.model.User.password", new SaltedHashP
mappingPdxSerializer.setCustomPdxSerializers(customPdxSerializers);
----
Notice the use of the fully-qualified field or propety name (that is `example.app.auth.model.User.password`)
Notice the use of the fully-qualified field or property name (that is `example.app.auth.model.User.password`)
as the custom `PdxSerializer` registration key.
NOTE: You could construct the registration key by using a more logical code snippet, such as the following:
`User.class.getName().concat(".password");`. We recommended this over the example shown earlier. The preceding example
tried to be as explicit as possible about the semantics of registration.
`User.class.getName().concat(".password");`. We recommended this over the example shown earlier.
The preceding example tried to be as explicit as possible about the semantics of registration.
[[mapping.pdx-serializer.id-properties]]
=== Mapping ID Properties
Like {data-store-name}'s `ReflectionBasedAutoSerializer`, SDG's `MappingPdxSerializer` is also able to determine
the identifier of the entity. However, `MappingPdxSerializer` does so by using Spring Data's mapping metadata,
specifically by finding the entity property designated as the identifier by using Spring Data's
Like {data-store-name}'s `ReflectionBasedAutoSerializer`, {sdg-acronym}'s `MappingPdxSerializer` is also able to
determine the identifier of the entity. However, `MappingPdxSerializer` does so by using Spring Data's mapping metadata,
specifically by finding the entity property designated as the identifier using Spring Data's
{spring-data-commons-javadoc}/org/springframework/data/annotation/Id.html[`@Id`] annotation.
For example:
@@ -267,8 +269,9 @@ when the `PdxSerializer.toData(..)` method is called during serialization.
What happens when your entity defines a read-only property?
First, it is important to understand what a "`read-only`" property is. If you define a POJO by following the http://www.oracle.com/technetwork/java/javase/documentation/spec-136004.html[JavaBeans]
specification (as Spring does), you might a POJO with a read-only property, as follows:
First, it is important to understand what a "`read-only`" property is. If you define a POJO by following the
http://www.oracle.com/technetwork/java/javase/documentation/spec-136004.html[JavaBeans]specification (as Spring does),
you might define a POJO with a read-only property, as follows:
[source,java]
----
@@ -286,17 +289,17 @@ class ApplicationDomainType {
}
----
Then the `readOnly` property is "`read-only`" because it does not provide a setter method. It has only a getter method.
In this case, the `readOnly` property (not to be confused with the `readOnly` `DomainType` field)
is considered "`read-only`".
The `readOnly` property is "`read-only`" because it does not provide a setter method. It has only a getter method.
In this case, the `readOnly` property (not to be confused with the `readOnly` `DomainType` field) is considered
"`read-only`".
As a result, the `MappingPdxSerializer` does not try to write this value back when populating the instance of `DomainType`
in the `PdxSerializer.fromData(:Class<?>, :PdxReader)` method.
As a result, the `MappingPdxSerializer` does not try to write this value back when populating an instance of
`DomainType` in the `PdxSerializer.fromData(:Class<?>, :PdxReader)` method.
This is useful in situations where you might be returning a view or projection of some entity type and you only want
to write state that is writable. Perhaps the view or projection of the entity is based on authorization or some other
criteria. The point is that you can leverage this feature as is appropriate for your application's use cases and requirements.
If you want the field or property to always be written, you can define a setter.
criteria. The point is that you can leverage this feature as is appropriate for your application's use cases
and requirements. If you want the field or property to always be written, you can define a setter.
[[mapping.pdx-serializer.transient-properties]]
=== Mapping Transient Properties
@@ -304,11 +307,11 @@ If you want the field or property to always be written, you can define a setter.
Likewise, what happens when your entity defines `transient` properties?
You would expect the `transient` fields or properties of your entity not to be serialized to the stream of PDX bytes
when serializing entity. That is exactly what happens, unlike {data-store-name}'s own
`ReflectionBasedAutoSerializer`, which serializes everything accessible from the object through Java reflection.
when serializing the entity. That is exactly what happens, unlike {data-store-name}'s own `ReflectionBasedAutoSerializer`,
which serializes everything accessible from the object through Java reflection.
The `MappingPdxSerializer` does not serialize any fields or properties that are qualified as being transient either by using
Java's `transient` keyword (in the case of fields) or by using the
The `MappingPdxSerializer` does not serialize any fields or properties that are qualified as being transient either
by using Java's `transient` keyword (in the case of fields) or by using the
{spring-data-commons-javadoc}/org/springframework/data/annotation/Transient.html[`@Transient`]
Spring Data annotation on either fields or properties.
@@ -342,11 +345,11 @@ Neither the `Process` `id` field nor the readable `hostname` property are writte
[[mapping.pdx-serializer.type-filtering]]
=== Filtering by Class types
Similar to {data-store-name}'s `ReflectionBasedAutoSerializer`, SDG's `MappingPdxSerializer` lets you filter
Similar to {data-store-name}'s `ReflectionBasedAutoSerializer`, {sdg-acronym}'s `MappingPdxSerializer` lets you filter
the types of objects that the `MappingPdxSerializer` serializes and deserializes.
However, unlike {data-store-name}'s `ReflectionBasedAutoSerializer`, which uses complex regular expressions to express
which types the serializer handles, SDG's `MappingPdxSerializer` uses the much more robust
which types the serializer handles, {sdg-acronym}'s `MappingPdxSerializer` uses the much more robust
https://docs.oracle.com/javase/8/docs/api/java/util/function/Predicate.html[`java.util.function.Predicate`] interface
and API to express type-matching criteria.

520
src/main/asciidoc/reference/region.adoc
View File

@@ -8,10 +8,11 @@ Typically, each Region is associated with one domain object, similar to a table
{data-store-name} implements the following types of Regions:
* *REPLICATE* - 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.
* *PARTITION* - Data is partitioned into buckets (sharded) among cache members that define the Region. This provides
high read and write performance and is suitable for large data sets that are too big for a single node.
* *REPLICATE* - Data is replicated across all cache members in the cluster that define the Region. This provides
very high read performance but writes take longer to perform the replication.
* *PARTITION* - Data is partitioned into buckets (sharded) among many cache members in the cluster that define
the Region. This provides high read and write performance and is suitable for 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 REPLICATE or PARTITION Region
hosted on cache servers in a cluster. It may hold data created or fetched locally. Alternately, it can be empty.
@@ -34,8 +35,7 @@ as `ordersRegion` for an existing Region named `Orders`, you can use the followi
<gfe:lookup-region id="ordersRegion" name="Orders"/>
----
If `name` is not specified, the bean's `id` will be used as the name of the Region.
The example above becomes:
If `name` is not specified, the bean's `id` will be used as the name of the Region. The example above becomes:
[source,xml]
----
@@ -55,14 +55,14 @@ was used. Alternately, one can reference the cache bean with the `cache-ref` att
<gfe:lookup-region id="ordersRegion" name="Orders" cache-ref="myCache"/>
----
`lookup-region` lets you retrieve existing, pre-configured regions without exposing
the region semantics or setup infrastructure.
`lookup-region` lets you retrieve existing, pre-configured Regions without exposing the Region semantics
or setup infrastructure.
[[bootstrap:region:lookup:auto]]
== Auto Region Lookup
"`auto-lookup`" lets you import all regions defined in a {data-store-name} native `cache.xml` file into a Spring
application context when you use the `cache-xml-location` attribute on the `<gfe:cache>` element.
"`auto-lookup`" lets you import all Regions defined in a {data-store-name} native `cache.xml` file into
a Spring `ApplicationContext` when you use the `cache-xml-location` attribute on the `<gfe:cache>` element.
For instance, consider the following `cache.xml` file:
@@ -89,7 +89,7 @@ You can import the preceding `cache.xml` file as follows:
----
You can then use the `<gfe:lookup-region>` element (for example, `<gfe:lookup-region id="Parent"/>`) to reference
specific Regions as beans in the Spring context, or you can choose to import all regions defined in `cache.xml`
specific Regions as beans in the Spring container, or you can choose to import all Regions defined in `cache.xml`
by using the following:
[source,xml]
@@ -97,16 +97,16 @@ by using the following:
<gfe:auto-region-lookup/>
----
Spring Data for {data-store-name} automatically creates beans for all {data-store-name} regions defined in `cache.xml` that have not been
explicitly added to the Spring context with explicit `<gfe:lookup-region>` bean declarations.
{sdg-name} automatically creates beans for all {data-store-name} Regions defined in `cache.xml` that have not been
explicitly added to the Spring container with explicit `<gfe:lookup-region>` bean declarations.
It is important to realize that Spring Data for {data-store-name} uses a Spring
http://docs.spring.io/spring/docs/current/javadoc-api/org/springframework/beans/factory/config/BeanPostProcessor.html[BeanPostProcessor]
to post-process the cache after it is both created and initialized to determine the regions defined in {data-store-name} to add
as beans in the Spring application context.
It is important to realize that {sdg-name} uses a Spring
{spring-framework-javadoc}/org/springframework/beans/factory/config/BeanPostProcessor.html[BeanPostProcessor]
to post-process the cache after it is both created and initialized to determine the Regions defined in {data-store-name}
to add as beans in the Spring `ApplicationContext`.
You may inject these "`auto-looked-up`" regions as you would any other bean defined in the Spring application context, with
one exception: You may need to define a `depends-on` association with the '`gemfireCache`' bean, as follows:
You may inject these "`auto-looked-up`" Regions as you would any other bean defined in the Spring `ApplicationContext`,
with one exception: You may need to define a `depends-on` association with the '`gemfireCache`' bean, as follows:
[source,java]
----
@@ -128,22 +128,22 @@ public class ApplicationDao extends DaoSupport {
}
----
The preceding example applies when you use Spring's `component-scan` functionality.
The preceding example only applies when you use Spring's `component-scan` functionality.
If you declarE your components by using Spring XML config, then you would do the following:
If you declare your components by using Spring XML config, then you would do the following:
[source,xml]
----
<bean class="example.ApplicationDao" depends-on="gemfireCache"/>
----
Doing so ensures that the {data-store-name} cache and all the regions defined in `cache.xml` get created before any components
with auto-wire references when using the new `<gfe:auto-region-lookup>` element.
Doing so ensures that the {data-store-name} cache and all the Regions defined in `cache.xml` get created before
any components with auto-wire references when using the new `<gfe:auto-region-lookup>` element.
[[bootstrap:region:overview]]
== Configuring Regions
Spring Data for {data-store-name} provides comprehensive support for configuring any type of Region through the following elements:
{sdg-name} provides comprehensive support for configuring any type of Region through the following elements:
* LOCAL Region: `<local-region>`
* PARTITION Region: `<partitioned-region>`
@@ -151,12 +151,12 @@ Spring Data for {data-store-name} provides comprehensive support for configuring
* Client Region: `<client-region>`
See the {data-store-name} documentation for a comprehensive description of
{x-data-store-docs}/developing/region_options/region_types.html[region types].
{x-data-store-docs}/developing/region_options/region_types.html[Region Types].
[[bootstrap:region:attributes]]
=== Common Region Attributes
The following table lists the attributes available for all region types:
The following table lists the attributes available for all Region types:
[cols="1,2,2", options="header"]
.Common Region Attributes
@@ -253,10 +253,10 @@ The following table lists the attributes available for all region types:
[[bootstrap:region:cache-listener]]
=== `CacheListener` instances
`CacheListener` instances are registered with a region to handle region events, such as when entries are created, updated,
destroyed, and so on. A `CacheListener` can be any bean that implements the
`CacheListener` instances are registered with a Region to handle Region events, such as when entries are created,
updated, destroyed, and so on. A `CacheListener` can be any bean that implements the
{x-data-store-javadoc}/org/apache/geode/cache/CacheListener.html[`CacheListener`] interface.
A region may have multiple listeners, declared with the `cache-listener` element nested in the containing
A Region may have multiple listeners, declared with the `cache-listener` element nested in the containing
`*-region` element.
The following example has two declared `CacheListener's`. The first references a named, top-level Spring bean.
@@ -279,7 +279,8 @@ The second is an anonymous inner bean definition.
The following example uses an alternate form of the `cache-listener` element with the `ref` attribute.
Doing so allows for more concise configuration when defining a single `CacheListener`.
Note: The namespace allows only a single `cache-listener` element, so either the style shown in the preceding example or the style in the following example must be used.
Note: The XML namespace allows only a single `cache-listener` element, so either the style shown in
the preceding example or the style in the following example must be used.
[source,xml]
----
@@ -291,35 +292,36 @@ Note: The namespace allows only a single `cache-listener` element, so either the
<bean id="myListener" class="example.CacheListener"/>
</beans>
----
WARNING: Using `ref` and a nested declaration in the `cache-listener` element is illegal. The two options are
mutually exclusive and using both in the same element results in an exception.
WARNING: Using `ref` and a nested declaration in the `cache-listener` element is illegal.
The two options are mutually exclusive and using both in the same element results in an exception.
.Bean Reference Conventions
[NOTE]
====
The `cache-listener` element is an example of a common pattern used in the namespace anywhere {data-store-name} provides
a callback interface to be implemented in order to invoke custom code in response to Cache or Region events.
The `cache-listener` element is an example of a common pattern used in the XML namespace anywhere {data-store-name}
provides a callback interface to be implemented in order to invoke custom code in response to cache or Region events.
When you use 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, if multiple instances are permitted, it may contain nested bean references
and inner bean definitions in any combination. The convention is to use
the singular form (that is, `cache-listener` vs `cache-listeners`), reflecting that the most common scenario is, in fact,
a single instance. We have already seen examples of this pattern in the <<bootstrap:cache:advanced,advanced cache>>
the schema allows a single occurrence of the `cache-listener` element, but, if multiple instances are permitted,
it may contain nested bean references and inner bean definitions in any combination. The convention is to use
the singular form (that is, `cache-listener` vs `cache-listeners`), reflecting that the most common scenario is,
in fact, a single instance. We have already seen examples of this pattern in the <<bootstrap:cache:advanced,advanced cache>>
configuration example.
====
[[bootstrap:region:cache-loaders-writers]]
=== CacheLoaders and CacheWriters
Similar to `cache-listener`, the namespace provides `cache-loader` and `cache-writer` elements to register
these {data-store-name} components for a region.
Similar to `cache-listener`, the XML namespace provides `cache-loader` and `cache-writer` elements to register
these {data-store-name} components for a Region.
A `CacheLoader` is invoked on a cache miss to let an entry be loaded from an external data source, such as a
database. A `CacheWriter` is invoked before an entry is created or updated, to allow the entry to be synchronized to
an external data source. The difference is that {data-store-name} supports, at most, a single instance `CacheLoader` and `CacheWriter`
per region. However, either declaration style may be used.
A `CacheLoader` is invoked on a cache miss to let an entry be loaded from an external data source, such as a database.
A `CacheWriter` is invoked before an entry is created or updated, to allow the entry to be synchronized to an external
data source. The main difference is that {data-store-name} supports, at most, a single instance of `CacheLoader`
and `CacheWriter` per Region. However, either declaration style may be used.
The following example declares a region with both a `CacheLoader` and a `CacheWriter`:
The following example declares a Region with both a `CacheLoader` and a `CacheWriter`:
[source,xml]
----
@@ -346,13 +348,13 @@ in the {data-store-name} documentation for more details.
[[bootstrap:region:compression]]
== Compression
{data-store-name} Regions may also be compressed in order to reduce JVM memory consumption and pressure to possibly avoid
stopping the global GCs. When you enable compression for a region, all values stored in memory for the region
are compressed, while keys and indexes remain uncompressed. New values are compressed when put into the region
and all values are decompressed automatically when read back from the region. Values are not compressed when
{data-store-name} Regions may also be compressed in order to reduce JVM memory consumption and pressure
to possibly avoid global GCs. When you enable compression for a Region, all values stored in memory for the Region
are compressed, while keys and indexes remain uncompressed. New values are compressed when put into the Region
and all values are decompressed automatically when read back from the Region. Values are not compressed when
persisted to disk or when sent over the wire to other peer members or clients.
The following example shows a region with compression enabled:
The following example shows a Region with compression enabled:
[source,xml]
----
@@ -366,18 +368,18 @@ The following example shows a region with compression enabled:
----
See {data-store-name}'s documentation for more information on
{x-data-store-docs}/managing/region_compression/region_compression.html[region compression].
{x-data-store-docs}/managing/region_compression/region_compression.html[Region Compression].
[[bootstrap:region:subregions]]
== Subregions
Spring Data for {data-store-name} also supports subregions, allowing regions to be arranged in a hierarchical relationship.
{sdg-name} also supports Sub-Regions, allowing Regions to be arranged in a hierarchical relationship.
For example, {data-store-name} allows for a (for example) `/Customer/Address` region and a different `/Employee/Address` region. Additionally,
a subregion may have its 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 {data-store-name} constraints. A subregion is naturally
declared as a child element of a region. The subregion's name attribute is the simple name. The preceding example
might be configured as follows:
For example, {data-store-name} allows for a `/Customer/Address` Region and a different `/Employee/Address` Region.
Additionally, a Sub-Region may have its own Sub-Regions and configuration. A Sub-Region does not inherit attributes
from its parent Region. Regions types may be mixed and matched subject to {data-store-name} constraints. A Sub-Region
is naturally declared as a child element of a Region. The Sub-Region's `name` attribute is the simple name.
The preceding example might be configured as follows:
[source,xml]
----
@@ -392,19 +394,20 @@ might be configured as follows:
</beans>
----
Note that the `Monospaced ([id])` attribute is not permitted for a subregion. The subregions are created with
bean names (/Customer/Address and /Employee/Address, respectively, in this case). So they may be injected
into other application beans that need them by using the full path name, such as `GemfireTemplate`. The full path should also be used in
OQL query strings.
Note that the `Monospaced ([id])` attribute is not permitted for a Sub-Region. Sub-Regions are created with bean names
(/Customer/Address and /Employee/Address, respectively, in this case). So they may be injected into other application
beans, such as a `GemfireTemplate`, that need them by using the full path name of the Region. The full pathname
of the Region should also be used in OQL query strings.
[[bootstrap:region:templates]]
== Region Templates
Spring Data for {data-store-name} also supports region templates. This feature allows developers to define common region
configuration settings and attributes once and reuse the configuration among many region bean definitions declared
in the Spring application context.
{sdg-name} also supports Region templates.
Spring Data for {data-store-name} includes five Region template tags in its namespace:
This feature allows developers to define common Region configuration and attributes once and reuse the configuration
among many Region bean definitions declared in the Spring `ApplicationContext`.
{sdg-name} includes five Region template tags in its namespace:
[cols="1,2", options="header"]
.Region Template Tags
@@ -413,24 +416,24 @@ Spring Data for {data-store-name} includes five Region template tags in its name
| Description
| `<gfe:region-template>`
| Defines common generic region attributes. Extends `regionType` in the namespace.
| Defines common generic Region attributes. Extends `regionType` in the XML namespace.
| `<gfe:local-region-template>`
| Defines common 'Local' region attributes. Extends `localRegionType` in the namespace.
| Defines common 'Local' Region attributes. Extends `localRegionType` in the XML namespace.
| `<gfe:partitioned-region-template>`
| Defines common 'PARTITION' region attributes. Extends `partitionedRegionType` in the namespace.
| Defines common 'PARTITION' Region attributes. Extends `partitionedRegionType` in the XML namespace.
| `<gfe:replicated-region-template>`
| Defines common 'REPLICATE' region attributes. Extends `replicatedRegionType` in the namespace.
| Defines common 'REPLICATE' Region attributes. Extends `replicatedRegionType` in the XML namespace.
| `<gfe:client-region-template>`
| Defines common 'Client' region attributes. Extends `clientRegionType` in the namespace.
| Defines common 'Client' Region attributes. Extends `clientRegionType` in the XML namespace.
|===
In addition to the tags, concrete `<gfe:*-region>` elements (along with the abstract `<gfe:*-region-template>` elements)
have a `template` attribute used to define the region template from which the region inherits its configuration.
Region templates may even inherit from other region templates.
have a `template` attribute used to define the Region template from which the Region inherits its configuration.
Region templates may even inherit from other Region templates.
The following example shows one possible configuration:
@@ -476,48 +479,48 @@ The following example shows one possible configuration:
</beans>
----
Region templates work for subregions as well. Notice that 'TemplateBasedPartitionRegion'
extends 'PartitionRegionTemplate', which extends 'ExtendedRegionTemplate', which extends 'BaseRegionTemplate'.
Attributes and sub-elements defined in subsequent, inherited region bean definitions override what is in the parent.
Region templates work for Sub-Regions as well. Notice that 'TemplateBasedPartitionRegion' extends 'PartitionRegionTemplate',
which extends 'ExtendedRegionTemplate', which extends 'BaseRegionTemplate'. Attributes and sub-elements defined in
subsequent, inherited Region bean definitions override what is in the parent.
=== How Templating Works
Spring Data for {data-store-name} applies region templates when the Spring application context configuration meta-data is parsed,
and therefore, the region templates must be declared in the order of inheritance. In other words, parent templates must be defined
before child templates. Doing so ensures that the proper configuration is applied, especially when element attributes or sub-elements
are overridden.
{sdg-name} applies Region templates when the Spring `ApplicationContext` configuration metadata is parsed, and therefore,
Region templates must be declared in the order of inheritance. In other words, parent templates must be defined before
child templates. Doing so ensures that the proper configuration is applied, especially when element attributes
or sub-elements are overridden.
IMPORTANT: It is equally important to remember that the Region types must only inherit from other similarly typed regions.
IMPORTANT: It is equally important to remember that the Region types must only inherit from other similarly typed Regions.
For instance, it is not possible for a `<gfe:replicated-region>` to inherit from a `<gfe:partitioned-region-template>`.
NOTE: Region Templates are single-inheritance.
NOTE: Region templates are single-inheritance.
[[bootstrap:region:regions-subregions-lookups-caution]]
=== Caution concerning Regions, Subregions and Lookups
=== Caution concerning Regions, Sub-Regions and Lookups
Previously, one of the underlying properties of the `replicated-region`, `partitioned-region`, `local-region`,
and `client-region` elements in the Spring Data for {data-store-name} XML namespace was to perform a lookup first before
attempting to create a Region. This was done in case the region already existed, which would be the case
if the region was defined in an imported {data-store-name} native `cache.xml` configuration file. Therefore, the lookup
was performed first to avoid any errors. This was by design and subject to change.
and `client-region` elements in the {sdg-name} XML namespace was to perform a lookup first before attempting to
create a Region. This was done in case the Region already existed, which would be the case if the Region was defined
in an imported {data-store-name} native `cache.xml` configuration file. Therefore, the lookup was performed first
to avoid any errors. This was by design and subject to change.
This behavior has been altered and the default behavior is now to create the region first. If the region
This behavior has been altered and the default behavior is now to create the Region first. If the Region
already exists, then the creation logic fails-fast and an appropriate exception is thrown. However, much like the
`CREATE TABLE IF NOT EXISTS ...` DDL syntax, the Spring Data for {data-store-name} `<*-region>` namespace elements now include
a `ignore-if-exists` attribute, which reinstates the old behavior by first performing a lookup of an existing region
identified by name. If an existing region is found by name if and `ignore-if-exists` is set to `true`, then
the region bean definition defined in the Spring configuration is ignored.
`CREATE TABLE IF NOT EXISTS ...` DDL syntax, the {sdg-name} `<gfe:*-region>` XML namespace elements now include
a `ignore-if-exists` attribute, which reinstates the old behavior by first performing a lookup of an existing Region
identified by name before attempting to create the Region. If an existing Region is found by name and `ignore-if-exists`
is set to `true`, then the Region bean definition defined in Spring configuration is ignored.
WARNING: The Spring team highly recommends that the `replicated-region`, `partitioned-region`, `local-region`,
and `client-region` namespace elements be strictly used for defining new regions only. One problem that could arise
if the regions defined by these elements already exist and the Region elements perform a lookup first is, if
you defined different region semantics and behaviors for eviction, expiration, subscription, and so on in your
and `client-region` XML namespace elements be strictly used for defining new Regions only. One problem that could arise
when the Regions defined by these elements already exist and the Region elements perform a lookup first is, if
you defined different Region semantics and behaviors for eviction, expiration, subscription, and so on in your
application config, then the Region definition might not match and could exhibit contrary behaviors to those required
by the application. Even worse, you might want to define the region as a distributed region
(for example, `PARTITION`) when, in fact, the existing Region definition is `LOCAL`.
by the application. Even worse, you might want to define the Region as a distributed Region (for example, `PARTITION`)
when, in fact, the existing Region definition is local only.
IMPORTANT: Recommended Practice - Use only `replicated-region`, `partitioned-region`, `local-region`, and `client-region`
namespace elements to define new Regions.
XML namespace elements to define new Regions.
Consider the following native {data-store-name} `cache.xml` configuration file:
@@ -555,7 +558,7 @@ public class CustomerAccountDao extends GemDaoSupport {
Here, we inject a reference to the `Customers/Accounts` Region in our application DAO. Consequently, it is
not uncommon for a developer to define beans for some or all of these Regions in Spring XML configuration
meta-data as follows:
metadata as follows:
[source,xml]
[subs="verbatim,attributes"]
@@ -577,10 +580,10 @@ meta-data as follows:
</beans>
----
The `Customers/Accounts` and `Customers/Accounts/Orders` regions are referenced as beans in the Spring
application context as `Customers/Accounts` and `Customers/Accounts/Orders`, respectively. The nice thing about
using the `lookup-region` element and the corresponding syntax (described earlier) is that it lets you
reference a subregion directly without unnecessarily defining a bean for the parent region (`Customers`, in this case).
The `Customers/Accounts` and `Customers/Accounts/Orders` Regions are referenced as beans in the Spring container
as `Customers/Accounts` and `Customers/Accounts/Orders`, respectively. The nice thing about using the `lookup-region`
element and the corresponding syntax (described earlier) is that it lets you reference a Sub-Region directly without
unnecessarily defining a bean for the parent Region (`Customers`, in this case).
Consider the following bad example, which changes the configuration metadata syntax to use the nested format:
@@ -593,7 +596,7 @@ Consider the following bad example, which changes the configuration metadata syn
</gfe:lookup-region>
----
Now consider another bad example, in which uses the top-level `replicated-region` element along with
Now consider another bad example which uses the top-level `replicated-region` element along with
the `ignore-if-exists` attribute set to perform a lookup first:
[source,xml]
@@ -605,18 +608,19 @@ the `ignore-if-exists` attribute set to perform a lookup first:
</gfe:replicated-region>
----
The Region beans defined in the Spring application context consist of the following:
The Region beans defined in the Spring `ApplicationContext` consist of the following:
`{ "Customers", "/Customers/Accounts", "/Customers/Accounts/Orders" }.` This means the dependency injected reference
shown in the earlier example (that is, `@Resource(name = "Customers/Accounts"))` is now broken, since no bean with name `Customers/Accounts`
is actually defined. For this reason, you should not configure regions as shown in the two preceding examples.
shown in the earlier example (that is, `@Resource(name = "Customers/Accounts")`) is now broken, since no bean with name
`Customers/Accounts` is actually defined. For this reason, you should not configure Regions as shown in
the two preceding examples.
{data-store-name} is flexible in referencing both parent regions and subregions with or without the leading forward slash.
For example, the parent can be referenced as `/Customers` or `Customers` and the child as `/Customers/Accounts`
or `Customers/Accounts`. However, Spring Data {data-store-name} is very specific when it comes to naming beans after regions. It
always uses the forward slash (/) to represent subregions (for example, `/Customers/Accounts`).
{data-store-name} is flexible in referencing both parent Regions and Sub-Regions with or without the leading forward
slash. For example, the parent can be referenced as `/Customers` or `Customers` and the child as `/Customers/Accounts`
or `Customers/Accounts`. However, {sdg-name} is very specific when it comes to naming beans after Regions. It always
uses the forward slash (/) to represent Sub-Regions (for example, `/Customers/Accounts`).
Therefore, you should use the nested `lookup-region` syntax shown earlier
or define direct references with a leading forward slash (/), as follows:
Therefore, you should use the non-nested `lookup-region` syntax shown earlier or define direct references with
a leading forward slash (/), as follows:
[source,xml]
----
@@ -624,10 +628,10 @@ or define direct references with a leading forward slash (/), as follows:
<gfe:lookup-region name="/Customers/Accounts/Orders"/>
----
The earlier example, where the nested `replicated-region` elements were used to reference the subregions, shows
the problem stated earlier. Are the customers, accounts and orders regions and subregions persistent or not?
They are not persistent, because the regions were defined in the native {data-store-name} `cache.xml` configuration file as `REPLICATES` and exist
before the cache is initialized (once the `<gfe:cache>` bean is processed).
The earlier example, where the nested `replicated-region` elements were used to reference the Sub-Regions, shows
the problem stated earlier. Are the Customers, Accounts and Orders Regions and Sub-Regions persistent or not?
They are not persistent, because the Regions were defined in the native {data-store-name} `cache.xml` configuration file
as `REPLICATE` and exist before the cache bean is initialized (once the `<gfe:cache>` element is processed).
[[bootstrap:region:eviction]]
== Data Eviction (with Overflow)
@@ -637,8 +641,8 @@ Currently, in {data-store-name}, eviction applies to the Least Recently Used ent
http://en.wikipedia.org/wiki/Cache_algorithms#Least_Recently_Used[LRU]). Evicted entries are either destroyed
or paged to disk (referred to as "`overflow to disk`").
Spring Data for {data-store-name} supports all eviction policies (entry count, memory, and heap usage) for PARTITION regions,
REPLICATE regions, and client, local regions by using the nested `eviction` element.
{sdg-name} supports all eviction policies (entry count, memory, and heap usage) for PARTITION Regions, REPLICATE Regions,
and client, local Regions by using the nested `eviction` element.
For example, to configure a PARTITION Region to overflow to disk if the memory size exceeds more than 512 MB,
you can specify the following configuration:
@@ -653,7 +657,7 @@ you can specify the following configuration:
IMPORTANT: Replicas cannot use `local destroy` eviction since that would invalidate them.
See the {data-store-name} docs for more information.
When configuring regions for overflow, you should configure the storage through the `disk-store` element
When configuring Regions for overflow, you should configure the storage through the `disk-store` element
for maximum efficiency.
For a detailed description of eviction policies, see the {data-store-name} documentation on
@@ -666,20 +670,20 @@ For a detailed description of eviction policies, see the {data-store-name} docum
as opposed to eviction, which is driven by the entry count or heap or memory usage. Once an entry expires,
it may no longer be accessed from the cache.
{data-store-name} supports the following Expiration types:
{data-store-name} supports the following expiration types:
* *Time-to-Live (TTL)*: The amount of time in seconds that an 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.
the Region is created and when an entry has its counter reset.
* *Idle Timeout (TTI)*: The amount of time in seconds that an 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 to entries in the region. Spring Data for {data-store-name} provides `<region-ttl>`,
`<region-tti>`, `<entry-ttl>`, and `<entry-tti>` region child elements to specify timeout values and expiration actions.
Each of these may be applied to the Region itself or to entries in the Region. {sdg-name} provides `<region-ttl>`,
`<region-tti>`, `<entry-ttl>`, and `<entry-tti>` Region child elements to specify timeout values and expiration actions.
The following example shows a partition region with expiration values set:
The following example shows a `PARTITION` Region with expiration values set:
[source,xml]
----
@@ -695,9 +699,9 @@ For a detailed description of expiration policies, see the {data-store-name} doc
[[bootstrap:region:expiration:annotation]]
=== Annotation-based Data Expiration
With Spring Data for {data-store-name}, you can define expiration policies and settings on individual
region entry values (or, to put it differently, directly on application domain objects). For instance, you can define Expiration
settings on a Session-based application domain object as follows:
With {sdg-name}, you can define expiration policies and settings on individual Region entry values (or, to put
it differently, directly on application domain objects). For instance, you can define expiration policies on
a Session-based application domain object as follows:
[source,java]
----
@@ -707,9 +711,9 @@ public class SessionBasedApplicationDomainObject {
}
----
You can also specify expiration type specific settings on region entries by using the
`@IdleTimeoutExpiration` and `@TimeToLiveExpiration` annotations for Idle Timeout (TTI) and Time-to-Live (TTL)
expiration, respectively, as the following example shows:
You can also specify expiration type specific settings on Region entries by using the `@IdleTimeoutExpiration`
and `@TimeToLiveExpiration` annotations for Idle Timeout (TTI) and Time-to-Live (TTL) expiration, respectively,
as the following example shows:
[source,java]
----
@@ -722,15 +726,15 @@ public class AnotherSessionBasedApplicationDomainObject {
----
Both `@IdleTimeoutExpiration` and `@TimeToLiveExpiration` take precedence over the generic `@Expiration` annotation
when more than one expiration annotation type is specified, as shown in the preceding example. Neither `@IdleTimeoutExpiration`
nor `@TimeToLiveExpiration` overrides the other. Rather, they compliment each other when different region entry
expiration types, such as TTL and TTI, are configured.
when more than one expiration annotation type is specified, as shown in the preceding example. Neither
`@IdleTimeoutExpiration` nor `@TimeToLiveExpiration` overrides the other. Rather, they compliment each other
when different Region entry expiration policies, such as TTL and TTI, are configured.
[NOTE]
====
All `@Expiration`-based annotations apply only to region entry values. Expiration for a region is not covered
by Spring Data for {data-store-name}'s expiration annotation support. However, {data-store-name} and Spring Data for {data-store-name} do let you
set region expiration by using the SDG XML namespace, as follows:
All `@Expiration`-based annotations apply only to Region entry values. Expiration for a Region is not covered by
{sdg-name}'s expiration annotation support. However, {data-store-name} and {sdg-name} do let you set Region expiration
by using the {sdg-acronym} XML namespace, as follows:
[source,xml]
----
@@ -741,22 +745,22 @@ set region expiration by using the SDG XML namespace, as follows:
----
====
Spring Data for {data-store-name}'s `@Expiration` annotation support is implemented with {data-store-name}'s
{sdg-name}'s `@Expiration` annotation support is implemented with {data-store-name}'s
{x-data-store-javadoc}/org/apache/geode/cache/CustomExpiry.html[`CustomExpiry`] interface.
See {data-store-name}'s documentation on {x-data-store-docs}/developing/expiration/configuring_data_expiration.html[configuring data expiration]
for more details
The Spring Data for {data-store-name} `AnnotationBasedExpiration` class (and `CustomExpiry` implementation) is responsible
for processing the SDG `@Expiration` annotations and applying the expiration policy and settings appropriately
for region entry expiration on request.
The {sdg-name} `AnnotationBasedExpiration` class (and `CustomExpiry` implementation) is responsible for processing
the {sdg-acronym} `@Expiration` annotations and applying the expiration policy configuration appropriately for Region
entry expiration on request.
To use Spring Data for {data-store-name} to configure specific {data-store-name} Regions to appropriately apply the Expiration policy
and settings applied to your application domain objects annotated with `@Expiration`-based annotations, you must:
To use {sdg-name} to configure specific {data-store-name} Regions to appropriately apply the expiration policy to
your application domain objects annotated with `@Expiration`-based annotations, you must:
. Define a bean in the Spring `ApplicationContext` of type `AnnotationBasedExpiration` by using the appropriate
constructor or one of the convenient factory methods. When configuring expiration for a specific expiration type,
such as Idle Timeout or Time-to-Live, you should use one of the factory methods in the
`AnnotationBasedExpiration` class, as follows:
such as Idle Timeout (TTI) or Time-to-Live (TTL), you should use one of the factory methods in
the `AnnotationBasedExpiration` class, as follows:
+
[source,xml]
----
@@ -774,14 +778,14 @@ To configure Idle Timeout (TTI) Expiration instead, use the `forIdleTimeout` fac
along with the `<gfe:custom-entry-tti ref="ttiExpiration"/>` element to set TTI.
====
. (optional) Annotate your application domain objects that are stored in the region with expiration policies
and custom settings by using one of Spring Data for {data-store-name}'s `@Expiration` annotations: `@Expiration`,
`@IdleTimeoutExpiration`, or `@TimeToLiveExpiration`
. (optional) Annotate your application domain objects that are stored in the Region with expiration policies
and custom settings by using one of {sdg-name}'s `@Expiration` annotations: `@Expiration`, `@IdleTimeoutExpiration`,
or `@TimeToLiveExpiration`
. (optional) In cases where particular application domain objects have not been annotated with Spring Data for {data-store-name}'s
`@Expiration` annotations at all, but the {data-store-name} Region is configured to use SDG's custom `AnnotationBasedExpiration`
class to determine the Expiration policy and settings for objects stored in the Region, you can set
"`default`" expiration attributes on the `AnnotationBasedExpiration` bean by doing the following:
. (optional) In cases where particular application domain objects have not been annotated with {sdg-name}'s
`@Expiration` annotations at all, but the {data-store-name} Region is configured to use {sdg-acronym}'s custom
`AnnotationBasedExpiration` class to determine the expiration policy and settings for objects stored in the Region,
you can set "`default`" expiration attributes on the `AnnotationBasedExpiration` bean by doing the following:
[source,xml]
----
@@ -800,14 +804,14 @@ class to determine the Expiration policy and settings for objects stored in the
</gfe:partitioned-region>
----
You may have noticed that Spring Data for {data-store-name}'s `@Expiration` annotations use a `String` as the attribute type rather
than, and perhaps more appropriately, being strongly typed -- for example, `int` for 'timeout' and SDG'S `ExpirationActionType`
for 'action'. Why is that?
You may have noticed that {sdg-name}'s `@Expiration` annotations use a `String` as the attribute type rather
than, and perhaps more appropriately, being strongly typed -- for example, `int` for 'timeout' and {sdg-acronym}'s
`ExpirationActionType` for 'action'. Why is that?
Well, enter one of Spring Data for {data-store-name}'s other features, leveraging Spring's core infrastructure
for configuration convenience: property placeholders and the Spring Expression Language (SpEL).
Well, enter one of {sdg-name}'s other features, leveraging Spring's core infrastructure for configuration convenience:
property placeholders and Spring Expression Language (SpEL) expressions.
For instance, a developer can specify both the expiration 'timeout' and 'action' by using Property Placeholders
For instance, a developer can specify both the expiration 'timeout' and 'action' by using property placeholders
in the `@Expiration` annotation attributes, as the following example shows:
[source,java]
@@ -832,12 +836,12 @@ Then, in your Spring XML config or in JavaConfig, you can declare the following
<context:property-placeholder properties-ref="expirationProperties"/>
----
This is convenient both when multiple application domain objects might share similar expiration policies and settings
and when you wish to externalize the configuration.
This is convenient both when multiple application domain objects might share similar expiration policies and when
you wish to externalize the configuration.
However, you may want more dynamic expiration configuration determined by the state of the running system.
This is where the power of SpEL comes in and is the recommended approach, actually. Not only can you refer to beans
in the Spring context and access bean properties, invoke methods, and so on, but the values for Expiration 'timeout'
However, you may want more dynamic expiration configuration determined by the state of the running system. This is where
the power of SpEL comes into play and is the recommended approach, actually. Not only can you refer to beans
in the Spring container and access bean properties, invoke methods, and so on, but the values for expiration 'timeout'
and 'action' can be strongly typed. Consider the following example (which builds on the preceding example):
[source,xml]
@@ -864,23 +868,23 @@ public class ExampleApplicationDomainObject {
----
You can imagine that the 'expirationSettings' bean could be a more interesting and useful object than a simple
instance of `java.util.Properties`. In the preceding example, the `properties` element (`expirationSettings`) uses SpEL to base
the action value on the actual expiration action enumerated type, leading to more quickly identified failures
if the types ever change.
instance of `java.util.Properties`. In the preceding example, the `properties` element (`expirationSettings`) uses SpEL
to base the action value on the actual `ExpirationAction` enumerated type, quickly leading to identified failures
if the enumerated type ever changes.
As an example, all of this has been demonstrated and tested in the Spring Data for {data-store-name} test suite. See the
As an example, all of this has been demonstrated and tested in the {sdg-name} test suite. See the
https://github.com/spring-projects/spring-data-geode[source] for further details.
[[bootstrap:region:persistence]]
== Data Persistence
Regions can be persistent. {data-store-name} ensures that all the data you put into a region that is configured for persistence
is written to disk in a way that is recoverable the next time you recreate the region. Doing so lets data
be recovered after machine or process failure or even after an orderly shutdown and subsequent restart of
Regions can be persistent. {data-store-name} ensures that all the data you put into a Region that is configured
for persistence is written to disk in a way that is recoverable the next time you recreate the Region. Doing so lets
data be recovered after machine or process failure or even after an orderly shutdown and subsequent restart of
the {data-store-name} data node.
To enable persistence with Spring Data for {data-store-name}, set the `persistent` attribute to `true` on
any of the `<*-region>` elements, as the following example shows:
To enable persistence with {sdg-name}, set the `persistent` attribute to `true` on any of the `<*-region>` elements,
as the following example shows:
[source,xml]
----
@@ -888,20 +892,21 @@ any of the `<*-region>` elements, as the following example shows:
----
Persistence may also be configured by setting the `data-policy` attribute. To do so, set the attribute's value to one of
{x-data-store-javadoc}/org/apache/geode/cache/DataPolicy.html[{data-store-name}'s DataPolicy settings], as the folloiwng example shows:
{x-data-store-javadoc}/org/apache/geode/cache/DataPolicy.html[{data-store-name}'s DataPolicy settings],
as the following example shows:
[source,xml]
----
<gfe:partitioned-region id="anotherExamplePersistentPartitionRegion" data-policy="PERSISTENT_PARTITION"/>
----
The `DataPolicy` must match the region type and must also agree with the `persistent` attribute if it is also explicitly set.
If the `persistent` attribute is set to `false` but a persistent `DataPolicy`
The `DataPolicy` must match the Region type and must also agree with the `persistent` attribute if it is also
explicitly set. If the `persistent` attribute is set to `false` but a persistent `DataPolicy`
was specified (such as `PERSISTENT_REPLICATE` or `PERSISTENT_PARTITION`), an initialization exception is thrown.
When persisting regions, for maximum efficiency, you should configure the storage through the `disk-store` element.
The `DiskStore` is referenced by using the `disk-store-ref` attribute. Additionally, the region
may perform disk writes synchronously or asynchronously. The following example shows a synchronous `DiskStore`:
For maximum efficiency when persisting Regions, you should configure the storage through the `disk-store` element.
The `DiskStore` is referenced by using the `disk-store-ref` attribute. Additionally, the Region may perform disk writes
synchronously or asynchronously. The following example shows a synchronous `DiskStore`:
[source,xml]
----
@@ -915,8 +920,9 @@ This is discussed further in <<bootstrap:diskstore>>.
== Subscription Policy
{data-store-name} allows configuration of {x-data-store-docs}/developing/events/configure_p2p_event_messaging.html[peer-to-peer (P2P) event messaging]
to control the entry events that the region receives. Spring Data for {data-store-name} provides the `<gfe:subscription/>`
sub-element to set the subscription policy on `REPLICATE` and `PARTITION` regions to either `ALL` or `CACHE_CONTENT`. The following example shows a region with its subscription policy set to `CACHE_CONTENT`:
to control the entry events that the Region receives. {sdg-name} provides the `<gfe:subscription/>` sub-element to set
the subscription policy on `REPLICATE` and `PARTITION` Regions to either `ALL` or `CACHE_CONTENT`. The following example
shows a region with its subscription policy set to `CACHE_CONTENT`:
[source,xml]
----
@@ -928,32 +934,33 @@ sub-element to set the subscription policy on `REPLICATE` and `PARTITION` region
[[bootstrap:region:local]]
== Local Region
Spring Data for {data-store-name} offers a dedicated `local-region` element for creating local regions. Local regions, as the name
implies, are standalone, meaning that they do not share data with any other distributed system member. Other than that,
all common region configuration options apply.
{sdg-name} offers a dedicated `local-region` element for creating local Regions. Local Regions, as the name implies,
are standalone, meaning that they do not share data with any other distributed system member. Other than that, all
common Region configuration options apply.
The following example shows a minimal declaration (again, the example relies on the Spring Data for {data-store-name} namespace
naming conventions to wire the cache):
The following example shows a minimal declaration (again, the example relies on the {sdg-name} XML namespace naming
conventions to wire the cache):
[source,xml]
----
<gfe:local-region id="exampleLocalRegion"/>
----
In the preceding example, a local region is created (if one does not already exist). The name of the region is the same as the bean ID
(`exampleLocalRegion`), and the bean assumes the existence of a {data-store-name} cache named `gemfireCache`.
In the preceding example, a local Region is created (if a Region by the same name does not already exist). The name of
the Region is the same as the bean ID (`exampleLocalRegion`), and the bean assumes the existence of a {data-store-name}
cache named `gemfireCache`.
[[bootstrap:region:replicate]]
== Replicated Region
One of the common region types is a `REPLICATE` region or "`replica`". In short, when a region is configured to be
a `REPLICATE`, every member that hosts the region stores a copy of the region's entries locally. Any update to
a `REPLICATE` region is distributed to all copies of the region. When a replica is created, it goes through
One of the common Region types is a `REPLICATE` Region or "`replica`". In short, when a Region is configured to be
a `REPLICATE`, every member that hosts the Region stores a copy of the Region's entries locally. Any update to
a `REPLICATE` 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.
All common configuration options are available for REPLICATE Regions.
Spring Data for {data-store-name} offers a `replicated-region` element. The following example shows a minimal declaration:
All common configuration options are available for REPLICATE Regions. {sdg-name} offers a `replicated-region` element.
The following example shows a minimal declaration:
[source,xml]
----
@@ -967,22 +974,22 @@ for more details.
[[bootstrap:region:partition]]
== Partitioned Region
The Spring Data for {data-store-name} namespace also supports `PARTITION` regions.
The {sdg-name} XML namespace also supports `PARTITION` Regions.
To quote the {data-store-name} 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. {data-store-name} 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 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. {data-store-name}
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 by using the `partitioned-region` element. Its configuration options are similar to that of
the `replicated-region` with the addition of partition-specific features, such as the number of redundant copies,
A `PARTITION` Region is created by using the `partitioned-region` element. Its configuration options are similar to
that of the `replicated-region` with the addition of partition-specific features, such as the number of redundant copies,
total maximum memory, number of buckets, partition resolver, and so on.
The following example shows how to set up a `PARTITION` region with two redundant copies:
The following example shows how to set up a `PARTITION` Region with two redundant copies:
[source,xml]
----
@@ -1001,7 +1008,8 @@ for more details.
=== Partitioned Region Attributes
The following table offers a quick overview of configuration options specific to `PARTITION` Regions.
These options are in addition to the common region configuration options described <<bootstrap:region:attributes, earlier>>.
These options are in addition to the common Region configuration options
described <<bootstrap:region:attributes, earlier>>.
[cols="1,2,2", options="header"]
.partitioned-region attributes
@@ -1017,7 +1025,7 @@ meaning there is no redundancy. Each copy provides extra backup at the expense o
| colocated-with
| valid region name
| The name of the `PARTITION` region with which this newly created `PARTITION` region is collocated.
| The name of the `PARTITION` region with which this newly created `PARTITION` Region is collocated.
| local-max-memory
| positive integer
@@ -1050,16 +1058,16 @@ immediately when a new member is added.
[[bootstrap:region:client]]
== Client Region
{data-store-name} supports various deployment topologies for managing and distributing data. The topic of {data-store-name} topologies is outside
the scope of this documentation. However, to quickly recap, {data-store-name}'s supported topologies can be classified as:
peer-to-peer (p2p), client-server, and wide area network (WAN). In the last two configurations, it is common
to declare client regions that connect to a cache server.
{data-store-name} supports various deployment topologies for managing and distributing data. The topic of
{data-store-name} topologies is beyond the scope of this documentation. However, to quickly recap, {data-store-name}'s
supported topologies can be classified as: peer-to-peer (p2p), client-server, and wide area network (WAN). In the last
two configurations, it is common to declare client Regions that connect to a cache server.
Spring Data for {data-store-name} offers dedicated support for each configuration through its <<bootstrap:cache:client, client-cache>> elements:
`client-region` and `pool`. As the names imply, `client-region` defines a client region, while `pool` defines
a pool of connections to be used and shared by the various client regions.
{sdg-name} offers dedicated support for each configuration through its <<bootstrap:cache:client, client-cache>> elements:
`client-region` and `pool`. As the names imply, `client-region` defines a client Region, while `pool` defines
a Pool of connections used and shared by the various client Regions.
The following example shows a typical client region configuration:
The following example shows a typical client Region configuration:
[source,xml]
----
@@ -1081,24 +1089,25 @@ The following example shows a typical client region configuration:
</gfe:pool>
----
As with the other region types, `client-region` supports `CacheListener` instances as well as a `CacheLoader` and a `CacheWriter`.
It also requires a connection `Pool` for connecting to a set of either locators or servers.
Each client region can have its own `Pool`, or they can share the same one.
As with the other Region types, `client-region` supports `CacheListener` instances as well as a `CacheLoader`
and a `CacheWriter`. It also requires a connection `Pool` for connecting to a set of either Locators or servers.
Each client Region can have its own `Pool`, or they can share the same one. If a Pool is not specified, then
the "DEFAULT" Pool will be used.
NOTE: In the preceding example, the `Pool` is configured with a `locator`. A locator is a separate process used to discover
NOTE: In the preceding example, the `Pool` is configured with a Locator. A Locator is a separate process used to discover
cache servers and peer data members in the distributed system and is recommended for production systems. It is also
possible to configure the `Pool` to connect directly to one or more cache servers by using the `server` element.
For a full list of options to set on the client and especially on the `Pool`, see
the Spring Data for {data-store-name} schema ("`<<appendix-schema>>`") and {data-store-name}'s documentation on
the {sdg-name} schema ("`<<appendix-schema>>`") and {data-store-name}'s documentation on
{x-data-store-docs}/topologies_and_comm/cs_configuration/chapter_overview.html[Client-Server Configuration].
[[bootstrap:region:client:interests]]
=== Client Interests
To minimize network traffic, each client can separately define its own 'interests' policies, indicating to {data-store-name}
the data it actually requires. In Spring Data for {data-store-name}, 'interests' can be defined for each client region separately.
Both key-based and regular expression-based interest types are supported.
To minimize network traffic, each client can separately define its own 'interests' policies, indicating to
{data-store-name} the data it actually requires. In {sdg-name}, 'interests' can be defined for each client Region
separately. Both key-based and regular expression-based interest types are supported.
The following example shows both key-based and regular expression-based `interest` types:
@@ -1114,24 +1123,26 @@ The following example shows both key-based and regular expression-based `interes
</gfe:client-region>
----
A special key, `ALL_KEYS`, means 'interest' is registered for all keys. The same can be accomplished by using a regex
of `".\*"`.
A special key, `ALL_KEYS`, means 'interest' is registered for all keys. The same can be accomplished
by using the regular expression, `".\*"`.
The `<gfe:*-interest>` key and regular expression elements support three attributes: `durable`, `receive-values`,
and `result-policy`.
`durable` indicates whether the 'interest' policy and subscription queue created for the client when the client connects
to one or more servers in the cluster is maintained across client sessions. If the client goes away and comes back,
a `durable` subscription queue on the servers for the client is maintained while the client is disconnected.
When the client reconnects, the client receives any events that occurred while the client was disconnected
from the servers in the cluster.
a `durable` subscription queue on the servers for the client is maintained while the client is disconnected. When the
client reconnects, the client receives any events that occurred while the client was disconnected from the servers
in the cluster.
A subscription queue on the servers in the cluster is maintained for each `Pool` of connections defined in the client
where a subscription has also been "`enabled`" for that `Pool`. The subscription queue is used to store (and possibly
conflate) events sent to the client. If the subscription queue is durable, it persists between client sessions
(that is, connections), potentially up to a specified timeout (if the client does not return within a given time frame
in order to reduce resource consumption on servers in the cluster). If the subscription queue is not `durable`,
it is destroyed when the client disconnects. You need to decide whether your client should receive events that came while it was disconnected or if it needs to receive only the latest events after it reconnects.
(that is, connections), potentially up to a specified timeout. If the client does not return within a given time frame
the client Pool subscription queue is destroyed in order to reduce resource consumption on servers in the cluster.
If the subscription queue is not `durable`, it is destroyed immediately when the client disconnects. You need to decide
whether your client should receive events that came while it was disconnected or if it needs to receive only the latest
events after it reconnects.
The `receive-values` attribute indicates whether or not the entry values are received for create and update events.
If `true`, values are received. If `false`, only invalidation events are received.
@@ -1141,7 +1152,8 @@ The `result-policy` controls the initial dump when the client first connects to
essentially seeding the client with events for all the entries that match the interest policy.
Client-side interest registration does not do much good without enabling subscription on the `Pool`, as mentioned earlier.
In fact, it is an error to attempt interest registration without subscription enabled. The following example shows how to do so:
In fact, it is an error to attempt interest registration without subscription enabled. The following example shows
how to do so:
[source,xml]
----
@@ -1151,18 +1163,17 @@ In fact, it is an error to attempt interest registration without subscription en
----
In addition to `subscription-enabled`, can you also set `subscription-ack-interval`,
`subscription-message-tracking-timeout`, and `subscription-redundancy`. `subscription-redundancy` is used to control
how many copies of the subscription queue should be maintained by the servers in the cluster. If redundancy
is greater than one, and the "`primary`" subscription queue (that is, the server) goes down, then a "`secondary`" subscription queue
`subscription-message-tracking-timeout`, and `subscription-redundancy`. `subscription-redundancy` is used to control how
many copies of the subscription queue should be maintained by the servers in the cluster. If redundancy is greater than
one, and the "`primary`" subscription queue (that is, the server) goes down, then a "`secondary`" subscription queue
takes over, keeping the client from missing events in a HA scenario.
In addition to the `Pool` settings, the server-side regions use an additional attribute,
`enable-subscription-conflation`, to control the conflation of events that are sent to the clients. This can also
help further minimize network traffic and is useful in situations where the application only cares about
the latest value of an entry. However, when the application keeps a time series of events that occurred,
conflation is going to hinder that use case. The default value is `false`. The following example shows a region configuration
on the server, for which the client contains a corresponding client `[CACHING_]PROXY` region with interests in keys
in this server region:
In addition to the `Pool` settings, the server-side Regions use an additional attribute, `enable-subscription-conflation`,
to control the conflation of events that are sent to the clients. This can also help further minimize network traffic
and is useful in situations where the application only cares about the latest value of an entry. However, when the
application keeps a time series of events that occurred, conflation is going to hinder that use case. The default value
is `false`. The following example shows a Region configuration on the server, for which the client contains a
corresponding client `[CACHING_]PROXY` Region with interests in keys in this server Region:
[source,xml]
----
@@ -1171,9 +1182,9 @@ in this server region:
</gfe:partitioned-region>
----
To control the amount of time (in seconds) that a "`durable`" subscription queue is maintained after a client is disconnected
from the servers in the cluster, set the `durable-client-timeout` attribute on the `<gfe:client-cache>` element
as follows:
To control the amount of time (in seconds) that a "`durable`" subscription queue is maintained after a client is
disconnected from the servers in the cluster, set the `durable-client-timeout` attribute on the `<gfe:client-cache>`
element as follows:
[source,xml]
----
@@ -1191,28 +1202,27 @@ for more details.
[[bootstrap:region:json]]
== JSON Support
{data-store-name} has support for caching JSON documents in regions, along with the ability to query stored JSON documents
using the {data-store-name} OQL (Object Query Language). JSON documents are stored internally as
{x-data-store-javadoc}/org/apache/geode/pdx/PdxInstance.html[PdxInstance] types by
using the {x-data-store-javadoc}/org/apache/geode/pdx/JSONFormatter.html[JSONFormatter] class
{data-store-name} has support for caching JSON documents in Regions, along with the ability to query stored JSON
documents using the {data-store-name} OQL (Object Query Language). JSON documents are stored internally as
{x-data-store-javadoc}/org/apache/geode/pdx/PdxInstance.html[PdxInstance] types
by using the {x-data-store-javadoc}/org/apache/geode/pdx/JSONFormatter.html[JSONFormatter] class
to perform conversion to and from JSON documents (as a `String`).
Spring Data for {data-store-name} provides the `<gfe-data:json-region-autoproxy/>` element to enable an
http://docs.spring.io/spring/docs/current/spring-framework-reference/htmlsingle/#aop-introduction[AOP]
component to advise appropriate, proxied region operations, which effectively encapsulates the `JSONFormatter`,
thereby letting your applications work directly with JSON Strings.
{sdg-name} provides the `<gfe-data:json-region-autoproxy/>` element to enable an
{spring-framework-docs}/#aop-introduction[AOP] component to advise appropriate, proxied Region operations,
which effectively encapsulates the `JSONFormatter`, thereby letting your applications work directly with JSON Strings.
In addition, Java objects written to JSON configured Regions are automatically converted to JSON using Jackson's
`ObjectMapper`. When these values are read back, they are returned as a JSON String.
By default, `<gfe-data:json-region-autoproxy/>` performs the conversion for all regions. To apply this feature
to selected regions, provide a comma-delimited list of region bean IDs in the `region-refs` attribute.
By default, `<gfe-data:json-region-autoproxy/>` performs the conversion for all Regions. To apply this feature
to selected Regions, provide a comma-delimited list of Region bean IDs in the `region-refs` attribute.
Other attributes include a `pretty-print` flag (defaults to `false`) and `convert-returned-collections`.
Also, by default, the results of the `getAll()` and `values()` Region operations are converted for
configured regions. This is done by creating a parallel data structure in local memory. This can incur
significant overhead for large collections, so set the `convert-returned-collections` to `false`
if you would like to disable automatic conversion for these region operations.
Also, by default, the results of the `getAll()` and `values()` Region operations are converted for configured Regions.
This is done by creating a parallel data structure in local memory. This can incur significant overhead for large
collections, so set the `convert-returned-collections` to `false` if you would like to disable automatic conversion
for these Region operations.
NOTE: Certain Region operations (specifically those that use {data-store-name}'s proprietary `Region.Entry`, such as:
`entries(boolean)`, `entrySet(boolean)` and `getEntry()` type) are not targeted for AOP advice. In addition,

172
src/main/asciidoc/reference/repositories.adoc
View File

@@ -1,17 +1,17 @@
[[gemfire-repositories]]
= Spring Data for {data-store-name} Repositories
= {sdg-name} Repositories
Spring Data for {data-store-name} provides support for using the Spring Data Repository abstraction to easily persist entities
into {data-store-name} along with execute queries. A general introduction to the repository programming model is provided
http://docs.spring.io/spring-data/data-commons/docs/current/reference/html/#repositories[here].
{sdg-name} provides support for using the Spring Data Repository abstraction to easily persist entities into
{data-store-name} along with executing queries. A general introduction to the Repository programming model
is provided http://docs.spring.io/spring-data/data-commons/docs/current/reference/html/#repositories[here].
[[gemfire-repositories.spring-configuration-xml]]
== Spring XML Configuration
To bootstrap Spring Data Repositories, use the `<repositories/>` element from the Spring Data for {data-store-name}
Data namespace, as the following example shows:
To bootstrap Spring Data Repositories, use the `<repositories/>` element from the {sdg-name} Data namespace,
as the following example shows:
.Bootstrap Spring Data for {data-store-name} Repositories in XML
.Bootstrap {sdg-name} Repositories in XML
====
[source,xml]
[subs="verbatim,attributes"]
@@ -30,21 +30,21 @@ Data namespace, as the following example shows:
----
====
The preceding configuration snippet looks for interfaces below the configured base package and creates repository instances
The preceding configuration snippet looks for interfaces below the configured base package and creates Repository instances
for those interfaces backed by a https://docs.spring.io/spring-data/geode/docs/current/api/org/springframework/data/gemfire/repository/support/SimpleGemfireRepository.html[`SimpleGemFireRepository`].
IMPORTANT: The bootstrap process fails unless you have your application domain classes correctly mapped to configured regions.
IMPORTANT: The bootstrap process fails unless you have your application domain classes correctly mapped
to configured Regions.
[[gemfire-repositories.spring-configuration-java]]
== Spring Java-based Configuration
Alternatively, many developers prefer to use Spring's
{spring-framework-docs}/core.html#beans-java[Java-based container configuration].
Alternatively, many developers prefer to use Spring's {spring-framework-docs}/core.html#beans-java[Java-based container configuration].
Using this approach, you can bootstrap Spring Data Repositories by using the SDG `@EnableGemfireRepositories`
Using this approach, you can bootstrap Spring Data Repositories by using the {sdg-acronym} `@EnableGemfireRepositories`
annotation, as the following example shows:
.Bootstrap _Spring Data for {data-store-name} Repositories_ with `@EnableGemfireRepositories`
.Bootstrap {sdg-name} Repositories with `@EnableGemfireRepositories`
====
[source, java]
----
@@ -57,46 +57,46 @@ class SpringDataApplication {
====
Rather than use the `basePackages` attribute, you may prefer to use the type-safe `basePackageClasses` attribute instead.
The `basePackageClasses` lets you specify the package that contains all your application repository classes
by specifying only one of your application repository interface types. Consider creating a special no-op marker class
or interface in each package that serves no purpose other than to identify the location of application repositories
The `basePackageClasses` lets you specify the package that contains all your application Repository classes by
specifying only one of your application Repository interface types. Consider creating a special no-op marker class
or interface in each package that serves no purpose other than to identify the location of application Repositories
referenced by this attribute.
In addition to the `basePackage[sClasses]` attributes, such as Spring's
In addition to the `basePackages and basePackageClasses` attributes, like Spring's
{spring-framework-javadoc}/org/springframework/context/annotation/ComponentScan.html[`@ComponentScan`] annotation,
the `@EnableGemfireRepositories` annotation provides include and exclude filters, based on Spring's
{spring-framework-javadoc}/org/springframework/context/annotation/ComponentScan.Filter.html[`ComponentScan.Filter`] type.
You can use the `filterType` attribute to filter by different aspects, such as whether an application repository type
You can use the `filterType` attribute to filter by different aspects, such as whether an application Repository type
is annotated with a particular annotation or extends a particular class type and so on. See the
{spring-framework-javadoc}/org/springframework/context/annotation/FilterType.html[`FilterType` Javadoc]
for more details.
The `@EnableGemfireRepositories` annotation also lets you specify the location of named OQL queries,
which reside in a Java `Properties` file, by using the `namedQueriesLocation` attribute. The property name must match
the name of a repository query method and the property value is the OQL query you want executed when
the repository query method is called.
The `@EnableGemfireRepositories` annotation also lets you specify the location of named OQL queries, which reside in
a Java `Properties` file, by using the `namedQueriesLocation` attribute. The property name must match the name
of a Repository query method and the property value is the OQL query you want executed when the Repository query method
is called.
The `repositoryImplementationPostfix` attribute can be set to an alternate value (defaults to `Impl`) if your
application requires one or more {spring-data-commons-docs-html}/#repositories.custom-implementations[custom repository implementations].
This feature is commonly used to extend the Spring Data repository infrastructure to implement a feature
not provided by the data store (for example, SDG).
This feature is commonly used to extend the Spring Data Repository infrastructure to implement a feature not provided by
the data store (for example, {sdg-acronym}).
One example of where custom repository implementations are needed with {data-store-name} is when performing joins.
Joins are not supported by SDG repositories. With a {data-store-name} `PARTITION` Region, the join must be
performed on co-located `PARTITION` regions, since {data-store-name} does not support "`distributed`" joins.
In addition, the Equi-Join OQL Query must be performed inside a {data-store-name} function.
Joins are not supported by {sdg-acronym} Repositories. With a {data-store-name} `PARTITION` Region, the join must be
performed on collocated `PARTITION` Regions, since {data-store-name} does not support "`distributed`" joins.
In addition, the Equi-Join OQL Query must be performed inside a {data-store-name} Function.
See http://gemfire91.docs.pivotal.io/geode/developing/partitioned_regions/join_query_partitioned_regions.html[here]
for more details on {data-store-name} _Equi-Join Queries_.
Many other aspects of the SDG's repository infrastructure extension may be customized as well. See the
https://docs.spring.io/spring-data/gemfire/docs/current/api/org/springframework/data/gemfire/repository/config/EnableGemfireRepositories.html[`@EnableGemfireRepositories` Javadoc]
for more details on all configuration settings.
Many other aspects of the {sdg-acronym}'s Repository infrastructure extension may be customized as well. See the
https://docs.spring.io/spring-data/gemfire/docs/current/api/org/springframework/data/gemfire/repository/config/EnableGemfireRepositories.html[`@EnableGemfireRepositories`]
Javadoc for more details on all configuration settings.
[[gemfire-repositories.queries.executing]]
== Executing OQL Queries
Spring Data for {data-store-name} Repositories enable the definition of query methods to easily execute {data-store-name} OQL queries
against the region the managed entity maps to, as the following example shows:
{sdg-name} Repositories enable the definition of query methods to easily execute {data-store-name} OQL queries
against the Region the managed entity maps to, as the following example shows:
.Sample Repository
====
@@ -127,8 +127,8 @@ The first query method listed in the preceding example causes the following OQL
`SELECT x FROM /People x WHERE x.emailAddress = $1`. The second query method works the same way except
it returns all entities found, whereas the first query method expects a single result to be found.
If the supported keywords are not sufficient to express and declare your OQL query, or the method name
becomes too verbose, you can annotate the query methods with `@Query` as shown on the third and fourth methods.
If the supported keywords are not sufficient to declare and express your OQL query, or the method name becomes too
verbose, then you can annotate the query methods with `@Query` as shown on the third and fourth methods.
The following table gives brief samples of the supported keywords that you can use in query methods:
@@ -200,25 +200,25 @@ The following table gives brief samples of the supported keywords that you can u
== OQL Query Extensions Using Annotations
Many query languages, such as {data-store-name}'s OQL (Object Query Language), have extensions that are not directly
supported by Spring Data Commons' repository infrastructure.
supported by Spring Data Commons' Repository infrastructure.
One of Spring Data Commons' repository infrastructure goals is to function as the lowest common denominator
to maintain support for and portability across the widest array of data stores available and in use
for application development today. Technically, this means developers can access multiple different data stores
supported by Spring Data Commons within their applications by reusing their existing application-specific
repository interfaces -- a convenient and powerful abstraction.
One of Spring Data Commons' Repository infrastructure goals is to function as the lowest common denominator to maintain
support for and portability across the widest array of data stores available and in use for application development
today. Technically, this means developers can access multiple different data stores supported by Spring Data Commons
within their applications by reusing their existing application-specific Repository interfaces -- a convenient
and powerful abstraction.
To support {data-store-name}'s OQL Query language extensions and preserve portability across different data stores,
Spring Data for {data-store-name} adds support for OQL Query extensions by using Java annotations. These Annotations are ignored
by other Spring Data repository implementations (such as Spring Data JPA or Spring Data Redis) that do not have
similar query language extensions.
{sdg-name} adds support for OQL Query extensions by using Java annotations. These annotations are ignored by other
Spring Data Repository implementations (such as Spring Data JPA or Spring Data Redis) that do not have similar
query language features.
For instance, many data stores most likely do not implement {data-store-name}'s OQL `IMPORT` keyword. Implementing `IMPORT`
as an annotation (that is, `@Import`) rather than as part of the query method signature (specifically, the method 'name')
does not interfere with the parsing infrastructure when evaluating the query method name to construct
another data store language appropriate query.
does not interfere with the parsing infrastructure when evaluating the query method name to construct another data store
language appropriate query.
Currently, the set of {data-store-name} OQL Query language extensions that are supported by Spring Data for {data-store-name} include:
Currently, the set of {data-store-name} OQL Query language extensions that are supported by {sdg-name} include:
[cols="1,2,2,2", options="header"]
.Supported {data-store-name} OQL extensions for Repository query methods
@@ -249,8 +249,8 @@ Currently, the set of {data-store-name} OQL Query language extensions that are s
| NA
|===
As an example, suppose you have a `Customers` application domain class and corresponding {data-store-name} region along with a
`CustomerRepository` and a query method to lookup `Customers` by last name, as follows:
As an example, suppose you have a `Customers` application domain class and corresponding {data-store-name} Region
along with a `CustomerRepository` and a query method to lookup `Customers` by last name, as follows:
.Sample Customers Repository
====
@@ -296,10 +296,11 @@ The preceding example results in the following OQL Query:
`<TRACE> <HINT 'LastNameIdx'> IMPORT org.example.app.domain.Customer; SELECT * FROM /Customers x WHERE x.lastName = $1 LIMIT 10`
Spring Data for {data-store-name}'s repository extension and support is careful not to create conflicting declarations when
the OQL Annotation extensions are used in combination with the `@Query` annotation.
{sdg-name}'s Repository extension is careful not to create conflicting declarations when the OQL annotation extensions
are used in combination with the `@Query` annotation.
As another example, suppose you have a raw `@Query` annotated query method defined in your `CustomerRepository`, as follows:
As another example, suppose you have a raw `@Query` annotated query method defined in your `CustomerRepository`,
as follows:
.CustomerRepository
====
@@ -318,33 +319,32 @@ public interface CustomerRepository extends GemfireRepository<Customer, Long> {
----
====
The preceding query method results in the following OQL Query:
The preceding query method results in the following OQL query:
`IMPORT org.example.app.domain.Customer; <TRACE> <HINT 'ReputationIdx'> SELECT DISTINCT * FROM /Customers x
WHERE x.reputation > $1 ORDER BY c.reputation DESC LIMIT 5`
The `@Limit(10)` annotation does not override the `LIMIT` defined explicitly in the raw query.
The `@Limit(10)` annotation does not override the `LIMIT` explicitly defined in the raw query.
Also, the `@Hint("CustomerIdx")` annotation does not override the `HINT` explicitly defined in the raw query.
Finally, the `@Trace` annotation is redundant and has no additional effect.
[NOTE]
====
The `ReputationIdx` index is probably not the most sensible index, given the number of customers who may possibly have
the same value for their reputation, which reduces the effectiveness of the index. Please choose
indexes and other optimizations wisely, as an improper or poorly chosen index can have the opposite effect on your
performance because of the overhead in maintaining the index. The `ReputationIdx` was used only to serve the purpose
of the example.
the same value for their reputation, which reduces the effectiveness of the index. Please choose indexes and other
optimizations wisely, as an improper or poorly chosen index can have the opposite effect on your performance because
of the overhead in maintaining the index. The `ReputationIdx` was used only to serve the purpose of the example.
====
[[gemfire-repositories.queries.post-processing]]
== Query Post Processing
Thanks to using the Spring Data repository abstraction, the query method convention for defining data store specific queries
(e.g. OQL) is easy and convenient. However, it is sometimes desirable to still want to inspect or even possibly
modify the query generated from the repository query method.
Thanks to using the Spring Data Repository abstraction, the query method convention for defining data store specific
queries (e.g. OQL) is easy and convenient. However, it is sometimes desirable to still want to inspect or even possibly
modify the query generated from the Repository query method.
Since 2.0.x, Spring Data for {data-store-name} includes the `o.s.d.gemfire.repository.query.QueryPostProcessor`
functional interface. The interface is loosely defined as follows:
Since 2.0.x, {sdg-name} includes the `o.s.d.gemfire.repository.query.QueryPostProcessor` functional interface.
The interface is loosely defined as follows:
.QueryPostProcessor
====
@@ -366,21 +366,21 @@ interface QueryPostProcessor<T extends Repository, QUERY> extends Ordered {
----
====
There are additional default methods provided that let you compose instances of `QueryPostProcessor` similar
to how https://docs.oracle.com/javase/8/docs/api/java/util/function/Function.html#compose-java.util.function.Function-[java.util.function.Function.andThen(:Function)]
There are additional default methods provided that let you compose instances of `QueryPostProcessor` similar to how
https://docs.oracle.com/javase/8/docs/api/java/util/function/Function.html#compose-java.util.function.Function-[java.util.function.Function.andThen(:Function)]
and https://docs.oracle.com/javase/8/docs/api/java/util/function/Function.html#compose-java.util.function.Function-[java.util.function.Function.compose(:Function)]
work.
Additionally, the `QueryPostProcessor` interface implements the
https://docs.spring.io/spring/docs/5.0.2.RELEASE/javadoc-api/org/springframework/core/Ordered.html[`org.springframework.core.Ordered`]
interface, which is useful when multiple `QueryPostProcessors` are declared and registered in the Spring context
and used to create a pipeline of processing for a group of generated query method queries.
{spring-framework-javadoc}/org/springframework/core/Ordered.html[`org.springframework.core.Ordered`] interface,
which is useful when multiple `QueryPostProcessors` are declared and registered in the Spring container and used to
create a pipeline of processing for a group of generated query method queries.
Finally, the `QueryPostProcessor` accepts type arguments corresponding to the type parameters, `T` and `QUERY`,
respectively. Type of `T` extends the Spring Data Commons marker interface,
respectively. Type `T` extends the Spring Data Commons marker interface,
{spring-data-commons-javadoc}/org/springframework/data/repository/Repository.html[`org.springframework.data.repository.Repository`].
We discuss this further later in this section. All `QUERY` type parameter arguments in Spring Data for {data-store-name}'s case
are of type `java.lang.String`.
We discuss this further later in this section. All `QUERY` type parameter arguments in {sdg-name}'s case are of type
`java.lang.String`.
NOTE: It is useful to define the query as type `QUERY`, since this `QueryPostProcessor` interface may be ported to
Spring Data Commons and therefore must handle all forms of queries by different data stores (such as JPA, MongoDB,
@@ -389,8 +389,8 @@ or Redis).
You can implement this interface to receive a callback with the query that was generated from the application
`Repository` interface method when the method is called.
For example, you might want to log all queries from all application repository interface definitions. You could do so by
using the following `QueryPostProcessor` implementation:
For example, you might want to log all queries from all application Repository interface definitions. You could do so
by using the following `QueryPostProcessor` implementation:
.LoggingQueryPostProcessor
====
@@ -416,9 +416,9 @@ class LoggingQueryPostProcessor implements QueryPostProcessor<Repository, String
====
The `LoggingQueryPostProcessor` was typed to the Spring Data `org.springframework.data.repository.Repository`
marker interface, and, therefore, logs all application repository interface query method generated queries.
marker interface, and, therefore, logs all application Repository interface query method generated queries.
You could limit the scope of this logging to queries only from certain types of application repository interfaces,
You could limit the scope of this logging to queries only from certain types of application Repository interfaces,
such as, say, a `CustomerRepository`, as the following example shows:
.CustomerRepository
@@ -445,12 +445,12 @@ class LoggingQueryPostProcessor implements QueryPostProcessor<CustomerRepository
----
====
As a result, only queries defined in the `CustomerRepository` interface (such as `findByAccountNumber`) are logged.
As a result, only queries defined in the `CustomerRepository` interface, such as `findByAccountNumber`, are logged.
You might want to create a `QueryPostProcessor` for a specific query defined by a repository query method. For example,
You might want to create a `QueryPostProcessor` for a specific query defined by a Repository query method. For example,
suppose you want to limit the OQL query generated from the `CustomerRepository.findByLastNameLike(:String)` query method
to only return five results and want to order the `Customers` by `firstName`, ascending. To do so, you can define
a custom `QueryPostProcessor`, as the following example shows:
to only return five results along with ordering the `Customers` by `firstName`, in ascending order . To do so,
you can define a custom `QueryPostProcessor`, as the following example shows:
.OrderedLimitedCustomerByLastNameQueryPostProcessor
====
@@ -478,8 +478,8 @@ class OrderedLimitedCustomerByLastNameQueryPostProcessor implements QueryPostPro
----
====
While the preceding example works, you can achieve the same effect by using the Spring Data repository convention and extensions
provided by Spring Data for {data-store-name}. For instance, the same query could be defined as follows:
While the preceding example works, you can achieve the same effect by using the Spring Data Repository convention
provided by {sdg-name}. For instance, the same query could be defined as follows:
.CustomerRepository using the convention
====
@@ -497,9 +497,9 @@ interface CustomerRepository extends CrudRepository<Customer, Long> {
However, if you do not have control over the application `CustomerRepository` interface definition,
then the `QueryPostProcessor` (that is, `OrderedLimitedCustomerByLastNameQueryPostProcessor`) is convenient.
If you want to ensure that the `LoggingQueryPostProcessor` always comes after the other application-defined `QueryPostProcessors`
that may have declared and registered in the Spring `ApplicationContext`, you can set the `order` property
by overriding the `o.s.core.Ordered.getOrder()` method, as the following example shows:
If you want to ensure that the `LoggingQueryPostProcessor` always comes after the other application-defined
`QueryPostProcessors` that may have bean declared and registered in the Spring `ApplicationContext`, you can set
the `order` property by overriding the `o.s.core.Ordered.getOrder()` method, as the following example shows:
.Defining the `order` property
====
@@ -526,6 +526,6 @@ class CustomerQueryPostProcessor implements QueryPostProcessor<CustomerRepositor
This ensures that you always see the effects of the post processing applied by other `QueryPostProcessors`
before the `LoggingQueryPostProcessor` logs the query.
You can define as many `QueryPostProcessors` in the Spring `ApplicationContext` as you like and apply them in any
order, to all or specific application repository interfaces, and be as granular as you like by using the provided
arguments to the `postProcess(..)` method callback.
You can define as many `QueryPostProcessors` in the Spring `ApplicationContext` as you like and apply them in any order,
to all or specific application Repository interfaces, and be as granular as you like by using the provided arguments
to the `postProcess(..)` method callback.

4
src/main/asciidoc/reference/samples.adoc
View File

@@ -4,7 +4,7 @@
NOTE: Sample applications are now maintained in the
https://github.com/spring-projects/spring-gemfire-examples[Spring {data-store-name} Examples] repository.
The Spring Data for {data-store-name} project also includes one sample application. Named "`Hello World`", the sample application
The {sdg-name} project also includes one sample application. Named "`Hello World`", the sample application
demonstrates how to configure and use {data-store-name} inside a Spring application. At run time, the sample offers
a shell that lets you run various commands against the data grid. It provides an excellent
starting point for developers who are unfamiliar with the essential components or with Spring and {data-store-name} concepts.
@@ -15,7 +15,7 @@ Maven-aware IDE (such as the https://spring.io/tools/sts[Spring Tool Suite]) or
[[samples:hello-world]]
== Hello World
The "`Hello World`" sample application demonstrates the core functionality of the Spring Data for {data-store-name} project.
The "`Hello World`" sample application demonstrates the core functionality of the {sdg-name} project.
It bootstraps {data-store-name}, configures it, executes arbitrary commands against the cache, and shuts it down
when the application exits. Multiple instances of the application can be started at the same time
and work together, sharing data without any user intervention.

46
src/main/asciidoc/reference/serialization.adoc
View File

@@ -2,15 +2,13 @@
= Working with {data-store-name} Serialization
To improve overall performance of the {data-store-name} In-memory Data Grid, {data-store-name} supports a dedicated
serialization protocol, called PDX, that is both faster and offers more compact results over
standard Java serialization in addition to working transparently across various language platforms (Java, C++, and .NET).
See
{x-data-store-docs}/developing/data_serialization/PDX_Serialization_Features.html[PDX Serialization Features]
and
{x-data-store-wiki}/PDX+Serialization+Internals[PDX Serialization Internals]
for more details.
serialization protocol, called PDX, that is both faster and offers more compact results over standard Java serialization
in addition to working transparently across various language platforms (Java, C++, and .NET).
This chapter discusses the various ways in which Spring Data for {data-store-name} simplifies and improves {data-store-name}'s
See {x-data-store-docs}/developing/data_serialization/PDX_Serialization_Features.html[PDX Serialization Features]
and {x-data-store-wiki}/PDX+Serialization+Internals[PDX Serialization Internals] for more details.
This chapter discusses the various ways in which {sdg-name} simplifies and improves {data-store-name}'s
custom serialization in Java.
[[serialization:wiring]]
@@ -19,21 +17,19 @@ custom serialization in Java.
It is fairly common for serialized objects to have transient data. Transient data is often dependent on the system
or environment where it lives at a certain point in time. For instance, a `DataSource` is environment specific.
Serializing such information is useless and potentially even dangerous, since it is local to a certain VM or machine.
For such cases, Spring Data for {data-store-name} offers a special
{x-data-store-javadoc}/org/apache/geode/Instantiator.html[`Instantiator`]
For such cases, {sdg-name} offers a special {x-data-store-javadoc}/org/apache/geode/Instantiator.html[`Instantiator`]
that performs wiring for each new instance created by {data-store-name} during deserialization.
Through such a mechanism, you can rely on the Spring container to inject and manage certain dependencies,
making it easy to split transient from persistent data and have rich domain objects in a transparent manner.
Through such a mechanism, you can rely on the Spring container to inject and manage certain dependencies, making it easy
to split transient from persistent data and have rich domain objects in a transparent manner.
Spring users might find this approach similar to that of
http://docs.spring.io/spring/docs/current/spring-framework-reference/htmlsingle/#aop-atconfigurable[`@Configurable`]).
Spring users might find this approach similar to that of {spring-framework-docs}/#aop-atconfigurable[`@Configurable`]).
The `WiringInstantiator` works similarly to `WiringDeclarableSupport`, trying to first locate a bean definition
as a wiring template and otherwise falling back to autowiring.
as a wiring template and otherwise falling back to auto-wiring.
See the previous section (<<apis:declarable>>) for more details on wiring functionality.
To use this SDG `Instantiator`, declare it as a bean, as the following example shows:
To use the {sdg-acronym} `Instantiator`, declare it as a bean, as the following example shows:
[source,xml]
----
@@ -45,18 +41,18 @@ To use this SDG `Instantiator`, declare it as a bean, as the following example s
</bean>
----
During the Spring container startup, once it is being initialized, the `Instantiator`, by default, registers
itself with the {data-store-name} serialization system and performs wiring on all instances of `SomeDataSerializableClass`
created by {data-store-name} during deserialization.
During the Spring container startup, once it has been initialized, the `Instantiator`, by default, registers itself with
the {data-store-name} serialization system and performs wiring on all instances of `SomeDataSerializableClass` created
by {data-store-name} during deserialization.
[[serialization:instance-generator]]
== Auto-generating Custom `Instantiators`
For data intensive applications, a large number of instances might be created on each machine as data flows in.
{data-store-name} uses reflection to create new types, but, for some scenarios, this might prove to be expensive.
As always, it is good to perform profiling to quantify whether this is the case or not. For such cases,
Spring Data for {data-store-name} allows the automatic generation of `Instatiator` classes, which instantiate a new type
(using the default constructor) without the use of reflection. The following example shows how to create an instantiator:
As always, it is good to perform profiling to quantify whether this is the case or not. For such cases, {sdg-name}
allows the automatic generation of `Instatiator` classes, which instantiate a new type (using the default constructor)
without the use of reflection. The following example shows how to create an instantiator:
[source,xml]
----
@@ -70,6 +66,6 @@ Spring Data for {data-store-name} allows the automatic generation of `Instatiato
</bean>
----
The preceding definition automatically generates two `Instantiators` for two classes (`CustomTypeA`
and `CustomTypeB`) and registers them with {data-store-name} under user ID `1025` and `1026`. The two `Instantiators` avoid
the use of reflection and create the instances directly through Java code.
The preceding definition automatically generates two `Instantiators` for two classes (`CustomTypeA` and `CustomTypeB`)
and registers them with {data-store-name} under user ID `1025` and `1026`. The two `Instantiators` avoid the use of
reflection and create the instances directly through Java code.

139
src/main/asciidoc/reference/snapshot.adoc
View File

@@ -1,22 +1,22 @@
[[bootstrap:snapshot]]
= Configuring the Snapshot Service
Spring Data for {data-store-name} supports `cache` and `region` snapshots by using
{sdg-name} supports cache and Region snapshots by using
{x-data-store-docs}/managing/cache_snapshots/chapter_overview.html[{data-store-name}'s Snapshot Service].
The out-of-the-box Snapshot Service support offers several convenient features to simplify the use of {data-store-name}'s
{x-data-store-javadoc}/org/apache/geode/cache/snapshot/CacheSnapshotService.html[Cache]
and {x-data-store-javadoc}/org/apache/geode/cache/snapshot/RegionSnapshotService.html[Region]
Snapshot Service APIs.
As the {x-data-store-docs}/managing/cache_snapshots/chapter_overview.html[{data-store-name} documentation]
describes, snapshots let you save and subsequently reload the cached data later, which can be useful for
moving data between environments, such as from production to a staging or test environment in order to reproduce
data-related issues in a controlled context. You can combine Spring Data for {data-store-name}'s Snapshot Service support
As the {x-data-store-docs}/managing/cache_snapshots/chapter_overview.html[{data-store-name} documentation] explains,
snapshots let you save and subsequently reload the cached data later, which can be useful for moving data between
environments, such as from production to a staging or test environment in order to reproduce data-related issues
in a controlled context. You can combine {sdg-name}'s Snapshot Service support
with http://docs.spring.io/spring/docs/current/spring-framework-reference/htmlsingle/#beans-definition-profiles[Spring's bean definition profiles]
to load snapshot data specific to the environment as necessary.
Spring Data for {data-store-name}'s support for {data-store-name}'s Snapshot Service begins with the `<gfe-data:snapshot-service>` element
from the `<gfe-data>` namespace.
{sdg-name}'s support for {data-store-name}'s Snapshot Service begins with the `<gfe-data:snapshot-service>` element
from the `<gfe-data>` XML namespace.
For example, you can define cache-wide snapshots to be loaded as well as saved by using a couple of snapshot imports
and a data export definition, as follows:
@@ -31,13 +31,14 @@ and a data export definition, as follows:
</gfe-data:snapshot-service>
----
You can define as many imports and exports as you like. You can define only imports or only exports.
The file locations and directory paths can be absolute or relative to the Spring Data for {data-store-name} application, which is the
JVM process's working directory.
You can define as many imports and exports as you like. You can define only imports or only exports. The file locations
and directory paths can be absolute or relative to the {sdg-name} application, which is the JVM process's
working directory.
The preceding example is pretty simple, and the Snapshot Service defined in this case refers to the {data-store-name} `cache` with
the default name of `gemfireCache` (as described in <<bootstrap:cache>>). If you name your cache bean definition
something other than the default, you can use the `cache-ref` attribute to refer to the cache bean by name, as follows:
The preceding example is pretty simple, and the Snapshot Service defined in this case refers to the {data-store-name}
cache instance with the default name of `gemfireCache` (as described in <<bootstrap:cache>>). If you name your cache
bean definition something other than the default, you can use the `cache-ref` attribute to refer to the cache bean
by name, as follows:
[source,xml]
----
@@ -48,8 +49,7 @@ something other than the default, you can use the `cache-ref` attribute to refer
</gfe-data:snapshot-service>
----
You can also define a Snapshot Service for a particular {data-store-name} Region by specifying
the `region-ref` attribute, as follows:
You can also define a Snapshot Service for a particular Region by specifying the `region-ref` attribute, as follows:
[source,xml]
----
@@ -61,39 +61,37 @@ the `region-ref` attribute, as follows:
</gfe-data:snapshot-service>
----
When the `region-ref` attribute is specified, Spring Data for {data-store-name}'s `SnapshotServiceFactoryBean` resolves
the `region-ref` attribute value to a region bean defined in the Spring context and creates a
When the `region-ref` attribute is specified, {sdg-name}'s `SnapshotServiceFactoryBean` resolves the `region-ref`
attribute value to a Region bean defined in the Spring container and creates a
{x-data-store-javadoc}/org/apache/geode/cache/snapshot/RegionSnapshotService.html[`RegionSnapshotService`].
The snapshot import and export definitions function the same way. However, the `location` must refer to a file
on export.
on an export.
NOTE: {data-store-name} is strict about imported snapshot files actually existing before they are referenced. For exports,
{data-store-name} creates the snapshot file. If the snapshot file for export already exists,
NOTE: {data-store-name} is strict about imported snapshot files actually existing before they are referenced.
For exports, {data-store-name} creates the snapshot file. If the snapshot file for export already exists,
the data is overwritten.
TIP: Spring Data for {data-store-name} includes a `suppress-import-on-init` attribute on the `<gfe-data:snapshot-service>` element
to suppress the configured Snapshot Service from trying to import data into the cache or region on initialization.
Doing so is useful, for example, when data exported from one region is used to feed the import of another region.
TIP: {sdg-name} includes a `suppress-import-on-init` attribute on the `<gfe-data:snapshot-service>` element
to suppress the configured Snapshot Service from trying to import data into the cache or Region on initialization.
Doing so is useful, for example, when data exported from one Region is used to feed the import of another Region.
[[bootstrap:snapshot:location]]
== Snapshot Location
For a `Cache`-based Snapshot Service
With the cache-based Snapshot Service
(that is, a {x-data-store-javadoc}/org/apache/geode/cache/snapshot/CacheSnapshotService.html[`CacheSnapshotService`])
you would typically pass it a directory containing all the snapshot files to load rather than
individual snapshot files, as the overloaded
{x-data-store-javadoc}/org/apache/geode/cache/snapshot/CacheSnapshotService.html#load-java.io.File-org.apache.geode.cache.snapshot.SnapshotOptions.SnapshotFormat[`load`]
you would typically pass it a directory containing all the snapshot files to load rather than individual snapshot files,
as the overloaded {x-data-store-javadoc}/org/apache/geode/cache/snapshot/CacheSnapshotService.html#load-java.io.File-org.apache.geode.cache.snapshot.SnapshotOptions.SnapshotFormat[`load`]
method in the `CacheSnapshotService` API indicates.
NOTE: Of course, you can use the other, overloaded `load(:File[], :SnapshotFormat, :SnapshotOptions)` method
variant to get specific about which snapshot files to load into the {data-store-name} `cache`.
NOTE: Of course, you can use the overloaded `load(:File[], :SnapshotFormat, :SnapshotOptions)` method to get specific
about which snapshot files to load into the {data-store-name} cache.
However, Spring Data for {data-store-name} recognizes that a typical developer workflow might be to extract and export data
However, {sdg-name} recognizes that a typical developer workflow might be to extract and export data
from one environment into several snapshot files, zip all of them up, and then conveniently move the zip file
to another environment for import.
Therefore, Spring Data for {data-store-name} lets you specify a jar or zip file on import for a `cache`-based
Snapshot Service, as follows:
Therefore, {sdg-name} lets you specify a jar or zip file on import for a `cache`-based Snapshot Service, as follows:
[source,xml]
----
@@ -102,19 +100,18 @@ Snapshot Service, as follows:
</gfe-data:snapshot-service>
----
Spring Data for {data-store-name} conveniently extracts the provided zip file and treats it as a directory import (load).
{sdg-name} conveniently extracts the provided zip file and treats it as a directory import (load).
[[bootstrap:snapshot:filters]]
== Snapshot Filters
The real power of defining multiple snapshot imports and exports is realized through the use of snapshot filters.
Snapshot filters implement {data-store-name}'s
{x-data-store-javadoc}/org/apache/geode/cache/snapshot/SnapshotFilter.html[`SnapshotFilter`]
interface and are used to filter region entries for inclusion into the region on import
and for inclusion into the snapshot on export.
Snapshot filters implement {data-store-name}'s {x-data-store-javadoc}/org/apache/geode/cache/snapshot/SnapshotFilter.html[`SnapshotFilter`] interface
and are used to filter Region entries for inclusion into the Region on import and for inclusion into the snapshot
on export.
Spring Data for {data-store-name} lets you use snapshot filters on import and export by using the `filter-ref`
attribute or an anonymous, nested bean definition, as the following example shows:
{sdg-name} lets you use snapshot filters on import and export by using the `filter-ref` attribute or an anonymous,
nested bean definition, as the following example shows:
[source,xml]
----
@@ -141,17 +138,15 @@ attribute or an anonymous, nested bean definition, as the following example show
----
In addition, you can express more complex snapshot filters by using the `ComposableSnapshotFilter` class.
This class implements {data-store-name}'s
{x-data-store-javadoc}/org/apache/geode/cache/snapshot/SnapshotFilter.html[SnapshotFilter]
interface as well as the https://en.wikipedia.org/wiki/Composite_pattern[Composite] software design pattern.
This class implements {data-store-name}'s {x-data-store-javadoc}/org/apache/geode/cache/snapshot/SnapshotFilter.html[SnapshotFilter] interface
as well as the https://en.wikipedia.org/wiki/Composite_pattern[Composite] software design pattern.
In a nutshell, the https://en.wikipedia.org/wiki/Composite_pattern[Composite] software design pattern lets you
compose multiple objects of the same type and treat the aggregate as single instance of the object type -- a
powerful and useful abstraction.
`ComposableSnapshotFilter` has two factory methods, `and` and `or`. They let you logically combine
individual snapshot filters using the AND and OR logical operators, respectively. The factory methods take a
list of `SnapshotFilters`.
`ComposableSnapshotFilter` has two factory methods, `and` and `or`. They let you logically combine individual snapshot
filters using the AND and OR logical operators, respectively. The factory methods take a list of `SnapshotFilters`.
The following example shows a definition for a `ComposableSnapshotFilter`:
@@ -187,36 +182,37 @@ You could then go on to combine the `activesUsersSinceFilter` with another filte
[[bootstrap::snapshot::events]]
== Snapshot Events
By default, Spring Data for {data-store-name} uses {data-store-name}'s Snapshot Services on startup to import data and on shutdown
By default, {sdg-name} uses {data-store-name}'s Snapshot Services on startup to import data and on shutdown
to export data. However, you may want to trigger periodic, event-based snapshots, for either import or export,
from within your Spring application.
For this purpose, Spring Data for {data-store-name} defines two additional Spring application events, extending Spring's
For this purpose, {sdg-name} defines two additional Spring application events, extending Spring's
http://docs.spring.io/spring/docs/current/javadoc-api/org/springframework/context/ApplicationEvent.html[`ApplicationEvent`]
class for imports and exports, respectively: `ImportSnapshotApplicationEvent` and `ExportSnapshotApplicationEvent`.
The two application events can be targeted at the entire {data-store-name} cache or individual {data-store-name} regions. The constructors
in these classes accept an optional region pathname (such as `/Example`) as well as xero or more `SnapshotMetadata` instances.
The two application events can be targeted for the entire {data-store-name} cache or for individual {data-store-name}
Regions. The constructors in these classes accept an optional Region pathname (such as `/Example`) as well as zero
or more `SnapshotMetadata` instances.
The array of `SnapshotMetadata` overrides the snapshot metadata defined by `<gfe-data:snapshot-import>`
and `<gfe-data:snapshot-export>` sub-elements, which are used in cases where snapshot application events
do not explicitly provide `SnapshotMetadata`. Each individual `SnapshotMetadata` instance can define its own
`location` and `filters` properties.
and `<gfe-data:snapshot-export>` sub-elements, which are used in cases where snapshot application events do not
explicitly provide `SnapshotMetadata`. Each individual `SnapshotMetadata` instance can define its own `location`
and `filters` properties.
All snapshot service beans defined in the Spring `ApplicationContext` receive import and export snapshot application events.
However, only matching Snapshot Service beans process import and export events.
All snapshot service beans defined in the Spring `ApplicationContext` receive import and export snapshot
application events. However, only matching Snapshot Service beans process import and export events.
A region-based `[Import|Export]SnapshotApplicationEvent` matches if the Snapshot Service bean defined
is a `RegionSnapshotService` and its region reference (as determined by the `region-ref` attribute) matches
the region's pathname, as specified by the snapshot application event.
A Region-based `[Import|Export]SnapshotApplicationEvent` matches if the Snapshot Service bean defined
is a `RegionSnapshotService` and its Region reference (as determined by the `region-ref` attribute) matches
the Region's pathname, as specified by the snapshot application event.
A Cache-based `[Import|Export]SnapshotApplicationEvent` (that is, a snapshot application event without a region pathname)
A Cache-based `[Import|Export]SnapshotApplicationEvent` (that is, a snapshot application event without a Region pathname)
triggers all Snapshot Service beans, including any `RegionSnapshotService` beans, to perform either an import or export,
respectively.
You can use Spring's
http://docs.spring.io/spring/docs/current/javadoc-api/org/springframework/context/ApplicationEventPublisher.html[`ApplicationEventPublisher`]
interface to fire import and export snapshot application events from your applicationas follows:
{spring-framework-javadoc}/org/springframework/context/ApplicationEventPublisher.html[`ApplicationEventPublisher`]
interface to fire import and export snapshot application events from your application as follows:
[source,java]
----
@@ -230,25 +226,30 @@ public class ExampleApplicationComponent {
private Region<?, ?> example;
public void someMethod() {
...
File dataSnapshot = new File(System.getProperty("user.dir"), "/path/to/export/data.snapshot");
SnapshotFilter myFilter = ...;
SnapshotMetadata exportSnapshotMetadata = new SnapshotMetadata(new File(System.getProperty("user.dir"),
"/path/to/export/data.snapshot"), myFilter, null);
SnapshotMetadata exportSnapshotMetadata =
new SnapshotMetadata(dataSnapshot, myFilter, null);
eventPublisher.publishEvent(new ExportSnapshotApplicationEvent(this, example.getFullPath(), exportSnapshotMetadata);
ExportSnapshotApplicationEvent exportSnapshotEvent =
new ExportSnapshotApplicationEvent(this, example.getFullPath(), exportSnapshotMetadata)
eventPublisher.publishEvent(exportSnapshotEvent);
...
}
}
----
In the preceding example, only the `/Example` region's Snapshot Service bean picks up and handles the export event,
saving the filtered, `/Example` region's data to the `data.snapshot` file in a sub-direcrtory
of the application's working directory.
In the preceding example, only the `/Example` Region's Snapshot Service bean picks up and handles the export event,
saving the filtered, "`/Example`" Region's data to the `data.snapshot` file in a sub-directory of the application's
working directory.
Using the Spring application events and messaging subsystem is a good way to keep your application loosely coupled.
You can also use Spring's
http://docs.spring.io/spring/docs/current/spring-framework-reference/htmlsingle/#scheduling-task-scheduler[Scheduling]
services to fire snapshot application events on a periodic basis.
You can also use Spring's {spring-framework-docs}/#scheduling-task-scheduler[Scheduling] services to fire
snapshot application events on a periodic basis.