Edit Appendix and replace all references to 'Apache Geode' using a documentation variable.
Remove all references to 'GemFire'.
This commit is contained in:
John Blum
@@ -1,8 +1,9 @@
|
||||
[[appendix]]
|
||||
== Appendix
|
||||
:geode-name: {apache-geode-name}
|
||||
|
||||
The following appendices provide additional help while developing Spring Boot applications backed by Apache Geode
|
||||
or Pivotal GemFire.
|
||||
|
||||
The following appendices provide additional help while developing Spring Boot applications backed by {geode-name}.
|
||||
|
||||
_Table of Contents_
|
||||
|
||||
@@ -24,9 +25,9 @@ include::configuration-properties.adoc[leveloffset=+1]
|
||||
[[geode-auto-configuration-disable]]
|
||||
=== Disabling Auto-configuration
|
||||
|
||||
If you would like to disable the _auto-configuration_ of any feature provided by Spring Boot for Apache Geode
|
||||
or Pivotal GemFire, then you can specify the _auto-configuration_ class in the `exclude` attribute
|
||||
of the `@SpringBootApplication` annotation, as follows:
|
||||
If you would like to disable the _auto-configuration_ of any feature provided by Spring Boot for {geode-name}, then you
|
||||
can specify the _auto-configuration_ class in the `exclude` attribute of the `@SpringBootApplication` annotation,
|
||||
as follows:
|
||||
|
||||
.Disable Auto-configuration of PDX
|
||||
[source,java]
|
||||
@@ -58,7 +59,7 @@ public class MySpringBootApplication {
|
||||
[[geode-auto-configuration-disable-classes]]
|
||||
==== Complete Set of Auto-configuration Classes
|
||||
|
||||
The current set of _auto-configuration_ classes in Spring Boot for Apache Geode & Pivotal GemFire (SBDG) include:
|
||||
The current set of _auto-configuration_ classes in Spring Boot for {geode-name} include:
|
||||
|
||||
* `CacheNameAutoConfiguration`
|
||||
* `CachingProviderAutoConfiguration`
|
||||
@@ -77,160 +78,36 @@ The current set of _auto-configuration_ classes in Spring Boot for Apache Geode
|
||||
* `SslAutoConfiguration`
|
||||
|
||||
[[geode-gemfire-switch]]
|
||||
=== Switch from Apache Geode to Pivotal Cloud Cache (a.k.a. Pivotal GemFire)
|
||||
=== Switching from {geode-name} to Pivotal GemFire or Pivotal Cloud Cache (PCC)
|
||||
|
||||
First, understand that {pivotal-gemfire-website}[Pivotal GemFire] is being succeeded by {pivotal-cloudcache-website}[Pivotal Cloud Cache] (PCC).
|
||||
Therefore, all references to Pivotal GemFire implies for Pivotal Cloud Cache (PCC) as well.
|
||||
WARNING: This section is now deprecated! Spring Boot for {geode-name} (SBDG) no longer provides the
|
||||
`spring-gemfire-starter` and related starter modules. As of SBDG 1.4, SBDG is based on {geode-name} 1.13. Standalone
|
||||
GemFire bits based on {geode-name} are no longer being released by VMware, Inc. after GemFire 9.10. GemFire 9.10 was
|
||||
based on {geode-name} 1.12, and as such, SBDG can longer properly support standalone GemFire bits (i.e. <= 9.10).
|
||||
|
||||
When it comes to Spring's support, whether you are developing with Open Source Software (OSS) {apache-geode-website}[Apache Geode]
|
||||
or developing for {pivotal-cloudcache-website}[Pivotal Cloud Cache], Spring has you covered.
|
||||
|
||||
At a strategic-level, this means:
|
||||
|
||||
1. From _Open Source Software_ (e.g. Apache Geode) to _Commercial_ (e.g. Pivotal Cloud Cache)
|
||||
2. From _Non-Managed Environments_ (e.g. Standalone, Externally Managed) to _Managed Environments_ (e.g. Pivotal Platform)
|
||||
3. With _**little**_ to _**no code or configuration**_ changes necessary. It just works!
|
||||
|
||||
You may also migrate your Spring Boot applications away from Pivotal Platform using the commercial software offering,
|
||||
Pivotal Cloud Cache, and switch back to Open Source Apache Geode running in a standalone, externally managed environment.
|
||||
|
||||
SBDG will never lock you in! It is, and always will be, your choice!
|
||||
|
||||
Technically, this means to go from Apache Geode to Pivotal Cloud Cache (PCC), you must change 2 things.
|
||||
|
||||
First, you must switch the dependency from `spring-geode-starter` to `spring-gemfire-starter`:
|
||||
|
||||
.Maven POM with Spring Boot for Apache Geode
|
||||
[source,xml]
|
||||
[subs="verbatim,attributes"]
|
||||
----
|
||||
<dependency>
|
||||
<groupId>org.springframework.geode</groupId>
|
||||
<artifactId>spring-geode-starter</artifactId>
|
||||
<version>{revnumber}</version>
|
||||
</dependency>
|
||||
----
|
||||
|
||||
.Gradle build file with Spring Boot for Apache Geode
|
||||
[source,groovy]
|
||||
[subs="verbatim,attributes"]
|
||||
----
|
||||
dependencies {
|
||||
compile 'org.springframework.geode:spring-geode-starter:{revnumber}'
|
||||
}
|
||||
----
|
||||
|
||||
To:
|
||||
|
||||
.Maven POM with Spring Boot for Pivotal GemFire
|
||||
[source,xml]
|
||||
[subs="verbatim,attributes"]
|
||||
----
|
||||
<dependency>
|
||||
<groupId>org.springframework.geode</groupId>
|
||||
<artifactId>spring-gemfire-starter</artifactId>
|
||||
<version>{revnumber}</version>
|
||||
</dependency>
|
||||
----
|
||||
|
||||
.Gradle build file with Spring Boot for Pivotal GemFire
|
||||
[source,groovy]
|
||||
[subs="verbatim,attributes"]
|
||||
----
|
||||
dependencies {
|
||||
compile 'org.springframework.geode:spring-gemfire-starter:{revnumber}'
|
||||
}
|
||||
----
|
||||
|
||||
Second, to obtain the commercial Pivotal Cloud Cache (PCC) or Pivotal GemFire bits, you must declare the appropriate
|
||||
repository declaration in your Maven POM or Gradle build file:
|
||||
|
||||
.Maven Repository definition to acquire PCC or Pivotal GemFire bits
|
||||
[source,xml]
|
||||
----
|
||||
<repositories>
|
||||
<repository>
|
||||
<id>pivotal-repository</id>
|
||||
<name>Pivotal Commercial Repository</name>
|
||||
<url>https://commercial-repo.pivotal.io/data3/gemfire-release-repo/gemfire</url>
|
||||
</repository>
|
||||
</repositories>
|
||||
----
|
||||
|
||||
.Gradle Repository definition to acquire PCC or Pivotal GemFire bits
|
||||
[source,groovy]
|
||||
----
|
||||
repositories {
|
||||
maven { url 'https://commercial-repo.pivotal.io/data3/gemfire-release-repo/gemfire' }
|
||||
}
|
||||
----
|
||||
|
||||
Accessing the Pivotal Commercial Repository requires you to sign up and authenticate with https://network.pivotal.io/[Pivotal Network]
|
||||
(a.k.a. "_PivNet_"). Once you have signed up and successfully created your account, you can use your username
|
||||
and password to configure access to the server in your Maven settings (i.e. ~/.m2/settings.xml):
|
||||
|
||||
.~/.m2/settings.xml
|
||||
[source,xml]
|
||||
----
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<settings xmlns="http://maven.apache.org/SETTINGS/1.1.0"
|
||||
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
|
||||
xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.1.0 https://maven.apache.org/xsd/settings-1.1.0.xsd">
|
||||
|
||||
<servers>
|
||||
<server>
|
||||
<id>pivotal-repository</id>
|
||||
<username>yourUsername</username>
|
||||
<password>yourPassword</password>
|
||||
</server>
|
||||
</servers>
|
||||
|
||||
</settings>
|
||||
----
|
||||
|
||||
TIP: For more details on acquiring the Pivotal Cloud Cache (PCC) or Pivotal GemFire bits, see Pivotal GemFire's
|
||||
https://gemfire.docs.pivotal.io/{pivotal-gemfire-version}/gemfire/getting_started/installation/obtain_gemfire_maven.html[documentation].
|
||||
When using the `spring-gemfire-starter`, you do not need to declare the Pivotal GemFire dependencies noted in
|
||||
the documentation. The `spring-gemfire-starter` does that for you! You only need to declare the repository
|
||||
and configure your settings.
|
||||
|
||||
To go back, simple change `spring-gemfire-starter` to `spring-geode-starter`.
|
||||
|
||||
Done!
|
||||
|
||||
It should just work without any code or configuration changes and if this is not the case, for whatever reason, then we
|
||||
will work to correct it, short of any feature differences between Pivotal Cloud Cache (PCC) that cannot be accomplished
|
||||
with Apache Geode itself, of course.
|
||||
|
||||
Spring Boot's _auto-configuration_ and _convention over configuration_ approach tries to determine the runtime
|
||||
environment in order to handle infrastructure logistics so you do not have to. This is true inside or outside
|
||||
of a managed environment so that we can provide users with a consistent and reliable experience without all the hassle
|
||||
and issues that arise by switching environments in the first place. Switching environments is especially common as you
|
||||
migrate your Spring Boot applications from DEV to TEST, followed by STAGING, and finally, to PRODUCTION.
|
||||
|
||||
Of course, it will nearly always be easier to "run" Apache Geode as a "managed" service inside Pivotal Platform (PCF)
|
||||
using Pivotal Cloud Cache (PCC) than it will be to manage an externally run Apache Geode cluster, especially if your
|
||||
Use Cases require maximum performance and high availability. We highly recommend this approach when and where possible,
|
||||
but it is still your choice.
|
||||
NOTE: What was "_Pivotal GemFire_" has now been rebranded as {pivotal-gemfire-website}[VMware Tanzu GemFire] and what
|
||||
was Pivotal Cloud Cache (PCC) running on Pivotal CloudFoundry (PCF) has been rebranded as
|
||||
{pivotal-cloudcache-website}[VMware Tanzu GemFire for VMs]
|
||||
and {pivotal-cloudfoundry-website}[VMware Tanzu Application Service (TAS)], respectively.
|
||||
|
||||
[[geode-cluster-configuration-bootstrapping]]
|
||||
=== Running an Apache Geode or Pivotal GemFire cluster using Spring Boot from your IDE
|
||||
=== Running an {geode-name} cluster using Spring Boot from your IDE
|
||||
|
||||
As described in <<geode-clientcache-applications>>, it is possible to configure and run a small Apache Geode
|
||||
or Pivotal GemFire cluster from inside your IDE using Spring Boot. This is extremely helpful during development
|
||||
since it allows you to manually spin up, test and debug your applications quickly and easily.
|
||||
As described in <<geode-clientcache-applications>>, it is possible to configure and run a small {geode-name} cluster
|
||||
from inside your IDE using Spring Boot. This is extremely helpful during development since it allows you to manually
|
||||
spin up, test and debug your applications quickly and easily.
|
||||
|
||||
Spring Boot for Apache Geode/Pivotal GemFire includes such a class:
|
||||
Spring Boot for {geode-name} includes such a class:
|
||||
|
||||
.Spring Boot application class used to configure and bootstrap an Apache Geode/Pivotal GemFire server
|
||||
.Spring Boot application class used to configure and bootstrap an {geode-name} server
|
||||
[source,java]
|
||||
----
|
||||
include::{docs-src-dir}/org/springframework/geode/docs/example/app/server/SpringBootApacheGeodeCacheServerApplication.java[tags=class]
|
||||
----
|
||||
|
||||
This class is a proper Spring Boot application that can be used to configure and bootstrap multiple Apache Geode
|
||||
or Pivotal GemFire servers and joining them together to form a small cluster simply by modifying
|
||||
the runtime configuration of this class ever so slightly.
|
||||
This class is a proper Spring Boot application that can be used to configure and bootstrap multiple {geode-name} servers
|
||||
and joining them together to form a small cluster simply by modifying the runtime configuration of this class ever so
|
||||
slightly.
|
||||
|
||||
Initially you will want to start a single, primary server with the embedded Locator and Manager service.
|
||||
|
||||
@@ -241,8 +118,8 @@ route data requests directly to the server hosting the data (a.k.a. single-hop a
|
||||
is partitioned/sharded across servers in the cluster. Locator Pools include support for load balancing connections
|
||||
and handling automatic fail-over in the event of failed connections, among other things.
|
||||
|
||||
The Manager service enables you to connect to this server using _Gfsh_ (the Apache Geode and Pivotal GemFire
|
||||
{apache-geode-docs}/tools_modules/gfsh/chapter_overview.html[shell tool]).
|
||||
The Manager service enables you to connect to this server using _Gfsh_ (the {geode-name}
|
||||
{apache-geode-docs}/tools_modules/gfsh/chapter_overview.html[command-line shell tool]).
|
||||
|
||||
To start our primary server, create a run configuration in your IDE for the `SpringBootApacheGeodeCacheServerApplication`
|
||||
class with the following, recommended JRE command-line options:
|
||||
@@ -421,9 +298,8 @@ Client Connections : 0
|
||||
|
||||
Now, let's start some additional servers to scale-out our cluster.
|
||||
|
||||
To do so, you simply need to vary the name of the members we will add to our cluster as peers. Apache Geode
|
||||
and Pivotal GemFire require that the members in a cluster be named and the names of each member in the cluster
|
||||
be unique.
|
||||
To do so, you simply need to vary the name of the members we will add to our cluster as peers. {geode-name} requires
|
||||
that the members in a cluster be named and the names of each member in the cluster be unique.
|
||||
|
||||
Additionally, since we are running multiple instances of our `SpringBootApacheGeodeCacheServerApplication` class,
|
||||
which also embeds a `CacheServer` instance enabling cache clients to connect, we need to be careful to vary our
|
||||
@@ -446,7 +322,7 @@ run profile configuration:
|
||||
Notice that we explicitly activated the "_clustered_" Spring profile, which enables the configuration provided
|
||||
in the nested `ClusteredConfiguration` class while disabling the `LonerConfiguration` class.
|
||||
|
||||
This `ClusteredConfiguration` class is also annotated with `@UseLocators`, which sets the GemFire/Geode `locators`
|
||||
This `ClusteredConfiguration` class is also annotated with `@UseLocators`, which sets the {geode-name} `locators`
|
||||
property to "_localhost[10334]_". By default, it assumes the Locator process/service is running on "_locahost_",
|
||||
listening on the default Locator port of "_10334_". You can of course adjust your Locators endpoint if your Locators
|
||||
are running elsewhere in your network by using the "locators" attribute of the `@UseLocators` annotation.
|
||||
@@ -464,7 +340,7 @@ used by "_ServerTwo_". The default `CacheServer` port is "40404". If we had no
|
||||
"_ServerTwo_" we would have hit a `java.net.BindException`.
|
||||
|
||||
TIP: Both the `spring.data.gemfire.name` and `spring.data.gemfire.cache.server.port` properties are well-known properties
|
||||
used by SDG to dynamically configure GemFire/Geode using a Spring Boot `application.properties` file
|
||||
used by SDG to dynamically configure {geode-name} using a Spring Boot `application.properties` file
|
||||
or Java System properties. You can find these properties in the Annotation Javadoc in SDG's Annotation-based
|
||||
Configuration model. For instance, the `spring.data.gemfire.cache.server.port` property is documented
|
||||
{spring-data-geode-javadoc}/org/springframework/data/gemfire/config/annotation/CacheServerApplication.html#port--[here].
|
||||
@@ -548,47 +424,42 @@ Running : true
|
||||
Client Connections : 0
|
||||
----
|
||||
|
||||
Congratulations! You just started a small Apache Geode/Pivotal GemFire cluster, with 3 members, using Spring Boot
|
||||
from inside your IDE.
|
||||
Congratulations! You just started a small {geode-name} cluster, with 3 members, using Spring Boot from inside your IDE.
|
||||
|
||||
It is pretty simple to build and run a Spring Boot, Apache Geode/Pivotal GemFire, `ClientCache` application
|
||||
that connects to this cluster. Simply include and use Spring Boot for Apache Geode/Pivotal GemFire, ;-).
|
||||
It is pretty simple to build and run a Spring Boot, {geode-name} `ClientCache` application that connects to this cluster.
|
||||
Simply include and use Spring Boot for {geode-name}.
|
||||
|
||||
[[geode-testing]]
|
||||
=== Testing
|
||||
|
||||
https://github.com/spring-projects/spring-test-data-geode[Spring Test for Apache Geode & Pivotal GemFire] is a new,
|
||||
soon to be released and upcoming project to help developers write both _Unit_ and _Integration Tests_
|
||||
when using either Apache Geode or Pivotal GemFire in a Spring context.
|
||||
https://github.com/spring-projects/spring-test-data-geode[Spring Test for {geode-name}] is a new, soon to be released
|
||||
and upcoming project to help developers write both _Unit_ and _Integration Tests_ when using {geode-name} in a Spring
|
||||
context.
|
||||
|
||||
In fact, the entire {github-url}/tree/master/spring-geode-autoconfigure/src/test/java/org/springframework/geode/boot/autoconfigure[test suite]
|
||||
in Spring Boot for Apache Geode & Pivotal GemFire is based on this project.
|
||||
in Spring Boot for {geode-name} is based on this project.
|
||||
|
||||
All Spring projects integrating with either Apache Geode or Pivotal GemFire will use this new test framework for all
|
||||
their testing needs, making this new test framework for Apache Geode and Pivotal GemFire a proven and reliable solution
|
||||
for all your Apache Geode/Pivotal GemFire application testing needs when using Spring as well.
|
||||
All Spring projects integrating with {geode-name} will use this new test framework for all their testing needs, making
|
||||
this new test framework for {geode-name} a proven and reliable solution for all your {geode-name} application testing
|
||||
needs when using Spring as well.
|
||||
|
||||
Later on, this reference guide will include and dedicate an entire chapter on testing.
|
||||
|
||||
[[geode-examples]]
|
||||
=== Examples
|
||||
|
||||
The definitive source of truth on how to best use Spring Boot for Apache Geode & Pivotal GemFire (or Pivotal Cloud Cache
|
||||
(PCC)) is to refer to the <<geode-samples,Samples>>.
|
||||
|
||||
Refer to the Pivotal Cloud Cache (PCC), https://github.com/pivotal-cf/PCC-Sample-App-PizzaStore[Pizza Store],
|
||||
Spring Boot application for an example of how to use Spring Boot for Pivotal GemFire (SBDG) in a `ClientCache`
|
||||
application interfacing with PCC.
|
||||
The definitive source of truth on how to best use Spring Boot for {geode-name} is to refer to
|
||||
the <<geode-samples,Samples>>.
|
||||
|
||||
Additionally, you may refer to the https://github.com/jxblum/temperature-service[Temperature Service], Spring Boot
|
||||
application, which implements a Temperature Sensor and Monitoring, Internet of Things (IOT) example. The example uses
|
||||
SBDG to showcase Apache Geode CQ, Function Implementations/Executions and positions Apache Geode as a _caching provider_
|
||||
in Spring's Cache Abstraction. It is a working, sophisticated and complete example, and is highly recommended
|
||||
as a good starting point for real-world use cases.
|
||||
application implementing a Temperature Sensor and Monitoring, Internet of Things (IOT) example. The example uses SBDG
|
||||
to showcase {geode-name} CQ, Function Implementations/Executions and positions {geode-name} as a _caching provider_
|
||||
in Spring's Cache Abstraction. It is a working, sophisticated and complete example, and is highly recommended as a good
|
||||
starting point for real-world use cases.
|
||||
|
||||
You may also refer to the https://github.com/jxblum/contacts-application/tree/master/boot-example[boot-example]
|
||||
from the _Contact Application_ Reference Implementation (RI) for Spring Data for Apache Geode & Pivotal GemFire
|
||||
(SDG) as yet another example.
|
||||
from the _Contact Application_ Reference Implementation (RI) for Spring Data for {geode-name} (SDG) as yet another
|
||||
example.
|
||||
|
||||
[[references]]
|
||||
=== References
|
||||
@@ -596,8 +467,7 @@ from the _Contact Application_ Reference Implementation (RI) for Spring Data for
|
||||
1. Spring Framework {spring-framework-docs}[Reference Guide] | {spring-framework-javadoc}[Javadoc]
|
||||
2. Spring Boot {spring-boot-docs-html}[Reference Guide] | {spring-boot-javadoc}[Javadoc]
|
||||
3. Spring Data Commons {spring-data-commons-docs-html}[Reference Guide] | {spring-data-commons-javadoc}[Javadoc]
|
||||
4. Spring Data for Apache Geode {spring-data-geode-docs-html}[Reference Guide] | {spring-data-geode-javadoc}[Javadoc]
|
||||
5. Spring Session for Apache Geode {spring-session-data-gemfire-docs}[Reference Guide] | {spring-session-data-gemfire-javadoc}[Javadoc]
|
||||
6. Spring Test for Apache Geode {spring-test-data-gemfire-website}[README]
|
||||
7. Apache Geode {apache-geode-docs}[User Guide] | {apache-geode-javadoc}[Javadoc]
|
||||
8. Pivotal GemFire {pivotal-gemfire-docs}[User Guide] | {pivotal-gemfire-javadoc}[Javadoc]
|
||||
4. Spring Data for {geode-name} {spring-data-geode-docs-html}[Reference Guide] | {spring-data-geode-javadoc}[Javadoc]
|
||||
5. Spring Session for {geode-name} {spring-session-data-gemfire-docs}[Reference Guide] | {spring-session-data-gemfire-javadoc}[Javadoc]
|
||||
6. Spring Test for {geode-name} {spring-test-data-gemfire-website}[README]
|
||||
7. {geode-name} {apache-geode-docs}[User Guide] | {apache-geode-javadoc}[Javadoc]
|
||||
|
||||
Reference in New Issue
Block a user