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 an existing cluster (of data servers) as a peer node. Well, you can do that too.

Remember the 2nd goal in Spring Boot’s documentation:

It is the 2nd part, "get out of the way quickly as requirements start to diverge from the defaults" 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 intention 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 class 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 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, 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 class 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 class SpringBootApacheGeodeCacheServerApplication {

    public static void main(String[] args) {
        SpringApplication.run(SpringBootApacheGeodeClientCacheApplication.class, args);
    }
}

	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, 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!

	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 due to port conflicts.

	Tip
	See the Appendix, Section 20.5, “Running an Apache Geode or Pivotal GemFire cluster using Spring Boot from your IDE” for more details.

In addition to ClientCache, CacheServer and peer Cache applications, SDG, and by extension SBDG, now supports Locator-based, Spring Boot applications.

An Apache Geode or Pivotal GemFire Locator is a location-based service, or alternatively and more typically, a standalone process enabling clients to "locate" a cluster of Apache Geode/Pivotal GemFire servers to manage data. Many cache clients can connect to the same cluster in order to share data. Running multiple clients is common in a Microservices architecture where you need to scale-up the number of app instances to satisfy the demand.

A Locator is also used by joining members of an existing cluster to scale-out and increase capacity of the logically pooled system resources (i.e. Memory, CPU and Disk). A Locator maintains metadata that is sent to the clients to 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 benefits and you are encouraged to read the documentation for more details.

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. 

@SpringBootApplication
@CacheServerApplication
@EnableLocator
class SpringBootCacheServerWithEmbeddedLocatorApplication {
	// ...
}

However, it is more common to start standalone Locator JVM processes. This is useful when you want to increase the resiliency of your cluster in face of network and process failures, which are bound to happen. If a Locator JVM process crashes or gets severed from the cluster due to a network failure, then having multiple Locators provides a 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 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.

To configure and bootstrap Locator-based, Spring Boot applications as standalone JVM processes, use the following configuration:

Standalone Locator Process. 

@SpringBootApplication
@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, 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. 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.

First, let’s startup 2 Locators using our Apache Geode Locator, Spring Boot application class.

SpringBootApacheGeodeLocatorApplication class. 

@UseLocators
@SpringBootApplication
@LocatorApplication(name = "SpringBootApacheGeodeLocatorApplication")
public class SpringBootApacheGeodeLocatorApplication {

	public static void main(String[] args) {

		new SpringApplicationBuilder(SpringBootApacheGeodeLocatorApplication.class)
			.web(WebApplicationType.NONE)
			.build()
			.run(args);

		System.err.println("Press <enter> to exit!");

		new Scanner(System.in).nextLine();
	}

	@Configuration
	@EnableManager(start = true)
	@Profile("manager")
	@SuppressWarnings("unused")
	static class ManagerConfiguration { }

}

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. 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, an Apache Geode or Pivotal GemFire Locator listens on port 10334. We can set the Locator port using the spring.data.gemfire.locator.port SDG property.

For our first Locator app instance (i.e. "SpringLocatorOne"), we also enable the "manager" Profile so that we can connect to the Locator using Gfsh.

Our IDE Run Configuration Profile for our first Locator app instance appears as:

-server -ea -Dspring.profiles.active=manager -Dspring.data.gemfire.locator.name=SpringLocatorOne -Dlogback.log.level=INFO

And our IDE Run Configuration Profile for our second Locator app instance appears as:

-server -ea -Dspring.profiles.active= -Dspring.data.gemfire.locator.name=SpringLocatorTwo -Dspring.data.gemfire.locator.port=11235 -Dlogback.log.level=INFO

You should see log output similar to the following when you start a Locator app instance:

Spring Boot, Apache Geode Locator log output. 

  .   ____          _            __ _ _
 /\\ / ___'_ __ _ _(_)_ __  __ _ \ \ \ \
( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
 \\/  ___)| |_)| | | | | || (_| |  ) ) ) )
  '  |____| .__|_| |_|_| |_\__, | / / / /
 =========|_|==============|___/=/_/_/_/
 :: Spring Boot ::  (v2.2.0.BUILD-SNAPSHOT)

2019-09-01 11:02:48,707  INFO .SpringBootApacheGeodeLocatorApplication:  55 - Starting SpringBootApacheGeodeLocatorApplication on jblum-mbpro-2.local with PID 30077 (/Users/jblum/pivdev/spring-boot-data-geode/spring-geode-docs/out/production/classes started by jblum in /Users/jblum/pivdev/spring-boot-data-geode/spring-geode-docs/build)
2019-09-01 11:02:48,711  INFO .SpringBootApacheGeodeLocatorApplication: 651 - No active profile set, falling back to default profiles: default
2019-09-01 11:02:49,374  INFO xt.annotation.ConfigurationClassEnhancer: 355 - @Bean method LocatorApplicationConfiguration.exclusiveLocatorApplicationBeanFactoryPostProcessor is non-static and returns an object assignable to Spring's BeanFactoryPostProcessor interface. This will result in a failure to process annotations such as @Autowired, @Resource and @PostConstruct within the method's declaring @Configuration class. Add the 'static' modifier to this method to avoid these container lifecycle issues; see @Bean javadoc for complete details.
2019-09-01 11:02:49,919  INFO ode.distributed.internal.InternalLocator: 530 - Starting peer location for Distribution Locator on 10.99.199.24[11235]
2019-09-01 11:02:49,925  INFO ode.distributed.internal.InternalLocator: 498 - Starting Distribution Locator on 10.99.199.24[11235]
2019-09-01 11:02:49,926  INFO distributed.internal.tcpserver.TcpServer: 242 - Locator was created at Sun Sep 01 11:02:49 PDT 2019
2019-09-01 11:02:49,927  INFO distributed.internal.tcpserver.TcpServer: 243 - Listening on port 11235 bound on address 0.0.0.0/0.0.0.0
2019-09-01 11:02:49,928  INFO ternal.membership.gms.locator.GMSLocator: 162 - GemFire peer location service starting.  Other locators: localhost[10334]  Locators preferred as coordinators: true  Network partition detection enabled: true  View persistence file: /Users/jblum/pivdev/spring-boot-data-geode/spring-geode-docs/build/locator11235view.dat
2019-09-01 11:02:49,928  INFO ternal.membership.gms.locator.GMSLocator: 416 - Peer locator attempting to recover from localhost/127.0.0.1:10334
2019-09-01 11:02:49,963  INFO ternal.membership.gms.locator.GMSLocator: 422 - Peer locator recovered initial membership of View[10.99.199.24(SpringLocatorOne:30043:locator)<ec><v0>:41000|0] members: [10.99.199.24(SpringLocatorOne:30043:locator)<ec><v0>:41000]
2019-09-01 11:02:49,963  INFO ternal.membership.gms.locator.GMSLocator: 407 - Peer locator recovered state from LocatorAddress [socketInetAddress=localhost/127.0.0.1:10334, hostname=localhost, isIpString=false]
2019-09-01 11:02:49,965  INFO ode.distributed.internal.InternalLocator: 644 - Starting distributed system
2019-09-01 11:02:50,007  INFO he.geode.internal.logging.LoggingSession:  82 -
---------------------------------------------------------------------------

  Licensed to the Apache Software Foundation (ASF) under one or more
  contributor license agreements.  See the NOTICE file distributed with this
  work for additional information regarding copyright ownership.

  The ASF licenses this file to You under the Apache License, Version 2.0
  (the "License"); you may not use this file except in compliance with the
  License.  You may obtain a copy of the License at

  https://www.apache.org/licenses/LICENSE-2.0

  Unless required by applicable law or agreed to in writing, software
  distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the
  License for the specific language governing permissions and limitations
  under the License.

---------------------------------------------------------------------------
Build-Date: 2019-04-19 11:49:13 -0700
Build-Id: onichols 0
Build-Java-Version: 1.8.0_192
Build-Platform: Mac OS X 10.14.4 x86_64
Product-Name: Apache Geode
Product-Version: 1.9.0
Source-Date: 2019-04-19 11:11:31 -0700
Source-Repository: release/1.9.0
Source-Revision: c0a73d1cb84986d432003bd12e70175520e63597
Native version: native code unavailable
Running on: 10.99.199.24/10.99.199.24, 8 cpu(s), x86_64 Mac OS X 10.13.6
Communications version: 100
Process ID: 30077
User: jblum
Current dir: /Users/jblum/pivdev/spring-boot-data-geode/spring-geode-docs/build
Home dir: /Users/jblum
Command Line Parameters:
  -ea
  -Dspring.profiles.active=
  -Dspring.data.gemfire.locator.name=SpringLocatorTwo
  -Dspring.data.gemfire.locator.port=11235
  -Dlogback.log.level=INFO
  -javaagent:/Applications/IntelliJ IDEA 19 CE.app/Contents/lib/idea_rt.jar=51961:/Applications/IntelliJ IDEA 19 CE.app/Contents/bin
  -Dfile.encoding=UTF-8
Class Path:
...
..
.
2019-09-01 11:02:54,112  INFO ode.distributed.internal.InternalLocator: 661 - Locator started on 10.99.199.24[11235]
2019-09-01 11:02:54,113  INFO ode.distributed.internal.InternalLocator: 769 - Starting server location for Distribution Locator on 10.99.199.24[11235]
2019-09-01 11:02:54,134  INFO nt.internal.locator.wan.LocatorDiscovery: 138 - Locator discovery task exchanged locator information 10.99.199.24[11235] with localhost[10334]: {-1=[10.99.199.24[10334]]}.
2019-09-01 11:02:54,242  INFO .SpringBootApacheGeodeLocatorApplication:  61 - Started SpringBootApacheGeodeLocatorApplication in 6.137470354 seconds (JVM running for 6.667)
Press <enter> to exit!

Next, start up the second Locator app instance (you should see log output similar to above). Then, connect to the cluster of Locators using Gfsh:

Cluster of Locators. 

$ echo $GEMFIRE
/Users/jblum/pivdev/apache-geode-1.9.0

$ gfsh
    _________________________     __
   / _____/ ______/ ______/ /____/ /
  / /  __/ /___  /_____  / _____  /
 / /__/ / ____/  _____/ / /    / /
/______/_/      /______/_/    /_/    1.9.0

Monitor and Manage Apache Geode

gfsh>connect
Connecting to Locator at [host=localhost, port=10334] ..
Connecting to Manager at [host=10.99.199.24, port=1099] ..
Successfully connected to: [host=10.99.199.24, port=1099]

gfsh>list members
      Name       | Id
---------------- | ------------------------------------------------------------------------
SpringLocatorOne | 10.99.199.24(SpringLocatorOne:30043:locator)<ec><v0>:41000 [Coordinator]
SpringLocatorTwo | 10.99.199.24(SpringLocatorTwo:30077:locator)<ec><v1>:41001

Using our SpringBootApacheGeodeCacheServerApplication main class from the previous section, we can configure and bootstrap an Apache Geode CacheServer application with Spring Boot and connect it to our cluster of Locators.

SpringBootApacheGeodeCacheServerApplication class. 

@SpringBootApplication
@CacheServerApplication(name = "SpringBootApacheGeodeCacheServerApplication")
@SuppressWarnings("unused")
public class SpringBootApacheGeodeCacheServerApplication {

	public static void main(String[] args) {

		new SpringApplicationBuilder(SpringBootApacheGeodeCacheServerApplication.class)
			.web(WebApplicationType.NONE)
			.build()
			.run(args);
	}

	@Configuration
	@UseLocators
	@Profile("clustered")
	static class ClusteredConfiguration { }

	@Configuration
	@EnableLocator
	@EnableManager(start = true)
	@Profile("!clustered")
	static class LonerConfiguration { }

}

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

After the server starts up, you should see the new peer member in the cluster:

Cluster with Spring Boot configured and bootstrapped Apache Geode CacheServer. 

gfsh>list members
      Name       | Id
---------------- | ------------------------------------------------------------------------
SpringLocatorOne | 10.99.199.24(SpringLocatorOne:30043:locator)<ec><v0>:41000 [Coordinator]
SpringLocatorTwo | 10.99.199.24(SpringLocatorTwo:30077:locator)<ec><v1>:41001
SpringServer     | 10.99.199.24(SpringServer:30216)<v2>:41002

Finally, we can even start additional Locators and Servers connected to this cluster using Gfsh:

Gfsh started Locators and Servers. 

gfsh>start locator --name=GfshLocator --port=12345 --log-level=config
Starting a Geode Locator in /Users/jblum/pivdev/lab/GfshLocator...
......
Locator in /Users/jblum/pivdev/lab/GfshLocator on 10.99.199.24[12345] as GfshLocator is currently online.
Process ID: 30259
Uptime: 5 seconds
Geode Version: 1.9.0
Java Version: 1.8.0_192
Log File: /Users/jblum/pivdev/lab/GfshLocator/GfshLocator.log
JVM Arguments: -Dgemfire.default.locators=10.99.199.24[11235],10.99.199.24[10334] -Dgemfire.enable-cluster-configuration=true -Dgemfire.load-cluster-configuration-from-dir=false -Dgemfire.log-level=config -Dgemfire.launcher.registerSignalHandlers=true -Djava.awt.headless=true -Dsun.rmi.dgc.server.gcInterval=9223372036854775806
Class-Path: /Users/jblum/pivdev/apache-geode-1.9.0/lib/geode-core-1.9.0.jar:/Users/jblum/pivdev/apache-geode-1.9.0/lib/geode-dependencies.jar

gfsh>start server --name=GfshServer --server-port=45454 --log-level=config
Starting a Geode Server in /Users/jblum/pivdev/lab/GfshServer...
...
Server in /Users/jblum/pivdev/lab/GfshServer on 10.99.199.24[45454] as GfshServer is currently online.
Process ID: 30295
Uptime: 2 seconds
Geode Version: 1.9.0
Java Version: 1.8.0_192
Log File: /Users/jblum/pivdev/lab/GfshServer/GfshServer.log
JVM Arguments: -Dgemfire.default.locators=10.99.199.24[11235],10.99.199.24[12345],10.99.199.24[10334] -Dgemfire.start-dev-rest-api=false -Dgemfire.use-cluster-configuration=true -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.9.0/lib/geode-core-1.9.0.jar:/Users/jblum/pivdev/apache-geode-1.9.0/lib/geode-dependencies.jar

gfsh>list members
      Name       | Id
---------------- | ------------------------------------------------------------------------
SpringLocatorOne | 10.99.199.24(SpringLocatorOne:30043:locator)<ec><v0>:41000 [Coordinator]
SpringLocatorTwo | 10.99.199.24(SpringLocatorTwo:30077:locator)<ec><v1>:41001
SpringServer     | 10.99.199.24(SpringServer:30216)<v2>:41002
GfshLocator      | 10.99.199.24(GfshLocator:30259:locator)<ec><v3>:41003
GfshServer       | 10.99.199.24(GfshServer:30295)<v4>:41004

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!

As discussed in the previous sections above, it is possible to enable a Spring Boot configured and bootstrapped Apache Geode or Pivotal GemFire peer member node in the cluster to function as a Manager.

