org.apache.catalina.session

Class PersistentManagerBase

Implemented Interfaces:
Lifecycle, MBeanRegistration, PropertyChangeListener, Manager
Known Direct Subclasses:
PersistentManager

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 onlyfor 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.19.2.1 $ $Date: 2004/11/18 22:13:36 $

Authors:
Craig R. McClanahan
Jean-Francois Arcand

Field Summary

protected int
expiredSessions
Number of sessions that expired.
protected LifecycleSupport
lifecycle
The lifecycle event support for this component.
protected int
maxActiveSessions
The maximum number of active Sessions allowed, or -1 for no limit.
protected int
maxIdleBackup
How long a session must be idle before it should be backed up.
protected int
maxIdleSwap
The maximum time a session may be idle before it should be swapped to file just on general principle.
protected int
minIdleSwap
Minimum time a session must be idle before it is swapped to disk.
protected long
processingTime
Processing time during session expiration and passivation.
protected int
rejectedSessions
Number of session creations that failed due to maxActiveSessions.
protected boolean
saveOnRestart
Whether to save and reload sessions when the Manager unload and load methods are called.
protected boolean
started
Has this component been started yet?
protected Store
store
Store object which will manage the Session store.

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

DEFAULT_ALGORITHM, algorithm, container, debug, defaultContext, devRandomSource, digest, distributable, domain, duplicates, entropy, initialized, log, maxActive, maxInactiveInterval, mserver, name, oname, random, randomClass, randomIS, sessionCounter, sessionIdLength, sessions, sm, support

Fields inherited from interface org.apache.catalina.Lifecycle

AFTER_START_EVENT, AFTER_STOP_EVENT, BEFORE_START_EVENT, BEFORE_STOP_EVENT, START_EVENT, STOP_EVENT

Method Summary

void
addLifecycleListener(LifecycleListener listener)
Add a lifecycle event listener to this component.
void
backgroundProcess()
Perform the background processes for this Manager
void
clearStore()
Clear all sessions from the Store.
LifecycleListener[]
findLifecycleListeners()
Get the lifecycle listeners associated with this lifecycle.
Session
findSession(String id)
Return the active Session, associated with this Manager, with the specified session id (if any); otherwise return null.
int
getExpiredSessions()
Number of sessions that expired.
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
getName()
Return the descriptive short name of this Manager implementation.
long
getProcessingTime()
int
getRejectedSessions()
Number of session creations that failed due to maxActiveSessions.
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
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.
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
propertyChange(PropertyChangeEvent event)
Process property change events from our associated Context.
void
remove(Session session)
Remove this Session from the active Sessions for this Manager, and from the Store.
void
removeLifecycleListener(LifecycleListener listener)
Remove a lifecycle event listener from this component.
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
setContainer(Container container)
Set the Container with which this Manager has been associated.
void
setExpiredSessions(int expiredSessions)
void
setMaxActiveSessions(int max)
Set the maximum number of actives 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
setProcessingTime(long processingTime)
void
setRejectedSessions(int rejectedSessions)
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
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, createEmptySession, createSession, destroy, expireSession, findSession, findSessions, generateSessionId, getActiveSessions, getAlgorithm, getClassName, getContainer, getDebug, getDefaultContext, getDigest, getDistributable, getDomain, getDuplicates, getEngine, getEntropy, getInfo, getJvmRoute, getLastAccessedTime, getMaxActive, getMaxInactiveInterval, getName, getNewSession, getObjectName, getRandom, getRandomBytes, getRandomClass, getRandomFile, getSessionAttribute, getSessionCounter, getSessionIdLength, init, listSessionIds, log, log, postDeregister, postRegister, preDeregister, preRegister, remove, removePropertyChangeListener, setAlgorithm, setContainer, setDebug, setDefaultContext, setDistributable, setDuplicates, setEntropy, setMaxActive, setMaxInactiveInterval, setRandomClass, setRandomFile, setSessionCounter, setSessionIdLength

Field Details

