Spring/spring-boot-data-geode
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Edit Reference Guide and replace all references to 'Apache Geode' using a documentation variable.

Browse Source 
Remove all references to 'GemFire'.

Fix compiler syntax errors in documentation code snippets.
This commit is contained in:
John Blum
2020-09-18 14:58:58 -07:00
parent 8f9a4e2f70
commit 429ff3f6dd
22 changed files with 739 additions and 717 deletions
Download Patch File Download Diff File Expand all files Collapse all files

10
spring-geode-docs/src/docs/asciidoc/_includes/actuator.adoc
View File

@@ -1,6 +1,7 @@
[[actuator]]
== Spring Boot Actuator
Spring Boot for {apache-geode-name} and {pivotal-gemfire-name} (SBDG) adds {spring-boot-docs-html}/production-ready.html[Spring Boot Actuator]
support and dedicated `HealthIndicators` for {apache-geode-name} and {pivotal-gemfire-name}. Equally, the provided
`HealthIndicators` will even work with Pivotal Cloud Cache, which is backed by {pivotal-gemfire-name}, when pushing your
@@ -36,8 +37,9 @@ The following section covers Spring Boot `HealthIndicators` that apply to both p
Spring Boot applications. That is, these `HealthIndicators` are not specific to the cache type.
In {apache-geode-name}, the cache instance is either a peer `Cache` instance, which makes your Spring Boot application
part of a GemFire/Geode cluster, or more commonly, a `ClientCache` instance that talks to an existing cluster. Your
Spring Boot application can only be one cache type or the other and can only have a single instance of that cache type.
part of a {apache-geode-name} cluster, or more commonly, a `ClientCache` instance that talks to an existing cluster.
Your Spring Boot application can only be one cache type or the other and can only have a single instance of
that cache type.
[[actuator-base-healthindicators-cache]]
==== GeodeCacheHealthIndicator
@@ -328,8 +330,8 @@ In addition, the following CQ query and statistical data is covered:
|=====================================================================================================================
In a more general sense, the GemFire/Geode Continuous Query system is tracked with the following, additional details
on the client:
In a more general sense, the {apache-geode-name} Continuous Query system is tracked with the following,
additional details on the client:
.Continuous Query(CQ), Statistic Details
[width="90%",cols="^3,<10",options="header"]

180
spring-geode-docs/src/docs/asciidoc/_includes/caching.adoc
View File

