SGF-300 - Change all Spring Data Geode and Apache Geode references to Spring Data GemFire and Pivotal GemFire.
This commit is contained in:
@@ -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
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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`.
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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]
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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`.
|
||||
|
||||
@@ -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).
|
||||
|
||||
@@ -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.
|
||||
|
||||
|
||||
@@ -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.
|
||||
|
||||
|
||||
@@ -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].
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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:
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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]
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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_.
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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.
|
||||
|
||||
|
||||
@@ -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`
|
||||
|
||||
@@ -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].
|
||||
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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>`
|
||||
|
||||
Reference in New Issue
Block a user