Top Description Methods
org.apache.catalina

public Interface Manager

Known Direct Implementers
org.apache.catalina.session.ManagerBase
Imports
java.beans.PropertyChangeListener, java.io.IOException

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:

Author
Craig R. McClanahan

Method Summary

Modifier and TypeMethod and Description
public void
add(Session
Session to be added
session
)

Add this Session to the set of active Sessions for this Manager.

public void
addPropertyChangeListener(PropertyChangeListener
The listener to add
listener
)

Add a property change listener to this component.

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

public void
changeSessionId(Session
The session to change the session ID for
session
,
String
new session ID
newId
)

Change the session ID of the current session to a specified session ID.

public Session

Returns:

An empty Session object
createEmptySession
()

Get a session from the recycled ones or create a new empty one.

public Session

Returns:

An empty Session object with the given ID or a newly created session ID if none was specified
createSession
(String
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.
sessionId
)

Construct and return a new session object, based on the default settings specified by this Manager's properties.

public Session

Returns:

the request session or null if a session with the requested ID could not be found
findSession
(String
The session id for the session to be returned
id
)

Return the active Session, associated with this Manager, with the specified session id (if any); otherwise return null.

public Session[]

Returns:

All the currently active sessions managed by this manager
findSessions
()

Return the set of active Sessions associated with this Manager.

public int

Returns:

Number of currently active sessions
getActiveSessions
()

Gets the number of currently active sessions.

public Context

Returns:

The associated Context
getContext
()

Get the Context with which this Manager is associated.

public long

Returns:

Number of sessions that have expired
getExpiredSessions
()

Gets the number of sessions that have expired.

public int

Returns:

Maximum number of sessions that have been active at the same time
getMaxActive
()

Gets the maximum number of sessions that have been active at the same time.

public default boolean

Returns:

true if the listener will be notified, false if it will not
getNotifyAttributeListenerOnUnchangedValue
()

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

public default boolean

Returns:

true if the listener will be notified, false if it will not
getNotifyBindingListenerOnUnchangedValue
()

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

public int

Returns:

Number of rejected sessions
getRejectedSessions
()

Gets the number of sessions that were not created because the maximum number of active sessions was reached.

public default boolean

Returns:

the flag value
getSessionActivityCheck
()

If this is true, Tomcat will track the number of active requests for each session.

public int

Returns:

Average time (in seconds) that expired sessions had been alive.
getSessionAverageAliveTime
()

Gets the average time (in seconds) that expired sessions had been alive.

public long

Returns:

Total number of sessions created by this manager.
getSessionCounter
()

Returns the total number of sessions created by this manager.

public int

Returns:

The current rate (in sessions per minute) of session creation
getSessionCreateRate
()

Gets the current rate of session creation (in session per minute).

public int

Returns:

The current rate (in sessions per minute) of session expiration
getSessionExpireRate
()

Gets the current rate of session expiration (in session per minute).

public SessionIdGenerator

Returns:

the session id generator
getSessionIdGenerator
()

public default boolean

Returns:

the flag value
getSessionLastAccessAtStart
()

If this is true, the last accessed time for sessions will be calculated from the beginning of the previous request.

public int

Returns:

Longest time (in seconds) that an expired session had been alive.
getSessionMaxAliveTime
()

Gets the longest time (in seconds) that an expired session had been alive.

public void
load()

Load any currently active sessions that were previously unloaded to the appropriate persistence mechanism, if any.

public void
remove(Session
Session to be removed
session
)

Remove this Session from the active Sessions for this Manager.

public void
remove(Session
Session to be removed
session
,
boolean
Should the expiration statistics be updated
update
)

Remove this Session from the active Sessions for this Manager.

public void
removePropertyChangeListener(PropertyChangeListener
The listener to remove
listener
)

Remove a property change listener from this component.

public default String

Returns:

The new session ID
rotateSessionId
(Session
The session to change the session ID for
session
)

Change the session ID of the current session to a new randomly generated session ID.

public void
setContext(Context
The newly associated Context
context
)

Set the Context with which this Manager is associated.

public void
setExpiredSessions(long
Number of sessions that have expired
expiredSessions
)

Sets the number of sessions that have expired.

public void
setMaxActive(int
Maximum number of sessions that have been active at the same time.
maxActive
)

(Re)sets the maximum number of sessions that have been active at the same time.

