diff --git a/spring-session-docs/modules/ROOT/nav.adoc b/spring-session-docs/modules/ROOT/nav.adoc index 182a80aa..647dda86 100644 --- a/spring-session-docs/modules/ROOT/nav.adoc +++ b/spring-session-docs/modules/ROOT/nav.adoc @@ -1,10 +1,4 @@ * xref:whats-new.adoc[What's New] -* xref:getting-started.adoc[Getting Started] -** xref:getting-started/using-redis.adoc[Using Redis] -** xref:getting-started/using-jdbc.adoc[Using JDBC] -** xref:getting-started/using-mongodb.adoc[Using MongoDB] -** xref:getting-started/using-hazelcast.adoc[Using Hazelcast] -** xref:getting-started/using-custom-session-repository.adoc[Using Your Own Session Repository] * xref:samples.adoc[Samples & Guides (Start Here)] ** Boot Samples *** HttpSession @@ -21,6 +15,8 @@ *** xref:guides/boot-webflux-custom-cookie.adoc[Custom Cookie] ** Java Configuration ** XML Configuration +* xref:configurations.adoc[Configurations] +** xref:configuration/redis.adoc[Redis] * xref:http-session.adoc[HttpSession Integration] * xref:web-socket.adoc[WebSocket Integration] * xref:web-session.adoc[WebSession Integration] diff --git a/spring-session-docs/modules/ROOT/pages/getting-started/using-redis.adoc b/spring-session-docs/modules/ROOT/pages/configuration/redis.adoc similarity index 58% rename from spring-session-docs/modules/ROOT/pages/getting-started/using-redis.adoc rename to spring-session-docs/modules/ROOT/pages/configuration/redis.adoc index 8b36ff68..c2474062 100644 --- a/spring-session-docs/modules/ROOT/pages/getting-started/using-redis.adoc +++ b/spring-session-docs/modules/ROOT/pages/configuration/redis.adoc @@ -1,158 +1,9 @@ -[[using-redis]] -= Using Spring Session with Redis - -Spring Session uses https://docs.spring.io/spring-data/data-redis/docs/{spring-data-redis-version}/reference/html/[Spring Data Redis] to support managing the session information in Redis. -In order to configure your application, you must choose what type of application you have: - -- <> -- <> - -[[spring-boot-configuration]] -== Spring Boot Configuration - -=== Adding the Dependencies - -First, you need to add the `spring-session-data-redis` dependency: - -==== -.pom.xml -[source,xml,role="primary"] -[subs="verbatim,attributes"] ----- - - - org.springframework.session - spring-session-data-redis - - ----- - -.build.gradle -[source,groovy,role="secondary"] ----- -implementation("org.springframework.session:spring-session-data-redis") ----- -==== - -As <>, we also need to add the Spring Data Redis dependency to our application, for that we can use the `spring-boot-starter-data-redis` dependency: - -==== -.pom.xml -[source,xml,role="primary"] -[subs="verbatim,attributes"] ----- - - - org.springframework.boot - spring-boot-starter-data-redis - - ----- - -.build.gradle -[source,groovy,role="secondary"] ----- -implementation("org.springframework.boot:spring-boot-starter-data-redis") ----- -==== - -Since we are using Spring Boot, it already {spring-boot-ref-docs}/web.html#web.spring-session[provides auto-configuration for the Redis support]. - -[NOTE] -==== -You can take control over Spring Session’s configuration using `@Enable*HttpSession` (servlet) or `@Enable*WebSession` (reactive). -This will cause the auto-configuration to back off. -Spring Session can then be configured using the annotation’s attributes rather than the configuration properties. -==== - -The basic setup is done, your application should be using Spring Session backed by Redis. -If you need, you can refer to {gh-samples-url}spring-session-sample-boot-redis[a sample Spring Boot application with Spring Session backed by Redis]. - -[[java-configuration]] -== Spring Java Configuration - -=== Adding the Dependencies - -First, we need to add the `spring-session-data-redis` and the `lettuce-core` dependency: - -==== -.pom.xml -[source,xml,role="primary"] -[subs="verbatim,attributes"] ----- - - - org.springframework.session - spring-session-data-redis - {spring-session-version} - - - io.lettuce - lettuce-core - {lettuce-core-version} - - ----- - -.build.gradle -[source,groovy,role="secondary"] ----- -implementation("org.springframework.session:spring-session-data-redis:{spring-session-version}") -implementation("io.lettuce:lettuce-core:{lettuce-core-version}") ----- -==== - -[[creating-spring-configuration]] -=== Creating the Spring Configuration - -After adding the required dependencies, we can create our Spring configuration. -The Spring configuration is responsible for creating a servlet filter that replaces the `HttpSession` implementation with an implementation backed by Spring Session. -To do so, add the following Spring Configuration: - -==== -[source,java] ----- -include::{samples-dir}spring-session-sample-javaconfig-redis/src/main/java/sample/Config.java[tags=class] ----- -==== - -<1> The `@EnableRedisHttpSession` annotation creates a Spring Bean with the name of `springSessionRepositoryFilter` that implements `Filter`. -The filter is in charge of replacing the `HttpSession` implementation to be backed by Spring Session. -In this instance, Spring Session is backed by Redis. -<2> We create a `RedisConnectionFactory` that connects Spring Session to the Redis Server using the `LettuceConnectionFactory`. -By default, it connects to `localhost` on the default port (6379). -For more information on configuring Spring Data Redis, see the https://docs.spring.io/spring-data/data-redis/docs/{spring-data-redis-version}/reference/html/#redis:connectors[reference documentation]. - -=== Initializing the Configuration into the Java Servlet Container - -Our <> created a Spring Bean named `springSessionRepositoryFilter` that implements `Filter`. -The `springSessionRepositoryFilter` bean is responsible for replacing the `HttpSession` with a custom implementation that is backed by Spring Session. - -In order for our `Filter` to work, Spring needs to load our `Config` class. -Last, we need to ensure that our Servlet Container uses our `springSessionRepositoryFilter` for every request. -Fortunately, Spring Session provides a utility class named `AbstractHttpSessionApplicationInitializer` to help with both of these steps. -The following shows an example: - -==== -.src/main/java/sample/Initializer.java -[source,java] ----- -include::{samples-dir}spring-session-sample-javaconfig-redis/src/main/java/sample/Initializer.java[tags=class] ----- -==== - -NOTE: The name of our class (`Initializer`) does not matter. What is important is that we extend `AbstractHttpSessionApplicationInitializer`. - -<1> The first step is to extend `AbstractHttpSessionApplicationInitializer`. -Doing so ensures that the Spring Bean by the name of `springSessionRepositoryFilter` is registered with our Servlet Container for every request. -<2> `AbstractHttpSessionApplicationInitializer` also provides a mechanism to ensure Spring loads our `Config`. - -== Further Customizations +[[redis-configurations]] += Redis Configurations Now that you have your application configured, you might want to start customizing things: - I want to {spring-boot-ref-docs}/application-properties.html#application-properties.data.spring.data.redis.host[customize the Redis configuration] using Spring Boot properties -- I want to customize the Redis configuration by <>. - I want <> `RedisSessionRepository` or `RedisIndexedSessionRepository`. - I want to <>. - I want to <>. @@ -160,9 +11,10 @@ Now that you have your application configured, you might want to start customizi - I want to <> [[serializing-session-using-json]] -=== Serializing the Session using JSON +== Serializing the Session using JSON By default, Spring Session uses Java Serialization to serialize the session attributes. +Sometimes it might be problematic, especially when you have multiple applications that use the same Redis instance but have different versions of the same class. You can provide a `RedisSerializer` bean to customize how the session is serialized into Redis. Spring Data Redis provides the `GenericJackson2JsonRedisSerializer` that serializes and deserializes objects using Jackson's `ObjectMapper`. @@ -188,12 +40,12 @@ public RedisSerializer springSessionDefaultRedisSerializer(ObjectMapper ==== [[using-a-different-namespace]] -=== Specifying a Different Namespace +== Specifying a Different Namespace It is not uncommon to have multiple applications that use the same Redis instance. For that reason, Spring Session uses a `namespace` (defaults to `spring:session`) to keep the session data separated if needed. -==== Using Spring Boot Properties +=== Using Spring Boot Properties You can specify it by setting the `spring.session.redis.namespace` property. @@ -214,7 +66,7 @@ spring: ---- ==== -==== Using the Annotation's Attributes +=== Using the Annotation's Attributes You can specify the `namespace` by setting the `redisNamespace` property in the `@EnableRedisHttpSession`, `@EnableRedisIndexedHttpSession`, or `@EnableRedisWebSession` annotations: @@ -251,7 +103,7 @@ public class SessionConfig { ==== [[choosing-between-regular-and-indexed]] -=== Choosing Between `RedisSessionRepository` and `RedisIndexedSessionRepository` +== Choosing Between `RedisSessionRepository` and `RedisIndexedSessionRepository` When working with Spring Session Redis, you will likely have to choose between the `RedisSessionRepository` and the `RedisIndexedSessionRepository`. Both are implementations of the `SessionRepository` interface that store session data in Redis. @@ -270,9 +122,9 @@ For example, it may create indexes based on session attributes like user ID or l These indexes allow for efficient querying of sessions based on specific criteria, enhancing performance and enabling advanced session management features. In addition to that, `RedisIndexedSessionRepository` also supports session expiration and deletion. -==== Configuring the `RedisSessionRepository` +=== Configuring the `RedisSessionRepository` -===== Using Spring Boot Properties +==== Using Spring Boot Properties If you are using Spring Boot, the `RedisSessionRepository` is the default implementation. However, if you want to be explicit about it, you can set the following property in your application: @@ -294,7 +146,7 @@ spring: ---- ==== -===== Using Annotations +==== Using Annotations You can configure the `RedisSessionRepository` by using the `@EnableRedisHttpSession` annotation: @@ -310,9 +162,9 @@ public class SessionConfig { ==== [[configuring-redisindexedsessionrepository]] -==== Configuring the `RedisIndexedSessionRepository` +=== Configuring the `RedisIndexedSessionRepository` -===== Using Spring Boot Properties +==== Using Spring Boot Properties You can configure the `RedisIndexedSessionRepository` by setting the following properties in your application: @@ -333,7 +185,7 @@ spring: ---- ==== -===== Using Annotations +==== Using Annotations You can configure the `RedisIndexedSessionRepository` by using the `@EnableRedisIndexedHttpSession` annotation: @@ -349,7 +201,7 @@ public class SessionConfig { ==== [[listening-session-events]] -=== Listening to Session Events +== Listening to Session Events Often times it is valuable to react to session events, for example, you might want to do some kind of processing depending on the session lifecycle. In order to be able to do that, you must be using the <>. @@ -389,7 +241,7 @@ public class SessionEventListener { ==== [[finding-all-user-sessions]] -=== Finding All Sessions of a Specific User +== Finding All Sessions of a Specific User By retrieving all sessions of a specific user, you can track the user's active sessions across devices or browsers. For example, you can use this information session management purposes, such as allowing the user to invalidate or logout from specific sessions or performing actions based on the user's session activity. diff --git a/spring-session-docs/modules/ROOT/pages/configurations.adoc b/spring-session-docs/modules/ROOT/pages/configurations.adoc new file mode 100644 index 00000000..ad16b2f9 --- /dev/null +++ b/spring-session-docs/modules/ROOT/pages/configurations.adoc @@ -0,0 +1,4 @@ +[[configuration]] += Configuration + +This section provides guidance on how to further configure Spring Session for each of its supported datastores. diff --git a/spring-session-docs/modules/ROOT/pages/getting-started.adoc b/spring-session-docs/modules/ROOT/pages/getting-started.adoc deleted file mode 100644 index 241d0c71..00000000 --- a/spring-session-docs/modules/ROOT/pages/getting-started.adoc +++ /dev/null @@ -1,22 +0,0 @@ -[[getting-started]] -= Getting Started - -In order to get started using Spring Session, you must choose a persistent store to use. -Spring Session supports a few different persistent stores out-of-the-box: - -- https://redis.io/[Redis] -- https://pt.wikipedia.org/wiki/JDBC[JDBC] -- https://hazelcast.com/[Hazelcast] -- https://www.mongodb.com/[MongoDB] - -There are other projects that are not supported by Spring Session, but are supported by the community: - -- https://github.com/spring-projects/spring-session-data-geode[Spring Session Data Geode] - -Now that you have chosen the persistence store that best fit your needs, you can jump to their respective sections: - -- xref:getting-started/using-redis.adoc[I want to use Redis] -- xref:getting-started/using-jdbc.adoc[I want to use JDBC] -- xref:getting-started/using-hazelcast.adoc[I want to use Hazelcast] -- xref:getting-started/using-mongodb.adoc[I want to use MongoDB] -- xref:getting-started/using-custom-session-repository.adoc[I want to use my own implementation] diff --git a/spring-session-docs/modules/ROOT/pages/getting-started/using-custom-session-repository.adoc b/spring-session-docs/modules/ROOT/pages/getting-started/using-custom-session-repository.adoc deleted file mode 100644 index 912c2305..00000000 --- a/spring-session-docs/modules/ROOT/pages/getting-started/using-custom-session-repository.adoc +++ /dev/null @@ -1,4 +0,0 @@ -[[using-custom-session-repository]] -= Using Spring Session with Custom Session Repository - -This section is still a work in progress, please refer to this xref:api.adoc#custom-sessionrepository[other section]. diff --git a/spring-session-docs/modules/ROOT/pages/getting-started/using-hazelcast.adoc b/spring-session-docs/modules/ROOT/pages/getting-started/using-hazelcast.adoc deleted file mode 100644 index aeea26e8..00000000 --- a/spring-session-docs/modules/ROOT/pages/getting-started/using-hazelcast.adoc +++ /dev/null @@ -1,4 +0,0 @@ -[[using-hazelcast]] -= Using Spring Session with Hazelcast - -This section is still a work in progress, please refer to this xref:http-session.adoc#httpsession-hazelcast[other section]. diff --git a/spring-session-docs/modules/ROOT/pages/getting-started/using-jdbc.adoc b/spring-session-docs/modules/ROOT/pages/getting-started/using-jdbc.adoc deleted file mode 100644 index e612d604..00000000 --- a/spring-session-docs/modules/ROOT/pages/getting-started/using-jdbc.adoc +++ /dev/null @@ -1,4 +0,0 @@ -[[using-jdbc]] -= Using Spring Session with JDBC - -This section is still a work in progress, please refer to this xref:guides/boot-jdbc.adoc[other section]. diff --git a/spring-session-docs/modules/ROOT/pages/getting-started/using-mongodb.adoc b/spring-session-docs/modules/ROOT/pages/getting-started/using-mongodb.adoc deleted file mode 100644 index 130ed3dd..00000000 --- a/spring-session-docs/modules/ROOT/pages/getting-started/using-mongodb.adoc +++ /dev/null @@ -1,4 +0,0 @@ -[[using-mongodb]] -= Using Spring Session with MongoDB - -This section is still a work in progress, please refer to this xref:guides/boot-mongo.adoc[other section].