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

Edit Sample Guides and replace all references to 'Apache Geode' using a documentation variable.

Browse Source 
Remove all references to 'GemFire'.

Fix compiler syntax errors in example code snippets.
This commit is contained in:
John Blum
2020-09-18 16:11:39 -07:00
parent 68c34b86ea
commit 546aa298f8
8 changed files with 187 additions and 232 deletions
Download Patch File Download Diff File Expand all files Collapse all files

11
spring-geode-docs/src/docs/asciidoc/guides/boot-actuator.adoc
View File

@@ -1,9 +1,8 @@
[[geode-samples-boot-actuator]]
= Spring Boot Actuator for Apache Geode & VMware Tanzu GemFire
= Spring Boot Actuator for Apache Geode
:geode-version: {apache-geode-doc-version}
:geode-name: Apache Geode
:geode-docs: https://geode.apache.org/docs/guide/{geode-version}
:gemfire-name: VMware Tanzu GemFire
:images-dir: ./images
:spring-boot-docs: https://docs.spring.io/spring-boot/docs/current/reference/html
:spring-framework-docs: https://docs.spring.io/spring/docs/current/spring-framework-reference
@@ -15,10 +14,10 @@
This guide walks through using {spring-boot-docs}/production-ready.html[Spring Boot Actuator] to assess the state
of your running {geode-name} or {gemfire-name}, Spring Boot application.
of your running {geode-name}, Spring Boot application.
The goal for SBDG's Spring Boot Actuator integration is to enable users to effectively manage and monitor their
Spring Boot applications using {geode-name} or {gemfire-name} in a production environment.
Spring Boot applications using {geode-name} in a production environment.
In particular, SBDG's integration with Spring Boot Actuator currently focuses on enabling
{spring-boot-docs}/production-ready-endpoints.html#production-ready-health[Health Information]
@@ -147,7 +146,7 @@ as designated by our `TemperatureReading` model class's, `@Region` annotation de
[source,java]
----
@Region("TemperatureReadings")
public class TemperatureReading { ... }
public class TemperatureReading { }
----
Additionally, the `readTempeature()` method uses our `TemperatureReadingRepository` to perform the necessary
@@ -401,7 +400,7 @@ management.endpoint.health.show-details=always
[[geode-samples-boot-actuator-conclusion]]
== Conclusion
Hopefully this guide has shown you how to use the Spring Boot Actuator feature for {geode-name} and {gemfire-name}.
Hopefully this guide has shown you how to use the Spring Boot Actuator feature for {geode-name}.
You are encouraged to read more about {spring-boot-docs}/production-ready.html[Spring Boot's Actuator] functionality.

27
spring-geode-docs/src/docs/asciidoc/guides/boot-configuration.adoc
View File

@@ -1,5 +1,5 @@
[[geode-samples-boot-configuration]]
= Spring Boot Auto-configuration for Apache Geode & VMware Tanzu GemFire
= Spring Boot Auto-configuration for Apache Geode
John Blum
:geode-version: {apache-geode-doc-version}
:geode-docs: https://geode.apache.org/docs/guide/{geode-version}
@@ -402,20 +402,19 @@ there are no servers or cluster running yet.
There are several ways in which to start a cluster. For example, you may use Spring to configure and bootstrap
the cluster, which has been demonstrated link:../index.html#geode-cluster-configuration-bootstrapping[here].
Although, for this example, we are going to use the tools provided with {geode-name}, i.e. _Gfsh_
(GemFire/Geode Shell) for reasons that will become apparent later.
Although, for this example, we are going to use the tools provided with {geode-name}, i.e. _Gfsh_ ({geode-name} Shell)
for reasons that will become apparent later.
NOTE: You need to https://geode.apache.org/releases/[download] and https://geode.apache.org/docs/guide/18/prereq_and_install.html[install]
a full distribution of {geode-name} to make use of the provided tools. After installation, you will need to set
the `GEODE` (or `GEMFIRE`) environment variable to the location of your installation. Additionally, add `$GEODE/bin`
to your system `$PATH`.
a full distribution of {geode-name} to make use of the provided tools. After installation, you will need to set the
`GEODE` environment variable to the location of your installation. Additionally, add `$GEODE/bin` to your system `$PATH`.
Once {geode-name} has been successfully installed, you can open a command prompt (terminal) and do:
.Running Gfsh
[source,txt]
----
$ echo $GEMFIRE
$ echo $GEODE
/Users/jblum/pivdev/apache-geode-1.2.1
@@ -609,11 +608,11 @@ public class CustomerServiceApplication {
That is, we additionally annotate our Customer Service application class with SDG's `@EnableClusterConfiguration`
annotation. We have also set the `useHttp` attribute to `true`. This sends the configuration metadata from the client
to the cluster via GemFire/Geode's Management REST API.
to the cluster via {geode-name}'s Management REST API.
This is useful when your GemFire/Geode cluster may be running behind a firewall, such as on public cloud infrastructure.
This is useful when your {geode-name} cluster may be running behind a firewall, such as on public cloud infrastructure.
However, there are other benefits to using HTTP as well. As stated, the client sends configuration metadata to
GemFire/Geode's Management REST interface, which is a facade for the server-side Cluster Configuration Service. If
{geode-name}'s Management REST interface, which is a facade for the server-side Cluster Configuration Service. If
another peer (e.g. server) is added to the cluster as a member, then this member will get the same configuration. If
the entire cluster goes down, it will have the same configuration when it is restarted.
@@ -879,18 +878,18 @@ First, we must secure the cluster (i.e. the Locator and Server).
In a nutshell, when using the {geode-name} API (with no help from Spring), you must do the following:
1. (Auth) Implement the `org.apache.geode.security.SecurityManager` interface.
2. (Auth) Configure your custom `SecurityManager` using the GemFire/Geode `security-manager` property in `gemfire.properties`.
2. (Auth) Configure your custom `SecurityManager` using the {geode-name} `security-manager` property in `gemfire.properties`.
3. (Auth) Either create a `gfsecurity.properties` file and set the `security-username` and `security-password` properties, or...
4. (Auth) Implement the `org.apache.geode.security.AuthInitialize` interface and set the `security-peer-auth-init` property
in `gemfire.properties` as described in {geode-docs}/managing/security/implementing_authentication.html[Implementing Authentication]
of the {geode-name} User Guide.
5. (SSL) Then, you must create Java KeyStore (jks) files for both the keystore and truststore used to configure
the SSL Socket.
6. (SSL) Configure the Java KeyStores using the GemFire/Geode `ssl-keystore` and `ssl-truststore` properties
6. (SSL) Configure the Java KeyStores using the {geode-name} `ssl-keystore` and `ssl-truststore` properties
in `gemfire.properties`.
7. (SSL) If you secured your Java KeyStores (recommended) then you must additionally set the `ssl-keystore-password`
and `ssl-truststore-password` properties.
8. (SSL) Optionally, configure the GemFire/Geode components that should be enabled with SSL using the
8. (SSL) Optionally, configure the {geode-name} components that should be enabled with SSL using the
`ssl-enabled-components` property (e.g. `locator` and `server` for client/server and Locator connections).
9. Then launch the cluster, and its members using _Gfsh_ in the proper order.
@@ -906,7 +905,7 @@ include::{samples-dir}/boot/configuration/src/main/resources/geode/bin/start-sec
----
NOTE: SBDG does provide server-side, peer Security _auto-configuration_ support. However, you must then configure
and bootstrap your GemFire/Geode servers with Spring. Again, an example of configuring/bootstrapping GemFire/Geode
and bootstrap your {geode-name} servers with Spring. Again, an example of configuring/bootstrapping {geode-name}
servers with Spring is provided <<../_includes/configuration-auto.adoc#geode-cluster-configuration-bootstrapping,here>>.
[[geode-samples-boot-configuration-clientserver-security-client]]

17
spring-geode-docs/src/docs/asciidoc/guides/boot-security.adoc
View File

@@ -1,5 +1,5 @@
[[geode-samples-boot-security]]
= Spring Boot Security for Apache Geode & VMware Tanzu GemFire
= Spring Boot Security for Apache Geode
Patrick Johnson, John Blum
:gemfire-name: VMware Tanzu GemFire
:geode-name: Apache Geode
@@ -12,7 +12,7 @@ Patrick Johnson, John Blum
:docinfodir: guides
This guide walks you through building a simple Spring Boot application enabled with Security, specifically Auth
and TLS using SSL. You should already be familiar with Spring Boot and {geode-name}/{gemfire-name}.
and TLS using SSL. You should already be familiar with Spring Boot and {geode-name}.
TIP: Refer to the link:../index.html#geode-security[Security] chapter in the reference documentation
for more information.
@@ -138,7 +138,7 @@ TIP: Because SDBG auto-configures a `ClientCache` instance by default, you do no
`@SpringBootApplication` class with SDG's `@ClientCacheApplication` annotation. In fact doing so disables some of the
auto-configuration, like security, applied by SBDG OOTB. The same is true when you declare one of the
[`@PeerCacheApplication`, `@CacheServerApplication`] annotations, which changes your `@SpringBootApplication` class
completely, from a client to a server-side GemFire/Geode process. Therefore, be careful! See the relevant
completely, from a client to a server-side {geode-name} process. Therefore, be careful! See the relevant
link:../index.html#geode-clientcache-applications[chapter] in the reference documentation for more details.
[[geode-samples-boot-security-example-classes-server]]
@@ -154,12 +154,12 @@ This class is a Spring Boot, {geode-name} server application (i.e. `CacheServer`
(i.e. `ClientCache`) to authenticate when connecting to the server and to communicate using SSL.
Unlike the client application class above, we annotate this `@SpringBootApplication` class with `@CacheServerApplication`
to override the default `ClientCache` auto-configured by SBDG OOTB. This makes the application a GemFire/Geode Server on
to override the default `ClientCache` auto-configured by SBDG OOTB. This makes the application a {geode-name} server on
startup, capable of serving clients.
We must additionally annotate the server application class with SBDG's `@EnableSecurity` annotation to enable GemFire
/ Geode Security on the server-side. By explicitly declaring a `PropertiesRealm` bean, we are using Apache Shiro as the
auth provider, supplying the security credentials (users, roles and permissions) via a Java Properties file:
We must additionally annotate the server application class with SBDG's `@EnableSecurity` annotation to enable
{geode-name} Security on the server-side. By explicitly declaring a `PropertiesRealm` bean, we are using Apache Shiro
as the auth provider, supplying the security credentials (users, roles and permissions) via a Java Properties file:
.Apache Shiro Properties file containing the security credentials configuration
[source,java]
@@ -349,5 +349,4 @@ https://security-app.apps.<cf-instance>.cf-app.com/message[https://security-app.
Replace `<cf-instance>` with the name of your CloudFoundry instance to verify that the application is using SSL.
Congratualtions! You have taken your first steps towards securing {geode-name} and {gemfire-name} applications
with Spring Boot.
Congratulations! You have taken your first steps towards securing an {geode-name} application with Spring Boot.

42
spring-geode-docs/src/docs/asciidoc/guides/caching-inline.adoc
View File

@@ -1,5 +1,6 @@
[[geode-samples-caching-inline]]
= Inline Caching with Spring
:apache-geode-name: Apache Geode
:apache-geode-version: {apache-geode-doc-version}
:apache-geode-docs: https://geode.apache.org/docs/guide/{apache-geode-version}
:apache-geode-javadoc: https://geode.apache.org/releases/latest/javadoc
@@ -20,10 +21,10 @@
This guide walks you through building a simple Spring Boot application
using {spring-framework-docs}/integration.html#cache[Spring's Cache Abstraction]
backed by Apache Geode as the caching provider for Inline Caching.
backed by {apache-geode-name} as the caching provider for Inline Caching.
It is assumed that the reader is familiar with the Spring _programming model_. No prior knowledge of Spring's
_Cache Abstraction_ or Apache Geode is required to utilize caching in your Spring Boot applications.
_Cache Abstraction_ or {apache-geode-name} is required to utilize caching in your Spring Boot applications.
Additionally, this Sample builds on the concepts from the link:caching-look-aside.html[Look-Aside Caching with Spring]
guide. Therefore, it would be helpful to have read that guide before proceeding through this guide.
@@ -31,8 +32,8 @@ guide. Therefore, it would be helpful to have read that guide before proceeding
Let's begin.
TIP: Refer to the link:../index.html#geode-caching-provider-inline-caching[Inline Caching] section
in the link:../index.html#geode-caching-provider[Caching with Apache Geode or VMware Tanzu GemFire] chapter
in the reference documentation for more information.
in the link:../index.html#geode-caching-provider[Caching with {apache-geode-name}] chapter in the reference documentation
for more information.
[#index-link]
link:../index.html[Index]
@@ -160,10 +161,9 @@ expired or been evicted. We neither configure eviction nor expiration for this
Both the `factorial(..)` and `sqrt(..)` methods have been annotated with Spring's `@Cacheable` annotation to demarcate
these methods with caching behavior. Of course, as explained in SBDG's <<../_includes/configuration-annotations.adoc#geode-caching-provider,documentation>>,
caching with Spring's Cache Abstraction using Apache Geode (or Pivotal GemFire, even Pivotal Cloud Cache (PCC)
when running in Pivotal CloudFoundry (PCF)) as the caching provider is enabled by default. Therefore, there is nothing
more you need do to start leverage caching in your Spring Boot applications than to annotate the service methods
with the appropriate Spring or JSR-107, JCache API annotations. Simple!
caching with Spring's Cache Abstraction using {apache-geode-name} as the caching provider is enabled by default.
Therefore, there is nothing more you need do to start leverage caching in your Spring Boot applications than to annotate
the service methods with the appropriate Spring or JSR-107, JCache API annotations. Simple!
It is worth noting that we are starting with the same applied pattern of caching as you would when using the
_Look-Aside Caching_ pattern. This is key to minimizing the invasive nature of _Inline Caching_. There is a subtle
@@ -187,7 +187,7 @@ The pertinent part of the configuration that enables _Inline Caching_ for our Ca
the `inlineCachingForCalculatorApplicationRegionsConfigurer` bean definition.
SBDG provides the `InlineCachingRegionConfigurer` class used in the bean definition to configure and enable the caches
(a.k.a. as Regions in Apache Geode & Pivotal GemFire terminology) with _Inline Caching_ behavior.
(a.k.a. as Regions in {apache-geode-name} terminology) with _Inline Caching_ behavior.
The Configurer's job is to configure the appropriate Spring Data (SD) _Repository_ used as a Region's `CacheLoader`
for "_read-through_" behavior as well as configure the same SD _Repository_ for a Region's `CacheWriter` for
@@ -238,19 +238,19 @@ that needs to be written back to a database (use https://spring.io/projects/spri
or https://spring.io/projects/spring-data-jpa[Spring Data JPA]).
This is what makes the Spring Data _Repository_ pattern so ideal. It is very flexible and has a highly consistent
API across a disparate grouping of data stores. And due to that uniformity, it is easy to "adapt" the GemFire/Geode
`CacheLoader`/`CacheWriter` interfaces to use a SD Repository under-the-hood. Indeed, that is exactly what SBDG
has done for you!
API across a disparate grouping of data stores. And due to that uniformity, it is easy to "adapt" the
{apache-geode-name} `CacheLoader`/`CacheWriter` interfaces to use a SD Repository under-the-hood. Indeed, that is
exactly what SBDG has done for you!
We will circle back to the `resultKeyGenerator` bean definition after we talk about the application domain model.
Also notice the use of the `@EnableCachingDefinedRegions` annotation.
Whenever you use a caching provider like Apache Geode or Redis, you must explicitly define or declare your caches
Whenever you use a caching provider like {apache-geode-name} or Redis, you must explicitly define or declare your caches
in some manner. This is inconvenient since you have basically already declared the caches required by your application
when using Spring's, or alternatively, the JSR-107, JCache API annotations (e.g. `@Cacheable`). Why should you have to
do this again? Well, using SBDG, you don't. You simply have to declare the `@EnableCachingDefinedRegions` annotation
and SBDG will take care of defining the necessary Apache Geode Regions backing the caches for you.
and SBDG will take care of defining the necessary {apache-geode-name} Regions backing the caches for you.
Regions for caches are not auto-configured for you because there are many different ways to "define" a Region, with
different configuration, such as eviction and expiration polices, memory requirements, application callbacks, etc.
@@ -260,13 +260,12 @@ these Regions for you.
TIP: If you have not done so already, you should definitely read about SBDG's support for _Inline Caching_
in the link:../index.html#geode-caching-provider-inline-caching[Inline Caching] section.
TIP: To learn more about how Apache Geode's (or Pivotal GemFire's) data loading functionality works, or specifically,
how to {apache-geode-docs}/developing/outside_data_sources/sync_outside_data.html["Keep the Cache in Sync with Outside
Data Sources"] follow the link. You may also learn more by reading the _Javadoc_ for
{apache-geode-javadoc}//org/apache/geode/cache/CacheLoader.html[`CacheLoader`]
TIP: To learn more about how {apache-geode-name}'s data loading functionality works, or specifically, how to
{apache-geode-docs}/developing/outside_data_sources/sync_outside_data.html["Keep the Cache in Sync with Outside Data Sources"]
follow the link. You may also learn more by reading the _Javadoc_ for {apache-geode-javadoc}//org/apache/geode/cache/CacheLoader.html[`CacheLoader`]
and {apache-geode-javadoc}/org/apache/geode/cache/CacheWriter.html[`CacheWriter`].
TIP: To learn more about `@EnableCachingDefinedRegions`, see the Spring Data for Apache Geode
TIP: To learn more about `@EnableCachingDefinedRegions`, see the Spring Data for {apache-geode-name}
{spring-data-geode-docs}/#bootstrap-annotation-config-caching[documentation].
[[geode-samples-caching-inline-example-calculator-backend]]
@@ -491,7 +490,7 @@ the `latency` drops to zero (and *_cacheMiss_* is *_false_*):
image::{images-dir}/factorial-of-four-after.png[]
That is because the result (i.e. *24*) of `factorial(4)` is "cached" in Apache Geode (as well as persisted to
That is because the result (i.e. *24*) of `factorial(4)` is "cached" in {apache-geode-name} (as well as persisted to
the database; _write-through_) and therefore, the `CaculatorService.factorial(:int)` method is *not* called.
The result, however, is pulled from the cache, not the database.
@@ -532,6 +531,7 @@ and database consistent. While the database can serve as a fallback option for
will serve an important role in reducing the contention and load on the backend database.
As you have seen in this guide, the configuration of _Inline Caching_ is very simple to do with Spring Boot
for Apache Geode (SBDG) when using Spring's Cache Abstraction along with Apache Geode as the caching provider.
for {apache-geode-name} (SBDG) when using Spring's Cache Abstraction along with {apache-geode-name}
as the caching provider.
link:../index.html#geode-samples[Back to Samples]

86
spring-geode-docs/src/docs/asciidoc/guides/caching-look-aside.adoc
View File

@@ -1,5 +1,6 @@
[[geode-samples-caching-lookaside]]
= Look-Aside Caching with Spring
:apache-geode-name: Apache Geode
:apache-geode-version: {apache-geode-doc-version}
:apache-geode-docs: https://geode.apache.org/docs/guide/{apache-geode-version}
:apache-geode-javadoc: https://geode.apache.org/releases/latest/javadoc
@@ -19,15 +20,15 @@
This guide walks you through building a simple Spring Boot application
using {spring-framework-docs}/integration.html#cache[Spring's Cache Abstraction]
backed by Apache Geode as the caching provider for Look-Aside Caching.
backed by {apache-geode-name} as the caching provider for Look-Aside Caching.
It is assumed that the reader is familiar with the Spring _programming model_. No prior knowledge of Spring's
_Cache Abstraction_ or Apache Geode is required to utilize caching in your Spring Boot applications.
_Cache Abstraction_ or {apache-geode-name} is required to utilize caching in your Spring Boot applications.
Let's begin.
TIP: Refer to the link:../index.html#geode-caching-provider-look-aside-caching[Look-Aside Caching] section
in the link:../index.html#geode-caching-provider[Caching with Apache Geode or VMware Tanzu GemFire] chapter
in the link:../index.html#geode-caching-provider[Caching with {apache-geode-name}] chapter
in the reference documentation for more information.
[#index-link]
@@ -44,11 +45,11 @@ as well as improving efficiency by increasing throughput and reducing latency.
The fundamental premise of caching is, when given the same arguments, if a service call yields the same results
every time, then it is a good candidate for caching.
Indeed, if I am searching for a customer record by account number and the search always yields the same customer
for a given account number, then adding caching to the search operation will improve the overall user experience.
After all, the account number may be a form of customer identity. We can save compute resources by caching
the customer's information, which is especially useful if the customer's information is used in multiple workflows
of the application during the interactions with the customer.
Indeed, if I am searching for a customer record by account number and the search always yields the same customer for a
given account number, then adding caching to the search operation will improve the overall user experience. After all,
the account number may be a form of customer identity. We can save compute resources by caching the customer's
information, which is especially useful if the customer's information is used in multiple workflows of the application
during the interactions with the customer.
While there are different patterns of caching, the _**Look-Aside Caching**_ pattern is the most frequently used.
@@ -87,9 +88,10 @@ The _Look-Aside Caching_ pattern can be depicted in the following diagram:
image::{images-dir}/Look-Aside-Caching-Pattern.png[]
In the diagram above, we see that the caching provider (e.g. Apache Geode) is consulted first, #2, after the client
initiated the request, #1. If the result of the cacheable operation for the given input has already been computed
and stored in the cache (a _cache hit_), then the result is simply returned, #3, and passed back to the caller, #6.
In the diagram above, we see that the caching provider (e.g. {apache-geode-name}) is consulted first, #2, after the
client initiated the request, #1. If the result of the cacheable operation for the given input has already been
computed and stored in the cache (a _cache hit_), then the result is simply returned, #3, and passed back to the caller,
#6.
However, if the cacheable operation has never been invoked with the given input, or the previous computation of
the operation for the given input expired, or was evicted, then the cacheable operation is invoked (_cache miss_).
@@ -118,8 +120,8 @@ NOTE: See Spring Boot's documentation for a complete list of
[[geode-samples-caching-lookaside-example]]
== Example (with additional background)
To make the effects of Spring's _Cache Abstraction_ using Apache Geode as the cache provider apparent in
your application, we show how to enable and use caching with your application in a very small, simple example.
To make the effects of Spring's _Cache Abstraction_ using {apache-geode-name} as the cache provider apparent in your
application, we show how to enable and use caching with your application in a very small, simple example.
The example Spring Boot application implements a Counter Service, which simply maintains a collection of named counters.
The application provides a REST-ful Web interface to increment a counter, get the current cached count for a named
@@ -134,16 +136,16 @@ the door to a whole new set of problems (concurrency), usually at the expense of
always yield the desired results.
Opportunities for caching are often overlooked, yet is very effective at minimizing the over utilization of resources
by leveraging reuse. In an ever increasing Microservices based world, caching will become even more important
as it serves a very important role in the applications architecture, not the least of which is, resiliency.
by leveraging reuse. In an ever increasing Microservices based world, caching will become even more important as it
serves a very important role in the applications architecture, not the least of which is, resiliency.
Of course, you still must tune your cache. Most caches keep information in memory, and since memory is finite,
you must utilize strategies to manage memory effectively, such as eviction, expiration, or even Off-Heap
(i.e. native memory) for JVM-based caches. For example, evicting/expiring entries based on use (_Least Recently Used_,
or LRU) is 1 of many effective strategies.
Of course, you still must tune your cache. Most caches keep information in memory, and since memory is finite, you must
utilize strategies to manage memory effectively, such as eviction, expiration, or even Off-Heap (i.e. native memory) for
JVM-based caches. For example, evicting/expiring entries based on use (_Least Recently Used_, or LRU) is 1 of many
effective strategies.
Each caching provider's capabilities are different in this regard. The choice should not only be based on
what capabilities you need now, but capabilities (e.g. distributed compute, streaming) you may need in the future.
Each caching provider's capabilities are different in this regard. The choice should not only be based on what
capabilities you need now, but capabilities (e.g. distributed compute, streaming) you may need in the future.
So, choose wisely.
[[geode-samples-caching-lookaside-example-counterservice-application]]
@@ -171,11 +173,7 @@ With the `org.springframework.geode:spring-geode-starter` dependency on your app
----
And the `BootGeodeLookAsideCachingApplication` class annotated with `@SpringBootApplication`, you have everything you
need to begin using Spring's _Cache Abstraction_ in your application with Apache Geode as the caching provider.
TIP: You can switch from open source Apache Geode to Pivotal GemFire (PCC) very easily simply by changing
the artifactId from `spring-geode-starter` to `spring-gemfire-starter`. No configuration or code changes
are necessary.
need to begin using Spring's _Cache Abstraction_ in your application with {apache-geode-name} as the caching provider.
As an application developer, all you need do is focus on where in your application caching would be most beneficial.
@@ -210,8 +208,8 @@ the named counter.
Finally, we have a `@CacheEvict` annotated `resetCache(:String)` method, which will reset the named counter to 0
and evict the cache entry for the named counter.
TIP: Each of the Spring's Cache annotations can be replaced with the corresponding JSR-107 - JCache API annotations
as {spring-framework-docs}/integration.html#cache-jsr-107[documented here], and the application will work just the same.
TIP: Each of the Spring's Cache annotations can be replaced with the corresponding JSR-107 - JCache API annotations as
{spring-framework-docs}/integration.html#cache-jsr-107[documented here], and the application will work just the same.
[[geode-samples-caching-lookaside-example-counterservice-controller]]
=== CounterController
@@ -246,9 +244,8 @@ After running the `BootGeodeLookAsideCachingApplication` class, if you open a We
[[geode-samples-caching-lookaside-example-counterservice-configuration]]
=== Counter Service Configuration
While Spring Boot for Apache Geode/Pivotal GemFire (PCC), SBDG, takes care of enabling Spring's caching infrastructure
for you, configuring Apache Geode/Pivotal GemFire (PCC) as a caching provider, you still must define and declare
your individual caches.
While Spring Boot for {apache-geode-name}, SBDG, takes care of enabling Spring's caching infrastructure for you,
configuring {apache-geode-name} as a caching provider, you still must define and declare your individual caches.
No Spring caching provider is fully configured by Spring or Spring Boot for that matter. Part of the reason for this
is that there are many different ways to configure the caches.
@@ -268,12 +265,12 @@ include::{samples-dir}/caching/look-aside/src/main/java/example/app/caching/look
----
The only thing of real significance here is the `@EnableCachingDefinedRegions` annotation. This Spring Data
for Apache Geode/Pivotal GemFire (SDG) annotation is responsible for introspecting our Spring Boot application
on Spring container startup, identifying all the caching annotations (both Spring Cache annotations as wells JSR-107,
JCache annotations) used in our application components, and creating the appropriate caches.
for {apache-geode-name} (SDG) annotation is responsible for introspecting our Spring Boot application on Spring
container startup, identifying all the caching annotations (both Spring Cache annotations as wells JSR-107, JCache
annotations) used in our application components, and creating the appropriate caches.
If you were not using SDG's `@EnablingCachingDefinedRegions` annotation, then you would need to define the Region
using the equivalent _JavaConfig_:
If you were not using SDG's `@EnablingCachingDefinedRegions` annotation, then you would need to define the Region using
the equivalent _JavaConfig_:
."Counters" Region definition using JavaConfig
[source,java]
@@ -302,20 +299,21 @@ Or using XML:
<gfe:client-region id="Counters" shortcut="LOCAL"/>
----
In Apache Geode terminology, each cache identified in 1 of the caching annotations by name, will have an Apache Geode
In {apache-geode-name} terminology, each cache identified in 1 of the caching annotations by name, will have an {apache-geode-name}
Region created for it.
In our case, SBDG provides us a `ClientCache` instance by default, so we will be creating client `LOCAL` Regions.
The client "Counters" Region is `LOCAL` since we do not (yet) have a cluster of servers running.
However, it would be very simple to convert this application into using a client/server topology by simply starting
a cluster of servers.
However, it would be very simple to convert this application into using a client/server topology by simply starting a
cluster of servers.
[[geode-samples-caching-lookaside-example-counterservice-configuration-clientserver]]
==== Client/Server Configuration
To use the client/server topology, you need to start a cluster with 1 or more servers using the default configuration.
You can start the cluster using the GemFire/Geode Shell tool (_Gfsh_) and create the "Counters" Region on the servers.
You can start the cluster using the {apache-geode-name} Shell tool (_Gfsh_) and create the "Counters" Region
on the servers.
Of course, you technically do not even need to create the "Counters" Region on the server. The `@EnableClusterAware`
annotation is meta-annotated with SDG's `@EnableClusterConfiguration(..)` annotation, which will create the necessary
@@ -394,7 +392,7 @@ Region | size | 0
We will refer to the client/server approach further below, when running the example.
Refer to Apache Geode's documentation to learn more about the
Refer to {apache-geode-name}'s documentation to learn more about the
{apache-geode-docs}/topologies_and_comm/cs_configuration/chapter_overview.html[client/server topology].
Refer to SDG's documentation to learn more about
@@ -547,9 +545,9 @@ B | 2
As you have learned, Spring makes enabling and using caching in your application really easy.
With SBDG, using either Apache Geode or Pivotal GemFire as your caching provider in Spring's _Cache Abstraction_
is as easy as making sure `org.springframework.geode:spring-geode-starter` is on your application's classpath. You just
need to focus on areas of your application that would benefit from caching.
With SBDG, using {apache-geode-name} as your caching provider in Spring's _Cache Abstraction_ is as easy as making sure
`org.springframework.geode:spring-geode-starter` is on your application's classpath. You just need to focus on areas of
your application that would benefit from caching.
You have now successfully used the _**Look-Aside Caching**_ pattern in your Spring Boot application.

50
spring-geode-docs/src/docs/asciidoc/guides/caching-multi-site.adoc
View File

@@ -3,7 +3,6 @@
:apache-geode-version: {apache-geode-doc-version}
:apache-geode-docs: https://geode.apache.org/docs/guide/{apache-geode-version}
:apache-geode-javadoc: https://geode.apache.org/releases/latest/javadoc
:gemfire-name: VMware Tanzu GemFire
:geode-name: Apache Geode
:images-dir: ./images
:spring-boot-docs: https://docs.spring.io/spring-boot/docs/current/reference/html
@@ -35,7 +34,7 @@ on _Look-Aside Caching_ before continuing with this guide.
Let's begin.
TIP: Refer to the link:../index.html#geode-caching-provider-multi-site-caching[Multi-Site Caching] section
in the link:../index.html#geode-caching-provider[Caching with Apache Geode or VMware Tanzu GemFire] chapter
in the link:../index.html#geode-caching-provider[Caching with {geode-name}] chapter
in the reference documentation for more information.
[#index-link]
@@ -133,21 +132,21 @@ such as application service methods, it also provides an appropriate abstraction
provider_ implementation you want, matching the unique requirements (or SLAs) of your use case.
Various caching providers include, but are not limited to: `java.util.concurrent.ConcurrentMap`, {geode-name}, Caffeine,
Couchbase, Ehcache, Hazelcast, Infinispan, Redis, {gemfire-name} or any _JCache_ (JSR-107) provider implementation. See
the core Spring Framework's documentation on {spring-framework-docs}/integration.html#cache-store-configuration[Configuring the Cache Storage]
Couchbase, Ehcache, Hazelcast, Infinispan, Redis, or any _JCache_ (JSR-107) provider implementation. See the core Spring
Framework's documentation on {spring-framework-docs}/integration.html#cache-store-configuration[Configuring the Cache Storage]
along with Spring Boot's {spring-boot-docs}/spring-boot-features.html#boot-features-caching-provider[Supported Cache Providers]
for more details.
NOTE: Not only is it easy to swap the underlying _caching provider_ in the Spring-based code snippet above, it is also
a simple matter to change the underlying _System of Record_ (SOR), or persistent, data management technology given the
Spring Data _Repository_ interface is a common abstraction for persistent storage (e.g. JDBC, JPA or R2DBC for an RDBMS,
MongoDB for Document store, Neo4j for a Graph store, GemFire/Geode for a Key/Value store, and so on). Some data
MongoDB for Document store, Neo4j for a Graph store, {geode-name} for a Key/Value store, and so on). Some data
management technologies can be used as both a _System or Record_ (i.e. persistent data store) as well as a _Cache_,
e.g. {geode-name}.
TIP: See the Spring Boot for {geode-name} (SBDG) chapter on link:../index.html#geode-caching-provider[Caching]
for more information on how {geode-name} (or {gemfire-name}) can be used to enable different caching patterns
in your Spring Boot applications.
for more information on how {geode-name} can be used to enable different caching patterns in your Spring Boot
applications.
[[geode-samples-caching-multisite-wan-background]]
=== WAN Topology
@@ -159,13 +158,13 @@ topologies: client/server, peer-to-peer (P2P) and WAN, or a multi-site configura
The _Look-Aside Caching_ pattern is not only the least invasive pattern of caching, it can also be easily extended
or composed with other caching patterns, typically without any code changes to the application. Of course, this all
depends on the capabilities of the underlying _caching provider_, or more generally, data management technology.
With {geode-name} or {gemfire-name}, this is very easy.
With {geode-name}, this is very easy.
When _Look-Aside Caching_ is extended or combined with other caching patterns (e.g. _Inline_, _Near_, _Multi-Site_,
or a combination of), the value realized from your caching solution is greatly enhanced.
By implementing _Multi-Site Caching_ with {geode-name} or {gemfire-name}'s WAN topology and configuration, your
application's data is geographically distributed.
By implementing _Multi-Site Caching_ with {geode-name}'s WAN topology and configuration, your application's data is
geographically distributed.
image::{images-dir}/Multi-Site-Caching-Pattern.png[]
@@ -174,7 +173,7 @@ Intranet (VPN), or even over the Internet. This replication can be 1-way (_Acti
(_Active-Active_). By default, it uses asynchronous communication across sites. Guaranteed message delivery along with
persistent message queues can be configured. From a Spring Boot application's perspective, this simply appears as
_Look-Aside Caching_, but all the logistics of data replication and sharing between the sites over WAN is managed by
{geode-name} or {gemfire-name}.
{geode-name}.
You can imagine that having data redundantly distributed geographical is useful in Disaster Recovery (DR) situations.
However, _Multi-Site Caching_ has many other useful benefits.
@@ -289,9 +288,9 @@ include::{samples-dir}/caching/multi-site/src/main/java/example/app/caching/mult
----
The main Java class is annotated with `@SpringBootApplication` making it a proper Spring Boot application. Additionally,
we declare SDG's `@EnableCachingDefinedRegions` annotation to create {geode-name} (or {gemfire-name}) `Regions` to back
the caches used by the application (e.g. "CustomersByName"), which are declared on the application's components
(e.g. `CustomerService`) using Spring's caching annotations, such as `@Cacheable`.
we declare SDG's `@EnableCachingDefinedRegions` annotation to create {geode-name} `Regions` to back the caches used by
the application (e.g. "CustomersByName"), which are declared on the application's components (e.g. `CustomerService`)
using Spring's caching annotations, such as `@Cacheable`.
TIP: It is also possible to annotate your Spring application components with JSR-107, _JCache_ API annotations since
Spring recognizes _JCache_ annotations as well. See the {spring-framework-docs}/integration.html#cache-jsr-107[reference documentation]
@@ -335,7 +334,7 @@ TIP: Refer to the documentation on {apache-geode-docs}/topologies_and_comm/cs_co
as well as {apache-geode-docs}/topologies_and_comm/multi_site_configuration/chapter_overview.html[Multi-site (WAN) Configuration]
for more details.
Naturally, we use Spring Boot to configure and bootstrap an {geode-name} (or {gemfire-name}) server:
Naturally, we use Spring Boot to configure and bootstrap an {geode-name} server:
.`CacheServer` application
[source,java]
@@ -376,7 +375,7 @@ Each member in the cluster must have a unique name, therefore we set the `spring
serves to name our peer cache instance and member of the cluster. This is especially necessary when running the Locator
and CacheServer as standalone processes in the same cluster.
To allow us to connect to the cluster from _Gfsh_ (the GemFire/Geode Shell tool), we additionally configure the Manager
To allow us to connect to the cluster from _Gfsh_ ({geode-name} Shell tool), we additionally configure the Manager
port. Technically, the Manager allows any JMX compliant application (e.g. _JConsole_, _JVisualVM_, etc) to connect to
the cluster. The Manager, like the Locator, is an embedded service, which could also be configured to run as standalone
JVM process (recommended). By default, in most production {geode-name} clusters, the standalone Locators also serve as
@@ -466,8 +465,8 @@ talk about the final bit of configuration that enables _Multi-Site Caching_ with
==== `GatewaySender` and `GatewayReceiver` Configuration
The final bit of configuration configures a `GatewaySender` for sending `Region` events from this cluster
(i.e. cluster #1) to a remote cluster (e.g. cluster #2). {geode-name} (or {gemfire-name}) Gateways are the essential
component for enabling _Multi-Site Caching_ using a WAN topology:
(i.e. cluster #1) to a remote cluster (e.g. cluster #2). {geode-name} Gateways are the essential component for enabling
_Multi-Site Caching_ using a WAN topology:
.Gateway Sender & Receiver
[source,java]
@@ -515,11 +514,10 @@ using _Gfsh_.
[[geode-samples-caching-multisite-example-run]]
== Run the Example
For this exercise, it would be helpful to have an installation of {geode-name} (or {gemfire-name}) installed on
your system. Follow the instructions in the {apache-geode-docs}/prereq_and_install.html[User Guide] to get started.
For this exercise, it would be helpful to have an installation of {geode-name} installed on your system. Follow the
instructions in the {apache-geode-docs}/prereq_and_install.html[User Guide] to get started.
Once you have installed {geode-name} (or {gemfire-name}) and set your environment variables accordingly, you can start
_Gfsh_:
Once you have installed {geode-name} and set your environment variables accordingly, you can start _Gfsh_:
.Starting & Using Gfsh
[source,text]
@@ -1163,8 +1161,8 @@ not include the `Customer` application domain model class on the cluster servers
possible to deserialize an instance of `Customer` as a `Customer` on the servers in the cluster.
Not having to implement `java.io.Serializable` nor include your application domain model types on the servers' classpath
is actually a powerful feature of {geode-name} and {gemfire-name}. When no de/serialization strategy has been explicitly
configured, SBDG will configure {geode-name}'s PDX Serialization framework.
is actually a powerful feature of {geode-name}. When no de/serialization strategy has been explicitly configured, SBDG
will configure {geode-name}'s PDX Serialization framework.
PDX allows you to query objects in serialized form, without causing a deserialization, as long as you know the structure
of your application domain model types. Using PDX can be helpful in situations where your application domain model types
@@ -1181,8 +1179,8 @@ leave as an exercise for the curious reader.
== Summary
You have now just learned and witnessed first-hand the power of _Look-Aside Caching_ enhanced with _Multi-Site Caching_,
implemented with {geode-name} (or {gemfire-name}) WAN Gateway functionality. This is but a simple example. WAN Gateway
functionality can accommodate a wide-range of different use cases and complex configuration.
implemented with {geode-name} WAN Gateway functionality. This is but a simple example. WAN Gateway functionality can
accommodate a wide-range of different use cases and complex configuration.
Imagine if timely and accurate (i.e. "consistent") information is a major concern for your application use case
and your application is backed by an RDBMS for its _System of Record_ (SOR). How do you keep the remote database

4
spring-geode-docs/src/docs/asciidoc/guides/caching-near.adoc
View File

@@ -32,7 +32,7 @@ _Look-Aside Caching_ followed by the guide on _Inline Caching_, first, before co
Let's begin.
TIP: Refer to the link:../index.html#geode-caching-provider-near-caching[Near Caching] section
in the link:../index.html#geode-caching-provider[Caching with Apache Geode or VMware Tanzu GemFire] chapter
in the link:../index.html#geode-caching-provider[Caching with {apache-geode-name}] chapter
in the reference documentation for more information.
[#index-link]
@@ -168,7 +168,7 @@ include::{samples-dir}/caching/near/src/main/java/example/app/caching/near/serve
----
TIP: For more information on configurating and bootstrapping a small cluster of {apache-geode-name} servers using Spring Boot,
see link:../index.html#geode-cluster-configuration-bootstrapping[Running an {apache-geode-name} or Pivotal GemFire Cluster using Spring Boot].
see link:../index.html#geode-cluster-configuration-bootstrapping[Running an {apache-geode-name} cluster using Spring Boot].
[[geode-samples-caching-near-example-client-side]]
=== Client-side Configuration

182
spring-geode-docs/src/docs/asciidoc/guides/getting-started.adoc
View File

@@ -29,17 +29,17 @@ John Blum
:docinfodir: guides
This guide walks you through building and running a simple Spring Boot, Apache Geode `ClientCache` application
using the Spring Boot for Apache Geode (SBDG) framework. Later in this guide, we switch the application from
{apache-geode-website}[Apache Geode] to {pivotal-cloudcache-website}[Pivotal Cloud Cache] and deploy (i.e `_push_`)
This guide walks you through building and running a simple Spring Boot, {geode-name} `ClientCache` application
using the Spring Boot for {geode-name} (SBDG) framework. Later in this guide, we switch the application from
{apache-geode-website}[{geode-name}] to {pivotal-cloudcache-website}[Pivotal Cloud Cache] and deploy (i.e `_push_`)
the application up to {pivotal-cloudfoundry-website}[_Pivotal Platform_].
Specifically, you will:
1. Create a new "_Spring for Apache Geode_" project using _Spring Initializer_ at https://start.spring.io[start.spring.io].
1. Create a new "_Spring for {geode-name}_" project using _Spring Initializer_ at https://start.spring.io[start.spring.io].
Goto the <<geode-samples-getting-started-spring-initializer,Spring Initializer>> topic.
2. Then, we build a simple Spring Boot, Apache Geode `ClientCache` application that can persist data locally
in Apache Geode. Goto the <<spring-geode-samples-getting-started-build-app,Build App>> topic.
2. Then, we build a simple Spring Boot, {geode-name} `ClientCache` application that can persist data locally
in {geode-name}. Goto the <<spring-geode-samples-getting-started-build-app,Build App>> topic.
3. Next, we switch the application from running locally to using a client/server topology.
Goto the <<spring-geode-samples-getting-started-run-app-clientserver,Client/Server>> topic.
4. And finally, we deploy the application to _Pivotal Platform_ and bind our application to a provisioned
@@ -50,13 +50,10 @@ Our goal is to accomplish each step with _little to no code or configuration_ ch
NOTE: It is also possible to migrate from a Commercial, Managed environment (running in _Pivotal Platform_
using _Pivotal Cloud Cache_ (PCC)) back to an Open Source, Non-Managed environment (i.e. running with an externally
managed Apache Geode cluster).
managed {geode-name} cluster).
By the end of this guide, you should feel comfortable and ready to begin building Spring Boot applications using either
Apache Geode standalone or by deploying and running in _Pivotal Platform_ using _Pivotal Cloud Cache_ (PCC).
NOTE: {pivotal-cloudcache-website}[_Pivotal Cloud Cache_] (PCC) has replaced {pivotal-gemfire-website}[_Pivotal GemFire_]
as the new brand name.
{geode-name} standalone or by deploying and running in _Pivotal Platform_ using _Pivotal Cloud Cache_ (PCC).
Let's begin!
@@ -80,7 +77,7 @@ When creating the example app for this guide, we selected:
** _Artifact_: **crm**
** _Options_:
*** _Package Name_: **example.app.crm**
* _Dependencies_: Add "**Spring for Apache Geode**" by typing "_Geode_" into the "_Search dependencies to add_"
* _Dependencies_: Add "**Spring for {geode-name}**" by typing "_Geode_" into the "_Search dependencies to add_"
text field.
* (Optional) _Dependencies_: Add "_Spring Web_" to pull in `org.springframework.boot:spring-boot-starter-web`
if you want this Spring Boot application to be a Web application.
@@ -98,7 +95,7 @@ Your selections should look similar to:
image::{images-dir}/spring-initializer-screenshot.png[]
Be sure to click the "*+*" button next to the "_Spring for Apache Geode_" dependency to select and add it to
Be sure to click the "*+*" button next to the "_Spring for {geode-name}_" dependency to select and add it to
the generated project Maven POM file.
You can explore the contents of the generated project by pressing the `CTRL+SPACE` keys:
@@ -112,7 +109,7 @@ Download the ZIP file and unpack it to your desired working directory.
You can then use your favorite IDE (e.g. https://www.jetbrains.com/idea/[IntelliJ IDEA]
or https://spring.io/tools[Spring Tool Suite] (STS)) to open the generated project.
You are ready to begin developing your Spring Boot, Apache Geode `ClientCache` application.
You are ready to begin developing your Spring Boot, {geode-name} `ClientCache` application.
[[about-versions]]
.Versions
@@ -151,10 +148,10 @@ public class CrmApplication {
}
----
Additionally, in the project Maven POM file, we see the "_Spring Boot for Apache Geode_" (SBDG) dependency
Additionally, in the project Maven POM file, we see the "_Spring Boot for {geode-name}_" (SBDG) dependency
(`org.springframework.geode:spring-geode-starter)`:
.Spring Boot for Apache Geode dependency
.Spring Boot for {geode-name} dependency
[source,xml]
[subs="verbatim,attributes"]
----
@@ -164,9 +161,9 @@ Additionally, in the project Maven POM file, we see the "_Spring Boot for Apache
</dependency>
----
With the _Spring Boot for Apache Geode_ dependency (i.e. `org.springframework.geode:spring-geode-starter`)
With the _Spring Boot for {geode-name}_ dependency (i.e. `org.springframework.geode:spring-geode-starter`)
on the application classpath along with the main Java class being a proper Spring Boot application, this application
will startup and run as an Apache Geode `ClientCache` application:
will startup and run as an {geode-name} `ClientCache` application:
.Application log output
[source,txt]
@@ -634,17 +631,17 @@ Process finished with exit code 0
----
First, you see the JVM bootstrap Spring Boot, which in turn runs our `CrmApplication` and also auto-configures
and bootstraps an Apache Geode `ClientCache` instance. Most of the output comes from Apache Geode.
and bootstraps an {geode-name} `ClientCache` instance. Most of the output comes from {geode-name}.
The application falls straight through because it is not doing anything interesting, and technically, because there are
no non-daemon Threads (e.g. Socket Thread listening on HTTP port 8080 in the case of Web applications running
an embedded Servlet Container like Apache Tomcat) that prevents the "main" Java Thread from exiting immediately.
[[spring-geode-samples-getting-started-build-app]]
== Build a Spring Boot, Apache Geode `ClientCache` application
== Build a Spring Boot, {geode-name} `ClientCache` application
Our Spring Boot application is a simple _Customer Relationship Management_ (CRM) application that allows users
to persist `Customer` data in Apache Geode and lookup `Customers` by name.
to persist `Customer` data in {geode-name} and lookup `Customers` by name.
[[spring-geode-samples-getting-started-build-app-model]]
=== `Customer` class
@@ -660,15 +657,15 @@ include::{samples-dir}/intro/getting-started/src/main/java/example/app/crm/model
The CRM application defines a `Customer` in terms of an identifier (i.e. `Long id`) and a name (i.e. `String name`).
Both fields are required.
Additionally, we map `Customer` objects to the "_/Customers_" Region using Spring Data for Apache Geode's (SDG)
Additionally, we map `Customer` objects to the "_/Customers_" Region using Spring Data for {geode-name}'s (SDG)
{spring-data-geode-javadoc}/org/springframework/data/gemfire/mapping/annotation/Region.html[`@Region`] annotation.
The `@Region` annotation tells Spring Data where to persist and access `Customer` objects in Apache Geode. It is
The `@Region` annotation tells Spring Data where to persist and access `Customer` objects in {geode-name}. It is
basically equivalent to JPA's `@javax.persistence.Table` annotation.
Additionally, we annotate the `Long id` field with Spring Data's `@org.springframework.data.annotation.Id` annotation.
This designates the `id` field as the identifier, or in Apache Geode's case, the "key" since a Region is a key/value
store. In fact, Apache Geode's {apache-geode-javadoc}/org/apache/geode/cache/Region.html[`Region`] interface
This designates the `id` field as the identifier, or in {geode-name}'s case, the "key" since a Region is a key/value
store. In fact, {geode-name}'s {apache-geode-javadoc}/org/apache/geode/cache/Region.html[`Region`] interface
implements the `java.uti.Map` interface making it a `Map` data structure.
We use https://projectlombok.org/[Project Lombok] to simply the implementation of the `Customer` class.
@@ -683,7 +680,7 @@ subjective topic on whether to use Lombok in production code. We have no opinio
=== `CustomerRepository` interface
Now that we have defined a basic model for managing customer data, we can create a Spring Data `CrudRepository` used by
our application to persist `Customer` objects to Apache Geode. This same _Repository_ can be used to lookup, or query
our application to persist `Customer` objects to {geode-name}. This same _Repository_ can be used to lookup, or query
`Customers` by name.
.`CustomerRepository` interface
@@ -697,7 +694,7 @@ that enables an application to perform basic CRUD (i.e. CREATE, READ, UPDATE, DE
data access operations on a persistent entity (e.g. `Customer`).
TIP: Review the Spring Data Commons Reference Guide for more details on {spring-data-commons-docs}/#repositories[Working with Spring Data Repositories]
and Spring Data for Apache Geode's (SDG) {spring-data-geode-docs}/#gemfire-repositories[extension and implementation]
and Spring Data for {geode-name}'s (SDG) {spring-data-geode-docs}/#gemfire-repositories[extension and implementation]
of Spring Data Commons Repository Abstraction.
[[spring-geode-samples-getting-started-build-app-controller]]
@@ -731,8 +728,8 @@ for accessing the CRM application via a Web client (e.g. Web browser).
|===
NOTE: If you did not enable the Web components by adding the Spring Web dependency to your application classpath, then
no worries, we will still be inspecting the application's effects on Apache Geode using _Gfsh_ (Apache Geode & Pivotal
GemFire's shell tool). Of course, you can just add the `org.springframework.boot:spring-boot-starter-web` dependency
no worries, we will still be inspecting the application's effects on {geode-name} using _Gfsh_ ({geode-name}'s
command-line shell tool). Of course, you can just add the `org.springframework.boot:spring-boot-starter-web` dependency
to your Maven POM file as well.
[[spring-geode-samples-getting-started-build-app-configuration]]
@@ -755,7 +752,7 @@ responsibility as the application developer. One example is Region configuratio
There are many ways to configure a Region and it varies significantly from application Use Case to application Use Case.
First, there are different data management policies (e.g. `PARTITION` or `REPLICATE`) that might be applicable depending
on the type of data you store in Apache Geode (e.g. Transactional vs. Reference data). You might need different
on the type of data you store in {geode-name} (e.g. Transactional vs. Reference data). You might need different
Eviction and Expiration policies depending on your user base or workloads. Some data is suited for Off-Heap memory.
Depending on the data management policy of the Region (e.g. `PARTITION`) you can configure additional per node and total
Region memory usage restrictions, collocate the Region with another Region for use in JOIN Queries, etc.
@@ -765,7 +762,7 @@ especially during development. So, while SBDG may not provide implicit _auto-co
this does not mean you are left to figure it all out by yourself (e.g. Region configuration).
During development, if you don't care specifically "_how_" your data is stored and you just want to simply and rapidly
iterate, putting and getting data into and out of Apache Geode, then SBDG can help.
iterate, putting and getting data into and out of {geode-name}, then SBDG can help.
The first thing we will do is annotate our application configuration with SDG's `@EnableEntityDefinedRegions` annotation
and set the `basePackageClasses` attribute to our `Customer` class:
@@ -775,7 +772,7 @@ and set the `basePackageClasses` attribute to our `Customer` class:
----
@Configuration
@EnableEntityDefinedRegions(basePackageClasses = Customer.class)
public class CustomerConfiguration { ... }
public class CustomerConfiguration { }
----
Using the `@EnableEntityDefinedRegions` annotation is basically equivalent to the JPA entity scan and Hibernate's
@@ -798,8 +795,11 @@ _JavaConfig_, like so:
.Using Spring JavaConfig
[source,java]
----
@Bean("Customers")
public ClientRegionFactoryBean<Long, Customer> customersRegion(GemFireCache gemfireCache) {
@Configuration
class GeodeConfiguration {
@Bean("Customers")
public ClientRegionFactoryBean<Long, Customer> customersRegion(GemFireCache gemfireCache) {
ClientRegionFactoryBean<Long, Customer> clientRegion = new ClientRegionFactoryBean<>();
@@ -807,6 +807,7 @@ public ClientRegionFactoryBean<Long, Customer> customersRegion(GemFireCache gemf
clientRegion.setShortcut(ClientRegionShortcut.PROXY);
return clientRegion;
}
}
----
@@ -815,19 +816,19 @@ You can also use Spring XML:
.Using Spring XML
[source,xml]
----
<gfe:client-region id="Customers" shortcut="PROXY">
<gfe:client-region id="Customers" shortcut="PROXY"/>
----
[[spring-geode-samples-getting-started-build-app-configuration-cluster]]
==== Configure the Application to be Cluster-Aware
The final bit of configuration helps determine whether the client application is by itself or whether a cluster of
Apache Geode servers are available to manage the application's data.
{geode-name} servers are available to manage the application's data.
During development, you might be iteratively and rapidly developing inside your IDE, debugging and testing new functions
locally and then switch to a client/server environment for further integration testing.
Apache Geode requires 1) all client Regions that send data to/from the cluster be `*PROXY` Regions and 2) that a
{geode-name} requires 1) all client Regions that send data to/from the cluster be `*PROXY` Regions and 2) that a
server-side Region by the same name exists in the cluster.
Switching the data management policy for all client Regions' from `*PROXY` to `LOCAL` when pulling your application code
@@ -841,7 +842,7 @@ pushing back up to the client/server environment is a tedious and error-prone ta
----
@Configuration
@EnableClusterAware
public class CustomerConfiguration { ... }
public class CustomerConfiguration { }
----
The nearly equivalent alternative to `@EnableClusterAware` is:
@@ -851,7 +852,7 @@ The nearly equivalent alternative to `@EnableClusterAware` is:
----
@Configuration
@EnableEntityDefinedRegions(clientRegionShortcut = ClientRegionShortcut.LOCAL)
public class CustomerConfiguration { ... }
public class CustomerConfiguration { }
----
If you switch to a client/server topology, then you would need to remember to change the `clientRegionShortcut` to
@@ -887,7 +888,7 @@ to our main `@SpringBootApplication` class:
include::{samples-dir}/intro/getting-started/src/main/java/example/app/crm/CrmApplication.java[tags=runner]
----
The runner creates a new `Customer` "_JonDoe_", persists "_JonDoe_" to Apache Geode in the "_/Customers_" client `LOCAL`
The runner creates a new `Customer` "_JonDoe_", persists "_JonDoe_" to {geode-name} in the "_/Customers_" client `LOCAL`
Region, runs an OQL query to lookup "_JonDoe_" by name using a wildcard query with the LIKE operator and argument
"_%Doe_", then asserts that the result is correct.
@@ -942,7 +943,7 @@ Customer was [Customer(name=JonDoe)]
SBDG, with the help of `@EnableEntityDefinedRegions` and `@EnableClusterAware`, along with Spring Data, has already done
quite a bit of work for us:
1. SBDG _auto-configured_ a `ClientCache` instance required to use Apache Geode in the application.
1. SBDG _auto-configured_ a `ClientCache` instance required to use {geode-name} in the application.
2. The `@EnableEntityDefinedRegion` annotation created the required "_/Customers_" client Region from our `Customer`
entity class.
3. SBDG _auto-configured_ the Spring Data Repository infrastructure and supplied an implementation for
@@ -1019,7 +1020,7 @@ image::{images-dir}/customer-service-application-jondoe.png[]
[[spring-geode-samples-getting-started-run-app-clientserver]]
== Run the Application in a Client/Server Topology
Now that we have a simple Spring Boot, Apache Geode `ClientCache` application running locally inside our IDE, we want to
Now that we have a simple Spring Boot, {geode-name} `ClientCache` application running locally inside our IDE, we want to
expand on this bit and switch to a client/server topology.
Although we are not quite ready to move to a managed cloud platform environment, like _Pivotal Platform_ (formerly
@@ -1029,11 +1030,11 @@ Without persistence, we would lose all our data if the client application were s
in-memory. Additionally, by maintaining the data locally, other client applications, or even other instances of our
existing application (e.g. in a Microservices landscape) would not be able to use this data, which is useless!
To switch to a client/server topology, we need to first configure and bootstrap an Apache Geode cluster.
To switch to a client/server topology, we need to first configure and bootstrap an {geode-name} cluster.
The Example Code for this Guide already provides the necessary Geode shell script (_Gfsh_) to start a cluster:
.Gfsh shell script to start an Apache Geode cluster
.Gfsh shell script to start an {geode-name} cluster
[source,txt]
----
include::{samples-dir}/intro/getting-started/src/main/resources/geode/bin/start-cluster.gfsh[]
@@ -1049,7 +1050,7 @@ gfsh> run --file=@SBDG_HOME@/spring-geode-samples/intro/getting-started/src/main
NOTE: Be sure to change the `@SBDG_HOME@` placeholder variable with the location of your cloned copy of SBDG.
The _Gfsh_ shell script starts an Apache Geode cluster with 1 _Locator_ and 2 _Servers_.
The _Gfsh_ shell script starts an {geode-name} cluster with 1 _Locator_ and 2 _Servers_.
The output from the shell script will look similar to:
@@ -1256,7 +1257,7 @@ the best data management policy and organization for transactional data. The "_
on our 2 _Servers_, "ServerOne" and "ServerTwo".
WARNING: You must have redundancy (and optionally, persistence) configured in your cluster to prevent (complete)
data loss, which forms the basis for high-availability (HA) in Apache Geode and Pivotal Cloud Cache (PCC).
data loss, which forms the basis for high-availability (HA) in {geode-name} and Pivotal Cloud Cache (PCC).
We can query "_JonDoe_" from _Gfsh_:
@@ -1348,10 +1349,10 @@ Once again, SBDG is providing you with tremendous power and convenience that you
While there are very apparent things happening, there are also a few non-apparent things happening as well.
In addition to the aforementioned things in the last section, we are now benefiting from:
1. SBDG appropriately configured and relied on Apache Geode internal features to connect the client to the cluster.
1. SBDG appropriately configured and relied on {geode-name} internal features to connect the client to the cluster.
2. Configuration metadata for our application's required client Regions (e.g. "_/Customers_") was sent to the cluster
and created on the servers to leverage the client/server topology.
3. SBDG _auto-configured_ PDX, Apache Geode's highly powerful Serialization framework and alternative to
3. SBDG _auto-configured_ PDX, {geode-name}'s highly powerful Serialization framework and alternative to
_Java Serialization_.
Once we migrate to a managed cloud platform environment, we'll see the full effects of SBDG's _auto-configuration_
@@ -1361,14 +1362,14 @@ at play.
*****
Anytime you need to send data over the network, persist or overflow data to disk, your objects need to be serializable.
SBDG employs Apache Geode's {apache-geode-docs}/developing/data_serialization/gemfire_pdx_serialization.html[PDX Serialization]
SBDG employs {geode-name}'s {apache-geode-docs}/developing/data_serialization/gemfire_pdx_serialization.html[PDX Serialization]
framework so your application entity classes do not need to implement `java.io.Serializable`. In other cases,
implementing `java.io.Serializable` may not even be possible if your application domain types are composed of types
from 3rd party libraries for which you have no control over.
Perhaps you don't want to use _Java Serialization_ given the inherit overhead of the _Java Serialization_ format.
In any case, using Apache Geode PDX Serialization is ideal if you have large number of objects forming a complex graph
In any case, using {geode-name} PDX Serialization is ideal if you have large number of objects forming a complex graph
where missing a type that needs to be serialized is easy to do. PDX allows you to query data in serialized form
and even allows non-Java clients (e.g. native clients written in C#/C++) to access the same data.
@@ -1402,7 +1403,7 @@ If SBDG's Auto-configuration for PDX was disabled, such as by doing:
[source,java]
----
@SpringBootApplication(exclude = PdxSerializationAutoConfiguration.class)
class CrmApplication { ... }
class CrmApplication { }
----
Then you would have encountered a serialization Exception:
@@ -1491,7 +1492,7 @@ gfsh> create region --name=Example --type=PARTITION ...
While this can be scripted and the script can be checked into source control (a definitive plus) the same as
the application code, you sill need to create matching Regions on the client, for which there is no assistance
provided by Apache Geode or Pivotal Cloud Cache.
provided by {geode-name} or Pivotal Cloud Cache.
This is why `@EnableClusterAware` will help you be much more productive during development. After you are ready to
promote the application to the next environment, it is a simple matter to {apache-geode-docs}/tools_modules/gfsh/command-pages/export.html#topic_mdv_jgz_ck[export]
@@ -1530,33 +1531,6 @@ See link:../index.html#cloudfoundry-geode[Hybrid Cloud Environments] for more de
Once you have acquired a _Pivotal Platform_ environment and installed the required tools (e.g. CF CLI), then you can
package the application and deploy (i.e. "_push_") it to _Pivotal Platform_.
Before we package the application, we must switch the "_Spring (Boot) for Apache Geode_" dependency in our application
Maven POM file from:
.Spring Boot for Apache Geode dependency
[source,xml]
[subs="verbatim,attributes"]
----
<dependency>
<groupId>org.springframework.geode</groupId>
<artifactId>spring-geode-starter</artifactId>
<version>{version}</version>
</dependency>
----
To:
.Spring Boot for Pivotal GemFire (a.k.a. Pivotal Cloud Cache (PCC)) dependency
[source,xml]
[subs="verbatim,attributes"]
----
<dependency>
<groupId>org.springframework.geode</groupId>
<artifactId>spring-gemfire-starter</artifactId>
<version>{version}</version>
</dependency>
----
TIP: See the link:../index.html#geode-gemfire-switch[Appendix] for more details on making the switch.
.Matching Client/Server Versions
@@ -1582,6 +1556,10 @@ Use the following table to make sure your client and server versions are correct
| {spring-boot-data-geode-version} | {spring-boot-version} | {pivotal-gemfire-artifact-version} | {apache-geode-artifact-version} | {pivotal-cloudcache-docs}/product-snapshot.html[{pivotal-cloudcache-artifact-version}]
| 1.4.x | 2.4.x | NA | 1.13.x | https://docs.pivotal.io/p-cloud-cache/1-13-beta/product-snapshot.html[1.13.x+]
| 1.3.x | 2.3.x | 9.10.x | 1.12.x | https://docs.pivotal.io/p-cloud-cache/1-12/product-snapshot.html[1.12.x+]
| 1.2.x | 2.2.x | 9.8.x | 1.9.x | https://docs.pivotal.io/p-cloud-cache/1-8/product-snapshot.html[1.8.x+]
| 1.1.x | 2.1.x | 9.5.x | 1.6.x | https://resources.docs.pivotal.io/pdfs/p-cloud-cache-1.5.pdf[1.5.x+]
@@ -1592,26 +1570,10 @@ TIP: Your Spring Boot application is the client and the cloud environment, hosti
is the server-side.
*****
.Acquiring {cloudcache-name} Bits
*****
In order to acquire the Pivotal Cloud Cache (PCC) / Pivotal GemFire bits used by your Spring Boot application, you must
sign up and register on https://network.pivotal.io/[Pivotal Network] (a.k.a. "_PivNet_").
This should include instructions on how to configure your application Maven POM file with the necessary `<repository>`
declaration for acquiring the _Pivotal Cloud Cache_ / Pivotal GemFire bits pulled in by the
`org.springframework.geode:spring-gemfire-starter` SBDG application dependency as well as the necessary settings in
`~/.m2/settings.xml` to authenticate and access the Pivotal Commercial Repository server.
This is absolutely necessary since Pivotal Cloud Cache (PCC) / Pivotal GemFire bits are not available in _Maven Central_.
You can also find more details on acquiring the bits in the Pivotal GemFire
https://gemfire.docs.pivotal.io/{pivotal-gemfire-version}/gemfire/getting_started/installation/obtain_gemfire_maven.html[documentation].
*****
.Required Spring Boot Actuator Bits
*****
As of Apache Geode 1.9 and Pivotal GemFire 9.8, upon which Pivotal Cloud Cache (PCC) 1.8 is {pivotal-cloudcache-docs}/product-snapshot.html[based],
both GemFire and Geode require and declare Micrometer on the classpath as a compile-time dependency.
As of {geode-name} 1.9, upon which {cloudcache-name} (PCC) 1.8 is {pivotal-cloudcache-docs}/product-snapshot.html[based],
{geode-name} requires you to declare Micrometer on the classpath as a compile-time dependency.
Technically, the Micrometer bits are pulled in by `org.apache.geode:geode-core:1.9.0` and the Micrometer version
is determined by the version of Spring Boot you are using:
@@ -1626,7 +1588,7 @@ is determined by the version of Spring Boot you are using:
As of this writing, due to an https://github.com/cloudfoundry/java-buildpack-metric-writer/issues/6[Issue]
in the _Java buildpack_ for CloudFoundry, you are also required to put Spring Boot Actuator on the classpath
for your Spring Boot application using Apache Geode or PCC:
for your Spring Boot application using {geode-name} or PCC:
.Declaring Spring Boot Actuator on the application classpath
[source.xml]
@@ -1634,7 +1596,7 @@ for your Spring Boot application using Apache Geode or PCC:
----
<dependency>
<groupId>org.springframework.geode</groupId>
<artifactId>spring-gemfire-starter-actuator</artifactId>
<artifactId>spring-geode-starter-actuator</artifactId>
<version>{version}</version>
</dependency>
----
@@ -1655,15 +1617,15 @@ OUT at o.s.c.a.TypeMappedAnnotation.getValue(TypeMappedAnnotation.java:403)
...
----
On the other hand, if you try to exclude Micrometer from the Apache Geode or PCC dependency, for example:
On the other hand, if you try to exclude Micrometer from the {geode-name} or PCC dependency, for example:
.Excluding the Micrometer dependency from `spring-gemfire-starter`
.Excluding the Micrometer dependency from `spring-geode-starter`
[source,txt]
[subs="verbatim,attributes"]
----
<dependency>
<groupId>org.springframework.geode</groupId>
<artifactId>spring-gemfire-starter</artifactId>
<artifactId>spring-geode-starter</artifactId>
<version>{version}</version>
<exclusions>
<exclusion>
@@ -1675,9 +1637,9 @@ On the other hand, if you try to exclude Micrometer from the Apache Geode or PCC
----
Then, you will get past the _Java buildpack_ Exception, but you will encounter another Exception when Spring Boot
tries to bootstrap Apache Geode on startup:
tries to bootstrap {geode-name} on startup:
.Exception in Apache Geode
.Exception in {geode-name}
[source,txt]
----
[OUT] Caused by: java.lang.NoClassDefFoundError: io/micrometer/core/instrument/MeterRegistry
@@ -1686,7 +1648,7 @@ tries to bootstrap Apache Geode on startup:
Therefore, you must include Spring Boot Actuator on your Spring Boot application classpath when deploying
to Pivotal Platform and using Pivotal Cloud Cache (PCC). Again, the easiest way to do that is include the
`org.springframework.geode:spring-gemfire-starter-actuator` dependency on your application classpath.
`org.springframework.geode:spring-geode-starter-actuator` dependency on your application classpath.
*****
Additionally, and specifically when deploying to _Pivotal Platform_, we will create a `manifest.yml` file
@@ -1993,7 +1955,7 @@ id | name
1 | JonDoe
----
You successfully deployed the CRM, Spring Boot Apache Geode/Pivotal Cloud Cache `ClientCache` application to the cloud!
You successfully deployed the CRM, Spring Boot {geode-name}/Pivotal Cloud Cache `ClientCache` application to the cloud!
In this final incarnation of our CRM, Spring Boot application, SBDG yet again handled many different concerns for us
so we did not need to. This is in addition to all the things mentioned above when running the application locally
@@ -2020,7 +1982,7 @@ specifically cover the details of doing so in this guide.
Running in a Hybrid Cloud Environment specifically means deploying your CRM, Spring Boot `ClientCache` application to
a managed cloud platform environment, such as Pivotal Platform, but connect the app to an externally managed
Apache Geode or Pivotal GemFire cluster, i.e. the GemFire/Geode cluster is running and managed off platform.
{geode-name} cluster, i.e. the {geode-name} cluster is running and managed off platform.
NOTE: As of this writing, the inverse is also being explored, running your Spring Boot applications off platform,
but connecting those apps to managed data services (e.g. Pivotal Cloud Cache (PCC)) on platform.
@@ -2036,10 +1998,10 @@ link:../index.html#cloudfoundry-geode[here].
[[spring-geode-samples-getting-started-summary]]
== Summary
In this guide, we saw first-hand the power of Spring Boot for Apache Geode (SBDG) when building Apache Geode powered
In this guide, we saw first-hand the power of Spring Boot for {geode-name} (SBDG) when building {geode-name} powered
Spring Boot applications.
Apache Geode can truly make your Spring Boot applications highly resilient to failures, highly available, performant
{geode-name} can truly make your Spring Boot applications highly resilient to failures, highly available, performant
(i.e. high throughput and low latency), without sacrificing consistency, which is paramount to any data intensive
application.
@@ -2047,7 +2009,7 @@ SBDG handles a lot of low-level application concerns so you do not have to. You
can remain on building the application to meet your customers' needs, collect feedback, iterate rapidly, and realize
the value proposition sooner.
Indeed, our intended goal is to make developing Apache Geode applications with Spring, and Spring Boot in particular,
Indeed, our intended goal is to make developing {geode-name} applications with Spring, and Spring Boot in particular,
a highly productive and enjoyable experience.
We hope you enjoy!