An Apache Geode or Pivotal GemFire Manager is a peer member node in the cluster running the Management Service, allowing the cluster to be managed and monitored using JMX based tools, like Gfsh, JConsole or JVisualVM, for instance. Any tool that uses the JMX API can connect to and manage the GemFire/Geode cluster for whatever purpose.

The cluster may have more than 1 Manager for redundancy. Only server-side, peer member nodes in the cluster may function as a Manager. Therefore, a ClientCache application cannot be a Manager.

To create a Manager, you use the SDG @EnableManager annotation.

The 3 primary uses of the @EnableManager annotation to create a Manager is:

1 - CacheServer Manager Application. 

@SpringBootApplication
@CacheServerApplication(name = "CacheServerManagerApplication")
@EnableManager(start = true)
class CacheServerManagerApplication {
	// ...
}

2 - Peer Cache Manager Application. 

@SpringBootApplication
@PeerCacheApplication(name = "PeerCacheManagerApplication")
@EnableManager(start = "true")
class SpringBootPeerCacheManagerApplication {
	// ...
}

3 - Locator Manager Application. 

@SpringBootApplication
@LocatorApplication(name = "LocatorManagerApplication")
@EnableManager(start = true)
class LocatorManagerApplication {
	// ...
}

#1 creates a peer Cache instance with a CacheServer component accepting client connections along with an embedded Manager enabling JMX clients to connect.

#2 creates only a peer Cache instance along with an embedded Manager. As a peer Cache with NO CacheServer component, clients are not able to connect to this node. It is merely a server managing data.

#3 creates a Locator instance with an embedded Manager.

In all configuration arrangements, the Manager was configured to start immediately.

	Tip
	See the @EnableManager annotation Javadoc for additional configuration options.

As of Apache Geode 1.11.0, you must now include additional Geode dependencies on your Spring Boot application classpath to make your application a proper Apache Geode/Pivotal GemFire Manager in the cluster, particularly if you are also enabling the embedded HTTP service in the Manager.

The required dependencies are:

Additional Manager dependencies expressed in Gradle. 

runtime "org.apache.geode:geode-http-service"
runtime "org.apache.geode:geode-web"
runtime "org.springframework.boot:spring-boot-starter-jetty"

The embedded HTTP service (implemented with the Eclipse Jetty Servlet Container), runs the Management (Admin) REST API, which is used by tooling, such as Gfsh, to connect to the cluster over HTTP. In addition, it also runs the Pulse Monitoring Tool.

Even if you do not start the embedded HTTP service (Jetty Servlet Container), a Manager still requires the geode-http-service, geode-web and spring-boot-starter-jetty dependencies.

You might ask how I can customize the Auto-configuration provided by SBDG if I do not explicitly declare the annotation?

For example, you mat want to customize the member’s "name". You know that the @ClientCacheApplication annotation provides the name attribute so you can set the client member’s "name". But SBDG has already implicitly declared the @ClientCacheApplication annotation via Auto-configuration on your behalf. What do you do?

Well, SBDG supplies a few very useful Annotations in this case.

For example, to set the (client or peer) member’s name, you can use the @UseMemberName annotation, like so:

Setting the member’s name using @UseMemberName. 

@SpringBootApplication
@UseMemberName("MyMemberName")
class SpringBootClientCacheApplication { ... }

Alternatively, you could set the spring.application.name or the spring.data.gemfire.name property in Spring Boot application.properties

Setting the member’s name using the spring.application.name property. 

# Spring Boot application.properties

spring.application.name = MyMemberName

Or:

Setting the member’s name using the spring.data.gemfire.cache.name property. 

# Spring Boot application.properties

spring.data.gemfire.cache.name = MyMemberName

In general, there are 3 ways to customize configuration, even in the context of SBDG’s Auto-configuration:

	Tip
	For the complete list of documented Properties, see here.

Disabling Spring Boot Auto-configuration is explained in detail in Spring Boot’s Reference Guide.

Disabling SBDG Auto-confiugration was also explained in detail.

In a nutshell, if you want to disable any Auto-configuration provided by either Spring Boot or SBDG, then you can declare your intent in the @SpringBootApplication annotation, like so:

Disabling Specific Auto-configuration Classes. 

@SpringBootApplication(
  exclude = { DataSourceAutoConfiguration.class, PdxAutoConfiguration.class }
)
class SpringBootClientCacheApplication { ... }

	Warning
	Make sure you understand what you are doing when you are "disabling" Auto-configuration.

Overriding SBDG Auto-configuration was explained in detail as well.

In a nutshell, if you want to override the default Auto-configuration provided by SBDG then you must annotate your @SpringBootApplication class with your intent.

For example, say you want to configure and bootstrap an Apache Geode or Pivotal GemFire CacheServer application (a peer; not a client), then you would:

Overriding the default ClientCache Auto-Configuration by configuring & bootstrapping a CacheServer application. 

@SpringBootApplication
@CacheServerApplication
class SpringBootCacheServerApplication { ... }

Even when you explicitly declare the @ClientCacheApplication annotation on your @SpringBootApplication class, like so:

Overriding by explicitly declaring @ClientCacheApplication. 

@SpringBootApplication
@ClientCacheApplication
class SpringBootClientCacheApplication { ... }

You are overriding SBDG’s Auto-configuration of the ClientCache instance. As a result, you now have also implicitly consented to being responsible for other aspects of the configuration (e.g. Security)! Why?

This is because in certain cases, like Security, certain aspects of Security configuration (e.g. SSL) must be configured before the cache instance is created. And, Spring Boot always applies user configuration before Auto-configuration partially to determine what needs to be auto-configured in the first place.

	Warning
	Especially make sure you understand what you are doing when you are "overriding" Auto-configuration.

We will simply refer you to the Spring Boot Reference Guide on replacing Auto-configuration. See here.

This section covers the SBDG provided Auto-configuration classes corresponding to the SDG Annotations in more detail.

To review the complete list of SBDG Auto-confiugration classes, see here.

5.5.1 @ClientCacheApplication

	Note
	The ClientCacheAutoConfiguration class corresponds to the @ClientCacheApplication annotation.

SBDG starts with the opinion that application developers will primarily be building Apache Geode or Pivotal GemFire client applications using Spring Boot.

Technically, this means building Spring Boot applications with either an Apache Geode or Pivotal GemFire ClientCache instance connected to a dedicated cluster of Apache Geode or Pivotal GemFire servers that manage the data as part of a client/server topology.

By way of example, this means you do not need to explicitly declare and annotate your @SpringBootApplication class with SDG’s @ClientCacheApplication annotation, like so:

Do Not Do This. 

@SpringBootApplication
@ClientCacheApplication
class SpringBootClientCacheApplication { ... }

This is because SBDG’s provided Auto-configuration class is already meta-annotated with SDG’s @ClientCacheApplication annotation. Therefore, you simply need:

Do This. 

@SpringBootApplication
class SpringBootClientCacheApplication { ... }

	Tip
	Refer to SDG’s Referene Guide for more details on Apache Geode or Pivotal GemFire cache applications, and client/server applications in particular.

5.5.2 @EnableGemfireCaching

	Note
	The CachingProviderAutoConfiguration class corresponds to the @EnableGemfireCaching annotation.

If you simply used the core Spring Framework to configure either Apache Geode or Pivotal GemFire as a caching provider in Spring’s Cache Abstraction, you would need to do this:

Configuring caching using the Spring Framework. 

@SpringBootApplication
@EnableCaching
class CachingUsingApacheGeodeConfiguration {

  @Bean
  GemfireCacheManager cacheManager(GemFireCache cache) {

      GemfireCacheManager cacheManager = new GemfireCacheManager();

      cacheManager.setCache(cache);

      return cacheManager;
  }
}

If you were using Spring Data for Apache Geode’s @EnableGemfireCaching annotation, then the above configuration could be simplified to:

Configuring caching using Spring Data Geode. 

@SpringBootApplication
@EnableGemfireCaching
class CachingUsingApacheGeodeConfiguration {

}

And, if you use SBDG, then you only need to do this:

Configuring caching using Spring Data Geode. 

@SpringBootApplication
class CachingUsingApacheGeodeConfiguration {

}

This allows you to focus on the areas in your application that would benefit from caching without having to enable the plumbing. Simply demarcate the service methods in your application that are good candidates for caching:

Using caching in your application. 

@Service
class CustomerService {

  @Caching("CustomersByName")
  Customer findBy(String name) {
    ...
  }
}

	Tip
	Refer to the documentation for more details.

5.5.3 @EnableContinuousQueries

	Note
	The ContinuousQueryAutoConfiguration class corresponds to the @EnableContinuousQueries annotation.

Without having to enable anything, you simply annotate your application (POJO) component method(s) with the SDG @ContinuousQuery annotation to register a CQ and start receiving events. The method acts as a CqEvent handler, or in Apache Geode and Pivotal GemFire’s case, the method would be an implementation of CqListener.

Declare application CQs. 

@Component
class MyCustomerApplicationContinuousQueries

  @ContinuousQuery("SELECT customer.* FROM /Customers customers"
    + " WHERE customer.getSentiment().name().equalsIgnoreCase('UNHAPPY')")
  public void handleUnhappyCustomers(CqEvent event) {
    ...
  }
}

As shown above, you define the events you are interested in receiving by using a OQL query with a finely tuned query predicate describing the events of interests and implement the handler method to process the events (e.g. apply a credit to the customer’s account and follow up in email).

	Tip
	Refer to the documentation for more details.

5.5.4 @EnableGemfireFunctionExecutions & @EnableGemfireFunctions

	Note
	The FunctionExecutionAutoConfiguration class corresponds to both the @EnableGemfireFunctionExecutions and @EnableGemfireFunctions annotations.

Whether you need to execute a Function or implement a Function, SBDG will detect the Function definition and auto-configure it appropriately for use in your Spring Boot application. You only need to define the Function execution or implementation in a package below the main @SpringBootApplication class.

Declare a Function Execution. 

package example.app.functions;

@OnRegion("Accounts")
interface MyCustomerApplicationFunctions {

    void applyCredit(Customer customer);

}

Then you can inject the Function execution into any application component and use it:

Use the Function. 

package example.app.service;

@Service
interface CustomerService {

    @Autowired
    private MyCustomerapplicationFunctions customerFunctions;

    public void analyzeCustomerSentiment(Customer customer) {

        ...

        this.customerFunctions.applyCredit(customer);

        ...
    }
}

The same pattern basically applies to Function implementations, except in the implementation case, SBDG "registers" the Function implementation for use (i.e. to be called by a Function execution).

The point is, you are simply focusing on defining the logic required by your application, and not worrying about how Functions are registered, called, etc. SBDG is handling this concern for you!

	Note
	Function implementations are typically defined and registered on the server-side.

	Tip
	Refer to the documentation for more details.

5.5.5 @EnableGemfireRepositories

	Note
	The GemFireRepositoriesAutoConfigurationRegistrar class corresponds to the @EnableGemfireRepositories annotation.

Like Functions, you are only concerned with the data access operations (e.g. basic CRUD and simple Queries) required by your application to carry out its functions, not how to create and perform them (e.g. Region.get(key) & Region.put(key, obj)) or execute (e.g. Query.execute(arguments)).

Simply define your Spring Data Repository:

Define an application-specific Repository. 

package example.app.repo;

interface CustomerRepository extends CrudRepository<Customer, Long> {

  List<Customer> findBySentimentEqualTo(Sentiment sentiment);

}

And use it:

Using the application-specific Repository. 

package example.app.sevice;

@Service
class CustomerService {

  @Autowired
  private CustomerRepository repository;

  public void processCustomersWithSentiment(Sentiment sentiment) {

    this.repository.findBySentimentEqualTo(sentiment).forEach(customer -> { ... });

    ...
  }
}

Your application-specific Repository simply needs to be declared in a package below the main @SpringBootApplication class. Again, you are only focusing on the data access operations and queries required to carry out the functions of your application, nothing more.

	Tip
	Refer to the documentation for more details.

5.5.6 @EnableLogging

	Note
	The LoggingAutoConfiguration class corresponds to the @EnableLogging annotation.

Logging is an essential application concern to understand what is happening in the system along with when and where the event occurred. As such, SBDG auto-configures logging for Apache Geode and Pivotal GemFire by default, using the default log-level, "config".

If you wish to change an aspect of logging, such as the log-level, you would typically do this in Spring Boot application.properties:

Change the log-level for Apache Geode. 

# Spring Boot application.properites.

spring.data.gemfire.cache.log-level=debug

Other aspects may be configured as well, such as the log file size and disk space limits for the file system location used to store the Apache Geode log files at runtime.

Under-the-hood, Apache Geode’s logging is based on Log4j. Therefore, you can configure Apache Geode logging using any logging provider (e.g. Logback) and configuration metadata appropriate for that logging provider so long as you supply the necessary adapter between Log4j and whatever logging system you are using. For instance, if you include org.springframework.boot:spring-boot-starter-logging then you will be using Logback and you will need the org.apache.logging.log4j:log4j-to-slf4j adapter.

5.5.7 @EnablePdx

	Note
	The PdxSerializationAutoConfiguration class corresponds to the @EnablePdx annotation.

Anytime you need to send an object over the network, overflow or persist an object to disk, then your application domain object must be serializable. It would be painful to have to implement java.io.Serializable in everyone of your application domain objects (e.g. Customer) that would potentially need to be serialized.

Furthermore, using Java Serialization may not be ideal (e.g. the most portable or efficient) in all cases, or even possible in other cases (e.g. when you are using a 3rd party library for which you have no control over).

In these situations, you need to be able to send your object anywhere without unduly requiring the class type to be serializable as well as to exist on the classpath for every place it is sent. Indeed, the final destination may not even be a Java application! This is where Apache Geode PDX Serialization steps into help.

However, you don’t have to figure out how to configure PDX to identify the application class types that will need to be serialized. You simply define your class type:

Customer class. 

@Region("Customers")
class Customer {

  @Id
  private Long id;

  @Indexed
  private String name;

  ...
}

And, SBDG’s Auto-configuration will handle the rest!

	Tip
	Refer to the documentation for more details.

5.5.8 @EnableSecurity

	Note
	The ClientSecurityAutoConfiguration class and PeerSecurityAutoConfiguration class corresponds to the @EnableSecurity annotation, but applies Security, and specifically, Authentication/Authorization configuration for both clients and servers.

Configuring your Spring Boot, Apache Geode ClientCache application to properly authenticate with a cluster of secure Apache Geode or Pivotal GemFire servers is as simple as setting a username and password in Spring Boot application.properties:

Supplying Authentication Credentials. 

# Spring Boot application.properties

spring.data.gemfire.security.username=Batman
spring.data.gemfire.security.password=r0b!n5ucks

	Note
	Authentication is even easier to configure in a managed environment like PCF when using PCC; you don’t have to do anything!

Authorization is configured on the server-side and is made simple with SBDG and the help of Apache Shiro. Of course, this assumes you are using SBDG to configure and bootstrap your Apache Geode cluster in the first place, which is possible, and made even easier with SBDG.

	Tip
	Refer to the documentation for more details.

5.5.9 @EnableSsl

	Note
	The SslAutoConfiguration class corresponds to the @EnableSsl annotation.

