9. API Documentation

You can see a typical example of how to create a new instance in the following listing:

RedisTemplate<Object, Object> redisTemplate = new RedisTemplate<>();

// ... configure redisTemplate ...

SessionRepository<? extends Session> repository = new RedisIndexedSessionRepository(redisTemplate);

For additional information on how to create a RedisConnectionFactory, see the Spring Data Redis Reference.

In a web environment, the simplest way to create a new RedisIndexedSessionRepository is to use @EnableRedisHttpSession. You can find complete example usage in the Chapter 3, Samples and Guides (Start Here). You can use the following attributes to customize the configuration:

RedisIndexedSessionRepository is subscribed to receive events from Redis by using a RedisMessageListenerContainer. You can customize the way those events are dispatched by creating a bean named springSessionRedisTaskExecutor, a bean springSessionRedisSubscriptionExecutor, or both. You can find more details on configuring Redis task executors here.

The following sections outline how Redis is updated for each operation. The following example shows an example of creating a new session:

HMSET spring:session:sessions:33fdd1b6-b496-4b33-9f7d-df96679d32fe creationTime 1404360000000 \
	maxInactiveInterval 1800 \
	lastAccessedTime 1404360000000 \
	sessionAttr:attrName someAttrValue \
	sessionAttr2:attrName someAttrValue2
EXPIRE spring:session:sessions:33fdd1b6-b496-4b33-9f7d-df96679d32fe 2100
APPEND spring:session:sessions:expires:33fdd1b6-b496-4b33-9f7d-df96679d32fe ""
EXPIRE spring:session:sessions:expires:33fdd1b6-b496-4b33-9f7d-df96679d32fe 1800
SADD spring:session:expirations:1439245080000 expires:33fdd1b6-b496-4b33-9f7d-df96679d32fe
EXPIRE spring:session:expirations1439245080000 2100

The subsequent sections describe the details.

HMSET spring:session:sessions:33fdd1b6-b496-4b33-9f7d-df96679d32fe creationTime 1404360000000 \
	maxInactiveInterval 1800 \
	lastAccessedTime 1404360000000 \
	sessionAttr:attrName someAttrValue \
	sessionAttr2:attrName someAttrValue2

HMSET spring:session:sessions:33fdd1b6-b496-4b33-9f7d-df96679d32fe sessionAttr:attrName2 newValue

Session Expiration

An expiration is associated with each session by using the EXPIRE command, based upon the Session.getMaxInactiveInterval(). The following example shows a typical EXPIRE command:

EXPIRE spring:session:sessions:33fdd1b6-b496-4b33-9f7d-df96679d32fe 2100

Note that the expiration that is set to five minutes after the session actually expires. This is necessary so that the value of the session can be accessed when the session expires. An expiration is set on the session itself five minutes after it actually expires to ensure that it is cleaned up, but only after we perform any necessary processing.

	Note
	The SessionRepository.findById(String) method ensures that no expired sessions are returned. This means that you need not check the expiration before using a session.

Spring Session relies on the delete and expired keyspace notifications from Redis to fire a SessionDeletedEvent and a SessionExpiredEvent, respectively. SessionDeletedEvent or SessionExpiredEvent ensure that resources associated with the Session are cleaned up. For example, when you use Spring Session’s WebSocket support, the Redis expired or delete event triggers any WebSocket connections associated with the session to be closed.

Expiration is not tracked directly on the session key itself, since this would mean the session data would no longer be available. Instead, a special session expires key is used. In the preceding example, the expires key is as follows:

APPEND spring:session:sessions:expires:33fdd1b6-b496-4b33-9f7d-df96679d32fe ""
EXPIRE spring:session:sessions:expires:33fdd1b6-b496-4b33-9f7d-df96679d32fe 1800

When a session expires key is deleted or expires, the keyspace notification triggers a lookup of the actual session, and a SessionDestroyedEvent is fired.

One problem with relying on Redis expiration exclusively is that, if the key has not been accessed, Redis makes no guarantee of when the expired event is fired. Specifically, the background task that Redis uses to clean up expired keys is a low-priority task and may not trigger the key expiration. For additional details, see the Timing of Expired Events section in the Redis documentation.

To circumvent the fact that expired events are not guaranteed to happen, we can ensure that each key is accessed when it is expected to expire. This means that, if the TTL is expired on the key, Redis removes the key and fires the expired event when we try to access the key.

For this reason, each session expiration is also tracked to the nearest minute. This lets a background task access the potentially expired sessions to ensure that Redis expired events are fired in a more deterministic fashion. The following example shows these events:

