Package org.apache.catalina.session

Class PersistentManagerBase

java.lang.Object

org.apache.catalina.util.LifecycleBase

org.apache.catalina.util.LifecycleMBeanBase

org.apache.catalina.session.ManagerBase

org.apache.catalina.session.PersistentManagerBase

All Implemented Interfaces:

MBeanRegistration, DistributedManager, JmxEnabled, Lifecycle, Manager, StoreManager

Direct Known Subclasses:

PersistentManager

public abstract class PersistentManagerBase
extends ManagerBase
implements StoreManager

Extends the ManagerBase class to implement most of the functionality required by a Manager which supports any kind of persistence, even if only for restarts.

IMPLEMENTATION NOTE: Correct behavior of session storing and reloading depends upon external calls to the Lifecycle.start() and Lifecycle.stop() methods of this class at the correct times.

Author:

Craig R. McClanahan

Nested Class Summary

Nested classes/interfaces inherited from class org.apache.catalina.session.ManagerBase

ManagerBase.SessionTiming

Nested classes/interfaces inherited from interface org.apache.catalina.Lifecycle

Lifecycle.SingleUse

Field Summary

Fields

Modifier and Type	Field	Description
protected int	maxIdleBackup	How long a session must be idle before it should be backed up.
protected int	maxIdleSwap	The maximum time in seconds a session may be idle before it is eligible to be swapped to disk due to inactivity.
protected int	minIdleSwap	The minimum time in seconds a session must be idle before it is eligible to be swapped to disk to keep the active session count below maxActiveSessions.
protected boolean	saveOnRestart	Whether to save and reload sessions when the Manager unload and load methods are called.
protected Store	store	Store object which will manage the Session store.

Fields inherited from class org.apache.catalina.session.ManagerBase

expiredSessions, maxActive, maxActiveSessions, processExpiresFrequency, processingTime, rejectedSessions, secureRandomAlgorithm, secureRandomClass, secureRandomProvider, sessionCreationTiming, sessionExpirationTiming, sessionIdGenerator, sessionIdGeneratorClass, sessionMaxAliveTime, sessions, sm, support, TIMING_STATS_CACHE_SIZE

Fields inherited from interface org.apache.catalina.Lifecycle

AFTER_DESTROY_EVENT, AFTER_INIT_EVENT, AFTER_START_EVENT, AFTER_STOP_EVENT, BEFORE_DESTROY_EVENT, BEFORE_INIT_EVENT, BEFORE_START_EVENT, BEFORE_STOP_EVENT, CONFIGURE_START_EVENT, CONFIGURE_STOP_EVENT, PERIODIC_EVENT, START_EVENT, STOP_EVENT

Constructor Summary

Constructors

Constructor	Description
PersistentManagerBase()

Method Summary

Modifier and Type	Method	Description
void	clearStore()	Clear all sessions from the Store.
Session	findSession(String id)	Return the active Session, associated with this Manager, with the specified session id (if any); otherwise return null.
int	getActiveSessionsFull()	Returns the total session count for primary, backup and proxy.
int	getMaxIdleBackup()	Indicates how many seconds old a session can get, after its last use in a request, before it should be backed up to the store.
int	getMaxIdleSwap()
int	getMinIdleSwap()
String	getName()
boolean	getSaveOnRestart()	Indicates whether sessions are saved when the Manager is shut down properly.
Set<String>	getSessionIdsFull()	Returns the list of all sessions IDS (primary, backup and proxy).
Store	getStore()
boolean	isLoaded(String id)	Check, whether a session is loaded in memory
void	load()	Load all sessions found in the persistence mechanism, assuming they are marked as valid and have not passed their expiration limit.
void	processExpires()	Invalidate all sessions that have expired.
protected void	processMaxActiveSwaps()	Swap idle sessions out to Store if too many are active
protected void	processMaxIdleBackups()	Back up idle sessions.
protected void	processMaxIdleSwaps()	Swap idle sessions out to Store if they are idle too long.
void	processPersistenceChecks()	Called by the background thread after active sessions have been checked for expiration, to allow sessions to be swapped out, backed up, etc.
void	remove(Session session, boolean update)	Remove this Session from the active Sessions for this Manager.
protected void	removeSession(String id)	Remove this Session from the active Sessions for this Manager, and from the Store.
void	removeSuper(Session session)	Remove this Session from the active Sessions for this Manager, but not from the Store.
void	setMaxIdleBackup(int backup)	Sets the option to back sessions up to the Store after they are used in a request.
void	setMaxIdleSwap(int max)	Sets the maximum time in seconds a session may be idle before it is eligible to be swapped to disk due to inactivity.
void	setMinIdleSwap(int min)	Sets the minimum time in seconds a session must be idle before it is eligible to be swapped to disk to keep the active session count below maxActiveSessions.
void	setSaveOnRestart(boolean saveOnRestart)	Set the option to save sessions to the Store when the Manager is shut down, then loaded when the Manager starts again.
void	setStore(Store store)	Set the Store object which will manage persistent Session storage for this Manager.
protected void	startInternal()	Start this component and implement the requirements of LifecycleBase.startInternal().
protected void	stopInternal()	Stop this component and implement the requirements of LifecycleBase.stopInternal().
protected Session	swapIn(String id)	Look for a session in the Store and, if found, restore it in the Manager's list of active sessions if appropriate.
protected void	swapOut(Session session)	Remove the session from the Manager's list of active sessions and write it out to the Store.
void	unload()	Save all currently active sessions in the appropriate persistence mechanism, if any.
protected void	writeSession(Session session)	Write the provided session to the Store without modifying the copy in memory or triggering passivation events.

