diff --git a/spring-geode-docs/src/docs/asciidoc/clientcache-applications.adoc b/spring-geode-docs/src/docs/asciidoc/clientcache-applications.adoc new file mode 100644 index 00000000..a2d7464e --- /dev/null +++ b/spring-geode-docs/src/docs/asciidoc/clientcache-applications.adoc @@ -0,0 +1,339 @@ +[[geode-clientcache-applications]] +== 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 putting either Spring Boot for Apache Geode or 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 in Apache Geode/Pivotal GemFire's +{apache-geode-docs}/topologies_and_comm/cs_configuration/chapter_overview.html[Client/Server Configuration] +and topology. This is the most common and traditional arrangement employed in most application system architectures. + +For example, declare the `spring-geode-starter` on your application classpath: + +.Maven +[source,xml] +---- + + + org.springframework.geode + spring-geode-starter + {spring-boot-data-geode-version} + + { + + ClientCache clientCache = (ClientCache) gemfireCache; + + // perform additional ClientCache initialization as needed + }; + } +} +---- + +[[geode-peercache-applications]] +=== Embedded (Peer & Server) Cache Applications + +What if you want to build an embedded, Peer `Cache` application instead? + +Perhaps, you don't want to start with a `ClientCache` instance, but need an actual peer member, configured +and bootstrapped with Spring (Boot) with the additional ability to add this peer member to a (possibly) +existing cluster. Well, you can do that too. + +Remember the 2nd goal in Spring Boot's {spring-boot-doc-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. + +If your application requirements require you to 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 +{spring-data-geode-javadoc}/org/springframework/data/gemfire/config/annotation/PeerCacheApplication.html[`@PeerCacheApplication`] annotation, +or if you need to enable connections from other cache client apps, use the SDG +{spring-data-geode-javadoc}/org/springframework/data/gemfire/config/annotation/CacheServerApplication.html[`@CacheServerApplication`] annotation: + +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. + +.Spring Boot, Apache Geode/Pivotal GemFire CacheServer Application +[source,java] +---- +@SpringBootApplication +@CacheServerApplication(name = "MySpringBootApacheGeodeCacheServerApplication") +public SpringBootApacheGeodeCacheServerApplication { + + public static void main(String[] args) { + SpringApplication.run(SpringBootApacheGeodeClientCacheApplication.class, args); + } +} +---- + +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, +which enables connections from cache client apps. + +I can also enable 2 other GemFire/Geode services, an embedded Locator, which allows either clients or even other peers +to "locate" servers in a cluster, as well as an embedded Manager, which allows the GemFire/Geode application process +to be managed and/or monitored using {apache-geode-docs}/tools_modules/gfsh/chapter_overview.html[_Gfsh_], +GemFire/Geode's shell tool: + +.Spring Boot, Apache Geode/Pivotal GemFire CacheServer Application with Locator and Manager services enabled +[source,java] +---- +@SpringBootApplication +@CacheServerApplication(name = "MySpringBootApacheGeodeCacheServerApplication") +@EnableLocator +@EnableManager +public SpringBootApacheGeodeCacheServerApplication { + + public static void main(String[] args) { + SpringApplication.run(SpringBootApacheGeodeClientCacheApplication.class, args); + } +} +---- + +Then, you can even use _Gfsh_ (the Apache Geode/Pivotal GemFire shell tool, outside your IDE) to connect to +and manage this server: + +[source,text] +---- +$ echo $GEMFIRE +/Users/jblum/pivdev/apache-geode-1.2.1 + +$ gfsh + _________________________ __ + / _____/ ______/ ______/ /____/ / + / / __/ /___ /_____ / _____ / + / /__/ / ____/ _____/ / / / / +/______/_/ /______/_/ /_/ 1.2.1 + +Monitor and Manage Apache Geode + +gfsh>connect +Connecting to Locator at [host=localhost, port=10334] .. +Connecting to Manager at [host=10.0.0.121, port=1099] .. +Successfully connected to: [host=10.0.0.121, port=1099] + + +gfsh>list members + Name | Id +------------------------------------------- | -------------------------------------------------------------------------- +SpringBootApacheGeodeCacheServerApplication | 10.0.0.121(SpringBootApacheGeodeCacheServerApplication:29798):1024 + +gfsh> +gfsh>describe member --name=SpringBootApacheGeodeCacheServerApplication +Name : SpringBootApacheGeodeCacheServerApplication +Id : 10.0.0.121(SpringBootApacheGeodeCacheServerApplication:29798):1024 +Host : 10.0.0.121 +Regions : +PID : 29798 +Groups : +Used Heap : 168M +Max Heap : 3641M +Working Dir : /Users/jblum/pivdev/spring-boot-data-geode/spring-geode-docs/build +Log file : /Users/jblum/pivdev/spring-boot-data-geode/spring-geode-docs/build +Locators : localhost[10334] + +Cache Server Information +Server Bind : +Server Port : 40404 +Running : true +Client Connections : 0 +---- + +I can then even start additional servers in _Gfsh_, which will connect to my Spring Boot configured and bootstrapped +Apache Geode or Pivotal GemFire `CacheServer` application. These additional servers started in _Gfsh_ know about +my Spring Boot, GemFire/Geode server because of the embedded Locator service, which is running on `localhost`, +listening on the default Locator port, `10334`: + +[source,text] +---- +gfsh>start server --name=GfshServer --log-level=config --disable-default-server +Starting a Geode Server in /Users/jblum/pivdev/lab/GfshServer... +... +Server in /Users/jblum/pivdev/lab/GfshServer on 10.0.0.121 as GfshServer is currently online. +Process ID: 30031 +Uptime: 3 seconds +Geode Version: 1.2.1 +Java Version: 1.8.0_152 +Log File: /Users/jblum/pivdev/lab/GfshServer/GfshServer.log +JVM Arguments: -Dgemfire.default.locators=10.0.0.121:127.0.0.1[10334] -Dgemfire.use-cluster-configuration=true -Dgemfire.start-dev-rest-api=false -Dgemfire.log-level=config -XX:OnOutOfMemoryError=kill -KILL %p -Dgemfire.launcher.registerSignalHandlers=true -Djava.awt.headless=true -Dsun.rmi.dgc.server.gcInterval=9223372036854775806 +Class-Path: /Users/jblum/pivdev/apache-geode-1.2.1/lib/geode-core-1.2.1.jar:/Users/jblum/pivdev/apache-geode-1.2.1/lib/geode-dependencies.jar + + +gfsh>list members + Name | Id +------------------------------------------- | -------------------------------------------------------------------------- +SpringBootApacheGeodeCacheServerApplication | 10.0.0.121(SpringBootApacheGeodeCacheServerApplication:29798):1024 +GfshServer | 10.0.0.121(GfshServer:30031):1025 +---- + +Perhaps I want to start the other way around. As developer, I may need to connect my Spring Boot configured +and bootstrapped GemFire/Geode server application to an existing cluster. I can start the cluster in _Gfsh_ +by executing the following commands: + +[source,text] +---- +gfsh>start locator --name=GfshLocator --port=11235 --log-level=config +Starting a Geode Locator in /Users/jblum/pivdev/lab/GfshLocator... +... +Locator in /Users/jblum/pivdev/lab/GfshLocator on 10.0.0.121[11235] as GfshLocator is currently online. +Process ID: 30245 +Uptime: 3 seconds +Geode Version: 1.2.1 +Java Version: 1.8.0_152 +Log File: /Users/jblum/pivdev/lab/GfshLocator/GfshLocator.log +JVM Arguments: -Dgemfire.log-level=config -Dgemfire.enable-cluster-configuration=true -Dgemfire.load-cluster-configuration-from-dir=false -Dgemfire.launcher.registerSignalHandlers=true -Djava.awt.headless=true -Dsun.rmi.dgc.server.gcInterval=9223372036854775806 +Class-Path: /Users/jblum/pivdev/apache-geode-1.2.1/lib/geode-core-1.2.1.jar:/Users/jblum/pivdev/apache-geode-1.2.1/lib/geode-dependencies.jar + +Successfully connected to: JMX Manager [host=10.0.0.121, port=1099] + +Cluster configuration service is up and running. + +gfsh> +gfsh>start server --name=GfshServer --log-level=config --disable-default-server +Starting a Geode Server in /Users/jblum/pivdev/lab/GfshServer... +.... +Server in /Users/jblum/pivdev/lab/GfshServer on 10.0.0.121 as GfshServer is currently online. +Process ID: 30270 +Uptime: 4 seconds +Geode Version: 1.2.1 +Java Version: 1.8.0_152 +Log File: /Users/jblum/pivdev/lab/GfshServer/GfshServer.log +JVM Arguments: -Dgemfire.default.locators=10.0.0.121[11235] -Dgemfire.use-cluster-configuration=true -Dgemfire.start-dev-rest-api=false -Dgemfire.log-level=config -XX:OnOutOfMemoryError=kill -KILL %p -Dgemfire.launcher.registerSignalHandlers=true -Djava.awt.headless=true -Dsun.rmi.dgc.server.gcInterval=9223372036854775806 +Class-Path: /Users/jblum/pivdev/apache-geode-1.2.1/lib/geode-core-1.2.1.jar:/Users/jblum/pivdev/apache-geode-1.2.1/lib/geode-dependencies.jar + + +gfsh>list members + Name | Id +----------- | -------------------------------------------------- +GfshLocator | 10.0.0.121(GfshLocator:30245:locator):1024 +GfshServer | 10.0.0.121(GfshServer:30270):1025 +---- + +Then, I modify my `SpringBootApacheGeodeCacheServerApplication` to connect to the existing cluster, like so: + +.Spring Boot, Apache Geode/Pivotal GemFire CacheServer Application with Locator and Manager services enabled +[source,java] +---- +@SpringBootApplication +@CacheServerApplication(name = "MySpringBootApacheGeodeCacheServerApplication", locators = "localhost[11235]") +public SpringBootApacheGeodeCacheServerApplication { + + public static void main(String[] args) { + SpringApplication.run(SpringBootApacheGeodeClientCacheApplication.class, args); + } +} +---- + +TIP: Notice I configured the `SpringBootApacheGeodeCacheServerApplication` class, `@CacheServerApplication` annotation, +`locators` property with the host and port (i.e. "localhost[11235]") on which I started by Locator using _Gfsh_. + +After running my Spring Boot, Apache Geode `CacheServer` application again, and then listing members in _Gfsh_, I see: + +[source,text] +---- +gfsh>list members + Name | Id +------------------------------------------- | ---------------------------------------------------------------------- +GfshLocator | 10.0.0.121(GfshLocator:30245:locator):1024 +GfshServer | 10.0.0.121(GfshServer:30270):1025 +SpringBootApacheGeodeCacheServerApplication | 10.0.0.121(SpringBootApacheGeodeCacheServerApplication:30279):1026 + + +gfsh>describe member --name=SpringBootApacheGeodeCacheServerApplication +Name : SpringBootApacheGeodeCacheServerApplication +Id : 10.0.0.121(SpringBootApacheGeodeCacheServerApplication:30279):1026 +Host : 10.0.0.121 +Regions : +PID : 30279 +Groups : +Used Heap : 165M +Max Heap : 3641M +Working Dir : /Users/jblum/pivdev/spring-boot-data-geode/spring-geode-docs/build +Log file : /Users/jblum/pivdev/spring-boot-data-geode/spring-geode-docs/build +Locators : localhost[11235] + +Cache Server Information +Server Bind : +Server Port : 40404 +Running : true +Client Connections : 0 +---- + +In both scenarios, the Spring Boot configured/bootstrapped GemFire/Geode server and the _Gfsh_ Locator/servers +formed a cluster. While you can use either approach and Spring will not care, it is far more convenient +to use Spring Boot and your IDE to form a small cluster while developing. By leveraging Spring profiles, +it is far simpler to configure and start a small cluster much faster. + +Plus, this is useful for rapidly prototyping, testing and debugging your entire, end-to-end application +and system architecture, all right from the comfort and familiarity of your IDE of choice. No addition tooling +(e.g. _Gfsh_) knowledge required to get started quickly and easily. + +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 `BindException` due to ports currently in use +conflicts. diff --git a/spring-geode-docs/src/docs/asciidoc/index.adoc b/spring-geode-docs/src/docs/asciidoc/index.adoc index 400203cb..5679e2f2 100644 --- a/spring-geode-docs/src/docs/asciidoc/index.adoc +++ b/spring-geode-docs/src/docs/asciidoc/index.adoc @@ -9,13 +9,21 @@ John Blum :hide-uri-scheme: :apache-geode-version: 16 :apache-geode-docs: http://geode.apache.org/docs/guide/{apache-geode-version} +:apache-geode-javadoc: http://geode.apache.org/releases/latest/javadoc :spring-boot-docs: https://docs.spring.io/spring-boot/docs/current/reference -:spring-boot-docs-html: {spring-boot-docs}/htmlsingle/ +:spring-boot-docs-html: {spring-boot-docs}/htmlsingle +:spring-boot-javadoc: https://docs.spring.io/spring-boot/docs/current/api :spring-data-commons-docs: https://docs.spring.io/spring-data/commons/docs/current/reference :spring-data-commons-docs-html: {spring-data-commons-docs}/html +:spring-data-commons-javadoc: https://docs.spring.io/spring-data/commons/docs/current/api :spring-data-geode-docs: https://docs.spring.io/spring-data/geode/docs/current/reference :spring-data-geode-docs-html: {spring-data-geode-docs}/html +:spring-data-geode-javadoc: https://docs.spring.io/spring-data/geode/docs/current/api +:spring-data-gemfire-docs: https://docs.spring.io/spring-data/gemfire/docs/current/reference +:spring-data-gemfire-docs-html: {spring-data-gemfire-docs}/html +:spring-data-gemfire-javadoc: https://docs.spring.io/spring-data/gemfire/docs/current/api :spring-framework-docs: https://docs.spring.io/spring/docs/current/spring-framework-reference +:spring-framework-javadoc: https://docs.spring.io/spring/docs/current/javadoc-api :wikipedia-docs: https://en.wikipedia.org/wiki [[abstract]]