From 8f869c39955c8ee9934c0af2139f3b3940a3d06f Mon Sep 17 00:00:00 2001 From: John Blum Date: Mon, 19 Aug 2019 20:05:10 -0700 Subject: [PATCH] Edit the wording in 'Building ClientCache Applications' that describes local development vs. the client/server architecture to clarify the meaning and intent. Resolves gh-41. --- .../asciidoc/clientcache-applications.adoc | 60 ++++++++++++------- 1 file changed, 38 insertions(+), 22 deletions(-) diff --git a/spring-geode-docs/src/docs/asciidoc/clientcache-applications.adoc b/spring-geode-docs/src/docs/asciidoc/clientcache-applications.adoc index 3d967b17..9e47a0a1 100644 --- a/spring-geode-docs/src/docs/asciidoc/clientcache-applications.adoc +++ b/spring-geode-docs/src/docs/asciidoc/clientcache-applications.adoc @@ -1,19 +1,31 @@ [[geode-clientcache-applications]] == Building ClientCache Applications -This first, opinionated option Spring Boot for Apache Geode & Pivotal GemFire gives you out-of-the-box -is a {apache-geode-javadoc}/org/apache/geode/cache/client/ClientCache.html[ClientCache] instance, -simply by declaring either Spring Boot for Apache Geode or Pivotal GemFire on your application classpath. +The first, opinionated option provided to you by Spring Boot for Apache Geode & Pivotal GemFire (SBDG) out-of-the-box is +a {apache-geode-javadoc}/org/apache/geode/cache/client/ClientCache.html[ClientCache] instance, simply by declaring +either Spring Boot for Apache Geode or Spring Boot for Pivotal GemFire on your application classpath. -It is assumed that most developers using Spring Boot to build applications backed by either Apache Geode -or Pivotal GemFire will be building Spring cache client applications deployed in an Apache Geode/Pivotal GemFire -{apache-geode-docs}/topologies_and_comm/cs_configuration/chapter_overview.html[Client/Server topology]. This is -the most common and traditional arrangement employed by most application system architectures. +It is assumed that most application developers using Spring Boot to build applications backed by either Apache Geode +or Pivotal GemFire will be building cache client applications deployed in an Apache Geode or Pivotal GemFire +{apache-geode-docs}/topologies_and_comm/cs_configuration/chapter_overview.html[Client/Server topology]. +A client/server topology is the most common and traditional architecture employed by enterprise applications. -For example, build your Spring Boot, Apache Geode/Pivotal GemFire, `ClientCache` application with either -the `spring-geode-starter` or `spring-gemfire-starter` on your application's classpath, and then: +For example, you can begin building a Spring Boot, Apache Geode or Pivotal GemFire, `ClientCache` application +with either the `spring-geode-starter` or `spring-gemfire-starter` on your application's classpath: -.Spring Boot, Apache Geode/Pivotal GemFire ClientCache Application +.Spring Boot for Apache Geode on the application classpath +[source,xml] +---- + + org.springframework.geode + spring-geode-starter + +---- + +Then, you configure and bootstrap your Spring Boot, Apache Geode `ClientCache` application with the following +main application class: + +.Spring Boot, Apache Geode `ClientCache` Application [source,java] ---- @SpringBootApplication @@ -25,24 +37,28 @@ public SpringBootApacheGeodeClientCacheApplication { } ---- -Your application now has a `ClientCache` instance, which can connect to an Apache Geode/Pivotal GemFire server, -running on `localhost`, listening on the default `CacheServer` port of `40404`, by default. +Your application now has a `ClientCache` instance, which is able to connect to an Apache Geode or Pivotal GemFire server +running on `localhost`, listening on the default `CacheServer` port `40404`. -However, the `ClientCache` instance does *not* require a GemFire/Geode sever (i.e. `CacheServer`) to be running -in order to use the `ClientCache` instance. It is perfectly valid to create a cache client and perform local -data access operations on `LOCAL` Regions. +By default, an Apache Geode or Pivotal GemFire server (i.e. `CacheServer`) must be running in order to use +the `ClientCache` instance. However, it is perfectly valid to create a `ClientCache` instance and perform +data access operations using `LOCAL` Regions. This is very useful during development. -Later on, when needed, you can expand your Spring Boot, `ClientCache` application into a fully functional client/server -architecture by changing the client Region's {apache-geode-javadoc}/org/apache/geode/cache/client/ClientRegionShortcut.html[data policy] -from `LOCAL` to `PROXY` or `CACHING_PROXY`, and send/receive data to/from 1 or more servers, respectively. +TIP: To develop with `LOCAL` Regions, you only need to define your cache Regions with the +{apache-geode-javadoc}/org/apache/geode/cache/client/ClientRegionShortcut.html#LOCAL[`ClientRegionShortcut.LOCAL`] +data management policy. + +When you are ready to switch from your local development environment (IDE) to a client/server architecture in a managed +environment, you simply change the data management policy of the client Region from `LOCAL` back to the default `PROXY`, +or even a `CACHING_PROXY`, which will cause the data to be sent/received to/from 1 or more servers, respectively. TIP: Compare and contrast the above configuration with Spring Data for Apache Geode/Pivotal GemFire's {spring-data-geode-docs-html}/#bootstrap-annotation-config-geode-applications[approach]. -It is uncommon to ever need a direct reference to the `ClientCache` instance injected into your application components -(e.g. `@Service` or `@Repository` beans defined in the Spring context) whether you are configuring additional -GemFire/Geode objects (e.g. Regions, Indexes, etc) or simply using those objects indirectly in your applications. -However, it is also possible to do if and when needed. +It is uncommon to ever need a direct reference to the `ClientCache` instance provided by SBDG and injected into your +application components (e.g. `@Service` or `@Repository` beans defined in a Spring `ApplicationContext`) whether you +are configuring additional GemFire/Geode objects (e.g. Regions, Indexes, etc) or simply using those objects indirectly +in your applications. However, it is also possible to do so if and when needed. For example, perhaps you want to perform some additional initialization in a Spring Boot {spring-boot-javadoc}/org/springframework/boot/ApplicationRunner.html[ApplicationRunner] on startup: