[[spring-boot-data-geode]]
= Spring Boot for Apache Geode Reference Guide
John Blum
:revdate: {localdate}
:revnumber: {version}
:doctype: book
:hide-uri-scheme:
:icons: font
:include-dir: _includes
:numbered:
:source-highlighter: prettify
:toc: left
:toclevels: 1
:java-version: 8
:jdk-javadoc: https://docs.oracle.com/javase/{java-version}/docs/api
:apache-geode-name: Apache Geode
:apache-geode-version: {apache-geode-doc-version}
:apache-geode-docs: https://geode.apache.org/docs/guide/{apache-geode-version}
:apache-geode-javadoc: https://geode.apache.org/releases/latest/javadoc
:apache-geode-website: https://geode.apache.org/
:apache-geode-wiki: https://cwiki.apache.org/confluence/display/GEODE
:pivotal-cloudcache-name: VMware Tanzu GemFire for VMs
:pivotal-cloudcache-version: {pivotal-cloudcache-doc-version}
:pivotal-cloudcache-docs: https://docs.pivotal.io/p-cloud-cache/{pivotal-cloudcache-version}
:pivotal-cloudcache-website: https://pivotal.io/pivotal-cloud-cache
:pivotal-cloudfoundry-name: VMware Tanzu Application Service (TAS)
:pivotal-cloudfoundry-version: 2-10
:pivotal-cloudfoundry-docs: https://docs.pivotal.io/platform/application-service/{pivotal-cloudfoundry-version}
:pivotal-cloudfoundry-website: https://pivotal.io/platform
:pivotal-gemfire-name: VMware Tanzu GemFire
:pivotal-gemfire-version: {pivotal-gemfire-doc-version}
:pivotal-gemfire-docs: https://gemfire.docs.pivotal.io/{pivotal-gemfire-version}/geode/reference
:pivotal-gemfire-javadoc: https://gemfire-{pivotal-gemfire-version}-javadocs.docs.pivotal.io/
:pivotal-gemfire-website: https://pivotal.io/pivotal-gemfire
:vmware-gemfire-name: VMware Tanzu GemFire for K8S
:spring-boot-docs: https://docs.spring.io/spring-boot/docs/current/reference
:spring-boot-docs-html: {spring-boot-docs}/html
:spring-boot-javadoc: https://docs.spring.io/spring-boot/docs/current/api
:spring-boot-website: https://spring.io/projects/spring-boot
:spring-boot-data-geode-javadoc: https://docs.spring.io/spring-boot-data-geode-build/current/api/
:spring-data-commons-docs: https://docs.spring.io/spring-data/commons/docs/current/reference
:spring-data-commons-docs-html: {spring-data-commons-docs}/html
:spring-data-commons-javadoc: https://docs.spring.io/spring-data/commons/docs/current/api
:spring-data-commons-website: https://spring.io/projects/spring-data
:spring-data-gemfire-docs: https://docs.spring.io/spring-data/gemfire/docs/current/reference
:spring-data-gemfire-docs-html: {spring-data-gemfire-docs}/html
:spring-data-gemfire-javadoc: https://docs.spring.io/spring-data/gemfire/docs/current/api
:spring-data-gemfire-website: https://spring.io/projects/spring-data-gemfire
:spring-data-geode-docs: https://docs.spring.io/spring-data/geode/docs/current/reference
:spring-data-geode-docs-html: {spring-data-geode-docs}/html
:spring-data-geode-javadoc: https://docs.spring.io/spring-data/geode/docs/current/api
:spring-data-geode-website: https://spring.io/projects/spring-data-geode
:spring-data-website: https://spring.io/projects/spring-data
:spring-dependency-management-gradle-plugin-version: 1.0.10.RELEASE
:spring-framework-docs: https://docs.spring.io/spring/docs/current/spring-framework-reference
:spring-framework-javadoc: https://docs.spring.io/spring/docs/current/javadoc-api
:spring-framework-website: https://spring.io/projects/spring-framework
:spring-session-docs: https://docs.spring.io/spring-session/docs/current/reference/html5
:spring-session-javadoc: https://docs.spring.io/spring-session/docs/current/api
:spring-session-website: https://spring.io/projects/spring-session
:spring-session-data-gemfire-docs: https://docs.spring.io/autorepo/docs/spring-session-data-geode-build/{spring-session-data-gemfire-version}/reference/html5
:spring-session-data-gemfire-javadoc: https://docs.spring.io/autorepo/docs/spring-session-data-geode-build/{spring-session-data-gemfire-version}/api
:spring-session-data-gemfire-website: https://spring.io/projects/spring-session-data-geode
:spring-test-data-gemfire-website: https://github.com/spring-projects/spring-test-data-geode#spring-test-framework-for-apache-geode--vmware-tanzu-gemfire
:wikipedia-docs: https://en.wikipedia.org/wiki


