Package org.eclipse.jetty.server.session

Interface SessionCache

All Superinterfaces:

LifeCycle

All Known Implementing Classes:

AbstractSessionCache, DefaultSessionCache, NullSessionCache

public interface SessionCache
extends LifeCycle

SessionCache A working set of Session objects for a context. Ideally, multiple requests for the same session id in the same context will always share the same Session object from the SessionCache, but it would be possible for implementations of SessionCache to create a fresh object for each request. The SessionData pertaining to the Session objects is obtained from/written to a SessionDataStore. The SessionDataStore is the authoritative source of session data:

• if the session data is not present in the SessionDataStore the session does not exist.
• if the session data is present in the SessionDataStore but its expiry time has passed then the session is deemed to have expired and is therefore invalid

A SessionCache can passivate a valid Session to the SessionDataStore and evict it from the cache according to various strategies:

• whenever the last request exits a Session
• whenever the Session has not been accessed for a configurable number of seconds

. Eviction can save memory, and can also help mitigate some of the problems of a non-sticky load balancer by forcing the session data to be re-read from the SessionDataStore more frequently.

Nested Class Summary

Nested classes/interfaces inherited from interface org.eclipse.jetty.util.component.LifeCycle

LifeCycle.Listener

Field Summary

Fields

Modifier and Type	Field	Description
static final int	EVICT_ON_INACTIVITY
static final int	EVICT_ON_SESSION_EXIT
static final int	NEVER_EVICT

Method Summary

Modifier and Type	Method	Description
void	add(String id, Session session)	Adds a new Session, with a never-before-used id, to the cache.
Set<String>	checkExpiration(Set<String> candidates)	Check a list of session ids that belong to potentially expired sessions.
void	checkInactiveSession(Session session)	Check a Session to see if it might be appropriate to evict or expire.
void	commit(Session session)	Called when a response is about to be committed.
boolean	contains(String id)	Check to see if a Session is in the cache.
Session	delete(String id)	Remove a Session completely: from both this cache and the SessionDataStore.
boolean	exists(String id)	Check to see if a session exists: WILL consult the SessionDataStore.
Session	get(String id)	Get an existing Session.
int	getEvictionPolicy()
SessionDataStore	getSessionDataStore()
SessionHandler	getSessionHandler()
void	initialize(SessionContext context)
boolean	isFlushOnResponseCommit()
boolean	isInvalidateOnShutdown()
boolean	isRemoveUnloadableSessions()
boolean	isSaveOnCreate()
boolean	isSaveOnInactiveEviction()
Session	newSession(jakarta.servlet.http.HttpServletRequest request, String id, long time, long maxInactiveMs)	Create an entirely new Session.
Session	newSession(SessionData data)	Re-materialize a Session that has previously existed.
void	put(String id, Session session)	Deprecated. use release(String, Session) instead
void	release(String id, Session session)	Finish using a Session.
Session	renewSessionId(String oldId, String newId, String oldExtendedId, String newExtendedId)	Change the id of a Session.
void	setEvictionPolicy(int policy)	Sessions in this cache can be: never evicted evicted once the last request exits evicted after a configurable period of inactivity
void	setFlushOnResponseCommit(boolean flushOnResponse)	If true, a dirty session will be written to the SessionDataStore just before a response is returned to the client.
void	setInvalidateOnShutdown(boolean invalidateOnShutdown)	If true, all existing sessions in the cache will be invalidated when the server shuts down.
void	setRemoveUnloadableSessions(boolean removeUnloadableSessions)	If the data for a session exists but is unreadable, the SessionCache can instruct the SessionDataStore to delete it.
void	setSaveOnCreate(boolean saveOnCreate)	Whether or not a session that is newly created should be immediately saved.
void	setSaveOnInactiveEviction(boolean saveOnEvict)	Whether or not a a session that is about to be evicted should be saved before being evicted.
void	setSessionDataStore(SessionDataStore sds)	A SessionDataStore that is the authoritative source of session information.
void	shutdown()

Methods inherited from interface org.eclipse.jetty.util.component.LifeCycle

addEventListener, isFailed, isRunning, isStarted, isStarting, isStopped, isStopping, removeEventListener, start, stop

Field Details

NEVER_EVICT

static final int NEVER_EVICT

See Also:

• Constant Field Values

EVICT_ON_SESSION_EXIT

static final int EVICT_ON_SESSION_EXIT

See Also:

• Constant Field Values

EVICT_ON_INACTIVITY

static final int EVICT_ON_INACTIVITY

See Also:

• Constant Field Values

Method Details

initialize

void initialize(SessionContext context)

Parameters:

context - the SessionContext to use for this cache

shutdown

void shutdown()

getSessionHandler

SessionHandler getSessionHandler()

newSession

Session newSession(jakarta.servlet.http.HttpServletRequest request,
 String id,
 long time,
 long maxInactiveMs)

Create an entirely new Session.

Parameters:

request - the request

id - the unique id associated to the session

time - the timestamp of the session creation

maxInactiveMs - the max inactive time in milliseconds

Returns:

a new Session

newSession

Session newSession(SessionData data)

Re-materialize a Session that has previously existed.

Parameters:

data - the data associated with the session

Returns:

a Session object for the data supplied

renewSessionId

Session renewSessionId(String oldId,
 String newId,
 String oldExtendedId,
 String newExtendedId)
                throws Exception

