Document the SBDG configuration processor and associated, provided (auto-configured) @ConfigurationProperties classes.

Resolves gh-14.

spring-geode-docs/src/docs/asciidoc/configuration.adoc

@@ -0,0 +1,140 @@
+[[geode-configuration]]
+== Externalized Configuration
+
+Like Spring Boot itself (see {spring-boot-docs-html}/boot-features-external-config.html[here]),
+Spring Boot for Apache Geode and Pivotal GemFire (SBDG) supports externalized configuration.
+
+By externalized configuration, we mean configuration meta-data stored in a Spring Boot
+{spring-boot-docs-html}/boot-features-external-config.html#boot-features-external-config-application-property-files[`application.properties` file],
+for instance.  Properties can even be delineated by concern, broken out into individual properties files, that are
+perhaps only enabled by a specific {spring-boot-docs-html}/boot-features-external-config.html#boot-features-external-config-profile-specific-properties[Profile].
+
+There are many other powerful things you can do, such as use {spring-boot-docs-html}/boot-features-external-config.html#boot-features-external-config-placeholders-in-properties[placeholders]
+in properties, {spring-boot-docs-html}/boot-features-external-config.html#boot-features-encrypting-properties[encrypt]
+properties, and so on.  What we are particularly interested in, in this section, is
+{spring-boot-docs-html}/boot-features-external-config.html#boot-features-external-config-typesafe-configuration-properties[type-safety].
+
+Like Spring Boot, Spring Boot for Apache Geode/Pivotal GemFire provides a hierarchy of classes used to capture
+the configuration of several Apache Geode or Pivotal GemFire features in an associated `@ConfigurationProperties`
+annotated class.  Again, the configuration is specified as well-known, documented properties in 1 or more Spring Boot
+`application.properties` files.
+
+For instance, I may have configured my Spring Boot, `ClientCache` application as follows:
+
+.Spring Boot `application.properties` containing Spring Data properties for Apache Geode /  Pivotal GemFire
+[source,properties]
+----
+# Spring Boot application.properties used to configure Apache Geode
+
+spring.data.gemfire.name=MySpringBootApacheGeodeApplication
+
+# Configure general cache properties
+spring.data.gemfire.cache.copy-on-read=true
+spring.data.gemfire.cache.log-level=debug
+
+# Configure ClientCache specific properties
+spring.data.gemfire.cache.client.durable-client-id=123
+spring.data.gemfire.cache.client.keep-alive=true
+
+# Configure a log file
+spring.data.gemfire.logging.log-file=/path/to/geode.log
+
+# Configure the client's connection Pool to the servers in the cluster
+spring.data.gemfire.pool.locators=10.105.120.16[11235],boombox[10334]
+
+----
+
+There are many other properties a user may use to externalize the configuration of their Spring Boot,
+Apache Geode application.  You may refer to the Spring Data for Apache Geode (SDG) configuration annotations
+{spring-data-geode-javadoc}/org/springframework/data/gemfire/config/annotation/package-frame.html[Javadoc]
+for specific configuration properties as needed.  Specifically, review the "enabling" annotation attributes.
+
+There may be cases where you require access to the configuration meta-data (specified in properties)
+in your Spring Boot applications themselves, perhaps to further inspect or act on a particular configuration setting.
+
+Of course, you can access any property using Spring's {spring-framework-javadoc}/org/springframework/core/env/Environment.html[`Environment`] abstraction,
+like so:
+
+.Using the Spring `Enviornment
+[source,java]
+----
+  boolean copyOnRead = environment.getProperty("spring.data.gemfire.cache.copy-on-read", Boolean.TYPE, false);
+----
+
+While using the `Environment` is a nice approach, you might need access to additional properties or want to access
+the property values in a type-safe manner. Therefore, it is now possible, thanks to SBDG's auto-configured
+configuration processor, to access the configuration meta-data using provided `@ConfigurationProperties` classes.
+
+Following on to our example above, I can now do the following:
+
+.Using `GemFireProperties`
+[source,java]
+----
+
+@Component
+class MyApplicationComponent {
+
+  @Autowired
+  private GemFireProperties gemfireProperties;
+
+  public void someMethodUsingGemFireProperties() {
+
+    boolean copyOnRead = this.gemfireProperties.getCache().isCopyOnRead();
+
+    // do something with `copyOnRead`
+  }
+
+  ...
+}
+----
+
+Given a handle to {spring-boot-data-geode-javadoc}/org/springframework/geode/boot/autoconfigure/configuration/GemFireProperties.html[`GemFireProperties`],
+you can access any of the configuration properties used to configure either Apache Geode or Pivotal GemFire in
+a Spring context. You simply only need to autowire an instance of `GemFireProperties` into your application component.
+
+A complete reference to the SBDG provided `@ConfigurationProperties` classes and supporting classes is available
+{spring-boot-data-geode-javadoc}/org/springframework/geode/boot/autoconfigure/configuration/package-frame.html[here].
+
+[[geode-configuration-session]]
+=== Externalized Configuration of Spring Session
+
+The same capability applies to accessing the externalized configuration of Spring Session when using either
+Apache Geode or Pivotal GemFire as your (HTTP) Session state caching provider.
+
+In this case, you simply only need to acquire a handle to an instance of the
+{spring-boot-data-geode-javadoc}/org/springframework/geode/boot/autoconfigure/configuration/SpringSessionProperties.html[`SpringSessionProperties`]
+class.
+
+As before, you would specify Spring Session for Apache Geode (SSDG) properties as follows:
+
+.Spring Boot `application.properties` for Spring Session using Apache Geode as the (HTTP) Session state caching provider
+[source,properties]
+----
+# Spring Boot application.properties used to configure Apache Geode as a Session state caching provider in Spring Session
+
+spring.session.data.gemfire.session.expiration.max-inactive-interval-seconds=300
+spring.session.data.gemfire.session.region.name=UserSessions
+
+----
+
+Then, in your application:
+
+.Using `SpringSessionProperties`
+[source,java]
+----
+@Component
+class MyApplicationComponent {
+
+  @Autowired
+  private SpringSessionProperties springSessionProperties;
+
+  public void someMethodUsingSpringSessionProperties() {
+
+    String sessionRegionName = this.springSessionProperties.getSession().getRegion().getName();
+
+    // do something with `sessionRegionName`
+  }
+
+  ...
+}
+----

spring-geode-docs/src/docs/asciidoc/index.adoc

@@ -20,6 +20,7 @@ John Blum
 :spring-boot-docs: https://docs.spring.io/spring-boot/docs/current/reference
 :spring-boot-docs-html: {spring-boot-docs}/html
 :spring-boot-javadoc: https://docs.spring.io/spring-boot/docs/current/api
+:spring-boot-data-geode-javadoc: https://docs.spring.io/autorepo/docs/spring-boot-data-geode-build/1.0.0.BUILD-SNAPSHOT/api/
 :spring-data-commons-docs: https://docs.spring.io/spring-data/commons/docs/current/reference
 :spring-data-commons-docs-html: {spring-data-commons-docs}/html
 :spring-data-commons-javadoc: https://docs.spring.io/spring-data/commons/docs/current/api
@@ -206,6 +207,7 @@ repositories {
 endif::[]
 
 include::clientcache-applications.adoc[]
+include::configuration.adoc[]
 include::caching.adoc[]
 include::repositories.adoc[]
 include::functions.adoc[]