Skip to content

Commit

Permalink
Cross-reference the reference documentation and sample guide for Spri…
Browse files Browse the repository at this point in the history 
…ng Boot Auto-configuration.
  • Loading branch information
@jxblum
jxblum committed Sep 18, 2020
1 parent ea04817 commit 912e7aa
Show file tree
Hide file tree
Showing 2 changed files with 107 additions and 88 deletions.
116 changes: 66 additions & 50 deletions spring-geode-docs/src/docs/asciidoc/_includes/configuration-auto.adoc
View file
Original file line number Diff line number Diff line change
@@ -1,9 +1,9 @@
[[geode-configuration-auto]]
== Auto-configuration

The following Spring Framework, Spring Data for Apache Geode & Pivotal GemFire (SDG) and Spring Session for Apache Geode
& Pivotal GemFire (SSDG) _Annotations_ are implicitly declared by Spring Boot for Apache Geode & Pivotal GemFire's
(SBDG) _Auto-configuration_.
The following Spring Framework, Spring Data for {apache-geode-name} & {pivotal-gemfire-name} (SDG) and Spring Session
for {apache-geode-name} and {pivotal-gemfire-name} (SSDG) _Annotations_ are implicitly declared by Spring Boot for
{apache-geode-name} & {pivotal-gemfire-name}'s (SBDG) _Auto-configuration_.

* `@ClientCacheApplication`
* `@EnableGemfireCaching` (or alternatively, Spring Framework's `@EnableCaching`)
Expand All @@ -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
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].

TIP: You should review the chapter in Spring Data for Apache Geode and Pivotal GemFire's (SDG) Reference Guide on
{spring-data-geode-docs-html}/#bootstrap-annotation-config[Annotation-based Configuration]. For a quick reference,
TIP: You should review the chapter in Spring Data for {apache-geode-name} and {pivotal-gemfire-name}'s (SDG) Reference Documentation
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].

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]]
=== Customizing Auto-configuration

Expand All @@ -49,7 +53,9 @@ For example, to set the (client or peer) member's name, you can use the `@UseMem
----
@SpringBootApplication
@UseMemberName("MyMemberName")
class SpringBootClientCacheApplication { ... }
class SpringBootClientCacheApplication {
///...
}
----

Alternatively, you could set the `spring.application.name` or the `spring.data.gemfire.name` property in Spring Boot
Expand Down Expand Up @@ -104,7 +110,9 @@ then you can declare your intent in the `@SpringBootApplication` annotation, lik
@SpringBootApplication(
exclude = { DataSourceAutoConfiguration.class, PdxAutoConfiguration.class }
)
class SpringBootClientCacheApplication { ... }
class SpringBootClientCacheApplication {
// ...
}
----

WARNING: Make sure you understand what you are doing when you are "disabling" _Auto-configuration_.
Expand All @@ -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
your `@SpringBootApplication` class with your intent.

For example, say you want to configure and bootstrap an Apache Geode or Pivotal GemFire `CacheServer` application
(a peer; not a client), then you would:
For example, say you want to configure and bootstrap an {apache-geode-name} `CacheServer` application (a peer;
not a client), then you would:

.Overriding the default `ClientCache` _Auto-Configuration_ by configuring & bootstrapping a `CacheServer` application
[source,java]
----
@SpringBootApplication
@CacheServerApplication
class SpringBootCacheServerApplication { ... }
class SpringBootCacheServerApplication {
// ...
}
----

Even when you explicitly declare the `@ClientCacheApplication` annotation on your `@SpringBootApplication` class,
Expand All @@ -136,7 +146,9 @@ like so:
----
@SpringBootApplication
@ClientCacheApplication
class SpringBootClientCacheApplication { ... }
class SpringBootClientCacheApplication {
// ...
}
----

You are overriding SBDG's _Auto-configuration_ of the `ClientCache` instance. As a result, you now have also implicitly
Expand Down Expand Up @@ -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
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
or Pivotal GemFire <<geode-clientcache-applications,client applications>> using Spring Boot.
SBDG <<getting-started,starts>> with the opinion that application developers will primarily be building {apache-geode-name}
<<geode-clientcache-applications,client applications>> using Spring Boot.

Technically, this means building Spring Boot applications with either an Apache Geode or Pivotal GemFire `ClientCache`
instance connected to a dedicated cluster of Apache Geode or Pivotal GemFire servers that manage the data as part of a
Technically, this means building Spring Boot applications with an {apache-geode-name} `ClientCache` instance connected
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.

By way of example, this means you *do not* need to explicitly declare and annotate your `@SpringBootApplication` class
Expand All @@ -182,7 +194,9 @@ with SDG's `@ClientCacheApplication` annotation, like so:
----
@SpringBootApplication
@ClientCacheApplication
class SpringBootClientCacheApplication { ... }
class SpringBootClientCacheApplication {
// ...
}
----

