org.apache.catalina.session

Class PersistentManagerBase

java.lang.Object

org.apache.catalina.session.ManagerBase

org.apache.catalina.session.PersistentManagerBase

All Implemented Interfaces:

PropertyChangeListener, EventListener, Lifecycle, Manager

Direct Known Subclasses:

PersistentManager, ReplicationManagerBase

public abstract class PersistentManagerBase
extends ManagerBase
implements Lifecycle, PropertyChangeListener

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 start() and stop() methods of this class at the correct times.

Version:

$Revision: 1.16 $ $Date: 2007/05/05 05:32:19 $

Author:

Craig R. McClanahan, Jean-Francois Arcand

Field Summary

Fields

Modifier and Type	Field and Description
protected ConcurrentHashMap<String,Long>	invalidatedSessions The set of invalidated Sessions for this Manager, keyed by session identifier.
protected LifecycleSupport	lifecycle The lifecycle event support for this component.
protected static String	name The descriptive name of this Manager implementation (for logging).

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

container, debug, devRandomSource, distributable, domain, duplicates, entropy, expiredSessions, initialized, log, maxActive, maxActiveUpdateLock, maxInactiveInterval, oname, randomClass, randomIS, rb, rejectedSessions, sessionAverageAliveTime, sessionCounter, sessionIdLength, sessionLocker, sessionMaxAliveTime, sessions, support, uuidGenerator

Fields inherited from interface org.apache.catalina.Lifecycle

AFTER_START_EVENT, AFTER_STOP_EVENT, BEFORE_START_EVENT, BEFORE_STOP_EVENT, INIT_EVENT, START_EVENT, STOP_EVENT

Constructor Summary

Constructors

Constructor and Description
PersistentManagerBase()

Method Summary

Modifier and Type	Method and Description
void	addLifecycleListener(LifecycleListener listener) Add a lifecycle event listener to this component.
void	addToInvalidatedSessions(String sessionId) Add this Session id to the set of invalidated Session ids for this Manager.
void	backgroundProcess() Perform the background processes for this Manager
void	clearStore() Clear all sessions from the Store.
Session	createSession() Return a new session object as long as the number of active sessions does not exceed maxActiveSessions.
Session	createSession(String sessionId) Construct and return a new session object, based on the default settings specified by this Manager's properties, using the specified session id.
List<LifecycleListener>	findLifecycleListeners() Gets the (possibly empty) list of lifecycle listeners associated with this session manager.
Session	findSession(String id) Return the active Session, associated with this Manager, with the specified session id (if any); otherwise return null.
Session	findSession(String id, boolean removeCachedCopy) Return the active Session, associated with this Manager, with the specified session id (if any); otherwise return null.
String	getInfo() Return descriptive information about this Manager implementation and the corresponding version number, in the format <description>/<version>.
int	getMaxActiveSessions() Return the maximum number of active Sessions allowed, or -1 for no limit.
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() The time in seconds after which a session should be swapped out of memory to disk.
int	getMinIdleSwap() The minimum time in seconds that a session must be idle before it can be swapped out of memory, or -1 if it can be swapped out at any time.
String	getMonitorAttributeValues()
String	getName() Return the descriptive short name of this Manager implementation.
boolean	getSaveOnRestart() Indicates whether sessions are saved when the Manager is shut down properly.
Store	getStore() Return the Store object which manages persistent Session storage for this Manager.
boolean	isLoaded(String id) Return true, if the session id is loaded in memory otherwise false is returned
boolean	isSessionIdValid(String sessionId)
protected boolean	isStarted() Get the started status.
void	load() Load all sessions found in the persistence mechanism, assuming they are marked as valid and have not passed their expiration limit.
protected void	processExpires() Invalidate all sessions that have expired.
protected void	processInvalidatedSessions() Purges those session ids from the map of invalidated session ids whose time has come up
protected void	processMaxActiveSwaps() Swap idle sessions out to Store if too many are active Hercules: modified method
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	propertyChange(PropertyChangeEvent event) Process property change events from our associated Context.
void	release()
void	remove(Session session) Remove this Session from the active Sessions for this Manager, and from the Store.
void	remove(Session session, boolean persistentRemove) Remove this Session from the active Sessions for this Manager, and from the Store.
void	removeFromInvalidatedSessions(String sessionId) Removes the given session id from the map of invalidated session ids.
void	removeLifecycleListener(LifecycleListener listener) Remove a lifecycle event listener from this component.
void	removeSuper(Session session) Remove this Session from the active Sessions for this Manager, but not from the Store.
void	setContainer(Container container) Set the Container with which this Manager has been associated.
void	setMaxActiveSessions(int max) Set the maximum number of active Sessions allowed, or -1 for no limit.
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 time in seconds after which a session should be swapped out of memory to disk.
void	setMinIdleSwap(int min) Sets the minimum time in seconds that a session must be idle before it can be swapped out of memory due to maxActiveSession.
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.
protected void	setStarted(boolean started) Set the started flag
void	setStore(Store store) Set the Store object which will manage persistent Session storage for this Manager.
void	start() Prepare for the beginning of active use of the public methods of this component.
void	stop() Gracefully terminate the active use of the public methods of this component.
protected Session	superFindSession(String id) used by subclasses of PersistentManagerBase Hercules: added method
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 Session	swapIn(String id, String version) 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, changeSessionId, checkSessionAttribute, clearSessions, createEmptySession, destroy, expireSession, findSession, findSession, findSessions, generateSessionId, generateSessionId, getActiveSessions, getClassName, getContainer, getDebug, getDistributable, getDomain, getDuplicates, getEngine, getEntropy, getExpiredSessions, getJvmRoute, getLastAccessedTimeMillis, getMaxActive, getMaxInactiveInterval, getMaxInactiveIntervalSeconds, getNewSession, getObjectName, getRandom, getRandomBytes, getRandomClass, getRandomFile, getRejectedSessions, getSessionAttribute, getSessionAverageAliveTime, getSessionAverageAliveTimeSeconds, getSessionCount, getSessionCounter, getSessionIdLength, getSessionMaxAliveTime, getSessionMaxAliveTimeSeconds, getUuidGenerator, init, isSessionVersioningSupported, listSessionIds, lockSession, log, log, postRequestDispatcherProcess, preRequestDispatcherProcess, removePropertyChangeListener, resetRandom, setDebug, setDistributable, setDuplicates, setEntropy, setExpiredSessions, setMaxActive, setMaxInactiveInterval, setMaxInactiveIntervalSeconds, setRandomClass, setRandomFile, setRejectedSessions, setSessionAverageAliveTime, setSessionAverageAliveTimeSeconds, setSessionCount, setSessionCounter, setSessionIdLength, setSessionLocker, setSessionMaxAliveTime, setSessionMaxAliveTimeSeconds, setUuidGenerator, toCookie, unlockSession, update

