Manager (Apache Tomcat 11.0.25 API Documentation)
Description: declaration: package: org.apache.catalina, interface: Manager

# Interface Manager

All Known Subinterfaces:
  `ClusterManager`

All Known Implementing Classes:
  `BackupManager, ClusterManagerBase, DeltaManager, ManagerBase, PersistentManager, PersistentManagerBase, StandardManager`

public interface Manager
A Manager manages the pool of Sessions that are associated with a particular Context. Different Manager implementations may support value-added features such as the persistent storage of session data, as well as migrating sessions for distributable web applications.

In order for a `Manager` implementation to successfully operate with a `Context` implementation that implements reloading, it must obey the following constraints:

- Must implement `Lifecycle` so that the Context can indicate that a restart is required.
- Must allow a call to `stop()` to be followed by a call to `start()` on the same `Manager` instance.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `add(Session session)`
  Add this Session to the set of active Sessions for this Manager.
  `void`
  `addPropertyChangeListener(PropertyChangeListener listener)`
  Add a property change listener to this component.
  `void`
  `backgroundProcess()`
  This method will be invoked by the context/container on a periodic basis and allows the manager to implement a method that executes periodic tasks, such as expiring sessions etc.
  `void`
  `changeSessionId(Session session, String newId)`
  Change the session ID of the current session to a specified session ID.
  `Session`
  `createEmptySession()`
  Get a session from the recycled ones or create a new empty one.
  `Session`
  `createSession(String sessionId)`
  Construct and return a new session object, based on the default settings specified by this Manager's properties.
  `Session`
  `findSession(String id)`
  Return the active Session, associated with this Manager, with the specified session id (if any); otherwise return `null`.
  `Session[]`
  `findSessions()`
  Return the set of active Sessions associated with this Manager.
  `int`
  `getActiveSessions()`
  Gets the number of currently active sessions.
  `Context`
  `getContext()`
  Get the Context with which this Manager is associated.
  `long`
  `getExpiredSessions()`
  Gets the number of sessions that have expired.
  `int`
  `getMaxActive()`
  Gets the maximum number of sessions that have been active at the same time.
  `default boolean`
  `getNotifyAttributeListenerOnUnchangedValue()`
  When an attribute that is already present in the session is added again under the same name and a `HttpSessionAttributeListener` is configured for the session should `HttpSessionAttributeListener.attributeReplaced(jakarta.servlet.http.HttpSessionBindingEvent)` be called?
  `default boolean`
  `getNotifyBindingListenerOnUnchangedValue()`
  When an attribute that is already present in the session is added again under the same name and the attribute implements `HttpSessionBindingListener`, should `HttpSessionBindingListener.valueUnbound(jakarta.servlet.http.HttpSessionBindingEvent)` be called followed by `HttpSessionBindingListener.valueBound(jakarta.servlet.http.HttpSessionBindingEvent)`?
  `int`
  `getRejectedSessions()`
  Gets the number of sessions that were not created because the maximum number of active sessions was reached.
  `default boolean`
  `getSessionActivityCheck()`
  If this is `true`, Tomcat will track the number of active requests for each session.
  `int`
  `getSessionAverageAliveTime()`
  Gets the average time (in seconds) that expired sessions had been alive.
  `long`
  `getSessionCounter()`
  Returns the total number of sessions created by this manager, which is approximated as the number of active sessions plus the number of expired sessions.
  `int`
  `getSessionCreateRate()`
  Gets the current rate of session creation (in session per minute).
  `int`
  `getSessionExpireRate()`
  Gets the current rate of session expiration (in session per minute).
  `SessionIdGenerator`
  `getSessionIdGenerator()`
  Returns the session id generator for this manager.
  `default boolean`
  `getSessionLastAccessAtStart()`
  If this is `true`, the last accessed time for sessions will be calculated from the beginning of the previous request.
  `int`
  `getSessionMaxAliveTime()`
  Gets the longest time (in seconds) that an expired session had been alive.
  `void`
  `load()`
  Load any currently active sessions that were previously unloaded to the appropriate persistence mechanism, if any.
  `void`
  `remove(Session session)`
  Remove this Session from the active Sessions for this Manager.
  `void`
  `remove(Session session, boolean update)`
  Remove this Session from the active Sessions for this Manager.
  `void`
  `removePropertyChangeListener(PropertyChangeListener listener)`
  Remove a property change listener from this component.
  `default String`
  `rotateSessionId(Session session)`
  Change the session ID of the current session to a new randomly generated session ID.
  `void`
  `setContext(Context context)`
  Set the Context with which this Manager is associated.
  `void`
  `setExpiredSessions(long expiredSessions)`
  Sets the number of sessions that have expired.
  `void`
  `setMaxActive(int maxActive)`
  (Re)sets the maximum number of sessions that have been active at the same time.
  `void`
  `setNotifyAttributeListenerOnUnchangedValue(boolean notifyAttributeListenerOnUnchangedValue)`
  Configure if `HttpSessionAttributeListener.attributeReplaced(jakarta.servlet.http.HttpSessionBindingEvent)` when an attribute that is already present in the session is added again under the same name and a `HttpSessionAttributeListener` is configured for the session.
  `void`
  `setNotifyBindingListenerOnUnchangedValue(boolean notifyBindingListenerOnUnchangedValue)`
  Configure if `HttpSessionBindingListener.valueUnbound(jakarta.servlet.http.HttpSessionBindingEvent)` be called followed by `HttpSessionBindingListener.valueBound(jakarta.servlet.http.HttpSessionBindingEvent)` when an attribute that is already present in the session is added again under the same name and the attribute implements `HttpSessionBindingListener`.
  `void`
  `setSessionActivityCheck(boolean sessionActivityCheck)`
  Configure if Tomcat will track the number of active requests for each session.
  `void`
  `setSessionIdGenerator(SessionIdGenerator sessionIdGenerator)`
  Sets the session id generator
  `void`
  `setSessionLastAccessAtStart(boolean sessionLastAccessAtStart)`
  Configure if the last accessed time for sessions will be calculated from the beginning of the previous request.
  `void`
  `setSessionMaxAliveTime(int sessionMaxAliveTime)`
  Sets the longest time (in seconds) that an expired session had been alive.
  `void`
  `unload()`
  Save any currently active sessions in the appropriate persistence mechanism, if any.
  `boolean`
  `willAttributeDistribute(String name, Object value)`
  Would the Manager distribute the given session attribute?

