[[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-9
: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-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]]
Welcome to _Spring Boot for {apache-geode-name} & {pivotal-gemfire-name}_.

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

Secondarily, Spring Boot for {apache-geode-name} & {pivotal-gemfire-name} aims to provide developers with a consistent
experience whether building and running Spring Boot, {apache-geode-name} & {pivotal-gemfire-name} applications locally
or in a managed environment, such as with https://pivotal.io/platform[Pivotal CloudFoundry] (PCF).

This project is a continuation and a logical extension to Spring Data for {apache-geode-name} & {pivotal-gemfire-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* and as *easily* as possible_.
In fact, Spring Boot for {apache-geode-name} & {pivotal-gemfire-name} builds on this very {spring-data-geode-docs-html}/#bootstrap-annotation-config[foundation]
cemented in Spring Data for {apache-geode-name} & {pivotal-gemfire-name} (SDG footnote:SDG[Spring Data for {apache-geode-name}
and Spring Data for {pivotal-gemfire-name} are commonly known as SDG.]) since the Spring Data Kay Release Train.

[[introduction]]
== Introduction

Spring Boot for {apache-geode-name} & {pivotal-gemfire-name} automatically applies _auto-configuration_ to several key
application concerns (_Use Cases_) including, but not limited to:

* _Look-Aside, Inline, Near_ and _Multi-Site Caching_, using {apache-geode-name} as a caching provider in
{spring-framework-docs}/integration.html#cache[Spring's Cache Abstraction].
<<geode-caching-provider,Learn more>>.
* {wikipedia-docs}/System_of_record[_System of Record_ (SOR)], persisting application state reliably in {apache-geode-name}
using {spring-data-commons-docs-html}/#repositories[Spring Data Repositories].
<<geode-repositories,Learn more>>.
* _Transactions_, managing application state consistently with {spring-framework-docs}/data-access.html#transaction[Spring Transaction Management]
and SDGfootnote:SDG[] 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_, ran with {apache-geode-name}'s {apache-geode-docs}/developing/function_exec/chapter_overview.html[Function Execution] framework,
and conveniently implemented and executed with SDGfootnote:SDG[] {spring-data-geode-docs-html}/#function-annotations[POJO-based, annotation support for Functions].
<<geode-functions,Learn more>>.
* _Continuous Queries_, expressing interests in a stream of events, allowing applications to 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)].
Handlers are defined as simple Message-Driven POJOs (MDP) using Spring's {spring-framework-docs}/integration.html#jms-mdp[Message Listener Container],
which has been {spring-data-geode-docs-html}/#apis:continuous-query[extended] in SDGfootnote:SDG[] with its
{spring-data-geode-docs-html}/#bootstrap-annotation-config-continuous-queries[configurable] CQ support.
<<geode-continuous-query,Learn more>>.
* _Data Serialization_ with {apache-geode-name} {apache-geode-docs}/developing/data_serialization/gemfire_pdx_serialization.html[PDX],
including first-class {spring-data-geode-docs-html}/#bootstrap-annotation-config-pdx[configuration]
and {spring-data-geode-docs-html}/#mapping.pdx-serializer[support] in SDGfootnote:SDG[].
<<geode-data-serialization,Learn more>>.
* _Data Initialization_ to quickly load (import) to hydrate the cache during application startup or write (export) data
on application shutdown to move data between environments (e.g. TEST to DEV). <<geode-data-using,Learn more>>.
* _Actuator_ - to gain insight into the runtime behavior and operation of your cache, whether a client or a peer.
<<actuator,Learn more>>.
* _Logging_ - 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 app as they occur.
<<geode-logging,Learn more>>.
* _Security_, including {apache-geode-docs}/managing/security/authentication_overview.html[Authentication]
& {apache-geode-docs}/managing/security/authorization_overview.html[Authorization] as well as Transport Layer Security (TLS)
using {apache-geode-name} {apache-geode-docs}/managing/security/ssl_overview.html[Secure Socket Layer (SSL)]. Once more,
SDGfootnote:SDG[] 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].
<<geode-security,Learn more>>.
* _HTTP Session state management_, by including Spring Session for {apache-geode-name} on your application's classpath.
<<geode-session,Learn more>>.
* _Testing_ - whether writing 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} & {pivotal-gemfire-name} offers a simple, consistent, convenient
and declarative approach to configure all these powerful {apache-geode-name} features, Spring Boot for {apache-geode-name}
& {pivotal-gemfire-name} makes it even easier to do as we will explore throughout this reference documentation.

[[getting-started]]
== Getting Started

In order to be immediately productive and as effective as possible using Spring Boot for {apache-geode-name}
& {pivotal-gemfire-name}, it is helpful to understand the foundation on which this project was built.

Of course, our 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} & {pivotal-gemfire-name}
(SDGfootnote:SDG[]) to truly simplify the development of {apache-geode-name} & {pivotal-gemfire-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 SDGfootnote:SDG[] {spring-data-geode-docs-html}/#bootstrap-annotation-config[Annotation-based configuration model].
Though this new configuration approach using annotations provides sensible defaults out-of-the-box, 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 SDGfootnote: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}/{pivotal-gemfire-name} based applications in the
easiest, quickest and most reliable way possible.  We accomplish this by combining Spring Data for {apache-geode-name}
& {pivotal-gemfire-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 such, it would be pertinent to begin your Spring Boot education {spring-boot-docs-html}/#getting-started[here].

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

TIP: Refer to 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}, simply declare the `spring-geode-starter` on your 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-gradle-bom]]
=== Maven BOM

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

Your application use case(s) may require more than 1 module if, for example, you need (HTTP) Session state management
and replication (e.g. `spring-geode-starter-session`), or you need to enable Spring Boot Actuator endpoints for
{apache-geode-name} (e.g. `spring-geode-starter-actuator`), or perhaps you need assistance writing complex Unit
and distributed Integration Tests using STDG (e.g. `spring-geode-starter-test`).

You can declare (include) and use any 1 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 1 SBDG module is in play, then it makes sense to use the `spring-geode-bom` to manage all
the dependencies so that the versions and transitive dependencies necessarily align properly.

Your Spring Boot application Maven POM using the `spring-geode-bom` along with 2 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 1) the Spring Boot application Maven POM (`pom.xml`) contains a `<dependencyManagement>` section declaring
the `org.springframework.geode:spring-geode-bom` and that 2) none of the `spring-geode-starter[-xyz]` dependencies
specify an explicit `<version>`, which is 3) managed by the `spring-geode.version` property making it easy to switch
between versions of SBDG as needed.

If you change the version of SBDG, make sure to change the `org.springframework.boot:spring-boot-starter-parent` POM
version to match.  SBDG is always 1 `major` version behind, but matches on `minor` version and `patch` version
(and `version qualifier`, e.g. `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`. It is important that the versions align.

Of course, all of these concerns are easy to do by simply going to https://start.spring.io[start.spring.io]
and adding the "_Spring for {apache-geode-name}_" dependency.

Clink on 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 are using _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 are using _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 are using _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 are using _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}/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[]