Methods inherited from class java.lang.Object

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

Field Detail

lifecycle

protected LifecycleSupport lifecycle

The lifecycle event support for this component.

name

protected static final String name

The descriptive name of this Manager implementation (for logging).

See Also:

Constant Field Values

invalidatedSessions

protected ConcurrentHashMap<String,Long> invalidatedSessions

The set of invalidated Sessions for this Manager, keyed by session identifier.

Constructor Detail

PersistentManagerBase

public PersistentManagerBase()

Method Detail

backgroundProcess

public void backgroundProcess()

Perform the background processes for this Manager

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.

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 checkInterval. 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 + checkInterval 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()

The time in seconds after which a session should be swapped out of memory to disk.

setMaxIdleSwap

public void setMaxIdleSwap(int max)

Sets the time in seconds after which a session should be swapped out of memory to disk.

getMinIdleSwap

public int getMinIdleSwap()

The minimum time in seconds that a session must be idle before it can be swapped out of memory, or -1 if it can be swapped out at any time.

setMinIdleSwap

public void setMinIdleSwap(int min)

Sets the minimum time in seconds that a session must be idle before it can be swapped out of memory due to maxActiveSession. Set it to -1 if it can be swapped out at any time.

setContainer

public void setContainer(Container container)

Set the Container with which this Manager has been associated. If it is a Context (the usual case), listen for changes to the session timeout property.

Specified by:

setContainer in interface Manager

Overrides:

setContainer in class ManagerBase

Parameters:

container - The associated Container

getInfo

public String getInfo()

Return descriptive information about this Manager implementation and the corresponding version number, in the format <description>/<version>.

Specified by:

getInfo in interface Manager

Overrides:

getInfo in class ManagerBase

isLoaded

public boolean isLoaded(String id)

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

Parameters:

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

Throws:

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

getMaxActiveSessions

public int getMaxActiveSessions()

Return the maximum number of active Sessions allowed, or -1 for no limit.

setMaxActiveSessions

public void setMaxActiveSessions(int max)

Set the maximum number of active Sessions allowed, or -1 for no limit.

Parameters:

max - The new maximum number of sessions

getName

public String getName()

Return the descriptive short name of this Manager implementation.

Overrides:

getName in class ManagerBase

isStarted

protected boolean isStarted()

Get the started status.

setStarted

protected void setStarted(boolean started)