- ## Method Details

  - ### getContext

    Context getContext()
    Get the Context with which this Manager is associated.
    Returns:
      The associated Context

  - ### setContext

    void setContext(Context context)
    Set the Context with which this Manager is associated. The Context must be set to a non-null value before the Manager is first used. Multiple calls to this method before first use are permitted. Once the Manager has been used, this method may not be used to change the Context (including setting a `null` value) that the Manager is associated with.
    Parameters:
      `context` - The newly associated Context

  - ### getSessionIdGenerator

    SessionIdGenerator getSessionIdGenerator()
    Returns the session id generator for this manager.
    Returns:
      the session id generator

  - ### setSessionIdGenerator

    void setSessionIdGenerator(SessionIdGenerator sessionIdGenerator)
    Sets the session id generator
    Parameters:
      `sessionIdGenerator` - The session id generator

  - ### getSessionCounter

    long getSessionCounter()
    Returns the total number of sessions created by this manager, which is approximated as the number of active sessions plus the number of expired sessions.
    Returns:
      Total number of sessions created by this manager.

  - ### getMaxActive

    int getMaxActive()
    Gets the maximum number of sessions that have been active at the same time.
    Returns:
      Maximum number of sessions that have been active at the same time

  - ### setMaxActive

    void setMaxActive(int maxActive)
    (Re)sets the maximum number of sessions that have been active at the same time.
    Parameters:
      `maxActive` - Maximum number of sessions that have been active at the same time.

  - ### getActiveSessions

    int getActiveSessions()
    Gets the number of currently active sessions.
    Returns:
      Number of currently active sessions

  - ### getExpiredSessions

    long getExpiredSessions()
    Gets the number of sessions that have expired.
    Returns:
      Number of sessions that have expired

  - ### setExpiredSessions

    void setExpiredSessions(long expiredSessions)
    Sets the number of sessions that have expired.
    Parameters:
      `expiredSessions` - Number of sessions that have expired

  - ### getRejectedSessions

    int getRejectedSessions()
    Gets the number of sessions that were not created because the maximum number of active sessions was reached.
    Returns:
      Number of rejected sessions

  - ### getSessionMaxAliveTime

    int getSessionMaxAliveTime()
    Gets the longest time (in seconds) that an expired session had been alive.
    Returns:
      Longest time (in seconds) that an expired session had been alive.

  - ### setSessionMaxAliveTime

    void setSessionMaxAliveTime(int sessionMaxAliveTime)
    Sets the longest time (in seconds) that an expired session had been alive.
    Parameters:
      `sessionMaxAliveTime` - Longest time (in seconds) that an expired session had been alive.

  - ### getSessionAverageAliveTime

    int getSessionAverageAliveTime()
    Gets the average time (in seconds) that expired sessions had been alive. This may be based on sample data.
    Returns:
      Average time (in seconds) that expired sessions had been alive.

  - ### getSessionCreateRate

    int getSessionCreateRate()
    Gets the current rate of session creation (in session per minute). This may be based on sample data.
    Returns:
      The current rate (in sessions per minute) of session creation

  - ### getSessionExpireRate

    int getSessionExpireRate()
    Gets the current rate of session expiration (in session per minute). This may be based on sample data
    Returns:
      The current rate (in sessions per minute) of session expiration

  - ### add

    void add(Session session)
    Add this Session to the set of active Sessions for this Manager.
    Parameters:
      `session` - Session to be added

  - ### addPropertyChangeListener

    void addPropertyChangeListener(PropertyChangeListener listener)
    Add a property change listener to this component.
    Parameters:
      `listener` - The listener to add

  - ### rotateSessionId

    default String rotateSessionId(Session session)
    Change the session ID of the current session to a new randomly generated session ID.
    Parameters:
      `session` - The session to change the session ID for
    Returns:
      The new session ID

  - ### changeSessionId

    void changeSessionId(Session session, String newId)
    Change the session ID of the current session to a specified session ID.
    Parameters:
      `session` - The session to change the session ID for
      `newId` - new session ID

  - ### createEmptySession

    Session createEmptySession()
    Get a session from the recycled ones or create a new empty one. The PersistentManager manager does not need to create session data because it reads it from the Store.
    Returns:
      An empty Session object

  - ### createSession

    Session createSession(String sessionId)
    Construct and return a new session object, based on the default settings specified by this Manager's properties. The session id specified will be used as the session id. If a new session cannot be created for any reason, return `null`.
    Parameters:
      `sessionId` - The session id which should be used to create the new session; if `null`, the session id will be assigned by this method, and available via the getId() method of the returned session.
    Returns:
      An empty Session object with the given ID or a newly created session ID if none was specified
    Throws:
      `IllegalStateException` - if a new session cannot be instantiated for any reason

  - ### findSession

    Session findSession(String id) throws IOException
    Return the active Session, associated with this Manager, with the specified session id (if any); otherwise return `null`.
    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:
      `IllegalStateException` - if a new session cannot be instantiated for any reason
      `IOException` - if an input/output error occurs while processing this request

  - ### findSessions

    Session[] findSessions()
    Return the set of active Sessions associated with this Manager. If this Manager has no active Sessions, a zero-length array is returned.
    Returns:
      All the currently active sessions managed by this manager

  - ### load

    void load() throws ClassNotFoundException, IOException
    Load any currently active sessions that were previously unloaded to the appropriate persistence mechanism, if any. If persistence is not supported, this method returns without doing anything.
    Throws:
      `ClassNotFoundException` - if a serialized class cannot be found during the reload
      `IOException` - if an input/output error occurs

  - ### remove

    void remove(Session session)
    Remove this Session from the active Sessions for this Manager.
    Parameters:
      `session` - Session to be removed

  - ### remove

    void remove(Session session, boolean update)
    Remove this Session from the active Sessions for this Manager.
    Parameters:
      `session` - Session to be removed
      `update` - Should the expiration statistics be updated

  - ### removePropertyChangeListener

    void removePropertyChangeListener(PropertyChangeListener listener)
    Remove a property change listener from this component.
    Parameters:
      `listener` - The listener to remove

  - ### unload

    void unload() throws IOException
    Save any currently active sessions in the appropriate persistence mechanism, if any. If persistence is not supported, this method returns without doing anything.
    Throws:
      `IOException` - if an input/output error occurs

  - ### backgroundProcess

    void backgroundProcess()
    This method will be invoked by the context/container on a periodic basis and allows the manager to implement a method that executes periodic tasks, such as expiring sessions etc.

  - ### willAttributeDistribute

    boolean willAttributeDistribute(String name, Object value)
    Would the Manager distribute the given session attribute? Manager implementations may provide additional configuration options to control which attributes are distributable.
    Parameters:
      `name` - The attribute name
      `value` - The attribute value
    Returns:
      `true` if the Manager would distribute the given attribute otherwise `false`

  - ### getNotifyBindingListenerOnUnchangedValue

    default boolean getNotifyBindingListenerOnUnchangedValue()
    When an attribute that is already present in the session is added again under the same name and the attribute implements `HttpSessionBindingListener`, should `HttpSessionBindingListener.valueUnbound(jakarta.servlet.http.HttpSessionBindingEvent)` be called followed by `HttpSessionBindingListener.valueBound(jakarta.servlet.http.HttpSessionBindingEvent)`?

    The default value is `false`.

    Returns:
      `true` if the listener will be notified, `false` if it will not

  - ### setNotifyBindingListenerOnUnchangedValue

    void setNotifyBindingListenerOnUnchangedValue(boolean notifyBindingListenerOnUnchangedValue)
    Configure if `HttpSessionBindingListener.valueUnbound(jakarta.servlet.http.HttpSessionBindingEvent)` be called followed by `HttpSessionBindingListener.valueBound(jakarta.servlet.http.HttpSessionBindingEvent)` when an attribute that is already present in the session is added again under the same name and the attribute implements `HttpSessionBindingListener`.
    Parameters:
      `notifyBindingListenerOnUnchangedValue` - `true` the listener will be called, `false` it will not

  - ### getNotifyAttributeListenerOnUnchangedValue

    default boolean getNotifyAttributeListenerOnUnchangedValue()
    When an attribute that is already present in the session is added again under the same name and a `HttpSessionAttributeListener` is configured for the session should `HttpSessionAttributeListener.attributeReplaced(jakarta.servlet.http.HttpSessionBindingEvent)` be called?

    The default value is `true`.

    Returns:
      `true` if the listener will be notified, `false` if it will not

  - ### setNotifyAttributeListenerOnUnchangedValue

    void setNotifyAttributeListenerOnUnchangedValue(boolean notifyAttributeListenerOnUnchangedValue)
    Configure if `HttpSessionAttributeListener.attributeReplaced(jakarta.servlet.http.HttpSessionBindingEvent)` when an attribute that is already present in the session is added again under the same name and a `HttpSessionAttributeListener` is configured for the session.
    Parameters:
      `notifyAttributeListenerOnUnchangedValue` - `true` the listener will be called, `false` it will not

  - ### getSessionActivityCheck

    default boolean getSessionActivityCheck()
    If this is `true`, Tomcat will track the number of active requests for each session. When determining if a session is valid, any session with at least one active request will always be considered valid. If `org.apache.catalina.STRICT_SERVLET_COMPLIANCE` is set to `true`, the default of this setting will be `true`, else the default value will be `false`.
    Returns:
      the flag value

  - ### setSessionActivityCheck

    void setSessionActivityCheck(boolean sessionActivityCheck)
    Configure if Tomcat will track the number of active requests for each session. When determining if a session is valid, any session with at least one active request will always be considered valid.
    Parameters:
      `sessionActivityCheck` - the new flag value

  - ### getSessionLastAccessAtStart

    default boolean getSessionLastAccessAtStart()
    If this is `true`, the last accessed time for sessions will be calculated from the beginning of the previous request. If `false`, the last accessed time for sessions will be calculated from the end of the previous request. This also affects how the idle time is calculated. If `org.apache.catalina.STRICT_SERVLET_COMPLIANCE` is set to `true`, the default of this setting will be `true`, else the default value will be `false`.
    Returns:
      the flag value

  - ### setSessionLastAccessAtStart

    void setSessionLastAccessAtStart(boolean sessionLastAccessAtStart)
    Configure if the last accessed time for sessions will be calculated from the beginning of the previous request. If `false`, the last accessed time for sessions will be calculated from the end of the previous request. This also affects how the idle time is calculated.
    Parameters:
      `sessionLastAccessAtStart` - the new flag value