[[abstract]]
Spring Boot for {apache-geode-name} provides the convenience of Spring Boot's _convention over configuration_ approach
by using _auto-configuration_ with Spring Framework's powerful abstractions and highly consistent programming model to
simplify the development of {apache-geode-name} applications in a Spring context.

Secondarily, Spring Boot for {apache-geode-name} provides developers with a consistent experience whether building
and running Spring Boot, {apache-geode-name} applications locally or in a managed environment, such as with
https://tanzu.vmware.com/tanzu[VMware Tanzu Application Service] (TAS).

This project is a continuation and a logical extension to Spring Data for {apache-geode-name}'s
{spring-data-geode-docs-html}/#bootstrap-annotation-config[Annotation-based configuration model], and the goals
set forth in that model: _To enable application developers to *get up and running* as *quickly*, *reliably*, and as
*easily* as possible_. In fact, Spring Boot for {apache-geode-name} builds on this very
{spring-data-geode-docs-html}/#bootstrap-annotation-config[foundation] cemented in Spring Data for {apache-geode-name}
since the Spring Data Kay (2.0) Release Train.

[[introduction]]
== Introduction

Spring Boot for {apache-geode-name} automatically applies _auto-configuration_ to several key application concerns
(_use cases_) including, but not limited to:

* _Look-Aside, [Async] Inline, Near_ and _Multi-Site Caching_, by using {apache-geode-name} as a caching provider
in {spring-framework-docs}/integration.html#cache[Spring's Cache Abstraction].
For more information, see <<geode-caching-provider>>.
* {wikipedia-docs}/System_of_record[_System of Record_ (SOR)], persisting application state in {apache-geode-name}
by using {spring-data-commons-docs-html}/#repositories[Spring Data Repositories].
For more information, see <<geode-repositories>>.
* _Transactions_, managing application state consistently with {spring-framework-docs}/data-access.html#transaction[Spring Transaction Management]
with support for both {spring-data-geode-docs-html}/#apis:transaction-management[Local Cache]
and {spring-data-geode-docs-html}/#apis:global-transaction-management[Global JTA] Transactions.
* _Distributed Computations_, run with {apache-geode-name}'s {apache-geode-docs}/developing/function_exec/chapter_overview.html[Function Execution]
framework and conveniently implemented and executed with {spring-data-geode-docs-html}/#function-annotations[POJO-based, annotation support for Functions].
For more information, see <<geode-functions>>.
* _Continuous Queries_, expressing interests in a stream of events and letting applications react to and process changes
to data in near real-time with {apache-geode-name}'s {apache-geode-docs}/developing/continuous_querying/chapter_overview.html[Continuous Query (CQ)].
Listeners/Handlers are defined as simple Message-Driven POJOs (MDP) with Spring's {spring-framework-docs}/integration.html#jms-mdp[Message Listener Container],
which has been {spring-data-geode-docs-html}/#apis:continuous-query[extended] with its {spring-data-geode-docs-html}/#bootstrap-annotation-config-continuous-queries[configurable]
CQ support.
For more information, see <<geode-continuous-query>>.
* _Data Serialization_ using {apache-geode-name} {apache-geode-docs}/developing/data_serialization/gemfire_pdx_serialization.html[PDX]
with first-class {spring-data-geode-docs-html}/#bootstrap-annotation-config-pdx[configuration]
and {spring-data-geode-docs-html}/#mapping.pdx-serializer[support].
For more information, see <<geode-data-serialization>>.
* _Data Initialization_ to quickly load (import) data to hydrate the cache during application startup or write (export)
data on application shutdown to move data between environments (for example, TEST to DEV).
For more information, see <<geode-data-using>>.
* _Actuator_, to gain insight into the runtime behavior and operation of your cache, whether a client or a peer.
For more information, see <<actuator>>.
* _Logging_, to quickly and conveniently enable or adjust {apache-geode-name} log levels in your Spring Boot application
to gain insight into the runtime operations of the application as they occur.
For more information, see <<geode-logging>>.
* _Security_, including {apache-geode-docs}/managing/security/authentication_overview.html[Authentication]
& {apache-geode-docs}/managing/security/authorization_overview.html[Authorization], and Transport Layer Security (TLS)
with {apache-geode-name} {apache-geode-docs}/managing/security/ssl_overview.html[Secure Socket Layer (SSL)]. Once more,
Spring Data for {apache-geode-name} includes first-class support for configuring {spring-data-geode-docs-html}/#bootstrap-annotation-config-security[Auth]
and {spring-data-geode-docs-html}/#bootstrap-annotation-config-ssl[SSL].
For more information, see <<geode-security>>.
* _HTTP Session state management_, by including Spring Session for {apache-geode-name} on your application's classpath.
For more information, see <<geode-session>>.
* _Testing_. Whether you write Unit or Integration Tests for Apache Geode in a Spring context, SBDG covers all
your testing needs with the help of {spring-test-data-gemfire-website}[STDG].

