Configuring Liberty session persistence with JCache

When session data must be maintained after a server restart or an unexpected server failure, you can configure Liberty to persist the session data with Java™ Caching (JCache). This configuration enables multiple servers to share session data, and recovery of session data if a failover occurs.

In version 21.0.0.6 and later, for information about configuring Liberty session persistence with J Cache, see the Open Liberty website.

To configure one or more servers in Liberty to persist session data with JCache, complete the following steps.

Procedure

Define a shared session management configuration on all of your servers.
1. Enable the sessionCache-1.0 feature.
2. Define a library that points to the location of your JCache provider.
```
<library id="jCacheVendorLib">
  <fileset dir="${shared.resource.dir}/hazelcast" includes="hazelcast.jar"/>
</library>
```
3. Refer to the library from the session cache configuration.
```
<httpSessionCache libraryRef="jCacheVendorLib"/>
```
4. Specify any needed JCache vendor configuration in one of three ways:
  - Specify a provider-specific URI. Use the URI syntax that the JCache provider documents for supplying to the javax.caching.spi.CachingProvider.getCacheManager method. This URI is generally the path to a provider-specific configuration file.
```
<httpSessionCache libraryRef="jCacheVendorLib" uri="file:${shared.resource.dir}/hazelcast/hazelcast.xml"/>
```
  - Specify provider-specific properties, if any, as key-value pairs on the httpSessionCache nested properties element. Use property keys and values that the JCache provider documents for supplying to the javax.caching.spi.CachingProvider.getCacheManager method.
```
<httpSessionCache libraryRef="jCacheVendorLib">
  <properties hazelcast.config.location="file:${shared.resource.dir}/hazelcast/hazelcast.xml"/>
</httpSessionCache>
```
  - Specify provider-specific system properties. System properties can be set in Liberty with the jvm.options file.
  For details about the httpSession and httpSessionCache elements, see JCache Session Persistence.
  For example, to configure session persistence by using Hazelcast as the JCache provider, you can configure your server.xml as follows:
```
<server description="Demonstrates HTTP Session Persistence configuration with JCache">
  <featureManager>
    <feature>sessionCache-1.0</feature>
    <feature>servlet-4.0</feature>
  </featureManager>

  <httpEndpoint id="defaultHttpEndpoint" host="*" httpPort="${httpPort}"/>

  <library id="jCacheVendorLib">
    <fileset dir="${shared.resource.dir}/hazelcast" includes="hazelcast.jar"/>
  </library>

  <httpSessionCache libraryRef="jCacheVendorLib"
                    uri="file:${shared.resource.dir}/hazelcast/hazelcast.xml"/>

  <httpSession cloneId="${cloneId}"/>
  <application location="${shared.app.dir}/test.ear"/>
</server>
```
  Tip: If you configure multiple servers to persist session data to the same database, ensure those servers share the session management configuration. Any other configuration is not supported.
  
  The HTTP server plug-in uses the clone ID that is inserted into the response or request header to maintain session affinity between requests. While the clone ID usually doesn't change, in Liberty the clone ID is generated when you start a server for the first time, and it is regenerated if you start the server with the --clean option. For production use, manually assign a clone ID to ensure that the ID is stable and that request affinity is maintained. The clone ID must be unique for each server and consists of alphanumeric characters The clone ID is specified in step 2.
  
  Any needed Hazelcast configuration, such as for security, can be provided in the ${shared.resource.dir}/hazelcast/hazelcast.xml file.
Specify unique variables in the bootstrap.properties file of each server.
- ${wlp.user.dir}/servers/s1/bootstrap.properties
```
httpPort=9081
cloneId=s1
```
- ${wlp.user.dir}/servers/s2/bootstrap.properties
```
httpPort=9082
cloneId=s2
```
Synchronize the system clocks of all computers that host Liberty servers. If the system clocks are not synchronized, session invalidation can occur prematurely.
Optional: Integrate HTTP sessions and security in Liberty. By default, after a session is created and accessed within a protected resource with security enabled, only the originating owner of that session can access it. Session security (security integration) is enabled by default.
Optional: Install and configure the web server plug-in to route requests to each of the servers that you configured. The session affinity is only maintained if your plug-in configuration specifies clone IDs that match the clone IDs in the server configuration.