Configuring SSL for secure transport (TLS) between your Spring Boot, Apache Geode ClientCache application and the cluster can be a real problematic task, especially to get correct from the start. So, it is something that SBDG makes simple to do out-of-the-box.

Simply supply a trusted.keystore file containing the certificates in a well-known location (e.g. root of your application classpath) and SBDG’s Auto-configuration will kick in and handle of the rest.

This is useful during development, but we highly recommend using a more secure procedure (e.g. integrating with a secure credential store like LDAP, CredHub or Vault) when deploying your Spring Boot application to production.

	Tip
	Refer to the documentation for more details.

5.5.10 @EnableGemFireHttpSession

	Note
	The SpringSessionAutoConfiguration class corresponds to the @EnableSsl annotation.

Configuring Apache Geode or Pivotal GemFire to serve as the (HTTP) Session state caching provider using Spring Session is as simple as including the correct starter, e.g. spring-geode-starter-session.

Using Spring Session. 

<dependency>
    <groupId>org.springframework.geode</groupId>
    <artifactId>spring-geode-starter-session</artifactId>
    <version>1.3.0.M2</version>
</dependency>

With Spring Session, and specifically Spring Session for Apache Geode or Pivotal GemFire (SSDG), on the classpath of your Spring Boot, Apache Geode ClientCache Web application, you can manage your (HTTP) Session state with either Apache Geode or Pivotal GemFire. No further configuration is needed. SBDG Auto-configuration detects Spring Session on the application classpath and does the right thing.

	Tip
	Refer to the documentation for more details.

5.5.11 RegionTemplateAutoConfiguration

The SBDG RegionTemplateAutoConfiguration class has no corresponding SDG Annotation. However, the Auto-configuration of a GemfireTemplate for every single Apache Geode Region defined and declared in your Spring Boot application is supplied by SBDG never-the-less.

For example, if you defined a Region using:

Region definition using JavaConfig. 

@Configuration
class GeodeConfiguration {


  @Bean("Customers")
  ClientRegionFactoryBean<Long, Customer> customersRegion(GemFireCache cache) {

    ClientRegionFactoryBean<Long, Customer> customersRegion =
      new ClientRegionFactoryBean<>();

    customersRegion.setCache(cache);
    customersRegion.setShortcut(ClientRegionShortcut.PROXY);

    return customersRegion;
  }
}

Alternatively, you could define the "Customers" Region using:

Region definition using @EnableEntityDefinedRegions. 

@Configuration
@EnableEntityDefinedRegion(basePackageClasses = Customer.class)
class GeodeConfiguration {

}

Then, SBDG will supply a GemfireTemplate instance that you can use to perform low-level, data access operations (indirectly) on the "Customers" Region:

Use the GemfireTemplate to access the "Customers" Region. 

@Repository
class CustomersDao {

  @Autowired
  @Qualifier("customersTemplate")
  private GemfireTemplate customersTemplate;

  Customer findById(Long id) {
    return this.customerTemplate.get(id);
  }
}

You do not need to explicitly configure GemfireTemplates for each Region you need to have low-level data access to (e.g. such as when you are not using the Spring Data Repository abstraction).

Be careful to "qualify" the GemfireTemplate for the Region you need data access to, especially given that you will probably have more than 1 Region defined in your Spring Boot application.

	Tip
	Refer to the documentation for more details.

Auto-configuration was explained in complete detail in the chapter, "Auto-configuration".

The following SDG Annotations are not implicitly applied by SBDG’s Auto-configuration:

	Tip
	This was also covered here.

Part of the reason for this is because several of the Annotations are server-specific:

And, we already stated that SBDG is opinionated about providing a ClientCache instance out-of-the-box.

Other Annotations are driven by need, for example:

While still other Annotations require more careful planning, for example:

One in particular is used exclusively for Unit Testing:

The bottom-line is, a framework should not Auto-configure every possible feature, especially when the features consume additional system resources, or requires more careful planning as determined by the use case.

Still, all of these Annotations are available for the application developer to use when needed.

This section calls out the Annotations we believe to be most beneficial for your application development purposes when using either Apache Geode or Pivotal GemFire in Spring Boot applications.

6.3.1 @EnableClusterAware (SBDG)

The @EnableClusterAware annotation is arguably the most powerful and valuable Annotation in the set of Annotations!

When you annotate your main @SpringBootApplication class with @EnableClusterAware:

Declaring @EnableClusterAware. 

@SpringBootApplication
@EnableClusterAware
class SpringBootApacheGeodeClientCacheApplication { ... }

Your Spring Boot, Apache Geode ClientCache application is able to seamlessly switch between client/server and local-only topologies with no code or configuration changes.

When a cluster of Apache Geode or Pivotal GemFire servers is detected, the client application will send and receive data to and from the cluster. If a cluster is not available, then the client automatically switches to storing data locally on the client using LOCAL Regions.

Additionally, the @EnableClusterAware annotation is meta-annotated with SDG’s @EnableClusterConfiguration annotation.

The @EnableClusterConfiguration enables configuration metadata defined on the client (e.g. Region and Index definitions) as needed by the application based on requirements and use cases, to be sent to the cluster of servers. If those schema objects are not already present, they will be created by the servers in the cluster in such a way that the servers will remember the configuration on a restart as well as provide the configuration to new servers joining the cluster when scaling out. This feature is careful not to stomp on any existing Region or Index objects already present on the servers, particularly since you may already have data stored in the Regions.

The primary motivation behind the @EnableClusterAware annotation is to allow you to switch environments with very little effort. It is a very common development practice to debug and test your application locally, in your IDE, then push up to a production-like environment for more rigorous integration testing.

By default, the configuration metadata is sent to the cluster using a non-secure HTTP connection. Using HTTPS, changing host and port, and configuring the data management policy used by the servers when creating Regions is all configurable.

	Tip
	Refer to the section in the SDG Reference Guide on Configuring Cluster Configuration Push for more details.

6.3.2 @EnableCachingDefinedRegions, @EnableClusterDefinedRegions & @EnableEntityDefinedRegions (SDG)

These Annotations are used to create Regions in the cache to manage your application data.

Of course, you can create Regions using Java configuration and the Spring API as follows:

Creating a Region with Spring JavaConfig. 

@Bean("Customers")
ClientRegionFactoryBean<Long, Customer> customersRegion(GemFireCache cache) {

  ClientRegionFactoryBean<Long, Customer> customers = new ClientRegionFactoryBean<>();

  customers.setCache(cache);
  customers.setShortcut(ClientRegionShortcut.PROXY);

  return customers;
}

Or XML:

Creating a client Region using Spring XML. 

<gfe:client-region id="Customers" shorcut="PROXY"/>

However, using the provided Annotations is far easier, especially during development when the complete Region configuration may be unknown and you simply want to create a Region to persist your application data and move on.

@EnableCachingDefinedRegions

The @EnableCachingDefinedRegions annotation is used when you have application components registered in the Spring Container that are annotated with Spring or JSR-107, JCache annotations.

Caches that identified by name in the caching annotations are used to create Regions holding the data you want cached.

For example, given:

Defining Regions based on Spring or JSR-107 JCache Annotations. 

@Service
class CustomerService {

  @Cacheable("CustomersByAccountNumber" key="#account.number")
  Customer findBy(Account account) {
    ...
  }
}

When your main @SpringBootApplication class is annotated with @EnableCachingDefinedRegions:

Using @EnableCachingDefinedRegions. 

@SpringBootApplication
@EnableCachingDefineRegions
class SpringBootApacheGeodeClientCacheApplication { ... }

Then, SBDG would create a client PROXY Region (or PARTITION_REGION if your application were a peer member of the cluster) with the name "CustomersByAccountNumber" as if you created the Region using either the JavaConfig or XML approaches shown above.

You can use the clientRegionShortcut or serverRegionShortcut attribute to change the data management policy of the Regions created on the client or servers, respectively.

For client Regions, you can additionally assign a specific Pool of connections used by the client *PROXY Regions to send data to the cluster by setting the poolName attribute.

@EnableEntityDefinedRegions

Like @EnableCachingDefinedRegions, @EnableEntityDefinedRegions allows you to create Regions based on the entity classes you have defined in your application domain model.

For instance, if you have entity class annotated with SDG’s @Region mapping annotation:

Customer entity class annotated with @Region. 

@Region("Customers")
class Customer {

  @Id
  private Long id;

  @Indexed
  private String name;

  ...
}

Then SBDG will create Regions from the name specified in the @Region mapping annotation on the entity class. In this case, the Customer application-defined entity class will result in the creation of a Region named "Customers" when the main @SpringBootApplication class is annotated with @EnableEntityDefinedRegions:

Using @EnableEntityDefinedRegions. 

@SpringBootApplication
@EnableEntityDefinedRegions(basePackageClasses = Customer.class,
    clientRegionShortcut = ClientRegionShortcut.CACHING_PROXY)
class SpringBootApacheGeodeClientCacheApplication { ... }

Like the @EnableCachingDefinedRegions annotation, you can set the client and server Region data management policy using the clientRegionShortcut and serverRegionShortcut attributes, respectively, as well as set a dedicated Pool of connections used by client Regions with the poolName attribute.

However, unlike the @EnableCachingDefinedRegions annotation, users are required to specify either the basePackage, or the type-safe alternative, basePackageClasses attribute (recommended) when using the @EnableEntityDefinedRegions annotation.

Part of the reason for this is that @EnableEntityDefinedRegions performs a component scan for the entity classes defined by your application. The component scan loads each class to inspect the Annotation metadata for that class. This is not unlike the JPA entity scan when working with JPA providers like Hibernate.

Therefore, it is customary to limit the scope of the scan, otherwise you end up potentially loading many classes unnecessarily so. After all, the JVM uses dynamic linking to only load classes when needed.

Both the basePackages and basePackageClasses attributes accept an array of values. With basePackageClasses you only need to refer to a single class type in that package and every class in that package as well as classes in the sub-packages will be scanned to determine if the class type represents an entity. A class type is an entity if it is annotated with the @Region mapping annotation, otherwise it is not considered an entity.

By example, suppose you had the following structure:

Entity Scan. 

- example.app.crm.model
 |- Customer.class
 |- NonEntity.class
 |- contact
   |- Address.class
   |- PhoneNumber.class
   |- AnotherNonEntity.class
- example.app.accounts.model
 |- Account.class
...
..
.

Then, you could configure the @EnableEntityDefinedRegions as follows:

Targeting with @EnableEntityDefinedRegions. 

@SpringBootApplication
@EnableEntityDefinedRegions(basePackageClasses = { NonEntity.class, Account.class } )
class SpringBootApacheGeodeClientCacheApplication { ... }

If Customer, Address, PhoneNumber and Account were all entity classes properly annotated with @Region, then the component scan would pick up all these classes and create Regions for them. The NonEntity class only serves as a marker in this case pointing to where (i.e. what package) the scan should begin.

Additionally, the @EnableEntityDefinedRegions annotation provides include and exclude filters, the same as the core Spring Frameworks @ComponentScan annotation.

	Tip
	Refer to the SDG Reference Guide on Configuring Regions for more details.

@EnableClusterDefinedRegions

Sometimes it is ideal or even necessary to pull configuration from the cluster (rather than push to the cluster). That is, you want the Regions defined on the servers to be created on the client and used by your application.

This is as simple as annotating your main @SpringBootApplication class with @EnableClusterDefinedRegions:

Using @EnableClusterDefinedRegions. 

@SpringBootApplication
@EnableClusterDefinedRegions
class SpringBootApacheGeodeClientCacheApplication { ... }

Every Region that exists on the cluster of servers will have a corresponding PROXY Region defined and created on the client as a bean in your Spring Boot application.

If the cluster of servers defines a Region called "ServerRegion" you can inject the client PROXY Region by the same name (i.e. "ServerRegion") into your Spring Boot application and use it:

Using a server-side Region on the client. 

@Component
class SomeApplicationComponent {

  @Resource(name = "ServerRegion")
  private Region<Integer, EntityType> serverRegion;

  public void sometMethod() {

    EntityType entity = ...;

    this.serverRegion.put(1, entity);

    ...
  }

Of course, SBDG auto-configures a GemfireTemplate for the "ServerRegion" Region (as described here), so a better way to interact with the client PROXY Region corresponding to the "ServerRegion" Region on the server is to inject the template:

Using a server-side Region on the client with a template. 

@Component
class SomeApplicationComponent {

  @Autowired
  @Qualifier("serverRegionTemplate")
  private GemfireTemplate serverRegionTemplate

  public void sometMethod() {

    EntityType entity = ...;

    this.serverRegionTemplate.put(1, entity);

    ...
  }

	Tip
	Refer to the SDG Reference Guide on Configuring Cluster-defined Regions for more details.

6.3.3 @EnableIndexing (SDG)

Only when using @EnableEntityDefinedRegions can you also use the @EnableIndexing annotation. This is because @EnableIndexing requires the entities to be scanned and analyzed for mapping metadata defined on the class type of the entity. This includes annotations like Spring Data Commons @Id annotation as well as SDG provided annotations, @Indexed and @LuceneIndexed.

The @Id annotation identifies the (primary) key of the entity. The @Indexed defines OQL Indexes on object fields which are used in the predicates of your OQL Queries. The @LuceneIndexed annotation is used to define Apache Lucene Indexes required for searches.

	Note
	Lucene Indexes can only be created on PARTITION Regions, and PARTITION Regions are only defined on the server-side.

You may have noticed that the Customer entity class’s name field was annotated with @Indexed.

Customer entity class with @Indexed annotated name field. 

@Region("Customers")
class Customer {

  @Id
  private Long id;

  @Indexed
  private String name;

  ...
}

As a result, when our main @SpringBootApplication class is annotated with @EnableIndexing:

Using @EnableIndexing. 

@SpringBootApplication
@EnableEntityDefinedRegions(basePackageClasses = Customer.class)
@EnableIndexing
class SpringBootApacheGeodeClientCacheApplication { ... }

An Apache Geode OQL Index for the Customer.name field will be created thereby making OQL Queries on Customers by name use this Index.

	Note
	Keep in mind that OQL Indexes are not persistent between restarts (i.e. Apache Geode & Pivotal GemFire maintains Indexes in-memory only). An OQL Index is always rebuilt when the node is restarted.

When you combine @EnableIndexing with either @EnableClusterConfiguration or @EnableClusterAware, then the Index definitions will be pushed to the server-side Regions where OQL Queries are generally executed.

	Tip
	Refer to the SDG Reference Guide on Configuring Indexes for more details.

6.3.4 @EnableExpiration (SDG)

It is often useful to define both Eviction and Expiration policies, particularly with a system like Apache Geode or Pivotal GemFire, especially given it primarily keeps data in-memory, on the JVM Heap. As you can imagine your data volume size may far exceed the amount of available JVM Heap memory and/or keeping too much data on the JVM Heap can cause Garbage Collection (GC) issues.

	Tip
	You can enable off-heap (or main memory usage) capabilities by declaring SDG’s @EnableOffHeap annotation. Refer to the SDG Reference Guide on Configuring Off-Heap Memory for more details.

Defining Eviction and Expiration policies is a useful for limiting what is kept in memory and for how long.

While configuring Eviction is easy with SDG, we particularly want to call out Expiration since configuring Expiration has special support in SDG.

With SDG, it is possible to define the Expiration policies associated with a particular application class type on the class type itself, using the @Expiration, @IdleTimeoutExpiration and @TimeToLiveExpiration annotations.