Methods inherited from class org.apache.catalina.session.ManagerBase

add, addPropertyChangeListener, backgroundProcess, changeSessionId, changeSessionId, createEmptySession, createSession, expireSession, findSessions, generateSessionId, getActiveSessions, getClassName, getContext, getCreationTime, getCreationTimestamp, getDomainInternal, getEngine, getExpiredSessions, getJvmRoute, getLastAccessedTime, getLastAccessedTimestamp, getMaxActive, getMaxActiveSessions, getNewSession, getNotifyAttributeListenerOnUnchangedValue, getNotifyBindingListenerOnUnchangedValue, getObjectNameKeyProperties, getPersistAuthentication, getProcessExpiresFrequency, getProcessingTime, getRejectedSessions, getSecureRandomAlgorithm, getSecureRandomClass, getSecureRandomProvider, getSession, getSessionActivityCheck, getSessionAttribute, getSessionAttributeNameFilter, getSessionAttributeNamePattern, getSessionAttributeValueClassNameFilter, getSessionAttributeValueClassNamePattern, getSessionAverageAliveTime, getSessionCounter, getSessionCreateRate, getSessionExpireRate, getSessionIdGenerator, getSessionLastAccessAtStart, getSessionMaxAliveTime, getThisAccessedTime, getThisAccessedTimestamp, getWarnOnSessionAttributeFilterFailure, initInternal, listSessionIds, remove, removePropertyChangeListener, rotateSessionId, setContext, setExpiredSessions, setMaxActive, setMaxActiveSessions, setNotifyAttributeListenerOnUnchangedValue, setNotifyBindingListenerOnUnchangedValue, setPersistAuthentication, setProcessExpiresFrequency, setProcessingTime, setSecureRandomAlgorithm, setSecureRandomClass, setSecureRandomProvider, setSessionActivityCheck, setSessionAttributeNameFilter, setSessionAttributeValueClassNameFilter, setSessionIdGenerator, setSessionLastAccessAtStart, setSessionMaxAliveTime, setWarnOnSessionAttributeFilterFailure, toString, updateSessionMaxAliveTime, willAttributeDistribute

Methods inherited from class org.apache.catalina.util.LifecycleMBeanBase

destroyInternal, getDomain, getObjectName, postDeregister, postRegister, preDeregister, preRegister, register, setDomain, unregister, unregister

Methods inherited from class org.apache.catalina.util.LifecycleBase

addLifecycleListener, destroy, findLifecycleListeners, fireLifecycleEvent, getState, getStateName, getThrowOnFailure, init, removeLifecycleListener, setState, setState, setThrowOnFailure, start, stop

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Details

store

protected Store store

Store object which will manage the Session store.

saveOnRestart

protected boolean saveOnRestart

Whether to save and reload sessions when the Manager unload and load methods are called.

maxIdleBackup