expiredSessions

protected int expiredSessions
Number of sessions that expired.


lifecycle

protected LifecycleSupport lifecycle
The lifecycle event support for this component.


maxActiveSessions

protected int maxActiveSessions
The maximum number of active Sessions allowed, or -1 for no limit.


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.


maxIdleSwap

protected int maxIdleSwap
The maximum time a session may be idle before it should be swapped to file just on general principle. Setting this to -1 means sessions should not be forced out.


minIdleSwap

protected int minIdleSwap
Minimum time a session must be idle before it is swapped to disk. This overrides maxActiveSessions, to prevent thrashing if there are lots of active sessions. Setting to -1 means it's ignored.


processingTime

protected long processingTime
Processing time during session expiration and passivation.


rejectedSessions

protected int rejectedSessions
Number of session creations that failed due to maxActiveSessions.


saveOnRestart

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


started

protected boolean started
Has this component been started yet?


store

protected Store store
Store object which will manage the Session store.

Method Details

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


backgroundProcess

public void backgroundProcess()
Perform the background processes for this Manager
Specified by:
backgroundProcess in interface Manager
Overrides:
backgroundProcess in interface ManagerBase


clearStore

public void clearStore()
Clear all sessions from the Store.


findLifecycleListeners

public LifecycleListener[] findLifecycleListeners()
Get the lifecycle listeners associated with this lifecycle. If this Lifecycle has no listeners registered, a zero-length array is returned.
Specified by:
findLifecycleListeners in interface Lifecycle


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 interface ManagerBase

Parameters:
id - The session id for the session to be returned


getExpiredSessions

public int getExpiredSessions()
Number of sessions that expired.
Specified by:
getExpiredSessions in interface Manager

Returns:
The count


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 interface ManagerBase


getMaxActiveSessions

public int getMaxActiveSessions()
Return the maximum number of active Sessions allowed, or -1 for no limit.


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.


getMaxIdleSwap

public int getMaxIdleSwap()
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.


getName

public String getName()
Return the descriptive short name of this Manager implementation.
Overrides:
getName in interface ManagerBase


getProcessingTime

public long getProcessingTime()


getRejectedSessions

public int getRejectedSessions()
Number of session creations that failed due to maxActiveSessions.
Specified by:
getRejectedSessions in interface Manager

Returns:
The count


getSaveOnRestart

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


getStore

public Store getStore()
Return the Store object which manages persistent Session storage for this Manager.


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


isStarted

protected boolean isStarted()
Get the started status.


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


processExpires

public void processExpires()
Invalidate all sessions that have expired.


processMaxActiveSwaps

protected void processMaxActiveSwaps()
Swap idle sessions out to Store if too many are active


processMaxIdleBackups

protected void processMaxIdleBackups()
Back up idle sessions.


processMaxIdleSwaps

protected void processMaxIdleSwaps()
Swap idle sessions out to Store if they are idle too long.


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.


propertyChange

public void propertyChange(PropertyChangeEvent event)
Process property change events from our associated Context.

Parameters:
event - The property change event that has occurred


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 interface ManagerBase

Parameters:
session - Session to be removed


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


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


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


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 interface ManagerBase

Parameters:
container - The associated Container


setExpiredSessions

public void setExpiredSessions(int expiredSessions)
Specified by:
setExpiredSessions in interface Manager


setMaxActiveSessions

public void setMaxActiveSessions(int max)
Set the maximum number of actives Sessions allowed, or -1 for no limit.

Parameters:
max - The new maximum number of sessions


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.


setMaxIdleSwap

public void setMaxIdleSwap(int max)
Sets the time in seconds after which a session should be swapped out of memory to disk.


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.


setProcessingTime

public void setProcessingTime(long processingTime)


setRejectedSessions

public void setRejectedSessions(int rejectedSessions)
Specified by:
setRejectedSessions in interface Manager


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.


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


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


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.


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.


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


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.


Copyright B) 2000-2003 Apache Software Foundation. All Rights Reserved.