Top Description Fields Methods
org.eclipse.jetty.session

public Interface SessionCache

extends LifeCycle
Known Direct Implementers
org.eclipse.jetty.session.AbstractSessionCache
Imports
java.util.Set, org.eclipse.jetty.util.component.LifeCycle
SessionCache A working set of ManagedSession 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: A SessionCache can passivate a valid Session to the SessionDataStore and evict it from the cache according to various strategies: . 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.

Field Summary

Modifier and TypeField and Description
public static final int
EVICT_ON_INACTIVITY

public static final int
EVICT_ON_SESSION_EXIT

public static final int
NEVER_EVICT

Method Summary

Modifier and TypeMethod and Description
public void
add(String
id
id, ManagedSession
session
session)

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

public Set<String>

Returns:

the set of session ids that have actually expired: this can be a superset of the original candidate list.
checkExpiration(Set<String>
the session ids to check
candidates)

Check a list of session ids that belong to potentially expired sessions.

public void
checkInactiveSession(ManagedSession
the session to check
session)

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

public void
commit(ManagedSession session)

Called when a response is about to be committed.

public boolean

Returns:

true if a Session object matching the id is present in the cache, false otherwise
contains(String
the session id
id)

Check to see if a Session is in the cache.

public ManagedSession

Returns:

the Session that was removed, null otherwise
delete(String
the session id
id)

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

public boolean

Returns:

true if the session exists, false otherwise
exists(String
the session id
id)

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

public ManagedSession

Returns:

the Session if one exists, null otherwise
get(String
the session id
id)

Get an existing Session.

public int

Returns:

the eviction policy
getEvictionPolicy()

public SessionDataStore

Returns:

the SessionDataStore used
getSessionDataStore()

public SessionManager
getSessionManager()

public void
initialize(SessionContext
the SessionContext to use for this cache
context)

public boolean

Returns:

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

public boolean
isInvalidateOnShutdown()

public boolean

Returns:

if true unloadable session will be deleted
isRemoveUnloadableSessions()

public boolean

Returns:

if true the newly created session will be saved immediately
isSaveOnCreate()

public boolean

Returns:

true if the session should be saved before being evicted
isSaveOnInactiveEviction()

public ManagedSession

Returns:

a new Session
newSession(String
the unique id associated to the session
id, long
the timestamp of the session creation
time, long
the max inactive time in milliseconds
maxInactiveMs)

Create an entirely new Session.

public ManagedSession

Returns:

a Session object for the data supplied
newSession(SessionData
the data associated with the session
data)

Re-materialize a Session that has previously existed.

public void
release(ManagedSession
the current session object
session)

Finish using a Session.

public ManagedSession

Returns:

the Session after changing its id
renewSessionId(String
the current session id
oldId, String
the new session id
newId, String
the current extended session id
oldExtendedId, String
the new extended session id
newExtendedId)

Change the id of a Session.

public void
setEvictionPolicy(int
-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.
policy)

Sessions in this cache can be:

  • never evicted
  • evicted once the last request exits
  • evicted after a configurable period of inactivity
public void
setFlushOnResponseCommit(boolean flushOnResponse)

If true, a dirty session will be written to the SessionDataStore just before a response is returned to the client.

public void
setInvalidateOnShutdown(boolean
true invalidate all sessions in cache on server shutdown
invalidateOnShutdown)

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

public void
setRemoveUnloadableSessions(boolean
true to delete session which cannot be loaded
removeUnloadableSessions)

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

public void
setSaveOnCreate(boolean
true to immediately save the newly created session
saveOnCreate)

Whether or not a session that is newly created should be immediately saved.

public void
setSaveOnInactiveEviction(boolean
true if the session should be saved before being evicted
saveOnEvict)

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

public void
setSessionDataStore(SessionDataStore
the SessionDataStore to use
sds)

A SessionDataStore that is the authoritative source of session information.

public void
shutdown()

Inherited from org.eclipse.jetty.util.component.LifeCycle:
addEventListenerisFailedisRunningisStartedisStartingisStoppedisStoppingremoveEventListenerstartstartstopstop

Field Detail

EVICT_ON_INACTIVITYback to summary
public static final int EVICT_ON_INACTIVITY
EVICT_ON_SESSION_EXITback to summary
public static final int EVICT_ON_SESSION_EXIT
NEVER_EVICTback to summary
public static final int NEVER_EVICT

