Package org.apache.catalina

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.

Author:

Craig R. McClanahan

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()
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	setSessionCounter(long sessionCounter)	Deprecated. This will be removed in Tomcat 11
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

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.

setSessionCounter

@Deprecated
void setSessionCounter(long sessionCounter)

Deprecated.

This will be removed in Tomcat 11

Sets the total number of sessions created by this manager.

Parameters:

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