From 546aa298f810101afcdda61bbeddd773a3fd12fd Mon Sep 17 00:00:00 2001 From: John Blum Date: Fri, 18 Sep 2020 16:11:39 -0700 Subject: [PATCH] Edit Sample Guides and replace all references to 'Apache Geode' using a documentation variable. Remove all references to 'GemFire'. Fix compiler syntax errors in example code snippets. --- .../docs/asciidoc/guides/boot-actuator.adoc | 11 +- .../asciidoc/guides/boot-configuration.adoc | 27 ++- .../docs/asciidoc/guides/boot-security.adoc | 17 +- .../docs/asciidoc/guides/caching-inline.adoc | 42 ++-- .../asciidoc/guides/caching-look-aside.adoc | 86 ++++----- .../asciidoc/guides/caching-multi-site.adoc | 50 +++-- .../docs/asciidoc/guides/caching-near.adoc | 4 +- .../docs/asciidoc/guides/getting-started.adoc | 182 +++++++----------- 8 files changed, 187 insertions(+), 232 deletions(-) diff --git a/spring-geode-docs/src/docs/asciidoc/guides/boot-actuator.adoc b/spring-geode-docs/src/docs/asciidoc/guides/boot-actuator.adoc index 0bef985a..489d27d4 100644 --- a/spring-geode-docs/src/docs/asciidoc/guides/boot-actuator.adoc +++ b/spring-geode-docs/src/docs/asciidoc/guides/boot-actuator.adoc @@ -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. diff --git a/spring-geode-docs/src/docs/asciidoc/guides/boot-configuration.adoc b/spring-geode-docs/src/docs/asciidoc/guides/boot-configuration.adoc index eb21117b..60200f37 100644 --- a/spring-geode-docs/src/docs/asciidoc/guides/boot-configuration.adoc +++ b/spring-geode-docs/src/docs/asciidoc/guides/boot-configuration.adoc @@ -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]] diff --git a/spring-geode-docs/src/docs/asciidoc/guides/boot-security.adoc b/spring-geode-docs/src/docs/asciidoc/guides/boot-security.adoc index 3c38c542..e3669dc8 100644 --- a/spring-geode-docs/src/docs/asciidoc/guides/boot-security.adoc +++ b/spring-geode-docs/src/docs/asciidoc/guides/boot-security.adoc @@ -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-app.com/message[https://security-app. Replace `` 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. diff --git a/spring-geode-docs/src/docs/asciidoc/guides/caching-inline.adoc b/spring-geode-docs/src/docs/asciidoc/guides/caching-inline.adoc index 3776326a..13251d4e 100644 --- a/spring-geode-docs/src/docs/asciidoc/guides/caching-inline.adoc +++ b/spring-geode-docs/src/docs/asciidoc/guides/caching-inline.adoc @@ -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] diff --git a/spring-geode-docs/src/docs/asciidoc/guides/caching-look-aside.adoc b/spring-geode-docs/src/docs/asciidoc/guides/caching-look-aside.adoc index a6ba1d2e..0ecd4280 100644 --- a/spring-geode-docs/src/docs/asciidoc/guides/caching-look-aside.adoc +++ b/spring-geode-docs/src/docs/asciidoc/guides/caching-look-aside.adoc @@ -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: ---- -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. diff --git a/spring-geode-docs/src/docs/asciidoc/guides/caching-multi-site.adoc b/spring-geode-docs/src/docs/asciidoc/guides/caching-multi-site.adoc index 674bdc7e..e0b59d8b 100644 --- a/spring-geode-docs/src/docs/asciidoc/guides/caching-multi-site.adoc +++ b/spring-geode-docs/src/docs/asciidoc/guides/caching-multi-site.adoc @@ -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 diff --git a/spring-geode-docs/src/docs/asciidoc/guides/caching-near.adoc b/spring-geode-docs/src/docs/asciidoc/guides/caching-near.adoc index 5a9ed496..a33e8ada 100644 --- a/spring-geode-docs/src/docs/asciidoc/guides/caching-near.adoc +++ b/spring-geode-docs/src/docs/asciidoc/guides/caching-near.adoc @@ -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 diff --git a/spring-geode-docs/src/docs/asciidoc/guides/getting-started.adoc b/spring-geode-docs/src/docs/asciidoc/guides/getting-started.adoc index 8b30b478..7a5d03db 100644 --- a/spring-geode-docs/src/docs/asciidoc/guides/getting-started.adoc +++ b/spring-geode-docs/src/docs/asciidoc/guides/getting-started.adoc @@ -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 <> topic. -2. Then, we build a simple Spring Boot, Apache Geode `ClientCache` application that can persist data locally -in Apache Geode. Goto the <> topic. +2. Then, we build a simple Spring Boot, {geode-name} `ClientCache` application that can persist data locally +in {geode-name}. Goto the <> topic. 3. Next, we switch the application from running locally to using a client/server topology. Goto the <> 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 ---- -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 customersRegion(GemFireCache gemfireCache) { +@Configuration +class GeodeConfiguration { + + @Bean("Customers") + public ClientRegionFactoryBean customersRegion(GemFireCache gemfireCache) { ClientRegionFactoryBean clientRegion = new ClientRegionFactoryBean<>(); @@ -807,6 +807,7 @@ public ClientRegionFactoryBean customersRegion(GemFireCache gemf clientRegion.setShortcut(ClientRegionShortcut.PROXY); return clientRegion; + } } ---- @@ -815,19 +816,19 @@ You can also use Spring XML: .Using Spring XML [source,xml] ---- - + ---- [[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"] ----- - - org.springframework.geode - spring-geode-starter - {version} - ----- - -To: - -.Spring Boot for Pivotal GemFire (a.k.a. Pivotal Cloud Cache (PCC)) dependency -[source,xml] -[subs="verbatim,attributes"] ----- - - org.springframework.geode - spring-gemfire-starter - {version} - ----- - 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 `` -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: ---- org.springframework.geode - spring-gemfire-starter-actuator + spring-geode-starter-actuator {version} ---- @@ -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"] ---- org.springframework.geode - spring-gemfire-starter + spring-geode-starter {version} @@ -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!