diff --git a/spring-geode-docs/src/docs/asciidoc/configuration.adoc b/spring-geode-docs/src/docs/asciidoc/configuration.adoc new file mode 100644 index 00000000..222e1422 --- /dev/null +++ b/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` + } + + ... +} +---- diff --git a/spring-geode-docs/src/docs/asciidoc/index.adoc b/spring-geode-docs/src/docs/asciidoc/index.adoc index 7ee0130a..1dda6845 100644 --- a/spring-geode-docs/src/docs/asciidoc/index.adoc +++ b/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[]