Coherence Spring Session

This section dives into the Coherence Spring Session module. It explains how to use Coherence’s support for Spring Session.

1. Getting Started

In this chapter you will learn how to configure Coherence as an HTTP session store using Spring Session.

First you need to add the coherence-spring-session dependency:

Example 1. Adding the Coherence Spring Session Dependency

Maven

<dependencies>
    <dependency>
        <groupId>com.oracle.coherence.spring</groupId>
        <artifactId>coherence-spring-session</artifactId>
        <version>4.1.0</version>
    </dependency>
    <dependency>
        <groupId>com.oracle.coherence.ce</groupId>
        <artifactId>coherence</artifactId>
        <version>23.09.1</version>
    </dependency>
</dependencies>

Gradle

dependencies {
    compile("com.oracle.coherence.spring:coherence-spring-session:4.1.0")
    compile("com.oracle.coherence.ce:coherence:23.09.1")
}

Coherence Spring support for Spring Session can be used for either the free Coherence Community Edition (CE) or the commercial version. Coherence Spring does not bring in the Coherence dependency automatically but users must specify the Coherence dependency explicitly.

In order to enable Spring Session support for Coherence, make sure Coherence is enabled and then enable Spring Session using the @EnableCoherenceHttpSession annotation.

Enabling Coherence Spring Sessions

@Configuration
@EnableCoherence
@EnableCoherenceHttpSession(                     (1)
        session = "coherence_session",           (2)
        cache = "spring:session:sessions",       (3)
        flushMode = FlushMode.ON_SAVE,           (4)
        sessionTimeoutInSeconds = 1800,          (5)
        useEntryProcessor = true                 (6)
)
static class CoherenceSessionConfig {
}

1	Enables Spring Session support for Coherence
2	Specify the name of the Coherence Session. Optional. Defaults to Coherence' default session.
3	The name of the cache to use. Optional. Defaults to `spring:session:sessions`.
4	The FlushMode to use. Optional. Defaults to `FlushMode.ON_SAVE`.
5	The session timeout. Optional. Defaults to `1800` seconds (`30` minutes)
6	When doing HTTP session updates, shall we use a Coherence entry processor? The default is {@code true}.

Are you running Coherence as a dedicated server instance? Then you need to make sure that your Coherence server may need one or more additional dependencies on its classpath for serialization. Depending on your requirements, you may need Coherence Spring Session, Spring Security Core, Spring Security Web. Please also ensure that dependency version between Coherence server and application clients matches exactly.

An alternative is to set useEntryProcessor to false. This is less efficient as the entire session has to be sent over the wire when updating session properties. The positive side effect is that your Coherence server instance will not need to be aware of the additional dependencies on its classpath.

2. POF Serialization

In case that you configured the cache using POF serialization, additional POF configuration for the class MapSession is necessary:

POF Configuration

 <user-type>
     <type-id>2001</type-id>
     <class-name>org.springframework.session.MapSession</class-name>
     <serializer>
         <class-name>com.oracle.coherence.spring.session.serialization.pof.MapSessionPofSerializer</class-name>
     </serializer>
 </user-type>

Depending on your serialization requirements and your session data, additional POF configuration may be necessary.

3. Spring Session Sample

This Coherence Spring source code repository provides a dedicated example application, illustrating the usage of Spring Session and Spring Security using Spring Boot.

The example application show-cases 2 use-cases:

Use Spring Session with embedded Coherence instances and Java serialization
Use Spring Session with remote Coherence instances (Coherence*Extends) and Java serialization

Even though this demo is targeting Spring Session, we use Spring Security as well, since the authentication details are stored in the session as well. In regard to authentication, users have 2 choices:

A user can POST a JSON request containing the username and password in the body of the request.
Use basic authentication

The username is coherence, and the password rocks.

Example Authentication Request

 { "username": "coherence", "password": "rocks" }

Once successfully authenticated, the application will return a 2xx HTTP status with an empty body and a session cookie. An Authentication failure, on the other hand, produces a non-2xx HTTP status with an empty body. The application has an endpoint that responds to a GET request to the URL /hello that returns the string Hello Coherence. All endpoints require an authenticated user using the session cookie or the username and password.

3.1. Start Spring Session with Embedded Coherence Instances

Build the Coherence Server instance

 $ ./mvnw clean package -pl samples/spring-session-demo/spring-session-demo-app