	Tip
	Refer to the Apache Geode User Guide for more details on the different Expiration Types (i.e. Idle Timeout (TTI) vs. Time-To-Live (TTL)).

For example, suppose we want to limit the number of Customers maintained in memory for a period of time (measured in seconds) based on the last time a Customer was accessed (e.g. read). We can the define an Idle Timeout Expiration policy on our Customer class type, like so:

Customer entity class with @Indexed annotated name field. 

@Region("Customers")
@IdleTimeoutExpiration(action = "INVALIDATE", timeout = "300")
class Customer {

  @Id
  private Long id;

  @Indexed
  private String name;

  ...
}

The Customer entry in the "Customers" Region will be invalidated after 300 seconds (or 5 minutes).

All we need to do to enable annotation-based Expiration policies is annotate our main @SpringBootApplication class with @EnableExpiration:

Enabling Expiration. 

@SpringBootApplication
@EnableExpiration
class SpringBootApacheGeodeApplication { ... }

	Note
	Technically, this entity class specific Annotation-based Expiration policy is implemented using Apache Geode’s CustomExpiry interface.

	Tip
	Refer to the SDG Reference Guide for more details on configuring Expiration, along with Annotation-based Data Expiration in particular.

@RunWith(SpringRunner.class)
@SpringBootTest
class MyApplicationTestClass {

  @Test
  public void someTestCase() {
    ...
  }

  @Configuration
  @EnableGemFireMockObjects
  static class GeodeConfiguration { }

}

@SpringBootApplication
@EnableEntityDefinedRegions(basePackageClasses = Customer.class)
class SpringBootApacheGeodeClientCacheApplication { ... }

@RunWith(SpringRunner.class)
@SpringBootTest
class MyApplicationTestClass {

  @Resource(name = "Customers")
  private Region<Long, Customer> customers;

  @Test
  public void someTestCase() {

    Customer jonDoe = ...;

    // Use the application in some way and test the interaction on the "Customers" Region

    assertThat(this.customers).containsValue(jonDoe);

    ...
  }

  ...

}

The same capability applies to accessing the externalized configuration of Spring Session when using either Apache Geode or Pivotal GemFire as your (HTTP) Session state caching provider.

In this case, you simply only need to acquire a reference to an instance of the SpringSessionProperties class.

As before, you would specify Spring Session for Apache Geode (SSDG) properties as follows:

Spring Boot application.properties for Spring Session using Apache Geode as the (HTTP) Session state caching provider. 

# Spring Boot application.properties used to configure Apache Geode as a Session state caching provider in Spring Session

spring.session.data.gemfire.session.expiration.max-inactive-interval-seconds=300
spring.session.data.gemfire.session.region.name=UserSessions

Then, in your application:

Using SpringSessionProperties. 

@Component
class MyApplicationComponent {

  @Autowired
  private SpringSessionProperties springSessionProperties;

  public void someMethodUsingSpringSessionProperties() {

    String sessionRegionName = this.springSessionProperties.getSession().getRegion().getName();

    // do something with `sessionRegionName`
  }

  ...
}

Three different types of caching patterns can be applied with Spring when using Apace Geode or Pivotal GemFire for your application caching needs.

The 3 primary caching patterns include:

8.1.1 Look-Aside Caching

The caching pattern demonstrated in the example above is a form of Look-Aside Caching.

Essentially, the data of interest is searched for in the cache first, before calling a potentially expensive operation, e.g. like an operation that makes an IO or network bound request resulting in either a blocking, or a latency sensitive computation.

If the data can be found in the cache (stored in-memory to reduce latency) then the data is returned without ever invoking the expensive operation. If the data cannot be found in the cache, then the operation must be invoked. However, before returning, the result of the operation is cached for subsequent requests when the the same input is requested again, by another caller resulting in much improved response times.

Again, typical Look-Aside Caching pattern applied in your application code looks similar to the following:

Look-Aside Caching Pattern Applied. 

@Service
class CustomerService {

  private final CustomerRepository customerRepository;

  @Cacheable("Customers")
  Customer findByAcccount(Account account) {

    // pre-processing logic here

    Customer customer = customerRepository.findByAccoundNumber(account.getNumber());

    // post-processing logic here

    return customer;
  }
}

In this design, the CustomerRepository is perhaps a JDBC or JPA/Hibernate backed implementation accessing the external data source (i.e. RDBMS) directly. The @Cacheable annotation wraps, or "decorates", the findByAccount(:Account):Customer operation to provide caching facilities.

	Note
	This operation may be expensive because it might validate the Customer’s Account before looking up the Customer, pull multiple bits of information to retrieve the Customer record, and so on, hence the need for caching.

8.1.2 Near Caching

Near Caching is another pattern of caching where the cache is collocated with the application. This is useful when the caching technology is configured using a client/server arrangement.

We already mentioned that Spring Boot for Apache Geode & Pivotal GemFire provides an auto-configured, ClientCache instance, out-of-the-box, by default. The ClientCache instance is most effective when the data access operations, including cache access, is distributed to the servers in a cluster accessible by the client, and in most cases, multiple clients. This allows other cache client applications to access the same data. However, this also means the application will incur a network hop penalty to evaluate the presence of the data in the cache.

To help avoid the cost of this network hop in a client/server topology, a local cache can be established, which maintains a subset of the data in the corresponding server-side cache (i.e. Region). Therefore, the client cache only contains the data of interests to the application. This "local" cache (i.e. client-side Region) is consulted before forwarding the lookup request to the server.

To enable Near Caching when using either Apache Geode or Pivotal GemFire, simply change the Region’s (i.e. the Cache in Spring’s Cache Abstraction) data management policy from PROXY (the default) to CACHING_PROXY, like so:

@SpringBootApplication
@EnableCachingDefinedRegions(clientRegionShortcut = ClientRegionShortcut.CACHING_PROXY)
class FinancialLoanApplication {

    public static void main(String[] args) {
        SpringApplication.run(FinancialLoanApplication.class, args);
    }
}

	Tip
	The default, client Region data management policy is ClientRegionShortcut.PROXY. As such, all data access operations are immediately forwarded to the server.

	Tip
	Also see the Apache Geode documentation concerning Client/Server Event Distribution and specifically, "Client Interest Registration on the Server" when using local, client CACHING_PROXY Regions to manage state in addition to the corresponding server-side Region. This is necessary to receive updates on entries in the Region that might have been changed by other clients accessing the same data.

8.1.3 Inline Caching

The final pattern of caching we’ll discuss is Inline Caching.

When employing Inline Caching and a cache miss occurs, the application service method may still not be invoked since the a Region can be configured to invoke a loader to load the missing entry from an external data source.

With Apache Geode and Pivotal GemFire, the cache, or using Apache Geode/Pivotal GemFire terminology, the Region, can be configured with a CacheLoader. This CacheLoader is implemented to retrieve missing values from some external data source, which could be an RDBMS or any other type of data store (e.g. another NoSQL store like Apache Cassandra, MongoDB or Neo4j).

	Tip
	See the Apache Geode User Guide on Data Loaders for more details.

Likewise, an Apache Geode or Pivotal Gemfire Region can be configured with a CacheWriter. A CacheWriter is responsible for writing any entry put into the Region to the backend data store, such as an RDBMS. This is referred to as a "write-through" operations because it is synchronous. If the backend data store fails to be written to then the entry will not be stored in the Region. This helps to ensure some level of consistency between the backing data store and the Apache Geode or Pivotal GemFire Region.

	Tip
	It is also possible to implement Inline-Caching using an asynchronous, write-behind operation by registering an AsyncEventListener on an AEQ tied to a server-side Region. You should consult the Apache Geode User Guide for more details.

	Note
	Since SBDG is currently focused on the client-side, async, write-behind behavior is not currently covered with extensive, convenient support, although, it is still very much possible to do.

The typical pattern of Inline Caching when applied to application code looks like the following:

Inline Caching Pattern Applied. 

@Service
class CustomerService {

  private CustomerRepository customerRepository;

  Customer findByAccount(Account account) {

      // pre-processing logic here

      Customer customer = customerRepository.findByAccountNumber(account.getNumber());

      // post-processing locic here.

      return customer;
  }
}

The main difference is, there are no Spring or JSR-107 caching annotations applied to the service methods and the CustomerRepository is accessing Apache Geode or Pivotal GemFire directly and NOT the RDBMS.

Implementing CacheLoaders, CacheWriters for Inline Caching

You can use Spring to configure a CacheLoader or CacheWriter as a bean in the Spring ApplicationContext and then wire it to a Region. Given the CacheLoader or CacheWriter is a Spring bean like any other bean in the Spring ApplicationContext, you can inject any DataSource you like into the Loader/Writer.

While you can configure client Regions with CacheLoaders and CacheWriters, it is typically more common to configure the corresponding server-side Region; for example:

@SpringBootApplication
@CacheServerApplication
class FinancialLoanApplicationServer {

    public static void main(String[] args) {
        SpringApplication.run(FinancialLoanApplicationServer.class, args);
    }

	@Bean("EligibilityDecisions")
	PartitionedRegionFactoryBean<Object, Object> eligibilityDecisionsRegion(
            GemFireCache gemfireCache, CacheLoader decisionManagementSystemLoader,
            CacheWriter decisionManagemenSystemWriter) {

        PartitionedRegionFactoryBean<?, EligibilityDecision> eligibilityDecisionsRegion =
            new PartitionedRegionFactoryBean<>();

        eligibilityDecisionsRegion.setCache(gemfireCache);
        eligibilityDecisionsRegion.setCacheLoader(decisionManagementSystemLoader);
        eligibilityDecisionsRegion.setCacheWriter(decisionManagementSystemWriter);
        eligibilityDecisionsRegion.setClose(false);
        eligibilityDecisionsRegion.setPersistent(false);

        return eligibilityDecisionsRegion;
    }


    @Bean
    CacheLoader<?, EligibilityDecision> decisionManagementSystemLoader(
            DataSource dataSource) {

        return new DecisionManagementSystemLoader(dataSource);
    }

    @Bean
    CacheWriter<?, EligibilityDecision> decisionManagementSystemWriter(
            DataSource dataSource) {

        return new DecisionManagementSystemWriter(dataSource);
    }

    @Bean
    DataSource dataSource(..) {
      ...
    }
}

Then, you would implement the CacheLoader and CacheWriter interfaces as appropriate:

DecisionManagementSystemLoader. 

class DecisionManagementSystemLoader implements CacheLoader<?, EligibilityDecision> {

  private final DataSource dataSource;

  DecisionManagementSystemLoader(DataSource dataSource) {
    this.dataSource = dataSource;
  }

  public EligibilityDecision load(LoadHelper<?, EligibilityDecision> helper) {

     Object key = helper.getKey();

     // Use the configured DataSource to load the value from an external data store.

     return ...
   }
}

	Tip
	SBDG provides the org.springframework.geode.cache.support.CacheLoaderSupport @FunctionalInterface to conveniently implement application CacheLoaders.

If the configured CacheLoader still cannot resolve the value, then the cache lookup operation results in a miss and the application service method will then be invoked to compute the value.

DecisionManagementSystemWriter. 

class DecisionManagementSystemWriter implements CacheWriter<?, EligibilityDecision> {

  private final DataSource dataSource;

  DecisionManagementSystemWriter(DataSource dataSource) {
    this.dataSource = dataSource;
  }

  public void beforeCreate(EntryEvent<?, EligiblityDecision> entryEvent) {
    // Use configured DataSource to save (e.g. INSERT) the entry to the backend data store
  }

  public void beforeUpdate(EntryEvent<?, EligiblityDecision> entryEvent) {
    // Use the configured DataSource to save (e.g. UPDATE or UPSERT) the entry in the backend data store
  }

  public void beforeDestroy(EntryEvent<?, EligiblityDecision> entryEvent) {
    // Use the configured DataSource to delete (i.e. DELETE) the entry from the backend data store
  }

  ...
}

	Tip
	SBDG provides the org.springframework.geode.cache.support.CacheWriterSupport interface to conveniently implement application CacheWriters.

	Note
	Of course, your CacheWriter implementation can use any data access technology to interface with your backend data store (e.g. JDBC, Spring’s JdbcTemplate, JPA/Hibernate, etc). It is not limited to only using a javax.sql.DataSource. In fact, we will present another, more useful and convenient approach to implementing Inline Caching in the next section.

Inline Caching using Spring Data Repositories.

Spring Boot for Apache Geode & Pivotal GemFire (SBDG) now offers dedicated support and configuration of Inline Caching using Spring Data Repositories.

This is very powerful because it allows you to:

1. Access any backend data store supported by Spring Data (e.g. Redis for Key/Value or other data structures, MongoDB for Documents, Neo4j for Graphs, Elasticsearch for Search, and so on).
2. Use complex mapping strategies (e.g. ORM provided by JPA/Hibernate).

It is our belief that users should be putting data where it is most easily accessible. If you are accessing and processing Documents, then most likely MongoDB (or Couchbase or another document store) might be the most logical choice to manage your application’s Documents.

However, that does not mean you have to give up Apache Geode or Pivotal GemFire in your application/system architecture. You can leverage each data store for what it is good at. While MongoDB is good at Document handling, Apache Geode is a highly valuable choice for consistency, high availability, multi-site, low-latency/high-throughput scale-out Use Cases.

As such, using Apache Geode and Pivotal GemFire’s CacheLoader/CacheWriter mechanism provides a integration point between itself and other data stores to best serve your Use Case and application requirements/needs.

And now, SBDG just made this even easier.

EXAMPLE

Let’s say you are using JPA/Hibernate to access (store and retrieve) data in a Oracle Database.

Then, you can configure Apache Geode to read/write-through to the backend Oracle Database when performing cache (Region) operations by delegating to a Spring Data (JPA) Repository.

The configuration might look something like:

Inline Caching configuration using SBDG. 

@SpringBootApplication
@EntityScan(basePackageClasses = Customer.class)
@EnableEntityDefinedRegions(basePackageClasses = Customer.class)
@EnableJpaRepositories(basePackageClasses = CustomerRepository.class)
class SpringBootOracleDatabaseApacheGeodeApplication {

  @Bean
  InlineCachingRegionConfigurer<Customer, Long> inlineCachingForCustomersRegionConfigurer(
      CustomerRepository customerRepository) {

    return new InlineCachingRegionConfigurer<>(customerRepository, Predicate.isEqual("Customers"));
  }
}

Out-of-the-box, SBDG provides the InlineCachingRegionConfigurer<ENTITY, ID> interface.

Given a Predicate to express and match the target Region by name along with a Spring Data CrudRepository, the InlineCachingRegionConfigurer will configure and adapt the Spring Data CrudRepository as a CacheLoader and CacheWriter for the Region (e.g. "Customers"), i.e. it enables the Region to use Inline Caching.

You simply only need to declare InlineCachingRegionConfigurer as a bean in the Spring application context and make the association between the Region (by name) and the appropriate Spring Data CrudRepository.

In this example, we used JPA and Spring Data JPA to store/retrieve the data in the cache (Region) to/from a backend database. But, you can inject any Spring Data Repository for any data store (e.g. Redis, MongoDB, etc) that supports the Spring Data Repository abstraction.