SADD spring:session:expirations:1439245080000 expires:33fdd1b6-b496-4b33-9f7d-df96679d32fe
EXPIRE spring:session:expirations1439245080000 2100

The background task then uses these mappings to explicitly request each key. By accessing the key, rather than deleting it, we ensure that Redis deletes the key for us only if the TTL is expired.

	Note
	We do not explicitly delete the keys, since, in some instances, there may be a race condition that incorrectly identifies a key as expired when it is not. Short of using distributed locks (which would kill our performance), there is no way to ensure the consistency of the expiration mapping. By simply accessing the key, we ensure that the key is only removed if the TTL on that key is expired.

SessionDeletedEvent and SessionExpiredEvent are both types of SessionDestroyedEvent.

RedisIndexedSessionRepository supports firing a SessionDeletedEvent when a Session is deleted or a SessionExpiredEvent when a Session expires. This is necessary to ensure resources associated with the Session are properly cleaned up.

For example, when integrating with WebSockets, the SessionDestroyedEvent is in charge of closing any active WebSocket connections.

Firing SessionDeletedEvent or SessionExpiredEvent is made available through the SessionMessageListener, which listens to Redis Keyspace events. In order for this to work, Redis Keyspace events for Generic commands and Expired events needs to be enabled. The following example shows how to do so:

redis-cli config set notify-keyspace-events Egx

If you use @EnableRedisHttpSession, managing the SessionMessageListener and enabling the necessary Redis Keyspace events is done automatically. However, in a secured Redis enviornment, the config command is disabled. This means that Spring Session cannot configure Redis Keyspace events for you. To disable the automatic configuration, add ConfigureRedisAction.NO_OP as a bean.

For example, with Java configuration, you can use the following:

@Bean
ConfigureRedisAction configureRedisAction() {
	return ConfigureRedisAction.NO_OP;
}

In XML configuration, you can use the following:

<util:constant
	static-field="org.springframework.session.data.redis.config.ConfigureRedisAction.NO_OP"/>

When a session is created, an event is sent to Redis with a channel ID of spring:session:channel:created:33fdd1b6-b496-4b33-9f7d-df96679d32fe, where 33fdd1b6-b496-4b33-9f7d-df96679d32fe is the session ID. The body of the event is the session that was created.

If registered as a MessageListener (the default), RedisIndexedSessionRepository then translates the Redis message into a SessionCreatedEvent.

After installing redis-cli, you can inspect the values in Redis using the redis-cli. For example, you can enter the following into a terminal:

$ redis-cli
redis 127.0.0.1:6379> keys *
1) "spring:session:sessions:4fc39ce3-63b3-4e17-b1c4-5e1ed96fb021" 
2) "spring:session:expirations:1418772300000" 

You can also view the attributes of each session. The following example shows how to do so:

redis 127.0.0.1:6379> hkeys spring:session:sessions:4fc39ce3-63b3-4e17-b1c4-5e1ed96fb021
1) "lastAccessedTime"
2) "creationTime"
3) "maxInactiveInterval"
4) "sessionAttr:username"
redis 127.0.0.1:6379> hget spring:session:sessions:4fc39ce3-63b3-4e17-b1c4-5e1ed96fb021 sessionAttr:username
"\xac\xed\x00\x05t\x00\x03rob"

The following example shows how to create a new instance:

// ... create and configure connectionFactory and serializationContext ...

ReactiveRedisTemplate<String, Object> redisTemplate = new ReactiveRedisTemplate<>(connectionFactory,
		serializationContext);

ReactiveSessionRepository<? extends Session> repository = new ReactiveRedisSessionRepository(redisTemplate);

For additional information on how to create a ReactiveRedisConnectionFactory, see the Spring Data Redis Reference.

In a web environment, the simplest way to create a new ReactiveRedisSessionRepository is to use @EnableRedisWebSession. You can use the following attributes to customize the configuration:

After installing redis-cli, you can inspect the values in Redis using the redis-cli. For example, you can enter the following command into a terminal window:

$ redis-cli
redis 127.0.0.1:6379> keys *
1) "spring:session:sessions:4fc39ce3-63b3-4e17-b1c4-5e1ed96fb021" 

You can also view the attributes of each session by using the hkeys command. The following example shows how to do so:

