Skip to content
main
Switch branches/tags
Code

Build Status

Spring Boot for Apache Geode

Spring Boot for Apache Geode (SBDG) extends Spring Boot to also include auto-configuration and other convention & configuration features to simplify the development of Spring applications using Apache Geode.

Project Features

SBDG adds dedicated Spring Boot auto-configuration and actuator support for Apache Geode and integrates with other Spring projects in addition to 3rd-party Java libraries.

Among other things, this project builds on Spring Boot and Spring Data for Apache Geode (SDG) to offer:

  1. Auto-configures an Apache Geode ClientCache instance automatically when Spring Data for Apache Geode (SDG) is on the application’s CLASSPATH.

  2. Auto-configures Apache Geode as a caching provider in Spring’s Cache Abstraction when Spring Data for Apache Geode (SDG) is on the application’s CLASSPATH to solve caching uses cases.

  3. Auto-configures Spring Data for Apache Geode (SDG) Repositories when Spring Data for Apache Geode (SDG) is on the application’s CLASSPATH and Spring Boot detects SDG Repositories in your Spring Boot application to solve persistent use cases.

  4. Auto-configures Apache Geode Functions when Spring Data for Apache Geode (SDG) is on the application’s CLASSPATH and Spring Boot auto-detects SDG Function implementations or executions to solve distributed compute problems.

  5. Auto-configures Apache Geode CQ when Spring Data for Apache Geode (SDG) is on the application’s CLASSPATH and Spring Boot auto-detects SDG CQ query declarations on application components to solve (near) realtime event stream processing use cases.

  6. Auto-configures Apache Geode as a HTTP Session state management provider when Spring Session for Apache Geode (SSDG) is on the application’s CLASSPATH.

  7. Auto-configures Apache Geode Security including Authentication & Authorization (Auth) as well as Transport Layer Security (TLS) using SSL.

  8. Provides additional support for Spring Boot and Spring Data for Apache Geode applications deployed to VMware Tanzu Application Service (TAS) using VMware Tanzu GemFire for VMs.

  9. Provides first-class support for Unit & Integration Testing in your Spring Boot applications using Apache Geode with Spring Test for Apache Geode (STDG).

This, along with many other benefits, are provided by this project.

Learn

The following SBDG versions are currently maintained and developed.

Table 1. Supported Versions
Version Reference Documentation Javadoc Samples

current

Ref Docs

Javadoc

Samples

1.6.0-SNAPSHOT

Ref Docs

Javadoc

Samples

1.6.0-M1

Ref Docs

Javadoc

Samples

1.5.4-SNAPSHOT

Ref Docs

Javadoc

Samples

1.5.3

Ref Docs

Javadoc

Samples

1.4.10-SNAPSHOT

Ref Docs

Javadoc

Samples

1.4.9

Ref Docs

Javadoc

Samples

1.3.13.BUILD-SNAPSHOT

Ref Docs

Javadoc

Samples

1.3.12.RELEASE

Ref Docs

Javadoc

Samples

1.2.14.BUILD-SNAPSHOT

Ref Docs

Javadoc

Samples

1.2.13.RELEASE

Ref Docs

Javadoc

Samples

The following SBDG versions have reached their End-of-Life (EOL).

Table 2. Unsupported (EOL) Versions
Version Reference Documentation Javadoc Samples

1.1.12.BUILD-SNAPSHOT

Ref Docs

Javadoc

Samples

1.1.11.RELEASE

Ref Docs

Javadoc

Samples

1.0.2.BUILD-SNAPSHOT

Ref Docs

Javadoc

Samples

1.0.1.RELEASE

Ref Docs

Javadoc

Samples

See Spring Boot’s Releases in the Support Versions Wiki page for more details.

Get Started!

To start using SBDG immediately, simply add the following dependency to your Spring Boot application Maven POM or Gradle build file:

SBDG Maven POM dependency
<dependency>
    <groupId>org.springframework.geode</groupId>
    <artifactId>spring-geode-starter</artifactId>
    <version>1.6.0-M1</version>
</dependency>
SBDG Gradle build dependency
dependencies {
    compile "org.springframework.geode:spring-geode-starter:1.6.0-M1"
}

If you are using a SNAPSHOT or MILESTONE version of SBDG, perhaps to pick up a bug fix, improvement or new feature, be sure to declare the appropriate Spring Repository. For example, the when using a MILESTONE (e.g. M1), declare the Spring Milestone Repository.