While Spring Data for {apache-geode-name} offers a simple, consistent, convenient and declarative approach to configure
all these powerful {apache-geode-name} features, Spring Boot for {apache-geode-name} makes it even easier to do, as we
will explore throughout this reference documentation.

[[introduction-goals]]
=== Goals

While the SBDG project has many goals and objectives, the primary goals of this project centers around
three key principles:

1. From **_Open Source_** ({apache-geode-name}) to **_Commercial_** ({pivotal-gemfire-name}).
2. From **_Non-Managed_** (self-managed/hosted or on-premise installations) to **_Managed_**
({pivotal-cloudcache-name}, {vmware-gemfire-name}) environments.
3. With **little to no code or configuration changes** necessary.

It is also possible to go in the reverse direction, from _Managed_ back to a _Non-Managed_ environment
and even from _Commercial_ back to the _Open Source_ offering, again, with _little to no code or configuration_ changes.

NOTE: SBDG's promise is to deliver on these principles as much as is technically possible and as is technically allowed
by {apache-geode-name}.

[[getting-started]]
== Getting Started

To be immediately productive and as effective as possible when you use Spring Boot for {apache-geode-name}, it helps
to understand the foundation on which this project is built.

The story begins with the Spring Framework and the {spring-framework-docs}/core.html#spring-core[core technologies and concepts]
built into the Spring container.

Then our journey continues with the extensions built into Spring Data for {apache-geode-name} to simplify the development
of {apache-geode-name} applications in a Spring context, using Spring's powerful abstractions and highly consistent
programming model. This part of the story was greatly enhanced in Spring Data Kay,
with the {spring-data-geode-docs-html}/#bootstrap-annotation-config[Annotation-based configuration model].
Though this new configuration approach uses annotations and provides sensible defaults, its use is also very explicit
and assumes nothing. If any part of the configuration is ambiguous, SDG will fail fast. SDG gives you "`_choice_`",
so you still must tell SDG what you want.

Next, we venture into Spring Boot and all of its wonderfully expressive and highly opinionated "`_convention over configuration_`"
approach for getting the most out of your Spring {apache-geode-name} applications in the easiest, quickest, and most
reliable way possible. We accomplish this by combining Spring Data for {apache-geode-name}'s {spring-data-geode-docs-html}/#bootstrap-annotation-config[annotation-based configuration]
with Spring Boot's {spring-boot-docs-html}/#using-boot-auto-configuration[auto-configuration] to get you up and running
even faster and more reliably so that you are productive from the start.

As a result, it would be pertinent to begin your Spring Boot education with {spring-boot-docs-html}/#getting-started[Spring Boot's documentation].

Finally, we arrive at Spring Boot for {apache-geode-name} (SBDG).

TIP: See the corresponding Sample link:guides/getting-started.html[Guide] and {github-samples-url}/intro/getting-started[Code]
to see Spring Boot for {apache-geode-name} in action.

[[maven-gradle]]
== Using Spring Boot for {apache-geode-name}

To use Spring Boot for {apache-geode-name}, declare the `spring-geode-starter` on your Spring Boot application classpath:

.Maven
====
[source,xml]
[subs="verbatim,attributes"]
----
<dependencies>
    <dependency>
        <groupId>org.springframework.geode</groupId>
        <artifactId>spring-geode-starter</artifactId>
        <version>{spring-boot-data-geode-version}</version>
    </dependency>
</dependencies>
----

.Gradle
[source,gradle]
[subs="verbatim,attributes"]
----
dependencies {
    compile 'org.springframework.geode:spring-geode-starter:{spring-boot-data-geode-version}'
}
----
====

[[maven-bom]]
=== Maven BOM

