Files
spring-boot-data-geode/spring-geode-docs/src/docs/asciidoc/index.adoc

435 lines
21 KiB
Plaintext

[[spring-boot-data-geode]]
= Spring Boot for Apache Geode & VMware Tanzu GemFire 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-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
: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--pivotal-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} & {pivotal-gemfire-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>>.
* _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>>.
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 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 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 Spring Test for Apache Geode (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
explicitly specify a `<version>`, which is 3) managed by the `spring-geode.version` property making it easy to switch
between versions of SBDG as needed, applied evenly to all the SBDG modules declared and used in your application Maven
POM.
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` and so on. It is important that the versions align.
Of course, all of these concerns are easy to do and handled for you 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!
[[gradle-dependency-management]]
=== Gradle Dependency Management
The user experience when using Gradle is similar to that of Maven.
Again, if you will be declaring and using more than 1 SBDG module in your Spring Boot application, for example,
the `spring-geode-starter` along with the `spring-geode-starter-actuator` dependency, then using the `spring-geode-bom`
inside your application Gradle build file will help.
Your application Gradle build file configuration will roughly appear 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]
manage 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 3rd party Java
libraries. Together they make adding dependencies and managing (compatible) versions easier!
Again, you don't need to explicitly declare the version when adding a dependency, including a new SBDG module dependency
(e.g. `spring-geode-starter-session`) since this has already been determined for you. You can simply declare the
dependency:
[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, simply set the `springGeodeVersion` property to the desired version
(e.g. `1.3.5.RELEASE`). Of course, make sure the version of Spring Boot matches!
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` and so on. It is important that the versions align.
Of course, all of these concerns are easy to do and handled for you 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/#!type=gradle-project&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[]