The first, opinionated option provided to you by Spring Boot for Apache Geode & Pivotal GemFire (SBDG) out-of-the-box is a 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 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 Client/Server topology. A client/server topology is the most common and traditional architecture employed by enterprise applications.
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 for Apache Geode on the application classpath.
<dependency> <groupId>org.springframework.geode</groupId> <artifactId>spring-geode-starter</artifactId> </dependency>
Then, you configure and bootstrap your Spring Boot, Apache Geode ClientCache application with the following
main application class:
Spring Boot, Apache Geode ClientCache Application.
@SpringBootApplication public SpringBootApacheGeodeClientCacheApplication { public static void main(String[] args) { SpringApplication.run(SpringBootApacheGeodeClientCacheApplication.class, args); } }
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.
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.
![[Tip]](images/tip.png) | Tip |
|---|---|
|
To develop with |
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, data management policy which will cause the data to be sent/received to and from 1 or more
servers, respectively.
| Tip |
|---|---|
|
Compare and contrast the above configuration with Spring Data for Apache Geode/Pivotal GemFire’s approach. |
It is uncommon to ever need a direct reference to the ClientCache instance provided by SBDG 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 ClientCache initialization in a Spring Boot
ApplicationRunner on startup:
Injecting a GemFireCache reference.
@SpringBootApplication public SpringBootApacheGeodeClientCacheApplication { public static void main(String[] args) { SpringApplication.run(SpringBootApacheGeodeClientCacheApplication.class, args); } @Bean ApplicationRunner runAdditionalClientCacheInitialization(GemFireCache gemfireCache) { return args -> { ClientCache clientCache = (ClientCache) gemfireCache; // perform additional ClientCache initialization as needed }; } }
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.
Remember the 2nd goal in Spring Boot’s 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 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
@PeerCacheApplication annotation,
or alternatively, if you need to enable connections from ClientCache apps as well, use the SDG
@CacheServerApplication annotation:
Spring Boot, Apache Geode/Pivotal GemFire CacheServer Application.
@SpringBootApplication @CacheServerApplication(name = "MySpringBootApacheGeodeCacheServerApplication") public SpringBootApacheGeodeCacheServerApplication { public static void main(String[] args) { SpringApplication.run(SpringBootApacheGeodeCacheServerApplication.class, args); } }
| 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. |
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 ClientCache apps.
You can also enable 2 other GemFire/Geode services, an embedded Locator, which allows 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 monitored using Gfsh, GemFire/Geode’s shell tool:
Spring Boot, Apache Geode/Pivotal GemFire CacheServer Application with Locator and Manager services enabled.
@SpringBootApplication @CacheServerApplication(name = "SpringBootApacheGeodeCacheServerApplication") @EnableLocator @EnableManager public SpringBootApacheGeodeCacheServerApplication { public static void main(String[] args) { SpringApplication.run(SpringBootApacheGeodeCacheServerApplication.class, args); } }
Then, you can use Gfsh to connect to and manage this server:
$ 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)<ec><v0>:1024
gfsh>
gfsh>describe member --name=SpringBootApacheGeodeCacheServerApplication
Name : SpringBootApacheGeodeCacheServerApplication
Id : 10.0.0.121(SpringBootApacheGeodeCacheServerApplication:29798)<ec><v0>: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
You can even start additional servers in Gfsh, which will connect to your Spring Boot configured and bootstrapped
Apache Geode or Pivotal GemFire CacheServer application. These additional servers started in Gfsh know about
the Spring Boot, GemFire/Geode server because of the embedded Locator service, which is running on localhost,
listening on the default Locator port, 10334:
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)<ec><v0>:1024
GfshServer | 10.0.0.121(GfshServer:30031)<v1>:1025
Perhaps you 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. You can start the cluster in Gfsh by executing the following commands:
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>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)<ec><v0>:1024 GfshServer | 10.0.0.121(GfshServer:30270)<v1>:1025
Then, modify the SpringBootApacheGeodeCacheServerApplication class to connect to the existing cluster, like so:
Spring Boot, Apache Geode/Pivotal GemFire CacheServer Application with Locator and Manager services enabled.
@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 |
After running your Spring Boot, Apache Geode CacheServer application again, and then running list members in Gfsh,
you should see:
gfsh>list members
Name | Id
------------------------------------------- | ----------------------------------------------------------------------
GfshLocator | 10.0.0.121(GfshLocator:30245:locator)<ec><v0>:1024
GfshServer | 10.0.0.121(GfshServer:30270)<v1>:1025
SpringBootApacheGeodeCacheServerApplication | 10.0.0.121(SpringBootApacheGeodeCacheServerApplication:30279)<v2>:1026
gfsh>describe member --name=SpringBootApacheGeodeCacheServerApplication
Name : SpringBootApacheGeodeCacheServerApplication
Id : 10.0.0.121(SpringBootApacheGeodeCacheServerApplication:30279)<v2>: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 and bootstrapped Apache Geode (or Pivotal GemFire) server and the Gfsh Locator and Server formed a cluster.
While you can use either approach and Spring does 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 and much faster to configure and start a small cluster.
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 additional tooling (e.g. Gfsh) or knowledge is required to get started quickly and easily.
Just build and run it!
| Tip |
|---|---|
|
Be careful to vary your port numbers for the embedded services, like the |
| Tip |
|---|---|
|
See the Appendix, Section 17.5, “Running an Apache Geode/Pivotal GemFire cluster using Spring Boot from your IDE” for more details. |