@@ -1,18 +1,18 @@
[[geode-caching-provider]]
== Caching using Apache Geode or VMware Tanzu GemFire
== Caching with Apache Geode
:gemfire-name: {pivotal-gemfire-name}
:geode-name: {apache-geode-name}
One of the quickest, easiest and least invasive ways to get started using {geode-name} or {gemfire-name} in your
Spring Boot applications is to use either {geode-name} or {gemfire-name} as a
{spring-framework-docs}/integration.html#cache-store-configuration[_caching provider_]
One of the easiest, quickest and least invasive ways to get started using {geode-name} in your Spring Boot applications
is to use {geode-name} as a {spring-framework-docs}/integration.html#cache-store-configuration[_caching provider_]
in {spring-framework-docs}/integration.html#cache[Spring's Cache Abstraction]. SDG
{spring-framework-docs}/integration.html#cache-store-configuration-gemfire[enables]
{geode-name} or {gemfire-name} to function as a _caching provider_ in Spring's Cache Abstraction.
{geode-name} to function as a _caching provider_ in Spring's Cache Abstraction.
TIP: See the _Spring Data for {geode-name} Reference Guide_ for more details on the
{spring-data-geode-docs-html}/#apis:spring-cache-abstraction[support] and {spring-data-geode-docs-html}/#bootstrap-annotation-config-caching[configuration]
of {geode-name} or {gemfire-name} as a _caching provider_ in Spring's Cache Abstraction.
of {geode-name} as a _caching provider_ in Spring's Cache Abstraction.
TIP: Make sure you thoroughly understand the {spring-framework-docs}/integration.html#cache-strategies[concepts]
behind Spring's Cache Abstraction before you continue.
@@ -28,63 +28,61 @@ Some classic examples of caching include, but are not limited to: looking up a c
looking up a book by ISBN, geocoding a physical address, caching the calculation of a person's credit score
when the person applies for a financial loan.
If you need the proven power of an enterprise-class caching solution, with strong consistency, high availability
and multi-site (WAN) capabilities, then you should consider https://geode.apache.org/[{geode-name}], or alternatively
https://pivotal.io/pivotal-gemfire[{gemfire-name}]. Additionally, https://pivotal.io/[Pivotal Software, Inc.]
offers {gemfire-name} as a service, known as https://pivotal.io/platform/services-marketplace/data-management/pivotal-cloud-cache[Pivotal Cloud Cache (PCC)],
when deploying and running your Spring Boot applications in https://pivotal.io/platform[Pivotal Cloud Foundry (PCF)].
If you need the proven power of an enterprise-class caching solution, with strong consistency, high availability,
low latency and multi-site (WAN) capabilities, then you should consider https://geode.apache.org/[{geode-name}],
or alternatively, VMWare, Inc. offers a commercial solution built on {geode-name} called, {gemfire-name}.
Spring's {spring-framework-docs}/integration.html#cache-annotations[declarative, annotation-based caching] makes it
extremely simple to get started with caching, which is as easy as annotating your application service components with
extremely simple to get started with caching, which is as easy as annotating your application components with
the appropriate Spring cache annotations.
TIP: Spring's declarative, annotation-based caching also {spring-framework-docs}/integration.html#cache-jsr-107[supports]
JCache (JSR-107) annotations.
For example, suppose you want to cache the results of determining a person's eligibility when applying for
a financial loan. A person's financial status is not likely to change in the time that the computer runs the algorithms
to compute a person's eligibility after all the financial information for the person has been collected and submitted
for review and processing.
For example, suppose you want to cache the results of determining a person's eligibility when applying for a financial
loan. A person's financial status is unlikely to change in the time that the computer runs the algorithms to compute
a person's eligibility after all the financial information for the person has been collected and submitted for review
and processing.
Our application might consist of a financial loan service to process a person's eligibility over a given period of time:
.Spring application service component applicable to caching
[source,java]
----
@Service
class FinancialLoanApplicationService {
@Cacheable("EligibilityDecisions")
EligibilityDecision processEligility(Person person, Timespan timespan) {
EligibilityDecision processEligibility(Person person, Timespan timespan) {
// ...
}
}
----
Notice the `@Cacheable` annotation on the `processEligibility(:Person, :Timespan)` method of our service class.
Notice the `@Cacheable` annotation declared on the `processEligibility(:Person, :Timespan)` method of our service class.
When the `FinancialLoanApplicationService.processEligibility(..)` method is called, Spring's caching infrastructure
first consults the "`EligibilityDecisions`" cache to determine if a decision has already been computed for the given
first consults the "_EligibilityDecisions_" cache to determine if a decision has already been computed for the given
person within the given span of time. If the person's eligibility in the given time frame has already been determined,
then the existing decision is returned from the cache. Otherwise, the `processEligibility(..)` method will be invoked
and the result of the method will be cached when the method returns, before returning the value to the caller.
and the result of the method will be cached when the method returns, before returning the decision to the caller.
Spring Boot for {geode-name}/{gemfire-name} _auto-configures_ {geode-name} or {gemfire-name} as the _caching provider_
when either one is declared on the application classpath, and when no other _caching provider_ (e.g. Redis)
has been configured.
Spring Boot for {geode-name} _auto-configures_ {geode-name} as the _caching provider_ when {geode-name} is declared on
the application classpath, and when no other _caching provider_ (e.g. Redis) has been configured.
If Spring Boot for {geode-name}/{gemfire-name} detects that another _cache provider_ has already been configured,
then neither {geode-name} nor {gemfire-name} will function as the _caching provider_. This allows users to configure,
another store, e.g. Redis, as the _caching provider_ and use {geode-name} or {gemfire-name} as your application's
persistent store, perhaps.
If Spring Boot for {geode-name} detects that another _cache provider_ has already been configured, then {geode-name}
will not function as the _caching provider_ for the application. This allows users to configure another store, e.g.
Redis, as the _caching provider_ and perhaps use {geode-name} as your application's persistent store.
The only other requirement to enable caching in a Spring Boot application is for the declared caches (as specified
in Spring's or JSR-107's caching annotations) to have been created and already exist, especially before the operation,
on which caching has been applied, is invoked. This means the backend data store must provide the data structure
serving as the "_cache_". For {geode-name} or {gemfire-name}, this means a `Region`.
in Spring's or JSR-107's caching annotations) to have been created and already exist, especially before the operation
on which caching has been applied is invoked. This means the backend data store must provide the data structure
serving as the "_cache_". For {geode-name} this means a cache `Region`.
To configure the necessary Regions backing the caches declared in Spring's cache annotations, this is as simple as
using Spring Data for {geode-name} or {gemfire-name}'s
{spring-data-geode-javadoc}/org/springframework/data/gemfire/config/annotation/EnableCachingDefinedRegions.html[`@EnableCachingDefinedRegions`] annotation.
using Spring Data for {geode-name}'s
{spring-data-geode-javadoc}/org/springframework/data/gemfire/config/annotation/EnableCachingDefinedRegions.html[`@EnableCachingDefinedRegions`]
annotation.
The complete Spring Boot application looks like this:
@@ -108,15 +106,14 @@ is annotated with Spring's `@Service` stereotype annotation.
TIP: You can set the `DataPolicy` of the Region created through the `@EnableCachingDefinedRegions` annotation by
setting the `clientRegionShortcut` to a valid enumerated value.
NOTE: Spring Boot for {geode-name}/{gemfire-name} does not recognize nor apply the `spring.cache.cache-names` property.
Instead, you should use SDG's `@EnableCachingDefinedRegions` on an appropriate Spring Boot application
`@Configuration` class.
NOTE: Spring Boot for {geode-name} does not recognize nor apply the `spring.cache.cache-names` property. Instead, you
should use SDG's `@EnableCachingDefinedRegions` on an appropriate Spring Boot application `@Configuration` class.
[[geode-caching-provider-look-aside-near-inline-multi-site]]
=== Look-Aside Caching, Near Caching, Inline Caching and Multi-Site Caching
Four different types of caching patterns can be applied with Spring when using Apace Geode or {gemfire-name}
for your application caching needs.
Four different types of caching patterns can be applied with Spring when using {geode-name} for your application caching
needs.
The 4 primary caching patterns include:
@@ -128,9 +125,9 @@ The 4 primary caching patterns include:
Typically, when most users think of caching, they are thinking of _Look-Aside Caching_. This is the default caching
pattern applied by _Spring's Cache Abstraction_.
In a nutshell, _Near Caching_ keeps the data closer to where the data is used thereby improving on performance
due to lower latencies when data is needed (i.e. no network hops). This also improves application throughput,
i.e. the amount of work completed in a given time frame.
In a nutshell, _Near Caching_ keeps the data closer to where the data is used thereby improving on performance due to
lower latencies when data is needed (i.e. no extra network hops). This also improves application throughput, i.e. the
amount of work completed in a given period of time.
Within _Inline Caching_, developers have a choice between synchronous (_Read/Write-Through_) and asynchronous
(_Write-Behind_) configurations depending on the application use case and requirements. Synchronous, Read/Write-Through
@@ -198,10 +195,10 @@ to see _Near Caching_ using {apache-geode-name} in action!
_Near Caching_ is another pattern of caching where the cache is collocated with the application. This is useful when
the caching technology is configured using a client/server arrangement.
We already mentioned that Spring Boot for {geode-name} & {gemfire-name} <<clientcache-applications.adoc#geode-clientcache-applications, provides>>
an _auto-configured_, `ClientCache` instance, out-of-the-box, by default. The `ClientCache` instance is most effective
when the data access operations, including cache access, is distributed to the servers in a cluster accessible by
the client, and in most cases, multiple clients. This allows other cache client applications to access the same data.
We already mentioned that Spring Boot for {geode-name} <<clientcache-applications.adoc#geode-clientcache-applications, provides>>
an _auto-configured_, `ClientCache` instance, out-of-the-box, by default. A `ClientCache` instance is most effective
when the data access operations, including cache access, is distributed to the servers in a cluster accessible by the
client, and in most cases, multiple clients. This allows other cache client applications to access the same data.
However, this also means the application will incur a network hop penalty to evaluate the presence of the data
in the cache.
@@ -210,9 +207,10 @@ maintains a subset of the data in the corresponding server-side cache (i.e. Regi
only contains the data of interests to the application. This "local" cache (i.e. client-side Region) is consulted
before forwarding the lookup request to the server.
To enable _Near Caching_ when using either {geode-name} or {gemfire-name}, simply change the Region's (i.e. the `Cache`
in Spring's Cache Abstraction) data management policy from `PROXY` (the default) to `CACHING_PROXY`, like so:
To enable _Near Caching_ when using either {geode-name}, simply change the Region's (i.e. the `Cache` in Spring's
Cache Abstraction) data management policy from `PROXY` (the default) to `CACHING_PROXY`, like so:
.Enabling Near Caching using {geode-name}
[source,java]
----
@SpringBootApplication
@@ -231,45 +229,44 @@ As such, all data access operations are immediately forwarded to the server.
TIP: Also see the {geode-name} documentation concerning
{apache-geode-docs}/developing/events/how_client_server_distribution_works.html[Client/Server Event Distribution]
and specifically, "_Client Interest Registration on the Server_" when using local, client CACHING_PROXY Regions
to manage state in addition to the corresponding server-side Region. This is necessary to receive updates on entries
in the Region that might have been changed by other clients accessing the same data.
and specifically, "_Client Interest Registration on the Server_" when client CACHING_PROXY Regions to manage state
in addition to the corresponding server-side Region. This is necessary to receive updates on entries in the Region
that might have been changed by other clients accessing the same data.
[[geode-caching-provider-inline-caching]]
==== Inline Caching
TIP: Refer to the corresponding Sample link:guides/caching-inline.html[Guide] and {github-samples-url}/caching/inline[Code]
to see _Inline Caching_ using {apache-geode-name} in action!
to see _Inline Caching_ using {geode-name} in action!
The next pattern of caching we will discuss in this chapter is _Inline Caching_.
There are two different configurations of _Inline Caching_ that developers can apply to their Spring Boot applications
when using this pattern of caching: Synchronous (_Read/Write-Through_) and Asynchronous (_Write-Behind_).
when using _Inline Caching_ pattern: Synchronous (_Read/Write-Through_) and Asynchronous (_Write-Behind_).
NOTE: Asynchronous (currently) only offers write capabilities, from the cache to the backend, external data source.
There is not option to asynchronously and automatically load the cache when the entry value becomes available in the
backend, external data source.
There is no option to asynchronously and automatically load the cache when the value becomes available in the backend,
external data source.
[[geode-caching-provider-inline-caching-synchronous]]
===== Synchronous Inline Caching
When employing _Inline Caching_ and a cache miss occurs, the application service method may still not be invoked
since a Region can be configured to invoke a loader to load the missing entry from an backend, external data source.
When employing _Inline Caching_ and a cache miss occurs, the application service method may still not be invoked since
a cache can be configured to invoke a loader to load the missing entry from an backend, external data source.
With {geode-name} and {gemfire-name}, the cache, or using {geode-name}/{gemfire-name} terminology, the Region, can be
configured with a {apache-geode-javadoc}/org/apache/geode/cache/CacheLoader.html[CacheLoader]. A `CacheLoader` is
implemented to retrieve missing values from an external data source, which could be an RDBMS or any other type of
data store (e.g. another NoSQL store like Apache Cassandra, MongoDB or Neo4j).
With {geode-name} the cache, or using {geode-name} terminology, the Region, can be configured with a
{apache-geode-javadoc}/org/apache/geode/cache/CacheLoader.html[CacheLoader]. A `CacheLoader` is implemented to retrieve
missing values from an external data source, which could be an RDBMS or any other type of data store (e.g. another NoSQL
data store like Apache Cassandra, MongoDB or Neo4j), when a cache miss occurs.
TIP: See the {geode-name} User Guide on {apache-geode-docs}/developing/outside_data_sources/how_data_loaders_work.html[Data Loaders]
for more details.
TIP: See the {geode-name} User Guide on
{apache-geode-docs}/developing/outside_data_sources/how_data_loaders_work.html[Data Loaders] for more details.
Likewise, an {geode-name} or {gemfire-name} Region can also be configured with a
Likewise, an {geode-name} Region can also be configured with a
{apache-geode-javadoc}/org/apache/geode/cache/CacheWriter.html[CacheWriter]. A `CacheWriter` is responsible for writing
any entry put into the Region to the backend data store, such as an RDBMS. This is referred to as a "_write-through_"
an entry put into the Region to the backend data store, such as an RDBMS. This is referred to as a "_write-through_"
operation because it is synchronous. If the backend data store fails to be updated then the entry will not be stored in
the Region. This helps to ensure some level of consistency between the backend data store and the {geode-name}
or {gemfire-name} Region.
the Region. This helps to ensure consistency between the backend data store and the {geode-name} Region.
TIP: It is also possible to implement _Inline-Caching_ using _asynchronous_, _write-behind_ operations by registering
an {apache-geode-javadoc}/org/apache/geode/cache/asyncqueue/AsyncEventListener.html[AsyncEventListener] on an
@@ -302,7 +299,7 @@ class CustomerService {
----
The main difference is, there are no Spring or JSR-107 caching annotations applied to the application's service methods
and the `CustomerRepository` is accessing {geode-name} or {gemfire-name} directly and NOT the RDBMS.
and the `CustomerRepository` is accessing {geode-name} directly and NOT the RDBMS.
[[geode-caching-provider-inline-caching-synchronous-cacheloader-cachewriter]]
====== Implementing CacheLoaders & CacheWriters for Inline Caching
@@ -429,8 +426,8 @@ _Inline Caching_ in the next section.
[[geode-caching-provider-inline-caching-synchronous-using-spring-data-repositories]]
====== Inline Caching using Spring Data Repositories
Spring Boot for {geode-name} & {gemfire-name} (SBDG) now offers dedicated support and configuration of _Inline Caching_
using Spring Data Repositories.
Spring Boot for {geode-name} (SBDG) offers dedicated support to configure _Inline Caching_ using Spring Data
Repositories.
This is very powerful because it allows you to:
@@ -443,22 +440,19 @@ It is our belief that users should be storing data where it is most easily acces
and processing Documents, then MongoDB, Couchbase or another document store is probably going to be the most logical
choice to manage your application's Documents.
However, that does not mean you have to give up {geode-name} or {gemfire-name} in your application/system architecture.
You can leverage each data store for what it is good at. While MongoDB is excellent at handling documents, {geode-name}
is a highly valuable choice for consistency, high availability, multi-site, low-latency/high-throughput scale-out
application use cases.
However, this does not mean you have to give up {geode-name} in your application/system architecture. You can leverage
each data store for what it is good at. While MongoDB is excellent at handling documents, {geode-name} is a highly
valuable choice for consistency, high availability, low-latency/high-throughput, multi-site, scale-out application
use cases.
As such, using {geode-name} and {gemfire-name}'s `CacheLoader/CacheWriter` mechanism provides a nice integration point
between itself and other data stores to best serve your application's use case and requirements.
And now, SBDG has just made this even easier.
As such, using {geode-name}'s `CacheLoader/CacheWriter` functionality provides a nice integration point between itself
and other data stores to best serve your application's use case and requirements.
EXAMPLE
Let's say you are using JPA/Hibernate to access (store and retrieve) data managed in an Oracle Database.
Then, you can configure {geode-name} to read/write-through to the backend Oracle Database when performing cache (Region)
operations by delegating to a Spring Data (JPA) Repository.
Let's say you are using JPA/Hibernate to access (store and read) data managed in an Oracle Database. Then, you can
configure {geode-name} to read/write-through to the backend Oracle Database when performing cache (Region) operations
by delegating to a Spring Data JPA Repository.
The configuration might look something like:
@@ -905,14 +899,14 @@ in more detail in the Sample link:guides/caching-multi-site.html[Guide]. Also, b
[[geode-caching-provider-advanced-configuration]]
=== Advanced Caching Configuration
Both {geode-name} and {gemfire-name} support additional caching capabilities to manage the entries stored in the cache.
{geode-name} supports additional caching capabilities to manage the entries stored in the cache.
As you can imagine, given that cache entries are stored in-memory, it becomes important to monitor and manage the
available memory wisely. After all, by default, both {geode-name} and {gemfire-name} store data in the JVM Heap.
available memory wisely. After all, by default, {geode-name} stores data in the JVM Heap.
Several techniques can be employed to more effectively manage memory, such as using
{apache-geode-docs}/developing/eviction/chapter_overview.html[Eviction], possibly
{apache-geode-docs}/developing/storing_data_on_disk/chapter_overview.html[overflowing to disk],
{apache-geode-docs}/developing/storing_data_on_disk/chapter_overview.html[overflowing data to disk],
configuring both entry _Idle-Timeout_ (TTI) as well as _Time-To-Live_ (TTL)
{apache-geode-docs}/developing/expiration/chapter_overview.html[Expiration policies],
configuring {apache-geode-docs}/managing/region_compression.html[Compression],
@@ -921,17 +915,16 @@ and using {apache-geode-docs}/managing/heap_use/off_heap_management.html[Off-Hea
There are several other strategies that can be used as well, as described in
{apache-geode-docs}/managing/heap_use/heap_management.html[Managing Heap and Off-heap Memory].
While this is well beyond the scope of this document, know that Spring Data for {geode-name} & {gemfire-name}
make all of these {spring-data-geode-docs-html}/#bootstrap-annotation-config-regions[configuration options] available
and simple to use.
While this is well beyond the scope of this document, know that Spring Data for {geode-name} makes all of these
{spring-data-geode-docs-html}/#bootstrap-annotation-config-regions[configuration options] available and simple to use.
[[geode-caching-provider-disable]]
=== Disable Caching
There may be cases where you do not want your Spring Boot application to cache application state with
{spring-framework-docs}/integration.html#cache[Spring's Cache Abstraction] using either {geode-name} or {gemfire-name}.
In certain cases, you may be using another Spring supported caching provider, such as Redis, to cache and manage
your application state, while, even in other cases, you may not want to use Spring's Cache Abstraction at all.
{spring-framework-docs}/integration.html#cache[Spring's Cache Abstraction] using {geode-name}. In certain cases, you
may be using another Spring supported caching provider, such as Redis, to cache and manage your application state,
while, even in other cases, you may not want to use Spring's Cache Abstraction at all.
Either way, you can specifically call out your Spring Cache Abstraction provider using the `spring.cache.type` property
in `application.properties`, as follows:
@@ -961,9 +954,8 @@ See Spring Boot {spring-boot-docs-html}/boot-features-caching.html#boot-features
for more details.
TIP: It is possible to include multiple providers on the classpath of your Spring Boot application. For instance,
you might be using Redis to cache your application's state while using either {geode-name} or {gemfire-name}
as your application's persistent store (_System of Record_).
you might be using Redis to cache your application's state while using {geode-name} as your application's persistent
data store (_System of Record_).
NOTE: Spring Boot does not properly recognize `spring.cache.type=[gemfire|geode]` even though
Spring Boot for {geode-name}/{gemfire-name} is setup to handle either of these property values
(i.e. either "`gemfire`" or "`geode`").
NOTE: Spring Boot does not properly recognize `spring.cache.type=[gemfire|geode]` even though Spring Boot
for {geode-name} is setup to handle either of these property values (i.e. either "`gemfire`" or "`geode`").

141
spring-geode-docs/src/docs/asciidoc/_includes/clientcache-applications.adoc
View File

@@ -1,19 +1,22 @@
[[geode-clientcache-applications]]
== Building ClientCache Applications
== Building `ClientCache` Applications
:geode-name: {apache-geode-name}
The first, opinionated option provided to you by Spring Boot for Apache Geode & Pivotal GemFire (SBDG) out-of-the-box is
a {apache-geode-javadoc}/org/apache/geode/cache/client/ClientCache.html[ClientCache] instance, simply by declaring
either Spring Boot for Apache Geode or Spring Boot for Pivotal GemFire on your application classpath.
It is assumed that most application developers using Spring Boot to build applications backed by either Apache Geode
or Pivotal GemFire will be building cache client applications deployed in an Apache Geode or Pivotal GemFire
{apache-geode-docs}/topologies_and_comm/cs_configuration/chapter_overview.html[Client/Server topology].
A client/server topology is the most common and traditional architecture employed by enterprise applications.
The first opinionated option provided to you by Spring Boot for {geode-name} (SBDG) out-of-the-box is a
{apache-geode-javadoc}/org/apache/geode/cache/client/ClientCache.html[ClientCache] instance simply by declaring
Spring Boot for {geode-name} on your application classpath.
For example, you can begin building a Spring Boot, Apache Geode or Pivotal GemFire, `ClientCache` application
with either the `spring-geode-starter` or `spring-gemfire-starter` on your application's classpath:
It is assumed that most application developers using Spring Boot to build applications backed by {geode-name} will be
building cache client applications deployed in an {geode-name}
{apache-geode-docs}/topologies_and_comm/cs_configuration/chapter_overview.html[Client/Server Topology].
The _client/server topology_ is the most common and traditional architecture employed by enterprise applications when
using {geode-name}.
.Spring Boot for Apache Geode on the application classpath
For example, you can begin building a Spring Boot, {geode-name} `ClientCache` application by declaring the
`spring-geode-starter` on your application's classpath:
.Spring Boot for {geode-name} on the application classpath
[source,xml]
----
<dependency>
@@ -22,10 +25,10 @@ with either the `spring-geode-starter` or `spring-gemfire-starter` on your appli
</dependency>
----
Then, you configure and bootstrap your Spring Boot, Apache Geode `ClientCache` application with the following
Then, you configure and bootstrap your Spring Boot, {geode-name} `ClientCache` application with the following
main application class:
.Spring Boot, Apache Geode `ClientCache` Application
.Spring Boot, {geode-name} `ClientCache` Application
[source,java]
----
@SpringBootApplication
@@ -37,28 +40,27 @@ public class SpringBootApacheGeodeClientCacheApplication {
}
----
Your application now has a `ClientCache` instance, which is able to connect to an Apache Geode or Pivotal GemFire server
running on `localhost`, listening on the default `CacheServer` port, `40404`.
Your application now has a `ClientCache` instance, which is able to connect to an {geode-name} server running on
`localhost`, listening on the default `CacheServer` port, `40404`.
By default, an Apache Geode or Pivotal GemFire server (i.e. `CacheServer`) must be running in order to use
the `ClientCache` instance. However, it is perfectly valid to create a `ClientCache` instance and perform
data access operations using `LOCAL` Regions. This is very useful during development.
By default, an {geode-name} server (i.e. `CacheServer`) must be running in order to use the `ClientCache` instance.
However, it is perfectly valid to create a `ClientCache` instance and perform data access operations using `LOCAL`
Regions. This is very useful during development.
TIP: To develop with `LOCAL` Regions, you only need to define your cache Regions with the
TIP: To develop with `LOCAL` Regions, you only need to configure your cache Regions with the
{apache-geode-javadoc}/org/apache/geode/cache/client/ClientRegionShortcut.html#LOCAL[`ClientRegionShortcut.LOCAL`]
data management policy.
When you are ready to switch from your local development environment (IDE) to a client/server architecture in a managed
environment, you simply change the data management policy of the client Region from `LOCAL` back to the default `PROXY`,
or even a `CACHING_PROXY`, data management policy which will cause the data to be sent/received to and from 1 or more
servers, respectively.
or even a `CACHING_PROXY`, which will cause the data to be sent/received to and from 1 or more servers, respectively.
TIP: Compare and contrast the above configuration with Spring Data for Apache Geode/Pivotal GemFire's
TIP: Compare and contrast the above configuration with Spring Data for {geode-name}
{spring-data-geode-docs-html}/#bootstrap-annotation-config-geode-applications[approach].
It is uncommon to ever need a direct reference to the `ClientCache` instance provided by SBDG injected into your
application components (e.g. `@Service` or `@Repository` beans defined in a Spring `ApplicationContext`) whether you
are configuring additional GemFire/Geode objects (e.g. Regions, Indexes, etc) or simply using those objects indirectly
are configuring additional {geode-name} objects (e.g. Regions, Indexes, etc) or simply using those objects indirectly
in your applications. However, it is also possible to do so if and when needed.
For example, perhaps you want to perform some additional `ClientCache` initialization in a Spring Boot
@@ -103,16 +105,16 @@ It is the 2nd part, "_get out of the way quickly as requirements start to diverg
that we refer to here.
If your application requirements demand you use Spring Boot to configure and bootstrap an embedded, peer `Cache`
Apache Geode or Pivotal GemFire application, then simply declare your intention with either SDG's
instance, then simply declare your intention with either SDG's
{spring-data-geode-javadoc}/org/springframework/data/gemfire/config/annotation/PeerCacheApplication.html[`@PeerCacheApplication`] annotation,
or alternatively, if you need to enable connections from `ClientCache` apps as well, use the SDG
or alternatively, if you need to enable connections from `ClientCache` apps as well, use SDG's
{spring-data-geode-javadoc}/org/springframework/data/gemfire/config/annotation/CacheServerApplication.html[`@CacheServerApplication`] annotation:
.Spring Boot, Apache Geode/Pivotal GemFire CacheServer Application
.Spring Boot, {geode-name} `CacheServer` Application
[source,java]
----
@SpringBootApplication
@CacheServerApplication(name = "MySpringBootApacheGeodeCacheServerApplication")
@CacheServerApplication(name = "SpringBootApacheGeodeCacheServerApplication")
public class SpringBootApacheGeodeCacheServerApplication {
public static void main(String[] args) {
@@ -121,19 +123,19 @@ public class SpringBootApacheGeodeCacheServerApplication {
}
----
TIP: An Apache Geode/Pivotal GemFire "server" is not necessarily a "`CacheServer`" capable of serving cache clients.
It is merely a peer member node in a GemFire/Geode cluster (a.k.a. distributed system) that stores and manages data.
TIP: An {geode-name} "server" is not necessarily a `CacheServer` capable of serving cache clients. It is merely a peer
member node in an {geode-name} cluster (a.k.a. distributed system) that stores and manages data.
By explicitly declaring the `@CacheServerApplication` annotation, you are telling Spring Boot that you do not want
the default, `ClientCache` instance, but rather an embedded, peer `Cache` instance with a `CacheServer` component,
which enables connections from `ClientCache` apps.
You can also enable 2 other GemFire/Geode services, an embedded _Locator_, which allows clients or even other peers
to "locate" servers in a cluster, as well as an embedded _Manager_, which allows the GemFire/Geode application process
to be managed and monitored using {apache-geode-docs}/tools_modules/gfsh/chapter_overview.html[_Gfsh_], GemFire/Geode's
shell tool:
You can also enable 2 other {geode-name} services, an embedded _Locator_, which allows clients or even other peers
to "locate" servers in the cluster, as well as an embedded _Manager_, which allows the {geode-name} application process
to be managed and monitored using {apache-geode-docs}/tools_modules/gfsh/chapter_overview.html[_Gfsh_], {geode-name}'s
command-line shell tool:
.Spring Boot, Apache Geode/Pivotal GemFire CacheServer Application with _Locator_ and _Manager_ services enabled
.Spring Boot, {geode-name} `CacheServer` Application with _Locator_ and _Manager_ services enabled
[source,java]
----
@SpringBootApplication
@@ -197,9 +199,9 @@ Client Connections : 0
----
You can even start additional servers in _Gfsh_, which will connect to your Spring Boot configured and bootstrapped
Apache Geode or Pivotal GemFire `CacheServer` application. These additional servers started in _Gfsh_ know about
the Spring Boot, GemFire/Geode server because of the embedded _Locator_ service, which is running on `localhost`,
listening on the default _Locator_ port, `10334`:
{geode-name} `CacheServer` application. These additional servers started in _Gfsh_ know about the Spring Boot,
{geode-name} server because of the embedded _Locator_ service, which is running on `localhost`, listening on
the default _Locator_ port, `10334`:
[source,text]
----
@@ -224,7 +226,7 @@ GfshServer | 10.0.0.121(GfshServer:30031)<v1>:1
----
Perhaps you want to start the other way around. As developer, I may need to connect my Spring Boot configured
and bootstrapped GemFire/Geode server application to an existing cluster. You can start the cluster in _Gfsh_
and bootstrapped {geode-name} server application to an existing cluster. You can start the cluster in _Gfsh_
by executing the following commands:
[source,text]
@@ -268,11 +270,11 @@ GfshServer | 10.0.0.121(GfshServer:30270)<v1>:1025
Then, modify the `SpringBootApacheGeodeCacheServerApplication` class to connect to the existing cluster, like so:
.Spring Boot, Apache Geode/Pivotal GemFire CacheServer Application with _Locator_ and _Manager_ services enabled
.Spring Boot, {geode-name} `CacheServer` Application connecting to an external cluster
[source,java]
----
@SpringBootApplication
@CacheServerApplication(name = "MySpringBootApacheGeodeCacheServerApplication", locators = "localhost[11235]")
@CacheServerApplication(name = "SpringBootApacheGeodeCacheServerApplication", locators = "localhost[11235]")
public class SpringBootApacheGeodeCacheServerApplication {
public static void main(String[] args) {
@@ -284,7 +286,7 @@ public class SpringBootApacheGeodeCacheServerApplication {
TIP: Notice I configured the `SpringBootApacheGeodeCacheServerApplication` class, `@CacheServerApplication` annotation's
`locators` property with the host and port (i.e. "_localhost[11235]_") on which I started my _Locator_ using _Gfsh_.
After running your Spring Boot, Apache Geode `CacheServer` application again, and then running `list members` in _Gfsh_,
After running your Spring Boot, {geode-name} `CacheServer` application again, and then running `list members` in _Gfsh_,
you should see:
[source,text]
@@ -317,8 +319,8 @@ Running : true
Client Connections : 0
----
In both scenarios, the Spring Boot configured and bootstrapped Apache Geode (or Pivotal GemFire) server
and the _Gfsh_ _Locator_ and _Server_ formed a cluster.
In both scenarios, the Spring Boot configured and bootstrapped {geode-name} server and the _Gfsh_ _Locator_
and _Gfsh_ _Server_ formed a cluster.
While you can use either approach and Spring does not care, it is far more convenient to use Spring Boot and your IDE
to form a small cluster while developing. By leveraging Spring profiles, it is far simpler and much faster to
@@ -342,10 +344,10 @@ TIP: See the Appendix, <<geode-cluster-configuration-bootstrapping>> for more de
In addition to `ClientCache`, `CacheServer` and peer `Cache` applications, SDG, and by extension SBDG, now supports
Locator-based, Spring Boot applications.
An Apache Geode or Pivotal GemFire Locator is a location-based service, or alternatively and more typically,
a standalone process enabling clients to "locate" a cluster of Apache Geode/Pivotal GemFire servers to manage data.
Many cache clients can connect to the same cluster in order to share data. Running multiple clients is common in a
Microservices architecture where you need to scale-up the number of app instances to satisfy the demand.
An {geode-name} Locator is a location-based service, or alternatively and more typically, a standalone process enabling
clients to "locate" a cluster of {geode-name} servers to manage data. Many cache clients can connect to the same cluster
in order to share data. Running multiple clients is common in a Microservices architecture where you need to scale-up
the number of app instances to satisfy the demand.
A Locator is also used by joining members of an existing cluster to scale-out and increase capacity of the logically
pooled system resources (i.e. Memory, CPU and Disk). A Locator maintains metadata that is sent to the clients to
@@ -398,8 +400,8 @@ class SpringBootApacheGeodeLocatorApplication {
Instead of using the `@EnableLocator` annotation, you now use the `@LocatorApplication` annotation.
The `@LocatorApplication` annotation works in the same way as the `@PeerCacheApplication` and `@CacheServerApplication`
annotations, bootstrapping a Apache Geode or Pivotal GemFire process, overriding the default `ClientCache` instance
provided by SBDG out-of-the-box.
annotations, bootstrapping an {geode-name} process, overriding the default `ClientCache` instance provided by SBDG
out-of-the-box.
NOTE: If your `@SpringBootApplication` class is annotated with `@LocatorApplication`, then it can only be a `Locator`
and not a `ClientCache`, `CacheServer` or peer `Cache` application. If you need the application to function as a
@@ -407,10 +409,10 @@ peer `Cache`, perhaps with an embedded `CacheServer` components and embedded Loc
the approach shown above using the `@EnableLocator` annotation with either the `@PeerCacheApplication`
or `@CacheServerApplication` annotation.
With our Spring Boot, Apache Geode Locator application, we can connect both Spring Boot configured and bootstrapped
With our Spring Boot, {geode-name} Locator application, we can connect both Spring Boot configured and bootstrapped
peer members (peer `Cache`, `CacheServer` and `Locator` applications) as well as _Gfsh_ started Locators and Servers.
First, let's startup 2 Locators using our Apache Geode Locator, Spring Boot application class.
First, let's startup 2 Locators using our {geode-name} Locator, Spring Boot application class.
.SpringBootApacheGeodeLocatorApplication class
[source,java]
@@ -420,14 +422,13 @@ include::{docs-src-dir}/org/springframework/geode/docs/example/app/locator/Sprin
We also need to vary the configuration for each Locator app instance.
Apache Geode and Pivotal GemFire requires each peer member in the cluster to be uniquely named. We can set the name
of the Locator by using the `spring.data.gemfire.locator.name` SDG property set as a JVM System Property in your IDE's
Run Configuration Profile for the application main class like so: `-Dspring.data.gemfire.locator.name=SpringLocatorOne`.
We name the second Locator app instance, "_SpringLocatorTwo_".
{geode-name} requires each peer member in the cluster to be uniquely named. We can set the name of the Locator by using
the `spring.data.gemfire.locator.name` SDG property set as a JVM System Property in your IDE's Run Configuration Profile
for the application main class like so: `-Dspring.data.gemfire.locator.name=SpringLocatorOne`. We name the second
Locator app instance, "_SpringLocatorTwo_".
Additionally, we must vary the port numbers that the Locators use to listen for connections. By default,
an Apache Geode or Pivotal GemFire Locator listens on port `10334`. We can set the Locator port using the
`spring.data.gemfire.locator.port` SDG property.
Additionally, we must vary the port numbers that the Locators use to listen for connections. By default, an {geode-name}
Locator listens on port `10334`. We can set the Locator port using the `spring.data.gemfire.locator.port` SDG property.
For our first Locator app instance (i.e. "_SpringLocatorOne_"), we also enable the "_manager_" Profile so that
we can connect to the Locator using _Gfsh_.
@@ -442,7 +443,7 @@ And our IDE Run Configuration Profile for our second Locator app instance appear
You should see log output similar to the following when you start a Locator app instance:
.Spring Boot, Apache Geode Locator log output
.Spring Boot, {geode-name} Locator log output
[source,txt]
----
. ____ _ __ _ _
@@ -551,7 +552,7 @@ SpringLocatorTwo | 10.99.199.24(SpringLocatorTwo:30077:locator)<ec><v1>:41001
----
Using our `SpringBootApacheGeodeCacheServerApplication` main class from the previous section, we can configure
and bootstrap an Apache Geode `CacheServer` application with Spring Boot and connect it to our cluster of Locators.
and bootstrap an {geode-name} `CacheServer` application with Spring Boot and connect it to our cluster of Locators.
.SpringBootApacheGeodeCacheServerApplication class
[source,java]
@@ -565,7 +566,7 @@ Simply enable the "clustered" Profile by using a IDE Run Profile Configuration s
After the server starts up, you should see the new peer member in the cluster:
.Cluster with Spring Boot configured and bootstrapped Apache Geode `CacheServer`
.Cluster with Spring Boot configured and bootstrapped {geode-name} `CacheServer`
[source,txt]
----
gfsh>list members
@@ -615,18 +616,18 @@ GfshLocator | 10.99.199.24(GfshLocator:30259:locator)<ec><v3>:41003
GfshServer | 10.99.199.24(GfshServer:30295)<v4>:41004
----
You must be careful to vary the ports and name your peer members appropriately. With Spring, and Spring Boot
for Apache Geode and Pivotal GemFire (SBDG) in particular, it really is that easy!
You must be careful to vary the ports and name of your peer members appropriately. With Spring, and Spring Boot
for {geode-name} (SBDG) in particular, it really is that easy!
[[geode-manager-applications]]
=== Building Manager Applications
As discussed in the previous sections above, it is possible to enable a Spring Boot configured and bootstrapped
Apache Geode or Pivotal GemFire peer member node in the cluster to function as a _Manager_.
{geode-name} peer member node in the cluster to function as a _Manager_.
An Apache Geode or Pivotal GemFire _Manager_ is a peer member node in the cluster running the Management Service,
allowing the cluster to be managed and monitored using JMX based tools, like _Gfsh_, _JConsole_ or _JVisualVM_,
for instance. Any tool that uses the JMX API can connect to and manage the GemFire/Geode cluster for whatever purpose.
An {geode-name} _Manager_ is a peer member node in the cluster running the Management Service, allowing the cluster
to be managed and monitored using JMX based tools, like _Gfsh_, _JConsole_ or _JVisualVM_, for instance. Any tool
that uses the JMX API can connect to and manage an {geode-name} cluster for whatever purpose.
The cluster may have more than 1 _Manager_ for redundancy. Only server-side, peer member nodes in the cluster
may function as a _Manager_. Therefore, a `ClientCache` application cannot be a _Manager_.
@@ -682,9 +683,9 @@ TIP: See the `@EnableManager` annotation
{spring-data-geode-javadoc}/org/springframework/data/gemfire/config/annotation/EnableManager.html[Javadoc]
for additional configuration options.
As of Apache Geode 1.11.0, you must now include additional Geode dependencies on your Spring Boot application classpath
to make your application a proper Apache Geode/Pivotal GemFire _Manager_ in the cluster, particularly if you are also
enabling the embedded HTTP service in the _Manager_.
As of {geode-name} 1.11.0, you must now include additional {geode-name} dependencies on your Spring Boot application
classpath to make your application a proper {geode-name} _Manager_ in the cluster, particularly if you are also enabling
the embedded HTTP service in the _Manager_.
The required dependencies are:

144
spring-geode-docs/src/docs/asciidoc/_includes/cloudfoundry.adoc
View File

@@ -1,21 +1,29 @@
[[cloudfoundry]]
== Pivotal CloudFoundry
:geode-name: {apache-geode-name}
:images-dir: ./images
:pcc-name: Pivotal Cloud Cache
:pcf-name: Pivotal CloudFoundry
In most cases, when you "_push_" (i.e. "_deploy_") your Spring Boot applications to Pivotal CloudFoundry (PCF)
you will bind your app to 1 or more instances of the Pivotal Cloud Cache (PCC) service.
In a nutshell, {pivotal-cloudcache-website}[Pivotal Cloud Cache] is a managed version of
{pivotal-gemfire-website}[Pivotal GemFire] running in {pivotal-cloudfoundry-website}[Pivotal CloudFoundry].
NOTE: As of the VMware, Inc acquisition of Pivotal Software, Inc, {pcf-name} (PCF) is now known as VMware Tanzu
Application Service (TAS) for VMs. Also, {pcc-name} (PCC) has been rebranded as VMware Tanzu GemFire for VMS.
This documentation will eventually be updated to reflect the rebranding.
In most cases, when you deploy (i.e. "_push_") your Spring Boot applications to {pcf-name} (PCF) you will bind your app
to 1 or more instances of the {pcc-name} (PCC) service.
In a nutshell, {pivotal-cloudcache-website}[{pcc-name}] (PCC) is a managed version of
{pivotal-gemfire-website}[Pivotal GemFire] running in {pivotal-cloudfoundry-website}[{pcf-name}] (PCF).
When running in or across cloud environments (e.g. AWS, Azure, GCP or PWS), PCC with PCF offers several advantages
over trying to run and manage your own standalone Apache Geode or Pivotal GemFir clusters. It handles many of
the infrastructure-related, operational concerns so you do not have to.
over trying to run and manage your own standalone {geode-name} clusters. It handles many of the infrastructure-related,
operational concerns so you do not have to.
[[cloudfoundry-cloudcache-security-auth-runtime-user-configuration]]
=== Running Spring Boot applications as a specific user
By default, Spring Boot applications run as a "_cluster_operator_" Role-based user in Pivotal CloudFoundry (PCF)
when the app is bound to a Pivotal Cloud Cache (PCC) service instance.
By default, Spring Boot applications run as a "_cluster_operator_" Role-based user in {pcf-name} when the app is bound
to a {pcc-name} service instance.
A "_cluster_operator_" has full system privileges (i.e. Authorization) to do whatever that user wishes to involving
the PCC service instance. A "_cluster_operator_" has read/write access to all the data, can modify the schema
@@ -34,12 +42,12 @@ the `@EnableClusterConfiguration` annotation:
----
@SpringBootApplication
@EnableClusterConfiguration(useHttp = true)
class SpringBootApacheGeodeClientCacheApplication { ... }
class SpringBootApacheGeodeClientCacheApplication { }
----
With `@EnableClusterConfiguration`, Region and OQL Index configuration metadata defined on the client can be sent to
servers in the PCC cluster. Apache Geode and Pivotal GemFire requires matching Regions by name on both the client
and servers in order for clients to send and receive data to and from the cluster.
servers in the PCC cluster. {geode-name} requires matching Regions by name on both the client and servers in order for
clients to send and receive data to and from the cluster.
For example, when you declare the Region where an application entity will be persisted using the `@Region` mapping
annotation and additionally declare the `@EnableEntityDefinedRegions` annotation on the main `@SpringBootApplication`
@@ -57,12 +65,12 @@ may only need read access. Therefore, it is ideal to be able to configure your
a different user at runtime other than the auto-configured "_cluster_operator_", by default.
A prerequisite for running a Spring Boot application using PCC with a specific user is to create a user with restricted
permissions using Pivotal CloudFoundry AppsManager while provisioning the PCC service instance to which the Spring Boot
application will be bound.
permissions using {pcf-name} _AppsManager_ while provisioning the PCC service instance to which the Spring Boot app
will be bound.
Configuration metadata for the PCC service instance might appear as follows:
.Pivotal Cloud Cache configuration metadata
.{pcc-name} configuration metadata
[source,json]
----
{
@@ -82,7 +90,6 @@ Configuration metadata for the PCC service instance might appear as follows:
"password": "*****",
"roles": [ "developer" ],
"username": "developer_user"
},
}, {
"password": "*****",
"roles": [ "read-only-user" ],
@@ -97,7 +104,6 @@ Configuration metadata for the PCC service instance might appear as follows:
}
}
},
...
"name": "jblum-pcc",
"plan": "small",
"tags": [ "gemfire", "cloudcache", "database", "pivotal" ]
@@ -122,9 +128,8 @@ TIP: The `spring.data.gemfire.security.username` property corresponds directly t
See the {spring-data-geode-javadoc}/org/springframework/data/gemfire/config/annotation/EnableSecurity.html#securityUsername--[Javadoc]
for more details.
The `spring.data.gemfire.security.username` property is the same property used by Spring Data for Apache Geode
and Pivotal GemFire (SDG) to configure the runtime user of your Spring Data application when connecting to either
an externally managed Apache Geode or Pivotal GemFire cluster.
The `spring.data.gemfire.security.username` property is the same property used by Spring Data for {geode-name} (SDG) to
configure the runtime user of your Spring Data application when connecting to an externally managed {geode-name} cluster.
In this case, SBDG simply uses the configured username to lookup the authentication credentials of the user to set
the username and password used by the Spring Boot, `ClientCache` app when connecting to PCC while running in PCF.
@@ -134,15 +139,15 @@ If the username is not valid, then an `IllegalStateException` is thrown.
By using {spring-boot-docs-html}/#boot-features-profiles[Spring Profiles], it would be a simple matter to configure
the Spring Boot application to run with a different user depending on environment.
See the Pivotal Cloud Cache documentation on {pivotal-cloudcache-docs}/security.html[Security] for configuring users
with assigned roles & permissions.
See the {pcc-name} documentation on {pivotal-cloudcache-docs}/security.html[Security] for configuring users with
assigned roles & permissions.
[[cloudfoundry-cloudcache-security-auth-autoconfiguration-override]]
==== Overriding Authentication Auto-configuration
It should be generally understood that _auto-configuration_ for client authentication is only available for managed
environments, like Pivotal CloudFoundry. When running in externally managed environments, you must explicitly set
a username and password to authenticate, as described <<geode-security-auth-clients-non-managed,here>>.
environments, like {pcf-name}. When running in externally managed environments, you must explicitly set a username
and password to authenticate, as described <<geode-security-auth-clients-non-managed,here>>.
To completely override the _auto-configuration_ of client authentication, simply set both a username and password:
@@ -159,14 +164,14 @@ In this case, SBDG's _auto-configuration_ for authentication is effectively disa
will not be extracted from the environment.
[[cloudfoundry-cloudcache-serviceinstance-targeting]]
=== Targeting Specific Pivotal Cloud Cache Service Instances
=== Targeting Specific {pcc-name} Service Instances
It is possible to provision multiple instances of the Pivotal Cloud Cache service in your Pivotal CloudFoundry
environment. You can then bind multiple PCC service instances to your Spring Boot app.
It is possible to provision multiple instances of the {pcc-name} service in your {pcf-name} environment. You can then
bind multiple PCC service instances to your Spring Boot app.
However, Spring Boot for Apache Geode & Pivotal GemFire (SBDG) will only auto-configure 1 PCC service instance for your
Spring Boot application. This does not mean it is not possible to use multiple PCC service instances with your
Spring Boot app, just that SBDG only "_auto-configures_" 1 service instance for you.
However, Spring Boot for {geode-name} (SBDG) will only auto-configure 1 PCC service instance for your Spring Boot
application. This does not mean it is not possible to use multiple PCC service instances with your Spring Boot app,
just that SBDG only "_auto-configures_" 1 service instance for you.
You must select which PCC service instance your Spring Boot app will auto-configure for you automatically when you have
multiple instances and want to target a specific PCC service instance to use.
@@ -193,14 +198,14 @@ then SBDG will auto-configure the first PCC service instance it finds by name, a
If you did not set the property and no PCC service instance is found, then SBDG will log a warning.
[[cloudfoundry-cloudcache-multiinstance-using]]
=== Using Multiple Pivotal Cloud Cache Service Instances
=== Using Multiple {pcc-name} Service Instances
If you want to use multiple PCC service instances with your Spring Boot application, then you need to configure
multiple connection `Pools` connected to each PCC service instance used by your Spring Boot application.
The configuration would be similar to the following:
.Multple Pivotal Cloud Cache Service Instance Configuration
.Multiple {pcc-name} Service Instance Configuration
[source,java]
----
@Configuration
@@ -211,7 +216,7 @@ The configuration would be similar to the following:
@EnablePool(name = "PccN")
})
class PccConfiguration {
...
// ...
}
----
@@ -241,9 +246,12 @@ the specific PCC service instance (cluster):
.Assigning a Pool to a client Region
[source,java]
----
@Bean("Example")
ClientRegionFactoryBean exampleRegion(GemFireCache gemfireCache,
@Qualifier("PccTwo") Pool poolForPccTwo) {
@Configuration
class GeodeConfiguration {
@Bean("Example")
ClientRegionFactoryBean exampleRegion(GemFireCache gemfireCache,
@Qualifier("PccTwo") Pool poolForPccTwo) {
ClientRegionFactoryBean exampleRegion = new ClientRegionFactoryBean();
@@ -252,11 +260,12 @@ ClientRegionFactoryBean exampleRegion(GemFireCache gemfireCache,
exampleRegion.setShortcut(ClientRegionShortcut.PROXY);
return exampleRegion;
}
}
----
You can configure as many Pools and client Regions as needed by your application. Again, the `Pool` determines
which Pivotal Cloud Cache service instance and cluster the data for the client Region will reside.
which {pcc-name} service instance and cluster the data for the client Region will reside.
NOTE: By default, SBDG configures all `Pools` declared in a Spring Boot, `ClientCache` application to connect to
and use a single PCC service instance. This may be a targeted PCC service instance when using the
@@ -264,19 +273,18 @@ and use a single PCC service instance. This may be a targeted PCC service insta
as discussed <<cloudfoundry-cloudcache-multiinstance-using,above>>.
[[cloudfoundry-geode]]
=== Hybrid Pivotal CloudFoundry & Apache Geode Spring Boot Applications
=== Hybrid {pcf-name} & {geode-name} Spring Boot Applications
Sometimes, it is desirable to deploy (i.e. "_push_") and run your Spring Boot applications in Pivotal CloudFoundry,
but still connect your Spring Boot applications to an externally managed, standalone Apache Geode or Pivotal GemFire
cluster.
Sometimes, it is desirable to deploy (i.e. "_push_") and run your Spring Boot applications in {pcf-name}, but still
connect your Spring Boot applications to an externally managed, standalone {geode-name} cluster.
Spring Boot for Apache Geode & Pivotal GemFire (SBDG) makes this a non-event and honors its "_little to no code
or configuration changes necessary_" goal, regardless of your runtime choice, "_it should just work!_"
Spring Boot for {geode-name} (SBDG) makes this a non-event and honors its "_little to no code or configuration changes
necessary_" goal, regardless of your runtime choice, "_it should just work!_"
To help guide you through this process, we will cover the following topics:
1. Install and Run PCFDev.
2. Start an Apache Geode cluster.
2. Start an {geode-name} cluster.
3. Create a User-Provided Service (CUPS).
4. Push and Bind a Spring Boot application.
5. Run the Spring Boot application.
@@ -292,9 +300,9 @@ applications. However, it does so in the confines of your local development envi
Additionally, PCF Dev provides several services out-of-the-box, such as MySQL, Redis and RabbitMQ. These services
can be bound and used by your Spring Boot application to accomplish its tasks.
However, PCF Dev lacks the Pivotal Cloud Cache (PCC) service that is available in PCF. This is actually ideal for
this little exercise since we are trying to build and run Spring Boot applications in a PCF environment
but connect to an externally managed, standalone Apache Geode or Pivotal GemFire cluster.
However, PCF Dev lacks the {pcc-name} service that is available in PCF. This is actually ideal for this little exercise
since we are trying to build and run Spring Boot applications in a PCF environment but connect to an externally managed,
standalone {geode-name} cluster.
As a prerequisite, you will need to follow the steps outlined in the
https://pivotal.io/platform/pcf-tutorials/getting-started-with-pivotal-cloud-foundry-dev/introduction[tutorial]
@@ -369,12 +377,12 @@ Apps Manager provides a nice UI to manage your org, space, services and apps. I
create services, bind apps to the services and start and stop your deployed applications, among many other things.
[[cloudfoundry-geode-cluster]]
==== Running an Apache Geode Cluster
==== Running an {geode-name} Cluster
Now that PCF Dev is setup and running, we need to start an external, standalone Apache Geode cluster that our Spring Boot
Now that PCF Dev is setup and running, we need to start an external, standalone {geode-name} cluster that our Spring Boot
application will connect to and use to manage its data.
You will need to install a {apache-geode-website}/releases/[distribution] of Apache Geode on your workstation.
You will need to install a {apache-geode-website}/releases/[distribution] of {geode-name} on your workstation.
Then you must set the `$GEODE` environment variable. It is also convenient to add `$GEODE/bin` to your system `$PATH`.
Afterward, you can launch the Geode Shell (_Gfsh_) tool:
@@ -396,9 +404,9 @@ Monitor and Manage Apache Geode
gfsh>
----
We have conveniently provided the _Gfsh_ shell script used to start the Apache Geode cluster:
We have conveniently provided the _Gfsh_ shell script used to start the {geode-name} cluster:
.Gfsh shell script to start the Apache Geode cluster
.Gfsh shell script to start the {geode-name} cluster
[source,txt]
----
include::{docs-resources-dir}/geode/bin/start-cluster.gfsh[]
@@ -416,7 +424,7 @@ size your cluster accordingly, based on your application's needs since there is
You will see output similar to the following when starting the Locator and Server:
.Starting the Apache Geode cluster
.Starting the {geode-name} cluster
[source,txt]
----
gfsh>start locator --name=LocatorOne --log-level=config --classpath=/Users/jblum/pivdev/spring-boot-data-geode/apache-geode-extensions/build/libs/apache-geode-extensions-1.1.0.BUILD-SNAPSHOT.jar --J=-Dgemfire.security-manager=org.springframework.geode.security.TestSecurityManager --J=-Dgemfire.http-service-port=8080
@@ -482,12 +490,12 @@ as well as on the server-side (cluster). More on this below.
[[cloudfoundry-geode-cups]]
==== Creating a User-Provided Service
Now that we have PCF Dev and a small Apache Geode cluster up and running, it is time to create a User-Provided Service
to the external, standalone Apache Geode cluster that we started in <<cloudfoundry-geode-cluster,step 2>>.
Now that we have PCF Dev and a small {geode-name} cluster up and running, it is time to create a User-Provided Service
to the external, standalone {geode-name} cluster that we started in <<cloudfoundry-geode-cluster,step 2>>.
As mentioned, PCF Dev offers the MySQL, Redis and RabbitMQ services out-of-the-box. However, to use Apache Geode
(or Pivotal GemFire) in the same capacity as you would Pivotal Cloud Cache when running in a production-grade,
PCF environment, you need to create a User-Provided Service for the standalone Apache Geode cluster.
As mentioned, PCF Dev offers the MySQL, Redis and RabbitMQ services out-of-the-box. However, to use {geode-name} in
the same capacity as you would {pcc-name} when running in a production-grade, PCF environment, you need to create a
User-Provided Service for the standalone {geode-name} cluster.
To do so, execute the following `cf` CLI command:
@@ -524,14 +532,14 @@ cf cups apacheGeodeService -t "gemfire, cloudcache, database, pivotal" \
-p '{ "locators": [ "10.99.199.24[10334]" ], "urls": { "gfsh": "https://10.99.199.24/gemfire/v1" }, "users": [{ "password": "admin", "roles": [ "cluster_operator" ], "username": "admin" }] }'
----
We replaced the `<hostname>` placeholder tag with the IP address of our external Apache Geode Locator. The IP address
We replaced the `<hostname>` placeholder tag with the IP address of our external {geode-name} Locator. The IP address
can be found in the _Gfsh_ `start locator` output above.
Additionally, the `<port>` placeholder tag has been replaced with the default Locator port, `10334`,
Finally, we set the `username` and `password` accordingly.
TIP: Spring Boot for Apache Geode (SBDG) provides template files in the {docs-dir}/src/main/resources directory.
TIP: Spring Boot for {geode-name} (SBDG) provides template files in the {docs-dir}/src/main/resources directory.
Once the service has been created, you can query the details from the `cf` CLI:
@@ -675,9 +683,9 @@ the "apacheGeodeService" as seen in the `VCAP_SERVICES` _Environment Variable_:
image::{images-dir}/pcfdev-appsmanager-org-space-app-settings-envvars.png[]
This JSON document structure is not unlike the configuration used to bind your Spring Boot, `ClientCache` application
to the Pivotal Cloud Cache service when deploying the same app to Pivotal CloudFoundry. This is actually very key
if you want to minimize the amount of boilerplate code and configuration changes when migrating between different
CloudFoundry environments, even https://www.cloudfoundry.org/[Open Source CloudFoundry].
to the {pcc-name} service when deploying the same app to {pcf-name}. This is actually very key if you want to minimize
the amount of boilerplate code and configuration changes when migrating between different CloudFoundry environments,
even https://www.cloudfoundry.org/[Open Source CloudFoundry].
Again, SBDG's entire goal is to simply the effort for you, as a developer, to build, run and manage your application,
in whatever context your application lands, even if it changes later. If you follow the steps in this documentation,
@@ -757,12 +765,12 @@ Rows : 1
There you have it!
The ability to deploy Spring Boot, Apache Geode or Pivotal GemFire `ClientCache` applications to Pivotal CloudFoundry,
yet connect your app to a externally managed, standalone Apache Geode or Pivotal GemFire cluster.
The ability to deploy Spring Boot, {geode-name} `ClientCache` applications to {pcf-name}, yet connect your app to an
externally managed, standalone {geode-name} cluster is powerful.
Indeed, this is will be a useful arrangement and stepping stone for many users as they begin their journey towards
a Cloud-Native platform like Pivotal CloudFoundry (PCF) and using services like Pivotal Cloud Cache (PCC).
Cloud-Native platforms like {pcf-name} and using services like {pcc-name}.
Later, when the time comes and your need is very real, you can simply migrate your Spring Boot applications to a fully
managed and production-grade Pivotal CloudFoundry environment and SBDG will figure out what to do, leaving you to focus
entirely on your application.
Later, when the time comes and your need is real, you can simply migrate your Spring Boot applications to a fully
managed and production-grade {pcf-name} environment and SBDG will figure out what to do, leaving you to focus entirely
on your application.

72
spring-geode-docs/src/docs/asciidoc/_includes/configuration-annotations.adoc
View File

@@ -1,36 +1,39 @@
[[geode-auto-configuration-annotations]]
== Auto-configuration vs. Annotation-based configuration
:geode-name: {apache-geode-name}
:vmw-gemfire-name: VMware Tanzu GemFire
:vmw-tas-name: VMware Tanzu Application Service
The question most often asked is, "_What Spring Data for Apache Geode/Pivotal GemFire annotations can I use,
or must I use, when developing Apache Geode or Pivotal GemFire applications with Spring Boot?_"
The question most often asked is, "_What Spring Data for {geode-name} (SDG) annotations can I use, or must I use, when
developing {geode-name} applications with Spring Boot?_"
This section will answer this question and more.
Readers should refer to the complimentary sample, link:guides/boot-configuration.html[Spring Boot Auto-configuration for Apache Geode & Pivotal GemFire],
which showcases the _auto-configuration_ provided by Spring Boot for Apache Geode/Pivotal GemFire in action.
Readers should refer to the complimentary sample, link:guides/boot-configuration.html[Spring Boot Auto-configuration for {geode-name}],
which showcases the _auto-configuration_ provided by Spring Boot for {geode-name} in action.
[[geode-autoconfiguration-annotations-background]]
=== Background
To help answer this question, we must start by reviewing the complete collection of available
Spring Data for Apache Geode/Pivotal GemFire (SDG) annotations. These annotations are provided in the
To help answer this question, we must start by reviewing the complete collection of available Spring Data for {geode-name}
(SDG) annotations. These annotations are provided in the
{spring-data-geode-javadoc}/org/springframework/data/gemfire/config/annotation/package-summary.html[org.springframework.data.gemfire.config.annotation]
package. Most of the pertinent annotations begin with `@Enable...`, except for the base annotations:
`@ClientCacheApplication`, `@PeerCacheApplication` and `@CacheServerApplication`.
By extension, Spring Boot for Apache Geode/Pivotal GemFire (SBDG) builds on SDG's Annotation-based configuration model
to implement _auto-configuration_ and apply Spring Boot's core concepts, like "_convention over configuration_",
enabling GemFire/Geode applications to be built with Spring Boot reliably, quickly and easily.
By extension, Spring Boot for {geode-name} (SBDG) builds on SDG's Annotation-based configuration model to implement
_auto-configuration_ and apply Spring Boot's core concepts, like "_convention over configuration_", enabling
{geode-name} applications to be built with Spring Boot reliably, quickly and easily.
SDG provides this Annotation-based configuration model to, first and foremost, give application developers "_choice_"
when building Spring applications using either Apache Geode or Pivotal GemFire. SDG makes no assumptions about what
application developers are trying to do and fails fast anytime the configuration is ambiguous, giving users immediate
feedback.
when building Spring applications using {geode-name}. SDG makes no assumptions about what application developers are
trying to do and fails fast anytime the configuration is ambiguous, giving users immediate feedback.
Second, SDG's Annotations were meant to get application developers up and running quickly and reliably with ease. SDG
accomplishes this by applying sensible defaults so application developers do not need to know, or even have to learn,
all the intricate configuration details and tooling provided by GemFire/Geode to accomplish simple tasks,
e.g. build a prototype.
all the intricate configuration details and tooling provided by {geode-name} to accomplish simple tasks, e.g. build a
prototype.
So, SDG is all about "choice" and SBDG is all about "convention". Together these frameworks provide application
developers with convenience and reliability to move quickly and easily.
@@ -83,10 +86,9 @@ In this section, we cover a few examples to make the behavior when overriding mo
By default, SBDG provides you with a `ClientCache` instance. Technically, SBDG accomplishes this by annotating
an auto-configuration class with `@ClientCacheApplication`, internally.
It is by convention that we assume most application developers' will be developing Spring Boot applications
using Apache Geode or Pivotal GemFire as "client" applications in GemFire/Geode's client/server topology. This is
especially true as users migrate their applications to a managed environment, such as Pivotal CloudFoundry (PCF)
using Pivotal Cloud Cache (PCC).
It is by convention that we assume most application developers' will be developing Spring Boot applications using
{geode-name} as "client" applications in {geode-name}'s client/server topology. This is especially true as users
migrate their applications to a managed cloud environment.
Still, users are free to "override" the default settings and declare their Spring applications to be actual peer `Cache`
members of a cluster, instead.
@@ -97,7 +99,7 @@ For example:
----
@SpringBootApplication
@CacheServerApplication
class MySpringBootPeerCacheServerApplication { ... }
class MySpringBootPeerCacheServerApplication { }
----
By declaring the `@CacheServerApplication` annotation, you effectively override the SBDG default. Therefore, SBDG
@@ -139,10 +141,10 @@ spring.data.gemfire.security.password=Secret
You do not need to explicitly declare the `@EnableSecurity` annotation just to specify Security configuration
(e.g. username/password).
Inside a managed environment, such as Pivotal CloudFoundry (PCF) when using Pivotal Cloud Cache (PCC), SBDG is able to
introspect the environment and configure Security (Auth) completely without the need to specify any configuration,
usernames/passwords, or otherwise. This is due in part because PCF supplies the security details in the VCAP
environment when the app is deployed to PCF and bound to services (e.g. PCC).
Inside a managed environment, such as the {vmw-tas-name} (TAS) when using {vmw-gemfire-name}, SBDG is able to introspect
the environment and configure Security (Auth) completely without the need to specify any configuration, usernames
/ passwords, or otherwise. This is due in part because PCF supplies the security details in the VCAP environment
when the app is deployed to TAS and bound to services (e.g. {vmw-gemfire-name}).
So, in short, you do not need to explicitly declare the `@EnableSecurity` annotation (or the `@ClientCacheApplication`
for that matter).
@@ -154,8 +156,8 @@ While explicitly declaring `@EnableSecurity` makes more sense when "overriding"
explicitly declaring the `@ClientCacheApplication` annotation most likely makes less sense with regard to its impact
on Security configuration.
This is entirely due to the internals of GemFire/Geode, which in certain cases, like Security, not even Spring
is able to completely shield users from the nuances of GemFire/Geode's configuration.
This is entirely due to the internals of {geode-name}, which in certain cases, like Security, not even Spring is able to
completely shield users from the nuances of {geode-name}'s configuration.
Both Auth and SSL must be configured before the cache instance (whether a `ClientCache` or a peer `Cache`,
it does not matter) is created. Technically, this is because Security is enabled/configured during the "construction"
@@ -169,7 +171,7 @@ in SBDG must be triggered before the ClientCache _auto-configuration_ class, whi
(i.e. you must also explicitly declare the `@EnableSecurity` annotation in this case since you overrode the
_auto-configuration_ of the cache, and, well, implicitly Security as well).
Again, this is due to the way Security (Auth) and SSL meta-data must be supplied to GemFire/Geode.
Again, this is due to the way Security (Auth) and SSL metadata must be supplied to {geode-name}.
See the <<geode-security,Reference Guide>> for more details.
@@ -209,7 +211,7 @@ class CustomerService {
}
----
Of course, it is necessary to create GemFire/Geode Regions backing the caches declared in your application service
Of course, it is necessary to create {geode-name} Regions backing the caches declared in your application service
components (e.g. "CustomersByName") using Spring's Caching Annotations (e.g. `@Cacheable), or alternatively,
JSR-107, JCache annotations (e.g. `@CacheResult`).
@@ -220,7 +222,7 @@ You can do that by defining each Region explicitly, or more conveniently, you ca
----
@SpringBootApplication
@EnableCachingDefinedRegions
class Application { ... }
class Application { }
----
`@EnableCachingDefinedRegions` is optional, provided for convenience, and complimentary to caching when used
@@ -256,7 +258,7 @@ public class TemperatureMonitor extends AbstractTemperatureEventPublisher {
}
----
Of course, GemFire/Geode CQ only applies to clients.
Of course, {geode-name} CQ only applies to clients.
See the <<geode-continuous-query,Reference Guide>> for more details.
@@ -271,11 +273,11 @@ and executions. You simply need to define the implementation:
[source,java]
----
@Component
class GemFireFunctions {
class GeodeFunctions {
@GemfireFunction
Object exampleFunction(Object arg) {
...
// ...
}
}
----
@@ -286,13 +288,13 @@ And then define the execution:
[source,java]
----
@OnRegion(region = "Example")
interface GemFireFunctionExecutions {
interface GeodeFunctionExecutions {
Object exampleFunction(Object arg);
}
----
SBDG will automatically find, configure and register Function Implementations (POJOs) in GemFire/Geode as proper
SBDG will automatically find, configure and register Function Implementations (POJOs) in {geode-name} as proper
`Functions` as well as create Executions proxies for the Interfaces which can then be injected into application service
components to invoke the registered `Functions` without needing to explicitly declare the enabling annotations.
The application Function Implementations & Executions (Interfaces) should simply exist below the `@SpringBootApplication`
@@ -343,7 +345,7 @@ See the <<geode-repositories,Reference Guide>> for more details.
=== Explicit Configuration
Most of the other annotations provided in SDG are focused on particular application concerns, or enable certain
GemFire/Geode features, rather than being a necessity.
{geode-name} features, rather than being a necessity.
A few examples include:
@@ -388,7 +390,7 @@ the feature appropriately, as needed by your application (e.g. `@EnableRedisServ
In other cases, you might also want to explicitly declare a complimentary annotation (e.g. `@EnableEntityDefinedRegions`)
for convenience, since there is no convention or "opinion" provided by SBDG out-of-the-box.
In all remaining cases, it boils down to understanding how GemFire/Geode works under-the-hood. While we go to great
In all remaining cases, it boils down to understanding how {geode-name} works under-the-hood. While we go to great
lengths to shield users from as many details as possible, it is not feasible or practical to address all matters,
e.g. cache creation and Security.

74
spring-geode-docs/src/docs/asciidoc/_includes/configuration-auto.adoc
View File

@@ -1,9 +1,10 @@
[[geode-configuration-auto]]
== Auto-configuration
:geode-name: {apache-geode-name}
The following Spring Framework, Spring Data for {apache-geode-name} & {pivotal-gemfire-name} (SDG) and Spring Session
for {apache-geode-name} and {pivotal-gemfire-name} (SSDG) _Annotations_ are implicitly declared by Spring Boot for
{apache-geode-name} & {pivotal-gemfire-name}'s (SBDG) _Auto-configuration_.
The following Spring Framework, Spring Data for {geode-name} (SDG) and Spring Session for {geode-name} (SSDG)
_Annotations_ are implicitly declared by Spring Boot for {geode-name}'s (SBDG) _Auto-configuration_.
* `@ClientCacheApplication`
* `@EnableGemfireCaching` (or alternatively, Spring Framework's `@EnableCaching`)
@@ -24,12 +25,12 @@ you wanted to "_override_" Spring Boot's, and in particular, SBDG's _Auto-config
TIP: You should read the chapter in Spring Boot's Reference Documentation on
{spring-boot-docs-html}/#using-boot-auto-configuration[Auto-configuration].
TIP: You should review the chapter in Spring Data for {apache-geode-name} and {pivotal-gemfire-name}'s (SDG) Reference Documentation
TIP: You should review the chapter in Spring Data for {geode-name}'s (SDG) Reference Documentation
on {spring-data-geode-docs-html}/#bootstrap-annotation-config[Annotation-based Configuration]. For a quick reference,
or an overview of Annotation-based Configuration, see {spring-data-geode-docs-html}/#bootstap-annotations-quickstart[here].
TIP: Refer to the corresponding Sample link:guides/boot-configuration.html[Guide] and {github-samples-url}/boot/configuration[Code]
to see Spring Boot Auto-configuration for {apache-geode-name} in action!
to see Spring Boot Auto-configuration for {geode-name} in action!
[[geode-configuration-auto-customizing]]
@@ -125,8 +126,8 @@ Overriding SBDG _Auto-configuration_ was <<geode-autoconfiguration-annotations-o
In a nutshell, if you want to override the default _Auto-configuration_ provided by SBDG then you must annotate
your `@SpringBootApplication` class with your intent.
For example, say you want to configure and bootstrap an {apache-geode-name} `CacheServer` application (a peer;
not a client), then you would:
For example, say you want to configure and bootstrap an {geode-name} `CacheServer` application (a peer; not a client),
then you would:
.Overriding the default `ClientCache` _Auto-Configuration_ by configuring & bootstrapping a `CacheServer` application
[source,java]
@@ -179,11 +180,11 @@ To review the complete list of SBDG _Auto-confiugration_ classes, <<geode-auto-c
NOTE: The {spring-boot-data-geode-javadoc}/org/springframework/geode/boot/autoconfigure/ClientCacheAutoConfiguration.html[`ClientCacheAutoConfiguration`] class
corresponds to the {spring-data-geode-javadoc}/org/springframework/data/gemfire/config/annotation/ClientCacheApplication.html[`@ClientCacheApplication`] annotation.
SBDG <<getting-started,starts>> with the opinion that application developers will primarily be building {apache-geode-name}
SBDG <<getting-started,starts>> with the opinion that application developers will primarily be building {geode-name}
<<geode-clientcache-applications,client applications>> using Spring Boot.
Technically, this means building Spring Boot applications with an {apache-geode-name} `ClientCache` instance connected
to a dedicated cluster of {apache-geode-name} servers that manage the data as part of a
Technically, this means building Spring Boot applications with an {geode-name} `ClientCache` instance connected to a
dedicated cluster of {geode-name} servers that manage the data as part of a
{apache-geode-docs}/topologies_and_comm/cs_configuration/chapter_overview.html[client/server] topology.
By way of example, this means you *do not* need to explicitly declare and annotate your `@SpringBootApplication` class
@@ -211,7 +212,7 @@ class SpringBootClientCacheApplication {
}
----
TIP: Refer to SDG's Reference Documentation for more details on {apache-geode-name}
TIP: Refer to SDG's Reference Documentation for more details on {geode-name}
{spring-data-geode-docs-html}/#bootstrap-annotation-config-geode-applications[cache applications],
and {spring-data-geode-docs-html}/#bootstrap-annotation-config-client-server-applications[client/server applications]
in particular.
@@ -222,7 +223,7 @@ in particular.
NOTE: The {spring-boot-data-geode-javadoc}/org/springframework/geode/boot/autoconfigure/CachingProviderAutoConfiguration.html[`CachingProviderAutoConfiguration`] class
corresponds to the {spring-data-geode-javadoc}/org/springframework/data/gemfire/cache/config/EnableGemfireCaching.html[`@EnableGemfireCaching`] annotation.
If you simply used the core Spring Framework to configure {apache-geode-name} as a _caching provider_
If you simply used the core Spring Framework to configure {geode-name} as a _caching provider_
in {spring-framework-docs}/integration.html#cache[Spring's Cache Abstraction], you would need to do this:
.Configuring caching using the Spring Framework
@@ -244,7 +245,7 @@ class CachingUsingApacheGeodeConfiguration {
}
----
If you were using Spring Data for {apache-geode-name}'s `@EnableGemfireCaching` annotation, then the above configuration
If you were using Spring Data for {geode-name}'s `@EnableGemfireCaching` annotation, then the above configuration
could be simplified to:
.Configuring caching using Spring Data Geode
@@ -294,7 +295,7 @@ corresponds to the {spring-data-geode-javadoc}/org/springframework/data/gemfire/
Without having to enable anything, you simply annotate your application (POJO) component method(s) with the SDG
{spring-data-geode-javadoc}/org/springframework/data/gemfire/listener/annotation/ContinuousQuery.html[`@ContinuousQuery`]
annotation to register a CQ and start receiving events. The method acts as a `CqEvent` handler, or in {apache-geode-name}'s
annotation to register a CQ and start receiving events. The method acts as a `CqEvent` handler, or in {geode-name}'s
case, the method would be an implementation of
{apache-geode-javadoc}/org/apache/geode/cache/query/CqListener.html[`CqListener`].
@@ -437,13 +438,13 @@ NOTE: The {spring-boot-data-geode-javadoc}/org/springframework/geode/boot/autoco
corresponds to the {spring-data-geode-javadoc}/org/springframework/data/gemfire/config/annotation/EnableLogging.html[`@EnableLogging`] annotation.
Logging is an essential application concern to understand what is happening in the system along with when and where
the event occurred. As such, SBDG auto-configures logging for {apache-geode-name} by default, using the default
log-level, "_config_".
the event occurred. As such, SBDG auto-configures logging for {geode-name} by default, using the default log-level,
"_config_".
If you wish to change an aspect of logging, such as the log-level, you would typically do this in Spring Boot
`application.properties`:
.Change the log-level for {apache-geode-name}
.Change the log-level for {geode-name}
[source,txt]
----
# Spring Boot application.properites.
@@ -452,11 +453,11 @@ spring.data.gemfire.cache.log-level=debug
----
Other aspects may be configured as well, such as the log file size and disk space limits for the file system location
used to store the {apache-geode-name} log files at runtime.
used to store the {geode-name} log files at runtime.
Under-the-hood, {apache-geode-name}'s logging is based on Log4j. Therefore, you can configure {apache-geode-name} logging using
any logging provider (e.g. Logback) and configuration metadata appropriate for that logging provider so long as you
supply the necessary adapter between Log4j and whatever logging system you are using. For instance, if you include
Under-the-hood, {geode-name}'s logging is based on Log4j. Therefore, you can configure {geode-name} logging using any
logging provider (e.g. Logback) and configuration metadata appropriate for that logging provider so long as you supply
the necessary adapter between Log4j and whatever logging system you are using. For instance, if you include
`org.springframework.boot:spring-boot-starter-logging` then you will be using Logback and you will need the
`org.apache.logging.log4j:log4j-to-slf4j` adapter.
@@ -475,8 +476,8 @@ or even possible in other cases (e.g. when you are using a 3rd party library for
In these situations, you need to be able to send your object anywhere without unduly requiring the class type
to be serializable as well as to exist on the classpath for every place it is sent. Indeed, the final destination
may not even be a Java application! This is where {apache-geode-name} {apache-geode-docs}/developing/data_serialization/gemfire_pdx_serialization.html[PDX Serialization]
steps into help.
may not even be a Java application! This is where {geode-name}
{apache-geode-docs}/developing/data_serialization/gemfire_pdx_serialization.html[PDX Serialization] steps into help.
However, you don't have to figure out how to configure PDX to identify the application class types that will need to be
serialized. You simply define your class type:
@@ -509,9 +510,8 @@ and {spring-boot-data-geode-javadoc}/org/springframework/geode/boot/autoconfigur
corresponds to the {spring-data-geode-javadoc}/org/springframework/data/gemfire/config/annotation/EnableSecurity.html[`@EnableSecurity`] annotation, but applies
Security, and specifically, Authentication/Authorization configuration for both clients and servers.
Configuring your Spring Boot, {apache-geode-name} `ClientCache` application to properly authenticate with a cluster of
secure{apache-geode-name} servers is as simple as setting a _username_ and _password_ in Spring Boot
`application.properties`:
Configuring your Spring Boot, {geode-name} `ClientCache` application to properly authenticate with a cluster of secure
{geode-name} servers is as simple as setting a _username_ and _password_ in Spring Boot `application.properties`:
.Supplying Authentication Credentials
[source,txt]
@@ -526,7 +526,7 @@ NOTE: Authentication is even easier to configure in a managed environment like P
you don't have to do anything!
Authorization is configured on the server-side and is made simple with SBDG and the help of https://shiro.apache.org/[Apache Shiro].
Of course, this assumes you are using SBDG to configure and bootstrap your {apache-geode-name} cluster in the first place,
Of course, this assumes you are using SBDG to configure and bootstrap your {geode-name} cluster in the first place,
which is <<geode-cluster-configuration-bootstrapping,possible>>, and made even easier with SBDG.
TIP: Refer to the <<geode-security,documentation>> for more details.
@@ -537,9 +537,9 @@ TIP: Refer to the <<geode-security,documentation>> for more details.
NOTE: The {spring-boot-data-geode-javadoc}/org/springframework/geode/boot/autoconfigure/SslAutoConfiguration.html[`SslAutoConfiguration`] class
corresponds to the {spring-data-geode-javadoc}/org/springframework/data/gemfire/config/annotation/EnableSsl.html[`@EnableSsl`] annotation.
Configuring SSL for secure transport (TLS) between your Spring Boot, {apache-geode-name} `ClientCache` application
and the cluster can be a real problematic task, especially to get correct from the start. So, it is something
that SBDG makes simple to do out-of-the-box.
Configuring SSL for secure transport (TLS) between your Spring Boot, {geode-name} `ClientCache` application and the
cluster can be a real problematic task, especially to get correct from the start. So, it is something that SBDG makes
simple to do out-of-the-box.
Simply supply a `trusted.keystore` file containing the certificates in a well-known location (e.g. root of your
application classpath) and SBDG's _Auto-configuration_ will kick in and handle of the rest.
@@ -555,8 +555,8 @@ TIP: Refer to the <<geode-security-ssl,documentation>> for more details.
NOTE: The {spring-boot-data-geode-javadoc}/org/springframework/geode/boot/autoconfigure/SpringSessionAutoConfiguration.html[`SpringSessionAutoConfiguration`] class
corresponds to the {spring-session-data-gemfire-javadoc}/org/springframework/session/data/gemfire/config/annotation/EnableSsl.html[`@EnableSsl`] annotation.
Configuring {apache-geode-name} to serve as the (HTTP) Session state caching provider using Spring Session is as simple
as including the correct starter, e.g. `spring-geode-starter-session`.
Configuring {geode-name} to serve as the (HTTP) Session state caching provider using Spring Session is as simple as
including the correct starter, e.g. `spring-geode-starter-session`.
.Using Spring Session
[source,xml]
@@ -569,10 +569,10 @@ as including the correct starter, e.g. `spring-geode-starter-session`.
</dependency>
----
With Spring Session, and specifically Spring Session for {apache-geode-name} (SSDG), on the classpath of your Spring
Boot, {apache-geode-name} `ClientCache` Web application, you can manage your (HTTP) Session state with {apache-geode-name}.
No further configuration is needed. SBDG _Auto-configuration_ detects Spring Session on the application classpath
and does the right thing.
With Spring Session, and specifically Spring Session for {geode-name} (SSDG), on the classpath of your Spring Boot,
{geode-name} `ClientCache` Web application, you can manage your (HTTP) Session state with {geode-name}. No further
configuration is needed. SBDG _Auto-configuration_ detects Spring Session on the application classpath and does
the right thing.
TIP: Refer to the <<geode-session,documentation>> for more details.
@@ -581,7 +581,7 @@ TIP: Refer to the <<geode-session,documentation>> for more details.
The SBDG {spring-boot-data-geode-javadoc}/org/springframework/geode/boot/autoconfigure/RegionTemplateAutoConfiguration.html[`RegionTemplateAutoConfiguration`] class
has no corresponding SDG _Annotation_. However, the _Auto-configuration_ of a `GemfireTemplate` for every single
{apache-geode-name} `Region` defined and declared in your Spring Boot application is supplied by SBDG never-the-less.
{geode-name} `Region` defined and declared in your Spring Boot application is supplied by SBDG never-the-less.
For example, if you defined a Region using:

141
spring-geode-docs/src/docs/asciidoc/_includes/configuration-declarative.adoc
View File

@@ -1,5 +1,7 @@
[[geode-configuration-declarative]]
== Declarative Configuration
:geode-name: {apache-geode-name}
The primary purpose of any software development framework is to help you be _productive_ as _quickly_ and as _easily_
as possible, and to do so in a _reliable_ manner.
@@ -35,12 +37,12 @@ Now, that we explained the motivation behind this chapter, let's outline what we
* Refer you to the SDG _Annotations_ covered by SBDG's _Auto-configuration_
* List all SDG _Annotations_ not covered by SBDG's _Auto-configuration_
* Cover the SBDG, SSDG and SDG _Annotations_ that must be declared explicitly and that provide the most value and productivity
when getting started using either Apache Geode or Pivotal GemFire in Spring [Boot] applications.
* Cover the SBDG, SSDG and SDG _Annotations_ that must be declared explicitly and that provide the most value
and productivity when getting started using either {geode-name} in Spring [Boot] applications.
NOTE: SDG refers to {spring-data-geode-website}[Spring Data for Apache Geode & Pivotal GemFire]. SSDG refers to
{spring-session-data-gemfire-website}[Spring Session for Apache Geode & Pivotal GemFire] and SBDG refers to
_Spring Boot for Apache Geode & Pivotal GemFire_, this project.
NOTE: SDG refers to {spring-data-geode-website}[Spring Data for {geode-name}]. SSDG refers to
{spring-session-data-gemfire-website}[Spring Session for {geode-name}] and SBDG refers to
_Spring Boot for {geode-name}_, this project.
TIP: The list of SDG _Annotations_ covered by SBDG's _Auto-configuration_ is discussed in detail in the <<appendix, Appendix>>,
in the section, <<geode-auto-configuration-annotations,Auto-configuration vs. Annotation-based configuration>>.
@@ -105,12 +107,12 @@ instance out-of-the-box.
Other _Annotations_ are driven by need, for example:
* `@EnableAutoRegionLookup` & `@EnableBeanFactoryLocator` - really only useful when mixing configuration metadata
formats, e.g. Spring config with GemFire `cache.xml`. This is usually only the case if you have legacy `cache.xml`
formats, e.g. Spring config with {geode-name} `cache.xml`. This is usually only the case if you have legacy `cache.xml`
config to begin with, otherwise, don't do this!
* `@EnableCompression` - requires the Snappy Compression Library on your application classpath.
* `@EnableDiskStore(s)` - only used for overflow and persistence.
* `@EnableOffHeap` - enables data to be stored in main memory, which is only useful when your application data
(i.e. Objects stored in GemFire/Geode) are generally uniform in size.
(i.e. Objects stored in {geode-name}) are generally uniform in size.
* `@EnableGemFireAsLastResource` - only needed in the context of JTA Transactions.
* `@EnableStatistics` - useful if you need runtime metrics, however enabling statistics gathering does consume
considerable system resources (e.g. CPU & Memory).
@@ -133,8 +135,8 @@ Still, all of these _Annotations_ are available for the application developer to
[[geode-configuration-declarative-annotations-productivity]]
=== Productivity Annotations
This section calls out the _Annotations_ we believe to be most beneficial for your application development purposes
when using either Apache Geode or Pivotal GemFire in Spring Boot applications.
This section calls out the _Annotations_ we believe to be most beneficial for your application development purposes when
using {geode-name} in Spring Boot applications.
[[geode-configuration-declarative-annotations-productivity-enableclusteraware]]
==== `@EnableClusterAware` (SBDG)
@@ -148,15 +150,15 @@ When you annotate your main `@SpringBootApplication` class with `@EnableClusterA
----
@SpringBootApplication
@EnableClusterAware
class SpringBootApacheGeodeClientCacheApplication { ... }
class SpringBootApacheGeodeClientCacheApplication { }
----
Your Spring Boot, Apache Geode `ClientCache` application is able to seamlessly switch between client/server
Your Spring Boot, {geode-name} `ClientCache` application is able to seamlessly switch between client/server
and local-only topologies with no code or configuration changes.
When a cluster of Apache Geode or Pivotal GemFire servers is detected, the client application will send and receive data
to and from the cluster. If a cluster is not available, then the client automatically switches to storing data locally
on the client using `LOCAL` Regions.
When a cluster of {geode-name} servers is detected, the client application will send and receive data to and from the
cluster. If a cluster is not available, then the client automatically switches to storing data locally on the client
using `LOCAL` Regions.
Additionally, the `@EnableClusterAware` annotation is meta-annotated with SDG's
{spring-data-geode-javadoc}/org/springframework/data/gemfire/config/annotation/EnableClusterConfiguration.html[`@EnableClusterConfiguration`] annotation.
@@ -189,15 +191,19 @@ Of course, you can create Regions using Java configuration and the Spring API as
.Creating a Region with Spring JavaConfig
[source,java]
----
@Bean("Customers")
ClientRegionFactoryBean<Long, Customer> customersRegion(GemFireCache cache) {
@Configuration
class GeodeConfiguration {
ClientRegionFactoryBean<Long, Customer> customers = new ClientRegionFactoryBean<>();
@Bean("Customers")
ClientRegionFactoryBean<Long, Customer> customersRegion(GemFireCache cache) {
customers.setCache(cache);
customers.setShortcut(ClientRegionShortcut.PROXY);
ClientRegionFactoryBean<Long, Customer> customers = new ClientRegionFactoryBean<>();
return customers;
customers.setCache(cache);
customers.setShortcut(ClientRegionShortcut.PROXY);
return customers;
}
}
----
@@ -228,9 +234,9 @@ For example, given:
@Service
class CustomerService {
@Cacheable("CustomersByAccountNumber" key="#account.number")
@Cacheable(cacheNames = "CustomersByAccountNumber", key = "#account.number")
Customer findBy(Account account) {
...
// ...
}
}
----
@@ -242,7 +248,7 @@ When your main `@SpringBootApplication` class is annotated with `@EnableCachingD
----
@SpringBootApplication
@EnableCachingDefineRegions
class SpringBootApacheGeodeClientCacheApplication { ... }
class SpringBootApacheGeodeClientCacheApplication { }
----
Then, SBDG would create a client `PROXY` Region (or `PARTITION_REGION` if your application were a peer member of the
@@ -276,7 +282,6 @@ class Customer {
@Indexed
private String name;
...
}
----
@@ -290,7 +295,7 @@ the main `@SpringBootApplication` class is annotated with `@EnableEntityDefinedR
@SpringBootApplication
@EnableEntityDefinedRegions(basePackageClasses = Customer.class,
clientRegionShortcut = ClientRegionShortcut.CACHING_PROXY)
class SpringBootApacheGeodeClientCacheApplication { ... }
class SpringBootApacheGeodeClientCacheApplication { }
----
Like the `@EnableCachingDefinedRegions` annotation, you can set the client and server Region data management policy
@@ -339,7 +344,7 @@ Then, you could configure the `@EnableEntityDefinedRegions` as follows:
----
@SpringBootApplication
@EnableEntityDefinedRegions(basePackageClasses = { NonEntity.class, Account.class } )
class SpringBootApacheGeodeClientCacheApplication { ... }
class SpringBootApacheGeodeClientCacheApplication { }
----
If `Customer`, `Address`, `PhoneNumber` and `Account` were all entity classes properly annotated with `@Region`, then
@@ -365,7 +370,7 @@ This is as simple as annotating your main `@SpringBootApplication` class with `@
----
@SpringBootApplication
@EnableClusterDefinedRegions
class SpringBootApacheGeodeClientCacheApplication { ... }
class SpringBootApacheGeodeClientCacheApplication { }
----
Every Region that exists on the cluster of servers will have a corresponding `PROXY` Region defined and created on the
@@ -383,14 +388,15 @@ class SomeApplicationComponent {
@Resource(name = "ServerRegion")
private Region<Integer, EntityType> serverRegion;
public void sometMethod() {
public void someMethod() {
EntityType entity = ...;
EntityType entity = new EntityType();
this.serverRegion.put(1, entity);
...
// ...
}
}
----
Of course, SBDG _auto-configures_ a `GemfireTemplate` for the "_ServerRegion_" Region (as described <<geode-configuration-declarative-auto-configuration-regiontemplates,here>>),
@@ -405,16 +411,17 @@ class SomeApplicationComponent {
@Autowired
@Qualifier("serverRegionTemplate")
private GemfireTemplate serverRegionTemplate
private GemfireTemplate serverRegionTemplate;
public void sometMethod() {
public void someMethod() {
EntityType entity = ...;
EntityType entity = new EntityType();
this.serverRegionTemplate.put(1, entity);
...
//...
}
}
----
TIP: Refer to the SDG Reference Guide on {spring-data-geode-docs-html}/#bootstrap-annotation-config-region-cluster-defined[Configuring Cluster-defined Regions]
@@ -449,7 +456,6 @@ class Customer {
@Indexed
private String name;
...
}
----
@@ -461,14 +467,14 @@ As a result, when our main `@SpringBootApplication` class is annotated with `@En
@SpringBootApplication
@EnableEntityDefinedRegions(basePackageClasses = Customer.class)
@EnableIndexing
class SpringBootApacheGeodeClientCacheApplication { ... }
class SpringBootApacheGeodeClientCacheApplication { }
----
An Apache Geode OQL Index for the `Customer.name` field will be created thereby making OQL Queries on Customers by name
An {geode-name} OQL Index for the `Customer.name` field will be created thereby making OQL Queries on Customers by name
use this Index.
NOTE: Keep in mind that OQL Indexes are not persistent between restarts (i.e. Apache Geode & Pivotal GemFire
maintains Indexes in-memory only). An OQL Index is always rebuilt when the node is restarted.
NOTE: Keep in mind that OQL Indexes are not persistent between restarts (i.e. {geode-name} maintains Indexes in-memory
only). An OQL Index is always rebuilt when the node is restarted.
When you combine `@EnableIndexing` with either `@EnableClusterConfiguration` or `@EnableClusterAware`, then the Index
definitions will be pushed to the server-side Regions where OQL Queries are generally executed.
@@ -479,10 +485,10 @@ for more details.
[[geode-configuration-declarative-annotations-productivity-enableexpiration]]
==== `@EnableExpiration` (SDG)
It is often useful to define both _Eviction_ and _Expiration_ policies, particularly with a system like Apache Geode
or Pivotal GemFire, especially given it primarily keeps data in-memory, on the JVM Heap. As you can imagine your data
volume size may far exceed the amount of available JVM Heap memory and/or keeping too much data on the JVM Heap
can cause Garbage Collection (GC) issues.
It is often useful to define both _Eviction_ and _Expiration_ policies, particularly with a system like {geode-name},
especially given it primarily keeps data in-memory, on the JVM Heap. As you can imagine your data volume size may far
exceed the amount of available JVM Heap memory and/or keeping too much data on the JVM Heap can cause Garbage Collection
(GC) issues.
TIP: You can enable off-heap (or main memory usage) capabilities by declaring SDG's `@EnableOffHeap` annotation.
Refer to the SDG Reference Guide on {spring-data-geode-docs-html}/#bootstrap-annotation-config-region-off-heap[Configuring Off-Heap Memory]
@@ -501,7 +507,7 @@ class type itself, using the {spring-data-geode-javadoc}/org/springframework/dat
and {spring-data-geode-javadoc}/org/springframework/data/gemfire/expiration/TimeToLiveExpiration.html[`@TimeToLiveExpiration`]
annotations.
TIP: Refer to the Apache Geode {apache-geode-docs}/developing/expiration/how_expiration_works.html[User Guide]
TIP: Refer to the {geode-name} {apache-geode-docs}/developing/expiration/how_expiration_works.html[User Guide]
for more details on the different Expiration Types (i.e. _Idle Timeout_ (TTI) vs. _Time-To-Live_ (TTL)).
For example, suppose we want to limit the number of `Customers` maintained in memory for a period of time (measured in
@@ -521,7 +527,6 @@ class Customer {
@Indexed
private String name;
...
}
----
@@ -535,10 +540,10 @@ with `@EnableExpiration`:
----
@SpringBootApplication
@EnableExpiration
class SpringBootApacheGeodeApplication { ... }
class SpringBootApacheGeodeApplication { }
----
NOTE: Technically, this entity class specific Annotation-based Expiration policy is implemented using Apache Geode's
NOTE: Technically, this entity class specific Annotation-based Expiration policy is implemented using {geode-name}'s
{apache-geode-javadoc}/org/apache/geode/cache/CustomExpiry.html[`CustomExpiry`] interface.
TIP: Refer to the SDG Reference Guide for more details on
@@ -551,23 +556,22 @@ TIP: Refer to the SDG Reference Guide for more details on
_Software Testing_ in general, and _Unit Testing_ in particular, are a very important development tasks to ensure
the quality of your Spring Boot applications.
Apache Geode and Pivotal GemFire can make testing difficult in some cases, especially when tests have to be written as
_Integration Tests_ in order to assert the correct behavior. This can be very costly and lengthens the feedback cycle.
Fortunately, it is possible to write _Unit Tests_ as well!
{geode-name} can make testing difficult in some cases, especially when tests have to be written as _Integration Tests_
in order to assert the correct behavior. This can be very costly and lengthens the feedback cycle. Fortunately, it is
possible to write _Unit Tests_ as well!
Spring has your back and once again provides a framework for testing Spring Boot applications using either Apache Geode
or Pivotal GemFire. This is where the {spring-test-data-gemfire-website}[Spring Test for Apache Geode & Pivotal GemFire (STDG)] project
can help, particularly with _Unit Testing_.
Spring has your back and once again provides a framework for testing Spring Boot applications using {geode-name}. This
is where the {spring-test-data-gemfire-website}[Spring Test for {geode-name} (STDG)] project can help, particularly with
_Unit Testing_.
For example, if you do not care what Apache Geode or Pivotal GemFire would actually do in certain cases and only care
about the "contract", which is what mocking a collaborator is all about, then you could effectively mock Apache Geode
or Pivotal GemFire's objects in order to isolate the "_Subject Under Test_" (SUT) and focus on the interaction(s)
or outcomes you expect to happen.
For example, if you do not care what {geode-name} would actually do in certain cases and only care about the "contract",
which is what mocking a collaborator is all about, then you could effectively mock {geode-name} objects in order to
isolate the "_Subject Under Test_" (SUT) and focus on the interaction(s) or outcomes you expect to happen.
With STDG, you don't have to change a bit of configuration to enable mocks in the _Unit Tests_ for your Spring Boot
applications. You simply only need to annotate the test class with `@EnableGemFireMockObjects`, like so:
.Using Mock Apache Geode or Pivotal GemFire objects
.Using Mock {geode-name} Objects
[source,java]
----
@RunWith(SpringRunner.class)
@@ -576,7 +580,7 @@ class MyApplicationTestClass {
@Test
public void someTestCase() {
...
// ...
}
@Configuration
@@ -586,26 +590,26 @@ class MyApplicationTestClass {
}
----
Your Spring Boot configuration of Apache Geode will return mock objects for all Apache Geode objects, such as Regions.
Your Spring Boot configuration of {geode-name} will return mock objects for all {geode-name} objects, such as Regions.
Mocking Apache Geode or Pivotal GemFire objects even works for GemFire/Geode objects created from the productivity
annotations discussed in the previous sections above.
Mocking {geode-name} objects even works for objects created from the productivity annotations discussed in the previous
sections above.
For example, given the following Spring Boot, Apache Geode `ClientCache` application class:
For example, given the following Spring Boot, {geode-name} `ClientCache` application class:
.Main `@SpringBootApplication` class under test
[source,java]
----
@SpringBootApplication
@EnableEntityDefinedRegions(basePackageClasses = Customer.class)
class SpringBootApacheGeodeClientCacheApplication { ... }
class SpringBootApacheGeodeClientCacheApplication { }
----
The "_Customers_" Region defined by the `Customer` entity class and created by the `@EnableEntityDefinedRegions`
annotation would be a "mock" Region and not an actual Region. You can still inject the Region in your test as before
and assert interactions on the Region based on your application workflows:
.Using Mock Apache Geode or Pivotal GemFire objects
.Using Mock {geode-name} Objects
[source,java]
----
@RunWith(SpringRunner.class)
@@ -618,17 +622,14 @@ class MyApplicationTestClass {
@Test
public void someTestCase() {
Customer jonDoe = ...;
Customer jonDoe = new Customer(1, "Jon Doe");
// Use the application in some way and test the interaction on the "Customers" Region
assertThat(this.customers).containsValue(jonDoe);
...
// ...
}
...
}
----

46
spring-geode-docs/src/docs/asciidoc/_includes/configuration-externalized.adoc
View File

@@ -1,8 +1,10 @@
[[geode-configuration-externalized]]
== Externalized Configuration
:geode-name: {apache-geode-name}
Like Spring Boot itself (see {spring-boot-docs-html}/boot-features-external-config.html[here]),
Spring Boot for Apache Geode and Pivotal GemFire (SBDG) supports externalized configuration.
Like Spring Boot itself (see {spring-boot-docs-html}/boot-features-external-config.html[here]), Spring Boot
for {geode-name} (SBDG) supports externalized configuration.
By externalized configuration, we mean configuration metadata stored in a Spring Boot
{spring-boot-docs-html}/boot-features-external-config.html#boot-features-external-config-application-property-files[`application.properties` file],
@@ -15,17 +17,16 @@ in properties, {spring-boot-docs-html}/boot-features-external-config.html#boot-f
properties, and so on. What we are particularly interested in, in this section, is
{spring-boot-docs-html}/boot-features-external-config.html#boot-features-external-config-typesafe-configuration-properties[type-safety].
Like Spring Boot, Spring Boot for Apache Geode & Pivotal GemFire provides a hierarchy of classes used to capture
configuration for several Apache Geode or Pivotal GemFire features in an associated `@ConfigurationProperties`
annotated class. Again, the configuration metadata is specified as well-known, documented properties in 1 or more
Spring Boot `application.properties` files.
Like Spring Boot, Spring Boot for {geode-name} provides a hierarchy of classes used to capture configuration for several
{geode-name} features in an associated `@ConfigurationProperties` annotated class. Again, the configuration metadata is
specified as well-known, documented properties in 1 or more Spring Boot `application.properties` files.
For instance, I may have configured my Spring Boot, `ClientCache` application as follows:
.Spring Boot `application.properties` containing Spring Data properties for Apache Geode / Pivotal GemFire
.Spring Boot `application.properties` containing Spring Data properties for {geode-name}
[source,properties]
----
# Spring Boot application.properties used to configure Apache Geode
# Spring Boot application.properties used to configure {geode-name}
spring.data.gemfire.name=MySpringBootApacheGeodeApplication
@@ -46,7 +47,7 @@ spring.data.gemfire.pool.locators=10.105.120.16[11235],boombox[10334]
----
There are many other properties a user may use to externalize the configuration of their Spring Boot,
Apache Geode applications. You may refer to the Spring Data for Apache Geode (SDG) configuration annotations
{geode-name} applications. You may refer to the Spring Data for {geode-name} (SDG) configuration annotations
{spring-data-geode-javadoc}/org/springframework/data/gemfire/config/annotation/package-frame.html[Javadoc]
for specific configuration properties as needed. Specifically, review the "_enabling_" annotation attributes.
@@ -56,10 +57,15 @@ in your Spring Boot applications themselves, perhaps to further inspect or act o
Of course, you can access any property using Spring's {spring-framework-javadoc}/org/springframework/core/env/Environment.html[`Environment`] abstraction,
like so:
.Using the Spring `Enviornment`
.Using the Spring `Environment`
[source,java]
----
boolean copyOnRead = environment.getProperty("spring.data.gemfire.cache.copy-on-read", Boolean.TYPE, false);
@Configuration
class GeodeConfiguration {
void readConfigurationFromEnvironment(Environment environment) {
boolean copyOnRead = environment.getProperty("spring.data.gemfire.cache.copy-on-read", Boolean.TYPE, false);
}
}
----
While using the `Environment` is a nice approach, you might need access to additional properties or want to access
@@ -84,14 +90,12 @@ class MyApplicationComponent {
// do something with `copyOnRead`
}
...
}
----
Given a handle to {spring-boot-data-geode-javadoc}/org/springframework/geode/boot/autoconfigure/configuration/GemFireProperties.html[`GemFireProperties`],
you can access any of the configuration properties used to configure either Apache Geode or Pivotal GemFire in
a Spring context. You simply only need to autowire an instance of `GemFireProperties` into your application component.
you can access any of the configuration properties used to configure {geode-name} in a Spring context. You simply only
need to autowire an instance of `GemFireProperties` into your application component.
A complete reference to the SBDG provided `@ConfigurationProperties` classes and supporting classes is available
{spring-boot-data-geode-javadoc}/org/springframework/geode/boot/autoconfigure/configuration/package-frame.html[here].
@@ -99,19 +103,19 @@ A complete reference to the SBDG provided `@ConfigurationProperties` classes and
[[geode-configuration-externalized-session]]
=== Externalized Configuration of Spring Session
The same capability applies to accessing the externalized configuration of Spring Session when using either
Apache Geode or Pivotal GemFire as your (HTTP) Session state caching provider.
The same capability applies to accessing the externalized configuration of Spring Session when using {geode-name} as
your (HTTP) Session state caching provider.
In this case, you simply only need to acquire a reference to an instance of the
{spring-boot-data-geode-javadoc}/org/springframework/geode/boot/autoconfigure/configuration/SpringSessionProperties.html[`SpringSessionProperties`]
class.
As before, you would specify Spring Session for Apache Geode (SSDG) properties as follows:
As before, you would specify Spring Session for {geode-name} (SSDG) properties as follows:
.Spring Boot `application.properties` for Spring Session using Apache Geode as the (HTTP) Session state caching provider
.Spring Boot `application.properties` for Spring Session using {geode-name} as the (HTTP) Session state caching provider
[source,properties]
----
# Spring Boot application.properties used to configure Apache Geode as a Session state caching provider in Spring Session
# Spring Boot application.properties used to configure {geode-name} as a Session state caching provider in Spring Session
spring.session.data.gemfire.session.expiration.max-inactive-interval-seconds=300
spring.session.data.gemfire.session.region.name=UserSessions
@@ -135,7 +139,5 @@ class MyApplicationComponent {
// do something with `sessionRegionName`
}
...
}
----

49
spring-geode-docs/src/docs/asciidoc/_includes/configuration-properties.adoc
View File

@@ -1,12 +1,14 @@
[[geode-configuration-metadata]]
== Configuration Metadata Reference
:geode-name: {apache-geode-name}
The following 2 reference sections cover documented and well-known properties recognized and processed by
_Spring Data for Apache Geode/Pivotal GemFire_ (SDG) as well as _Spring Session for Apache Geode/Pivotal GemFire_ (SSDG).
_Spring Data for {geode-name}_ (SDG) as well as _Spring Session for {geode-name}_ (SSDG).
These properties may be used in Spring Boot `application.properties` files, or as JVM System properties, to configure
different aspects of or enable individual features of Apache Geode or Pivotal GemFire in a Spring application.
When combined with the power of Spring Boot, magical things begin to happen.
different aspects of or enable individual features of {geode-name} in a Spring application. When combined with the power
of Spring Boot, magical things begin to happen.
[[geode-configuration-metadata-springdata]]
=== Spring Data Based Properties
@@ -20,9 +22,9 @@ property, use `spring.data.gemfire.cache.copy-on-read` in Spring Boot `applicati
|=====================================================================================================================
| Name | Description | Default | From
| name | Name of the Apache Geode / Pivotal GemFire member. | SpringBasedCacheClientApplication | {spring-data-geode-javadoc}/org/springframework/data/gemfire/config/annotation/ClientCacheApplication.html#name--[ClientCacheApplication.name]
| name | Name of the {geode-name}. | SpringBasedCacheClientApplication | {spring-data-geode-javadoc}/org/springframework/data/gemfire/config/annotation/ClientCacheApplication.html#name--[ClientCacheApplication.name]
| locators | Comma-delimited list of Locator endpoints formatted as: locator1[port1],...,locatorN[portN]. | [] | {spring-data-geode-javadoc}/org/springframework/data/gemfire/config/annotation/PeerCacheApplication.html#locators--[PeerCacheApplication.locators]
| use-bean-factory-locator | Enable the SDG BeanFactoryLocator when mixing Spring config with GemFire/Geode native config (e.g. cache.xml) and you wish to configure GemFire objects declared in cache.xml with Spring. | false | {spring-data-geode-javadoc}/org/springframework/data/gemfire/config/annotation/ClientCacheApplication.html#useBeanFactoryLocator--[ClientCacheApplication.useBeanFactoryLocator]
| use-bean-factory-locator | Enable the SDG BeanFactoryLocator when mixing Spring config with {geode-name} native config (e.g. cache.xml) and you wish to configure {geode-name} objects declared in `cache.xml` with Spring. | false | {spring-data-geode-javadoc}/org/springframework/data/gemfire/config/annotation/ClientCacheApplication.html#useBeanFactoryLocator--[ClientCacheApplication.useBeanFactoryLocator]
|=====================================================================================================================
@@ -35,14 +37,14 @@ property, use `spring.data.gemfire.cache.copy-on-read` in Spring Boot `applicati
| cache.copy-on-read | Configure whether a copy of an object returned from Region.get(key) is made. | false | {spring-data-geode-javadoc}/org/springframework/data/gemfire/config/annotation/ClientCacheApplication.html#copyOnRead--[ClientCacheApplication.copyOnRead]
| cache.critical-heap-percentage | Percentage of heap at or above which the cache is considered in danger of becoming inoperable. | | {spring-data-geode-javadoc}/org/springframework/data/gemfire/config/annotation/ClientCacheApplication.html#criticalHeapPercentage--[ClientCacheApplication.criticalHeapPercentage]
| cache.critical-off-heap-percentage | Percentage of off-heap at or above which the cache is considered in danger of becoming inoperable. | | {spring-data-geode-javadoc}/org/springframework/data/gemfire/config/annotation/ClientCacheApplication.html#criticalOffHeapPercentage--[ClientCacheApplication.criticalOffHeapPercentage]
| cache.enable-auto-region-lookup | Configure whether to lookup Regions configured in GemFire/Geode native config and declare them as Spring beans. | false | {spring-data-geode-javadoc}/org/springframework/data/gemfire/config/annotation/EnableAutoRegionLookup.html#enabled--[EnableAutoRegionLookup.enable]
| cache.enable-auto-region-lookup | Configure whether to lookup Regions configured in {geode-name} native config and declare them as Spring beans. | false | {spring-data-geode-javadoc}/org/springframework/data/gemfire/config/annotation/EnableAutoRegionLookup.html#enabled--[EnableAutoRegionLookup.enable]
| cache.eviction-heap-percentage | Percentage of heap at or above which the eviction should begin on Regions configured for HeapLRU eviction. | | {spring-data-geode-javadoc}/org/springframework/data/gemfire/config/annotation/ClientCacheApplication.html#evictionHeapPercentage--[ClientCacheApplication.evictionHeapPercentage]
| cache.eviction-off-heap-percentage | Percentage of off-heap at or above which the eviction should begin on Regions configured for HeapLRU eviction. | | {spring-data-geode-javadoc}/org/springframework/data/gemfire/config/annotation/ClientCacheApplication.html#evictionOffHeapPercentage--[ClientCacheApplication.evictionOffHeapPercentage]
| cache.log-level | Configure the log-level of an Apache Geode / Pivotal GemFire cache. | config | {spring-data-geode-javadoc}/org/springframework/data/gemfire/config/annotation/ClientCacheApplication.html#logLevel--[ClientCacheApplication.logLevel]
| cache.log-level | Configure the log-level of an {geode-name} cache. | config | {spring-data-geode-javadoc}/org/springframework/data/gemfire/config/annotation/ClientCacheApplication.html#logLevel--[ClientCacheApplication.logLevel]
| cache.name | Alias for 'spring.data.gemfire.name'. | SpringBasedCacheClientApplication | {spring-data-geode-javadoc}/org/springframework/data/gemfire/config/annotation/ClientCacheApplication.html#name--[ClientCacheApplication.name]
| cache.compression.bean-name | Name of a Spring bean implementing org.apache.geode.compression.Compressor. | | {spring-data-geode-javadoc}/org/springframework/data/gemfire/config/annotation/EnableCompression.html#compressorBeanName--[EnableCompression.compressorBeanName]
| cache.compression.region-names | Comma-delimited list of Region names for which compression will be configured. | [] | {spring-data-geode-javadoc}/org/springframework/data/gemfire/config/annotation/EnableCompression.html#regionNames--[EnableCompression.regionNames]
| cache.off-heap.memory-size | Determines the size of off-heap memory used by GemFire/Geode in megabytes (m) or gigabytes (g); for example 120g. | | {spring-data-geode-javadoc}/org/springframework/data/gemfire/config/annotation/EnableOffHeap.html#memorySize--[EnableOffHeap.memorySize]
| cache.off-heap.memory-size | Determines the size of off-heap memory used by {geode-name} in megabytes (m) or gigabytes (g); for example 120g. | | {spring-data-geode-javadoc}/org/springframework/data/gemfire/config/annotation/EnableOffHeap.html#memorySize--[EnableOffHeap.memorySize]
| cache.off-heap.region-names | Comma-delimited list of Region names for which off-heap will be configured. | [] | {spring-data-geode-javadoc}/org/springframework/data/gemfire/config/annotation/EnableOffHeap.html#regionNames--[EnableOffHeap.regionNames]
|=====================================================================================================================
@@ -70,7 +72,7 @@ property, use `spring.data.gemfire.cache.copy-on-read` in Spring Boot `applicati
| cache.peer.lock-timeout | Configures the number of seconds a cache operation will wait to obtain a distributed lock lease. | 60 | {spring-data-geode-javadoc}/org/springframework/data/gemfire/config/annotation/PeerCacheApplication.html#lockTimeout--[PeerCacheApplication.lockTimeout]
| cache.peer.message-sync-interval | Configures the frequency (in seconds) at which a message will be sent by the primary cache-server to all the secondary cache-server nodes to remove the events which have already been dispatched from the queue. | 1 | {spring-data-geode-javadoc}/org/springframework/data/gemfire/config/annotation/PeerCacheApplication.html#messageSyncInterval--[PeerCacheApplication.messageSyncInterval]
| cache.peer.search-timeout | Configures the number of seconds a cache get operation can spend searching for a value. | 300 | {spring-data-geode-javadoc}/org/springframework/data/gemfire/config/annotation/PeerCacheApplication.html#searchTimeout--[PeerCacheApplication.searchTimeout]
| cache.peer.use-cluster-configuration | Configures whether this GemFire cache member node would pull it's configuration meta-data from the cluster-based Cluster Configuration Service. | false | {spring-data-geode-javadoc}/org/springframework/data/gemfire/config/annotation/PeerCacheApplication.html#useClusterConfiguration--[PeerCacheApplication.useClusterConfiguration]
| cache.peer.use-cluster-configuration | Configures whether this cache member node would pull it's configuration meta-data from the cluster-based Cluster Configuration Service. | false | {spring-data-geode-javadoc}/org/springframework/data/gemfire/config/annotation/PeerCacheApplication.html#useClusterConfiguration--[PeerCacheApplication.useClusterConfiguration]
|=====================================================================================================================
@@ -125,7 +127,7 @@ spring.data.gemfire.cache.server.[<cacheServerBeanName>].bind-address=...
| disk.store.allow-force-compaction | Configures whether to allow DiskStore.forceCompaction() to be called on Regions using a DiskStore. | false | {spring-data-geode-javadoc}/org/springframework/data/gemfire/config/annotation/EnableDiskStore.html#allowForceCompaction--[EnableDiskStore.allowForceCompaction]
| disk.store.auto-compact | Configures whether to cause the disk files to be automatically compacted. | true | {spring-data-geode-javadoc}/org/springframework/data/gemfire/config/annotation/EnableDiskStore.html#autoCompact--[EnableDiskStore.autoCompact]
| disk.store.compaction-threshold | Configures the threshold at which an oplog will become compactable. | 50 | {spring-data-geode-javadoc}/org/springframework/data/gemfire/config/annotation/EnableDiskStore.html#compactionThreshold--[EnableDiskStore.compactionThreshold]
| disk.store.directory.location | Configures the system directory where the GemFire/Geode DiskStore (oplog) files will be stored. | [] | {spring-data-geode-javadoc}/org/springframework/data/gemfire/config/annotation/EnableDiskStore.html#diskDirectories--[EnableDiskStore.diskDirectories.location]
| disk.store.directory.location | Configures the system directory where the `DiskStore` (oplog) files will be stored. | [] | {spring-data-geode-javadoc}/org/springframework/data/gemfire/config/annotation/EnableDiskStore.html#diskDirectories--[EnableDiskStore.diskDirectories.location]
| disk.store.directory.size | Configures the amount of disk space allowed to store DiskStore (oplog) files. | 21474883647 | {spring-data-geode-javadoc}/org/springframework/data/gemfire/config/annotation/EnableDiskStore.html#diskDirectories--[EnableDiskStore.diskDirectories.size]
| disk.store.disk-usage-critical-percentage | Configures the critical threshold for disk usage as a percentage of the total disk volume. | 99.0 | {spring-data-geode-javadoc}/org/springframework/data/gemfire/config/annotation/EnableDiskStore.html#diskUsageCriticalPercentage--[EnableDiskStore.diskUsageCriticalPercentage]
| disk.store.disk-usage-warning-percentage | Configures the warning threshold for disk usage as a percentage of the total disk volume. | 90.0 | {spring-data-geode-javadoc}/org/springframework/data/gemfire/config/annotation/EnableDiskStore.html#diskUsageWarningPercentage--[EnableDiskStore.diskUsageWarningPercentage]
@@ -188,7 +190,7 @@ specified location and limited to the defined size.
|=====================================================================================================================
| Name | Description | Default | From
| logging.level | Configures the log-level of an Apache Geode / Pivotal GemFire cache; Alias for 'spring.data.gemfire.cache.log-level'. | config | {spring-data-geode-javadoc}/org/springframework/data/gemfire/config/annotation/EnableLogging.html#logLevel--[EnableLogging.logLevel]
| logging.level | Configures the log-level of an {geode-name} cache; Alias for 'spring.data.gemfire.cache.log-level'. | config | {spring-data-geode-javadoc}/org/springframework/data/gemfire/config/annotation/EnableLogging.html#logLevel--[EnableLogging.logLevel]
| logging.log-disk-space-limit | Configures the amount of disk space allowed to store log files. | | {spring-data-geode-javadoc}/org/springframework/data/gemfire/config/annotation/EnableLogging.html#logDiskSpaceLimit--[EnableLogging.logDiskSpaceLimit]
| logging.log-file | Configures the pathname of the log file used to log messages. | | {spring-data-geode-javadoc}/org/springframework/data/gemfire/config/annotation/EnableLogging.html#logFile--[EnableLogging.logFile]
| logging.log-file-size | Configures the maximum size of a log file before the log file is rolled. | | {spring-data-geode-javadoc}/org/springframework/data/gemfire/config/annotation/EnableLogging.html#logFileSizeLimit--[EnableLogging.logFileSize]
@@ -201,9 +203,9 @@ specified location and limited to the defined size.
|=====================================================================================================================
| Name | Description | Default | From
| management.use-http | Configures whether to use the HTTP protocol to communicate with a GemFire/Geode Manager. | false | {spring-data-geode-javadoc}/org/springframework/data/gemfire/config/annotation/EnableClusterConfiguration.html#useHttp--[EnableClusterConfiguration.useHttp]
| management.http.host | Configures the IP address or hostname of the GemFire/Geode Manager running the HTTP service. | | {spring-data-geode-javadoc}/org/springframework/data/gemfire/config/annotation/EnableClusterConfiguration.html#host--[EnableClusterConfiguration.host]
| management.http.port | Configures the port used by the GemFire/Geode Manager's HTTP service to listen for connections. | 7070 | {spring-data-geode-javadoc}/org/springframework/data/gemfire/config/annotation/EnableClusterConfiguration.html#port--[EnableClusterConfiguration.port]
| management.use-http | Configures whether to use the HTTP protocol to communicate with a {geode-name} Manager. | false | {spring-data-geode-javadoc}/org/springframework/data/gemfire/config/annotation/EnableClusterConfiguration.html#useHttp--[EnableClusterConfiguration.useHttp]
| management.http.host | Configures the IP address or hostname of the {geode-name} Manager running the HTTP service. | | {spring-data-geode-javadoc}/org/springframework/data/gemfire/config/annotation/EnableClusterConfiguration.html#host--[EnableClusterConfiguration.host]
| management.http.port | Configures the port used by the {geode-name} Manager's HTTP service to listen for connections. | 7070 | {spring-data-geode-javadoc}/org/springframework/data/gemfire/config/annotation/EnableClusterConfiguration.html#port--[EnableClusterConfiguration.port]
|=====================================================================================================================
@@ -288,7 +290,7 @@ specified location and limited to the defined size.
| security.peer.authenticator | Static creation method returning an Authenticator object, which is used by a peer to verify the credentials of a connecting node. | | {spring-data-geode-javadoc}/org/springframework/data/gemfire/config/annotation/EnableAuth.html#peerAuthenticator--[EnableAuth.peerAuthenticator]
| security.peer.verify-member-timeout | Configures the timeout in milliseconds used by a peer to verify membership of an unknown authenticated peer requesting a secure connection. | | {spring-data-geode-javadoc}/org/springframework/data/gemfire/config/annotation/EnableAuth.html#peerVerifyMemberTimeout--[EnableAuth.peerVerifyMemberTimeout]
| security.post-processor.class-name | Configures the name of a class implementing the org.apache.geode.security.PostProcessor interface that can be used to change the returned results of Region get operations. | | {spring-data-geode-javadoc}/org/springframework/data/gemfire/config/annotation/EnableSecurity.html#securityPostProcessorClassName--[EnableSecurity.securityPostProcessorClassName]
| security.shiro.ini-resource-path | Configures the Apache Geode System Property referring to the location of an Apache Shiro INI file that configures the Apache Shiro Security Framework in order to secure Apache Geode. | | {spring-data-geode-javadoc}/org/springframework/data/gemfire/config/annotation/EnableSecurity.html#shiroIniResourcePath--[EnableSecurity.shiroIniResourcePath]
| security.shiro.ini-resource-path | Configures the {geode-name} System Property referring to the location of an Apache Shiro INI file that configures the Apache Shiro Security Framework in order to secure {geode-name}. | | {spring-data-geode-javadoc}/org/springframework/data/gemfire/config/annotation/EnableSecurity.html#shiroIniResourcePath--[EnableSecurity.shiroIniResourcePath]
|=====================================================================================================================
@@ -299,14 +301,14 @@ specified location and limited to the defined size.
| Name | Description | Default | From
| security.ssl.certificate.alias.cluster | Configures the alias to the stored SSL certificate used by the cluster to secure communications. | | {spring-data-geode-javadoc}/org/springframework/data/gemfire/config/annotation/EnableSsl.html#componentCertificateAliases--[EnableSsl.componentCertificateAliases]
| security.ssl.certificate.alias.default-alias | Configures the default alias to the stored SSL certificate used to secure communications across the entire GemFire/Geode system. | | {spring-data-geode-javadoc}/org/springframework/data/gemfire/config/annotation/EnableSsl.html#defaultCertificateAlias--[EnableSsl.defaultCertificateAlias]
| security.ssl.certificate.alias.default-alias | Configures the default alias to the stored SSL certificate used to secure communications across the entire {geode-name} system. | | {spring-data-geode-javadoc}/org/springframework/data/gemfire/config/annotation/EnableSsl.html#defaultCertificateAlias--[EnableSsl.defaultCertificateAlias]
| security.ssl.certificate.alias.gateway | Configures the alias to the stored SSL certificate used by the WAN Gateway Senders/Receivers to secure communications. | | {spring-data-geode-javadoc}/org/springframework/data/gemfire/config/annotation/EnableSsl.html#componentCertificateAliases--[EnableSsl.componentCertificateAliases]
| security.ssl.certificate.alias.jmx | Configures the alias to the stored SSL certificate used by the Manager's JMX based JVM MBeanServer and JMX clients to secure communications. | | {spring-data-geode-javadoc}/org/springframework/data/gemfire/config/annotation/EnableSsl.html#componentCertificateAliases--[EnableSsl.componentCertificateAliases]
| security.ssl.certificate.alias.locator | Configures the alias to the stored SSL certificate used by the Locator to secure communications. | | {spring-data-geode-javadoc}/org/springframework/data/gemfire/config/annotation/EnableSsl.html#componentCertificateAliases--[EnableSsl.componentCertificateAliases]
| security.ssl.certificate.alias.server | Configures the alias to the stored SSL certificate used by clients and servers to secure communications. | | {spring-data-geode-javadoc}/org/springframework/data/gemfire/config/annotation/EnableSsl.html#componentCertificateAliases--[EnableSsl.componentCertificateAliases]
| security.ssl.certificate.alias.web | Configures the alias to the stored SSL certificate used by the embedded HTTP server to secure communications (HTTPS). | | {spring-data-geode-javadoc}/org/springframework/data/gemfire/config/annotation/EnableSsl.html#componentCertificateAliases--[EnableSsl.componentCertificateAliases]
| security.ssl.ciphers | Comma-separated list of SSL ciphers or “any”. | | {spring-data-geode-javadoc}/org/springframework/data/gemfire/config/annotation/EnableSsl.html#ciphers--[EnableSsl.ciphers]
| security.ssl.components | Comma-delimited list of GemFire/Geode components (e.g. WAN) to be configured for SSL communication. | | {spring-data-geode-javadoc}/org/springframework/data/gemfire/config/annotation/EnableSsl.html#components--[EnableSsl.components]
| security.ssl.components | Comma-delimited list of {geode-name} components (e.g. WAN) to be configured for SSL communication. | | {spring-data-geode-javadoc}/org/springframework/data/gemfire/config/annotation/EnableSsl.html#components--[EnableSsl.components]
| security.ssl.keystore | Configures the system pathname to the Java KeyStore file storing certificates for SSL. | | {spring-data-geode-javadoc}/org/springframework/data/gemfire/config/annotation/EnableSsl.html#keystore--[EnableSsl.keystore]
| security.ssl.keystore.password | Configures the password used to access the Java KeyStore file. | | {spring-data-geode-javadoc}/org/springframework/data/gemfire/config/annotation/EnableSsl.html#keystorePassword--[EnableSsl.keystorePassword]
| security.ssl.keystore.type | Configures the password used to access the Java KeyStore file (e.g. JKS). | | {spring-data-geode-javadoc}/org/springframework/data/gemfire/config/annotation/EnableSsl.html#keystoreType--[EnableSsl.keystoreType]
@@ -328,7 +330,7 @@ specified location and limited to the defined size.
| service.http.bind-address | Configures the IP address or hostname of the system NIC used by the embedded HTTP server to bind and listen for HTTP(S) connections. | | {spring-data-geode-javadoc}/org/springframework/data/gemfire/config/annotation/EnableHttpService.html#bindAddress--[EnableHttpService.bindAddress]
| service.http.port | Configures the port used by the embedded HTTP server to listen for HTTP(S) connections. | 7070 | {spring-data-geode-javadoc}/org/springframework/data/gemfire/config/annotation/EnableHttpService.html#port--[EnableHttpService.port]
| service.http.ssl-require-authentication | Configures whether 2-way HTTP authentication is required. | false | {spring-data-geode-javadoc}/org/springframework/data/gemfire/config/annotation/EnableHttpService.html#sslRequireAuthentication--[EnableHttpService.sslRequireAuthentication]
| service.http.dev-rest-api-start | Configures whether to start the Developer REST API web service. A full installation of Apache Geode or Pivotal GemFire is required and you must set the $GEODE environment variable. | false | {spring-data-geode-javadoc}/org/springframework/data/gemfire/config/annotation/EnableHttpService.html#startDeveloperRestApi--[EnableHttpService.startDeveloperRestApi]
| service.http.dev-rest-api-start | Configures whether to start the Developer REST API web service. A full installation of {geode-name} is required and you must set the $GEODE environment variable. | false | {spring-data-geode-javadoc}/org/springframework/data/gemfire/config/annotation/EnableHttpService.html#startDeveloperRestApi--[EnableHttpService.startDeveloperRestApi]
| service.memcached.port | Configures the port of the embedded Memcached server (service). | 11211| {spring-data-geode-javadoc}/org/springframework/data/gemfire/config/annotation/EnableMemcachedServer.html#port--[EnableMemcachedServer.port]
| service.memcached.protocol | Configures the protocol used by the embedded Memcached server (service). | ASCII | {spring-data-geode-javadoc}/org/springframework/data/gemfire/config/annotation/EnableMemcachedServer.html#protocol--[EnableMemcachedServer.protocol]
| service.redis.bind-address | Configures the IP address or hostname of the system NIC used by the embedded Redis server to bind an listen for connections. | | {spring-data-geode-javadoc}/org/springframework/data/gemfire/config/annotation/EnableRedisServer.html#bindAddress--[EnableRedis.bindAddress]
@@ -360,12 +362,11 @@ name, use `spring.session.data.gemfire.session.region.name` in Spring Boot `appl
|=====================================================================================================================
[[geode-configuration-metadata-apachegeode]]
=== Apache Geode Properties
=== {geode-name} Properties
While it is not recommended to use Apache Geode properties directly in your Spring applications, SBDG will not prevent
you from doing so. A complete reference to the Apache Geode specific properties can be found
While it is not recommended to use {geode-name} properties directly in your Spring applications, SBDG will not prevent
you from doing so. A complete reference to the {geode-name} specific properties can be found
{apache-geode-docs}/reference/topics/gemfire_properties.html[here].
WARNING: Apache Geode (and Pivotal GemFire) are very strict about the properties that maybe specified in
a `gemfire.properties` file. You cannot mix Spring properties with `gemfire.*` properties in an Apache Geode
or Pivotal GemFire, `gemfire.properties` file.
WARNING: {geode-name} is very strict about the properties that maybe specified in a `gemfire.properties` file. You
cannot mix Spring properties with `gemfire.*` properties in an {geode-name} `gemfire.properties` file.

28
spring-geode-docs/src/docs/asciidoc/_includes/continuous-query.adoc
View File

@@ -1,25 +1,26 @@
[[geode-continuous-query]]
== Continuous Query
:geode-name: {apache-geode-name}
Arguably, the most invaluable of applications are those that can process a stream of events as they happen,
and intelligently react in near real-time to the countless changes in the data over time. The most useful
of frameworks are those that can make processing a stream of events as they happen, as easy as possible.
Spring Boot for Apache Geode & Pivotal GemFire does just that, without users having to perform any complex setup
or configure any necessary infrastructure components to enable such functionality. Developers can simply define
the criteria for the data they are interested in and implement a handler to process the stream of events
as they occur.
Spring Boot for {geode-name} does just that, without users having to perform any complex setup or configure any
necessary infrastructure components to enable such functionality. Developers can simply define the criteria for the
data they are interested in and implement a handler to process the stream of events as they occur.
Apache Geode & Pivotal GemFire make defining criteria for data of interests easy when using
{geode-name} make defining criteria for data of interests easy when using
{apache-geode-docs}/developing/continuous_querying/chapter_overview.html[Continuous Query (CQ)]. With CQ, you can
express the criteria matching the data of interests using a query predicate. Apache Geode & Pivotal GemFire implements
express the criteria matching the data of interests using a query predicate. {geode-name} implements
the {apache-geode-docs}/developing/querying_basics/query_basics.html[Object Query Language (OQL)] for defining
and executing queries. OQL is not unlike SQL, and supports projections, query predicates, ordering and aggregates.
And, when used in CQs, they execute continuously, firing events when the data changes in such ways as to match
the criteria expressed in the query predicate.
Spring Boot for Apache Geode/Pivotal GemFire combines the ease of expressing interests in data using an OQL
query statement with implementing the listener handler callback, in 1 easy step.
Spring Boot for {geode-name} combines the ease of expressing interests in data using an OQL query statement with
implementing the listener handler callback, in 1 easy step.
For example, suppose we want to perform some follow up action anytime a customer's financial loan application
is either approved or denied.
@@ -38,8 +39,6 @@ class EligibilityDecision {
private final Timespan timespan;
...
enum Status {
APPROVED,
@@ -64,7 +63,7 @@ class EligibilityDecisionPostProcessor {
FROM /EligibilityDecisions decisions
WHERE decisions.getStatus().name().equalsIgnoreCase('APPROVED')")
public void processApprovedDecisions(CqEvent event) {
...
// ...
}
@ContinuousQuery(name = "DeniedDecisionsHandler",
@@ -72,7 +71,7 @@ class EligibilityDecisionPostProcessor {
FROM /EligibilityDecisions decisions
WHERE decisions.getStatus().name().equalsIgnoreCase('DENIED')")
public void processDeniedDecisions(CqEvent event) {
...
// ...
}
}
----
@@ -83,6 +82,5 @@ anyway you like. And, because our Continuous Query handler class is a component
`ApplicationContext`, you can auto-wire any other beans necessary to carry out the application's intended function.
This is not unlike Spring's {spring-framework-docs}/integration.html#jms-annotated[Annotation-driven listener endpoints]
used in (JMS) message listeners/handlers, except in Spring Boot for Apache Geode/Pivotal GemFire, you do not need to do
anything special to enable this functionality. Just declare the `@ContinuousQuery` annotation on any POJO method
and off you go.
used in (JMS) message listeners/handlers, except in Spring Boot for {geode-name}, you do not need to do anything special
to enable this functionality. Just declare the `@ContinuousQuery` annotation on any POJO method and off you go.

50
spring-geode-docs/src/docs/asciidoc/_includes/data-serialization.adoc
View File

@@ -1,27 +1,29 @@
[[geode-data-serialization]]
== Data Serialization with PDX
:geode-name: {apache-geode-name}
Anytime data is overflowed or persisted to disk, transferred between clients and servers, peers in a cluster or between
different clusters in a multi-site topology, then all data stored in Apache Geode/Pivotal GemFire must be serializable.
different clusters in a multi-site topology, then all data stored in {geode-name} must be serializable.
To serialize objects in Java, object types must implement the `java.io.Serializable` interface. However, if you have
a large number of application domain object types that currently do not implement `java.io.Serializable`, then
refactoring hundreds or even thousands of class types to implement `Serializable` would be a tedious task just to
store and manage those objects in Apache Geode or Pivotal GemFire.
store and manage those objects in {geode-name}.
Additionally, it is not just your application domain object types you necessarily need to worry about either. If you
used 3rd party libraries in your application domain model, any types referred to by your application domain object types
stored in Apache Geode or Pivotal GemFire must be serializable too. This type explosion may bleed into class types
for which you may have no control over.
stored in {geode-name} must be serializable too. This type explosion may bleed into class types for which you may have
no control over.
Furthermore, Java serialization is not the most efficient format given that meta-data about your types is stored with
the data itself. Therefore, even though Java serialized bytes are more descriptive, it adds a great deal of overhead.
Then, along came serialization using Apache Geode or Pivotal GemFire's {apache-geode-docs}/developing/data_serialization/gemfire_pdx_serialization.html[PDX]
Then, along came serialization using {geode-name}'s {apache-geode-docs}/developing/data_serialization/gemfire_pdx_serialization.html[PDX]
format. PDX stands for _Portable Data Exchange_, and achieves 4 goals:
1. Separates type meta-data from the data itself making the bytes more efficient during transfer. Apache Geode
and Pivotal GemFire maintain a type registry storing type meta-data about the objects serialized using PDX.
1. Separates type meta-data from the data itself making the bytes more efficient during transfer. {geode-name} maintains
a type registry storing type meta-data about the objects serialized using PDX.
2. Supports versioning as your application domain types evolve. It is not uncommon to have old and new applications
deployed to production, running simultaneously, sharing data, and possibly using different versions of the same domain
@@ -44,43 +46,43 @@ how you structure and design your application domain object types.
Also, PDX cannot handle field type changes.
Furthermore, while GemFire/Geode's general {apache-geode-docs}/developing/data_serialization/gemfire_data_serialization.html[Data Serialization]
Furthermore, while {geode-name}'s general {apache-geode-docs}/developing/data_serialization/gemfire_data_serialization.html[Data Serialization]
handles {apache-geode-docs}/developing/delta_propagation/chapter_overview.html[deltas], this is not achievable without
de-serializing the object bytes since it involves a method invocation, which defeats 1 of the key benefits of PDX,
preserving format to avoid the cost of de/serialization.
However, we think the benefits of using PDX greatly outweigh the limitations and therefore have enabled PDX by default
when using Spring Boot for Apache Geode/Pivotal GemFire.
when using Spring Boot for {geode-name}.
There is nothing special you need to do. Simply code your types and rest assured that objects of those types will be
properly serialized when overflowed/persisted to disk, transferred between clients and servers, or peers in a cluster
and even when data is transferred over the WAN when using GemFire/Geode's multi-site topology.
and even when data is transferred over the WAN when using {geode-name}'s multi-site topology.
.EligibilityDecision is automatically serialiable without implementing Java Serializable.
[source,java]
----
@Region("EligibilityDecisions")
class EligibilityDecision {
...
// ...
}
----
TIP: Apache Geode/Pivotal GemFire does {apache-geode-docs}/developing/data_serialization/java_serialization.html[support]
the standard Java Serialization format.
TIP: {geode-name} does {apache-geode-docs}/developing/data_serialization/java_serialization.html[support] the standard
Java Serialization format.
=== SDG `MappingPdxSerializer` vs. GemFire/Geode's `ReflectionBasedAutoSerializer`
=== SDG `MappingPdxSerializer` vs. {geode-name}'s `ReflectionBasedAutoSerializer`
Under-the-hood, Spring Boot for Apache Geode/Pivotal GemFire {spring-data-geode-docs-html}/#bootstrap-annotation-config-pdx[enables]
and uses Spring Data for Apache Geode/Pivotal GemFire's {spring-data-geode-javadoc}/org/springframework/data/gemfire/mapping/MappingPdxSerializer.html[MappingPdxSerializer]
Under-the-hood, Spring Boot for {geode-name} {spring-data-geode-docs-html}/#bootstrap-annotation-config-pdx[enables]
and uses Spring Data for {geode-name}'s {spring-data-geode-javadoc}/org/springframework/data/gemfire/mapping/MappingPdxSerializer.html[MappingPdxSerializer]
to serialize your application domain objects using PDX.
TIP: Refer to the SDG {spring-data-geode-docs-html}/#mapping.pdx-serializer[Reference Guide] for more details
on the `MappingPdxSerializer` class.
The `MappingPdxSerializer` offers several advantages above and beyond GemFire/Geode's own
The `MappingPdxSerializer` offers several advantages above and beyond {geode-name}'s own
{apache-geode-javadoc}/org/apache/geode/pdx/ReflectionBasedAutoSerializer.html[ReflectionBasedAutoSerializer] class.
TIP: Refer to Apache Geode's {apache-geode-docs}/developing/data_serialization/auto_serialization.html[User Guide]
TIP: Refer to {geode-name}'s {apache-geode-docs}/developing/data_serialization/auto_serialization.html[User Guide]
for more details about the `ReflectionBasedAutoSerializer`.
The SDG `MappingPdxSerializer` offers the following capabilities:
@@ -88,9 +90,10 @@ The SDG `MappingPdxSerializer` offers the following capabilities:
1. PDX serialization is based on Spring Data's powerful mapping infrastructure and meta-data, as such...
2. Includes support for both `includes` and `excludes` with {spring-data-geode-docs-html}/#mapping.pdx-serializer.type-filtering[type filtering].
Additionally, type filters can be implemented using Java's `java.util.function.Predicate` interface as opposed to GemFire/Geode's
limited regex capabilities provided by the `ReflectionBasedAutoSerializer` class. By default, `MappingPdxSerializer`
excludes all types in the following packages: `java`, `org.apache.geode`, `org.springframework` & `com.gemstone.gemfire`.
Additionally, type filters can be implemented using Java's `java.util.function.Predicate` interface as opposed to
{geode-name}'s limited regex capabilities provided by the `ReflectionBasedAutoSerializer` class. By default,
`MappingPdxSerializer` excludes all types in the following packages: `java`, `org.apache.geode`, `org.springframework`
& `com.gemstone.gemfire`.
3. Handles {spring-data-geode-docs-html}/#mapping.pdx-serializer.transient-properties[transient object fields & properties]
when either Java's `transient` keyword or Spring Data's `@Transient` annotation is used.
@@ -103,8 +106,8 @@ with Spring Data's {spring-data-commons-javadoc}/org/springframework/data/annota
6. Allows `o.a.g.pdx.PdxSerializers` to be registered in order to {spring-data-geode-docs-html}/#mapping.pdx-serializer.custom-serialization[customize the serialization]
of nested entity field/property types.
Number two above deserves special attention since the `MappingPdxSerializer` "excludes" all Java, Spring
and Apache Geode/Pivotal GemFire types, by default. But, what happens when you need to serialize 1 of those types?
Number two above deserves special attention since the `MappingPdxSerializer` "excludes" all Java, Spring and {geode-name}
types, by default. But, what happens when you need to serialize 1 of those types?
For example, suppose you need to be able to serialize objects of type `java.security.Principal`. Well, then you can
override the excludes by registering an "include" type filter, like so:
@@ -114,7 +117,6 @@ override the excludes by registering an "include" type filter, like so:
package example.app;
import java.security.Principal;
import ...;
@SpringBootApplication
@EnablePdx(serializerBeanName = "myCustomMappingPdxSerializer")

20
spring-geode-docs/src/docs/asciidoc/_includes/data.adoc
View File

@@ -1,7 +1,7 @@
[[geode-data-using]]
== Using Data
:geode-name: Apache Geode
:gemfire-name: VMware Tanzu GemFire
One of the most important tasks during development is ensuring your Spring Boot application handles data correctly.
In order to verify the accuracy, integrity and availability of your data, your application needs data to work with.
@@ -22,17 +22,17 @@ Alternatively, using {geode-name}'s _Snapshot Service_, you can export data cont
cluster during shutdown and import the data into another cluster on startup. The _Snapshot Service_ allows you to filter
data while its being imported and exported.
Finally, GemFire/Geode Shell (_Gfsh_) commands can be used to {spring-data-geode-docs-html}/tools_modules/gfsh/command-pages/export.html#topic_263B70069BFC4A7185F86B3272011734[export data]
Finally, {geode-name} Shell (_Gfsh_) commands can be used to {spring-data-geode-docs-html}/tools_modules/gfsh/command-pages/export.html#topic_263B70069BFC4A7185F86B3272011734[export data]
and {apache-geode-docs}/tools_modules/gfsh/command-pages/import.html#topic_jw2_2ld_2l[import data].
TIP: Spring Data for Apache Geode (SDG) contains dedicated support for {spring-data-geode-docs-html}/#bootstrap:region:persistence[Persistence]
TIP: Spring Data for {geode-name} (SDG) contains dedicated support for {spring-data-geode-docs-html}/#bootstrap:region:persistence[Persistence]
and the {spring-data-geode-docs-html}/#bootstrap:snapshot[Snapshot Service].
In all cases, the files generated by _persistence_, the _Snapshot Service_ and _Gfsh's_ `export` command are in a
proprietary, binary format.
Furthermore, none of these approaches are as convenient as Spring Boot's database initialization automation. Therefore,
Spring Boot for Apache Geode (SBDG) offers support to import data from JSON into {geode-name} as PDX.
Spring Boot for {geode-name} (SBDG) offers support to import data from JSON into {geode-name} as PDX.
Unlike Spring Boot, SBDG offers support to export data as well. Data is imported and exported in JSON format, by default.
@@ -220,7 +220,7 @@ This follows the same convention used in Spring Data. Typically, Spring Data ma
field or property annotated with {spring-data-commons-javadoc}/org/springframework/data/annotation/Id.html[@Id]. If no
field or property is annotated with `@Id`, then the framework falls back to searching for a field or property named "id".
In Spring Data for Apache Geode (SDG), this `@Id` annotated, or "id" named field or property is used as the identifier,
In Spring Data for {geode-name} (SDG), this `@Id` annotated, or "id" named field or property is used as the identifier,
and as the key for the object when storing it into a `Region`.
However, what happens when an object, or entity does not have a surrogate id defined? Perhaps the application domain
@@ -283,7 +283,7 @@ Here, the `@identifier` JSON metadata field informs the framework that the "isbn
==== Conditionally Importing Data
While the Spring team recommends that users should only use this feature when developing and testing their Spring Boot
applications with Apache Geode, a user may occasionally use this feature in production.
applications with {geode-name}, a user may occasionally use this feature in production.
Users might use this feature in production to preload a (REPLICATE) Region with "reference" data. Reference data is
largely static, infrequently changing and non-transactional. Preloading reference data is particularly useful in caching
@@ -348,11 +348,11 @@ later consumed by your Spring Boot application.
WARNING: It may be necessary to set the `-Dgemfire.disableShutdownHook` JVM System property to `true` before your Spring
Boot application starts up when using Export. Unfortunately, this Java Runtime shutdown hook is registered and enabled
in {geode-name} & {gemfire-name} by default, which results in the cache and _Regions_ being closed before the SBDG
Export functionality can "export the data", thereby resulting in a `CacheClosedException`. SBDG
in {geode-name} by default, which results in the cache and _Regions_ being closed before the SBDG Export functionality
can "export the data", thereby resulting in a `CacheClosedException`. SBDG
{github-url}/spring-geode-autoconfigure/src/main/java/org/springframework/geode/boot/autoconfigure/DataImportExportAutoConfiguration.java#L173-L183[makes a best effort]
to disable the GemFire/Geode shutdown hook when export is enabled, but it is at the mercy of the JVM `ClassLoader` since
GemFire/Geode's JVM shutdown hook
to disable the {geode-name} shutdown hook when export is enabled, but it is at the mercy of the JVM `ClassLoader` since
{geode-name}'s JVM shutdown hook
{apache-geode-src}/geode-core/src/main/java/org/apache/geode/distributed/internal/InternalDistributedSystem.java#L2185-L2223[registration]
is declared in a `static` initializer.

3
spring-geode-docs/src/docs/asciidoc/_includes/docker.adoc
View File

@@ -5,6 +5,7 @@
:geode-name: Apache Geode
:testcontainers-url: https://www.testcontainers.org
The state of modern software application development is moving towards https://www.docker.com/resources/what-container[_containerization_].
Containers offer a controlled environment to predictably build (configure & package), run and manage your applications
in a reliable and repeatable manner regardless of context. The intrinsic benefit of using Containers is a no brainer.
@@ -373,4 +374,4 @@ running in a Docker Container.
Later, we will provide more information on how to scale up, or rather scale out, our {geode-name} cluster running in
Docker. Additionally, we will provide details on how you can use {geode-name}'s Docker Image with **Testcontainers**
when writing _Integration Tests_, which will formally become part of the Spring Test for Apache Geode (STDG) project.
when writing _Integration Tests_, which will formally become part of the Spring Test for {geode-name} (STDG) project.

29
spring-geode-docs/src/docs/asciidoc/_includes/functions.adoc
View File

@@ -1,5 +1,9 @@
[[geode-functions]]
== Function Implementations & Executions
:geode-name: {apache-geode-name}
This chapter is about using {geode-name} in a Spring context for distributed compute use cases.
=== Background
@@ -15,21 +19,20 @@ Additionally, when the computations are handled in parallel, across the cluster
can be performed much faster. This typically involves intelligently organizing the data using various partitioning
(a.k.a. sharding) strategies to uniformly balance the data set across the cluster.
Well, both Apache Geode and Pivotal GemFire address this very important application concern in its
Well, {geode-name} addresses this very important application concern in its
{apache-geode-docs}/developing/function_exec/chapter_overview.html[Function Execution] framework.
Spring Data for Apache Geode/Pivotal GemFire {spring-data-geode-docs-html}/#function-annotations[builds] on
this Function Execution framework by enabling developers to {spring-data-geode-docs-html}/#function-implementation[implement]
and {spring-data-geode-docs-html}/#function-execution[execute] GemFire/Geode Functions using a very simple POJO-based,
Spring Data for {geode-name} {spring-data-geode-docs-html}/#function-annotations[builds] on this Function Execution
framework by enabling developers to {spring-data-geode-docs-html}/#function-implementation[implement]
and {spring-data-geode-docs-html}/#function-execution[execute] {geode-name} Functions using a very simple POJO-based,
annotation configuration model.
TIP: See {spring-data-geode-docs-html}/#_implementation_vs_execution[here] for the difference between
Function implementation & executions.
Taking this 1 step further, Spring Boot for Apache Geode/Pivotal GemFire _auto-configures_ and enables both Function
implementation and execution out-of-the-box. Therefore, you can immediately begin writing Functions and invoking them
without having to worry about all the necessary plumbing to begin with. You can rest assured that it will just work
as expected.
Taking this 1 step further, Spring Boot for {geode-name} _auto-configures_ and enables both Function implementation
and execution out-of-the-box. Therefore, you can immediately begin writing Functions and invoking them without having
to worry about all the necessary plumbing to begin with. You can rest assured that it will just work as expected.
=== Applying Functions
@@ -58,14 +61,14 @@ class EligibilityDeterminationFunction {
@GemfireFunction(HA = true, hasResult = true, optimizeForWrite=true)
public EligibilityDecision determineEligibility(FunctionContext functionContext, Person person, Timespan timespan) {
...
// ...
}
}
----
Using the SDG {spring-data-geode-javadoc}/org/springframework/data/gemfire/function/annotation/GemfireFunction.html[`@GemfireFunction`]
annotation, it is easy to implement our Function as a POJO method. SDG handles registering this POJO method
as a proper Function with GemFire/Geode appropriately.
as a proper Function with {geode-name} appropriately.
If we now want to call this Function from our Spring Boot, `ClientCache` application, then we simply define
a Function Execution interface with a method name matching the Function name, and targeting the execution
@@ -97,14 +100,14 @@ class FinancialLoanApplicationService {
this.execution = execution;
}
@Cacheable("EligibilityDecisions", ...)
EligibilityDecision processEligility(Person person, Timespan timespan) {
@Cacheable("EligibilityDecisions")
EligibilityDecision processEligibility(Person person, Timespan timespan) {
return this.execution.determineEligibility(person, timespan);
}
}
----
Just like caching, no addition configuration is required to enable and find your application Function implementations
and executions. Simply build and run. Spring Boot for Apache Geode/Pivotal GemFire handles the rest.
and executions. Simply build and run. Spring Boot for {geode-name} handles the rest.
TIP: It is common to implement and register your application Functions on the server and execute them from the client.

80
spring-geode-docs/src/docs/asciidoc/_includes/gemfire-properties.adoc
View File

@@ -1,13 +1,13 @@
[[geode-configuration-gemfire-properties]]
== Using Geode Properties
:gemfire-name: Pivotal GemFire
:geode-name: Apache Geode
As of Spring Boot for {geode-name} & {gemfire-name} (SBDG) 1.3, it is now possible to declare {geode-name}
and {gemfire-name} properties from `gemfire.properties` in a Spring Boot `application.properties` file.
TIP: A complete list of valid {geode-name} (or {gemfire-name}) properties (also known as "_Geode Properties_")
can be found in the {apache-geode-docs}/reference/topics/gemfire_properties.html[User Guide].
As of Spring Boot for {geode-name} (SBDG) 1.3, it is possible to declare {geode-name} properties from
`gemfire.properties` in a Spring Boot `application.properties` file.
TIP: A complete list of valid {geode-name} properties can be found in the
{apache-geode-docs}/reference/topics/gemfire_properties.html[User Guide].
It should be known that only valid Geode Properties can be declared in `gemfire.properties`, or alternatively,
`gfsecurity.properties`.
@@ -28,8 +28,8 @@ durable-client-id=123
All of the properties declared in the `gemfire.properties` file shown above correspond to valid Geode Properties.
It is illegal to declare properties in a `gemfire.properties` file that are not valid Geode Properties, even if those
properties are prefixed with a different qualifier (e.g. "_spring.*_"). Both {geode-name} and {gemfire-name} are
very particular about this and will throw an `IllegalArgumentException` for invalid properties.
properties are prefixed with a different qualifier (e.g. "_spring.*_"). {geode-name} is very particular about this
and will throw an `IllegalArgumentException` for invalid properties.
For example, given the following `gemfire.properties` file with "_invalid-property_" declared:
@@ -42,7 +42,7 @@ name=ExampleCacheName
invalid-property=TEST
----
{geode-name} and {gemfire-name} throw an `IllegalArgumentException`:
{geode-name} throws an `IllegalArgumentException`:
.{geode-name} Exception for Invalid Property (Full Text Omitted)
[source,txt]
@@ -67,30 +67,29 @@ Valid attribute names are: ack-severe-alert-threshold ack-wait-threshold archive
at org.example.app.ApacheGeodeClientCacheApplication.main(...)
----
It is inconvenient to have to separate {geode-name} or {gemfire-name} properties from other application properties,
or to have to declare only Geode Properties in a `gemfire.properties` file and application properties in a separate
properties file, such as Spring Boot `application.properties`.
It is inconvenient to have to separate {geode-name} properties from other application properties, or to have to declare
only {geode-name} properties in a `gemfire.properties` file and application properties in a separate properties file,
such as Spring Boot `application.properties`.
Additionally, because of {geode-name} and {gemfire-name}'s constraint on properties, you are not able to leverage the
full power of Spring Boot when composing `application.properties`.
Additionally, because of {geode-name}'s constraint on properties, you are not able to leverage the full power of
Spring Boot when composing `application.properties`.
It is well-known that you can include certain properties based on a Spring Profile while excluding other properties.
This is essential when properties are environment or context specific.
Of course, users should be aware that Spring Data for {geode-name} & {gemfire-name} (SDG) provide a wide range of
properties mapping to {geode-name} and {gemfire-name} properties already.
Of course, users should be aware that Spring Data for {geode-name} (SDG) provide a wide range of properties mapping to
{geode-name} properties already.
For example, the SDG `spring.data.gemfire.locators` property maps to the `gemfire.locators` property (or simply,
`locators` in `gemfire.properties`) from {geode-name} and {gemfire-name}. Likewise, there are a full set of SDG
Properties mapping to the corresponding {geode-name} or {gemfire-name} properties in the
<<geode-configuration-metadata-springdata,Appendix>>.
`locators` in `gemfire.properties`) from {geode-name}. Likewise, there are a full set of SDG properties mapping to
the corresponding {geode-name} properties in the <<geode-configuration-metadata-springdata,Appendix>>.
The Geode Properties shown above can be expressed as SDG Properties in Spring Boot `application.properties` as follows:
.Configurring Geode Properties using SDG Properties
[source,properties]
----
# Spring Data GemFire properties in application.properties
# Spring Data for {geode-name} properties in application.properties
spring.data.gemfire.name=ExampleCacheName
spring.data.gemfire.cache.log-level=TRACE
@@ -99,13 +98,13 @@ spring.data.gemfire.cache.client.durable-client-id=123
# ...
----
However, there are some {geode-name} and {gemfire-name} properties that have no equivalent SDG property, such as
`gemfire.groups` (or simply, `groups` in `gemfire.properties`). This is partly due to the fact that many {geode-name}
and {gemfire-name} Properties are applicable only configured on the server (e.g. `groups` or `enforce-unique-host`).
However, there are some {geode-name} properties that have no equivalent SDG property, such as `gemfire.groups`
(or simply, `groups` in `gemfire.properties`). This is partly due to the fact that many {geode-name} properties are
applicable only configured on the server (e.g. `groups` or `enforce-unique-host`).
TIP: See the `@EnableGemFireProperties` annotation
({spring-data-geode-javadoc}/org/springframework/data/gemfire/config/annotation/EnableGemFireProperties.html[attributes])
from SDG for a complete list of {geode-name} and {gemfire-name} properties, which have no corresponding SDG property.
from SDG for a complete list of {geode-name} properties, which have no corresponding SDG property.
Furthermore, many of the SDG properties also correspond to API calls.
@@ -114,12 +113,12 @@ For example, `spring.data.gemfire.cache.client.keep-alive`
actually translates to the call, `ClientCache.close(boolean keepAlive)`
(see {apache-geode-javadoc}/org/apache/geode/cache/client/ClientCache.html#close-boolean-[here]).
Still, it would be convenient to be able to declare application and {geode-name} or {gemfire-name} properties together,
in a single properties file, such as Spring Boot `application.properties`. After all, it is not uncommon to declare
JDBC Connection properties in a Spring Boot `application.properties` file.
Still, it would be convenient to be able to declare application and {geode-name} properties together, in a single
properties file, such as Spring Boot `application.properties`. After all, it is not uncommon to declare JDBC Connection
properties in a Spring Boot `application.properties` file.
Therefore, as of SBDG 1.3, it is now possible to declare {geode-name} and {gemfire-name} properties in Spring Boot
`application.properties` directly.
Therefore, as of SBDG 1.3, it is now possible to declare {geode-name} properties in Spring Boot `application.properties`
directly.
For example:
@@ -136,8 +135,8 @@ gemfire.enable-time-statistics=true
This is convenient and ideal for several reasons:
1. If you already have a large number of {geode-name} or {gemfire-name} properties declared as Geode Properties,
either in `gemfire.properties` or `gfsecurity.properties`, or declared on the Java command-line as JVM System Properties
1. If you already have a large number of {geode-name} properties declared as `gemfire.` properties, either in
`gemfire.properties` or `gfsecurity.properties`, or declared on the Java command-line as JVM System Properties
(e.g. `-Dgemfire.name=ExampleCacheName`), then you can reuse these property declarations as is.
2. If you are unfamiliar with SDG's corresponding properties, then you can simply declare Geode Properties instead.
@@ -150,17 +149,16 @@ e.g. `gemfire.log-level=${external.log-level.property}`
TIP: As much as possible, we encourage users to use the SDG provided properties.
However, 1 strict requirement imposed by SBDG is that the Geode Property must have the "_gemfire._" prefix in a
Spring Boot `application.properties` file. This qualifies that the property belongs to {geode-name} or {gemfire-name}.
Without, the "_gemfire._" prefix, the property will not be appropriately applied to the {geode-name} or {gemfire-name}
cache instance.
Spring Boot `application.properties` file. This qualifies that the property belongs to {geode-name}. Without, the
"_gemfire._" prefix, the property will not be appropriately applied to the {geode-name} cache instance.
It would be ambiguous if your Spring Boot applications integrated with several technologies, including either
{geode-name} or {gemfire-name}, and they had matching properties, e.g. `bind-address` or `log-file`, perhaps.
It would be ambiguous if your Spring Boot applications integrated with several technologies, including {geode-name},
and they too had matching properties, e.g. `bind-address` or `log-file`, perhaps.
SBDG makes a best attempt to log warnings when the Geode Property is invalid or not set. For example, the following
Geode Property would result in a log warning:
.Invalid GemFire Property
.Invalid {geode-name} Property
[source,properties]
----
# Spring Boot application.properties
@@ -232,8 +230,8 @@ It is then a simple matter to apply the appropriate set of properties by configu
`-Dspring.profiles.active=prod`. It is also possible to enable more than 1 profile at a time by using:
`-Dspring.profiles.active=profile1,profile2,...,profileN`
If both `spring.data.gemfire.*` properties and the matching {geode-name} or {gemfire-name} properties are declared
in Spring Boot `application.properties`, then the SDG properties take precedence.
If both `spring.data.gemfire.*` properties and the matching {geode-name} properties are declared in Spring Boot
`application.properties`, then the SDG properties take precedence.
If a property is specified more than once, as would potentially be the case when composing multiple `application.properties`
files and you enable more than 1 Spring Profile at time, then the last property declaration wins. In the example shown
@@ -250,9 +248,9 @@ gemfire.durable-client-id=123
spring.data.gemfire.cache.client.durable-client-id=987
----
Then the `durable-client-id` will be `987`. It does not matter which order the SDG or {geode-name}/{gemfire-name}
properties are declared in `application.properties`, the matching SDG property will override the {geode-name}
or {gemfire-name} property when duplicates are found.
Then the `durable-client-id` will be `987`. It does not matter which order the SDG or {geode-name} properties are
declared in `application.properties`, the matching SDG property will override the {geode-name} property when duplicates
are found.
Finally, it is not possible to refer to Geode Properties declared in Spring Boot `application.properties` with the
SBDG `GemFireProperties` class (See {spring-boot-data-geode-javadoc}/org/springframework/geode/boot/autoconfigure/configuration/GemFireProperties.html[Javadoc]).

1
spring-geode-docs/src/docs/asciidoc/_includes/geode-api-ext.adoc
View File

@@ -1,6 +1,5 @@
[[geode-api-extensions]]
== Apache Geode API Extensions
:gemfire-name: Pivotal GemFire
:geode-name: Apache Geode
:images-dir: ./images

127
spring-geode-docs/src/docs/asciidoc/_includes/logging.adoc
View File

@@ -1,30 +1,32 @@
[[geode-logging]]
== Logging
:geode-name: Apache Geode
Apache Geode `1.9.2` was modularized to separate its use of the Apache Log4j API to log output in Geode code from
{geode-name} `1.9.2` was modularized to separate its use of the Apache Log4j API to log output in Geode code from
the underlying implementation of logging, which uses Apache Log4j as the logging provider by default.
Prior to `1.9.2`, the Apache Log4j API (i.e. `log4j-api`) along with the Apache Log4j provider (i.e. `log4j-core`)
were automatically pulled in by Apache Geode core (i.e. `org.apache.geode:geode-core`) thereby making it problematic
to change logging providers when using Apache Geode in Spring Boot applications.
were automatically pulled in by {geode-name} core (i.e. `org.apache.geode:geode-core`) thereby making it problematic
to change logging providers when using {geode-name} in Spring Boot applications.
However, now, in order to get any log output from Apache Geode whatsoever, Apache Geode requires a logging provider on
your Spring Boot application classpath. Consequently, this also means the old Apache Geode `Properties`,
However, now, in order to get any log output from {geode-name} whatsoever, {geode-name} requires a logging provider on
your Spring Boot application classpath. Consequently, this also means the old {geode-name} `Properties`,
e.g. `log-level` no longer have any effect, regardless of whether the property (e.g. `log-level`) is specified in
`gemfire.properties`, in Spring Boot `application.properties` or even as a JVM System Property, `-Dgemfire.log-level`.
TIP: Refer to Apache Geode's {apache-geode-docs}/reference/topics/gemfire_properties.html[Documentation]
TIP: Refer to {geode-name}'s {apache-geode-docs}/reference/topics/gemfire_properties.html[Documentation]
for a complete list of valid `Properties`, including the `Properties` used to configure logging.
Unfortunately, this also means the _Spring Data for Apache Geode & Pivotal GemFire_ (SDG)
Unfortunately, this also means the _Spring Data for {geode-name} (SDG)
{spring-data-geode-javadoc}/org/springframework/data/gemfire/config/annotation/EnableLogging.html[`@EnableLogging`]
annotation no longer has any effect on Apache Geode or Pivotal GemFire logging either and is the reason it has been
https://jira.spring.io/browse/DATAGEODE-299[deprecated]. The reason `@EnableLogging` no longer has any effect on
logging is because this annotation's attributes and associated SDG properties indirectly sets the corresponding
Apache Geode or Pivotal GemFire properties, which again, are useless from Apache Geode `1.9.2` onward.
annotation no longer has any effect on {geode-name} logging either and is the reason it has been
https://jira.spring.io/browse/DATAGEODE-299[deprecated]. The reason `@EnableLogging` no longer has any effect on logging
is because this annotation's attributes and associated SDG properties indirectly sets the corresponding {geode-name}
properties, which again, are useless from {geode-name} `1.9.2` onward.
By way of example, and to make this concrete, **none** of the following approaches have any effect on Apache Geode
or Pivotal GemFire logging:
By way of example, and to make this concrete, **none** of the following approaches have any effect on
{geode-name} logging:
.Command-line configuration
[source,txt]
@@ -33,10 +35,10 @@ $ java -classpath ...:/path/to/MySpringBootApacheGeodeClientCacheApplication.jar
example.app.MySpringBootApacheGeodeClientCacheApplication
----
.Externalized configuration using Apache Geode `gemfire.properties`
.Externalized configuration using {geode-name} `gemfire.properties`
[source,properties]
----
# Apache Geode/Pivotal GemFire only/specific properties
# {geode-name} only/specific properties
log-level=INFO
----
@@ -66,11 +68,11 @@ class MySpringBootApacheGeodeClientApplication {
That is to say, none of the approaches above have any effect without the **new** SBDG logging starter.
[[geode-logging-configuration]]
=== Configure Apache Geode & Pivotal GemFire Logging
=== Configure {geode-name} Logging
So, how do you configure logging for Apache Geode and Pivotal GemFire?
So, how do you configure logging for {geode-name}?
Effectively, 3 things are required to get Apache Geode or Pivotal GemFire to log output:
Effectively, 3 things are required to get {geode-name} to log output:
1) First, you must declare a logging provider on your Spring Boot application classpath (e.g. _Logback_).
@@ -81,7 +83,7 @@ For example, if you use the SLF4J API to log output from your Spring Boot applic
logging provider/implementation, then you must include the `org.apache.logging.log4j.log4j-to-slf4j` adapter/bridge JAR
dependency as well.
Internally, Apache Geode uses the Apache Log4j API to log output from Geode components. Therefore, you must bridge Log4j
Internally, {geode-name} uses the Apache Log4j API to log output from Geode components. Therefore, you must bridge Log4j
to any other logging provider (e.g. _Logback_) that is not Log4j (i.e. `log4j-core`). If you are using Log4j as your
logging provider then you do not need to declare an adapter/bridge JAR on your Spring Boot application classpath.
@@ -89,11 +91,11 @@ logging provider then you do not need to declare an adapter/bridge JAR on your S
For example, when using _Logback_, you must provide a `logback.xml` configuration file on your Spring Boot application
classpath, or in the filesystem. Alternatively, you can use other means to configure your logging provider and get
Apache Geode to log output.
{geode-name} to log output.
NOTE: Apache Geode's `geode-log4j` module covers the required configuration for steps 1-3 above and uses Apache Log4j
NOTE: {geode-name}'s `geode-log4j` module covers the required configuration for steps 1-3 above and uses Apache Log4j
(i.e. `org.apache.logging.log4j:log4j-core`) as the logging provider. The `geode-log4j` module even provides a default,
`log4j2.xml` configuration file to configure Loggers, Appenders and log levels for Apache Geode.
`log4j2.xml` configuration file to configure Loggers, Appenders and log levels for {geode-name}.
If you declare Spring Boot's own `org.springframework.boot:spring-boot-starter-logging` on your application classpath
then this will cover Steps 1 and 2 above.
@@ -101,12 +103,12 @@ then this will cover Steps 1 and 2 above.
The `spring-boot-starter-logging` dependency declares _Logback_ as the logging provider and automatically adapts,
or bridges `java.util.logging` (JUL) and Apache Log4j to SLF4J. However, you still need to supply logging provider
configuration, such as a `logback.xml` file for _Logback_, to configure logging not only for your Spring Boot
application, but also for Apache Geode as well.
application, but also for {geode-name} as well.
SBDG has simplified the setup of Apache Geode and Pivotal GemFire logging. Simply declare the
SBDG has simplified the setup of {geode-name} logging. Simply declare the
`org.springframework.geode:spring-geode-starter-logging` dependency on your Spring Boot application classpath!
Unlike Apache Geode's default Log4j XML configuration file (i.e. `log4j2.xml`), SBDG's provided `logback.xml`
Unlike {geode-name}'s default Log4j XML configuration file (i.e. `log4j2.xml`), SBDG's provided `logback.xml`
configuration file is properly parameterized enabling you to adjust log levels as well as add Appenders.
In addition, SBDG's provided _Logback_ configuration uses templates so you can compose your own logging configuration
@@ -117,27 +119,29 @@ while still "including" snippets from SBDG's provided logging configuration meta
One of the most common logging tasks is to adjust the log-level of one or more Loggers, or the ROOT Logger. However,
a user may only want to adjust the log-level for specific components of his/her Spring Boot application, such as for
Apache Geode, by setting the log-level for only the Logger that logs Apache Geode events.
{geode-name}, by setting the log-level for only the Logger that logs {geode-name} events.
SBDG's _Logback_ configuration defines 3 Loggers to control the log output from Apache Geode:
SBDG's _Logback_ configuration defines 3 Loggers to control the log output from {geode-name}:
.Apache Geode Loggers by name
.{geode-name} Loggers by name
[source,xml]
----
<logger name="com.gemstone.gemfire" level="${spring.boot.data.gemfire.log.level:-INFO}"/>
<logger name="org.apache.geode" level="${spring.boot.data.gemfire.log.level:-INFO}"/>
<logger name="org.jgroups" level="${spring.boot.data.gemfire.jgroups.log.level:-ERROR}"/>
<comfiguration>
<logger name="com.gemstone.gemfire" level="${spring.boot.data.gemfire.log.level:-INFO}"/>
<logger name="org.apache.geode" level="${spring.boot.data.gemfire.log.level:-INFO}"/>
<logger name="org.jgroups" level="${spring.boot.data.gemfire.jgroups.log.level:-ERROR}"/>
</comfiguration>
----
The `com.gemstone.gemfire` Logger is a legacy Logger covering old Pivotal GemFire bits still present in Apache Geode
for backwards compatibility reasons. This Logger's use should be largely unnecessary.
The `com.gemstone.gemfire` Logger is a legacy Logger covering old GemFire bits still present in {geode-name}
for backwards compatibility reasons. This Logger's use should be largely unnecessary.
The `org.apache.geode` Logger is the primary Logger used to control log output from all Apache Geode components
during the runtime operation of Apache Geode. Both this Logger and the legacy `com.gemstone.gemfire` Logger default
The `org.apache.geode` Logger is the primary Logger used to control log output from all {geode-name} components
during the runtime operation of {geode-name}. Both this Logger and the legacy `com.gemstone.gemfire` Logger default
log output to `INFO`.
The `org.jgroups` Logger is used to log output from Apache Geode's message distribution and membership system.
Apache Geode uses JGroups for membership and message distribution between peer members (nodes) in the cluster
The `org.jgroups` Logger is used to log output from {geode-name}'s message distribution and membership system.
{geode-name} uses JGroups for membership and message distribution between peer members (nodes) in the cluster
(distributed system). By default, JGroups log messages are logged at `ERROR`.
The log-level for the `com.gemstone.gemfire` and `org.apache.geode` Loggers are configured with the
@@ -157,7 +161,7 @@ $ java -classpath ...:/path/to/MySpringBootApplication.jar -Dspring.boot.data.ge
NOTE: Setting JVM System Properties using `$ java -jar MySpringBootApplication.jar -Dspring.boot.data.gemfire.log.level=DEBUG`
is not supported by the Java Runtime Environment (JRE).
Alternatively, you can configure and control Apache Geode logging in Spring Boot `application.properties`:
Alternatively, you can configure and control {geode-name} logging in Spring Boot `application.properties`:
.Setting the log-level in `application.properties`
[source,properties]
@@ -165,7 +169,7 @@ Alternatively, you can configure and control Apache Geode logging in Spring Boot
spring.boot.data.gemfire.log.level=DEBUG
----
For backwards compatibility, SBDG additionally supports the old _Spring Data for Apache Geode_ (SDG) logging properties
For backwards compatibility, SBDG additionally supports the old _Spring Data for {geode-name}_ (SDG) logging properties
as well, using either:
`spring.data.gemfire.cache.log-level=DEBUG`
@@ -238,11 +242,16 @@ For example, you could compose both the _Logback_ `ConsoleAppender` and `FileApp
.Composing multiple `Appenders`
[source,java]
----
ConsoleAppender<ILoggingEvent> consoleAppender = ...;
class LoggingConfiguration {
void composeApenders() {
FileAppender<ILoggingEvent> fileAppender = ...;
ConsoleAppender<ILoggingEvent> consoleAppender = new ConsoleAppender<>();
Appender<ILoggingEvent> compositeAppender = CompositeAppender.compose(consoleAppender, fileAppender);
FileAppender<ILoggingEvent> fileAppender = new FileApender<>();
Appender<ILoggingEvent> compositeAppender = CompositeAppender.compose(consoleAppender, fileAppender);
}
}
// do something with the compositeAppender
----
@@ -252,10 +261,15 @@ You could then add the `CompositeAppender` to a "named" `Logger` by doing:
.Register `CompositeAppender` on "named" `Logger`
[source,java]
----
Logger namedLogger = LoggerFactory.getLogger("loggerName");
class LoggerConfiguration {
void registerAppenderOnLogger() {
LogbackSupport.toLogbackLogger(namedLogger)
.ifPresent(it -> LogbackSupport.addAppender(it, compositeAppender));
Logger namedLogger = LoggerFactory.getLogger("loggerName");
LogbackSupport.toLogbackLogger(namedLogger)
.ifPresent(it -> LogbackSupport.addAppender(it, compositeAppender));
}
}
----
In this case, the "named" `Logger` will log events (or log messages) to both the _Console_ and _File_ `Appenders`.
@@ -279,18 +293,23 @@ With a reference to a `DelegatingAppender`, you can add any `Appender` as the de
.Add `ConsoleAppender` as the "delegate" for the `DelegatingAppender`
[source,java]
----
ConsoleAppender consoleAppender = new ConsoleAppender();
class LoggerConfiguration {
void setupDelegation() {
LogbackSupport.resolveLoggerContext().ifPresent(consoleAppender::setContext);
ConsoleAppender consoleAppender = new ConsoleAppender();
consoleAppender.setImmediateFlush(true);
consoleAppender.start();
LogbackSupport.resolveLoggerContext().ifPresent(consoleAppender::setContext);
LogbackSupport.resolveRootLogger()
.flatMap(LogbackSupport::toLogbackLogger)
.flatMap(rootLogger -> LogbackSupport.resolveAppender(rootLogger,
LogbackSupport.DELEGATE_APPENDER_NAME, DelegatingAppender.class))
.ifPresent(delegateAppender -> delegateAppender.setAppender(consoleAppender));
consoleAppender.setImmediateFlush(true);
consoleAppender.start();
LogbackSupport.resolveRootLogger()
.flatMap(LogbackSupport::toLogbackLogger)
.flatMap(rootLogger -> LogbackSupport.resolveAppender(rootLogger,
LogbackSupport.DELEGATE_APPENDER_NAME, DelegatingAppender.class))
.ifPresent(delegateAppender -> delegateAppender.setAppender(consoleAppender));
}
}
----
[[geode-logging-slf4j-logback-api-support-appender-string]]

23
spring-geode-docs/src/docs/asciidoc/_includes/repositories.adoc
View File

@@ -1,21 +1,22 @@
[[geode-repositories]]
== Spring Data Repositories
:geode-name: {apache-geode-name}
Using Spring Data Repositories with Apache Geode or Pivotal GemFire makes short work of data access operations when
using either Apache Geode or Pivotal GemFire as your System of Record (SOR) to persist your application's state.
Using Spring Data Repositories with {geode-name} makes short work of data access operations when using {geode-name}
as your System of Record (SOR) to persist your application's state.
{spring-data-commons-docs-html}/#repositories[Spring Data Repositories] provides a convenient and highly powerful way
to define basic CRUD and simple query data access operations easily just by specifying the contract of those data access
operations in a Java interface.
Spring Boot for Apache Geode & Pivotal GemFire _auto-configures_ the Spring Data for Apache Geode/Pivotal GemFire
{spring-data-geode-docs-html}/#gemfire-repositories[Repository extension] when either is declared on your application's
classpath. You do not need to do anything special to enable it. Simply start coding your application-specific
Repository interfaces and the way you go.
Spring Boot for {geode-name} _auto-configures_ the Spring Data for {geode-name} {spring-data-geode-docs-html}/#gemfire-repositories[Repository extension]
when either is declared on your application's classpath. You do not need to do anything special to enable it. Simply
start coding your application-specific Repository interfaces and the way you go.
For example:
Define a `Customer` class to model customers and map it to the GemFire/Geode "Customers" Region using the SDG
Define a `Customer` class to model customers and map it to the {geode-name} "Customers" Region using the SDG
{spring-data-geode-javadoc}/org/springframework/data/gemfire/mapping/annotation/Region.html[`@Region`] mapping
annotation:
@@ -24,7 +25,6 @@ annotation:
----
package example.app.books.model;
import ...;
@Region("Customers")
class Customer {
@@ -33,7 +33,6 @@ class Customer {
private String name;
....
}
----
@@ -44,8 +43,6 @@ Declare your _Repository_ (a.k.a. {wikipedia-docs}/Data_access_object[Data Acces
----
package example.app.books.repo;
import ...;
interface CustomerRepository extends CrudRepository<Customer, Long> {
List<Customer> findByLastNameLikeOrderByLastNameDescFirstNameAsc(String customerLastNameWildcard);
@@ -60,8 +57,6 @@ Then use the `CustomerRepository` in an application service class:
----
package example.app;
import ...;
@SpringBootApplication
@EnableEntityDefinedRegions(basePackageClasses = Customer.class)
class SpringBootApacheGeodeClientCacheApplication {
@@ -83,5 +78,5 @@ class SpringBootApacheGeodeClientCacheApplication {
----
Again, see Spring Data Commons' {spring-data-commons-docs-html}/#repositories[Repositories abstraction] in general,
and Spring Data for Apache Geode/Pivotal GemFire {spring-data-geode-docs-html}/#gemfire-repositories[Repositories extension]
and Spring Data for {geode-name}'s {spring-data-geode-docs-html}/#gemfire-repositories[Repositories extension]
in particular, for more details.

43
spring-geode-docs/src/docs/asciidoc/_includes/samples.adoc
View File

@@ -1,57 +1,58 @@
[[geode-samples]]
== Samples
:geode-name: {apache-geode-name}
This section contains working examples demonstrating how to use Spring Boot for Apache Geode and Pivotal GemFire (SBDG)
effectively.
This section contains working examples demonstrating how to use Spring Boot for {geode-name} (SBDG) effectively.
Some examples focus on specific Use Cases (e.g. [(HTTP) Session state] caching) while other examples demonstrate how
SBDG works under-the-hood to give users a better understanding of what is actually happening and how to debug problems
with their Apache Geode / Pivotal GemFire, Spring Boot applications.
with their {geode-name}, Spring Boot applications.
.Example Spring Boot applications using Apache Geode
.Example Spring Boot applications using {geode-name}
|===
| Guide | Description | Source
| link:guides/getting-started.html[Getting Started with Spring Boot for Apache Geode]
| Explains how to get started quickly, easily and reliably building Apache Geode and Pivotal Cloud Cache powered
| link:guides/getting-started.html[Getting Started with Spring Boot for {geode-name}]
| Explains how to get started quickly, easily and reliably building {geode-name} and Pivotal Cloud Cache powered
applications with Spring Boot.
| {github-samples-url}/intro/getting-started[Getting Started]
| link:guides/boot-configuration.html[Spring Boot Auto-Configuration for Apache Geode/Pivotal GemFire]
| link:guides/boot-configuration.html[Spring Boot Auto-Configuration for {geode-name}]
| Explains what auto-configuration is provided by SBDG out-of-the-box and what the auto-configuration is doing.
| {github-samples-url}/boot/configuration[Boot Auto-Configuration]
| link:guides/boot-actuator.html[Spring Boot Actuator for Apache Geode/Pivotal GemFire]
| Explains how to use Spring Boot Actuator for Apache Geode and how it works.
| link:guides/boot-actuator.html[Spring Boot Actuator for {geode-name}]
| Explains how to use Spring Boot Actuator for {geode-name} and how it works.
| {github-samples-url}/boot/actuator[Boot Actuator]
| link:guides/boot-security.html[Spring Boot Security for Apache Geode/Pivotal GemFire]
| Explains how to configure Auth and TLS with SSL when using Apache Geode and Pivotal Cloud Cache
| link:guides/boot-security.html[Spring Boot Security for {geode-name}]
| Explains how to configure Auth and TLS with SSL when using {geode-name} and Pivotal Cloud Cache
in Spring Boot applications.
| {github-samples-url}/boot/security[Boot Security]
| link:guides/caching-look-aside.html[Look-Aside Caching with Spring's Cache Abstraction and Apache Geode]
| Explains how to enable and use the Spring Cache Abstraction with Apache Geode as the caching provider for Look-Aside Caching.
| link:guides/caching-look-aside.html[Look-Aside Caching with Spring's Cache Abstraction and {geode-name}]
| Explains how to enable and use the Spring Cache Abstraction with {geode-name} as the caching provider for Look-Aside Caching.
| {github-samples-url}/caching/look-aside[Look-Aside Caching]
| link:guides/caching-inline.html[Inline Caching with Spring's Cache Abstraction and Apache Geode]
| Explains how to enable and use the Spring Cache Abstraction with Apache Geode as the caching provider for Inline Caching.
| link:guides/caching-inline.html[Inline Caching with Spring's Cache Abstraction and {geode-name}]
| Explains how to enable and use the Spring Cache Abstraction with {geode-name} as the caching provider for Inline Caching.
This sample builds on the *_Look-Aside Caching_* sample above.
| {github-samples-url}/caching/inline[Inline Caching]
| link:guides/caching-near.html[Near Caching with Spring's Cache Abstraction and Apache Geode]
| Explains how to enable and use the Spring Cache Abstraction with Apache Geode as the caching provider for Near Caching.
| link:guides/caching-near.html[Near Caching with Spring's Cache Abstraction and {geode-name}]
| Explains how to enable and use the Spring Cache Abstraction with {geode-name} as the caching provider for Near Caching.
This sample builds on the *_Look-Aside Caching_* sample above
| {github-samples-url}/caching/near[Near Caching]
| link:guides/caching-multi-site.html[Multi-Site Caching with Spring's Cache Abstraction and Apache Geode]
| Explains how to enable and use the Spring Cache Abstraction with Apache Geode as the caching provider for Multi-Site Caching.
| link:guides/caching-multi-site.html[Multi-Site Caching with Spring's Cache Abstraction and {geode-name}]
| Explains how to enable and use the Spring Cache Abstraction with {geode-name} as the caching provider for Multi-Site Caching.
This sample builds on the *_Look-Aside Caching_* sample above and is the 4th and final leg in our study
of _caching patterns_.
| {github-samples-url}/caching/multi-site[Multi-Site Caching]
| link:guides/caching-http-session.html[HTTP Session Caching with Spring Session and Apache Geode]
| Explains how to enable and use Spring Session with Apache Geode to manage HTTP Session state.
| link:guides/caching-http-session.html[HTTP Session Caching with Spring Session and {geode-name}]
| Explains how to enable and use Spring Session with {geode-name} to manage HTTP Session state.
| {github-samples-url}/caching/http-session[HTTP Session Caching]
|===

80
spring-geode-docs/src/docs/asciidoc/_includes/security.adoc
View File

@@ -1,33 +1,34 @@
[[geode-security]]
== Security
:geode-name: {apache-geode-name}
This sections covers Security configuration for {apache-geode-name}, which includes both Authentication & Authorization
This sections covers Security configuration for {geode-name}, which includes both Authentication & Authorization
(collectively, Auth) as well as Transport Layer Security (TLS) using SSL.
NOTE: Securing Data at Rest is not generally supported by either {apache-geode-name}, {pivotal-gemfire-name}
or Pivotal Cloud Cache (PCC) yet.
NOTE: Securing Data at Rest is not supported by {geode-name}.
TIP: Refer to the corresponding Sample link:guides/boot-security.html[Guide] and {github-samples-url}/boot/security[Code]
to see Spring Boot Security for {apache-geode-name} in action!
to see Spring Boot Security for {geode-name} in action!
[[geode-security-auth]]
=== Authentication & Authorization
{apache-geode-name} employs Username and Password based {apache-geode-docs}/managing/security/authentication_overview.html[Authentication]
{geode-name} employs Username and Password based {apache-geode-docs}/managing/security/authentication_overview.html[Authentication]
along with Role-based {apache-geode-docs}/managing/security/authorization_overview.html[Authorization] to secure
your client to server data exchanges and operations.
Spring Data for {apache-geode-name} (SDG) provides {spring-data-geode-docs-html}/#bootstrap-annotation-config-security[first-class support]
for {apache-geode-name}'s Security framework, which is based on the
Spring Data for {geode-name} provides {spring-data-geode-docs-html}/#bootstrap-annotation-config-security[first-class support]
for {geode-name}'s Security framework, which is based on the
{apache-geode-javadoc}/org/apache/geode/security/SecurityManager.html[SecurityManager] interface.
Additionally, {apache-geode-name}'s Security framework is integrated with https://shiro.apache.org/[Apache Shiro],
Additionally, {geode-name}'s Security framework is integrated with https://shiro.apache.org/[Apache Shiro],
making the security for servers an even easier and more familiar task.
NOTE: Eventually, support and integration with https://spring.io/projects/spring-security[Spring Security]
will be provided by SBDG as well.
When you use Spring Boot for {apache-geode-name} (SBDG), which builds on the bits provided in Spring Data
for {apache-geode-name} (SDG), it makes short work of enabling Auth in both your clients and servers.
When you use Spring Boot for {geode-name}, which builds on the bits provided in Spring Data for {geode-name},
it makes short work of enabling Auth in both your clients and servers.
[[geode-security-auth-servers]]
==== Auth for Servers
@@ -52,16 +53,16 @@ class ApacheGeodeSecurityConfiguration {
}
----
When an Apache Shiro Realm (e.g. `DefaultLdapRealm`) is declared and registered in the Spring `ApplicationContext`
as a Spring bean, Spring Boot will automatically detect this `Realm` bean (or `Realm` beans if more than 1 is configured)
and the {apache-geode-name} servers in the cluster will automatically be configured with Authentication and Authorization
When an Apache Shiro Realm (e.g. `DefaultLdapRealm`) is declared and registered in the Spring `ApplicationContext` as a
Spring bean, Spring Boot will automatically detect this `Realm` bean (or `Realm` beans if more than 1 is configured)
and the {geode-name} servers in the cluster will automatically be configured with Authentication and Authorization
enabled.
Alternatively, you can provide an custom, application-specific implementation of {apache-geode-name}'s
Alternatively, you can provide an custom, application-specific implementation of {geode-name}'s
{apache-geode-javadoc}/org/apache/geode/security/SecurityManager.html[SecurityManager] interface,
declared and registered as a bean in the Spring `ApplicationContext`:
.Declaring a custom {apache-geode-name} `SecurityManager`
.Declaring a custom {geode-name} `SecurityManager`
[source,java]
----
@Configuration
@@ -77,26 +78,25 @@ class ApacheGeodeSecurityConfiguration {
----
Spring Boot will discover your custom, application-specific `SecurityManager` implementation and configure
the servers in the {apache-geode-name} cluster with Authentication and Authorization enabled.
the servers in the {geode-name} cluster with Authentication and Authorization enabled.
TIP: The Spring team recommends that you use Apache Shiro to manage the Authentication & Authorization of your
{apache-geode-name} servers over implementing {apache-geode-name}'s `SecurityManager` interface.
{geode-name} servers over implementing {geode-name}'s `SecurityManager` interface.
[[geode-security-auth-clients]]
==== Auth for Clients
When {apache-geode-name} servers have been configured with Authentication & Authorization enabled,
then clients must authenticate when connecting.
When {geode-name} servers have been configured with Authentication & Authorization enabled, then clients must
authenticate when connecting.
Spring Boot for {apache-geode-name} (SBDG) makes this easy, regardless of whether you are running your Spring Boot,
`ClientCache` applications in a local, non-managed environment or even when running in a managed environment, like
Pivotal CloudFoundry (PCF).
Spring Boot for {geode-name} makes this easy, regardless of whether you are running your Spring Boot, `ClientCache`
applications in a local, non-managed environment or even when running in a cloud managed environment.
[[geode-security-auth-clients-non-managed]]
===== Non-Managed Auth for Clients
To enable Auth for clients connecting to a secure {apache-geode-name} cluster, you simply only need to set
a username and password in your Spring Boot `application.properties` file:
To enable Auth for clients connecting to a secure {geode-name} cluster, you simply only need to set a username
and password in your Spring Boot `application.properties` file:
[source,txt]
----
@@ -106,7 +106,7 @@ spring.data.gemfire.security.username = jdoe
spring.data.gemfire.security.password = p@55w0rd
----
Spring Boot for {apache-geode-name} (SBDG) will handle the rest.
Spring Boot for {geode-name} will handle the rest.
[[geode-secuirty-auth-clients-managed]]
===== Managed Auth for Clients
@@ -117,10 +117,9 @@ is even easier.
You do not need to do anything!
When your Spring Boot application uses SBDG and is bound to PCC, then when you push (i.e. deploy) your app to PCF,
Spring Boot for {apache-geode-name} (SBDG) will extract the required Auth credentials from the environment that you
setup when you provisioned a PCC service instance in your PCF organization & space. PCC automatically assigns 2 users
with roles "_cluster_operator_" and "_developer_", respectively, to any Spring Boot application bound to the PCC service
instance.
Spring Boot for {geode-name} will extract the required Auth credentials from the environment that you setup when you
provisioned a PCC service instance in your PCF organization & space. PCC automatically assigns 2 users with roles
"_cluster_operator_" and "_developer_", respectively, to any Spring Boot application bound to the PCC service instance.
By default, SBDG will auto-configure your Spring Boot app to run with the user having the "_cluster_operator" Role.
This ensures that your Spring Boot app has the necessary permissions (i.e. Authorization) to perform all data access
@@ -143,21 +142,21 @@ Securing data in motion is also essential to the integrity of your application.
For instance, it would not do much good to send usernames and passwords over plain text Socket connections
between your clients and servers, nor send sensitive data over those same connections.
Therefore, {apache-geode-name} supports SSL between clients & servers, JMX clients (e.g. _Gfsh_) and the _Manager_,
Therefore, {geode-name} supports SSL between clients & servers, JMX clients (e.g. _Gfsh_) and the _Manager_,
HTTP clients when using the Developer REST API or _Pulse_, between peers in the cluster, and when using the WAN Gateway
to connect multiple sites (i.e. clusters).
Spring Data for {apache-geode-name} (SDG) provides
Spring Data for {geode-name} provides
https://docs.spring.io/spring-data/geode/docs/current/reference/html/#bootstrap-annotation-config-ssl[first-class support]
for configuring and enabling SSL as well. Still, Spring Boot makes it even easier to configure and enable SSL,
especially during development.
{apache-geode-name} requires certain properties to be configured, which translate to the appropriate
{geode-name} requires certain properties to be configured, which translate to the appropriate
`javax.net.ssl.*` properties required by the JRE, to create Secure Socket Connections using
https://docs.oracle.com/javase/8/docs/technotes/guides/security/jsse/JSSERefGuide.html[JSSE].
But, ensuring that you have set all the required SSL properties correctly is an error prone and tedious task.
Therefore, Spring Boot for {apache-geode-name} (SBDG) applies some basic conventions for you, out-of-the-box.
Therefore, Spring Boot for {geode-name} applies some basic conventions for you, out-of-the-box.
Simply create a `trusted.keystore`, JKS-based `KeyStore` file and place it in 1 of 3 well-known locations:
@@ -166,11 +165,11 @@ Simply create a `trusted.keystore`, JKS-based `KeyStore` file and place it in 1
3. In your user home directory (as defined by the `user.home` Java System property).
When this file is named `trusted.keystore` and is placed in 1 of these 3 well-known locations, Spring Boot
for {apache-geode-name} (SBDG) will automatically configure your client to use SSL Socket connections.
for {geode-name} will automatically configure your client to use SSL Socket connections.
If you are using Spring Boot to configure and bootstrap an {apache-geode-name} server:
If you are using Spring Boot to configure and bootstrap an {geode-name} server:
.Spring Boot configured and bootstrapped {apache-geode-name} server
.Spring Boot configured and bootstrapped {geode-name} server
[source,java]
----
@SpringBootApplication
@@ -216,12 +215,11 @@ annotation for all the configuration attributes and the corresponding properties
[[geode-security-encryption]]
=== Securing Data at Rest
Currently, neither {apache-geode-name} nor {pivotal-gemfire-name} along with Spring Boot or Spring Data for
{apache-geode-name} and {pivotal-gemfire-name} offer any support for securing your data while at rest (e.g. when your
data has been overflowed or persisted to disk).
Currently, neither {geode-name} nor Spring Boot or Spring Data for {geode-name} offer any support for securing your data
while at rest (e.g. when your data has been overflowed or persisted to disk).
To secure data at rest when using {apache-geode-name}, with or without Spring, you must employ 3rd party solutions
like disk encryption, which is usually highly contextual and technology specific.
To secure data at rest when using {geode-name}, with or without Spring, you must employ 3rd party solutions like disk
encryption, which is usually highly contextual and technology specific.
For example, to secure data at rest using Amazon EC2, see
https://aws.amazon.com/blogs/security/how-to-protect-data-at-rest-with-amazon-ec2-instance-store-encryption/[Instance Store Encryption].

68
spring-geode-docs/src/docs/asciidoc/_includes/session.adoc
View File

@@ -1,8 +1,12 @@
[[geode-session]]
== Spring Session
:geode-name: {apache-geode-name}
:pcc-name: Pivotal Cloud Cache
:vmw-tas-name: VMware Tanzu Application Service
This chapter covers auto-configuration of Spring Session using either {apache-geode-name} or {pivotal-gemfire-name}
to manage (HTTP) Session state in a reliable (consistent), highly-available (replicated) and clustered manner.
This chapter covers auto-configuration of Spring Session using {geode-name} to manage (HTTP) Session state in a reliable
(consistent), highly-available (replicated) and clustered manner.
{spring-session-website}[Spring Session] provides an API and several implementations for managing a user's session
information. It has the ability to replace the `javax.servlet.http.HttpSession` in an application container neutral
@@ -14,19 +18,19 @@ and reactive Spring WebFlux WebSessions.
A full discussion of Spring Session is beyond the scope of this document, and the reader is encouraged to learn more
by reading the {spring-session-docs}[docs] and reviewing the {spring-session-docs}/#samples[samples].
Of course, Spring Boot for {apache-geode-name} provides auto-configuration support to configure {apache-geode-name}
as the user's session information management provider and store when {spring-session-data-gemfire-website}[Spring Session for {apache-geode-name}]
Of course, Spring Boot for {geode-name} provides auto-configuration support to configure {geode-name}
as the user's session information management provider and store when {spring-session-data-gemfire-website}[Spring Session for {geode-name}]
is on your Spring Boot application's classpath.
TIP: You can learn more about Spring Session for {apache-geode-name} in the {spring-session-data-gemfire-docs}[docs].
TIP: You can learn more about Spring Session for {geode-name} in the {spring-session-data-gemfire-docs}[docs].
TIP: Refer to the corresponding Sample link:guides/caching-http-session.html.html[Guide] and {github-samples-url}/caching/http-session[Code]
to see Spring Session for {apache-geode-name} in action!
to see Spring Session for {geode-name} in action!
[[geode-session-configuration]]
=== Configuration
There is nothing special that you need to do in order to use {apache-geode-name} as a Spring Session provider,
There is nothing special that you need to do in order to use {geode-name} as a Spring Session provider,
managing the (HTTP) Session state of your Spring Boot application.
Simply include the appropriate Spring Session dependency on your Spring Boot application's classpath, for example:
@@ -56,11 +60,6 @@ Maven POM or Gradle build file:
</dependency>
----
TIP: You may replace {apache-geode-name} with Pivotal Cloud Cache or {pivotal-gemfire-name} by changing the artifact ID
from `org.springframework.session:spring-session-data-geode` to `org.springframework.session:spring-session-data-gemfire`.
Alternatively, you may replace {apache-geode-name} with Pivotal Cloud Cache (PCC) or {pivotal-gemfire-name} by changing the artifact
ID from `spring-geode-starter-session` to `spring-gemfire-starter-session`. The version number is the same.
After declaring the required Spring Session dependency, then begin your Spring Boot application as you normally would:
.Spring Boot Application
@@ -95,16 +94,16 @@ class MyApplicationController {
}
----
The `HttpSession` is replaced by a Spring managed `Session` that will be stored in {apache-geode-name}.
The `HttpSession` is replaced by a Spring managed `Session` that will be stored in {geode-name}.
[[geode-session-configuration-custom]]
=== Custom Configuration
By default, Spring Boot for {apache-geode-name} (SBDG) applies reasonable and sensible defaults when configuring
{apache-geode-name} as the provider in Spring Session.
By default, Spring Boot for {geode-name} (SBDG) applies reasonable and sensible defaults when configuring
{geode-name} as the provider in Spring Session.
So, for instance, by default, SBDG set the session expiration timeout to 30 minutes. It also uses a
`ClientRegionShortcut.PROXY` as the client Region data management policy for the {apache-geode-name}
`ClientRegionShortcut.PROXY` as the client Region data management policy for the {geode-name}
Region managing the (HTTP) Session state when the Spring Boot application is using a `ClientCache`, which it does
by <<geode-clientcache-applications, default>>.
@@ -113,15 +112,15 @@ However, what if the defaults are not sufficient for your application requiremen
[[geode-session-configuration-custom-properties]]
==== Custom Configuration using Properties
Spring Session for {apache-geode-name} publishes
Spring Session for {geode-name} publishes
{spring-session-data-gemfire-docs}/#httpsession-gemfire-configuration-properties[well-known configuration properties]
for each of the various Spring Session configuration options when using {apache-geode-name} as the (HTTP) Session state
for each of the various Spring Session configuration options when using {geode-name} as the (HTTP) Session state
management provider.
You may specify any of these properties in a Spring Boot `application.properties` file to adjust Spring Session's
configuration when using {apache-geode-name}.
configuration when using {geode-name}.
In addition to the properties provided in and by Spring Session for {apache-geode-name}, Spring Boot for {apache-geode-name}
In addition to the properties provided in and by Spring Session for {geode-name}, Spring Boot for {geode-name}
also recognizes and respects the `spring.session.timeout` property as well as the `server.servlet.session.timeout`
property as discussed {spring-boot-docs-html}/boot-features-session.html[here].
@@ -132,13 +131,13 @@ of these properties have been simultaneously configured in the Spring `Environme
[[geode-session-configuration-custom-configurer]]
==== Custom Configuration using a Configurer
Spring Session for {apache-geode-name} also provides the
Spring Session for {geode-name} also provides the
{spring-session-data-gemfire-javadoc}/org/springframework/session/data/gemfire/config/annotation/web/http/support/SpringSessionGemFireConfigurer.html[`SpringSessionGemFireConfigurer`]
callback interface, which can be declared in your Spring `ApplicationContext` to programmatically control
the configuration of Spring Session when using {apache-geode-name}.
the configuration of Spring Session when using {geode-name}.
The `SpringSessionGemFireConfigurer`, when declared in the Spring `ApplicationContext`, takes precedence over any of the
Spring Session (for {apache-geode-name}) configuration properties, and will effectively override them when both
Spring Session (for {geode-name}) configuration properties, and will effectively override them when both
are present.
More information on using the `SpringSessionGemFireConfigurer` can be found in the
@@ -147,7 +146,7 @@ More information on using the `SpringSessionGemFireConfigurer` can be found in t
[[geode-session-disable]]
=== Disabling Session State Caching
There may be cases where you do not want your Spring Boot application to manage (HTTP) Session state using {apache-geode-name}.
There may be cases where you do not want your Spring Boot application to manage (HTTP) Session state using {geode-name}.
In certain cases, you may be using another Spring Session provider, such as Redis, to cache and manage your Spring Boot
application's (HTTP) Session state, while, even in other cases, you do not want to use Spring Session to manage your
(HTTP) Session state at all. Rather, you prefer to use your Web Server's (e.g. Tomcat) `HttpSession` state management.
@@ -179,23 +178,22 @@ spring.session.store-type=none
Again, see Spring Boot {spring-boot-docs-html}/boot-features-session.html[docs] for more details.
TIP: It is possible to include multiple providers on the classpath of your Spring Boot application. For instance,
you might be using Redis to cache your application's (HTTP) Session state while using {apache-geode-name} as your
you might be using Redis to cache your application's (HTTP) Session state while using {geode-name} as your
application's persistent store (_System of Record_).
NOTE: Spring Boot does not properly recognize `spring.session.store-type=[gemfire|geode]` even though
Spring Boot for {apache-geode-name} is setup to handle either of these property values
Spring Boot for {geode-name} is setup to handle either of these property values
(i.e. either "`gemfire`" or "`geode`").
[[geode-session-pcc]]
=== Using Spring Session with Pivotal Cloud Cache
=== Using Spring Session with {pcc-name} (PCC)
Whether you are using Spring Session in a Spring Boot `ClientCache` application connecting to an externally managed
cluster of {apache-geode-name} servers, or connecting to a cluster of servers in a Pivotal Cloud Cache instance
managed by a Pivotal Platform environment, the setup is the same.
cluster of {geode-name} servers, or connecting to a cluster of servers in a {pcc-name} service instance managed by
a {vmw-tas-name} (TAS) environment, the setup is the same.
Spring Session for {apache-geode-name}, {pivotal-gemfire-name}, and Pivotal Cloud Cache (PCC) expects there to exist
a cache Region in the cluster that will store and manage the (HTTP) Session state when your Spring Boot application
is a `ClientCache` application in a client/server topology.
Spring Session for {geode-name} expects there to exist a cache Region in the cluster that will store and manage (HTTP)
Session state when your Spring Boot application is a `ClientCache` application in a client/server topology.
By default, the cache Region used to store and manage (HTTP) Session state is called "_ClusteredSpringSessions_".
@@ -248,7 +246,7 @@ the entry (i.e. Session object) will be "_invalidated_".
NOTE: Session expiration is managed by the Expiration Policy set on the cache Region used to store Session state.
The Servlet Container's (HTTP) Session expiration configuration is not used since Spring Session is replacing
the Servlet Container's Session management capabilities with its own and Spring Session delegates this behavior
to the individual providers, like GemFire and Geode.
to the individual providers, like {geode-name}.
Alternatively, you could send the definition for the cache Region from your Spring Boot `ClientCache` application
to the cluster using the SBDG {spring-boot-data-geode-javadoc}/org/springframework/geode/config/annotation/EnableClusterAware.html[`@EnableClusterAware`] annotation,
@@ -281,5 +279,5 @@ gfsh> alter region --name=MySessions --entry-idle-time-expiration=1800
That is it!
Now your Spring Boot `ClientCache` application using Spring Session in a client/server topology is configured to store
and manage user (HTTP) Session state in the cluster. This works for either standalone, externally managed {apache-geode-name}
clusters, or when using PCC running in a Pivotal Platform environment.
and manage user (HTTP) Session state in the cluster. This works for either standalone, externally managed {geode-name}
clusters, or when using PCC running in a {vmw-tas-name} environment.

47
spring-geode-docs/src/docs/asciidoc/_includes/templates.adoc
View File

@@ -1,13 +1,15 @@
[[geode-data-access-region-templates]]
== Data Access with GemfireTemplate
:geode-name: Apache Geode
There are several ways to access data stored in Apache Geode.
There are several ways to access data stored in {geode-name}.
For instance, developers may choose to use the {apache-geode-javadoc}/org/apache/geode/cache/Region.html[Region API]
directly. If developers are driven by the application's domain context, they might choose to leverage the power of
{spring-data-commons-docs-html}/#repositories[Spring Data Repositories] instead.
While using the _Region_ API directly offers flexibility, it couples your application to Apache Geode, which is usually
While using the _Region_ API directly offers flexibility, it couples your application to {geode-name}, which is usually
undesirable and unnecessary. While using Spring Data _Repositories_ provides a very powerful and convenient abstraction,
you give up flexibility provided by a lower level API.
@@ -20,11 +22,11 @@ the core Spring Framework.
Other Spring Data modules, such as Spring Data Redis, offer the
https://docs.spring.io/spring-data/redis/docs/current/api/org/springframework/data/redis/core/RedisTemplate.html[RedisTemplate],
and Spring Data for Apache Geode/Pivotal GemFire (SDG) offers the
and Spring Data for {geode-name} (SDG) offers the
{spring-data-gemfire-javadoc}/org/springframework/data/gemfire/GemfireTemplate.html[GemfireTemplate].
The `GemfireTemplate` provides a highly consistent and familiar API to perform data access operations on Apache Geode
or Pivotal GemFire cache `Regions`.
The `GemfireTemplate` provides a highly consistent and familiar API to perform data access operations on {geode-name}
cache `Regions`.
`GemfireTemplate` offers:
@@ -33,8 +35,8 @@ or Pivotal GemFire cache `Regions`.
3. Automatic enlistment in the presence of local, cache transactions.
4. Protection from {apache-geode-javadoc}/org/apache/geode/cache/Region.html[Region API] breaking changes.
Given these conveniences, Spring Boot for Apache Geode & Pivotal GemFire (SBDG) will auto-configure `GemfireTemplate`
beans for each Region present in the GemFire/Geode cache.
Given these conveniences, Spring Boot for {geode-name} (SBDG) will auto-configure `GemfireTemplate` beans for each
Region present in the {geode-name} cache.
Additionally, SBDG is careful not to create a `GemfireTemplate` if the user has already declared a `GemfireTemplate`
bean in the Spring `ApplicationContext` for a given Region.
@@ -51,7 +53,7 @@ class GemFireConfiguration {
@Bean("Example")
ClientRegionFactoryBean<?, ?> exampleRegion (GemFireCache gemfireCache) {
...
// ...
}
}
----
@@ -88,7 +90,7 @@ Given the following entity class:
----
@Region("Customers")
class Customer {
...
// ...
}
----
@@ -97,9 +99,9 @@ And configuration:
[source,java]
----
@Configuration
@EnableEntityDefinedRegions(basePackageClasses = Customer.class}
class GemFireConfiguration {
...
@EnableEntityDefinedRegions(basePackageClasses = Customer.class)
class GeodeConfiguration {
// ...
}
----
@@ -127,9 +129,8 @@ explicitly or implicitly, such as when using the `@EnableEntityDefineRegions` an
SBDG auto-configures `GemfireTemplate` beans for Caching-defined Regions.
When you are using Spring Framework's {spring-framework-docs}/integration.html#cache[Cache Abstraction] backed by
either Apache Geode or Pivotal GemFire, 1 of the requirements is to configure Regions for each of the caches specified
in the {spring-framework-docs}integration.html#cache-annotations[Caching Annotations] of your application service
components.
{geode-name}, 1 of the requirements is to configure Regions for each of the caches specified in the
{spring-framework-docs}integration.html#cache-annotations[Caching Annotations] of your application service components.
Fortunately, SBDG makes enabling and configuring caching easy and <<geode-caching-provider,automatic>> out-of-the-box.
@@ -183,10 +184,10 @@ when autowiring does not.
[[geode-data-access-region-templates-native-defined]]
=== Native-defined Regions
SBDG will even auto-configure `GemfireTemplate` beans for Regions defined using Apache Geode and Pivotal GemFire native
configuration meta-data, such as `cache.xml`.
SBDG will even auto-configure `GemfireTemplate` beans for Regions defined using {geode-name} native configuration
metadata, such as `cache.xml`.
Given the following GemFire/Geode native `cache.xml`:
Given the following {geode-name} native `cache.xml`:
[source,xml]
----
@@ -208,7 +209,7 @@ And Spring configuration:
@Configuration
@EnableGemFireProperties(cacheXmlFile = "cache.xml")
class GemFireConfiguration {
...
// ...
}
----
@@ -243,7 +244,7 @@ class GemFireConfiguration {
@Bean
public GemfireTemplate customersTemplate(GemFireCache cache) {
return new GemfireTemplate(cache.getRegion("/Customers");
return new GemfireTemplate(cache.getRegion("/Customers"));
}
}
----
@@ -254,7 +255,7 @@ Using our same Customers class, as above:
----
@Region("Customers")
class Customer {
...
// ...
}
----
@@ -274,11 +275,11 @@ With the following configuration, SBDG is still careful not to create the Templa
----
@Configuration
@EnableEntityDefinedRegions(basePackageClasses = Customer.class)
class GemFireConfiguration {
class GeodeConfiguration {
@Bean
public GemfireTemplate vipCustomersTemplate(GemFireCache cache) {
return new GemfireTemplate(cache.getRegion("/Customers");
return new GemfireTemplate(cache.getRegion("/Customers"));
}
}
----