Spring/spring-boot-data-geode
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

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

Browse Source
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
Download Patch File Download Diff File Expand all files Collapse all files

116
spring-geode-docs/src/docs/asciidoc/_includes/configuration-auto.adoc
View File

@@ -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`)
@@ -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
@@ -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
@@ -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_.
@@ -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,
@@ -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
@@ -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
@@ -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
@@ -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.
@@ -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
@@ -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
@@ -263,7 +279,7 @@ class CustomerService {
@Caching("CustomersByName")
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
{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) {
...
// ...
}
}
----
@@ -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);
...
// ...
}
}
----
@@ -400,9 +416,9 @@ class CustomerService {
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.
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.
@@ -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
@@ -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
@@ -477,7 +493,7 @@ class Customer {
@Indexed
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
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
@@ -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.
@@ -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.
@@ -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]
@@ -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.
@@ -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:

79
spring-geode-docs/src/docs/asciidoc/guides/boot-configuration.adoc
View File

@@ -1,8 +1,9 @@
[[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
:apache-geode-version: {apache-geode-doc-version}
:apache-geode-docs: https://geode.apache.org/docs/guide/{apache-geode-version}
:geode-version: {apache-geode-doc-version}
:geode-docs: https://geode.apache.org/docs/guide/{geode-version}
:geode-name: Apache Geode
:toc: left
:toclevels: 2
:stylesdir: ../
@@ -10,10 +11,10 @@ John Blum
:docinfodir: guides
This guide walks you through building a simple Customer Service, Spring Boot application using Apache Geode
to manage Customer interactions. You should already be familiar with Spring Boot and 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 {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.
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.
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
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.
TIP: Refer to the link:../index.html#geode-configuration-auto[Auto-configuration] chapter in the reference documentation
for more information.
[#index-link]
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.
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
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
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:
.CustomerRepository inteface
@@ -81,12 +85,12 @@ any query methods you may have explicitly defined on the interface in addition t
the `CrudRepository` interface extension.
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
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
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).
=== `CustomerServiceApplication` (Spring Boot main class)
@@ -129,7 +133,7 @@ Simply execute it with `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`)
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]]
== Auto-configuration for Apache Geode, Take One
== Auto-configuration for {geode-name}, Take One
"_With great power comes great responsibility._" - Uncle Ben
@@ -149,16 +153,16 @@ in this example.
=== 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
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.
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
{apache-geode-docs}/topologies_and_comm/cs_configuration/chapter_overview.html[client/server topology].
SBDG is opinionated and assumes most {geode-name} applications will be client applications in {geode-name}'s
{geode-docs}/topologies_and_comm/cs_configuration/chapter_overview.html[client/server topology].
Therefore, SBDG auto-configures a `ClientCache` instance by default.
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
(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
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.
@@ -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
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.
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`
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
[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
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:
.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
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:
.Enable Cluster Configuration
@@ -689,7 +693,7 @@ Jon Doe
That was easy!
[[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,
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
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_:
{apache-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_.
Well, {geode-name} provides 2 proprietary serialization formats in addition to _Java Serialization_:
{geode-docs}/developing/data_serialization/gemfire_data_serialization.html[Data Serialization]
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
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.
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.
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).
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.
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...
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]
of the Apache Geode User Guide.
in `gemfire.properties` as described in {geode-docs}/managing/security/implementing_authentication.html[Implementing Authentication]
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
the SSL Socket.
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
many steps to configuring client Security in Apache Geode/Pivotal GemFire properly, as there was on the server. All you
need to worry about is supplying the credentials. Easy!
many steps to configuring client Security in {geode-name} properly, as there was on the server. All you need to
worry about is supplying the credentials. Easy!
To include the `application-security.properties`, simply enable the Spring "security" profile in your run configuration
when running the `CustomerServiceApplication` class:
@@ -1144,11 +1148,10 @@ and application requirements grow.
== Conclusion
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
applications with Spring.
Spring Boot for {geode-name} (SBDG) is giving you when developing {geode-name} applications with Spring.
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`
* `@EnableGemfireRepositories`