protected int maxIdleBackup

How long a session must be idle before it should be backed up. -1 means sessions won't be backed up.

minIdleSwap

protected int minIdleSwap

The minimum time in seconds a session must be idle before it is eligible to be swapped to disk to keep the active session count below maxActiveSessions. Setting to -1 means sessions will not be swapped out to keep the active session count down.

maxIdleSwap

protected int maxIdleSwap

The maximum time in seconds a session may be idle before it is eligible to be swapped to disk due to inactivity. Setting this to -1 means sessions should not be swapped out just because of inactivity.

Constructor Details

PersistentManagerBase

public PersistentManagerBase()

Method Details

getMaxIdleBackup

public int getMaxIdleBackup()

Indicates how many seconds old a session can get, after its last use in a request, before it should be backed up to the store. -1 means sessions are not backed up.

Returns:

the timeout after which sessions are ripe for back up

setMaxIdleBackup

public void setMaxIdleBackup(int backup)

Sets the option to back sessions up to the Store after they are used in a request. Sessions remain available in memory after being backed up, so they are not passivated as they are when swapped out. The value set indicates how old a session may get (since its last use) before it must be backed up: -1 means sessions are not backed up.

Note that this is not a hard limit: sessions are checked against this age limit periodically according to processExpiresFrequency. This value should be considered to indicate when a session is ripe for backing up.

So it is possible that a session may be idle for maxIdleBackup + processExpiresFrequency * engine.backgroundProcessorDelay seconds, plus the time it takes to handle other session expiration, swapping, etc. tasks.

Parameters:

backup - The number of seconds after their last accessed time when they should be written to the Store.

getMaxIdleSwap

public int getMaxIdleSwap()

Returns:

The maximum time in seconds a session may be idle before it is eligible to be swapped to disk due to inactivity. A value of -1 means sessions should not be swapped out just because of inactivity.

setMaxIdleSwap

public void setMaxIdleSwap(int max)

Sets the maximum time in seconds a session may be idle before it is eligible to be swapped to disk due to inactivity. Setting this to -1 means sessions should not be swapped out just because of inactivity.

Parameters:

max - time in seconds to wait for possible swap out

getMinIdleSwap

public int getMinIdleSwap()

Returns:

The minimum time in seconds a session must be idle before it is eligible to be swapped to disk to keep the active session count below maxActiveSessions. A value of -1 means sessions will not be swapped out to keep the active session count down.

setMinIdleSwap

public void setMinIdleSwap(int min)

Sets the minimum time in seconds a session must be idle before it is eligible to be swapped to disk to keep the active session count below maxActiveSessions. Setting to -1 means sessions will not be swapped out to keep the active session count down.

Parameters:

min - time in seconds before a possible swap out

isLoaded

public boolean isLoaded(String id)

Check, whether a session is loaded in memory

Parameters:

id - The session id for the session to be searched for

Returns:

true, if the session id is loaded in memory otherwise false is returned

getName

public String getName()

Overrides:

getName in class ManagerBase

Returns:

The descriptive short name of this Manager implementation.

setStore

public void setStore(Store store)

Set the Store object which will manage persistent Session storage for this Manager.

Parameters:

store - the associated Store

getStore

public Store getStore()

Specified by:

getStore in interface StoreManager

Returns:

the Store object which manages persistent Session storage for this Manager.

getSaveOnRestart

public boolean getSaveOnRestart()

Indicates whether sessions are saved when the Manager is shut down properly. This requires the unload() method to be called.

Returns:

true, when sessions should be saved on restart, {code false} otherwise

setSaveOnRestart

public void setSaveOnRestart(boolean saveOnRestart)

Set the option to save sessions to the Store when the Manager is shut down, then loaded when the Manager starts again. If set to false, any sessions found in the Store may still be picked up when the Manager is started again.

Parameters:

saveOnRestart - true if sessions should be saved on restart, false if they should be ignored.

clearStore

public void clearStore()

Clear all sessions from the Store.

processExpires

public void processExpires()

Invalidate all sessions that have expired.

Direct call to processExpires and processPersistenceChecks

Overrides:

processExpires in class ManagerBase

processPersistenceChecks

public void processPersistenceChecks()

Called by the background thread after active sessions have been checked for expiration, to allow sessions to be swapped out, backed up, etc.