This is because SBDG's provided _Auto-configuration_ class is already meta-annotated with SDG's
Expand All @@ -192,10 +206,12 @@ This is because SBDG's provided _Auto-configuration_ class is already meta-annot
[source,java]
----
@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],
and {spring-data-geode-docs-html}/#bootstrap-annotation-config-client-server-applications[client/server applications]
in particular.
Expand All @@ -206,7 +222,7 @@ in particular.
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.

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:

.Configuring caching using the Spring Framework
Expand All @@ -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:

.Configuring caching using Spring Data Geode
Expand Down Expand Up @@ -263,7 +279,7 @@ class CustomerService {
@Caching("CustomersByName")
Customer findBy(String name) {
...
// ...
}
}
----
Expand All @@ -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
{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
Pivotal GemFire's case, the method would be an implementation of
annotation to register a CQ and start receiving events. The method acts as a `CqEvent` handler, or in {apache-geode-name}'s
case, the method would be an implementation of
{apache-geode-javadoc}/org/apache/geode/cache/query/CqListener.html[`CqListener`].

.Declare application CQs
[source,java]
----
@Component
class MyCustomerApplicationContinuousQueries
class MyCustomerApplicationContinuousQueries {
@ContinuousQuery("SELECT customer.* FROM /Customers customers"
+ " WHERE customer.getSentiment().name().equalsIgnoreCase('UNHAPPY')")
public void handleUnhappyCustomers(CqEvent event) {
...
// ...
}
}
----
Expand Down Expand Up @@ -335,18 +351,18 @@ Then you can inject the Function execution into any application component and us
package example.app.service;
@Service
interface CustomerService {
class CustomerService {
@Autowired
private MyCustomerapplicationFunctions customerFunctions;
public void analyzeCustomerSentiment(Customer customer) {
void analyzeCustomerSentiment(Customer customer) {
...
// ...
this.customerFunctions.applyCredit(customer);
...
// ...
}
}
----
Expand Down Expand Up @@ -400,9 +416,9 @@ class CustomerService {
public void processCustomersWithSentiment(Sentiment sentiment) {
this.repository.findBySentimentEqualTo(sentiment).forEach(customer -> { ... });
this.repository.findBySentimentEqualTo(sentiment).forEach(customer -> { /* ... */ });
...
// ...
}
}
----
Expand All @@ -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.

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 default log-level, "_config_".
the event occurred. As such, SBDG auto-configures logging for {apache-geode-name} by default, using the default
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
`application.properties`:

.Change the log-level for Apache Geode
.Change the log-level for {apache-geode-name}
[source,txt]
----
# Spring Boot application.properites.
Expand All @@ -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
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
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
Expand All @@ -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
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.

However, you don't have to figure out how to configure PDX to identify the application class types that will need to be
Expand All @@ -477,7 +493,7 @@ class Customer {
@Indexed
private String name;
...
// ...
}
----

Expand All @@ -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
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
Apache Geode or Pivotal GemFire servers is as simple as setting a _username_ and _password_ in Spring Boot
Configuring your Spring Boot, {apache-geode-name} `ClientCache` application to properly authenticate with a cluster of
secure{apache-geode-name} servers is as simple as setting a _username_ and _password_ in Spring Boot
`application.properties`:

.Supplying Authentication Credentials
Expand All @@ -510,7 +526,7 @@ NOTE: Authentication is even easier to configure in a managed environment like P
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].
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.

TIP: Refer to the <<geode-security,documentation>> for more details.
Expand All @@ -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
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
that SBDG makes simple to do out-of-the-box.

Expand All @@ -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
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
is as simple as including the correct starter, e.g. `spring-geode-starter-session`.
Configuring {apache-geode-name} to serve as the (HTTP) Session state caching provider using Spring Session is as simple
as including the correct starter, e.g. `spring-geode-starter-session`.

.Using Spring Session
[source,xml]
Expand All @@ -553,10 +569,10 @@ is as simple as including the correct starter, e.g. `spring-geode-starter-sessio
</dependency>
----

With Spring Session, and specifically Spring Session for Apache Geode or Pivotal GemFire (SSDG), on the classpath of
your Spring Boot, Apache Geode `ClientCache` Web application, you can manage your (HTTP) Session state with either
Apache Geode or Pivotal GemFire. No further configuration is needed. SBDG _Auto-configuration_ detects Spring Session
on the application classpath and does the right thing.
With Spring Session, and specifically Spring Session for {apache-geode-name} (SSDG), on the classpath of your Spring
Boot, {apache-geode-name} `ClientCache` Web application, you can manage your (HTTP) Session state with {apache-geode-name}.
No further configuration is needed. SBDG _Auto-configuration_ detects Spring Session on the application classpath
and does the right thing.

TIP: Refer to the <<geode-session,documentation>> for more details.

Expand All @@ -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
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:

Expand Down
Loading

0 comments on commit 912e7aa

Please sign in to comment.