	Tip
	If you only want to support oneway data access operations when using Inline Caching, then you can use either the RepositoryCacheLoaderRegionConfigurer for reads or the RepositoryCacheWriterRegionConfigurer for writes, instead of the InlineCachingRegionConfigurer, which supports both reads and writes.

	Tip
	To see a similar implementation of Inline Caching using a Database (In-Memory, HSQLDB Database) in action, have a look at this test class from the SBDG test suite. A dedicated sample will be provided in a future release.

Both Apache Geode and Pivotal GemFire support additional caching capabilities to manage the entries stored in the cache.

As you can imagine, given the cache entries are stored in-memory, it becomes important to monitor and manage the available memory wisely. After all, by default, both Apache Geode and Pivotal GemFire store data in the JVM Heap.

Several techniques can be employed to more effectively manage memory, such as using Eviction, possibly overflowing to disk, configuring both entry Idle-Timeout (TTI) as well as Time-To-Live (TTL) Expiration policies, configuring Compression, and using Off-Heap, or main memory.

There are several other strategies that can be used as well, as described in Managing Heap and Off-heap Memory.

While this is well beyond the scope of this document, know that Spring Data for Apache Geode & Pivotal GemFire make all of these configuration options simple.

There may be cases where you do not want your Spring Boot application to cache application state with Spring’s Cache Abstraction using either Apache Geode or Pivotal GemFire. In certain cases, you may be using another Spring supported caching provider, such as Redis, to cache and manage your application state, while, even in other cases, you may not want to use Spring’s Cache Abstraction at all.

Either way, you can specifically call out your Spring Cache Abstraction provider using the spring.cache.type property in application.properties, as follows:

Use Redis as the Spring Cache Abstraction Provider. 

#application.properties

spring.cache.type=redis
...

If you prefer not to use Spring’s Cache Abstraction to manage your Spring Boot application’s state at all, then do the following:

Disable Spring’s Cache Abstraction. 

#application.properties

spring.cache.type=none
...

See Spring Boot docs for more details.

	Tip
	It is possible to include multiple providers on the classpath of your Spring Boot application. For instance, you might be using Redis to cache your application’s state while using either Apache Geode or Pivotal GemFire as your application’s persistent store (System of Record).

	Note
	Spring Boot does not properly recognize spring.cache.type=[gemfire|geode] even though Spring Boot for Apache Geode/Pivotal GemFire is setup to handle either of these property values (i.e. either “gemfire” or “geode”).

Given an explicitly declared Region bean definition:

@Configuration
class GemFireConfiguration {

  @Bean("Example")
  ClientRegionFactoryBean<?, ?> exampleRegion (GemFireCache gemfireCache) {
    ...
  }
}

SBDG will automatically create a GemfireTemplate bean for the "Example" Region using a bean name "exampleTemplate". SBDG will name the GemfireTemplate bean after the Region by converting the first letter in the Region’s name to lowercase and appending the word "Template" to the bean name.

In a managed Data Access Object (DAO), I can inject the Template, like so:

@Repository
class ExampleDataAccessObject {

  @Autowired
  @Qualifier("exampleTemplate")
  private GemfireTemplate exampleTemplate;

}

It’s advisable, especially if you have more than 1 Region, to use the @Qualifier annotation to qualify which GemfireTemplate bean you are specifically referring as demonstrated above.

SBDG auto-configures GemfireTemplate beans for Entity-defined Regions.

Given the following entity class:

@Region("Customers")
class Customer {
  ...
}

And configuration:

@Configuration
@EnableEntityDefinedRegions(basePackageClasses = Customer.class}
class GemFireConfiguration {
  ...
}

SBDG auto-configures a GemfireTemplate bean for the "Customers" Region named "customersTemplate", which you can then inject into an application component:

@Service
class CustomerService {

  @Bean
  @Qualifier("customersTemplate")
  private GemfireTemplate customersTemplate;

}

Again, be careful to qualify the GemfireTemplate bean injection if you have multiple Regions, whether declared explicitly or implicitly, such as when using the @EnableEntityDefineRegions annotation.

SBDG auto-configures GemfireTemplate beans for Caching-defined Regions.

When you are using Spring Framework’s Cache Abstraction backed by either Apache Geode or Pivotal GemFire, 1 of the requirements is to configure Regions for each of the caches specified in the Caching Annotations of your application service components.

Fortunately, SBDG makes enabling and configuring caching easy and automatic out-of-the-box.

Given a cacheable application service component:

@Service
class CacheableCustomerService {

  @Bean
  @Qualifier("customersByNameTemplate")
  private GemfireTemplate customersByNameTemplate;

  @Cacheable("CustomersByName")
  public Customer findBy(String name) {
    return toCustomer(customersByNameTemplate.query("name = " + name));
  }
}

And configuration:

@Configuration
@EnableCachingDefinedRegions
class GemFireConfiguration {

  @Bean
  public CustomerService customerService() {
    return new CustomerService();
  }
}

SBDG auto-configures a GemfireTemplate bean named "customersByNameTemplate" used to perform data access operations on the "CustomersByName" (@Cacheable) Region, which you can inject into any managed application component, as shown above.

Again, be careful to qualify the GemfireTemplate bean injection if you have multiple Regions, whether declared explicitly or implicitly, such as when using the @EnableCachingDefineRegions annotation.

Warning

There are certain cases where autowiring (i.e. injecting) GemfireTemplate beans auto-configured by SBDG for Caching-defined Regions into your application components will not always work! This has to do with the Spring Container bean creation process. In those case you may need to lazily lookup the GemfireTemplate as needed, using applicationContext.getBean("customersByNameTemplate", GemfireTemplate.class). This is certainly not ideal but works when autowiring does not.

SBDG will even auto-configure GemfireTemplate beans for Regions defined using Apache Geode and Pivotal GemFire native configuration meta-data, such as cache.xml.

Given the following GemFire/Geode native cache.xml:

<?xml version="1.0" encoding="UTF-8"?>
<client-cache xmlns="http://geode.apache.org/schema/cache"
			  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
			  xsi:schemaLocation="http://geode.apache.org/schema/cache http://geode.apache.org/schema/cache/cache-1.0.xsd"
			  version="1.0">

	<region name="Example" refid="LOCAL"/>

</client-cache>

And Spring configuration:

@Configuration
@EnableGemFireProperties(cacheXmlFile = "cache.xml")
class GemFireConfiguration {
  ...
}

SBDG will auto-configure a GemfireTemplate bean named "exampleTemplate" after the "Example" Region defined in cache.xml. This Template can be injected like any other Spring managed bean:

@Service
class ExampleService {

  @Autowired
  @Qualifier("exampleTemplate")
  private GemfireTemplate exampleTemplate;

}

The same rules as above apply when multiple Regions are present.

Fortunately, SBDG is careful not to create a GemfireTemplate bean for a Region if a Template by the same name already exists. For example, if you defined and declared the following configuration:

@Configuration
@EnableEntityDefinedRegions(basePackageClasses = Customer.class)
class GemFireConfiguration {

  @Bean
  public GemfireTemplate customersTemplate(GemFireCache cache) {
    return new GemfireTemplate(cache.getRegion("/Customers");
  }
}

Using our same Customers class, as above:

@Region("Customers")
class Customer {
  ...
}

Because you explicitly defined the "customersTemplate" bean, SBDG will not create a Template for the "Customers" Region automatically. This applies regardless of how the Region was created, whether using @EnableEntityDefinedRegions, @EnableCachingDefinedRegions, declaring Regions explicitly or defining Regions natively.

Even if you name the Template differently from the Region for which the Template was configured, SBDG will conserve resources and not create the Template.

For example, suppose you named the GemfireTemplate bean, "vipCustomersTemplate", even though the Region name is "Customers", based on the @Region annotated Customer class, which specified Region "Customers".

With the following configuration, SBDG is still careful not to create the Template:

@Configuration
@EnableEntityDefinedRegions(basePackageClasses = Customer.class)
class GemFireConfiguration {

  @Bean
  public GemfireTemplate vipCustomersTemplate(GemFireCache cache) {
    return new GemfireTemplate(cache.getRegion("/Customers");
  }
}

SBDG identifies that your "vipCustomersTemplate" is the Template used with the "Customers" Region and SBDG will not create the "customersTemplate" bean, which would result in 2 GemfireTemplate beans for the same Region.

	Note
	The name of your Spring bean defined in JavaConfig is the name of the method if the Spring bean is not explicitly named using the name (or value) attribute of the @Bean annotation.

Distributed processing, particularly in conjunction with data access and mutation operations, is a very effective and efficient use of clustered computing resources. This is along the same lines as MapReduce.

A naively conceived query returning potentially hundreds of thousands, or even millions of rows of data in a result set back to the application that queried and requested the data can be very costly, especially under load. Therefore, it is typically more efficient to move the processing and computations on the predicated data set to where the data resides, perform the required computations, summarize the results and then send the reduced data set back to the client.

Additionally, when the computations are handled in parallel, across the cluster of computing resources, the operation can be performed much faster. This typically involves intelligently organizing the data using various partitioning (a.k.a. sharding) strategies to uniformly balance the data set across the cluster.

Well, both Apache Geode and Pivotal GemFire address this very important application concern in its Function Execution framework.

Spring Data for Apache Geode/Pivotal GemFire builds on this Function Execution framework by enabling developers to implement and execute GemFire/Geode Functions using a very simple POJO-based, annotation configuration model.

	Tip
	See here for the difference between Function implementation & executions.

Taking this 1 step further, Spring Boot for Apache Geode/Pivotal GemFire auto-configures and enables both Function implementation and execution out-of-the-box. Therefore, you can immediately begin writing Functions and invoking them without having to worry about all the necessary plumbing to begin with. You can rest assured that it will just work as expected.

Earlier, when we talked about caching, we described a FinancialLoanApplicationService class that could process eligibility when a Person applied for a financial loan.

This can be a very resource intensive & expensive operation since it might involve collecting credit and employment history, gathering information on existing, outstanding/unpaid loans, and so on and so forth. We applied caching in order to not have to recompute, or redetermine eligibility every time a loan office may want to review the decision with the customer.

But what about the process of computing eligibility in the first place?

Currently the application’s FinancialLoanApplicationService class seems to be designed to fetch the data and perform the eligibility determination in place. However, it might be far better to distribute the processing and even determine eligibility for a larger group of people all at once, especially when multiple, related people are involved in a single decision, as is typically the case.

We implement an EligibilityDeterminationFunction class using SDG very simply as:

Function implementation. 

@Component
class EligibilityDeterminationFunction {

    @GemfireFunction(HA = true, hasResult = true, optimizeForWrite=true)
    public EligibilityDecision determineEligibility(FunctionContext functionContext, Person person, Timespan timespan) {
        ...
    }
}

Using the SDG @GemfireFunction annotation, it is easy to implement our Function as a POJO method. SDG handles registering this POJO method as a proper Function with GemFire/Geode appropriately.

If we now want to call this Function from our Spring Boot, ClientCache application, then we simply define a Function Execution interface with a method name matching the Function name, and targeting the execution on the "EligibilityDecisions" Region:

Function execution. 

@OnRegion("EligibilityDecisions")
interface EligibilityDeterminationExecution {

  EligibilityDecision determineEligibility(Person person, Timespan timespan);

}

We can then inject the EligibilityDeterminationExecution into our FinancialLoanApplicationService like any other object/Spring bean:

Function use. 

@Service
class FinancialLoanApplicationService {

    private final EligibilityDeterminationExecution execution;

    public LoanApplicationService(EligibilityDeterminationExecution execution) {
        this.execution = execution;
    }

    @Cacheable("EligibilityDecisions", ...)
    EligibilityDecision processEligility(Person person, Timespan timespan) {
        return this.execution.determineEligibility(person, timespan);
    }
}

Just like caching, no addition configuration is required to enable and find your application Function implementations and executions. Simply build and run. Spring Boot for Apache Geode/Pivotal GemFire handles the rest.

	Tip
	It is common to implement and register your application Functions on the server and execute them from the client.

Under-the-hood, Spring Boot for Apache Geode/Pivotal GemFire enables and uses Spring Data for Apache Geode/Pivotal GemFire’s MappingPdxSerializer to serialize your application domain objects using PDX.

	Tip
	Refer to the SDG Reference Guide for more details on the MappingPdxSerializer class.

The MappingPdxSerializer offers several advantages above and beyond GemFire/Geode’s own ReflectionBasedAutoSerializer class.

	Tip
	Refer to Apache Geode’s User Guide for more details about the ReflectionBasedAutoSerializer.

The SDG MappingPdxSerializer offers the following capabilities:

Number two above deserves special attention since the MappingPdxSerializer "excludes" all Java, Spring and Apache Geode/Pivotal GemFire types, by default. But, what happens when you need to serialize 1 of those types?

For example, suppose you need to be able to serialize objects of type java.security.Principal. Well, then you can override the excludes by registering an "include" type filter, like so:

package example.app;

import java.security.Principal;
import ...;

@SpringBootApplication
@EnablePdx(serializerBeanName = "myCustomMappingPdxSerializer")
class SpringBootApacheGeodeClientCacheApplication {

    public static void main(String[] args) {
        SpringApplication.run(SpringBootApacheGeodeClientCacheApplication.class, args);
    }

    @Bean
    MappingPdxSerializer myCustomMappingPdxSerializer() {

        MappingPdxSerializer customMappingPdxSerializer =
            MappingPdxSerializer.newMappginPdxSerializer();

        customMappingPdxSerializer.setIncludeTypeFilters(
            type -> Principal.class.isAssignableFrom(type));

        return customMappingPdxSerializer;
    }
}

	Tip
	Normally, you do not need to explicitly declare SDG’s @EnablePdx annotation to enable and configure PDX. However, if you want to override auto-configuration, as we have demonstrated above, then this is what you must do.

Apache Geode & Pivotal GemFire employs Username and Password based Authentication along with Role-based Authorization to secure your client to server data exchanges and operations.

Spring Data for Apache Geode & Pivotal GemFire (SDG) provides first-class support for Apache Geode & Pivotal GemFire’s Security framework, which is based on the SecurityManager interface. Additionally, Apache Geode’s Security framework is integrated with Apache Shiro, making the security for servers an even easier and more familiar task.

	Note
	Eventually, support and integration with Spring Security will be provided by SBDG as well.

When you use Spring Boot for Apache Geode & Pivotal GemFire (SBDG), which builds on the bits provided in Spring Data for Apache Geode & Pivotal GemFire (SDG), it makes short work of enabling Auth in both your clients and servers.

14.1.1 Auth for Servers

The easiest and most standard way to enable Auth in the servers of your cluster is to simply define 1 or more Apache Shiro Realms as beans in the Spring ApplicationContext.

For example:

Declaring an Apache Shiro Realm. 

@Configuration
class ApacheGeodeSecurityConfiguration {

    @Bean
    DefaultLdapRealm ldapRealm(..) {
        return new DefaultLdapRealm();
    }