findSession

public Session findSession(String id)
                    throws IOException

Return the active Session, associated with this Manager, with the specified session id (if any); otherwise return null.

This method checks the persistence store if persistence is enabled, otherwise just uses the functionality from ManagerBase.

Specified by:

findSession in interface Manager

Overrides:

findSession in class ManagerBase

Parameters:

id - The session id for the session to be returned

Returns:

the request session or null if a session with the requested ID could not be found

Throws:

IOException - if an input/output error occurs while processing this request

removeSuper

public void removeSuper(Session session)

Description copied from interface: StoreManager

Remove this Session from the active Sessions for this Manager, but not from the Store. (Used by the PersistentValve)

Specified by:

removeSuper in interface StoreManager

Parameters:

session - Session to be removed

load

public void load()

Load all sessions found in the persistence mechanism, assuming they are marked as valid and have not passed their expiration limit. If persistence is not supported, this method returns without doing anything.

Note that by default, this method is not called by the MiddleManager class. In order to use it, a subclass must specifically call it, for example in the start() and/or processPersistenceChecks() methods.

Specified by:

load in interface Manager

remove

public void remove(Session session,
 boolean update)

Remove this Session from the active Sessions for this Manager.

Remove this Session from the Store.

Specified by:

remove in interface Manager

Overrides:

remove in class ManagerBase

Parameters:

session - Session to be removed

update - Should the expiration statistics be updated

removeSession

protected void removeSession(String id)

Remove this Session from the active Sessions for this Manager, and from the Store.

Parameters:

id - Session's id to be removed

unload

public void unload()

Save all currently active sessions in the appropriate persistence mechanism, if any. If persistence is not supported, this method returns without doing anything.

Note that by default, this method is not called by the MiddleManager class. In order to use it, a subclass must specifically call it, for example in the stop() and/or processPersistenceChecks() methods.

Specified by:

unload in interface Manager

getActiveSessionsFull

public int getActiveSessionsFull()

Description copied from interface: DistributedManager

Returns the total session count for primary, backup and proxy.

Specified by:

getActiveSessionsFull in interface DistributedManager

Returns:

The total session count across the cluster.

getSessionIdsFull

public Set<String> getSessionIdsFull()

Description copied from interface: DistributedManager

Returns the list of all sessions IDS (primary, backup and proxy).

Specified by:

getSessionIdsFull in interface DistributedManager

Returns:

The complete set of sessions IDs across the cluster.

swapIn

protected Session swapIn(String id)
                  throws IOException

Look for a session in the Store and, if found, restore it in the Manager's list of active sessions if appropriate. The session will be removed from the Store after swapping in, but will not be added to the active session list if it is invalid or past its expiration.

Parameters:

id - The id of the session that should be swapped in

Returns:

restored session, or null, if none is found

Throws:

IOException - an IO error occurred

swapOut

protected void swapOut(Session session)
                throws IOException

Remove the session from the Manager's list of active sessions and write it out to the Store. If the session is past its expiration or invalid, this method does nothing.

Parameters:

session - The Session to write out

Throws:

IOException - an IO error occurred

writeSession

protected void writeSession(Session session)
                     throws IOException

Write the provided session to the Store without modifying the copy in memory or triggering passivation events. Does nothing if the session is invalid or past its expiration.

Parameters:

session - The session that should be written

Throws:

IOException - an IO error occurred

startInternal

protected void startInternal()
                      throws LifecycleException

Start this component and implement the requirements of LifecycleBase.startInternal().

Overrides:

startInternal in class ManagerBase

Throws:

LifecycleException - if this component detects a fatal error that prevents this component from being used

stopInternal

protected void stopInternal()
                     throws LifecycleException

Stop this component and implement the requirements of LifecycleBase.stopInternal().

Overrides:

stopInternal in class ManagerBase

Throws:

LifecycleException - if this component detects a fatal error that prevents this component from being used

processMaxIdleSwaps

protected void processMaxIdleSwaps()

Swap idle sessions out to Store if they are idle too long.

processMaxActiveSwaps

protected void processMaxActiveSwaps()

Swap idle sessions out to Store if too many are active

processMaxIdleBackups

protected void processMaxIdleBackups()

Back up idle sessions.