= Spring Boot for Apache Geode & Pivotal GemFire Reference Guide
John Blum
:revdate: {localdate}
:revnumber: {version}
:doctype: book
:toc:
:toclevels: 1
:source-highlighter: prettify
:numbered:
:icons: font
:hide-uri-scheme:
:apache-geode-version: 16
:apache-geode-docs: https://geode.apache.org/docs/guide/{apache-geode-version}
:apache-geode-javadoc: https://geode.apache.org/releases/latest/javadoc
:pivotal-cloudcache-version: 1-3
:pivotal-cloudcache-docs: https://docs.pivotal.io/p-cloud-cache/{pivotal-cloudcache-version}/developer.html
:pivotal-gemfire-version: 95
:pivotal-gemfire-docs: https://gemfire.docs.pivotal.io/{pivotal-gemfire-version}/geode/reference/topics/gemfire_properties.html
:pivotal-gemfire-javadoc: https://gemfire-{pivotal-gemfire-version}-javadocs.docs.pivotal.io/
: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-data-geode-javadoc: https://docs.spring.io/autorepo/docs/spring-boot-data-geode-build/1.0.0.BUILD-SNAPSHOT/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-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-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-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-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://github.com/spring-projects/spring-session-data-geode/blob/master/README.adoc
:wikipedia-docs: https://en.wikipedia.org/wiki


[[abstract]]
Welcome to _Spring Boot for Apache Geode & Pivotal GemFire_.

Spring Boot for Apache Geode & Pivotal GemFire 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 or Pivotal GemFire applications in a Spring context.

Secondarily, Spring Boot for Apache Geode & Pivotal GemFire aims to provide developers with a consistent experience
whether building and running Spring Boot, Apache Geode/Pivotal GemFire 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/Pivotal GemFire'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/Pivotal GemFire builds on this very
{spring-data-geode-docs-html}/#bootstrap-annotation-config[foundation] cemented in
Spring Data for Apache Geode/Pivotal GemFire
(SDG footnoteref:[SDG, Spring Data for Apache Geode and Spring Data for Pivotal GemFire are commonly known as SDG.])
since the Spring Data Kay Release Train.

[[introduction]]
== Introduction

Spring Boot for Apache Geode & Pivotal GemFire automatically applies _auto-configuration_ to several key
application concerns (_Use Cases_) including, but not limited to:

* _Look-Aside Caching_, using either Apache Geode or Pivotal GemFire as a caching provider in
{spring-framework-docs}/integration.html#cache[Spring's Cache Abstraction].
* {wikipedia-docs}/System_of_record[_System of Record_ (SOR)], persisting application state reliably in Apache Geode
or Pivotal GemFire using {spring-data-commons-docs-html}/#repositories[Spring Data Repositories].
* _Transactions_, managing application state consistently with {spring-framework-docs}/data-access.html#transaction[Spring Transaction Management]
and SDGfootnoteref:[SDG, Spring Data for Apache Geode and Spring Data for Pivotal GemFire are commonly known as SDG.]
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/Pivotal GemFire's {apache-geode-docs}/developing/function_exec/chapter_overview.html[Function Executions] framework
and conveniently implemented and executed with SDGfootnoteref:[SDG] {spring-data-geode-docs-html}/#function-annotations[POJO-based, annotation support for Functions].
* _Continuous Queries_, expressing interests in a stream of events, where applications are able to react to and process changes to data in near real-time
using Apache Geode/Pivotal GemFire {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] by SDGfootnoteref:[SDG] with its
{spring-data-geode-docs-html}/#bootstrap-annotation-config-continuous-queries[configurable] CQ support.
* _Data Serialization_ with Apache Geode/Pivotal GemFire {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 SDGfootnoteref:[SDG].
* _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/Pivotal GemFire's {apache-geode-docs}/managing/security/ssl_overview.html[Secure Socket Layer (SSL)].
Once again, SDGfootnoteref:[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].
* _HTTP Session state management_, by including Spring Session for Apache Geode/Pivotal GemFire on your application's
classpath.

While Spring Data for Apache Geode & Pivotal GemFire offers a simple, convenient and declarative approach to configure
all these powerful Apache Geode/Pivotal GemFire features, Spring Boot for Apache Geode & Pivotal Gemfire 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/Pivotal GemFire,
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 & Pivotal GemFire
(SDGfootnoteref:[SDG, Spring Data for Apache Geode and Spring Data for Pivotal GemFire are commonly known as SDG.])
to truly simplify the development of Apache Geode & Pivotal GemFire 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 SDGfootnoteref:[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 SDGfootnoteref:[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/Pivotal GemFire based applications in the easiest,
quickest and most reliable way possible.  We accomplish this by combining Spring Data for Apache Geode/Pivotal GemFire'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 & Pivotal GemFire (SBDG).

[[maven-gradle]]
== Using Spring Boot for Apache Geode and Pivotal GemFire

To use Spring Boot for Apache Geode, 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,java]
[subs="verbatim,attributes"]
----
dependencies {
    compile 'org.springframework.geode:spring-geode-starter:{spring-boot-data-geode-version}'
}
----

TIP: To use Pivotal GemFire in place of Apache Geode, simply change the `artifactId` from `spring-geode-starter`
to `spring-gemfire-starter`.

ifeval::["{version-snapshot}" == "true"]
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/libs-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/libs-snapshot' }
}
----
endif::[]

ifeval::["{version-milestone}" == "true"]
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/libs-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/libs-milestone' }
}
----
endif::[]

include::clientcache-applications.adoc[]
include::configuration.adoc[]
include::caching.adoc[]
include::templates.adoc[]
include::repositories.adoc[]
include::functions.adoc[]
include::continuous-query.adoc[]
include::data-serialization.adoc[]
include::security.adoc[]
include::actuator.adoc[]
include::session.adoc[]
include::samples.adoc[]
include::appendix.adoc[]
