From 6d34d24b2ac4eed866df540ac891aabc45f980d9 Mon Sep 17 00:00:00 2001 From: John Blum Date: Tue, 17 Jul 2018 14:38:49 -0700 Subject: [PATCH] SGF-768 - Replace all direct URL/links with Asciidoc variables. Replace all product names with Asciidoc variables. Replace all product versions with Asciidoc variables. --- pom.xml | 1 - .../asciidoc/appendix/appendix-schema.adoc | 6 +- src/main/asciidoc/index.adoc | 32 +- .../asciidoc/introduction/introduction.adoc | 6 +- .../asciidoc/introduction/new-features.adoc | 104 ++-- .../asciidoc/introduction/requirements.adoc | 4 +- src/main/asciidoc/links.adoc | 20 +- src/main/asciidoc/preface.adoc | 6 +- .../reference/bootstrap-annotations.adoc | 588 +++++++++--------- src/main/asciidoc/reference/bootstrap.adoc | 68 +- src/main/asciidoc/reference/cache.adoc | 138 ++-- src/main/asciidoc/reference/cq-container.adoc | 43 +- src/main/asciidoc/reference/data-access.adoc | 14 +- src/main/asciidoc/reference/data.adoc | 156 ++--- src/main/asciidoc/reference/diskstore.adoc | 8 +- .../reference/function-annotations.adoc | 126 ++-- src/main/asciidoc/reference/function.adoc | 12 +- src/main/asciidoc/reference/gateway.adoc | 10 +- .../asciidoc/reference/gemfire-bootstrap.adoc | 70 +-- src/main/asciidoc/reference/indexing.adoc | 88 +-- src/main/asciidoc/reference/introduction.adoc | 27 +- src/main/asciidoc/reference/lucene.adoc | 52 +- src/main/asciidoc/reference/mapping.adoc | 40 +- src/main/asciidoc/reference/region.adoc | 188 +++--- src/main/asciidoc/reference/repositories.adoc | 66 +- src/main/asciidoc/reference/samples.adoc | 20 +- .../asciidoc/reference/serialization.adoc | 26 +- src/main/asciidoc/reference/snapshot.adoc | 60 +- 28 files changed, 1002 insertions(+), 977 deletions(-) diff --git a/pom.xml b/pom.xml index e51269b1..e4ee6356 100644 --- a/pom.xml +++ b/pom.xml @@ -316,7 +316,6 @@ html5 ${project.root}/target/site/reference/html - false prettify true diff --git a/src/main/asciidoc/appendix/appendix-schema.adoc b/src/main/asciidoc/appendix/appendix-schema.adoc index 51495c2a..794d5d7e 100644 --- a/src/main/asciidoc/appendix/appendix-schema.adoc +++ b/src/main/asciidoc/appendix/appendix-schema.adoc @@ -1,6 +1,6 @@ [[appendix-schema]] [appendix] -= Spring Data for Pivotal GemFire Schema += Spring Data for {data-store-name} Schema -* 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 {data-store-name} Core Schema (`gfe` namespace)] +* http://www.springframework.org/schema/gemfire/spring-data-gemfire.xsd[Spring Data for {data-store-name} Data Access Schema (`gfe-data` namespace)] diff --git a/src/main/asciidoc/index.adoc b/src/main/asciidoc/index.adoc index 9f9f214b..7721c2da 100644 --- a/src/main/asciidoc/index.adoc +++ b/src/main/asciidoc/index.adoc @@ -1,7 +1,7 @@ -= Spring Data for Pivotal GemFire Reference Guide += Spring Data for {data-store-name} Reference Guide Costin Leau; David Turanski; John Blum; Oliver Gierke; Jay Bryant -:revnumber: {version} :revdate: {localdate} +:revnumber: {version} :linkcss: :doctype: book :docinfo: shared @@ -10,8 +10,30 @@ Costin Leau; David Turanski; John Blum; Oliver Gierke; Jay Bryant :source-highlighter: prettify :icons: font :imagesdir: images +:apache-geode-version: 16 +:apache-geode-docs: http://geode.apache.org/docs/guide/{apache-geode-version} +:apache-geode-javadoc: http://geode.apache.org/releases/latest/javadoc +:apache-geode-website: http://geode.apache.org +:apache-geode-wiki: https://cwiki.apache.org/confluence/display/GEODE +:data-store-name: Pivotal GemFire +:data-store-version: 9.5.1 +:pivotal-gemfire-version: 95 +:pivotal-gemfire-docs: http://gemfire.docs.pivotal.io/{pivotal-gemfire-version} +:pivotal-gemfire-javadoc: http://gemfire-{pivotal-gemfire-version}-javadocs.docs.pivotal.io/ +:pivotal-gemfire-website: https://pivotal.io/pivotal-gemfire +:sdg-name: Spring Data for {data-store-name} +:spring-data-commons-docs: https://docs.spring.io/spring-data/commons/docs/current/reference +:spring-data-commons-docs-html: {spring-data-commons-docs}/html +:spring-data-commons-javadoc: https://docs.spring.io/spring-data/commons/docs/current/api +:spring-data-website: https://spring.io/projects/spring-data +:spring-framework-docs: https://docs.spring.io/spring/docs/current/spring-framework-reference +:spring-framework-javadoc: https://docs.spring.io/spring/docs/current/javadoc-api +:spring-framework-website: https://spring.io/projects/spring-framework +:x-data-store-docs: {apache-geode-docs} +:x-data-store-javadoc: {pivotal-gemfire-javadoc} +:x-data-store-website: {pivotal-gemfire-website} +:x-data-store-wiki: {apache-geode-wiki} 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 (C) 2010-2018 The original authors. @@ -45,8 +67,8 @@ include::{basedocdir}/reference/samples.adoc[leveloffset=+1] = Resources In addition to this reference documentation, there are a number of other resources that may help you learn -how to use Pivotal GemFire with the _Spring Framework_. These additional, third-party resources are enumerated -in this section. +how to use {data-store-product-name} with the _Spring Framework_. These additional, third-party resources +are enumerated in this section. include::{basedocdir}/links.adoc[leveloffset=+1] diff --git a/src/main/asciidoc/introduction/introduction.adoc b/src/main/asciidoc/introduction/introduction.adoc index 6161b787..aedb7ce5 100644 --- a/src/main/asciidoc/introduction/introduction.adoc +++ b/src/main/asciidoc/introduction/introduction.adoc @@ -1,6 +1,6 @@ [[introduction]] = Introduction -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. +The Spring Data for {data-store-name} reference guide explains how to use the Spring Framework +to configure and develop applications with {data-store-name}. It presents the basic concepts +and provides numerous examples to help you get started quickly. diff --git a/src/main/asciidoc/introduction/new-features.adoc b/src/main/asciidoc/introduction/new-features.adoc index 1979c00b..a2848ff9 100644 --- a/src/main/asciidoc/introduction/new-features.adoc +++ b/src/main/asciidoc/introduction/new-features.adoc @@ -1,119 +1,119 @@ [[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 GemFire, has been renamed to +Spring Data for {data-store-name} to reflect that it is now a module of the http://projects.spring.io/spring-data/[Spring Data] project -and built on https://pivotal.io/pivotal-gemfire[Pivotal GemFire]. +and built on {x-data-store-website}[{data-store-name}]. [[new-in-1-2-0]] == New in the 1.2 Release -* 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 <>. +* Full support for {data-store-name} configuration through the SDG *gfe* namespace. Now {data-store-name} components may be configured completely without requiring a native cache.xml file. +* WAN Gateway support for {data-store-name} 6.6.x. See <>. * Spring Data Repository support using a dedicated SDG namespace, *gfe-data*. See <> -* Namespace support for registering Pivotal GemFire Functions. See <> +* Namespace support for registering {data-store-name} Functions. 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 by nested `<*-region>` elements. +* {data-store-name} 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. +* Support for the re-designed WAN Gateway in {data-store-name} 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 by using annotations. In addition, function executions are defined as +* Annotation support for {data-store-name} Functions. It is now possible to declare and register Functions written as POJOs by using annotations. In addition, function executions are defined as annotated interfaces, similar to the way Spring Data Repositories work. See <>. -* 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 simplify establishing a basic <> to a {data-store-name} 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. +in {data-store-name} 7.0, enabling Spring AOP to perform the necessary conversions automatically on Region operations. +* Upgraded to {data-store-name} 7.0.1 and added namespace support for new AsyncEventQueue attributes. * Added 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 <>. -* 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 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 entry time-to-live and entry idle-time on a {data-store-name} Client Cache. See <>. +* Support for multiple Spring Data for {data-store-name} web-based applications by using a single {data-store-name} cluster, operating concurrently inside tc Server. +* Support for `concurrency-checks-enabled` on all {data-store-name} Cache Region definitions by using the SDG `gfe` namespace. See <>. * 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 registering CacheListeners, AsyncEventQueues, and Gateway Senders on {data-store-name} Cache Sub-Regions. +* Support for PDX persistent keys in {data-store-name} Regions. * Support for correct Partition Region bean creation in a Spring context when collocation is specified with the `colocated-with` attribute. -* Full support for 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. +* Full support for {data-store-name} Cache Sub-Regions using proper, nested `<*-region>` element syntax in the SDG `gfe` namespace. +* Upgraded Spring Data for {data-store-name} to Spring Framework 3.2.8. +* Upgraded Spring Data for {data-store-name} to Spring Data Commons 1.7.1. [[new-in-1-4-0]] == New in the 1.4 Release -* Upgraded to Pivotal GemFire 7.0.2. +* Upgraded to {data-store-name} 7.0.2. * Upgraded to Spring Data Commons 1.8.x.RELEASE. * Upgraded to Spring Framework 3.2.x.RELEASE. -* Integrated Spring Data for 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 +* Integrated Spring Data for {data-store-name} with Spring Boot, which includes both a `spring-boot-starter-data-gemfire` POM +and a Spring Boot sample application that demonstrates {data-store-name} Cache Transactions configured with SDG and bootstrapped with Spring Boot. -* Added support for bootstrapping a Spring `ApplicationContext` in a Pivotal GemFire Server when started from `Gfsh`. +* Added support for bootstrapping a Spring `ApplicationContext` in a {data-store-name} Server when started from `Gfsh`. See <> for more details. -* Added support for persisting application domain object and entities to multiple Pivotal GemFire Cache Regions. +* Added support for persisting application domain object and entities to multiple {data-store-name} Cache Regions. See <> for more details. -* Added support for persisting application domain object and entities to Pivotal GemFire Cache Sub-Regions, avoiding collisions +* Added support for persisting application domain object and entities to {data-store-name} Cache Sub-Regions, avoiding collisions when Sub-Regions are uniquely identifiable but identically named. See <> for more details. * Added strict XSD type rules to and full support for Data Policies and Region Shortcuts -on all Pivotal GemFire Cache Region types. +on all {data-store-name} Cache Region types. * Changed the default behavior of SDG `<*-region>` elements from lookup to always create a new Region along with an option to restore the old behavior (by using the `ignore-if-exists` attribute). See <> and <> for more details. -* Spring Data for Pivotal GemFire can now be fully built and ran on JDK 7 and JDK 8. +* Spring Data for {data-store-name} can now be fully built and ran on JDK 7 and JDK 8. [[new-in-1-5-0]] == New in the 1.5 Release -* Maintained support for Pivotal GemFire 7.0.2. +* Maintained support for {data-store-name} 7.0.2. * Upgraded to _Spring Data Commons_ 1.9.x.RELEASE. * Upgraded to _Spring Framework_ 4.0.x.RELEASE. * Migrated the Reference Guide to Asciidoc. -* Renewed support for deploying Spring Data for 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. +* Renewed support for deploying Spring Data for {data-store-name} in an OSGi container. +* Removed all default values in the Spring Data for {data-store-name} XML namespace Region-type elements to +rely on {data-store-name} defaults instead. * Added convenience to automatically create Disk Store directory locations. * SDG annotated Function implementations can now be executed from `Gfsh`. -* Enabled Pivotal GemFire `GatewayReceivers` to be started manually. +* Enabled {data-store-name} `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 -* Upgraded to Pivotal GemFire 8.0.0. +* Upgraded to {data-store-name} 8.0.0. * Upgraded to Spring Data Commons 1.10.x.RELEASE. * Maintained support for Spring Framework 4.0.x.RELEASE. -* Added support for Pivotal GemFire 8's new Cluster-based Configuration. -* Enabled 'auto-reconnect' functionality to be employed in Spring-configured Pivotal GemFire Servers. +* Added support for {data-store-name} 8's new Cluster-based Configuration. +* Enabled 'auto-reconnect' functionality to be employed in Spring-configured {data-store-name} Servers. * Allowed the creation of concurrent and parallel Async Event Queues and Gateway Senders. -* Added support for Pivotal GemFire 8's Region data compression. +* Added support for {data-store-name} 8's Region data compression. * Added attributes to set both critical and warning percentages on Disk Store usage. * Supported the capability to add the new EventSubstitutionFilters to GatewaySenders. [[new-in-1-7-0]] == New in the 1.7 Release -* Upgraded to Pivotal GemFire 8.1.0. +* Upgraded to {data-store-name} 8.1.0. * Upgraded to Spring Data Commons 1.11.x.RELEASE. * Upgraded to Spring Framework 4.1.x.RELEASE. -* Added early access support for 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 early access support for {data-store-name}. +* Added support for adding Spring-defined Cache Listeners, Loaders, and Writers on "existing" {data-store-name} Regions +configured in Spring XML, `cache.xml`, or even with {data-store-name}'s Cluster Config. * 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. +* Enables the use of the `` element with non-Spring-configured {data-store-name} Servers. * Added multi-index definition and creation support. * <> * <> @@ -122,7 +122,7 @@ endpoint lists configured with Spring's property placeholders. [[new-in-1-8-0]] == New in the 1.8 Release -* Upgraded to Pivotal GemFire 8.2.0. +* Upgraded to {data-store-name} 8.2.0. * Upgraded to Spring Data Commons 1.12.x.RELEASE. * Upgraded to Spring Framework 4.2.x.RELEASE. * Added Maven POM to build SDG with Maven. @@ -132,32 +132,32 @@ endpoint lists configured with Spring's property placeholders. * 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. +* Handled case-insensitive {data-store-name} OQL queries defined as Repository query methods. +* Changed `GemFireCache.evict(key)` to call `Region.remove(key)` in SDG's Spring Cache Abstraction support. * Fixed `RegionNotFoundException` with Repository queries on a client `Region` associated with a specific `Pool` -configured for Pivotal GemFire server groups. -* Changed `Gateway Senders/Receivers` to no longer be tied to the _Spring_ container. +configured for {data-store-name} server groups. +* Changed `Gateway Senders/Receivers` to no longer be tied to the Spring container. [[new-in-1-9-0]] == New in the 1.9 Release -* Upgraded to Pivotal GemFire 8.2.4. +* Upgraded to {data-store-name} 8.2.4. * Upgraded to Spring Data Commons 1.13.x.RELEASE. * Upgraded to Spring Framework 4.3.x.RELEASE. * Introduced an entirely new Annotation-based configuration model inspired by Spring Boot. * Added support for suspend and resume in the `GemfireTransactionManager`. * Added support in Repositories to use the bean `id` property as the Region key when the `@Id` annotation is not present. -* Used `MappingPdxSerializer` as the default Pivotal GemFire serialization strategy when `@EnablePdx` is used. +* Used `MappingPdxSerializer` as the default {data-store-name} serialization strategy when `@EnablePdx` is used. * Enabled `GemfireCacheManager` to explicitly list Region names to be used in the Spring's Caching Abstraction. -* Configured Pivotal GemFire Caches, CacheServers, Locators, Pools, Regions, Indexes, DiskStores, Expiration, Eviction, +* Configured {data-store-name} Caches, CacheServers, Locators, Pools, Regions, Indexes, DiskStores, Expiration, Eviction, Statistics, Mcast, HttpService, Auth, SSL, Logging, System Properties. * Added repository support with multiple Spring Data modules on the classpath. [[new-in-2-0-0]] == New in the 2.0 Release -* Upgraded to Pivotal GemFire 9.0.x. +* Upgraded to {data-store-name} 9.0.x. * Upgraded to Spring Data Commons 2.0.x.RELEASE. * Upgraded to Spring Framework 5.0.x.RELEASE. * Reorganized the SDG codebase by better packaging different classes and components by concern. @@ -168,4 +168,4 @@ Statistics, Mcast, HttpService, Auth, SSL, Logging, System Properties. * Renamed `@EnableIndexes` to `@EnableIndexing`. * Introduced a `InterestsBuilder` class to easily and conveniently express Interests in keys and values between client and server when using JavaConfig. -* Added support for Off-Heap, Redis Adapter, and Pivotal GemFire's new Security framework to the Annotation configuration model. +* Added support for Off-Heap, Redis Adapter, and {data-store-name}'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 03a3aa08..5c01cdf6 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 -and http://geode.apache.org/[Pivotal GemFire] 9.0.x. +Spring Data for {data-store-name} requires Java 8.0, {spring-framework-website}[Spring Framework] 5 +and {x-data-store-website}[{data-store-name}] {data-store-version}. diff --git a/src/main/asciidoc/links.adoc b/src/main/asciidoc/links.adoc index 05663b2a..b846bcad 100644 --- a/src/main/asciidoc/links.adoc +++ b/src/main/asciidoc/links.adoc @@ -1,14 +1,14 @@ [[sgf-links]] = Useful Links -* http://projects.spring.io/spring-data-gemfire[Spring Data for Pivotal GemFire Project Page] -* https://github.com/spring-projects/spring-data-gemfire[Spring Data for Pivotal GemFire source code] -* https://jira.spring.io/browse/SGF[Spring Data for Pivotal GemFire JIRA] -* http://stackoverflow.com/questions/tagged/spring-data-gemfire[Spring Data for Pivotal GemFire on StackOverflow] -* http://forum.spring.io/forum/spring-projects/data/gemfire[Archive of the Spring Data for Pivotal GemFire Forum on Spring IO] -* https://pivotal.io/pivotal-gemfire[Pivotal GemFire Home Page] -* http://gemfire.docs.pivotal.io/latest/gemfire/about_gemfire.html[Pivotal GemFire Documentation] -* http://geode.apache.org/community/[Apache Geode Community] +* http://projects.spring.io/spring-data-gemfire[Spring Data for {data-store-name} Project Page] +* https://github.com/spring-projects/spring-data-gemfire[Spring Data for {data-store-name} source code] +* https://jira.spring.io/browse/SGF[Spring Data for {data-store-name} JIRA] +* http://stackoverflow.com/questions/tagged/spring-data-gemfire[Spring Data for {data-store-name} on StackOverflow] +* http://forum.spring.io/forum/spring-projects/data/gemfire[Archive of the Spring Data for {data-store-name} Forum on Spring IO] +* {x-data-store-website}[{data-store-name} Home Page] +* {x-data-store-docs}/getting_started/book_intro.html[{data-store-name} Documentation] +* {apache-geode-website}/community/[Apache Geode Community] * https://github.com/apache/geode[Apache Geode source code] -* https://issues.apache.org/jira/projects/GEODE/issues/GEODE-4748?filter=allopenissues[Apache Geode JIRA] -* http://stackoverflow.com/questions/tagged/gemfire[Pivotal GemFire on StackOverflow] +* https://issues.apache.org/jira/projects/GEODE/issues[Apache Geode JIRA] +* http://stackoverflow.com/questions/tagged/gemfire[{data-store-name} on StackOverflow] diff --git a/src/main/asciidoc/preface.adoc b/src/main/asciidoc/preface.adoc index ba9920ea..c805bc4d 100644 --- a/src/main/asciidoc/preface.adoc +++ b/src/main/asciidoc/preface.adoc @@ -1,10 +1,10 @@ = 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 when you use Pivotal GemFire. +Spring Data for {data-store-name} focuses on integrating the Spring Framework's powerful, non-invasive programming model +and concepts with {data-store-name} to simplify configuration and development of Java applications when you use {data-store-name}. This document assumes you already have a basic understanding of and some familiarity with the core Spring Framework -and Pivotal GemFire concepts and APIs. +and {data-store-name} 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 (for example, data distribution management diff --git a/src/main/asciidoc/reference/bootstrap-annotations.adoc b/src/main/asciidoc/reference/bootstrap-annotations.adoc index 39b108b1..6d050882 100644 --- a/src/main/asciidoc/reference/bootstrap-annotations.adoc +++ b/src/main/asciidoc/reference/bootstrap-annotations.adoc @@ -1,87 +1,83 @@ -The following example shows how to configure a region bean in Java: - [[bootstrap-annotation-config]] -= Bootstrapping Pivotal GemFire using Spring Annotations += Bootstrapping {data-store-name} using Spring Annotations -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. +Spring Data for {data-store-name} (SDG) 2.0 introduces a new annotation-based configuration model +to configure and bootstrap {data-store-name} 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 {data-store-name} +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 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: +{data-store-name} can be difficult to setup and use correctly, given all the +{x-data-store-docs}/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] +* {x-data-store-javadoc}[Java API] +* {x-data-store-docs}/reference/topics/chapter_overview_cache_xml.html[cache.xml] +* {x-data-store-docs}/tools_modules/gfsh/chapter_overview.html[_Gfsh_] +with {x-data-store-docs}/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] +* ({x-data-store-docs}/topologies_and_comm/cs_configuration/chapter_overview.html[client/server] +* {x-data-store-docs}/topologies_and_comm/p2p_configuration/chapter_overview.html[P2P] +* {x-data-store-docs}/topologies_and_comm/multi_site_configuration/chapter_overview.html[WAN]) +* {x-data-store-wiki}/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 +The Annotation-based configuration model is an alternative to XML-based configuration using Spring Data for {data-store-name}'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. +for {data-store-name}'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 +Like Spring Boot, Spring Data for {data-store-name}'s annotation-based configuration model was designed as an opinionated, +convention-over-configuration approach for using {data-store-name}. 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. 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. +provided in {data-store-name} for the same configuration property or setting. -The intention is to let you enable a Pivotal GemFire feature or an embedded service by +The intention is to let you enable a {data-store-name} 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. -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 +However, the option to customize the configuration metadata and behavior of {data-store-name} is there if you +need it, and Spring Data for {data-store-name}'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. +there are several ways to configure a {data-store-name} feature or embedded service by using annotations. 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 {data-store-name} Applications with Spring 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: +a Spring Boot application can easily become a {data-store-name} cache application by declaring any one of three main Annotations: * `@ClientCacheApplication` * `@PeerCacheApplication` * `@CacheServerApplication` -These three annotations are the Spring and Pivotal GemFire application developer's starting point. +These three annotations are the Spring and {data-store-name} application developer's starting point. 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. +that can be created with {data-store-name}: a client or a peer. -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 you +You can configure a Spring Boot application as aa {data-store-name} cache client (that is, with an instance of `ClientCache`), +which communicates with an existing, standalone cluster of {data-store-name} servers used to manage the application's data. +The client-server topology is the most typical system architecture employed when using {data-store-name} 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 +Alternatively, a Spring Boot application may be a peer member of an {data-store-name} 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`. @@ -90,16 +86,16 @@ and perform data access operations on the server. This is accomplished by annota `@CacheServerApplication` instead of `@PeerCacheApplication`, which creates a peer `Cache` instance along with the `CacheServer`. -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) +NOTE: A {data-store-name} 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 {data-store-name} 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] +{x-data-store-docs}/developing/region_options/data_hosts_and_accessors.html[data accessors] that can service clients as `CacheServers` as well, but doing so is beyond the scope of this document. -By way of example, if you want to create a Spring Boot Pivotal GemFire cache client application, you can start with the following: +By way of example, if you want to create a Spring Boot {data-store-name} cache client application, you can start with the following: -.Spring-based Pivotal GemFire `ClientCache` application +.Spring-based {data-store-name} `ClientCache` application [source, java] ---- @SpringBootApplication @@ -108,9 +104,9 @@ class ClientApplication { .. } ---- 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: +is a server and a peer member of a cluster or distributed system formed by {data-store-name}, you could start with the following: -.Spring-based Pivotal GemFire embedded peer `Cache` application +.Spring-based {data-store-name} embedded peer `Cache` application [source, java] ---- @SpringBootApplication @@ -122,7 +118,7 @@ Alternatively, you can use the `@CacheServerApplication` annotation instead of ` 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 +.Spring-based {data-store-name} embedded `CacheServer` Application [source, java] ---- @SpringBootApplication @@ -133,21 +129,21 @@ class ServerApplication { .. } [[bootstrap-annotation-config-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. +There are multiple ways that a client can connect to and communicate with servers in an {data-store-name} cluster. +The most common and recommended approach is to use {data-store-name} Locators. -NOTE: A cache client can connect to one or more locators in the Pivotal GemFire cluster instead of directly to a +NOTE: A cache client can connect to one or more locators in the {data-store-name} 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 +NOTE: Locators are also peer members in a cluster. Locators actually constitute what makes up a cluster of {data-store-name} 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. -Pivotal GemFire sets up a `DEFAULT` `Pool` connected to a `CacheServer` running on localhost, listening on port +{data-store-name} 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 @@ -155,12 +151,12 @@ Spring Boot application with `@ClientCacheApplication`, and you are ready to go. 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. +may prefer to configure and start your servers by using the Spring Data for {data-store-name} approach: with annotations. -As an application developer, you will no doubt want to customize the `DEFAULT` `Pool` set up by Pivotal GemFire +As an application developer, you will no doubt want to customize the `DEFAULT` `Pool` set up by {data-store-name} to possibly connect to one or more locators, as the following example shows: -.Spring-based Pivotal GemFire `ClientCache` application using Locators +.Spring-based {data-store-name} `ClientCache` application using Locators [source, java] ---- @SpringBootApplication @@ -175,9 +171,9 @@ Along with the `locators` attribute, the `@ClientCacheApplication` annotation ha 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 use either the `locators` or `servers` attribute, but not both (this is enforced by Pivotal GemFire). +NOTE: You can use either the `locators` or `servers` attribute, but not both (this is enforced by {data-store-name}). -You can also configure additional `Pool` instances (other than the `DEFAULT` `Pool` provided by Pivotal GemFire when +You can also configure additional `Pool` instances (other than the `DEFAULT` `Pool` provided by {data-store-name} when a `ClientCache` instance is created with the `@ClientCacheApplication` annotation) by using the `@EnablePool` and `@EnablePools` annotations. @@ -187,7 +183,7 @@ on a class. The following example uses the `@EnablePool` and `@EnablePools` annotations: -.Spring-based Pivotal GemFire `ClientCache` application using multiple named `Pools` +.Spring-based {data-store-name} `ClientCache` application using multiple named `Pools` [source, java] ---- @SpringBootApplication @@ -210,11 +206,11 @@ class ClientApplication { .. } 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. +in {data-store-name}. 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` +.Spring-based {data-store-name} `CacheServer` application using multiple named `CacheServers` [source, java] ---- @SpringBootApplication @@ -251,16 +247,16 @@ One of the finer features of Spring is the ability to use property placeholders 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 +So, Spring Data for {data-store-name} 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`]. +{spring-framework-javadoc}/org/springframework/web/servlet/config/annotation/ContentNegotiationConfigurer.html[`org.springframework.web.servlet.config.annotation.ContentNegotiationConfigurer`]. 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 +Spring Data for {data-store-name} 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` @@ -326,13 +322,13 @@ In addition, when the `Configurer` is declared as a bean in the Spring context, of other Spring container features, such as property placeholders, SpEL expressions that use the `@Value` annotation on factory method parameters, and so on. -All `Configurers` provided by Spring Data for Pivotal GemFire take two bits of information in the callback: the name of the bean created +All `Configurers` provided by Spring Data for {data-store-name} 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 +create and configure the {data-store-name} 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 you would use in Spring's -https://docs.spring.io/spring/docs/current/spring-framework-reference/core.html#beans-java[Java-based container configuration] +{spring-framework-docs}/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 same `FactoryBeans` for their configuration. So, in essence, the annotations are a facade and provide an extra layer of abstraction for convenience. @@ -484,20 +480,20 @@ TIP: Property placeholder nesting can be arbitrarily deep. [[bootstrap-annotation-config-embedded-services]] == Configuring Embedded Services -Pivotal GemFire provides the ability to start many different embedded services that are required by an application, depending on +{data-store-name} 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 -As mentioned previously, Pivotal GemFire locators are used by clients to connect with and find servers in a cluster +As mentioned previously, {data-store-name} 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 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 +It is often convenient for application developers as they are developing their Spring Boot and Spring Data for {data-store-name} +applications to startup up a small cluster of two or three {data-store-name} 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 +.Spring, {data-store-name} `CacheServer` application running an embedded Locator [source, java] ---- @SpringBootApplication @@ -506,7 +502,7 @@ process, you can annotate your Spring Boot `@CacheServerApplication` class with class ServerApplication { .. } ---- -The `@EnableLocator` annotation starts an embedded locator in the Spring Pivotal GemFire `CacheServer` application +The `@EnableLocator` annotation starts an embedded locator in the Spring {data-store-name} `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. @@ -517,7 +513,7 @@ and `spring.data.gemfire.locator.port` properties in `application.properties`. 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 +.Spring, {data-store-name} `CacheServer` application connecting to a Locator [source, java] ---- @SpringBootApplication @@ -560,19 +556,19 @@ 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 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. +of {data-store-name} 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. We strongly recommend that locators be standalone, independent processes in the cluster. -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]. +More details on how {data-store-name} locators work can be found +{x-data-store-docs}/topologies_and_comm/topology_concepts/how_member_discovery_works.html[here]. [[bootstrap-annotation-config-embedded-services-manager]] === Configuring an Embedded Manager -A Pivotal GemFire Manager is another peer member or node in the cluster that is responsible for "`management`" activities. +A {data-store-name} 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. @@ -583,7 +579,7 @@ both JMX-enabled clients as well. 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 of 1099. +By default, the manager binds to localhost, listening on the default {data-store-name} Manager port of 1099. Several aspects of the manager can be configured with annotation attributes or the corresponding properties. The following example shows how to create an embedded manager in Java: @@ -618,7 +614,7 @@ $ gfsh / /__/ / ____/ _____/ / / / / /______/_/ /______/_/ /_/ 1.2.1 -Monitor and Manage Pivotal GemFire +Monitor and Manage {data-store-name} gfsh>connect Connecting to Locator at [host=localhost, port=10334] .. @@ -648,20 +644,20 @@ NOTE: Like the `@EnableLocator` annotation, the `@EnableManager` annotation is a 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 -http://gemfire.docs.pivotal.io/gemfire/managing/book_intro.html[here]. +More details on {data-store-name} management and monitoring can be found +{x-data-store-docs}/managing/book_intro.html[here]. [[bootstrap-annotation-config-embedded-services-http]] === Configuring the Embedded HTTP Server -Pivotal GemFire is also capable of running an embedded HTTP server. The current implementation is backed by +{data-store-name} 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], -and the http://gemfire.docs.pivotal.io/geode/tools_modules/pulse/pulse-overview.html[Pulse Monitoring Web Application]. +The embedded HTTP server is used to host {data-store-name}'s management (admin) REST API (not a publicly advertised API), +the {x-data-store-docs}/rest_apps/book_intro.html[Developer REST API], +and the {x-data-store-docs}/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 {data-store-name}-provided web applications, you must have a full installation of {data-store-name} installed on your system, and you must set the `GEODE_HOME` environment variable to your installation directory. To enable the embedded HTTP server, add the `@EnableHttpService` annotation to any `@PeerCacheApplication` @@ -684,8 +680,8 @@ Follow the earlier links for more details on HTTP support and the services provi [[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 +{data-store-name} also implements the memcached protocol with the ability to service memcached clients. That is, memcached +clients can connect to an {data-store-name} cluster and perform memcached operations as if the {data-store-name} servers in the cluster were actual memcached servers. To enable the embedded memcached service, add the `@EnableMemcachedServer` annotation to any @@ -700,15 +696,15 @@ To enable the embedded memcached service, add the `@EnableMemcachedServer` annot public class ServerApplication { .. } ---- -More details on Pivotal GemFire's Gemcached service can be found -http://gemfire.docs.pivotal.io/geode/tools_modules/gemcached/chapter_overview.html[here]. +More details on {data-store-name}'s Gemcached service can be found +{x-data-store-docs}/tools_modules/gemcached/chapter_overview.html[here]. [[bootstrap-annotation-config-embedded-services-redis]] === 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 -in Pivotal GemFire is still experimental. +{data-store-name} also implements the Redis server protocol, which enables Redis clients to connect to and communicate with +a cluster of {data-store-name} Servers to issue Redis commands. As of this writing, the Redis server protocol support +in {data-store-name} is still experimental. To enable the embedded Redis service, add the `@EnableRedisServer` annotation to any `@PeerCacheApplication` or `@CacheServerApplication` annotated class, as follows: @@ -722,13 +718,13 @@ or `@CacheServerApplication` annotated class, as follows: public class ServerApplication { .. } ---- -More details on Pivotal GemFire's Redis adapter can be found -http://gemfire.docs.pivotal.io/geode/tools_modules/redis_adapter.html[here]. +More details on {data-store-name}'s Redis adapter can be found +{x-data-store-docs}/tools_modules/redis_adapter.html[here]. [[bootstrap-annotation-config-logging]] == Configuring Logging -Oftentimes, 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 {data-store-name} is doing and when. To enable Logging, annotate your application class with `@EnableLogging` and set the appropriate attributes or associated properties, as follows: @@ -754,12 +750,12 @@ See the https://docs.spring.io/spring-data/gemfire/docs/current/api/org/springfr [[bootstrap-annotation-config-statistics]] == Configuring Statistics -To gain even deeper insight into Pivotal GemFire at runtime, you can enable statistics. +To gain even deeper insight into {data-store-name} 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, you 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 {data-store-name}'s +{x-data-store-docs}/tools_modules/vsd/chapter_overview.html[VSD (Visual Statistics Display)] tool to analyze the statistical data that is collected. To enable statistics, annotate your application class with `@EnableStatistics`, as follows: @@ -781,14 +777,14 @@ and collection process. 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 -http://gemfire.docs.pivotal.io/gemfire/managing/statistics/chapter_overview.html[here]. +More details on {data-store-name}'s statistics can be found +{x-data-store-docs}/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]. +One of the more powerful features of {data-store-name} is +{x-data-store-docs}/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: @@ -800,7 +796,7 @@ and without data loss. * 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 any time data is transferred to or from clients and servers or between +In general, serialization in {data-store-name} 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. @@ -819,16 +815,16 @@ public class ClientApplication { .. } ---- 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`] +{x-data-store-javadoc}/org/apache/geode/pdx/PdxSerializable.html[`org.apache.geode.pdx.PdxSerializable`] 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`] +{x-data-store-javadoc}/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 lets one `PdxSerializer` be registered, which suggests that all application +Unfortunately, {data-store-name} 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 {data-store-name}, 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], you @@ -837,7 +833,7 @@ domain object type-specific `PdxSerializer` instances but acts as a single `PdxS 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 Data for {data-store-name} takes care of registering it with {data-store-name} 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` [source, java] @@ -854,9 +850,9 @@ 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 +It is also possible to declare {data-store-name}'s +{x-data-store-javadoc}/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 {data-store-name}'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 metadata and infrastructure applied to the serialization process for more efficient handling than reflection alone. @@ -886,13 +882,13 @@ public class ClientApplication { .. } Then you need to set the necessary SSL configuration attributes or properties (keystores, usernames/passwords, and so on). -You can individually configure different Pivotal GemFire components (`GATEWAY`, `HTTP`, `JMX`, `LOCATOR`, and `SERVER`) +You can individually configure different {data-store-name} 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 +You can specify which {data-store-name} 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 +.Spring `ClientCache` application with SSL enabled by Aache {data-store-name} component [source, java] ---- @SpringBootApplication @@ -906,65 +902,65 @@ by using the corresponding annotation attribute or associated configuration prop 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]. +More details on {data-store-name} SSL support can be found +{x-data-store-docs}/managing/security/ssl_overview.html[here]. [[bootstrap-annotation-config-gemfire-properties]] -== Configuring Pivotal GemFire Properties +== Configuring {data-store-name} Properties -While many of the http://gemfire.docs.pivotal.io/geode/reference/topics/gemfire_properties.html[gemfire.properties] +While many of the {x-data-store-docs}/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. +the less commonly used {data-store-name} properties are still accessible from the `@EnableGemFireProperties` 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 +Using the `@EnableGemFireProperties` annotation on your application class is convenient and a nice alternative to +creating a `gemfire.properties` file or setting {data-store-name} properties as Java system properties on the command line when launching your application. -TIP: We recommend that these Pivotal GemFire properties be set in a `gemfire.properties` file when deploying +TIP: We recommend that these {data-store-name} 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 you usually need not worry about include, +A few examples of some of the less common {data-store-name} 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, 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: +To individually set any {data-store-name} property, annotate your application class with `@EnableGemFireProperties` +and set the {data-store-name} properties you want to change from the default value set by {data-store-name}, as follows: -.Spring `ClientCache` application with specific _Pivotal GemFire Properties_ set +.Spring `ClientCache` application with specific _{data-store-name} Properties_ set [source, java] ---- @SpringBootApplication @ClientCacheApplication -@EnablePivotal GemFireProperties(conflateEvents = true, socketBufferSize = 16384) +@EnableGemFireProperties(conflateEvents = true, socketBufferSize = 16384) public class ClientApplication { .. } ---- -Keep in mind that some of the Pivotal GemFire properties are client-specific (for example, `conflateEvents`), while others are +Keep in mind that some of the {data-store-name} 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]. +More details on {data-store-name} properties can be found +{x-data-store-docs}/reference/topics/gemfire_properties.html[here]. [[bootstrap-annotation-config-regions]] == Configuring Regions -So far, outside of PDX, our discussion has centered around configuring Pivotal GemFire's more administrative functions: +So far, outside of PDX, our discussion has centered around configuring {data-store-name}'s more administrative functions: 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 +{data-store-name} organizes data in a cache into +{x-data-store-docs}/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 +Previously, Spring Data for {data-store-name} 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] or using <>. +{spring-framework-docs}/core.html#beans-java[Java-based container configuration] or using <>. The following example shows how to configure a region bean in Java: @@ -972,10 +968,10 @@ The following example shows how to configure a region bean in Java: [source, java] ---- @Configuration -class Pivotal GemFireConfiguration { +class GemFireConfiguration { @Bean("Example") - PartitionedRegionFactoryBean exampleRegion(Pivotal GemFireCache gemfireCache) { + PartitionedRegionFactoryBean exampleRegion(GemFireCache gemfireCache) { PartitionedRegionFactoryBean exampleRegion = new PartitionedRegionFactoryBean<>(); @@ -1009,13 +1005,13 @@ Now you can define and configure regions based on their application domain objec you need to explicitly define `region` bean definitions in Spring configuration metadata, unless you require finer-grained control. -To simplify region creation, Spring Data for Pivotal GemFire combines the use of Spring Data Repositories with the expressive +To simplify region creation, Spring Data for {data-store-name} 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, -which has been specifically customized to optimize data access operations for Pivotal GemFire. +{spring-data-commons-docs-html}/#repositories[Spring Data Repository abstraction] +and Spring Data for {data-store-name}'s <> of Spring Data's_ _Repository abstraction, +which has been specifically customized to optimize data access operations for {data-store-name}. First, an application developer starts by defining the application domain objects, as follows: @@ -1055,16 +1051,16 @@ operations (CRUD) along with support for simple queries (such as `findById(..)`) 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 +Under the hood, Spring Data for {data-store-name} 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 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 +and stored by declaring the Spring Data for {data-store-name} 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, which contains mapping metadata for all the entities defined in your +Spring Data for {data-store-name} 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, annotate the application class with `@EnableEntityDefinedRegions`, as follows: @@ -1080,7 +1076,7 @@ class ClientApplication { .. } ---- 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 +Spring Data for {data-store-name}'s repository support is enabled with the `@EnableGemfireRepositories` annotation, as shown in the preceding example. By default, the `@EnableEntityDefinedRegions` annotation scans for entity classes recursively, starting from @@ -1115,18 +1111,18 @@ See the https://docs.spring.io/spring-data/gemfire/docs/current/api/org/springfr [[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]. +{data-store-name} supports many different +{x-data-store-docs}/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`], +{x-data-store-javadoc}/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 (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. +See {x-data-store-docs}/developing/region_options/storage_distribution_options.html["`Storage and Distribution Options`"] +in the {data-store-name} User Guide for more details. 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 +Spring Data for {data-store-name} 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 you declare the application as a `ClientCache` by using the `@ClientCacheApplication` annotation, @@ -1134,7 +1130,7 @@ SDG creates a client `PROXY` `Region`. Alternatively, if you declare the applica `@PeerCacheApplication` or `@CacheServerApplication` annotations, SDG creates a server `PARTITION` `Region`. 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: +applied by Spring Data for {data-store-name}, four new region mapping annotations have been introduced: * `@ClientRegion` * `@LocalRegion` @@ -1168,17 +1164,17 @@ All `Region` type-specific annotations provide additional attributes that are bo 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 -http://gemfire.docs.pivotal.io/geode/developing/region_options/region_types.html[here]. +More details on {data-store-name} region types can be found +{x-data-store-docs}/developing/region_options/region_types.html[here]. [[bootstrap-annotation-config-region-eviction]] === Configuring Eviction -Managing data with Pivotal GemFire is an active task. Tuning is generally required, and you must employ a combination +Managing data with {data-store-name} 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. +to effectively manage your data in memory with {data-store-name}. -Given that Pivotal GemFire is an In-Memory Data Grid (IMDG), data is managed in-memory and distributed to other nodes +Given that {data-store-name} 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), you can increase capacity by adding new nodes to the cluster. This is commonly referred to @@ -1189,8 +1185,8 @@ Still, even with a cluster of nodes, it is usually imperative that only the most 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 Least Recently Used (LRU) eviction. -That is, Pivotal GemFire evicts region entries based on when those entries were last accessed by using +So, to help manage memory and keep the most important data around, {data-store-name} supports Least Recently Used (LRU) eviction. +That is, {data-store-name} evicts region entries based on when those entries were last accessed by using the Least Recently Used algorithm. To enable eviction, annotate the application class with `@EnableEviction`, as follows: @@ -1214,8 +1210,8 @@ Eviction policies are usually set on the regions in the servers. 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, +Additionally, a user can reference a custom implementation of {data-store-name}'s +{x-data-store-javadoc}/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 by using the `objectSizerName` attribute. An `ObjectSizer` let you define the criteria used to evaluate and determine the the size of objects @@ -1223,26 +1219,26 @@ stored in a region. 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]. +More details on {data-store-name} Eviction can be found +{x-data-store-docs}/developing/eviction/chapter_overview.html[here]. [[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. Pivotal GemFire supports both Time-to-Live (TTL)-based and Idle-Timeout (TTI)-based entry +by allowing entries stored in a region to expire. {data-store-name} 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 the +Spring Data for {data-store-name}'s annotation-based expiration configuration is based on the <> added in -Spring Data for Pivotal GemFire version 1.5. +Spring Data for {data-store-name} version 1.5. -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. +Essentially, Spring Data for {data-store-name}'s expiration annotation support is based on a custom implementation of +{data-store-name}'s {x-data-store-javadoc}/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. -Spring Data for Pivotal GemFire provides the following expiration annotations used on application domain object types: +Spring Data for {data-store-name} provides the following expiration annotations used on application domain object types: * `Expiration` * `IdleTimeoutExpiration` @@ -1291,8 +1287,8 @@ 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]. +More details on {data-store-name} Expiration can be found +{x-data-store-docs}/developing/expiration/chapter_overview.html[here]. [[bootstrap-annotation-config-region-compression]] === Configuring Compression @@ -1301,9 +1297,9 @@ In addition to <> and <>, you can also configure your data regions to use compression to reduce memory consumption. -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.Pivotal GemFire uses Google's http://google.github.io/snappy/[Snappy] +{data-store-name} lets you compress in-memory region values by using pluggable +{x-data-store-javadoc}/org/apache/geode/compression/Compressor.html[`Compressors`], +or different compression codecs.{data-store-name} uses Google's http://google.github.io/snappy/[Snappy] compression library. To enable compression support, annotate the application class with `@EnableCompression`, as follows: @@ -1319,8 +1315,8 @@ class ClientApplication { .. } NOTE: Neither the `compressorBeanName` nor the `regionNames` attribute are required. -The `compressorBeanName` defaults to `SnappyCompressor`, enabling Pivotal GemFire's -http://gemfire-91-javadocs.docs.pivotal.io/org/apache/geode/compression/SnappyCompressor.html[`SnappyCompressor`]. +The `compressorBeanName` defaults to `SnappyCompressor`, enabling {data-store-name}'s +{x-data-store-javadoc}/org/apache/geode/compression/SnappyCompressor.html[`SnappyCompressor`]. 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. @@ -1329,29 +1325,29 @@ TIP: Alternatively, you can use the `spring.data.gemfire.cache.compression.compr 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 +WARNING: To use {data-store-name}'s Region Compression feature, you must include the `org.iq80.snappy:snappy` dependency 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`] +if you use {data-store-name}'s default support for region compression, which uses the +{x-data-store-javadoc}/org/apache/geode/compression/SnappyCompressor.html[`SnappyCompressor`] 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 set +for that compression library on your application's classpath. Additionally, you need to implement {data-store-name}'s +{x-data-store-javadoc}/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 set the `compressorBeanName` to this custom bean definition. 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 +More details on {data-store-name} Compression can be found http://gemfire91.docs.pivotal.io/geode/managing/region_compression.html[here]. [[bootstrap-annotation-config-region-off-heap]] === Configuring Off-Heap Memory 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 +{data-store-name}'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]. +are mostly less than 128K, and do not need to be deserialized frequently, as explained in the {data-store-name} +{x-data-store-docs}/managing/heap_use/off_heap_management.html[User Guide]. To enable off-heap support, annotate the application class with `@EnableOffHeap`, as follows: @@ -1382,26 +1378,26 @@ See the https://docs.spring.io/spring-data/gemfire/docs/current/api/org/springfr 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 is known in advance, -data is commonly retrieved by executing queries on the regions that contain the data. With Pivotal GemFire, queries are +data is commonly retrieved by executing queries on the regions that contain the data. With {data-store-name}, 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 inefficient. When executing queries without an index, Pivotal GemFire +Generally, querying without indexes is inefficient. When executing queries without an index, {data-store-name} 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 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. +{x-data-store-docs}/developing/query_index/creating_key_indexes.html[key] +and {x-data-store-docs}/developing/query_index/creating_hash_indexes.html[hash] indexes, can be created. -Spring Data for Pivotal GemFire makes it easy to create indexes on regions where the data is stored and accessed. +Spring Data for {data-store-name} 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] ---- @Bean("BooksIsbnIndex") -IndexFactoryBean bookIsbnIndex(Pivotal GemFireCache gemfireCache) { +IndexFactoryBean bookIsbnIndex(GemFireCache gemfireCache) { IndexFactoryBean bookIsbnIndex = new IndexFactoryBean(); @@ -1456,13 +1452,13 @@ 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, +which identifies the field containing the unique identifier for `Book` instances, and, in Spring Data for {data-store-name}, the `@Id` annotated field or property is used as the key in the region when storing the entry. -* `@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. +* `@Id` annotated fields or properties result in the creation of an {data-store-name} `KEY` Index. +* `@Indexed` annotated fields or properties result in the creation of an {data-store-name} `HASH` Index (the default). +* `@LuceneIndexed` annotated fields or properties result in the creation of an {data-store-name} Lucene Index, used in +text-based searches with {data-store-name}'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 or property of the class on which the `@Indexed` annotation has been added. The `expression` @@ -1470,7 +1466,7 @@ is exactly the name of the field or property. The `fromClause` is derived from t the domain object's class (or the simple name of the domain object class if the `@Region` annotation was not specified). Of course, you can explicitly set any of the `@Indexed` annotation attributes to override the default values -provided by Spring Data for Pivotal GemFire. +provided by Spring Data for {data-store-name}. .Application domain object type modeling a book by using customized indexes [source, java] @@ -1520,56 +1516,56 @@ Essentially, indexes are defined from fields or properties on the entity class t 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 (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 +While Lucene queries are not (yet) supported on Spring Data for {data-store-name} repositories, SDG does provide comprehensive +https://docs.spring.io/spring-data-gemfire/docs/current/reference/html/#bootstrap:lucene[support] for {data-store-name} Lucene queries by using the familiar Spring template design pattern. Finally, we close this section with a few extra tips to keep in mind when using indexes: * While OQL indexes are not required to execute OQL Queries, Lucene Indexes are required to execute Lucene text-based searches. -* 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 {data-store-name} node is restarted, the Index must be rebuilt. * 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] +{x-data-store-javadoc}/org/apache/geode/cache/RegionFactory.html#setIndexMaintenanceSynchronous-boolean-[configured] as an asynchronous task. 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 +is to first define all the indexes up front and then create them all at once, which, in Spring Data for {data-store-name}, happens when the Spring context is refreshed. 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`"] -in Pivotal GemFire's User Guide for more details. +See {x-data-store-docs}/developing/query_index/create_multiple_indexes.html["`Creating Multiple Indexes at Once`"] +in {data-store-name}'s User Guide for more details. 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 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 -http://gemfire.docs.pivotal.io/geode/developing/querying_basics/chapter_overview.html[here]. +More details on {data-store-name} OQL queries can be found +{x-data-store-docs}/developing/querying_basics/chapter_overview.html[here]. -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 {data-store-name} indexes can be found +{x-data-store-docs}/developing/query_index/query_index.html[here]. -More details on Pivotal GemFire Lucene queries can be found -http://gemfire.docs.pivotal.io/geode/tools_modules/lucene_integration.html[here]. +More details on {data-store-name} Lucene queries can be found +{x-data-store-docs}/tools_modules/lucene_integration.html[here]. [[bootstrap-annotation-config-region-continuous-queries]] === Configuring Disk Stores 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 +explicit `DiskStore` has not been set on a region with persistence or overflow configured, {data-store-name} uses the `DEFAULT` `DiskStore`. 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 {data-store-name} 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 one or more `@EnableDiskStore` annotations. @@ -1593,7 +1589,7 @@ class ServerApplication { .. } Again, more than one `DiskStore` can be defined by using the composite, `@EnableDiskStores` annotation. -As other Annotations in Spring Data for Pivotal GemFire's annotation-based configuration model, both `@EnableDiskStore` +As other Annotations in Spring Data for {data-store-name}'s annotation-based configuration model, both `@EnableDiskStore` and `@EnableDiskStores` have many attributes along with associated configuration properties to customize the `DiskStores` created at runtime. @@ -1603,7 +1599,7 @@ Individual `DiskStore` configuration override a particular global setting, but t 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 configuration +Spring Data for {data-store-name} 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 @@ -1632,14 +1628,14 @@ class ServerApplication { 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 -http://gemfire.docs.pivotal.io/geode/developing/storing_data_on_disk/chapter_overview.html[here]. +More details on {data-store-name} Region Persistence and Overflow (using disk stores) can be found +{x-data-store-docs}/developing/storing_data_on_disk/chapter_overview.html[here]. [[bootstrap-annotation-config-continuous-queries]] == Configuring Continuous Queries -Another very important and useful feature of Pivotal GemFire is -http://gemfire.docs.pivotal.io/geode/developing/continuous_querying/chapter_overview.html[Continuous Querying]. +Another very important and useful feature of {data-store-name} is +{x-data-store-docs}/developing/continuous_querying/chapter_overview.html[Continuous Querying]. 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 @@ -1647,14 +1643,14 @@ important requirement for many applications. One example is self-driving vehicle 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. By using Continuous Queries (CQ), a client application +Fortunately, {data-store-name} 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 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 +Spring Data for {data-store-name} makes it easy to define and register CQs, along with an associated listener to handle and process CQ +events without all the cruft of {data-store-name}'s plumbing. SDG's new annotation-based configuration for CQs builds on the existing continuous query support in the <>. @@ -1700,23 +1696,23 @@ Additionally, the POJO method signature should adhere to the requirements outlin 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 {data-store-name}'s continuous query support 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]. +More details on {data-store-name}'s continuous queries can be found +{x-data-store-docs}/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 {data-store-name}, {data-store-name} can be used as a caching provider in Spring's +{spring-framework-docs}/integration.html#cache[cache abstraction]. 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 +In Spring Data for {data-store-name}, 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. @@ -1742,19 +1738,19 @@ class PointOfSaleService } ---- -To make your work easier when you use Spring Data for Pivotal GemFire and Pivotal GemFire with +To make your work easier when you use Spring Data for {data-store-name} and {data-store-name} with Spring's cache abstraction, two new features have been added to the ne annotation-based configuration model. Consider the following Spring caching configuration: -.Enabling Caching using Pivotal GemFire with Spring Data for Pivotal GemFire +.Enabling Caching using {data-store-name} with Spring Data for {data-store-name} [source, java] ---- @EnableCaching class CachingConfiguration { @Bean - GemfireCacheManager cacheManager(Pivotal GemFireCache gemfireCache) { + GemfireCacheManager cacheManager(GemFireCache gemfireCache) { GemfireCacheManager cacheManager = new GemfireCacheManager(); @@ -1764,7 +1760,7 @@ class CachingConfiguration { } @Bean("BookPricesCache") - ReplicatedRegionFactoryBean bookPricesRegion(Pivotal GemFireCache gemfireCache) { + ReplicatedRegionFactoryBean bookPricesRegion(GemFireCache gemfireCache) { ReplicatedRegionFactoryBean bookPricesRegion = new ReplicatedRegionFactoryBean<>(); @@ -1783,9 +1779,9 @@ class CachingConfiguration { } ---- -Using Spring Data for Pivotal GemFire's new features, you can simplify the same caching configuration to the following: +Using Spring Data for {data-store-name}'s new features, you can simplify the same caching configuration to the following: -.Enabling Pivotal GemFire Caching +.Enabling {data-store-name} Caching [source, java] ---- @EnableGemfireCaching @@ -1805,7 +1801,7 @@ the need to declare an explicit `cacheManager` bean definition in the Spring con Second, the `@EnableCachingDefinedRegions` annotation, like the `@EnableEntityDefinedRegions` annotation described in "`<>`", 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. +in {data-store-name} for these caches on application startup. 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 @@ -1815,30 +1811,30 @@ NOTE: SDG cannot determine the cache required by a service method using a Spring used in the operation at runtime. 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_] +See the core {spring-framework-docs}/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. +using {data-store-name} as a caching provider in Spring's Cache abstraction. More details on Spring's Cache Abstraction can be found -https://docs.spring.io/spring/docs/current/spring-framework-reference/integration.html#cache[here]. +{spring-framework-docs}/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 {data-store-name}. 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 +which the client is connected. Not only that, but this "`push`" is performed in such a way that {data-store-name} 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 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 +on all the servers in the cluster. Except that now, with Spring Data for {data-store-name}, 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 +Spring Data for {data-store-name}, already contains all the configuration metadata needed to create regions and indexes for the user. When you use the Spring Data repository abstraction, we know all the Regions (such as those defined by the `@Region`annotated @@ -1851,17 +1847,17 @@ or otherwise, and whether for configuration, for mapping, or whatever purpose. 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 +and so on) and Spring Data for {data-store-name} takes care of all the {data-store-name} 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 +in part by the use of {data-store-name}'s {x-data-store-docs}/configuring/cluster_config/gfsh_persist.html[Cluster Configuration] +service. {data-store-name}'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 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. +Spring Data for {data-store-name} 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 re-create a region @@ -1869,7 +1865,7 @@ or index, you must use Gfsh to first destroy the region or index and then restar 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 supports the creation of regions and indexes only on the servers from a client. +NOTE: Unlike Gfsh, Spring Data for {data-store-name} 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. Consider the power expressed in the following configuration: @@ -1888,8 +1884,8 @@ Consider the power expressed in the following configuration: class ClientApplication { .. } ---- -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 +You instantly get a Spring Boot application that uses {data-store-name} `ClientCache`, +Spring Data repositories, Spring's cache abstraction, and {data-store-name} as the caching provider (where regions and indexes are not only created on the client but pushed to the servers in the cluster). From there, you need to do the following: @@ -1900,10 +1896,10 @@ From there, you need to do the following: * 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. +and plumbing required in the application's back-end services (such as {data-store-name}). Database users have similar +features. Now Spring and {data-store-name} developers can, too. -When combined with the following Spring Data for Pivotal GemFire annotations, this application really starts to take flight, with minimal effort: +When combined with the following Spring Data for {data-store-name} annotations, this application really starts to take flight, with minimal effort: * `@EnableContinuousQueries` * `@EnableGemfireFunctionExecutions` @@ -1914,33 +1910,33 @@ See the https://docs.spring.io/spring-data/gemfire/docs/current/api/index.html?o [[bootstrap-annotation-config-security]] == Configuring Security -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. +Without a doubt, application Security is extremely important, and Spring Data for {data-store-name} provides comprehensive support +for securing both {data-store-name} clients and servers. -Recently, Pivotal GemFire introduced a new http://gemfire.docs.pivotal.io/geode/managing/security/implementing_security.html[Integrated Security] framework +Recently, {data-store-name} introduced a new {x-data-store-docs}/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 remainder of this section 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 {data-store-name} can simplify {data-store-name}'s Security story even further. [[bootstrap-annotation-config-security-server]] === Configuring Server Security -There are several different ways in which you 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 {data-store-name} cluster. -* Implement the Pivotal GemFire `org.apache.geode.security.SecurityManager` interface and set Pivotal GemFire's +* Implement the {data-store-name} `org.apache.geode.security.SecurityManager` interface and set {data-store-name}'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 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`. +with the {x-data-store-javadoc}/org/apache/geode/cache/CacheFactory.html#setSecurityManager-org.apache.geode.security.SecurityManager[CacheFactory.setSecurityManager(:SecurityManager)] +method when creating a {data-store-name} peer `Cache`. * 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 +and permissions defined for your application and then set the {data-store-name} `security-shiro-init` property to refer to this `shiro.ini` file, which must be available in the `CLASSPATH`. -* Using only Apache Shiro, annotate your Spring Boot application class with Spring Data for Pivotal GemFire's new +* Using only Apache Shiro, annotate your Spring Boot application class with Spring Data for {data-store-name}'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). @@ -1949,10 +1945,10 @@ The problem with the first approach is that you must implement your own `Securit 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. +universally known and non-{data-store-name}-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 one possible way +TIP: See {data-store-name}'s Security examples for {x-data-store-docs}/managing/security/authentication_examples.html[Authentication] +and {x-data-store-docs}/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 you still need to be familiar with @@ -1975,7 +1971,7 @@ class ServerApplication { PropertiesRealm propertiesRealm = new PropertiesRealm(); propertiesRealm.setResourcePath("classpath:shiro.properties"); - propertiesRealm.setPermissionResolver(new Pivotal GemFirePermissionResolver()); + propertiesRealm.setPermissionResolver(new GemFirePermissionResolver()); return propertiesRealm; } @@ -1995,36 +1991,36 @@ 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. +defined as beans in the Spring context, Spring Data for {data-store-name} detects this configuration and uses Apache Shiro +as the security provider to secure your {data-store-name} 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 +TIP: You can find more information about Spring Data for {data-store-name}'s support for {data-store-name}'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 blog post]. 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 -http://gemfire.docs.pivotal.io/geode/managing/security/chapter_overview.html[here]. +More details on {data-store-name} Security can be found +{x-data-store-docs}/managing/security/chapter_overview.html[here]. [[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 {data-store-name} cache client applications. -Pivotal GemFire's process for securing a client application is, honestly, rather involved. In a nutshell, you +{data-store-name}'s process for securing a client application is, honestly, rather involved. In a nutshell, you need to: . Provide an implementation of the -http://gemfire-91-javadocs.docs.pivotal.io/org/apache/geode/security/AuthInitialize.html[`org.apache.geode.security.AuthInitialize`] interface. -. Set the Pivotal GemFire `security-client-auth-init` (System) property to refer to the custom, application-provided +{x-data-store-javadoc}/org/apache/geode/security/AuthInitialize.html[`org.apache.geode.security.AuthInitialize`] interface. +. Set the {data-store-name} `security-client-auth-init` (System) property to refer to the custom, application-provided `AuthInitialize` interface. -. Specify the user credentials in a proprietary, Pivotal GemFire +. Specify the user credentials in a proprietary, {data-store-name} `gfsecurity.properties` file. -Spring Data for Pivotal GemFire simplifies all of those steps by using the same `@EnableSecurity` annotation on +Spring Data for {data-store-name} 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 @@ -2052,13 +2048,13 @@ spring.data.gemfire.security.password=b@cK!nB1@cK 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]. +{spring-framework-docs}/core.html#resources[resource abstraction]. 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 -http://gemfire.docs.pivotal.io/geode/managing/security/chapter_overview.html[here]. +More details on {data-store-name} Security can be found +{x-data-store-docs}/managing/security/chapter_overview.html[here]. [[bootstrap-annotation-config-tips]] == Configuration Tips @@ -2072,7 +2068,7 @@ The following tips can help you get the most out of using the new annotation-bas === Configuration Organization 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 +many {data-store-name} or Spring Data for {data-store-name} 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. @@ -2101,7 +2097,7 @@ We could break this configuration down by concern, as follows: [source, java] ---- @SpringBootApplication -@Import({ Pivotal GemFireConfiguration.class, CachingConfiguration.class, +@Import({ GemFireConfiguration.class, CachingConfiguration.class, FunctionsConfiguration.class, QueriesConfiguration.class, RepositoriesConfiguration.class }) class ClientApplication { .. } @@ -2109,7 +2105,7 @@ class ClientApplication { .. } @ClientCacheApplication @EnableClusterConfiguration @EnableGemfireCacheTransactions -class Pivotal GemFireConfiguration { .. } +class GemFireConfiguration { .. } @EnableGemfireCaching @EnableCachingDefinedRegions @@ -2139,26 +2135,26 @@ While it does not matter to the Spring framework, we generally recommend aiming === Additional Configuration-based Annotations 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 +a deprecated feature of {data-store-name} or because there are better, alternative ways to accomplishing the function that the annotation provides: -* `@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 +* `@EnableAuth`: Enables {data-store-name}'s old authentication and authorization security model. (Deprecated. +{data-store-name}'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 "`<>`" +using Spring and Spring Data for {data-store-name}. 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 that uses UDP-based multi-cast networking. -(_Deprecated_. Use Pivotal GemFire locators instead. See +* `@EnableGemFireAsLastResource`: Discussed in +<> with {data-store-name}. +* `@EnableMcast`: Enables {data-store-name}'s old peer discovery mechanism that uses UDP-based multi-cast networking. +(_Deprecated_. Use {data-store-name} 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 @@ -2167,16 +2163,16 @@ as beans in the Spring context, intercepting the region operation and logging th [[bootstrap-annotation-config-conclusion]] == Conclusion -As we learned in the previous sections, Spring Data for Pivotal GemFire's +As we learned in the previous sections, Spring Data for {data-store-name}'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. +to get started quickly when using {data-store-name} with Spring. 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`] +{spring-framework-javadoc}/org/springframework/context/annotation/Import.html[`@Import`] +and {spring-framework-javadoc}/org/springframework/context/annotation/ImportResource.html[`@ImportResource`] 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, +provide a bean definition that would otherwise be provided by Spring Data for {data-store-name} by using an annotation, the annotation-based configuration backs away. [NOTE] @@ -2185,7 +2181,7 @@ In certain cases, you may even need to fall back to Java configuration, as in th 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 you need Java or XML configuration is when configuring Pivotal GemFire WAN components, +For example, another case where you need Java or XML configuration is when configuring {data-store-name} 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 diff --git a/src/main/asciidoc/reference/bootstrap.adoc b/src/main/asciidoc/reference/bootstrap.adoc index e37222eb..1a28d944 100644 --- a/src/main/asciidoc/reference/bootstrap.adoc +++ b/src/main/asciidoc/reference/bootstrap.adoc @@ -1,30 +1,34 @@ [[bootstrap]] -= Bootstrapping Pivotal GemFire with the Spring container += Bootstrapping {data-store-name} with the Spring container -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. +Spring Data for {data-store-name} provides full configuration and initialization of the {data-store-name} In-Memory Data Grid (IMDG) +using the Spring IoC container. The framework includes several classes to help simplify the configuration of {data-store-name} components, +including: Caches, Regions, Indexes, DiskStores, Functions, WAN Gateways, persistence backup, and several other Distributed System components +to support a variety of application use cases with minimal effort. -NOTE: This section assumes basic familiarity with Pivotal GemFire. For more information, -see the Pivotal GemFire http://geode.apache.org/docs/[product documentation]. +NOTE: This section assumes basic familiarity with {data-store-name}. For more information, +see the {data-store-name} {x-data-store-docs}/gemfire/about_gemfire.html[product documentation]. [[bootstrap:namespace:xml]] -== Advantages of Using Spring over Pivotal GemFire `cache.xml` +== Advantages of using Spring over {data-store-name} `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 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. +Spring Data for {data-store-name}'s XML namespace supports full configuration of the {data-store-name} In-Memory Data Grid (IMDG). +The XML namespace is one of two ways to configure {data-store-name} in a Spring context in order to properly +manage {data-store-name}'s lifecycle inside the Spring container. The other way to configure Pivotal Gemfire +in a Spring context is by using <>. While support for +{data-store-name}'s native `cache.xml` persists for legacy reasons, {data-store-name} application developers +who use XML configuration are encouraged to do everything in Spring XML to take advantage of the many wonderful things +Spring has to offer, such as modular XML configuration, property placeholders and overrides, +SpEL ({spring-framework-docs}/core.html#expressions[Spring Expression Language]), and environment profiles. +Behind the XML namespace, Spring Data for {data-store-name} makes extensive use of Spring's `FactoryBean` pattern +to simplify the creation, configuration, and initialization of {data-store-name} components. -Pivotal GemFire provides several callback interfaces, such as `CacheListener`, `CacheLoader`, and `CacheWriter`, +{data-store-name} provides several callback interfaces, such as `CacheListener`, `CacheLoader`, and `CacheWriter`, that let developers add custom event handlers. Using Spring's IoC container, you can configure these callbacks -as normal Spring beans and inject them into 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). +as normal Spring beans and inject them into {data-store-name} components. This is a significant improvement +over native `cache.xml`, which provides relatively limited configuration options and requires callbacks to implement +{data-store-name}'s `Declarable` interface (see <> 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. @@ -32,17 +36,19 @@ 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 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. +To simplify configuration, Spring Data for {data-store-name} provides a dedicated XML namespace for configuring +core {data-store-name} components. It is possible to configure beans directly by using Spring's standard +`` definition. However, all bean properties are exposed through the XML namespace, so there is little benefit +to using raw bean definitions. + +NOTE: For more information about XML Schema-based configuration in Spring, see the +{spring-framework-docs}/core.html#appendix[appendix] in the Spring Framework reference documentation. NOTE: Spring Data Repository support uses a separate XML namespace. See <> for more information -on how to configure Spring Data for Pivotal GemFire Repositories. +on how to configure Spring Data for {data-store-name} Repositories. -To use the Spring Data for Pivotal GemFire XML namespace, declare it in your Spring XML configuration meta-data, as the following example shows: +To use the Spring Data for {data-store-name} XML namespace, declare it in your Spring XML configuration meta-data, +as the following example shows: [source,xml] ---- @@ -60,17 +66,17 @@ To use the Spring Data for Pivotal GemFire XML namespace, declare it in your Spr ---- -<1> Spring Data for Pivotal GemFire XML namespace prefix. Any name works, but, throughout this reference documentation, +<1> Spring Data for {data-store-name} XML namespace prefix. Any name works, but, throughout this reference documentation, `gfe` is used. <2> The XML namespace prefix is mapped to the URI. <3> The XML namespace URI location. Note that, even though the location points to an external address (which does exist -and is valid), Spring resolves the schema locally, as it is included in the Spring Data for Pivotal GemFire library. +and is valid), Spring resolves the schema locally, as it is included in the Spring Data for {data-store-name} library. <4> Example declaration using the XML namespace with the `gfe` prefix. [NOTE] ==== You can change the default namespace from `beans` to `gfe`. This is useful for XML configuration -composed mainly of Pivotal GemFire components, as it avoids declaring the prefix. To do so, swap the namespace +composed mainly of {data-store-name} components, as it avoids declaring the prefix. To do so, swap the namespace prefix declaration shown earlier, as the following example shows: [source,xml] @@ -89,7 +95,7 @@ prefix declaration shown earlier, as the following example shows: ---- -<1> The default namespace declaration for this XML document points to the Spring Data for Pivotal GemFire XML namespace. +<1> The default namespace declaration for this XML document points to the Spring Data for {data-store-name} XML namespace. <2> The `beans` namespace prefix declaration for Spring's raw bean definitions. <3> Bean declaration using the `beans` namespace. Notice the prefix. <4> Bean declaration using the `gfe` namespace. Notice the lack of prefix since `gfe` is the default namespace. diff --git a/src/main/asciidoc/reference/cache.adoc b/src/main/asciidoc/reference/cache.adoc index acbf78ad..86aa32e8 100644 --- a/src/main/asciidoc/reference/cache.adoc +++ b/src/main/asciidoc/reference/cache.adoc @@ -1,8 +1,8 @@ [[bootstrap:cache]] = Configuring a Cache -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`). +To use {data-store-name}, you need to either create a new `Cache` or connect to an existing one. +With the current version of {data-store-name}, you can have only one open Cache per VM (more strictly, per `ClassLoader`). In most cases, the `Cache` should only be created once. NOTE: This section describes the creation and configuration of a peer cache member, appropriate in @@ -19,11 +19,11 @@ A peer cache with default configuration can be created with the following simple ---- 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. +a `CacheFactoryBean` that creates a Spring bean named `gemfireCache`, which references a {data-store-name} `Cache` instance. This bean refers to either an existing cache or, if one does not already exist, a newly created one. Since no additional properties were specified, a newly created cache applies the default cache configuration. -All Spring Data for Pivotal GemFire components that depend on the cache respect this naming convention, so you need not +All Spring Data for {data-store-name} components that depend on the cache respect this naming convention, so you need not explicitly declare the cache dependency. If you prefer, you can make the dependency explicit by using the `cache-ref` attribute provided by various SDG XML namespace elements. Also, you can override the cache's bean name using the `id` attribute, as follows: @@ -33,9 +33,9 @@ the `id` attribute, as follows: ---- -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: +A {data-store-name} `Cache` can be fully configured using Spring. However, {data-store-name}'s native XML configuration file, `cache.xml`, +is also supported. For situations where the {data-store-name} cache needs to be configured natively, you can provide a reference +to the {data-store-name} XML configuration file by using the `cache-xml-location` attribute, as follows: [source,xml] ---- @@ -49,8 +49,8 @@ NOTE: The configuration makes use of Spring's http://docs.spring.io/spring/docs/ 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, you can also specify Pivotal GemFire System -http://geode.apache.org/docs/guide/11/reference/topics/gemfire_properties.html[properties] +In addition to referencing an external XML configuration file, you can also specify {data-store-name} System +{x-data-store-docs}/reference/topics/gemfire_properties.html[properties] that use any of Spring's `Properties` support features. For example, you can use the `properties` element defined in the `util` namespace to define `Properties` @@ -127,44 +127,44 @@ or child elements, as the following listing shows: ---- <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]. +see the {data-store-name} 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 (common in web applications), set this value to `false`. -<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] +<2> Setting the `enable-auto-reconnect` attribute to `true` (the default is `false`) lets a disconnected {data-store-name} member +automatically reconnect and rejoin the {data-store-name} cluster. +See the {data-store-name} {x-data-store-docs}/managing/autoreconnect/member-reconnect.html[product documentation] for more details. <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` +Spring (XML) configuration metadata and {data-store-name} `cache.xml` is used to configure the {data-store-name} cache node +(whether client or peer). This option lets {data-store-name} 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` (the default is `false`) enables a Pivotal GemFire member to +<4> Setting the `use-cluster-configuration` attribute to `true` (the default is `false`) enables a {data-store-name} 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] +See the {data-store-name} {x-data-store-docs}/configuring/cluster_config/gfsh_persist.html[product documentation] for more details. <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]. +{x-data-store-javadoc}/org/apache/geode/cache/TransactionListener.html[TransactionListener]. 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]. +{x-data-store-javadoc}/org/apache/geode/cache/TransactionWriter.html[TransactionWriter]. 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 +must implement {x-data-store-javadoc}/org/apache/geode/cache/util/GatewayConflictResolver.html [GatewayConflictResolver]. A `GatewayConflictResolver` is a cache-level plugin that is called upon to decide what to do with events that originate in other systems and arrive through the WAN Gateway. -<8> Enables Pivotal GemFire's http://geode.apache.org/docs/guide/11/developing/region_options/dynamic_region_creation.html[DynamicRegionFactory], +<8> Enables {data-store-name}'s {x-data-store-docs}/developing/region_options/dynamic_region_creation.html[DynamicRegionFactory], which provides a distributed Region creation service. -<9> Declares a JNDI binding to enlist an external DataSource in a Pivotal GemFire transaction. +<9> Declares a JNDI binding to enlist an external DataSource in a {data-store-name} transaction. [[bootstrap:cache:pdx-serialization]] === Enabling PDX Serialization -The preceding example includes a number of attributes related to Pivotal GemFire's enhanced serialization framework, PDX. +The preceding example includes a number of attributes related to {data-store-name}'s enhanced serialization framework, PDX. While a complete discussion of PDX is beyond the scope of this reference guide, it is important to note that PDX -is enabled by registering a `PdxSerializer`, which is specified by setting the `pdx-serializer` attribute. Pivotal GemFire provides +is enabled by registering a `PdxSerializer`, which is specified by setting the `pdx-serializer` attribute. {data-store-name} provides an implementing class (`org.apache.geode.pdx.ReflectionBasedAutoSerializer`) that uses Java Reflection. However, it is common for developers to provide their own implementation. The value of the attribute is simply a reference to a Spring bean that implements the `PdxSerializer` interface. @@ -176,17 +176,17 @@ More information on serialization support can be found in <> You should be careful when setting the ` ---- -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. +NOTE: While certain {data-store-name} tools, such as `Gfsh`, have their actions "`recorded`" when schema-like changes are made +(for example, `gfsh>create region --name=Example --type=PARTITION`), Spring Data for {data-store-name}'s configuration metadata +is not recorded. The same is true when using {data-store-name}'s public Java API directly. It, too, is not recorded. -For more information on Pivotal GemFire's Cluster Configuration Service, see the -http://geode.apache.org/docs/guide/11/configuring/cluster_config/gfsh_persist.html[product documentation]. +For more information on {data-store-name}'s Cluster Configuration Service, see the +{x-data-store-docs}/configuring/cluster_config/gfsh_persist.html[product documentation]. [[bootstrap:cache:server]] -== Configuring a Pivotal GemFire CacheServer +== Configuring a {data-store-name} CacheServer -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], +Spring Data for {data-store-name} includes dedicated support for configuring a +{x-data-store-javadoc}/org/apache/geode/cache/server/CacheServer.html[CacheServer], allowing complete configuration through the Spring container, as the following example shows: [source,xml] @@ -262,7 +262,7 @@ allowing complete configuration through the Spring container, as the following e - + > and is supported by the `org.springframework.data.gemfire.client.ClientCacheFactoryBean`. +the {data-store-name} peer <> and is supported by the `org.springframework.data.gemfire.client.ClientCacheFactoryBean`. -The simplest definition of a Pivotal GemFire cache client using default configuration follows: +The simplest definition of a {data-store-name} cache client using default configuration follows: [source,xml] ---- @@ -336,14 +336,14 @@ to the cache definition, as the following example shows: ---- 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()`]. +initialization includes a call to {x-data-store-javadoc}/org/apache/geode/cache/client/ClientCache.html#readyForEvents[`ClientCache.readyForEvents()`]. <> covers client-side configuration in more detail. [[bootstrap:cache:client:pool]] -=== Pivotal GemFire's DEFAULT Pool and Spring Data for Pivotal GemFire Pool Definitions +=== {data-store-name}'s DEFAULT Pool and Spring Data for {data-store-name} Pool Definitions -If a Pivotal GemFire `ClientCache` is local-only, then no Pool definition is required. For instance, you can define the following: +If a {data-store-name} `ClientCache` is local-only, then no Pool definition is required. For instance, you can define the following: [source,xml] ---- @@ -353,14 +353,14 @@ 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`] +no pool is necessary. This is true for any client-side, local-only region, as defined by the {data-store-name}'s +{x-data-store-javadoc}/org/apache/geode/cache/client/ClientRegionShortcut.html[`ClientRegionShortcut`] (all `LOCAL_*` shortcuts). However, if a client Region is a (caching) proxy to a server-side Region, a pool is required. In that case, there are several ways to define and use a Pool. -When a client cache, a pool, and a proxy-based region are all defined but not explicitly identified, Spring Data for Pivotal GemFire +When a client cache, a pool, and a proxy-based region are all defined but not explicitly identified, Spring Data for {data-store-name} resolves the references automatically, as the following example shows: [source,xml] @@ -375,10 +375,10 @@ resolves the references automatically, as the following example shows: ---- 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 +as `Example`. However, the client cache initializes {data-store-name}'s `DEFAULT` pool from `gemfirePool`, and the client Region uses the `gemfirePool` when distributing data between the client and the server. -Basically, Spring Data for Pivotal GemFire resolves the preceding configuration to the following: +Basically, Spring Data for {data-store-name} resolves the preceding configuration to the following: [source,xml] ---- @@ -391,7 +391,7 @@ Basically, Spring Data for Pivotal GemFire resolves the preceding configuration ---- -Pivotal GemFire still creates a pool called `DEFAULT`. Spring Data for Pivotal GemFire causes the `DEFAULT` pool to be +{data-store-name} still creates a pool called `DEFAULT`. Spring Data for {data-store-name} causes the `DEFAULT` pool to be initialized from the `gemfirePool`. Doing so is useful in situations where multiple pools are defined and client regions are using separate Pools. @@ -416,12 +416,12 @@ Consider the following: ---- -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 +In this setup, the {data-store-name} client cache's `DEFAULT` pool is initialized from `locatorPool`, as specified by the +`pool-name` attribute. There is no Spring Data for {data-store-name}-defined `gemfirePool`, since both pools were explicitly identified (named) -- `locatorPool` and `serverPool`, respectively. 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 +{data-store-name}'s `DEFAULT` pool, which was configured from the `locatorPool` based on the client cache bean definition's `pool-name` attribute. Finally, the `YetAnotherExample` egion does not use a Pool, because it is `LOCAL`. diff --git a/src/main/asciidoc/reference/cq-container.adoc b/src/main/asciidoc/reference/cq-container.adoc index 94436796..2b8f5e1b 100644 --- a/src/main/asciidoc/reference/cq-container.adoc +++ b/src/main/asciidoc/reference/cq-container.adoc @@ -1,28 +1,29 @@ [[apis:continuous-query]] = Continuous Query (CQ) -A powerful functionality offered by Pivotal GemFire is -http://geode.apache.org/docs/guide/11/developing/continuous_querying/chapter_overview.html[Continuous Query] (or CQ). -In short, CQ allows one to create and register an OQL query, and then automatically be notified when new data -that gets added to Pivotal GemFire matches the query predicate. _Spring Data for Pivotal GemFire_ provides dedicated support for CQs through -the `org.springframework.data.gemfire.listener` package and its *listener container*; very similar in functionality -and naming to the JMS integration in the _Spring Framework_; in fact, users familiar with the JMS support in _Spring_, -should feel right at home. +A powerful functionality offered by {data-store-name} is +{x-data-store-docs}/developing/continuous_querying/chapter_overview.html[Continuous Query] (or CQ). -Basically _Spring Data for Pivotal GemFire_ allows methods on POJOs to become end-points for CQ. Simply define the query -and indicate the method that should be called to be notified when there is a match. _Spring Data for Pivotal GemFire_ takes care +In short, CQ allows a developer to create and register an OQL query, and then automatically be notified when new data +that gets added to {data-store-name} matches the query predicate. Spring Data for {data-store-name} provides dedicated +support for CQs through the `org.springframework.data.gemfire.listener` package and its *listener container*; +very similar in functionality and naming to the JMS integration in the _Spring Framework_; in fact, users familiar with +the JMS support in Spring, should feel right at home. + +Basically Spring Data for {data-store-name} allows methods on POJOs to become end-points for CQ. Simply define the query +and indicate the method that should be called to be notified when there is a match. Spring Data for {data-store-name} takes care of the rest. This is very similar to Java EE's message-driven bean style, but without any requirement for base class -or interface implementations, based on Pivotal GemFire. +or interface implementations, based on {data-store-name}. -NOTE: Currently, Continuous Query is only supported in Pivotal GemFire's client/server topology. Additionally, the client Pool -used is required to have the subscription enabled. Please refer to the Pivotal GemFire -http://geode.apache.org/docs/guide/11/developing/continuous_querying/implementing_continuous_querying.html[documentation] +NOTE: Currently, Continuous Query is only supported in {data-store-name}'s client/server topology. Additionally, the client Pool +used is required to have the subscription enabled. Please refer to the {data-store-name} +{x-data-store-docs}/developing/continuous_querying/implementing_continuous_querying.html[documentation] for more information. [[apis:continuous-query:container]] == Continuous Query Listener Container -_Spring Data for Pivotal GemFire_ simplifies creation, registration, life-cycle and dispatch of CQ events by taking care of +Spring Data for {data-store-name} simplifies creation, registration, life-cycle and dispatch of CQ events by taking care of the infrastructure around CQ with the use of SDG's `ContinuousQueryListenerContainer`, which does all the heavy lifting on behalf of the user. Users familiar with EJB and JMS should find the concepts familiar as it is designed as close as possible to the support provided in the _Spring Framework_ with its Message-driven POJOs (MDPs). @@ -33,11 +34,11 @@ is responsible for all threading of message reception and dispatches into the li the intermediary between an EDP (Event-driven POJO) and the event provider and takes care of creation and registration of CQs (to receive events), resource acquisition and release, exception conversion and the like. This allows you, as an application developer, to write the (possibly complex) business logic associated with receiving an event -(and reacting to it), and delegate the boilerplate Pivotal GemFire infrastructure concerns to the framework. +(and reacting to it), and delegate the boilerplate {data-store-name} infrastructure concerns to the framework. The listener container is fully customizable. A developer can chose either to use the CQ thread to perform the dispatch (synchronous delivery) or a new thread (from an existing pool) for an asynchronous approach by defining the suitable -`java.util.concurrent.Executor` (or _Spring's_ `TaskExecutor`). Depending on the load, the number of listeners +`java.util.concurrent.Executor` (or Spring's `TaskExecutor`). Depending on the load, the number of listeners or the runtime environment, the developer should change or tweak the executor to better serve her needs. In particular, in managed environments (such as app servers), it is highly recommended to pick a proper `TaskExecutor` to take advantage of its runtime. @@ -45,10 +46,10 @@ to take advantage of its runtime. [[apis:continuous-query:adapter]] == The `ContinuousQueryListener` and `ContinuousQueryListenerAdapter` -The `ContinuousQueryListenerAdapter` class is the final component in _Spring Data for Pivotal GemFire_ CQ support. In a nutshell, +The `ContinuousQueryListenerAdapter` class is the final component in Spring Data for {data-store-name} CQ support. In a nutshell, class allows you to expose almost *any* implementing class as an EDP with minimal constraints. `ContinuousQueryListenerAdapter` implements the `ContinuousQueryListener` interface, a simple listener interface -similar to Pivotal GemFire's http://geode.apache.org/releases/latest/javadoc/org/apache/geode/cache/query/CqListener.html[CqListener]. +similar to {data-store-name}'s {x-data-store-javadoc}/org/apache/geode/cache/query/CqListener.html[CqListener]. Consider the following interface definition. Notice the various event handling methods and their parameters: @@ -75,7 +76,7 @@ class DefaultEventDelegate implements EventDelegate { } ---- -In particular, note how the above implementation of the `EventDelegate` interface has *no* Pivotal GemFire dependencies at all. +In particular, note how the above implementation of the `EventDelegate` interface has *no* {data-store-name} dependencies at all. It truly is a POJO that we can and will make into an EDP via the following configuration. NOTE: the class does not have to implement an interface; an interface is only used to better showcase the decoupling @@ -115,7 +116,7 @@ reference and the actual query definition are required. It's possible, however, the resulting Continuous Query (useful for monitoring) but also the name of the method (the default is `handleEvent`). The specified method can have various argument types, the `EventDelegate` interface lists the allowed types. -The example above uses the _Spring Data for Pivotal GemFire_ namespace to declare the event listener container +The example above uses the Spring Data for {data-store-name} namespace to declare the event listener container and automatically register the listeners. The full blown, *beans* definition is displayed below: [source,xml] @@ -142,6 +143,6 @@ and automatically register the listeners. The full blown, *beans* definition is ---- -Each time an event is received, the adapter automatically performs type translation between the Pivotal GemFire event +Each time an event is received, the adapter automatically performs type translation between the {data-store-name} event and the required method argument(s) transparently. Any exception caused by the method invocation is caught and handled by the container (by default, being logged). diff --git a/src/main/asciidoc/reference/data-access.adoc b/src/main/asciidoc/reference/data-access.adoc index e7d22428..2bd222c2 100644 --- a/src/main/asciidoc/reference/data-access.adoc +++ b/src/main/asciidoc/reference/data-access.adoc @@ -1,16 +1,16 @@ [[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`), -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 a `` tag that offers a convenient way to connect to a Pivotal GemFire cluster. +In addition to the core XML namespace (`gfe`), Spring Data for {data-store-name} provides a data access XML namespace (`gfe-data`), +which is primarily intended to simplify the development of {data-store-name} client applications. This namespace currently contains +support for {data-store-name} <> and function <>, +as well as a `` tag that offers a convenient way to connect to a {data-store-name} cluster. [[data-access:datasource]] -== An Easy Way to Connect to Pivotal GemFire +== An Easy Way to Connect to {data-store-name} -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 +For many applications, a basic connection to a {data-store-name} data grid using default values is sufficient. +Spring Data for {data-store-name}'s `` 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. diff --git a/src/main/asciidoc/reference/data.adoc b/src/main/asciidoc/reference/data.adoc index 7aa32c7f..a79af7a6 100644 --- a/src/main/asciidoc/reference/data.adoc +++ b/src/main/asciidoc/reference/data.adoc @@ -1,19 +1,19 @@ [[apis]] -= Working with Pivotal GemFire APIs += Working with {data-store-name} APIs -Once the Pivotal GemFire Cache and Regions have been configured, they can be injected and used inside application objects. -This chapter describes the integration with _Spring's_ Transaction Management functionality and DAO exception hierarchy. -This chapter also covers support for dependency injection of Pivotal GemFire managed objects. +Once the {data-store-name} Cache and Regions have been configured, they can be injected and used inside application objects. +This chapter describes the integration with Spring's Transaction Management functionality and DAO exception hierarchy. +This chapter also covers support for dependency injection of {data-store-name} managed objects. [[apis:template]] == GemfireTemplate -As with many other high-level abstractions provided by _Spring_, _Spring Data for Pivotal GemFire_ provides a *template* -to simplify Pivotal GemFire data access operations. The class provides several methods containing common Region operations, -but also provides the capability to *execute* code against native Pivotal GemFire APIs without having to deal with -Pivotal GemFire checked exceptions by using a `GemfireCallback`. +As with many other high-level abstractions provided by Spring, Spring Data for {data-store-name} provides a *template* +to simplify {data-store-name} data access operations. The class provides several methods containing common Region operations, +but also provides the capability to *execute* code against native {data-store-name} APIs without having to deal with +{data-store-name} checked exceptions by using a `GemfireCallback`. -The template class requires a Pivotal GemFire `Region`, and once configured, is thread-safe and is reusable +The template class requires a {data-store-name} `Region`, and once configured, is thread-safe and is reusable across multiple application classes: [source,xml] @@ -22,14 +22,14 @@ across multiple application classes: ---- Once the template is configured, a developer can use it alongside `GemfireCallback` to work directly with -the Pivotal GemFire `Region` without having to deal with checked exceptions, threading or resource management concerns: +the {data-store-name} `Region` without having to deal with checked exceptions, threading or resource management concerns: [source,java] ---- template.execute(new GemfireCallback>() { public Iterable doInGemfire(Region region) - throws Pivotal GemFireCheckedException, Pivotal GemFireException { + throws GemFireCheckedException, GemFireException { Region localRegion = (Region) region; @@ -41,7 +41,7 @@ template.execute(new GemfireCallback>() { }); ---- -For accessing the full power of the Pivotal GemFire query language, a developer can use the `find` and `findUnique` +For accessing the full power of the {data-store-name} query language, a developer can use the `find` and `findUnique` methods, which, compared to the `query` method, can execute queries across multiple Regions, execute projections, and the like. @@ -63,9 +63,9 @@ As mentioned in _Spring Framework's_ documentation, http://docs.spring.io/spring/docs/current/spring-framework-reference/htmlsingle/#orm-exception-translation[Exception translation] can be applied transparently to your Data Access Objects (DAO) through the use of the `@Repository` annotation and AOP by defining a `PersistenceExceptionTranslationPostProcessor` bean. The same exception translation functionality -is enabled when using Pivotal GemFire as long as the `CacheFactoryBean` is declared, e.g. using either a `` +is enabled when using {data-store-name} as long as the `CacheFactoryBean` is declared, e.g. using either a `` or `` declaration, which acts as an exception translator and is automatically detected by -the _Spring_ infrastructure and used accordingly. +the Spring infrastructure and used accordingly. [[apis:transaction-management]] == Local, Cache Transaction Management @@ -73,44 +73,44 @@ the _Spring_ infrastructure and used accordingly. One of the most popular features of the _Spring Framework_ is http://docs.spring.io/spring/docs/current/spring-framework-reference/htmlsingle/#transaction[Transaction Management]. -If you are not familiar with _Spring's_ transaction abstraction then we strongly recommend +If you are not familiar with Spring's transaction abstraction then we strongly recommend http://docs.spring.io/spring/docs/current/spring-framework-reference/htmlsingle/#transaction-motivation[reading] about _Spring's Transaction Management_ infrastructure as it offers a consistent _programming model_ that works transparently across multiple APIs and can be configured either programmatically or declaratively (the most popular choice). -For Pivotal GemFire, _Spring Data for Pivotal GemFire_ provides a dedicated, per-cache, `PlatformTransactionManager` that, -once declared, allows Region operations to be executed atomically through _Spring_: +For {data-store-name}, Spring Data for {data-store-name} provides a dedicated, per-cache, `PlatformTransactionManager` that, +once declared, allows Region operations to be executed atomically through Spring: [source,xml] ---- ---- -NOTE: The example above can be simplified even further by eliminating the `cache-ref` attribute if the Pivotal GemFire cache -is defined under the default name, `gemfireCache`. As with the other _Spring Data for Pivotal GemFire_ namespace elements, +NOTE: The example above can be simplified even further by eliminating the `cache-ref` attribute if the {data-store-name} cache +is defined under the default name, `gemfireCache`. As with the other Spring Data for {data-store-name} namespace elements, if the cache bean name is not configured, the aforementioned naming convention will be used. Additionally, the transaction manager name is "`gemfireTransactionManager`" if not explicitly specified. -Currently, Pivotal GemFire supports optimistic transactions with *read committed* isolation. Furthermore, to guarantee +Currently, {data-store-name} supports optimistic transactions with *read committed* isolation. Furthermore, to guarantee this isolation, developers should avoid making *in-place* changes that manually modify values present in the cache. To prevent this from happening, the transaction manager configures the cache to use *copy on read* semantics by default, meaning a clone of the actual value is created each time a read is performed. This behavior can be disabled if needed through the `copyOnRead` property. For more information on the semantics and behavior of the underlying Geode transaction manager, please refer to the Geode -http://geode.apache.org/releases/latest/javadoc/org/apache/geode/cache/CacheTransactionManager.html[CacheTransactionManager Javadoc] -as well as the http://geode.apache.org/docs/guide/11/developing/transactions/chapter_overview.html[documentation]. +{x-data-store-javadoc}/org/apache/geode/cache/CacheTransactionManager.html[CacheTransactionManager Javadoc] +as well as the {x-data-store-docs}/developing/transactions/chapter_overview.html[documentation]. [[apis:global-transaction-management]] == Global, JTA Transaction Management -It is also possible for Pivotal GemFire to participate in a Global, JTA based transaction, such as a transaction managed +It is also possible for {data-store-name} to participate in a Global, JTA based transaction, such as a transaction managed by an Java EE Application Server (e.g. WebSphere Application Server, a.k.a. WAS) using Container Managed Transactions (CMT) along with other JTA resources. -However, unlike many other JTA "compliant" resources (e.g. JMS Message Brokers like ActiveMQ), Pivotal GemFire is *not* -an XA compliant resource. Therefore, Pivotal GemFire must be positioned as the "_Last Resource_" in a JTA transaction +However, unlike many other JTA "compliant" resources (e.g. JMS Message Brokers like ActiveMQ), {data-store-name} is *not* +an XA compliant resource. Therefore, {data-store-name} must be positioned as the "_Last Resource_" in a JTA transaction (_prepare phase_) since it does not implement the 2-phase commit protocol, or rather does not handle distributed transactions. @@ -121,23 +121,23 @@ In fact, Red Hat's JBoss project, http://narayana.io/[Narayana] is one such LGPL refers to this as "_Last Resource Commit Optimization_" (LRCO). More details can be found http://narayana.io//docs/project/index.html#d0e1859[here]. -However, whether you are using Pivotal GemFire in a standalone environment with an Open Source JTA Transaction Management +However, whether you are using {data-store-name} in a standalone environment with an Open Source JTA Transaction Management implementation that supports "_Last Resource_", or a managed environment (e.g. Java EE AS such as WAS), _Spring Data Geode_ has you covered. -There are a series of steps you must complete to properly use Pivotal GemFire as a "_Last Resource_" in a JTA transaction +There are a series of steps you must complete to properly use {data-store-name} as a "_Last Resource_" in a JTA transaction involving more than 1 transactional resource. Additionally, there can only be 1 non-XA compliant resource -(e.g. Pivotal GemFire) in such an arrangement. +(e.g. {data-store-name}) in such an arrangement. -1) First, you must complete Steps 1-4 in Pivotal GemFire's documentation +1) First, you must complete Steps 1-4 in {data-store-name}'s documentation http://gemfire90.docs.pivotal.io/geode/developing/transactions/JTA_transactions.html#concept_csy_vfb_wk[here]. -NOTE: #1 above is independent of your _Spring [Boot] and/or [Data Pivotal GemFire]_ application +NOTE: #1 above is independent of your Spring [Boot] and/or [Data for {data-store-name}] application and must be completed successfully. -2) Referring to Step 5 in Pivotal GemFire's http://gemfire90.docs.pivotal.io/geode/developing/transactions/JTA_transactions.html#concept_csy_vfb_wk[documentation], -_Spring Data for Pivotal GemFire's_ Annotation support will attempt to set the `Pivotal GemFireCache`, http://gemfire-90-javadocs.docs.pivotal.io/org/apache/geode/cache/Pivotal GemFireCache.html#setCopyOnRead-boolean-[`copyOnRead`] -property for you when using the `@EnablePivotal GemFireAsLastResource` annotation. +2) Referring to Step 5 in {data-store-name}'s http://gemfire90.docs.pivotal.io/geode/developing/transactions/JTA_transactions.html#concept_csy_vfb_wk[documentation], +_Spring Data for {data-store-name}'s_ Annotation support will attempt to set the `GemFireCache`, {x-data-store-javadoc}/org/apache/geode/cache/GemFireCache.html#setCopyOnRead-boolean-[`copyOnRead`] +property for you when using the `@EnableGemFireAsLastResource` annotation. However, if SDG's auto-configuration is unsuccessful then you must explicitly set the `copy-on-read` attribute on the `` or `` element in XML or the `copyOnRead` property of the SDG `CacheFactoryBean` class @@ -192,18 +192,18 @@ Client Cache JavaConfig: NOTE: explicitly setting the `copy-on-read` attribute or optionally the `copyOnRead` property really should not be necessary. -3) At this point, you *skip* Steps 6-8 in Pivotal GemFire's http://gemfire90.docs.pivotal.io/geode/developing/transactions/JTA_transactions.html#concept_csy_vfb_wk[documentation] -and let _Spring Data Geode_ work its magic. All you need do is annotate your _Spring_ `@Configuration` class -with _Spring Data for Pivotal GemFire's_ *new* `@EnablePivotal GemFireAsLastResource` annotation and a combination of _Spring's_ +3) At this point, you *skip* Steps 6-8 in {data-store-name}'s http://gemfire90.docs.pivotal.io/geode/developing/transactions/JTA_transactions.html#concept_csy_vfb_wk[documentation] +and let _Spring Data Geode_ work its magic. All you need do is annotate your Spring `@Configuration` class +with Spring Data for {data-store-name}'s *new* `@EnableGemFireAsLastResource` annotation and a combination of Spring's http://docs.spring.io/spring/docs/current/spring-framework-reference/htmlsingle/#transaction[Transaction Management] -infrastructure and _Spring Data for Pivotal GemFire's_ `@EnablePivotal GemFireAsLastResource` configuration does the trick. +infrastructure and _Spring Data for {data-store-name}'s_ `@EnableGemFireAsLastResource` configuration does the trick. The configuration looks like this... [source,java] ---- @Configuration -@EnablePivotal GemFireAsLastResource +@EnableGemFireAsLastResource @EnableTransactionManagement(order = 1) class GeodeConfiguration { @@ -213,13 +213,13 @@ class GeodeConfiguration { The only requirements are... -3.1) The `@EnablePivotal GemFireAsLastResource` annotation must be declared on the same _Spring_ `@Configuration` class -where _Spring's_ `@EnableTransactionManagement` annotation is also specified. +3.1) The `@EnableGemFireAsLastResource` annotation must be declared on the same Spring `@Configuration` class +where Spring's `@EnableTransactionManagement` annotation is also specified. 3.2) The `order` attribute of the `@EnableTransactionManagement` annotation must be explicitly set to an integer value that is not `Integer.MAX_VALUE` or `Integer.MIN_VALUE` (defaults to `Integer.MAX_VALUE`). -Of course, hopefully you are aware that you also need to configure _Spring's_ `JtaTransactionManager` +Of course, hopefully you are aware that you also need to configure Spring's `JtaTransactionManager` when using JTA Transactions like so.. [source,java] @@ -236,15 +236,15 @@ public JtaTransactionManager transactionManager(UserTransaction userTransaction) ---- NOTE: The configuration in section <> does *not* apply here. -The use of _Spring Data for Pivotal GemFire's_ `GemfireTransactionManager` is applicable only in "Local", Cache Transactions, +The use of _Spring Data for {data-store-name}'s_ `GemfireTransactionManager` is applicable only in "Local", Cache Transactions, *not* "Global", JTA Transactions. Therefore, you do *not* configure the SDG `GemfireTransactionManager` in this case. -You configure _Spring's_ `JtaTransactionManager` as shown above. +You configure Spring's `JtaTransactionManager` as shown above. For more details on using _Spring's Transaction Management_ with JTA, see http://docs.spring.io/spring/docs/current/spring-framework-reference/htmlsingle/#transaction-application-server-integration[here]. -Effectively, _Spring Data for Pivotal GemFire's_ `@EnablePivotal GemFireAsLastResource` annotation imports configuration containing 2 Aspect -bean definitions that handles the Pivotal GemFire `o.a.g.ra.GFConnectionFactory.getConnection()` +Effectively, _Spring Data for {data-store-name}'s_ `@EnableGemFireAsLastResource` annotation imports configuration containing 2 Aspect +bean definitions that handles the {data-store-name} `o.a.g.ra.GFConnectionFactory.getConnection()` and `o.a.g.ra.GFConnection.close()` operations at the appropriate points during the transactional operation. Specifically, the correct sequence of events are... @@ -260,10 +260,10 @@ Specifically, the correct sequence of events are... 5. Finally, `GFConnection.close()` This is consistent with how you, as the application developer, would code this manually if you had to use the JTA API -+ Pivotal GemFire API yourself, as shown in the -Pivotal GemFire http://gemfire90.docs.pivotal.io/geode/developing/transactions/jca_adapter_example.html#concept_swv_z2p_wk[example]. ++ {data-store-name} API yourself, as shown in the +{data-store-name} http://gemfire90.docs.pivotal.io/geode/developing/transactions/jca_adapter_example.html#concept_swv_z2p_wk[example]. -Thankfully, _Spring_ does the heavy lifting for you and all you need do after applying the appropriate configuration +Thankfully, Spring does the heavy lifting for you and all you need do after applying the appropriate configuration (shown above) is... [source,java] @@ -280,11 +280,11 @@ class MyTransactionalService ... { } ---- -#1 & #4 above are appropriately handled for you by _Spring's_ JTA based `PlatformTransactionManager` once the +#1 & #4 above are appropriately handled for you by Spring's JTA based `PlatformTransactionManager` once the `@Transactional` boundary is entered by your application (i.e. when the `MyTransactionSerivce.someTransactionalMethod()` is called). -#2 & #3 are handled by _Spring Data for Pivotal GemFire's_ new Aspects enabled with the `@EnablePivotal GemFireAsLastResource` annotation. +#2 & #3 are handled by Spring Data for {data-store-name}'s new Aspects enabled with the `@EnableGemFireAsLastResource` annotation. #3 of course is the responsibility of your application. @@ -294,8 +294,8 @@ Indeed, with the appropriate logging configured, you will see the correct sequen ---- 2017-Jun-22 11:11:37 TRACE TransactionInterceptor - Getting transaction for [example.app.service.MessageService.send] -2017-Jun-22 11:11:37 TRACE Pivotal GemFireAsLastResourceConnectionAcquiringAspect - Acquiring Pivotal GemFire Connection -from Pivotal GemFire JCA ResourceAdapter registered at [gfe/jca] +2017-Jun-22 11:11:37 TRACE GemFireAsLastResourceConnectionAcquiringAspect - Acquiring {data-store-name} Connection +from {data-store-name} JCA ResourceAdapter registered at [gfe/jca] 2017-Jun-22 11:11:37 TRACE MessageService - PRODUCER [ Message : [{ @type = example.app.domain.Message, id= MSG0000000000, message = SENT }], @@ -303,13 +303,13 @@ JSON : [{"id":"MSG0000000000","message":"SENT"}] ] 2017-Jun-22 11:11:37 TRACE TransactionInterceptor - Completing transaction for [example.app.service.MessageService.send] -2017-Jun-22 11:11:37 TRACE Pivotal GemFireAsLastResourceConnectionClosingAspect - Closed Pivotal GemFire Connection @ [Reference [...]] +2017-Jun-22 11:11:37 TRACE GemFireAsLastResourceConnectionClosingAspect - Closed {data-store-name} Connection @ [Reference [...]] ---- -For more details on using Pivotal GemFire in JTA transactions, +For more details on using {data-store-name} in JTA transactions, see http://gemfire90.docs.pivotal.io/geode/developing/transactions/JTA_transactions.html[here]. -For more details on configuring Pivotal GemFire as a "_Last Resource_", +For more details on configuring {data-store-name} as a "_Last Resource_", see http://gemfire90.docs.pivotal.io/geode/developing/transactions/JTA_transactions.html#concept_csy_vfb_wk[here]. :leveloffset: +1 @@ -321,33 +321,33 @@ include::{basedocdir}/reference/cq-container.adoc[] [[apis:declarable]] == Wiring `Declarable` Components -Pivotal GemFire XML configuration (usually referred to as `cache.xml`) allows *user* objects to be declared +{data-store-name} XML configuration (usually referred to as `cache.xml`) allows *user* objects to be declared as part of the configuration. Usually these objects are `CacheLoaders` or other pluggable callback components -supported by Pivotal GemFire. Using native Pivotal GemFire configuration, each user type declared through XML must implement +supported by {data-store-name}. Using native {data-store-name} configuration, each user type declared through XML must implement the `Declarable` interface, which allows arbitrary parameters to be passed to the declared class through a `Properties` instance. In this section, we describe how you can configure these pluggable components when defined in `cache.xml` -using _Spring_ while keeping your Cache/Region configuration defined in `cache.xml`. This allows your +using Spring while keeping your Cache/Region configuration defined in `cache.xml`. This allows your pluggable components to focus on the application logic and not the location or creation of `DataSources` or other collaborators. However, if you are starting a green field project, it is recommended that you configure Cache, Region, -and other pluggable Pivotal GemFire components directly in _Spring_. This avoids inheriting from the `Declarable` interface +and other pluggable {data-store-name} components directly in Spring. This avoids inheriting from the `Declarable` interface or the base class presented in this section. See the following sidebar for more information on this approach. .Eliminate `Declarable` components **** -A developer can configure custom types entirely through _Spring_ as mentioned in <>. +A developer can configure custom types entirely through Spring as mentioned in <>. That way, a developer does not have to implement the `Declarable` interface, and also benefits from -all the features of the _Spring_ IoC container (not just dependency injection but also life-cycle +all the features of the Spring IoC container (not just dependency injection but also life-cycle and instance management). **** -As an example of configuring a `Declarable` component using _Spring_, consider the following declaration -(taken from the `Declarable` http://geode.apache.org/releases/latest/javadoc/org/apache/geode/cache/Declarable.html[Javadoc]): +As an example of configuring a `Declarable` component using Spring, consider the following declaration +(taken from the `Declarable` {x-data-store-javadoc}/org/apache/geode/cache/Declarable.html[Javadoc]): [source,xml] ---- @@ -359,16 +359,16 @@ As an example of configuring a `Declarable` component using _Spring_, consider t ---- -To simplify the task of parsing, converting the parameters and initializing the object, _Spring Data for Pivotal GemFire_ offers -a base class (`WiringDeclarableSupport`) that allows Pivotal GemFire user objects to be wired through a *template* bean definition -or, in case that is missing, perform auto-wiring through the _Spring_ IoC container. To take advantage of this feature, +To simplify the task of parsing, converting the parameters and initializing the object, Spring Data for {data-store-name} offers +a base class (`WiringDeclarableSupport`) that allows {data-store-name} user objects to be wired through a *template* bean definition +or, in case that is missing, perform auto-wiring through the Spring IoC container. To take advantage of this feature, the user objects need to extend `WiringDeclarableSupport`, which automatically locates the declaring `BeanFactory` and performs wiring as part of the initialization process. .Why is a base class needed? **** -In the current Pivotal GemFire release there is no concept of an *object factory* and the types declared are instantiated -and used as is. In other words, there is no easy way to manage object creation outside Pivotal GemFire. +In the current {data-store-name} release there is no concept of an *object factory* and the types declared are instantiated +and used as is. In other words, there is no easy way to manage object creation outside {data-store-name}. **** [[apis:declarable:template-wiring]] @@ -419,8 +419,8 @@ class DBLoader extends WiringDeclarableSupport implements CacheLoader { ---- In the scenario above, as no parameter was specified, a bean with the id/name `com.company.app.DBLoader` was used -as a template for wiring the instance created by Pivotal GemFire. For cases where the bean name uses a different convention, -one can pass in the `bean-name` parameter in the Pivotal GemFire configuration: +as a template for wiring the instance created by {data-store-name}. For cases where the bean name uses a different convention, +one can pass in the `bean-name` parameter in the {data-store-name} configuration: [source,xml] ---- @@ -465,7 +465,7 @@ However, a developer can also use JDK 5 annotations to provide additional inform TIP: We strongly recommend reading the dedicated http://docs.spring.io/spring/docs/current/spring-framework-reference/htmlsingle/#beans-annotation-config[chapter] -in the _Spring_ documentation for more information on the supported annotations and enabling factors. +in the Spring documentation for more information on the supported annotations and enabling factors. For example, the hypothetical `DBLoader` declaration above can be injected with a Spring-configured `DataSource` in the following way: @@ -510,17 +510,17 @@ class DBLoader extends WiringDeclarableSupport implements CacheLoader { By using the JSR-330 annotations, the `CacheLoader` code has been simplified since the location and creation of the `DataSource` has been externalized and the user code is concerned only with the loading process. The `DataSource` might be transactional, created lazily, shared between multiple objects or retrieved from JNDI. -These aspects can easily be configured and changed through the _Spring_ container without touching +These aspects can easily be configured and changed through the Spring container without touching the `DBLoader` code. [[apis:spring-cache-abstraction]] == Support for the Spring Cache Abstraction -_Spring Data for Pivotal GemFire_ provides an implementation of the _Spring_ +Spring Data for {data-store-name} provides an implementation of the Spring http://docs.spring.io/spring/docs/current/spring-framework-reference/htmlsingle/#cache[Cache Abstraction] -to position Pivotal GemFire as a _caching provider_ in Spring's caching infrastructure. +to position {data-store-name} as a _caching provider_ in Spring's caching infrastructure. -To use Pivotal GemFire as a backing implementation, a "_caching provider_" _in Spring's Cache Abstraction_, +To use {data-store-name} as a backing implementation, a "_caching provider_" _in Spring's Cache Abstraction_, simply add `GemfireCacheManager` to your configuration: [source,xml] @@ -550,9 +550,9 @@ NOTE: The `cache-ref` attribute on the `CacheManager` bean definition is not nec is used (i.e. "gemfireCache"), i.e. `` without an explicit ID. When the `GemfireCacheManager` (Singleton) bean instance is declared and declarative caching is enabled -(either in XML with `` or in JavaConfig with _Spring's_ `@EnableCaching` annotation), -the _Spring_ caching annotations (e.g. `@Cacheable`) identify the "caches" that will cache data in-memory -using Pivotal GemFire Regions. +(either in XML with `` or in JavaConfig with Spring's `@EnableCaching` annotation), +the Spring caching annotations (e.g. `@Cacheable`) identify the "caches" that will cache data in-memory +using {data-store-name} Regions. These caches (i.e. Regions) must exist before the caching annotations that use them otherwise an error will occur. diff --git a/src/main/asciidoc/reference/diskstore.adoc b/src/main/asciidoc/reference/diskstore.adoc index 82381f29..80b2de8c 100644 --- a/src/main/asciidoc/reference/diskstore.adoc +++ b/src/main/asciidoc/reference/diskstore.adoc @@ -1,7 +1,7 @@ [[bootstrap:diskstore]] = Configuring a DiskStore -Spring Data for Pivotal GemFire supports `DiskStore` configuration and creation through the `disk-store` element, as the following example shows: +Spring Data for {data-store-name} supports `DiskStore` configuration and creation through the `disk-store` element, as the following example shows: [source,xml] ---- @@ -13,9 +13,9 @@ Spring Data for Pivotal GemFire supports `DiskStore` configuration and creation ---- `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`. +as well as persistent backup for WAN Gateways. Multiple {data-store-name} components may share the same `DiskStore`. Additionally, multiple file system directories may be defined for a single `DiskStore`, as shown in the preceding example. -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] +See {data-store-name}'s documentation for a complete explanation of +{x-data-store-docs}/developing/storing_data_on_disk/chapter_overview.html[Persistence and Overflow] 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 caa6658e..124f32ec 100644 --- a/src/main/asciidoc/reference/function-annotations.adoc +++ b/src/main/asciidoc/reference/function-annotations.adoc @@ -1,22 +1,22 @@ [[function-annotations]] = Annotation Support for Function Execution -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 +Spring Data for {data-store-name} includes annotation support to simplify working with {data-store-name} +{x-data-store-docs}/developing/function_exec/chapter_overview.html[function execution]. +Under the hood, the {data-store-name} API provides classes to implement and register {data-store-name} +{x-data-store-javadoc}/org/apache/geode/cache/execute/Function.html[functions] +that are deployed on {data-store-name} servers, which may then be invoked by other peer member applications or remotely from cache clients. -Functions can execute in parallel, distributed among multiple Pivotal GemFire servers in the cluster, aggregating results +Functions can execute in parallel, distributed among multiple {data-store-name} servers in the cluster, aggregating results with the map-reduce pattern that are sent back to the caller. Functions can also be targeted to run on a single server -or region. The Pivotal GemFire API supports remote execution of functions targeted by using various predefined scopes: +or region. The {data-store-name} API supports remote execution of functions targeted by using various predefined scopes: on region, on members (in groups), on servers, and others. The implementation and execution of remote functions, as with any RPC protocol, requires some boilerplate code. -Spring Data for 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 +Spring Data for {data-store-name}, true to Spring's core value proposition, aims to hide the mechanics of remote function execution +and let you focus on core POJO programming and business logic. To this end, Spring Data for {data-store-name} introduces +annotations to declaratively register the public methods of a POJO class as {data-store-name} functions along with the ability to invoke registered functions (including remotely) by using annotated interfaces. == Implementation Versus Execution @@ -24,26 +24,26 @@ invoke registered functions (including remotely) by using annotated interfaces. There are two separate concerns to address implementation and execution. 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`] +{x-data-store-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`], +{x-data-store-javadoc}/org/apache/geode/cache/execute/ResultSender.html[`ResultsSender`], and other execution context information. The function implementation typically accesses the cache and regions and is registered with the -http://geode.apache.org/releases/latest/javadoc/org/apache/geode/cache/execute/FunctionService.html[`FunctionService`] +{x-data-store-javadoc}/org/apache/geode/cache/execute/FunctionService.html[`FunctionService`] under a unique ID. A cache client application invoking a function does not depend on the implementation. To invoke a function, the application instantiates an -http://geode.apache.org/releases/latest/javadoc/org/apache/geode/cache/execute/Execution.html[`Execution`] +{x-data-store-javadoc}/org/apache/geode/cache/execute/Execution.html[`Execution`] providing the function ID, invocation arguments, and the function target, which defines its scope: region, server, servers, member, or members. If the function produces a result, the invoker uses a -http://geode.apache.org/releases/latest/javadoc/org/apache/geode/cache/execute/ResultCollector.html[`ResultCollector`] +{x-data-store-javadoc}/org/apache/geode/cache/execute/ResultCollector.html[`ResultCollector`] to aggregate and acquire the execution results. In certain cases, a custom `ResultCollector` implementation is required and may be registered with the `Execution`. NOTE: 'Client' and 'Server' are used here in the context of function execution, which may have a different meaning -than client and server in 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 +than client and server in {data-store-name}'s client-server topology. While it is common for an application using a `ClientCache` +to invoke a function on one or more {data-store-name} servers in a cluster, it is also possible to execute functions in a peer-to-peer (P2P) configuration, where the application is a member of the cluster hosting a peer `Cache`. Keep in mind that a peer member cache application is subject to all the constraints of being a peer member of the cluster. @@ -51,7 +51,7 @@ of the cluster. [[function-implementation]] == Implementing a Function -Using Pivotal GemFire APIs, the `FunctionContext` provides a runtime invocation context that includes the client's +Using {data-store-name} APIs, the `FunctionContext` provides a runtime invocation context that includes the client's calling arguments and a `ResultSender` implementation to send results back to the client. Additionally, if the function is executed on a region, the `FunctionContext` is actually an instance of `RegionFunctionContext`, which provides additional information, such as the target region on which the function was invoked, @@ -98,7 +98,7 @@ or the `ResultSender` if you need to control how the results are returned to the === Annotations for Function Implementation The following example shows how SDG's function annotations are used to expose POJO methods -as Pivotal GemFire functions: +as {data-store-name} functions: [source,java] ---- @@ -117,7 +117,7 @@ public class ApplicationFunctions { } ---- -Note that the class itself must be registered as a Spring bean and each Pivotal GemFire Function is annotated +Note that the class itself must be registered as a Spring bean and each {data-store-name} Function is annotated with `@GemfireFunction`. In the preceding example, Spring's `@Component` annotation was used, but you can register the bean by using any method supported by Spring (such as XML configuration or with a Java configuration class when using Spring Boot). This lets the Spring container create an instance of this class and wrap it in a @@ -126,15 +126,15 @@ Spring creates a wrapper instance for each method annotated with `@GemfireFuncti 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 +the `ApplicationContext` with {data-store-name} components, such as the cache and regions. These may be injected into the class if necessary. -Spring creates the wrapper class and registers the functions with Pivotal GemFire's function service. The function ID used +Spring creates the wrapper class and registers the functions with {data-store-name}'s function service. The function ID used to register each function must be unique. By using convention, it defaults to the simple (unqualified) method name. 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. +which correspond to properties defined by {data-store-name}'s +{x-data-store-javadoc}/org/apache/geode/cache/execute/Function.html[`Function`] interface. If the method's return type is `void`, then the `hasResult` property is automatically set to `false`. Otherwise, if the method returns a value, the `hasResult` attributes is set to `true`. @@ -142,7 +142,7 @@ Even for `void` return types, the annotation's `hasResult` attribute can be set 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 +The `PojoFunctionWrapper` implements {data-store-name}'s `Function` interface, binds method parameters, and invokes the target method in its `execute()` method. It also sends the method's return value by using the `ResultSender`. === Batching Results @@ -179,11 +179,11 @@ class ApplicationConfiguration { .. } == Executing a Function A process that invokes a remote function needs to provide the function's ID, calling arguments, the execution target -(`onRegion`, `onServers`, `onServer`, `onMember`, or `onMembers`) and (optionally) a filter set. By using Spring Data for Pivotal GemFire, +(`onRegion`, `onServers`, `onServer`, `onMember`, or `onMembers`) and (optionally) a filter set. By using Spring Data for {data-store-name}, all you need do is define an interface supported by annotations. Spring creates a dynamic proxy for the interface, which uses the `FunctionService` to create an `Execution`, invoke the `Execution`, and (if necessary) coerce the results to the defined return type. This technique is similar to the way -Spring Data for Pivotal GemFire's repository extension works. Thus, some of the configuration and concepts should be familiar. +Spring Data for {data-store-name}'s repository extension works. Thus, some of the configuration and concepts should be familiar. Generally, a single interface definition maps to multiple function executions, one corresponding to each method defined in the interface. @@ -191,11 +191,11 @@ defined in the interface. To support client-side Function execution, the following SDG Function annotations are provided: `@OnRegion`, `@OnServer`, `@OnServers`, `@OnMember`, and `@OnMembers`. These annotations correspond to the `Execution` implementations -provided by Pivotal GemFire's -http://geode.apache.org/releases/latest/javadoc/org/apache/geode/cache/execute/FunctionService.html[`FunctionService`]. +provided by {data-store-name}'s +{x-data-store-javadoc}/org/apache/geode/cache/execute/FunctionService.html[`FunctionService`]. Each annotation exposes the appropriate attributes. These annotations also provide an optional `resultCollector` attribute whose value is the name of a Spring bean implementing the -http://geode.apache.org/releases/latest/javadoc/org/apache/geode/cache/execute/ResultCollector.html[`ResultCollector`] +{x-data-store-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 @@ -283,12 +283,12 @@ The filter argument is optional. The remaining arguments are a variable argument [[function-execution-pdx]] == Function Execution with PDX -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], +When using Spring Data for {data-store-name}'s function annotation support combined with {data-store-name}'s +{x-data-store-docs}/developing/data_serialization/gemfire_pdx_serialization.html[PDX Serialization], there are a few logistical things to keep in mind. -As explained earlier in this section, and by way of example, you should typically define Pivotal GemFire functions by using POJO classes -annotated with Spring Data for Pivotal GemFire +As explained earlier in this section, and by way of example, you should typically define {data-store-name} functions by using POJO classes +annotated with Spring Data for {data-store-name} http://docs.spring.io/spring-data-gemfire/docs/current/api/org/springframework/data/gemfire/function/annotation/package-summary.html[function annotations], as follows: @@ -329,7 +329,7 @@ public enum OrderSource { } ---- -Of course, you can define a function `Execution` interface to call the 'process' Pivotal GemFire server function, as follows: +Of course, you can define a function `Execution` interface to call the 'process' {data-store-name} server function, as follows: [source,java] ---- @@ -344,16 +344,16 @@ Clearly, this `process(..)` `Order` Function is being called from a client-side The same is true when invoking peer-to-peer member functions (such as `@OnMember(s)) between peers in the cluster. Any form of `distribution` requires the data transmitted between client and server (or peers) to be serialized. -Now, if you have configured Pivotal GemFire to use PDX for serialization (instead of Java serialization, for instance) +Now, if you have configured {data-store-name} to use PDX for serialization (instead of Java serialization, for instance) you can also set the `pdx-read-serialized` attribute to `true` in your configuration -of the Pivotal GemFire server(s), as follows: +of the {data-store-name} server(s), as follows: [source,xml] ---- ---- -Alternatively, you can set the `pdx-read-serialized` attribute to `true` for a Pivotal GemFire cache client application, as follows: +Alternatively, you can set the `pdx-read-serialized` attribute to `true` for a {data-store-name} cache client application, as follows: [source,xml] ---- @@ -363,24 +363,24 @@ Alternatively, you can set the `pdx-read-serialized` attribute to `true` for a P 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 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 +{data-store-name} serializes only application domain object types that you have specifically configured (registered) +either by using {data-store-name}'s +{x-data-store-javadoc}/org/apache/geode/pdx/ReflectionBasedAutoSerializer.html[`ReflectionBasedAutoSerializer`], +or specifically (and recommended) by using a "`custom`" {data-store-name} +{x-data-store-javadoc}/org/apache/geode/pdx/PdxSerializer.html[`PdxSerializer`]. If you use +Spring Data for {data-store-name}'s repository extension to Spring Data Common's repository abstraction and infrastructure, +you might even want to consider using Spring Data for {data-store-name}'s http://docs.spring.io/spring-data-gemfire/docs/current/api/org/springframework/data/gemfire/mapping/MappingPdxSerializer.html[`MappingPdxSerializer`], which uses an entity's mapping meta-data to determine data from the application domain object that are serialized to the PDX instance. -What is less than apparent, though, is that Pivotal GemFire automatically handles Java `Enum` types regardless of whether they are +What is less than apparent, though, is that {data-store-name} automatically handles Java `Enum` types regardless of whether they are explicitly configured (that is, registered with a `ReflectionBasedAutoSerializer` using a regex pattern -and the `classes` parameter or are handled by a "`custom`" Pivotal GemFire `PdxSerializer`), despite the fact that Java enumerations +and the `classes` parameter or are handled by a "`custom`" {data-store-name} `PdxSerializer`), despite the fact that Java enumerations implement `java.io.Serializable`. -So, when you set `pdx-read-serialized` to `true` on Pivotal GemFire servers where the Pivotal GemFire functions -(including Spring Data for Pivotal GemFire function-annotated POJO classes) are registered, then you +So, when you set `pdx-read-serialized` to `true` on {data-store-name} servers where the {data-store-name} functions +(including Spring Data for {data-store-name} function-annotated POJO classes) are registered, then you may encounter surprising behavior when invoking the function `Execution`. You might pass the following arguments when invoking the function: @@ -390,7 +390,7 @@ You might pass the following arguments when invoking the function: orderProcessingFunctions.process(new Order(123, customer, Calendar.getInstance(), items), OrderSource.ONLINE, 400); ---- -However, the Pivotal GemFire function on the server gets the following: +However, the {data-store-name} function on the server gets the following: [source,java] ---- @@ -398,19 +398,19 @@ process(regionData, order:PdxInstance, :PdxInstanceEnum, 400); ---- 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]. +{x-data-store-javadoc}/org/apache/geode/pdx/PdxInstance.html[PDX instances]. Again, this all happens because `pdx-read-serialized` is set to `true`, which may be necessary in cases where -the Pivotal GemFire servers interact with multiple different clients (for example, a combination of Java clients and native clients, such as C++, C#, and others). +the {data-store-name} servers interact with multiple different clients (for example, a combination of Java clients and native clients, such as C++, C#, and others). -This flies in the face of Spring Data for Pivotal GemFire's strongly-typed function-annotated POJO class method signatures, +This flies in the face of Spring Data for {data-store-name}'s strongly-typed function-annotated POJO class method signatures, as you should reasonably expect application domain object types, not PDX serialized instances. -Consequently, Spring Data for Pivotal GemFire includes enhanced function support to automatically convert method arguments +Consequently, Spring Data for {data-store-name} includes enhanced function support to automatically convert method arguments type PDX to the desired application domain object types defined by the function method's parameter types. -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: +However, this also requires you to explicitly register a {data-store-name} `PdxSerializer` on the {data-store-name} Servers +where Spring Data for {data-store-name} function-annotated POJOs are registered and used, as the following example shows: [source,java] ---- @@ -419,13 +419,13 @@ where Spring Data for Pivotal GemFire function-annotated POJOs are registered an ---- -Alternatively, you can use Pivotal GemFire's -http://gemfire-90-javadocs.docs.pivotal.io/org/apache/geode/pdx/ReflectionBasedAutoSerializer.html[`ReflectionBasedAutoSerializer`] +Alternatively, you can use {data-store-name}'s +{x-data-store-javadoc}/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, as follows: +Finally, Spring Data for {data-store-name} is careful not to convert your function arguments if you treat your function arguments +generically or as one of {data-store-name}'s PDX types, as follows: [source,java] ---- @@ -435,9 +435,9 @@ public Object genericFunction(String value, Object domainObject, PdxInstanceEnum } ---- -Spring Data for Pivotal GemFire converts PDX type data to the corresponding application domain types if and only if +Spring Data for {data-store-name} converts PDX type data to the corresponding application domain types if and only if the corresponding application domain types are on the classpath and the function-annotated POJO method expects it. -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 +For a good example of custom, composed application-specific {data-store-name} `PdxSerializers` as well as appropriate +POJO function parameter type handling based on the method signatures, see Spring Data for {data-store-name}'s https://github.com/spring-projects/spring-data-gemfire/blob/2.0.0.M2/src/test/java/org/springframework/data/gemfire/function/ClientCacheFunctionExecutionWithPdxIntegrationTest.java[`ClientCacheFunctionExecutionWithPdxIntegrationTest`] class. diff --git a/src/main/asciidoc/reference/function.adoc b/src/main/asciidoc/reference/function.adoc index 2c657909..a209d9e0 100644 --- a/src/main/asciidoc/reference/function.adoc +++ b/src/main/asciidoc/reference/function.adoc @@ -1,17 +1,17 @@ [[bootstrap:function]] = Configuring the Function Service -Spring Data for Pivotal GemFire provides <> support for implementing and registering -Pivotal GemFire Functions. +Spring Data for {data-store-name} provides <> support for implementing and registering +{data-store-name} 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] +Spring Data for {data-store-name} also provides namespace support for registering {data-store-name} +{x-data-store-javadoc}/org/apache/geode/cache/execute/Function.html[functions] for remote function execution. -See Pivotal GemFire's http://geode.apache.org/docs/guide/11/developing/function_exec/chapter_overview.html[documentation] +See {data-store-name}'s {x-data-store-docs}/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` +{data-store-name} Functions are declared as Spring beans and must implement the `org.apache.geode.cache.execute.Function` interface or extend `org.apache.geode.cache.execute.FunctionAdapter`. The namespace uses a familiar pattern to declare functions, as the following example shows: diff --git a/src/main/asciidoc/reference/gateway.adoc b/src/main/asciidoc/reference/gateway.adoc index 4999704d..974f292e 100644 --- a/src/main/asciidoc/reference/gateway.adoc +++ b/src/main/asciidoc/reference/gateway.adoc @@ -1,10 +1,10 @@ [[bootstrap:gateway]] = 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. +WAN Gateways provide a way to synchronize {data-store-name} Distributed Systems across geographic areas. +Spring Data for {data-store-name} provides namespace support for configuring WAN Gateways as illustrated in the following examples. -== WAN Configuration in Pivotal GemFire 7.0 +== WAN Configuration in {data-store-name} 7.0 In the following example, `GatewaySenders` are configured for a `PARTITION` region by adding child elements (`gateway-sender` and `gateway-sender-ref`) to the region. @@ -60,6 +60,6 @@ The `GatewayReceiver` may also be configured with `EventFilters` and `TransportF ---- -See the Pivotal GemFire -http://geode.apache.org/docs/guide/11/topologies_and_comm/multi_site_configuration/chapter_overview.html[documentation] +See the {data-store-name} +{x-data-store-docs}/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 f5757b54..292ccb26 100644 --- a/src/main/asciidoc/reference/gemfire-bootstrap.adoc +++ b/src/main/asciidoc/reference/gemfire-bootstrap.adoc @@ -1,37 +1,37 @@ [[gemfire-bootstrap]] -= Bootstrapping a Spring ApplicationContext in Pivotal GemFire += Bootstrapping a Spring ApplicationContext in {data-store-name} -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 +Normally, a Spring based application <> by using Spring Data for {data-store-name}'s caching features. +By specifying a `` element that uses the Spring Data for {data-store-name} XML namespace, a single embedded {data-store-name} peer `Cache` instance is created and initialized with default settings in the same JVM process as your application. -However, it is sometimes necessary (perhaps as a requirement imposed by your IT organization) that 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 +However, it is sometimes necessary (perhaps as a requirement imposed by your IT organization) that {data-store-name} be fully managed +and operated by the provided {data-store-name} tool suite, perhaps with +{x-data-store-docs}/tools_modules/gfsh/chapter_overview.html[Gfsh]. By using Gfsh, +{data-store-name} bootstraps your Spring application context rather than the other way around. Instead of +an application server or a Java main class that uses Spring Boot, {data-store-name} does the bootstrapping and hosts your application. -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. +NOTE: {data-store-name} is not an application server. In addition, there are limitations to using +this approach where the {data-store-name} cache configuration is concerned. [[gemfire-bootstrap-gfsh]] -== Using Pivotal GemFire to Bootstrap a Spring Context Started with Gfsh +== Using {data-store-name} 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 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. +In order to bootstrap a Spring application context in {data-store-name} when starting a {data-store-name} Server process by using Gfsh, +you must use {data-store-name}'s +{x-data-store-docs}/basic_config/the_cache/setting_cache_initializer.html[initalizer]. +An initializer block can declare a callback application that is launched after the cache is initialized by {data-store-name}. 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, +{x-data-store-docs}/reference/topics/cache_xml.html#initializer[initializer] element by +using a minimal snippet of {data-store-name}'s native `cache.xml`. To bootstrap the Spring application context, the `cache.xml` file is required, in much the same way as a minimal snippet of Spring XML config is needed to bootstrap a Spring application context configured with component scanning (for example ``). 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: +The following example shows a typical yet minimal configuration for this class inside {data-store-name}'s `cache.xml` file: [source,xml] ---- @@ -79,7 +79,7 @@ on the classpath, as the following example shows: ---- Then, with a properly configured and constructed `CLASSPATH` and `cache.xml` file (shown earlier) specified as -a command-line option when starting a Pivotal GemFire Server in Gfsh, the command-line would be as follows: +a command-line option when starting a {data-store-name} Server in Gfsh, the command-line would be as follows: [source] ---- @@ -89,35 +89,35 @@ gfsh>start server --name=Server1 --log-level=config ... ---- 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 +elements. The only limitation with this approach is that a {data-store-name} cache cannot be configured by using +the Spring Data for {data-store-name} namespace. In other words, none of the `` 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 and initialized the cache before the initializer +The reason for this is that {data-store-name} itself has already created and initialized the cache before the initializer gets invoked. As a result, the cache already exists and, since it is a "`singleton`", it cannot be re-initialized or have any of its configuration augmented. [[gemfire-bootstrap-lazywiring]] -== Lazy-wiring Pivotal GemFire Components +== Lazy-wiring {data-store-name} Components -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 +Spring Data for {data-store-name} already provides support for wiring {data-store-name} components (such as `CacheListeners`, +`CacheLoaders`, `CacheWriters` and so on) that are declared and created by {data-store-name} in `cache.xml` by using SDG's `WiringDeclarableSupport` class, as described in <>. However, this works only -when Spring is the one doing the bootstrapping (that is, when Spring bootstraps Pivotal GemFire). +when Spring is the one doing the bootstrapping (that is, when Spring bootstraps {data-store-name}). -When your Spring application context is bootstrapped by Pivotal GemFire, these Pivotal GemFire application components go unnoticed, +When your Spring application context is bootstrapped by {data-store-name}, these {data-store-name} application components go unnoticed, because the Spring application context does not yet exist. The Spring application context does not get created -until Pivotal GemFire calls the initializer block, which only occurs after all the other Pivotal GemFire components and configuration +until {data-store-name} calls the initializer block, which only occurs after all the other {data-store-name} components and configuration have already been created and initialized. 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 +register itself to be configured by the Spring container that is eventually be created by {data-store-name} +once the initializer is called. In essence, this gives your {data-store-name} application components a chance to be configured and auto-wired with Spring beans defined in the Spring application context. -In order for your Pivotal GemFire application components to be auto-wired by the Spring container, you should create an application class +In order for your {data-store-name} application components to be auto-wired by the Spring container, you should create an application class that extends the `LazyWiringDeclarableSupport` and annotate any class member that needs to be provided as a Spring bean dependency, similar to the following example: @@ -134,14 +134,14 @@ public class UserDataSourceCacheLoader extends LazyWiringDeclarableSupport ---- As implied in the `CacheLoader` example above, you might necessarily (though rarely) have defined both -a region and a `CacheListener` component in 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 +a region and a `CacheListener` component in {data-store-name} `cache.xml`. The `CacheLoader` may need access to an application DAO +(or perhaps a JDBC `DataSource` defined in the Spring application context) for loading `Users` into a {data-store-name} `REPLICATE` region on start. 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 +Be careful when mixing the different life-cycles of {data-store-name} and the Spring Container together +in this manner. Not all use cases and scenarios are supported. The {data-store-name} `cache.xml` configuration would be similar to the following (which comes from SDG's test suite): [source,xml] diff --git a/src/main/asciidoc/reference/indexing.adoc b/src/main/asciidoc/reference/indexing.adoc index 6a0e76dd..0ccfe7d1 100644 --- a/src/main/asciidoc/reference/indexing.adoc +++ b/src/main/asciidoc/reference/indexing.adoc @@ -1,19 +1,19 @@ [[bootstrap:indexing]] = Configuring an Index -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. +{data-store-name} allows indexes (also sometimes pluralized as indices) to be created on region data to improve the performance of OQL (Object Query Language) queries. -In Spring Data for Pivotal GemFire (SDG), indexes are declared with the `index` element, as the following example shows: +In Spring Data for {data-store-name} (SDG), indexes are declared with the `index` element, as the following example shows: [source,xml] ---- ---- -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 +In Spring Data for {data-store-name}'s XML schema (also called the SDG namespace), `index` bean declarations are not bound to a region, +unlike {data-store-name}'s native `cache.xml`. Rather, they are top-level elements similar to `<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. +significant improvement over {data-store-name}'s native `cache.xml` format. An `Index` must have a name. You can give the `Index` an explicit name by using the `name` attribute. Otherwise, the bean name (that is, the value of the `id` attribute) of the `index` bean definition is used as @@ -69,29 +69,29 @@ Therefore, you might want to create an `Index` with a statement similar to the f ---- 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. +This is not specific to Spring Data Pivotal GemFir. It is a feature of {data-store-name}. -The `index` `type` may be one of three enumerated values defined by Spring Data for Pivotal GemFire's +The `index` `type` may be one of three enumerated values defined by Spring Data for {data-store-name}'s http://docs.spring.io/spring-data-gemfire/docs/current/api/org/springframework/data/gemfire/IndexType.html[`IndexType`] enumeration: `FUNCTIONAL`, `HASH`, and `PRIMARY_KEY`. -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`] +Each of the enumerated values corresponds to one of the {x-data-store-javadoc}/org/apache/geode/cache/query/QueryService.html[`QueryService`] `create[|Key|Hash]Index` methods invoked when the actual `index` is to be created (or "`defined`" -- you can find more on "`defining`" indexes in the next section). For instance, if the `IndexType` is `PRIMARY_KEY`, then the -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(..)] +{x-data-store-javadoc}/org/apache/geode/cache/query/QueryService.html#createKeyIndex-java.lang.String-java.lang.String-java.lang.String-[QueryService.createKeyIndex(..)] is invoked to create a `KEY` `Index`. The default is `FUNCTIONAL` and results in one of the `QueryService.createIndex(..)` methods being invoked. -See the Spring Data for Pivotal GemFire XML schema for a full set of options. +See the Spring Data for {data-store-name} 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]`" -in Pivotal GemFire's User Guide. +For more information on indexing in {data-store-name}, see "`http://gemfire90.docs.pivotal.io/geode/developing/query_index/query_index.html[Working with Indexes]`" +in {data-store-name}'s User Guide. == Defining Indexes -In addition to creating Indexes up front as `ndex` bean definitions are processed by Spring Data for Pivotal GemFire +In addition to creating Indexes up front as `ndex` bean definitions are processed by Spring Data for {data-store-name} on Spring container initialization, you may also define all of your application indexes prior to creating them by using the `define` attribute, as follows: @@ -102,9 +102,9 @@ them by using the `define` attribute, as follows: When `define` is set to `true` (it defaults to `false`), it does not actually create the `Index` at that moment. All "`defined`" Indexes are created all at once, when the Spring `ApplicationContext` is "`refreshed`" or, to put it differently, -when a `ContextRefreshedEvent` is published by the Spring container. Spring Data for 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()`]. +when a `ContextRefreshedEvent` is published by the Spring container. Spring Data for {data-store-name} registers itself as +an `ApplicationListener` listening for the `ContextRefreshedEvent`. When fired, Spring Data for {data-store-name} calls +{x-data-store-javadoc}/org/apache/geode/cache/query/QueryService.html#createDefinedIndexes[`QueryService.createDefinedIndexes()`]. Defining indexes and creating them all at once boosts speed and efficiency when creating indexes. @@ -113,34 +113,34 @@ for more details. == `IgnoreIfExists` and `Override` -Two Spring Data for Pivotal GemFire `Index` configuration options warrant special mention: `ignoreIfExists` and `override`. +Two Spring Data for {data-store-name} `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 {data-store-name}'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 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. Pivotal GemFire has no equivalent options or functionality. +NOTE: These options are only available in Spring Data for {data-store-name} and exist to workaround known limitations +with {data-store-name}. {data-store-name} has no equivalent options or functionality. -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 +Each option significantly differs in behavior and entirely depends on the type of {data-store-name} `Index` exception thrown. +This also means that neither option has any effect if a {data-store-name} Index-type exception is not thrown. These options +are meant to specifically handle {data-store-name} `IndexExistsException` and `IndexNameConflictException` instances, which can occur for various, sometimes obscure reasons. The exceptions have the following causes: -* An http://gemfire-90-javadocs.docs.pivotal.io/org/apache/geode/cache/query/IndexExistsException.html[`IndexExistsException`] +* An {x-data-store-javadoc}/org/apache/geode/cache/query/IndexExistsException.html[`IndexExistsException`] is thrown when there exists another `Index` with the same definition but a different name when attempting to create an `Index`. -* An http://gemfire-90-javadocs.docs.pivotal.io/org/apache/geode/cache/query/IndexNameConflictException.html[`IndexNameConflictException`] +* An {x-data-store-javadoc}/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_ are "`handled`" +Spring Data for {data-store-name}'s default behavior is to fail-fast, always. So, neither `Index` _Exception_ are "`handled`" by default. These `Index` exceptions are wrapped in a SDG `GemfireIndexException` and rethrown. If you wish -for Spring Data for Pivotal GemFire to handle them for you, you can set either of these `Index` bean definition options to `true`. +for Spring Data for {data-store-name} to handle them for you, you can set either of these `Index` bean definition options to `true`. `IgnoreIfExists` always takes precedence over `Override`, primarily because it uses fewer resources (because it returns the "`existing`" `index` in both exceptional cases). @@ -152,11 +152,11 @@ then the `index` that would have been created by this `index` bean definition or and the existing `Index` is returned. There is little consequence in returning the existing `index`, since the `Index` definition is the same, -as determined by Pivotal GemFire itself, not SDG. +as determined by {data-store-name} itself, not SDG. 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()`]). +actually exists from {data-store-name}'s perspective (that is, with +{x-data-store-javadoc}/org/apache/geode/cache/query/QueryService.html#getIndexes[`QueryService.getIndexes()`]). Therefore, you should be careful when writing OQL query statements that use query hints, especially hints that refer to the application `Index` being ignored. Those query hints need to be changed. @@ -173,7 +173,7 @@ this might not be the case. Consequently, you should verify your index names. NOTE: SDG makes a best effort to inform the user when the `Index` being ignored is significantly different in its definition from the existing `Index`. However, in order for SDG to accomplish this, it must be able to find -the existing `Index`, which is looked up by using the Pivotal GemFire API (the only means available). +the existing `Index`, which is looked up by using the {data-store-name} API (the only means available). === `Override` Behavior @@ -182,7 +182,7 @@ When an `IndexExistsException` is thrown and `override` is set to `true` (or `&l the `Index` is effectively renamed. Remember, `IndexExistsExceptions` are thrown when multiple indexes exist that have the same definition but different names. -Spring Data for Pivotal GemFire can only accomplish this by using Pivotal GemFire's API, by first removing the existing `Index` +Spring Data for {data-store-name} can only accomplish this by using {data-store-name}'s API, by first removing the existing `Index` and then recreating the `index` with the new name. It is possible that either the remove or subsequent create invocation could fail. There is no way to execute both actions atomically and rollback this joint operation if either fails. @@ -197,7 +197,7 @@ is thrown. If so, SDG is smart and returns the existing Index as is, even on `override`. There is no harm in this behavior, since both the name and the definition are exactly the same. Of course, SDG can only accomplish this when -SDG is able to find the existing `Index`, which is dependent on Pivotal GemFire's APIs. If it cannot be found, +SDG is able to find the existing `Index`, which is dependent on {data-store-name}'s APIs. If it cannot be found, nothing happens and a SDG `GemfireIndexException` is thrown that wraps the `IndexNameConflictException`. However, when the definition of the existing `Index` is different, SDG attempts to re-create the `Index` by @@ -207,31 +207,31 @@ and make sure the `Index` definition matches your expectations and application r === 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 (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 +multiple configuration sources are used to configure {data-store-name} (Spring Data for {data-store-name}, {data-store-name} Cluster Config, +{data-store-name} native `cache.xml`, the API, and so on). You should definitely prefer one configuration method and stick with it. However, when does an `IndexNameConflictException` get thrown? One particular case is an `Index` defined on a `PARTITION` region (PR). When an `Index` is defined on -a `PARTITION` region (for example, `X`), Pivotal GemFire distributes the `Index` definition (and name) to other peer members +a `PARTITION` region (for example, `X`), {data-store-name} distributes the `Index` definition (and name) to other peer members in the cluster that also host the same `PARTITION` region (that is, "X"). The distribution of this `Index` definition to and subsequent creation of this `Index` by peer members on a need-to-know basis (that is, those hosting the same PR) is performed asynchronously. -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)`]. +During this window of time, it is possible that these pending PR `Indexes` cannot be identified by {data-store-name} -- +such as with a call to {x-data-store-javadoc}/org/apache/geode/cache/query/QueryService.html#getIndexes[`QueryService.getIndexes()`] +with {x-data-store-javadoc}/org/apache/geode/cache/query/QueryService.html#getIndexes-org.apache.geode.cache.Region[`QueryService.getIndexes(:Region)`], +or even with {x-data-store-javadoc}/org/apache/geode/cache/query/QueryService.html#getIndex-org.apache.geode.cache.Region-java.lang.String[`QueryService.getIndex(:Region, indexName:String)`]. -As a result, the only way for SDG or other Pivotal GemFire cache client applications (not involving Spring) to know for sure +As a result, the only way for SDG or other {data-store-name} cache client applications (not involving Spring) to know for sure is to attempt to create the `Index`. If it fails with either an `IndexNameConflictException` or even an `IndexExistsException`, the application knows there is a problem. This is because the `QueryService` `Index` creation waits on -pending `Index` definitions, whereas the other Pivotal GemFire API calls do not. +pending `Index` definitions, whereas the other {data-store-name} API calls do not. In any case, SDG makes a best effort and attempts to inform you what has happened or is happening and tell you -the corrective action. Given that all 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. +the corrective action. Given that all {data-store-name} `QueryService.createIndex(..)` methods are synchronous, blocking operations, +the state of {data-store-name} should be consistent and accessible after either of these index-type exceptions are thrown. Consequently, SDG can inspect the state of the system and act accordingly, based on your configuration. In 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 20752464..2264097a 100644 --- a/src/main/asciidoc/reference/introduction.adoc +++ b/src/main/asciidoc/reference/introduction.adoc @@ -1,29 +1,30 @@ [[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 {data-store-name}: * <> describes the configuration support provided for configuring, initializing, and accessing -Pivotal GemFire caches, regions, and related distributed system components. +{data-store-name} 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 {data-store-name} APIs and the various data access features +available in Spring, such as template-based data access, exception translation, transaction management, and caching. -* <> describes enhancements to Pivotal GemFire's serialization and deserialization of managed objects. +* <> describes enhancements to {data-store-name}'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 {data-store-name} using Spring Data. * <> describes how to create and use Spring Data Repositories to access data -stored in Pivotal GemFire by using basic CRUD and simple query operations. +stored in {data-store-name} by using basic CRUD and simple query operations. -* <> describes how to create and use Pivotal GemFire functions by using annotations +* <> describes how to create and use {data-store-name} 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 (Object Query Language) query. +* <> describes how to use {data-store-name}'s Continuous Query (CQ) functionality +to process a stream of events based on interest defined and registered using {data-store-name}'s +OQL (Object Query Language) query. -* <> describes how to bootstrap a Spring `ApplicationContext` running in an Pivotal GemFire server -by using `Gfsh`. +* <> describes how to bootstrap a Spring `ApplicationContext` running in an {data-store-name} server +using `Gfsh`. * <> describes the examples provided with the distribution to illustrate the various features -available in Spring Data for Pivotal GemFire. +available in Spring Data for {data-store-name}. diff --git a/src/main/asciidoc/reference/lucene.adoc b/src/main/asciidoc/reference/lucene.adoc index f97b2607..838fbec0 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 let you -index and search on data stored in Pivotal GemFire by using Lucene queries. Search-based queries also include +{x-data-store-website}[{data-store-name}] integrates with http://lucene.apache.org/[Apache Lucene] to let you +index and search on data stored in {data-store-name} by using Lucene queries. Search-based queries also include the ability to page through query results. -Additionally, Spring Data for Pivotal GemFire adds support for query projections based on the Spring Data Commons +Additionally, Spring Data for {data-store-name} adds support for query projections based on the Spring Data Commons projection infrastructure. This feature lets the query results be projected into first-class application domain types as needed by the application use case. 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: +can be created in Spring (Data for {data-store-name}) XML config as follows: [source,xml] ---- @@ -40,8 +40,8 @@ and can be configured as shown in the following example: The `Map` can be specified as a top-level bean definition and referenced by using the `ref` attribute in the nested `` element, as follows: ``. -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`] +Spring Data for {data-store-name}'s `LuceneIndexFactoryBean` API and SDG's XML namespace also let a +{x-data-store-javadoc}/org/apache/geode/cache/lucene/LuceneSerializer.html[`org.apache.geode.cache.lucene.LuceneSerializer`] be specified when you create the `LuceneIndex`. The `LuceneSerializer` lets you configure the way objects are converted to Lucene documents for the index when the object is indexed. @@ -74,7 +74,7 @@ inside a `@Configuration` class, as the following example shows: ---- @Bean(name = "Books") @DependsOn("bookTitleIndex") -PartitionedRegionFactoryBean booksRegion(Pivotal GemFireCache gemfireCache) { +PartitionedRegionFactoryBean booksRegion(GemFireCache gemfireCache) { PartitionedRegionFactoryBean peopleRegion = new PartitionedRegionFactoryBean<>(); @@ -87,7 +87,7 @@ PartitionedRegionFactoryBean booksRegion(Pivotal GemFireCache gemfir } @Bean -LuceneIndexFactoryBean bookTitleIndex(Pivotal GemFireCache gemFireCache, +LuceneIndexFactoryBean bookTitleIndex(GemFireCache gemFireCache, LuceneSerializer luceneSerializer) { LuceneIndexFactoryBean luceneIndex = new LuceneIndexFactoryBean(); @@ -106,20 +106,20 @@ CustomLuceneSerializer myLuceneSerialier() { } ---- -There are a few limitations of Pivotal GemFire's, Apache Lucene integration and support. +There are a few limitations of {data-store-name}'s, Apache Lucene integration and support. -First, a `LuceneIndex` can only be created on a Pivotal GemFire `PARTITION` Region. +First, a `LuceneIndex` can only be created on a {data-store-name} `PARTITION` Region. Second, all `LuceneIndexes` must be created before the region to which the `LuceneIndex` applies. 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`] +You may register this Spring {spring-framework-javadoc}/org/springframework/beans/factory/config/BeanFactoryPostProcessor.html[`BeanFactoryPostProcessor`] 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]. +More details about Spring's `BeanFactoryPostProcessors` can be found {spring-framework-docs}/core.html#beans-factory-extension-factory-postprocessors[here]. -It is possible that these Pivotal GemFire restrictions will not apply in a future release which is why +It is possible that these {data-store-name} restrictions will not apply in a future release which is why the SDG `LuceneIndexFactoryBean` API takes a reference to the region directly as well, rather than just the region path. This is more ideal when you want to define a `LuceneIndex` on an existing region @@ -136,11 +136,11 @@ Now that we have a `LuceneIndex`, we can perform Lucene-based data access operat == Lucene Template Data Accessors -Spring Data for Pivotal GemFire provides two primary templates for Lucene data access operations, depending on +Spring Data for {data-store-name} provides two primary templates for Lucene data access operations, depending on how low of a level your application is prepared to deal with. -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: +The `LuceneOperations` interface defines query operations by using {data-store-name} +{x-data-store-javadoc}/org/apache/geode/cache/lucene/package-summary.html[Lucene types], which are defined in the following interface definition: [source,java] ---- @@ -170,18 +170,18 @@ public interface LuceneOperations { NOTE: The `[, int resultLimit]` indicates that the `resultLimit` parameter is optional. -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` +The operations in the `LuceneOperations` interface match the operations provided by the {data-store-name}'s +{x-data-store-javadoc}/org/apache/geode/cache/lucene/LuceneQuery.html[LuceneQuery] interface. +However, SDG has the added value of translating proprietary {data-store-name} or Apache Lucene `Exceptions` 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 occur. +introduced by the underlying {data-store-name} or Apache Lucene APIs when they occur. -However, it would be sad to offer a Lucene Data Access Object (DAO) that only uses Pivotal GemFire -and Apache Lucene data types (such as 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 {data-store-name} +and Apache Lucene data types (such as {data-store-name}'s `LuceneResultStruct`). Therefore, SDG gives you the `ProjectingLuceneOperations` interface to remedy these important application concerns. The following listing shows the `ProjectingLuceneOperations` interface definition: @@ -244,7 +244,7 @@ If I define the following `LuceneIndex`... [source,java] ---- @Bean -LuceneIndexFactoryBean personLastNameIndex(Pivotal GemFireCache gemfireCache) { +LuceneIndexFactoryBean personLastNameIndex(GemFireCache gemfireCache) { LuceneIndexFactoryBean personLastNameIndex = new LuceneIndexFactoryBean(); @@ -291,8 +291,8 @@ You can use `setProjectionFactory(:ProjectionFactory)` to set a custom `Projecti == Annotation Configuration Support -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 +Finally, Spring Data for {data-store-name} provides annotation configuration support for `LuceneIndexes`. +Eventually, the SDG Lucene support finds its way into the repository infrastructure extension for {data-store-name} so that Lucene queries can be expressed as methods on an application `Repository` interface, in much the same way as the http://docs.spring.io/spring-data-gemfire/docs/current/reference/html/#gemfire-repositories.executing-queries[OQL support] works today. @@ -333,7 +333,7 @@ class ApplicationConfiguration { } ---- -NOTE: `LuceneIndexes` can be created only on Apache Geode Servers since `LuceneIndexes` only apply +NOTE: `LuceneIndexes` can be created only on {data-store-name} Servers since `LuceneIndexes` only apply to `PARTITION` Regions. Given our earlier definition of the `Person` class, the SDG annotation configuration support diff --git a/src/main/asciidoc/reference/mapping.adoc b/src/main/asciidoc/reference/mapping.adoc index 07cadaf2..3cd61fec 100644 --- a/src/main/asciidoc/reference/mapping.adoc +++ b/src/main/asciidoc/reference/mapping.adoc @@ -10,10 +10,10 @@ This section covers: [[mapping.entities]] == Entity Mapping -Spring Data for Pivotal GemFire provides support to map entities that are stored in a region in the Geode In-Memory Data Grid. +Spring Data for {data-store-name} provides support to map entities that are stored in a region in the Geode In-Memory Data Grid. The mapping metadata is defined by using annotations on application domain classes, as the following example shows: -.Mapping a domain class to a Pivotal GemFire Region +.Mapping a domain class to a {data-store-name} Region ==== [source,java] ---- @@ -57,17 +57,17 @@ 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 by +Be sure to use the full path of the {data-store-name} region, as defined with the Spring Data for {data-store-name} XML namespace by using the `id` or `name` attributes of the `<*-region>` element. [[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 +In addition to the `@Region` annotation, Spring Data for {data-store-name} also recognizes the region type-specific mapping annotations: `@ClientRegion`, `@LocalRegion`, `@PartitionRegion`, and `@ReplicateRegion`. 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 +mapping infrastructure. However, these additional mapping annotations are useful in Spring Data for {data-store-name}'s annotation configuration model. When combined with the `@EnableEntityDefinedRegions` configuration annotation on a Spring `@Configuration` annotated class, it is possible to generate regions in the local cache, whether the application is a client or peer. @@ -86,7 +86,7 @@ As an alternative to specifying the region in which the entity is stored by usin on the entity class, you can also specify the `@Region` annotation on the entity's `Repository`. See <> for more details. -However, suppose you want to store a `Person` record in multiple Pivotal GemFire Regions (for example, `People` and `Customers`). +However, suppose you want to store a `Person` record in multiple {data-store-name} Regions (for example, `People` and `Customers`). Then you can define your corresponding `Repository` interface extensions as follows: [source,java] @@ -102,7 +102,7 @@ public interface CustomerRepository extends GemfireRepository { } ---- -Then, using each Repository individually, you can store the entity in multiple Pivotal GemFire Regions, as the following example shows: +Then, using each Repository individually, you can store the entity in multiple {data-store-name} Regions, as the following example shows: [source,java] ---- @@ -126,8 +126,8 @@ 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 {data-store-name} provides a custom +{x-data-store-javadoc}/org/apache/geode/pdx/PdxSerializer.html[`PdxSerializer`] implementation that uses the mapping information to customize entity serialization. It also lets you customize entity instantiation by using the Spring Data `EntityInstantiator` abstraction. @@ -137,7 +137,7 @@ explicitly annotated with `@PersistenceConstructor`). To provide arguments for constructor parameters, the serializer reads fields with the named constructor parameter, explicitly specified using Spring's `@Value` annotation, from the supplied -http://gemfire-95-javadocs.docs.pivotal.io/org/apache/geode/pdx/PdxReader.html[`PdxReader`], as shown in the following example: +{x-data-store-javadoc}/org/apache/geode/pdx/PdxReader.html[`PdxReader`], as shown in the following example: .Using `@Value` on entity constructor parameters ==== @@ -156,10 +156,10 @@ An entity class annotated in this way has the `thing` field read from the `PdxRe for the constructor parameter, `firstname`. The value for `lastName` is a Spring bean with the name `bean`. In addition to the custom instantiation logic and strategy provided by `EntityInstantiators`, -the `MappingPdxSerializer` also provides capabilities beyond Pivotal GemFire's own -http://gemfire-95-javadocs.docs.pivotal.io/org/apache/geode/pdx/ReflectionBasedAutoSerializer.html[`ReflectionBasedAutoSerializer`]. +the `MappingPdxSerializer` also provides capabilities beyond {data-store-name}'s own +{x-data-store-javadoc}/org/apache/geode/pdx/ReflectionBasedAutoSerializer.html[`ReflectionBasedAutoSerializer`]. -While Pivotal GemFire's `ReflectionBasedAutoSerializer` conveniently uses Java reflection to populate entities and +While {data-store-name}'s `ReflectionBasedAutoSerializer` conveniently uses Java reflection to populate entities and uses regular expressions to identify types that should be handled (serialized and deserialized) by the `ReflectionBasedAutoSerializer`, it cannot, unlike `MappingPdxSerializer`, perform the following: @@ -240,10 +240,10 @@ 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 +Like {data-store-name}'s `ReflectionBasedAutoSerializer`, SDG's `MappingPdxSerializer` is also able to determine the identifier of the entity. However, `MappingPdxSerializer` does so by using Spring Data's mapping metadata, specifically by finding the entity property designated as the identifier by using Spring Data's -https://docs.spring.io/spring-data/commons/docs/current/api/org/springframework/data/annotation/Id.html[`@Id`] annotation. +{spring-data-commons-javadoc}/org/springframework/data/annotation/Id.html[`@Id`] annotation. For example: @@ -259,7 +259,7 @@ class Customer { ---- 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)`] +{x-data-store-javadoc}/org/apache/geode/pdx/PdxWriter.html#markIdentityField-java.lang.String-[`PdxWriter.markIdentifierField(:String)`] when the `PdxSerializer.toData(..)` method is called during serialization. [[mapping.pdx-serializer.read-only-properties]] @@ -304,12 +304,12 @@ If you want the field or property to always be written, you can define a setter. Likewise, what happens when your entity defines `transient` properties? You would expect the `transient` fields or properties of your entity not to be serialized to the stream of PDX bytes -when serializing entity. That is exactly what happens, unlike Pivotal GemFire's own +when serializing entity. That is exactly what happens, unlike {data-store-name}'s own `ReflectionBasedAutoSerializer`, which serializes everything accessible from the object through Java reflection. 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-commons-javadoc}/org/springframework/data/annotation/Transient.html[`@Transient`] Spring Data annotation on either fields or properties. For example, you might define an entity with transient fields and properties as follows: @@ -342,10 +342,10 @@ Neither the `Process` `id` field nor the readable `hostname` property are writte [[mapping.pdx-serializer.type-filtering]] === Filtering by Class types -Similar to Pivotal GemFire's `ReflectionBasedAutoSerializer`, SDG's `MappingPdxSerializer` lets you filter +Similar to {data-store-name}'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 +However, unlike {data-store-name}'s `ReflectionBasedAutoSerializer`, which uses complex regular expressions to express which types the serializer handles, SDG's `MappingPdxSerializer` uses the much more robust 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. diff --git a/src/main/asciidoc/reference/region.adoc b/src/main/asciidoc/reference/region.adoc index c9b73426..24d14fc4 100644 --- a/src/main/asciidoc/reference/region.adoc +++ b/src/main/asciidoc/reference/region.adoc @@ -6,7 +6,7 @@ extending `java.util.Map` and enables basic data access using familiar key-value is wired into application classes that require it so the actual Region type is decoupled from the programming model. Typically, each Region is associated with one domain object, similar to a table in a relational database. -Pivotal GemFire implements the following types of Regions: +{data-store-name} implements the following types of Regions: * *REPLICATE* - Data is replicated across all cache members that define the Region. This provides very high read performance but writes take longer to perform the replication. @@ -19,13 +19,13 @@ Local updates are synchronized to the cache server. Also, a client Region may su stay up-to-date (synchronized) with changes originating from remote processes that access the same server Region. For more information about the various Region types and their capabilities as well as configuration options, -please refer to Pivotal GemFire's documentation on -http://geode.apache.org/docs/guide/11/developing/region_options/region_types.html[Region Types]. +please refer to {data-store-name}'s documentation on +{x-data-store-docs}/developing/region_options/region_types.html[Region Types]. [[bootstrap:region:lookup]] == Using an externally configured Region -To reference Regions already configured in a Pivotal GemFire native `cache.xml` file, use the `lookup-region` element. +To reference Regions already configured in a {data-store-name} native `cache.xml` file, use the `lookup-region` element. Simply declare the target Region name with the `name` attribute. For example, to declare a bean definition identified as `ordersRegion` for an existing Region named `Orders`, you can use the following bean definition: @@ -61,7 +61,7 @@ the region semantics or setup infrastructure. [[bootstrap:region:lookup:auto]] == Auto Region Lookup -"`auto-lookup`" lets you import all regions defined in a Pivotal GemFire native `cache.xml` file into a Spring +"`auto-lookup`" lets you import all regions defined in a {data-store-name} native `cache.xml` file into a Spring application context when you use the `cache-xml-location` attribute on the `` element. For instance, consider the following `cache.xml` file: @@ -97,12 +97,12 @@ by using the following: ---- -Spring Data for Pivotal GemFire automatically creates beans for all Pivotal GemFire regions defined in `cache.xml` that have not been +Spring Data for {data-store-name} automatically creates beans for all {data-store-name} regions defined in `cache.xml` that have not been explicitly added to the Spring context with explicit `` 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 {data-store-name} uses a Spring http://docs.spring.io/spring/docs/current/javadoc-api/org/springframework/beans/factory/config/BeanPostProcessor.html[BeanPostProcessor] -to post-process the cache after it is both created and initialized to determine the regions defined in Pivotal GemFire to add +to post-process the cache after it is both created and initialized to determine the regions defined in {data-store-name} to add as beans in the Spring application context. You may inject these "`auto-looked-up`" regions as you would any other bean defined in the Spring application context, with @@ -137,21 +137,21 @@ If you declarE your components by using Spring XML config, then you would do the ---- -Doing so ensures that the Pivotal GemFire cache and all the regions defined in `cache.xml` get created before any components +Doing so ensures that the {data-store-name} cache and all the regions defined in `cache.xml` get created before any components with auto-wire references when using the new `` element. [[bootstrap:region:overview]] == Configuring Regions -Spring Data for Pivotal GemFire provides comprehensive support for configuring any type of Region through the following elements: +Spring Data for {data-store-name} provides comprehensive support for configuring any type of Region through the following elements: * LOCAL Region: `` * PARTITION Region: `` * REPLICATE Region: `` * Client Region: `` -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 {data-store-name} documentation for a comprehensive description of +{x-data-store-docs}/developing/region_options/region_types.html[region types]. [[bootstrap:region:attributes]] === Common Region Attributes @@ -166,8 +166,8 @@ The following table lists the attributes available for all region types: | Description | cache-ref -| Pivotal GemFire Cache bean reference -| The name of the bean defining the Pivotal GemFire Cache (by default, 'gemfireCache'). +| {data-store-name} Cache bean reference +| The name of the bean defining the {data-store-name} Cache (by default, 'gemfireCache'). | cloning-enabled | boolean (default: `false`) @@ -182,7 +182,7 @@ The following table lists the attributes available for all region types: | 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]. +| See {data-store-name}'s {x-data-store-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 @@ -234,7 +234,7 @@ The following table lists the attributes available for all region types: | 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 +| See {x-data-store-javadoc}/org/apache/geode/cache/RegionShortcut.html | The `RegionShortcut` for this region. Allows easy initialization of the region based on pre-defined defaults. | statistics @@ -255,7 +255,7 @@ The following table lists the attributes available for all region types: `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. +{x-data-store-javadoc}/org/apache/geode/cache/CacheListener.html[`CacheListener`] interface. A region may have multiple listeners, declared with the `cache-listener` element nested in the containing `*-region` element. @@ -298,7 +298,7 @@ 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 +The `cache-listener` element is an example of a common pattern used in the namespace anywhere {data-store-name} provides a callback interface to be implemented in order to invoke custom code in response to Cache or Region events. 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 @@ -312,11 +312,11 @@ configuration example. === CacheLoaders and CacheWriters Similar to `cache-listener`, the namespace provides `cache-loader` and `cache-writer` elements to register -these Pivotal GemFire components for a region. +these {data-store-name} components for a region. A `CacheLoader` is invoked on a cache miss to let an entry be loaded from an external data source, such as a database. A `CacheWriter` is invoked before an entry is created or updated, to allow the entry to be synchronized to -an external data source. The difference is that Pivotal GemFire supports, at most, a single instance `CacheLoader` and `CacheWriter` +an external data source. The difference is that {data-store-name} supports, at most, a single instance `CacheLoader` and `CacheWriter` per region. However, either declaration style may be used. The following example declares a region with both a `CacheLoader` and a `CacheWriter`: @@ -339,14 +339,14 @@ The following example declares a region with both a `CacheLoader` and a `CacheWr ---- -See http://geode.apache.org/releases/latest/javadoc/org/apache/geode/cache/CacheLoader.html[`CacheLoader`] -and http://geode.apache.org/releases/latest/javadoc/org/apache/geode/cache/CacheWriter.html[`CacheWriter`] -in the Pivotal GemFire documentation for more details. +See {x-data-store-javadoc}/org/apache/geode/cache/CacheLoader.html[`CacheLoader`] +and {x-data-store-javadoc}/org/apache/geode/cache/CacheWriter.html[`CacheWriter`] +in the {data-store-name} documentation for more details. [[bootstrap:region:compression]] == Compression -Pivotal GemFire Regions may also be compressed in order to reduce JVM memory consumption and pressure to possibly avoid +{data-store-name} Regions may also be compressed in order to reduce JVM memory consumption and pressure to possibly avoid stopping the global GCs. When you enable compression for a region, all values stored in memory for the region are compressed, while keys and indexes remain uncompressed. New values are compressed when put into the region and all values are decompressed automatically when read back from the region. Values are not compressed when @@ -365,17 +365,17 @@ The following example shows a region with compression enabled: ---- -See Pivotal GemFire's documentation for more information on -http://gemfire.docs.pivotal.io/geode/managing/region_compression/region_compression.html[region compression]. +See {data-store-name}'s documentation for more information on +{x-data-store-docs}/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 {data-store-name} also supports subregions, allowing regions to be arranged in a hierarchical relationship. -For example, Pivotal GemFire allows for a (for example) `/Customer/Address` region and a different `/Employee/Address` region. Additionally, +For example, {data-store-name} allows for a (for example) `/Customer/Address` region and a different `/Employee/Address` region. Additionally, a subregion may have its own subregions and its own configuration. A subregion does not inherit attributes from -the parent region. Regions types may be mixed and matched subject to Pivotal GemFire constraints. A subregion is naturally +the parent region. Regions types may be mixed and matched subject to {data-store-name} constraints. A subregion is naturally declared as a child element of a region. The subregion's name attribute is the simple name. The preceding example might be configured as follows: @@ -400,11 +400,11 @@ 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 +Spring Data for {data-store-name} also supports region templates. This feature allows developers to define common region configuration settings and attributes once and reuse the configuration among many region bean definitions declared in the Spring application context. -Spring Data for Pivotal GemFire includes five Region template tags in its namespace: +Spring Data for {data-store-name} includes five Region template tags in its namespace: [cols="1,2", options="header"] .Region Template Tags @@ -482,7 +482,7 @@ Attributes and sub-elements defined in subsequent, inherited region bean definit === How Templating Works -Spring Data for Pivotal GemFire applies region templates when the Spring application context configuration meta-data is parsed, +Spring Data for {data-store-name} applies region templates when the Spring application context configuration meta-data is parsed, and therefore, the region templates must be declared in the order of inheritance. In other words, parent templates must be defined before child templates. Doing so ensures that the proper configuration is applied, especially when element attributes or sub-elements are overridden. @@ -496,14 +496,14 @@ NOTE: Region Templates are single-inheritance. === 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 +and `client-region` elements in the Spring Data for {data-store-name} XML namespace was to perform a lookup first before attempting to create a Region. This was done in case the region already existed, which would be the case -if the region was defined in an imported Pivotal GemFire native `cache.xml` configuration file. Therefore, the lookup +if the region was defined in an imported {data-store-name} native `cache.xml` configuration file. Therefore, the lookup was performed first to avoid any errors. This was by design and subject to change. This behavior has been altered and the default behavior is now to create the region first. If the region 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 +`CREATE TABLE IF NOT EXISTS ...` DDL syntax, the Spring Data for {data-store-name} `<*-region>` namespace elements now include a `ignore-if-exists` attribute, which reinstates the old behavior by first performing a lookup of an existing region identified by name. If an existing region is found by name if and `ignore-if-exists` is set to `true`, then the region bean definition defined in the Spring configuration is ignored. @@ -519,7 +519,7 @@ by the application. Even worse, you might want to define the region as a distrib 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 {data-store-name} `cache.xml` configuration file: [source,xml] ---- @@ -609,9 +609,9 @@ The Region beans defined in the Spring application context consist of the follow 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. +{data-store-name} is flexible in referencing both parent regions and subregions with or without the leading forward slash. For example, the parent can be referenced as `/Customers` or `Customers` and the child as `/Customers/Accounts` -or `Customers/Accounts`. However, Spring Data Pivotal GemFire is very specific when it comes to naming beans after regions. It +or `Customers/Accounts`. However, Spring Data {data-store-name} is very specific when it comes to naming beans after regions. It always uses the forward slash (/) to represent subregions (for example, `/Customers/Accounts`). Therefore, you should use the nested `lookup-region` syntax shown earlier @@ -625,18 +625,18 @@ or define direct references with a leading forward slash (/), as follows: 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 +They are not persistent, because the regions were defined in the native {data-store-name} `cache.xml` configuration file as `REPLICATES` and exist before the cache is initialized (once the `` 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 {data-store-name}, 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`"). -Spring Data for Pivotal GemFire supports all eviction policies (entry count, memory, and heap usage) for PARTITION regions, +Spring Data for {data-store-name} supports all eviction policies (entry count, memory, and heap usage) for PARTITION regions, REPLICATE regions, and client, local regions by using the nested `eviction` element. For example, to configure a PARTITION Region to overflow to disk if the memory size exceeds more than 512 MB, @@ -650,22 +650,22 @@ you can specify the following configuration: ---- IMPORTANT: Replicas cannot use `local destroy` eviction since that would invalidate them. -See the Pivotal GemFire docs for more information. +See the {data-store-name} docs for more information. When configuring regions for overflow, you should configure the storage through the `disk-store` element for maximum efficiency. -For a detailed description of eviction policies, see the Pivotal GemFire documentation on -http://geode.apache.org/docs/guide/11/developing/eviction/chapter_overview.html[Eviction]. +For a detailed description of eviction policies, see the {data-store-name} documentation on +{x-data-store-docs}/developing/eviction/chapter_overview.html[Eviction]. [[bootstrap:region:expiration]] == Data Expiration -Pivotal GemFire lets you control how long entries exist in the cache. Expiration is driven by elapsed time, +{data-store-name} 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: +{data-store-name} supports the following Expiration types: * *Time-to-Live (TTL)*: The amount of time in seconds that an object may remain in the cache after the last creation or update. For entries, the counter is set to zero for create and put operations. Region counters are reset when @@ -675,7 +675,7 @@ The Idle Timeout counter for an object is reset any time its TTL counter is rese Idle Timeout counter is reset any time the entry is accessed through a get operation or a `netSearch`. The Idle Timeout counter for a Region is reset whenever the Idle Timeout is reset for one of its entries. -Each of these may be applied to the region itself or to entries in the region. Spring Data for Pivotal GemFire provides ``, +Each of these may be applied to the region itself or to entries in the region. Spring Data for {data-store-name} provides ``, ``, ``, and `` region child elements to specify timeout values and expiration actions. The following example shows a partition region with expiration values set: @@ -688,13 +688,13 @@ The following example shows a partition region with expiration values set: ---- -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]. +For a detailed description of expiration policies, see the {data-store-name} documentation on +{x-data-store-docs}/developing/expiration/chapter_overview.html[expiration]. [[bootstrap:region:expiration:annotation]] === Annotation-based Data Expiration -With Spring Data for Pivotal GemFire, you can define expiration policies and settings on individual +With Spring Data for {data-store-name}, you can define expiration policies and settings on individual region entry values (or, to put it differently, directly on application domain objects). For instance, you can define Expiration settings on a Session-based application domain object as follows: @@ -728,7 +728,7 @@ 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 let you +by Spring Data for {data-store-name}'s expiration annotation support. However, {data-store-name} and Spring Data for {data-store-name} do let you set region expiration by using the SDG XML namespace, as follows: [source,xml] @@ -740,16 +740,16 @@ set region expiration by using the SDG XML namespace, as follows: ---- ==== -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. -See Pivotal GemFire's documentation on http://geode.apache.org/docs/guide/11/developing/expiration/configuring_data_expiration.html[configuring data expiration] +Spring Data for {data-store-name}'s `@Expiration` annotation support is implemented with {data-store-name}'s +{x-data-store-javadoc}/org/apache/geode/cache/CustomExpiry.html[`CustomExpiry`] interface. +See {data-store-name}'s documentation on {x-data-store-docs}/developing/expiration/configuring_data_expiration.html[configuring data expiration] for more details -The Spring Data for Pivotal GemFire `AnnotationBasedExpiration` class (and `CustomExpiry` implementation) is responsible +The Spring Data for {data-store-name} `AnnotationBasedExpiration` class (and `CustomExpiry` implementation) is responsible for processing the SDG `@Expiration` annotations and applying the expiration policy and settings appropriately for region entry expiration on request. -To use Spring Data for Pivotal GemFire to configure specific Pivotal GemFire Regions to appropriately apply the Expiration policy +To use Spring Data for {data-store-name} to configure specific {data-store-name} Regions to appropriately apply the Expiration policy and settings applied to your application domain objects annotated with `@Expiration`-based annotations, you must: . Define a bean in the Spring `ApplicationContext` of type `AnnotationBasedExpiration` by using the appropriate @@ -774,11 +774,11 @@ along with the `` element to set TTI. ==== . (optional) Annotate your application domain objects that are stored in the region with expiration policies -and custom settings by using one of Spring Data for Pivotal GemFire's `@Expiration` annotations: `@Expiration`, +and custom settings by using one of Spring Data for {data-store-name}'s `@Expiration` annotations: `@Expiration`, `@IdleTimeoutExpiration`, or `@TimeToLiveExpiration` -. (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` +. (optional) In cases where particular application domain objects have not been annotated with Spring Data for {data-store-name}'s +`@Expiration` annotations at all, but the {data-store-name} Region is configured to use SDG's custom `AnnotationBasedExpiration` class to determine the Expiration policy and settings for objects stored in the Region, you can set "`default`" expiration attributes on the `AnnotationBasedExpiration` bean by doing the following: @@ -799,11 +799,11 @@ 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 attribute type rather +You may have noticed that Spring Data for {data-store-name}'s `@Expiration` annotations use a `String` as the attribute type rather than, and perhaps more appropriately, being strongly typed -- for example, `int` for 'timeout' and SDG'S `ExpirationActionType` for 'action'. Why is that? -Well, enter one of Spring Data for Pivotal GemFire's other features, leveraging Spring's core infrastructure +Well, enter one of Spring Data for {data-store-name}'s other features, leveraging Spring's core infrastructure for configuration convenience: property placeholders and the Spring Expression Language (SpEL). For instance, a developer can specify both the expiration 'timeout' and 'action' by using Property Placeholders @@ -867,18 +867,18 @@ instance of `java.util.Properties`. In the preceding example, the `properties` e the action value on the actual expiration action enumerated type, leading to more quickly identified failures if the types ever change. -As an example, all of this has been demonstrated and tested in the Spring Data for Pivotal GemFire test suite. See the +As an example, all of this has been demonstrated and tested in the Spring Data for {data-store-name} test suite. See the https://github.com/spring-projects/spring-data-geode[source] for further details. [[bootstrap:region:persistence]] == Data Persistence -Regions can be persistent. Pivotal GemFire ensures that all the data you put into a region that is configured for persistence +Regions can be persistent. {data-store-name} ensures that all the data you put into a region that is configured for persistence is written to disk in a way that is recoverable the next time you recreate the region. Doing so lets data be recovered after machine or process failure or even after an orderly shutdown and subsequent restart of -the Pivotal GemFire data node. +the {data-store-name} data node. -To enable persistence with Spring Data for Pivotal GemFire, set the `persistent` attribute to `true` on +To enable persistence with Spring Data for {data-store-name}, set the `persistent` attribute to `true` on any of the `<*-region>` elements, as the following example shows: [source,xml] @@ -887,7 +887,7 @@ any of the `<*-region>` elements, as the following example shows: ---- Persistence may also be configured by setting the `data-policy` attribute. To do so, set the attribute's value to one of -http://geode.apache.org/releases/latest/javadoc/org/apache/geode/cache/DataPolicy.html[Pivotal GemFire's DataPolicy settings], as the folloiwng example shows: +{x-data-store-javadoc}/org/apache/geode/cache/DataPolicy.html[{data-store-name}'s DataPolicy settings], as the folloiwng example shows: [source,xml] ---- @@ -913,8 +913,8 @@ 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 receives. Spring Data for Pivotal GemFire provides the `` +{data-store-name} allows configuration of {x-data-store-docs}/developing/events/configure_p2p_event_messaging.html[peer-to-peer (P2P) event messaging] +to control the entry events that the region receives. Spring Data for {data-store-name} provides the `` 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` region [[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 +Spring Data for {data-store-name} offers a dedicated `local-region` element for creating local regions. Local regions, as the name implies, are standalone, meaning that they do not share data with any other distributed system member. Other than that, all common region configuration options apply. -The following example shows a minimal declaration (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 {data-store-name} namespace naming conventions to wire the cache): [source,xml] @@ -940,7 +940,7 @@ naming conventions to wire the cache): ---- 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`. +(`exampleLocalRegion`), and the bean assumes the existence of a {data-store-name} cache named `gemfireCache`. [[bootstrap:region:replicate]] == Replicated Region @@ -952,29 +952,29 @@ an initialization stage, in which it discovers other replicas and automatically While one replica is initializing, you can still continue to use the other replicas. All common configuration options are available for REPLICATE Regions. -Spring Data for Pivotal GemFire offers a `replicated-region` element. The following example shows a minimal declaration: +Spring Data for {data-store-name} offers a `replicated-region` element. The following example shows a minimal declaration: [source,xml] ---- ---- -See Pivotal GemFire's documentation on -http://geode.apache.org/docs/guide/11/developing/distributed_regions/chapter_overview.html[Distributed and Replicated Regions] +See {data-store-name}'s documentation on +{x-data-store-docs}/developing/distributed_regions/chapter_overview.html[Distributed and Replicated Regions] for more details. [[bootstrap:region:partition]] == Partitioned Region -The Spring Data for Pivotal GemFire namespace also supports `PARTITION` regions. +The Spring Data for {data-store-name} namespace also supports `PARTITION` regions. -To quote the Pivotal GemFire docs: +To quote the {data-store-name} docs: "`A partitioned region is a region where data is divided between peer servers hosting the region so that each peer stores a subset of the data. When using a partitioned region, applications are presented with a logical view of the region that looks like a single map containing all of the data in the region. Reads or writes to this map are transparently routed to the peer that hosts the entry that is the target of -the operation. Pivotal GemFire divides the domain of hashcodes into buckets. Each bucket is assigned to a specific peer, +the operation. {data-store-name} divides the domain of hashcodes into buckets. Each bucket is assigned to a specific peer, but may be relocated at any time to another peer in order to improve the utilization of resources across the cluster.`" A partition is created by using the `partitioned-region` element. Its configuration options are similar to that of @@ -992,8 +992,8 @@ The following example shows how to set up a `PARTITION` region with two redundan ---- -See Pivotal GemFire's documentation on -http://geode.apache.org/docs/guide/11/developing/partitioned_regions/chapter_overview.html[Partitioned Regions] +See {data-store-name}'s documentation on +{x-data-store-docs}/developing/partitioned_regions/chapter_overview.html[Partitioned Regions] for more details. [[bootstrap:region:partition:attributes]] @@ -1049,12 +1049,12 @@ immediately when a new member is added. [[bootstrap:region:client]] == Client Region -Pivotal GemFire supports various deployment topologies for managing and distributing data. The topic of Pivotal GemFire topologies is outside -the scope of this documentation. However, to quickly recap, Pivotal GemFire's supported topologies can be classified as: +{data-store-name} supports various deployment topologies for managing and distributing data. The topic of {data-store-name} topologies is outside +the scope of this documentation. However, to quickly recap, {data-store-name}'s supported topologies can be classified as: peer-to-peer (p2p), client-server, and wide area network (WAN). In the last two configurations, it is common to declare client regions that connect to a cache server. -Spring Data for Pivotal GemFire offers dedicated support for each configuration through its <> elements: +Spring Data for {data-store-name} 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. @@ -1089,14 +1089,14 @@ cache servers and peer data members in the distributed system and is recommended possible to configure the `Pool` to connect directly to one or more cache servers by using the `server` element. For a full list of options to set on the client and especially on the `Pool`, see -the Spring Data for 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]. +the Spring Data for {data-store-name} schema ("`<>`") and {data-store-name}'s documentation on +{x-data-store-docs}/topologies_and_comm/cs_configuration/chapter_overview.html[Client-Server Configuration]. [[bootstrap:region:client:interests]] === Client Interests -To minimize network traffic, each client can separately define its own 'interests' policies, indicating to Pivotal GemFire -the data it actually requires. In Spring Data for Pivotal GemFire, 'interests' can be defined for each client region separately. +To minimize network traffic, each client can separately define its own 'interests' policies, indicating to {data-store-name} +the data it actually requires. In Spring Data for {data-store-name}, 'interests' can be defined for each client region separately. Both key-based and regular expression-based interest types are supported. The following example shows both key-based and regular expression-based `interest` types: @@ -1183,20 +1183,20 @@ as follows: A full, in-depth discussion of how client interests work and capabilities is beyond the scope of this document. -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] +See {data-store-name}'s documentation on +{x-data-store-docs}/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 (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 +{data-store-name} has support for caching JSON documents in regions, along with the ability to query stored JSON documents +using the {data-store-name} OQL (Object Query Language). JSON documents are stored internally as +{x-data-store-javadoc}/org/apache/geode/pdx/PdxInstance.html[PdxInstance] types by +using the {x-data-store-javadoc}/org/apache/geode/pdx/JSONFormatter.html[JSONFormatter] class to perform conversion to and from JSON documents (as a `String`). -Spring Data for Pivotal GemFire provides the `` element to enable an +Spring Data for {data-store-name} 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. @@ -1213,7 +1213,7 @@ configured regions. This is done by creating a parallel data structure in local 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: +NOTE: Certain Region operations (specifically those that use {data-store-name}'s proprietary `Region.Entry`, such as: `entries(boolean)`, `entrySet(boolean)` and `getEntry()` type) are not targeted for AOP advice. In addition, the `entrySet()` method (which returns a `Set>`) is also not affected. diff --git a/src/main/asciidoc/reference/repositories.adoc b/src/main/asciidoc/reference/repositories.adoc index 837f7423..41f5b2fe 100644 --- a/src/main/asciidoc/reference/repositories.adoc +++ b/src/main/asciidoc/reference/repositories.adoc @@ -1,17 +1,17 @@ [[gemfire-repositories]] -= Spring Data for Pivotal GemFire Repositories += Spring Data for {data-store-name} Repositories -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 +Spring Data for {data-store-name} provides support for using the Spring Data Repository abstraction to easily persist entities +into {data-store-name} along with execute queries. A general introduction to the repository programming model is provided http://docs.spring.io/spring-data/data-commons/docs/current/reference/html/#repositories[here]. [[gemfire-repositories.spring-configuration-xml]] == Spring XML Configuration -To bootstrap Spring Data Repositories, use the `` element from the Spring Data for Pivotal GemFire +To bootstrap Spring Data Repositories, use the `` element from the Spring Data for {data-store-name} Data namespace, as the following example shows: -.Bootstrap Spring Data for Pivotal GemFire Repositories in XML +.Bootstrap Spring Data for {data-store-name} Repositories in XML ==== [source,xml] ---- @@ -37,12 +37,12 @@ IMPORTANT: The bootstrap process fails unless you have your application domain c == Spring Java-based Configuration 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]. +{spring-framework-docs}/core.html#beans-java[Java-based container configuration]. Using this approach, you can bootstrap Spring Data Repositories by using the SDG `@EnableGemfireRepositories` annotation, as the following example shows: -.Bootstrap _Spring Data for Pivotal GemFire Repositories_ with `@EnableGemfireRepositories` +.Bootstrap _Spring Data for {data-store-name} Repositories_ with `@EnableGemfireRepositories` ==== [source, java] ---- @@ -61,12 +61,12 @@ or interface in each package that serves no purpose other than to identify the l referenced by this attribute. 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, +{spring-framework-javadoc}/org/springframework/context/annotation/ComponentScan.html[`@ComponentScan`] annotation, 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. +{spring-framework-javadoc}/org/springframework/context/annotation/ComponentScan.Filter.html[`ComponentScan.Filter`] type. You can use the `filterType` attribute to filter by different aspects, such as whether an application repository type 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] +{spring-framework-javadoc}/org/springframework/context/annotation/FilterType.html[`FilterType` Javadoc] for more details. The `@EnableGemfireRepositories` annotation also lets you specify the location of named OQL queries, @@ -75,16 +75,16 @@ the name of a repository query method and the property value is the OQL query yo the repository query method is called. The `repositoryImplementationPostfix` attribute can be set to an alternate value (defaults to `Impl`) if your -application requires one or more https://docs.spring.io/spring-data/commons/docs/current/reference/html/#repositories.custom-implementations[custom repository implementations]. +application requires one or more {spring-data-commons-docs-html}/#repositories.custom-implementations[custom repository implementations]. This feature is commonly used to extend the Spring Data repository infrastructure to implement a feature not provided by the data store (for example, SDG). -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. +One example of where custom repository implementations are needed with {data-store-name} is when performing joins. +Joins are not supported by SDG repositories. With a {data-store-name} `PARTITION` Region, the join must be +performed on co-located `PARTITION` regions, since {data-store-name} does not support "`distributed`" joins. +In addition, the Equi-Join OQL Query must be performed inside a {data-store-name} function. 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_. +for more details on {data-store-name} _Equi-Join Queries_. Many other aspects of the SDG's repository infrastructure extension may be customized as well. See the https://docs.spring.io/spring-data/gemfire/docs/current/api/org/springframework/data/gemfire/repository/config/EnableGemfireRepositories.html[`@EnableGemfireRepositories` Javadoc] @@ -93,7 +93,7 @@ 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 +Spring Data for {data-store-name} Repositories enable the definition of query methods to easily execute {data-store-name} OQL queries against the region the managed entity maps to, as the following example shows: .Sample Repository @@ -197,7 +197,7 @@ The following table gives brief samples of the supported keywords that you can u [[gemfire-repositories.queries.oql-extensions]] == OQL Query Extensions Using Annotations -Many query languages, such as Pivotal GemFire's OQL (Object Query Language), have extensions that are not directly +Many query languages, such as {data-store-name}'s OQL (Object Query Language), have extensions that are not directly supported by Spring Data Commons' repository infrastructure. One of Spring Data Commons' repository infrastructure goals is to function as the lowest common denominator @@ -206,48 +206,48 @@ for application development today. Technically, this means developers can access 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 by using Java annotations. These Annotations are ignored +To support {data-store-name}'s OQL Query language extensions and preserve portability across different data stores, +Spring Data for {data-store-name} adds support for OQL Query extensions by using Java annotations. These Annotations are ignored by other Spring Data repository implementations (such as Spring Data JPA or Spring Data Redis) that do not have similar query language extensions. -For instance, many data stores most likely do not implement Pivotal GemFire's OQL `IMPORT` keyword. Implementing `IMPORT` +For instance, many data stores most likely do not implement {data-store-name}'s OQL `IMPORT` keyword. Implementing `IMPORT` as an annotation (that is, `@Import`) rather than as part of the query method signature (specifically, the method 'name') does not interfere with the parsing infrastructure when evaluating the query method name to construct another data store language appropriate query. -Currently, the set of Pivotal GemFire OQL Query language extensions that are supported by Spring Data for Pivotal GemFire include: +Currently, the set of {data-store-name} OQL Query language extensions that are supported by Spring Data for {data-store-name} include: [cols="1,2,2,2", options="header"] -.Supported Pivotal GemFire OQL extensions for Repository query methods +.Supported {data-store-name} OQL extensions for Repository query methods |=== | Keyword | Annotation | Description | Arguments -| http://gemfire.docs.pivotal.io/docs-gemfire/latest/developing/query_index/query_index_hints.html#topic_cfb_mxn_jq[HINT] +| {x-data-store-docs}/developing/query_index/query_index_hints.html#topic_cfb_mxn_jq[HINT] | `@Hint` | 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] +| {x-data-store-docs}/developing/query_select/the_import_statement.html#concept_2E9F15B2FE9041238B54736103396BF7[IMPORT] | `@Import` | Qualify application-specific types. | `String` (e.g. @Import("org.example.app.domain.Type")) -| http://gemfire.docs.pivotal.io/docs-gemfire/latest/developing/query_select/the_select_statement.html#concept_85AE7D6B1E2941ED8BD2A8310A81753E__section_25D7055B33EC47B19B1B70264B39212F[LIMIT] +| {x-data-store-docs}/developing/query_select/the_select_statement.html#concept_85AE7D6B1E2941ED8BD2A8310A81753E__section_25D7055B33EC47B19B1B70264B39212F[LIMIT] | `@Limit` | Limit the returned query result set. | `Integer` (e.g. @Limit(10); default is Integer.MAX_VALUE) -| http://gemfire.docs.pivotal.io/docs-gemfire/latest/developing/query_additional/query_debugging.html#concept_2D557E24AAB24044A3DB36B3124F6748[TRACE] +| {x-data-store-docs}/developing/query_additional/query_debugging.html#concept_2D557E24AAB24044A3DB36B3124F6748[TRACE] | `@Trace` | 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 +As an example, suppose you have a `Customers` application domain class and corresponding {data-store-name} region along with a `CustomerRepository` and a query method to lookup `Customers` by last name, as follows: .Sample Customers Repository @@ -294,7 +294,7 @@ 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 {data-store-name}'s repository extension and support is careful not to create conflicting declarations when the OQL Annotation extensions are used in combination with the `@Query` annotation. As another example, suppose you have a raw `@Query` annotated query method defined in your `CustomerRepository`, as follows: @@ -340,7 +340,7 @@ Thanks to using the Spring Data repository abstraction, the query method convent (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 includes the `o.s.d.gemfire.repository.query.QueryPostProcessor` +Since 2.0.x, Spring Data for {data-store-name} includes the `o.s.d.gemfire.repository.query.QueryPostProcessor` functional interface. The interface is loosely defined as follows: .QueryPostProcessor @@ -375,8 +375,8 @@ and used to create a pipeline of processing for a group of generated query metho 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, -https://docs.spring.io/spring-data/commons/docs/current/api/org/springframework/data/repository/Repository.html[`org.springframework.data.repository.Repository`]. -We discuss this further later in this section. All `QUERY` type parameter arguments in Spring Data for Pivotal GemFire's case +{spring-data-commons-javadoc}/org/springframework/data/repository/Repository.html[`org.springframework.data.repository.Repository`]. +We discuss this further later in this section. All `QUERY` type parameter arguments in Spring Data for {data-store-name}'s case are of type `java.lang.String`. NOTE: It is useful to define the query as type `QUERY`, since this `QueryPostProcessor` interface may be ported to @@ -476,7 +476,7 @@ class OrderedLimitedCustomerByLastNameQueryPostProcessor implements QueryPostPro ==== While the preceding example works, you can achieve the same effect by using the Spring Data repository convention and extensions -provided by Spring Data for Pivotal GemFire. For instance, the same query could be defined as follows: +provided by Spring Data for {data-store-name}. For instance, the same query could be defined as follows: .CustomerRepository using the convention ==== diff --git a/src/main/asciidoc/reference/samples.adoc b/src/main/asciidoc/reference/samples.adoc index 2e1152c1..0b3414a6 100644 --- a/src/main/asciidoc/reference/samples.adoc +++ b/src/main/asciidoc/reference/samples.adoc @@ -2,12 +2,12 @@ = Sample Applications NOTE: Sample applications are now maintained in the -https://github.com/spring-projects/spring-gemfire-examples[Spring Pivotal GemFire Examples] repository. +https://github.com/spring-projects/spring-gemfire-examples[Spring {data-store-name} Examples] repository. -The Spring Data for Pivotal GemFire project also includes one sample application. Named "`Hello World`", the sample application -demonstrates how to configure and use Pivotal GemFire inside a Spring application. At run time, the sample offers +The Spring Data for {data-store-name} project also includes one sample application. Named "`Hello World`", the sample application +demonstrates how to configure and use {data-store-name} inside a Spring application. At run time, the sample offers a shell that lets you run various commands against the data grid. It provides an excellent -starting point for developers who are unfamiliar with the essential components or with Spring and Pivotal GemFire concepts. +starting point for developers who are unfamiliar with the essential components or with Spring and {data-store-name} concepts. The sample is bundled with the distribution and is Maven-based. You can import it into any Maven-aware IDE (such as the https://spring.io/tools/sts[Spring Tool Suite]) or run them from the command-line. @@ -15,13 +15,13 @@ Maven-aware IDE (such as the https://spring.io/tools/sts[Spring Tool Suite]) or [[samples:hello-world]] == Hello World -The "`Hello World`" sample application demonstrates the core functionality of the Spring Data for Pivotal GemFire project. -It bootstraps Pivotal GemFire, configures it, executes arbitrary commands against the cache, and shuts it down +The "`Hello World`" sample application demonstrates the core functionality of the Spring Data for {data-store-name} project. +It bootstraps {data-store-name}, configures it, executes arbitrary commands against the cache, and shuts it down when the application exits. Multiple instances of the application can be started at the same time and work together, sharing data without any user intervention. .Running under Linux -NOTE: If you experience networking problems when starting Pivotal GemFire or the samples, try adding the following +NOTE: If you experience networking problems when starting {data-store-name} or the samples, try adding the following system property `java.net.preferIPv4Stack=true` to the command line (for example, `-Djava.net.preferIPv4Stack=true`). For an alternative (global) fix (especially on Ubuntu), see https://jira.spring.io/browse/SGF-28[SGF-28]. @@ -43,7 +43,7 @@ The output should resemble the following: [source] ---- -INFO: Created Pivotal GemFire Cache [Spring Pivotal GemFire World] v. X.Y.Z +INFO: Created {data-store-name} Cache [Spring {data-store-name} World] v. X.Y.Z INFO: Created new cache region [myWorld] INFO: Member xxxxxx:50694/51611 connecting to region [myWorld] Hello World! @@ -80,7 +80,7 @@ and its information, as the following example shows: [source] ---- -INFO: Connected to Distributed System ['Spring Pivotal GemFire World'=xxxx:56218/49320@yyyyy] +INFO: Connected to Distributed System ['Spring {data-store-name} World'=xxxx:56218/49320@yyyyy] Hello World! ... @@ -106,7 +106,7 @@ http://docs.spring.io/spring/docs/current/spring-framework-reference/htmlsingle/ 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, a region, and for illustrative purposes, a `CacheListener` +The cache configuration defines the {data-store-name} 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 diff --git a/src/main/asciidoc/reference/serialization.adoc b/src/main/asciidoc/reference/serialization.adoc index 8e9a8364..7d7a2003 100644 --- a/src/main/asciidoc/reference/serialization.adoc +++ b/src/main/asciidoc/reference/serialization.adoc @@ -1,16 +1,16 @@ [[serialization]] -= Working with Pivotal GemFire Serialization += Working with {data-store-name} Serialization -To improve overall performance of the Pivotal GemFire In-memory Data Grid, Pivotal GemFire supports a dedicated +To improve overall performance of the {data-store-name} In-memory Data Grid, {data-store-name} supports a dedicated serialization protocol, called PDX, that is both faster and offers more compact results over standard Java serialization in addition to working transparently across various language platforms (Java, C++, and .NET). See -http://geode.apache.org/docs/guide/11/developing/data_serialization/PDX_Serialization_Features.html[PDX Serialization Features] +{x-data-store-docs}/developing/data_serialization/PDX_Serialization_Features.html[PDX Serialization Features] and -https://cwiki.apache.org/confluence/display/GEODE/PDX+Serialization+Internals[PDX Serialization Internals] +{x-data-store-wiki}/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 {data-store-name} simplifies and improves {data-store-name}'s custom serialization in Java. [[serialization:wiring]] @@ -19,9 +19,9 @@ custom serialization in Java. It is fairly common for serialized objects to have transient data. Transient data is often dependent on the system or environment where it lives at a certain point in time. For instance, a `DataSource` is environment specific. Serializing such information is useless and potentially even dangerous, since it is local to a certain VM or machine. -For such cases, Spring Data for 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. +For such cases, Spring Data for {data-store-name} offers a special +{x-data-store-javadoc}/org/apache/geode/Instantiator.html[`Instantiator`] +that performs wiring for each new instance created by {data-store-name} during deserialization. Through such a mechanism, you can rely on the Spring container to inject and manage certain dependencies, making it easy to split transient from persistent data and have rich domain objects in a transparent manner. @@ -46,16 +46,16 @@ To use this SDG `Instantiator`, declare it as a bean, as the following example s ---- 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. +itself with the {data-store-name} serialization system and performs wiring on all instances of `SomeDataSerializableClass` +created by {data-store-name} during deserialization. [[serialization:instance-generator]] == Auto-generating Custom `Instantiators` For data intensive applications, a large number of instances might be created on each machine as data flows in. -Pivotal GemFire uses reflection to create new types, but, for some scenarios, this might prove to be expensive. +{data-store-name} uses reflection to create new types, but, for some scenarios, this might prove to be expensive. As always, it is good to perform profiling to quantify whether this is the case or not. For such cases, -Spring Data for Pivotal GemFire allows the automatic generation of `Instatiator` classes, which instantiate a new type +Spring Data for {data-store-name} allows the automatic generation of `Instatiator` classes, which instantiate a new type (using the default constructor) without the use of reflection. The following example shows how to create an instantiator: [source,xml] @@ -71,5 +71,5 @@ Spring Data for Pivotal GemFire allows the automatic generation of `Instatiator` ---- 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 +and `CustomTypeB`) and registers them with {data-store-name} under user ID `1025` and `1026`. The two `Instantiators` avoid the use of reflection and create the instances directly through Java code. diff --git a/src/main/asciidoc/reference/snapshot.adoc b/src/main/asciidoc/reference/snapshot.adoc index a29226f5..517e15d5 100644 --- a/src/main/asciidoc/reference/snapshot.adoc +++ b/src/main/asciidoc/reference/snapshot.adoc @@ -1,21 +1,21 @@ [[bootstrap:snapshot]] = Configuring the Snapshot Service -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] -and http://geode.apache.org/releases/latest/javadoc/org/apache/geode/cache/snapshot/RegionSnapshotService.html[Region] +Spring Data for {data-store-name} supports `cache` and `region` snapshots by using +{x-data-store-docs}/managing/cache_snapshots/chapter_overview.html[{data-store-name}'s Snapshot Service]. +The out-of-the-box Snapshot Service support offers several convenient features to simplify the use of {data-store-name}'s +{x-data-store-javadoc}/org/apache/geode/cache/snapshot/CacheSnapshotService.html[Cache] +and {x-data-store-javadoc}/org/apache/geode/cache/snapshot/RegionSnapshotService.html[Region] Snapshot Service APIs. -As the http://geode.apache.org/docs/guide/11/managing/cache_snapshots/chapter_overview.html[Pivotal GemFire documentation] +As the {x-data-store-docs}/managing/cache_snapshots/chapter_overview.html[{data-store-name} documentation] describes, snapshots let you save and subsequently reload the cached data later, which can be useful for moving data between environments, such as from production to a staging or test environment in order to reproduce -data-related issues in a controlled context. You can combine Spring Data for Pivotal GemFire's Snapshot Service support +data-related issues in a controlled context. You can combine Spring Data for {data-store-name}'s Snapshot Service support with http://docs.spring.io/spring/docs/current/spring-framework-reference/htmlsingle/#beans-definition-profiles[Spring's bean definition profiles] to load snapshot data specific to the environment as necessary. -Spring Data for Pivotal GemFire's support for Pivotal GemFire's Snapshot Service begins with the `` element +Spring Data for {data-store-name}'s support for {data-store-name}'s Snapshot Service begins with the `` element from the `` namespace. For example, you can define cache-wide snapshots to be loaded as well as saved by using a couple of snapshot imports @@ -32,10 +32,10 @@ and a data export definition, as follows: ---- 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 +The file locations and directory paths can be absolute or relative to the Spring Data for {data-store-name} application, which is the JVM process's working directory. -The preceding example is pretty simple, and the Snapshot Service defined in this case refers to the Pivotal GemFire `cache` with +The preceding example is pretty simple, and the Snapshot Service defined in this case refers to the {data-store-name} `cache` with the default name of `gemfireCache` (as described in <>). 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: @@ -48,7 +48,7 @@ something other than the default, you can use the `cache-ref` attribute to refer ---- -You can also define a Snapshot Service for a particular Pivotal GemFire Region by specifying +You can also define a Snapshot Service for a particular {data-store-name} Region by specifying the `region-ref` attribute, as follows: [source,xml] @@ -61,17 +61,17 @@ the `region-ref` attribute, as follows: ---- -When the `region-ref` attribute is specified, Spring Data for Pivotal GemFire's `SnapshotServiceFactoryBean` resolves +When the `region-ref` attribute is specified, Spring Data for {data-store-name}'s `SnapshotServiceFactoryBean` resolves the `region-ref` attribute value to a region bean defined in the Spring context and creates a -http://geode.apache.org/releases/latest/javadoc/org/apache/geode/cache/snapshot/RegionSnapshotService.html[`RegionSnapshotService`]. +{x-data-store-javadoc}/org/apache/geode/cache/snapshot/RegionSnapshotService.html[`RegionSnapshotService`]. The snapshot import and export definitions function the same way. However, the `location` must refer to a file on export. -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, +NOTE: {data-store-name} is strict about imported snapshot files actually existing before they are referenced. For exports, +{data-store-name} creates the snapshot file. If the snapshot file for export already exists, the data is overwritten. -TIP: Spring Data for Pivotal GemFire includes a `suppress-import-on-init` attribute on the `` element +TIP: Spring Data for {data-store-name} 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. @@ -79,20 +79,20 @@ Doing so is useful, for example, when data exported from one region is used to f == Snapshot Location For a `Cache`-based Snapshot Service -(that is, a http://geode.apache.org/releases/latest/javadoc/org/apache/geode/cache/snapshot/CacheSnapshotService.html[`CacheSnapshotService`]) +(that is, a {x-data-store-javadoc}/org/apache/geode/cache/snapshot/CacheSnapshotService.html[`CacheSnapshotService`]) you would typically pass it a directory containing all the snapshot files to load rather than individual snapshot files, as the overloaded -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`] +{x-data-store-javadoc}/org/apache/geode/cache/snapshot/CacheSnapshotService.html#load-java.io.File-org.apache.geode.cache.snapshot.SnapshotOptions.SnapshotFormat[`load`] method in the `CacheSnapshotService` API indicates. NOTE: Of course, you can use the other, overloaded `load(:File[], :SnapshotFormat, :SnapshotOptions)` method -variant to get specific about which snapshot files to load into the Pivotal GemFire `cache`. +variant to get specific about which snapshot files to load into the {data-store-name} `cache`. -However, Spring Data for Pivotal GemFire recognizes that a typical developer workflow might be to extract and export data +However, Spring Data for {data-store-name} recognizes that a typical developer workflow might be to extract and export data from one environment into several snapshot files, zip all of them up, and then conveniently move the zip file to another environment for import. -Therefore, Spring Data for Pivotal GemFire lets you specify a jar or zip file on import for a `cache`-based +Therefore, Spring Data for {data-store-name} lets you specify a jar or zip file on import for a `cache`-based Snapshot Service, as follows: [source,xml] @@ -102,18 +102,18 @@ Snapshot Service, as follows: ---- -Spring Data for Pivotal GemFire conveniently extracts the provided zip file and treats it as a directory import (load). +Spring Data for {data-store-name} conveniently extracts the provided zip file and treats it as a directory import (load). [[bootstrap:snapshot:filters]] == Snapshot Filters The real power of defining multiple snapshot imports and exports is realized through the use of snapshot filters. -Snapshot filters implement Pivotal GemFire's -http://geode.apache.org/releases/latest/javadoc/org/apache/geode/cache/snapshot/SnapshotFilter.html[`SnapshotFilter`] +Snapshot filters implement {data-store-name}'s +{x-data-store-javadoc}/org/apache/geode/cache/snapshot/SnapshotFilter.html[`SnapshotFilter`] interface and are used to filter region entries for inclusion into the region on import and for inclusion into the snapshot on export. -Spring Data for Pivotal GemFire lets you use snapshot filters on import and export by using the `filter-ref` +Spring Data for {data-store-name} lets you use snapshot filters on import and export by using the `filter-ref` attribute or an anonymous, nested bean definition, as the following example shows: [source,xml] @@ -141,8 +141,8 @@ attribute or an anonymous, nested bean definition, as the following example show ---- In addition, you can express more complex snapshot filters by using the `ComposableSnapshotFilter` class. -This class implements Pivotal GemFire's -http://geode.apache.org/releases/latest/javadoc/org/apache/geode/cache/snapshot/SnapshotFilter.html[SnapshotFilter] +This class implements {data-store-name}'s +{x-data-store-javadoc}/org/apache/geode/cache/snapshot/SnapshotFilter.html[SnapshotFilter] interface as well as the https://en.wikipedia.org/wiki/Composite_pattern[Composite] software design pattern. In a nutshell, the https://en.wikipedia.org/wiki/Composite_pattern[Composite] software design pattern lets you @@ -187,15 +187,15 @@ You could then go on to combine the `activesUsersSinceFilter` with another filte [[bootstrap::snapshot::events]] == Snapshot Events -By default, Spring Data for Pivotal GemFire uses Pivotal GemFire's Snapshot Services on startup to import data and on shutdown +By default, Spring Data for {data-store-name} uses {data-store-name}'s Snapshot Services on startup to import data and on shutdown to export data. However, you may want to trigger periodic, event-based snapshots, for either import or export, from within your Spring application. -For this purpose, Spring Data for Pivotal GemFire defines two additional Spring application events, extending Spring's +For this purpose, Spring Data for {data-store-name} defines two additional Spring application events, extending Spring's http://docs.spring.io/spring/docs/current/javadoc-api/org/springframework/context/ApplicationEvent.html[`ApplicationEvent`] class for imports and exports, respectively: `ImportSnapshotApplicationEvent` and `ExportSnapshotApplicationEvent`. -The two application events can be targeted at the entire Pivotal GemFire cache or individual Pivotal GemFire regions. The constructors +The two application events can be targeted at the entire {data-store-name} cache or individual {data-store-name} regions. The constructors in these classes accept an optional region pathname (such as `/Example`) as well as xero or more `SnapshotMetadata` instances. The array of `SnapshotMetadata` overrides the snapshot metadata defined by ``