PersistentManagerBase (Apache Tomcat 10.1.16 API Documentation)
Description: declaration: package: org.apache.catalina.session, class: PersistentManagerBase

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

  `duplicates, expiredSessions, maxActive, maxActiveSessions, processExpiresFrequency, processingTime, rejectedSessions, secureRandomAlgorithm, secureRandomClass, secureRandomProvider, sessionCounter, 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, getDuplicates, 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, setDuplicates, setExpiredSessions, setMaxActive, setMaxActiveSessions, setNotifyAttributeListenerOnUnchangedValue, setNotifyBindingListenerOnUnchangedValue, setPersistAuthentication, setProcessExpiresFrequency, setProcessingTime, setSecureRandomAlgorithm, setSecureRandomClass, setSecureRandomProvider, setSessionActivityCheck, setSessionAttributeNameFilter, setSessionAttributeValueClassNameFilter, setSessionCounter, 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)
    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.