If you anticipate using more than one Spring Boot for {apache-geode-name} (SBDG) module in your Spring Boot application,
you can also declare the new `org.springframework.geode:spring-geode-bom` Maven BOM in your application Maven POM.

Your application use case may require more than one module if (for example, you need (HTTP) Session state management
and replication with, for example, `spring-geode-starter-session`), if you need to enable Spring Boot Actuator endpoints
for {apache-geode-name} (for example, `spring-geode-starter-actuator`), or if you need assistance writing complex Unit
and (Distributed) Integration Tests with Spring Test for Apache Geode (STDG) (for example, `spring-geode-starter-test`).

You can declare and use any one of the SBDG modules:

* `spring-geode-starter`
* `spring-geode-starter-actuator`
* `spring-geode-starter-logging`
* `spring-geode-starter-session`
* `spring-geode-starter-test`

When more than one SBDG module is in use, it makes sense to declare the `spring-geode-bom` to manage all the dependencies
such that the versions and transitive dependencies necessarily align properly.

A Spring Boot application Maven POM that declares the `spring-geode-bom` along with two or more module dependencies
might appear as follows:

.Spring Boot application Maven POM
====
[source,xml]
[subs="verbatim,attributes"]
----
<project xmlns="http://maven.apache.org/POM/4.0.0">

    <modelVersion>4.0.0</modelVersion>

    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>{spring-boot-version}</version>
    </parent>

    <artifactId>my-spring-boot-application</artifactId>

    <properties>
        <spring-geode.version>{spring-boot-data-geode-version}</spring-geode.version>
    </properties>

    <dependencyManagement>
        <dependencies>
            <dependency>
                <groupId>org.springframework.geode</groupId>
                <artifactId>spring-geode-bom</artifactId>
                <version>${spring-geode.version}</version>
                <scope>import</scope>
                <type>pom</type>
            </dependency>
        </dependencies>
    </dependencyManagement>

    <dependencies>
        <dependency>
            <groupId>org.springframework.geode</groupId>
            <artifactId>spring-geode-starter</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.geode</groupId>
            <artifactId>spring-geode-starter-session</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.geode</groupId>
            <artifactId>spring-geode-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
    </dependencies>

</project>
----
====

Notice that:

* The Spring Boot application Maven POM (`pom.xml`) contains a `<dependencyManagement>` section that declares
the `org.springframework.geode:spring-geode-bom`.
* None of the `spring-geode-starter[-xyz]` dependencies explicitly specify a `<version>`. The version is managed by
the `spring-geode.version` property, making it easy to switch between versions of SBDG as needed and use it in all
the SBDG modules declared and used in your application Maven POM.

If you change the version of SBDG, be sure to change the `org.springframework.boot:spring-boot-starter-parent` POM
version to match.  SBDG is always one `major` version behind but matches on `minor` version and `patch` version
(and `version qualifier` -- `SNAPSHOT`, `M#`, `RC#`, or `RELEASE`, if applicable).

For example, SBDG `1.4.0` is based on Spring Boot `2.4.0`. SBDG `1.3.5.RELEASE` is based on Spring Boot `2.3.5.RELEASE`,
and so on. It is important that the versions align.

TIP: All of these concerns are handled for you by going to https://start.spring.io[start.spring.io]
and adding the "_Spring for {apache-geode-name}_" dependency to a project. For convenience, you can click
this https://start.spring.io/#!platformVersion={spring-boot-version}&dependencies=geode[link] to get started.

[[gradle-dependency-management]]
=== Gradle Dependency Management

Using Gradle is similar to using Maven.

Again, if you declare and use more than one SBDG module in your Spring Boot application (for example,
the `spring-geode-starter` along with the `spring-geode-starter-actuator` dependency), declaring the `spring-geode-bom`
inside your application Gradle build file helps.

Your application Gradle build file configuration (roughly) appears as follows:

.Spring Boot application Gradle build file
====
[source,groovy]
[subs="verbatim,attributes"]
----
plugins {
  id 'org.springframework.boot' version '{spring-boot-version}'
  id 'io.spring.dependency-management' version '{spring-dependency-management-gradle-plugin-version}'
  id 'java'
}

// ...

ext {
  set('springGeodeVersion', "{spring-boot-data-geode-version}")
}

dependencies {
  implementation 'org.springframework.geode:spring-geode-starter'
  implementation 'org.springframework.geode:spring-geode-starter-actuator'
  testImplementation 'org.springframework.boot:spring-boot-starter-test'
}