public void
setNotifyAttributeListenerOnUnchangedValue(boolean
true the listener will be called, false it will not
notifyAttributeListenerOnUnchangedValue
)

Configure if jakarta.servlet.http.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 jakarta.servlet.http.HttpSessionAttributeListener is configured for the session.

public void
setNotifyBindingListenerOnUnchangedValue(boolean
true the listener will be called, false it will not
notifyBindingListenerOnUnchangedValue
)

Configure if jakarta.servlet.http.HttpSessionBindingListener#valueUnbound(jakarta.servlet.http.HttpSessionBindingEvent) be called followed by jakarta.servlet.http.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 jakarta.servlet.http.HttpSessionBindingListener.

public void
setSessionActivityCheck(boolean
the new flag value
sessionActivityCheck
)

Configure if Tomcat will track the number of active requests for each session.

public void
setSessionCounter(long
Total number of sessions created by this manager.
sessionCounter
)

Sets the total number of sessions created by this manager.

public void
setSessionIdGenerator(SessionIdGenerator
The session id generator
sessionIdGenerator
)

Sets the session id generator

public void
setSessionLastAccessAtStart(boolean
the new flag value
sessionLastAccessAtStart
)

Configure if the last accessed time for sessions will be calculated from the beginning of the previous request.

public void
setSessionMaxAliveTime(int
Longest time (in seconds) that an expired session had been alive.
sessionMaxAliveTime
)

Sets the longest time (in seconds) that an expired session had been alive.

public void
unload()

Save any currently active sessions in the appropriate persistence mechanism, if any.

public boolean

Returns:

true if the Manager would distribute the given attribute otherwise false
willAttributeDistribute
(String
The attribute name
name
,
Object
The attribute value
value
)

Would the Manager distribute the given session attribute?

Method Detail

addback to summary
public void add(Session session)

Add this Session to the set of active Sessions for this Manager.

Parameters
session:Session

Session to be added

addPropertyChangeListenerback to summary
public void addPropertyChangeListener(PropertyChangeListener listener)

Add a property change listener to this component.

Parameters
listener:PropertyChangeListener

The listener to add

backgroundProcessback to summary
public 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.

changeSessionIdback to summary
public void changeSessionId(Session session, String newId)

Change the session ID of the current session to a specified session ID.

Parameters
session:Session

The session to change the session ID for

newId:String

new session ID

createEmptySessionback to summary
public 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:Session

An empty Session object

createSessionback to summary
public 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:String

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:Session

An empty Session object with the given ID or a newly created session ID if none was specified

Exceptions
IllegalStateException:
if a new session cannot be instantiated for any reason
findSessionback to summary
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.

Parameters
id:String

The session id for the session to be returned

Returns:Session

the request session or null if a session with the requested ID could not be found

Exceptions
IOException:
if an input/output error occurs while processing this request
IllegalStateException:
if a new session cannot be instantiated for any reason
findSessionsback to summary
public 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:Session[]

All the currently active sessions managed by this manager

getActiveSessionsback to summary
public int getActiveSessions()

Gets the number of currently active sessions.

Returns:int

Number of currently active sessions

getContextback to summary
public Context getContext()

Get the Context with which this Manager is associated.

Returns:Context

The associated Context

getExpiredSessionsback to summary
public long getExpiredSessions()

Gets the number of sessions that have expired.

Returns:long

Number of sessions that have expired

getMaxActiveback to summary
public int getMaxActive()

Gets the maximum number of sessions that have been active at the same time.

Returns:int

Maximum number of sessions that have been active at the same time

getNotifyAttributeListenerOnUnchangedValueback to summary
public default boolean getNotifyAttributeListenerOnUnchangedValue()

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

The default value is true.

Returns:boolean

true if the listener will be notified, false if it will not

getNotifyBindingListenerOnUnchangedValueback to summary
public default boolean getNotifyBindingListenerOnUnchangedValue()

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

The default value is false.

Returns:boolean

true if the listener will be notified, false if it will not

getRejectedSessionsback to summary
public int getRejectedSessions()

Gets the number of sessions that were not created because the maximum number of active sessions was reached.

Returns:int

Number of rejected sessions

getSessionActivityCheckback to summary
public 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:boolean

the flag value

getSessionAverageAliveTimeback to summary
public int getSessionAverageAliveTime()

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

Returns:int

Average time (in seconds) that expired sessions had been alive.