redis 127.0.0.1:6379> hkeys spring:session:sessions:4fc39ce3-63b3-4e17-b1c4-5e1ed96fb021
1) "lastAccessedTime"
2) "creationTime"
3) "maxInactiveInterval"
4) "sessionAttr:username"
redis 127.0.0.1:6379> hget spring:session:sessions:4fc39ce3-63b3-4e17-b1c4-5e1ed96fb021 sessionAttr:username
"\xac\xed\x00\x05t\x00\x03rob"

The following example shows how to create a new instance:

SessionRepository<? extends Session> repository = new MapSessionRepository(new ConcurrentHashMap<>());

The Hazelcast Sample is a complete application that demonstrates how to use Spring Session with Hazelcast.

To run it, use the following command:

	./gradlew :samples:hazelcast:tomcatRun

The Hazelcast Spring Sample is a complete application that demonstrates how to use Spring Session with Hazelcast and Spring Security.

It includes example Hazelcast MapListener implementations that support firing SessionCreatedEvent, SessionDeletedEvent, and SessionExpiredEvent.

To run it, use the following command:

	./gradlew :samples:hazelcast-spring:tomcatRun

The following example shows how to create a new instance:

JdbcTemplate jdbcTemplate = new JdbcTemplate();

// ... configure jdbcTemplate ...

TransactionTemplate transactionTemplate = new TransactionTemplate();

// ... configure transactionTemplate ...

SessionRepository<? extends Session> repository = new JdbcIndexedSessionRepository(jdbcTemplate,
		transactionTemplate);

For additional information on how to create and configure JdbcTemplate and PlatformTransactionManager, see the Spring Framework Reference Documentation.

In a web environment, the simplest way to create a new JdbcIndexedSessionRepository is to use @EnableJdbcHttpSession. You can find complete example usage in the Chapter 3, Samples and Guides (Start Here) You can use the following attributes to customize the configuration:

By default, this implementation uses SPRING_SESSION and SPRING_SESSION_ATTRIBUTES tables to store sessions. Note that you can customize the table name, as already described. In that case, the table used to store attributes is named by using the provided table name suffixed with _ATTRIBUTES. If further customizations are needed, you can customize the SQL queries used by the repository by using set*Query setter methods. In this case, you need to manually configure the sessionRepository bean.

Due to the differences between the various database vendors, especially when it comes to storing binary data, make sure to use SQL scripts specific to your database. Scripts for most major database vendors are packaged as org/springframework/session/jdbc/schema-*.sql, where * is the target database type.

For example, with PostgreSQL, you can use the following schema script:

CREATE TABLE SPRING_SESSION (
	PRIMARY_ID CHAR(36) NOT NULL,
	SESSION_ID CHAR(36) NOT NULL,
	CREATION_TIME BIGINT NOT NULL,
	LAST_ACCESS_TIME BIGINT NOT NULL,
	MAX_INACTIVE_INTERVAL INT NOT NULL,
	EXPIRY_TIME BIGINT NOT NULL,
	PRINCIPAL_NAME VARCHAR(100),
	CONSTRAINT SPRING_SESSION_PK PRIMARY KEY (PRIMARY_ID)
);

CREATE UNIQUE INDEX SPRING_SESSION_IX1 ON SPRING_SESSION (SESSION_ID);
CREATE INDEX SPRING_SESSION_IX2 ON SPRING_SESSION (EXPIRY_TIME);
CREATE INDEX SPRING_SESSION_IX3 ON SPRING_SESSION (PRINCIPAL_NAME);

CREATE TABLE SPRING_SESSION_ATTRIBUTES (
	SESSION_PRIMARY_ID CHAR(36) NOT NULL,
	ATTRIBUTE_NAME VARCHAR(200) NOT NULL,
	ATTRIBUTE_BYTES BYTEA NOT NULL,
	CONSTRAINT SPRING_SESSION_ATTRIBUTES_PK PRIMARY KEY (SESSION_PRIMARY_ID, ATTRIBUTE_NAME),
	CONSTRAINT SPRING_SESSION_ATTRIBUTES_FK FOREIGN KEY (SESSION_PRIMARY_ID) REFERENCES SPRING_SESSION(PRIMARY_ID) ON DELETE CASCADE
);

With MySQL database, you can use the following script:

CREATE TABLE SPRING_SESSION (
	PRIMARY_ID CHAR(36) NOT NULL,
	SESSION_ID CHAR(36) NOT NULL,
	CREATION_TIME BIGINT NOT NULL,
	LAST_ACCESS_TIME BIGINT NOT NULL,
	MAX_INACTIVE_INTERVAL INT NOT NULL,
	EXPIRY_TIME BIGINT NOT NULL,
	PRINCIPAL_NAME VARCHAR(100),
	CONSTRAINT SPRING_SESSION_PK PRIMARY KEY (PRIMARY_ID)
) ENGINE=InnoDB ROW_FORMAT=DYNAMIC;

