diff --git a/spring-geode-docs/src/docs/asciidoc/_includes/appendix.adoc b/spring-geode-docs/src/docs/asciidoc/_includes/appendix.adoc index dc239de3..384b60ee 100644 --- a/spring-geode-docs/src/docs/asciidoc/_includes/appendix.adoc +++ b/spring-geode-docs/src/docs/asciidoc/_includes/appendix.adoc @@ -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"] ----- - - org.springframework.geode - spring-geode-starter - {revnumber} - ----- - -.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"] ----- - - org.springframework.geode - spring-gemfire-starter - {revnumber} - ----- - -.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] ----- - - - pivotal-repository - Pivotal Commercial Repository - https://commercial-repo.pivotal.io/data3/gemfire-release-repo/gemfire - - ----- - -.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] ----- - - - - - - pivotal-repository - yourUsername - yourPassword - - - - ----- - -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 <>, 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 <>, 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 <>. - -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 <>. 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]