dependencyManagement {
  imports {
    mavenBom "org.springframework.geode:spring-geode-bom:$\{springGeodeVersion\}"
  }
}
----
====

A combination of the {spring-boot-docs-html}/using-spring-boot.html#using-boot-gradle[Spring Boot Gradle Plugin]
and the https://github.com/spring-gradle-plugins/dependency-management-plugin[Spring Dependency Management Gradle Plugin]
manages the application dependencies for you.

In a nutshell, the _Spring Dependency Management Gradle Plugin_ provides dependency management capabilities for Gradle,
much like Maven. The _Spring Boot Gradle Plugin_ defines a curated and tested set of versions for many third party Java
libraries. Together, they make adding dependencies and managing (compatible) versions easier.

Again, you need not explicitly declare the version when adding a dependency, including a new SBDG module dependency
(for example, `spring-geode-starter-session`), since this has already been determined for you. You can declare the
dependency as follows:

====
[source,groovy]
----
implementation 'org.springframework.geode:spring-geode-starter-session'
----
====

The version of SBDG is controlled by the extension property (`springGeodeVersion`) in the application Gradle build file.

To use a different version of SBDG, set the `springGeodeVersion` property to the desired version (for example,
`1.3.5.RELEASE`). Remember to be sure that the version of Spring Boot matches.

SBDG is always one `major` version behind but matches on `minor` version and `patch` version (and `version qualifier`,
such as `SNAPSHOT`, `M#`, `RC#`, or `RELEASE`, if applicable). For example, SBDG `1.4.0` is based on Spring Boot `2.4.0`,
SBDG `1.3.5.RELEASE` is based on Spring Boot `2.3.5.RELEASE`, and so on. It is important that the versions align.

TIP: All of these concerns are handled for you by going to https://start.spring.io[start.spring.io]
and adding the "_Spring for {apache-geode-name}_" dependency to a project. For convenience, you can click
this https://start.spring.io/#!platformVersion={spring-boot-version}&dependencies=geode[link] to get started.

ifeval::["{version-snapshot}" == "true"]
[[maven-gradle-repository]]
=== Repository Declaration

Since you are using a `SNAPSHOT` version, you need to add the Spring Snapshot Maven Repository.

If you use Maven, include the following `repository` declaration in your `pom.xml`:

.Maven
====
[source,xml]
----
<repositories>
    <repository>
        <id>spring-snapshot</id>
        <url>https://repo.spring.io/snapshot</url>
    </repository>
</repositories>
----
====

If you use Gradle, include the following `repository` declaration in your `build.gradle`:

.Gradle
====
[source,gradle]
----
repositories {
    maven { url: 'https://repo.spring.io/snapshot' }
}
----
====
endif::[]

ifeval::["{version-milestone}" == "true"]
[[maven-gradle-repository]]
=== Repository declaration

Since you are using a Milestone version, you need to add the Spring Milestone Maven Repository.

If you use Maven, include the following `repository` declaration in your `pom.xml`:

.Maven
====
[source,xml]
----
<repositories>
    <repository>
        <id>spring-milestone</id>
        <url>https://repo.spring.io/milestone</url>
    </repository>
</repositories>
----
====

If you use Gradle, include the following `repository` declaration in your `build.gradle`:

.Gradle
====
[source,gradle]
----
repositories {
    maven { url: 'https://repo.spring.io/milestone' }
}
----
====
endif::[]

include::{include-dir}/clientcache-applications.adoc[]
include::{include-dir}/configuration-auto.adoc[]
include::{include-dir}/configuration-declarative.adoc[]
include::{include-dir}/configuration-externalized.adoc[]
include::{include-dir}/gemfire-properties.adoc[]
include::{include-dir}/caching.adoc[]
include::{include-dir}/templates.adoc[]
include::{include-dir}/repositories.adoc[]
include::{include-dir}/functions.adoc[]
include::{include-dir}/continuous-query.adoc[]
include::{include-dir}/data.adoc[]
include::{include-dir}/data-serialization.adoc[]
include::{include-dir}/logging.adoc[]
include::{include-dir}/security.adoc[]
include::{include-dir}/testing.adoc[]
include::{include-dir}/geode-api-ext.adoc[]
include::{include-dir}/actuator.adoc[]
include::{include-dir}/session.adoc[]
include::{include-dir}/cloudfoundry.adoc[]
include::{include-dir}/docker.adoc[]
include::{include-dir}/samples.adoc[]
include::{include-dir}/appendix.adoc[]
