Cross-reference the reference documentation and sample guide for Spring Boot Auto-configuration.

This commit is contained in:
John Blum
2020-09-03 17:29:14 -07:00
parent ab1c64dbf8
commit c4302adafe
2 changed files with 107 additions and 88 deletions

View File

@@ -1,9 +1,9 @@
[[geode-configuration-auto]] [[geode-configuration-auto]]
== Auto-configuration == Auto-configuration
The following Spring Framework, Spring Data for Apache Geode & Pivotal GemFire (SDG) and Spring Session for Apache Geode The following Spring Framework, Spring Data for {apache-geode-name} & {pivotal-gemfire-name} (SDG) and Spring Session
& Pivotal GemFire (SSDG) _Annotations_ are implicitly declared by Spring Boot for Apache Geode & Pivotal GemFire's for {apache-geode-name} and {pivotal-gemfire-name} (SSDG) _Annotations_ are implicitly declared by Spring Boot for
(SBDG) _Auto-configuration_. {apache-geode-name} & {pivotal-gemfire-name}'s (SBDG) _Auto-configuration_.
* `@ClientCacheApplication` * `@ClientCacheApplication`
* `@EnableGemfireCaching` (or alternatively, Spring Framework's `@EnableCaching`) * `@EnableGemfireCaching` (or alternatively, Spring Framework's `@EnableCaching`)
@@ -21,13 +21,17 @@ NOTE: This means you DO NOT need to explicitly declare any of these _Annotations
since they are provided by SBDG already. The only reason you would explicitly declare any of these _Annotations_ is if since they are provided by SBDG already. The only reason you would explicitly declare any of these _Annotations_ is if
you wanted to "_override_" Spring Boot's, and in particular, SBDG's _Auto-configuration_. Otherwise, it is unnecessary! you wanted to "_override_" Spring Boot's, and in particular, SBDG's _Auto-configuration_. Otherwise, it is unnecessary!
TIP: You should read the chapter in Spring Boot's Reference Guide on TIP: You should read the chapter in Spring Boot's Reference Documentation on
{spring-boot-docs-html}/#using-boot-auto-configuration[Auto-configuration]. {spring-boot-docs-html}/#using-boot-auto-configuration[Auto-configuration].
TIP: You should review the chapter in Spring Data for Apache Geode and Pivotal GemFire's (SDG) Reference Guide on TIP: You should review the chapter in Spring Data for {apache-geode-name} and {pivotal-gemfire-name}'s (SDG) Reference Documentation
{spring-data-geode-docs-html}/#bootstrap-annotation-config[Annotation-based Configuration]. For a quick reference, on {spring-data-geode-docs-html}/#bootstrap-annotation-config[Annotation-based Configuration]. For a quick reference,
or an overview of Annotation-based Configuration, see {spring-data-geode-docs-html}/#bootstap-annotations-quickstart[here]. or an overview of Annotation-based Configuration, see {spring-data-geode-docs-html}/#bootstap-annotations-quickstart[here].
TIP: Refer to the corresponding Sample link:guides/boot-configuration.html[Guide] and {github-samples-url}/boot/configuration[Code]
to see Spring Boot Auto-configuration for {apache-geode-name} in action!
[[geode-configuration-auto-customizing]] [[geode-configuration-auto-customizing]]
=== Customizing Auto-configuration === Customizing Auto-configuration
@@ -49,7 +53,9 @@ For example, to set the (client or peer) member's name, you can use the `@UseMem
---- ----
@SpringBootApplication @SpringBootApplication
@UseMemberName("MyMemberName") @UseMemberName("MyMemberName")
class SpringBootClientCacheApplication { ... } class SpringBootClientCacheApplication {
///...
}
---- ----
Alternatively, you could set the `spring.application.name` or the `spring.data.gemfire.name` property in Spring Boot Alternatively, you could set the `spring.application.name` or the `spring.data.gemfire.name` property in Spring Boot
@@ -104,7 +110,9 @@ then you can declare your intent in the `@SpringBootApplication` annotation, lik
@SpringBootApplication( @SpringBootApplication(
exclude = { DataSourceAutoConfiguration.class, PdxAutoConfiguration.class } exclude = { DataSourceAutoConfiguration.class, PdxAutoConfiguration.class }
) )
class SpringBootClientCacheApplication { ... } class SpringBootClientCacheApplication {
// ...
}
---- ----
WARNING: Make sure you understand what you are doing when you are "disabling" _Auto-configuration_. WARNING: Make sure you understand what you are doing when you are "disabling" _Auto-configuration_.
@@ -117,15 +125,17 @@ Overriding SBDG _Auto-configuration_ was <<geode-autoconfiguration-annotations-o
In a nutshell, if you want to override the default _Auto-configuration_ provided by SBDG then you must annotate In a nutshell, if you want to override the default _Auto-configuration_ provided by SBDG then you must annotate
your `@SpringBootApplication` class with your intent. your `@SpringBootApplication` class with your intent.
For example, say you want to configure and bootstrap an Apache Geode or Pivotal GemFire `CacheServer` application For example, say you want to configure and bootstrap an {apache-geode-name} `CacheServer` application (a peer;
(a peer; not a client), then you would: not a client), then you would:
.Overriding the default `ClientCache` _Auto-Configuration_ by configuring & bootstrapping a `CacheServer` application .Overriding the default `ClientCache` _Auto-Configuration_ by configuring & bootstrapping a `CacheServer` application
[source,java] [source,java]
---- ----
@SpringBootApplication @SpringBootApplication
@CacheServerApplication @CacheServerApplication
class SpringBootCacheServerApplication { ... } class SpringBootCacheServerApplication {
// ...
}
---- ----
Even when you explicitly declare the `@ClientCacheApplication` annotation on your `@SpringBootApplication` class, Even when you explicitly declare the `@ClientCacheApplication` annotation on your `@SpringBootApplication` class,
@@ -136,7 +146,9 @@ like so:
---- ----
@SpringBootApplication @SpringBootApplication
@ClientCacheApplication @ClientCacheApplication
class SpringBootClientCacheApplication { ... } class SpringBootClientCacheApplication {
// ...
}
---- ----
You are overriding SBDG's _Auto-configuration_ of the `ClientCache` instance. As a result, you now have also implicitly You are overriding SBDG's _Auto-configuration_ of the `ClientCache` instance. As a result, you now have also implicitly
@@ -167,11 +179,11 @@ To review the complete list of SBDG _Auto-confiugration_ classes, <<geode-auto-c
NOTE: The {spring-boot-data-geode-javadoc}/org/springframework/geode/boot/autoconfigure/ClientCacheAutoConfiguration.html[`ClientCacheAutoConfiguration`] class NOTE: The {spring-boot-data-geode-javadoc}/org/springframework/geode/boot/autoconfigure/ClientCacheAutoConfiguration.html[`ClientCacheAutoConfiguration`] class
corresponds to the {spring-data-geode-javadoc}/org/springframework/data/gemfire/config/annotation/ClientCacheApplication.html[`@ClientCacheApplication`] annotation. corresponds to the {spring-data-geode-javadoc}/org/springframework/data/gemfire/config/annotation/ClientCacheApplication.html[`@ClientCacheApplication`] annotation.
SBDG <<getting-started,starts>> with the opinion that application developers will primarily be building Apache Geode SBDG <<getting-started,starts>> with the opinion that application developers will primarily be building {apache-geode-name}
or Pivotal GemFire <<geode-clientcache-applications,client applications>> using Spring Boot. <<geode-clientcache-applications,client applications>> using Spring Boot.
Technically, this means building Spring Boot applications with either an Apache Geode or Pivotal GemFire `ClientCache` Technically, this means building Spring Boot applications with an {apache-geode-name} `ClientCache` instance connected
instance connected to a dedicated cluster of Apache Geode or Pivotal GemFire servers that manage the data as part of a to a dedicated cluster of {apache-geode-name} servers that manage the data as part of a
{apache-geode-docs}/topologies_and_comm/cs_configuration/chapter_overview.html[client/server] topology. {apache-geode-docs}/topologies_and_comm/cs_configuration/chapter_overview.html[client/server] topology.
By way of example, this means you *do not* need to explicitly declare and annotate your `@SpringBootApplication` class By way of example, this means you *do not* need to explicitly declare and annotate your `@SpringBootApplication` class
@@ -182,7 +194,9 @@ with SDG's `@ClientCacheApplication` annotation, like so:
---- ----
@SpringBootApplication @SpringBootApplication
@ClientCacheApplication @ClientCacheApplication
class SpringBootClientCacheApplication { ... } class SpringBootClientCacheApplication {
// ...
}
---- ----
This is because SBDG's provided _Auto-configuration_ class is already meta-annotated with SDG's This is because SBDG's provided _Auto-configuration_ class is already meta-annotated with SDG's
@@ -192,10 +206,12 @@ This is because SBDG's provided _Auto-configuration_ class is already meta-annot
[source,java] [source,java]
---- ----
@SpringBootApplication @SpringBootApplication
class SpringBootClientCacheApplication { ... } class SpringBootClientCacheApplication {
// ...
}
---- ----
TIP: Refer to SDG's Referene Guide for more details on Apache Geode or Pivotal GemFire TIP: Refer to SDG's Reference Documentation for more details on {apache-geode-name}
{spring-data-geode-docs-html}/#bootstrap-annotation-config-geode-applications[cache applications], {spring-data-geode-docs-html}/#bootstrap-annotation-config-geode-applications[cache applications],
and {spring-data-geode-docs-html}/#bootstrap-annotation-config-client-server-applications[client/server applications] and {spring-data-geode-docs-html}/#bootstrap-annotation-config-client-server-applications[client/server applications]
in particular. in particular.
@@ -206,7 +222,7 @@ in particular.
NOTE: The {spring-boot-data-geode-javadoc}/org/springframework/geode/boot/autoconfigure/CachingProviderAutoConfiguration.html[`CachingProviderAutoConfiguration`] class NOTE: The {spring-boot-data-geode-javadoc}/org/springframework/geode/boot/autoconfigure/CachingProviderAutoConfiguration.html[`CachingProviderAutoConfiguration`] class
corresponds to the {spring-data-geode-javadoc}/org/springframework/data/gemfire/cache/config/EnableGemfireCaching.html[`@EnableGemfireCaching`] annotation. corresponds to the {spring-data-geode-javadoc}/org/springframework/data/gemfire/cache/config/EnableGemfireCaching.html[`@EnableGemfireCaching`] annotation.
If you simply used the core Spring Framework to configure either Apache Geode or Pivotal GemFire as a _caching provider_ If you simply used the core Spring Framework to configure {apache-geode-name} as a _caching provider_
in {spring-framework-docs}/integration.html#cache[Spring's Cache Abstraction], you would need to do this: in {spring-framework-docs}/integration.html#cache[Spring's Cache Abstraction], you would need to do this:
.Configuring caching using the Spring Framework .Configuring caching using the Spring Framework
@@ -228,7 +244,7 @@ class CachingUsingApacheGeodeConfiguration {
} }
---- ----
If you were using Spring Data for Apache Geode's `@EnableGemfireCaching` annotation, then the above configuration If you were using Spring Data for {apache-geode-name}'s `@EnableGemfireCaching` annotation, then the above configuration
could be simplified to: could be simplified to:
.Configuring caching using Spring Data Geode .Configuring caching using Spring Data Geode
@@ -263,7 +279,7 @@ class CustomerService {
@Caching("CustomersByName") @Caching("CustomersByName")
Customer findBy(String name) { Customer findBy(String name) {
... // ...
} }
} }
---- ----
@@ -278,20 +294,20 @@ corresponds to the {spring-data-geode-javadoc}/org/springframework/data/gemfire/
Without having to enable anything, you simply annotate your application (POJO) component method(s) with the SDG Without having to enable anything, you simply annotate your application (POJO) component method(s) with the SDG
{spring-data-geode-javadoc}/org/springframework/data/gemfire/listener/annotation/ContinuousQuery.html[`@ContinuousQuery`] {spring-data-geode-javadoc}/org/springframework/data/gemfire/listener/annotation/ContinuousQuery.html[`@ContinuousQuery`]
annotation to register a CQ and start receiving events. The method acts as a `CqEvent` handler, or in Apache Geode and annotation to register a CQ and start receiving events. The method acts as a `CqEvent` handler, or in {apache-geode-name}'s
Pivotal GemFire's case, the method would be an implementation of case, the method would be an implementation of
{apache-geode-javadoc}/org/apache/geode/cache/query/CqListener.html[`CqListener`]. {apache-geode-javadoc}/org/apache/geode/cache/query/CqListener.html[`CqListener`].
.Declare application CQs .Declare application CQs
[source,java] [source,java]
---- ----
@Component @Component
class MyCustomerApplicationContinuousQueries class MyCustomerApplicationContinuousQueries {
@ContinuousQuery("SELECT customer.* FROM /Customers customers" @ContinuousQuery("SELECT customer.* FROM /Customers customers"
+ " WHERE customer.getSentiment().name().equalsIgnoreCase('UNHAPPY')") + " WHERE customer.getSentiment().name().equalsIgnoreCase('UNHAPPY')")
public void handleUnhappyCustomers(CqEvent event) { public void handleUnhappyCustomers(CqEvent event) {
... // ...
} }
} }
---- ----
@@ -335,18 +351,18 @@ Then you can inject the Function execution into any application component and us
package example.app.service; package example.app.service;
@Service @Service
interface CustomerService { class CustomerService {
@Autowired @Autowired
private MyCustomerapplicationFunctions customerFunctions; private MyCustomerapplicationFunctions customerFunctions;
public void analyzeCustomerSentiment(Customer customer) { void analyzeCustomerSentiment(Customer customer) {
... // ...
this.customerFunctions.applyCredit(customer); this.customerFunctions.applyCredit(customer);
... // ...
} }
} }
---- ----
@@ -400,9 +416,9 @@ class CustomerService {
public void processCustomersWithSentiment(Sentiment sentiment) { public void processCustomersWithSentiment(Sentiment sentiment) {
this.repository.findBySentimentEqualTo(sentiment).forEach(customer -> { ... }); this.repository.findBySentimentEqualTo(sentiment).forEach(customer -> { /* ... */ });
... // ...
} }
} }
---- ----
@@ -421,13 +437,13 @@ NOTE: The {spring-boot-data-geode-javadoc}/org/springframework/geode/boot/autoco
corresponds to the {spring-data-geode-javadoc}/org/springframework/data/gemfire/config/annotation/EnableLogging.html[`@EnableLogging`] annotation. corresponds to the {spring-data-geode-javadoc}/org/springframework/data/gemfire/config/annotation/EnableLogging.html[`@EnableLogging`] annotation.
Logging is an essential application concern to understand what is happening in the system along with when and where Logging is an essential application concern to understand what is happening in the system along with when and where
the event occurred. As such, SBDG auto-configures logging for Apache Geode and Pivotal GemFire by default, using the event occurred. As such, SBDG auto-configures logging for {apache-geode-name} by default, using the default
the default log-level, "_config_". log-level, "_config_".
If you wish to change an aspect of logging, such as the log-level, you would typically do this in Spring Boot If you wish to change an aspect of logging, such as the log-level, you would typically do this in Spring Boot
`application.properties`: `application.properties`:
.Change the log-level for Apache Geode .Change the log-level for {apache-geode-name}
[source,txt] [source,txt]
---- ----
# Spring Boot application.properites. # Spring Boot application.properites.
@@ -436,9 +452,9 @@ spring.data.gemfire.cache.log-level=debug
---- ----
Other aspects may be configured as well, such as the log file size and disk space limits for the file system location Other aspects may be configured as well, such as the log file size and disk space limits for the file system location
used to store the Apache Geode log files at runtime. used to store the {apache-geode-name} log files at runtime.
Under-the-hood, Apache Geode's logging is based on Log4j. Therefore, you can configure Apache Geode logging using Under-the-hood, {apache-geode-name}'s logging is based on Log4j. Therefore, you can configure {apache-geode-name} logging using
any logging provider (e.g. Logback) and configuration metadata appropriate for that logging provider so long as you any logging provider (e.g. Logback) and configuration metadata appropriate for that logging provider so long as you
supply the necessary adapter between Log4j and whatever logging system you are using. For instance, if you include supply the necessary adapter between Log4j and whatever logging system you are using. For instance, if you include
`org.springframework.boot:spring-boot-starter-logging` then you will be using Logback and you will need the `org.springframework.boot:spring-boot-starter-logging` then you will be using Logback and you will need the
@@ -459,7 +475,7 @@ or even possible in other cases (e.g. when you are using a 3rd party library for
In these situations, you need to be able to send your object anywhere without unduly requiring the class type In these situations, you need to be able to send your object anywhere without unduly requiring the class type
to be serializable as well as to exist on the classpath for every place it is sent. Indeed, the final destination to be serializable as well as to exist on the classpath for every place it is sent. Indeed, the final destination
may not even be a Java application! This is where Apache Geode {apache-geode-docs}/developing/data_serialization/gemfire_pdx_serialization.html[PDX Serialization] may not even be a Java application! This is where {apache-geode-name} {apache-geode-docs}/developing/data_serialization/gemfire_pdx_serialization.html[PDX Serialization]
steps into help. steps into help.
However, you don't have to figure out how to configure PDX to identify the application class types that will need to be However, you don't have to figure out how to configure PDX to identify the application class types that will need to be
@@ -477,7 +493,7 @@ class Customer {
@Indexed @Indexed
private String name; private String name;
... // ...
} }
---- ----
@@ -493,8 +509,8 @@ and {spring-boot-data-geode-javadoc}/org/springframework/geode/boot/autoconfigur
corresponds to the {spring-data-geode-javadoc}/org/springframework/data/gemfire/config/annotation/EnableSecurity.html[`@EnableSecurity`] annotation, but applies corresponds to the {spring-data-geode-javadoc}/org/springframework/data/gemfire/config/annotation/EnableSecurity.html[`@EnableSecurity`] annotation, but applies
Security, and specifically, Authentication/Authorization configuration for both clients and servers. Security, and specifically, Authentication/Authorization configuration for both clients and servers.
Configuring your Spring Boot, Apache Geode `ClientCache` application to properly authenticate with a cluster of secure Configuring your Spring Boot, {apache-geode-name} `ClientCache` application to properly authenticate with a cluster of
Apache Geode or Pivotal GemFire servers is as simple as setting a _username_ and _password_ in Spring Boot secure{apache-geode-name} servers is as simple as setting a _username_ and _password_ in Spring Boot
`application.properties`: `application.properties`:
.Supplying Authentication Credentials .Supplying Authentication Credentials
@@ -510,7 +526,7 @@ NOTE: Authentication is even easier to configure in a managed environment like P
you don't have to do anything! you don't have to do anything!
Authorization is configured on the server-side and is made simple with SBDG and the help of https://shiro.apache.org/[Apache Shiro]. Authorization is configured on the server-side and is made simple with SBDG and the help of https://shiro.apache.org/[Apache Shiro].
Of course, this assumes you are using SBDG to configure and bootstrap your Apache Geode cluster in the first place, Of course, this assumes you are using SBDG to configure and bootstrap your {apache-geode-name} cluster in the first place,
which is <<geode-cluster-configuration-bootstrapping,possible>>, and made even easier with SBDG. which is <<geode-cluster-configuration-bootstrapping,possible>>, and made even easier with SBDG.
TIP: Refer to the <<geode-security,documentation>> for more details. TIP: Refer to the <<geode-security,documentation>> for more details.
@@ -521,7 +537,7 @@ TIP: Refer to the <<geode-security,documentation>> for more details.
NOTE: The {spring-boot-data-geode-javadoc}/org/springframework/geode/boot/autoconfigure/SslAutoConfiguration.html[`SslAutoConfiguration`] class NOTE: The {spring-boot-data-geode-javadoc}/org/springframework/geode/boot/autoconfigure/SslAutoConfiguration.html[`SslAutoConfiguration`] class
corresponds to the {spring-data-geode-javadoc}/org/springframework/data/gemfire/config/annotation/EnableSsl.html[`@EnableSsl`] annotation. corresponds to the {spring-data-geode-javadoc}/org/springframework/data/gemfire/config/annotation/EnableSsl.html[`@EnableSsl`] annotation.
Configuring SSL for secure transport (TLS) between your Spring Boot, Apache Geode `ClientCache` application Configuring SSL for secure transport (TLS) between your Spring Boot, {apache-geode-name} `ClientCache` application
and the cluster can be a real problematic task, especially to get correct from the start. So, it is something and the cluster can be a real problematic task, especially to get correct from the start. So, it is something
that SBDG makes simple to do out-of-the-box. that SBDG makes simple to do out-of-the-box.
@@ -539,8 +555,8 @@ TIP: Refer to the <<geode-security-ssl,documentation>> for more details.
NOTE: The {spring-boot-data-geode-javadoc}/org/springframework/geode/boot/autoconfigure/SpringSessionAutoConfiguration.html[`SpringSessionAutoConfiguration`] class NOTE: The {spring-boot-data-geode-javadoc}/org/springframework/geode/boot/autoconfigure/SpringSessionAutoConfiguration.html[`SpringSessionAutoConfiguration`] class
corresponds to the {spring-session-data-gemfire-javadoc}/org/springframework/session/data/gemfire/config/annotation/EnableSsl.html[`@EnableSsl`] annotation. corresponds to the {spring-session-data-gemfire-javadoc}/org/springframework/session/data/gemfire/config/annotation/EnableSsl.html[`@EnableSsl`] annotation.
Configuring Apache Geode or Pivotal GemFire to serve as the (HTTP) Session state caching provider using Spring Session Configuring {apache-geode-name} to serve as the (HTTP) Session state caching provider using Spring Session is as simple
is as simple as including the correct starter, e.g. `spring-geode-starter-session`. as including the correct starter, e.g. `spring-geode-starter-session`.
.Using Spring Session .Using Spring Session
[source,xml] [source,xml]
@@ -553,10 +569,10 @@ is as simple as including the correct starter, e.g. `spring-geode-starter-sessio
</dependency> </dependency>
---- ----
With Spring Session, and specifically Spring Session for Apache Geode or Pivotal GemFire (SSDG), on the classpath of With Spring Session, and specifically Spring Session for {apache-geode-name} (SSDG), on the classpath of your Spring
your Spring Boot, Apache Geode `ClientCache` Web application, you can manage your (HTTP) Session state with either Boot, {apache-geode-name} `ClientCache` Web application, you can manage your (HTTP) Session state with {apache-geode-name}.
Apache Geode or Pivotal GemFire. No further configuration is needed. SBDG _Auto-configuration_ detects Spring Session No further configuration is needed. SBDG _Auto-configuration_ detects Spring Session on the application classpath
on the application classpath and does the right thing. and does the right thing.
TIP: Refer to the <<geode-session,documentation>> for more details. TIP: Refer to the <<geode-session,documentation>> for more details.
@@ -565,7 +581,7 @@ TIP: Refer to the <<geode-session,documentation>> for more details.
The SBDG {spring-boot-data-geode-javadoc}/org/springframework/geode/boot/autoconfigure/RegionTemplateAutoConfiguration.html[`RegionTemplateAutoConfiguration`] class The SBDG {spring-boot-data-geode-javadoc}/org/springframework/geode/boot/autoconfigure/RegionTemplateAutoConfiguration.html[`RegionTemplateAutoConfiguration`] class
has no corresponding SDG _Annotation_. However, the _Auto-configuration_ of a `GemfireTemplate` for every single has no corresponding SDG _Annotation_. However, the _Auto-configuration_ of a `GemfireTemplate` for every single
Apache Geode `Region` defined and declared in your Spring Boot application is supplied by SBDG never-the-less. {apache-geode-name} `Region` defined and declared in your Spring Boot application is supplied by SBDG never-the-less.
For example, if you defined a Region using: For example, if you defined a Region using:

View File

@@ -1,8 +1,9 @@
[[geode-samples-boot-configuration]] [[geode-samples-boot-configuration]]
= Spring Boot Auto-configuration for Apache Geode & Pivotal GemFire = Spring Boot Auto-configuration for Apache Geode & VMware Tanzu GemFire
John Blum John Blum
:apache-geode-version: {apache-geode-doc-version} :geode-version: {apache-geode-doc-version}
:apache-geode-docs: https://geode.apache.org/docs/guide/{apache-geode-version} :geode-docs: https://geode.apache.org/docs/guide/{geode-version}
:geode-name: Apache Geode
:toc: left :toc: left
:toclevels: 2 :toclevels: 2
:stylesdir: ../ :stylesdir: ../
@@ -10,10 +11,10 @@ John Blum
:docinfodir: guides :docinfodir: guides
This guide walks you through building a simple Customer Service, Spring Boot application using Apache Geode This guide walks you through building a simple Customer Service, Spring Boot application using {geode-name}
to manage Customer interactions. You should already be familiar with Spring Boot and Apache Geode. to manage Customer interactions. You should already be familiar with Spring Boot and {geode-name}.
By the end of this lesson, you should have a better understanding of what Spring Boot for Apache Geode's (SBDG) By the end of this lesson, you should have a better understanding of what Spring Boot for {geode-name}'s (SBDG)
_auto-configuration_ support actually does. _auto-configuration_ support actually does.
This guide compliments the link:../index.html#geode-auto-configuration-annotations[Auto-configuration vs. Annotation-based configuration] This guide compliments the link:../index.html#geode-auto-configuration-annotations[Auto-configuration vs. Annotation-based configuration]
@@ -21,11 +22,14 @@ chapter with concrete examples.
Let's begin. Let's begin.
NOTE: This guide builds on the https://www.youtube.com/watch?v=OvY5wzCtOV0[_Simplifying Apache Geode with Spring Data_] NOTE: This guide builds on the https://www.youtube.com/watch?v=OvY5wzCtOV0[_Simplifying {geode-name} with Spring Data_]
presentation by John Blum during the 2017 SpringOne Platform conference. While this example as well as the example presentation by John Blum during the 2017 SpringOne Platform conference. While this example as well as the example
presented in the talk both use Spring Boot, only this example is using Spring Boot for Apache Geode (SBDG). This guide presented in the talk both use Spring Boot, only this example is using Spring Boot for {geode-name} (SBDG). This guide
improves on the example from the presentation by using SBDG. improves on the example from the presentation by using SBDG.
TIP: Refer to the link:../index.html#geode-configuration-auto[Auto-configuration] chapter in the reference documentation
for more information.
[#index-link] [#index-link]
link:../index.html[Index] link:../index.html[Index]
@@ -52,7 +56,7 @@ the details we care about. Lombok is useful for testing or prototyping purposes.
optional and in most production applications, and I would not recommend it. optional and in most production applications, and I would not recommend it.
Additionally, the `Customer` class is annotated with Spring Data Geode's (SDG) `@Region` annotation. `@Region` Additionally, the `Customer` class is annotated with Spring Data Geode's (SDG) `@Region` annotation. `@Region`
is a mapping annotation declaring the Apache Geode cache `Region` in which `Customer` data will be persisted. is a mapping annotation declaring the {geode-name} cache `Region` in which `Customer` data will be persisted.
Finally, the `org.springframework.data.annotation.Id` annotation was used to designate the `Customer.id` field as Finally, the `org.springframework.data.annotation.Id` annotation was used to designate the `Customer.id` field as
the identifier for `Customer` objects. The identifier is the Key used in the Entry stored in the "Customers"`Region`. the identifier for `Customer` objects. The identifier is the Key used in the Entry stored in the "Customers"`Region`.
@@ -64,7 +68,7 @@ class with `@Region`, which we will cover below.
=== `CustomerRepository` interface === `CustomerRepository` interface
Next, we create a _Data Access Object_ (DAO) to persist `Customers` to Apache Geode. We create the DAO Next, we create a _Data Access Object_ (DAO) to persist `Customers` to {geode-name}. We create the DAO
using Spring Data's _Repository_ abstraction: using Spring Data's _Repository_ abstraction:
.CustomerRepository inteface .CustomerRepository inteface
@@ -81,12 +85,12 @@ any query methods you may have explicitly defined on the interface in addition t
the `CrudRepository` interface extension. the `CrudRepository` interface extension.
In addition to the base `CrudRepository` operations, `CustomerRepository` has additionally defined a In addition to the base `CrudRepository` operations, `CustomerRepository` has additionally defined a
`findByNameLike(:String):Customer` query method. The Apache Geode OQL query is derived from the method declaration. `findByNameLike(:String):Customer` query method. The {geode-name} OQL query is derived from the method declaration.
NOTE: Though it is beyond the scope of this document, Spring Data's _Repository_ infrastructure is capable of generating NOTE: Though it is beyond the scope of this document, Spring Data's _Repository_ infrastructure is capable of generating
data store specific queries (e.g. Apache Geode OQL) for _Repository_ interface query method declarations just by data store specific queries (e.g. {geode-name} OQL) for _Repository_ interface query method declarations just by
introspecting the method signature. The query methods must conform to specific conventions. Alternatively, users introspecting the method signature. The query methods must conform to specific conventions. Alternatively, users
may use `@Query` to annotate query methods to specify the raw query instead (i.e. OQL for Apache Geode, SQL for JDBC, may use `@Query` to annotate query methods to specify the raw query instead (i.e. OQL for {geode-name}, SQL for JDBC,
possibly HQL for JPA, and so on). possibly HQL for JPA, and so on).
=== `CustomerServiceApplication` (Spring Boot main class) === `CustomerServiceApplication` (Spring Boot main class)
@@ -129,7 +133,7 @@ Simply execute it with `bootRun`:
`$ gradlew :spring-geode-samples-boot-configuration:bootRun` `$ gradlew :spring-geode-samples-boot-configuration:bootRun`
If you wish to adjust the log levels for either Apache Geode or Spring Boot while running the example, then you can set If you wish to adjust the log levels for either {geode-name} or Spring Boot while running the example, then you can set
the log level for the individual Loggers (i.e. `org.apache` or `org.springframework`) the log level for the individual Loggers (i.e. `org.apache` or `org.springframework`)
in `src/main/resources/logback.xml`: in `src/main/resources/logback.xml`:
@@ -140,7 +144,7 @@ include::{samples-dir}/boot/configuration/src/main/resources/logback.xml[]
---- ----
[[geode-samples-boot-configuration-autoconfig]] [[geode-samples-boot-configuration-autoconfig]]
== Auto-configuration for Apache Geode, Take One == Auto-configuration for {geode-name}, Take One
"_With great power comes great responsibility._" - Uncle Ben "_With great power comes great responsibility._" - Uncle Ben
@@ -149,16 +153,16 @@ in this example.
=== Cache instance === Cache instance
First, in order to put anything into Apache Geode you need a cache instance. A cache instance is also required to First, in order to put anything into {geode-name} you need a cache instance. A cache instance is also required to
create `Regions` which ultimately store the application's data (state). Again, a `Region` is just a Key/Value data create `Regions` which ultimately store the application's data (state). Again, a `Region` is just a Key/Value data
structure, like `java.util.Map`, mapping a Key to a Value, or an Object. A `Region` is actually much more than a structure, like `java.util.Map`, mapping a Key to a Value, or an Object. A `Region` is actually much more than a
simple `Map` since it is distributed. However, since `Region` implements `java.util.Map`, it can be treated as such. simple `Map` since it is distributed. However, since `Region` implements `java.util.Map`, it can be treated as such.
NOTE: A complete discussion of `Region` and it concepts are beyond the scope of this document. You may learn more NOTE: A complete discussion of `Region` and it concepts are beyond the scope of this document. You may learn more
by reading Apache Geode's User Guide on {apache-geode-docs}/developing/region_options/chapter_overview.html[Regions]. by reading {geode-name}'s User Guide on {geode-docs}/developing/region_options/chapter_overview.html[Regions].
SBDG is opinionated and assumes most Apache Geode applications will be client applications in Apache Geode's SBDG is opinionated and assumes most {geode-name} applications will be client applications in {geode-name}'s
{apache-geode-docs}/topologies_and_comm/cs_configuration/chapter_overview.html[client/server topology]. {geode-docs}/topologies_and_comm/cs_configuration/chapter_overview.html[client/server topology].
Therefore, SBDG auto-configures a `ClientCache` instance by default. Therefore, SBDG auto-configures a `ClientCache` instance by default.
The intrinsic `ClientCache` _auto-configuration_ provided by SBDG can be made apparent by disabling it: The intrinsic `ClientCache` _auto-configuration_ provided by SBDG can be made apparent by disabling it:
@@ -331,7 +335,7 @@ class CustomerServiceApplication { }
---- ----
The `basePackageClasses` attribute is an alternative to `basePackages`, and a type-safe way to target the packages The `basePackageClasses` attribute is an alternative to `basePackages`, and a type-safe way to target the packages
(and subpackages) containing the entity classes that your application will persist to Apache Geode. You only need to (and subpackages) containing the entity classes that your application will persist to {geode-name}. You only need to
choose one class from each top-level package for where you want the scan to begin. Spring Data Geode uses this class choose one class from each top-level package for where you want the scan to begin. Spring Data Geode uses this class
to determine the package to begin the scan. 'basePackageClasses` accepts an array of `Class` types so you can specify to determine the package to begin the scan. 'basePackageClasses` accepts an array of `Class` types so you can specify
multiple independent top-level packages. The annotation also includes the ability to filter types. multiple independent top-level packages. The annotation also includes the ability to filter types.
@@ -398,15 +402,15 @@ there are no servers or cluster running yet.
There are several ways in which to start a cluster. For example, you may use Spring to configure and bootstrap There are several ways in which to start a cluster. For example, you may use Spring to configure and bootstrap
the cluster, which has been demonstrated link:../index.html#geode-cluster-configuration-bootstrapping[here]. the cluster, which has been demonstrated link:../index.html#geode-cluster-configuration-bootstrapping[here].
Although, for this example, we are going to use the tools provided with Apache Geode, or Pivotal GemFire, i.e. _Gfsh_ Although, for this example, we are going to use the tools provided with {geode-name}, i.e. _Gfsh_
(GemFire/Geode Shell) for reasons that will become apparent later. (GemFire/Geode Shell) for reasons that will become apparent later.
NOTE: You need to https://geode.apache.org/releases/[download] and https://geode.apache.org/docs/guide/18/prereq_and_install.html[install] NOTE: You need to https://geode.apache.org/releases/[download] and https://geode.apache.org/docs/guide/18/prereq_and_install.html[install]
a full distribution of Apache Geode to make use of the provided tools. After installation, you will need to set a full distribution of {geode-name} to make use of the provided tools. After installation, you will need to set
the `GEODE` (or `GEMFIRE`) environment variable to the location of your installation. Additionally, add `$GEODE/bin` the `GEODE` (or `GEMFIRE`) environment variable to the location of your installation. Additionally, add `$GEODE/bin`
to your system `$PATH`. to your system `$PATH`.
Once Apache Geode has been successfully installed, you can open a command prompt (terminal) and do: Once {geode-name} has been successfully installed, you can open a command prompt (terminal) and do:
.Running Gfsh .Running Gfsh
[source,txt] [source,txt]
@@ -479,7 +483,7 @@ NOTE: You will need to change the path to the `spring-boot-data-geode/samples/bo
`run --file=...` _Gfsh_ command above based on where you git cloned the `spring-boot-data-geode` project `run --file=...` _Gfsh_ command above based on where you git cloned the `spring-boot-data-geode` project
to your computer. to your computer.
Now, our simple cluster with an Apache Geode Locator and (Cache) Server is running. We can verify by listing Now, our simple cluster with an {geode-name} Locator and (Cache) Server is running. We can verify by listing
and describing the members: and describing the members:
.List and Describe Members .List and Describe Members
@@ -589,7 +593,7 @@ gfsh>create region --name=Customers --type=PARTITION
But, what if you have hundreds of application domain objects each requiring a Region for persistence? It is not an But, what if you have hundreds of application domain objects each requiring a Region for persistence? It is not an
unusual or unreasonable requirement in any practical enterprise scale application. unusual or unreasonable requirement in any practical enterprise scale application.
While it is not a "convention" in Spring Boot for Apache Geode (SBDG), Spring Data for Apache Geode (SDG) comes to While it is not a "convention" in Spring Boot for {geode-name} (SBDG), Spring Data for {geode-name} (SDG) comes to
our rescue. We simply only need to enable cluster configuration from the client: our rescue. We simply only need to enable cluster configuration from the client:
.Enable Cluster Configuration .Enable Cluster Configuration
@@ -689,7 +693,7 @@ Jon Doe
That was easy! That was easy!
[[geode-samples-boot-configuration-clientserver-autoconfig]] [[geode-samples-boot-configuration-clientserver-autoconfig]]
== Auto-configuration for Apache Geode, Take Two == Auto-configuration for {geode-name}, Take Two
What may not be apparent in this example up to this point is how the data got from the client to the server. Certainly, What may not be apparent in this example up to this point is how the data got from the client to the server. Certainly,
our client did send `Jon Doe` to the server, but our `Customer` class is not `java.io.Serializable`. So, how was an our client did send `Jon Doe` to the server, but our `Customer` class is not `java.io.Serializable`. So, how was an
@@ -724,16 +728,16 @@ Result : false
So, how was the data sent then? How were we able to access the data stored in the server(s) on the cluster with the So, how was the data sent then? How were we able to access the data stored in the server(s) on the cluster with the
OQL query `SELECT customer.name FROM /Customers customer` as seen above? OQL query `SELECT customer.name FROM /Customers customer` as seen above?
Well, Apache Geode and Pivotal GemFire provide 2 proprietary serialization formats in addition to _Java Serialization_: Well, {geode-name} provides 2 proprietary serialization formats in addition to _Java Serialization_:
{apache-geode-docs}/developing/data_serialization/gemfire_data_serialization.html[Data Serialization] {geode-docs}/developing/data_serialization/gemfire_data_serialization.html[Data Serialization]
and {apache-geode-docs}/developing/data_serialization/gemfire_pdx_serialization.html[PDX], or _Portable Data Exchange_. and {geode-docs}/developing/data_serialization/gemfire_pdx_serialization.html[PDX], or _Portable Data Exchange_.
While _Data Serialization_ is more efficient, PDX is more flexible (i.e. "portable"). PDX enables data to be queried While _Data Serialization_ is more efficient, PDX is more flexible (i.e. "portable"). PDX enables data to be queried
in serialized form and is the format used to support both Java and Native Clients (C++, C#) simultaneously. Therefore, in serialized form and is the format used to support both Java and Native Clients (C++, C#) simultaneously. Therefore,
PDX is auto-configured in Spring Boot Data Geode (SBDG) by default. PDX is auto-configured in Spring Boot Data Geode (SBDG) by default.
This is convenient since you may not want to implement `java.io.Serializable` for all your application domain model This is convenient since you may not want to implement `java.io.Serializable` for all your application domain model
types that you store in Apache Geode. In other cases, you may not even have control over the types referred to by your types that you store in {geode-name}. In other cases, you may not even have control over the types referred to by your
application domain model types to make them `Serializable`, such as when using a 3rd party library. application domain model types to make them `Serializable`, such as when using a 3rd party library.
So, SBDG auto-configures PDX and uses Spring Data Geode's `MappingPdxSerializer` as the `PdxSerializer` to de/serialize So, SBDG auto-configures PDX and uses Spring Data Geode's `MappingPdxSerializer` as the `PdxSerializer` to de/serialize
@@ -872,14 +876,14 @@ see how SBDG helps us properly configure these concerns, easily and reliably.
First, we must secure the cluster (i.e. the Locator and Server). First, we must secure the cluster (i.e. the Locator and Server).
In a nutshell, when using the Apache Geode API (with no help from Spring), you must do the following: In a nutshell, when using the {geode-name} API (with no help from Spring), you must do the following:
1. (Auth) Implement the `org.apache.geode.security.SecurityManager` interface. 1. (Auth) Implement the `org.apache.geode.security.SecurityManager` interface.
2. (Auth) Configure your custom `SecurityManager` using the GemFire/Geode `security-manager` property in `gemfire.properties`. 2. (Auth) Configure your custom `SecurityManager` using the GemFire/Geode `security-manager` property in `gemfire.properties`.
3. (Auth) Either create a `gfsecurity.properties` file and set the `security-username` and `security-password` properties, or... 3. (Auth) Either create a `gfsecurity.properties` file and set the `security-username` and `security-password` properties, or...
4. (Auth) Implement the `org.apache.geode.security.AuthInitialize` interface and set the `security-peer-auth-init` property 4. (Auth) Implement the `org.apache.geode.security.AuthInitialize` interface and set the `security-peer-auth-init` property
in `gemfire.properties` as described in {apache-geode-docs}/managing/security/implementing_authentication.html[Implementing Authentication] in `gemfire.properties` as described in {geode-docs}/managing/security/implementing_authentication.html[Implementing Authentication]
of the Apache Geode User Guide. of the {geode-name} User Guide.
5. (SSL) Then, you must create Java KeyStore (jks) files for both the keystore and truststore used to configure 5. (SSL) Then, you must create Java KeyStore (jks) files for both the keystore and truststore used to configure
the SSL Socket. the SSL Socket.
6. (SSL) Configure the Java KeyStores using the GemFire/Geode `ssl-keystore` and `ssl-truststore` properties 6. (SSL) Configure the Java KeyStores using the GemFire/Geode `ssl-keystore` and `ssl-truststore` properties
@@ -958,8 +962,8 @@ include::{samples-dir}/boot/configuration/src/main/resources/application-securit
---- ----
The act of setting a username and password triggers the client Security _auto-configuration_ provided by SBDG. There are The act of setting a username and password triggers the client Security _auto-configuration_ provided by SBDG. There are
many steps to configuring client Security in Apache Geode/Pivotal GemFire properly, as there was on the server. All you many steps to configuring client Security in {geode-name} properly, as there was on the server. All you need to
need to worry about is supplying the credentials. Easy! worry about is supplying the credentials. Easy!
To include the `application-security.properties`, simply enable the Spring "security" profile in your run configuration To include the `application-security.properties`, simply enable the Spring "security" profile in your run configuration
when running the `CustomerServiceApplication` class: when running the `CustomerServiceApplication` class:
@@ -1144,11 +1148,10 @@ and application requirements grow.
== Conclusion == Conclusion
Hopefully this guide has now given you a better understanding of what the _auto-configuration_ support provided by Hopefully this guide has now given you a better understanding of what the _auto-configuration_ support provided by
Spring Boot for Apache Geode/Pivotal GemFire (SBDG) is giving you when developing Apache Geode or Pivotal GemFire Spring Boot for {geode-name} (SBDG) is giving you when developing {geode-name} applications with Spring.
applications with Spring.
In this guide, we have seen that SBDG provides _auto-configuration_ support for the following In this guide, we have seen that SBDG provides _auto-configuration_ support for the following
Spring Data for Apache Geode's (SDG) annotations: Spring Data for {geode-name}'s (SDG) annotations:
* `@ClientCacheApplication` * `@ClientCacheApplication`
* `@EnableGemfireRepositories` * `@EnableGemfireRepositories`