Change the id of a Session.

Parameters:

oldId - the current session id

newId - the new session id

oldExtendedId - the current extended session id

newExtendedId - the new extended session id

Returns:

the Session after changing its id

Throws:

Exception - if any error occurred

add

void add(String id,
 Session session)
  throws Exception

Adds a new Session, with a never-before-used id, to the cache.

Parameters:

id -

session -

Throws:

Exception

get

Session get(String id)
     throws Exception

Get an existing Session. If necessary, the cache will load the data for the session from the configured SessionDataStore.

Parameters:

id - the session id

Returns:

the Session if one exists, null otherwise

Throws:

Exception - if any error occurred

put

@Deprecated
void put(String id,
 Session session)
  throws Exception

Deprecated.

use release(String, Session) instead

Finish using a Session. This is called by the SessionHandler once a request is finished with a Session. SessionCache implementations may want to delay writing out Session contents until the last request exits a Session.

Parameters:

id - the session id

session - the current session object

Throws:

Exception - if any error occurred

release

void release(String id,
 Session session)
      throws Exception

Finish using a Session. This is called by the SessionHandler once a request is finished with a Session. SessionCache implementations may want to delay writing out Session contents until the last request exits a Session.

Parameters:

id - the session id

session - the current session object

Throws:

Exception - if any error occurred

commit

void commit(Session session)
     throws Exception

Called when a response is about to be committed. The cache can write the session to ensure that the SessionDataStore contains changes to the session that occurred during the lifetime of the request. This can help ensure that if a subsequent request goes to a different server, it will be able to see the session changes via the shared store.

Throws:

Exception

contains

boolean contains(String id)
          throws Exception

Check to see if a Session is in the cache. Does NOT consult the SessionDataStore.

Parameters:

id - the session id

Returns:

true if a Session object matching the id is present in the cache, false otherwise

Throws:

Exception - if any error occurred

exists

boolean exists(String id)
        throws Exception

Check to see if a session exists: WILL consult the SessionDataStore.

Parameters:

id - the session id

Returns:

true if the session exists, false otherwise

Throws:

Exception - if any error occurred

delete

Session delete(String id)
        throws Exception

Remove a Session completely: from both this cache and the SessionDataStore.

Parameters:

id - the session id

Returns:

the Session that was removed, null otherwise

Throws:

Exception - if any error occurred

checkExpiration

Set<String> checkExpiration(Set<String> candidates)

Check a list of session ids that belong to potentially expired sessions. The Session in the cache should be checked, but also the SessionDataStore, as that is the authoritative source of all session information.

Parameters:

candidates - the session ids to check

Returns:

the set of session ids that have actually expired: this can be a superset of the original candidate list.

checkInactiveSession

void checkInactiveSession(Session session)

Check a Session to see if it might be appropriate to evict or expire.

Parameters:

session - the session to check

setSessionDataStore

void setSessionDataStore(SessionDataStore sds)

A SessionDataStore that is the authoritative source of session information.

Parameters:

sds - the SessionDataStore to use

getSessionDataStore

SessionDataStore getSessionDataStore()

Returns:

the SessionDataStore used

setEvictionPolicy

void setEvictionPolicy(int policy)

Sessions in this cache can be:

• never evicted
• evicted once the last request exits
• evicted after a configurable period of inactivity

Parameters:

policy - -1 is never evict; 0 is evict-on-exit; and any other positive value is the time in seconds that a session can be idle before it can be evicted.

getEvictionPolicy

int getEvictionPolicy()

Returns:

the eviction policy

setSaveOnInactiveEviction

void setSaveOnInactiveEviction(boolean saveOnEvict)

Whether or not a a session that is about to be evicted should be saved before being evicted.

Parameters:

saveOnEvict - true if the session should be saved before being evicted

isSaveOnInactiveEviction

boolean isSaveOnInactiveEviction()

Returns:

true if the session should be saved before being evicted

setSaveOnCreate

void setSaveOnCreate(boolean saveOnCreate)

Whether or not a session that is newly created should be immediately saved. If false, a session that is created and invalidated within a single request is never persisted.

Parameters:

saveOnCreate - true to immediately save the newly created session

isSaveOnCreate

boolean isSaveOnCreate()

Returns:

if true the newly created session will be saved immediately

setRemoveUnloadableSessions

void setRemoveUnloadableSessions(boolean removeUnloadableSessions)

If the data for a session exists but is unreadable, the SessionCache can instruct the SessionDataStore to delete it.

Parameters:

removeUnloadableSessions - true to delete session which cannot be loaded

isRemoveUnloadableSessions

boolean isRemoveUnloadableSessions()

Returns:

if true unloadable session will be deleted

setFlushOnResponseCommit

void setFlushOnResponseCommit(boolean flushOnResponse)

If true, a dirty session will be written to the SessionDataStore just before a response is returned to the client. This ensures that subsequent requests to either the same node or a different node see the changed session data.

isFlushOnResponseCommit

boolean isFlushOnResponseCommit()

Returns:

true if dirty sessions should be written before the response is committed.

setInvalidateOnShutdown

void setInvalidateOnShutdown(boolean invalidateOnShutdown)

If true, all existing sessions in the cache will be invalidated when the server shuts down. Default is false.

Parameters:

invalidateOnShutdown -

isInvalidateOnShutdown

boolean isInvalidateOnShutdown()