    ...
}

When an Apache Shiro Realm (e.g. DefaultLdapRealm) is declared and registered in the Spring ApplicationContext as a Spring bean, Spring Boot will automatically detect this Realm bean (or Realm beans if more than 1 is configured) and the Apache Geode & Pivotal GemFire servers in the cluster will automatically be configured with Authentication and Authorization enabled.

Alternatively, you can provide an custom, application-specific implementation of Apache Geode & Pivotal GemFire’s SecurityManager interface, declared and registered as a bean in the Spring ApplicationContext:

Declaring a custom Apache Geode or Pivotal GemFire SecurityManager. 

@Configuration
class ApacheGeodeSecurityConfiguration {

    @Bean
    CustomSecurityManager customSecurityManager(..) {
        return new CustomSecurityManager();
    }

    ...
}

Spring Boot will discover your custom, application-specific SecurityManager implementation and configure the servers in the Apache Geode or Pivotal GemFire cluster with Authentication and Authorization enabled.

	Tip
	The Spring team recommends that you use Apache Shiro to manage the Authentication & Authorization of your Apache Geode or Pivotal GemFire servers over implementing Apache Geode or Pivotal GemFire’s SecurityManager interface.

# Spring Boot client application.properties

spring.data.gemfire.security.username = jdoe
spring.data.gemfire.security.password = p@55w0rd

Securing data in motion is also essential to the integrity of your application.

For instance, it would not do much good to send usernames and passwords over plain text Socket connections between your clients and servers, nor send sensitive data over those same connections.

Therefore, both Apache Geode & Pivotal GemFire support SSL between clients & servers, JMX clients (e.g. Gfsh) and the Manager, HTTP clients when using the Developer REST API or Pulse, between peers in the cluster, and when using the WAN Gateway to connect multiple sites (i.e. clusters).

Spring Data for Apache Geode & Pivotal GemFire (SDG) provides first-class support for configuring and enabling SSL as well. Still, Spring Boot makes it even easier to configure and enable SSL, especially during development.

Apache Geode & Pivotal GemFire require certain properties to be configured, which translate to the appropriate javax.net.ssl.* properties required by the JRE, to create Secure Socket Connections using JSSE.

But, ensuring that you have set all the required SSL properties correctly is an error prone and tedious task. Therefore, Spring Boot for Apache Geode & Pivotal GemFire (SBDG) applies some basic conventions for you, out-of-the-box.

Simply create a trusted.keystore, JKS-based KeyStore file and place it in 1 of 3 well-known locations:

When this file is named trusted.keystore and is placed in 1 of these 3 well-known locations, Spring Boot for Apache Geode & Pivotal GemFire (SBDG) will automatically configure your client to use SSL Socket connections.

If you are using Spring Boot to configure and bootstrap an Apache Geode or Pivotal GemFire server:

Spring Boot configured and bootstrapped Apache Geode or Pivotal GemFire server. 

@SpringBootApplication
@CacheServerApplication
class SpringBootApacheGeodeCacheServerApplication {
    ...
}

Then, Spring Boot will apply the same procedure to enable SSL on the servers, between peers, as well.

	Tip
	During development it is convenient not to set a trusted.keystore password when accessing the keys in the JKS file. However, it is highly recommended that you secure the trusted.keystore file when deploying your application to a production environment.

If your trusted.keystore file is secured with a password, you will need to additionally specify the following property:

Accessing a secure trusted.keystore. 

# Spring Boot application.properties

spring.data.gemfire.security.ssl.keystore.password = p@55w0rd!

You can also configure the location of the keystore and truststore files, if they are separate, and have not been placed in 1 of the default, well-known locations searched by Spring Boot:

Accessing a secure trusted.keystore. 

# Spring Boot application.properties

spring.data.gemfire.security.ssl.keystore = /absolute/file/system/path/to/keystore.jks
spring.data.gemfire.security.ssl.keystore.password = keystorePassword
spring.data.gemfire.security.ssl.truststore = /absolute/file/system/path/to/truststore.jks
spring.data.gemfire.security.ssl.truststore.password = truststorePassword

See the SDG EnableSsl annotation for all the configuration attributes and the corresponding properties expressed in application.properties.

Currently, neither Apache Geode nor Pivotal GemFire along with Spring Boot or Spring Data for Apache Geode and Pivotal GemFire offer any support for securing your data while at rest (e.g. when your data has been overflowed or persisted to disk).

To secure data at rest when using Apache Geode or Pivotal GemFire, with or without Spring, you must employ 3rd party solutions like disk encryption, which is usually highly contextual and technology specific.

For example, to secure data at rest using Amazon EC2, see Instance Store Encryption.

So, how do you configure logging for Apache Geode and Pivotal GemFire?

Effectively, 3 things are required to get Apache Geode or Pivotal GemFire to log output:

1) First, you must declare a logging provider on your Spring Boot application classpath (e.g. Logback).

2) (optional) Next, you must declare an adapter, or bridge JAR, between Log4j and your logging provider if your declared logging provider is not Apache Log4j.

For example, if you use the SLF4J API to log output from your Spring Boot application along with Logback as your logging provider/implementation, then you must include the org.apache.logging.log4j.log4j-to-slf4j adapter/bridge JAR dependency as well.

Internally, Apache Geode uses the Apache Log4j API to log output from Geode components. Therefore, you must bridge Log4j to any other logging provider (e.g. Logback) that is not Log4j (i.e. log4j-core). If you are using Log4j as your logging provider then you do not need to declare an adapter/bridge JAR on your Spring Boot application classpath.

3) Finally, you must supply logging provider configuration to configure Loggers, Appenders, log levels, etc.

For example, when using Logback, you must provide a logback.xml configuration file on your Spring Boot application classpath, or in the filesystem. Alternatively, you can use other means to configure your logging provider and get Apache Geode to log output.

	Note
	Apache Geode’s geode-log4j module covers the required configuration for steps 1-3 above and uses Apache Log4j (i.e. org.apache.logging.log4j:log4j-core) as the logging provider. The geode-log4j module even provides a default, log4j2.xml configuration file to configure Loggers, Appenders and log levels for Apache Geode.

If you declare Spring Boot’s own org.springframework.boot:spring-boot-starter-logging on your application classpath then this will cover Steps 1 and 2 above.

The spring-boot-starter-logging dependency declares Logback as the logging provider and automatically adapts, or bridges java.util.logging (JUL) and Apache Log4j to SLF4J. However, you still need to supply logging provider configuration, such as a logback.xml file for Logback, to configure logging not only for your Spring Boot application, but also for Apache Geode as well.

SBDG has simplified the setup of Apache Geode and Pivotal GemFire logging. Simply declare the org.springframework.geode:spring-geode-starter-logging dependency on your Spring Boot application classpath!

Unlike Apache Geode’s default Log4j XML configuration file (i.e. log4j2.xml), SBDG’s provided logback.xml configuration file is properly parameterized enabling you to adjust log levels as well as add Appenders.

In addition, SBDG’s provided Logback configuration uses templates so you can compose your own logging configuration while still "including" snippets from SBDG’s provided logging configuration metadata, such as Loggers and Appenders.

15.1.1 Configuring Log Levels

One of the most common logging tasks is to adjust the log-level of one or more Loggers, or the ROOT Logger. However, a user may only want to adjust the log-level for specific components of his/her Spring Boot application, such as for Apache Geode, by setting the log-level for only the Logger that logs Apache Geode events.

SBDG’s Logback configuration defines 3 Loggers to control the log output from Apache Geode:

Apache Geode Loggers by name. 

<logger name="com.gemstone.gemfire" level="${spring.boot.data.gemfire.log.level:-INFO}"/>
<logger name="org.apache.geode" level="${spring.boot.data.gemfire.log.level:-INFO}"/>
<logger name="org.jgroups" level="${spring.boot.data.gemfire.jgroups.log.level:-ERROR}"/>

The com.gemstone.gemfire Logger is a legacy Logger covering old Pivotal GemFire bits still present in Apache Geode for backwards compatibility reasons. This Logger’s use should be largely unnecessary.

The org.apache.geode Logger is the primary Logger used to control log output from all Apache Geode components during the runtime operation of Apache Geode. Both this Logger and the legacy com.gemstone.gemfire Logger default log output to INFO.

The org.jgroups Logger is used to log output from Apache Geode’s message distribution and membership system. Apache Geode uses JGroups for membership and message distribution between peer members (nodes) in the cluster (distributed system). By default, JGroups log messages are logged at ERROR.

The log-level for the com.gemstone.gemfire and org.apache.geode Loggers are configured with the spring.boot.data.gemfire.log.level property. The org.jgroups Logger is independently configured with the spring.boot.data.gemfire.jgroups.log.level property.

The SBDG logging properties can be set on the command-line as JVM System Properties when running your Spring Boot application:

Setting the log-level from the command-line. 

$ java -classpath ...:/path/to/MySpringBootApplication.jar -Dspring.boot.data.gemfire.log.level=DEBUG
    package.to.MySpringBootApplicationClass

	Note
	Setting JVM System Properties using $ java -jar MySpringBootApplication.jar -Dspring.boot.data.gemfire.log.level=DEBUG is not supported by the Java Runtime Environment (JRE).

Alternatively, you can configure and control Apache Geode logging in Spring Boot application.properties:

Setting the log-level in application.properties. 

spring.boot.data.gemfire.log.level=DEBUG

For backwards compatibility, SBDG additionally supports the old Spring Data for Apache Geode (SDG) logging properties as well, using either:

spring.data.gemfire.cache.log-level=DEBUG

Or:

spring.data.gemfire.logging.level=DEBUG

If you previously used either of these SDG based logging properties, they will continue to work as designed in SBDG 1.3 or later.

<?xml version="1.0" encoding="UTF-8"?>
<included>

	<appender name="console" class="ch.qos.logback.core.ConsoleAppender">
		<encoder>
			<pattern>%d %5p %40.40c:%4L - %m%n</pattern>
		</encoder>
	</appender>

	<appender name="delegate" class="org.springframework.geode.logging.slf4j.logback.DelegatingAppender"/>

	<logger name="com.gemstone.gemfire" level="${spring.boot.data.gemfire.log.level:-INFO}"/>
	<logger name="org.apache.geode" level="${spring.boot.data.gemfire.log.level:-INFO}"/>
	<logger name="org.jgroups" level="${spring.boot.data.gemfire.jgroups.log.level:-ERROR}"/>

</included>

<?xml version="1.0" encoding="UTF-8"?>
<configuration debug="false">

	<statusListener class="ch.qos.logback.core.status.NopStatusListener"/>

	<include resource="logback-include.xml"/>

	<root level="${logback.root.log.level:-INFO}">
		<appender-ref ref="console"/>
		<appender-ref ref="delegate"/>
	</root>

</configuration>

SBDG provides additional support when working with the SLF4J and Logback APIs. This support is available when you declare the org.springframework.geode:spring-geode-starter-logging dependency on your Spring Boot application classpath.

One of the main supporting classes from the spring-geode-starter-logger is the org.springframework.geode.logging.slf4j.logback.LogbackSupport class. This class provides methods to:

LogbackSupport can even suppress the auto-configuration of Logback performed by Spring Boot on startup, another useful utility during automated testing.

In addition to the LogbackSupport class, SBDG also provides some custom Logback Appenders.

ConsoleAppender<ILoggingEvent> consoleAppender = ...;

FileAppender<ILoggingEvent> fileAppender = ...;

Appender<ILoggingEvent> compositeAppender = CompositeAppender.compose(consoleAppender, fileAppender);

// do something with the compositeAppender

Logger namedLogger = LoggerFactory.getLogger("loggerName");

LogbackSupport.toLogbackLogger(namedLogger)
  .ifPresent(it -> LogbackSupport.addAppender(it, compositeAppender));

ConsoleAppender consoleAppender = new ConsoleAppender();

LogbackSupport.resolveLoggerContext().ifPresent(consoleAppender::setContext);

consoleAppender.setImmediateFlush(true);
consoleAppender.start();

LogbackSupport.resolveRootLogger()
  .flatMap(LogbackSupport::toLogbackLogger)
  .flatMap(rootLogger -> LogbackSupport.resolveAppender(rootLogger,
    LogbackSupport.DELEGATE_APPENDER_NAME, DelegatingAppender.class))
  .ifPresent(delegateAppender -> delegateAppender.setAppender(consoleAppender));

class ApplicationComponent {

	private final Logger logger = LoggerFactory.getLogger(getClass());

	public void someMethod() {
		logger.debug("Some debug message");
		// ...
	}

	public void someOtherMethod() {
		logger.info("Some info message");
	}
}

// Assuming the ApplicationComponent Logger was configured with log-level 'INFO', then...
class ApplicationComponentUnitTests {

	private final ApplicationComponent applicationComponent = new ApplicationComponent();

	private final Logger logger = LoggerFactory.getLogger(ApplicationComponent.class);

	private StringAppender stringAppender;

	@Before
    public void setup() {

        LogbackSupport.toLogbackLogger(logger)
            .map(Logger::getLevel)
            .ifPresent(level -> assertThat(level).isEqualTo(Level.INFO));

        stringAppender = new StringAppender.Builder()
            .applyTo(logger)
            .build();
    }

    @Test
    public void someMethodDoesNotLogDebugMessage() {

        applicationComponent.someMethod();

        assertThat(stringAppender.getLogOutput).doesNotContain("Some debug message");
    }

    @Test
    public void someOtherMethodLogsInfoMessage() {

        applicationComponent.someOtherMethod();

        assertThat(stringAppender.getLogOutput()).contains("Some info message");
    }
}

The following section covers Spring Boot HealthIndicators that apply to both peer Cache and ClientCache, Spring Boot applications. That is, these HealthIndicators are not specific to the cache type.

In both Apache Geode and Pivotal GemFire, the cache instance is either a peer Cache instance, which makes your Spring Boot application part of a GemFire/Geode cluster, or more commonly, a ClientCache instance that talks to an existing cluster. Your Spring Boot application can only be one cache type or the other and can only have a single instance of that cache type.

The ClientCache based HealthIndicators provide additional details specifically for Spring Boot, cache client applications. These HealthIndicators are only available when the Spring Boot application creates a ClientCache instance (i.e. is a cache client), which is the default.

The peer Cache based HealthIndicators provide additional details specifically for Spring Boot, peer cache member applications. These HealthIndicators are only available when the Spring Boot application creates a peer Cache instance.

	Note
	The default cache instance created by Spring Boot for Apache Geode/Pivotal GemFire is a ClientCache instance.

	Tip
	To control what type of cache instance is created, such as a "peer", then you can explicitly declare either the @PeerCacheApplication, or alternatively, the @CacheServerApplication, annotation on your @SpringBootApplication annotated class.

There is nothing special that you need to do in order to use either Apache Geode or Pivotal GemFire as a Spring Session provider, managing the (HTTP) Session state of your Spring Boot application.

Simply include the appropriate Spring Session dependency on your Spring Boot application’s classpath, for example:

Maven dependency declaration. 

  <dependency>
    <groupId>org.springframework.session</groupId>
    <artifactId>spring-session-data-geode</artifactId>
    <version>2.3.0.M2</version>
  </dependency>

Alternatively, you may declare the provided spring-geode-starter-session dependency in your Spring Boot application Maven POM or Gradle build file:

Maven dependency declaration. 

