diff --git a/src/main/asciidoc/appendix/appendix-schema.adoc b/src/main/asciidoc/appendix/appendix-schema.adoc index 120d4895..51495c2a 100644 --- a/src/main/asciidoc/appendix/appendix-schema.adoc +++ b/src/main/asciidoc/appendix/appendix-schema.adoc @@ -1,7 +1,6 @@ [[appendix-schema]] [appendix] = Spring Data for Pivotal GemFire Schema -:resourcesDir: {basedocdir}/../resources -- http://www.springframework.org/schema/gemfire/spring-gemfire.xsd[Spring Data for Pivotal GemFire Core Schema (`gfe`-namespace)] -- http://www.springframework.org/schema/gemfire/spring-data-gemfire.xsd[Spring Data for Pivotal GemFire Data Access Schema (`gfe-data`-namespace)] +* http://www.springframework.org/schema/gemfire/spring-gemfire.xsd[Spring Data for Pivotal GemFire Core Schema (`gfe` namespace)] +* http://www.springframework.org/schema/gemfire/spring-data-gemfire.xsd[Spring Data for Pivotal GemFire Data Access Schema (`gfe-data` namespace)] diff --git a/src/main/asciidoc/images/epub-cover.png b/src/main/asciidoc/images/epub-cover.png new file mode 100644 index 00000000..6e118989 Binary files /dev/null and b/src/main/asciidoc/images/epub-cover.png differ diff --git a/src/main/asciidoc/images/epub-cover.svg b/src/main/asciidoc/images/epub-cover.svg new file mode 100644 index 00000000..b39994db --- /dev/null +++ b/src/main/asciidoc/images/epub-cover.svg @@ -0,0 +1,10 @@ + + + + + Spring Data GemFire + Reference Guide + Costin Leau, David Turanski, + John Blum, Oliver Gierke, + Jay Bryant + diff --git a/src/main/asciidoc/index.adoc b/src/main/asciidoc/index.adoc index 3b80c0bc..9f9f214b 100644 --- a/src/main/asciidoc/index.adoc +++ b/src/main/asciidoc/index.adoc @@ -1,10 +1,17 @@ = Spring Data for Pivotal GemFire Reference Guide -Costin Leau , David Turanski , John Blum , Oliver Gierke +Costin Leau; David Turanski; John Blum; Oliver Gierke; Jay Bryant :revnumber: {version} :revdate: {localdate} +:linkcss: +:doctype: book +:docinfo: shared +:toc: left +:toclevels: 4 +:source-highlighter: prettify +:icons: font +:imagesdir: images +ifdef::backend-epub3[:front-cover-image: image:epub-cover.png[Front Cover,1050,1600]] :spring-data-commons-docs: {basedocdir}/../../../../spring-data-commons/src/main/asciidoc -:toc: -:!toc-placement: (C) 2010-2018 The original authors. @@ -12,39 +19,27 @@ NOTE: Copies of this document may be made for your own use and for distribution charge any fee for such copies and further provided that each copy contains this Copyright Notice whether distributed in print or electronically. -toc::[] - [[preface]] include::{basedocdir}/preface.adoc[] -ifndef::leveloffset[:leveloffset: 0] - -:leveloffset: +1 - -include::{basedocdir}/introduction/introduction.adoc[] -include::{basedocdir}/introduction/requirements.adoc[] -include::{basedocdir}/introduction/new-features.adoc[] - -:leveloffset: -1 +include::{basedocdir}/introduction/introduction.adoc[leveloffset=+1] +include::{basedocdir}/introduction/requirements.adoc[leveloffset=+1] +include::{basedocdir}/introduction/new-features.adoc[leveloffset=+1] [[reference]] = Reference Guide -:leveloffset: +1 - -include::{basedocdir}/reference/introduction.adoc[] -include::{basedocdir}/reference/bootstrap.adoc[] -include::{basedocdir}/reference/bootstrap-annotations.adoc[] -include::{basedocdir}/reference/data.adoc[] -include::{basedocdir}/reference/serialization.adoc[] -include::{basedocdir}/reference/mapping.adoc[] -include::{basedocdir}/reference/repositories.adoc[] -include::{basedocdir}/reference/function-annotations.adoc[] -include::{basedocdir}/reference/lucene.adoc[] -include::{basedocdir}/reference/gemfire-bootstrap.adoc[] -include::{basedocdir}/reference/samples.adoc[] - -:leveloffset: -1 +include::{basedocdir}/reference/introduction.adoc[leveloffset=+1] +include::{basedocdir}/reference/bootstrap.adoc[leveloffset=+1] +include::{basedocdir}/reference/bootstrap-annotations.adoc[leveloffset=+1] +include::{basedocdir}/reference/data.adoc[leveloffset=+1] +include::{basedocdir}/reference/serialization.adoc[leveloffset=+1] +include::{basedocdir}/reference/mapping.adoc[leveloffset=+1] +include::{basedocdir}/reference/repositories.adoc[leveloffset=+1] +include::{basedocdir}/reference/function-annotations.adoc[leveloffset=+1] +include::{basedocdir}/reference/lucene.adoc[leveloffset=+1] +include::{basedocdir}/reference/gemfire-bootstrap.adoc[leveloffset=+1] +include::{basedocdir}/reference/samples.adoc[leveloffset=+1] [[resources]] = Resources @@ -53,22 +48,14 @@ In addition to this reference documentation, there are a number of other resourc how to use Pivotal GemFire with the _Spring Framework_. These additional, third-party resources are enumerated in this section. -:leveloffset: +1 - -include::{basedocdir}/links.adoc[] - -:leveloffset: -1 +include::{basedocdir}/links.adoc[leveloffset=+1] [[appendices]] = Appendices :!sectnums: -:leveloffset: +1 - -include::{spring-data-commons-docs}/repository-namespace-reference.adoc[] -include::{spring-data-commons-docs}/repository-populator-namespace-reference.adoc[] -include::{spring-data-commons-docs}/repository-query-keywords-reference.adoc[] -include::{spring-data-commons-docs}/repository-query-return-types-reference.adoc[] -include::{basedocdir}/appendix/appendix-schema.adoc[] - -:leveloffset: -1 +include::{spring-data-commons-docs}/repository-namespace-reference.adoc[leveloffset=+1] +include::{spring-data-commons-docs}/repository-populator-namespace-reference.adoc[leveloffset=+1] +include::{spring-data-commons-docs}/repository-query-keywords-reference.adoc[leveloffset=+1] +include::{spring-data-commons-docs}/repository-query-return-types-reference.adoc[leveloffset=+1] +include::{basedocdir}/appendix/appendix-schema.adoc[leveloffset=+1] diff --git a/src/main/asciidoc/introduction/introduction.adoc b/src/main/asciidoc/introduction/introduction.adoc index 1a88e0b1..6161b787 100644 --- a/src/main/asciidoc/introduction/introduction.adoc +++ b/src/main/asciidoc/introduction/introduction.adoc @@ -1,6 +1,6 @@ [[introduction]] = Introduction -Welcome! The _Spring Data for Pivotal GemFire_ reference guide explains how to use the _Spring Framework_ +The Spring Data for Pivotal GemFire reference guide explains how to use the Spring Framework to configure and develop applications with Pivotal GemFire. It presents the basic concepts and provides numerous examples to help you get started. diff --git a/src/main/asciidoc/introduction/new-features.adoc b/src/main/asciidoc/introduction/new-features.adoc index e2d681e1..1979c00b 100644 --- a/src/main/asciidoc/introduction/new-features.adoc +++ b/src/main/asciidoc/introduction/new-features.adoc @@ -1,124 +1,120 @@ [[new-features]] = New Features -NOTE: As of the 1.2.0.RELEASE, this project, formerly known as _Spring Pivotal GemFire_, has been renamed to -_Spring Data for Pivotal GemFire_ to reflect that it is now a module of the +NOTE: As of the 1.2.0.RELEASE, this project, formerly known as Spring Pivotal GemFire, has been renamed to +Spring Data for Pivotal GemFire to reflect that it is now a module of the http://projects.spring.io/spring-data/[Spring Data] project and built on https://pivotal.io/pivotal-gemfire[Pivotal GemFire]. [[new-in-1-2-0]] == New in the 1.2 Release -* Full support for Pivotal GemFire configuration via the SDG *gfe* namespace. Now Pivotal GemFire components may be configured completely without requiring a native *cache.xml* file. +* Full support for Pivotal GemFire configuration through the SDG *gfe* namespace. Now Pivotal GemFire components may be configured completely without requiring a native cache.xml file. * WAN Gateway support for Pivotal GemFire 6.6.x. See <>. * Spring Data Repository support using a dedicated SDG namespace, *gfe-data*. See <> * Namespace support for registering Pivotal GemFire Functions. See <> -* A top-level `` element has been added to the SDG *gfe* namespace to allow sharing of persist stores among Regions, -and other components that support persistent backup or overflow. See <> +* A top-level `` 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 <> + WARNING: The `<*-region>` elements no longer allow a nested `` element. + -* Pivotal GemFire Sub-Regions are supported via nested `<*-region>` elements. +* Pivotal GemFire Sub-Regions are supported by nested `<*-region>` elements. * A `` element has been added to configure a Local Region. * Support for the re-designed WAN Gateway in Pivotal GemFire 7.0. [[new-in-1-3-0]] == New in the 1.3 Release -* Annotation support for Pivotal GemFire Functions. It is now possible to declare and register Functions written as POJOs using annotations. In addition, Function executions are defined as +* Annotation support for Pivotal GemFire 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 <>. -* Added a `` element to the SDG *gfe-data* namespace to simplify establishing a basic <> to a Pivotal GemFire data grid. -* Added a `` element to the SDG *gfe-data* namespace to <> features introduced +* Added a `` element to the SDG `gfe-data` namespace to simplify establishing a basic <> to a Pivotal GemFire data grid. +* Added a `` element to the SDG `gfe-data` namespace to <> features introduced in Pivotal GemFire 7.0, enabling Spring AOP to perform the necessary conversions automatically on Region operations. * Upgraded to Pivotal GemFire 7.0.1 and added namespace support for new AsyncEventQueue attributes. * Added support for setting subscription interest policy on Regions. * Support for void returns on Function executions. See <> for complete details. -* Support for persisting Local Regions. See <> and <>. +* Support for persisting Local Regions. See <>. * Support for entry time-to-live and entry idle-time on a Pivotal GemFire Client Cache. See <>. -* Support for multiple Spring Data for Pivotal GemFire web-based applications using a single Pivotal GemFire cluster, operating concurrently inside tc Server. -* Support for concurrency-checks-enabled on all Pivotal GemFire Cache Region definitions using the SDG *gfe* namespace. See <>. -* Support for Cache Loaders and Cache Writers on Client, Local Regions. See <>. -* Support for registering CacheListeners, AsyncEventQueues and Gateway Senders on Pivotal GemFire Cache Sub-Regions. +* Support for multiple Spring Data for Pivotal GemFire web-based applications by using a single Pivotal GemFire cluster, operating concurrently inside tc Server. +* Support for `concurrency-checks-enabled` on all Pivotal GemFire Cache Region definitions by using the SDG `gfe` namespace. See <>. +* Support for Cache Loaders and Cache Writers on the Client for Local Regions. +* Support for registering CacheListeners, AsyncEventQueues, and Gateway Senders on Pivotal GemFire Cache Sub-Regions. * Support for PDX persistent keys in Pivotal GemFire Regions. -* Support for correct Partition Region bean creation in a Spring context when collocation is specified with the *colocated-with* attribute. -* Full support for Pivotal GemFire Cache Sub-Regions using proper, nested `<*-region>` element syntax in the SDG *gfe* namespace. +* Support for correct Partition Region bean creation in a Spring context when collocation is specified with the `colocated-with` attribute. +* Full support for Pivotal GemFire Cache Sub-Regions using proper, nested `<*-region>` element syntax in the SDG `gfe` namespace. * Upgraded Spring Data for Pivotal GemFire to Spring Framework 3.2.8. * Upgraded Spring Data for Pivotal GemFire to Spring Data Commons 1.7.1. [[new-in-1-4-0]] == New in the 1.4 Release -* Upgrades to Pivotal GemFire 7.0.2. -* Upgrades to _Spring Data Commons_ 1.8.x.RELEASE. -* Upgrades to _Spring Framework_ 3.2.x.RELEASE. -* Integrates _Spring Data for Pivotal GemFire_ with _Spring Boot_, which includes both a *spring-boot-starter-data-gemfire* POM -along with a _Spring Boot_ sample application demonstrating Pivotal GemFire Cache Transactions configured with SDG -and bootstrapped with _Spring Boot_. -* Support for bootstrapping a Spring `ApplicationContext` in a Pivotal GemFire Server when started from _Gfsh_. +* Upgraded to Pivotal GemFire 7.0.2. +* Upgraded to Spring Data Commons 1.8.x.RELEASE. +* Upgraded to Spring Framework 3.2.x.RELEASE. +* Integrated Spring Data for Pivotal GemFire with Spring Boot, which includes both a `spring-boot-starter-data-gemfire` POM +and a Spring Boot sample application that demonstrates Pivotal GemFire Cache Transactions configured with SDG +and bootstrapped with Spring Boot. +* Added support for bootstrapping a Spring `ApplicationContext` in a Pivotal GemFire Server when started from `Gfsh`. See <> for more details. -* Support for persisting application domain object/entities to multiple Pivotal GemFire Cache Regions. +* Added support for persisting application domain object and entities to multiple Pivotal GemFire Cache Regions. See <> for more details. -* Support for persisting application domain object/entities to Pivotal GemFire Cache Sub-Regions, avoiding collisions -when Sub-Regions are uniquely identifiable, but identically named. +* Added support for persisting application domain object and entities to Pivotal GemFire Cache Sub-Regions, avoiding collisions +when Sub-Regions are uniquely identifiable but identically named. See <> for more details. -* Adds strict XSD type rules to, and full support for, Data Policies and Region Shortcuts +* Added strict XSD type rules to and full support for Data Policies and Region Shortcuts on all Pivotal GemFire 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 old behavior using the *ignore-if-exists* attribute. +along with an option to restore the old behavior (by using the `ignore-if-exists` attribute). See <> and <> for more details. -* _Spring Data for Pivotal GemFire_ can now be fully built and ran on JDK 7 and JDK 8. - -CAUTION: Pivotal GemFire has not yet been fully tested and certified to run JDK 8; See -http://gemfire.docs.pivotal.io/docs-gemfire/supported_configs/supported_configs_and_system_reqs.html[Pivotal GemFire User Guide] -for additional details. +* Spring Data for Pivotal GemFire can now be fully built and ran on JDK 7 and JDK 8. [[new-in-1-5-0]] == New in the 1.5 Release -* Maintains support for Pivotal GemFire 7.0.2. -* Upgrades to _Spring Data Commons_ 1.9.x.RELEASE. -* Upgrades to _Spring Framework_ 4.0.x.RELEASE. -* Reference Guide migrated to Asciidoc. -* Renewed support for deploying _Spring Data for Pivotal GemFire_ in an OSGi container. -* Removed all default values in the _Spring Data for Pivotal GemFire_ XML namespace Region-type elements to +* Maintained support for Pivotal GemFire 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 Pivotal GemFire in an OSGi container. +* Removed all default values in the Spring Data for Pivotal GemFire XML namespace Region-type elements to rely on Pivotal GemFire defaults instead. * Added convenience to automatically create Disk Store directory locations. -* SDG annotated Function implementations can now be executed from _Gfsh_. -* Enable Pivotal GemFire `GatewayReceivers` to be started manually. -* Support for Auto Region Lookups. See <> for further details. -* Support for Region Templates. See <> for further details. +* SDG annotated Function implementations can now be executed from `Gfsh`. +* Enabled Pivotal GemFire `GatewayReceivers` to be started manually. +* Added support for Auto Region Lookups. See <> for further details. +* Added support for Region Templates. See <> for further details. [[new-in-1-6-0]] == New in the 1.6 Release -* Upgrades to Pivotal GemFire 8.0.0. -* Upgrades to _Spring Data Commons_ 1.10.x.RELEASE. -* Maintains support on _Spring Framework_ 4.0.x.RELEASE. -* Adds support for Pivotal GemFire 8's new Cluster-based Configuration. -* Enables 'auto-reconnect' functionality to be employed in Spring-configured Pivotal GemFire Servers. -* Allows the creation of concurrent and parallel Async Event Queues and Gateway Senders. -* Adds support for Pivotal GemFire 8's Region data compression. -* Adds attributes to set both critical and warning percentages on Disk Store usage. -* Supports the capability to add the new EventSubstitutionFilters to GatewaySenders. +* Upgraded to Pivotal GemFire 8.0.0. +* Upgraded to Spring Data Commons 1.10.x.RELEASE. +* Maintained support for Spring Framework 4.0.x.RELEASE. +* Added support for Pivotal GemFire 8's new Cluster-based Configuration. +* Enabled 'auto-reconnect' functionality to be employed in Spring-configured Pivotal GemFire Servers. +* Allowed the creation of concurrent and parallel Async Event Queues and Gateway Senders. +* Added support for Pivotal GemFire 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. [[new-in-1-7-0]] == New in the 1.7 Release -* Upgrades to Pivotal GemFire 8.1.0. -* Upgrades to _Spring Data Commons_ 1.11.x.RELEASE. -* Upgrades to _Spring Framework_ 4.1.x.RELEASE. -* Early access support for Pivotal GemFire. -* Support for adding _Spring_-defined Cache Listeners, Loaders and Writers on "existing" Pivotal GemFire Regions -configured in _Spring_ XML, `cache.xml` or even with Pivotal GemFire's _Cluster Config_. -* _Spring_ JavaConfig support added to `SpringContextBootstrappingInitializer`. -* Support for custom `ClassLoaders` in `SpringContextBootstrappingInitializer` to load _Spring_-defined bean classes. -* Support for `LazyWiringDeclarableSupport` re-initialization and complete replacement for `WiringDeclarableSupport`. -* Adds `locators` and `servers` attributes to the `` element allowing variable Locator/Server -endpoint lists configured with _Spring's_ property placeholders. -* Enables the use of `` element with non-_Spring_ configured Pivotal GemFire Servers. -* Multi-Index definition and creation support. +* Upgraded to Pivotal GemFire 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 Pivotal GemFire. +* Added support for adding Spring-defined Cache Listeners, Loaders, and Writers on "existing" Pivotal GemFire Regions +configured in Spring XML, `cache.xml`, or even with Pivotal GemFire's Cluster Config. +* 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`. +* Added `locators` and `servers` attributes to the `` element, allowing variable Locator and Server +endpoint lists configured with Spring's property placeholders. +* Enables the use of the `` element with non-Spring-configured Pivotal GemFire Servers. +* Added multi-index definition and creation support. * <> * <> * <> @@ -126,50 +122,50 @@ endpoint lists configured with _Spring's_ property placeholders. [[new-in-1-8-0]] == New in the 1.8 Release -* Upgrades to Pivotal GemFire 8.2.0. -* Upgrades to _Spring Data Commons_ 1.12.x.RELEASE. -* Upgrades to _Spring Framework_ 4.2.x.RELEASE. -* Adds Maven POM to build SDG with Maven. -* Adds support for CDI. -* Enables a `ClientCache` to be configured without a `Pool`. -* `` and `` elements `use-bean-factory-locator` attributes now default to *false*. -* Adds `durable-client-id` and `durable-client-timeout` attributes to ``. -* GemfirePersistentProperty now properly handles other non-entity, scalar-like types (e.g. `BigDecimal`, `BigInteger`). -* Prevents SDG-defined `Pools` from being destroyed before `Regions` that use those `Pools`. -* Handles case-insensitive Pivotal GemFire OQL queries defined as _Repository_ query methods. -* Changes `Pivotal GemFireCache.evict(key)` to call `Region.remove(key)` in SDG's _Spring Cache Abstraction_ support. -* Fixes `RegionNotFoundException` with _Repository_ queries on a client `Region` associated with a specific `Pool` +* Upgraded to Pivotal GemFire 8.2.0. +* Upgraded to Spring Data Commons 1.12.x.RELEASE. +* Upgraded to Spring Framework 4.2.x.RELEASE. +* Added Maven POM to build SDG with Maven. +* Addsed support for CDI. +* Enabled a `ClientCache` to be configured without a `Pool`. +* Made `` and `` elements `use-bean-factory-locator` attributes default to *false*. +* Added `durable-client-id` and `durable-client-timeout` attributes to ``. +* Made GemfirePersistentProperty now properly handle other non-entity, scalar-like types (such as `BigDecimal` and `BigInteger`). +* Prevented SDG-defined `Pools` from being destroyed before `Regions` that use those `Pools`. +* Handled case-insensitive Pivotal GemFire OQL queries defined as Repository query methods. +* Changed `Pivotal 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 Pivotal GemFire server groups. -* Changes `Gateway Senders/Receivers` to no longer be tied to the _Spring_ container. +* Changed `Gateway Senders/Receivers` to no longer be tied to the _Spring_ container. [[new-in-1-9-0]] == New in the 1.9 Release -* Upgrades to Pivotal GemFire 8.2.4. -* Upgrades to _Spring Data Commons_ 1.13.x.RELEASE. -* Upgrades to _Spring Framework_ 4.3.x.RELEASE. -* Introduces an entirely new Annotation-based configuration model inspired by _Spring Boot_. -* Adds support for suspend and resume in the `GemfireTransactionManager`. -* Adds support in _Repositories_ to use the bean `id` property as the Region key when the `@Id` annotation +* Upgraded to Pivotal GemFire 8.2.4. +* Upgraded to Spring Data Commons 1.13.x.RELEASE. +* Upgraded to Spring Framework 4.3.x.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. -* Uses `MappingPdxSerializer` as the default Pivotal GemFire serialization strategy when `@EnablePdx` is used. -* Enables `GemfireCacheManager` to explicitly list Region names to be used in the _Spring's Caching Abstraction_. -* Configure Pivotal GemFire Caches, CacheServers, Locators, Pools, Regions, Indexes, DiskStores, Expiration, Eviction, +* Used `MappingPdxSerializer` as the default Pivotal GemFire serialization strategy when `@EnablePdx` is used. +* Enabled `GemfireCacheManager` to explicitly list Region names to be used in the Spring's Caching Abstraction. +* Configured Pivotal GemFire Caches, CacheServers, Locators, Pools, Regions, Indexes, DiskStores, Expiration, Eviction, Statistics, Mcast, HttpService, Auth, SSL, Logging, System Properties. -* 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 -* Upgrades to Pivotal GemFire 9.0.x. -* Upgrades to _Spring Data Commons_ 2.0.x.RELEASE. -* Upgrades to _Spring Framework_ 5.0.x.RELEASE. -* Reorganizes the SDG codebase by better packaging different classes and components by concern. -* Adds extensive support for Java 8 types, particularly in the SD _Repository_ abstraction. -* Changes to the _Repository_ interface and abstraction, e.g. IDs are no longer required to be `java.io.Serializable`. -* Sets `@EnableEntityDefinedRegions` annotation `ignoreIfExists` attribute to *true* by default. -* Sets `@Indexed` annotation `override` attribute to *false* by default. -* Renames `@EnableIndexes` to `@EnableIndexing`. -* Introduces a `InterestsBuilder` class to easily and conveniently express Interests in keys/values between client +* Upgraded to Pivotal GemFire 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. +* 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. +* Set `@Indexed` annotation `override` attribute to `false` by default. +* 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. -* Adds support for Off-Heap, Redis Adapter and Pivotal GemFire's new Security framework to the Annotation configuration model. +* Added support for Off-Heap, Redis Adapter, and Pivotal GemFire's new Security framework to the Annotation configuration model. diff --git a/src/main/asciidoc/introduction/requirements.adoc b/src/main/asciidoc/introduction/requirements.adoc index 75feae41..03a3aa08 100644 --- a/src/main/asciidoc/introduction/requirements.adoc +++ b/src/main/asciidoc/introduction/requirements.adoc @@ -1,5 +1,5 @@ [[requirements]] = Requirements -_Spring Data for Pivotal GemFire_ requires JDK 8.0, http://projects.spring.io/spring-framework[Spring Framework] 5 +Spring Data for Pivotal GemFire requires JDK 8.0, http://projects.spring.io/spring-framework[Spring Framework] 5 and http://geode.apache.org/[Pivotal GemFire] 9.0.x. diff --git a/src/main/asciidoc/preface.adoc b/src/main/asciidoc/preface.adoc index 278eb211..ba9920ea 100644 --- a/src/main/asciidoc/preface.adoc +++ b/src/main/asciidoc/preface.adoc @@ -1,16 +1,14 @@ = Preface -_Spring Data for Pivotal GemFire_ focuses on integrating the _Spring Framework's_ powerful, non-invasive programming model -and concepts with Pivotal GemFire to simplify configuration and development of Java applications using Pivotal GemFire. +Spring Data for Pivotal GemFire focuses on integrating the Spring Framework's powerful, non-invasive programming model +and concepts with Pivotal GemFire to simplify configuration and development of Java applications when you use Pivotal GemFire. -This document assumes the reader already has a basic understanding and some familiarity with the core _Spring Framework_ +This document assumes you already have a basic understanding of and some familiarity with the core Spring Framework and Pivotal GemFire concepts and APIs. 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 (e.g. data distribution management -using partitioning with HA while still preserving consistency). Additionally, some typos might have crept in. -If you do spot mistakes or even more serious errors and you can spare a few cycles, please do bring these issues -to the attention of the _Spring Data_ team by raising an appropriate +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]. - -Thank you. diff --git a/src/main/asciidoc/reference/bootstrap-annotations.adoc b/src/main/asciidoc/reference/bootstrap-annotations.adoc index 76bea2eb..836c7579 100644 --- a/src/main/asciidoc/reference/bootstrap-annotations.adoc +++ b/src/main/asciidoc/reference/bootstrap-annotations.adoc @@ -1,98 +1,103 @@ +The following example shows how to configure a region bean in Java: + [[bootstrap-annotation-config]] = Bootstrapping Pivotal GemFire using Spring Annotations -_Spring Data for Pivotal GemFire_ (SDG) 2.0 introduces a **new** Annotation-based configuration model -to configure and bootstrap Pivotal GemFire using the Spring container. +Spring Data for Pivotal GemFire (SDG) 2.0 introduces a new annotation-based configuration model +to configure and bootstrap Pivotal GemFire by using the Spring container. -The primary motivation for introducing an Annotation-based approach to the configuration of Pivotal GemFire in -a Spring context is to enable application developers to _**get up and running** as **quickly** -and as **easily** as possible_. +The primary motivation for introducing an annotation-based approach to the configuration of Pivotal GemFire in +a Spring context is to enable application developers to get up and running as quickly +and as easily as possible. [[bootstrap-annotation-config-introduction]] == Introduction -Pivotal GemFire can be very difficult to setup and use correctly given all the +Pivotal GemFire can be difficult to set up and use correctly, given all the http://gemfire.docs.pivotal.io/geode/reference/topics/gemfire_properties.html[configuration properties], configuration options: -(http://gemfire-93-javadocs.docs.pivotal.io/)[Java API], -(http://gemfire.docs.pivotal.io/geode/reference/topics/chapter_overview_cache_xml.html[cache.xml], -http://gemfire.docs.pivotal.io/gemfire/tools_modules/gfsh/chapter_overview.html[_Gfsh_] -with http://gemfire.docs.pivotal.io/geode/configuring/chapter_overview.html[_Cluster Configuration_], -<>) -in addition to different supported _topologies_ -(http://gemfire.docs.pivotal.io/geode/topologies_and_comm/cs_configuration/chapter_overview.html[client/server], -http://gemfire.docs.pivotal.io/geode/topologies_and_comm/p2p_configuration/chapter_overview.html[P2P], -http://gemfire.docs.pivotal.io/geode/topologies_and_comm/multi_site_configuration/chapter_overview.html[WAN]) -and https://cwiki.apache.org/confluence/display/GEODE/Geode+Internal+Architecture?src=contextnavpagetreemode[_Distributed System Design Patterns_] -(e.g. shared-nothing architecture). The Annotation-based configuration model aims to simplify all this plus more. -The Annotation-based configuration model is an alternative to XML-based configuration using _Spring Data for Pivotal GemFire's_ -XML Namespace. With XML, an application developer would use the `spring-gemfire` (`gfe`) schema for configuration -and the `spring-data-gemfire` (`gfe-data`) schema for data access related concerns. See <> for more details. -NOTE: As of SDG 2.0, the new Annotation-based configuration model does not yet have configuration support +* (http://gemfire-93-javadocs.docs.pivotal.io/)[Java API] +* (http://gemfire.docs.pivotal.io/geode/reference/topics/chapter_overview_cache_xml.html[cache.xml] +* http://gemfire.docs.pivotal.io/gemfire/tools_modules/gfsh/chapter_overview.html[_Gfsh_] +with http://gemfire.docs.pivotal.io/geode/configuring/chapter_overview.html[cluster configuration] +* <>) + +Further complexity comes from the different supported topologies: +* (http://gemfire.docs.pivotal.io/geode/topologies_and_comm/cs_configuration/chapter_overview.html[client/server] +* http://gemfire.docs.pivotal.io/geode/topologies_and_comm/p2p_configuration/chapter_overview.html[P2P] +* http://gemfire.docs.pivotal.io/geode/topologies_and_comm/multi_site_configuration/chapter_overview.html[WAN]) +* https://cwiki.apache.org/confluence/display/GEODE/Geode+Internal+Architecture?src=contextnavpagetreemode[distributed system design patterns] +(such as shared-nothing architecture). + +The Annotation-based configuration model aims to simplify all this and more. + +The Annotation-based configuration model is an alternative to XML-based configuration using Spring Data for Pivotal GemFire's +XML Namespace. With XML, you could use the `spring-gemfire` (`gfe`) schema for configuration +and the `spring-data-gemfire` (`gfe-data`) schema for data access-related concerns. See "`<>`" for more details. + +NOTE: As of SDG 2.0, the annotation-based configuration model does not yet have configuration support for Pivotal GemFire's WAN components and topology. -Like _Spring Boot_, _Spring Data for Pivotal GemFire's_ Annotation-based configuration model was designed as an opinionated, -_convention over configuration_ approach for using Pivotal GemFire. Indeed, this Annotation-based configuration model -was inspired by _Spring Boot_ as well as several other Spring and _Spring Data_ projects. +Like Spring Boot, Spring Data for Pivotal GemFire's annotation-based configuration model was designed as an opinionated, +convention-over-configuration approach for using Pivotal GemFire. Indeed, this annotation-based configuration model +was inspired by Spring Boot as well as several other Spring and Spring Data projects. -By following convention, all Annotations provide reasonable and sensible defaults for all configuration attributes -out-of-the-box. The default value for a given Annotation attribute directly corresponds to the default value +By following convention, all annotations provide reasonable and sensible defaults for all configuration attributes. + The default value for a given annotation attribute directly corresponds to the default value provided in Pivotal GemFire for the same configuration property or setting. -The intention is to let an application developer enable a Pivotal GemFire feature or an embedded service by simply -declaring the Annotation on his/her Spring `@Configuration` or `@SpringBootApplication` class without needing to +The intention is to let you enable a Pivotal GemFire feature or an embedded service by +declaring the annotation on your Spring `@Configuration` or `@SpringBootApplication` class without needing to unnecessarily configure a large number of attributes or properties just to use the feature. -Again, _getting up and running as quickly and as easily as possible_ is the primary objective. +Again, getting up and running as quickly and as easily as possible is the primary objective. -However, the option to customize the configuration meta-data and behavior of Pivotal GemFire is there should an application -developer need it and _Spring Data for Pivotal GemFire's_ Annotation-based configuration will quietly back away. The application -developer simply just needs to specify the configuration attributes s/he wishes to adjust. And, as we will see below, -there are several ways to configure an Pivotal GemFire feature or embedded service using Annotations. +However, the option to customize the configuration metadata and behavior of Pivotal GemFire is there if you +need it, and Spring Data for Pivotal GemFire's Annotation-based configuration quietlys back away. You need +only specify the configuration attributes you wish to adjust. Also, as we see later in this document, +there are several ways to configure a Pivotal GemFire feature or embedded service by using annotations. -All the **new** SDG Annotations can be found in the `org.springframework.data.gemfire.config.annotation` package. +You can find all the new SDG Annotations in the `org.springframework.data.gemfire.config.annotation` package. [[bootstrap-annotation-config-geode-applications]] -== Bootstrapping Pivotal GemFire applications with Spring +== Bootstrapping Pivotal GemFire Applications with Spring -Like all _Spring Boot_ applications that begin by annotating the application class with `@SpringBootApplication`, -a _Spring Boot_ application can easily become an Pivotal GemFire cache application simply by declaring -1 of 3 main Annotations: +Like all Spring Boot applications that begin by annotating the application class with `@SpringBootApplication`, +a Spring Boot application can easily become a Pivotal GemFire cache application by declaring any one of three main Annotations: -1. `@ClientCacheApplication` -2. `@PeerCacheApplication` -3. `@CacheServerApplication` +* `@ClientCacheApplication` +* `@PeerCacheApplication` +* `@CacheServerApplication` -These 3 Annotations are the Spring/Pivotal GemFire application developer's starting point. +These three annotations are the Spring and Pivotal GemFire application developer's starting point. -To realize the intent behind these Annotations, a user must understand that there are 2 types of cache instances -that can be created with Pivotal GemFire: a _client_ or a _peer_. +To realize the intent behind these annotations, you must understand that there are two types of cache instances +that can be created with Pivotal GemFire: a client or a peer. -A _Spring Boot_ application can be configured as an Pivotal GemFire cache client (i.e. with an instance of `ClientCache`), +You can configure a Spring Boot application as aa Pivotal GemFire cache client (that is, with an instance of `ClientCache`), which communicates with an existing, standalone cluster of Pivotal GemFire servers used to manage the application's data. -The _client/server_ topology is the most typical system architecture employed when using Pivotal GemFire and the user -can make her _Spring Boot_ application a cache client simply by annotating it with `@ClientCacheApplication`. +The client-server topology is the most typical system architecture employed when using Pivotal GemFire and you +can make your Spring Boot application a cache client by annotating it with `@ClientCacheApplication`. -Alternatively, a _Spring Boot_ application may be a peer member of an Pivotal GemFire cluster. That is, the application -itself is just another server in the cluster of servers that will manage data. The _Spring Boot_ application creates -an "embedded" peer `Cache` instance when a developer annotates his/her application class with `@PeerCacheApplication`. +Alternatively, a Spring Boot application may be a peer member of an Pivotal GemFire cluster. That is, the application +itself is another server in the cluster of servers that manage data. The Spring Boot application creates +an "`embedded`" peer `Cache` instance when you annotate your application class with `@PeerCacheApplication`. -By extension, the application may also serve as a `CacheServer` serving cache clients, allowing clients to connect -and perform data access operations on the server. This is accomplished by annotating the application class with -`@CacheServerApplication` instead of `@PeerCacheApplication`, which will create a peer `Cache` instance along with +By extension, the application may also serve as a `CacheServer`, serving cache clients and letting clients connect +and perform data access operations on the server. This is accomplished by annotating the application class with +`@CacheServerApplication` instead of `@PeerCacheApplication`, which creates a peer `Cache` instance along with the `CacheServer`. -NOTE: An Pivotal GemFire Server is not necessarily a "_Cache Server_" by default. That is, a server is not necessarily -setup to serve cache clients just because it is a "server". A Pivotal GemFire Server can just be a peer member/data node -of the cluster that manages data without serving any clients while other peer members in the cluster are indeed setup -to serve clients in addition to managing data. It also possible to setup certain peer members as non-data node, +NOTE: A Pivotal GemFire Server is not necessarily a cache server by default. That is, a server is not necessarily +set up to serve cache clients just because it is a server. A Pivotal GemFire Server can be a peer member (or data node) +of the cluster that manages data without serving any clients while other peer members in the cluster are indeed set up +to serve clients in addition to managing data. It also possible to set up certain peer members as non-data nodes, http://gemfire.docs.pivotal.io/geode/developing/region_options/data_hosts_and_accessors.html[data accessors] -that can service clients as `CacheServers` as well, but is beyond the scope of this document. +that can service clients as `CacheServers` as well, but doing so is beyond the scope of this document. -By way of example, if I wanted to create a _Spring Boot_, Pivotal GemFire cache client application, I would start with... +By way of example, if you want to create a Spring Boot Pivotal GemFire cache client application, you can start with the following: .Spring-based Pivotal GemFire `ClientCache` application [source, java] @@ -102,8 +107,8 @@ By way of example, if I wanted to create a _Spring Boot_, Pivotal GemFire cache class ClientApplication { .. } ---- -And, if I wanted to create a _Spring Boot_ application with an embedded peer `Cache` instance, where my application -will be a server and peer member of a cluster, or distributed system formed by Pivotal GemFire, then I would start with... +Also, if you want to create a Spring Boot application with an embedded peer `Cache` instance, where your application +is a server and a peer member of a cluster or distributed system formed by Pivotal GemFire, you could start with the following: .Spring-based Pivotal GemFire embedded peer `Cache` application [source, java] @@ -113,9 +118,9 @@ will be a server and peer member of a cluster, or distributed system formed by P class ServerApplication { .. } ---- -Alternatively, a user may use the `@CacheServerApplication` annotation instead of `@PeerCacheApplication` to create -both an "embedded" peer `Cache` instance along with a `CacheServer` running on "_localhost_", listening on -the default cache server port, *40404*... +Alternatively, you can use the `@CacheServerApplication` annotation instead of `@PeerCacheApplication` to create +both an embedded peer `Cache` instance and a `CacheServer` running on localhost, listening on +the default cache server port, 40404, as follows: .Spring-based Pivotal GemFire embedded `CacheServer` Application [source, java] @@ -126,35 +131,34 @@ class ServerApplication { .. } ---- [[bootstrap-annotation-config-client-server-applications]] -== Going in-detail on _client/server_ applications - +== Going in-detail on Client-server Applications There are multiple ways that a client can connect to and communicate with servers in an Pivotal GemFire cluster. The most common and recommended approach is to use Pivotal GemFire Locators. -NOTE: A cache client can connect to 1 or more Locators in the Pivotal GemFire cluster instead of directly to a -`CacheServer`. The advantage of using Locators over direct `CacheServer` connections is that Locators provide meta-data -about the cluster to which clients are connected. This meta-data includes information like which servers contain -the data of interests to the client, or which servers have the least amount of load. A Locator also provides fail-over -capabilities in case a `CacheServer` goes down. By enabling the PR single-hop capability in the client `Pool`, -the client is routed directly to the server containing the data the client needs access to, to obtain the data requested. +NOTE: A cache client can connect to one or more locators in the Pivotal GemFire cluster instead of directly to a +`CacheServer`. The advantage of using locators over direct `CacheServer` connections is that locators provide metadata +about the cluster to which clients are connected. This metadata includes information such as which servers contain +the data of interest to the client or which servers have the least amount of load. A locator also provides fail-over +capabilities in case a `CacheServer` goes down. By enabling the PR single-hop capability in the client `Pool`, +the client is routed directly to the server containing the data the client needs to obtain the data requested. -NOTE: Locators are also peer members in a cluster. Locators actually constitute what makes up a cluster of Pivotal GemFire -nodes; i.e. all nodes connected by a Locator make up a cluster of peers and new members use Locators to join a cluster +NOTE: Locators are also peer members in a cluster. Locators actually constitute what makes up a cluster of Pivotal GemFire +nodes. That is, all nodes connected by a locator make up a cluster of peers, and new members use locators to join a cluster and find other members. -Since Pivotal GemFire sets up a "DEFAULT" `Pool` connected to a `CacheServer` running on "_localhost_", listening on port -**40404** by default when a `ClientCache` instance is created, and a `CacheServer` listens on port **40404** accepting -connections on all system NICs, there is nothing special a user needs to do to utilize the _client/server_ topology. -Simply annotate your server-side _Spring Boot_ application with `@CacheServerApplication` and your client-side -_Spring Boot_ application with `@ClientCacheApplication` and you are ready to go. +Pivotal GemFire sets up a `DEFAULT` `Pool` connected to a `CacheServer` running on localhost, listening on port +40404 (by default) when a `ClientCache` instance is created. A `CacheServer` listens on port 40404, accepting +connections on all system NICs. You need do nothing special to use the client-server topology. +To do so, annotate your server-side Spring Boot application with `@CacheServerApplication` and your client-side +Spring Boot application with `@ClientCacheApplication`, and you are ready to go. -You can even start your servers using _Gfsh's_ `start server` command if you prefer. Your _Spring Boot_ -`@ClientCacheApplication` will still connect to the server regardless of how it is started. Although, we think you -will prefer to configure and start your servers using the _Spring Data for Pivotal GemFire_ approach, with Annotations. +If you prefer, you can even start your servers by using Gfsh's `start server` command. Your Spring Boot +`@ClientCacheApplication` still connects to the server regardless of how it is started. However, you +may prefer to configure and start your servers by using the Spring Data for Pivotal GemFire approach: with annotations. -As an application developer, you will no doubt want to customize the "DEFAULT" `Pool` setup by Pivotal GemFire -to possibly connect to 1 or more Locators, for instance... +As an application developer, you will no doubt want to customize the `DEFAULT` `Pool` set up by Pivotal GemFire +to possibly connect to one or more locators, as the following example shows: .Spring-based Pivotal GemFire `ClientCache` application using Locators [source, java] @@ -168,19 +172,21 @@ class ClientApplication { .. } ---- Along with the `locators` attribute, the `@ClientCacheApplication` annotation has a `servers` attribute that can be used -to specify 1 or more nested `@Server` annotations that enable the cache client to connect directly to 1 or more servers, +to specify one or more nested `@Server` annotations that let the cache client connect directly to one or more servers, if necessary. -NOTE: You can only use either the `locators` or `servers` attribute, but not both, which is enforced by Pivotal GemFire. +NOTE: You can use either the `locators` or `servers` attribute, but not both (this is enforced by Pivotal GemFire). -A user may also configure additional `Pools`, other than the "DEFAULT" `Pool` provided by Pivotal GemFire when -a `ClientCache` instance is created with the `@ClientCacheApplication` annotation, by using the `@EnablePool` +You can also configure additional `Pool` instances (other than the `DEFAULT` `Pool` provided by Pivotal GemFire when +a `ClientCache` instance is created with the `@ClientCacheApplication` annotation) by using the `@EnablePool` and `@EnablePools` annotations. NOTE: `@EnablePools` is a composite annotation that aggregates several nested `@EnablePool` annotations on -a single class. Java 8 and earlier does not allow more than 1 annotation of the same type to be declared +a single class. Java 8 and earlier does not allow more than one annotation of the same type to be declared on a class. +The following example uses the `@EnablePool` and `@EnablePools` annotations: + .Spring-based Pivotal GemFire `ClientCache` application using multiple named `Pools` [source, java] ---- @@ -201,12 +207,12 @@ on a class. class ClientApplication { .. } ---- -The `name` attribute is the only required attribute of the `@EnablePool` annotation. As we will see below, the value -of `name` corresponds to both the name of the `Pool` bean created in the Spring context as well as the name used to -reference the corresponding configuration properties. It is also the name of the `Pool` registered and used +The `name` attribute is the only required attribute of the `@EnablePool` annotation. As we see later, the value +of `name` corresponds to both the name of the `Pool` bean created in the Spring context and the name used to +reference the corresponding configuration properties. It is also the name of the `Pool` registered and used in Pivotal GemFire. -Similarly, on the server, a user can configure multiple `CacheServers` that a client can connect to... +Similarly, on the server, you can configure multiple `CacheServers` that a client can connect to, as follows: .Spring-based Pivotal GemFire `CacheServer` application using multiple named `CacheServers` [source, java] @@ -223,39 +229,39 @@ class ServerApplication { .. } ---- NOTE: Like `@EnablePools`, `@EnableCacheServers` is a composite annotation for aggregating multiple `@EnableCacheServer` -annotations on a single class. Again, Java 8 and earlier does not allow more than 1 annotation of the same type +annotations on a single class. Again, Java 8 and earlier does not allow more than one annotation of the same type to be declared on a class. -One thing an observant reader may have noticed is, in all cases, the user is specifying hard-coded values for hostnames, -ports as well other configuration-oriented Annotation attributes. This is not ideal when a user's application gets +One thing an observant reader may have noticed is that, in all cases, you specify hard-coded values for hostnames, +ports, and configuration-oriented annotation attributes. This is not ideal when a user's application gets promoted and deployed to different environments, such as from DEV to QA to STAGING to PROD. -How does an application developer handle dynamic configuration determined at runtime? +The next section covers how to handle dynamic configuration determined at runtime. [[bootstrap-annotation-config-configurers]] == Runtime configuration using `Configurers` -Another goal when designing the Annotation-based configuration model was to preserve _Type-Safety_ in the Annotation -attributes. For example, if the configuration attribute could be expressed as an `int`, like a port number, then +Another goal when designing the Annotation-based configuration model was to preserve type safety in the annotation +attributes. For example, if the configuration attribute could be expressed as an `int` (such as a port number), the attribute's type should be an `int`. Unfortunately, this is not conducive to dynamic and resolvable configuration at runtime. -One of the finer features of Spring is the ability to use _property placeholders_ and/or _SpEL expressions_ -in properties or attributes of the configuration meta-data when configuring beans in a Spring context. -Although, this would require all Annotation attributes to be `Strings` thereby giving up _Type-Safety_; not acceptable! +One of the finer features of Spring is the ability to use property placeholders and SpEL expressions +in properties or attributes of the configuration metadata when configuring beans in a Spring context. +However, this would require all annotation attributes to be `String` objects, thereby giving up type safety, which is not acceptable. -So, _Spring Data for Pivotal GemFire_ borrows from another commonly used pattern in Spring, `Configurers`. Many different -`Configurer` interfaces are provided out-of-the-box in Spring Web MVC, such as the +So, Spring Data for Pivotal GemFire borrows from another commonly used pattern in Spring, `Configurers`. Many different +`Configurer` interfaces are provided in Spring Web MVC, including the https://docs.spring.io/spring/docs/current/javadoc-api/org/springframework/web/servlet/config/annotation/ContentNegotiationConfigurer.html[`org.springframework.web.servlet.config.annotation.ContentNegotiationConfigurer`]. -The `Configurers` design pattern are a way to allow application developers to receive a callback to customize -the configuration of a component, or bean on startup. The framework calls back to user-provided code to adjust +The `Configurers` design pattern is a way to let application developers receive a callback to customize +the configuration of a component or bean on startup. The framework calls back to user-provided code to adjust the configuration at runtime. One of the more common uses of this pattern is to supply conditional configuration based on the application's runtime environment. -_Spring Data for Pivotal GemFire_ provides several `Configurer` callback interfaces to customize different aspects of Annotation-based -configuration meta-data at runtime, before the _Spring_ managed beans that the Annotations create are initialized: +Spring Data for Pivotal GemFire provides several `Configurer` callback interfaces to customize different aspects of annotation-based +configuration metadata at runtime, before the Spring managed beans that the annotations create are initialized: * `ClientCacheConfigurer` * `PeerCacheConfigurer` @@ -266,10 +272,10 @@ configuration meta-data at runtime, before the _Spring_ managed beans that the A * `PoolConfigurer` * `RegionConfigurer` -For example, we can use the `CacheServerConfigurer` and `ClientCacheConfigurer` to customize the port numbers -used by our _Spring Boot_ `CacheServer` and `ClientCache` applications, respectively. +For example, you can use the `CacheServerConfigurer` and `ClientCacheConfigurer` to customize the port numbers +used by your Spring Boot `CacheServer` and `ClientCache` applications, respectively. -First, in our server application... +Consider the following example from a server application: .Customizing a Spring Boot `CacheServer` application with a `CacheServerConfigurer` [source, java] @@ -292,7 +298,7 @@ class ServerApplication { } ---- -Then, in our client application... +Next, consider the following example from a client application: .Customizing a Spring Boot `ClientCache` application with a `ClientCacheConfigurer` [source, java] @@ -313,39 +319,39 @@ class ClientApplication { } ---- -By using the provided `Configurers`, a user is able to receive a callback in order to further customize -the configuration that is enabled by the associated Annotation at runtime, during startup. +By using the provided `Configurers`, you can receive a callback in order to further customize +the configuration that is enabled by the associated annotation at runtime, during startup. In addition, when the `Configurer` is declared as a bean in the Spring context, the bean definition can take advantage -of other Spring container features, such as _property placeholders_, or _SpEL expressions_ using the `@Value` annotation +of other Spring container features, such as property placeholders, SpEL expressions that use the `@Value` annotation on factory method parameters, and so on. -All _Spring Data for Pivotal GemFire_-provided `Configurers` take 2 bits of information in the callback: the name of the bean created -in the Spring context by the Annotation along with a reference to the `FactoryBean` used by the Annotation to -create and configure the Pivotal GemFire component (e.g. a `ClientCache` instance is created and configured with +All `Configurers` provided by Spring Data for Pivotal GemFire take two bits of information in the callback: the name of the bean created +in the Spring context by the annotation and a reference to the `FactoryBean` used by the annotation to +create and configure the Pivotal GemFire component (for example, a `ClientCache` instance is created and configured with SDG's `ClientCacheFactoryBean`). -NOTE: SDG `FactoryBeans` are part of the SDG public API and are what an application developer would use in Spring's +NOTE: SDG `FactoryBeans` are part of the SDG public API and are what you would use in Spring's https://docs.spring.io/spring/docs/current/spring-framework-reference/core.html#beans-java[Java-based container configuration] -if this **new** Annotation-based configuration model were not provided. Indeed, the Annotations themselves are using -these very same `FactoryBeans` for their configuration. So, in essence, the Annotations are a facade +if this new annotation-based configuration model were not provided. Indeed, the annotations themselves are using +these same `FactoryBeans` for their configuration. So, in essence, the annotations are a facade and provide an extra layer of abstraction for convenience. -Given a `Configurer` can be declared as a regular bean definition like any other POJO, it is not difficult to imagine -a user combining different Spring configuration options, such as the use of _Spring Profiles_ with `Conditions` -using both Property Placeholders and SpEL expressions as well as other nifty features to create -even more sophisticated and flexible configuration. +Given that a `Configurer` can be declared as a regular bean definition like any other POJO, you can combine +different Spring configuration options, such as the use of Spring Profiles with `Conditions` that +use both property placeholders and SpEL expressions. These and other nifty features let you create +even more sophisticated and flexible configurations. However, `Configurers` are not the only option. [[bootstrap-annotation-config-properties]] -== Runtime configuration using `Properties` +== Runtime Configuration Using `Properties` -In addition to `Configurers`, each Annotation attribute in the Annotation-based configuration model is associated -with a corresponding configuration _property_, prefixed with `spring.data.gemfire.`, that can be declared in a -_Spring Boot_ `application.properties` file. +In addition to `Configurers`, each annotation attribute in the annotation-based configuration model is associated +with a corresponding configuration property (prefixed with `spring.data.gemfire.`) that can be declared in a +Spring Boot `application.properties` file. -Building on our examples above, the client's `application.properties` would define... +Building on the earlier examples, the client's `application.properties` file would define the following set of properties: .Client `application.properties` [source, java] @@ -364,7 +370,7 @@ spring.data.gemfire.pool.Neptune.servers=saturn[41414],neptune[42424] spring.data.gemfire.pool.Neptune.min-connections=25 ---- -And, the server's application.properties would define... +Also, the server's `application.properties` file would define the following properties: .Server `application.properties` [source, java] @@ -376,7 +382,7 @@ spring.data.gemfire.cache.server.Saturn.port=41414 spring.data.gemfire.cache.server.Neptune.port=41414 ---- -Then, we can simplify the `@ClientCacheApplication` class to... +Then you can simplify the `@ClientCacheApplication` class to the following: .Spring `@ClientCacheApplication` class [source, java] @@ -391,7 +397,7 @@ Then, we can simplify the `@ClientCacheApplication` class to... class ClientApplication { .. } ---- -And, the `@CacheServerApplication` class as... +Also, the `@CacheServerApplication` class can become the following: .Spring `@CacheServerApplication` class [source, java] @@ -406,10 +412,10 @@ And, the `@CacheServerApplication` class as... class ServerApplication { .. } ---- -The example above illustrates why it is import to "name" your Annotation-based beans (other than, it is required -in certain cases). Doing so makes it possible to reference the bean in a Spring context from XML, properties -and even Java. It is even possible to inject Annotation-defined beans into an application class, -for whatever purpose; for example... +The preceding example shows why it is important to "`name`" your annotation-based beans (other than because it is required +in certain cases). Doing so makes it possible to reference the bean in a Spring context from XML, properties, +and Java. It is even possible to inject annotation-defined beans into an application class, +for whatever purpose, as the following example shows: [source, java] ---- @@ -423,13 +429,13 @@ class MyApplicationComponent { } ---- -Likewise, naming a Annotation-defined bean allows you to code a `Configurer` to customize a specific, "named" bean +Likewise, naming an annotation-defined bean lets you code a `Configurer` to customize a specific, "`named`" bean since the `beanName` is 1 of 2 arguments passed to the callback. -Often times, an associated Annotation attribute property takes 2 forms: a "named" property along with -an "unnamed" property. +Oftentimes, an associated annotation attribute property takes two forms: a "`named`" property along with +an "`unnamed`" property. -For example... +The following example shows such an arrangement: [source, java] ---- @@ -439,19 +445,20 @@ spring.data.gemfire.cache.server.Saturn... spring.data.gemfire.cache.server.Neptune... ---- -While there are 3 named `CacheServers` above, there is 1 unnamed `CacheServer` property that serves as the default -value for any unspecified value for that property even for "named" `CacheServers`. So, while "Venus" sets -and overrides its own `bind-address`, "Saturn" and "Neptune" inherit from the unnamed +While there are three named `CacheServers` above, there is one unnamed `CacheServer` property that serves as the default +value for any unspecified value for that property, even for "`named`" `CacheServers`. So, while `Venus` sets +and overrides its own `bind-address`, `Saturn` and `Neptune` inherit from the "`unnamed`" `spring.data.gemfire.cache.server.bind-address` property. -Refer to an Annotation's _Javadoc_ for which Annotation attributes support property-based configuration, and whether -they support "named" properties over just default, "unnamed" properties. +See an annotation's Javadoc for which annotation attributes support property-based configuration and whether +they support "`named`" properties over default, "`unnamed`" properties. [[bootstrap-annotation-config-properties-of-properties]] === `Properties` of `Properties` -Of course, in Spring fashion, you can even express `Properties` in terms of other `Properties`, whether that is -using a _Spring Boot_ `application.properties` file or by using the `@Value` annotation in your Java class... +In the usual Spring fashion, you can even express `Properties` in terms of other `Properties`, whether that is +by using a Spring Boot `application.properties` file or by using the `@Value` annotation in your Java class. +The following example shows a nested property being set in an `application.properties` file: .Properties of Properties [source, java] @@ -459,7 +466,7 @@ using a _Spring Boot_ `application.properties` file or by using the `@Value` ann spring.data.gemfire.cache.server.port=${gemfire.cache.server.port:40404} ---- -Or, in Java... +The following example shows a nested property being set in Java: [source, java] ---- @@ -472,23 +479,23 @@ Or, in Java... } ---- -Property placeholder nesting can be arbitrarily deep. +TIP: Property placeholder nesting can be arbitrarily deep. [[bootstrap-annotation-config-embedded-services]] -== Configuring embedded services +== Configuring Embedded Services -Pivotal GemFire provides the ability to start many different embedded services required by an application depending on +Pivotal GemFire provides the ability to start many different embedded services that are required by an application, depending on the use case. [[bootstrap-annotation-config-embedded-services-locator]] -=== Configuring an embedded Locator +=== Configuring an Embedded Locator -As mentioned previously, Pivotal GemFire Locators are used by clients to connect with and find servers in a cluster +As mentioned previously, Pivotal GemFire locators are used by clients to connect with and find servers in a cluster as well as by new members joining an existing cluster to find other peers. -It is often convenient for application developers as they are developing their _Spring Boot_, _Spring Data for Pivotal GemFire_ -applications to startup up a small cluster of 2 or 3 Pivotal GemFire servers. Rather than starting a separate Locator -process, a user can simply annotate her _Spring Boot_ `@CacheServerApplication` class with `@EnableLocator`. +It is often convenient for application developers as they are developing their Spring Boot and Spring Data for Pivotal GemFire +applications to startup up a small cluster of two or three Pivotal GemFire servers. Rather than starting a separate locator +process, you can annotate your Spring Boot `@CacheServerApplication` class with `@EnableLocator`, as follows: .Spring, Pivotal GemFire `CacheServer` application running an embedded Locator [source, java] @@ -499,16 +506,16 @@ process, a user can simply annotate her _Spring Boot_ `@CacheServerApplication` class ServerApplication { .. } ---- -The `@EnableLocator` annotation starts an embedded Locator in the Spring, Pivotal GemFire `CacheServer` application -process running on "_localhost_", listening on the default Locator port **10334**. It is possible to customize -the `host` (a.k.a bind address) and `port` that the embedded Locator binds to using the corresponding -Annotation attributes. +The `@EnableLocator` annotation starts an embedded locator in the Spring Pivotal GemFire `CacheServer` application +process running on localhost, listening on the default Locator port: 10334. You can customize +the `host` (that is, the bind address) and `port` that the embedded locator binds to by using the corresponding +annotation attributes. -Additionally, the `@EnableLocator` attributes may be set with the `spring.data.gemfire.locator.host` -and `spring.data.gemfire.locator.port` properties in `application.properties` as well. +Additionally, you can set the `@EnableLocator` attributes by setting the `spring.data.gemfire.locator.host` +and `spring.data.gemfire.locator.port` properties in `application.properties`. -Then, it is possible to start other _Spring Boot_, `@CacheServerApplication` enabled applications connecting to this -Locator with... +Then you can start other Spring Boot `@CacheServerApplication`-enabled applications by connecting to this +Locator with the following: .Spring, Pivotal GemFire `CacheServer` application connecting to a Locator [source, java] @@ -518,9 +525,9 @@ Locator with... class ServerApplication { .. } ---- -You can even combine both application classes shown above into a single class and use your IDE to create different -run profile configurations to run different instances of the same class with slightly modified configuration using -Java System Properties... +You can even combine both application classes shown earlier into a single class and use your IDE to create different +run profile configurations to run different instances of the same class with slightly modified configuration by using +Java system properties, as follows: .Spring `CacheServer` application running an embedded Locator and connecting to the Locator [source, java] @@ -540,7 +547,7 @@ public class ServerApplication { } ---- -Then, for each run profile, a user simply sets and changes the following System properties... +Then, for each run profile, you can set and change the following system properties: .IDE run profile configuration [source, java] @@ -551,35 +558,37 @@ spring.profiles.active=embedded-locator ---- Only 1 of the run profiles for the `ServerApplication` class should be set with the -`-Dspring.profiles.active=embedded-locator` Java System Property. Then, simply change the `..name` -and `..cache.server.port` for each of the other run profiles and you'll have yourself a small cluster/distributed system -of Pivotal GemFire Servers running on your local system. Pretty slick! +`-Dspring.profiles.active=embedded-locator` Java system property. Then you can change the `..name` +and `..cache.server.port` for each of the other run profiles and have a small cluster or distributed system +of Pivotal GemFire Servers running on your local system. NOTE: The `@EnableLocator` annotation was meant to be a development-time annotation only and not something -an application developer should use in production. It is strongly recommended that Locators be stand-alone, +an application developer should use in production. We strongly recommend that locators be standalone, independent processes in the cluster. -More details on how Pivotal GemFire Locators work can be found +More details on how Pivotal GemFire locators work can be found http://gemfire.docs.pivotal.io/geode/topologies_and_comm/topology_concepts/how_member_discovery_works.html[here]. [[bootstrap-annotation-config-embedded-services-manager]] -=== Configuring an embedded Manager +=== Configuring an Embedded Manager -An Pivotal GemFire Manager is another peer member/node in the cluster that is responsible for "management" activities. -Management activities include things like creating Regions, Indexes, DiskStores, etc along with monitoring the runtime +A Pivotal GemFire Manager is another peer member or node in the cluster that is responsible for "`management`" activities. +Management activities include creating regions, indexes, diskstores, and so on, along with monitoring the runtime operations and behavior of these components. -The Manager allows a JMX-enabled client (e.g. the _Gfsh_ shell tool) to connect to the Manager to manage the cluster. -It is also possible to connect to a Manager with JDK provided tools like _JConsole_ or _JVisualVM_, given these are +The manager lets a JMX-enabled client (such as the Gfsh shell tool) connect to the manager to manage the cluster. +It is also possible to connect to a manager with JDK-provided tools such as JConsole or JVisualVM, given that these are both JMX-enabled clients as well. -Perhaps we would also like to make our Spring `@CacheServerApplication` shown above a Manager as well. Simply annotate -your Spring `@Configuration` or `@SpringBootApplication` class with `@EnableManager` and you are in business. +Perhaps you would also like to make the Spring `@CacheServerApplication` shown earlier be a manager as well. To do so, annotate +your Spring `@Configuration` or `@SpringBootApplication` class with `@EnableManager`. -By default, the Manager binds to "_localhost_" listening on the default Pivotal GemFire Manager port **1099**. -Several aspects of the Manager can be configured with the Annotation attributes or corresponding properties. +By default, the manager binds to localhost, listening on the default Pivotal GemFire Manager port of 1099. +Several aspects of the manager can be configured with annotation attributes or the corresponding properties. -.Spring `CacheServer` application running an embedded Manager +The following example shows how to create an embedded manager in Java: + +.Spring `CacheServer` application running an embedded manager [source, java] ---- @SpringBootApplication @@ -598,7 +607,7 @@ public class ServerApplication { } ---- -With the above class, you can even use _Gfsh_ to connect to this server and manage it! +With the preceding class, you can even use Gfsh to connect to this server and manage it, as follows: [source, java] ---- @@ -624,10 +633,10 @@ SpringCacheServerTwo | 10.99.199.5(SpringCacheServerTwo:14844):1025 SpringCacheServerThree | 10.99.199.5(SpringCacheServerThree:14846):1026 ---- -Because we also have the embedded Locator enabled, we are able to connect indirectly to the Manager through -the Locator. A Locator allows JMX clients to connect and find a Manager node in the cluster. If none exist, -the Locator will assume the role of a Manager. However, if no existing Locator is present, then we would need to -connect directly to the Manager using... +Because we also have the embedded locator enabled, we can connect indirectly to the manager through +the locator. A locator lets JMX clients connect and find a manager node in the cluster. If none exists, +the locator assumes the role of a manager. However, if no locator exists, we would need to +connect directly to the Manager by using the following: .Gfsh `connect` command connecting directly to the Manager [source, java] @@ -635,28 +644,28 @@ connect directly to the Manager using... gfsh>connect --jmx-manager=localhost[1099] ---- -NOTE: Like the `@EnableLocator` annotation, the `@EnableManager` annotation was also meant to be a development-time -only annotation and not something an application developer should use in production. It is strongly recommended -that Managers, like Locators, be stand-alone, independent and dedicated processes in the cluster. +NOTE: Like the `@EnableLocator` annotation, the `@EnableManager` annotation is also meant to be a development-time +only annotation and not something an application developer should use in production. We strongly recommend +that managers, like Locators, be standalone, independent, and dedicated processes in the cluster. -More details on Pivotal GemFire Management and Monitoring can be found +More details on Pivotal GemFire management and monitoring can be found http://gemfire.docs.pivotal.io/gemfire/managing/book_intro.html[here]. [[bootstrap-annotation-config-embedded-services-http]] -=== Configuring the embedded HTTP Server +=== Configuring the Embedded HTTP Server -Pivotal GemFire is also capable of running an embedded HTTP server. The current implementation is backed by +Pivotal GemFire is also capable of running an embedded HTTP server. The current implementation is backed by https://www.eclipse.org/jetty/[Eclipse Jetty]. -The embedded HTTP server is used to host Pivotal GemFire's Management (Admin) REST API (not a publicly advertised API), -the http://gemfire.docs.pivotal.io/geode/rest_apps/book_intro.html[Developer REST API] +The embedded HTTP server is used to host Pivotal GemFire's management (admin) REST API (not a publicly advertised API), +the http://gemfire.docs.pivotal.io/geode/rest_apps/book_intro.html[Developer REST API], and the http://gemfire.docs.pivotal.io/geode/tools_modules/pulse/pulse-overview.html[Pulse Monitoring Web Application]. -However, to use any of these Pivotal GemFire provided Web applications, you must have a full installation of Pivotal GemFire +However, to use any of these Pivotal GemFire-provided web applications, you must have a full installation of Pivotal GemFire installed on your system, and you must set the `GEODE_HOME` environment variable to your installation directory. -To enable the embedded HTTP server, simply add the `@EnableHttpService` annotation to any `@PeerCacheApplication` -or `@CacheServerApplication` annotated class... +To enable the embedded HTTP server, add the `@EnableHttpService` annotation to any `@PeerCacheApplication` +or `@CacheServerApplication` annotated class, as follows: .Spring `CacheServer` application running an embedded HTTP server [source, java] @@ -667,20 +676,20 @@ or `@CacheServerApplication` annotated class... public class ServerApplication { .. } ---- -By default, the embedded HTTP server listens on port **7070** for HTTP client requests. Of course, you can use -the Annotation attributes or corresponding configuration properties to adjust the configuration as needed. +By default, the embedded HTTP server listens on port 7070 for HTTP client requests. Of course, you can use +the annotation attributes or corresponding configuration properties to adjust the port as needed. -Follow the links above for more details on HTTP support and the services provided. +Follow the earlier links for more details on HTTP support and the services provided. [[bootstrap-annotation-config-embedded-services-memcached]] === Configuring the embedded Memcached Server (Gemcached) -Pivotal GemFire also implements the Memcached protocol with the ability to service Memcached clients. That is Memcached -clients can connect to an Pivotal GemFire cluster and perform Memcached operations as if the Pivotal GemFire Servers -in the cluster were actual Memcached Servers. +Pivotal GemFire also implements the memcached protocol with the ability to service memcached clients. That is, memcached +clients can connect to an Pivotal GemFire cluster and perform memcached operations as if the Pivotal GemFire servers +in the cluster were actual memcached servers. -To enable the embedded Memcached Service, simply add the `@EnableMemcachedServer` annotation to any -`@PeerCacheApplication` or `@CacheServerApplication` annotated class... +To enable the embedded memcached service, add the `@EnableMemcachedServer` annotation to any +`@PeerCacheApplication` or `@CacheServerApplication` annotated class, as follows: .Spring `CacheServer` application running an embedded Memcached Server [source, java] @@ -691,18 +700,18 @@ To enable the embedded Memcached Service, simply add the `@EnableMemcachedServer public class ServerApplication { .. } ---- -More details on Pivotal GemFire's _Gemcached_ service can be found +More details on Pivotal GemFire's Gemcached service can be found http://gemfire.docs.pivotal.io/geode/tools_modules/gemcached/chapter_overview.html[here]. [[bootstrap-annotation-config-embedded-services-redis]] -=== Configuring the embedded Redis Server +=== Configuring the Embedded Redis Server -Pivotal GemFire also implements the Redis Server protocol, which enables Redis clients to connect to and communicate with -a cluster of Pivotal GemFire Servers to issue Redis commands. As of this writing, the Redis Server protocol support +Pivotal GemFire also implements the Redis server protocol, which enables Redis clients to connect to and communicate with +a cluster of Pivotal GemFire Servers to issue Redis commands. As of this writing, the Redis server protocol support in Pivotal GemFire is still experimental. -To enable the embedded Redis Service, simply add the `@EnableRedisServer` annotation to any `@PeerCacheApplication` -or `@CacheServerApplication` annotated class... +To enable the embedded Redis service, add the `@EnableRedisServer` annotation to any `@PeerCacheApplication` +or `@CacheServerApplication` annotated class, as follows: .Spring `CacheServer` application running an embedded Redis Server [source, java] @@ -713,16 +722,16 @@ or `@CacheServerApplication` annotated class... public class ServerApplication { .. } ---- -More details on Pivotal GemFire's Redis Adapter can be found +More details on Pivotal GemFire's Redis adapter can be found http://gemfire.docs.pivotal.io/geode/tools_modules/redis_adapter.html[here]. [[bootstrap-annotation-config-logging]] == Configuring Logging -Often times it is necessary to turn up logging in order to understand exactly what Pivotal GemFire is doing and when. +Oftentimes, it is necessary to turn up logging in order to understand exactly what Pivotal GemFire is doing and when. -To enable _Logging_, simply annotate your application class with `@EnableLogging` and set the appropriate attributes -or associated properties... +To enable Logging, annotate your application class with `@EnableLogging` and set the appropriate attributes +or associated properties, as follows: .Spring `ClientCache` application with Logging enabled [source, java] @@ -734,26 +743,26 @@ public class ClientApplication { .. } ---- While the `logLevel` attribute can be specified with all the cache-based application annotations -(e.g. `@ClientCacheApplication(logLevel="info")`), it is easier to customize logging behavior with +(for example, `@ClientCacheApplication(logLevel="info")`), it is easier to customize logging behavior with the `@EnableLogging` annotation. -Additionally, you can specify the `log-level` using the `spring.data.gemfire.logging.level` property +Additionally, you can specify the `log-level` by setting the `spring.data.gemfire.logging.level` property in `application.properties`. -See the `@EnableLogging` annotation _Javadoc_ for more details. +See the https://docs.spring.io/spring-data/gemfire/docs/current/api/org/springframework/data/gemfire/config/annotation/EnableLogging.html[`@EnableLogging` annotation Javadoc] for more details. [[bootstrap-annotation-config-statistics]] == Configuring Statistics -To gain even deeper insight into Pivotal GemFire at runtime, an application developer can enable _Statistics_. -Gathering statistical data facilitates system analysis and troubleshooting when complex problems occur, -which are often distributed in nature and where timing is a crucial factor. +To gain even deeper insight into Pivotal GemFire at runtime, you can enable statistics. +Gathering statistical data facilitates system analysis and troubleshooting when complex problems, +which are often distributed in nature and where timing is a crucial factor, occur. -When _Statistics_ are enabled, a user can use Pivotal GemFire's -http://gemfire.docs.pivotal.io/gemfire/tools_modules/vsd/chapter_overview.html[VSD (_Visual Statistics Display_)] tool +When statistics are enabled, you can use Pivotal GemFire's +http://gemfire.docs.pivotal.io/gemfire/tools_modules/vsd/chapter_overview.html[VSD (Visual Statistics Display)] tool to analyze the statistical data that is collected. -To enable _Statistics_, simply annotate your application class with `@EnableStatistics`... +To enable statistics, annotate your application class with `@EnableStatistics`, as follows: .Spring `ClientCache` application with Statistics enabled [source, java] @@ -764,41 +773,41 @@ To enable _Statistics_, simply annotate your application class with `@EnableStat public class ClientApplication { .. } ---- -Enabling _Statistics_ on a server is particularly valuable when evaluating performance, which is as simple as -annotating your `@PeerCacheApplication` or `@CacheServerApplication` class with `@EnableStatistics`. +Enabling statistics on a server is particularly valuable when evaluating performance. To do so, +annotate your `@PeerCacheApplication` or `@CacheServerApplication` class with `@EnableStatistics`. -Use the `@EnableStatistics` annotation attributes or associated properties to customize the _Statistics_ gathering +You can use the `@EnableStatistics` annotation attributes or associated properties to customize the statistics gathering and collection process. -See the `@EnableStatistics` annotation _Javadoc_ for more details. +See the https://docs.spring.io/spring-data/gemfire/docs/current/api/org/springframework/data/gemfire/config/annotation/EnableStatistics.html[`@EnableStatistics` annotation Javadoc] for more details. -More details on Pivotal GemFire's _Statistics_ can be found +More details on Pivotal GemFire's statistics can be found http://gemfire.docs.pivotal.io/gemfire/managing/statistics/chapter_overview.html[here]. [[bootstrap-annotation-config-pdx]] == Configuring PDX One of the more powerful features of Pivotal GemFire is -http://gemfire.docs.pivotal.io/geode/developing/data_serialization/gemfire_pdx_serialization.html[PDX Serialization]. +http://gemfire.docs.pivotal.io/geode/developing/data_serialization/gemfire_pdx_serialization.html[PDX serialization]. While a complete discussion on PDX is beyond the scope of this document, serialization using PDX is a much better -alternative to _Java Serialization_, with the following benefits... +alternative to Java serialization, with the following benefits: -1. PDX uses a centralized _Type Registry_ to keep the serialized bytes of an object more compact. -2. PDX is a neutral serialization format allowing both Java and Native Clients to operate on the same data set. -3. PDX supports versioning and allows object fields to be added or removed with affecting existing applications -using either older or newer versions of the PDX serialized, application domain objects that have changed, +* PDX uses a centralized type registry to keep the serialized bytes of an object more compact. +* PDX is a neutral serialization format, allowing both Java and Native clients to operate on the same data set. +* PDX supports versioning and lets object fields be added or removed without affecting existing applications +using either older or newer versions of the PDX serialized application domain objects that have changed, and without data loss. -4. PDX allows object fields to be accessed individually or in OQL query projections and predicates without +* PDX lets object fields be accessed individually or in OQL query projections and predicates without the object needing to be de-serialized first. -In general, serialization in Pivotal GemFire is needed anytime data is transferred to/from clients and servers or between +In general, serialization in Pivotal GemFire is needed any time data is transferred to or from clients and servers or between peers in a cluster for normal distribution and replication processes as well as when data is overflowed or persisted to disk. Enabling PDX serialization is much simpler than modifying all of your application domain object types to be -`java.io.Serializable`, which maybe undesirable to impose such restrictions on your application domain model. +`java.io.Serializable`, especially when it may be undesirable to impose such restrictions on your application domain model. -To enable PDX, simply annotate your application class with `@EnablePdx`... +To enable PDX, annotate your application class with `@EnablePdx`, as follows: .Spring `ClientCache` application with PDX enabled [source, java] @@ -809,28 +818,28 @@ To enable PDX, simply annotate your application class with `@EnablePdx`... public class ClientApplication { .. } ---- -Typically, an application's domain object types will either implement the +Typically, an application's domain object types either implements the http://gemfire-91-javadocs.docs.pivotal.io/org/apache/geode/pdx/PdxSerializable.html[`org.apache.geode.pdx.PdxSerializable`] -interface, or an application developer will choose to implement and register a non-invasive implementation of the +interface or you can implement and register a non-invasive implementation of the http://gemfire-91-javadocs.docs.pivotal.io/org/apache/geode/pdx/PdxSerializer.html[`org.apache.geode.pdx.PdxSerializer`] interface to handle all the application domain object types that need to be serialized. -Unfortunately, Pivotal GemFire only allows one `PdxSerializer` to be registered, which suggests that all application -domain object types should be handled by a "single" `PdxSerializer` instance. But, that is a serious anti-pattern -and unmaintainable practice to be sure. +Unfortunately, Pivotal GemFire only lets one `PdxSerializer` be registered, which suggests that all application +domain object types should be handled by a single `PdxSerializer` instance. However, that is a serious anti-pattern +and an unmaintainable practice. -Even though only a single `PdxSerializer` instance can be registered with Pivotal GemFire , it makes sense to create a +Even though only a single `PdxSerializer` instance can be registered with Pivotal GemFire, it makes sense to create a single `PdxSerializer` implementation per application domain object type. -By using the https://en.wikipedia.org/wiki/Composite_pattern[Composite Software Design Pattern], the application -developer can provide an implementation of the `PdxSerializer` interface that aggregates all of the application -domain object type-specific `PdxSerializer` instances, but acts as a single `PdxSerializer` instance, and register it. +By using the https://en.wikipedia.org/wiki/Composite_pattern[Composite Software Design Pattern], you +can provide an implementation of the `PdxSerializer` interface that aggregates all of the application +domain object type-specific `PdxSerializer` instances but acts as a single `PdxSerializer` instance and register it. -You can declare this _Composite_ `PdxSerializer` as a managed bean in the Spring context and refer to this -_Composite_ `PdxSerializer` by bean name in the `@EnablePdx` annotation using the `serializerBeanName` attribute. -_Spring Data for Pivotal GemFire_ will take care of registering it with Pivotal GemFire on the user's behalf. +You can declare this composite `PdxSerializer` as a managed bean in the Spring context and refer to this +composite `PdxSerializer` by its bean name in the `@EnablePdx` annotation by using the `serializerBeanName` attribute. +Spring Data for Pivotal GemFire takes care of registering it with Pivotal GemFire on your behalf. The following example shows how to create a custom composite `PdxSerializer`: -.Spring `ClientCache` application with PDX enabled, using a custom, composite `PdxSerializer` +.Spring `ClientCache` application with PDX enabled, using a custom composite `PdxSerializer` [source, java] ---- @SpringBootApplication @@ -847,25 +856,24 @@ public class ClientApplication { It is also possible to declare Pivotal GemFire's http://gemfire-91-javadocs.docs.pivotal.io/org/apache/geode/pdx/ReflectionBasedAutoSerializer.html[`org.apache.geode.pdx.ReflectionBasedAutoSerializer`] -as a bean definition in a Spring context. Alternatively, you should use _Spring Data for Pivotal GemFire's_ more robust, +as a bean definition in a Spring context. Alternatively, you should use Spring Data for Pivotal GemFire's more robust https://docs.spring.io/spring-data-gemfire/docs/current/api/org/springframework/data/gemfire/mapping/MappingPdxSerializer.html[`org.springframework.data.gemfire.mapping.MappingPdxSerializer`], -which uses _Spring Data_ mapping meta-data and infrastructure applied to the serialization process for more efficient +which uses Spring Data mapping metadata and infrastructure applied to the serialization process for more efficient handling than reflection alone. Many other aspects and features of PDX can be adjusted with the `@EnablePdx` annotation attributes or associated configuration properties. -See the `@EnablePdx` annotation _Javadoc_ for more details. +See the https://docs.spring.io/spring-data/gemfire/docs/current/api/org/springframework/data/gemfire/config/annotation/EnablePdx.html[`@EnablePdx` annotation Javadoc] for more details. [[bootstrap-annotation-config-ssl]] == Configuring SSL -Equally important to serializing data to be transferred over-the-wire is securing the data while in transit. -Of course, the common way to accomplish this in _Java_ is using the _Secure Sockets Extension_ (SSE) -and _Transport Layer Security_ (TLS). +Equally important to serializing data to be transferred over the wire is securing the data while in transit. +Of course, the common way to accomplish this in Java is by using the Secure Sockets Extension (SSE) +and Transport Layer Security (TLS). -To enable SSL, simply annotate your application class with `@EnableSsl` and set the necessary SSL configuration -attributes or properties (e.g. keystores, usernames/passwords, etc)... +To enable SSL, annotate your application class with `@EnableSsl`, as follows: .Spring `ClientCache` application with SSL enabled [source, java] @@ -876,11 +884,13 @@ attributes or properties (e.g. keystores, usernames/passwords, etc)... public class ClientApplication { .. } ---- -Different Pivotal GemFire components: `GATEWAY`, `HTTP`, `JMX`, `LOCATOR`, `SERVER` can be individually configured -with SSL, or they can all be collectively configured at once to use SSL using the `CLUSTER` enumerated value. +Then you need to set the necessary SSL configuration attributes or properties (keystores, usernames/passwords, and so on). -It is easy to specify which Pivotal GemFire components that the SSL configuration settings should applied to using -the nested `@EnableSsl` annotation `Component` enum... +You can individually configure different Pivotal GemFire components (`GATEWAY`, `HTTP`, `JMX`, `LOCATOR`, and `SERVER`) +with SSL, or you can collectively configure them to use SSL by using the `CLUSTER` enumerated value. + +You can specify which Pivotal GemFire components the SSL configuration settings should applied to by using +the nested `@EnableSsl` annotation `Component` enum, as follows: .Spring `ClientCache` application with SSL enabled by Aache Pivotal GemFire component [source, java] @@ -891,10 +901,10 @@ the nested `@EnableSsl` annotation `Component` enum... public class ClientApplication { .. } ---- -In addition component-level SSL configuration, `ciphers`, `protocols` and `keystore`/`truststore` information can -also be specified using the corresponding Annotation attribute or associated configuration properties. +In addition, you can also specify component-level SSL configuration (`ciphers`, `protocols` and `keystore`/`truststore` information) +by using the corresponding annotation attribute or associated configuration properties. -See the `@EnableSsl` annotation _Javadoc_ for more details. +See the https://docs.spring.io/spring-data/gemfire/docs/current/api/org/springframework/data/gemfire/config/annotation/EnableSsl.html[`@EnableSsl` annotation Javadoc] for more details. More details on Pivotal GemFire SSL support can be found http://gemfire.docs.pivotal.io/geode/managing/security/ssl_overview.html[here]. @@ -903,22 +913,22 @@ http://gemfire.docs.pivotal.io/geode/managing/security/ssl_overview.html[here]. == Configuring Pivotal GemFire Properties While many of the http://gemfire.docs.pivotal.io/geode/reference/topics/gemfire_properties.html[gemfire.properties] -are conveniently encapsulated in and abstracted with an Annotation in the SDG Annotation-based configuration model, -the less commonly used _Pivotal GemFire Properties_ are still accessible from the `@EnablePivotal GemFireProperties` annotation. +are conveniently encapsulated in and abstracted with an annotation in the SDG annotation-based configuration model, +the less commonly used Pivotal GemFire properties are still accessible from the `@EnablePivotal GemFireProperties` annotation. Using the `@EnablePivotal GemFireProperties` annotation on your application class is convenient and a nice alternative to -creating a `gemfire.properties` file or setting _Pivotal GemFire Properties_ as Java System properties on the command-line +creating a `gemfire.properties` file or setting Pivotal GemFire properties as Java system properties on the command line when launching your application. -TIP: It is recommended that these _Pivotal GemFire Properties_ be set in a `gemfire.properties` file when deploying -your application to production. But, at development-time, it can be convenient to set these properties individually, +TIP: We recommend that these Pivotal GemFire properties be set in a `gemfire.properties` file when deploying +your application to production. However, at development time, it can be convenient to set these properties individually, as needed, for prototyping and testing purposes. -A few examples of some of the less common _Pivotal GemFire Properties_ that a user usually need not worry about include, -but are not limited to: `ack-wait-threshold`, `disable-tcp`, `socket-buffer-size`, etc. +A few examples of some of the less common Pivotal GemFire properties that you usually need not worry about include, +but are not limited to: `ack-wait-threshold`, `disable-tcp`, `socket-buffer-size`, and others. -To individually set any _Pivotal GemFire Property_, simply annotate your application class with `@EnablePivotal GemFireProperties` -and set the _Pivotal GemFire Properties_ you want to change from the default, out-of-the-box value set by Pivotal GemFire... +To individually set any Pivotal GemFire property, annotate your application class with `@EnablePivotal GemFireProperties` +and set the Pivotal GemFire properties you want to change from the default value set by Pivotal GemFire, as follows: .Spring `ClientCache` application with specific _Pivotal GemFire Properties_ set [source, java] @@ -929,9 +939,9 @@ and set the _Pivotal GemFire Properties_ you want to change from the default, ou public class ClientApplication { .. } ---- -Keep in mind, some of the _Pivotal GemFire Properties_ are client specific (e.g. `conflateEvents`) while others are -server specific (e.g. `distributedSystemId`, `enableNetworkPartitionDetection`, `enforceUniqueHost`, `memberTimeout`, -`redundancyZone`, etc). +Keep in mind that some of the Pivotal GemFire properties are client-specific (for example, `conflateEvents`), while others are +server-specific (for examplem `distributedSystemId`, `enableNetworkPartitionDetection`, `enforceUniqueHost`, `memberTimeout`, +`redundancyZone`, and others). More details on Pivotal GemFire properties can be found http://gemfire.docs.pivotal.io/geode/reference/topics/gemfire_properties.html[here]. @@ -940,23 +950,25 @@ http://gemfire.docs.pivotal.io/geode/reference/topics/gemfire_properties.html[he == Configuring Regions So far, outside of PDX, our discussion has centered around configuring Pivotal GemFire's more administrative functions: -creating a cache instance, starting embedded services, enabling Logging, Statistics and SSL, using `gemfire.properties` -to affect very low-level configuration and behavior. While all these configuration options are important, none of them -relate directly to the application. In other words, we still need some place to store our application data and make it +creating a cache instance, starting embedded services, enabling logging, statistics, SSL, and using `gemfire.properties` +to affect low-level configuration and behavior. While all these configuration options are important, none of them +relate directly to the application. In other words, we still need some place to store our application data and make it generally available and accessible. Pivotal GemFire organizes data in a cache into -http://gemfire.docs.pivotal.io/geode/basic_config/data_regions/chapter_overview.html[Regions]. You can think of a -Region as a table in a relational database. Generally, a Region should only store a single type of object making it -more conducive for building effective `Indexes` and writing queries. We will talk about Indexing +http://gemfire.docs.pivotal.io/geode/basic_config/data_regions/chapter_overview.html[regions]. You can think of a +region as a table in a relational database. Generally, a region should only store a single type of object, which makes it +more conducive for building effective `indexes` and writing queries. We cover indexing <>. -Previously, _Spring Data for Pivotal GemFire_ users needed to explicitly define and declare the Regions used in their applications -to store data by writing very verbose Spring configuration meta-data, whether a user was using SDG's `FactoryBeans` +Previously, Spring Data for Pivotal GemFire users needed to explicitly define and declare the regions used in their applications +to store data by writing very verbose Spring configuration metadata, whether a user was using SDG's `FactoryBeans` from the API in Spring's -https://docs.spring.io/spring/docs/current/spring-framework-reference/core.html#beans-java[Java-based container configuration]... +https://docs.spring.io/spring/docs/current/spring-framework-reference/core.html#beans-java[Java-based container configuration] or using <>. -.Example Region bean definition using Spring Java-based container configuration +The following example shows how to configure a region bean in Java: + +.Example region bean definition using Spring Java-based container configuration [source, java] ---- @Configuration @@ -979,7 +991,7 @@ class Pivotal GemFireConfiguration { } ---- -Or, using <>... +The following example shows how to configure a region bean in XML: .Example Region bean definition using the SDG XML Namespace [source, xml] @@ -989,25 +1001,23 @@ Or, using <>... ---- -While neither Java nor XML configuration is all that difficult to do, it is cumbersome, especially if an application -has a large number of Regions that need to be defined. Many relational database-based applications can literally +While neither Java nor XML configuration is all that difficult, either one can be cumbersome, especially if an application +has a large number of regions that need to be defined. Many relational database-based applications can literally have hundreds or even thousands of tables. -Ugh! +Now you can define and configure regions based on their application domain objects (that is, entities). No longer do +you need to explicitly define `region` bean definitions in Spring configuration metadata, unless you require finer-grained +control. -Now users can define and configure Regions based on their application domain objects (i.e. entities). No longer will -a user need to explicitly define `Region` bean definitions in Spring configuration meta-data, unless finer-grained -control is required. +To simplify region creation, Spring Data for Pivotal GemFire combines the use of Spring Data Repositories with the expressive +power of annotation-based configuration using the new `@EnableEntityDefinedRegions` annotation. -To simplify Region creation, _Spring Data for Pivotal GemFire_ combines the use of _Spring Data_ _Repositories_ with the expressive -power of Annotation-based configuration using the **new** `@EnableEntityDefinedRegions` annotation. - -NOTE: Most _Spring Data_ application developers should already be familiar with the -https://docs.spring.io/spring-data/commons/docs/current/reference/html/#repositories[_Spring Data Repository_ abstraction] -and _Spring Data for Pivotal GemFire's_ <> of _Spring Data's_ _Repository abstraction_, +NOTE: Most Spring Data application developers should already be familiar with the +https://docs.spring.io/spring-data/commons/docs/current/reference/html/#repositories[Spring Data Repository abstraction] +and Spring Data for Pivotal GemFire's <> of Spring Data's_ _Repository abstraction, which has been specifically customized to optimize data access operations for Pivotal GemFire. -First, an application developer starts by defining the application domain objects... +First, an application developer starts by defining the application domain objects, as follows: .Application domain object type modeling a Book [source, java] @@ -1031,8 +1041,8 @@ class Book { } ---- -Next, an application developer would define a basic _Repository_ for `Books` by extending _Spring Data Commons_ -`org.springframework.data.repository.CrudRepository` interface... +Next, you can define a basic repository for `Books` by extending Spring Data Commons +`org.springframework.data.repository.CrudRepository` interface, as follows: .Repository for Books [source, java] @@ -1041,23 +1051,23 @@ interface BookRepository extends CrudRepository { .. } ---- The `org.springframe.data.repository.CrudRepository` is a Data Access Object (DAO) providing basic data access -operations (CRUD) along with support for simple queries (e.g. `findById(..)`). The user can define additional, -more sophisticated queries simply by declaring query methods on the _Repository_ interface -(e.g. `List findByAuthor(Author author);`). +operations (CRUD) along with support for simple queries (such as `findById(..)`). You can define additional, +more sophisticated queries by declaring query methods on the repository interface +(for example, `List findByAuthor(Author author);`). -Under-the-hood, _Spring Data for Pivotal GemFire_ provides an implementation of the applications _Repository_ interface when -the Spring container is bootstrapped. SDG will even implement the query methods defined by the user so long as -the user follows simple <>. +Under the hood, Spring Data for Pivotal GemFire provides an implementation of the applications repository interface when +the Spring container is bootstrapped. SDG even implements the query methods that you define, so long as +you follow these <>. -Now, when a user defined the `Book` class, she also specified the Region in which instances of `Book` will be mapped -and stored by declaring the _Spring Data for Pivotal GemFire_ mapping annotation, `@Region` on the entity's type. Of course, if -the entity type (i.e. `Book`) referenced in the type parameter of the _Repository_ interface (i.e. `BookRepository`) -is not annotated with `@Region`, the name is derived from the simple class name of the entity type (i.e. "Book"). +Now, when you defined the `Book` class, you also specified the region in which instances of `Book` are mapped +and stored by declaring the Spring Data for Pivotal GemFire mapping annotation, `@Region` on the entity's type. Of course, if +the entity type (`Book`, in this case) referenced in the type parameter of the repository interface (`BookRepository`, in this case) +is not annotated with `@Region`, the name is derived from the simple class name of the entity type (`Book`, in this case). -_Spring Data for Pivotal GemFire_ uses the mapping context containing mapping meta-data for all the entities defined in your -application to determine all the Regions that will be needed at runtime. +Spring Data for Pivotal GemFire uses the mapping context, which contains mapping metadata for all the entities defined in your +application, to determine all the regions that are needed at runtime. -To enable and use this feature, simply annotate the application class with `@EnableEntityDefinedRegions`... +To enable and use this feature, annotate the application class with `@EnableEntityDefinedRegions`, as follows: .Entity-defined Region Configuration [source, java] @@ -1069,19 +1079,19 @@ To enable and use this feature, simply annotate the application class with `@Ena class ClientApplication { .. } ---- -TIP: Creating Regions from entity classes is the most useful when using _Spring Data Repositories_ in your application. -_Spring Data for Pivotal GemFire's_ _Repository_ support is enabled with the `@EnableGemfireRepositories` annotation, as shown -in the example above. +TIP: Creating regions from entity classes is most useful when using Spring Data repositories in your application. +Spring Data for Pivotal GemFire's repository support is enabled with the `@EnableGemfireRepositories` annotation, as shown +in the preceding example. -By default, the `@EnableEntityDefinedRegions` annotation will scan for entity classes recursively starting from +By default, the `@EnableEntityDefinedRegions` annotation scans for entity classes recursively, starting from the package of the configuration class on which the `@EnableEntityDefinedRegions` annotation is declared. However, it is common to limit the search during the scan by setting the `basePackages` attribute with the package names -containing your application entity classes. +that contain your application entity classes. -Alternatively, a user can use the more type-safe `basePackageClasses` attribute for specifying the package to scan -by setting the attribute to an entity type in the package containing the entity's class, or by using a non-entity -placeholder class in the package specifically created for identifying the package to scan. For example... +Alternatively, you can use the more type-safe `basePackageClasses` attribute for specifying the package to scan +by setting the attribute to an entity type in the package that contains the entity's class or by using a non-entity +placeholder class specifically created for identifying the package to scan. The following example shows how to specify the entity types for which to scan for our book repository example: .Entity-defined Region Configuration using the Entity class type [source, java] @@ -1096,56 +1106,56 @@ placeholder class in the package specifically created for identifying the packag class ClientApplication { .. } ---- -In addition to specifying the location where to begin the scan, like Spring's `@ComponentScan` annotation, a user can +In addition to specifying where to begin the scan, like Spring's `@ComponentScan` annotation, you can specify `include` and `exclude` filters with all the same semantics of the `org.springframework.context.annotation.ComponentScan.Filter` annotation. -See the `@EnableEntityDefinedRegion` annotation _Javadoc_ for more details. +See the https://docs.spring.io/spring-data/gemfire/docs/current/api/org/springframework/data/gemfire/config/annotation/EnableEntityDefinedRegions.html[`@EnableEntityDefinedRegions` annotation Javadoc] for more details. [[bootstrap-annotation-config-region-types]] === Configuring Type-specific Regions Pivotal GemFire supports many different -http://gemfire.docs.pivotal.io/geode/developing/region_options/region_types.html[types of Regions]. -Each type corresponds to the Region's +http://gemfire.docs.pivotal.io/geode/developing/region_options/region_types.html[types of regions]. +Each type corresponds to the region's http://gemfire-91-javadocs.docs.pivotal.io/org/apache/geode/cache/DataPolicy.html[`DataPolicy`], which determines exactly how the data in the Region will be managed (e.g. distributed/replicated, etc). -NOTE: Other configuration settings also can affect how data is managed like the Region's `scope`. -See http://gemfire.docs.pivotal.io/geode/developing/region_options/storage_distribution_options.html[Storage and Distribution Options] +NOTE: Other configuration settings (such as the region's `scope`) can also affect how data is managed. +See http://gemfire.docs.pivotal.io/geode/developing/region_options/storage_distribution_options.html["`Storage and Distribution Options`"] in the Pivotal GemFire User Guide for more details. -When the user annotates her application domain object types with the generic `@Region` mapping annotation, -_Spring Data for Pivotal GemFire_ will decide which type of `Region` to create. SDG's default strategy takes the cache type -into consideration when determining the type of `Region` to create. +When you annotates your application domain object types with the generic `@Region` mapping annotation, +Spring Data for Pivotal GemFire decides which type of region to create. SDG's default strategy takes the cache type +into consideration when determining the type of region to create. -For example, if the application was declared as a `ClientCache` using the `@ClientCacheApplication` annotation, -then SDG would create a client `PROXY` `Region`. Or, if the application was declared as a peer `Cache` using either the -`@PeerCacheApplication` or `@CacheServerApplication` annotations, then SDG would create a server `PARTITION` `Region`. +For example, if you declare the application as a `ClientCache` by using the `@ClientCacheApplication` annotation, +SDG creates a client `PROXY` `Region`. Alternatively, if you declare the application as a peer `Cache` by using either the +`@PeerCacheApplication` or `@CacheServerApplication` annotations, SDG creates a server `PARTITION` `Region`. -Of course, an application developer is always able to override the default when necessary. To override the default -applied by _Spring Data for Pivotal GemFire_, 4 new Region mapping annotations have been introduced: +Of course, you can always override the default when necessary. To override the default +applied by Spring Data for Pivotal GemFire, four new region mapping annotations have been introduced: -* `ClientRegion` -* `LocalRegion` -* `PartitionRegion` -* `ReplicateRegion` +* `@ClientRegion` +* `@LocalRegion` +* `@PartitionRegion` +* `@ReplicateRegion` -The `ClientRegion` mapping annotation is specific to client applications. All other Region mapping annotations -listed above can only be used in server applications with an embedded peer `Cache`. +The `@ClientRegion` mapping annotation is specific to client applications. All of the other region mapping annotations +listed above can be used only in server applications that have an embedded peer `Cache`. -It is sometimes necessary for client applications to create and use "local-only" Regions, perhaps to aggregate data -from other Regions in order to analyze the data locally and carry out some function performed by the application -for the user. In this case, the data may not need to be distributed back to the server, not unless other applications -need access to the results. This Region might even be temporary and discarded after use, which could be accomplished -with Idle-Timeout (TTI) and Time-To-Live (TTL) expiration policies on the Region itself. +It is sometimes necessary for client applications to create and use "`local-only`" regions, perhaps to aggregate data +from other regions in order to analyze the data locally and carry out some function performed by the application +for the user. In this case, the data does not need to be distributed back to the server unless other applications +need access to the results. This region might even be temporary and discarded after use, which could be accomplished +with Idle-Timeout (TTI) and Time-To-Live (TTL) expiration policies on the region itself. (See "`<>`" for more about expiration policies.) NOTE: Region-level Idle-Timeout (TTI) and Time-To-Live (TTL) expiration policies are independent of and different from -entry-level TTI/TTL expiration policies. +entry-level TTI and TTL expiration policies. -In any case, if a user wanted to create a local-only, client Region where the data is not gong to be distributed to -a corresponding Region with the same name on the server, the user would simply declare the `@ClientRegion` -mapping annotation and set the `shortcut` attribute to `ClientRegionShortcut.LOCAL`... +In any case, if you want to create a local-only client region where the data is not going to be distributed to +a corresponding region with the same name on the server, you can declare the `@ClientRegion` +mapping annotation and set the `shortcut` attribute to `ClientRegionShortcut.LOCAL`, as follows: .Spring `ClientCache` application with a local-only, client Region [source, java] @@ -1155,35 +1165,35 @@ class ClientLocalEntityType { .. } ---- All `Region` type-specific annotations provide additional attributes that are both common across `Region` types -as well as specific to only that type of `Region` (e.g. the `collocatedWith` and `redundantCopies` attributes -in the `PartitionRegion` annotation apply to `PARTITION` Regions only). +as well as specific to only that type of region (for example, the `collocatedWith` and `redundantCopies` attributes +in the `PartitionRegion` annotation apply to `PARTITION` regions only). -More details on Pivotal GemFire Region Types can be found +More details on Pivotal GemFire region types can be found http://gemfire.docs.pivotal.io/geode/developing/region_options/region_types.html[here]. [[bootstrap-annotation-config-region-eviction]] === Configuring Eviction -Managing data with Pivotal GemFire is an active task. More than likely, tuning will be required and a combination -of features (e.g. both _Eviction_ and <>) will need to -be employed to effectively manage your data in memory with Pivotal GemFire. +Managing data with Pivotal GemFire is an active task. Tuning is generally required, and you must employ a combination +of features (for example, both eviction and <>) +to effectively manage your data in memory with Pivotal GemFire. -Given that Pivotal GemFire is an _In-Memory Data Grid_ (IMDG), data is managed in "memory" and distributed to other nodes +Given that Pivotal GemFire is an In-Memory Data Grid (IMDG), data is managed in-memory and distributed to other nodes that participate in a cluster in order to minimize latency, maximize throughput and ensure that data is highly available. -Since not all of an application's data is going to typically fit in memory, even across an entire cluster of nodes, -much less on a single node, capacity can be increased by adding new nodes to the cluster. This is commonly referred to -as linear scale-out (rather than scaling up, which means to add more memory, more CPU, more disk, more network bandwidth, +Since not all of an application's data is going to typically fit in memory (even across an entire cluster of nodes, +much less on a single node), you can increase capacity by adding new nodes to the cluster. This is commonly referred to +as linear scale-out (rather than scaling up, which means adding more memory, more CPU, more disk, or more network bandwidth -- basically more of every system resource in order to handle the load). Still, even with a cluster of nodes, it is usually imperative that only the most important data be kept in memory. -Running out-of-memory, or even venturing near full capacity, is rarely, if ever, a good thing. Stop-the-world GCs -or worse, `OutOfMemoryErrors`, will bring your application to a screaming halt. +Running out of memory, or even venturing near full capacity, is rarely, if ever, a good thing. Stop-the-world GCs +or worse, `OutOfMemoryErrors`, bring your application to a screaming halt. -So, to help manage memory and keep the most important data around, Pivotal GemFire supports LRU-based _Eviction_. -That is, Pivotal GemFire evicts Region entries based on when those entries were last accessed by using -the _Least Recently Used_ algorithm. +So, to help manage memory and keep the most important data around, Pivotal GemFire supports Least Recently Used (LRU) eviction. +That is, Pivotal GemFire evicts region entries based on when those entries were last accessed by using +the Least Recently Used algorithm. -To enable _Eviction_, simply annotate the application class with `@EnableEviction`... +To enable eviction, annotate the application class with `@EnableEviction`, as follows: .Spring application with Eviction enabled [source, java] @@ -1199,19 +1209,19 @@ To enable _Eviction_, simply annotate the application class with `@EnableEvictio class ServerApplication { .. } ---- -Eviction policies are usually set on the Regions in the server(s). +Eviction policies are usually set on the regions in the servers. -As shown above, the `policies` attribute can specify 1 or more nested `@EvictionPolicy` annotations, each 1 individually -catered to 1 or more Regions where the Eviction policy needs to be applied. +As shown earlier, the `policies` attribute can specify one or more nested `@EvictionPolicy` annotations, with each one being individually +catered to one or more regions where the rviction policy needs to be applied. Additionally, a user can reference a custom implementation of Pivotal GemFire's http://gemfire-91-javadocs.docs.pivotal.io/org/apache/geode/cache/util/ObjectSizer.html[`org.apache.geode.cache.util.ObjectSizer`] interface, -which can be defined as a bean in the Spring context and referenced by name using the `objectSizerName` attribute. +which can be defined as a bean in the Spring context and referenced by name by using the `objectSizerName` attribute. -An `ObjectSizer` allows the user to define the criteria used to evaluate and determine the the size of objects -stored in a Region. +An `ObjectSizer` let you define the criteria used to evaluate and determine the the size of objects +stored in a region. -See the `@EnableEviction` annotation _Javadoc_ for a complete list of Eviction configuration options. +See the https://docs.spring.io/spring-data/gemfire/docs/current/api/org/springframework/data/gemfire/config/annotation/EnableEviction.html[`@EnableEviction` annotation Javadoc] for a complete list of eviction configuration options. More details on Pivotal GemFire Eviction can be found http://gemfire.docs.pivotal.io/geode/developing/eviction/chapter_overview.html[here]. @@ -1219,29 +1229,28 @@ http://gemfire.docs.pivotal.io/geode/developing/eviction/chapter_overview.html[h [[bootstrap-annotation-config-region-expiration]] === Configuring Expiration -Along with <>, _Expiration_ can also be used to manage memory -by allowing entries stored in a Region to expire. Both _Time-to-Live_ (TTL) and _Idle-Timeout_ (TTI) based entry -expiration policies are supported in Pivotal GemFire. +Along with <>, Expiration can also be used to manage memory +by allowing entries stored in a region to expire. Pivotal GemFire supports both Time-to-Live (TTL)-based and Idle-Timeout (TTI)-based entry +expiration policies. -_Spring Data for Pivotal GemFire's_ Annotation-based Expiration configuration is based on -<> added in -_Spring Data for Pivotal GemFire_ version 1.5. +Spring Data for Pivotal GemFire's annotation-based expiration configuration is based on the +<> added in +Spring Data for Pivotal GemFire version 1.5. -Essentially, _Spring Data for Pivotal GemFire's_ Expiration annotation support is based on a provided, custom implementation of +Essentially, Spring Data for Pivotal GemFire's expiration annotation support is based on a custom implementation of Pivotal GemFire's http://gemfire-91-javadocs.docs.pivotal.io/org/apache/geode/cache/CustomExpiry.html[`org.apache.geode.cache.CustomExpiry`] interface. -This `o.a.g.cache.CustomExpiry` implementation inspects the user's application domain objects stored in a Region -for the presence of type-level Expiration annotations. +This `o.a.g.cache.CustomExpiry` implementation inspects the user's application domain objects stored in a region +for the presence of type-level expiration annotations. -_Spring Data for Pivotal GemFire_ provides the following Expiration annotations used on application domain object types, -out-of-the-box... +Spring Data for Pivotal GemFire provides the following expiration annotations used on application domain object types: * `Expiration` * `IdleTimeoutExpiration` * `TimeToLiveExpiration` -An application domain object type can be annotated with 1 or more of the Expiration annotations, like so... +An application domain object type can be annotated with one or more of the expiration annotations, as follows: -.Applicaton domain object specific Expiration policy +.Applicaton domain object specific expiration policy [source, java] ---- @Region("Books") @@ -1260,10 +1269,10 @@ To enable _Expiration_, simply annotate the application class with `@EnableExpir class ServerApplication { .. } ---- -In addition to application domain object type-level Expiration policies, individual Expiration policies on a -Region-by-Region basis can be configured directly with the `@EnableExpiration` annotation as well. +In addition to application domain object type-level expiration policies, you can directly configure individual expiration policies on a +region-by-region basis by using the `@EnableExpiration` annotation, as follows: -.Spring application with global Expiration policies +.Spring application with region-specific expiration policies [source, java] ---- @SpringBootApplication @@ -1276,9 +1285,11 @@ Region-by-Region basis can be configured directly with the `@EnableExpiration` a class ServerApplication { .. } ---- -Expiration policies are usually set on the Regions in the server(s). +The preceding example sets expiration policies for the `Books`, `Customers`, and `Orders` regions. -See the `@EnableExpiration` annotation _Javadoc_ for a complete list of Expiration configuration options. +Expiration policies are usually set on the regions in the servers. + +See the https://docs.spring.io/spring-data/gemfire/docs/current/api/org/springframework/data/gemfire/config/annotation/EnableExpiration.html[`@EnableExpiration` annotation Javadoc] for a complete list of Expiration configuration options. More details on Pivotal GemFire Expiration can be found http://gemfire.docs.pivotal.io/geode/developing/expiration/chapter_overview.html[here]. @@ -1286,18 +1297,18 @@ http://gemfire.docs.pivotal.io/geode/developing/expiration/chapter_overview.html [[bootstrap-annotation-config-region-compression]] === Configuring Compression -In addition to <> -and <>, a user may also configure his or her data Regions -to use Compression in order to reduce memory consumption. +In addition to <> +and <>, you can also configure your data regions +to use compression to reduce memory consumption. -Pivotal GemFire allows users to compress in-memory Region values using pluggable +Pivotal GemFire lets you compress in-memory region values by using pluggable http://gemfire-91-javadocs.docs.pivotal.io/org/apache/geode/compression/Compressor.html[`Compressors`], -or different compression codecs. Out-of-the-box, Pivotal GemFire uses Google's http://google.github.io/snappy/[Snappy] +or different compression codecs.Pivotal GemFire uses Google's http://google.github.io/snappy/[Snappy] compression library. -To enable Compression support, simply annotate the application class with `@EnableCompression`... +To enable compression support, annotate the application class with `@EnableCompression`, as follows: -.Spring application with Compression enabled +.Spring application with compression enabled [source, java] ---- @SpringBootApplication @@ -1308,42 +1319,41 @@ class ClientApplication { .. } NOTE: Neither the `compressorBeanName` nor the `regionNames` attribute are required. -The `compressorBeanName` defaults to "`SnappyCompressor`" enabling Pivotal GemFire's provided -http://gemfire-91-javadocs.docs.pivotal.io/org/apache/geode/compression/SnappyCompressor.html[`SnappyCompressor`] -by default. +The `compressorBeanName` defaults to `SnappyCompressor`, enabling Pivotal GemFire's +http://gemfire-91-javadocs.docs.pivotal.io/org/apache/geode/compression/SnappyCompressor.html[`SnappyCompressor`]. -The `regionNames` attribute is an array of Region names specifying the Regions that will have compression enabled. -By default, all Regions will compress values if the `regionNames` attribute is not explicitly set. +The `regionNames` attribute is an array of region names that specify the regions that have compression enabled. +By default, all regions compress values if the `regionNames` attribute is not explicitly set. -TIP: Alternatively, a user may use the `spring.data.gemfire.cache.compression.compressor-bean-name` +TIP: Alternatively, you can use the `spring.data.gemfire.cache.compression.compressor-bean-name` and `spring.data.gemfire.cache.compression.region-names` properties in the `application.properties` file to set and configure the values of these `@EnableCompression` annotation attributes. WARNING: To use Pivotal GemFire's Region Compression feature, you must include the `org.iq80.snappy:snappy` dependency -in your application _Maven_ `pom.xml` file, or `build.gradle` file when using _Gradle_. This is only necessary -if you use Pivotal GemFire's default, out-of-the-box support for Region Compression, which uses the +in your application's `pom.xml` file (for Maven) or `build.gradle` file (for Gradle). This is necessary only +if you use Pivotal GemFire's default support for region compression, which uses the http://gemfire-91-javadocs.docs.pivotal.io/org/apache/geode/compression/SnappyCompressor.html[`SnappyCompressor`] -by default. Of course, if you are using another compression library, you will need to include dependencies -for that compression library on your application's classpath. Additionally, you will need to implement Pivotal GemFire's +by default. Of course, if you use another compression library, you need to include dependencies +for that compression library on your application's classpath. Additionally, you need to implement Pivotal GemFire's http://gemfire-91-javadocs.docs.pivotal.io/org/apache/geode/compression/Compressor.html[`Compressor`] interface -to adapt your compression library of choice, define it as a bean in the _Spring_ context, and then set +to adapt your compression library of choice, define it as a bean in the _Spring_ context, and set the `compressorBeanName` to this custom bean definition. -See the `@EnableCompression` annotation _Javadoc_ for more details. +See the https://docs.spring.io/spring-data/gemfire/docs/current/api/org/springframework/data/gemfire/config/annotation/EnableCompression.html[`@EnableCompression` annotation Javadoc] for more details. More details on Pivotal GemFire Compression can be found http://gemfire91.docs.pivotal.io/geode/managing/region_compression.html[here]. [[bootstrap-annotation-config-region-off-heap]] -=== Configuring Off-Heap +=== Configuring Off-Heap Memory -Another effective means for reducing pressure on the JVM's Heap memory and minimize GC activity is to use -Pivotal GemFire's _Off-Heap_ memory support. Rather than storing Region entries on the JVM Heap, entries are stored -in the system's main memory. Off-Heap generally works best when the objects being stored are uniform in size, -are mostly less than 128K and do not need to be deserialized frequently, as explained in the Pivotal GemFire +Another effective means for reducing pressure on the JVM's Heap memory and minimizeing GC activity is to use +Pivotal GemFire's off-heap memory support. Rather than storing region entries on the JVM Heap, entries are stored +in the system's main memory. Off-heap memory generally works best when the objects being stored are uniform in size, +are mostly less than 128K, and do not need to be deserialized frequently, as explained in the Pivotal GemFire http://gemfire.docs.pivotal.io/geode/managing/heap_use/off_heap_management.html[User Guide]. -To enable _Off-Heap_ support, simple annotate the application class with `@EnableOffHeap`... +To enable off-heap support, annotate the application class with `@EnableOffHeap`, as follows: .Spring application with Off-Heap enabled [source, java] @@ -1354,38 +1364,38 @@ To enable _Off-Heap_ support, simple annotate the application class with `@Enabl class ServerApplication { .. } ---- -The `memorySize` attribute is required. The value for the `memorySize` attribute specifies the amount of main memory -a Region is allowed to use in either megabytes (`m`) or gigabytes (`g`). +The `memorySize` attribute is required. The value for the `memorySize` attribute specifies the amount of main memory +a region can use in either megabytes (`m`) or gigabytes (`g`). -The `regionNames` attribute is an array of Region names specifying the Regions that will store entries in main memory. -By default, all Regions will use main memory if the `regionNames` attribute is not explicitly set. +The `regionNames` attribute is an array of region names that specifies the regions that store entries in main memory. +By default, all regions use main memory if the `regionNames` attribute is not explicitly set. -TIP: Alternatively, a user may use the `spring.data.gemfire.cache.off-heap.memory-size` +TIP: Alternatively, you can use the `spring.data.gemfire.cache.off-heap.memory-size` and `spring.data.gemfire.cache.off-heap.region-names` properties in the `application.properties` file to set and configure the values of these `@EnableOffHeap` annotation attributes. -See the `@EnableOffHeap` annotation _Javadoc_ for more details. +See the https://docs.spring.io/spring-data/gemfire/docs/current/api/org/springframework/data/gemfire/config/annotation/EnableOffHeap.html[`@EnableOffHeap` annotation Javadoc] for more details. [[bootstrap-annotation-config-region-indexes]] === Configuring Indexes -There is not much use in storing data in Regions unless the data can be accessed. +There is not much use in storing data in regions unless the data can be accessed. -In addition to `Region.get(key)` operations, particularly when the key of the value of interest is known in advance, -data is commonly retrieved by executing queries on the Regions containing the data. With Pivotal GemFire, queries are -written using the _Object Query Language_ (OQL), and the specific data set that a client wishes to access is expressed -in the query's predicate (e.g. `SELECT * FROM /Books b WHERE b.author.name = 'Jon Doe'`). +In addition to `Region.get(key)` operations, particularly when the key is known in advance, +data is commonly retrieved by executing queries on the regions that contain the data. With Pivotal GemFire, queries are +written by using the Object Query Language (OQL), and the specific data set that a client wishes to access is expressed +in the query's predicate (for example, `SELECT * FROM /Books b WHERE b.author.name = 'Jon Doe'`). -Generally, querying without Indexes is not very efficient. When executing queries without an Index, Pivotal GemFire +Generally, querying without indexes is inefficient. When executing queries without an index, Pivotal GemFire performs the equivalent of a full table scan. -Indexes are created and maintained for fields on objects used in query predicates to match the data of interests, -expressed by the query's projection. Different types of Indexes can be created, such as -http://gemfire.docs.pivotal.io/geode/developing/query_index/creating_key_indexes.html[Key] -and http://gemfire.docs.pivotal.io/geode/developing/query_index/creating_hash_indexes.html[Hash] Indexes. +Indexes are created and maintained for fields on objects used in query predicates to match the data of interest, as +expressed by the query's projection. Different types of indexes, such as +http://gemfire.docs.pivotal.io/geode/developing/query_index/creating_key_indexes.html[key] +and http://gemfire.docs.pivotal.io/geode/developing/query_index/creating_hash_indexes.html[hash] indexes, can be created. -_Spring Data for Pivotal GemFire_ makes it very easy to create Indexes on Regions where the data is stored and accessed. -Rather than explicitly declaring `Index` bean definitions using Spring config as before... +Spring Data for Pivotal GemFire makes it easy to create indexes on regions where the data is stored and accessed. +Rather than explicitly declaring `Index` bean definitions by using Spring config as before, we can create an index bean definition in Java, as follows: .Index bean definition using Java config [source, java] @@ -1405,7 +1415,7 @@ IndexFactoryBean bookIsbnIndex(Pivotal GemFireCache gemfireCache) { } ---- -Or, in <>... +Alternatively, we can use <> to create an index bean definition, as follows: .Index bean definition using XML [source, xml] @@ -1413,14 +1423,14 @@ Or, in <>... ---- -Indexes can now be defined directly on the fields declared in application domain object types that a user knows -will be used in query predicates to speedup those queries. Indexes will even be applied for OQL queries generated -from user-defined query methods on an application's _Repository_ interfaces. +You can now directly define indexes on the fields declared in the application domain object types that you know +are used in query predicates to speed up those queries. You can even apply indexes for OQL queries generated +from user-defined query methods on an application's repository interfaces. -Re-using the example `Book` class from above, we can annotate the fields on `Book` that we know will be used in queries -we define with query methods in the `BookRepository` interface... +Re-using the example `Book` class from earlier, we can annotate the fields on `Book` that we know are used in queries that +we define with query methods in the `BookRepository` interface, as follows: -.Application domain object type modeling a Book using Indexes +.Application domain object type modeling a book using indexes [source, java] ---- @Region("Books") @@ -1445,24 +1455,24 @@ class Book { ---- In our new `Book` class definition, we annotated the `author` field with `@Indexed` and the `title` field -with `@LuceneIndexed`. Also, the `isbn` field had previously been annotated with _Spring Data's_ `@Id` annotation, -which identifies the field containing the unique identifier for `Book` instances, and in _Spring Data for Pivotal GemFire_, -the `@Id` annotated field or property is used as the key in the Region when storing the entry. +with `@LuceneIndexed`. Also, the `isbn` field had previously been annotated with Spring Data's `@Id` annotation, +which identifies the field containing the unique identifier for `Book` instances, and, in Spring Data for Pivotal GemFire, +the `@Id` annotated field or property is used as the key in the region when storing the entry. -* `@Id` annotated fields/properties result in the creation of an Pivotal GemFire KEY Index. -* `@Indexed` annotated fields/properties result in the creation of an Pivotal GemFire HASH Index (default). -* `@LuceneIndexed` annotated fields/properties result in the creation of an Pivotal GemFire Lucene Index, used in -text-based searches with Pivotal GemFire's Lucene Integration and support. +* `@Id` annotated fields or properties result in the creation of an Pivotal GemFire `KEY` Index. +* `@Indexed` annotated fields or properties result in the creation of an Pivotal GemFire `HASH` Index (the default). +* `@LuceneIndexed` annotated fields or properties result in the creation of an Pivotal GemFire Lucene Index, used in +text-based searches with Pivotal GemFire's Lucene integration and support. -When the `@Indexed` annotation is used without setting any attributes, the Index `name`, `expression`, and `fromClause` -are derived from the field/property of the class on which the `@Indexed` annotation has been added. The `expression` -is exactly the name of the field or property. The `fromClause` is derived from the `@Region` annotation on +When the `@Indexed` annotation is used without setting any attributes, the index `name`, `expression`, and `fromClause` +are derived from the field or property of the class on which the `@Indexed` annotation has been added. The `expression` +is exactly the name of the field or property. The `fromClause` is derived from the `@Region` annotation on the domain object's class (or the simple name of the domain object class if the `@Region` annotation was not specified). -Of course, any of the `@Indexed` annotation attributes may be explicitly set to override the default values -provided by _Spring Data for Pivotal GemFire_. +Of course, you can explicitly set any of the `@Indexed` annotation attributes to override the default values +provided by Spring Data for Pivotal GemFire. -.Application domain object type modeling a Book using cutomized Indexes +.Application domain object type modeling a book by using customized indexes [source, java] ---- @Region("Books") @@ -1486,14 +1496,14 @@ class Book { } ---- -The `name` of the Index, which is auto-generated when not explicitly set, is also used as the name of the bean -registered in the Spring context for the Index. If necessary, this Index bean could even be injected by name +The `name` of the index, which is auto-generated when not explicitly set, is also used as the name of the bean +registered in the Spring context for the index. If necessary, this index bean ca even be injected by name into another application component. -The generated name of the Index follows the pattern: `Idx`. -For example, the name of the `author` Index would be, "`BooksAuthorHashIdx`". +The generated name of the index follows this pattern: `Idx`. +For example, the name of the `author` index would be, `BooksAuthorHashIdx`. -To enable Indexing, simply annotate the application class with `@EnableIndexing`... +To enable indexing, annotate the application class with `@EnableIndexing`, as follows: .Spring application with Indexing enabled [source, java] @@ -1506,71 +1516,70 @@ class ServerApplication { .. } ---- NOTE: The `@EnablingIndexing` annotation has no effect unless the `@EnableEntityDefinedRegions` is also declared. -Essentially, Indexes are defined from fields/properties on the entity class types, and entity classes must be scanned -in order to inspect the entity's fields and properties for the presence of Index annotations. Without this scan, -Index annotations would not be found. It is also strongly recommended that you limit the scope of the scan. +Essentially, indexes are defined from fields or properties on the entity class types, and entity classes must be scanned +to inspect the entity's fields and properties for the presence of index annotations. Without this scan, +index annotations cannot be found. We also strongly recommend that you limit the scope of the scan. -While Lucene queries are not supported on _Spring Data for Pivotal GemFire_ _Repositories_ (yet), SDG does provide comprehensive +While Lucene queries are not (yet) supported on Spring Data for Pivotal GemFire repositories, SDG does provide comprehensive https://docs.spring.io/spring-data-gemfire/docs/current/reference/html/#bootstrap:lucene[support] for Pivotal GemFire -Lucene queries using the familiar Spring _Template_ design pattern. +Lucene queries by using the familiar Spring template design pattern. -Finally, we close with a few extra tips to keep in mind when using Indexes: +Finally, we close this section with a few extra tips to keep in mind when using indexes: -1. While OQL Indexes are not required to execute OQL Queries, Lucene Indexes are required to execute Lucene, +* While OQL indexes are not required to execute OQL Queries, Lucene Indexes are required to execute Lucene text-based searches. -2. In addition, OQL Indexes are not persisted to disk; they are maintained only in memory. So, when an Pivotal GemFire +* OQL Indexes are not persisted to disk. They are maintained only in memory. So, when an Pivotal GemFire node is restarted, the Index must be rebuilt. -3. You also need to be aware of the overhead associated in maintaining Indexes, particularly since an Index is stored -exclusively in memory, and especially when Region entries are updated. Index "maintenance" can be +* You also need to be aware of the overhead associated in maintaining indexes, particularly since an index is stored +exclusively in memory and especially when region entries are updated. Index "`maintenance`" can be http://gemfire-91-javadocs.docs.pivotal.io/org/apache/geode/cache/RegionFactory.html#setIndexMaintenanceSynchronous-boolean-[configured] as an asynchronous task. -Another optimization that may be utilized when re-starting your Spring application where Indexes have to be rebuilt -is to first define all the Indexes upfront and then create them all at once, which, in _Spring Data for Pivotal GemFire_, happens +Another optimization that you can use when restarting your Spring application where indexes have to be rebuilt +is to first define all the indexes up front and then create them all at once, which, in Spring Data for Pivotal GemFire, happens when the Spring context is refreshed. -Indexes can be defined upfront then created all at once by setting the `define` attribute on the `@EnableIndexing` +You can define indexes up front and then create them all at once by setting the `define` attribute on the `@EnableIndexing` annotation to `true`. -See http://gemfire.docs.pivotal.io/geode/developing/query_index/create_multiple_indexes.html[Creating Multiple Indexes at Once] +See http://gemfire.docs.pivotal.io/geode/developing/query_index/create_multiple_indexes.html["`Creating Multiple Indexes at Once`"] in Pivotal GemFire's User Guide for more details. -Creating sensible Indexes is an important task since it is possible for an Index to do more harm than good -if not properly designed. +Creating sensible indexes is an important task, since it is possible for a poorly designed index to do more harm than good. -See both the `@Indexed` annotation and `@LuceneIndexed` annotation _Javadoc_ for complete list of configuration options. +See both the https://docs.spring.io/spring-data/gemfire/docs/current/api/org/springframework/data/gemfire/mapping/annotation/Indexed.html[`@Indexed`] annotation and https://docs.spring.io/spring-data/gemfire/docs/current/api/org/springframework/data/gemfire/mapping/annotation/LuceneIndexed.html[`@LuceneIndexed`] annotation Javadoc for complete list of configuration options. -More details on Pivotal GemFire OQL Queries can be found +More details on Pivotal GemFire OQL queries can be found http://gemfire.docs.pivotal.io/geode/developing/querying_basics/chapter_overview.html[here]. -More details on Pivotal GemFire Indexes can be found +More details on Pivotal GemFire indexes can be found http://gemfire.docs.pivotal.io/geode/developing/query_index/query_index.html[here]. -More details on Pivotal GemFire Lucene Queries can be found +More details on Pivotal GemFire Lucene queries can be found http://gemfire.docs.pivotal.io/geode/tools_modules/lucene_integration.html[here]. [[bootstrap-annotation-config-region-continuous-queries]] === Configuring Disk Stores -Regions can be configured to persist data to disk. Regions can also be configured to overflow data to disk when -Region entries are evicted. In both cases, a `DiskStore` is required to persist or overflow the data. When an -explicit `DiskStore` has not been set on a Region with persistence or overflow configured, then Pivotal GemFire -will use the "DEFAULT" `DiskStore`. +You can configure regions to persist data to disk. You can also configure regions to overflow data to disk when +region entries are evicted. In both cases, a `DiskStore` is required to persist or overflow the data. When an +explicit `DiskStore` has not been set on a region with persistence or overflow configured, Pivotal GemFire +uses the `DEFAULT` `DiskStore`. -However, it is possible and recommended to define Region-specific `DiskStores` when persisting or overflowing data +However, we recommend defining region-specific `DiskStores` when persisting or overflowing data to disk. -_Spring Data for Pivotal GemFire_ provides Annotation support for defining and creating application Region `DiskStores` +Spring Data for Pivotal GemFire provides annotation support for defining and creating application region `DiskStores` by annotating the application class with the `@EnableDiskStore` and `@EnableDiskStores` annotations. -TIP: `@EnableDiskStores` is a composite annotation for aggregating 1 or more `@EnableDiskStore` annotations. +TIP: `@EnableDiskStores` is a composite annotation for aggregating one or more `@EnableDiskStore` annotations. -For example, while `Book` product information might mostly consist of reference data, from some external data source -(e.g. Amazon), `Order` data is most likely going to be transactional in nature and something the application is going to -need to retain, maybe even overflow to disk if the transaction volume is high enough, or so any Book publisher +For example, while `Book` product information might mostly consist of reference data from some external data source +(such as Amazon), `Order` data is most likely going to be transactional in nature and something the application is going to +need to retain (and maybe even overflow to disk if the transaction volume is high enough) -- or so any book publisher and author hopes, anyway. -Using the `@EnableDiskStore` annotation, I can define and create a `DiskStore` as follows... +Using the `@EnableDiskStore` annotation, you can define and create a `DiskStore` as follows: .Spring application defining a `DiskStore` [source, java] @@ -1582,20 +1591,20 @@ Using the `@EnableDiskStore` annotation, I can define and create a `DiskStore` a class ServerApplication { .. } ---- -Again, more than 1 `DiskStore` can be defined using the composite, `@EnableDiskStores` annotation. +Again, more than one `DiskStore` can be defined by using the composite, `@EnableDiskStores` annotation. -Like other Annotations in _Spring Data for Pivotal GemFire's_ Annotation-based configuration model, both `@EnableDiskStore` +As other Annotations in Spring Data for Pivotal GemFire's annotation-based configuration model, both `@EnableDiskStore` and `@EnableDiskStores` have many attributes along with associated configuration properties to customize the `DiskStores` created at runtime. -Additionally, the `@EnableDiskStores` annotation defines certain, common `DiskStore` attributes that apply to all +Additionally, the `@EnableDiskStores` annotation defines certain common `DiskStore` attributes that apply to all `DiskStores` created from `@EnableDiskStore` annotations composed with the `@EnableDiskStores` annotation itself. -Individual `DiskStore` configuration will override a particular global setting, but the `@EnableDiskStores` -annotation conveniently defines common configuration attributes applied across all `DiskStores` aggregated by +Individual `DiskStore` configuration override a particular global setting, but the `@EnableDiskStores` +annotation conveniently defines common configuration attributes that apply across all `DiskStores` aggregated by the annotation. -_Spring Data for Pivotal GemFire_ also provides the `DiskStoreConfigurer` callback interface, which can be declared in Java config -and used instead of configuration properties to customize a `DiskStore` at runtime... +Spring Data for Pivotal GemFire also provides the `DiskStoreConfigurer` callback interface, which can be declared in Java configuration +and used instead of configuration properties to customize a `DiskStore` at runtime, as the following example shows: .Spring application with custom DiskStore configuration [source, java] @@ -1620,10 +1629,10 @@ class ServerApplication { } ---- -See the `@EnableDiskStore` and `@EnableDiskStores` annotation _Javadoc_ for more details on the available +See the https://docs.spring.io/spring-data/gemfire/docs/current/api/org/springframework/data/gemfire/config/annotation/EnableDiskStore.html[`@EnableDiskStore`] and https://docs.spring.io/spring-data/gemfire/docs/current/api/org/springframework/data/gemfire/config/annotation/EnableDiskStores.html[`@EnableDiskStores`] annotation Javadoc for more details on the available attributes as well as associated configuration properties. -More details on Pivotal GemFire Region Persistence and Overflow (using Disk Stores) can be found +More details on Pivotal GemFire Region Persistence and Overflow (using disk stores) can be found http://gemfire.docs.pivotal.io/geode/developing/storing_data_on_disk/chapter_overview.html[here]. [[bootstrap-annotation-config-continuous-queries]] @@ -1632,26 +1641,26 @@ http://gemfire.docs.pivotal.io/geode/developing/storing_data_on_disk/chapter_ove Another very important and useful feature of Pivotal GemFire is http://gemfire.docs.pivotal.io/geode/developing/continuous_querying/chapter_overview.html[Continuous Querying]. -In a world of Internet-enabled things, events and streams of data are coming in from everywhere. Being able to handle -and process a large stream of data and react to events in real-time, as they happen, is becoming an increasingly -important requirement for many applications. One example is self-driving vehicles. Being able to receive, filter, -transform, analyze and act on data in real-time is a key differentiator and characteristic of real-time enabled +In a world of Internet-enabled things, events and streams of data come from everywhere. Being able to handle +and process a large stream of data and react to events in real time is an increasingly +important requirement for many applications. One example is self-driving vehicles. Being able to receive, filter, +transform, analyze, and act on data in real time is a key differentiator and characteristic of real-time applications. -Fortunately, Pivotal GemFire was ahead of its time in this regard. Using _Continuous Queries_ (CQ), a client application -can express the data, or events it is interested in and register listeners to handle and process the events as they -occur. The data that a client application may be interested in is expressed as an OQL query, where the query predicate -is used to filter, or identify the data of interests. When data is changed or added, and it matches the criteria +Fortunately, Pivotal GemFire was ahead of its time in this regard. By using Continuous Queries (CQ), a client application +can express the data or events it is interested in and register listeners to handle and process the events as they +occur. The data that a client application may be interested in is expressed as an OQL query, where the query predicate +is used to filter or identify the data of interest. When data is changed or added and it matches the criteria defined in the query predicate of the registered CQ, the client application is notified. -_Spring Data for Pivotal GemFire_ makes defining and registering CQs along with an associated listener to handle and process CQ -events without all the cruft of Pivotal GemFire's plumbing, a non-event (no pun intended). SDG's new Annotation-based -configuration for CQs builds on the existing _Continuous Query_ support in the -<>. +Spring Data for Pivotal GemFire makes it easy to define and register CQs, along with an associated listener to handle and process CQ +events without all the cruft of Pivotal GemFire's plumbing. SDG's new annotation-based +configuration for CQs builds on the existing continuous query support in the +<>. -For instance, say a Book publisher wants to register interests in and receive notification anytime orders (demand) -for a `Book` exceeds the current inventory (supply), then the publisher's print application might register -the following CQ... +For instance, say a book publisher wants to register interest in and receive notification any time orders (demand) +for a `Book` exceeds the current inventory (supply). Then the publisher's print application might register +the following CQ: .Spring `ClientCache` application with registered CQ and Listener. [source, java] @@ -1678,41 +1687,41 @@ class PublisherPrintApplication { } ---- -To enable _Continuous Queries_, simply annotate your application class with `@EnableContinuousQueries`. +To enable continuous queries, annotate your application class with `@EnableContinuousQueries`. -Defining _Continuous Queries_ is as simple as annotating any Spring `@Component` annotated POJO class methods -with the `@ContinuousQuery` annotation, in similar fashion to SDG's Function annotated POJO methods. A POJO method -defined with a CQ using the `@ContinuousQuery` annotation will be called anytime data matching the query predicate +Defining Continuous Queries consists of annotating any Spring `@Component`-annotated POJO class methods +with the `@ContinuousQuery` annotation (in similar fashion to SDG's function-annotated POJO methods). A POJO method +defined with a CQ by using the `@ContinuousQuery` annotation is called any time data matching the query predicate is added or changed. Additionally, the POJO method signature should adhere to the requirements outlined in the section on -<>. +<>. -See the `@EnableContinuousQueries` and `@ContinuousQuery` annotation _Javadoc_ for more details on +See the https://docs.spring.io/spring-data/gemfire/docs/current/api/org/springframework/data/gemfire/config/annotation/EnableContinuousQueries.html[`@EnableContinuousQueries`] and https://docs.spring.io/spring-data/gemfire/docs/current/api/index.html?org/springframework/data/gemfire/config/annotation/EnableContinuousQueries.html[`@ContinuousQuery`] annotation Javadoc for more details on available attributes and configuration settings. -More details on _Spring Data for Pivotal GemFire's_ Continuous Query support can be found +More details on Spring Data for Pivotal GemFire's continuous query support can be found <>. -More details on Pivotal GemFire's Continuous Queries can be found +More details on Pivotal GemFire's continuous queries can be found http://gemfire.docs.pivotal.io/geode/developing/continuous_querying/chapter_overview.html[here]. [[bootstrap-annotation-config-caching]] == Configuring Spring's Cache Abstraction -With _Spring Data for Pivotal GemFire_, Pivotal GemFire can be used as a caching provider in Spring's -https://docs.spring.io/spring/docs/current/spring-framework-reference/integration.html#cache[Cache Abstraction]. +With Spring Data for Pivotal GemFire, Pivotal GemFire can be used as a caching provider in Spring's +https://docs.spring.io/spring/docs/current/spring-framework-reference/integration.html#cache[cache abstraction]. -In _Spring's Cache Abstraction_, the caching annotations (e.g. `@Cacheable`) identify the cache on which a cache lookup -is performed before invoking a potentially expensive operation, or where the results of an application service method +In Spring's cache abstraction, the caching annotations (such as `@Cacheable`) identify the cache on which a cache lookup +is performed before invoking a potentially expensive operation or where the results of an application service method are cached after the operation is invoked. -In _Spring Data for Pivotal GemFire_, a Spring `Cache` corresponds directly to a Region. The Region must exist before any -`@Cacheable` application service methods are called. This is true for any of Spring's caching annotations -(i.e. `@Cacheable`, `@CachePut` and `@CacheEvict`) that identify the cache to use in the operation. +In Spring Data for Pivotal GemFire, a Spring `Cache` corresponds directly to a region. The region must exist before any +`@Cacheable` application service methods are called. This is true for any of Spring's caching annotations +(that is, `@Cacheable`, `@CachePut` and `@CacheEvict`) that identify the cache to use in the operation. -For instance, our publisher's Point-of-Sale (POS) application might have a feature to determine, or lookup -the `Price` of a `Book` during a sales transaction. +For instance, our publisher's Point-of-Sale (PoS) application might have a feature to determine or lookup +the `Price` of a `Book` during a sales transaction, as the following example shows: [source, java] ---- @@ -1733,10 +1742,10 @@ class PointOfSaleService } ---- -To make the application developer's life easier when using _Spring Data for Pivotal GemFire_ and Pivotal GemFire with -_Spring's Cache Abstraction_, 2 new features have been added to the **new** Annotation-based configuration model. +To make your work easier when you use Spring Data for Pivotal GemFire and Pivotal GemFire with +Spring's cache abstraction, two new features have been added to the ne annotation-based configuration model. -Given the following Spring caching configuration... +Consider the following Spring caching configuration: .Enabling Caching using Pivotal GemFire with Spring Data for Pivotal GemFire [source, java] @@ -1774,7 +1783,7 @@ class CachingConfiguration { } ---- -Using _Spring Data for Pivotal GemFire's_ new features, the same caching configuration can be simplified to... +Using Spring Data for Pivotal GemFire's new features, you can simplify the same caching configuration to the following: .Enabling Pivotal GemFire Caching [source, java] @@ -1790,80 +1799,80 @@ class CachingConfiguration { } ---- -First, the `@EnableGemfireCaching` annotation replaces both the Spring `EnableCaching` annotation along with +First, the `@EnableGemfireCaching` annotation replaces both the Spring `@EnableCaching` annotation and the need to declare an explicit `cacheManager` bean definition in the Spring config. Second, the `@EnableCachingDefinedRegions` annotation, like the `@EnableEntityDefinedRegions` annotation described in -<>, inspects all the Spring application, caching annotated -service components to identify all the caches that will be needed by the application at runtime and creates Regions +"`<>`", inspects the entire Spring application, caching annotated +service components to identify all the caches that are needed by the application at run time and creating regions in Pivotal GemFire for these caches on application startup. -The Region created is local to the application process that created the Region. If the application is a peer `Cache`, -then the Region will only exist on the application node. If the application is a `ClientCache`, then SDG creates -a client `PROXY` Region and expects that a Region with the same name already exists on the servers in the cluster. +The created region is local to the application process that created the region. If the application is a peer `Cache`, +the Region exists only on the application node. If the application is a `ClientCache`, then SDG creates +a client `PROXY` Region and expects that a region with the same name already exists on the servers in the cluster. NOTE: SDG cannot determine the cache required by a service method using a Spring `CacheResolver` to resolve the cache used in the operation at runtime. -TIP: SDG also supports _JCache_, JSR-107 cache annotations on application service components as well. -Refer to the core https://docs.spring.io/spring/docs/current/spring-framework-reference/integration.html#cache-jsr-107[_Spring Framework Reference Guide_] -for the equivalent Spring caching annotation to use in place of _JCache_, JSR-107 caching annotations. +TIP: SDG also supports JCache (JSR-107) cache annotations on application service components. +See the core https://docs.spring.io/spring/docs/current/spring-framework-reference/integration.html#cache-jsr-107[_Spring Framework Reference Guide_] +for the equivalent Spring caching annotation to use in place of JCache caching annotations. -Refer to the section, <> for more details on -using Pivotal GemFire as a caching provider in _Spring's Cache Abstraction_. +Refer to the <> section for more details on +using Pivotal GemFire as a caching provider in Spring's Cache abstraction. -More details on _Spring's Cache Abstraction_ can be found +More details on Spring's Cache Abstraction can be found https://docs.spring.io/spring/docs/current/spring-framework-reference/integration.html#cache[here]. [[bootstrap-annotation-config-cluster]] == Configuring Cluster Configuration Push -This may be the most exciting **new** feature in _Spring Data for Pivotal GemFire_. +This may be the most exciting new feature in Spring Data for Pivotal GemFire. -When a client application class is annotated with `@EnableClusterConfiguration`, any Regions or Indexes defined -and declared as beans in the Spring context by the client application are "pushed" to the cluster of servers to -which the client is connected. Not only that, but this "push" is performed in such a way that Pivotal GemFire will -remember the configuration pushed by the client, when using HTTP. If all the nodes in the cluster go down, they -will come back up with the same configuration as before. +When a client application class is annotated with `@EnableClusterConfiguration`, any regions or indexes defined +and declared as beans in the Spring context by the client application are "`pushed`" to the cluster of servers to +which the client is connected. Not only that, but this "`push`" is performed in such a way that Pivotal GemFire +remembers the configuration pushed by the client when using HTTP. If all the nodes in the cluster go down, they +come back up with the same configuration as before. -In a sense, this feature is not much different than if a user were to use _Gfsh_ to create the Regions and Indexes -on all the servers in the cluster, manually. Except now, with _Spring Data for Pivotal GemFire_, users does **not** need to use -_Gfsh_ to create Regions and Indexes. The user's _Spring Boot_ application, enabled with the power of -_Spring Data for Pivotal GemFire_, already contains all the configuration meta-data needed to create Regions and Indexes +In a sense, this feature is not much different than if a user were to use Gfsh to manually create the regions and indexes +on all the servers in the cluster. Except that now, with Spring Data for Pivotal GemFire, you need not use +Gfsh to create regions and indexes. Your Spring Boot application, enabled with the power of +Spring Data for Pivotal GemFire, already contains all the configuration metadata needed to create regions and indexes for the user. -When users are using the _Spring Data Repository_ abstraction, we know all the Regions (e.g. `@Region` annotated -entity types) and Indexes (e.g. `@Indexed` annotated entity fields and properties) that the users' application -will need. When users are using _Spring's Cache Abstraction_, we also know all the Regions for all the caches -identified in the caching annotations needed by the application's service components. Essentially, the user is -already telling us everything we need to know just by developing her application with the entire _Spring Framework_ -and all of its provided services, infrastructure, etc, whether expressed in Annotation meta-data, Java, XML +When you use the Spring Data repository abstraction, we know all the Regions (such as those defined by the `@Region`annotated +entity types) and indexes (such as those defined by the `@Indexed`-annotated entity fields and properties) that your application +needs. When you use Spring's Cache Abstraction, we also know all the regions for all the caches +identified in the caching annotations needed by the application's service components. Essentially, you are +already telling us everything we need to know by developing your application with the Spring Framework +and all of its provided services, infrastructure, and other components, whether expressed in annotation metadata, Java, XML or otherwise, and whether for configuration, for mapping, or whatever purpose. -The point is, users can focus on their application business logic along with using the framework provided services -and supporting infrastructure (e.g. _Spring Data Repositories_, _Spring's Transaction Management_, _Spring Caching_, -and so on) and _Spring Data for Pivotal GemFire_ will take care of all the Pivotal GemFire plumbing required by those framework -services on the user's behalf. +The point is that you can focus on your application's business logic while using the framework's services +and supporting infrastructure (such Spring Data Repositories, Spring's Transaction Management, Spring Caching, +and so on) and Spring Data for Pivotal GemFire takes care of all the Pivotal GemFire plumbing required by those framework +services on the your behalf. Pushing configuration from the client to the servers in the cluster and having the cluster remember it is made possible -in part by the use of Pivotal GemFire's http://gemfire.docs.pivotal.io/geode/configuring/cluster_config/gfsh_persist.html[_Cluster Configuration_] -service. Pivotal GemFire's _Cluster Configuration_ service is also the same service used by _Gfsh_ to record -schema-related changes (e.g. `gfsh> create region --name=Example --type=PARTITION`) issued by the user to the cluster +in part by the use of Pivotal GemFire's http://gemfire.docs.pivotal.io/geode/configuring/cluster_config/gfsh_persist.html[Cluster Configuration] +service. Pivotal GemFire's Cluster Configuration service is also the same service used by Gfsh to record +schema-related changes (for example, `gfsh> create region --name=Example --type=PARTITION`) issued by the user to the cluster from the shell. -Of course, since the cluster "remembers" the prior configuration pushed by a client from a previous run, perhaps, -_Spring Data for Pivotal GemFire_ is careful not to stomp on any existing Regions and Indexes already defined in the servers. -This is especially important when Regions already contain data, for instance. +Of course, since the cluster may "`remember`" the prior configuration pushed by a client from a previous run, +Spring Data for Pivotal GemFire is careful not to stomp on any existing regions and indexes already defined in the servers. +This is especially important, for instance, when regions already contain data. -NOTE: Currently there is no option to overwrite any existing Region or Index definitions. To recreate a Region -or Index, the user must use _Gfsh_ to destroy the Region or Index first and then restart the client application -so that configuration will be pushed up to the server again. Alternatively a user can just use _Gfsh_ to -(re-)define the Regions and Indexes manually. +NOTE: Currently, there is no option to overwrite any existing region or index definitions. To re-create a region +or index, you must use Gfsh to first destroy the region or index and then restart the client application +so that configuration is pushed up to the server again. Alternatively, you can use Gfsh to +(re-)define the regions and indexes manually. -NOTE: Unlike _Gfsh_, _Spring Data for Pivotal GemFire_ only supports the creation of Regions and Indexes on the servers from a client. -For advanced configuration and use cases, _Gfsh_ should be used to manage the cluster. +NOTE: Unlike Gfsh, Spring Data for Pivotal GemFire supports the creation of regions and indexes only on the servers from a client. +For advanced configuration and use cases, you should use Gfsh to manage the cluster. -For a moment, just imagine the power expressed in the following configuration... +Consider the power expressed in the following configuration: .Spring `ClientCache` application [source, java] @@ -1879,77 +1888,78 @@ For a moment, just imagine the power expressed in the following configuration... class ClientApplication { .. } ---- -An application developer instantly gets a _Spring Boot_, Pivotal GemFire `ClientCache` application using -_Spring Data Repositories_ with _Spring's Cache Abstraction_, using Pivotal GemFire as the caching provider, -where Regions and Indexes are not only created on the client, but pushed to the servers in the cluster. +You instantly get a Spring Boot application that uses Pivotal GemFire `ClientCache`, +Spring Data repositories, Spring's cache abstraction, and Pivotal GemFire as the caching provider +(where regions and indexes are not only created on the client but pushed to the servers in the cluster). -All the application developer need do is define the application's domain model objects annotated with mapping -and Index annotations, define Repository interfaces supporting basic data access operations and simple queryies -for each of the entity types, define the service components containing the business logic transacting -the entities, declare the appropriate annotations on service methods that require caching, transactional -behavior, etc, and the developer is in business. Nothing the user did in this case pertains to infrastructure -and plumbing required in the application's back-end services (e.g. Pivotal GemFire). Database users have similar -features. Now Spring, Pivotal GemFire developers can too! +From there, you need to do the following: -When combined with a couple more _Spring Data for Pivotal GemFire_ Annotations... +* Define the application's domain model objects annotated with mapping and index annotations. +* Define repository interfaces to support basic data access operations and simple queries for each of the entity types. +* Define the service components containing the business logic transacting the entities. +* Declare the appropriate annotations on service methods that require caching, transactional behavior, and so on. + +Nothing in this case pertains to the infrastructure +and plumbing required in the application's back-end services (such as Pivotal GemFire). Database users have similar +features. Now Spring and Pivotal GemFire developers can, too. + +When combined with the following Spring Data for Pivotal GemFire annotations, this application really starts to take flight, with minimal effort: * `@EnableContinuousQueries` * `@EnableGemfireFunctionExecutions` * `@EnableGemfireCacheTransactions` -Then, this application is really going to start to take flight, with very minimal effort. - -See the `@EnableClusterConfiguration` annotation _Javadoc_ for more details. +See the https://docs.spring.io/spring-data/gemfire/docs/current/api/index.html?org/springframework/data/gemfire/config/annotation/EnableClusterConfiguration.html[`@EnableClusterConfiguration` annotation Javadoc] for more details. [[bootstrap-annotation-config-security]] == Configuring Security -Without a doubt, application _Security_ is extremely important and _Spring Data for Pivotal GemFire_ provides comprehensive support +Without a doubt, application Security is extremely important, and Spring Data for Pivotal GemFire provides comprehensive support for securing both Pivotal GemFire clients and servers. -Recently, Pivotal GemFire introduced a new http://gemfire.docs.pivotal.io/geode/managing/security/implementing_security.html[Integrated Security] framework, -replacing its old Authentication and Authorization Security model, for handling authentication and authorization. -One of the main features and benefits of this new Security framework is that it integrates with +Recently, Pivotal GemFire introduced a new http://gemfire.docs.pivotal.io/geode/managing/security/implementing_security.html[Integrated Security] framework +(replacing its old authentication and authorization security model) for handling authentication and authorization. +One of the main features and benefits of this new security framework is that it integrates with https://shiro.apache.org/[Apache Shiro] and can therefore delegate both authentication and authorization requests to Apache Shiro when enforcing security. -The following demonstrates how _Spring Data for Pivotal GemFire_ can simplify Pivotal GemFire's Security story even further. +The remainder of this section demonstrates how Spring Data for Pivotal GemFire can simplify Pivotal GemFire's Security story even further. [[bootstrap-annotation-config-security-server]] === Configuring Server Security -There are several different ways in which a user can configure Security for servers in an Pivotal GemFire cluster. +There are several different ways in which you can configure security for servers in an Pivotal GemFire cluster. -1. Implement the Pivotal GemFire `org.apache.geode.security.SecurityManager` interface and set Pivotal GemFire's -`security-manager` property to refer to your application `SecurityManager` implementation by the FQCN. +* Implement the Pivotal GemFire `org.apache.geode.security.SecurityManager` interface and set Pivotal GemFire's +`security-manager` property to refer to your application `SecurityManager` implementation by the fully qualified class name. Alternatively, users can construct and initialize an instance of their `SecurityManager` implementation and set it -with http://gemfire-91-javadocs.docs.pivotal.io/org/apache/geode/cache/CacheFactory.html#setSecurityManager-org.apache.geode.security.SecurityManager-[CacheFactory.setSecurityManager(:SecurityManager)] -method when creating an instance of an Pivotal GemFire peer `Cache`. +with the http://gemfire-91-javadocs.docs.pivotal.io/org/apache/geode/cache/CacheFactory.html#setSecurityManager-org.apache.geode.security.SecurityManager[CacheFactory.setSecurityManager(:SecurityManager)] +method when creating a Pivotal GemFire peer `Cache`. -2. Create an Apache Shiro https://shiro.apache.org/configuration.html[`shiro.ini`] file with the _users_, _roles_ -and _permissions_ defined for your application, then set the Pivotal GemFire `security-shiro-init` property to refer +* Create an Apache Shiro https://shiro.apache.org/configuration.html[`shiro.ini`] file with the users, roles, +and permissions defined for your application and then set the Pivotal GemFire `security-shiro-init` property to refer to this `shiro.ini` file, which must be available in the `CLASSPATH`. -3. Using just Apache Shiro, annotate your _Spring Boot_ application class with _Spring Data for Pivotal GemFire's_ **new** -`@EnableSecurity` annotation and define 1 or more Apache Shiro https://shiro.apache.org/realm.html[`Realms`] (as needed) -as beans in the Spring context for accessing your application's Security meta-data (i.e. _authorized users_, _roles_ -and _permissions_), and your done! +* Using only Apache Shiro, annotate your Spring Boot application class with Spring Data for Pivotal GemFire's new +`@EnableSecurity` annotation and define one or more Apache Shiro https://shiro.apache.org/realm.html[`Realms`] (as needed) +as beans in the Spring context for accessing your application's Security metadata (that is, authorized users, roles, +and permissions). -The problem with the first approach is that a user must implement his/her own `SecurityManager`, which can be quite -tedious and error prone. Implementing a custom `SecurityManager` does afford a user some flexibility in accessing -Security meta-data from whatever data source stores the meta-data, such as LDAP or even a proprietary, internal -data source, but then that is a problem already solved by configuring and using Apache Shiro `Realms`, which is more -universally known and non-Pivotal GemFire specific. +The problem with the first approach is that you must implement your own `SecurityManager`, which can be quite +tedious and error-prone. Implementing a custom `SecurityManager` offers some flexibility in accessing +security metadata from whatever data source stores the metadata, such as LDAP or even a proprietary, internal +data source. However, that problem has already been solved by configuring and using Apache Shiro `Realms`, which is more +universally known and non-Pivotal GemFire-specific. TIP: See Pivotal GemFire's Security examples for http://gemfire.docs.pivotal.io/geode/managing/security/authentication_examples.html[Authentication] -and http://gemfire.docs.pivotal.io/geode/managing/security/authorization_example.html[Authorization] as 1 possible way -to implement your own custom, application specific `SecurityManager`. However, this is strongly **not** recommended. +and http://gemfire.docs.pivotal.io/geode/managing/security/authorization_example.html[Authorization] as one possible way +to implement your own custom, application-specific `SecurityManager`. However, we strongly recommend *against* doing so. -The second approach using an Apache Shiro INI file is marginally better, but a user still needs to be familiar with -the INI file format in the first place. Additionally, an INI file is static and not easily updatable at runtime. +The second approach, using an Apache Shiro INI file, is marginally better, but you still need to be familiar with +the INI file format in the first place. Additionally, an INI file is static and not easily updatable at run time. -The third approach is the most ideal since it adheres to widely known and industry accepted concepts -(i.e. Apache Shiro's Security framework) and is easy to setup... +The third approach is the most ideal, since it adheres to widely known and industry-accepted concepts +(that is, Apache Shiro's Security framework) and is easy to set up, as the following example shows: .Spring server application using Apache Shiro [source, java] @@ -1972,24 +1982,27 @@ class ServerApplication { } ---- -TIP: The configured `Realm` shown in the example above could have easily been any of Apache Shiro's supported `Realms` -out-of-the-box: (https://shiro.apache.org/static/1.3.2/apidocs/org/apache/shiro/realm/activedirectory/package-frame.html[ActiveDirectory], -https://shiro.apache.org/static/1.3.2/apidocs/org/apache/shiro/realm/jdbc/package-frame.html[JDBC], -https://shiro.apache.org/static/1.3.2/apidocs/org/apache/shiro/realm/jndi/package-frame.html[JNDI], -https://shiro.apache.org/static/1.3.2/apidocs/org/apache/shiro/realm/ldap/package-frame.html[LDAP], -or even a `Realm` supporting the https://shiro.apache.org/static/1.3.2/apidocs/org/apache/shiro/realm/text/IniRealm.html[INI format]) -or perhaps a custom implementation of an Apache Shiro `Realm` implemented by the user. See Apache Shiro's -https://shiro.apache.org/realm.html[documentation on Realms] for more details. +TIP: The configured `Realm` shown in the preceding example could easily have been any of Apache Shiro's supported `Realms`: -When Apache Shiro is on the `CLASSPATH` of the servers in the cluster and 1 or more Apache Shiro `Realms` have been -defined as beans in the Spring context, _Spring Data for Pivotal GemFire_ will detect this configuration and use Apache Shiro -as the Security provider to secure your Pivotal GemFire servers when the `@EnableSecurity` annotation is used. +* https://shiro.apache.org/static/1.3.2/apidocs/org/apache/shiro/realm/activedirectory/package-frame.html[ActiveDirectory] +* https://shiro.apache.org/static/1.3.2/apidocs/org/apache/shiro/realm/jdbc/package-frame.html[JDBC] +* https://shiro.apache.org/static/1.3.2/apidocs/org/apache/shiro/realm/jndi/package-frame.html[JNDI] +* https://shiro.apache.org/static/1.3.2/apidocs/org/apache/shiro/realm/ldap/package-frame.html[LDAP] +* A `Realm` supporting the https://shiro.apache.org/static/1.3.2/apidocs/org/apache/shiro/realm/text/IniRealm.html[INI format]. -TIP: Earlier, information was posted on _Spring Data for Pivotal GemFire's_ support for Pivotal GemFire's **new** Integrated Security +You could even create a custom implementation of an Apache Shiro `Realm`. + +See Apache Shiro's https://shiro.apache.org/realm.html[documentation on Realms] for more details. + +When Apache Shiro is on the `CLASSPATH` of the servers in the cluster and one or more Apache Shiro `Realms` have been +defined as beans in the Spring context, Spring Data for Pivotal GemFire detects this configuration and uses Apache Shiro +as the security provider to secure your Pivotal GemFire servers when the `@EnableSecurity` annotation is used. + +TIP: You can find more information about Spring Data for Pivotal GemFire's support for Pivotal GemFire's new integrated security framework using Apache Shiro in this -https://spring.io/blog/2016/11/10/spring-data-geode-1-0-0-incubating-release-released[spring.io blob post]. +https://spring.io/blog/2016/11/10/spring-data-geode-1-0-0-incubating-release-released[spring.io blog post]. -See the `@EnableSecurity` annotation _Javadoc_ for more details on available attributes +See the https://docs.spring.io/spring-data/gemfire/docs/current/api/index.html?org/springframework/data/gemfire/config/annotation/EnableSecurity.html[`@EnableSecurity` annotation Javadoc] for more details on available attributes and associated configuration properties. More details on Pivotal GemFire Security can be found @@ -1998,26 +2011,26 @@ http://gemfire.docs.pivotal.io/geode/managing/security/chapter_overview.html[her [[bootstrap-annotation-config-security-client]] === Configuring Client Security -The Security story would not be complete without discussing how to secure Spring-based, Pivotal GemFire cache client +The Security story would not be complete without discussing how to secure Spring-based Pivotal GemFire cache client applications. -Pivotal GemFire's process to securing a client application is, well, rather involved. In a nutshell, a user essentially -needs to... +Pivotal GemFire's process for securing a client application is, honestly, rather involved. In a nutshell, you +need to: -1. Provide an implementation of the +. Provide an implementation of the http://gemfire-91-javadocs.docs.pivotal.io/org/apache/geode/security/AuthInitialize.html[`org.apache.geode.security.AuthInitialize`] interface. -2. Set the Pivotal GemFire `security-client-auth-init` (System) property to refer to the custom, application-provided +. Set the Pivotal GemFire `security-client-auth-init` (System) property to refer to the custom, application-provided `AuthInitialize` interface. -3. And finally, a user would typically specify the user credentials in a proprietary, Pivotal GemFire +. Specify the user credentials in a proprietary, Pivotal GemFire `gfsecurity.properties` file. -_Spring Data for Pivotal GemFire_ simplifies all of that using the same `@EnableSecurity` annotation as applied to -server applications. In other words, the same `@EnableSecurity` annotation handles Security for both client -and server applications. This makes it easier for users when they decide to switch their applications from -an embedded peer `Cache` application to a `ClientCache` application, for instance. Simply change the SDG annotation -from `@PeerCacheApplication` or `@CacheServerApplication` to `@ClientCacheApplication` and you are done. +Spring Data for Pivotal GemFire simplifies all of those steps by using the same `@EnableSecurity` annotation on +server applications. In other words, the same `@EnableSecurity` annotation handles security for both client +and server applications. This feature makes it easier for users when (for instance) they decide to switch their applications from +an embedded peer `Cache` application to a `ClientCache` application. Change the SDG annotation +from `@PeerCacheApplication` or `@CacheServerApplication` to `@ClientCacheApplication`, and you are done. -Effectively, all a user need do on the client is... +Effectively, all you need do on the client is the following: .Spring client application using `@EnableSecurity` [source, java] @@ -2028,8 +2041,7 @@ Effectively, all a user need do on the client is... class ClientApplication { .. } ---- -Then define the familiar _Spring Boot_ `application.properties` file containing the required _username_ and _password_ -Security properties and you are all set. +Then you can define the familiar Spring Boot `application.properties` file containing the required username and password, as the following example shows, and you are all set: .Spring Boot `application.properties` file with the required Security credentials [source, java] @@ -2038,13 +2050,11 @@ spring.data.gemfire.security.username=jackBlack spring.data.gemfire.security.password=b@cK!nB1@cK ---- -That was easy! +TIP: By default, Spring Boot can find an `application.properties` file when it is placed in the root of +the application's `CLASSPATH`. Of course, Spring supports may ways to locate resources by using its +https://docs.spring.io/spring/docs/current/spring-framework-reference/core.html#resources[resource abstraction]. -TIP: By default, _Spring Boot_ can find an `application.properties` file when placed in the root of -the application's `CLASSPATH`. Of course, Spring supports may ways to locate resources using its -https://docs.spring.io/spring/docs/current/spring-framework-reference/core.html#resources[Resource abstraction]. - -See the `@EnableSecurity` annotation _Javadoc_ for more details on available attributes +See the https://docs.spring.io/spring-data/gemfire/docs/current/api/index.html?org/springframework/data/gemfire/config/annotation/EnableSecurity.html[`@EnableSecurity` annotation Javadoc] for more details on available attributes and associated configuration properties. More details on Pivotal GemFire Security can be found @@ -2053,19 +2063,22 @@ http://gemfire.docs.pivotal.io/geode/managing/security/chapter_overview.html[her [[bootstrap-annotation-config-tips]] == Configuration Tips -The following tips will help users get the most out of using the **new** Annotation-based configuration model. +The following tips can help you get the most out of using the new annotation-based configuration model: + +* <> +* <> [[bootstrap-annotation-config-tips-organization]] -== Configuration Organization +=== Configuration Organization -As we saw in the section on <>, when -many Pivotal GemFire and/or _Spring Data for Pivotal GemFire_ features are enabled using Annotations, we start to stack a lot of -Annotations on the Spring `@Configuration` or `@SpringBootApplication` class. In this situation, it makes sense +As we saw in the section on <>, when +many Pivotal GemFire or Spring Data for Pivotal GemFire features are enabled by using annotations, we start to stack a lot of +annotations on the Spring `@Configuration` or `@SpringBootApplication` class. In this situation, it makes sense to start compartmentalizing the configuration a bit. -For instance, given... +For instance, consider the following declaration: -.Spring `ClientCache` application with the kitcken sink to boot +.Spring `ClientCache` application with the kitchen sink [source, java] ---- @SpringBootApplication @@ -2082,7 +2095,7 @@ For instance, given... class ClientApplication { .. } ---- -We could break this configuration down by concern. For example... +We could break this configuration down by concern, as follows: .Spring `ClientCache` application with the kitcken sink to boot [source, java] @@ -2120,66 +2133,66 @@ class QueriesConfiguration { class RepositoriesConfiguration { .. } ---- -Spring does not care. Organize your application configuration as you see fit. +While it does not matter to the Spring framework, we generally recommend aiming for readability, for the sake of the next person who has to maintain the code (which might be you at some point in the future). [[bootstrap-annotation-config-tips-undocumented-annotations]] -== Additional Configuration-based Annotations +=== Additional Configuration-based Annotations -_SDG Annotations you never heard of..._ +The following SDG Annotations were not discussed in this reference documentation, either because the annotation supports +a deprecated feature of Pivotal GemFire or because there are better, alternative ways to accomplishing the function that +the annotation provides: -The following SDG Annotations were not discussed in this reference documentation either because the Annotation supports -a deprecated feature of Pivotal GemFire, or there are better, alternative ways to accomplishing the function that -the Annotation provides. - -* `@EnableAuth` - enable Pivotal GemFire's old Authentication/Authorization Security model. (_Deprecated_; -use Pivotal GemFire's new _Integrated Security_ framework discussed <>). -Again, Pivotal GemFire's new _Integrated Security_ framework can be enabled on both clients and servers using SDG's -`@EnableSecurity` annotation as described in <>. -* `@EnableAutoRegionLookup` - Not recommended. Essentially, this Annotation supports finding Regions defined in -external configuration meta-data (e.g. `cache.xml`, or _Cluster Configuration_ when applied to a server) and registers -those Regions as beans in the Spring context automatically. Users should generally prefer Spring config when -using Spring and _Spring Data for Pivotal GemFire_. See <> -and <> instead. -* `@EnableBeanFactoryLocator` - enables the SDG `GemfireBeanFactoryLocator` feature, which is only useful, again, -when using external configuration meta-data (e.g. `cache.xml`). For example, if a user defines a `CacheLoader` on -a Region defined in `cache.xml`, the user can still auto-wire this `CacheLoader` with say, a relational database -`DataSource` bean defined in Spring config. This Annotation takes advantage of this SDG <> -and might be useful for users who have a large amount of legacy configuration meta-data, like `cache.xml` files. -* `@EnablePivotal GemFireAsLastResource` - is actually discussed in +* `@EnableAuth`: Enables Pivotal GemFire's old authentication and authorization security model. (Deprecated. +Pivotal GemFire's new integrated security framework can be enabled on both clients and servers by using SDG's +`@EnableSecurity` annotation, as described in "`<>`".) +* `@EnableAutoRegionLookup`: Not recommended. Essentially, this annotation supports finding regions defined in +external configuration metadata (such as `cache.xml` or cluster configuration when applied to a server) and automatically registers +those regions as beans in the Spring context. Users should generally prefer Spring configuration when +using Spring and Spring Data for Pivotal GemFire. See "`<>`" +and "`<>`" instead. +* `@EnableBeanFactoryLocator`: Enables the SDG `GemfireBeanFactoryLocator` feature, which is only useful +when using external configuration metadata (for example, `cache.xml`). For example, if you define a `CacheLoader` on +a region defined in `cache.xml`, you can still auto-wire this `CacheLoader` with, say, a relational database +`DataSource` bean defined in Spring configuration. This annotation takes advantage of this SDG <> +and might be useful if you have a large amount of legacy configuration metadata, such as `cache.xml` files. +* `@EnablePivotal GemFireAsLastResource`: Discussed in <> with Pivotal GemFire. -* `@EnableMcast` - enables Pivotal GemFire's old peer discovery mechanism using UDP-based Multi-cast Networking. -(_Deprecated_; users should be using Pivotal GemFire Locators instead; see -<>. -* `@EnableRegionDataAccessTracing` - is useful for debugging purposes; the Annotation enables tracing for all -data access operations performed on a Region by registering an AOP Aspect that proxies all Regions declared -as beans in the Spring context, intercepting the Region op and logging the event. +* `@EnableMcast`: Enables Pivotal GemFire's old peer discovery mechanism that uses UDP-based multi-cast networking. +(_Deprecated_. Use Pivotal GemFire locators instead. See +"`<>`". +* `@EnableRegionDataAccessTracing`: Useful for debugging purposes. The Annotation enables tracing for all +data access operations performed on a region by registering an AOP Aspect that proxies all regions declared +as beans in the Spring context, intercepting the region operation and logging the event. [[bootstrap-annotation-config-conclusion]] == Conclusion -As we learned in the previous sections, there is a tremendous amount of power provided by _Spring Data for Pivotal GemFire_'s -**new** Annotation-based configuration model. Hopefully, it lives up to its goal of making it easier for users +As we learned in the previous sections, Spring Data for Pivotal GemFire's +new annotation-based configuration model provides a tremendous amout of power. Hopefully, it lives up to its goal of making it easier for you to get started quickly when using Pivotal GemFire with Spring. -Keep in mind when using the new Annotations that it does not preclude you, the application developer, from using -Java config, or even XML, if you prefer. You can even combine all 3 approaches by using Spring's +Keep in mind that, when you use the new annotations, you can still use +Java configuration or XML configuration. You can even combine all three approaches by using Spring's https://docs.spring.io/spring/docs/current/javadoc-api/org/springframework/context/annotation/Import.html[`@Import`] and https://docs.spring.io/spring/docs/current/javadoc-api/org/springframework/context/annotation/ImportResource.html[`@ImportResource`] -annotations on a Spring `@Configuration` or `@SpringBootApplication` class, if you like. The moment you explicitly -provide a bean definition that would otherwise be provided by _Spring Data for Pivotal GemFire_ using an Annotation, -the Annotation-based configuration backs away. +annotations on a Spring `@Configuration` or `@SpringBootApplication` class. The moment you explicitly +provide a bean definition that would otherwise be provided by Spring Data for Pivotal GemFire by using an annotation, +the annotation-based configuration backs away. -In certain cases you may even need to fallback to Java config, as in the `Configurers` case, to handle more complex -or conditional configuration logic that is not easily expressed in or cannot be accomplished using Annotations. -Do not be alarmed; this is to be expected. +[NOTE] +==== +In certain cases, you may even need to fall back to Java configuration, as in the `Configurers` case, to handle more complex +or conditional configuration logic that is not easily expressed in or cannot be accomplished by using annotations. +Do not be alarmed. This behavior is to be expected. -For example, another case where Java config or XML will be needed is when configuring Pivotal GemFire WAN components, -which currently do not have any Annotation configuration support. However, defining and registering WAN components -is as simple as using the `org.springframework.data.gemfire.wan.GatewayReceiverFactoryBean` -and `org.springframework.data.gemfire.wan.GatewaySenderFactoryBean` API classes in Java configuration of your Spring +For example, another case where you need Java or XML configuration is when configuring Pivotal GemFire WAN components, +which currently do not have any annotation configuration support. However, defining and registering WAN components +requires only using the `org.springframework.data.gemfire.wan.GatewayReceiverFactoryBean` +and `org.springframework.data.gemfire.wan.GatewaySenderFactoryBean` API classes in the Java configuration of your Spring `@Configuration` or `@SpringBootApplication` classes (recommended). +==== -The Annotations were not meant to handle every situation; the Annotations were meant to help application developers -**get up and running** as **quickly** and as **easily** as possible, especially during development. +The Annotations were not meant to handle every situation. The Annotations were meant to help you +get up and running as quickly and as easily as possible, especially during development. We hope you will enjoy these new capabilities! diff --git a/src/main/asciidoc/reference/bootstrap.adoc b/src/main/asciidoc/reference/bootstrap.adoc index c0454d16..e37222eb 100644 --- a/src/main/asciidoc/reference/bootstrap.adoc +++ b/src/main/asciidoc/reference/bootstrap.adoc @@ -1,48 +1,48 @@ [[bootstrap]] = Bootstrapping Pivotal GemFire with the Spring container -_Spring Data for Pivotal GemFire_ provides full configuration and initialization of the Pivotal GemFire In-Memory Data Grid (IMDG) -using the _Spring_ IoC container. The framework includes several classes to help simplify the configuration of -Pivotal GemFire components including: Caches, Regions, Indexes, DiskStores, Functions, WAN Gateways, persistence backup -along with several other Distributed System components in order to support a variety of use cases with minimal effort. +Spring Data for Pivotal GemFire provides full configuration and initialization of the Pivotal GemFire In-Memory Data Grid (IMDG) +by using the Spring IoC container. The framework includes several classes to help simplify the configuration of +Pivotal GemFire components, including: Caches, Regions, Indexes, DiskStores, Functions, WAN Gateways, persistence backup, +and several other Distributed System components to support a variety of use cases with minimal effort. NOTE: This section assumes basic familiarity with Pivotal GemFire. For more information, see the Pivotal GemFire http://geode.apache.org/docs/[product documentation]. [[bootstrap:namespace:xml]] -== Advantages of using Spring over Pivotal GemFire `cache.xml` +== Advantages of Using Spring over Pivotal GemFire `cache.xml` -_Spring Data for Pivotal GemFire's_ XML namespace supports full configuration of the Pivotal GemFire In-Memory Data Grid (IMDG). -The XML namespace is the preferred way to configure Pivotal GemFire in a _Spring_ context in order to properly -manage Pivotal GemFire's lifecycle inside the _Spring_ container. While support for Pivotal GemFire's native `cache.xml` persists -for legacy reasons, Pivotal GemFire application developers 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, and environment profiles. Behind the XML namespace, _Spring Data for Pivotal GemFire_ makes extensive use of _Spring's_ -`FactoryBean` pattern to simplify the creation, configuration and initialization of Pivotal GemFire components. +Spring Data for Pivotal GemFire's XML namespace supports full configuration of the Pivotal GemFire In-Memory Data Grid (IMDG). +The XML namespace is one of two ways to configure Pivotal GemFire in a Spring context in order to properly +manage Pivotal GemFire's lifecycle inside the Spring container. The other way to configure Pivotal Gemfire in a Spring context is by using <>. While support for Pivotal GemFire's native `cache.xml` persists +for legacy reasons, Pivotal GemFire 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 (https://docs.spring.io/spring/docs/current/spring-framework-reference/core.html#expressions[Spring Expression Language]), and environment profiles. Behind the XML namespace, Spring Data for Pivotal GemFire makes extensive use of Spring's +`FactoryBean` pattern to simplify the creation, configuration, and initialization of Pivotal GemFire components. -Pivotal GemFire provides several callback interfaces, such as `CacheListener`, `CacheLoader` and `CacheWriter`, -that allow developers to add custom event handlers. Using _Spring's_ IoC container, these callbacks may be configured -as normal _Spring_ beans and injected into Pivotal GemFire components. This is a significant improvement over native `cache.xml`, +Pivotal GemFire 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 Pivotal GemFire components. This is a significant improvement over native `cache.xml`, which provides relatively limited configuration options and requires callbacks to implement Pivotal GemFire's `Declarable` -interface (see <> to see how you can still use `Declarables` within _Spring's_ IoC/DI container). +interface (see <> to see how you can still use `Declarables` within Spring's IoC/DI container). -In addition, IDEs, such as the _Spring Tool Suite_ (STS), provide excellent support for _Spring_ XML namespaces -including code completion, pop-up annotations, and real time validation, making them easy to use. +In addition, IDEs, such as the Spring Tool Suite (STS), provide excellent support for Spring XML namespaces, +including code completion, pop-up annotations, and real-time validation. [[bootstrap:namespace]] == Using the Core Namespace -To simplify configuration, _Spring Data for Pivotal GemFire_ provides a dedicated XML namespace for configuring core Pivotal GemFire -components. It is possible to configure beans directly using _Spring's_ standard `` definition. However, -all bean properties are exposed via the XML namespace so there is little benefit to using raw bean definitions. -For more information about XML Schema-based configuration in _Spring_, see the +To simplify configuration, Spring Data for Pivotal GemFire provides a dedicated XML namespace for configuring core Pivotal GemFire +components. It is possible to configure beans directly by using Spring's standard `` definition. However, +all bean properties are exposed through the XML namespace, so there is little benefit to using raw bean definitions. +For more information about XML Schema-based configuration in Spring, see the http://docs.spring.io/spring/docs/current/spring-framework-reference/htmlsingle/#xsd-config[appendix] -in the _Spring Framework_ reference documentation. +in the Spring Framework reference documentation. -NOTE: _Spring Data Repository_ support uses a separate XML namespace. See <> for more information -on how to configure _Spring Data for Pivotal GemFire_ Repositories. +NOTE: Spring Data Repository support uses a separate XML namespace. See <> for more information +on how to configure Spring Data for Pivotal GemFire Repositories. -To use the _Spring Data for Pivotal GemFire_ XML namespace, simply declare it in your _Spring_ XML configuration meta-data: +To use the Spring Data for Pivotal GemFire XML namespace, declare it in your Spring XML configuration meta-data, as the following example shows: [source,xml] ---- @@ -60,18 +60,18 @@ To use the _Spring Data for Pivotal GemFire_ XML namespace, simply declare it in ---- -<1> _Spring Data for Pivotal GemFire_ XML namespace prefix. Any name will do but through out this reference documentation, -`gfe` will be used. +<1> Spring Data for Pivotal GemFire 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_ will resolve the schema locally as it is included in the _Spring Data for Pivotal GemFire_ library. +<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 Pivotal GemFire library. <4> Example declaration using the XML namespace with the `gfe` prefix. [NOTE] ==== -It is possible to change the default namespace from `beans` to `gfe`. This is useful for XML configuration -composed mainly of Pivotal GemFire components as it avoids declaring the prefix. To achieve this, simply swap the namespace -prefix declaration above: +You can change the default namespace from `beans` to `gfe`. This is useful for XML configuration +composed mainly of Pivotal GemFire components, as it avoids declaring the prefix. To do so, swap the namespace +prefix declaration shown earlier, as the following example shows: [source,xml] ---- @@ -89,21 +89,17 @@ prefix declaration above: ---- -<1> The default namespace declaration for this XML document points to the _Spring Data for Pivotal GemFire_ XML namespace. -<2> The `beans` namespace prefix declaration for _Spring's_ raw bean definitions. +<1> The default namespace declaration for this XML document points to the Spring Data for Pivotal GemFire 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. ==== -:leveloffset: +1 - -include::{basedocdir}/reference/data-access.adoc[] -include::{basedocdir}/reference/cache.adoc[] -include::{basedocdir}/reference/region.adoc[] -include::{basedocdir}/reference/indexing.adoc[] -include::{basedocdir}/reference/diskstore.adoc[] -include::{basedocdir}/reference/snapshot.adoc[] -include::{basedocdir}/reference/function.adoc[] -include::{basedocdir}/reference/gateway.adoc[] - -:leveloffset: -1 +include::{basedocdir}/reference/data-access.adoc[leveloffset=+1] +include::{basedocdir}/reference/cache.adoc[leveloffset=+1] +include::{basedocdir}/reference/region.adoc[leveloffset=+1] +include::{basedocdir}/reference/indexing.adoc[leveloffset=+1] +include::{basedocdir}/reference/diskstore.adoc[leveloffset=+1] +include::{basedocdir}/reference/snapshot.adoc[leveloffset=+1] +include::{basedocdir}/reference/function.adoc[leveloffset=+1] +include::{basedocdir}/reference/gateway.adoc[v] diff --git a/src/main/asciidoc/reference/cache.adoc b/src/main/asciidoc/reference/cache.adoc index 8c9aca6b..acbf78ad 100644 --- a/src/main/asciidoc/reference/cache.adoc +++ b/src/main/asciidoc/reference/cache.adoc @@ -1,60 +1,60 @@ [[bootstrap:cache]] = Configuring a Cache -To use Pivotal GemFire, a developer needs to either create a new `Cache` or connect to an existing one. -With the current version of Pivotal GemFire, there can be only one open Cache per VM (technically, per `ClassLoader`). +To use Pivotal GemFire, you need to either create a new `Cache` or connect to an existing one. +With the current version of Pivotal GemFire, you can have only one open Cache per VM (more strictly, 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 standalone applications -and integration tests. However, in most typical production systems, most application processes will act as -cache clients, creating a `ClientCache` instance instead. This is described in the sections <> -and <>. +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 <> +and <> sections. -A peer cache with default configuration can be created with a very simple declaration: +A peer cache with default configuration can be created with the following simple declaration: [source,xml] ---- ---- -During Spring container initialization, any application context containing this cache definition will register -a `CacheFactoryBean` that creates a Spring bean named `gemfireCache` referencing a Pivotal GemFire `Cache` instance. -This bean will refer 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 will apply the default cache configuration. +During Spring container initialization, any application context containing this cache definition registers +a `CacheFactoryBean` that creates a Spring bean named `gemfireCache`, which references a Pivotal GemFire `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 Pivotal GemFire_ components that depend on the cache respect this naming convention, so there is no need -to explicitly declare the cache dependency. If you prefer, you can make the dependency explicit via the `cache-ref` -attribute provided by various SDG XML namespace elements. Also, you can easily override the cache's bean name using -the `id` attribute: +All Spring Data for Pivotal GemFire 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: [source,xml] ---- ---- -A Pivotal GemFire `Cache` can be fully configured using Spring, however, Pivotal GemFire's native XML configuration file, `cache.xml`, -is also supported. For situations where the Pivotal GemFire cache needs to be configured natively, simply provide a reference -to the Pivotal GemFire XML configuration file using the `cache-xml-location` attribute: +A Pivotal GemFire `Cache` can be fully configured using Spring. However, Pivotal GemFire's native XML configuration file, `cache.xml`, +is also supported. For situations where the Pivotal GemFire cache needs to be configured natively, you can provide a reference +to the Pivotal GemFire XML configuration file by using the `cache-xml-location` attribute, as follows: [source,xml] ---- ---- -In this example, if a cache needs to be created, it will use a file named `cache.xml` located in the classpath root +In this example, if a cache needs to be created, it uses a file named `cache.xml` located in the classpath root to configure it. NOTE: The configuration makes use of Spring's http://docs.spring.io/spring/docs/current/spring-framework-reference/htmlsingle/#resources[`Resource`] -abstraction to locate the file. This allows various search patterns to be used, depending on the runtime environment +abstraction to locate the file. The `Resource` abstraction lets various search patterns be used, depending on the runtime environment or the prefix specified (if any) in the resource location. -In addition to referencing an external XML configuration file, a developer may also specify Pivotal GemFire System +In addition to referencing an external XML configuration file, you can also specify Pivotal GemFire System http://geode.apache.org/docs/guide/11/reference/topics/gemfire_properties.html[properties] -using any of Spring's `Properties` support features. +that use any of Spring's `Properties` support features. -For example, the developer may use the `properties` element defined in the `util` namespace to define `Properties` -directly or load properties from a properties file: +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] ---- @@ -75,17 +75,17 @@ directly or load properties from a properties file: ---- -Using a properties file is recommended for externalizing environment specific settings outside +Using a properties file is recommended for externalizing environment-specific settings outside the application configuration. -NOTE: Cache settings apply only if a new cache needs to be created. If an open cache already exists in the VM, +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. [[bootstrap:cache:advanced]] == Advanced Cache Configuration For advanced cache configuration, the `cache` element provides a number of configuration options exposed as attributes -or child elements: +or child elements, as the following listing shows: [source,xml] ---- @@ -126,86 +126,86 @@ or child elements: ---- -<1> Various cache options are supported by attributes. For further information regarding anything shown in this example, -please consult the Pivotal GemFire http://docs.pivotal.io/gemfire[product documentation]. +<1> Attributes support various cache options. For further information regarding anything shown in this example, +see the Pivotal GemFire http://docs.pivotal.io/gemfire[product documentation]. The `close` attribute determines whether the cache should be closed when the Spring application context is closed. -The default is `true`, however, for use cases in which multiple application contexts use the cache +The default is `true`. However, for use cases in which multiple application contexts use the cache (common in web applications), set this value to `false`. -<2> Setting the `enable-auto-reconnect` attribute to true (default is false), allows a disconnected Pivotal GemFire member to +<2> Setting the `enable-auto-reconnect` attribute to `true` (the default is `false`) lets a disconnected Pivotal GemFire member automatically reconnect and rejoin the Pivotal GemFire cluster. See the Pivotal GemFire http://geode.apache.org/docs/guide/11/managing/autoreconnect/member-reconnect.html[product documentation] for more details. -<3> Setting the `use-bean-factory-locator` attribute to `true` (defaults to `false`) is only applicable when both -Spring (XML) configuration meta-data and Pivotal GemFire `cache.xml` is used to configure the Pivotal GemFire cache node -(whether client or peer). This option allows Pivotal GemFire components (e.g. `CacheLoader`) expressed in `cache.xml` -to be auto-wired with beans (e.g. `DataSource`) defined in the Spring application context. This option is typically +<3> Setting the `use-bean-factory-locator` attribute to `true` (it defaults to `false`) applies only when both +Spring (XML) configuration metadata and Pivotal GemFire `cache.xml` is used to configure the Pivotal GemFire cache node +(whether client or peer). This option lets Pivotal GemFire components (such as `CacheLoader`) expressed in `cache.xml` +be auto-wired with beans (such as `DataSource`) defined in the Spring application context. This option is typically used in conjunction with `cache-xml-location`. -<4> Setting the `use-cluster-configuration` attribute to `true` (default is `false`) enables a Pivotal GemFire member to +<4> Setting the `use-cluster-configuration` attribute to `true` (the default is `false`) enables a Pivotal GemFire member to retrieve the common, shared Cluster-based configuration from a Locator. See the Pivotal GemFire http://geode.apache.org/docs/guide/11/configuring/cluster_config/gfsh_persist.html[product documentation] for more details. -<5> Example of a `TransactionListener` callback declaration using a bean reference. The referenced bean must implement +<5> Example of a `TransactionListener` callback declaration that uses a bean reference. The referenced bean must implement http://geode.apache.org/releases/latest/javadoc/org/apache/geode/cache/TransactionListener.html[TransactionListener]. -A `TransactionListener` can be implemented to handle transaction related events (e.g. afterCommit, afterRollback). +A `TransactionListener` can be implemented to handle transaction related events (such as afterCommit and afterRollback). <6> Example of a `TransactionWriter` callback declaration using an inner bean declaration. The bean must implement http://geode.apache.org/releases/latest/javadoc/org/apache/geode/cache/TransactionWriter.html[TransactionWriter]. -The `TransactionWriter` is a callback that is allowed to veto a transaction. +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 http://geode.apache.org/releases/latest/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 +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> Enable Pivotal GemFire's http://geode.apache.org/docs/guide/11/developing/region_options/dynamic_region_creation.html[DynamicRegionFactory], +<8> Enables Pivotal GemFire's http://geode.apache.org/docs/guide/11/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 Pivotal GemFire transaction. [[bootstrap:cache:pdx-serialization]] === Enabling PDX Serialization -The example above includes a number of attributes related to Pivotal GemFire's enhanced serialization framework, PDX. +The preceding example includes a number of attributes related to Pivotal GemFire's enhanced serialization framework, PDX. While a complete discussion of PDX is beyond the scope of this reference guide, it is important to note that PDX -is enabled by registering a `PdxSerializer` which is specified via the `pdx-serializer` attribute. Pivotal GemFire provides -an implementing class `org.apache.geode.pdx.ReflectionBasedAutoSerializer` that uses Java Reflection, however, it is +is enabled by registering a `PdxSerializer`, which is specified by setting the `pdx-serializer` attribute. Pivotal GemFire 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 <> [[boostrap:cache:auto-reconnect]] -=== Enabling auto-reconnect +=== Enabling Auto-reconnect -Setting the `` attribute to `true`. -Generally, 'auto-reconnect' should only be enabled in cases where _Spring Data for Pivotal GemFire's_ XML namespace is used to +Generally, 'auto-reconnect' should only be enabled in cases where Spring Data for Pivotal GemFire's XML namespace is used to configure and bootstrap a new, non-application Pivotal GemFire Server to add to a cluster. In other words, 'auto-reconnect' -should not be enabled when _Spring Data for Pivotal GemFire_ is used to develop and build an Pivotal GemFire application that also happens +should not be enabled when Spring Data for Pivotal GemFire is used to develop and build a Pivotal GemFire application that also happens to be a peer cache member of the Pivotal GemFire cluster. -The main reason for this is that most Pivotal GemFire applications use references to the Pivotal GemFire cache or Regions in order to -perform data access operations. These references are "injected" by the Spring container into application components -(e.g. DAOs or Repositories) for use by the application. When a peer member is forcefully disconnected from the rest +The main reason for this restriction is that most Pivotal GemFire applications use references to the Pivotal GemFire 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 will shutdown -and all Pivotal GemFire component references (e.g. Cache, Regions, etc) become invalid. +peer members into a group too small to function as an independent distributed system, the peer member shuts down +and all Pivotal GemFire 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. -The JGroups stack shuts down, the Distributed System is put in a shutdown state and finally, the Cache is closed. +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 -Cache, Regions and other Pivotal GemFire 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. +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 Pivotal GemFire 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. -Pivotal GemFire makes no guarantee, even when using the Pivotal GemFire public Java API, that application Cache, Region or other -component references will be automatically refreshed by the reconnect operation. As such, Pivotal GemFire applications +Pivotal GemFire makes no guarantee (even when using the Pivotal GemFire public Java API) that application cache, region, or other +component references are automatically refreshed by the reconnect operation. As such, Pivotal GemFire 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, the application developer would have a clean way to know when to call -`ConfigurableApplicationContext.refresh()`, if even applicable for an application to do so, which is why -this "feature" of Pivotal GemFire is not recommended for peer cache Pivotal GemFire applications. +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 Pivotal GemFire is not recommended for peer cache Pivotal GemFire applications. For more information about 'auto-reconnect', see Pivotal GemFire's http://geode.apache.org/docs/guide/11/managing/autoreconnect/member-reconnect.html[product documentation]. @@ -214,28 +214,28 @@ http://geode.apache.org/docs/guide/11/managing/autoreconnect/member-reconnect.ht === Using Cluster-based Configuration Pivotal GemFire'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 will be compatible with +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 Pivotal GemFire Distributed System when the member joins. -This feature of _Spring Data for Pivotal GemFire_ (setting the `use-cluster-configuration` attribute to `true`) works in the same way +This feature of Spring Data for Pivotal GemFire (setting the `use-cluster-configuration` attribute to `true`) works in the same way as the `cache-xml-location` attribute, except the source of the Pivotal GemFire configuration meta-data comes from the network -via a Locator as opposed to a native `cache.xml` file residing in the local file system. +through a locator, as opposed to a native `cache.xml` file residing in the local file system. -All Pivotal GemFire native configuration meta-data, whether from `cache.xml` or from the Cluster Configuration Service, -gets applied before any _Spring_ (XML) configuration meta-data. As such, _Spring's_ config serves to "augment" the -native Pivotal GemFire configuration meta-data and would most likely be specific to the application. +All Pivotal GemFire 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 +native Pivotal GemFire configuration metadata and would most likely be specific to the application. -Again, to enable this feature, just specify the following in the _Spring_ XML config: +Again, to enable this feature, specify the following in the Spring XML config: [source,xml] ---- ---- -NOTE: While certain Pivotal GemFire tools, like _Gfsh_, have their actions "recorded" when schema-like changes are made -(e.g. `gfsh>create region --name=Example --type=PARTITION`), _Spring Data for Pivotal GemFire's_ configuration meta-data -is not recorded. The same is true when using Pivotal GemFire's public Java API directly; it too is not recorded. +NOTE: While certain Pivotal GemFire 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 Pivotal GemFire's configuration metadata +is not recorded. The same is true when using Pivotal GemFire's public Java API directly. It, too, is not recorded. For more information on Pivotal GemFire's Cluster Configuration Service, see the http://geode.apache.org/docs/guide/11/configuring/cluster_config/gfsh_persist.html[product documentation]. @@ -243,9 +243,9 @@ http://geode.apache.org/docs/guide/11/configuring/cluster_config/gfsh_persist.ht [[bootstrap:cache:server]] == Configuring a Pivotal GemFire CacheServer -_Spring Data for Pivotal GemFire_ includes dedicated support for configuring a +Spring Data for Pivotal GemFire includes dedicated support for configuring a http://geode.apache.org/releases/latest/javadoc/org/apache/geode/cache/server/CacheServer.html[CacheServer], -allowing complete configuration through the Spring container: +allowing complete configuration through the Spring container, as the following example shows: [source,xml] ---- @@ -277,35 +277,34 @@ allowing complete configuration through the Spring container: ---- -The configuration above illustrates the `cache-server` element and the many options available. +The preceding configuration shows the `cache-server` element and the many available options. -NOTE: Rather than hard-coding the port, this configuration uses _Spring's_ +NOTE: Rather than hard-coding the port, this configuration uses Spring's http://docs.spring.io/spring/docs/current/spring-framework-reference/htmlsingle/#xsd-config-body-schemas-context[context] -namespace to declare a `property-placeholder`. +namespace to declare a `property-placeholder`. A http://docs.spring.io/spring/docs/current/spring-framework-reference/htmlsingle/#beans-factory-placeholderconfigurer[property placeholder] -reads one or more properties files and then replaces property placeholders with values at runtime. This allows administrators -to change values without having to touch the main application configuration. _Spring_ also provides the +reads one or more properties files and then replaces property placeholders with values at runtime. Doing so lets administrators +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 the http://docs.spring.io/spring/docs/current/spring-framework-reference/htmlsingle/#beans-environment[environment abstraction] +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. -NOTE: To avoid initialization problems, the `CacheServer` started by _Spring Data for Pivotal GemFire_ will start *after* -the _Spring_ container has been fully initialized. This allows potential Regions, Listeners, Writers or Instantiators -defined declaratively to be fully initialized and registered before the server starts accepting connections. -Keep this in mind when programmatically configuring these elements as the server might start after your components +NOTE: To avoid initialization problems, the `CacheServer` started by Spring Data for Pivotal GemFire 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 Pivotal GemFire ClientCache -In addition to defining a Pivotal GemFire peer http://geode.apache.org/releases/latest/javadoc/org/apache/geode/cache/Cache.html[Cache], -_Spring Data for Pivotal GemFire_ also supports the definition of a Pivotal GemFire http://geode.apache.org/releases/latest/javadoc/org/apache/geode/cache/client/ClientCache.html[ClientCache] -in a _Spring_ context. A `ClientCache` definition is very similar in configuration and use to -the Pivotal GemFire peer <> and is supported by the `org.springframework.data.gemfire.client.ClientCacheFactoryBean`. +In addition to defining a Pivotal GemFire peer http://geode.apache.org/releases/latest/javadoc/org/apache/geode/cache/Cache.html[cache], +Spring Data for Pivotal GemFire also supports the definition of a Pivotal GemFire http://geode.apache.org/releases/latest/javadoc/org/apache/geode/cache/client/ClientCache.html[`ClientCache`] +in a Spring context. A `ClientCache` definition is similar in configuration and use to +the Pivotal GemFire peer <> and is supported by the `org.springframework.data.gemfire.client.ClientCacheFactoryBean`. -The simplest definition of a Pivotal GemFire cache client using default configuration can be accomplished with the following -declaration: +The simplest definition of a Pivotal GemFire cache client using default configuration follows: [source,xml] ---- @@ -314,16 +313,16 @@ declaration: ---- -`client-cache` supports many of the same options as the <> 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`, 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 <> 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 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 -to the cache definition: +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] ---- @@ -336,15 +335,15 @@ to the cache definition: ---- -The `` element also has a `ready-for-events` attribute. If set to `true`, the client cache -initialization will include a call to http://geode.apache.org/releases/latest/javadoc/org/apache/geode/cache/client/ClientCache.html#readyForEvents--[ClientCache.readyForEvents()]. +The `` element also has a `ready-for-events` attribute. If the attribute is set to `true`, the client cache +initialization includes a call to http://geode.apache.org/releases/latest/javadoc/org/apache/geode/cache/client/ClientCache.html#readyForEvents[`ClientCache.readyForEvents()`]. -Client-side configuration is covered in more detail in <>. +<> covers client-side configuration in more detail. [[bootstrap:cache:client:pool]] === Pivotal GemFire's DEFAULT Pool and Spring Data for Pivotal GemFire Pool Definitions -If a Pivotal GemFire `ClientCache` is local-only, then no Pool definition is required. For instance, a developer may define: +If a Pivotal GemFire `ClientCache` is local-only, then no Pool definition is required. For instance, you can define the following: [source,xml] ---- @@ -353,18 +352,16 @@ If a Pivotal GemFire `ClientCache` is local-only, then no Pool definition is req ---- -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 Pivotal GemFire's -http://geode.apache.org/releases/latest/javadoc/org/apache/geode/cache/client/ClientRegionShortcut.html[ClientRegionShortcut] +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 Pivotal GemFire's +http://geode.apache.org/releases/latest/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, then a Pool is required. There are several -ways to define and use a Pool in this case. +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, Pool and proxy-based Region are all defined, but not explicitly identified, _Spring Data for Pivotal GemFire_ -will resolve the references automatically for you. - -For example: +When a client cache, a pool, and a proxy-based region are all defined but not explicitly identified, Spring Data for Pivotal GemFire +resolves the references automatically, as the following example shows: [source,xml] ---- @@ -377,11 +374,11 @@ For example: ---- -In the example above, the client cache is identified as `gemfireCache`, the Pool as `gemfirePool` and the client Region -as "Example". However, the client cache will initialize Pivotal GemFire's DEFAULT Pool from `gemfirePool` and the client Region -will use the `gemfirePool` when distributing data between the client and the server. +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 Pivotal GemFire'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 Pivotal GemFire_ resolves the above configuration to the following: +Basically, Spring Data for Pivotal GemFire resolves the preceding configuration to the following: [source,xml] ---- @@ -394,8 +391,8 @@ Basically, _Spring Data for Pivotal GemFire_ resolves the above configuration to ---- -Pivotal GemFire still creates a Pool called "DEFAULT". _Spring Data for Pivotal GemFire_ will just cause the "DEFAULT" Pool to be -initialized from the `gemfirePool`. This is useful in situations where multiple Pools are defined and client Regions +Pivotal GemFire still creates a pool called `DEFAULT`. Spring Data for Pivotal GemFire 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. Consider the following: @@ -419,19 +416,18 @@ Consider the following: ---- -In this setup, the Pivotal GemFire client cache's "DEFAULT" Pool is initialized from "locatorPool" as specified with the -`pool-name` attribute. There is no _Spring Data for Pivotal GemFire_-defined `gemfirePool` since both Pools were explicitly -identified (named) "locatorPool" and "serverPool", respectively. +In this setup, the Pivotal GemFire client cache's `DEFAULT` pool is initialized from `locatorPool`, as specified by the +`pool-name` attribute. There is no Spring Data for Pivotal GemFire-defined `gemfirePool`, since both pools were explicitly +identified (named) -- `locatorPool` and `serverPool`, respectively. -The "Example" Region explicitly refers to and uses the "serverPool" exclusively. The "AnotherExample" Region uses -Pivotal GemFire's "DEFAULT" Pool, which was configured from the "locatorPool" based on the client cache bean definition's +The `Example` region explicitly refers to and exclusively uses the `serverPool`. The `AnotherExample` region uses +Pivotal GemFire's `DEFAULT` pool, which was configured from the `locatorPool` based on the client cache bean definition's `pool-name` attribute. -Finally, the "YetAnotherExample" Region will not use a Pool since it is `LOCAL`. +Finally, the `YetAnotherExample` egion 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 (i.e. ``) or a Pool bean explicitly named `gemfirePool` -(e.g. ``). +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, ``) or a pool bean explicitly named `gemfirePool` +(for example, ``). -NOTE: We could have either named "locatorPool", "gemfirePool", or made the Pool bean definition anonymous -and it would have the same effect as the above 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. diff --git a/src/main/asciidoc/reference/data-access.adoc b/src/main/asciidoc/reference/data-access.adoc index f9f54490..e7d22428 100644 --- a/src/main/asciidoc/reference/data-access.adoc +++ b/src/main/asciidoc/reference/data-access.adoc @@ -1,18 +1,18 @@ [[data-access]] = Using the Data Access Namespace -In addition to the core XML namespace (`gfe`), _Spring Data for Pivotal GemFire_ provides a data access XML namespace (`gfe-data`), +In addition to the core XML namespace (`gfe`), Spring Data for Pivotal GemFire provides a data access XML namespace (`gfe-data`), which is primarily intended to simplify the development of Pivotal GemFire client applications. This namespace currently contains -support for Pivotal GemFire <> and function <> -as well as includes a `` tag offering a convenient way to connect to a Pivotal GemFire cluster. +support for Pivotal GemFire <> and function <>, +as well as a `` tag that offers a convenient way to connect to a Pivotal GemFire cluster. [[data-access:datasource]] == An Easy Way to Connect to Pivotal GemFire For many applications, a basic connection to a Pivotal GemFire data grid using default values is sufficient. -_Spring Data for Pivotal GemFire's_ `` tag provides a simple way to access data. The data source creates -a `ClientCache` and connection `Pool`. In addition, it will query the cluster servers for all existing root Regions -and create an (empty) client Region proxy for each one. +Spring Data for Pivotal GemFire's `` 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 +22,12 @@ and create an (empty) client Region proxy for each one. ---- The `` tag is syntactically similar to ``. 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 will automatically create client Region beans for each Region defined on -cluster members connected to the Locator, so they may be seamlessly referenced by _Spring Data_ mapping annotations, -`GemfireTemplate`, and wired into application classes. +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. -Of course, you can explicitly configure client Regions. For example, if you want to cache data in local memory: +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] ---- diff --git a/src/main/asciidoc/reference/diskstore.adoc b/src/main/asciidoc/reference/diskstore.adoc index d7d4ae7e..82381f29 100644 --- a/src/main/asciidoc/reference/diskstore.adoc +++ b/src/main/asciidoc/reference/diskstore.adoc @@ -1,9 +1,7 @@ [[bootstrap:diskstore]] = Configuring a DiskStore -_Spring Data for Pivotal GemFire_ supports `DiskStore` configuration and creation via the `disk-store` element. - -For example: +Spring Data for Pivotal GemFire supports `DiskStore` configuration and creation through the `disk-store` element, as the following example shows: [source,xml] ---- @@ -14,10 +12,10 @@ For example: ---- -`DiskStores` are used by Regions for file system persistent backup and overflow of evicted entries -as well as persistent backup for WAN Gateways. Multiple Pivotal GemFire components may share the same `DiskStore`. -Additionally, multiple file system directories may be defined for a single `DiskStore` as shown in the example above. +`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 Pivotal GemFire components may share the same `DiskStore`. +Additionally, multiple file system directories may be defined for a single `DiskStore`, as shown in the preceding example. -Please refer to Pivotal GemFire's documentation for a complete explanation of +See Pivotal GemFire's documentation for a complete explanation of http://gemfire.docs.pivotal.io/95/geode/developing/storing_data_on_disk/chapter_overview.html[Persistence and Overflow] -along with configuration options on `DiskStores`. +and configuration options on `DiskStore` instances. diff --git a/src/main/asciidoc/reference/function-annotations.adoc b/src/main/asciidoc/reference/function-annotations.adoc index 02beb9ab..caa6658e 100644 --- a/src/main/asciidoc/reference/function-annotations.adoc +++ b/src/main/asciidoc/reference/function-annotations.adoc @@ -1,83 +1,80 @@ [[function-annotations]] = Annotation Support for Function Execution -== Introduction - -_Spring Data for Pivotal GemFire_ includes annotation support to simplify working with Pivotal GemFire -http://geode.apache.org/docs/guide/11/developing/function_exec/chapter_overview.html[Function Execution]. -Under-the-hood, the Pivotal GemFire API provides classes to implement and register Pivotal GemFire -http://geode.apache.org/releases/latest/javadoc/org/apache/geode/cache/execute/Function.html[Functions] +Spring Data for Pivotal GemFire includes annotation support to simplify working with Pivotal GemFire +http://geode.apache.org/docs/guide/11/developing/function_exec/chapter_overview.html[function execution]. +Under the hood, the Pivotal GemFire API provides classes to implement and register Pivotal GemFire +http://geode.apache.org/releases/latest/javadoc/org/apache/geode/cache/execute/Function.html[functions] that are deployed on Pivotal GemFire servers, which may then be invoked by other peer member applications or remotely from cache clients. Functions can execute in parallel, distributed among multiple Pivotal GemFire 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 Pivotal GemFire API supports remote execution of Functions targeted using various predefined scopes: -on Region, on members [in groups], on servers, etc. The implementation and execution of remote Functions, +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 Pivotal GemFire 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 Pivotal GemFire_, true to _Spring's_ core value proposition, aims to hide the mechanics of remote Function execution -and allow developers to focus on core POJO programming and business logic. To this end, _Spring Data for Pivotal GemFire_ introduces -annotations to declaratively register public methods of a POJO class as Pivotal GemFire Functions along with the ability to -invoke registered Functions [remotely] via annotated interfaces. +Spring Data for Pivotal GemFire, 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 Pivotal GemFire introduces +annotations to declaratively register the public methods of a POJO class as Pivotal GemFire functions along with the ability to +invoke registered functions (including remotely) by using annotated interfaces. -== Implementation vs Execution +== Implementation Versus Execution There are two separate concerns to address implementation and execution. -First is Function implementation (server-side), which must interact with the -http://geode.apache.org/releases/latest/javadoc/org/apache/geode/cache/execute/FunctionContext.html[FunctionContext] +The first is function implementation (server-side), which must interact with the +http://geode.apache.org/releases/latest/javadoc/org/apache/geode/cache/execute/FunctionContext.html[`FunctionContext`] to access the invocation arguments, -http://geode.apache.org/releases/latest/javadoc/org/apache/geode/cache/execute/ResultSender.html[ResultsSender] -as well as other execution context information. The Function implementation typically accesses the Cache and/or Regions +http://geode.apache.org/releases/latest/javadoc/org/apache/geode/cache/execute/ResultSender.html[`ResultsSender`], +and other execution context information. The function implementation typically accesses the cache and regions and is registered with the -http://geode.apache.org/releases/latest/javadoc/org/apache/geode/cache/execute/FunctionService.html[FunctionService] -under a unique Id. +http://geode.apache.org/releases/latest/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 -http://geode.apache.org/releases/latest/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 -http://geode.apache.org/releases/latest/javadoc/org/apache/geode/cache/execute/ResultCollector.html[ResultCollector] -to aggregate and acquire the execution results. In certain cases, a custom `ResultCollector` implementation +http://geode.apache.org/releases/latest/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 +http://geode.apache.org/releases/latest/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 Pivotal GemFire's client-server topology. While it is common for an application using a `ClientCache` -to invoke a Function on one or more Pivotal GemFire servers in a cluster, it is also possible to execute Functions +NOTE: 'Client' and 'Server' are used here in the context of function execution, which may have a different meaning +than client and server in Pivotal GemFire's client-server topology. While it is common for an application using a `ClientCache` +to invoke a function on one or more Pivotal GemFire 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 same constraints of being a peer member +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 Pivotal GemFire 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 -and any Filter (set of specific keys) associated with the `Execution`, etc. 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 only the local data. -Using _Spring_, a developer can write a simple POJO and use the _Spring_ container to bind one or more of it'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 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 +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 +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 int as the calling arguments. These are provided -in the `FunctionContext` as an array: +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 };` -Then, the _Spring_ container should be able to bind to any method signature similar to the following. -Let's ignore 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] ---- @@ -90,18 +87,18 @@ public void method5(String s1, ResultSender rs, int i2); public void method6(FunctionContest context); ---- -The general rule is that once any additional arguments, i.e. 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 (either 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 example above, 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. +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. === Annotations for Function Implementation -The following example illustrates how SDG's Function annotations are used to expose POJO methods -as Pivotal GemFire Functions: +The following example shows how SDG's function annotations are used to expose POJO methods +as Pivotal GemFire functions: [source,java] ---- @@ -120,58 +117,56 @@ public class ApplicationFunctions { } ---- -Note, the class itself must be registered as a _Spring_ bean and each Pivotal GemFire Function is annotated -with `@GemfireFunction`. In this example, _Spring's_ `@Component` annotation was used, but you may register the bean -by any method supported by _Spring_ (e.g. XML configuration or with a Java configuration class using _Spring Boot_). -This allows the _Spring_ container to 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 +Note that the class itself must be registered as a Spring bean and each Pivotal GemFire 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 Pivotal GemFire components such as the Cache and Regions. These may be injected into the class +TIP: The fact that the POJO Function class is a Spring bean may offer other benefits, since it shares +the `ApplicationContext` with Pivotal GemFire components, such as the cache and regions. These may be injected into the class if necessary. -_Spring_ creates the wrapper class and registers the Function(s) with Pivotal GemFire's Function Service. The Function id used -to register the Functions must be unique. Using convention it defaults to the simple (unqualified) method name. -The name can be explicitly defined using the `id` attribute of the `@GemfireFunction` annotation. +Spring creates the wrapper class and registers the functions with Pivotal GemFire'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. +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 Pivotal GemFire's -http://geode.apache.org/releases/latest/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`; -otherwise, if the method returns a value the `hasResult` attributes is set to `true`. +http://geode.apache.org/releases/latest/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`. +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 above. Presumably, the intention is to use the `ResultSender` directly +as shown in the `functionWithContext` method show previously. Presumably, the intention is to use the `ResultSender` directly to send results to the caller. -The `PojoFunctionWrapper` implements Pivotal GemFire's `Function` interface, binds method parameters and invokes the target method -in its `execute()` method. It also sends the method's return value using the `ResultSender`. +The `PojoFunctionWrapper` implements Pivotal GemFire'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`. === Batching Results -If the return type is an array or Collection, then some consideration must be given to how the results are returned. -By default, the `PojoFunctionWrapper` returns the entire array or Collection at once. If the number of elements -in the array or Collection quite is large, it may incur a performance penalty. To divide the payload into smaller, -more maneable chunks, you can set the `batchSize` attribute, as illustrated in `function2`, above. +If the return type is an array or `Collection`, then some consideration must be given to how the results are returned. +By default, the `PojoFunctionWrapper` returns the entire array or `Collection` at once. If the number of elements +in the array or `Collection` is quite large, it may incur a performance penalty. To divide the payload into smaller, +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 via the `FunctionContext` and use it directly +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. === Enabling Annotation Processing -In accordance with _Spring_ standards, you must explicitly activate annotation processing for `@GemfireFunction` -annotations. - -Using XML: +In accordance with Spring standards, you must explicitly activate annotation processing for `@GemfireFunction` +annotations. The following example activates annotation processing with XML: [source,xml] ---- ---- -Or by annotating a Java configuration class: +The following example activates annotations by annotating a Java configuration class: [source,java] ---- @@ -183,31 +178,31 @@ class ApplicationConfiguration { .. } [[function-execution]] == Executing a Function -A process invoking a remote Function needs to provide the Function's ID, calling arguments, the execution target -(onRegion, onServers, onServer, onMember, onMembers) and optionally, a Filter set. Using _Spring Data for Pivotal GemFire_, -all a developer need do is define an interface supported by annotations. _Spring_ will create a dynamic proxy -for the interface, which will use the `FunctionService` to create an `Execution`, invoke the `Execution` and coerce -the results to the defined return type, if necessary. This technique is very similar to the way -_Spring Data for Pivotal GemFire'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 Spring Data for Pivotal GemFire, +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 Pivotal GemFire'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`, `@OnMembers`. These annotations correspond to the `Execution` implementations -prodided by Pivotal GemFire's -http://geode.apache.org/releases/latest/javadoc/org/apache/geode/cache/execute/FunctionService.html[FunctionService]. +`@OnServer`, `@OnServers`, `@OnMember`, and `@OnMembers`. These annotations correspond to the `Execution` implementations +provided by Pivotal GemFire's +http://geode.apache.org/releases/latest/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 -http://geode.apache.org/releases/latest/javadoc/org/apache/geode/cache/execute/ResultCollector.html[ResultCollector] +`resultCollector` attribute whose value is the name of a Spring bean implementing the +http://geode.apache.org/releases/latest/javadoc/org/apache/geode/cache/execute/ResultCollector.html[`ResultCollector`] to use for the execution. -CAUTION: The proxy interface binds all declared methods to the same execution configuration. Although, it is expected -that single method interfaces will be common, all methods in the interface are backed by the same proxy instance +CAUTION: The proxy interface binds all declared methods to the same execution configuration. Although it is expected +that single method interfaces are common, all methods in the interface are backed by the same proxy instance and therefore all share the same configuration. -Here are a few examples: +The following listing shows a few examples: [source,java] ---- @@ -222,24 +217,24 @@ 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: +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: [source,xml] ---- ---- -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` namespace. The `base-package` attribute is required, +to avoid scanning the entire classpath. Additional filters are provided as described in the Spring http://docs.spring.io/spring/docs/current/spring-framework-reference/htmlsingle/#beans-scanning-filters[reference documentation]. -Optionally, a developer can annotate her Java configuration class: +Optionally, you can annotate your Java configuration class as follows: [source,java] ---- @@ -266,8 +261,8 @@ public class MyApplication { } ---- -Alternately, you can use a Function execution template directly. For example, `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` ==== @@ -280,22 +275,22 @@ String result = template.executeAndExtract("someFunction", myFilter, "hello", "w ---- ==== -Internally, Function `Executions` always return a `List`. `executeAndExtract` assumes a singleton `List` -containing the result and will attempt 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 following 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 Pivotal GemFire's_ Function annotation support combined with Pivotal GemFire's +When using Spring Data for Pivotal GemFire's function annotation support combined with Pivotal GemFire's http://geode.apache.org/docs/guide/11/developing/data_serialization/gemfire_pdx_serialization.html[PDX Serialization], there are a few logistical things to keep in mind. -As explained above, and by way of example, typically developers will define Pivotal GemFire Functions using POJO classes +As explained earlier in this section, and by way of example, you should typically define Pivotal GemFire functions by using POJO classes annotated with Spring Data for Pivotal GemFire -http://docs.spring.io/spring-data-gemfire/docs/current/api/org/springframework/data/gemfire/function/annotation/package-summary.html[Function annotations] -like so... +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] ---- @@ -307,11 +302,11 @@ public class OrderFunctions { } ---- -NOTE: The Integer type, count parameter is arbitrary as is the separation of the `Order` class and `OrderSource` Enum, +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. +function executions in the context of PDX. -Your `Order` and `OrderSource` enum might be as follows... +Your `Order` and `OrderSource` enum might be as follows: [source,java] ---- @@ -334,7 +329,7 @@ public enum OrderSource { } ---- -Of course, a developer may define a Function `Execution` interface to call the 'process' Pivotal GemFire Server Function... +Of course, you can define a function `Execution` interface to call the 'process' Pivotal GemFire server function, as follows: [source,java] ---- @@ -344,78 +339,78 @@ public interface OrderProcessingFunctions { } ---- -Clearly, this `process(..)` `Order` Function is being called from a client-side with a `ClientCache` -(i.e. ``) based application. This implies that the Function arguments must also be serializable. -The same is true when invoking peer-to-peer member Functions (e.g. `@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 a client-side with an application based on `ClientCache` +(that is ``). 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 the developer has configured Pivotal GemFire to use PDX for serialization (instead of Java serialization, for instance) -it is common for developers to also set the `pdx-read-serialized` attribute to *true* in their configuration -of the Pivotal GemFire server(s)... +Now, if you have configured Pivotal GemFire 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 Pivotal GemFire server(s), as follows: [source,xml] ---- ---- -Or from a Pivotal GemFire cache client application... +Alternatively, you can set the `pdx-read-serialized` attribute to `true` for a Pivotal GemFire cache client application, as follows: [source,xml] ---- ---- -This causes all values read from the cache (i.e. 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. -Pivotal GemFire will only serialize application domain object types that you have specifically configured (registered), -with either Pivotal GemFire's -http://gemfire-90-javadocs.docs.pivotal.io/org/apache/geode/pdx/ReflectionBasedAutoSerializer.html[ReflectionBasedAutoSerializer], -or specifically (and recommended) using a "custom" Pivotal GemFire -http://gemfire-90-javadocs.docs.pivotal.io/org/apache/geode/pdx/PdxSerializer.html[PdxSerializer]. If you are using -_Spring Data for Pivotal GemFire's_ Repository extension to _Spring Data Common's_ Repository abstraction and infrastructure, -you might even want to consider using _Spring Data for Pivotal GemFire's_ -http://docs.spring.io/spring-data-gemfire/docs/current/api/org/springframework/data/gemfire/mapping/MappingPdxSerializer.html[MappingPdxSerializer], -which uses a entity's mapping meta-data to determine data from the application domain object that will be serialized +Pivotal GemFire serializes only application domain object types that you have specifically configured (registered) +either by using Pivotal GemFire's +http://gemfire-90-javadocs.docs.pivotal.io/org/apache/geode/pdx/ReflectionBasedAutoSerializer.html[`ReflectionBasedAutoSerializer`], +or specifically (and recommended) by using a "`custom`" Pivotal GemFire +http://gemfire-90-javadocs.docs.pivotal.io/org/apache/geode/pdx/PdxSerializer.html[`PdxSerializer`]. If you use +Spring Data for Pivotal GemFire's repository extension to Spring Data Common's repository abstraction and infrastructure, +you might even want to consider using Spring Data for Pivotal GemFire'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 to the PDX instance. -What is less than apparent, though, is that Pivotal GemFire automatically handles Java Enum types regardless of whether they are -explicitly configured or not (i.e. registered with a `ReflectionBasedAutoSerializer` using a regex pattern -and the `classes` parameter, or are handled by a "custom" Pivotal GemFire `PdxSerializer`), despite the fact that Java Enums +What is less than apparent, though, is that Pivotal GemFire 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`" Pivotal GemFire `PdxSerializer`), despite the fact that Java enumerations implement `java.io.Serializable`. -So, when a developer sets `pdx-read-serialized` to *true* on Pivotal GemFire Servers where the Pivotal GemFire Functions -(including Spring Data for Pivotal GemFire Function annotated POJO classes) are registered, then the developer -may encounter surprising behavior when invoking the Function `Execution`. +So, when you set `pdx-read-serialized` to `true` on Pivotal GemFire servers where the Pivotal GemFire functions +(including Spring Data for Pivotal GemFire function-annotated POJO classes) are registered, then you +may encounter surprising behavior when invoking the function `Execution`. -What the developer may pass as arguments when invoking the Function is... +You might pass the following arguments when invoking the function: [source,java] ---- orderProcessingFunctions.process(new Order(123, customer, Calendar.getInstance(), items), OrderSource.ONLINE, 400); ---- -But, what the Pivotal GemFire Function on the Server gets is... +However, the Pivotal GemFire 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 http://gemfire-90-javadocs.docs.pivotal.io/org/apache/geode/pdx/PdxInstance.html[PDX instances]. -Again, this is all because `pdx-read-serialized` is set to *true*, which may be necessary in cases where -the Pivotal GemFire Servers are interacting with multiple different clients (e.g. Java, native clients, such as C++/C#, etc). +Again, this all happens because `pdx-read-serialized` is set to `true`, which may be necessary in cases where +the Pivotal GemFire servers interact with multiple different clients (for example, a combination of Java clients and native clients, such as C++, C#, and others). -This flies in the face of _Spring Data for Pivotal GemFire's_ "strongly-typed", Function annotated POJO class method signatures, -as the developer is expecting application domain object types, not PDX serialized instances. +This flies in the face of Spring Data for Pivotal GemFire's strongly-typed function-annotated POJO class method signatures, +as you should reasonably expect application domain object types, not PDX serialized instances. -So, _Spring Data for Pivotal GemFire_ includes enhanced Function support to automatically convert method arguments passed to -the Function that are of type PDX to the desired application domain object types defined by the Function method's +Consequently, Spring Data for Pivotal GemFire 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. -However, this also requires the developer to explicitly register a Pivotal GemFire `PdxSerializer` on the Pivotal GemFire Servers -where _Spring Data for Pivotal GemFire_ Function annotated POJOs are registered and used, e.g. ... +However, this also requires you to explicitly register a Pivotal GemFire `PdxSerializer` on the Pivotal GemFire Servers +where Spring Data for Pivotal GemFire function-annotated POJOs are registered and used, as the following example shows: [source,java] ---- @@ -424,13 +419,13 @@ where _Spring Data for Pivotal GemFire_ Function annotated POJOs are registered ---- -Alternatively, a developer my use Pivotal GemFire's -http://gemfire-90-javadocs.docs.pivotal.io/org/apache/geode/pdx/ReflectionBasedAutoSerializer.html[ReflectionBasedAutoSerializer] -for convenience. Of course, it is recommended that you use a "custom" `PdxSerializer` where possible to maintain -finer grained control over your serialization strategy. +Alternatively, you can use Pivotal GemFire's +http://gemfire-90-javadocs.docs.pivotal.io/org/apache/geode/pdx/ReflectionBasedAutoSerializer.html[`ReflectionBasedAutoSerializer`] +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 Pivotal GemFire_ is careful not to convert your Function arguments if you treat your Function arguments -generically, or as one of Pivotal GemFire's PDX types... +Finally, Spring Data for Pivotal GemFire is careful not to convert your function arguments if you treat your function arguments +generically or as one of Pivotal GemFire's PDX types, as follows: [source,java] ---- @@ -440,9 +435,9 @@ public Object genericFunction(String value, Object domainObject, PdxInstanceEnum } ---- -_Spring Data for Pivotal GemFire_ only converts PDX type data to the corresponding application domain types if and only if -the corresponding application domain types are on the classpath the the Function annotated POJO method expects it. +Spring Data for Pivotal GemFire 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. -For a good example of "custom", "composed" application-specific Pivotal GemFire `PdxSerializers` as well as appropriate -POJO Function parameter type handling based on the method signatures, see Spring Data for Pivotal GemFire'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. +For a good example of custom, composed application-specific Pivotal GemFire `PdxSerializers` as well as appropriate +POJO function parameter type handling based on the method signatures, see Spring Data for Pivotal GemFire'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. diff --git a/src/main/asciidoc/reference/function.adoc b/src/main/asciidoc/reference/function.adoc index 7f963db5..2c657909 100644 --- a/src/main/asciidoc/reference/function.adoc +++ b/src/main/asciidoc/reference/function.adoc @@ -1,20 +1,20 @@ [[bootstrap:function]] = Configuring the Function Service -_Spring Data for Pivotal GemFire_ provides <> support for implementing and registering +Spring Data for Pivotal GemFire provides <> support for implementing and registering Pivotal GemFire Functions. -_Spring Data for Pivotal GemFire_ also provides namespace support for registering Pivotal GemFire -http://geode.apache.org/releases/latest/javadoc/org/apache/geode/cache/execute/Function.html[Functions] -for remote Function execution. +Spring Data for Pivotal GemFire also provides namespace support for registering Pivotal GemFire +http://geode.apache.org/releases/latest/javadoc/org/apache/geode/cache/execute/Function.html[functions] +for remote function execution. -Please refer to Pivotal GemFire' http://geode.apache.org/docs/guide/11/developing/function_exec/chapter_overview.html[documentation] -for more information on the Function execution framework. +See Pivotal GemFire's http://geode.apache.org/docs/guide/11/developing/function_exec/chapter_overview.html[documentation] +for more information on the function execution framework. -Pivotal GemFire Functions are declared as _Spring_ beans and must implement the `org.apache.geode.cache.execute.Function` +Pivotal GemFire 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: +The namespace uses a familiar pattern to declare functions, as the following example shows: [source,xml] ---- diff --git a/src/main/asciidoc/reference/gateway.adoc b/src/main/asciidoc/reference/gateway.adoc index 0e0af21f..4999704d 100644 --- a/src/main/asciidoc/reference/gateway.adoc +++ b/src/main/asciidoc/reference/gateway.adoc @@ -2,15 +2,15 @@ = Configuring WAN Gateways WAN Gateways provide a way to synchronize Pivotal GemFire Distributed Systems across geographic areas. -_Spring Data for Pivotal GemFire_ provides namespace support for configuring WAN Gateways as illustrated in the following examples. +Spring Data for Pivotal GemFire provides namespace support for configuring WAN Gateways as illustrated in the following examples. == WAN Configuration in Pivotal GemFire 7.0 -In the example below, `GatewaySenders` are configured for a PARTITION Region by adding child elements to the Region -(`gateway-sender` and `gateway-sender-ref`). +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`. Also shown below is an example configuration -of an `AsyncEventQueue` which must also be wired into a Region (not shown). +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): [source,xml] ---- @@ -48,8 +48,8 @@ of an `AsyncEventQueue` which must also be wired into a Region (not shown). ---- -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`. +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] ---- @@ -60,6 +60,6 @@ The `GatewayReceiver` may also be configured with `EventFilters` and `TransportF ---- -Please refer to the Pivotal GemFire +See the Pivotal GemFire http://geode.apache.org/docs/guide/11/topologies_and_comm/multi_site_configuration/chapter_overview.html[documentation] for a detailed explanation of all the configuration options. diff --git a/src/main/asciidoc/reference/gemfire-bootstrap.adoc b/src/main/asciidoc/reference/gemfire-bootstrap.adoc index 75eabc0f..f5757b54 100644 --- a/src/main/asciidoc/reference/gemfire-bootstrap.adoc +++ b/src/main/asciidoc/reference/gemfire-bootstrap.adoc @@ -1,39 +1,37 @@ [[gemfire-bootstrap]] = Bootstrapping a Spring ApplicationContext in Pivotal GemFire -== Introduction - -Normally, a _Spring_-based application will <> using _Spring Data for Pivotal GemFire's. -Just by specifying a `` element using the _Spring Data for Pivotal GemFire_ XML namespace, a single, embedded Pivotal GemFire +Normally, a Spring based application <> by using Spring Data for Pivotal GemFire's caching features. +By specifying a `` element that uses the Spring Data for Pivotal GemFire XML namespace, a single embedded Pivotal GemFire peer `Cache` instance is created and initialized with default settings in the same JVM process as your application. -However, it is sometimes necessary, perhaps a requirement imposed by your IT organization, that Pivotal GemFire be fully managed -and operated using the provided Pivotal GemFire tool suite, such as with -http://geode.apache.org/docs/guide/11/tools_modules/gfsh/chapter_overview.html[Gfsh]. By using _Gfsh_, -Pivotal GemFire will bootstrap your _Spring_ application context rather than the other way around. Instead of -an application server, or a Java main class using _Spring Boot_, whatever, Pivotal GemFire does the bootstrapping and will -host your application. +However, it is sometimes necessary (perhaps as a requirement imposed by your IT organization) that Pivotal GemFire be fully managed +and operated by the provided Pivotal GemFire tool suite, perhaps with +http://geode.apache.org/docs/guide/11/tools_modules/gfsh/chapter_overview.html[Gfsh]. By using Gfsh, +Pivotal GemFire 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, Pivotal GemFire does the bootstrapping and +hosts your application. -Keep in mind, however, that Pivotal GemFire is not an application server. In addition, there are limitations to using -this approach where Pivotal GemFire cache configuration is concerned. +NOTE: Pivotal GemFire is not an application server. In addition, there are limitations to using +this approach where the Pivotal GemFire cache configuration is concerned. [[gemfire-bootstrap-gfsh]] == Using Pivotal GemFire to Bootstrap a Spring Context Started with Gfsh -In order to bootstrap a _Spring_ application context in Pivotal GemFire when starting a Pivotal GemFire Server process using _Gfsh_, -a user must make use of Pivotal GemFire's -http://geode.apache.org/docs/guide/11/basic_config/the_cache/setting_cache_initializer.html[Initalizer] functionality. -An Initializer block can declare a callback application that is launched after the cache is initialized by Pivotal GemFire. +In order to bootstrap a Spring application context in Pivotal GemFire when starting a Pivotal GemFire Server process by using Gfsh, +you must use Pivotal GemFire's +http://geode.apache.org/docs/guide/11/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 Pivotal GemFire. -An Initializer is declared within an -http://geode.apache.org/docs/guide/11/reference/topics/cache_xml.html#initializer[initializer] element -using a minimal snippet of Pivotal GemFire's native `cache.xml`. The `cache.xml` file is required in order to bootstrap -the _Spring_ application context, much like a minimal snippet of _Spring_ XML config is needed to bootstrap -a _Spring_ application context configured with component scanning (e.g. ``) +An initializer is declared within an +http://geode.apache.org/docs/guide/11/reference/topics/cache_xml.html#initializer[initializer] element by +using a minimal snippet of Pivotal GemFire'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 ``). -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]. -A typical, yet very minimal configuration for this class inside Pivotal GemFires's `cache.xml` file will look like this: +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 Pivotal GemFires's `cache.xml` file: [source,xml] ---- @@ -53,14 +51,14 @@ A typical, yet very minimal configuration for this class inside Pivotal GemFires ---- -The `SpringContextBootstrappingInitializer` class follows similar conventions as _Spring's_ `ContextLoaderListener` -class used to bootstrap a _Spring_ application context inside a Web Application, where application context -configuration files are specified with the `contextConfigLocations` Servlet Context Parameter. +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. In addition, the `SpringContextBootstrappingInitializer` class can also be used with a `basePackages` parameter -to specify a comma-separated list of base packages containing appropriately annotated application components -that the _Spring_ container will search in order to find and create _Spring_ beans and other application components -on the classpath: +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: [source,xml] ---- @@ -80,8 +78,8 @@ on the classpath: ---- -Then, with a properly configured and constructed `CLASSPATH` along with `cache.xml` file shown above, specified as -a command-line option when starting a Pivotal GemFire Server in _Gfsh_, the command-line would be: +Then, with a properly configured and constructed `CLASSPATH` and `cache.xml` file (shown earlier) specified as +a command-line option when starting a Pivotal GemFire Server in Gfsh, the command-line would be as follows: [source] ---- @@ -90,38 +88,38 @@ gfsh>start server --name=Server1 --log-level=config ... --cache-xml-file="/path/to/geode/cache.xml" ---- -The `application-context.xml` can be any valid _Spring_ context configuration meta-data including all the SDG namespace -elements. The only limitation with this approach is that a Pivotal GemFire cache cannot be configured using -the _Spring Data for Pivotal GemFire_ namespace. In other words, none of the `` element attributes, -such as `cache-xml-location`, `properties-ref`, `critical-heap-percentage`, `pdx-serializer-ref`, `lock-lease`, etc, -can be specified. If used, these attributes will be ignored. +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 Pivotal GemFire cache cannot be configured by using +the Spring Data for Pivotal GemFire namespace. In other words, none of the `` 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 Pivotal GemFire itself has already created an initialized the cache before the Initializer -gets invoked. As such, the cache will already exist and since it is a "Singleton", it cannot be re-initialized -or have any of it's configuration augmented. +The reason for this is that Pivotal GemFire 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 +or have any of its configuration augmented. [[gemfire-bootstrap-lazywiring]] -== Lazy-Wiring Pivotal GemFire Components +== Lazy-wiring Pivotal GemFire Components -_Spring Data for Pivotal GemFire_ already provides existing support for wiring Pivotal GemFire components, such as `CacheListeners`, -`CacheLoaders`, `CacheWriters` and so on, that are declared and created by Pivotal GemFire in `cache.xml` using -SDG's `WiringDeclarableSupport` class as described in <>. However, this only works -when _Spring_ is the one doing the bootstrapping (i.e. bootstrapping Pivotal GemFire). +Spring Data for Pivotal GemFire already provides support for wiring Pivotal GemFire components (such as `CacheListeners`, +`CacheLoaders`, `CacheWriters` and so on) that are declared and created by Pivotal GemFire in `cache.xml` by using +SDG's `WiringDeclarableSupport` class, as described in <>. However, this works only +when Spring is the one doing the bootstrapping (that is, when Spring bootstraps Pivotal GemFire). -When your _Spring_ application context is bootstrapped by Pivotal GemFire, then these Pivotal GemFire application components go unnoticed -since the _Spring_ application context does not even exist yet! The _Spring_ application context will not get created -until Pivotal GemFire calls the Initializer block, which only occurs after all the other Pivotal GemFire components and configuration +When your Spring application context is bootstrapped by Pivotal GemFire, these Pivotal GemFire application components go unnoticed, +because the Spring application context does not yet exist. The Spring application context does not get created +until Pivotal GemFire calls the initializer block, which only occurs after all the other Pivotal GemFire components and configuration have already been created and initialized. -So, in order to solve this problem, a new `LazyWiringDeclarableSupport` class was introduced that is, in a sense, -_Spring_ application context aware. The intention of this abstract base class is that any implementing class -will register itself to be configured by the _Spring_ container that will eventually be created by Pivotal GemFire -once the Initializer is called. In essence, this give your Pivotal GemFire defined application components a chance -to be configured and auto-wired with _Spring_ beans defined in the _Spring_ application context. +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 Pivotal GemFire +once the initializer is called. In essence, this gives your Pivotal GemFire application components a chance +to be configured and auto-wired with Spring beans defined in the Spring application context. -In order for your Pivotal GemFire application components to be auto-wired by the _Spring_ container, create an application class +In order for your Pivotal GemFire 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: +a Spring bean dependency, similar to the following example: [source,java] ---- @@ -135,13 +133,15 @@ public class UserDataSourceCacheLoader extends LazyWiringDeclarableSupport } ---- -As implied in the `CacheLoader` example above, you might necessarily (although, rarely) have defined both -a Region and `CacheListener` component in Pivotal GemFire `cache.xml`. The `CacheLoader` may need access to an application DAO, -or perhaps a _Spring_ application context defined JDBC `DataSource` for loading `Users` into a Pivotal GemFire `REPLICATE` Region +As implied in the `CacheLoader` example above, you might necessarily (though rarely) have defined both +a region and a `CacheListener` component in Pivotal GemFire `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 Pivotal GemFire `REPLICATE` region on start. -CAUTION: Be careful when mixing the different life-cycles of Pivotal GemFire and the _Spring_ Container together -in this manner as not all use cases and scenarios are supported. The Pivotal GemFire `cache.xml` configuration would be +CAUTION +==== +Be careful when mixing the different life-cycles of Pivotal GemFire and the Spring Container together +in this manner. Not all use cases and scenarios are supported. The Pivotal GemFire `cache.xml` configuration would be similar to the following (which comes from SDG's test suite): [source,xml] @@ -173,3 +173,4 @@ similar to the following (which comes from SDG's test suite): ---- +==== diff --git a/src/main/asciidoc/reference/indexing.adoc b/src/main/asciidoc/reference/indexing.adoc index 8f8a9492..6a0e76dd 100644 --- a/src/main/asciidoc/reference/indexing.adoc +++ b/src/main/asciidoc/reference/indexing.adoc @@ -1,31 +1,31 @@ [[bootstrap:indexing]] = Configuring an Index -Pivotal GemFire allows Indexes (or Indices) to be created on Region data to improve the performance of OQL queries. +Pivotal GemFire 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 Pivotal GemFire_ (SDG), Indexes are declared with the `index` element: +In Spring Data for Pivotal GemFire (SDG), indexes are declared with the `index` element, as the following example shows: [source,xml] ---- ---- -In _Spring Data for Pivotal GemFire's_ XML schema (a.k.a. SDG namespace), `Index` bean declarations are not bound to a _Region_, -unlike Pivotal GemFire's native `cache.xml`. Rather, they are top-level elements just like `<gfe:cache>`. This allows -a developer to declare any number of Indexes on any _Region_ whether they were just created or already exist, -a significant improvement over Pivotal GemFire's native `cache.xml` format. +In Spring Data for Pivotal GemFire's XML schema (also called the SDG namespace), `index` bean declarations are not bound to a region, +unlike Pivotal GemFire's native `cache.xml`. Rather, they are top-level elements similar to `<gfe:cache>`. This lets +you declare any number of indexes on any Region, whether they were just created or already exist -- a +significant improvement over Pivotal GemFire's native `cache.xml` format. -An `Index` must have a name. A developer may give the `Index` an explicit name using the `name` attribute, -otherwise the _bean name_ (i.e. value of the `id` attribute) of the `Index` bean definition is used as -the `Index` name. +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 `expression` and `from` clause form the main components of an `Index`, identifying the data to index -(i.e. the _Region_ identified in the `from` clause) along with what criteria (i.e. `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 lookup 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. -For example, if I have a `Customer` that has a `lastName` property... +Consider the following example, which has a `lastName` property: [source,java] ---- @@ -42,7 +42,7 @@ class Customer { } ---- -And, I also have an application defined SD[G] _Repository_ to query for `Customers`... +Now consider the following example, which has an application-defined SDG repository to query for `Customer` objects: [source,java] ---- @@ -54,185 +54,184 @@ interface CustomerRepository extends GemfireRepository { } ---- -Then, the SD[G] _Repository_ finder/query method would result in the following OQL statement being executed... +The SDG repository finder/query method results in the following OQL statement being run: [source,java] ---- SELECT * FROM /Customers c WHERE c.lastName = '$1' ---- -Therefore, I might want to create an `Index` like so... +Therefore, you might want to create an `Index` with a statement similar to the following: [source,xml] ---- ---- -The `from` clause must refer to a valid, existing _Region_ and is how an `Index` gets applied to a _Region_. -This is *not* _Sprig Data Pivotal GemFire_ specific; this is a feature of Pivotal GemFire. +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 Pivotal GemFire. -The `Index` `type` maybe 1 of 3 enumerated values defined by _Spring Data for Pivotal GemFire'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 Spring Data for Pivotal GemFire's +http://docs.spring.io/spring-data-gemfire/docs/current/api/org/springframework/data/gemfire/IndexType.html[`IndexType`] +enumeration: `FUNCTIONAL`, `HASH`, and `PRIMARY_KEY`. -Each of the enumerated values correspond to one of the http://gemfire-90-javadocs.docs.pivotal.io/org/apache/geode/cache/query/QueryService.html[QueryService] -`create[|Key|Hash]Index` methods invoked when the actual `Index` is to be created (or "defined"; more on "defining" -Indexes below). For instance, if the `IndexType` is `PRIMARY_KEY`, then the +Each of the enumerated values corresponds to one of the http://gemfire-90-javadocs.docs.pivotal.io/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 http://gemfire-90-javadocs.docs.pivotal.io/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 Pivotal GemFire_ XML schema for a full set of options. +See the Spring Data for Pivotal GemFire XML schema for a full set of options. -For more information on Indexing in Pivotal GemFire, see http://gemfire90.docs.pivotal.io/geode/developing/query_index/query_index.html[Working with Indexes] +For more information on indexing in Pivotal GemFire, see "`http://gemfire90.docs.pivotal.io/geode/developing/query_index/query_index.html[Working with Indexes]`" in Pivotal GemFire's User Guide. == Defining Indexes -In addition to creating Indexes upfront as `Index` bean definitions are processed by _Spring Data for Pivotal GemFire_ -on _Spring_ container initialization, you may also *define* all of your application Indexes prior to creating -them by using the `define` attribute, like so... +In addition to creating Indexes up front as `ndex` bean definitions are processed by Spring Data for Pivotal GemFire +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] ---- ---- -When `define` is set to `true` (defaults to `false`), this will not actually create the `Index` right then and there. -All "defined" Indexes are created all at once, when the _Spring_ `ApplicationContext` is "refreshed", or, that is, -when a `ContextRefreshedEvent` is published by the _Spring_ container. _Spring Data for Pivotal GemFire_ registers itself as -an `ApplicationListener` listening for the `ContextRefreshedEvent`. When fired, _Spring Data for Pivotal GemFire_ will call -http://gemfire-90-javadocs.docs.pivotal.io/org/apache/geode/cache/query/QueryService.html#createDefinedIndexes--[QueryService.createDefinedIndexes()]. +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 Pivotal GemFire registers itself as +an `ApplicationListener` listening for the `ContextRefreshedEvent`. When fired, Spring Data for Pivotal GemFire calls +http://gemfire-90-javadocs.docs.pivotal.io/org/apache/geode/cache/query/QueryService.html#createDefinedIndexes[`QueryService.createDefinedIndexes()`]. -Defining Indexes and creating them all at once helps promote speed and efficiency when creating Indexes. +Defining indexes and creating them all at once boosts speed and efficiency when creating indexes. -See http://gemfire90.docs.pivotal.io/geode/developing/query_index/create_multiple_indexes.html[Creating Multiple Indexes at Once] +See "`http://gemfire90.docs.pivotal.io/geode/developing/query_index/create_multiple_indexes.html[Creating Multiple Indexes at Once]`" for more details. == `IgnoreIfExists` and `Override` -Two _Spring Data for Pivotal GemFire_ `Index` configuration options warrant special mention here: `ignoreIfExists` and `override`. +Two Spring Data for Pivotal GemFire `Index` configuration options warrant special mention: `ignoreIfExists` and `override`. These options correspond to the `ignore-if-exists` and `override` attributes on the `<gfe:index>` element -in _Spring Data for Pivotal GemFire's_ XML schema, respectively. +in Spring Data for Pivotal GemFire's XML schema, respectively. -WARNING: Make sure you absolutely understand what you are doing before using either of these options. These options can -affect the performance and/or resources (e.g. memory) consumed by your application at runtime. As such, both of -these options are disabled (i.e. set to `false`) in SDG by default. +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. -NOTE: These options are only available in _Spring Data for Pivotal GemFire_ and exist to workaround known limitations -with Pivotal GemFire; there are no equivalent options or functionality available in Pivotal GemFire itself. +NOTE: These options are only available in Spring Data for Pivotal GemFire and exist to workaround known limitations +with Pivotal GemFire. Pivotal GemFire has no equivalent options or functionality. -Each option significantly differs in behavior and entirely depends on the type of Pivotal GemFire `Index` _Exception_ thrown. -This also means that neither option has any effect if a Pivotal GemFire Index-type _Exception_ is *not* thrown. These options -are meant to specifically handle Pivotal GemFire `IndexExistsExceptions` and `IndexNameConflictExceptions`, which can occur -for various, sometimes obscure reasons. But, in general... +Each option significantly differs in behavior and entirely depends on the type of Pivotal GemFire `Index` exception thrown. +This also means that neither option has any effect if a Pivotal GemFire Index-type exception is not thrown. These options +are meant to specifically handle Pivotal GemFire `IndexExistsException` and `IndexNameConflictException` instances, which can occur +for various, sometimes obscure reasons. The exceptions have the following causes: -* An http://gemfire-90-javadocs.docs.pivotal.io/org/apache/geode/cache/query/IndexExistsException.html[IndexExistsException] -is thrown when there exists another `Index` with the same definition but different name when attempting to +* An http://gemfire-90-javadocs.docs.pivotal.io/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 create an `Index`. -* An http://gemfire-90-javadocs.docs.pivotal.io/org/apache/geode/cache/query/IndexNameConflictException.html[IndexNameConflictException] +* An http://gemfire-90-javadocs.docs.pivotal.io/org/apache/geode/cache/query/IndexNameConflictException.html[`IndexNameConflictException`] is thrown when there exists another `Index` with the same name but possibly different definition when attempting to create an `Index`. -_Spring Data for Pivotal GemFire's_ default behavior is to *_fail-fast_*, always! So, neither `Index` _Exception_ will be "handled" -by default; these `Index` _Exceptions_ are simply wrapped in a SDG `GemfireIndexException` and rethrown. If you wish -for _Spring Data for Pivotal GemFire_ to handle them for you, then you can set either of these `Index` bean definition options. +Spring Data for Pivotal GemFire'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 Pivotal GemFire 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 less resources given it returns -the "existing" `Index` in both exceptional cases. +`IgnoreIfExists` always takes precedence over `Override`, primarily because it uses fewer resources (because it returns +the "`existing`" `index` in both exceptional cases). === `IgnoreIfExists` Behavior When an `IndexExistsException` is thrown and `ignoreIfExists` is set to `true` (or `<gfe:index ignore-if-exists="true">`), -then the `Index` that would have been created by this `Index` bean definition / declaration will be "*ignored*", -and the "existing" `Index` will be returned. +then the `index` that would have been created by this `index` bean definition or declaration is ignored, +and the existing `Index` is returned. -There is very little consequence in returning the "existing" `Index` since the `Index` "definition" is the same, -as deemed by Pivotal GemFire itself, *not* SDG. +There is little consequence in returning the existing `index`, since the `Index` definition is the same, +as determined by Pivotal GemFire itself, not SDG. -However, this also means that *no* `Index` with the "`name`" specified in your `Index` bean definition / declaration -will "actually" exist from Pivotal GemFire's perspective either (i.e. with -http://gemfire-90-javadocs.docs.pivotal.io/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_ will need to be changed. +However, this also means that no `index` with the "`name`" specified in your `Index` bean definition or declaration +actually exists from Pivotal GemFire's perspective (that is, with +http://gemfire-90-javadocs.docs.pivotal.io/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. -Now, when an `IndexNameConflictException` is thrown and `ignoreIfExists` is set to `true` (or `<gfe:index ignore-if-exists="true">`), -then the `Index` that would have been created by this `Index` bean definition / declaration will also be "*ignored*", -and the "existing" Index will be returned, just like when an `IndexExistsException` is thrown. +When an `IndexNameConflictException` is thrown and `ignoreIfExists` is set to `true` (or `<gfe:index ignore-if-exists="true">`), +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. -However, there is more risk in returning the "existing" `Index` and "*ignoring*" the application's definition -of the `Index` when an `IndexNameConflictException` is thrown since, for a `IndexNameConflictException`, while the "names" -of the conflicting Indexes are the same, the "definitions" could very well be different! This obviously 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. So, make sure you verify. +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 using the Pivotal GemFire API (the only means available). +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 Pivotal GemFire API (the only means available). === `Override` Behavior -When an `IndexExistsException` is thrown and `override` is set to `true` (or `<gfe:index override="true">`), then -the `Index` is effectively "_renamed_". Remember, `IndexExistsExceptions` are thrown when multiple Indexes exist, -all having the same "definition" but different "names". +When an `IndexExistsException` is thrown and `override` is set to `true` (or `<gfe:index override="true">`), +the `Index` is effectively renamed. Remember, `IndexExistsExceptions` are thrown when multiple indexes exist that +have the same definition but different names. -_Spring Data for Pivotal GemFire_ can only accomplish this using Pivotal GemFire'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 +Spring Data for Pivotal GemFire can only accomplish this by using Pivotal GemFire'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_" referring to the old `Index` by name must be changed. +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. -Now, when an `IndexNameConflictException` is thrown and `override` is set to `true` (or `<gfe:index override="true">`), -then potentially the "existing" `Index` will be "_re-defined_". I say "potentially", because it is possible for the -"like-named", "existing" `Index` to have exactly the same definition and name when an `IndexNameConflictException` +When an `IndexNameConflictException` is thrown and `override` is set to `true` (or `<gfe:index override="true">`), +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 will just return the "existing" Index as is, even on `override`. There is no harm in this -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 Pivotal GemFire's APIs. If it cannot find it, -nothing happens and a SDG `GemfireIndexException` is thrown wrapping the `IndexNameConflictException`. +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 Pivotal GemFire's APIs. If it cannot be found, +nothing happens and a SDG `GemfireIndexException` is thrown that wraps the `IndexNameConflictException`. -However, when the "definition" of the "existing" `Index` is different, then SDG will attempt to "_recreate_" the `Index` -using the `Index` definition specified in the `Index` bean definition /declaration. Make sure this is what you want +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. -=== How does `IndexNameConflictExceptions` actually happen? +=== 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 Pivotal GemFire (e.g. _Spring Data for Pivotal GemFire_, Pivotal GemFire _Cluster Config_, -maybe Pivotal GemFire native `cache.xml`, the API, etc, etc). You should definitely prefer 1 configuration method here +multiple configuration sources are used to configure Pivotal GemFire (Spring Data for Pivotal GemFire, Pivotal GemFire Cluster Config, +Pivotal GemFire 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?_ +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_ (e.g. "X"), Pivotal GemFire distributes the `Index` definition (and name) to other peer members -in the cluster that also host the same `PARTITION` _Region_ (i.e. "X"). The distribution of this `Index` definition -to and subsequent creation of this `Index` by peer members on a "need-to-know" basis (i.e. those hosting the same PR) +One particular case is an `Index` defined on a `PARTITION` region (PR). When an `Index` is defined on +a `PARTITION` region (for example, `X`), Pivotal GemFire 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. -During this window of time, it is possible that these "pending" PR `Indexes` will not be identifiable by Pivotal GemFire, -such as with a call to http://gemfire-90-javadocs.docs.pivotal.io/org/apache/geode/cache/query/QueryService.html#getIndexes--[QueryService.getIndexes()] -or with http://gemfire-90-javadocs.docs.pivotal.io/org/apache/geode/cache/query/QueryService.html#getIndexes-org.apache.geode.cache.Region-[QueryService.getIndexes(:Region)], -or even with http://gemfire-90-javadocs.docs.pivotal.io/org/apache/geode/cache/query/QueryService.html#getIndex-org.apache.geode.cache.Region-java.lang.String-[QueryService.getIndex(:Region, indexName:String)]. +During this window of time, it is possible that these pending PR `Indexes` cannot be identified by Pivotal GemFire -- +such as with a call to http://gemfire-90-javadocs.docs.pivotal.io/org/apache/geode/cache/query/QueryService.html#getIndexes[`QueryService.getIndexes()`] +with http://gemfire-90-javadocs.docs.pivotal.io/org/apache/geode/cache/query/QueryService.html#getIndexes-org.apache.geode.cache.Region[`QueryService.getIndexes(:Region)`], +or even with http://gemfire-90-javadocs.docs.pivotal.io/org/apache/geode/cache/query/QueryService.html#getIndex-org.apache.geode.cache.Region-java.lang.String[`QueryService.getIndex(:Region, indexName:String)`]. -As such, the only way for SDG or other Pivotal GemFire cache client applications (not involving _Spring_) to know for sure, -is to just attempt to create the `Index`. If it fails with either an `IndexNameConflictException`, -or even an `IndexExistsException`, then you will know. This is because the `QueryService` `Index` creation waits on -"pending" `Index` definitions, where as the other Pivotal GemFire API calls do not. +As a result, the only way for SDG or other Pivotal GemFire 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 Pivotal GemFire API calls do not. -In any case, SDG makes a best effort and attempts to inform the user what has or is happening along with -the corrective action. Given all Pivotal GemFire `QueryService.createIndex(..)` methods are synchronous, "blocking" operations, -then the state of Pivotal GemFire should be consistent and accessible after either of these Index-type _Exceptions_ are thrown, -in which case, SDG can inspect the state of the system and respond/act accordingly, based on the user's -desired configuration. +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 Pivotal GemFire `QueryService.createIndex(..)` methods are synchronous, blocking operations, +the state of Pivotal GemFire 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 all other cases, SDG will simply *_fail-fast_*! +In all other cases, SDG embraces a fail-fast strategy. diff --git a/src/main/asciidoc/reference/introduction.adoc b/src/main/asciidoc/reference/introduction.adoc index 9c68ea85..20752464 100644 --- a/src/main/asciidoc/reference/introduction.adoc +++ b/src/main/asciidoc/reference/introduction.adoc @@ -1,29 +1,29 @@ [[ref-introduction]] = Document Structure -The following chapters explain the core functionality offered by _Spring Data for Pivotal GemFire_. +The following chapters explain the core functionality offered by Spring Data for Pivotal GemFire: -<> describes the configuration support provided for configuring, initializing and accessing -Pivotal GemFire Caches, Regions, and other related Distributed System components. +* <> describes the configuration support provided for configuring, initializing, and accessing +Pivotal GemFire caches, regions, and related distributed system components. -<> explains the integration between the Pivotal GemFire APIs and the various data access features -available in _Spring_, such as data access, exception translation, transaction management and caching. +* <> explains the integration between the Pivotal GemFire APIs and the various data access features +available in Spring, such as data access, exception translation, transaction management, and caching. -<> describes enhancements to Pivotal GemFire's (de)serialization of managed objects. +* <> describes enhancements to Pivotal GemFire's serialization and deserialization of managed objects. -<> describes persistence mapping for POJOs stored in Pivotal GemFire using _Spring Data_. +* <> describes persistence mapping for POJOs stored in Pivotal GemFire using Spring Data. -<> describes how to create and use _Spring Data Repositories_ to access data -stored in Pivotal GemFire using basic CRUD and simple query operations. +* <> describes how to create and use Spring Data Repositories to access data +stored in Pivotal GemFire by using basic CRUD and simple query operations. -<> describes how to create and use Pivotal GemFire Functions using Annotations +* <> describes how to create and use Pivotal GemFire functions by using annotations to perform distributed computations where the data lives. -<> describes how to use Pivotal GemFire's Continuous Query (CQ) functionality -to process a stream of events based on interest defined and registered using a Pivotal GemFire OQL query. +* <> describes how to use Pivotal GemFire's Continuous Query (CQ) functionality +to process a stream of events based on interest defined and registered using a Pivotal GemFire OQL (Object Query Language) query. -<> describes how to bootstrap a _Spring_ `ApplicationContext` running in an Pivotal GemFire server -using _Gfsh_. +* <> describes how to bootstrap a Spring `ApplicationContext` running in an Pivotal GemFire server +by using `Gfsh`. -<> describes the examples provided with the distribution to illustrate the various features -available in _Spring Data for Pivotal GemFire_. +* <> describes the examples provided with the distribution to illustrate the various features +available in Spring Data for Pivotal GemFire. diff --git a/src/main/asciidoc/reference/lucene.adoc b/src/main/asciidoc/reference/lucene.adoc index a3eace43..f97b2607 100644 --- a/src/main/asciidoc/reference/lucene.adoc +++ b/src/main/asciidoc/reference/lucene.adoc @@ -1,16 +1,16 @@ [[bootstrap:lucene]] = Apache Lucene Integration -https://pivotal.io/pivotal-gemfire[Pivotal GemFire] integrates with http://lucene.apache.org/[Apache Lucene] to allow developers -to index and search on data stored in Pivotal GemFire using Lucene queries. Search-based queries also includes -the capability to page through query results. +https://pivotal.io/pivotal-gemfire[Pivotal GemFire] integrates with http://lucene.apache.org/[Apache Lucene] to let you +index and search on data stored in Pivotal GemFire by using Lucene queries. Search-based queries also include +the ability to page through query results. -Additionally, _Spring Data for Pivotal GemFire_ adds support for query projections based on _Spring Data Commons_ -Projection infrastructure. This feature enables the query results to be projected into first-class, -application domain types as needed or required by the application use case. +Additionally, Spring Data for Pivotal GemFire 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. -However, a Lucene `Index` must be created before any Lucene search-based query can be ran. A `LuceneIndex` -can be created in _Spring (Data for Pivotal GemFire)_ XML config like so... +A Lucene `Index` must be created before any Lucene search-based query can be run. A `LuceneIndex` +can be created in Spring (Data for Pivotal GemFire) XML config as follows: [source,xml] ---- @@ -18,8 +18,8 @@ can be created in _Spring (Data for Pivotal GemFire)_ XML config like so... ---- 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 using... +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] ---- @@ -37,15 +37,15 @@ and can be configured using... ---- -Of course, the `Map` can be specified as a top-level bean definition and referenced using the `ref` attribute -in the nested `` element like this, ``. +The `Map` can be specified as a top-level bean definition and referenced by using the `ref` attribute +in the nested `` element, as follows: ``. -Spring Data for Pivotal GemFire's `LuceneIndexFactoryBean` API and SDG's XML namespace also allows the addition of a +Spring Data for Pivotal GemFire's `LuceneIndexFactoryBean` API and SDG's XML namespace also let a http://gemfire-95-javadocs.docs.pivotal.io/org/apache/geode/cache/lucene/LuceneSerializer.html[`org.apache.geode.cache.lucene.LuceneSerializer`] -to be specified when creating the `LuceneIndex`. The `LuceneSerializer` is used to configure the way objects +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. -To add an `LuceneSerializer` to the `LuceneIndex`, you only need to... +The following example shows how to add an `LuceneSerializer` to the `LuceneIndex`: [source,xml] ---- @@ -56,7 +56,7 @@ To add an `LuceneSerializer` to the `LuceneIndex`, you only need to... ---- -Of course, you may specify the `LuceneSerializer` as a anonymous, nested bean definition as well, like so... +You can specify the `LuceneSerializer` as an anonymous, nested bean definition as well, as follows: [source,xml] ---- @@ -67,8 +67,8 @@ Of course, you may specify the `LuceneSerializer` as a anonymous, nested bean de ---- -Alternatively, a developer may declare or define a `LuceneIndex` in Spring Java config, -inside a `@Configuration` class with... +Alternatively, you can declare or define a `LuceneIndex` in Spring Java config, +inside a `@Configuration` class, as the following example shows: [source,java] ---- @@ -108,39 +108,39 @@ CustomLuceneSerializer myLuceneSerialier() { There are a few limitations of Pivotal GemFire's, Apache Lucene integration and support. -First, a `LuceneIndex` can only be created on an Pivotal GemFire `PARTITION` Region. +First, a `LuceneIndex` can only be created on a Pivotal GemFire `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 +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`. You may register this Spring https://docs.spring.io/spring/docs/current/javadoc-api/org/springframework/beans/factory/config/BeanFactoryPostProcessor.html[`BeanFactoryPostProcessor`] -in XML config using `` +in XML config by using `` The `o.s.d.g.config.support.LuceneIndexRegionBeanFactoryPostProcessor` may only be used when using SDG XML config. More details about Spring's `BeanFactoryPostProcessors` can be found https://docs.spring.io/spring/docs/current/spring-framework-reference/core.html#beans-factory-extension-factory-postprocessors[here]. It is possible that these Pivotal GemFire 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 `LuceneIndexFactoryBean` API takes a reference to the region directly as well, rather than just the region path. -This is more ideal if think about the case in which users may 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` will be 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 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: Additional, in the example above, you will notice the presence of Spring's `@DependsOn` annotation -on the "Books" Region bean definition. This is used to create a dependency from the "Books" Region bean -to the "bookTitleIndex" LuceneIndex bean definition ensuring that the `LuceneIndex` will be created before -the Region on which it applies. +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. -Now that we have a `LuceneIndex` we can perform Lucene based data access operations, such as queries. +Now that we have a `LuceneIndex`, we can perform Lucene-based data access operations, such as queries. == Lucene Template Data Accessors -_Spring Data for Pivotal GemFire_ provides 2 primary templates for Lucene data access operations, depending on +Spring Data for Pivotal GemFire 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 using Pivotal GemFire -http://gemfire-95-javadocs.docs.pivotal.io/org/apache/geode/cache/lucene/package-summary.html[Lucene types]. +The `LuceneOperations` interface defines query operations by using Pivotal GemFire +http://gemfire-95-javadocs.docs.pivotal.io/org/apache/geode/cache/lucene/package-summary.html[Lucene types], which are defined in the following interface definition: [source,java] ---- @@ -173,16 +173,17 @@ NOTE: The `[, int resultLimit]` indicates that the `resultLimit` parameter is op The operations in the `LuceneOperations` interface match the operations provided by the Pivotal GemFire's http://gemfire-95-javadocs.docs.pivotal.io/org/apache/geode/cache/lucene/LuceneQuery.html[LuceneQuery] interface. However, SDG has the added value of translating proprietary Pivotal GemFire 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 single store or repository. +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 -introduced by the underlying Pivotal GemFire or Apache Lucene APIs when they do and will occur. +Additionally, SDG's `LuceneOperations` interface can shield your application from interface-breaking changes +introduced by the underlying Pivotal GemFire or Apache Lucene APIs when they occur. -However, it would be remorse to only offer a Lucene Data Access Object (DAO) that only uses Pivotal GemFire -and Apache Lucene data types (e.g. Pivotal GemFire's `LuceneResultStruct`), therefore SDG gives you the +However, it would be sad to offer a Lucene Data Access Object (DAO) that only uses Pivotal GemFire +and Apache Lucene data types (such as Pivotal GemFire's `LuceneResultStruct`). Therefore, SDG gives you the `ProjectingLuceneOperations` interface to remedy these important application concerns. +The following listing shows the `ProjectingLuceneOperations` interface definition: [source,java] ---- @@ -198,15 +199,15 @@ public interface ProjectingLuceneOperations { } ---- -The `ProjectingLuceneOperations` interface primarily uses application domain object types allowing you to work with -your application data. The `query` method variants accept a projection type and the template applies the query results -to instances of the given projection type using the _Spring Data Commons_ Projection infrastructure. +The `ProjectingLuceneOperations` interface primarily uses application domain object types that let you work with +your application data. The `query` method variants accept a projection type, and the template applies the query results +to instances of the given projection type by using the Spring Data Commons Projection infrastructure. -Additionally, the template wraps the paged Lucene query results in an instance of the _Spring Data Commons_ -`Page` abstraction. The same projection logic can still be applied to the results in the page and are lazily projected +Additionally, the template wraps the paged Lucene query results in an instance of the Spring Data Commons +`Page` abstraction. The same projection logic can still be applied to the results in the page and are lazily projected as each page in the collection is accessed. -By way of example, suppose I have a class representing a `Person` like so... +By way of example, suppose you have a class representing a `Person`, as follows: [source,java] ---- @@ -227,7 +228,7 @@ class Person { } ---- -Additionally, I might have a single interface to represent people as `Customers` depending on my application view... +Additionally, you might have a single interface to represent people as `Customers`, depending on your application view, as follows: [source,java] ---- @@ -256,48 +257,48 @@ LuceneIndexFactoryBean personLastNameIndex(Pivotal GemFireCache gemfireCache) { } ---- -Then it is a simple matter to query for people as either `Person` objects... +Then you could query for people as `Person` objects, as follows: [source,java] ---- List people = luceneTemplate.query("lastName: D*", "lastName", Person.class); ---- -Or as a `Page` of type `Customer`... +Alternatively, you could query for a `Page` of type `Customer`, as follows: [source,java] ---- Page customers = luceneTemplate.query("lastName: D*", "lastName", 100, 20, Customer.class); ---- -The `Page` can then be used to fetch individual pages of the results... +The `Page` can then be used to fetch individual pages of the results, as follows: [source,java] ---- List firstPage = customers.getContent(); ---- -Conveniently, the _Spring Data Commons_ `Page` interface implements `java.lang.Iterable` too making it very easy +Conveniently, the Spring Data Commons `Page` interface also implements `java.lang.Iterable`, 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, out-of-the-box (OOTB) +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] +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. -A custom `ProjectionFactory` can be set on a Lucene template using `setProjectionFactory(:ProjectionFactory)`. +You can use `setProjectionFactory(:ProjectionFactory)` to set a custom `ProjectionFactory` on a Lucene template. -== Annotation configuration support +== Annotation Configuration Support -Finally, _Spring Data for Pivotal GemFire_ provides Annotation configuration support for `LuceneIndexes`. -Eventually, the SDG Lucene support will find its way into the _Repository_ infrastructure extension for Pivotal GemFire -so that Lucene queries can be expressed as methods on an application `Repository` interface, much like the +Finally, Spring Data for Pivotal GemFire provides annotation configuration support for `LuceneIndexes`. +Eventually, the SDG Lucene support finds its way into the repository infrastructure extension for Pivotal GemFire +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] -today. +works today. However, in the meantime, if you want to conveniently express `LuceneIndexes`, you can do so directly on -your application domain objects like so... +your application domain objects, as the following example shows: [source,java] ---- @@ -318,8 +319,8 @@ class Person { } ---- -You must use SDG's Annotation configuration support along with the `@EnableEntityDefineRegions` and `@EnableIndexing` -Annotations to enable this feature... +To enable this feature, you must use SDG's Annotation configuration support and the `@EnableEntityDefineRegions` and `@EnableIndexing` +Annotations, as follows: [source,java] ---- @@ -332,12 +333,10 @@ class ApplicationConfiguration { } ---- -NOTE: Keep in mind that `LuceneIndexes` can only be created on Apache Geode Servers since `LuceneIndexes` only apply -to `PARTTION` Regions. +NOTE: `LuceneIndexes` can be created only on Apache Geode Servers since `LuceneIndexes` only apply +to `PARTITION` Regions. -Given our definition of the `Person` class above, the SDG Annotation configuration support -will find the `Person` entity class definition, determine that people will be stored in -a `PARTITION` Region called "People" and that the `Person` will have an OQL `Index` on `birthDate` +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`. - -More will be described with this feature in subsequent releases. diff --git a/src/main/asciidoc/reference/mapping.adoc b/src/main/asciidoc/reference/mapping.adoc index 38f67899..07cadaf2 100644 --- a/src/main/asciidoc/reference/mapping.adoc +++ b/src/main/asciidoc/reference/mapping.adoc @@ -1,13 +1,17 @@ [[mapping]] -= POJO mapping += POJO Mapping + +This section covers: + +* <> +* <> +* The <> [[mapping.entities]] == Entity Mapping -_Spring Data for Pivotal GemFire_ provides support to map entities that will be stored in a Region -in the Geode In-Memory Data Grid. - -The mapping metadata is defined using annotations on application domain classes just like this: +Spring Data for Pivotal GemFire 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: .Mapping a domain class to a Pivotal GemFire Region ==== @@ -31,16 +35,14 @@ public class Person { ---- ==== -The first thing you notice here is the `@Region` annotation that 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 shall 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 `@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. +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. - -For instance: +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] ---- @@ -55,39 +57,37 @@ public class Guest extends User { } ---- -Be sure to use the full-path of the Pivotal GemFire Region, as defined with the _Spring Data for Pivotal GemFire_ XML namespace +Be sure to use the full path of the Pivotal GemFire region, as defined with the Spring Data for Pivotal GemFire 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 Pivotal GemFire_ also recognizes the Region type-specific -mapping annotations: `@ClientRegion`, `@LocalRegion`, `@PartitionRegion` and `@ReplicateRegion`. +In addition to the `@Region` annotation, Spring Data for Pivotal GemFire also recognizes the region type-specific +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 Pivotal GemFire's` -Annotation configuration model. When combined with the `@EnableEntityDefinedRegions` configuration annotation -on _Spring_ `@Configuration` annotated class, it is possible to generate Regions in the local cache, whether +mapping infrastructure. However, these additional mapping annotations are useful in Spring Data for Pivotal GemFire'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 the application is a client or peer. -These annotations allow you, the developer, to be more specific about what type of Region that your application -entity class should be mapped to, and also has an impact on the data management policies of the Region -(e.g. partition (a.k.a. sharding) vs. just replicating data). +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). -Using these Region type-specific mapping annotations with the SDG Annotation config model saves you from having to -explicitly define these Regions in config. - -The details of the new Annotation configuration model will be discussed in more detail in a subsequent releaase. +Using these region type-specific mapping annotations with the SDG Annotation config model saves you from having to +explicitly define these regions in configuration. [[mapping.repositories]] -=== Repository Mapping +== Repository Mapping -As an alternative to specifying the Region in which the entity will be stored using the `@Region` annotation +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`. See <> for more details. -However, let's say you want to store a `Person` in multiple Pivotal GemFire Regions (e.g. `People` and `Customers`), -then you can define your corresponding `Repository` interface extensions like so: +However, suppose you want to store a `Person` record in multiple Pivotal GemFire Regions (for example, `People` and `Customers`). +Then you can define your corresponding `Repository` interface extensions as follows: [source,java] ---- @@ -102,7 +102,7 @@ public interface CustomerRepository extends GemfireRepository { } ---- -Then, using each Repository individually, you can store the entity in multiple Pivotal GemFire Regions. +Then, using each Repository individually, you can store the entity in multiple Pivotal GemFire Regions, as the following example shows: [source,java] ---- @@ -120,24 +120,24 @@ class CustomerService { } ---- -It is not difficult to imagine wrapping the `update` service method in a _Spring_ managed transaction, +You can 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 Pivotal GemFire_ provides a custom -http://gemfire-95-javadocs.docs.pivotal.io/org/apache/geode/pdx/PdxSerializer.html[PdxSerializer] implementation +Spring Data for Pivotal GemFire provides a custom +http://gemfire-95-javadocs.docs.pivotal.io/org/apache/geode/pdx/PdxSerializer.html[`PdxSerializer`] implementation that uses the mapping information to customize entity serialization. -Beyond that, it also allows customizing entity instantiation by using the Spring Data `EntityInstantiator` abstraction. -By default, the serializer uses a `ReflectionEntityInstantiator` that will use the persistence constructor of -the mapped entity (either the default constructor, a singly declared constructor or an explicitly annotated constructor -annotated with the `@PersistenceConstructor` annotation). +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`). -To provide arguments for constructor parameters, the serializer will read fields with the named constructor parameter, +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 -http://gemfire-95-javadocs.docs.pivotal.io/org/apache/geode/pdx/PdxReader.html[PdxReader]. +http://gemfire-95-javadocs.docs.pivotal.io/org/apache/geode/pdx/PdxReader.html[`PdxReader`], as shown in the following example: .Using `@Value` on entity constructor parameters ==== @@ -145,29 +145,29 @@ http://gemfire-95-javadocs.docs.pivotal.io/org/apache/geode/pdx/PdxReader.html[P ---- public class Person { - public Person(@Value("#root.foo") String firstName, @Value("bean") String lastName) { + public Person(@Value("#root.thing") String firstName, @Value("bean") String lastName) { // … } } ---- ==== -An entity class annotated in this way will have the field `foo` read from the `PdxReader` and passed as the value -for the constructor parameter, `firstname`. The value for `lastName` will be a _Spring_ bean with the name `bean`. +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`. -In addition to the custom instantiation logic and strategy provided by `EntityInstantiators` -the `MappingPdxSerializer` also provides capabilities above and beyond even Pivotal GemFire's own +In addition to the custom instantiation logic and strategy provided by `EntityInstantiators`, +the `MappingPdxSerializer` also provides capabilities beyond Pivotal GemFire's own http://gemfire-95-javadocs.docs.pivotal.io/org/apache/geode/pdx/ReflectionBasedAutoSerializer.html[`ReflectionBasedAutoSerializer`]. -While Pivotal GemFire's `ReflectionBasedAutoSerializer` conveniently uses Java Reflection to populate entities as well as -use _Regular Expressions_ to identify types that should be handled (de/serialized) by the `ReflectionBasedAutoSerializer`, +While Pivotal GemFire'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: -1. Register custom `PdxSerializer` objects per entity field/property names and/or types. -2. Conveniently identifies ID properties. -3. Automatically handles *read-only* properties. -4. Automatically handles *transient* properties. -5. Allows more robust *type filtering* in a `null`-safe manner (e.g. not limited to only expressing types via Regex). +* 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). We now explore each feature of the `MappingPdxSerializer` in a bit more detail. @@ -175,9 +175,9 @@ We now explore each feature of the `MappingPdxSerializer` in a bit more detail. === Custom PdxSerializer Registration The `MappingPdxSerializer` gives you the ability to register custom `PdxSerializers` based on an entity's -field/property names and/or types. +field and property names and types. -For instance, suppose you have defined an entity type modeling a `User` as... +For instance, suppose you have defined an entity type modeling a `User` as follows: [source,java] ---- @@ -193,12 +193,12 @@ public class User { } ---- -While the `User's` "name" probably does not require any special logic to serialize the value for name, serializing -the `Password` might require additional logic in order 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 -a custom `PdxSerializer` to handle the `User's` `Password`, like so... +and you only want to store the salted hash. When using the `MappingPdxSerializer`, you can register +a custom `PdxSerializer` to handle the user's password, as follows: .Registering custom `PdxSerializers` by POJO field/property type ==== @@ -212,12 +212,12 @@ mappingPdxSerializer.setCustomPdxSerializers(customPdxSerializers); ---- After registering the application-defined `SaltedHashPasswordPdxSerializer` instance with the `Password` -application domain model type, the `MappingPdxSerializer` will consult the custom `PdxSerializer` to -de/serialize *all* `Password` objects regardless of the containing object (e.g. `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 only want to customize the serialization of `Passwords` on `User` objects, specifically. -Then, you can register the custom `PdxSerializer` for the `User` type only by specifying the fully-qualified -name of the `Class's` field/property. For example: +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: .Registering custom `PdxSerializers` by POJO field/property name ==== @@ -230,20 +230,20 @@ customPdxSerializers.put("example.app.auth.model.User.password", new SaltedHashP mappingPdxSerializer.setCustomPdxSerializers(customPdxSerializers); ---- -Notice the use of the fully-qualified field/propety name (i.e. "example.app.auth.model.User.password") +Notice the use of the fully-qualified field or propety name (that is `example.app.auth.model.User.password`) as the custom `PdxSerializer` registration key. -NOTE: You could construct the registration key using a more logical code snippet, such as: -`User.class.getName().concat(".password");` This is recommended over the example shown above. The example was simply -trying to be very explicit in the semantics of registration. +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. [[mapping.pdx-serializer.id-properties]] === Mapping ID Properties Like Pivotal GemFire'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 meta-data, -specifically by finding the entity property designated as the identifier using the -https://docs.spring.io/spring-data/commons/docs/current/api/org/springframework/data/annotation/Id.html[`@Id`] Spring Data annotation. +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 +https://docs.spring.io/spring-data/commons/docs/current/api/org/springframework/data/annotation/Id.html[`@Id`] annotation. For example: @@ -258,7 +258,7 @@ class Customer { } ---- -In this case, the `Customer's` `id` field will be marked as the identifier field in the PDX type meta-data using +In this case, the `Customer` `id` field is marked as the identifier field in the PDX type metadata by using http://gemfire-95-javadocs.docs.pivotal.io/org/apache/geode/pdx/PdxWriter.html#markIdentityField-java.lang.String-[`PdxWriter.markIdentifierField(:String)`] when the `PdxSerializer.toData(..)` method is called during serialization. @@ -267,8 +267,8 @@ 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 following the http://www.oracle.com/technetwork/java/javase/documentation/spec-136004.html[JavaBeans] -specification (as Spring does), and you have defined a POJO with some 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 a POJO with a read-only property, as follows: [source,java] ---- @@ -286,33 +286,33 @@ class ApplicationDomainType { } ---- -Then the `readOnly` property is "read-only" because it does not provide a setter method; it only has a getter method. +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". +is considered "`read-only`". -As such, the `MappingPdxSerializer` will not try to write this value back when populating the instance of `DomainType` +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. 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, you can leverage this feature as is appropriate for your application use cases and requirements. -If you want the field/property to always be written then simply define a setter. +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. [[mapping.pdx-serializer.transient-properties]] === Mapping Transient Properties Likewise, what happens when your entity defines `transient` properties? -You would expect the `transient` fields/properties of your entity not to be serialized to the stream of PDX bytes -when serializing entity. And, that is exactly what happens, unlike Pivotal GemFire's own -`ReflectionBasedAutoSerializer`, which serializes everything accessible from the object via _Java Reflection_. +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 Pivotal GemFire's own +`ReflectionBasedAutoSerializer`, which serializes everything accessible from the object through Java reflection. -The `MappingPdxSerializer` will not serialize any fields or properties which are qualified as transient either using -Java's `transient` keyword (in the case of fields) or when 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 https://docs.spring.io/spring-data/commons/docs/current/api/org/springframework/data/annotation/Transient.html[`@Transient`] Spring Data annotation on either fields or properties. -For example, if you defined an enity with transient fields and properties, like so... +For example, you might define an entity with transient fields and properties as follows: [source,java] ---- @@ -337,29 +337,29 @@ class Process { } ---- -Neither the `Process` `id` field nor the readable `hostname` property will be written to the PDX serialized bytes. +Neither the `Process` `id` field nor the readable `hostname` property are written to the PDX serialized bytes. [[mapping.pdx-serializer.type-filtering]] === Filtering by Class types -Similar to Pivotal GemFire's `ReflectionBasedAutoSerializer`, SDG's `MappingPdxSerializer` allows a user to filter -the types of objects that the `MappingPdxSerializer` will handle, i.e. de/serialize. +Similar to Pivotal GemFire's `ReflectionBasedAutoSerializer`, SDG's `MappingPdxSerializer` lets you filter +the types of objects that the `MappingPdxSerializer` serializes and deserializes. -However, unlike Pivotal GemFire's `ReflectionBasedAutoSerializer`, which uses complex _Regular Expressions_ to express -which types the serializer will handle, SDG's `MappingPdxSerializer` uses the much more robust +However, unlike Pivotal GemFire's `ReflectionBasedAutoSerializer`, which uses complex regular expressions to express +which types the serializer handles, SDG'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. +and API to express type-matching criteria. -Plus, if you feel strongly about using _Regular Expressions_, then you can always implement a `Predicate` using -_Java's_ https://docs.oracle.com/javase/8/docs/api/java/util/regex/package-summary.html[_Regular Expression_ support]. +If you like to use regular expressions, you can implement a `Predicate` by using +Java's https://docs.oracle.com/javase/8/docs/api/java/util/regex/package-summary.html[regular expression support]. -The nice part about Java's `Predicate` interface is that you can compose `Predicates` using the convenient -and appropriate API: +The nice part about Java's `Predicate` interface is that you can compose `Predicates` by using convenient +and appropriate API methods, including: https://docs.oracle.com/javase/8/docs/api/java/util/function/Predicate.html#and-java.util.function.Predicate-[`and(:Predicate)`], -https://docs.oracle.com/javase/8/docs/api/java/util/function/Predicate.html#or-java.util.function.Predicate-[`or(:Predicate)`] +https://docs.oracle.com/javase/8/docs/api/java/util/function/Predicate.html#or-java.util.function.Predicate-[`or(:Predicate)`], and https://docs.oracle.com/javase/8/docs/api/java/util/function/Predicate.html#negate--[`negate()`]. -For example: +The following example shows the `Predicate` API in use: [source,java] ---- @@ -376,6 +376,6 @@ For example: ---- NOTE: In addition to setting your own type filtering `Predicates`, SDG's `MappingPdxSerializer` now automatically -registers pre-canned `Predicates` that filters types from the `org.apache.geode` package along with `null` objects +registers pre-defined `Predicates` that filter types from the `org.apache.geode` package along with `null` objects when calling `PdxSerializer.toData(:Object, :PdxWriter)` or `null` `Class` types when calling `PdxSerializer.fromData(:Class, :PdxReader)` methods. diff --git a/src/main/asciidoc/reference/region.adoc b/src/main/asciidoc/reference/region.adoc index 69ef213f..c9b73426 100644 --- a/src/main/asciidoc/reference/region.adoc +++ b/src/main/asciidoc/reference/region.adoc @@ -55,16 +55,16 @@ was used. Alternately, one can reference the cache bean with the `cache-ref` att ---- -`lookup-region` provides a simple way of retrieving 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" allows all Regions defined in a Pivotal GemFire native `cache.xml` file to be imported into a _Spring_ -application context when using the`cache-xml-location` attribute on the `` element. +"`auto-lookup`" lets you import all regions defined in a Pivotal GemFire native `cache.xml` file into a Spring +application context when you use the `cache-xml-location` attribute on the `` element. -For instance, given a `cache.xml` file of... +For instance, consider the following `cache.xml` file: [source,xml] ---- @@ -81,32 +81,32 @@ For instance, given a `cache.xml` file of... ---- -A developer may import the `cache.xml` file as follows... +You can import the preceding `cache.xml` file as follows: [source,xml] ---- ---- -The developer may then use the `` element (e.g. ``) to reference -specific Regions as beans in the _Spring_ context, or the user may choose to import all Regions defined in `cache.xml` -with: +You can then use the `` element (for example, ``) to reference +specific Regions as beans in the Spring context, or you can choose to import all regions defined in `cache.xml` +by using the following: [source,xml] ---- ---- -_Spring Data for Pivotal GemFire_ will automatically create beans for all Pivotal GemFire Regions defined in `cache.xml` that have not been -explicitly added to the _Spring_ context with explicit `` bean declarations. +Spring Data for Pivotal GemFire automatically creates beans for all Pivotal GemFire regions defined in `cache.xml` that have not been +explicitly added to the Spring context with explicit `` bean declarations. -It is important to realize that _Spring Data for Pivotal GemFire_ uses a _Spring_ +It is important to realize that Spring Data for Pivotal GemFire 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 Pivotal GemFire to add -as beans in the _Spring_ application context. +to post-process the cache after it is both created and initialized to determine the regions defined in Pivotal GemFire to add +as beans in the Spring application context. -You may inject these "auto-looked-up" Regions like any other bean defined in the _Spring_ application context with -1 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 application context, with +one exception: You may need to define a `depends-on` association with the '`gemfireCache`' bean, as follows: [source,java] ---- @@ -128,35 +128,35 @@ public class ApplicationDao extends DaoSupport { } ---- -The example above is applicable when using _Spring's_ `component-scan` functionality. +The preceding example applies when you use Spring's `component-scan` functionality. -If you are declaring your components using _Spring_ XML config, then you would do... +If you declarE your components by using Spring XML config, then you would do the following: [source,xml] ---- ---- -This ensures the Pivotal GemFire cache and all the Regions defined in `cache.xml` get created before any components +Doing so ensures that the Pivotal GemFire cache and all the regions defined in `cache.xml` get created before any components with auto-wire references when using the new `` element. [[bootstrap:region:overview]] == Configuring Regions -_Spring Data for Pivotal GemFire_ provides comprehensive support for configuring any type of Region via the following elements: +Spring Data for Pivotal GemFire provides comprehensive support for configuring any type of Region through the following elements: * LOCAL Region: `` * PARTITION Region: `` * REPLICATE Region: `` * Client Region: `` -Please see the Pivotal GemFire documentation for a comprehensive description of -http://geode.apache.org/docs/guide/11/developing/region_options/region_types.html[Region Types]. +See the Pivotal GemFire documentation for a comprehensive description of +http://geode.apache.org/docs/guide/11/developing/region_options/region_types.html[region types]. [[bootstrap:region:attributes]] === Common Region Attributes -The following table lists 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 @@ -167,54 +167,54 @@ The following table lists attributes available for all Region types: | cache-ref | Pivotal GemFire Cache bean reference -| The name of the bean defining the Pivotal GemFire Cache (by default 'gemfireCache'). +| The name of the bean defining the Pivotal GemFire Cache (by default, 'gemfireCache'). | cloning-enabled -| boolean, default:false -| When true, the updates are applied to a clone of the value and then the clone is saved to the cache. When false, the value is modified in place in the cache. +| boolean (default: `false`) +| When `true`, the updates are applied to a clone of the value and then the clone is saved to the cache. When `false`, the value is modified in place in the cache. | close -| boolean, default:false -| Determines whether the Region should be closed at shutdown. +| boolean (default: `false`) +| Determines whether the region should be closed at shutdown. | concurrency-checks-enabled -| boolean, default:true -| Determines whether members perform checks to provide consistent handling for concurrent or out-of-order updates to distributed Regions. +| boolean (default: `true`) +| Determines whether members perform checks to provide consistent handling for concurrent or out-of-order updates to distributed regions. | data-policy -| See Pivotal GemFire's http://geode.apache.org/releases/latest/javadoc/org/apache/geode/cache/DataPolicy.html[Data Policy] -| The Region's Data Policy. Note, not all Data Policies are supported for every Region type. +| See Pivotal GemFire's http://geode.apache.org/releases/latest/javadoc/org/apache/geode/cache/DataPolicy.html[data policy]. +| The region's data policy. Note that not all data policies are supported for every Region type. | destroy -| boolean, default:false -| Determines whether the Region should be destroyed at shutdown. +| boolean (default: `false`) +| Determines whether the region should be destroyed at shutdown. | disk-store-ref -| The name of a configured Disk Store. -| A reference to a bean created via the `disk-store` element. +| The name of a configured disk store. +| A reference to a bean created through the `disk-store` element. | disk-synchronous -| boolean, default:true -| Determines whether Disk Store writes are synchronous. +| boolean (default: `true`) +| Determines whether disk store writes are synchronous. | id | Any valid bean name. -| Will be the Region name by default if no `name` attribute is specified. +| The default region name if no `name` attribute is specified. | ignore-if-exists -| boolean, default:false -| Ignores this bean definition if the Region already exists in the cache, resulting in a lookup instead. +| boolean (default: `false`) +| Ignores this bean definition if the region already exists in the cache, resulting in a lookup instead. | ignore-jta -| boolean, default:false -| Determines whether this Region will participate in JTA transactions. +| boolean (default: `false`) +| Determines whether this Region participates in JTA (Java Transaction API) transactions. | index-update-type -| synchronous or asynchronous, default:synchronous -| Determines whether Indices will be updated synchronously or asynchronously on entry creation. +| `synchronous` or `asynchronous` (default: `synchronous`) +| Determines whether Indices are updated synchronously or asynchronously on entry creation. | initial-capacity -| integer, default:16 +| integer (default: 16) | The initial memory allocation for the number of Region entries. | key-constraint @@ -222,28 +222,28 @@ The following table lists attributes available for all Region types: | Expected key type. | load-factor -| float, default:.75 -| Sets the initial parameters on the underlying java.util.ConcurrentHashMap used for storing Region entries. +| float (default: .75) +| Sets the initial parameters on the underlying `java.util.ConcurrentHashMap` used for storing region entries. | name -| Any valid Region name. -| The name of the Region. If not specified, it will assume the value of the `id` attribute (a.k.a. bean name). +| Any valid region name. +| The name of the region. If not specified, it assumes the value of the `id` attribute (that is, the bean name). | persistent -| *boolean, default:false -| Determines whether the Region will persist entries to local disk (Disk Store). +| *boolean (default: `false`) +| Determines whether the region persists entries to local disk (disk store). | shortcut | See http://geode.apache.org/releases/latest/javadoc/org/apache/geode/cache/RegionShortcut.html -| The `RegionShortcut` for this Region. Allows easy initialization of the Region based on pre-defined defaults. +| The `RegionShortcut` for this region. Allows easy initialization of the region based on pre-defined defaults. | statistics -| boolean, default:false -| Determines whether the Region reports statistics. +| boolean (default: `false`) +| Determines whether the region reports statistics. | template -| The name of a Region Template. -| A reference to a bean created via one of the `*region-template` elements. +| The name of a region template. +| A reference to a bean created through one of the `*region-template` elements. | value-constraint | Any valid, fully-qualified Java class name. @@ -251,16 +251,16 @@ The following table lists attributes available for all Region types: |=== [[bootstrap:region:cache-listener]] -=== CacheListeners +=== `CacheListener` instances -`CacheListeners` 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 http://geode.apache.org/releases/latest/javadoc/org/apache/geode/cache/CacheListener.html[`CacheListener`] interface. -A Region may have multiple listeners, declared using 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. -In the example below, there are two `CacheListener's` declared. The first references a named, top-level _Spring_ bean; -the second is an anonymous inner bean definition. +The following example has two declared `CacheListener's`. The first references a named, top-level Spring bean. +The second is an anonymous inner bean definition. [source,xml] ---- @@ -277,11 +277,9 @@ the second is an anonymous inner bean definition. ---- The following example uses an alternate form of the `cache-listener` element with the `ref` attribute. -This allows for more concise configuration when defining a single `CacheListener`. Note, the namespace only allows -a single `cache-listener` element so either the style above or below must be used. +Doing so allows for more concise configuration when defining a single `CacheListener`. -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 will result in an exception. +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. [source,xml] ---- @@ -293,17 +291,20 @@ mutually exclusive and using both in the same element will result in an exceptio ---- +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 Pivotal GemFire provides a callback interface to be implemented in order to invoke custom code in response to Cache or Region events. -Using _Spring's_ IoC container, the implementation is a standard _Spring_ bean. In order to simplify the configuration, -the schema allows a single occurrence of the `cache-listener` element, but it may contain nested bean references -and inner bean definitions in any combination if multiple instances are permitted. The convention is to use -the singular form (i.e., `cache-listener` vs `cache-listeners`) reflecting that the most common scenario will in fact -be a single instance. We have already seen examples of this pattern in the <> +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 <> configuration example. ==== @@ -311,14 +312,14 @@ configuration example. === CacheLoaders and CacheWriters Similar to `cache-listener`, the namespace provides `cache-loader` and `cache-writer` elements to register -these Pivotal GemFire components respectively for a Region. +these Pivotal GemFire components for a region. -A `CacheLoader` is invoked on a cache miss to allow an entry to be loaded from an external data source, such as a -database. A `CacheWriter` is invoked before an entry is created or updated, intended for synchronizing to -an external data source. The difference is Pivotal GemFire only 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 difference is that Pivotal GemFire supports, at most, a single instance `CacheLoader` and `CacheWriter` +per region. However, either declaration style may be used. -Example: +The following example declares a region with both a `CacheLoader` and a `CacheWriter`: [source,xml] ---- @@ -346,12 +347,12 @@ in the Pivotal GemFire documentation for more details. == Compression Pivotal GemFire Regions may also be compressed in order to reduce JVM memory consumption and pressure to possibly avoid -stop the world GCs. When you enable compression for a Region, all values stored in the Region, in-memory -are compressed while keys and indexes remain uncompressed. New values are compressed when put into Region -and all values are decompressed automatically when read back from the Region. Values are not compressed when +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 persisted to disk or when sent over the wire to other peer members or clients. -Example: +The following example shows a region with compression enabled: [source,xml] ---- @@ -364,19 +365,19 @@ Example: ---- -Please refer to Pivotal GemFire's documentation for more information on -http://gemfire.docs.pivotal.io/geode/managing/region_compression/region_compression.html[Region Compression]. +See Pivotal GemFire's documentation for more information on +http://gemfire.docs.pivotal.io/geode/managing/region_compression/region_compression.html[region compression]. [[bootstrap:region:subregions]] == Subregions -_Spring Data for Pivotal GemFire_ also supports Subregions, allowing Regions to be arranged in a hierarchical relationship. +Spring Data for Pivotal GemFire also supports subregions, allowing regions to be arranged in a hierarchical relationship. -For example, Pivotal GemFire allows for a */Customer/Address* Region and a different */Employee/Address* Region. Additionally, -a Subregion may have it's own Subregions and its own configuration. A Subregion does not inherit attributes from -the parent Region. Regions types may be mixed and matched subject to Pivotal GemFire constraints. A Subregion is naturally -declared as a child element of a Region. The Subregion's name attribute is the simple name. The above example -might be configured as: +For example, Pivotal GemFire 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 Pivotal GemFire 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: [source,xml] ---- @@ -391,19 +392,19 @@ might be configured as: ---- -Note that the `Monospaced ([id])` attribute is not permitted for a Subregion. The Subregions will be created with -bean names */Customer/Address* and */Employee/Address*, respectively. So they may be injected using the full path name -into other application beans that need them, such as `GemfireTemplate`. The full path should also be used in +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. [[bootstrap:region:templates]] == Region Templates -_Spring Data for Pivotal GemFire_ 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. +Spring Data for Pivotal GemFire 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. -_Spring Data for Pivotal GemFire_ includes 5 Region template tags in namespace: +Spring Data for Pivotal GemFire includes five Region template tags in its namespace: [cols="1,2", options="header"] .Region Template Tags @@ -412,26 +413,26 @@ _Spring Data for Pivotal GemFire_ includes 5 Region template tags in namespace: | Description | `` -| Defines common, generic Region attributes; extends `regionType` in the namespace. +| Defines common generic region attributes. Extends `regionType` in the namespace. | `` -| Defines common, 'Local' Region attributes; extends `localRegionType` in the namespace. +| Defines common 'Local' region attributes. Extends `localRegionType` in the namespace. | `` -| Defines common, 'PARTITION' Region attributes; extends `partitionedRegionType` in the namespace. +| Defines common 'PARTITION' region attributes. Extends `partitionedRegionType` in the namespace. | `` -| Defines common, 'REPLICATE' Region attributes; extends `replicatedRegionType` in the namespace. +| Defines common 'REPLICATE' region attributes. Extends `replicatedRegionType` in the namespace. | `` -| Defines common, 'Client' Region attributes; extends `clientRegionType` in the namespace. +| Defines common 'Client' region attributes. Extends `clientRegionType` in the namespace. |=== -In addition to the tags, concrete `` elements along with the abstract `` elements -have a `template` attribute used to define the Region Template from which the Region will inherit its configuration. -Region Templates may even inherit from other Region Templates. +In addition to the tags, concrete `` elements (along with the abstract `` 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. -Here is an example of 1 possible configuration... +The following example shows one possible configuration: [source,xml] ---- @@ -475,18 +476,18 @@ Here is an example of 1 possible configuration... ---- -Region Templates work for Subregions as well. Notice that 'TemplateBasedPartitionRegion' -extends 'PartitionRegionTemplate', which extends 'ExtendedRegionTemplate' that extends 'BaseRegionTemplate'. -Attributes and sub-elements defined in subsequent, inherited Region bean definitions override what is in the parent. +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. === How Templating Works -_Spring Data for Pivotal GemFire_ applies Region Templates when the _Spring_ application context configuration meta-data is *parsed*, -and therefore, *must be declared in the order of inheritance*. In other words, parent templates must be defined -before children. This ensures the proper configuration is applied, especially when element attributes or sub-elements -are "overridden". +Spring Data for Pivotal GemFire 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. -IMPORTANT: It is equally important to remember the Region types must only inherit from other similar 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 `` to inherit from a ``. NOTE: Region Templates are single-inheritance. @@ -494,31 +495,31 @@ NOTE: Region Templates are single-inheritance. [[bootstrap:region:regions-subregions-lookups-caution]] === Caution concerning Regions, Subregions 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 Pivotal GemFire_ 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 Pivotal GemFire native `cache.xml` configuration file. Therefore, the lookup -was performed first to avoid any errors. This was by design and subject to change. +Previously, one of the underlying properties of the `replicated-region`, `partitioned-region`, `local-region`, +and `client-region` elements in the Spring Data for Pivotal GemFire 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 Pivotal GemFire 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 -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 Pivotal GemFire_ `<*-region>` namespace elements now includes -a `ignore-if-exists` attribute, which re-instates the old behavior by performing a lookup of an existing Region -identified by name, first. If an existing Region by name is found and `ignore-if-exists` is set to `true`, then -the Region bean definition defined in _Spring_ config is ignored. +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 Pivotal GemFire `<*-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. -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 existed and the Region elements performed a lookup first is if -the developer defined different Region semantics and behaviors for eviction, expiration, subscription, etc in his/her -application config, then the Region definition may not match and could exhibit contrary behaviors to those required -by the application. Even worse, the application developer may want to define the Region as a distributed Region -(e.g. PARTITION) but in fact the existing Region definition is LOCAL. +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 +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`. -IMPORTANT: Recommended Practice - Only use `replicated-region`, `partitioned-region`, `local-region` and `client-region` +IMPORTANT: Recommended Practice - Use only `replicated-region`, `partitioned-region`, `local-region`, and `client-region` namespace elements to define new Regions. -Consider the following native Pivotal GemFire `cache.xml` configuration file... +Consider the following native Pivotal GemFire `cache.xml` configuration file: [source,xml] ---- @@ -539,7 +540,7 @@ Consider the following native Pivotal GemFire `cache.xml` configuration file... ---- -Also consider that you may have defined an application DAO as follows... +Further, consider that you may have defined an application DAO as follows: [source,java] ---- @@ -552,9 +553,9 @@ public class CustomerAccountDao extends GemDaoSupport { } ---- -Here, we are injecting a reference to the `Customers/Accounts` Region in our application DAO. As such, it is -not uncommon for a developer to define beans for all or even some of these Regions in _Spring_ XML configuration -meta-data as follows... +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: [source,xml] ---- @@ -575,12 +576,12 @@ meta-data as follows... ---- -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 above is that it allows a developer -to reference a Subregion directly without unnecessarily defining a bean for the parent Region (i.e. `Customers`). +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). -However, if now the developer changes his/her configuration meta-data syntax to using the nested format, like so... +Consider the following bad example, which changes the configuration metadata syntax to use the nested format: [source,xml] ---- @@ -591,8 +592,8 @@ However, if now the developer changes his/her configuration meta-data syntax to ---- -Or, perhaps the developer erroneously chooses to use the top-level `replicated-region` element along with -the `ignore-if-exists` attribute set to perform a lookup first, as in... +Now consider another bad example, in which uses the top-level `replicated-region` element along with +the `ignore-if-exists` attribute set to perform a lookup first: [source,xml] ---- @@ -603,18 +604,18 @@ the `ignore-if-exists` attribute set to perform a lookup first, as in... ---- -Then the Region beans defined in the _Spring_ application context will consist of the following: +The Region beans defined in the Spring application context consist of the following: `{ "Customers", "/Customers/Accounts", "/Customers/Accounts/Orders" }.` This means the dependency injected reference -above (i.e. `@Resource(name = "Customers/Accounts"))` is now broken since no bean with name "Customers/Accounts" -is actually defined. +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. -Pivotal GemFire 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 just "Customers/Accounts". However, _Spring Data _Pivotal GemFire is very specific when it comes to naming beans after Regions, -typically always using the forward slash (/) to represent Subregions (e.g. "/Customers/Accounts"). +Pivotal GemFire 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 Pivotal GemFire is very specific when it comes to naming beans after regions. It +always uses the forward slash (/) to represent subregions (for example, `/Customers/Accounts`). -Therefore, it is recommended that users either use the nested `lookup-region` syntax as shown above, -or define direct references with a leading forward slash (/) like so... +Therefore, you should use the nested `lookup-region` syntax shown earlier +or define direct references with a leading forward slash (/), as follows: [source,xml] ---- @@ -622,24 +623,24 @@ or define direct references with a leading forward slash (/) like so... ---- -The example above where the nested `replicated-region` elements were used to reference the Subregions serves to -illustrate the problem stated earlier. Are the Customers, Accounts and Orders Regions/Subregions persistent or not? -Not, since the Regions were defined in the native Pivotal GemFire `cache.xml` configuration file as `REPLICATES` and will exist -by the time the cache is initialized, or once the `` bean is processed. +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 Pivotal GemFire `cache.xml` configuration file as `REPLICATES` and exist +before the cache is initialized (once the `` bean is processed). [[bootstrap:region:eviction]] == Data Eviction (with Overflow) Based on various constraints, each Region can have an eviction policy in place for evicting data from memory. -Currently, in Pivotal GemFire, eviction applies to the _Least Recently Used_ entry (also known as +Currently, in Pivotal GemFire, eviction applies to the Least Recently Used entry (also known as 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). +or paged to disk (referred to as "`overflow to disk`"). -_Spring Data for Pivotal GemFire_ supports all eviction policies (entry count, memory and heap usage) for PARTITION Regions, -REPLICATE Regions and client, local Regions using the nested `eviction` element. +Spring Data for Pivotal GemFire 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, -a developer would specify the following configuration: +you can specify the following configuration: [source,xml] ---- @@ -651,33 +652,33 @@ a developer would specify the following configuration: IMPORTANT: Replicas cannot use `local destroy` eviction since that would invalidate them. See the Pivotal GemFire docs for more information. -When configuring Regions for overflow, it is recommended to 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, please refer to the Pivotal GemFire documentation on +For a detailed description of eviction policies, see the Pivotal GemFire documentation on http://geode.apache.org/docs/guide/11/developing/eviction/chapter_overview.html[Eviction]. [[bootstrap:region:expiration]] == Data Expiration -Pivotal GemFire allows you to control how long entries exist in the cache. Expiration is driven by elapsed time, -as opposed to Eviction, which is driven by the entry count or heap/memory usage. Once an entry expires +Pivotal GemFire lets you control how long entries exist in the cache. Expiration is driven by elapsed time, +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. Pivotal GemFire 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 +* *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. -* *Idle Timeout (TTI)* - The amount of time in seconds that an object may remain in the cache after the last access. +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. +Idle Timeout counter is reset any time the entry is accessed through a get operation or a `netSearch`. +The Idle Timeout counter for a Region is reset whenever the Idle Timeout is reset for one of its entries. -Each of these may be applied to the Region itself or entries in the Region. _Spring Data for Pivotal GemFire_ provides ``, -``, `` and `` 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. Spring Data for Pivotal GemFire provides ``, +``, ``, and `` region child elements to specify timeout values and expiration actions. -For example: +The following example shows a partition region with expiration values set: [source,xml] ---- @@ -687,15 +688,15 @@ For example: ---- -For a detailed description of expiration policies, please refer to the Pivotal GemFire documentation on -http://geode.apache.org/docs/guide/11/developing/expiration/chapter_overview.html[Expiration]. +For a detailed description of expiration policies, see the Pivotal GemFire documentation on +http://geode.apache.org/docs/guide/11/developing/expiration/chapter_overview.html[expiration]. [[bootstrap:region:expiration:annotation]] === Annotation-based Data Expiration -With _Spring Data for Pivotal GemFire_, a developer has the ability to define Expiration policies and settings on individual -Region Entry values, or rather, application domain objects directly. For instance, a developer might define Expiration -settings on a Session-based application domain object like so... +With Spring Data for Pivotal GemFire, 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: [source,java] ---- @@ -705,9 +706,9 @@ public class SessionBasedApplicationDomainObject { } ---- -In addition, a developer may also specify Expiration type specific settings on Region Entries using +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... +expiration, respectively, as the following example shows: [source,java] ---- @@ -720,15 +721,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 above. Though, neither `@IdleTimeoutExpiration` -nor `@TimeToLiveExpiration` overrides the other; rather they may 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 types, 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 Pivotal GemFire's_ Expiration annotation support. However, Pivotal GemFire and _Spring Data for Pivotal GemFire_ do allow you -to set Region Expiration using the SDG XML namespace, like so... +All `@Expiration`-based annotations apply only to region entry values. Expiration for a region is not covered +by Spring Data for Pivotal GemFire's expiration annotation support. However, Pivotal GemFire and Spring Data for Pivotal GemFire do let you +set region expiration by using the SDG XML namespace, as follows: [source,xml] ---- @@ -739,22 +740,22 @@ to set Region Expiration using the SDG XML namespace, like so... ---- ==== -_Spring Data for Pivotal GemFire's_ `@Expiration` annotation support is implemented with Pivotal GemFire's +Spring Data for Pivotal GemFire's `@Expiration` annotation support is implemented with Pivotal GemFire's http://geode.apache.org/releases/latest/javadoc/org/apache/geode/cache/CustomExpiry.html[`CustomExpiry`] interface. -Refer to Pivotal GemFire's documentation on http://geode.apache.org/docs/guide/11/developing/expiration/configuring_data_expiration.html[Configuring Data Expiration] +See Pivotal GemFire's documentation on http://geode.apache.org/docs/guide/11/developing/expiration/configuring_data_expiration.html[configuring data expiration] for more details -The _Spring Data for Pivotal GemFire_ `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 Spring Data for Pivotal GemFire `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. -To use _Spring Data for Pivotal GemFire_ to configure specific Pivotal GemFire Regions to appropriately apply the Expiration policy -and settings applied to your application domain objects annotated with `@Expiration`-based annotations, you must... +To use Spring Data for Pivotal GemFire to configure specific Pivotal GemFire Regions to appropriately apply the Expiration policy +and settings applied to your application domain objects annotated with `@Expiration`-based annotations, you must: -1. Define a bean in the _Spring_ `ApplicationContext` of type `AnnotationBasedExpiration` 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_, then you should use one of the factory methods in the -`AnnotationBasedExpiration` class, like so... +. 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: + [source,xml] ---- @@ -768,18 +769,18 @@ such as _Idle Timeout_ or _Time-to-Live_, then you should use one of the factory + [NOTE] ==== -To configure _Idle Timeout_ (TTI) Expiration instead, then you would of course use the `forIdleTimeout` factory method +To configure Idle Timeout (TTI) Expiration instead, use the `forIdleTimeout` factory method along with the `` element to set TTI. ==== -2. (optional) Annotate your application domain objects that will be stored in the Region with Expiration policies -and custom settings using one of _Spring Data for Pivotal GemFire's_ `@Expiration` annotations: `@Expiration`, -`@IdleTimeoutExpiration` and/or `@TimeToLiveExpiration` +. (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 Pivotal GemFire's `@Expiration` annotations: `@Expiration`, +`@IdleTimeoutExpiration`, or `@TimeToLiveExpiration` -3. (optional) In cases where particular application domain objects have not been annotated with _Spring Data for Pivotal GemFire's_ +. (optional) In cases where particular application domain objects have not been annotated with Spring Data for Pivotal GemFire's `@Expiration` annotations at all, but the Pivotal GemFire Region is configured to use SDG's custom `AnnotationBasedExpiration` -class to determine the Expiration policy and settings for objects stored in the Region, then it is possible to set -"default" Expiration attributes on the `AnnotationBasedExpiration` bean by doing the following... +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] ---- @@ -798,15 +799,15 @@ class to determine the Expiration policy and settings for objects stored in the ---- -You may have noticed that _Spring Data for Pivotal GemFire's_ `@Expiration` annotations use a String as the attributes type rather -than, and perhaps more appropriately, being strongly typed, i.e. `int` for 'timeout' and SDG'S `ExpirationActionType` -for 'action'. Why is that? +You may have noticed that Spring Data for Pivotal GemFire'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? -Well, enter one of _Spring Data for Pivotal GemFire's_ other features, leveraging _Spring's_ core infrastructure -for configuration convenience: _Property Placeholders_ and _Spring Expression Language_ (SpEL). +Well, enter one of Spring Data for Pivotal GemFire's other features, leveraging Spring's core infrastructure +for configuration convenience: property placeholders and the Spring Expression Language (SpEL). -For instance, a developer can specify both the Expiration 'timeout' and 'action' using _Property Placeholders_ -in the `@Expiration` annotation attributes... +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] ---- @@ -817,7 +818,7 @@ public class ExampleApplicationDomainObject { } ---- -Then, in your _Spring_ XML config or in JavaConfig, you would declare the following beans... +Then, in your Spring XML config or in JavaConfig, you can declare the following beans: [source,xml] ---- @@ -830,13 +831,13 @@ Then, in your _Spring_ XML config or in JavaConfig, you would declare the follow ---- -This is both convenient when multiple application domain objects might share similar Expiration policies and settings, -or when you wish to externalize the configuration. +This is convenient both when multiple application domain objects might share similar expiration policies and settings +and when you wish to externalize the configuration. -However, a developer 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, etc, the values for Expiration 'timeout' -and 'action' can be strongly typed. For example (building on the example above)... +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' +and 'action' can be strongly typed. Consider the following example (which builds on the preceding example): [source,xml] ---- @@ -850,7 +851,7 @@ and 'action' can be strongly typed. For example (building on the example above) ---- -Then, on your application domain object... +Then, on your application domain object, you can define a timeout and an action as follows: [source,java] ---- @@ -861,46 +862,45 @@ public class ExampleApplicationDomainObject { } ---- -You can imagine that the 'expirationSettings' bean could be a more interesting and useful object rather than a simple -instance of `java.util.Properties`. In this example, even the Properties (`expirationSettings`) uses SpEL to base -the action value on the actual Expiration action enumerated type leading to more quickly identified failures +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. -All of this has been demonstrated and tested in the _Spring Data for Pivotal GemFire_ test suite, by way of example. See the +As an example, all of this has been demonstrated and tested in the Spring Data for Pivotal GemFire 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. Pivotal GemFire ensures that all the data you put into a Region that is configured for persistence -will be written to disk in a way that is recoverable the next time you recreate the Region. This allows data -to be recovered after machine or process failure, or even after an orderly shutdown and subsequent restart of +Regions can be persistent. Pivotal GemFire 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 Pivotal GemFire data node. -To enable persistence with _Spring Data for Pivotal GemFire_, simply set the `persistent` attribute to `true` on -any of the `<*-region>` elements. For example... +To enable persistence with Spring Data for Pivotal GemFire, set the `persistent` attribute to `true` on +any of the `<*-region>` elements, as the following example shows: [source,xml] ---- ---- -Persistence may also be configured using the `data-policy` attribute; set the attribute's value to one of -http://geode.apache.org/releases/latest/javadoc/org/apache/geode/cache/DataPolicy.html[Pivotal GemFire's DataPolicy settings]. -For example... +Persistence may also be configured by setting the `data-policy` attribute. To do so, set the attribute's value to one of +http://geode.apache.org/releases/latest/javadoc/org/apache/geode/cache/DataPolicy.html[Pivotal GemFire's DataPolicy settings], as the folloiwng example shows: [source,xml] ---- ---- -The `DataPolicy` must match the Region type and must also agree with the `persistent` attribute if also explicitly set. -An initialization exception will be thrown if the `persistent` attribute is set to `false` yet a persistent `DataPolicy` -was specified (e.g. PERSISTENT_REPLICATE, 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` +was specified (such as `PERSISTENT_REPLICATE` or `PERSISTENT_PARTITION`), an initialization exception is thrown. -When persisting Regions, it is recommended to configure the storage through the `disk-store` element -for maximum efficiency. The DiskStore is referenced using the `disk-store-ref` attribute. Additionally, the Region -may perform disk writes synchronously or asynchronously: +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`: [source,xml] ---- @@ -908,14 +908,14 @@ may perform disk writes synchronously or asynchronously: disk-store-ref="myDiskStore" disk-synchronous="true"/> ---- -This is discussed further in <> +This is discussed further in <>. [[bootstrap:region:subscription]] == Subscription Policy Pivotal GemFire allows configuration of http://geode.apache.org/docs/guide/11/developing/events/configure_p2p_event_messaging.html[peer-to-peer (P2P) event messaging] -to control the entry events that the Region will receive. _Spring Data for Pivotal GemFire_ provides the `` -sub-element to set the subscription policy on REPLICATE and PARTITION Regions to either `ALL` or `CACHE_CONTENT`. +to control the entry events that the region receives. Spring Data for Pivotal GemFire provides the `` +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] ---- @@ -927,11 +927,11 @@ sub-element to set the subscription policy on REPLICATE and PARTITION Regions to [[bootstrap:region:local]] == Local Region -_Spring Data for Pivotal GemFire_ offers a dedicated `local-region` element for creating local Regions. Local Regions, as the name -implies, are standalone, meaning they do not share data with any other distributed system member. Other than that, -all common Region configuration options apply. +Spring Data for Pivotal GemFire 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. -A minimal declaration looks as follows (again, the example relies on the _Spring Data for Pivotal GemFire_ namespace +The following example shows a minimal declaration (again, the example relies on the Spring Data for Pivotal GemFire namespace naming conventions to wire the cache): [source,xml] @@ -939,49 +939,49 @@ naming conventions to wire the cache): ---- -Here, a local Region is created (if one doesn't exist already). The name of the Region is the same as the bean id -(`exampleLocalRegion`) and the bean assumes the existence of a Pivotal GemFire cache named `gemfireCache`. +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 Pivotal GemFire 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 -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 _replica_. +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. -_Spring Data for Pivotal GemFire_ offers a `replicated-region` element. A minimal declaration looks as follows. All common configuration options are available for REPLICATE Regions. +Spring Data for Pivotal GemFire offers a `replicated-region` element. The following example shows a minimal declaration: [source,xml] ---- ---- -Refer to Pivotal GemFire's documentation on +See Pivotal GemFire's documentation on http://geode.apache.org/docs/guide/11/developing/distributed_regions/chapter_overview.html[Distributed and Replicated Regions] for more details. [[bootstrap:region:partition]] == Partitioned Region -Another Region type supported out-of-the-box by the _Spring Data for Pivotal GemFire_ namespace is the PARTITION Region. +The Spring Data for Pivotal GemFire namespace also supports `PARTITION` regions. To quote the Pivotal GemFire docs: -"A partitioned region is a region where data is divided between peer servers hosting the region so that +"`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. Pivotal GemFire divides the domain of hashcodes into buckets. Each bucket is assigned to a specific peer, -but may be relocated at any time to another peer in order to improve the utilization of resources across the cluster." +but may be relocated at any time to another peer in order to improve the utilization of resources across the cluster.`" -A partition is created using the `partitioned-region` element. Its configuration options are similar to that of -the `replicated-region` plus the partition specific features such as the number of redundant copies, -total maximum memory, number of buckets, partition resolver and so on. +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, +total maximum memory, number of buckets, partition resolver, and so on. -Below is a quick example on setting up a PARTITION Region with 2 redundant copies: +The following example shows how to set up a `PARTITION` region with two redundant copies: [source,xml] ---- @@ -992,15 +992,15 @@ Below is a quick example on setting up a PARTITION Region with 2 redundant copie ---- -Refer to Pivotal GemFire's documentation on +See Pivotal GemFire's documentation on http://geode.apache.org/docs/guide/11/developing/partitioned_regions/chapter_overview.html[Partitioned Regions] for more details. [[bootstrap:region:partition:attributes]] === Partitioned Region Attributes -The following table offers a quick overview of configuration options specific to PARTITION Regions. -These are in addition to the common Region configuration options described <>. +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 <>. [cols="1,2,2", options="header"] .partitioned-region attributes @@ -1011,54 +1011,54 @@ These are in addition to the common Region configuration options described <>, -`client-region` and `pool` elements. As the names imply, the former defines a client Region while the latter defines -a Pool of connections to be used/shared by the various client Regions. +Spring Data for Pivotal GemFire offers dedicated support for each configuration through its <> 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. -Below is a typical client Region configuration: +The following example shows a typical client region configuration: [source,xml] ---- @@ -1080,26 +1080,26 @@ Below is a typical client Region configuration: ---- -As with the other Region types, `client-region` supports `CacheListener``s` as well as a `CacheLoader` and `CacheWriter`. -It also requires a connection `Pool` for connecting to either a set of 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. -NOTE: In the above example, the Pool is configured with `locator`. A Locator is a separate process used to discover -cache servers and peer data members in the distributed system and are recommended for production systems. It is also -possible to configure the Pool to connect directly to one or more cache servers using the `server` element. +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, please refer to -the _Spring Data for Pivotal GemFire_ schema (<>) and Pivotal GemFire's documentation on -http://geode.apache.org/docs/guide/11/topologies_and_comm/cs_configuration/chapter_overview.html[Client/Server Configuration]. +For a full list of options to set on the client and especially on the `Pool`, see +the Spring Data for Pivotal GemFire schema ("`<>`") and Pivotal GemFire's documentation on +http://geode.apache.org/docs/guide/11/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 Pivotal GemFire -the data it actually requires. In _Spring Data for Pivotal GemFire_, 'interests' can be defined for each client Region separately. -Both Key-based and Regular Expression-based interest types are supported. +the data it actually requires. In Spring Data for Pivotal GemFire, 'interests' can be defined for each client region separately. +Both key-based and regular expression-based interest types are supported. -For example: +The following example shows both key-based and regular expression-based `interest` types: [source,xml] ---- @@ -1113,36 +1113,34 @@ For example: ---- -A special key, `ALL_KEYS`, means 'interest' is registered for all keys. The same can be accomplished using a regex +A special key, `ALL_KEYS`, means 'interest' is registered for all keys. The same can be accomplished by using a regex of `".\*"`. -The `` _Key_ and _Regular Expression_ elements support 3 attributes: `durable`, `receive-values` +The `` 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 1 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 server(s) for the client is maintained while the client is disconnected, -and when the client reconnects, the client will receive any events that occurred while the client was disconnected -from the servers(s) in the cluster. +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 subscription queue on the servers in the cluster is maintained for each `Pool` of connections defined in the client -where 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 -(i.e. 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", -then it will be destroyed when the client disconnects. All you need to decide is, for your application use case, -is it important for the cache client to receive events while it is disconnected, or is it only important for -the application (cache client) to receive the "latest" events after it reconnects. +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. 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. +If `true`, values are received. If `false`, only invalidation events are received. -And finally, the 'result-policy` is an enumeration of: `KEYS`, `KEYS_VALUE` and `NONE`. The default is `KEYS_VALUES`. +And finally, the 'result-policy` is an enumeration of: `KEYS`, `KEYS_VALUE`, and `NONE`. The default is `KEYS_VALUES`. The `result-policy` controls the initial dump when the client first connects to initialize the local cache, essentially seeding the client with events for all the entries that match the interest policy. -Client-side interests registration does not do much good without enabling subscription on the `Pool` as mentioned above. -In fact, it is an error to attempt interests registration without subscription enabled. To do so, you simply... +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: [source,xml] ---- @@ -1152,18 +1150,18 @@ In fact, it is an error to attempt interests registration without subscription e ---- 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 1, and the "primary" subscription queue (i.e. server) goes down, then a "secondary" subscription queue -will take over, keeping the client from missing events in a HA scenario. +`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 will be sent to the clients. This can also +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, in cases where the application is keeping a time series of events that occurred, -conflation is going to hinder that use case. The default value is *false*. An example Region configuration -on the server for which the client contains a corresponding client [CACHING_]PROXY Region with interests in Keys -in this server Region, would look like... +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] ---- @@ -1172,9 +1170,9 @@ in this server Region, would look like... ---- -To control the amount of time in seconds that "durable" subscription queue is maintained after a client is disconnected -from the server(s) in the cluster, set the `durable-client-timeout` attribute on the `` element -like so... +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 `` element +as follows: [source,xml] ---- @@ -1185,41 +1183,41 @@ like so... A full, in-depth discussion of how client interests work and capabilities is beyond the scope of this document. -Please refer to Pivotal GemFire's documentation on +See Pivotal GemFire's documentation on http://gemfire.docs.pivotal.io/geode/developing/events/how_client_server_distribution_works.html[Client-to-Server Event Distribution] for more details. [[bootstrap:region:json]] == JSON Support -Pivotal GemFire has support for caching JSON documents in Regions along with the ability to query stored JSON documents -using the Pivotal GemFire OQL. JSON documents are stored internally as -http://geode.apache.org/releases/latest/javadoc/org/apache/geode/pdx/PdxInstance.html[PdxInstance] types +Pivotal GemFire has support for caching JSON documents in regions, along with the ability to query stored JSON documents +using the Pivotal GemFire OQL (Object Query Language). JSON documents are stored internally as +http://geode.apache.org/releases/latest/javadoc/org/apache/geode/pdx/PdxInstance.html[PdxInstance] types by using the http://geode.apache.org/releases/latest/javadoc/org/apache/geode/pdx/JSONFormatter.html[JSONFormatter] class to perform conversion to and from JSON documents (as a `String`). -_Spring Data for Pivotal GemFire_ provides the `` element to enable a -http://docs.spring.io/spring/docs/current/spring-framework-reference/htmlsingle/#aop-introduction[AOP, _Spring_] -component to advise appropriate, proxied Region operations, which effectively encapsulates the `JSONFormatter`, -thereby allowing your applications to work directly with JSON Strings. +Spring Data for Pivotal GemFire provides the `` 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. -In addition, Java objects written to JSON configured Regions will be automatically converted to JSON using Jackson's -`ObjectMapper`. Reading these values back will be returned as a JSON String. +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, `` performs the conversion for all Regions. To apply this feature -to selected Regions, provide a comma delimited list of Region bean ids via the `region-refs` attribute. -Other attributes include a `pretty-print` flag (defaults to *false*) and `convert-returned-collections`. +By default, `` 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 will be 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 Pivotal GemFire's proprietary `Region.Entry` such as: -`entries(boolean)`, `entrySet(boolean)` and `getEntry()` type are not targeted for AOP advice. In addition, -the `entrySet()` method which returns a `Set>` is also not affected. +NOTE: Certain Region operations (specifically those that use Pivotal GemFire's proprietary `Region.Entry`, such as: +`entries(boolean)`, `entrySet(boolean)` and `getEntry()` type) are not targeted for AOP advice. In addition, +the `entrySet()` method (which returns a `Set>`) is also not affected. -Example configuration: +The following example configuration shows how to set the `pretty-print` and `convert-returned-collections` attributes: [source,xml] ---- @@ -1227,4 +1225,4 @@ Example configuration: ---- This feature also works seamlessly with `GemfireTemplate` operations, provided that the template is declared -as a _Spring_ bean. Currently, the native `QueryService` operations are not supported. +as a Spring bean. Currently, the native `QueryService` operations are not supported. diff --git a/src/main/asciidoc/reference/repositories.adoc b/src/main/asciidoc/reference/repositories.adoc index 9a3c8ecd..837f7423 100644 --- a/src/main/asciidoc/reference/repositories.adoc +++ b/src/main/asciidoc/reference/repositories.adoc @@ -1,17 +1,15 @@ [[gemfire-repositories]] = Spring Data for Pivotal GemFire Repositories -== Introduction - -_Spring Data for Pivotal GemFire_ provides support to use the _Spring Data Repository_ abstraction to easily persist entities -into Pivotal GemFire along with execute queries. A general introduction to the _Repository programming model_ is provided +Spring Data for Pivotal GemFire provides support for using the Spring Data Repository abstraction to easily persist entities +into Pivotal GemFire 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]. [[gemfire-repositories.spring-configuration-xml]] == Spring XML Configuration -To bootstrap _Spring Data Repositories_, you use the `` element from the _Spring Data for Pivotal GemFire_ -Data namespace: +To bootstrap Spring Data Repositories, use the `` element from the Spring Data for Pivotal GemFire +Data namespace, as the following example shows: .Bootstrap Spring Data for Pivotal GemFire Repositories in XML ==== @@ -30,20 +28,19 @@ Data namespace: ---- ==== -This configuration snippet looks for interfaces below the configured base package and creates _Repository_ instances -for those interfaces backed by a `SimplePivotal GemFireRepository`. +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: You must have your application domain classes correctly mapped to configured Regions -or the bootstrap process will fail otherwise. +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 users prefer to use _Spring's_ +Alternatively, many developers prefer to use Spring's https://docs.spring.io/spring/docs/current/spring-framework-reference/core.html#beans-java[Java-based container configuration]. -Using this approach, it is a simple matter to bootstrap _Spring Data Repositories_ using the SDG `@EnableGemfireRepositories` -annotation: +Using this approach, you can bootstrap Spring Data Repositories by using the SDG `@EnableGemfireRepositories` +annotation, as the following example shows: .Bootstrap _Spring Data for Pivotal GemFire Repositories_ with `@EnableGemfireRepositories` ==== @@ -58,46 +55,46 @@ class SpringDataApplication { ==== Rather than use the `basePackages` attribute, you may prefer to use the type-safe `basePackageClasses` attribute instead. -The `basePackageClasses` allows you to specify the package containing all your application _Repository_ classes -by specifying just one of your application _Repository_ interface types. Consider creating a special no-op marker class -or interface in each package that serves no other purpose 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, like _Spring's_ +In addition to the `basePackage[sClasses]` attributes, such as Spring's https://docs.spring.io/spring/docs/current/javadoc-api/org/springframework/context/annotation/ComponentScan.html[`@ComponentScan`] annotation, -the `@EnableGemfireRepositories` annotation provides _include_ and _exclude_ filters, based on _Spring's_ +the `@EnableGemfireRepositories` annotation provides include and exclude filters, based on Spring's https://docs.spring.io/spring/docs/current/javadoc-api/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 -is annotated with a particular `Annotation` or extends a particular class type, and so on. See the -https://docs.spring.io/spring/docs/current/javadoc-api/org/springframework/context/annotation/FilterType.html[`FilterType` _Javadoc_] +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 +https://docs.spring.io/spring/docs/current/javadoc-api/org/springframework/context/annotation/FilterType.html[`FilterType` Javadoc] for more details. -The `@EnableGemfireRepositories` annotation also provides the ability to specify the location of named OQL queries, -which reside in a Java `Properties` file, 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 1 or more https://docs.spring.io/spring-data/commons/docs/current/reference/html/#repositories.custom-implementations[custom _Repository_ implementations]. -This feature is commonly used to extend the _Spring Data Repository_ infrastructure in order to implement a feature -not provided out-of-the-box (OOTB) by the data store (e.g. SDG). +The `repositoryImplementationPostfix` attribute can be set to an alternate value (defaults to `Impl`) if your +application requires one or more https://docs.spring.io/spring-data/commons/docs/current/reference/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). -One example of where custom _Repository_ implementations are needed with Pivotal GemFire is when performing _Joins_. -_Joins_ are not supported by SDG _Repositories_ OOTB. With a Pivotal GemFire `PARTITION` Region, the _Join_ must be -performed on collocated `PARTITION` Regions even, since Pivotal GemFire does not support "distributed" _Joins_. -In addition, the _Equi-Join_ OQL Query must be performed inside a Pivotal GemFire Function. +One example of where custom repository implementations are needed with Pivotal GemFire is when performing joins. +Joins are not supported by SDG repositories. With a Pivotal GemFire `PARTITION` Region, the join must be +performed on co-located `PARTITION` regions, since Pivotal GemFire does not support "`distributed`" joins. +In addition, the Equi-Join OQL Query must be performed inside a Pivotal GemFire function. See http://gemfire91.docs.pivotal.io/geode/developing/partitioned_regions/join_query_partitioned_regions.html[here] for more details on Pivotal GemFire _Equi-Join Queries_. -Many other aspects of the SDG's _Repository_ infrastructure extension maybe 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_] +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. [[gemfire-repositories.queries.executing]] == Executing OQL Queries -_Spring Data for Pivotal GemFire Repositories_ enable the definition of query methods to easily execute Pivotal GemFire OQL Queries -against the Region the managed entity is mapped to. +Spring Data for Pivotal GemFire Repositories enable the definition of query methods to easily execute Pivotal GemFire OQL queries +against the region the managed entity maps to, as the following example shows: .Sample Repository ==== @@ -124,12 +121,14 @@ public interface PersonRepository extends CrudRepository { ---- ==== -The first query method listed here will cause the following OQL query to be derived: -`SELECT x FROM /People x WHERE x.emailAddress = $1`. The second query method works the same way except -it's returning all entities found whereas the first query method expects a single result to be found. +The first query method listed in the preceding example causes the following OQL query to be derived: +`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. -In case the supported keywords are not sufficient to expresss and declare your OQL query, or the method name -becomes too verbose, you can annotate the query methods with `@Query` as seen for methods 3 and 4. +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. + +The following table gives brief samples of the supported keywords that you can use in query methods: [cols="1,2,2", options="header"] .Supported keywords for query methods @@ -196,28 +195,28 @@ becomes too verbose, you can annotate the query methods with `@Query` as seen fo |=== [[gemfire-repositories.queries.oql-extensions]] -== OQL Query Extensions using Annotations +== OQL Query Extensions Using Annotations Many query languages, such as Pivotal GemFire'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 -in order 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 very 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 Pivotal GemFire's OQL Query language extensions and preserve portability across different data stores, -_Spring Data for Pivotal GemFire_ adds support for OQL Query extensions using Java Annotations. These Annotations will be ignored -by other _Spring Data Repository_ implementations (e.g. _Spring Data_ JPA or _Spring Data Redis_) that do not have +Spring Data for Pivotal GemFire 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. -For instance, many data stores will most likely not implement Pivotal GemFire's OQL `IMPORT` keyword. By implementing `IMPORT` -as an Annotation (i.e. `@Import`) rather than as part of the query method signature (specifically, the method 'name'), -then this will not interfere with the parsing infrastructure when evaluating the query method name to construct +For instance, many data stores most likely do not implement Pivotal GemFire'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. -Currently, the set of Pivotal GemFire OQL Query language extensions that are supported by _Spring Data for Pivotal GemFire_ include: +Currently, the set of Pivotal GemFire OQL Query language extensions that are supported by Spring Data for Pivotal GemFire include: [cols="1,2,2,2", options="header"] .Supported Pivotal GemFire OQL extensions for Repository query methods @@ -229,7 +228,7 @@ Currently, the set of Pivotal GemFire OQL Query language extensions that are sup | http://gemfire.docs.pivotal.io/docs-gemfire/latest/developing/query_index/query_index_hints.html#topic_cfb_mxn_jq[HINT] | `@Hint` -| OQL Query Index Hints +| OQL query index hints | `String[]` (e.g. @Hint({ "IdIdx", "TxDateIdx" })) | http://gemfire.docs.pivotal.io/docs-gemfire/latest/developing/query_select/the_import_statement.html#concept_2E9F15B2FE9041238B54736103396BF7[IMPORT] @@ -244,12 +243,12 @@ Currently, the set of Pivotal GemFire OQL Query language extensions that are sup | http://gemfire.docs.pivotal.io/docs-gemfire/latest/developing/query_additional/query_debugging.html#concept_2D557E24AAB24044A3DB36B3124F6748[TRACE] | `@Trace` -| Enable OQL Query specific debugging. +| Enable OQL query-specific debugging. | NA |=== -As an example, suppose you have a `Customers` application domain class and corresponding Pivotal GemFire Region along with a -`CustomerRepository` and a query method to lookup `Customers` by last name, like so... +As an example, suppose you have a `Customers` application domain class and corresponding Pivotal GemFire region along with a +`CustomerRepository` and a query method to lookup `Customers` by last name, as follows: .Sample Customers Repository ==== @@ -291,15 +290,14 @@ public interface CustomerRepository extends GemfireRepository { ---- ==== -This will result in the following OQL Query: +The preceding example results in the following OQL Query: ` IMPORT org.example.app.domain.Customer; SELECT * FROM /Customers x WHERE x.lastName = $1 LIMIT 10` -_Spring Data for Pivotal GemFire's Repository_ extension and support is careful not to create conflicting declarations when +Spring Data for Pivotal GemFire'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. -As another example, suppose you have a raw `@Query` annotated query method defined in your `CustomerRepository` -like so... +As another example, suppose you have a raw `@Query` annotated query method defined in your `CustomerRepository`, as follows: .CustomerRepository ==== @@ -317,33 +315,33 @@ public interface CustomerRepository extends GemfireRepository { ---- ==== -This query method results in the following OQL Query: +The preceding query method results in the following OQL Query: `IMPORT org.example.app.domain.Customer; SELECT DISTINCT * FROM /Customers x WHERE x.reputation > $1 ORDER BY c.reputation DESC LIMIT 5` -As you can see, the `@Limit(10)` annotation will +not+ override the `LIMIT` defined explicitly in the raw query. -As well, `@Hint("CustomerIdx")` annotation does +not+ override the `HINT` explicitly defined in the raw query. +The `@Limit(10)` annotation does not override the `LIMIT` defined explicitly 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 will possibly have -the same value for their reputation, which will effectively reduce the effectiveness of the index. Please choose -indexes and other optimizations wisely as an improper or poorly choosen index can have the opposite effect on your -performance given the overhead in maintaining the index. The "ReputationIdx" was only used to serve the purpose +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. ==== [[gemfire-repositories.queries.post-processing]] == Query Post Processing -Using the Spring Data _Repository_ abstraction, 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 Pivotal GemFire_ introduces the `o.s.d.gemfire.repository.query.QueryPostProcessor` -functional interface. The interface is loosely defined as follows... +Since 2.0.x, Spring Data for Pivotal GemFire includes the `o.s.d.gemfire.repository.query.QueryPostProcessor` +functional interface. The interface is loosely defined as follows: .QueryPostProcessor ==== @@ -365,31 +363,31 @@ interface QueryPostProcessor extends Ordered { ---- ==== -There are additional default methods provided to allow users to compose instances of `QueryPostProcessor` very similar +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, you will notice that the `QueryPostProcessor` interface implements the +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. 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 of `T` extends the Spring Data Commons marker interface, https://docs.spring.io/spring-data/commons/docs/current/api/org/springframework/data/repository/Repository.html[`org.springframework.data.repository.Repository`]. -We will discuss this further below. All `QUERY` type parameter arguments in _Spring Data for Pivotal GemFire's_ case -will be of type `java.lang.String`. +We discuss this further later in this section. All `QUERY` type parameter arguments in Spring Data for Pivotal GemFire's case +are of type `java.lang.String`. -NOTE: It is useful to define the query as type `QUERY` since this `QueryPostProcessor` interface maybe ported to -_Spring Data Commons_ and therefore must handle all forms of queries by different data stores (e.g. JPA, MongoDB, +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, or Redis). -As user may implement this interface to receive a callback with the query that was generated from the application +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, I might want to log all queries from all application _Repository_ interface definitions. I could do so -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 ==== @@ -415,10 +413,10 @@ class LoggingQueryPostProcessor implements QueryPostProcessor { ---- ==== -Then, I could have typed the `LoggingQueryPostProcessor` specifically to the `CustomerRepository`, like so... +Then you could have typed the `LoggingQueryPostProcessor` specifically to the `CustomerRepository`, as follows: .CustomerLoggingQueryPostProcessor ==== @@ -444,12 +442,12 @@ class LoggingQueryPostProcessor implements QueryPostProcessor { ==== However, if you do not have control over the application `CustomerRepository` interface definition, -then the `QueryPostProcessor` (i.e. `OrderedLimitedCustomerByLastNameQueryPostProcessor`) is convenient. +then the `QueryPostProcessor` (that is, `OrderedLimitedCustomerByLastNameQueryPostProcessor`) is convenient. -If I want to ensure the `LoggingQueryPostProcessor` always comes after the other application-defined `QueryPostProcessors` -that I may have declared and registered in the Spring `ApplicationContext`, then I can set the `order` property -by overriding the `o.s.core.Ordered.getOrder()` method. +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: .Defining the `order` property ==== @@ -522,9 +520,9 @@ class CustomerQueryPostProcessor implements QueryPostProcessor - removes an entry (by key) from the grid ... ---- -For example to add new items to the grid one can use: +For example, to add new items to the grid, you can use the following commands: [source] ---- @@ -76,8 +75,8 @@ null 2 ---- -Multiple instances can be ran at the same time. Once started, the new VMs automatically see the existing Region -and its information: +Multiple instances can be ran at the same time. Once started, the new VMs automatically see the existing region +and its information, as the following example shows: [source] ---- @@ -93,22 +92,22 @@ Hello World! [one, two] ---- -Experiment with the example, start (and stop) as many instances as you want, run various commands in one instance -and see how the others react. To preserve data, at least one instance needs to be alive all times. If all instances +We encourage you to experiment with the example, start (and stop) as many instances as you want, and run various commands in one instance +and see how the others react. To preserve data, at least one instance needs to be alive all times. If all instances are shutdown, the grid data is completely destroyed. [[samples:hello-world:explained]] === Hello World Sample Explained -Hello World uses both _Spring_ XML and annotations for its configuration. The initial bootstrapping configuration is +The "`Hello World`" sample uses both Spring XML and annotations for its configuration. The initial bootstrapping configuration is `app-context.xml`, which includes the cache configuration defined in the `cache-context.xml` file and performs classpath http://docs.spring.io/spring/docs/current/spring-framework-reference/htmlsingle/#beans-classpath-scanning[component scanning] -for _Spring_ +for Spring http://docs.spring.io/spring/docs/current/spring-framework-reference/htmlsingle/#beans-annotation-config[components]. -The cache configuration defines the Pivotal GemFire cache, Region and for illustrative purposes, a simple `CacheListener` +The cache configuration defines the Pivotal GemFire cache, a region, and for illustrative purposes, a `CacheListener` that acts as a logger. -The main *beans* are `HelloWorld` and `CommandProcessor` which rely on the `GemfireTemplate` to interact with -the distributed fabric. Both classes use annotations to define their dependency and life-cycle callbacks. +The main beans are `HelloWorld` and `CommandProcessor`, which rely on the `GemfireTemplate` to interact with +the distributed fabric. Both classes use annotations to define their dependency and life-cycle callbacks. diff --git a/src/main/asciidoc/reference/serialization.adoc b/src/main/asciidoc/reference/serialization.adoc index ba8c26b6..8e9a8364 100644 --- a/src/main/asciidoc/reference/serialization.adoc +++ b/src/main/asciidoc/reference/serialization.adoc @@ -3,37 +3,37 @@ To improve overall performance of the Pivotal GemFire In-memory Data Grid, Pivotal GemFire supports a dedicated serialization protocol, called PDX, that is both faster and offers more compact results over -standard Java serialization in addition to works transparently across various language platforms (Java, C++, .NET). -Please refer to +standard Java serialization in addition to working transparently across various language platforms (Java, C++, and .NET). +See http://geode.apache.org/docs/guide/11/developing/data_serialization/PDX_Serialization_Features.html[PDX Serialization Features] and https://cwiki.apache.org/confluence/display/GEODE/PDX+Serialization+Internals[PDX Serialization Internals] for more details. -This chapter discusses the various ways in which _Spring Data for Pivotal GemFire_ simplifies and improves Pivotal GemFire's +This chapter discusses the various ways in which Spring Data for Pivotal GemFire simplifies and improves Pivotal GemFire's custom serialization in Java. [[serialization:wiring]] == Wiring deserialized instances 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/machine. -For such cases, _Spring Data for Pivotal GemFire_ offers a special +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 Pivotal GemFire offers a special http://geode.apache.org/releases/latest/javadoc/org/apache/geode/Instantiator.html[`Instantiator`] that performs wiring for each new instance created by Pivotal GemFire during deserialization. -Through such a mechanism, one 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 +Spring users might find this approach similar to that of http://docs.spring.io/spring/docs/current/spring-framework-reference/htmlsingle/#aop-atconfigurable[`@Configurable`]). -The `WiringInstantiator` works just like `WiringDeclarableSupport`, trying to first locate a bean definition -as a wiring template and falling back to autowiring otherwise. +The `WiringInstantiator` works similarly to `WiringDeclarableSupport`, trying to first locate a bean definition +as a wiring template and otherwise falling back to autowiring. -Please refer to the previous section (<>) for more details on wiring functionality. +See the previous section (<>) for more details on wiring functionality. -To use this SDG `Instantiator`, simply declare it as a bean: +To use this SDG `Instantiator`, declare it as a bean, as the following example shows: [source,xml] ---- @@ -45,18 +45,18 @@ To use this SDG `Instantiator`, simply declare it as a bean: ---- -During the _Spring_ container startup, once it is being initialized, the `Instantiator` will, by default, register -itself with the Pivotal GemFire serialization system and perform wiring on all instances of `SomeDataSerializableClass` +During the Spring container startup, once it is being initialized, the `Instantiator`, by default, registers +itself with the Pivotal GemFire serialization system and performs wiring on all instances of `SomeDataSerializableClass` created by Pivotal GemFire during deserialization. [[serialization:instance-generator]] -== Auto-generating custom `Instantiators` +== Auto-generating Custom `Instantiators` For data intensive applications, a large number of instances might be created on each machine as data flows in. -Out-of-the-box, Pivotal GemFire uses reflection to create new types, but for some scenarios, this might prove to be expensive. -As always, it is good to perform profiling to quantify whether this is the case or not. For such cases, -_Spring Data for Pivotal GemFire_ allows the automatic generation of `Instatiator` classes which instantiate a new type -(using the default constructor) without the use of reflection: +Pivotal GemFire uses reflection to create new types, but, for some scenarios, this might prove to be expensive. +As always, it is good to perform profiling to quantify whether this is the case or not. For such cases, +Spring Data for Pivotal GemFire 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 +70,6 @@ _Spring Data for Pivotal GemFire_ allows the automatic generation of `Instatiato ---- -The definition above, automatically generates two `Instantiators` for two classes, namely `CustomTypeA` -and `CustomTypeB` and registers them with Pivotal GemFire, under user id `1025` and `1026`. The two `Instantiators` avoid +The preceding definition automatically generates two `Instantiators` for two classes (`CustomTypeA` +and `CustomTypeB`) and registers them with Pivotal GemFire under user ID `1025` and `1026`. The two `Instantiators` avoid the use of reflection and create the instances directly through Java code. diff --git a/src/main/asciidoc/reference/snapshot.adoc b/src/main/asciidoc/reference/snapshot.adoc index 303adf72..a29226f5 100644 --- a/src/main/asciidoc/reference/snapshot.adoc +++ b/src/main/asciidoc/reference/snapshot.adoc @@ -1,7 +1,7 @@ [[bootstrap:snapshot]] = Configuring the Snapshot Service -_Spring Data for Pivotal GemFire_ supports `Cache` and `Region` snapshots using +Spring Data for Pivotal GemFire supports `cache` and `region` snapshots by using http://geode.apache.org/docs/guide/11/managing/cache_snapshots/chapter_overview.html[Pivotal GemFire's Snapshot Service]. The out-of-the-box Snapshot Service support offers several convenient features to simplify the use of Pivotal GemFire's http://geode.apache.org/releases/latest/javadoc/org/apache/geode/cache/snapshot/CacheSnapshotService.html[Cache] @@ -9,17 +9,17 @@ and http://geode.apache.org/releases/latest/javadoc/org/apache/geode/cache/snaps Snapshot Service APIs. As the http://geode.apache.org/docs/guide/11/managing/cache_snapshots/chapter_overview.html[Pivotal GemFire documentation] -describes, snapshots allow you to save and subsequently reload the cached data later, which can be useful for +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 imagine combining _Spring Data for Pivotal GemFire's_ Snapshot Service support +data-related issues in a controlled context. You can combine Spring Data for Pivotal GemFire'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 Pivotal GemFire's_ support for Pivotal GemFire's Snapshot Service begins with the `` element +Spring Data for Pivotal GemFire's support for Pivotal GemFire's Snapshot Service begins with the `` element from the `` namespace. -For example, I might want to define Cache-wide snapshots to be loaded as well as saved using a couple snapshot imports -and a data export definition as follows: +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: [source,xml] ---- @@ -31,13 +31,13 @@ and a data export definition as follows: ---- -You can define as many imports and/or exports as you like. You can define just imports or just exports. -The file locations and directory paths can be absolute, or relative to the _Spring Data for Pivotal GemFire_ application, +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 Pivotal GemFire application, which is the JVM process's working directory. -This is a pretty simple example and the Snapshot Service defined in this case refers to the Pivotal GemFire `Cache` with -the default name of `gemfireCache` (as described in <>). If you name your cache bean definition -something other than the default, than you can use the `cache-ref` attribute to refer to the cache bean by name: +The preceding example is pretty simple, and the Snapshot Service defined in this case refers to the Pivotal GemFire `cache` with +the default name of `gemfireCache` (as described in <>). 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 +48,8 @@ something other than the default, than you can use the `cache-ref` attribute to ---- -It is also straightforward to define a Snapshot Service for a particular Pivotal GemFire Region by specifying -the `region-ref` attribute: +You can also define a Snapshot Service for a particular Pivotal GemFire Region by specifying +the `region-ref` attribute, as follows: [source,xml] ---- @@ -61,39 +61,39 @@ the `region-ref` attribute: ---- -When the `region-ref` attribute is specified, _Spring Data for Pivotal GemFire's_ `SnapshotServiceFactoryBean` resolves -the `region-ref` attribute value to a Region bean defined in the _Spring_ context and proceeds to create a -http://geode.apache.org/releases/latest/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 +When the `region-ref` attribute is specified, Spring Data for Pivotal GemFire's `SnapshotServiceFactoryBean` resolves +the `region-ref` attribute value to a region bean defined in the Spring context and creates a +http://geode.apache.org/releases/latest/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. -NOTE: Pivotal GemFire is strict about imported snapshot files actually existing before they are referenced. For exports, -Pivotal GemFire will create the snapshot file if it does not already exist. If the snapshot file for export already exists, -the data will be overwritten. +NOTE: Pivotal GemFire is strict about imported snapshot files actually existing before they are referenced. For exports, +Pivotal GemFire creates the snapshot file. If the snapshot file for export already exists, +the data is overwritten. -TIP: _Spring Data for Pivotal GemFire_ includes a `suppress-import-on-init` attribute on the `` element -to suppress the configured Snapshot Service from trying to import data into the Cache or Region on initialization. -This is useful when data exported from 1 Region is used to feed the import of another Region, for example. +TIP: Spring Data for Pivotal GemFire includes a `suppress-import-on-init` attribute on the `` 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 -(i.e. http://geode.apache.org/releases/latest/javadoc/org/apache/geode/cache/snapshot/CacheSnapshotService.html[CacheSnapshotService]) -a developer would typically pass it a directory containing all the snapshot files to load rather than +(that is, a http://geode.apache.org/releases/latest/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 -http://geode.apache.org/releases/latest/javadoc/org/apache/geode/cache/snapshot/CacheSnapshotService.html#load-java.io.File-org.apache.geode.cache.snapshot.SnapshotOptions.SnapshotFormat-[load] +http://geode.apache.org/releases/latest/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, a developer may use the other, overloaded `load(:File[], :SnapshotFormat, :SnapshotOptions)` method -variant to get specific about which snapshot files are to be loaded into the Pivotal GemFire `Cache`. +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 Pivotal GemFire `cache`. -However, _Spring Data for Pivotal GemFire_ 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 +However, Spring Data for Pivotal GemFire 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 Pivotal GemFire_ enables the developer to specify a JAR or ZIP file on import for a `Cache`-based -Snapshot Service as follows: +Therefore, Spring Data for Pivotal GemFire lets you specify a jar or zip file on import for a `cache`-based +Snapshot Service, as follows: [source,xml] ---- @@ -102,19 +102,19 @@ Snapshot Service as follows: ---- -_Spring Data for Pivotal GemFire_ will conveniently extract the provided ZIP file and treat it like a directory import (load). +Spring Data for Pivotal GemFire 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 Pivotal GemFire's -http://geode.apache.org/releases/latest/javadoc/org/apache/geode/cache/snapshot/SnapshotFilter.html[SnapshotFilter] -interface and are used to filter Region entries for inclusion into the Region on import +http://geode.apache.org/releases/latest/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 Pivotal GemFire_ makes it brain dead simple to utilize snapshot filters on import and export using the `filter-ref` -attribute or an anonymous, nested bean definition: +Spring Data for Pivotal GemFire 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] ---- @@ -140,22 +140,20 @@ attribute or an anonymous, nested bean definition: ---- -In addition, more complex snapshot filters can be expressed with the `ComposableSnapshotFilter` _Spring Data for Pivotal GemFire_ -provided class. This class implements Pivotal GemFire's +In addition, you can express more complex snapshot filters by using the `ComposableSnapshotFilter` class. +This class implements Pivotal GemFire's http://geode.apache.org/releases/latest/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 allows developers -to compose multiple objects of the same type and treat the aggregate as single instance of the object type, -a very powerful and useful abstraction. +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'`, allowing developers to logically combine -individual snapshot filters using the AND and OR logical operators, respectively. The factory methods take a +`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`. -In this case, the developer is only limited by his/her imagination to leverage this powerful construct. - -For instance: +The following example shows a definition for a `ComposableSnapshotFilter`: [source,xml] ---- @@ -171,7 +169,7 @@ For instance: ---- -The developer could then go onto combine the `activesUsersSinceFilter` with another filter using `'or'` like so: +You could then go on to combine the `activesUsersSinceFilter` with another filter by using `or`, as follows: [source,xml] ---- @@ -189,36 +187,36 @@ The developer could then go onto combine the `activesUsersSinceFilter` with anot [[bootstrap::snapshot::events]] == Snapshot Events -By default, _Spring Data for Pivotal GemFire_ uses Pivotal GemFire's Snapshot Services on startup to import data and shutdown -to export data. However, you may want to trigger periodic, event-based snapshots, for either import or export -from within your _Spring_ application. +By default, Spring Data for Pivotal GemFire uses Pivotal GemFire'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 Pivotal GemFire_ defines two additional _Spring_ application events, extending _Spring's_ -http://docs.spring.io/spring/docs/current/javadoc-api/org/springframework/context/ApplicationEvent.html[ApplicationEvent] +For this purpose, Spring Data for Pivotal GemFire 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 Pivotal GemFire Cache, or individual Pivotal GemFire Regions. The constructors -in these classes accept an optional Region pathname (e.g. "/Example") as well as 0 or more `SnapshotMetadata` instances. +The two application events can be targeted at the entire Pivotal GemFire cache or individual Pivotal GemFire regions. The constructors +in these classes accept an optional region pathname (such as `/Example`) as well as xero or more `SnapshotMetadata` instances. -The array of `SnapshotMetadata` is used to override the snapshot meta-data defined by `` -and `` sub-elements in XML, which will be used in cases where snapshot application events -do not explicitly provide `SnapshotMetadata`. Each individual `SnapshotMetadata` instance can define it's own +The array of `SnapshotMetadata` overrides the snapshot metadata defined by `` +and `` 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. -Import/export snapshot application events are received by all snapshot service beans defined in the _Spring_ -`ApplicationContext`. However, import/export events are only processed by "matching" Snapshot Service beans. +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 it's Region reference (as determined by the `region-ref` attribute) matches -the Region's pathname 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` (i.e. 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. -It is very easy to use _Spring's_ -http://docs.spring.io/spring/docs/current/javadoc-api/org/springframework/context/ApplicationEventPublisher.html[ApplicationEventPublisher] -interface to fire import and/or export snapshot application events from your application like so: +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: [source,java] ---- @@ -246,12 +244,11 @@ public class ExampleApplicationComponent { } ---- -In this particular example, only the "/Example" Region's Snapshot Service bean will pick up and handle the export event, -saving the filtered, "/Example" Region's data to the "data.snapshot" file in a sub-direcrtory +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. -Using _Spring_ application events and messaging subsystem is a good way to keep your application loosely coupled. -It is also not difficult to imagine that the snapshot application events could be fired on a periodic basis -using _Spring's_ +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. +services to fire snapshot application events on a periodic basis.