## org.apache.catalina.session
Class PersistentManagerBase

    java.lang.Object
      org.apache.catalina.session.ManagerBase
          org.apache.catalina.session.PersistentManagerBase

All Implemented Interfaces:
  java.beans.PropertyChangeListener, java.util.EventListener, javax.management.MBeanRegistration, Lifecycle, Manager

Direct Known Subclasses:
  PersistentManager

    public abstract class PersistentManagerBase

extends ManagerBase
implements Lifecycle, java.beans.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: 656751 $ $Date: 2008-05-15 19:27:50 +0200 (Thu, 15 May 2008) $
Author:
  Craig R. McClanahan, Jean-Francois Arcand

Field Summary
`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
`algorithm, container, DEFAULT_ALGORITHM, devRandomSource, digest, distributable, domain, duplicates, entropy, expiredSessions, initialized, maxActive, maxInactiveInterval, mserver, oname, processExpiresFrequency, random, randomClass, randomIS, sessionAverageAliveTime, sessionCounter, sessionIdLength, sessionMaxAliveTime, sessions, sm, support`

Fields inherited from interface org.apache.catalina.Lifecycle
`AFTER_START_EVENT, AFTER_STOP_EVENT, BEFORE_START_EVENT, BEFORE_STOP_EVENT, DESTROY_EVENT, INIT_EVENT, PERIODIC_EVENT, START_EVENT, STOP_EVENT`

Constructor Summary
`PersistentManagerBase()`

Method Summary
`void` `addLifecycleListener(LifecycleListener listener)` Add a lifecycle event listener to this component.
`void` `clearStore()` Clear all sessions from the Store.
`LifecycleListener[]` `findLifecycleListeners()` Get the lifecycle listeners associated with this lifecycle.
`Session` `findSession(java.lang.String id)` Return the active Session, associated with this Manager, with the specified session id (if any); otherwise return `null`.
`java.lang.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. -1 means sessions are not backed up.
`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.
`java.lang.String` `getName()` Return the descriptive short name of this Manager implementation.
`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(java.lang.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()` Implements the Manager interface, direct call to processExpires and processPersistenceChecks
`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(java.beans.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(java.lang.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` `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` `setRejectedSessions(int rejectedSessions)` Sets the number of sessions that were not created because the maximum number of active sessions was reached.
`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(java.lang.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, createSession, destroy, expireSession, findSessions, generateSessionId, getActiveSessions, getAlgorithm, getClassName, getContainer, getCreationTime, getCreationTimestamp, getDigest, getDistributable, getDomain, getDuplicates, getEngine, getEntropy, getExpiredSessions, getJvmRoute, getLastAccessedTime, getLastAccessedTimestamp, getMaxActive, getMaxInactiveInterval, getNewSession, getObjectName, getProcessExpiresFrequency, getProcessingTime, getRandom, getRandomBytes, getRandomClass, getRandomFile, getSession, getSessionAttribute, getSessionAverageAliveTime, getSessionCounter, getSessionIdLength, getSessionMaxAliveTime, init, listSessionIds, postDeregister, postRegister, preDeregister, preRegister, removePropertyChangeListener, setAlgorithm, setDistributable, setDuplicates, setEntropy, setExpiredSessions, setMaxActive, setMaxInactiveInterval, setProcessExpiresFrequency, setProcessingTime, setRandomClass, setRandomFile, setSessionAverageAliveTime, setSessionCounter, setSessionIdLength, setSessionMaxAliveTime`

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.

### maxActiveSessions

    protected int maxActiveSessions

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

### started

    protected boolean started

  Has this component been started yet?

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

  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.

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

### rejectedSessions

    protected int rejectedSessions

  Number of session creations that failed due to maxActiveSessions.

### processingTime

    protected long processingTime

  Processing time during session expiration and passivation.

Constructor Detail

### PersistentManagerBase

    public PersistentManagerBase()

Method Detail

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

  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 java.lang.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(java.lang.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

### 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 actives Sessions allowed, or -1 for no limit.

  Parameters:
    `max` - The new maximum number of sessions

### getRejectedSessions

    public int getRejectedSessions()

  Number of session creations that failed due to maxActiveSessions.

  Specified by:
    `getRejectedSessions` in interface `Manager`
  Returns:
    The count

### setRejectedSessions

    public void setRejectedSessions(int rejectedSessions)

  Description copied from interface: `Manager`
  Sets the number of sessions that were not created because the maximum number of active sessions was reached.

  Specified by:
    `setRejectedSessions` in interface `Manager`
  Parameters:
    `rejectedSessions` - Number of rejected sessions

### getName

    public java.lang.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.

### clearStore

    public void clearStore()

  Clear all sessions from the Store.

### processExpires

    public void processExpires()

  Implements the Manager interface, 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(java.lang.String id)
                        throws java.io.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:
    `java.lang.IllegalStateException` - if a new session cannot be instantiated for any reason
    `java.io.IOException` - if an input/output error occurs while processing this request

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

### removeSession

    protected void removeSession(java.lang.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`

### swapIn

    protected Session swapIn(java.lang.String id)
                      throws java.io.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:
    `java.io.IOException`

### swapOut

    protected void swapOut(Session session)
                    throws java.io.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:
    `java.io.IOException`

### writeSession

    protected void writeSession(Session session)
                         throws java.io.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:
    `java.io.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 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`

### 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(java.beans.PropertyChangeEvent event)

  Process property change events from our associated Context.

  Specified by:
    `propertyChange` in interface `java.beans.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

### processMaxIdleBackups

    protected void processMaxIdleBackups()

  Back up idle sessions.

Copyright © 2000-2008 Apache Software Foundation. All Rights Reserved.