Now we are ready to run the application. Let’s launch 2 instances, one listening on the pre-configured port 8090, and the other one on port 8091.

Run the Spring Boot application

 $ java -jar samples/spring-session-demo/spring-session-demo-app/target/spring-session-demo-app-4.1.0.jar
 $ java -jar samples/spring-session-demo/spring-session-demo-app/target/spring-session-demo-app-4.1.0.jar --server.port=8091

3.2. Spring Session with Remote Coherence Instances

In this variation of the examle, we will start 1 central Coherence Server and the application will access that remote Coherence instance as a Coherence*Extend client.

Build the Coherence Server instance

 $ ./mvnw clean package -pl samples/spring-session-demo/spring-session-demo-server

Build the Application instance

 $ ./mvnw clean package -pl samples/spring-session-demo/spring-session-demo-app

Now we are ready to run the application. We will activate the coherence-client Spring Boot profile as well:

Run the Spring Boot application

 $ java -jar samples/spring-session-demo/spring-session-demo-server/target/spring-session-demo-server-4.1.0.jar
 $ java -jar samples/spring-session-demo/spring-session-demo-app/target/spring-session-demo-app-4.1.0.jar --spring.profiles.active=coherence-client

By default, Coherence Spring Session uses a Coherence Entry Processor to perform updates to the persisted HTTP Session. This will prevent the entire session to be sent over the wire. A drawback of that approach is that the Coherence instance needs to be aware of Coherence Spring classes for serialization purposes.

Alternatively, you can also set the Coherence Spring Session property coherence.spring.session.use-entry-processor and set it to false (It is true by default) in the client application spring-session-demo-app. With that in place, you can now remove the relevant Maven dependencies:

spring-security-web
coherence-spring-session

from the server application module spring-session-demo-server and the application will still work.

3.3. Accessing the REST Endpoints

Log into the application using CURL

 $ curl -i -c cookie.txt \
 -H "Accept: application/json" \
 -H "Content-Type:application/json" \
 -X POST --data '{"username": "coherence", "password": "rocks"}' \
 "http://localhost:8090/login"

Let’s access the HelloController

 $ curl -i -b cookie.txt \
 -H "Accept: application/json" \
 -H "Content-Type:application/json" \
 -X GET "http://localhost:8090/hello"

3.4. Spring Session Actuator

Using Spring Boot’s Actuator endpoints, we can introspect the session using the Sessions actuator at localhost:8090/actuator/sessions?username=coherence.

Retrieving session information for user coherence

 $ curl -i -b cookie.txt \
 -H "Accept: application/json" \
 -H "Content-Type:application/json" \
 -X GET "http://localhost:8090/actuator/sessions?username=coherence"

3.5. Generate Docker Image

If you prefer to use Docker, you can create an image using:

Generate a Docker image

 $ mvn spring-boot:build-image -pl samples/spring-session-demo/spring-session-demo-app -Dspring-boot.build-image.imageName=coherence/spring_session_demo

4. Session Expiration Strategies

When dealing with the expiration of cache entries, you generally have 2 options in Coherence:

Set the expiration time for each put operation explicitly
Configure caches in your coherence-cache-config.xml file

When you define a session timeout via the application, for example @EnableCoherenceHttpSession(sessionTimeoutInSeconds = 1000), the session expiration will be set for each put-operation in CoherenceIndexedSessionRepository.

If not set in the application, Coherence Spring will expire HTTP session caches in 1800 seconds (30 minutes).

If you rather prefer defining the session expiration timeouts in your coherence-cache-config.xml file, you should set the session timeout in the application to 0, for instance @EnableCoherenceHttpSession(sessionTimeoutInSeconds = 0). That way, put operations will never to set an expiration value for the cache entry. You can then set the expiry-delay cache configuration element for your cache in the coherence-cache-config.xml file.

In regard to the question, whether one strategy or the other strategy is preferable: It is mostly a matter of preference. You do have, however, a bit more control when configuring expiration logic via the coherence-cache-config.xml file, as you have the ability to define custom eviction policies.

For more information, please consult the respective chapter on Controlling the Growth of a Local Cache in the Coherence reference guide.

The underlying expiry delay parameter in Coherence is defined as an integer and is expressed in milliseconds. Therefore, the maximum amount of time can never exceed Integer.MAX_VALUE (2147483647) milliseconds or approximately 24 days.