  <dependency>
    <groupId>org.springframework.geode</groupId>
    <artifactId>spring-geode-starter-session</artifactId>
    <version>1.3.0.M2</version>
  </dependency>

Tip

You may replace Apache Geode with Pivotal Cloud Cache or Pivotal GemFire by changing the artifact ID from org.springframework.session:spring-session-data-geode to org.springframework.session:spring-session-data-gemfire. Alternatively, you may replace Apache Geode with Pivotal Cloud Cache (PCC) or Pivotal GemFire by changing the artifact ID from spring-geode-starter-session to spring-gemfire-starter-session. The version number is the same.

After declaring the required Spring Session dependency, then begin your Spring Boot application as you normally would:

Spring Boot Application. 

@SpringBootApplication
public class MySpringBootApplication {

  public static void main(String[] args) {
    SpringApplication.run(MySpringBootApplication.class, args);
  }

  ...
}

That is it!

Of course, you are free to create application-specific, Spring Web MVC Controllers to interact with the HttpSession as needed by your application:

Application Controller using HttpSession. 

@Controller
class MyApplicationController {

  @GetRequest(...)
  public String processGet(HttpSession session) {
    // interact with HttpSession
  }
}

The HttpSession is replaced by a Spring managed Session that will be stored in either Apache Geode or Pivotal GemFire, or even Pivotal Cloud Cache.

By default, Spring Boot for Apache Geode & Pivotal GemFire (SBDG) applies reasonable and sensible defaults when configuring Apache Geode or Pivotal GemFire as the provider in Spring Session.

So, for instance, by default, SBDG set the session expiration timeout to 30 minutes. It also uses a ClientRegionShortcut.PROXY as the client Region data management policy for the Apache Geode/Pivotal GemFire Region managing the (HTTP) Session state when the Spring Boot application is using a ClientCache, which it does by default.

However, what if the defaults are not sufficient for your application requirements?

17.2.1 Custom Configuration using Properties

Spring Session for Apache Geode/Pivotal GemFire publishes well-known configuration properties for each of the various Spring Session configuration options when using Apache Geode or Pivotal GemFire as the (HTTP) Session state management provider.

You may specify any of these properties in a Spring Boot application.properties file to adjust Spring Session’s configuration when using Apache Geode or Pivotal GemFire.

In addition to the properties provided in and by Spring Session for Apache Geode/Pivotal GemFire, Spring Boot for Apache Geode/Pivotal GemFire also recognizes and respects the spring.session.timeout property as well as the server.servlet.session.timeout property as discussed here.

	Tip
	spring.session.data.gemfire.session.expiration.max-inactive-interval-seconds takes precedence over spring.session.timeout, which takes precedence over server.servlet.session.timeout, when any combination of these properties have been simultaneously configured in the Spring Environment of your application.

There may be cases where you do not want your Spring Boot application to manage (HTTP) Session state using either Apache Geode or Pivotal GemFire. In certain cases, you may be using another Spring Session provider, such as Redis, to cache and manage your Spring Boot application’s (HTTP) Session state, while, even in other cases, you do not want to use Spring Session to manage your (HTTP) Session state at all. Rather, you prefer to use your Web Server’s (e.g. Tomcat) HttpSession state management.

Either way, you can specifically call out your Spring Session provider using the spring.session.store-type property in application.properties, as follows:

Use Redis as the Spring Session Provider. 

#application.properties

spring.session.store-type=redis
...

If you prefer not to use Spring Session to manage your Spring Boot application’s (HTTP) Session state at all, then do the following:

Use Web Server Session State Management. 

#application.properties

spring.session.store-type=none
...

Again, see Spring Boot docs for more details.

	Tip
	It is possible to include multiple providers on the classpath of your Spring Boot application. For instance, you might be using Redis to cache your application’s (HTTP) Session state while using either Apache Geode or Pivotal GemFire as your application’s persistent store (System of Record).