getSessionCounterback to summary
public long getSessionCounter()

Returns the total number of sessions created by this manager.

Returns:long

Total number of sessions created by this manager.

getSessionCreateRateback to summary
public int getSessionCreateRate()

Gets the current rate of session creation (in session per minute). This may be based on sample data.

Returns:int

The current rate (in sessions per minute) of session creation

getSessionExpireRateback to summary
public int getSessionExpireRate()

Gets the current rate of session expiration (in session per minute). This may be based on sample data

Returns:int

The current rate (in sessions per minute) of session expiration

getSessionIdGeneratorback to summary
public SessionIdGenerator getSessionIdGenerator()
Returns:SessionIdGenerator

the session id generator

getSessionLastAccessAtStartback to summary
public 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:boolean

the flag value

getSessionMaxAliveTimeback to summary
public int getSessionMaxAliveTime()

Gets the longest time (in seconds) that an expired session had been alive.

Returns:int

Longest time (in seconds) that an expired session had been alive.

loadback to summary
public 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.

Exceptions
ClassNotFoundException:
if a serialized class cannot be found during the reload
IOException:
if an input/output error occurs
removeback to summary
public void remove(Session session)

Remove this Session from the active Sessions for this Manager.

Parameters
session:Session

Session to be removed

removeback to summary
public void remove(Session session, boolean update)

Remove this Session from the active Sessions for this Manager.

Parameters
session:Session

Session to be removed

update:boolean

Should the expiration statistics be updated

removePropertyChangeListenerback to summary
public void removePropertyChangeListener(PropertyChangeListener listener)

Remove a property change listener from this component.

Parameters
listener:PropertyChangeListener

The listener to remove

rotateSessionIdback to summary
public default String rotateSessionId(Session session)

Change the session ID of the current session to a new randomly generated session ID.

Parameters
session:Session

The session to change the session ID for

Returns:String

The new session ID

setContextback to summary
public 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:Context

The newly associated Context

setExpiredSessionsback to summary
public void setExpiredSessions(long expiredSessions)

Sets the number of sessions that have expired.

Parameters
expiredSessions:long

Number of sessions that have expired

setMaxActiveback to summary
public void setMaxActive(int maxActive)

(Re)sets the maximum number of sessions that have been active at the same time.

Parameters
maxActive:int

Maximum number of sessions that have been active at the same time.

setNotifyAttributeListenerOnUnchangedValueback to summary
public void setNotifyAttributeListenerOnUnchangedValue(boolean notifyAttributeListenerOnUnchangedValue)

Configure if jakarta.servlet.http.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 jakarta.servlet.http.HttpSessionAttributeListener is configured for the session.

Parameters
notifyAttributeListenerOnUnchangedValue:boolean

true the listener will be called, false it will not

setNotifyBindingListenerOnUnchangedValueback to summary
public void setNotifyBindingListenerOnUnchangedValue(boolean notifyBindingListenerOnUnchangedValue)

Configure if jakarta.servlet.http.HttpSessionBindingListener#valueUnbound(jakarta.servlet.http.HttpSessionBindingEvent) be called followed by jakarta.servlet.http.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 jakarta.servlet.http.HttpSessionBindingListener.

Parameters
notifyBindingListenerOnUnchangedValue:boolean

true the listener will be called, false it will not

setSessionActivityCheckback to summary
public 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:boolean

the new flag value

setSessionCounterback to summary
public void setSessionCounter(long sessionCounter)

Sets the total number of sessions created by this manager.

Parameters
sessionCounter:long

Total number of sessions created by this manager.

setSessionIdGeneratorback to summary
public void setSessionIdGenerator(SessionIdGenerator sessionIdGenerator)

Sets the session id generator

Parameters
sessionIdGenerator:SessionIdGenerator

The session id generator

setSessionLastAccessAtStartback to summary
public 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:boolean

the new flag value

setSessionMaxAliveTimeback to summary
public void setSessionMaxAliveTime(int sessionMaxAliveTime)

Sets the longest time (in seconds) that an expired session had been alive.

Parameters
sessionMaxAliveTime:int

Longest time (in seconds) that an expired session had been alive.

unloadback to summary
public 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.

Exceptions
IOException:
if an input/output error occurs
willAttributeDistributeback to summary
public 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:String

The attribute name

value:Object

The attribute value

Returns:boolean

true if the Manager would distribute the given attribute otherwise false