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.
This project builds on Spring Boot along with Spring Data for Apache Geode (SDG), Spring Session for Apache Geode (SSDG) and Spring Test for Apache Geode (STDG).
2023-January-17:
At the end of 2022, VMware announced the general availability of the Spring for VMware GemFire portfolio of projects.
While these Spring based projects for VMware GemFire are open source and a succession to the Spring for Apache Geode projects, they are not a replacement. VMware GemFire forked from the Apache Geode project and is not open source. Additionally, newer Apache Geode and VMware GemFire clients are not backwards compatible with older Apache Geode and VMware GemFire servers. You can begin the transition by starting here.
Alternatively, the Spring portfolio provides first-class integration with other comparable caching providers. Also, see here and here.
Finally, keep in mind, the Spring for Apache Geode projects will still be maintained until OSS and commercial support ends. Maintenance will only include CVE and critical fixes. No new features or major enhancements will be made. The Spring Boot for Apache Geode support timelines can be viewed here. Also see the Version Compatibility Matrix for up-to-date dependency and version details.
2022-October-24:
See the October 24th NOTICE on the Spring Data for Apache Geode GitHub project page for complete details.
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:
-
Auto-configures an Apache Geode ClientCache instance automatically when Spring Data for Apache Geode (SDG) is on the application’s CLASSPATH.
-
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.
-
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.
-
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.
-
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.
-
Auto-configures Apache Geode as a HTTP Session state management provider when Spring Session for Apache Geode (SSDG) is on the application’s CLASSPATH.
-
Auto-configures Apache Geode Security including Authentication & Authorization (Auth) as well as Transport Layer Security (TLS) using SSL.
-
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.
-
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.
The following SBDG versions are currently maintained and developed.
| Version | Reference Documentation | Javadoc | Samples |
|---|---|---|---|
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
The following SBDG versions have reached their End-of-Life (EOL).
| Version | Reference Documentation | Javadoc | Samples |
|---|---|---|---|
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
See Spring Boot’s Releases in the Support Versions Wiki page for more details.
To start using SBDG immediately, simply add the following dependency to your Spring Boot application Maven POM or Gradle build file:
<dependency>
<groupId>org.springframework.geode</groupId>
<artifactId>spring-geode-starter</artifactId>
<version>2.0.0-M5</version>
</dependency>dependencies {
compile "org.springframework.geode:spring-geode-starter:2.0.0-M5"
}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.
<repositories>
<repository>
<name>spring-milestone</name>
<url>https://repo.spring.io/milestone</url>
</repository>
</repositories>build.gradlerepositories {
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.
|
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.
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.
@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 for a 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.
interface UserRepository extends CrudRepository<User, String> { }Finally, let’s create a Spring Boot application to tie everything together.
@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
@EnableEntityDefinedRegions 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 limit the scope of 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.
...
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.
To continue your journey of learning, see the Reference Documentation and jump into the Examples below.
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.
You can find documentation, issue management, support, samples, and guides for using Spring Boot at https://projects.spring.io/spring-boot/
Please see our code of conduct
Please see our Security policy.
Spring Boot and Spring Boot for Apache Geode is Open Source Software released under the Apache 2.0 license.