	Note
	Spring Boot does not properly recognize spring.session.store-type=[gemfire|geode] even though Spring Boot for Apache Geode/Pivotal GemFire is setup to handle either of these property values (i.e. either “gemfire” or “geode”).

Whether you are using Spring Session in a Spring Boot ClientCache application connecting to an externally managed cluster of Apache Geode or Pivotal GemFire servers, or connecting to a cluster of servers in a Pivotal Cloud Cache instance managed by a Pivotal Platform environment, the setup is the same.

Spring Session for Apache Geode, Pivotal GemFire, and Pivotal Cloud Cache (PCC) expects there to exist a cache Region in the cluster that will store and manage the (HTTP) Session state when your Spring Boot application is a ClientCache application in a client/server topology.

By default, the cache Region used to store and manage (HTTP) Session state is called "ClusteredSpringSessions".

You can set the name of the cache Region used to store and manage (HTTP) Session state either by explicitly declaring the @EnableGemFireHttpSession annotation on your main @SpringBootApplication class, like so:

Using `@EnableGemfireHttpSession. 

@SpringBootApplication
@EnableGemFireHttpSession(regionName = "MySessions")
class MySpringBootSpringSessionApplication { ... }

Or alternatively, we recommend users to configure the cache Region name using the well-known and documented property in Spring Boot application.properties:

Using properties. 

spring.session.data.gemfire.session.region.name=MySessions

Once you decide on the cache Region name used to store and manage (HTTP) Sessions, you must create the Region in the cluster somehow.

On the client, this is simple since SBDG’s auto-configuration will automatically create the client PROXY Region used to send/receive (HTTP) Session state between the client and server for you, when either Spring Session is on the application classpath (e.g. spring-geode-starter-session), or you explicitly declare the @EnableGemFireHttpSession annotation on your main @SpringBootApplication class.

However, on the server-side, you currently have a couple of options.

First, you can create the cache Region manually using Gfsh, like so:

Create the Sessions Region using Gfsh. 

gfsh> create region --name=MySessions --type=PARTITION --entry-idle-time-expiration=1800
        --entry-idle-time-expiration-action=INVALIDATE

You must create the cache Region with the appropriate name and an expiration policy.

In this case, we created an Idle Expiration Policy with a timeout of 1800 seconds (30 minutes), after which, the entry (i.e. Session object) will be "invalidated".

	Note
	Session expiration is managed by the Expiration Policy set on the cache Region used to store Session state. The Servlet Container’s (HTTP) Session expiration configuration is not used since Spring Session is replacing the Servlet Container’s Session management capabilities with its own and Spring Session delegates this behavior to the individual providers, like GemFire and Geode.

Alternatively, you could send the definition for the cache Region from your Spring Boot ClientCache application to the cluster using the SBDG @EnableClusterAware annotation, which is meta-annotated with SDG’s @EnableClusterConfiguration annotation.

	Tip
	See the Javadoc on the @EnableClusterConfiguration annotation as well as the documentation for more details.

Using @EnableClusterAware. 

@SpringBootApplication
@EnableClusterAware
class MySpringBootSpringSessionApplication { ... }

However, it is not currently possible to send Expiration Policy configuration metadata to the cluster yet. Therefore, you must manually alter the cache Region to set the Expiration Policy, like so:

Using Gfsh to Alter Region. 

gfsh> alter region --name=MySessions --entry-idle-time-expiration=1800
        --entry-idle-time-expiration-action=INVALIDATE

That is it!

Now your Spring Boot ClientCache application using Spring Session in a client/server topology is configured to store and manage user (HTTP) Session state in the cluster. This works for either standalone, externally managed Apache Geode or Pivotal GemFire clusters, or when using PCC running in a Pivotal Platform environment.

By default, Spring Boot applications run as a "cluster_operator" Role-based user in Pivotal CloudFoundry (PCF) when the app is bound to a Pivotal Cloud Cache (PCC) service instance.

A "cluster_operator" has full system privileges (i.e. Authorization) to do whatever that user wishes to involving the PCC service instance. A "cluster_operator" has read/write access to all the data, can modify the schema (e.g. create/destroy Regions, add/remove Indexes, change eviction or expiration policies, etc), start and stop servers in the PCC cluster, or even modify permissions.

@SpringBootApplication
@EnableClusterConfiguration(useHttp = true)
class SpringBootApacheGeodeClientCacheApplication { ... }

However…​

Not all Spring Boot applications using PCC will need to change the schema, or even modify data. Rather, certain apps may only need read access. Therefore, it is ideal to be able to configure your Spring Boot applications to run with a different user at runtime other than the auto-configured "cluster_operator", by default.

A prerequisite for running a Spring Boot application using PCC with a specific user is to create a user with restricted permissions using Pivotal CloudFoundry AppsManager while provisioning the PCC service instance to which the Spring Boot application will be bound.

Configuration metadata for the PCC service instance might appear as follows:

Pivotal Cloud Cache configuration metadata. 

{
  "p-cloudcache":[{
    "credentials": {
      "distributed_system_id": "0",
      "locators": [ "localhost[55221]" ],
      "urls": {
        "gfsh": "https://cloudcache-12345.services.cf.pws.com/gemfire/v1",
        "pulse": "https://cloudcache-12345.services.cf.pws.com/pulse"
      },
      "users": [{
        "password": "*****",
        "roles": [ "cluster_operator" ],
        "username": "cluster_operator_user"
      }, {
        "password": "*****",
        "roles": [ "developer" ],
        "username": "developer_user"
      },
      }, {
        "password": "*****",
        "roles": [ "read-only-user" ],
        "username": "guest"
      }],
      "wan": {
        "sender_credentials": {
          "active": {
            "password": "*****",
            "username": "gateway-sender-user"
          }
        }
      }
    },
    ...
    "name": "jblum-pcc",
    "plan": "small",
    "tags": [ "gemfire", "cloudcache", "database", "pivotal" ]
  }]
}

In the PCC service instance configuration metadata above, we see a "guest" user with the "read-only-user" Role. If the "read-only-user" Role is properly configured with "read-only" permissions as the name implies, then we could configure our Spring Boot application to run as "guest" with read-only access using:

Configuring a Spring Boot app to run as a specific user. 

# Spring Boot application.properties for PCF when using PCC

spring.data.gemfire.security.username=guest

	Tip
	The spring.data.gemfire.security.username property corresponds directly to the SDG @EnableSecurity annotation, securityUsername attribute. See the Javadoc for more details.

The spring.data.gemfire.security.username property is the same property used by Spring Data for Apache Geode and Pivotal GemFire (SDG) to configure the runtime user of your Spring Data application when connecting to either an externally managed Apache Geode or Pivotal GemFire cluster.

In this case, SBDG simply uses the configured username to lookup the authentication credentials of the user to set the username and password used by the Spring Boot, ClientCache app when connecting to PCC while running in PCF.

If the username is not valid, then an IllegalStateException is thrown.

By using Spring Profiles, it would be a simple matter to configure the Spring Boot application to run with a different user depending on environment.

See the Pivotal Cloud Cache documentation on Security for configuring users with assigned roles & permissions.

# Spring Boot application.properties

spring.data.gemfire.security.username=MyUser
spring.data.gemfire.security.password=MyPassword

It is possible to provision multiple instances of the Pivotal Cloud Cache service in your Pivotal CloudFoundry environment. You can then bind multiple PCC service instances to your Spring Boot app.

However, Spring Boot for Apache Geode & Pivotal GemFire (SBDG) will only auto-configure 1 PCC service instance for your Spring Boot application. This does not mean it is not possible to use multiple PCC service instances with your Spring Boot app, just that SBDG only "auto-configures" 1 service instance for you.

You must select which PCC service instance your Spring Boot app will auto-configure for you automatically when you have multiple instances and want to target a specific PCC service instance to use.

To do so, declare the following SBDG property in Spring Boot application.properties:

Spring Boot application.properties targeting a specific PCC service instance by name. 

# Spring Boot application.properties

spring.boot.data.gemfire.cloud.cloudfoundry.service.cloudcache.name=pccServiceInstanceTwo

The spring.boot.data.gemfire.cloud.cloudfoundry.service.cloudcache.name property tells SBDG which PCC service instance to auto-configure.

If the named PCC service instance identified by the property does not exist, then SBDG will throw an IllegalStateException stating the PCC service instance by name could not be found.

If you did not set the property and your Spring Boot app is bound to multiple PCC service instances, then SBDG will auto-configure the first PCC service instance it finds by name, alphabetically.

If you did not set the property and no PCC service instance is found, then SBDG will log a warning.

If you want to use multiple PCC service instances with your Spring Boot application, then you need to configure multiple connection Pools connected to each PCC service instance used by your Spring Boot application.

The configuration would be similar to the following:

Multple Pivotal Cloud Cache Service Instance Configuration. 

@Configuration
@EnablePools(pools = {
  @EnablePool(name = "PccOne"),
  @EnablePool(name = "PccTwo"),
  ...,
  @EnablePool(name = "PccN")
})
class PccConfiguration {
  ...
}

You would then externalize the configuration for the individually declared Pools in Spring Boot application.properties:

Configuring Pool Locator connection endpoints. 

# Spring Boot `application.properties`

spring.data.gemfire.pool.pccone.locators=pccOneHost1[port1], pccOneHost2[port2], ..., pccOneHostN[portN]

spring.data.gemfire.pool.pcctwo.locators=pccTwoHost1[port1], pccTwoHost2[port2], ..., pccTwoHostN[portN]

	Note
	Though less common, you can also configure the Pool of connections to target specific servers in the cluster using the spring.data.gemfire.pool.<named-pool>.severs property.

	Tip
	Keep in mind that properties in Spring Boot application.properties can refer to other properties like so: property=${otherProperty}. This allows you to further externalize properties using Java System properties or Environment Variables.

Of course, a client Region is then assigned the Pool of connections that are used to send data to/from the specific PCC service instance (cluster):

Assigning a Pool to a client Region. 

@Bean("Example")
ClientRegionFactoryBean exampleRegion(GemFireCache gemfireCache,
        @Qualifier("PccTwo") Pool poolForPccTwo) {

    ClientRegionFactoryBean exampleRegion = new ClientRegionFactoryBean();

    exampleRegion.setCache(gemfireCache);
    exampleRegion.setPool(poolForPccTwo);
    exampleRegion.setShortcut(ClientRegionShortcut.PROXY);

    return exampleRegion;
}

You can configure as many Pools and client Regions as needed by your application. Again, the Pool determines which Pivotal Cloud Cache service instance and cluster the data for the client Region will reside.

	Note
	By default, SBDG configures all Pools declared in a Spring Boot, ClientCache application to connect to and use a single PCC service instance. This may be a targeted PCC service instance when using the spring.boot.data.gemfire.cloud.cloudfoundry.service.cloudcache.name property as discussed above.

Sometimes, it is desirable to deploy (i.e. "push") and run your Spring Boot applications in Pivotal CloudFoundry, but still connect your Spring Boot applications to an externally managed, standalone Apache Geode or Pivotal GemFire cluster.

Spring Boot for Apache Geode & Pivotal GemFire (SBDG) makes this a non-event and honors its "little to no code or configuration changes necessary" goal, regardless of your runtime choice, "it should just work!"

To help guide you through this process, we will cover the following topics:

$ cf dev start -f ~/Downloads/Pivotal/CloudFoundry/Dev/pcfdev-v1.2.0-darwin.tgz

Downloading Network Helper...
Progress: |====================>| 100.0%
Installing cfdevd network helper (requires administrator privileges)...
Password:
Setting up IP aliases for the BOSH Director & CF Router (requires administrator privileges)
Downloading Resources...
Progress: |====================>| 100.0%
Setting State...
WARNING: PCF Dev requires 8192 MB of RAM to run. This machine may not have enough free RAM.
Creating the VM...
Starting VPNKit...
Waiting for the VM...
Deploying the BOSH Director...

Deploying PAS...
  Done (14m34s)
Deploying Apps-Manager...
  Done (1m41s)

 	 ██████╗  ██████╗███████╗██████╗ ███████╗██╗   ██╗
 	 ██╔══██╗██╔════╝██╔════╝██╔══██╗██╔════╝██║   ██║
 	 ██████╔╝██║     █████╗  ██║  ██║█████╗  ██║   ██║
 	 ██╔═══╝ ██║     ██╔══╝  ██║  ██║██╔══╝  ╚██╗ ██╔╝
 	 ██║     ╚██████╗██║     ██████╔╝███████╗ ╚████╔╝
 	 ╚═╝      ╚═════╝╚═╝     ╚═════╝ ╚══════╝  ╚═══╝
 	             is now running!

 	To begin using PCF Dev, please run:
 	    cf login -a https://api.dev.cfdev.sh --skip-ssl-validation

 	Admin user => Email: admin / Password: admin
 	Regular user => Email: user / Password: pass

 	To access Apps Manager, navigate here: https://apps.dev.cfdev.sh

 	To deploy a particular service, please run:
 	    cf dev deploy-service <service-name> [Available services: mysql,redis,rabbitmq,scs]

$ cf login -a https://api.dev.cfdev.sh --skip-ssl-validation

$ echo $GEODE
/Users/jblum/pivdev/apache-geode-1.6.0

$ gfsh
    _________________________     __
   / _____/ ______/ ______/ /____/ /
  / /  __/ /___  /_____  / _____  /
 / /__/ / ____/  _____/ / /    / /
/______/_/      /______/_/    /_/    1.6.0

Monitor and Manage Apache Geode
gfsh>

#!/bin/gfsh
# Gfsh shell script to configure and bootstrap an Apache Geode cluster.

start locator --name=LocatorOne --log-level=config --classpath=@project-dir@/apache-geode-extensions/build/libs/apache-geode-extensions-@[email protected] --J=-Dgemfire.security-manager=org.springframework.geode.security.TestSecurityManager --J=-Dgemfire.http-service-port=8080

start server --name=ServerOne --log-level=config --user=admin --password=admin --classpath=@project-dir@/apache-geode-extensions/build/libs/apache-geode-extensions-@[email protected]

gfsh>start locator --name=LocatorOne --log-level=config --classpath=/Users/jblum/pivdev/spring-boot-data-geode/apache-geode-extensions/build/libs/apache-geode-extensions-1.1.0.BUILD-SNAPSHOT.jar --J=-Dgemfire.security-manager=org.springframework.geode.security.TestSecurityManager --J=-Dgemfire.http-service-port=8080
Starting a Geode Locator in /Users/jblum/pivdev/lab/LocatorOne...
..
Locator in /Users/jblum/pivdev/lab/LocatorOne on 10.99.199.24[10334] as LocatorOne is currently online.
Process ID: 14358
Uptime: 1 minute 1 second
Geode Version: 1.6.0
Java Version: 1.8.0_192
Log File: /Users/jblum/pivdev/lab/LocatorOne/LocatorOne.log
JVM Arguments: -Dgemfire.enable-cluster-configuration=true -Dgemfire.load-cluster-configuration-from-dir=false -Dgemfire.log-level=config -Dgemfire.security-manager=org.springframework.geode.security.TestSecurityManager -Dgemfire.http-service-port=8080 -Dgemfire.launcher.registerSignalHandlers=true -Djava.awt.headless=true -Dsun.rmi.dgc.server.gcInterval=9223372036854775806
Class-Path: /Users/jblum/pivdev/apache-geode-1.6.0/lib/geode-core-1.6.0.jar:/Users/jblum/pivdev/spring-boot-data-geode/apache-geode-extensions/build/libs/apache-geode-extensions-1.1.0.BUILD-SNAPSHOT.jar:/Users/jblum/pivdev/apache-geode-1.6.0/lib/geode-dependencies.jar

Security Manager is enabled - unable to auto-connect. Please use "connect --locator=10.99.199.24[10334] --user --password" to connect Gfsh to the locator.

Authentication required to connect to the Manager.

gfsh>connect
Connecting to Locator at [host=localhost, port=10334] ..
Connecting to Manager at [host=10.99.199.24, port=1099] ..
user: admin
password: *****
Successfully connected to: [host=10.99.199.24, port=1099]

gfsh>start server --name=ServerOne --log-level=config --user=admin --password=admin --classpath=/Users/jblum/pivdev/spring-boot-data-geode/apache-geode-extensions/build/libs/apache-geode-extensions-1.1.0.BUILD-SNAPSHOT.jar
Starting a Geode Server in /Users/jblum/pivdev/lab/ServerOne...
....
Server in /Users/jblum/pivdev/lab/ServerOne on 10.99.199.24[40404] as ServerOne is currently online.
Process ID: 14401
Uptime: 3 seconds
Geode Version: 1.6.0
Java Version: 1.8.0_192
Log File: /Users/jblum/pivdev/lab/ServerOne/ServerOne.log
JVM Arguments: -Dgemfire.default.locators=10.99.199.24[10334] -Dgemfire.security-username=admin -Dgemfire.start-dev-rest-api=false -Dgemfire.security-password=******** -Dgemfire.use-cluster-configuration=true -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.6.0/lib/geode-core-1.6.0.jar:/Users/jblum/pivdev/spring-boot-data-geode/apache-geode-extensions/build/libs/apache-geode-extensions-1.1.0.BUILD-SNAPSHOT.jar:/Users/jblum/pivdev/apache-geode-1.6.0/lib/geode-dependencies.jar

gfsh>list members
   Name    | Id
---------- | -----------------------------------------------------------------
LocatorOne | 10.99.199.24(LocatorOne:14358:locator)<ec><v0>:1024 [Coordinator]
ServerOne  | 10.99.199.24(ServerOne:14401)<v1>:1025

gfsh>list regions
No Regions Found

18.4.3 Creating a User-Provided Service

Now that we have PCF Dev and a small Apache Geode cluster up and running, it is time to create a User-Provided Service to the external, standalone Apache Geode cluster that we started in step 2.

As mentioned, PCF Dev offers the MySQL, Redis and RabbitMQ services out-of-the-box. However, to use Apache Geode (or Pivotal GemFire) in the same capacity as you would Pivotal Cloud Cache when running in a production-grade, PCF environment, you need to create a User-Provided Service for the standalone Apache Geode cluster.

To do so, execute the following cf CLI command:

cf cups command. 

$ cf cups <service-name> -t "gemfire, cloudcache, database, pivotal" -p '<service-credentials-in-json>'

	Note
	It is important that you specify the tags ("gemfire, cloudcache, database, pivotal") exactly as shown in the cf CLI command above.

The argument passed to the -p command-line option is a JSON document (object) containing the "credentials" for our User-Provided Service.

The JSON object is as follows:

User-Provided Service Crendentials JSON. 

{
	"locators": [ "<hostname>[<port>]" ],
	"urls": { "gfsh": "https://<hostname>/gemfire/v1" },
	"users": [{ "password": "<password>", "roles": [ "cluster_operator" ], "username": "<username>" }]
}

The complete cf CLI command would be similar to the following:

Example cf cups command. 

cf cups apacheGeodeService -t "gemfire, cloudcache, database, pivotal" \
  -p '{ "locators": [ "10.99.199.24[10334]" ], "urls": { "gfsh": "https://10.99.199.24/gemfire/v1" }, "users": [{ "password": "admin", "roles": [ "cluster_operator" ], "username": "admin" }] }'

We replaced the <hostname> placeholder tag with the IP address of our external Apache Geode Locator. The IP address can be found in the Gfsh start locator output above.

Additionally, the <port> placeholder tag has been replaced with the default Locator port, 10334,

Finally, we set the username and password accordingly.

	Tip
	Spring Boot for Apache Geode (SBDG) provides template files in the /opt/jenkins/data/workspace/spring-boot-data-geode_master/spring-geode-docs/src/main/resources directory.

Once the service has been created, you can query the details from the cf CLI:

$ cf services
Getting services in org cfdev-org / space cfdev-space as admin...

name                 service         plan   bound apps      last operation   broker
apacheGeodeService   user-provided          boot-pcc-demo


$ cf service apacheGeodeService
Showing info of service apacheGeodeService in org cfdev-org / space cfdev-space as admin...

name:      apacheGeodeService
service:   user-provided
tags:      gemfire, cloudcache, database, pivotal

bound apps:
name            binding name   status             message
boot-pcc-demo                  create succeeded

You can also view the "apacheGeodeService" from Apps Manager, starting from the Service tab in your org and space:

By clicking on the "apacheGeodeService" service entry in the table you can get all the service details, such the bound apps:

Configuration:

And so on.

	Tip
	You can learn more about CUPS in the PCF documentation, here.

18.4.4 Push & Bind a Spring Boot application

Now it is time to push a Spring Boot application to PCF Dev and bind the app to the "apacheGeodeService".

Any Spring Boot ClientCache application using SBDG will do. For this example, we will use the PCCDemo application, available in GitHub.

After cloning the project to your workstation, you must perform a build to produce the artifact to push to PCF Dev:

Build the PCCDemo app. 

$ mvn clean package

Then, you can push the app to PCF Dev with the following cf CLI command:

Push app to PCF Dev. 

$ cf push boot-pcc-demo -u none --no-start -p target/client-0.0.1-SNAPSHOT.jar

Once the app has been successfully deployed to PCF Dev, you can get app details:

Details for deployed app. 

$ cf apps
Getting apps in org cfdev-org / space cfdev-space as admin...
OK

name            requested state   instances   memory   disk   urls
boot-pcc-demo   stopped           0/1         768M     1G     boot-pcc-demo.dev.cfdev.sh


$ cf app boot-pcc-demo
Showing health and status for app boot-pcc-demo in org cfdev-org / space cfdev-space as admin...

name:              boot-pcc-demo
requested state:   stopped
routes:            boot-pcc-demo.dev.cfdev.sh
last uploaded:     Tue 02 Jul 00:34:09 PDT 2019
stack:             cflinuxfs3
buildpacks:        https://github.com/cloudfoundry/java-buildpack.git

type:           web
instances:      0/1
memory usage:   768M
     state   since                  cpu    memory   disk     details
#0   down    2019-07-02T21:48:25Z   0.0%   0 of 0   0 of 0

type:           task
instances:      0/0
memory usage:   256M

There are no running instances of this process.

You can either bind the PPCDemo app to the "apacheGeodeService" using the cf CLI command:

Bind app to apacheGeodeService using CLI. 

cf bind-service boot-pcc-demo apacheGeodeService

Or, alternatively, you can create a YAML file (manifest.yml in src/main/resources) containing the deployment descriptor:

Example YAML deployment descriptor file. 

\---
applications:
  - name: boot-pcc-demo
    memory: 768M
    instances: 1
    path: ./target/client-0.0.1-SNAPSHOT.jar
    services:
      - apacheGeodeService
    buildpacks:
      - https://github.com/cloudfoundry/java-buildpack.git

You can also use Apps Manager to view app details and un/bind additional services. Start by navigating to the App tab under your org and space:

From there, you can click on the desired app and navigate to the Overview:

You can also review the app Settings. Specifically, we are looking at the configuration of the app once bound to the "apacheGeodeService" as seen in the VCAP_SERVICES Environment Variable:

This JSON document structure is not unlike the configuration used to bind your Spring Boot, ClientCache application to the Pivotal Cloud Cache service when deploying the same app to Pivotal CloudFoundry. This is actually very key if you want to minimize the amount of boilerplate code and configuration changes when migrating between different CloudFoundry environments, even Open Source CloudFoundry.

Again, SBDG’s entire goal is to simply the effort for you, as a developer, to build, run and manage your application, in whatever context your application lands, even if it changes later. If you follow the steps in this documentation, that goal will be realized.

18.4.5 Running the Spring Boot application

All that is left to do now is run the app.

You can start the PCCDemo app from the cf CLI using the following command:

Start the Spring Boot app. 

$ cf start boot-pcc-demo

Alternatively, you can also start the app from Apps Manager. This is convenient since then you can tail and monitor the application log file.

Once the app has started, you can click the VIEW APP link in the upper right corner of the APP screen.

You can navigate to any of the application Web Service, Controller endpoints. For example, if you know the ISBN of a Book, you can access it from the Web browser:

You can also access the same data from the Gfsh command-line tool. However, the first thing to observe is that our application informed the cluster that it needed a Region called "Books":

Books Region. 

gfsh>list regions
List of regions
---------------
Books


gfsh>describe region --name=/Books
..........................................................
Name            : Books
Data Policy     : partition
Hosting Members : ServerOne

Non-Default Attributes Shared By Hosting Members

 Type  |    Name     | Value
------ | ----------- | ---------
Region | size        | 1
       | data-policy | PARTITION

The PCCDemo app creates fake data on startup, which we can query in Gfsh like so:

Query Books. 

gfsh>query --query="SELECT book.isbn, book.title FROM /Books book"
Result : true
Limit  : 100
Rows   : 1

    isbn      | title
------------- | ---------------------
1235432BMF342 | The Torment of Others

There you have it!

The ability to deploy Spring Boot, Apache Geode or Pivotal GemFire ClientCache applications to Pivotal CloudFoundry, yet connect your app to a externally managed, standalone Apache Geode or Pivotal GemFire cluster.

Indeed, this is will be a useful arrangement and stepping stone for many users as they begin their journey towards a Cloud-Native platform like Pivotal CloudFoundry (PCF) and using services like Pivotal Cloud Cache (PCC).

Later, when the time comes and your need is very real, you can simply migrate your Spring Boot applications to a fully managed and production-grade Pivotal CloudFoundry environment and SBDG will figure out what to do, leaving you to focus entirely on your application.

The question most often asked is, "What Spring Data for Apache Geode/Pivotal GemFire annotations can I use, or must I use, when developing Apache Geode or Pivotal GemFire applications with Spring Boot?"

This section will answer this question and more.

Readers should refer to the complimentary sample, Spring Boot Auto-configuration for Apache Geode & Pivotal GemFire, which showcases the auto-configuration provided by Spring Boot for Apache Geode/Pivotal GemFire in action.

@SpringBootApplication
@CacheServerApplication
class MySpringBootPeerCacheServerApplication { ... }

spring.data.gemfire.security.username=MyUser
spring.data.gemfire.security.password=Secret

@Service
class CustomerService {

  @Autowired
  private CustomerRepository customerRepository;

  @Cacheable("CustomersByName")
  public Customer findBy(String name) {
    return customerRepository.findByName(name);
  }
}

@SpringBootApplication
@EnableCachingDefinedRegions
class Application { ... }