CREATE UNIQUE INDEX SPRING_SESSION_IX1 ON SPRING_SESSION (SESSION_ID);
CREATE INDEX SPRING_SESSION_IX2 ON SPRING_SESSION (EXPIRY_TIME);
CREATE INDEX SPRING_SESSION_IX3 ON SPRING_SESSION (PRINCIPAL_NAME);

CREATE TABLE SPRING_SESSION_ATTRIBUTES (
	SESSION_PRIMARY_ID CHAR(36) NOT NULL,
	ATTRIBUTE_NAME VARCHAR(200) NOT NULL,
	ATTRIBUTE_BYTES BLOB NOT NULL,
	CONSTRAINT SPRING_SESSION_ATTRIBUTES_PK PRIMARY KEY (SESSION_PRIMARY_ID, ATTRIBUTE_NAME),
	CONSTRAINT SPRING_SESSION_ATTRIBUTES_FK FOREIGN KEY (SESSION_PRIMARY_ID) REFERENCES SPRING_SESSION(PRIMARY_ID) ON DELETE CASCADE
) ENGINE=InnoDB ROW_FORMAT=DYNAMIC;

All JDBC operations in JdbcIndexedSessionRepository are executed in a transactional manner. Transactions are executed with propagation set to REQUIRES_NEW in order to avoid unexpected behavior due to interference with existing transactions (for example, running a save operation in a thread that already participates in a read-only transaction).

The following example shows how to create a new instance:

Config config = new Config();

// ... configure Hazelcast ...

HazelcastInstance hazelcastInstance = Hazelcast.newHazelcastInstance(config);

HazelcastIndexedSessionRepository repository = new HazelcastIndexedSessionRepository(hazelcastInstance);

For additional information on how to create and configure Hazelcast instance, see the Hazelcast documentation.

To use Hazelcast as your backing source for the SessionRepository, you can add the @EnableHazelcastHttpSession annotation to a @Configuration class. Doing so extends the functionality provided by the @EnableSpringHttpSession annotation but makes the SessionRepository for you in Hazelcast. You must provide a single HazelcastInstance bean for the configuration to work. You can find a complete configuration example in the Chapter 3, Samples and Guides (Start Here).

You can use the following attributes on @EnableHazelcastHttpSession to customize the configuration:

Using a MapListener to respond to entries being added, evicted, and removed from the distributed Map causes these events to trigger publishing of SessionCreatedEvent, SessionExpiredEvent, and SessionDeletedEvent events (respectively) through the ApplicationEventPublisher.

Sessions are stored in a distributed IMap in Hazelcast. The IMap interface methods are used to get() and put() Sessions. Additionally, the values() method supports a FindByIndexNameSessionRepository#findByIndexNameAndIndexValue operation, together with appropriate ValueExtractor (which needs to be registered with Hazelcast). See the Hazelcast Spring Sample for more details on this configuration. The expiration of a session in the IMap is handled by Hazelcast’s support for setting the time to live on an entry when it is put() into the IMap. Entries (sessions) that have been idle longer than the time to live are automatically removed from the IMap.

You should not need to configure any settings such as max-idle-seconds or time-to-live-seconds for the IMap within the Hazelcast configuration.

Note that if you use Hazelcast’s MapStore to persist your sessions IMap, the following limitations apply when reloading the sessions from MapStore:

Exposing the CookieSerializer as a Spring bean augments the existing configuration when you use configurations like @EnableRedisHttpSession.

The following example shows how to do so:

	@Bean
	public CookieSerializer cookieSerializer() {
		DefaultCookieSerializer serializer = new DefaultCookieSerializer();
		serializer.setCookieName("JSESSIONID"); 
		serializer.setCookiePath("/"); 
		serializer.setDomainNamePattern("^.+?\\.(\\w+\\.[a-z]+)$"); 
		return serializer;
	}

	Warning
	You should only match on valid domain characters, since the domain name is reflected in the response. Doing so prevents a malicious user from performing such attacks as HTTP Response Splitting.

You can customize how the session cookie is written by using any of the following configuration options on the DefaultCookieSerializer.

	Warning
	You should only match on valid domain characters, since the domain name is reflected in the response. Doing so prevents a malicious user from performing such attacks as HTTP Response Splitting.