SGF-300 - Change all Spring Data Geode and Apache Geode references to Spring Data GemFire and Pivotal GemFire.

This commit is contained in:
John Blum
2017-05-08 16:24:46 -07:00
parent 4d37cbe1a2
commit 87d5e7e16a
25 changed files with 421 additions and 417 deletions

View File

@@ -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

View File

@@ -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.

View File

@@ -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`.

View File

@@ -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.

View File

@@ -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]

View File

@@ -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.

View File

@@ -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 <<apis:declarable>> to see how you can still use `Declarables` within _Spring's_ IoC/DI container).
In addition, IDEs, such as the _Spring Tool Suite_ (STS), provide excellent support for _Spring_ XML namespaces
@@ -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 `<bean>` 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 <<gemfire-repositories>> 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_
</beans>
----
<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:
</beans>
----
<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.

View File

@@ -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:
<gfe:cache id="myCache"/>
----
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:
----
<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:gfe="http://www.springframework.org/schema/geode"
xmlns:gfe="http://www.springframework.org/schema/gemfire"
xmlns:util="http://www.springframework.org/schema/util"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="
http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
http://www.springframework.org/schema/geode http://www.springframework.org/schema/gemfire/spring-geode.xsd
http://www.springframework.org/schema/gemfire http://www.springframework.org/schema/gemfire/spring-gemfire.xsd
http://www.springframework.org/schema/util http://www.springframework.org/schema/util/spring-util.xsd">
<util:properties id="gemfireProperties" location="file:/path/to/gemfire.properties"/>
@@ -114,7 +114,7 @@ or child elements:
<gfe:transaction-listener ref="myTransactionListener"/> <!--5-->
<gfe:transaction-writer> <!--6-->
<bean class="org.example.app.geode.transaction.TransactionWriter"/>
<bean class="org.example.app.gemfire.transaction.TransactionWriter"/>
</gfe:transaction-writer>
<gfe:gateway-conflict-resolver ref="myGatewayConflictResolver"/> <!--7-->
@@ -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 <<serialization>>
Setting the `<gfe:cache enable-auto-reconnect="[true|false*]>` attribute to `true` should be done with care.
Generally, 'auto-reconnect' should only be enabled in cases where _Spring Data Geode's_ XML namespace is used to
configure and bootstrap a new, non-application Geode Server to add to a cluster. In other words, 'auto-reconnect'
should not be enabled when _Spring Data Geode_ is used to develop and build an Geode application that also happens
to be a peer cache member of the Geode cluster.
Generally, 'auto-reconnect' should only be enabled in cases where _Spring Data GemFire's_ XML namespace is used to
configure and bootstrap a new, non-application GemFire Server to add to a cluster. In other words, 'auto-reconnect'
should not be enabled when _Spring Data GemFire_ is used to develop and build an GemFire application that also happens
to be a peer cache member of the GemFire cluster.
The main reason for this is that most Geode applications use references to the Geode cache or Regions in order to
The main reason for this is that most GemFire applications use references to the GemFire cache or Regions in order to
perform data access operations. These references are "injected" by the Spring container into application components
(e.g. DAOs or Repositories) for use by the application. When a peer member is forcefully disconnected from the rest
of the cluster, presumably because the peer member has become unresponsive or a network partition separates one or more
peer members into a group too small to function as an independent distributed system, the peer member will shutdown
and all Geode component references (e.g. Cache, Regions, etc) become invalid.
and all GemFire component references (e.g. Cache, Regions, etc) become invalid.
Essentially, the current forced-disconnect processing logic in each peer member dismantles the system from the ground up.
The JGroups stack shuts down, the Distributed System is put in a shutdown state and finally, the Cache is closed.
@@ -195,36 +195,36 @@ Effectively, all memory references become stale and are lost.
After being disconnected from the Distributed System a peer member enters a "reconnecting" state and periodically
attempts to rejoin the Distributed System. If the peer member succeeds in reconnecting, the member rebuilds
its "view" of the Distributed System from existing members and receives a new Distributed System ID. Additionally, all
Cache, Regions and other Geode components are reconstructed. Therefore, all old references, which may have been
Cache, Regions and other GemFire components are reconstructed. Therefore, all old references, which may have been
injected into application by the Spring container are now stale and no longer valid.
Geode makes no guarantee, even when using the Geode public Java API, that application Cache, Region or other
component references will be automatically refreshed by the reconnect operation. As such, Geode applications
GemFire makes no guarantee, even when using the GemFire public Java API, that application Cache, Region or other
component references will be automatically refreshed by the reconnect operation. As such, GemFire applications
must take care to refresh their own references.
Unfortunately, there is no way to be notified of a disconnect event, and subsequently, a reconnect event.
If that were the case, the application developer would have a clean way to know when to call
`ConfigurableApplicationContext.refresh()`, if even applicable for an application to do so, which is why
this "feature" of Apache Geode is not recommended for peer cache Geode applications.
this "feature" of Pivotal GemFire is not recommended for peer cache GemFire applications.
For more information about 'auto-reconnect', see Geode's
For more information about 'auto-reconnect', see GemFire's
http://geode.apache.org/docs/guide/11/managing/autoreconnect/member-reconnect.html[product documentation].
[[bootstrap:cache:cluster-configuration]]
=== Using Cluster-based Configuration
Apache Geode's Cluster Configuration Service is a convenient way for any peer member joining the cluster to get
Pivotal GemFire's Cluster Configuration Service is a convenient way for any peer member joining the cluster to get
a "consistent view" of the cluster by using the shared, persistent configuration maintained by a Locator.
Using the Cluster-based Configuration ensures the peer member's configuration will be compatible with
the Geode Distributed System when the member joins.
the GemFire Distributed System when the member joins.
This feature of _Spring Data Geode_ (setting the `use-cluster-configuration` attribute to `true`) works in the same way
as the `cache-xml-location` attribute, except the source of the Geode configuration meta-data comes from the network
This feature of _Spring Data GemFire_ (setting the `use-cluster-configuration` attribute to `true`) works in the same way
as the `cache-xml-location` attribute, except the source of the GemFire configuration meta-data comes from the network
via a Locator as opposed to a native `cache.xml` file residing in the local file system.
All Geode native configuration meta-data, whether from `cache.xml` or from the Cluster Configuration Service,
All GemFire native configuration meta-data, whether from `cache.xml` or from the Cluster Configuration Service,
gets applied before any _Spring_ (XML) configuration meta-data. As such, _Spring's_ config serves to "augment" the
native Geode configuration meta-data and would most likely be specific to the application.
native GemFire configuration meta-data and would most likely be specific to the application.
Again, to enable this feature, just specify the following in the _Spring_ XML config:
@@ -233,17 +233,17 @@ Again, to enable this feature, just specify the following in the _Spring_ XML co
<gfe:cache use-cluster-configuration="true"/>
----
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:
<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:context="http://www.springframework.org/schema/context"
xmlns:gfe="http://www.springframework.org/schema/geode"
xmlns:gfe="http://www.springframework.org/schema/gemfire"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="
http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context.xsd
http://www.springframework.org/schema/geode http://www.springframework.org/schema/geode/spring-geode.xsd
http://www.springframework.org/schema/gemfire http://www.springframework.org/schema/gemfire/spring-gemfire.xsd
">
<gfe:cache/>
<!-- Example depicting serveral Geode CacheServer configuration options -->
<!-- Example depicting serveral GemFire CacheServer configuration options -->
<gfe:cache-server id="advanced-config" auto-startup="true"
bind-address="localhost" host-name-for-clients="localhost" port="${geode.cache.server.port}"
bind-address="localhost" host-name-for-clients="localhost" port="${gemfire.cache.server.port}"
load-poll-interval="2000" max-connections="22" max-message-count="1000" max-threads="16"
max-time-between-pings="30000" groups="test-server">
@@ -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 <<bootstrap:cache,Cache>> and is supported by the `org.springframework.data.gemfire.client.ClientCacheFactoryBean`.
the GemFire peer <<bootstrap:cache,Cache>> 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:
<gfe:client-cache id="my-cache" pool-name="myPool"/>
<gfe:pool id="myPool" subscription-enabled="true">
<gfe:locator host="${geode.locator.host}" port="${geode.locator.port}"/>
<gfe:locator host="${gemfire.locator.host}" port="${gemfire.locator.port}"/>
</gfe:pool>
</beans>
----
@@ -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:region:client>>.
[[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
<gfe:client-region id="Example" cache-ref="gemfireCache" pool-name="gemfirePool" shortcut="PROXY"/>
----
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:
<gfe:client-region id="YetAnotherExample" shortcut="LOCAL"/>
----
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`.

View File

@@ -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
</bean>
----
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).

View File

@@ -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 <<gemfire-repositories, Repositories>> and function <<function-execution, execution>> as well as
includes a `<datasource>` 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 <<gemfire-repositories, Repositories>> and function <<function-execution, execution>> as well as
includes a `<datasource>` 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_ `<datasource>` 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_ `<datasource>` 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.

View File

@@ -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<Iterable<String>>() {
});
----
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 `<gfe:cache/>`
is enabled when using GemFire as long as the `CacheFactoryBean` is declared, e.g. using either a `<gfe:cache/>`
or `<gfe:client-cache>` 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
</cache-loader>
----
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, `<gfe:cache>` without an explicit ID.
When the `GemfireCacheManager` (Singleton) bean instance is declared and declarative caching is enabled
(either in XML with `<cache:annotation-driven/>` 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.

View File

@@ -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].

View File

@@ -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]
----
<gfe-data:function-executions base-package="org.example.myapp.geode.functions"/>
<gfe-data:function-executions base-package="org.example.myapp.gemfire.functions"/>
----
The `function-executions` element is provided in the `gfe-data` namespace. The `base-package` attribute is required
@@ -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]
----
<gfe:cache ... pdx-read-serialized="true"/>
----
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]
----
<bean id="customPdxSerializer" class="x.y.z.geode.serialization.pdx.MyCustomPdxSerializer"/>
<bean id="customPdxSerializer" class="x.y.z.gemfire.serialization.pdx.MyCustomPdxSerializer"/>
<gfe:cache ... pdx-serializer-ref="customPdxSerializeer" pdx-read-serialized="true"/>
----
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.

View File

@@ -1,17 +1,17 @@
[[bootstrap:function]]
= Configuring the Function Service
_Spring Data Geode_ provides <<function-annotations,annotation>> support for implementing and registering
Apache Geode Functions.
_Spring Data GemFire_ provides <<function-annotations,annotation>> 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:

View File

@@ -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
</gfe:gateway-receiver>
----
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.

View File

@@ -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 <<bootstrap,bootstrap Apache Geode>> using _Spring Data Geode's.
Just by specifying a `<gfe:cache/>` element using the _Spring Data Geode_ XML namespace, a single, embedded Geode
Normally, a _Spring_-based application will <<bootstrap,bootstrap Pivotal GemFire>> using _Spring Data GemFire's.
Just by specifying a `<gfe:cache/>` 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. `<context:component-scan base-packages="..."/>`)
Fortunately, such an Initializer is already conveniently provided by the framework, the
http://docs.spring.io/spring-data-gemfire/docs/current/api/org/springframework/data/gemfire/support/SpringContextBootstrappingInitializer.html[SpringContextBootstrappingInitializer].
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 `<gfe:cache/>` element attributes,
the _Spring Data GemFire_ namespace. In other words, none of the `<gfe:cache/>` element attributes,
such as `cache-xml-location`, `properties-ref`, `critical-heap-percentage`, `pdx-serializer-ref`, `lock-lease`, 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 <<apis:declarable:autowiring>>. 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]

View File

@@ -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]
----
<gfe:index id="myIndex" expression="someField" from="/SomeRegion"/>
----
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.

View File

@@ -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.
<<bootstrap>> 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.
<<apis>> explains the integration between the Apache Geode APIs and the various data access features
<<apis>> explains the integration between the Pivotal GemFire APIs and the various data access features
available in _Spring_, such as transaction management and exception translation.
<<serialization>> describes the enhancements for Apache Geode (de)serialization and management of associated objects.
<<serialization>> describes the enhancements for Pivotal GemFire (de)serialization and management of associated objects.
<<mapping>> describes persistence mapping for POJOs stored in Apache Geode using _Spring Data_.
<<mapping>> describes persistence mapping for POJOs stored in Pivotal GemFire using _Spring Data_.
<<gemfire-repositories>> describes how to create and use _Spring Data Repositories_ to access data in Apache Geode.
<<gemfire-repositories>> describes how to create and use _Spring Data Repositories_ to access data in Pivotal GemFire.
<<function-annotations>> describes how to create and use Apache Geode Functions using Annotations.
<<function-annotations>> describes how to create and use Pivotal GemFire Functions using Annotations.
<<gemfire-bootstrap>> describes how to bootstrap a _Spring_ `ApplicationContext` running in an Apache Geode server
<<gemfire-bootstrap>> describes how to bootstrap a _Spring_ `ApplicationContext` running in an Pivotal GemFire server
using _Gfsh_.
<<samples>> describes the examples provided with the distribution to illustrate the various features
available in _Spring Data Geode_.
available in _Spring Data GemFire_.

View File

@@ -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.

View File

@@ -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 <<gemfire-repositories>> 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<Person, String> {
}
----
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

View File

@@ -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 `<gfe:cache>` element.
For instance, given a `cache.xml` file of...
@@ -97,12 +97,12 @@ with:
<gfe:auto-region-lookup/>
----
_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 `<gfe:lookup-region>` 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
<bean class="example.ApplicationDao" depends-on="gemfireCache"/>
----
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 `<gfe:auto-region-lookup>` 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: `<local-region>`
* PARTITION Region: `<partitioned-region>`
* REPLICATE Region: `<replicated-region>`
* Client 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:
</beans>
----
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 `<gfe:cache>` 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 `<region-ttl>`,
Each of these may be applied to the Region itself or entries in the Region. _Spring Data GemFire_ provides `<region-ttl>`,
`<region-tti>`, `<entry-ttl>` and `<entry-tti>` Region child elements to specify timeout values and expiration actions.
For example:
@@ -687,13 +687,13 @@ For example:
</gfe:replicated-region>
----
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 `<gfe:custom-entry-tti ref="ttiExpiration"/>` 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
</gfe:partitioned-region>
----
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:diskstore>>
[[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 `<gfe:subscription/>`
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 `<gfe:subscription/>`
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.
<gfe:replicated-region id="exampleReplica"/>
----
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
</gfe:partitioned-region>
----
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 <<bootstrap:cache:client, client-cache>>,
_Spring Data GemFire_ offers dedicated support for such configuration through <<bootstrap:cache:client, client-cache>>,
`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 (<<appendix-schema>>) and Geode's documentation on
the _Spring Data GemFire_ schema (<<appendix-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 `<gfe-data:json-region-autoproxy/>` element to enable a
_Spring Data GemFire_ provides the `<gfe-data:json-region-autoproxy/>` 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<java.util.Map.Entry<?, ?>>` is also not affected.

View File

@@ -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 `<repositories/>` element from the _Spring Data Geode_
To bootstrap _Spring Data Repositories_, you use the `<repositories/>` element from the _Spring Data GemFire_
Data namespace:
.Bootstrap Spring Data Geode Repositories
.Bootstrap Spring Data GemFire Repositories
====
[source,xml]
----
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:gfe-data="http://www.springframework.org/schema/data/geode"
xmlns:gfe-data="http://www.springframework.org/schema/data/gemfire"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="
http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
http://www.springframework.org/schema/data/geode http://www.springframework.org/schema/data/geode/spring-data-geode.xsd>
http://www.springframework.org/schema/data/gemfire http://www.springframework.org/schema/data/gemfire/spring-data-gemfire.xsd>
<gfe-data:repositories base-package="com.example.acme.repository"/>
@@ -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:
`<TRACE> <HINT 'LastNameIdx'> 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`

View File

@@ -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].

View File

@@ -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.

View File

@@ -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 `<gfe-data:snapshot-service>` element
_Spring Data GemFire's_ support for Pivotal GemFire's Snapshot Service begins with the `<gfe-data:snapshot-service>` element
from the `<gfe-data>` 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 <<bootstrap:cache>>). 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
</gfe-data:snapshot-service>
----
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:
</gfe-data:snapshot-service>
----
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 `<gfe-data:snapshot-service>` element
TIP: _Spring Data GemFire_ includes a `suppress-import-on-init` attribute on the `<gfe-data:snapshot-service>` element
to suppress the configured Snapshot Service from trying to import data into the Cache or Region on initialization.
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:
</gfe-data:snapshot-service>
----
_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:
<gfe:partitioned-region id="Admins" persistent="false"/>
<gfe:partitioned-region id="Guests" persistent="false"/>
<bean id="activeUsersFilter" class="example.geode.snapshot.filter.ActiveUsersFilter/>
<bean id="activeUsersFilter" class="example.gemfire.snapshot.filter.ActiveUsersFilter/>
<gfe-data:snapshot-service id="adminsSnapshotService" region-ref="Admins">
<gfe-data:snapshot-import location="/path/to/import/users.snapshot">
<bean class="example.geode.snapshot.filter.AdminsFilter/>
<bean class="example.gemfire.snapshot.filter.AdminsFilter/>
</gfe-data:snapshot-import>
<gfe-data:snapshot-export location="/path/to/export/active/admins.snapshot" filter-ref="activeUsersFilter"/>
</gfe-data:snapshot-service>
<gfe-data:snapshot-service id="guestsSnapshotService" region-ref="Guests">
<gfe-data:snapshot-import location="/path/to/import/users.snapshot">
<bean class="example.geode.snapshot.filter.GuestsFilter/>
<bean class="example.gemfire.snapshot.filter.GuestsFilter/>
</gfe-data:snapshot-import>
<gfe-data:snapshot-export location="/path/to/export/active/guests.snapshot" filter-ref="activeUsersFilter"/>
</gfe-data:snapshot-service>
----
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
<constructor-arg index="0">
<list>
<ref bean="activeUsersSinceFilter"/>
<bean class="example.geode.snapshot.filter.CovertUsersFilter"/>
<bean class="example.gemfire.snapshot.filter.CovertUsersFilter"/>
</list>
</constructor-arg>
</bean>
@@ -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 `<gfe-data:snapshot-import>`