diff --git a/spring-geode-docs/src/docs/asciidoc/clientcache-applications.adoc b/spring-geode-docs/src/docs/asciidoc/clientcache-applications.adoc index 4ea94827..9c53ebba 100644 --- a/spring-geode-docs/src/docs/asciidoc/clientcache-applications.adoc +++ b/spring-geode-docs/src/docs/asciidoc/clientcache-applications.adoc @@ -93,17 +93,17 @@ public SpringBootApacheGeodeClientCacheApplication { What if you want to build an embedded, peer `Cache` application instead? Perhaps you need an actual peer cache member, configured and bootstrapped with Spring Boot, along with the ability -to join this member to a (possibly) existing cluster (of data servers) as a peer. Well, you can do that too. +to join this member to an existing cluster (of data servers) as a peer node. Well, you can do that too. Remember the 2nd goal in Spring Boot's {spring-boot-docs-html}/#getting-started-introducing-spring-boot[documentation]: > _Be opinionated out of the box but get out of the way quickly as requirements start to diverge from the defaults._ It is the 2nd part, "_get out of the way quickly as requirements start to diverge from the defaults_" -that I refer to here. +that we refer to here. If your application requirements demand you use Spring Boot to configure and bootstrap an embedded, peer `Cache` -Apache Geode or Pivotal GemFire application, then simply declare your intentions with either SDG's +Apache Geode or Pivotal GemFire application, then simply declare your intention with either SDG's {spring-data-geode-javadoc}/org/springframework/data/gemfire/config/annotation/PeerCacheApplication.html[`@PeerCacheApplication`] annotation, or alternatively, if you need to enable connections from `ClientCache` apps as well, use the SDG {spring-data-geode-javadoc}/org/springframework/data/gemfire/config/annotation/CacheServerApplication.html[`@CacheServerApplication`] annotation: @@ -113,7 +113,7 @@ or alternatively, if you need to enable connections from `ClientCache` apps as w ---- @SpringBootApplication @CacheServerApplication(name = "MySpringBootApacheGeodeCacheServerApplication") -public SpringBootApacheGeodeCacheServerApplication { +public class SpringBootApacheGeodeCacheServerApplication { public static void main(String[] args) { SpringApplication.run(SpringBootApacheGeodeCacheServerApplication.class, args); @@ -122,7 +122,7 @@ public SpringBootApacheGeodeCacheServerApplication { ---- TIP: An Apache Geode/Pivotal GemFire "server" is not necessarily a "`CacheServer`" capable of serving cache clients. -It is merely a peer member in the GemFire/Geode cluster (a.k.a. distributed system) that stores and manages data. +It is merely a peer member node in a GemFire/Geode cluster (a.k.a. distributed system) that stores and manages data. By explicitly declaring the `@CacheServerApplication` annotation, you are telling Spring Boot that you do not want the default, `ClientCache` instance, but rather an embedded, peer `Cache` instance with a `CacheServer` component, @@ -140,7 +140,7 @@ shell tool: @CacheServerApplication(name = "SpringBootApacheGeodeCacheServerApplication") @EnableLocator @EnableManager -public SpringBootApacheGeodeCacheServerApplication { +public class SpringBootApacheGeodeCacheServerApplication { public static void main(String[] args) { SpringApplication.run(SpringBootApacheGeodeCacheServerApplication.class, args); @@ -273,7 +273,7 @@ Then, modify the `SpringBootApacheGeodeCacheServerApplication` class to connect ---- @SpringBootApplication @CacheServerApplication(name = "MySpringBootApacheGeodeCacheServerApplication", locators = "localhost[11235]") -public SpringBootApacheGeodeCacheServerApplication { +public class SpringBootApacheGeodeCacheServerApplication { public static void main(String[] args) { SpringApplication.run(SpringBootApacheGeodeClientCacheApplication.class, args); @@ -281,7 +281,7 @@ public SpringBootApacheGeodeCacheServerApplication { } ---- -TIP: Notice I configured the `SpringBootApacheGeodeCacheServerApplication` class, `@CacheServerApplication` annotation, +TIP: Notice I configured the `SpringBootApacheGeodeCacheServerApplication` class, `@CacheServerApplication` annotation's `locators` property with the host and port (i.e. "_localhost[11235]_") on which I started my _Locator_ using _Gfsh_. After running your Spring Boot, Apache Geode `CacheServer` application again, and then running `list members` in _Gfsh_, @@ -328,7 +328,7 @@ Plus, this is useful for rapidly prototyping, testing and debugging your entire, and system architecture, all right from the comfort and familiarity of your IDE of choice. No additional tooling (e.g. _Gfsh_) or knowledge is required to get started quickly and easily. -Just _build_ and _run_ it! +Just _build_ and _run_! TIP: Be careful to vary your port numbers for the embedded services, like the `CacheServer`, _Locators_ and _Manager_, especially if you start multiple instances, otherwise you will run into a `java.net.BindException` @@ -352,19 +352,21 @@ pooled system resources (i.e. Memory, CPU and Disk). A Locator maintains metada enable capabilities like single-hop data access, routing data access operations to the data node in the cluster maintaining the data of interests. A Locator also maintains load information for servers in the cluster, which enables the load to be uniformly distributed across the cluster while also providing fail-over services to a redundant member -if the primary fails. A Locator provides many more benefit and you are encouraged to read +if the primary fails. A Locator provides many more benefits and you are encouraged to read the {apache-geode-docs}/configuring/running/running_the_locator.html[documentation] for more details. -As shown above, a Locator service can be embedded in either a peer `Cache` or `CacheServer`, Spring Boot application +As shown above, a Locator service can be embedded within either a peer `Cache` or `CacheServer`, Spring Boot application using the SDG `@EnableLocator` annotation: .Embedded Locator Service [source,java] ---- -@EnableLocator -@CacheServerApplication @SpringBootApplication -class SpringBootCacheServerWithEmbeddedLocatorApplication { ... } +@CacheServerApplication +@EnableLocator +class SpringBootCacheServerWithEmbeddedLocatorApplication { + // ... +} ---- However, it is more common to start standalone Locator JVM processes. This is useful when you want to increase @@ -374,8 +376,8 @@ higher degree of availability (HA) through redundancy. Not to worry though, if all Locators in the cluster go down, then the cluster will still remain intact. You simply won't be able to add more peer members (i.e. scale-up the number of data nodes in the cluster) -or connect additional clients. If all the Locators in the cluster go down, then it is safe to simply restart them -after a thorough diagnosis. +or connect any more clients. If all the Locators in the cluster go down, then it is safe to simply restart them +only after a thorough diagnosis. NOTE: Once a client receives metadata about the cluster of servers, then all data access operations are sent directly to servers in the cluster, not a Locator. Therefore, existing, connected clients will remain connected and operable. @@ -386,19 +388,24 @@ configuration: .Standalone Locator Process [source,java] ---- -@LocatorApplication @SpringBootApplication -class SpringBootApacheGeodeLocatorApplication { ... } +@LocatorApplication +class SpringBootApacheGeodeLocatorApplication { + // ... +} ---- Instead of using the `@EnableLocator` annotation, you now use the `@LocatorApplication` annotation. The `@LocatorApplication` annotation works in the same way as the `@PeerCacheApplication` and `@CacheServerApplication` -annotations, bootstrapping a Apache Geode or Pivotal GemFire process and overriding the default `ClientCache` instance +annotations, bootstrapping a Apache Geode or Pivotal GemFire process, overriding the default `ClientCache` instance provided by SBDG out-of-the-box. NOTE: If your `@SpringBootApplication` class is annotated with `@LocatorApplication`, then it can only be a `Locator` -and not a `ClientCache`, `CacheServer` or peer `Cache` application. +and not a `ClientCache`, `CacheServer` or peer `Cache` application. If you need the application to function as a +peer `Cache`, perhaps with an embedded `CacheServer` components and embedded Locator, then you need to follow +the approach shown above using the `@EnableLocator` annotation with either the `@PeerCacheApplication` +or `@CacheServerApplication` annotation. With our Spring Boot, Apache Geode Locator application, we can connect both Spring Boot configured and bootstrapped peer members (peer `Cache`, `CacheServer` and `Locator` applications) as well as _Gfsh_ started Locators and Servers. @@ -415,7 +422,7 @@ We also need to vary the configuration for each Locator app instance. Apache Geode and Pivotal GemFire requires each peer member in the cluster to be uniquely named. We can set the name of the Locator by using the `spring.data.gemfire.locator.name` SDG property set as a JVM System Property in your IDE's -Run Configuration Profile for the application main class like so: `--Dspring.data.gemfire.locator.name=SpringLocatorOne`. +Run Configuration Profile for the application main class like so: `-Dspring.data.gemfire.locator.name=SpringLocatorOne`. We name the second Locator app instance, "_SpringLocatorTwo_". Additionally, we must vary the port numbers that the Locators use to listen for connections. By default, @@ -552,7 +559,7 @@ and bootstrap an Apache Geode `CacheServer` application with Spring Boot and con include::{docs-src-dir}/org/springframework/geode/docs/example/app/server/SpringBootApacheGeodeCacheServerApplication.java[tags=class] ---- -Simply enable the "clustered" Profile by using a IDE Run Configuration similar to: +Simply enable the "clustered" Profile by using a IDE Run Profile Configuration similar to: `-server -ea -Dspring.profiles.active=clustered -Dspring.data.gemfire.name=SpringServer -Dspring.data.gemfire.cache.server.port=41414 -Dlogback.log.level=INFO` @@ -608,5 +615,5 @@ GfshLocator | 10.99.199.24(GfshLocator:30259:locator):41003 GfshServer | 10.99.199.24(GfshServer:30295):41004 ---- -You simply must be careful to vary the ports is all and name your peer members appropriately. With Spring, -and Spring Boot for Apache Geode or Pivotal GemFire (SBDG) in particular, it really is that easy! +You must be careful to vary the ports and name your peer members appropriately. With Spring, and Spring Boot +for Apache Geode and Pivotal GemFire (SBDG) in particular, it really is that easy!