Spring Milestone Repository declared in Maven POM
<repositories>
    <repository>
        <name>spring-milestone</name>
        <url>https://repo.spring.io/milestone</url>
    </repository>
</repositories>
Spring Milestone Repository declare in build.gradle
repositories {
    maven { url "https://repo.spring.io/milestone" }
}
Note
To use a SNAPSHOT, simply change the URL from https://repo.spring.io/milestone to https://repo.spring.io/snapshot.
Note
Spring SNAPSHOT and MILESTONE artifacts are not published to Maven Central. Only GA release bits are published to Maven Central. When using GA bits, you do not need to declare a Repository for Maven Central when using Maven. You do need to declare mavenCentral() when using Gradle.

Getting Started with Spring Initializer

To make the task of creating a project even easier, the Spring Team recommends that you start at start.spring.io.

Use this link to create a Spring Boot project using Apache Geode.

In addition to declaring the SBDG dependency, org.springframework.geode:spring-geode-starter, the Maven POM or Gradle build file generated with Spring Initializer at start.spring.io includes the SBDG BOM, conveniently declared in a dependency management block in both Maven and Gradle projects. This is convenient when you anticipate that you will need to use more than 1 SBDG module.

For example, if you will also be using the org.springframework.geode:spring-geode-starter-session module for your (HTTP) Session management needs, or perhaps the org.springframework.geode:spring-geode-starter-test module to write Unit & Integration Tests for your Spring Boot, Apache Geode applications, then you can simply add the dependency and let the BOM manage the version for you. This also makes it easier to switch versions without having to change all the dependencies; simply change the version of the BOM.

Simple Spring Boot, Apache Geode application

In this section, we build a really simple Spring Boot application using Apache Geode showing you how to get started quickly, easily and reliably.

For our example, we will create and persist a User to Apache Geode, then lookup the User by name.

We start by defining our User application domain model class.

User class
@Getter
@ToString
@EqualsAndHashCode
@RequiredArgsConstructor
@Region("Users")
class User {

	@lombok.NonNull @Id
	private final String name;

}

We use Project Lombok to simplify the implementation of our User class. Otherwise, the only requirement to store Users in Apache Geode is to declare the User to data store mapping. We do this by annotating the User class with the SDG @Region mapping annotation along with declaring the User.name property to be the ID of User instances.

By declaring the @Region mapping annotation we are stating that instances of User will be stored in an Apache Geode cache Region named “Users”. The Spring Data @Id annotation serves to declare the identifier for a User object stored in Apache Geode. This is not unlike JPA’s @javax.persistence.Table and @javax.persistence.Id mapping annotations.

Note
An Apache Geode Region is equivalent to a database table and the cache is equivalent to a database schema. A database schema is a namespace for a collection of tables whereas an Apache Geode cache is a namespace or group of Regions that hold the data. Each data store has its own data structure to organize and manage data. An RDBMS uses a tabular data structure. Graph databases use a graph. Well, Apache Geode uses a Region, which is simply a key/value data structure, or a map. In fact, an Apache Geode Region implements java.util.Map (indirectly) and is essentially a distributed, horizontally scalable, highly concurrent, low-latency (among other things) Map implementation.

Next, let’s define a Spring Data CrudRepository to persist and access Users stored in Apache Geode.

UserRepository
interface UserRepository extends CrudRepository<User, String> { }

Finally, let’s create a Spring Boot application to tie everything together.

Spring Boot, Apache Geode application
@Slf4j
@SpringBootApplication
@EnableClusterAware
@EnableEntityDefinedRegions(basePackageClasses = User.class)
public class UserApplication {

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

	@Bean
	@SuppressWarnings("unused")
	ApplicationRunner runner(UserRepository userRepository) {

		return args -> {

			long count = userRepository.count();

			assertThat(count).isZero();

			log.info("Number of Users [{}]", count);

			User jonDoe = new User("jonDoe");

			log.info("Created User [{}]", jonDoe);

			userRepository.save(jonDoe);

			log.info("Saved User [{}]", jonDoe);

			count = userRepository.count();

			assertThat(count).isOne();

			log.info("Number of Users [{}]", count);

			User jonDoeFoundById = userRepository.findById(jonDoe.getName()).orElse(null);

			assertThat(jonDoeFoundById).isEqualTo(jonDoe);

			log.info("Found User by ID (name) [{}]", jonDoeFoundById);
		};
	}
}

@Getter
@ToString
@EqualsAndHashCode
@RequiredArgsConstructor
@Region("Users")
class User {