Set the started flag

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()

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

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.

release

public void release()

Overrides:

release in class ManagerBase

clearStore

public void clearStore()

Clear all sessions from the Store.

processExpires

protected void processExpires()

Invalidate all sessions that have expired. Hercules: modified method

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.

processInvalidatedSessions

protected void processInvalidatedSessions()

Purges those session ids from the map of invalidated session ids whose time has come up

createSession

public Session createSession()

Return a new session object as long as the number of active sessions does not exceed maxActiveSessions. If there aren't too many active sessions, or if there is no limit, a session is created or retrieved from the recycled pool.

Specified by:

createSession in interface Manager

Overrides:

createSession in class ManagerBase

Throws:

IllegalStateException - if a new session cannot be instantiated for any reason

createSession

public Session createSession(String sessionId)

Construct and return a new session object, based on the default settings specified by this Manager's properties, using the specified session id. IMPLEMENTATION NOTE: This method must be kept in sync with the createSession method that takes no arguments.

Specified by:

createSession in interface Manager

Overrides:

createSession in class ManagerBase

Parameters:

sessionId - the session id to assign to the new session

Returns:

the new session, or null if a session with the requested id already exists

Throws:

IllegalStateException - if a new session cannot be instantiated for any reason

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

Throws:

IllegalStateException - if a new session cannot be instantiated for any reason

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

findSession

public Session findSession(String id,
                           boolean removeCachedCopy)
                    throws IOException

Return the active Session, associated with this Manager, with the specified session id (if any); otherwise return null. This method first removes the cached copy if removeCachedCopy = true. Then this method checks the persistence store if persistence is enabled, otherwise just uses the functionality from ManagerBase.

Parameters:

id - The session id for the session to be returned

removeCachedCopy -

Throws:

IllegalStateException - if a new session cannot be instantiated for any reason

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

superFindSession

protected Session superFindSession(String id)
                            throws IOException

used by subclasses of PersistentManagerBase Hercules: added method

Throws:

IOException

removeSuper

public void removeSuper(Session session)

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

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)

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

Specified by:

remove in interface Manager

Overrides:

remove in class ManagerBase

Parameters:

session - Session to be removed

remove

public void remove(Session session,
                   boolean persistentRemove)

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

Parameters:

session - Session to be removed

persistentRemove - - do we remove persistent session too

addToInvalidatedSessions

public void addToInvalidatedSessions(String sessionId)

Add this Session id to the set of invalidated Session ids for this Manager.

Parameters:

sessionId - session id to be added

removeFromInvalidatedSessions

public void removeFromInvalidatedSessions(String sessionId)

Removes the given session id from the map of invalidated session ids.

Parameters:

sessionId - The session id to remove

isSessionIdValid

public boolean isSessionIdValid(String sessionId)

Returns:

true if the given session id is not contained in the map of invalidated session ids, false otherwise

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

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.

Throws:

IOException

swapIn

protected Session swapIn(String id,
                         String version)
                  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 session id

version - The requested session version

Throws:

IOException

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

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.

Throws:

IOException

addLifecycleListener

public void addLifecycleListener(LifecycleListener listener)

Add a lifecycle event listener to this component.

Specified by:

addLifecycleListener in interface Lifecycle

Parameters:

listener - The listener to add

findLifecycleListeners

public List<LifecycleListener> findLifecycleListeners()

Gets the (possibly empty) list of lifecycle listeners associated with this session manager.

Specified by:

findLifecycleListeners in interface Lifecycle

removeLifecycleListener

public void removeLifecycleListener(LifecycleListener listener)

Remove a lifecycle event listener from this component.

Specified by:

removeLifecycleListener in interface Lifecycle

Parameters:

listener - The listener to remove

start

public void start()
           throws LifecycleException

Prepare for the beginning of active use of the public methods of this component. This method should be called after configure(), and before any of the public methods of the component are utilized.

Specified by:

start in interface Lifecycle

Throws:

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

stop

public void stop()
          throws LifecycleException

Gracefully terminate the active use of the public methods of this component. This method should be the last one called on a given instance of this component.

Specified by:

stop in interface Lifecycle

Throws:

LifecycleException - if this component detects a fatal error that needs to be reported

propertyChange

public void propertyChange(PropertyChangeEvent event)

Process property change events from our associated Context.

Specified by:

propertyChange in interface PropertyChangeListener

Parameters:

event - The property change event that has occurred

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 Hercules: modified method

processMaxIdleBackups

protected void processMaxIdleBackups()

Back up idle sessions. Hercules: modified method

getMonitorAttributeValues

public String getMonitorAttributeValues()