From 87d5e7e16a3ef61f01b2a0458d4f8f51d2581953 Mon Sep 17 00:00:00 2001 From: John Blum Date: Mon, 8 May 2017 16:24:46 -0700 Subject: [PATCH] SGF-300 - Change all Spring Data Geode and Apache Geode references to Spring Data GemFire and Pivotal GemFire. --- src/main/asciidoc/index.adoc | 2 +- .../asciidoc/introduction/introduction.adoc | 4 +- .../asciidoc/introduction/new-features.adoc | 2 +- .../asciidoc/introduction/requirements.adoc | 4 +- src/main/asciidoc/links.adoc | 10 +- src/main/asciidoc/preface.adoc | 8 +- src/main/asciidoc/reference/bootstrap.adoc | 44 ++--- src/main/asciidoc/reference/cache.adoc | 134 +++++++-------- src/main/asciidoc/reference/cq-container.adoc | 28 ++-- src/main/asciidoc/reference/data-access.adoc | 14 +- src/main/asciidoc/reference/data.adoc | 58 ++++--- src/main/asciidoc/reference/diskstore.adoc | 6 +- .../reference/function-annotations.adoc | 102 ++++++------ src/main/asciidoc/reference/function.adoc | 10 +- src/main/asciidoc/reference/gateway.adoc | 6 +- .../asciidoc/reference/gemfire-bootstrap.adoc | 60 +++---- src/main/asciidoc/reference/indexing.adoc | 8 +- src/main/asciidoc/reference/introduction.adoc | 18 +- src/main/asciidoc/reference/lucene.adoc | 30 ++-- src/main/asciidoc/reference/mapping.adoc | 16 +- src/main/asciidoc/reference/region.adoc | 156 +++++++++--------- src/main/asciidoc/reference/repositories.adoc | 32 ++-- src/main/asciidoc/reference/samples.adoc | 10 +- .../asciidoc/reference/serialization.adoc | 20 +-- src/main/asciidoc/reference/snapshot.adoc | 56 +++---- 25 files changed, 421 insertions(+), 417 deletions(-) diff --git a/src/main/asciidoc/index.adoc b/src/main/asciidoc/index.adoc index 3c693150..6e93a03d 100644 --- a/src/main/asciidoc/index.adoc +++ b/src/main/asciidoc/index.adoc @@ -49,7 +49,7 @@ include::{basedocdir}/reference/samples.adoc[] = Resources In addition to this reference documentation, there are a number of other resources that may help you learn -how to use Apache Geode with the _Spring Framework_. These additional, third-party resources are enumerated +how to use Pivotal GemFire with the _Spring Framework_. These additional, third-party resources are enumerated in this section. :leveloffset: +1 diff --git a/src/main/asciidoc/introduction/introduction.adoc b/src/main/asciidoc/introduction/introduction.adoc index 3d317875..42aa210e 100644 --- a/src/main/asciidoc/introduction/introduction.adoc +++ b/src/main/asciidoc/introduction/introduction.adoc @@ -1,6 +1,6 @@ [[introduction]] = Introduction -This reference guide for _Spring Data Geode_ explains how to use the _Spring Framework_ to configure and develop -applications with Apache Geode. It presents the basic concepts, semantics and provides numerous examples +This reference guide for _Spring Data GemFire_ explains how to use the _Spring Framework_ to configure and develop +applications with Pivotal GemFire. It presents the basic concepts, semantics and provides numerous examples to help you get started. diff --git a/src/main/asciidoc/introduction/new-features.adoc b/src/main/asciidoc/introduction/new-features.adoc index 05e84b59..cd2fd35f 100644 --- a/src/main/asciidoc/introduction/new-features.adoc +++ b/src/main/asciidoc/introduction/new-features.adoc @@ -108,7 +108,7 @@ rely on GemFire defaults instead. * Upgrades to Pivotal GemFire 8.1.0. * Upgrades to _Spring Data Commons_ 1.11.x.RELEASE. * Upgrades to _Spring Framework_ 4.1.x.RELEASE. -* Early access support for Apache Geode. +* Early access support for Pivotal GemFire. * Support for adding _Spring_-defined Cache Listeners, Loaders and Writers on "existing" GemFire Regions configured in _Spring_ XML, `cache.xml` or even with Pivotal GemFire's _Cluster Config_. * _Spring_ JavaConfig support added to `SpringContextBootstrappingInitializer`. diff --git a/src/main/asciidoc/introduction/requirements.adoc b/src/main/asciidoc/introduction/requirements.adoc index 0b0aaa02..f93ea4a9 100644 --- a/src/main/asciidoc/introduction/requirements.adoc +++ b/src/main/asciidoc/introduction/requirements.adoc @@ -1,5 +1,5 @@ [[requirements]] = Requirements -_Spring Data Geode_ requires JDK 8.0, http://projects.spring.io/spring-framework[Spring Framework] 5 -and http://geode.apache.org/[Apache Geode] 1.2.0. +_Spring Data GemFire_ requires JDK 8.0, http://projects.spring.io/spring-framework[Spring Framework] 5 +and http://geode.apache.org/[Pivotal GemFire] 9.0.x. diff --git a/src/main/asciidoc/links.adoc b/src/main/asciidoc/links.adoc index c5a092a4..5573b747 100644 --- a/src/main/asciidoc/links.adoc +++ b/src/main/asciidoc/links.adoc @@ -2,13 +2,13 @@ = Useful Links * http://projects.spring.io/spring-data-gemfire[Spring Data GemFire Project Page] -* https://github.com/spring-projects/spring-data-geode[Spring Data Geode source code] -* https://jira.spring.io/browse/DATAGEODE[Spring Data Geode JIRA] +* https://github.com/spring-projects/spring-data-gemfire[Spring Data GemFire source code] +* https://jira.spring.io/browse/SGF[Spring Data GemFire JIRA] * http://stackoverflow.com/questions/tagged/spring-data-gemfire[Spring Data GemFire on StackOverflow] * http://forum.spring.io/forum/spring-projects/data/gemfire[Archive of the Spring Data GemFire Forum on Spring IO] -* http://geode.apache.org/[Apache Geode Home Page] -* http://geode.apache.org/docs/[Apache Geode Documentation] +* https://pivotal.io/pivotal-gemfire[Pivotal GemFire Home Page] +* http://gemfire.docs.pivotal.io/gemfire/about_gemfire.html[Pivotal GemFire Documentation] * http://geode.apache.org/community/[Apache Geode Community] * https://github.com/apache/geode[Apache Geode source code] * https://issues.apache.org/jira/browse/GEODE/?selectedTab=com.atlassian.jira.jira-projects-plugin:summary-panel[Apache Geode JIRA] -* http://stackoverflow.com/search?q=Apache%20Geode[Apache Geode on StackOverflow] +* http://stackoverflow.com/questions/tagged/gemfire[Pivotal GemFire on StackOverflow] diff --git a/src/main/asciidoc/preface.adoc b/src/main/asciidoc/preface.adoc index dc397e7b..491a0e31 100644 --- a/src/main/asciidoc/preface.adoc +++ b/src/main/asciidoc/preface.adoc @@ -1,16 +1,16 @@ = Preface -_Spring Data Geode_ focuses on integrating the _Spring Framework's_ powerful, non-invasive programming model -and concepts with Apache Geode to simplify configuration and development of Java applications using Geode. +_Spring Data GemFire_ focuses on integrating the _Spring Framework's_ powerful, non-invasive programming model +and concepts with Pivotal GemFire to simplify configuration and development of Java applications using GemFire. -This document assumes the reader already has a basic familiarity with the _Spring Framework_ and Apache Geode +This document assumes the reader already has a basic familiarity with the _Spring Framework_ and Pivotal GemFire concepts and APIs. While every effort has been made to ensure this documentation is comprehensive and complete, with no errors, some topics are beyond the scope of this document and may require more explanation (e.g. data distribution management with partitioning for HA while still preserving consistency). Additionally, some typos might have crept in. If you do spot mistakes or even more serious errors and you can spare a few cycles, please do bring these issues -to the attention of the _Spring Data Geode_ team by raising an appropriate +to the attention of the _Spring Data GemFire_ team by raising an appropriate https://jira.spring.io/browse/DATAGEODE[issue]. Thank you. diff --git a/src/main/asciidoc/reference/bootstrap.adoc b/src/main/asciidoc/reference/bootstrap.adoc index 278aa4a9..2d990537 100644 --- a/src/main/asciidoc/reference/bootstrap.adoc +++ b/src/main/asciidoc/reference/bootstrap.adoc @@ -1,29 +1,29 @@ [[bootstrap]] -= Bootstrapping Apache Geode with the Spring container += Bootstrapping Pivotal GemFire with the Spring container -_Spring Data Geode_ provides full configuration and initialization of the Apache Geode In-Memory Data Grid (IMDG) +_Spring Data GemFire_ provides full configuration and initialization of the Pivotal GemFire In-Memory Data Grid (IMDG) using the _Spring_ IoC container. The framework includes several classes to help simplify the configuration of -Apache Geode components including: Caches, Regions, Indexes, DiskStores, Functions, WAN Gateways, persistence backup +Pivotal GemFire components including: Caches, Regions, Indexes, DiskStores, Functions, WAN Gateways, persistence backup along with several other Distributed System components in order to support a variety of use cases with minimal effort. -NOTE: This section assumes basic familiarity with Apache Geode. For more information, -see the Apache Geode http://geode.apache.org/docs/[product documentation]. +NOTE: This section assumes basic familiarity with Pivotal GemFire. For more information, +see the Pivotal GemFire http://geode.apache.org/docs/[product documentation]. [[bootstrap:namespace:xml]] -== Advantages of using Spring over Apache Geode `cache.xml` +== Advantages of using Spring over Pivotal GemFire `cache.xml` -_Spring Data Geode's_ XML namespace supports full configuration of the Apache Geode In-Memory Data Grid (IMDG). -The XML namespace is the preferred way to configure Apache Geode in a _Spring_ context in order to properly -manage Geode's lifecycle inside the _Spring_ container. While support for Geode's native `cache.xml` persists -for legacy reasons, Geode application developers are encouraged to do everything in _Spring_ XML to take advantage of +_Spring Data GemFire's_ XML namespace supports full configuration of the Pivotal GemFire In-Memory Data Grid (IMDG). +The XML namespace is the preferred way to configure Pivotal GemFire in a _Spring_ context in order to properly +manage GemFire's lifecycle inside the _Spring_ container. While support for GemFire's native `cache.xml` persists +for legacy reasons, GemFire application developers are encouraged to do everything in _Spring_ XML to take advantage of the many wonderful things _Spring_ has to offer such as modular XML configuration, property placeholders and overrides, -SpEL, and environment profiles. Behind the XML namespace, _Spring Data Geode_ makes extensive use of _Spring's_ -`FactoryBean` pattern to simplify the creation, configuration and initialization of Geode components. +SpEL, and environment profiles. Behind the XML namespace, _Spring Data GemFire_ makes extensive use of _Spring's_ +`FactoryBean` pattern to simplify the creation, configuration and initialization of GemFire components. -Apache Geode provides several callback interfaces, such as `CacheListener`, `CacheLoader` and `CacheWriter`, +Pivotal GemFire provides several callback interfaces, such as `CacheListener`, `CacheLoader` and `CacheWriter`, that allow developers to add custom event handlers. Using _Spring's_ IoC container, these callbacks may be configured -as normal _Spring_ beans and injected into Geode components. This is a significant improvement over native `cache.xml`, -which provides relatively limited configuration options and requires callbacks to implement Geode's `Declarable` +as normal _Spring_ beans and injected into GemFire components. This is a significant improvement over native `cache.xml`, +which provides relatively limited configuration options and requires callbacks to implement GemFire's `Declarable` interface (see <> 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 @@ -32,7 +32,7 @@ including code completion, pop-up annotations, and real time validation, making [[bootstrap:namespace]] == Using the Core Namespace -To simplify configuration, _Spring Data Geode_ provides a dedicated XML namespace for configuring core Apache Geode +To simplify configuration, _Spring Data GemFire_ provides a dedicated XML namespace for configuring core Pivotal GemFire components. It is possible to configure beans directly using _Spring's_ standard `` definition. However, all bean properties are exposed via the XML namespace so there is little benefit to using raw bean definitions. For more information about XML Schema-based configuration in _Spring_, see the @@ -40,9 +40,9 @@ http://docs.spring.io/spring/docs/current/spring-framework-reference/htmlsingle/ 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 Geode_ Repositories. +on how to configure _Spring Data GemFire_ Repositories. -To use the _Spring Data Geode_ XML namespace, simply declare it in your _Spring_ XML configuration meta-data: +To use the _Spring Data GemFire_ XML namespace, simply declare it in your _Spring_ XML configuration meta-data: [source,xml] ---- @@ -60,17 +60,17 @@ To use the _Spring Data Geode_ XML namespace, simply declare it in your _Spring_ ---- -<1> _Spring Data Geode_ XML namespace prefix. Any name will do but through out this reference documentation, +<1> _Spring Data GemFire_ XML namespace prefix. Any name will do but through out this reference documentation, `gfe` will be used. <2> The XML namespace prefix is mapped to the URI. <3> The XML namespace URI location. Note that even though the location points to an external address (which does exist -and is valid), _Spring_ will resolve the schema locally as it is included in the _Spring Data Geode_ library. +and is valid), _Spring_ will resolve the schema locally as it is included in the _Spring Data GemFire_ library. <4> Example declaration using the XML namespace with the `gfe` prefix. [NOTE] ==== It is possible to change the default namespace from `beans` to `gfe`. This is useful for XML configuration -composed mainly of Geode components as it avoids declaring the prefix. To achieve this, simply swap the namespace +composed mainly of GemFire components as it avoids declaring the prefix. To achieve this, simply swap the namespace prefix declaration above: [source,xml] @@ -89,7 +89,7 @@ prefix declaration above: ---- -<1> The default namespace declaration for this XML document points to the _Spring Data Geode_ XML namespace. +<1> The default namespace declaration for this XML document points to the _Spring Data GemFire_ XML namespace. <2> The `beans` namespace prefix declaration for _Spring's_ raw bean definitions. <3> Bean declaration using the `beans` namespace. Notice the prefix. <4> Bean declaration using the `gfe` namespace. Notice the lack of prefix since `gfe` is the default namespace. diff --git a/src/main/asciidoc/reference/cache.adoc b/src/main/asciidoc/reference/cache.adoc index bbe32801..beed371c 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 Apache Geode, a developer needs to either create a new `Cache` or connect to an existing one. -With the current version of Geode, there can be only one open Cache per VM (technically, per `ClassLoader`). +To use Pivotal GemFire, a developer needs to either create a new `Cache` or connect to an existing one. +With the current version of GemFire, there can be only one open Cache per VM (technically, 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 a very simple declar ---- During Spring container initialization, any application context containing this cache definition will register -a `CacheFactoryBean` that creates a Spring bean named `gemfireCache` referencing a Geode `Cache` instance. +a `CacheFactoryBean` that creates a Spring bean named `gemfireCache` referencing a GemFire `Cache` instance. This bean will refer to either an existing cache, or if one does not already exist, a newly created one. Since no additional properties were specified, a newly created cache will apply the default cache configuration. -All _Spring Data Geode_ components that depend on the cache respect this naming convention, so there is no need +All _Spring Data GemFire_ components that depend on the cache respect this naming convention, so there is no need to explicitly declare the cache dependency. If you prefer, you can make the dependency explicit via the `cache-ref` attribute provided by various SDG XML namespace elements. Also, you can easily override the cache's bean name using the `id` attribute: @@ -33,9 +33,9 @@ the `id` attribute: ---- -A Geode `Cache` can be fully configured using Spring, however, Geode's native XML configuration file, `cache.xml`, -is also supported. For situations where the Geode cache needs to be configured natively, simply provide a reference -to the Geode XML configuration file using the `cache-xml-location` attribute: +A GemFire `Cache` can be fully configured using Spring, however, GemFire's native XML configuration file, `cache.xml`, +is also supported. For situations where the GemFire cache needs to be configured natively, simply provide a reference +to the GemFire XML configuration file using the `cache-xml-location` attribute: [source,xml] ---- @@ -49,7 +49,7 @@ NOTE: The configuration makes use of Spring's http://docs.spring.io/spring/docs/ abstraction to locate the file. This allows various search patterns to be used, depending on the runtime environment or the prefix specified (if any) in the resource location. -In addition to referencing an external XML configuration file, a developer may also specify Geode System +In addition to referencing an external XML configuration file, a developer may also specify GemFire System http://geode.apache.org/docs/guide/11/reference/topics/gemfire_properties.html[properties] using any of Spring's `Properties` support features. @@ -60,12 +60,12 @@ directly or load properties from a properties file: ---- @@ -114,7 +114,7 @@ or child elements: - + @@ -127,22 +127,22 @@ or child elements: ---- <1> Various cache options are supported by attributes. For further information regarding anything shown in this example, -please consult the Geode http://geode.apache.org/docs/[product documentation]. +please consult the GemFire http://docs.pivotal.io/gemfire[product documentation]. The `close` attribute determines whether the cache should be closed when the Spring application context is closed. The default is `true`, however, for use cases in which multiple application contexts use the cache (common in web applications), set this value to `false`. -<2> Setting the `enable-auto-reconnect` attribute to true (default is false), allows a disconnected Geode member to -automatically reconnect and rejoin the Geode cluster. -See the Geode http://geode.apache.org/docs/guide/11/managing/autoreconnect/member-reconnect.html[product documentation] +<2> Setting the `enable-auto-reconnect` attribute to true (default is false), allows a disconnected GemFire member to +automatically reconnect and rejoin the GemFire cluster. +See the GemFire http://geode.apache.org/docs/guide/11/managing/autoreconnect/member-reconnect.html[product documentation] for more details. <3> Setting the `use-bean-factory-locator` attribute to `true` (defaults to `false`) is only applicable when both -Spring (XML) configuration meta-data and Geode `cache.xml` is used to configure the Geode cache node -(whether client or peer). This option allows Geode components (e.g. `CacheLoader`) expressed in `cache.xml` +Spring (XML) configuration meta-data and GemFire `cache.xml` is used to configure the GemFire cache node +(whether client or peer). This option allows GemFire components (e.g. `CacheLoader`) expressed in `cache.xml` to be auto-wired with beans (e.g. `DataSource`) defined in the Spring application context. This option is typically used in conjunction with `cache-xml-location`. -<4> Setting the `use-cluster-configuration` attribute to `true` (default is `false`) enables a Geode member to +<4> Setting the `use-cluster-configuration` attribute to `true` (default is `false`) enables a GemFire member to retrieve the common, shared Cluster-based configuration from a Locator. -See the Geode http://geode.apache.org/docs/guide/11/configuring/cluster_config/gfsh_persist.html[product documentation] +See the GemFire http://geode.apache.org/docs/guide/11/configuring/cluster_config/gfsh_persist.html[product documentation] for more details. <5> Example of a `TransactionListener` callback declaration using a bean reference. The referenced bean must implement http://geode.apache.org/releases/latest/javadoc/org/apache/geode/cache/TransactionListener.html[TransactionListener]. @@ -155,16 +155,16 @@ must implement http://geode.apache.org/releases/latest/javadoc/org/apache/geode/ [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> Enable Geode's http://geode.apache.org/docs/guide/11/developing/region_options/dynamic_region_creation.html[DynamicRegionFactory], +<8> Enable GemFire's http://geode.apache.org/docs/guide/11/developing/region_options/dynamic_region_creation.html[DynamicRegionFactory], which provides a distributed Region creation service. -<9> Declares a JNDI binding to enlist an external DataSource in a Geode transaction. +<9> Declares a JNDI binding to enlist an external DataSource in a GemFire transaction. [[bootstrap:cache:pdx-serialization]] === Enabling PDX Serialization -The example above includes a number of attributes related to Geode's enhanced serialization framework, PDX. +The example above includes a number of attributes related to GemFire's enhanced serialization framework, PDX. While a complete discussion of PDX is beyond the scope of this reference guide, it is important to note that PDX -is enabled by registering a `PdxSerializer` which is specified via the `pdx-serializer` attribute. Geode provides +is enabled by registering a `PdxSerializer` which is specified via the `pdx-serializer` attribute. GemFire provides an implementing class `org.apache.geode.pdx.ReflectionBasedAutoSerializer` that uses Java Reflection, however, it is common for developers to provide their own implementation. The value of the attribute is simply a reference to a Spring bean that implements the `PdxSerializer` interface. @@ -176,17 +176,17 @@ More information on serialization support can be found in <> Setting the ` ---- -NOTE: While certain Geode tools, like _Gfsh_, have their actions "recorded" when schema-like changes are made -(e.g. `gfsh>create region --name=Example --type=PARTITION`), _Spring Data Geode's_ configuration meta-data -is not recorded. The same is true when using Geode's public Java API directly; it too is not recorded. +NOTE: While certain GemFire tools, like _Gfsh_, have their actions "recorded" when schema-like changes are made +(e.g. `gfsh>create region --name=Example --type=PARTITION`), _Spring Data GemFire's_ configuration meta-data +is not recorded. The same is true when using GemFire's public Java API directly; it too is not recorded. -For more information on Geode's Cluster Configuration Service, see the +For more information on GemFire's Cluster Configuration Service, see the http://geode.apache.org/docs/guide/11/configuring/cluster_config/gfsh_persist.html[product documentation]. [[bootstrap:cache:server]] -== Configuring a Geode CacheServer +== Configuring a GemFire CacheServer -_Spring Data Geode_ includes dedicated support for configuring a +_Spring Data GemFire_ includes dedicated support for configuring a http://geode.apache.org/releases/latest/javadoc/org/apache/geode/cache/server/CacheServer.html[CacheServer], allowing complete configuration through the Spring container: @@ -252,19 +252,19 @@ allowing complete configuration through the Spring container: - + @@ -290,21 +290,21 @@ and the http://docs.spring.io/spring/docs/current/spring-framework-reference/htm to support externalization of environment-specific properties from the main codebase, easing deployment across multiple machines. -NOTE: To avoid initialization problems, the `CacheServer` started by _Spring Data Geode_ will start *after* +NOTE: To avoid initialization problems, the `CacheServer` started by _Spring Data GemFire_ will start *after* the _Spring_ container has been fully initialized. This allows potential Regions, Listeners, Writers or Instantiators defined declaratively to be fully initialized and registered before the server starts accepting connections. Keep this in mind when programmatically configuring these elements as the server might start after your components and thus not be seen by the clients connecting right away. [[bootstrap:cache:client]] -== Configuring a Geode ClientCache +== Configuring a GemFire ClientCache -In addition to defining a Geode peer http://geode.apache.org/releases/latest/javadoc/org/apache/geode/cache/Cache.html[Cache], -_Spring Data Geode_ also supports the definition of a Geode http://geode.apache.org/releases/latest/javadoc/org/apache/geode/cache/client/ClientCache.html[ClientCache] +In addition to defining a GemFire peer http://geode.apache.org/releases/latest/javadoc/org/apache/geode/cache/Cache.html[Cache], +_Spring Data GemFire_ also supports the definition of a GemFire http://geode.apache.org/releases/latest/javadoc/org/apache/geode/cache/client/ClientCache.html[ClientCache] in a _Spring_ context. A `ClientCache` definition is very similar in configuration and use to -the Geode peer <> and is supported by the `org.springframework.data.gemfire.client.ClientCacheFactoryBean`. +the GemFire peer <> and is supported by the `org.springframework.data.gemfire.client.ClientCacheFactoryBean`. -The simplest definition of a Geode cache client using default configuration can be accomplished with the following +The simplest definition of a GemFire cache client using default configuration can be accomplished with the following declaration: [source,xml] @@ -331,7 +331,7 @@ to the cache definition: - + ---- @@ -342,9 +342,9 @@ initialization will include a call to http://geode.apache.org/releases/latest/ja Client-side configuration is covered in more detail in <>. [[bootstrap:cache:client:pool]] -=== Geode's DEFAULT Pool and Spring Data Geode Pool Definitions +=== GemFire's DEFAULT Pool and Spring Data GemFire Pool Definitions -If a Geode `ClientCache` is local-only, then no Pool definition is required. For instance, a developer may define: +If a GemFire `ClientCache` is local-only, then no Pool definition is required. For instance, a developer may define: [source,xml] ---- @@ -354,14 +354,14 @@ If a Geode `ClientCache` is local-only, then no Pool definition is required. Fo ---- 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 Geode's +no Pool is necessary. This is true for any client-side, local-only Region, as defined by the GemFire's http://geode.apache.org/releases/latest/javadoc/org/apache/geode/cache/client/ClientRegionShortcut.html[ClientRegionShortcut] (all `LOCAL_*` shortcuts). However, if a client Region is a (caching) proxy to a server-side Region, then a Pool is required. There are several ways to define and use a Pool in this case. -When a client cache, Pool and proxy-based Region are all defined, but not explicitly identified, _Spring Data Geode_ +When a client cache, Pool and proxy-based Region are all defined, but not explicitly identified, _Spring Data GemFire_ will resolve the references automatically for you. For example: @@ -378,10 +378,10 @@ For example: ---- In the example above, the client cache is identified as `gemfireCache`, the Pool as `gemfirePool` and the client Region -as "Example". However, the client cache will initialize Geode's DEFAULT Pool from `gemfirePool` and the client Region +as "Example". However, the client cache will initialize GemFire's DEFAULT Pool from `gemfirePool` and the client Region will use the `gemfirePool` when distributing data between the client and the server. -Basically, _Spring Data Geode_ resolves the above configuration to the following: +Basically, _Spring Data GemFire_ resolves the above configuration to the following: [source,xml] ---- @@ -394,7 +394,7 @@ Basically, _Spring Data Geode_ resolves the above configuration to the following ---- -Geode still creates a Pool called "DEFAULT". _Spring Data Geode_ will just cause the "DEFAULT" Pool to be +GemFire still creates a Pool called "DEFAULT". _Spring Data GemFire_ will just cause the "DEFAULT" Pool to be initialized from the `gemfirePool`. This is useful in situations where multiple Pools are defined and client Regions are using separate Pools. @@ -419,12 +419,12 @@ Consider the following: ---- -In this setup, the Geode client cache's "DEFAULT" Pool is initialized from "locatorPool" as specified with the -`pool-name` attribute. There is no _Spring Data Geode_-defined `gemfirePool` since both Pools were explicitly +In this setup, the GemFire client cache's "DEFAULT" Pool is initialized from "locatorPool" as specified with the +`pool-name` attribute. There is no _Spring Data GemFire_-defined `gemfirePool` since both Pools were explicitly identified (named) "locatorPool" and "serverPool", respectively. The "Example" Region explicitly refers to and uses the "serverPool" exclusively. The "AnotherExample" Region uses -Geode's "DEFAULT" Pool, which was configured from the "locatorPool" based on the client cache bean definition's +GemFire's "DEFAULT" Pool, which was configured from the "locatorPool" based on the client cache bean definition's `pool-name` attribute. Finally, the "YetAnotherExample" Region will not use a Pool since it is `LOCAL`. diff --git a/src/main/asciidoc/reference/cq-container.adoc b/src/main/asciidoc/reference/cq-container.adoc index 8c3f83d5..1bdb36e8 100644 --- a/src/main/asciidoc/reference/cq-container.adoc +++ b/src/main/asciidoc/reference/cq-container.adoc @@ -1,28 +1,28 @@ [[apis:continuous-query]] = Continuous Query (CQ) -A powerful functionality offered by Apache Geode is +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 Geode matches the query predicate. _Spring Data Geode_ provides dedicated support for CQs through +that gets added to GemFire matches the query predicate. _Spring Data 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. -Basically _Spring Data Geode_ 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 Geode_ takes care +Basically _Spring Data GemFire_ allows methods on POJOs to become end-points for CQ. Simply define the query +and indicate the method that should be called to be notified when there is a match. _Spring Data GemFire_ 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 Apache Geode. +or interface implementations, based on Pivotal GemFire. -NOTE: Currently, Continuous Query is only supported in Geode's client/server topology. Additionally, the client Pool -used is required to have the subscription enabled. Please refer to the Geode +NOTE: Currently, Continuous Query is only supported in GemFire's client/server topology. Additionally, the client Pool +used is required to have the subscription enabled. Please refer to the GemFire http://geode.apache.org/docs/guide/11/developing/continuous_querying/implementing_continuous_querying.html[documentation] for more information. [[apis:continuous-query:container]] == Continuous Query Listener Container -_Spring Data Geode_ simplifies creation, registration, life-cycle and dispatch of CQ events by taking care of +_Spring Data GemFire_ 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,7 +33,7 @@ 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 Geode infrastructure concerns to the framework. +(and reacting to it), and delegate the boilerplate GemFire 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 @@ -45,10 +45,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 Geode_ CQ support. In a nutshell, +The `ContinuousQueryListenerAdapter` class is the final component in _Spring Data GemFire_ 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 Geode's http://geode.apache.org/releases/latest/javadoc/org/apache/geode/cache/query/CqListener.html[CqListener]. +similar to GemFire's http://geode.apache.org/releases/latest/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 +75,7 @@ class DefaultEventDelegate implements EventDelegate { } ---- -In particular, note how the above implementation of the `EventDelegate` interface has *no* Geode dependencies at all. +In particular, note how the above implementation of the `EventDelegate` interface has *no* GemFire 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 +115,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 Geode_ namespace to declare the event listener container +The example above uses the _Spring Data GemFire_ namespace to declare the event listener container and automatically register the listeners. The full blown, *beans* definition is displayed below: [source,xml] @@ -142,6 +142,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 Geode event +Each time an event is received, the adapter automatically performs type translation between the GemFire 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 f45717df..b9268527 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 Geode_ provides a `gfe-data` XML namespace -primarily intended to simplify the development of Apache Geode client applications. This namespace currently contains -support for Geode <> and function <> as well as -includes a `` tag that offers a convenient way to connect to the Apache Geode data grid. +In addition to the core XML namespace (`gfe`), _Spring Data GemFire_ provides a `gfe-data` XML namespace +primarily intended to simplify the development of Pivotal GemFire client applications. This namespace currently contains +support for GemFire <> and function <> as well as +includes a `` tag that offers a convenient way to connect to the Pivotal GemFire data grid. [[data-access:datasource]] -== An Easy Way to Connect to Geode +== An Easy Way to Connect to GemFire -For many applications, a basic connection to a Geode data grid using default values is sufficient. -_Spring Data Geode's_ `` tag provides a simple way to access data. The data source creates +For many applications, a basic connection to a GemFire data grid using default values is sufficient. +_Spring Data GemFire's_ `` tag provides a simple way to access data. The data source creates a `ClientCache` and connection `Pool`. In addition, it will query the cluster servers for all existing root Regions and create an (empty) client Region proxy for each one. diff --git a/src/main/asciidoc/reference/data.adoc b/src/main/asciidoc/reference/data.adoc index 5090b2e2..bd6613c3 100644 --- a/src/main/asciidoc/reference/data.adoc +++ b/src/main/asciidoc/reference/data.adoc @@ -1,19 +1,19 @@ [[apis]] -= Working with Apache Geode APIs += Working with Pivotal GemFire APIs -Once the Apache Geode Cache and Regions have been configured, they can be injected and used inside application objects. +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 Geode managed objects. +This chapter also covers support for dependency injection of GemFire managed objects. [[apis:template]] == GemfireTemplate -As with many other high-level abstractions provided by _Spring_ projects, _Spring Data Geode_ provides a *template* -to simplify Geode data access. The class provides several *one-liner* methods containing common Region operations, -but also has the ability to *execute* code against the native Geode API without having to deal with Geode checked +As with many other high-level abstractions provided by _Spring_ projects, _Spring Data GemFire_ provides a *template* +to simplify GemFire data access. The class provides several *one-liner* methods containing common Region operations, +but also has the ability to *execute* code against the native GemFire API without having to deal with GemFire checked exceptions by using a `GemfireCallback`. -The template class requires a Geode `Region` instance, and once configured, is thread-safe and can be reused +The template class requires a GemFire `Region` instance, and once configured, is thread-safe and can be reused across multiple application classes: [source,xml] @@ -22,7 +22,7 @@ across multiple application classes: ---- Once the template is configured, a developer can use it alongside `GemfireCallback` to work directly with -the Geode `Region` without having to deal with checked exceptions, threading or resource management concerns: +the GemFire `Region` without having to deal with checked exceptions, threading or resource management concerns: [source,java] ---- @@ -38,7 +38,7 @@ template.execute(new GemfireCallback>() { }); ---- -For accessing the full power of the Apache Geode query language, a developer can use the `find` and `findUnique` +For accessing the full power of the Pivotal GemFire query language, a developer can use the `find` and `findUnique` methods, which, as opposed to the `query` method, can execute queries across multiple Regions, execute projections, and the like. @@ -60,7 +60,7 @@ 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 Geode as long as the `CacheFactoryBean` is declared, e.g. using either a `` +is enabled when using GemFire 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. @@ -75,7 +75,7 @@ http://docs.spring.io/spring/docs/current/spring-framework-reference/htmlsingle/ about it 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 Apache Geode, _Spring Data Geode_ provides a dedicated, per-cache, `PlatformTransactionManager` that, +For Pivotal GemFire, _Spring Data GemFire_ provides a dedicated, per-cache, `PlatformTransactionManager` that, once declared, allows Region operations to be executed atomically through _Spring_: [source,xml] @@ -84,28 +84,32 @@ once declared, allows Region operations to be executed atomically through _Sprin ---- NOTE: The example above can be simplified even further by eliminating the `cache-ref` attribute if the GemFire cache -is defined under the default name, `gemfireCache`. As with the other _Spring Data Geode_ namespace elements, +is defined under the default name, `gemfireCache`. As with the other _Spring Data GemFire_ 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, Apache Geode supports optimistic transactions with *read committed* isolation. Furthermore, to guarantee +Currently, Pivotal GemFire 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, 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 bevior of the underlying Geode transaction manager, please refer to the Geode +For more information on the semantics and bevior of the underlying GemFire transaction manager, please refer to the GemFire 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]. +:leveloffset: +1 + include::{basedocdir}/reference/cq-container.adoc[] +:leveloffset: -1 + [[apis:declarable]] == Wiring `Declarable` Components -Apache Geode XML configuration (usually referred to as `cache.xml`) allows *user* objects to be declared +Pivotal GemFire 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 Geode. Using native Geode configuration, each user type declared through XML must implement +supported by GemFire. Using native GemFire configuration, each user type declared through XML must implement the `Declarable` interface, which allows arbitrary parameters to be passed to the declared class through a `Properties` instance. @@ -115,7 +119,7 @@ pluggable components to focus on the application logic and not the location or c or other collaborators. However, if you are starting a green field project, it is recommended that you configure Cache, Region, -and other pluggable Geode components directly in _Spring_. This avoids inheriting from the `Declarable` interface +and other pluggable GemFire 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. @@ -141,16 +145,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 Geode_ offers -a base class (`WiringDeclarableSupport`) that allows Geode user objects to be wired through a *template* bean definition +To simplify the task of parsing, converting the parameters and initializing the object, _Spring Data GemFire_ offers +a base class (`WiringDeclarableSupport`) that allows GemFire user objects to be wired through a *template* bean definition or, in case that is missing, perform 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 Geode 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 Apache Geode. +In the current 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. **** [[apis:declarable:template-wiring]] @@ -201,8 +205,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 Geode. For cases where the bean name uses a different convention, -one can pass in the `bean-name` parameter in the Geode configuration: +as a template for wiring the instance created by GemFire. For cases where the bean name uses a different convention, +one can pass in the `bean-name` parameter in the GemFire configuration: [source,xml] ---- @@ -298,11 +302,11 @@ the `DBLoader` code. [[apis:spring-cache-abstraction]] == Support for Spring Cache Abstraction -_Spring Data Geode_ provides an implementation of the _Spring_ +_Spring Data GemFire_ provides an implementation of the _Spring_ http://docs.spring.io/spring/docs/current/spring-framework-reference/htmlsingle/#cache[Cache Abstraction] -to position Apache Geode as a _caching provider_ in Spring's caching infrastructure. +to position Pivotal GemFire as a _caching provider_ in Spring's caching infrastructure. -To use Apache Geode as a backing implementation, simply add `GemfireCacheManager` to your configuration: +To use Pivotal GemFire as a backing implementation, simply add `GemfireCacheManager` to your configuration: [source,xml] ---- @@ -333,7 +337,7 @@ is used (i.e. "gemfireCache"), that is, `` 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 Geode Regions. +using GemFire 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 402097f8..151812f5 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 Geode_ supports `DiskStore` configuration via the `disk-store` element. +_Spring Data GemFire_ supports `DiskStore` configuration via the `disk-store` element. For example: @@ -15,8 +15,8 @@ For example: ---- `DiskStores` are used by Regions for file system persistent backup and overflow of evicted entries -as well as persistent backup of WAN Gateways. Multiple Geode components may share the same `DiskStore`. +as well as persistent backup of WAN Gateways. Multiple GemFire components may share the same `DiskStore`. Additionally, multiple file system directories may be defined for a single `DiskStore`. -Please refer to Apache Geode's documentation for a complete explanation of the +Please refer to Pivotal GemFire's documentation for a complete explanation of the http://geode.apache.org/docs/guide/11/developing/storing_data_on_disk/chapter_overview.html[configuration options]. diff --git a/src/main/asciidoc/reference/function-annotations.adoc b/src/main/asciidoc/reference/function-annotations.adoc index 661e9581..d9f40541 100644 --- a/src/main/asciidoc/reference/function-annotations.adoc +++ b/src/main/asciidoc/reference/function-annotations.adoc @@ -3,22 +3,22 @@ == Introduction -_Spring Data Geode_ includes annotation support to simplify working with Geode +_Spring Data GemFire_ includes annotation support to simplify working with GemFire http://geode.apache.org/docs/guide/11/developing/function_exec/chapter_overview.html[Function Execution]. -Under-the-hood, the Apache Geode API provides classes to implement and register Geode +Under-the-hood, the Pivotal GemFire API provides classes to implement and register GemFire http://geode.apache.org/releases/latest/javadoc/org/apache/geode/cache/execute/Function.html[Functions] -that are deployed on Geode servers, which may then be invoked by other peer member applications +that are deployed on GemFire servers, which may then be invoked by other peer member applications or remotely from cache clients. -Functions can execute in parallel, distributed among multiple Geode servers in the cluster, aggregating results +Functions can execute in parallel, distributed among multiple GemFire servers in the cluster, aggregating results with the map-reduce pattern that are sent back to the caller. Functions can also be targeted to run on a single server -or Region. The Apache Geode API supports remote execution of Functions targeted using various predefined scopes: +or Region. The Pivotal GemFire API supports remote execution of Functions targeted using various predefined scopes: on Region, on members [in groups], on servers, etc. The implementation and execution of remote Functions, as with any RPC protocol, requires some boilerplate code. -_Spring Data Geode_, true to _Spring's_ core value proposition, aims to hide the mechanics of remote Function execution -and allow developers to focus on core POJO programming and business logic. To this end, _Spring Data Geode_ introduces -annotations to declaratively register public methods of a POJO class as Geode Functions along with the ability to +_Spring Data GemFire_, true to _Spring's_ core value proposition, aims to hide the mechanics of remote Function execution +and allow developers to focus on core POJO programming and business logic. To this end, _Spring Data GemFire_ introduces +annotations to declaratively register public methods of a POJO class as GemFire Functions along with the ability to invoke registered Functions [remotely] via annotated interfaces. == Implementation vs Execution @@ -44,8 +44,8 @@ to aggregate and acquire the execution results. In certain cases, a custom `Res 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 Geode's client-server topology. While it is common for an application using a `ClientCache` -to invoke a Function on one or more Geode servers in a cluster, it is also possible to execute Functions +than client and server in GemFire's client-server topology. While it is common for an application using a `ClientCache` +to invoke a Function on one or more GemFire servers in a cluster, it is also possible to execute Functions in a peer-to-peer (P2P) configuration, where the application is a member of the cluster hosting a peer `Cache`. Keep in mind that a peer member cache application is subject to all the same constraints of being a peer member of the cluster. @@ -53,7 +53,7 @@ of the cluster. [[function-implementation]] == Implementing a Function -Using Geode APIs, the `FunctionContext` provides a runtime invocation context that includes the client's +Using GemFire APIs, the `FunctionContext` provides a runtime invocation context that includes the client's calling arguments and a `ResultSender` implementation to send results back to the client. Additionally, if the Function is executed on a Region, the `FunctionContext` is actually an instance of `RegionFunctionContext`, which provides additional information such as the target Region on which the Function was invoked @@ -120,7 +120,7 @@ public class ApplicationFunctions { } ---- -Note, the class itself must be registered as a _Spring_ bean and each Geode Function is annotated +Note, the class itself must be registered as a _Spring_ bean and each GemFire Function is annotated with `@GemfireFunction`. In this example, _Spring's_ `@Component` annotation was used, but you may register the bean by any method supported by _Spring_ (e.g. XML configuration or with a Java configuration class using _Spring Boot_). This allows the _Spring_ container to create an instance of this class and wrap it in a @@ -129,14 +129,14 @@ _Spring_ creates a wrapper instance for each method annotated with `@GemfireFunc 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 Geode components such as the Cache and Regions. These may be injected into the class +the `ApplicationContext` with GemFire components such as the Cache and Regions. These may be injected into the class if necessary. -_Spring_ creates the wrapper class and registers the Function(s) with Geode's Function Service. The Function id used +_Spring_ creates the wrapper class and registers the Function(s) with GemFire's Function Service. The Function id used to register the Functions must be unique. Using convention it defaults to the simple (unqualified) method name. The name can be explicitly defined using the `id` attribute of the `@GemfireFunction` annotation. The `@GemfireFunction` annotation also provides other configuration attributes, `HA` and `optimizedForWrite`, -which correspond to properties defined by Geode's +which correspond to properties defined by GemFire's http://geode.apache.org/releases/latest/javadoc/org/apache/geode/cache/execute/Function.html[Function] interface. If the method's return type is void, then the `hasResult` property is automatically set to `false`; otherwise, if the method returns a value the `hasResult` attributes is set to `true`. @@ -145,7 +145,7 @@ Even for `void` return types, the annotation's `hasResult` attribute can be set as shown in the `functionWithContext` method above. Presumably, the intention is to use the `ResultSender` directly to send results to the caller. -The `PojoFunctionWrapper` implements Geode's `Function` interface, binds method parameters and invokes the target method +The `PojoFunctionWrapper` implements GemFire's `Function` interface, binds method parameters and invokes the target method in its `execute()` method. It also sends the method's return value using the `ResultSender`. === Batching Results @@ -184,11 +184,11 @@ class ApplicationConfiguration { .. } == Executing a Function A process invoking a remote Function needs to provide the Function's ID, calling arguments, the execution target -(onRegion, onServers, onServer, onMember, onMembers) and optionally, a Filter set. Using _Spring Data Geode_, +(onRegion, onServers, onServer, onMember, onMembers) and optionally, a Filter set. Using _Spring Data GemFire_, all a developer need do is define an interface supported by annotations. _Spring_ will create a dynamic proxy for the interface, which will use the `FunctionService` to create an `Execution`, invoke the `Execution` and coerce the results to the defined return type, if necessary. This technique is very similar to the way -_Spring Data Geode's Repository extension_ works, thus some of the configuration and concepts should be familiar. +_Spring Data GemFire's Repository extension_ works, thus some of the configuration and concepts should be familiar. Generally, a single interface definition maps to multiple Function executions, one corresponding to each method defined in the interface. @@ -196,7 +196,7 @@ defined in the interface. To support client-side Function execution, the following SDG Function annotations are provided: `@OnRegion`, `@OnServer`, `@OnServers`, `@OnMember`, `@OnMembers`. These annotations correspond to the `Execution` implementations -prodided by Geode's +prodided by GemFire's http://geode.apache.org/releases/latest/javadoc/org/apache/geode/cache/execute/FunctionService.html[FunctionService]. Each annotation exposes the appropriate attributes. These annotations also provide an optional `resultCollector` attribute whose value is the name of a _Spring_ bean implementing the @@ -232,7 +232,7 @@ Function execution annotation processing in XML: [source,xml] ---- - + ---- The `function-executions` element is provided in the `gfe-data` namespace. The `base-package` attribute is required @@ -243,7 +243,7 @@ Optionally, a developer can annotate her Java configuration class: [source,java] ---- -@EnableGemfireFunctionExecutions(basePackages = "org.example.myapp.geode.functions") +@EnableGemfireFunctionExecutions(basePackages = "org.example.myapp.gemfire.functions") ---- [[function-execution-programmatic]] @@ -288,12 +288,12 @@ The Filter argument is optional. The following arguments are a variable argumen [[function-execution-pdx]] == Function Execution with PDX -When using _Spring Data Geode's_ Function annotation support combined with Apache Geode's +When using _Spring Data GemFire's_ Function annotation support combined with Pivotal GemFire's http://geode.apache.org/docs/guide/11/developing/data_serialization/gemfire_pdx_serialization.html[PDX Serialization], there are a few logistical things to keep in mind. -As explained above, and by way of example, typically developers will define Geode Functions using POJO classes -annotated with Spring Data Geode +As explained above, and by way of example, typically developers will define GemFire Functions using POJO classes +annotated with Spring Data GemFire http://docs.spring.io/spring-data-gemfire/docs/current/api/org/springframework/data/gemfire/function/annotation/package-summary.html[Function annotations] like so... @@ -334,7 +334,7 @@ public enum OrderSource { } ---- -Of course, a developer may define a Function `Execution` interface to call the 'process' Geode Server Function... +Of course, a developer may define a Function `Execution` interface to call the 'process' GemFire Server Function... [source,java] ---- @@ -349,16 +349,16 @@ Clearly, this `process(..)` `Order` Function is being called from a client-side The same is true when invoking peer-to-peer member Functions (e.g. `@OnMember(s)) between peers in the cluster. Any form of `distribution` requires the data transmitted between client and server, or peers, to be serialized. -Now, if the developer has configured Geode to use PDX for serialization (instead of Java serialization, for instance) +Now, if the developer has configured GemFire to use PDX for serialization (instead of Java serialization, for instance) it is common for developers to also set the `pdx-read-serialized` attribute to *true* in their configuration -of the Geode server(s)... +of the GemFire server(s)... [source,xml] ---- ---- -Or from a Geode cache client application... +Or from a GemFire cache client application... [source,xml] ---- @@ -368,24 +368,24 @@ Or from a Geode cache client application... This causes all values read from the cache (i.e. Regions) as well as information passed between client and servers, or peers, to remain in serialized form, including, but not limited to, Function arguments. -Geode will only serialize application domain object types that you have specifically configured (registered), -with either Geode's +GemFire will only serialize application domain object types that you have specifically configured (registered), +with either GemFire's http://gemfire-90-javadocs.docs.pivotal.io/org/apache/geode/pdx/ReflectionBasedAutoSerializer.html[ReflectionBasedAutoSerializer], -or specifically (and recommended) using a "custom" Geode +or specifically (and recommended) using a "custom" GemFire http://gemfire-90-javadocs.docs.pivotal.io/org/apache/geode/pdx/PdxSerializer.html[PdxSerializer]. If you are using -_Spring Data Geode's_ Repository extension to _Spring Data Common's_ Repository abstraction and infrastructure, -you might even want to consider using _Spring Data Geode's_ +_Spring Data GemFire's_ Repository extension to _Spring Data Common's_ Repository abstraction and infrastructure, +you might even want to consider using _Spring Data GemFire's_ http://docs.spring.io/spring-data-gemfire/docs/current/api/org/springframework/data/gemfire/mapping/MappingPdxSerializer.html[MappingPdxSerializer], which uses a entity's mapping meta-data to determine data from the application domain object that will be serialized to the PDX instance. -What is less than apparent, though, is that Geode automatically handles Java Enum types regardless of whether they are +What is less than apparent, though, is that GemFire automatically handles Java Enum types regardless of whether they are explicitly configured or not (i.e. registered with a `ReflectionBasedAutoSerializer` using a regex pattern -and the `classes` parameter, or are handled by a "custom" Geode `PdxSerializer`), despite the fact that Java Enums +and the `classes` parameter, or are handled by a "custom" GemFire `PdxSerializer`), despite the fact that Java Enums implement `java.io.Serializable`. -So, when a developer sets `pdx-read-serialized` to *true* on Geode Servers where the Geode Functions -(including Spring Data Geode Function annotated POJO classes) are registered, then the developer +So, when a developer sets `pdx-read-serialized` to *true* on GemFire Servers where the GemFire Functions +(including Spring Data GemFire Function annotated POJO classes) are registered, then the developer may encounter surprising behavior when invoking the Function `Execution`. What the developer may pass as arguments when invoking the Function is... @@ -395,7 +395,7 @@ What the developer may pass as arguments when invoking the Function is... orderProcessingFunctions.process(new Order(123, customer, Calendar.getInstance(), items), OrderSource.ONLINE, 400); ---- -But, what the Geode Function on the Server gets is... +But, what the GemFire Function on the Server gets is... [source,java] ---- @@ -405,32 +405,32 @@ 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]. Again, this is all because `pdx-read-serialized` is set to *true*, which may be necessary in cases where -the Geode Servers are interacting with multiple different clients (e.g. Java, native clients, such as C++/C#, etc). +the GemFire Servers are interacting with multiple different clients (e.g. Java, native clients, such as C++/C#, etc). -This flies in the face of _Spring Data Geode's_ "strongly-typed", Function annotated POJO class method signatures, +This flies in the face of _Spring Data GemFire's_ "strongly-typed", Function annotated POJO class method signatures, as the developer is expecting application domain object types, not PDX serialized instances. -So, _Spring Data Geode_ includes enhanced Function support to automatically convert method arguments passed to +So, _Spring Data GemFire_ includes enhanced Function support to automatically convert method arguments passed to the Function that are of type PDX to the desired application domain object types defined by the Function method's parameter types. -However, this also requires the developer to explicitly register a Geode `PdxSerializer` on the Geode Servers -where _Spring Data Geode_ Function annotated POJOs are registered and used, e.g. ... +However, this also requires the developer to explicitly register a GemFire `PdxSerializer` on the GemFire Servers +where _Spring Data GemFire_ Function annotated POJOs are registered and used, e.g. ... [source,java] ---- - + ---- -Alternatively, a developer my use Geode's +Alternatively, a developer my use GemFire's http://gemfire-90-javadocs.docs.pivotal.io/org/apache/geode/pdx/ReflectionBasedAutoSerializer.html[ReflectionBasedAutoSerializer] for convenience. Of course, it is recommended that you use a "custom" `PdxSerializer` where possible to maintain finer grained control over your serialization strategy. -Finally, _Spring Data Geode_ is careful not to convert your Function arguments if you treat your Function arguments -generically, or as one of Geode's PDX types... +Finally, _Spring Data GemFire_ is careful not to convert your Function arguments if you treat your Function arguments +generically, or as one of GemFire's PDX types... [source,java] ---- @@ -440,9 +440,9 @@ public Object genericFunction(String value, Object domainObject, PdxInstanceEnum } ---- -_Spring Data Geode_ only converts PDX type data to the corresponding application domain types if and only if +_Spring Data GemFire_ only converts PDX type data to the corresponding application domain types if and only if the corresponding application domain types are on the classpath the the Function annotated POJO method expects it. -For a good example of "custom", "composed" application-specific Geode `PdxSerializers` as well as appropriate -POJO Function parameter type handling based on the method signatures, see Spring Data Geode's -https://github.com/spring-projects/spring-data-gemfire/blob/1.0.0.APACHE-GEODE-INCUBATING-RELEASE/src/test/java/org/springframework/data/gemfire/function/ClientCacheFunctionExecutionWithPdxIntegrationTest.java[ClientCacheFunctionExecutionWithPdxIntegrationTest] class. +For a good example of "custom", "composed" application-specific GemFire `PdxSerializers` as well as appropriate +POJO Function parameter type handling based on the method signatures, see Spring Data GemFire's +https://github.com/spring-projects/spring-data-gemfire/blob/2.0.0.M2/src/test/java/org/springframework/data/gemfire/function/ClientCacheFunctionExecutionWithPdxIntegrationTest.java[ClientCacheFunctionExecutionWithPdxIntegrationTest] class. diff --git a/src/main/asciidoc/reference/function.adoc b/src/main/asciidoc/reference/function.adoc index d43a2762..144c9037 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 Geode_ provides <> support for implementing and registering -Apache Geode Functions. +_Spring Data GemFire_ provides <> support for implementing and registering +Pivotal GemFire Functions. -_Spring Data Geode_ also provides namespace support for registering Apache Geode +_Spring Data GemFire_ also provides namespace support for registering Pivotal GemFire http://geode.apache.org/releases/latest/javadoc/org/apache/geode/cache/execute/Function.html[Functions] for remote Function execution. -Please refer to Apache Geode' http://geode.apache.org/docs/guide/11/developing/function_exec/chapter_overview.html[documentation] +Please refer to Pivotal GemFire' http://geode.apache.org/docs/guide/11/developing/function_exec/chapter_overview.html[documentation] for more information on the Function execution framework. -Geode Functions are declared as _Spring_ beans and must implement the `org.apache.geode.cache.execute.Function` +GemFire Functions are declared as _Spring_ beans and must implement the `org.apache.geode.cache.execute.Function` interface or extend `org.apache.geode.cache.execute.FunctionAdapter`. The namespace uses a familiar pattern to declare functions: diff --git a/src/main/asciidoc/reference/gateway.adoc b/src/main/asciidoc/reference/gateway.adoc index 1eaefe6d..8809dda6 100644 --- a/src/main/asciidoc/reference/gateway.adoc +++ b/src/main/asciidoc/reference/gateway.adoc @@ -1,8 +1,8 @@ [[bootstrap:gateway]] = Configuring WAN Gateways -WAN Gateways provide a way to synchronize Apache Geode Distributed Systems across geographic areas. -_Spring Data Geode_ provides namespace support for configuring WAN Gateways as illustrated in the following examples. +WAN Gateways provide a way to synchronize Pivotal GemFire Distributed Systems across geographic areas. +_Spring Data GemFire_ provides namespace support for configuring WAN Gateways as illustrated in the following examples. == WAN Configuration in GemFire 7.0 @@ -60,6 +60,6 @@ The `GatewayReceiver` may also be configured with `EventFilters` and `TransportF ---- -Please refer to the Apache Geode +Please refer to the Pivotal GemFire http://geode.apache.org/docs/guide/11/topologies_and_comm/multi_site_configuration/chapter_overview.html[documentation] for a detailed explanation of all the configuration options. diff --git a/src/main/asciidoc/reference/gemfire-bootstrap.adoc b/src/main/asciidoc/reference/gemfire-bootstrap.adoc index aaccaea8..ff2940e2 100644 --- a/src/main/asciidoc/reference/gemfire-bootstrap.adoc +++ b/src/main/asciidoc/reference/gemfire-bootstrap.adoc @@ -1,39 +1,39 @@ [[gemfire-bootstrap]] -= Bootstrapping a Spring ApplicationContext in Apache Geode += Bootstrapping a Spring ApplicationContext in Pivotal GemFire == Introduction -Normally, a _Spring_-based application will <> using _Spring Data Geode's. -Just by specifying a `` element using the _Spring Data Geode_ XML namespace, a single, embedded Geode +Normally, a _Spring_-based application will <> using _Spring Data GemFire's. +Just by specifying a `` element using the _Spring Data GemFire_ XML namespace, a single, embedded GemFire peer `Cache` instance is created and initialized with default settings in the same JVM process as your application. -However, it is sometimes necessary, perhaps a requirement imposed by your IT organization, that Geode be fully managed -and operated using the provided Apache Geode tool suite, such as with +However, it is sometimes necessary, perhaps a requirement imposed by your IT organization, that GemFire be fully managed +and operated using the provided Pivotal GemFire tool suite, such as with http://geode.apache.org/docs/guide/11/tools_modules/gfsh/chapter_overview.html[Gfsh]. By using _Gfsh_, -Geode will bootstrap your _Spring_ application context rather than the other way around. Instead of -an application server, or a Java main class using _Spring Boot_, whatever, Geode does the bootstrapping and will +GemFire will bootstrap your _Spring_ application context rather than the other way around. Instead of +an application server, or a Java main class using _Spring Boot_, whatever, GemFire does the bootstrapping and will host your application. -Keep in mind, however, that Geode is not an application server. In addition, there are limitations to using -this approach where Geode cache configuration is concerned. +Keep in mind, however, that GemFire is not an application server. In addition, there are limitations to using +this approach where GemFire cache configuration is concerned. [[gemfire-bootstrap-gfsh]] -== Using Apache Geode to Bootstrap a Spring Context Started with Gfsh +== Using Pivotal GemFire to Bootstrap a Spring Context Started with Gfsh -In order to bootstrap a _Spring_ application context in Geode when starting a Geode Server process using _Gfsh_, -a user must make use of Geode's +In order to bootstrap a _Spring_ application context in GemFire when starting a GemFire Server process using _Gfsh_, +a user must make use of GemFire's http://geode.apache.org/docs/guide/11/basic_config/the_cache/setting_cache_initializer.html[Initalizer] functionality. -An Initializer block can declare a callback application that is launched after the cache is initialized by Geode. +An Initializer block can declare a callback application that is launched after the cache is initialized by GemFire. An Initializer is declared within an http://geode.apache.org/docs/guide/11/reference/topics/cache_xml.html#initializer[initializer] element -using a minimal snippet of Geode's native `cache.xml`. The `cache.xml` file is required in order to bootstrap +using a minimal snippet of GemFire's native `cache.xml`. The `cache.xml` file is required in order to bootstrap the _Spring_ application context, much like a minimal snippet of _Spring_ XML config is needed to bootstrap a _Spring_ application context configured with component scanning (e.g. ``) Fortunately, such an Initializer is already conveniently provided by the framework, the http://docs.spring.io/spring-data-gemfire/docs/current/api/org/springframework/data/gemfire/support/SpringContextBootstrappingInitializer.html[SpringContextBootstrappingInitializer]. -A typical, yet very minimal configuration for this class inside Geodes's `cache.xml` file will look like this: +A typical, yet very minimal configuration for this class inside GemFires's `cache.xml` file will look like this: [source,xml] ---- @@ -81,7 +81,7 @@ on the classpath: ---- Then, with a properly configured and constructed `CLASSPATH` along with `cache.xml` file shown above, specified as -a command-line option when starting a Geode Server in _Gfsh_, the command-line would be: +a command-line option when starting a GemFire Server in _Gfsh_, the command-line would be: [source] ---- @@ -92,34 +92,34 @@ gfsh>start server --name=Server1 --log-level=config ... The `application-context.xml` can be any valid _Spring_ context configuration meta-data including all the SDG namespace elements. The only limitation with this approach is that a GemFire cache cannot be configured using -the _Spring Data Geode_ namespace. In other words, none of the `` element attributes, +the _Spring Data GemFire_ namespace. In other words, none of the `` element attributes, such as `cache-xml-location`, `properties-ref`, `critical-heap-percentage`, `pdx-serializer-ref`, `lock-lease`, etc, can be specified. If used, these attributes will be ignored. -The reason for this is that Geode itself has already created an initialized the cache before the Initializer +The reason for this is that GemFire itself has already created an initialized the cache before the Initializer gets invoked. As such, the cache will already exist and since it is a "Singleton", it cannot be re-initialized or have any of it's configuration augmented. [[gemfire-bootstrap-lazywiring]] == Lazy-Wiring GemFire Components -_Spring Data Geode_ already provides existing support for wiring Geode components, such as `CacheListeners`, -`CacheLoaders`, `CacheWriters` and so on, that are declared and created by Geode in `cache.xml` using +_Spring Data GemFire_ already provides existing support for wiring GemFire components, such as `CacheListeners`, +`CacheLoaders`, `CacheWriters` and so on, that are declared and created by GemFire in `cache.xml` using SDG's `WiringDeclarableSupport` class as described in <>. However, this only works -when _Spring_ is the one doing the bootstrapping (i.e. bootstrapping Geode). +when _Spring_ is the one doing the bootstrapping (i.e. bootstrapping GemFire). -When your _Spring_ application context is bootstrapped by Geode, then these Geode application components go unnoticed +When your _Spring_ application context is bootstrapped by GemFire, then these GemFire application components go unnoticed since the _Spring_ application context does not even exist yet! The _Spring_ application context will not get created -until Geode calls the Initializer block, which only occurs after all the other Geode components and configuration +until GemFire calls the Initializer block, which only occurs after all the other GemFire components and configuration have already been created and initialized. So, in order to solve this problem, a new `LazyWiringDeclarableSupport` class was introduced that is, in a sense, _Spring_ application context aware. The intention of this abstract base class is that any implementing class -will register itself to be configured by the _Spring_ container that will eventually be created by Geode -once the Initializer is called. In essence, this give your Geode defined application components a chance +will register itself to be configured by the _Spring_ container that will eventually be created by GemFire +once the Initializer is called. In essence, this give your GemFire defined application components a chance to be configured and auto-wired with _Spring_ beans defined in the _Spring_ application context. -In order for your Geode application components to be auto-wired by the _Spring_ container, create an application class +In order for your GemFire application components to be auto-wired by the _Spring_ container, 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: @@ -136,12 +136,12 @@ public class UserDataSourceCacheLoader extends LazyWiringDeclarableSupport ---- As implied in the `CacheLoader` example above, you might necessarily (although, rarely) have defined both -a Region and `CacheListener` component in Geode `cache.xml`. The `CacheLoader` may need access to an application DAO, -or perhaps a _Spring_ application context defined JDBC `DataSource` for loading `Users` into a Geode `REPLICATE` Region +a Region and `CacheListener` component in GemFire `cache.xml`. The `CacheLoader` may need access to an application DAO, +or perhaps a _Spring_ application context defined JDBC `DataSource` for loading `Users` into a GemFire `REPLICATE` Region on start. -CAUTION: Be careful when mixing the different life-cycles of Apache Geode and the _Spring_ Container together -in this manner as not all use cases and scenarios are supported. The Geode `cache.xml` configuration would be +CAUTION: Be careful when mixing the different life-cycles of Pivotal GemFire and the _Spring_ Container together +in this manner as not all use cases and scenarios are supported. The GemFire `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 6447c169..7206ab97 100644 --- a/src/main/asciidoc/reference/indexing.adoc +++ b/src/main/asciidoc/reference/indexing.adoc @@ -1,16 +1,16 @@ [[bootstrap:indexing]] = Configuring an Index -Apache Geode allows Indexes (or Indices) to be created to improve the performance of OQL queries. +Pivotal GemFire allows Indexes (or Indices) to be created to improve the performance of OQL queries. -In _Spring Data Geode_, Indexes are declared with the `index` element: +In _Spring Data GemFire_, Indexes are declared with the `index` element: [source,xml] ---- ---- -Before creating the `Index`, _Spring Data Geode_ will verify whether an `Index` with the same name already exists. +Before creating the `Index`, _Spring Data GemFire_ will verify whether an `Index` with the same name already exists. By default, SDG overrides an existing `Index` if an `Index` with the same name already exists. The existing Index is overridden by removing the old `Index` first followed by creating a new `Index` with the same name defined by the new bean definition, regardless if the old `Index` definition was the same or not. @@ -21,5 +21,5 @@ in a significant way, then set the `override` attribute to *false*, which effect `Index` declarations are not bound to a Region but rather are top-level elements (just like `cache`). This allows one to declare any number of Indices on any Region whether they are just created or already exist -- an improvement over Geode's native `cache.xml`. By default, the `Index` relies on the default cache declaration +- an improvement over GemFire's native `cache.xml`. By default, the `Index` relies on the default cache declaration but one can customize it accordingly or use a Pool (if need be) - see the XML schema for a full set of options. diff --git a/src/main/asciidoc/reference/introduction.adoc b/src/main/asciidoc/reference/introduction.adoc index f9d56c55..1d5a6a71 100644 --- a/src/main/asciidoc/reference/introduction.adoc +++ b/src/main/asciidoc/reference/introduction.adoc @@ -1,24 +1,24 @@ [[ref-introduction]] = Document Structure -The following chapters explain the core functionality offered by _Spring Data Geode_ for Apache Geode. +The following chapters explain the core functionality offered by _Spring Data GemFire_ for Pivotal GemFire. <> describes the configuration support provided for bootstrapping, configuring, initializing -and accessing Apache Geode Caches, Regions, and related Distributed System components. +and accessing Pivotal GemFire Caches, Regions, and related Distributed System components. -<> explains the integration between the Apache Geode APIs and the various data access features +<> explains the integration between the Pivotal GemFire APIs and the various data access features available in _Spring_, such as transaction management and exception translation. -<> describes the enhancements for Apache Geode (de)serialization and management of associated objects. +<> describes the enhancements for Pivotal GemFire (de)serialization and management of associated objects. -<> describes persistence mapping for POJOs stored in Apache Geode using _Spring Data_. +<> describes persistence mapping for POJOs stored in Pivotal GemFire using _Spring Data_. -<> describes how to create and use _Spring Data Repositories_ to access data in Apache Geode. +<> describes how to create and use _Spring Data Repositories_ to access data in Pivotal GemFire. -<> describes how to create and use Apache Geode Functions using Annotations. +<> describes how to create and use Pivotal GemFire Functions using Annotations. -<> describes how to bootstrap a _Spring_ `ApplicationContext` running in an Apache Geode server +<> describes how to bootstrap a _Spring_ `ApplicationContext` running in an Pivotal GemFire server using _Gfsh_. <> describes the examples provided with the distribution to illustrate the various features -available in _Spring Data Geode_. +available in _Spring Data GemFire_. diff --git a/src/main/asciidoc/reference/lucene.adoc b/src/main/asciidoc/reference/lucene.adoc index 2967fce2..798465e7 100644 --- a/src/main/asciidoc/reference/lucene.adoc +++ b/src/main/asciidoc/reference/lucene.adoc @@ -1,11 +1,11 @@ [[bootstrap:lucene]] = Apache Lucene Integration -http://geode.apache.org/[Apache Geode] integrates with http://lucene.apache.org/[Apache Lucene] to allow developers -to index and search on data stored in Apache Geode using Lucene queries. Search-based queries also includes +https://pivotal.io/pivotal-gemfire[Pivotal GemFire] integrates with http://lucene.apache.org/[Apache Lucene] to allow developers +to index and search on data stored in Pivotal GemFire using Lucene queries. Search-based queries also includes the capability to page through query results. -Additionally, _Spring Data Geode_ adds support for query projections based on _Spring Data Commons_ +Additionally, _Spring Data GemFire_ adds support for query projections based on _Spring Data Commons_ Projection infrastructure. This feature enables the query results to be projected into first-class, application domain types as needed or required by the application use case. @@ -68,11 +68,11 @@ LuceneIndexFactoryBean personTitleIndex(GemFireCache gemFireCache) { } ---- -There are a few limitations of Apache Geode's, Apache Lucene integration support. First, a `LuceneIndex` can only -be created on a Geode `PARTITION` Region. Second, all `LuceneIndexes` must be created before the the Region on which +There are a few limitations of Pivotal GemFire's, Apache Lucene integration support. First, a `LuceneIndex` can only +be created on a GemFire `PARTITION` Region. Second, all `LuceneIndexes` must be created before the the Region on which the `LuceneIndex` is applied. -It is possible that these Apache Geode restrictions will not apply in a future release which is why +It is possible that these Pivotal GemFire restrictions will not apply in a future release which is why the SDG `LuceneIndexFactoryBean` API takes a reference to the Region directly as well, rather than just the Region path. This is more ideal if think about the case in which users may want to define a `LuceneIndex` on an existing Region @@ -83,10 +83,10 @@ Now that we have a `LuceneIndex` we can perform Lucene based data access operati == Lucene Template Data Accessors -_Spring Data Geode_ provides 2 primary templates for Lucene data access operations, depending on how low a level +_Spring Data GemFire_ provides 2 primary templates for Lucene data access operations, depending on how low a level your application is prepared to deal with. -The `LuceneOperations` interface defines query operations using Apache Geode +The `LuceneOperations` interface defines query operations using Pivotal GemFire http://geode.apache.org/releases/latest/javadoc/org/apache/geode/cache/lucene/package-frame.html[Lucene types]. [source,java] @@ -117,18 +117,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 Apache Geode's +The operations in the `LuceneOperations` interface match the operations provided by the Pivotal GemFire's http://geode.apache.org/releases/latest/javadoc/org/apache/geode/cache/lucene/LuceneQuery.html[LuceneQuery] interface. -However, SDG has the added value of translating proprietary Geode or Lucene `Exceptions` into _Spring's_ highly +However, SDG has the added value of translating proprietary GemFire or Lucene `Exceptions` into _Spring's_ highly consistent and expressive DAO http://docs.spring.io/spring/docs/current/spring-framework-reference/htmlsingle/#dao-exceptions[Exception Hierarchy], particularly as many modern data access operations involve more than single store or repository. Additionally, SDG's `LuceneOperations` interface can shield your application from interface breaking changes -introduced by the underlying Apache Geode or Apache Lucene APIs when they do and will occur. +introduced by the underlying Pivotal GemFire or Apache Lucene APIs when they do and will occur. -However, it would be remorse to only offer a Lucene Data Access Object that only uses Apache Geode and Apache Lucene -data types (e.g. Geode's `LuceneResultStruct`), therefore SDG gives you the `ProjectingLuceneOperations` interface +However, it would be remorse to only offer a Lucene Data Access Object that only uses Pivotal GemFire and Apache Lucene +data types (e.g. GemFire's `LuceneResultStruct`), therefore SDG gives you the `ProjectingLuceneOperations` interface to remedy these important application concerns. [source,java] @@ -235,8 +235,8 @@ A custom `ProjectionFactory` can be set on a Lucene template using `setProjectio == Annotation configuration support -Finally, _Spring Data Geode_ provides Annotation configuration support for `LuceneIndexes`. Eventually, the SDG Lucene -support will find its way into the _Repository_ infrastructure extension for Apache Geode so that Lucene queries +Finally, _Spring Data GemFire_ provides Annotation configuration support for `LuceneIndexes`. Eventually, the SDG Lucene +support will find its way into the _Repository_ infrastructure extension for Pivotal GemFire so that Lucene queries can be expressed as methods on an application `Repository` interface, much like the http://docs.spring.io/spring-data-gemfire/docs/current/reference/html/#gemfire-repositories.executing-queries[OQL support] today. diff --git a/src/main/asciidoc/reference/mapping.adoc b/src/main/asciidoc/reference/mapping.adoc index 02c6680c..1c95530d 100644 --- a/src/main/asciidoc/reference/mapping.adoc +++ b/src/main/asciidoc/reference/mapping.adoc @@ -4,10 +4,10 @@ [[mapping.entities]] == Entity Mapping -_Spring Data Geode_ provides support to map entities that will be stored in a Region in the Geode In-Memory Data Grid. +_Spring Data GemFire_ provides support to map entities that will be stored in a Region in the GemFire In-Memory Data Grid. The mapping metadata is defined using annotations on application domain classes just like this: -.Mapping a domain class to a Geode Region +.Mapping a domain class to a GemFire Region ==== [source,java] ---- @@ -53,17 +53,17 @@ public class Guest extends User { } ---- -Be sure to use the full-path of the Geode Region, as defined with the _Spring Data Geode_ XML namespace +Be sure to use the full-path of the GemFire Region, as defined with the _Spring Data GemFire_ XML namespace 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 Geode_ also recognizes the Region type-specific +In addition to the `@Region` annotation, _Spring Data GemFire_ also recognizes the Region type-specific mapping annotations: `@ClientRegion`, `@LocalRegion`, `@PartitionRegion` and `@ReplicateRegion`. Functionally, these annotations are treated exactly the same as the generic `@Region` annotation in the SDG -mapping infrastructure. However, these additional mapping annotations are useful in _Spring Data Geode's` +mapping infrastructure. However, these additional mapping annotations are useful in _Spring Data GemFire's` Annotation configuration model. When combined with the `@EnableEntityDefinedRegions` configuration annotation on _Spring_ `@Configuration` annotated class, it is possible to generate Regions in the local cache, whether the application is a client or peer. @@ -84,7 +84,7 @@ As an alternative to specifying the Region in which the entity will be stored us on the entity class, you can also specify the `@Region` annotation on the entity's `Repository`. See <> for more details. -However, let's say you want to store a `Person` in multiple Geode Regions (e.g. `People` and `Customers`), +However, let's say you want to store a `Person` in multiple GemFire Regions (e.g. `People` and `Customers`), then you can define your corresponding `Repository` interface extensions like so: [source,java] @@ -100,7 +100,7 @@ public interface CustomerRepository extends GemfireRepository { } ---- -Then, using each Repository individually, you can store the entity in multiple Geode Regions. +Then, using each Repository individually, you can store the entity in multiple GemFire Regions. [source,java] ---- @@ -124,7 +124,7 @@ either as a local cache transaction or a global transaction. [[mapping.pdx-serializer]] == Mapping PDX Serializer -_Spring Data Geode_ provides a custom +_Spring Data GemFire_ provides a custom http://geode.apache.org/releases/latest/javadoc/org/apache/geode/pdx/PdxSerializer.html[PdxSerializer] implementation that uses the mapping information to customize entity serialization. Beyond that, it allows customizing the entity instantiation by using the Spring Data `EntityInstantiator` abstraction. By default the serializer diff --git a/src/main/asciidoc/reference/region.adoc b/src/main/asciidoc/reference/region.adoc index c15defc1..0d1ebc9b 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. -Geode implements the following types of Regions: +GemFire 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 Apache Geode's documentation on +please refer to Pivotal GemFire's documentation on http://geode.apache.org/docs/guide/11/developing/region_options/region_types.html[Region Types]. [[bootstrap:region:lookup]] == Using an externally configured Region -To reference Regions already configured in a Geode native `cache.xml` file, use the `lookup-region` element. +To reference Regions already configured in a GemFire 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" allows all Regions defined in a Geode native `cache.xml` file to be imported into a _Spring_ +"auto-lookup" allows all Regions defined in a GemFire native `cache.xml` file to be imported into a _Spring_ application context when using the`cache-xml-location` attribute on the `` element. For instance, given a `cache.xml` file of... @@ -97,12 +97,12 @@ with: ---- -_Spring Data Geode_ will automatically create beans for all Geode Regions defined in `cache.xml` that have not been +_Spring Data GemFire_ will automatically create beans for all GemFire Regions defined in `cache.xml` that have not been explicitly added to the _Spring_ context with explicit `` bean declarations. -It is important to realize that _Spring Data Geode_ uses a _Spring_ +It is important to realize that _Spring Data GemFire_ uses a _Spring_ http://docs.spring.io/spring/docs/current/javadoc-api/org/springframework/beans/factory/config/BeanPostProcessor.html[BeanPostProcessor] -to post process the cache after it is both created and initialized to determine the Regions defined in Geode to add +to post process the cache after it is both created and initialized to determine the Regions defined in GemFire to add as beans in the _Spring_ application context. You may inject these "auto-looked-up" Regions like any other bean defined in the _Spring_ application context with @@ -137,20 +137,20 @@ If you are declaring your components using _Spring_ XML config, then you would d ---- -This ensures the Geode cache and all the Regions defined in `cache.xml` get created before any components +This ensures the GemFire cache and all the Regions defined in `cache.xml` get created before any components with auto-wire references when using the new `` element. [[bootstrap:region:overview]] == Configuring Regions -_Spring Data Geode_ provides comprehensive support for configuring any type of Region via the following elements: +_Spring Data GemFire_ provides comprehensive support for configuring any type of Region via the following elements: * LOCAL Region: `` * PARTITION Region: `` * REPLICATE Region: `` * Client Region: `` -Please see the Apache Geode documentation for a comprehensive description of +Please see the Pivotal GemFire documentation for a comprehensive description of http://geode.apache.org/docs/guide/11/developing/region_options/region_types.html[Region Types]. [[bootstrap:region:attributes]] @@ -166,8 +166,8 @@ The following table lists attributes available for all Region types: | Description | cache-ref -| Geode Cache bean reference -| The name of the bean defining the Geode Cache (by default 'gemfireCache'). +| GemFire Cache bean reference +| The name of the bean defining the GemFire Cache (by default 'gemfireCache'). | cloning-enabled | boolean, default:false @@ -182,7 +182,7 @@ The following table lists 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 Geode's http://geode.apache.org/releases/latest/javadoc/org/apache/geode/cache/DataPolicy.html[Data Policy] +| See GemFire's http://geode.apache.org/releases/latest/javadoc/org/apache/geode/cache/DataPolicy.html[Data Policy] | The Region's Data Policy. Note, not all Data Policies are supported for every Region type. | destroy @@ -297,7 +297,7 @@ mutually exclusive and using both in the same element will result in an exceptio .Bean Reference Conventions [NOTE] ==== -The `cache-listener` element is an example of a common pattern used in the namespace anywhere Geode provides +The `cache-listener` element is an example of a common pattern used in the namespace anywhere GemFire provides a callback interface to be implemented in order to invoke custom code in response to Cache or Region events. Using _Spring's_ IoC container, the implementation is a standard _Spring_ bean. In order to simplify the configuration, the schema allows a single occurrence of the `cache-listener` element, but it may contain nested bean references @@ -311,11 +311,11 @@ configuration example. === CacheLoaders and CacheWriters Similar to `cache-listener`, the namespace provides `cache-loader` and `cache-writer` elements to register -these Geode components respectively for a Region. +these GemFire components respectively for a Region. A `CacheLoader` is invoked on a cache miss to allow an entry to be loaded from an external data source, such as a database. A `CacheWriter` is invoked before an entry is created or updated, intended for synchronizing to -an external data source. The difference is Geode only supports at most a single instance `CacheLoader` and `CacheWriter` +an external data source. The difference is GemFire only supports at most a single instance `CacheLoader` and `CacheWriter` per Region. However, either declaration style may be used. Example: @@ -340,12 +340,12 @@ Example: 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 Apache Geode documentation for more details. +in the Pivotal GemFire documentation for more details. [[bootstrap:region:compression]] == Compression -Geode Regions may also be compressed in order to reduce JVM memory consumption and pressure to possibly avoid +GemFire Regions may also be compressed in order to reduce JVM memory consumption and pressure to possibly avoid stop the world GCs. When you enable compression for a Region, all values stored in the Region, in-memory are compressed while keys and indexes remain uncompressed. New values are compressed when put into Region and all values are decompressed automatically when read back from the Region. Values are not compressed when @@ -364,17 +364,17 @@ Example: ---- -Please refer to Apache Geode's documentation for more information on +Please refer to Pivotal GemFire's documentation for more information on http://gemfire.docs.pivotal.io/geode/managing/region_compression/region_compression.html[Region Compression]. [[bootstrap:region:subregions]] == Subregions -_Spring Data Geode_ also supports Subregions, allowing Regions to be arranged in a hierarchical relationship. +_Spring Data GemFire_ also supports Subregions, allowing Regions to be arranged in a hierarchical relationship. -For example, Geode allows for a */Customer/Address* Region and a different */Employee/Address* Region. Additionally, +For example, GemFire allows for a */Customer/Address* Region and a different */Employee/Address* Region. Additionally, a Subregion may have it's own Subregions and its own configuration. A Subregion does not inherit attributes from -the parent Region. Regions types may be mixed and matched subject to Geode constraints. A Subregion is naturally +the parent Region. Regions types may be mixed and matched subject to GemFire constraints. A Subregion is naturally declared as a child element of a Region. The Subregion's name attribute is the simple name. The above example might be configured as: @@ -399,11 +399,11 @@ OQL query strings. [[bootstrap:region:templates]] == Region Templates -_Spring Data Geode_ also supports Region Templates. This feature allows developers to define common Region +_Spring Data GemFire_ also supports Region Templates. This feature allows developers to define common Region configuration settings and attributes once and reuse the configuration among many Region bean definitions declared in the _Spring_ application context. -_Spring Data Geode_ includes 5 Region template tags in namespace: +_Spring Data GemFire_ includes 5 Region template tags in namespace: [cols="1,2", options="header"] .Region Template Tags @@ -481,7 +481,7 @@ Attributes and sub-elements defined in subsequent, inherited Region bean definit === How Templating Works -_Spring Data Geode_ applies Region Templates when the _Spring_ application context configuration meta-data is *parsed*, +_Spring Data GemFire_ applies Region Templates when the _Spring_ application context configuration meta-data is *parsed*, and therefore, *must be declared in the order of inheritance*. In other words, parent templates must be defined before children. This ensures the proper configuration is applied, especially when element attributes or sub-elements are "overridden". @@ -495,14 +495,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 Geode_ XML namespace was to perform a lookup first before +and `client-region` elements in the _Spring Data GemFire_ XML namespace was to perform a lookup first before attempting to create a Region. This was done in case the Region already existed, which would be the case -if the Region was defined in an imported Geode native `cache.xml` configuration file. Therefore, the lookup +if the Region was defined in an imported GemFire native `cache.xml` configuration file. Therefore, the lookup was performed first to avoid any errors. This was by design and subject to change. This behavior has been altered and the default behavior is now to create the Region first. If the Region already exists, then the creation logic fails-fast and an appropriate exception is thrown. However, much like the -`CREATE TABLE IF NOT EXISTS ...` DDL syntax, the _Spring Data Geode_ `<*-region>` namespace elements now includes +`CREATE TABLE IF NOT EXISTS ...` DDL syntax, the _Spring Data GemFire_ `<*-region>` namespace elements now includes a `ignore-if-exists` attribute, which re-instates the old behavior by performing a lookup of an existing Region identified by name, first. If an existing Region by name is found and `ignore-if-exists` is set to `true`, then the Region bean definition defined in _Spring_ config is ignored. @@ -518,7 +518,7 @@ by the application. Even worse, the application developer may want to define th IMPORTANT: Recommended Practice - Only use `replicated-region`, `partitioned-region`, `local-region` and `client-region` namespace elements to define new Regions. -Consider the following native Geode `cache.xml` configuration file... +Consider the following native GemFire `cache.xml` configuration file... [source,xml] ---- @@ -608,9 +608,9 @@ Then the Region beans defined in the _Spring_ application context will consist o above (i.e. `@Resource(name = "Customers/Accounts"))` is now broken since no bean with name "Customers/Accounts" is actually defined. -Geode is flexible in referencing both parent Regions and Subregions with or without the leading forward slash. +GemFire is flexible in referencing both parent Regions and Subregions with or without the leading forward slash. For example, the parent can be referenced as "/Customers" or "Customers" and the child as "/Customers/Accounts" -or just "Customers/Accounts". However, _Spring Data _Geode is very specific when it comes to naming beans after Regions, +or just "Customers/Accounts". However, _Spring Data _GemFire is very specific when it comes to naming beans after Regions, typically always using the forward slash (/) to represent Subregions (e.g. "/Customers/Accounts"). Therefore, it is recommended that users either use the nested `lookup-region` syntax as shown above, @@ -624,18 +624,18 @@ or define direct references with a leading forward slash (/) like so... The example above where the nested `replicated-region` elements were used to reference the Subregions serves to illustrate the problem stated earlier. Are the Customers, Accounts and Orders Regions/Subregions persistent or not? -Not, since the Regions were defined in the native Geode `cache.xml` configuration file as `REPLICATES` and will exist +Not, since the Regions were defined in the native GemFire `cache.xml` configuration file as `REPLICATES` and will exist by the time the cache is initialized, or 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 Geode, eviction applies to the _Least Recently Used_ entry (also known as +Currently, in GemFire, eviction applies to the _Least Recently Used_ entry (also known as http://en.wikipedia.org/wiki/Cache_algorithms#Least_Recently_Used[LRU]). Evicted entries are either destroyed or paged to disk (referred to as *overflow* to disk). -_Spring Data Geode_ supports all eviction policies (entry count, memory and heap usage) for PARTITION Regions, +_Spring Data GemFire_ supports all eviction policies (entry count, memory and heap usage) for PARTITION Regions, REPLICATE Regions and client, local Regions using the nested `eviction` element. For example, to configure a PARTITION Region to overflow to disk if the memory size exceeds more than 512 MB, @@ -649,22 +649,22 @@ a developer would specify the following configuration: ---- IMPORTANT: Replicas cannot use `local destroy` eviction since that would invalidate them. -See the Geode docs for more information. +See the GemFire docs for more information. When configuring Regions for overflow, it is recommended to configure the storage through the `disk-store` element for maximum efficiency. -For a detailed description of eviction policies, please refer to the Geode documentation on +For a detailed description of eviction policies, please refer to the GemFire documentation on http://geode.apache.org/docs/guide/11/developing/eviction/chapter_overview.html[Eviction]. [[bootstrap:region:expiration]] == Data Expiration -Apache Geode allows you to control how long entries exist in the cache. Expiration is driven by elapsed time, +Pivotal GemFire allows you to control how long entries exist in the cache. Expiration is driven by elapsed time, as opposed to Eviction, which is driven by the entry count or heap/memory usage. Once an entry expires it may no longer be accessed from the cache. -Geode supports the following Expiration types: +GemFire supports the following Expiration types: * *Time-to-Live (TTL)* - The amount of time in seconds that an object may remain in the cache after the last creation or update. For entries, the counter is set to zero for create and put operations. Region counters are reset when @@ -674,7 +674,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 entries in the Region. _Spring Data Geode_ provides ``, +Each of these may be applied to the Region itself or entries in the Region. _Spring Data GemFire_ provides ``, ``, `` and `` Region child elements to specify timeout values and expiration actions. For example: @@ -687,13 +687,13 @@ For example: ---- -For a detailed description of expiration policies, please refer to the Geode documentation on +For a detailed description of expiration policies, please refer to the GemFire documentation on http://geode.apache.org/docs/guide/11/developing/expiration/chapter_overview.html[Expiration]. [[bootstrap:region:expiration:annotation]] === Annotation-based Data Expiration -With _Spring Data Geode_, a developer has the ability to define Expiration policies and settings on individual +With _Spring Data GemFire_, a developer has the ability to define Expiration policies and settings on individual Region Entry values, or rather, application domain objects directly. For instance, a developer might define Expiration settings on a Session-based application domain object like so... @@ -727,7 +727,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 Geode's_ Expiration annotation support. However, Apache Geode and _Spring Data Geode_ do allow you +by _Spring Data GemFire's_ Expiration annotation support. However, Pivotal GemFire and _Spring Data GemFire_ do allow you to set Region Expiration using the SDG XML namespace, like so... [source,xml] @@ -739,16 +739,16 @@ to set Region Expiration using the SDG XML namespace, like so... ---- ==== -_Spring Data Geode's_ `@Expiration` annotation support is implemented with Geode's +_Spring Data GemFire's_ `@Expiration` annotation support is implemented with GemFire's http://geode.apache.org/releases/latest/javadoc/org/apache/geode/cache/CustomExpiry.html[`CustomExpiry`] interface. -Refer to Geode's documentation on http://geode.apache.org/docs/guide/11/developing/expiration/configuring_data_expiration.html[Configuring Data Expiration] +Refer to GemFire's documentation on http://geode.apache.org/docs/guide/11/developing/expiration/configuring_data_expiration.html[Configuring Data Expiration] for more details -The _Spring Data Geode_ `AnnotationBasedExpiration` class (and `CustomExpiry` implementation) is responsible +The _Spring Data GemFire_ `AnnotationBasedExpiration` class (and `CustomExpiry` implementation) is responsible for processing the SDG `@Expiration` annotations and applying the Expiration policy and settings appropriately for Region Entry Expiration on request. -To use _Spring Data Geode_ to configure specific Geode Regions to appropriately apply the Expiration policy +To use _Spring Data GemFire_ to configure specific GemFire Regions to appropriately apply the Expiration policy and settings applied to your application domain objects annotated with `@Expiration`-based annotations, you must... 1. Define a bean in the _Spring_ `ApplicationContext` of type `AnnotationBasedExpiration` using the appropriate @@ -773,11 +773,11 @@ along with the `` element to set TTI. ==== 2. (optional) Annotate your application domain objects that will be stored in the Region with Expiration policies -and custom settings using one of _Spring Data Geode's_ `@Expiration` annotations: `@Expiration`, +and custom settings using one of _Spring Data GemFire's_ `@Expiration` annotations: `@Expiration`, `@IdleTimeoutExpiration` and/or `@TimeToLiveExpiration` -3. (optional) In cases where particular application domain objects have not been annotated with _Spring Data Geode's_ -`@Expiration` annotations at all, but the Geode Region is configured to use SDG's custom `AnnotationBasedExpiration` +3. (optional) In cases where particular application domain objects have not been annotated with _Spring Data GemFire's_ +`@Expiration` annotations at all, but the GemFire Region is configured to use SDG's custom `AnnotationBasedExpiration` class to determine the Expiration policy and settings for objects stored in the Region, then it is possible to set "default" Expiration attributes on the `AnnotationBasedExpiration` bean by doing the following... @@ -798,11 +798,11 @@ class to determine the Expiration policy and settings for objects stored in the ---- -You may have noticed that _Spring Data Geode's_ `@Expiration` annotations use a String as the attributes type rather +You may have noticed that _Spring Data GemFire's_ `@Expiration` annotations use a String as the attributes type rather than, and perhaps more appropriately, being strongly typed, i.e. `int` for 'timeout' and SDG'S `ExpirationActionType` for 'action'. Why is that? -Well, enter one of _Spring Data Geode's_ other features, leveraging _Spring's_ core infrastructure +Well, enter one of _Spring Data GemFire's_ other features, leveraging _Spring's_ core infrastructure for configuration convenience: _Property Placeholders_ and _Spring Expression Language_ (SpEL). For instance, a developer can specify both the Expiration 'timeout' and 'action' using _Property Placeholders_ @@ -866,18 +866,18 @@ instance of `java.util.Properties`. In this example, even the Properties (`expir the action value on the actual Expiration action enumerated type leading to more quickly identified failures if the types ever change. -All of this has been demonstrated and tested in the _Spring Data Geode_ test suite, by way of example. See the +All of this has been demonstrated and tested in the _Spring Data GemFire_ test suite, by way of example. See the https://github.com/spring-projects/spring-data-geode[source] for further details. [[bootstrap:region:persistence]] == Data Persistence -Regions can be persistent. Geode ensures that all the data you put into a Region that is configured for persistence +Regions can be persistent. GemFire ensures that all the data you put into a Region that is configured for persistence will be written to disk in a way that is recoverable the next time you recreate the Region. This allows data to be recovered after machine or process failure, or even after an orderly shutdown and subsequent restart of -the Geode data node. +the GemFire data node. -To enable persistence with _Spring Data Geode_, simply set the `persistent` attribute to `true` on +To enable persistence with _Spring Data GemFire_, simply set the `persistent` attribute to `true` on any of the `<*-region>` elements. For example... [source,xml] @@ -886,7 +886,7 @@ any of the `<*-region>` elements. For example... ---- Persistence may also be configured using the `data-policy` attribute; set the attribute's value to one of -http://geode.apache.org/releases/latest/javadoc/org/apache/geode/cache/DataPolicy.html[Geode's DataPolicy settings]. +http://geode.apache.org/releases/latest/javadoc/org/apache/geode/cache/DataPolicy.html[GemFire's DataPolicy settings]. For example... [source,xml] @@ -913,8 +913,8 @@ This is discussed further in <> [[bootstrap:region:subscription]] == Subscription Policy -Geode allows configuration of http://geode.apache.org/docs/guide/11/developing/events/configure_p2p_event_messaging.html[peer-to-peer (P2P) event messaging] -to control the entry events that the Region will receive. _Spring Data Geode_ provides the `` +GemFire allows configuration of http://geode.apache.org/docs/guide/11/developing/events/configure_p2p_event_messaging.html[peer-to-peer (P2P) event messaging] +to control the entry events that the Region will receive. _Spring Data GemFire_ provides the `` sub-element to set the subscription policy on REPLICATE and PARTITION Regions to either `ALL` or `CACHE_CONTENT`. [source,xml] @@ -927,11 +927,11 @@ sub-element to set the subscription policy on REPLICATE and PARTITION Regions to [[bootstrap:region:local]] == Local Region -_Spring Data Geode_ offers a dedicated `local-region` element for creating local Regions. Local Regions, as the name +_Spring Data GemFire_ offers a dedicated `local-region` element for creating local Regions. Local Regions, as the name implies, are standalone, meaning they do not share data with any other distributed system member. Other than that, all common Region configuration options apply. -A minimal declaration looks as follows (again, the example relies on the _Spring Data Geode_ namespace +A minimal declaration looks as follows (again, the example relies on the _Spring Data GemFire_ namespace naming conventions to wire the cache): [source,xml] @@ -940,7 +940,7 @@ naming conventions to wire the cache): ---- Here, a local Region is created (if one doesn't exist already). The name of the Region is the same as the bean id -(`myLocalRegion`) and the bean assumes the existence of a Geode cache named `gemfireCache`. +(`myLocalRegion`) and the bean assumes the existence of a GemFire cache named `gemfireCache`. [[bootstrap:region:replicate]] == Replicated Region @@ -951,7 +951,7 @@ a REPLICATE Region is distributed to all copies of the Region. When a _replica_ an initialization stage in which it discovers other _replicas_ and automatically copies all the entries. While one _replica_ is initializing you can still continue to use the other _replica_. -_Spring Data Geode_ offers a `replicated-region` element. A minimal declaration looks as follows. +_Spring Data GemFire_ offers a `replicated-region` element. A minimal declaration looks as follows. All common configuration options are available for REPLICATE Regions. [source,xml] @@ -959,22 +959,22 @@ All common configuration options are available for REPLICATE Regions. ---- -Refer to Geode's documentation on +Refer to GemFire's documentation on http://geode.apache.org/docs/guide/11/developing/distributed_regions/chapter_overview.html[Distributed and Replicated Regions] for more details. [[bootstrap:region:partition]] == Partitioned Region -Another Region type supported out-of-the-box by the _Spring Data Geode_ namespace is the PARTITION Region. +Another Region type supported out-of-the-box by the _Spring Data GemFire_ namespace is the PARTITION Region. -To quote the Geode docs: +To quote the GemFire docs: "A partitioned region is a region where data is divided between peer servers hosting the region so that each peer stores a subset of the data. When using a partitioned region, applications are presented with a logical view of the region that looks like a single map containing all of the data in the region. Reads or writes to this map are transparently routed to the peer that hosts the entry that is the target of -the operation. Geode divides the domain of hashcodes into buckets. Each bucket is assigned to a specific peer, +the operation. GemFire divides the domain of hashcodes into buckets. Each bucket is assigned to a specific peer, but may be relocated at any time to another peer in order to improve the utilization of resources across the cluster." A partition is created using the `partitioned-region` element. Its configuration options are similar to that of @@ -992,7 +992,7 @@ Below is a quick example on setting up a PARTITION Region with 2 redundant copie ---- -Refer to Geode's documentation on +Refer to GemFire's documentation on http://geode.apache.org/docs/guide/11/developing/partitioned_regions/chapter_overview.html[Partitioned Regions] for more details. @@ -1049,12 +1049,12 @@ immediately when a new member is added. [[bootstrap:region:client]] == Client Region -Apache Geode supports various deployment topologies for managing and distributing data. Geode topologies is outside -the scope of this documentation. However, to quickly recap, Geode's supported topologies can be classified in short as: +Pivotal GemFire supports various deployment topologies for managing and distributing data. GemFire topologies is outside +the scope of this documentation. However, to quickly recap, GemFire's supported topologies can be classified in short as: _peer-to-peer_ (p2p), _client-server_, and _wide area network_ (WAN). In the last two configurations, it is common to declare *client* Regions which connect to a cache server. -_Spring Data Geode_ offers dedicated support for such configuration through <>, +_Spring Data GemFire_ offers dedicated support for such configuration through <>, `client-region` and `pool` elements. As the names imply, the former defines a client Region while the latter defines a Pool of connections to be used/shared by the various client Regions. @@ -1089,14 +1089,14 @@ cache servers and peer data members in the distributed system and are recommende possible to configure the Pool to connect directly to one or more cache servers using the `server` element. For a full list of options to set on the client and especially on the Pool, please refer to -the _Spring Data Geode_ schema (<>) and Geode's documentation on +the _Spring Data GemFire_ schema (<>) and GemFire's documentation on http://geode.apache.org/docs/guide/11/topologies_and_comm/cs_configuration/chapter_overview.html[Client/Server Configuration]. [[bootstrap:region:client:interests]] === Client Interests -To minimize network traffic, each client can separately define its own 'interests' policies, indicating to Geode -the data it actually requires. In _Spring Data Geode_, 'interests' can be defined for each client Region separately. +To minimize network traffic, each client can separately define its own 'interests' policies, indicating to GemFire +the data it actually requires. In _Spring Data GemFire_, 'interests' can be defined for each client Region separately. Both Key-based and Regular Expression-based interest types are supported. For example: @@ -1185,20 +1185,20 @@ like so... A full, in-depth discussion of how client interests work and capabilities is beyond the scope of this document. -Please refer to Apache Geode's documentation on +Please refer to Pivotal GemFire's documentation on http://gemfire.docs.pivotal.io/geode/developing/events/how_client_server_distribution_works.html[Client-to-Server Event Distribution] for more details. [[bootstrap:region:json]] == JSON Support -Apache Geode has support for caching JSON documents in Regions along with the ability to query stored JSON documents -using the Geode OQL. JSON documents are stored internally as +Pivotal GemFire has support for caching JSON documents in Regions along with the ability to query stored JSON documents +using the GemFire OQL. JSON documents are stored internally as http://geode.apache.org/releases/latest/javadoc/org/apache/geode/pdx/PdxInstance.html[PdxInstance] types using the http://geode.apache.org/releases/latest/javadoc/org/apache/geode/pdx/JSONFormatter.html[JSONFormatter] class to perform conversion to and from JSON documents (as a `String`). -_Spring Data Geode_ provides the `` element to enable a +_Spring Data GemFire_ provides the `` element to enable a http://docs.spring.io/spring/docs/current/spring-framework-reference/htmlsingle/#aop-introduction[AOP, _Spring_] component to advise appropriate, proxied Region operations, which effectively encapsulates the `JSONFormatter`, thereby allowing your applications to work directly with JSON Strings. @@ -1215,7 +1215,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 Geode's proprietary `Region.Entry` such as: +NOTE: Certain Region operations, specifically those that use GemFire's proprietary `Region.Entry` such as: `entries(boolean)`, `entrySet(boolean)` and `getEntry()` type are not targeted for AOP advice. In addition, the `entrySet()` method which returns a `Set>` is also not affected. diff --git a/src/main/asciidoc/reference/repositories.adoc b/src/main/asciidoc/reference/repositories.adoc index ccd7f57f..04d12246 100644 --- a/src/main/asciidoc/reference/repositories.adoc +++ b/src/main/asciidoc/reference/repositories.adoc @@ -1,28 +1,28 @@ [[gemfire-repositories]] -= Spring Data Geode Repositories += Spring Data GemFire Repositories == Introduction -_Spring Data Geode_ provides support to use the _Spring Data Repository_ abstraction to easily persist entities -into Geode along with execute queries. A general introduction to the _Repository programming model_ is provided +_Spring Data GemFire_ provides support to use the _Spring Data Repository_ abstraction to easily persist entities +into GemFire along with execute queries. A general introduction to the _Repository programming model_ is provided http://docs.spring.io/spring-data/data-commons/docs/current/reference/html/#repositories[here]. [[gemfire-repositories.spring-configuration]] == Spring Configuration -To bootstrap _Spring Data Repositories_, you use the `` element from the _Spring Data Geode_ +To bootstrap _Spring Data Repositories_, you use the `` element from the _Spring Data GemFire_ Data namespace: -.Bootstrap Spring Data Geode Repositories +.Bootstrap Spring Data GemFire Repositories ==== [source,xml] ---- @@ -39,7 +39,7 @@ or the bootstrap process will fail otherwise. [[gemfire-repositories.executing-queries]] == Executing OQL Queries -_Spring Data Geode Repositories_ enable the definition of query methods to easily execute Geode OQL Queries +_Spring Data GemFire Repositories_ enable the definition of query methods to easily execute GemFire OQL Queries against the Region the managed entity is mapped to. .Sample Repository @@ -141,7 +141,7 @@ becomes too verbose, you can annotate the query methods with `@Query` as seen fo [[gemfire-repositories:oql-extensions]] == OQL Query Extensions using Annotations -Many query languages, such as Apache Geode's OQL (Object Query Language), have extensions that are not directly +Many query languages, such as Pivotal GemFire's OQL (Object Query Language), have extensions that are not directly supported by _Spring Data Commons' Repository_ infrastructure. One of _Spring Data Commons' Repository_ infrastructure goals is to function as the lowest common denominator @@ -150,20 +150,20 @@ for application development today. Technically, this means developers can acces supported by _Spring Data Commons_ within their applications by reusing their existing application-specific Repository interfaces, a very convenient and powerful abstraction. -To support Geode's OQL Query language extensions and preserve portability across different data stores, -_Spring Data Geode_ adds support for OQL Query extensions using Java Annotations. These Annotations will be ignored +To support GemFire's OQL Query language extensions and preserve portability across different data stores, +_Spring Data GemFire_ adds support for OQL Query extensions using Java Annotations. These Annotations will be ignored by other _Spring Data Repository_ implementations (e.g. _Spring Data_ JPA or _Spring Data Redis_) that do not have similar query language extensions. -For instance, many data stores will most likely not implement Geode's OQL `IMPORT` keyword. By implementing `IMPORT` +For instance, many data stores will most likely not implement GemFire's OQL `IMPORT` keyword. By implementing `IMPORT` as an Annotation (i.e. `@Import`) rather than as part of the query method signature (specifically, the method 'name'), then this will not interfere with the parsing infrastructure when evaluating the query method name to construct another data store language appropriate query. -Currently, the set of Geode OQL Query language extensions that are supported by _Spring Data Geode_ include: +Currently, the set of GemFire OQL Query language extensions that are supported by _Spring Data GemFire_ include: [cols="1,2,2,2", options="header"] -.Supported Geode OQL extensions for Repository query methods +.Supported GemFire OQL extensions for Repository query methods |=== | Keyword | Annotation @@ -191,7 +191,7 @@ Currently, the set of Geode OQL Query language extensions that are supported by | NA |=== -As an example, suppose you have a `Customers` application domain class and corresponding Geode Region along with a +As an example, suppose you have a `Customers` application domain class and corresponding GemFire Region along with a `CustomerRepository` and a query method to lookup `Customers` by last name, like so... .Sample Customers Repository @@ -238,7 +238,7 @@ This will result in the following OQL Query: ` IMPORT org.example.app.domain.Customer; SELECT * FROM /Customers x WHERE x.lastName = $1 LIMIT 10` -_Spring Data Geode's Repository_ extension and support is careful not to create conflicting declarations when +_Spring Data GemFire's Repository_ extension and support is careful not to create conflicting declarations when the OQL Annotation extensions are used in combination with the `@Query` annotation. As another example, suppose you have a raw `@Query` annotated query method defined in your `CustomerRepository` diff --git a/src/main/asciidoc/reference/samples.adoc b/src/main/asciidoc/reference/samples.adoc index 239156a5..e4b7e0c6 100644 --- a/src/main/asciidoc/reference/samples.adoc +++ b/src/main/asciidoc/reference/samples.adoc @@ -4,8 +4,8 @@ NOTE: Sample applications are now maintained in the https://github.com/spring-projects/spring-gemfire-examples[Spring GemFire Examples] repository. -The _Spring Data Geode_ project also includes one sample application. Named "Hello World", the sample application -demonstrates how to configure and use Apache Geode inside a _Spring_ application. At runtime, the sample offers +The _Spring Data 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 runtime, the sample offers a *shell* to the user allowing her to run various commands against the data grid. It provides an excellent starting point for users unfamiliar with the essential components or with _Spring_ and GemFire concepts. @@ -15,13 +15,13 @@ Maven-aware IDE (such as https://spring.io/tools/sts[Spring Tool Suite]) or run [[samples:hello-world]] == Hello World -The Hello World sample application demonstrates the core functionality of the _Spring Data Geode_ project. -It bootstraps Geode, 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 GemFire_ project. +It bootstraps GemFire, 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 they will work together, sharing data without any user intervention. .Running under Linux -NOTE: If you experience networking problems when starting Geode or the samples, try adding the following +NOTE: If you experience networking problems when starting GemFire or the samples, try adding the following system property `java.net.preferIPv4Stack=true` to the command line (e.g. `-Djava.net.preferIPv4Stack=true`). For an alternative (global) fix especially on Ubuntu see https://jira.spring.io/browse/SGF-28[SGF-28]. diff --git a/src/main/asciidoc/reference/serialization.adoc b/src/main/asciidoc/reference/serialization.adoc index 6148b2ba..cacc2ef3 100644 --- a/src/main/asciidoc/reference/serialization.adoc +++ b/src/main/asciidoc/reference/serialization.adoc @@ -1,7 +1,7 @@ [[serialization]] -= Working with Apache Geode Serialization += Working with Pivotal GemFire Serialization -To improve overall performance of the Apache Geode In-memory Data Grid, Geode supports a dedicated +To improve overall performance of the Pivotal GemFire In-memory Data Grid, GemFire supports a dedicated serialization protocol, called PDX, that is both faster and offers more compact results over standard Java serialization in addition to works transparently across various language platforms (Java, C++, .NET). Please refer to @@ -10,7 +10,7 @@ and https://cwiki.apache.org/confluence/display/GEODE/PDX+Serialization+Internals[PDX Serialization Internals] for more details. -This chapter discusses the various ways in which _Spring Data Geode_ simplifies and improves Geode's +This chapter discusses the various ways in which _Spring Data GemFire_ simplifies and improves GemFire'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/machine. -For such cases, _Spring Data Geode_ offers a special +For such cases, _Spring Data 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 Geode during deserialization. +that performs wiring for each new instance created by GemFire during deserialization. Through such a mechanism, one can rely on the _Spring_ container to inject and manage certain dependencies making it easy to split transient from persistent data and have *rich domain objects* in a transparent manner. @@ -46,16 +46,16 @@ To use this SDG `Instantiator`, simply declare it as a bean: ---- During the _Spring_ container startup, once it is being initialized, the `Instantiator` will, by default, register -itself with the Geode serialization system and perform wiring on all instances of `SomeDataSerializableClass` -created by Geode during deserialization. +itself with the GemFire serialization system and perform wiring on all instances of `SomeDataSerializableClass` +created by GemFire 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. -Out-of-the-box, Geode uses reflection to create new types, but for some scenarios, this might prove to be expensive. +Out-of-the-box, GemFire uses reflection to create new types, but for some scenarios, this might prove to be expensive. As always, it is good to perform profiling to quantify whether this is the case or not. For such cases, -_Spring Data Geode_ allows the automatic generation of `Instatiator` classes which instantiate a new type +_Spring Data GemFire_ allows the automatic generation of `Instatiator` classes which instantiate a new type (using the default constructor) without the use of reflection: [source,xml] @@ -71,5 +71,5 @@ _Spring Data Geode_ allows the automatic generation of `Instatiator` classes whi ---- The definition above, automatically generates two `Instantiators` for two classes, namely `CustomTypeA` -and `CustomTypeB` and registers them with Geode, under user id `1025` and `1026`. The two `Instantiators` avoid +and `CustomTypeB` and registers them with GemFire, under user id `1025` and `1026`. The two `Instantiators` avoid the use of reflection and create the instances directly through Java code. diff --git a/src/main/asciidoc/reference/snapshot.adoc b/src/main/asciidoc/reference/snapshot.adoc index 3d39bfb9..c4ce8815 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 Geode_ supports `Cache` and `Region` snapshots using -http://geode.apache.org/docs/guide/11/managing/cache_snapshots/chapter_overview.html[Apache Geode's Snapshot Service]. -The out-of-the-box Snapshot Service support offers several convenient features to simplify the use of Geode's +_Spring Data GemFire_ supports `Cache` and `Region` snapshots 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 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] Snapshot Service APIs. -As the http://geode.apache.org/docs/guide/11/managing/cache_snapshots/chapter_overview.html[Apache Geode documentation] +As the http://geode.apache.org/docs/guide/11/managing/cache_snapshots/chapter_overview.html[Pivotal GemFire documentation] describes, snapshots allow you to save and subsequently reload the cached data later, which can be useful for moving data between environments, such as from production to a staging or test environment in order to reproduce -data-related issues in a controlled context. You can imagine combining _Spring Data Geode's_ Snapshot Service support +data-related issues in a controlled context. You can imagine combining _Spring Data GemFire's_ Snapshot Service support with http://docs.spring.io/spring/docs/current/spring-framework-reference/htmlsingle/#beans-definition-profiles[Spring's bean definition profiles] to load snapshot data specific to the environment as necessary. -_Spring Data Geode's_ support for Apache Geode's Snapshot Service begins with the `` element +_Spring Data GemFire's_ support for Pivotal GemFire's Snapshot Service begins with the `` element from the `` namespace. For example, I might want to define Cache-wide snapshots to be loaded as well as saved using a couple snapshot imports @@ -32,10 +32,10 @@ and a data export definition as follows: ---- You can define as many imports and/or exports as you like. You can define just imports or just exports. -The file locations and directory paths can be absolute, or relative to the _Spring Data Geode_ application, +The file locations and directory paths can be absolute, or relative to the _Spring Data GemFire_ application, JVM process's working directory. -This is a pretty simple example and the Snapshot Service defined in this case refers to the Geode `Cache` with +This is a pretty simple example and the Snapshot Service defined in this case refers to the GemFire `Cache` with the default name of `gemfireCache` (as described in <>). If you name your cache bean definition something other than the default, than you can use the `cache-ref` attribute to refer to the cache bean by name: @@ -48,7 +48,7 @@ something other than the default, than you can use the `cache-ref` attribute to ---- -It is also straightforward to define a Snapshot Service for a particular Geode Region by specifying +It is also straightforward to define a Snapshot Service for a particular GemFire Region by specifying the `region-ref` attribute: [source,xml] @@ -61,17 +61,17 @@ the `region-ref` attribute: ---- -When the `region-ref` attribute is specified, _Spring Data Geode's_ `SnapshotServiceFactoryBean` resolves +When the `region-ref` attribute is specified, _Spring Data GemFire's_ `SnapshotServiceFactoryBean` resolves the `region-ref` attribute value to a Region bean defined in the _Spring_ context and proceeds to create a http://geode.apache.org/releases/latest/javadoc/org/apache/geode/cache/snapshot/RegionSnapshotService.html[RegionSnapshotService]. The snapshot import and export definitions function the same way, however, the `location` must refer to a file on export. -NOTE: Geode is strict about imported snapshot files actually existing before they are referenced. For exports, -Geode will create the snapshot file if it does not already exist. If the snapshot file for export already exists, +NOTE: GemFire is strict about imported snapshot files actually existing before they are referenced. For exports, +GemFire will create the snapshot file if it does not already exist. If the snapshot file for export already exists, the data will be overwritten. -TIP: _Spring Data Geode_ includes a `suppress-import-on-init` attribute on the `` element +TIP: _Spring Data GemFire_ includes a `suppress-import-on-init` attribute on the `` element to suppress the configured Snapshot Service from trying to import data into the Cache or Region on initialization. This is useful when data exported from 1 Region is used to feed the import of another Region, for example. @@ -86,13 +86,13 @@ http://geode.apache.org/releases/latest/javadoc/org/apache/geode/cache/snapshot/ method in the `CacheSnapshotService` API indicates. NOTE: Of course, a developer may use the other, overloaded `load(:File[], :SnapshotFormat, :SnapshotOptions)` method -variant to get specific about which snapshot files are to be loaded into the Geode `Cache`. +variant to get specific about which snapshot files are to be loaded into the GemFire `Cache`. -However, _Spring Data Geode_ recognizes that a typical developer workflow might be to extract and export data +However, _Spring Data GemFire_ recognizes that a typical developer workflow might be to extract and export data from one environment into several snapshot files, zip all of them up, and then conveniently move the ZIP file to another environment for import. -Therefore, _Spring Data Geode_ enables the developer to specify a JAR or ZIP file on import for a `Cache`-based +Therefore, _Spring Data GemFire_ enables the developer to 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 Geode_ will conveniently extract the provided ZIP file and treat it like a directory import (load). +_Spring Data GemFire_ will conveniently extract the provided ZIP file and treat it like 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 Apache Geode's +Snapshot filters implement Pivotal GemFire's http://geode.apache.org/releases/latest/javadoc/org/apache/geode/cache/snapshot/SnapshotFilter.html[SnapshotFilter] interface and are used to filter Region entries for inclusion into the Region on import and for inclusion into the snapshot on export. -_Spring Data Geode_ makes it brain dead simple to utilize snapshot filters on import and export using the `filter-ref` +_Spring Data GemFire_ makes it brain dead simple to utilize snapshot filters on import and export using the `filter-ref` attribute or an anonymous, nested bean definition: [source,xml] @@ -123,25 +123,25 @@ attribute or an anonymous, nested bean definition: - - - ---- -In addition, more complex snapshot filters can be expressed with the `ComposableSnapshotFilter` _Spring Data Geode_ -provided class. This class implements Geode's +In addition, more complex snapshot filters can be expressed with the `ComposableSnapshotFilter` _Spring Data GemFire_ +provided class. This class implements GemFire's http://geode.apache.org/releases/latest/javadoc/org/apache/geode/cache/snapshot/SnapshotFilter.html[SnapshotFilter] interface as well as the https://en.wikipedia.org/wiki/Composite_pattern[Composite] software design pattern. @@ -180,7 +180,7 @@ The developer could then go onto combine the `activesUsersSinceFilter` with anot - + @@ -189,15 +189,15 @@ The developer could then go onto combine the `activesUsersSinceFilter` with anot [[bootstrap::snapshot::events]] == Snapshot Events -By default, _Spring Data Geode_ uses Apache Geode's Snapshot Services on startup to import data and shutdown +By default, _Spring Data GemFire_ uses Pivotal GemFire's Snapshot Services on startup to import data and shutdown to export data. However, you may want to trigger periodic, event-based snapshots, for either import or export from within your _Spring_ application. -For this purpose, _Spring Data Geode_ defines two additional _Spring_ application events, extending _Spring's_ +For this purpose, _Spring Data GemFire_ defines two additional _Spring_ application events, extending _Spring's_ http://docs.spring.io/spring/docs/current/javadoc-api/org/springframework/context/ApplicationEvent.html[ApplicationEvent] class for imports and exports, respectively: `ImportSnapshotApplicationEvent` and `ExportSnapshotApplicationEvent`. -The two application events can be targeted at the entire Geode Cache, or individual Geode Regions. The constructors +The two application events can be targeted at the entire GemFire Cache, or individual GemFire Regions. The constructors in these classes accept an optional Region pathname (e.g. "/Example") as well as 0 or more `SnapshotMetadata` instances. The array of `SnapshotMetadata` is used to override the snapshot meta-data defined by ``