	@lombok.NonNull @Id
	private final String name;

}

interface UserRepository extends CrudRepository<User, String> { }

The UserApplication class is annotated with @SpringBootApplication making it a proper Spring Boot application. With SBDG on the classpath, this effectively makes our application an Apache Geode application as well. SBDG will auto-configure an Apache Geode ClientCache instance by default when SBDG is on the application classpath.

With the SDG @Region mapping annotation, we declared that instances of User will be stored in the “Users” Region. However, we have not yet created a “Users” Region. This is where the @EnableEntityDefinedRegions annotation comes in handy. Like JPA/Hibernate’s ability to create database tables from our @Entity declared classes, SDG’s @EnableEntityDefineRegions annotation scans the classpath for application entity classes (e.g. User) and detects any classes annotated with @Region in order to create the named Region required by the application to persist data. The basePackageClasses attribute is a type-safe way to pinpoint the scan.

While useful and convenient during development, @EnableEntityDefinedRegions was not made into an auto-configuration feature by default since there are many ways to define and configure a Region, which varies from data type to data type (e.g. transactional data vs. reference data), and varies greatly by use case and requirements.

We make use of 1 more powerful annotation, SBDG’s @EnableClusterAware, which allows you to switch between local-only, embedded development to a client/server topology with no code or configuration changes.

Tip
You can learn more about the @EnableClusterAware annotation in SBDG’s reference documentation (see here and in the Getting Started Sample).

Our Java main method uses Spring Boot’s SpringApplication class to bootstrap the the Apache Geode ClientCache application.

Finally, we declare an ApplicationRunner bean to persist a User and then lookup the stored User by ID (or "name"). Along the way, we log the operations to see the application in action.

Example application log output (formatted to fit this screen)
...
2021-01-26 20:46:34.842  INFO 33218 --- [main] example.app.user.UserApplication : Started UserApplication in 4.561 seconds (JVM running for 5.152)
2021-01-26 20:46:34.996  INFO 33218 --- [main] example.app.user.UserApplication : Number of Users [0]
2021-01-26 20:46:34.996  INFO 33218 --- [main] example.app.user.UserApplication : Created User [User(name=jonDoe)]
2021-01-26 20:46:35.025  INFO 33218 --- [main] example.app.user.UserApplication : Saved User [User(name=jonDoe)]
2021-01-26 20:46:35.027  INFO 33218 --- [main] example.app.user.UserApplication : Number of Users [1]
2021-01-26 20:46:35.029  INFO 33218 --- [main] example.app.user.UserApplication : Found User by ID (name) [User(name=jonDoe)]
...

That’s it! That’s all!

We have just created a simple Spring Boot application using Apache Geode to persist and access data.

Where To Next

To continue your journey of learning, see the Reference Documentation and jump into the Examples below.

Examples

The single, most relevant "source of truth" on how to get started quickly, easily and reliably, using Spring Boot for Apache Geode (SBDG) to solve problems, is to start with the Samples. There, you will find different examples with documentation and code showing you how to use SBDG to effectively handle specific application concerns, like Caching.

Additionally, there are examples that walk you through the evolution of SBDG to really showcase what SBDG affords you. The examples start by building a simple Spring Boot application using Apache Geode’s API only. Then, the app is rebuilt using Spring Data for Apache Geode (SDG) to show the simplifications that SDG brings to the table. Finally, the app is rebuilt once more using SBDG to demonstrate the full power of Apache Geode when combined with Spring Boot. The examples can be found in the PCCDemo GitHub repository. Each app can be deployed to Pivotal CloudFoundry (PCF) and bound to a Pivotal Cloud Cache (PCC) service instance. By using SBDG, little to no code or configuration changes are required to run the app locally and then later deploy the same app to a managed environment like PCF. It just works!

Then, there is the Temperature Service example app showcasing an Internet of Things (IoT) and Event Stream Processing (ESP) Use Case to manage Temperature Sensors and Monitors, powered by Apache Geode with the help of SBDG to make the application configuration and implementation as simple as can be.

Spring Boot Project Site

You can find documentation, issue management, support, samples, and guides for using Spring Boot at https://projects.spring.io/spring-boot/

Code of Conduct

Please see our code of conduct

Reporting Security Vulnerabilities

Please see our Security policy.

License

Spring Boot and Spring Boot for Apache Geode is Open Source Software released under the Apache 2.0 license.

About

Spring Boot support for Apache Geode and VMware Tanzu GemFire

Resources

License

Packages

No packages published

Languages