Method Detail

addback to summary
public void add(String id, ManagedSession session) throws Exception

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

Parameters
id:String

id

session:ManagedSession

session

checkExpirationback to summary
public 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:Set<String>

the session ids to check

Returns:Set<String>

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

checkInactiveSessionback to summary
public void checkInactiveSession(ManagedSession session)

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

Parameters
session:ManagedSession

the session to check

commitback to summary
public void commit(ManagedSession 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.

containsback to summary
public boolean contains(String id) throws Exception

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

Parameters
id:String

the session id

Returns:boolean

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

Exceptions
Exception:
if any error occurred
deleteback to summary
public ManagedSession delete(String id) throws Exception

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

Parameters
id:String

the session id

Returns:ManagedSession

the Session that was removed, null otherwise

Exceptions
Exception:
if any error occurred
existsback to summary
public boolean exists(String id) throws Exception

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

Parameters
id:String

the session id

Returns:boolean

true if the session exists, false otherwise

Exceptions
Exception:
if any error occurred
getback to summary
public ManagedSession 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:String

the session id

Returns:ManagedSession

the Session if one exists, null otherwise

Exceptions
Exception:
if any error occurred
getEvictionPolicyback to summary
public int getEvictionPolicy()
Returns:int

the eviction policy

getSessionDataStoreback to summary
public SessionDataStore getSessionDataStore()
Returns:SessionDataStore

the SessionDataStore used

getSessionManagerback to summary
public SessionManager getSessionManager()
initializeback to summary
public void initialize(SessionContext context)
Parameters
context:SessionContext

the SessionContext to use for this cache

isFlushOnResponseCommitback to summary
public boolean isFlushOnResponseCommit()
Returns:boolean

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

isInvalidateOnShutdownback to summary
public boolean isInvalidateOnShutdown()
isRemoveUnloadableSessionsback to summary
public boolean isRemoveUnloadableSessions()
Returns:boolean

if true unloadable session will be deleted

isSaveOnCreateback to summary
public boolean isSaveOnCreate()
Returns:boolean

if true the newly created session will be saved immediately

isSaveOnInactiveEvictionback to summary
public boolean isSaveOnInactiveEviction()
Returns:boolean

true if the session should be saved before being evicted

newSessionback to summary
public ManagedSession newSession(String id, long time, long maxInactiveMs)

Create an entirely new Session.

Parameters
id:String

the unique id associated to the session

time:long

the timestamp of the session creation

maxInactiveMs:long

the max inactive time in milliseconds

Returns:ManagedSession

a new Session

newSessionback to summary
public ManagedSession newSession(SessionData data)

Re-materialize a Session that has previously existed.

Parameters
data:SessionData

the data associated with the session

Returns:ManagedSession

a Session object for the data supplied

releaseback to summary
public void release(ManagedSession 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
session:ManagedSession

the current session object

Exceptions
Exception:
if any error occurred
renewSessionIdback to summary
public ManagedSession renewSessionId(String oldId, String newId, String oldExtendedId, String newExtendedId) throws Exception

Change the id of a Session.

Parameters
oldId:String

the current session id

newId:String

the new session id

oldExtendedId:String

the current extended session id

newExtendedId:String

the new extended session id

Returns:ManagedSession

the Session after changing its id

Exceptions
Exception:
if any error occurred
setEvictionPolicyback to summary
public 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:int

-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.

setFlushOnResponseCommitback to summary
public 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.

setInvalidateOnShutdownback to summary
public 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:boolean

true invalidate all sessions in cache on server shutdown

setRemoveUnloadableSessionsback to summary
public 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:boolean

true to delete session which cannot be loaded

setSaveOnCreateback to summary
public 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:boolean

true to immediately save the newly created session

setSaveOnInactiveEvictionback to summary
public void setSaveOnInactiveEviction(boolean saveOnEvict)

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

Parameters
saveOnEvict:boolean

true if the session should be saved before being evicted

setSessionDataStoreback to summary
public void setSessionDataStore(SessionDataStore sds)

A SessionDataStore that is the authoritative source of session information.

Parameters
sds:SessionDataStore

the SessionDataStore to use

shutdownback to summary
public void shutdown()