From c6c46ee70e14efea457802af5cdef3eaf66762fd Mon Sep 17 00:00:00 2001 From: John Blum Date: Thu, 3 Sep 2020 18:40:04 -0700 Subject: [PATCH] Cross-reference the reference documentation and sample guide for HTTP Session Caching with Spring Session using Apache Geode. --- .../src/docs/asciidoc/_includes/session.adoc | 97 ++++++++++--------- .../asciidoc/guides/caching-http-session.adoc | 28 +++--- 2 files changed, 66 insertions(+), 59 deletions(-) diff --git a/spring-geode-docs/src/docs/asciidoc/_includes/session.adoc b/spring-geode-docs/src/docs/asciidoc/_includes/session.adoc index 58afca65..251c0c57 100644 --- a/spring-geode-docs/src/docs/asciidoc/_includes/session.adoc +++ b/spring-geode-docs/src/docs/asciidoc/_includes/session.adoc @@ -1,12 +1,12 @@ [[geode-session]] == Spring Session -This section covers auto-configuration of Spring Session using either Apache Geode or Pivotal GemFire to manage -(HTTP) Session state in a reliable (consistent), highly-available (replicated) and clustered manner. +This chapter covers auto-configuration of Spring Session using either {apache-geode-name} or {pivotal-gemfire-name} +to manage (HTTP) Session state in a reliable (consistent), highly-available (replicated) and clustered manner. {spring-session-website}[Spring Session] provides an API and several implementations for managing a user's session information. It has the ability to replace the `javax.servlet.http.HttpSession` in an application container neutral -way along with proving Session IDs in HTTP headers to work with RESTful APIs. +way along with providing Session IDs in HTTP headers to work with RESTful APIs. Furthermore, Spring Session provides the ability to keep the HttpSession alive even when working with WebSockets and reactive Spring WebFlux WebSessions. @@ -14,19 +14,20 @@ and reactive Spring WebFlux WebSessions. A full discussion of Spring Session is beyond the scope of this document, and the reader is encouraged to learn more by reading the {spring-session-docs}[docs] and reviewing the {spring-session-docs}/#samples[samples]. -Of course, Spring Boot for Apache Geode & Pivotal GemFire provides auto-configuration support to configure -either Apache Geode or Pivotal GemFire as the user's session information management provider and store when -{spring-session-data-gemfire-website}[Spring Session for Apache Geode or Pivotal GemFire] is on -your Spring Boot application's classpath. +Of course, Spring Boot for {apache-geode-name} provides auto-configuration support to configure {apache-geode-name} +as the user's session information management provider and store when {spring-session-data-gemfire-website}[Spring Session for {apache-geode-name}] +is on your Spring Boot application's classpath. -TIP: You can learn more about Spring Session for Apache Geode & Pivotal GemFire in -the {spring-session-data-gemfire-docs}[docs]. +TIP: You can learn more about Spring Session for {apache-geode-name} in the {spring-session-data-gemfire-docs}[docs]. + +TIP: Refer to the corresponding Sample link:guides/caching-http-session.html.html[Guide] and {github-samples-url}/caching/http-session[Code] +to see Spring Session for {apache-geode-name} in action! [[geode-session-configuration]] === Configuration -There is nothing special that you need to do in order to use either Apache Geode or Pivotal GemFire as a Spring Session -provider, managing the (HTTP) Session state of your Spring Boot application. +There is nothing special that you need to do in order to use {apache-geode-name} as a Spring Session provider, +managing the (HTTP) Session state of your Spring Boot application. Simply include the appropriate Spring Session dependency on your Spring Boot application's classpath, for example: @@ -55,9 +56,9 @@ Maven POM or Gradle build file: ---- -TIP: You may replace Apache Geode with Pivotal Cloud Cache or Pivotal GemFire by changing the artifact ID +TIP: You may replace {apache-geode-name} with Pivotal Cloud Cache or {pivotal-gemfire-name} by changing the artifact ID from `org.springframework.session:spring-session-data-geode` to `org.springframework.session:spring-session-data-gemfire`. -Alternatively, you may replace Apache Geode with Pivotal Cloud Cache (PCC) or Pivotal GemFire by changing the artifact +Alternatively, you may replace {apache-geode-name} with Pivotal Cloud Cache (PCC) or {pivotal-gemfire-name} by changing the artifact ID from `spring-geode-starter-session` to `spring-gemfire-starter-session`. The version number is the same. After declaring the required Spring Session dependency, then begin your Spring Boot application as you normally would: @@ -72,7 +73,7 @@ public class MySpringBootApplication { SpringApplication.run(MySpringBootApplication.class, args); } - ... + // ... } ---- @@ -87,24 +88,23 @@ as needed by your application: @Controller class MyApplicationController { - @GetRequest(...) + @GetRequest("...") public String processGet(HttpSession session) { // interact with HttpSession } } ---- -The `HttpSession` is replaced by a Spring managed `Session` that will be stored in either Apache Geode -or Pivotal GemFire, or even Pivotal Cloud Cache. +The `HttpSession` is replaced by a Spring managed `Session` that will be stored in {apache-geode-name}. [[geode-session-configuration-custom]] === Custom Configuration -By default, Spring Boot for Apache Geode & Pivotal GemFire (SBDG) applies reasonable and sensible defaults -when configuring Apache Geode or Pivotal GemFire as the provider in Spring Session. +By default, Spring Boot for {apache-geode-name} (SBDG) applies reasonable and sensible defaults when configuring +{apache-geode-name} as the provider in Spring Session. So, for instance, by default, SBDG set the session expiration timeout to 30 minutes. It also uses a -`ClientRegionShortcut.PROXY` as the client Region data management policy for the Apache Geode/Pivotal GemFire +`ClientRegionShortcut.PROXY` as the client Region data management policy for the {apache-geode-name} Region managing the (HTTP) Session state when the Spring Boot application is using a `ClientCache`, which it does by <>. @@ -113,17 +113,17 @@ However, what if the defaults are not sufficient for your application requiremen [[geode-session-configuration-custom-properties]] ==== Custom Configuration using Properties -Spring Session for Apache Geode/Pivotal GemFire publishes +Spring Session for {apache-geode-name} publishes {spring-session-data-gemfire-docs}/#httpsession-gemfire-configuration-properties[well-known configuration properties] -for each of the various Spring Session configuration options when using Apache Geode or Pivotal GemFire -as the (HTTP) Session state management provider. +for each of the various Spring Session configuration options when using {apache-geode-name} as the (HTTP) Session state +management provider. You may specify any of these properties in a Spring Boot `application.properties` file to adjust Spring Session's -configuration when using Apache Geode or Pivotal GemFire. +configuration when using {apache-geode-name}. -In addition to the properties provided in and by Spring Session for Apache Geode/Pivotal GemFire, -Spring Boot for Apache Geode/Pivotal GemFire also recognizes and respects the `spring.session.timeout` property -as well as the `server.servlet.session.timeout` property as discussed {spring-boot-docs-html}/boot-features-session.html[here]. +In addition to the properties provided in and by Spring Session for {apache-geode-name}, Spring Boot for {apache-geode-name} +also recognizes and respects the `spring.session.timeout` property as well as the `server.servlet.session.timeout` +property as discussed {spring-boot-docs-html}/boot-features-session.html[here]. TIP: `spring.session.data.gemfire.session.expiration.max-inactive-interval-seconds` takes precedence over `spring.session.timeout`, which takes precedence over `server.servlet.session.timeout`, when any combination @@ -132,13 +132,13 @@ of these properties have been simultaneously configured in the Spring `Environme [[geode-session-configuration-custom-configurer]] ==== Custom Configuration using a Configurer -Spring Session for Apache Geode/Pivotal GemFire also provides the +Spring Session for {apache-geode-name} also provides the {spring-session-data-gemfire-javadoc}/org/springframework/session/data/gemfire/config/annotation/web/http/support/SpringSessionGemFireConfigurer.html[`SpringSessionGemFireConfigurer`] callback interface, which can be declared in your Spring `ApplicationContext` to programmatically control -the configuration of Spring Session when using Apache Geode or Pivotal GemFire. +the configuration of Spring Session when using {apache-geode-name}. The `SpringSessionGemFireConfigurer`, when declared in the Spring `ApplicationContext`, takes precedence over any of the -Spring Session (for Apache Geode/Pivotal GemFire) configuration properties, and will effectively override them when both +Spring Session (for {apache-geode-name}) configuration properties, and will effectively override them when both are present. More information on using the `SpringSessionGemFireConfigurer` can be found in the @@ -147,11 +147,10 @@ More information on using the `SpringSessionGemFireConfigurer` can be found in t [[geode-session-disable]] === Disabling Session State Caching -There may be cases where you do not want your Spring Boot application to manage (HTTP) Session state using either -Apache Geode or Pivotal GemFire. In certain cases, you may be using another Spring Session provider, -such as Redis, to cache and manage your Spring Boot application's (HTTP) Session state, while, even in other cases, -you do not want to use Spring Session to manage your (HTTP) Session state at all. Rather, you prefer to use your -Web Server's (e.g. Tomcat) `HttpSession` state management. +There may be cases where you do not want your Spring Boot application to manage (HTTP) Session state using {apache-geode-name}. +In certain cases, you may be using another Spring Session provider, such as Redis, to cache and manage your Spring Boot +application's (HTTP) Session state, while, even in other cases, you do not want to use Spring Session to manage your +(HTTP) Session state at all. Rather, you prefer to use your Web Server's (e.g. Tomcat) `HttpSession` state management. Either way, you can specifically call out your Spring Session provider using the `spring.session.store-type` property in `application.properties`, as follows: @@ -180,23 +179,23 @@ spring.session.store-type=none Again, see Spring Boot {spring-boot-docs-html}/boot-features-session.html[docs] for more details. TIP: It is possible to include multiple providers on the classpath of your Spring Boot application. For instance, -you might be using Redis to cache your application's (HTTP) Session state while using either Apache Geode -or Pivotal GemFire as your application's persistent store (_System of Record_). +you might be using Redis to cache your application's (HTTP) Session state while using {apache-geode-name} as your +application's persistent store (_System of Record_). NOTE: Spring Boot does not properly recognize `spring.session.store-type=[gemfire|geode]` even though -Spring Boot for Apache Geode/Pivotal GemFire is setup to handle either of these property values +Spring Boot for {apache-geode-name} is setup to handle either of these property values (i.e. either "`gemfire`" or "`geode`"). [[geode-session-pcc]] === Using Spring Session with Pivotal Cloud Cache Whether you are using Spring Session in a Spring Boot `ClientCache` application connecting to an externally managed -cluster of Apache Geode or Pivotal GemFire servers, or connecting to a cluster of servers in a Pivotal Cloud Cache -instance managed by a Pivotal Platform environment, the setup is the same. +cluster of {apache-geode-name} servers, or connecting to a cluster of servers in a Pivotal Cloud Cache instance +managed by a Pivotal Platform environment, the setup is the same. -Spring Session for Apache Geode, Pivotal GemFire, and Pivotal Cloud Cache (PCC) expects there to exist a cache Region -in the cluster that will store and manage the (HTTP) Session state when your Spring Boot application is a `ClientCache` -application in a client/server topology. +Spring Session for {apache-geode-name}, {pivotal-gemfire-name}, and Pivotal Cloud Cache (PCC) expects there to exist +a cache Region in the cluster that will store and manage the (HTTP) Session state when your Spring Boot application +is a `ClientCache` application in a client/server topology. By default, the cache Region used to store and manage (HTTP) Session state is called "_ClusteredSpringSessions_". @@ -208,7 +207,9 @@ the `@EnableGemFireHttpSession` annotation on your main `@SpringBootApplication` ---- @SpringBootApplication @EnableGemFireHttpSession(regionName = "MySessions") -class MySpringBootSpringSessionApplication { ... } +class MySpringBootSpringSessionApplication { + // ... +} ---- Or alternatively, we recommend users to configure the cache Region name using the well-known and documented property @@ -262,7 +263,9 @@ for more details. ---- @SpringBootApplication @EnableClusterAware -class MySpringBootSpringSessionApplication { ... } +class MySpringBootSpringSessionApplication { + // ... +} ---- However, it is not currently possible to send Expiration Policy configuration metadata to the cluster yet. Therefore, @@ -278,5 +281,5 @@ gfsh> alter region --name=MySessions --entry-idle-time-expiration=1800 That is it! Now your Spring Boot `ClientCache` application using Spring Session in a client/server topology is configured to store -and manage user (HTTP) Session state in the cluster. This works for either standalone, externally managed Apache Geode -or Pivotal GemFire clusters, or when using PCC running in a Pivotal Platform environment. +and manage user (HTTP) Session state in the cluster. This works for either standalone, externally managed {apache-geode-name} +clusters, or when using PCC running in a Pivotal Platform environment. diff --git a/spring-geode-docs/src/docs/asciidoc/guides/caching-http-session.adoc b/spring-geode-docs/src/docs/asciidoc/guides/caching-http-session.adoc index a0d207eb..aa1ff73e 100644 --- a/spring-geode-docs/src/docs/asciidoc/guides/caching-http-session.adoc +++ b/spring-geode-docs/src/docs/asciidoc/guides/caching-http-session.adoc @@ -1,6 +1,7 @@ [[geode-samples-caching-http-session]] = HTTP Session State Caching with Spring :apache-geode-version: {apache-geode-doc-version} +:apache-geode-name: Apache Geode :apache-geode-docs: https://geode.apache.org/docs/guide/{apache-geode-version} :apache-geode-javadoc: https://geode.apache.org/releases/latest/javadoc :apache-geode-website: https://geode.apache.org/ @@ -22,14 +23,17 @@ This guide walks you through building a simple Spring Boot application using {spring-session-website}[Spring Session] -backed by {apache-geode-website}[Apache Geode] to manage HTTP Session state. +backed by {apache-geode-website}[{apache-geode-name}] to manage HTTP Session state. It is assumed that the reader is familiar with the Spring _programming model_ as well as the _Java Servlet_ API. -No prior knowledge of Spring Session or Apache Geode is required to utilize HTTP Session State Caching in your +No prior knowledge of Spring Session or {apache-geode-name} is required to utilize HTTP Session State Caching in your Spring Boot applications. Let's begin. +TIP: Refer to the link:../index.html#geode-session[Spring Session] chapter in the reference documentation +for more information. + [#index-link] link:../index.html[Index] @@ -63,7 +67,7 @@ continuity and provide a consistent, uninterrupted experience, the HTTP Session One way to do this is to employ a data management solution in your application architecture that 1) makes the HTTP Session highly available and 2) makes the HTTP Session resilient to failures in the system architecture. -Apache Geode is ideal for managing HTTP Session state given that it can distribute data/state across a scaled-out, +{apache-geode-name} is ideal for managing HTTP Session state given that it can distribute data/state across a scaled-out, highly-available architecture by replicating data in a redundant and organized (partitioned) manner, thereby making the data resilient to network and hardware failures. @@ -94,8 +98,8 @@ image::{images-dir}/Spring-Session-Framework-Architecture.png[] Again, the `SessionRepository` interface is the central component of the framework enabling any backend data store to be adapted and serve as a provider for managing the HTTP Sessions. -This is effectively how https://github.com/spring-projects/spring-session-data-geode[Spring Session for Apache Geode -& Pivotal GemFire] works. +This is effectively how https://github.com/spring-projects/spring-session-data-geode[Spring Session for {apache-geode-name}] +works. [[geode-samples-caching-http-session-example]] == Example @@ -153,9 +157,9 @@ the application is switched to a client/server topology to the "_DEFAULT_" Pool. used to store HTTP Session state as "_Sessions_" (default name is "_ClusteredSpringSessions_"). TIP: In most production deployments, you will likely be using a client/server topology, where the HTTP Session is -managed by a cluster of Apache Geode or Pivotal GemFire servers so that the HTTP Session can be shared across multiple -instances of the Spring Boot, Web application. This would be especially true in a cloud environment when utilizing a -Microservices architecture. However, for example purposes, we tried to keep the sample as simple as possible. +managed by a cluster of {apache-geode-name} servers so that the HTTP Session can be shared across multiple instances +of the Spring Boot, Web application. This would be especially true in a cloud environment when utilizing a Microservices +architecture. However, for example purposes, we tried to keep the sample as simple as possible. NOTE: The default data management policy for the client cache (a.k.a. Region) used to manage HTTP Session state is a `PROXY`, which is the basis for the client/server topology. Therefore, the default configuration assumes you will be @@ -259,9 +263,9 @@ First, we must add Spring Session to the application's classpath. We do this si ---- The `spring-geode-starter-session` dependency adds Spring Session to the application's classpath at runtime -and positions Apache Geode as the provider used to manage the HTTP Session state. +and positions {apache-geode-name} as the provider used to manage the HTTP Session state. -With Apache Geode, we gain all the benefits of using a highly concurrent, highly distributed data management solution +With {apache-geode-name}, we gain all the benefits of using a highly concurrent, highly distributed data management solution that provides high availability (HA) and resiliency in a cloud environment. That's it! This is all we have to do to replace the Servlet's Container's HTTP Session management facilities with a @@ -277,7 +281,7 @@ Now we see that the implementing class for the `javax.servlet.http.HttpSession` Easy! Of course, the ability to scale-out and optimize the data management policies for HTTP Session management is very -provider-specific (e.g. Apache Geode) and highly dependent on the use case as well a application requirements, +provider-specific (e.g. {apache-geode-name}) and highly dependent on the use case as well a application requirements, therefore is beyond the scope of this guide. [[geode-samples-caching-http-session-summary]] @@ -286,7 +290,7 @@ therefore is beyond the scope of this guide. Spring Session is a powerful framework for managing your HTTP Session state. Not only does it allow you to plugin different backend data management providers (as of this writing): -* https://github.com/spring-projects/spring-session-data-geode#spring-session-for-apache-geode--pivotal-gemfire[_Apache Geode (or Pivotal GemFire)_] +* https://github.com/spring-projects/spring-session-data-geode#spring-session-for-apache-geode--pivotal-gemfire[_{apache-geode-name}_] * {spring-session-website}[_Hazelast_] * {spring-session-website}[_JDBC_] * https://spring.io/projects/spring-session-data-mongodb[_MongoDB_]