org.apache.catalina

Interface Manager

All Known Implementing Classes:

CookiePersistentManager, ManagerBase, PersistentManager, PersistentManagerBase, ReplicationManagerBase, ReplicationWebEventPersistentManager, StandardManager

public interface Manager

A Manager manages the pool of Sessions that are associated with a particular Container. 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.

Version:

$Revision: 1.6 $ $Date: 2006/11/17 23:06:36 $

Author:

Craig R. McClanahan

Method Summary

Modifier and Type	Method and 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	changeSessionId(Session session) Change the session ID of the current session to a new randomly generated session ID.
void	checkSessionAttribute(String name, Object value) Checks the given session attribute name and value to make sure they comply with any restrictions set forth by this session manager.
Session	createEmptySession() Get a session from the recycled ones or create a new empty one.
Session	createSession() Construct and return a new session object, based on the default settings specified by this Manager's properties.
Session	createSession(String sessionId) Construct and return a new session object, based on the default settings specified by this Manager's properties, using the specified session id.
Session	findSession(String id) Return the active Session, associated with this Manager, with the specified session id (if any); otherwise return null.
Session	findSession(String id, javax.servlet.http.HttpServletRequest request) Gets the session with the given id from the given request.
Session	findSession(String id, String version) Finds and returns the session with the given id that also satisfies the given version requirement.
Session[]	findSessions() Return the set of active Sessions associated with this Manager.
int	getActiveSessions() Gets the number of currently active sessions.
Container	getContainer() Return the Container with which this Manager is associated.
boolean	getDistributable() Return the distributable flag for the sessions supported by this Manager.
int	getExpiredSessions() Gets the number of sessions that have expired.
String	getInfo() Return descriptive information about this Manager implementation and the corresponding version number, in the format <description>/<version>.
int	getMaxActive() Gets the maximum number of sessions that have been active at the same time.
int	getMaxInactiveInterval() Same as getMaxInactiveIntervalSeconds
int	getMaxInactiveIntervalSeconds() Return the default maximum inactive interval (in seconds) for Sessions created by this Manager.
int	getRejectedSessions() Gets the number of sessions that were not created because the maximum number of active sessions was reached.
int	getSessionAverageAliveTime() Same as getSessionAverageAliveTimeSeconds
int	getSessionAverageAliveTimeSeconds() Gets the average time (in seconds) that expired sessions had been alive.
int	getSessionCount() Returns the total number of sessions created by this manager.
int	getSessionCounter() Same as getSessionCount
int	getSessionIdLength() Gets the session id length (in bytes) of Sessions created by this Manager.
int	getSessionMaxAliveTime() Same as getSessionMaxAliveTimeSeconds
int	getSessionMaxAliveTimeSeconds() Gets the longest time (in seconds) that an expired session had been alive.
boolean	isSessionVersioningSupported() Returns true if this session manager supports session versioning, false otherwise.
void	load() Load any currently active sessions that were previously unloaded to the appropriate persistence mechanism, if any.
boolean	lockSession(javax.servlet.ServletRequest request)
void	postRequestDispatcherProcess(javax.servlet.ServletRequest request, javax.servlet.ServletResponse response)
void	preRequestDispatcherProcess(javax.servlet.ServletRequest request, javax.servlet.ServletResponse response)
void	remove(Session session) Remove this Session from the active Sessions for this Manager.
void	removePropertyChangeListener(PropertyChangeListener listener) Remove a property change listener from this component.
void	setContainer(Container container) Set the Container with which this Manager is associated.
void	setDistributable(boolean distributable) Set the distributable flag for the sessions supported by this Manager.
void	setExpiredSessions(int 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	setMaxInactiveInterval(int interval) Same as setMaxInactiveIntervalSeconds
void	setMaxInactiveIntervalSeconds(int interval) Set the default maximum inactive interval (in seconds) for Sessions created by this Manager.
void	setRejectedSessions(int rejectedSessions) Sets the number of sessions that were not created because the maximum number of active sessions was reached.
void	setSessionAverageAliveTime(int sessionAverageAliveTime) Same as setSessionAverageAliveTimeSeconds
void	setSessionAverageAliveTimeSeconds(int sessionAverageAliveTime) Sets the average time (in seconds) that expired sessions had been alive.
void	setSessionCount(int sessionCounter) Sets the total number of sessions created by this manager.
void	setSessionCounter(int sessionCounter) Same as setSessionCount
void	setSessionIdLength(int length) Sets the session id length (in bytes) for Sessions created by this Manager.
void	setSessionMaxAliveTime(int sessionMaxAliveTime) Same as setSessionMaxAliveTimeSeconds
void	setSessionMaxAliveTimeSeconds(int sessionMaxAliveTime) Sets the longest time (in seconds) that an expired session had been alive.
javax.servlet.http.Cookie	toCookie(Session session) Converts the given session into a cookie as a way of persisting it.
void	unload() Save any currently active sessions in the appropriate persistence mechanism, if any.
void	unlockSession(javax.servlet.ServletRequest request)
void	update(javax.servlet.http.HttpSession session) Perform any operations when the request is finished.

Method Detail

getContainer

Container getContainer()

Return the Container with which this Manager is associated.

setContainer

void setContainer(Container container)

Set the Container with which this Manager is associated.

Parameters:

container - The newly associated Container

getDistributable

boolean getDistributable()

Return the distributable flag for the sessions supported by this Manager.

setDistributable

void setDistributable(boolean distributable)

Set the distributable flag for the sessions supported by this Manager. If this flag is set, all user data objects added to sessions associated with this manager must implement Serializable.

Parameters:

distributable - The new distributable flag

getInfo

String getInfo()

Return descriptive information about this Manager implementation and the corresponding version number, in the format <description>/<version>.

getMaxInactiveInterval

int getMaxInactiveInterval()

Same as getMaxInactiveIntervalSeconds

getMaxInactiveIntervalSeconds

int getMaxInactiveIntervalSeconds()

Return the default maximum inactive interval (in seconds) for Sessions created by this Manager.

setMaxInactiveInterval

void setMaxInactiveInterval(int interval)

Same as setMaxInactiveIntervalSeconds

setMaxInactiveIntervalSeconds

void setMaxInactiveIntervalSeconds(int interval)

Set the default maximum inactive interval (in seconds) for Sessions created by this Manager.

Parameters:

interval - The new default value

getSessionIdLength

int getSessionIdLength()

Gets the session id length (in bytes) of Sessions created by this Manager.

Returns:

The session id length

setSessionIdLength

void setSessionIdLength(int length)

Sets the session id length (in bytes) for Sessions created by this Manager.

Parameters:

length - The session id length

getSessionCounter

int getSessionCounter()

Same as getSessionCount

getSessionCount

int getSessionCount()

Returns the total number of sessions created by this manager.

Returns:

Total number of sessions created by this manager.

setSessionCounter

void setSessionCounter(int sessionCounter)

Same as setSessionCount

setSessionCount

void setSessionCount(int sessionCounter)

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

int getExpiredSessions()

Gets the number of sessions that have expired.

Returns:

Number of sessions that have expired

setExpiredSessions

void setExpiredSessions(int 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

setRejectedSessions

void setRejectedSessions(int rejectedSessions)

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

Parameters:

rejectedSessions - Number of rejected sessions

getSessionMaxAliveTime

int getSessionMaxAliveTime()

Same as getSessionMaxAliveTimeSeconds

getSessionMaxAliveTimeSeconds

int getSessionMaxAliveTimeSeconds()

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)

Same as setSessionMaxAliveTimeSeconds

setSessionMaxAliveTimeSeconds

void setSessionMaxAliveTimeSeconds(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()

Same as getSessionAverageAliveTimeSeconds

getSessionAverageAliveTimeSeconds

int getSessionAverageAliveTimeSeconds()

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

Returns:

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

setSessionAverageAliveTime

void setSessionAverageAliveTime(int sessionAverageAliveTime)

Same as setSessionAverageAliveTimeSeconds

setSessionAverageAliveTimeSeconds

void setSessionAverageAliveTimeSeconds(int sessionAverageAliveTime)

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

Parameters:

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

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

changeSessionId

void changeSessionId(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

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.

createSession

Session createSession()

Construct and return a new session object, based on the default settings specified by this Manager's properties. The session id will be assigned by this method, and available via the getId() method of the returned session. If a new session cannot be created for any reason, return null.

Throws:

IllegalStateException - if a new session cannot be instantiated for any reason

createSession

Session createSession(String sessionId)

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

Parameters:

sessionId - the session id to assign to the new session

Returns:

the new session, or null if a session with the requested id already exists

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

Throws:

IllegalStateException - if a new session cannot be instantiated for any reason

IOException - if an input/output error occurs while processing this request

findSession

Session findSession(String id,
                    String version)
             throws IOException

Finds and returns the session with the given id that also satisfies the given version requirement. This overloaded version of findSession() will be invoked only if isSessionVersioningSupported() returns true. By default, this method delegates to the version of findSession() that does not take any session version number.

Parameters:

id - The session id to match

version - The session version requirement to satisfy

Returns:

The session that matches the given id and also satisfies the given version requirement, or null if no such session could be found by this session manager

Throws:

IOException - if an IO error occurred

findSession

Session findSession(String id,
                    javax.servlet.http.HttpServletRequest request)
             throws IOException

Gets the session with the given id from the given request.

Parameters:

id - the session id

request - the request containing the requested session information

Returns:

the requested session, or null if not found

Throws:

IOException

isSessionVersioningSupported

boolean isSessionVersioningSupported()

Returns true if this session manager supports session versioning, false otherwise.

Returns:

true if this session manager supports session versioning, false otherwise.

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.

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

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

update

void update(javax.servlet.http.HttpSession session)
     throws Exception

Perform any operations when the request is finished.

Throws:

Exception

lockSession

boolean lockSession(javax.servlet.ServletRequest request)
             throws javax.servlet.ServletException

Throws:

javax.servlet.ServletException

unlockSession

void unlockSession(javax.servlet.ServletRequest request)

preRequestDispatcherProcess

void preRequestDispatcherProcess(javax.servlet.ServletRequest request,
                                 javax.servlet.ServletResponse response)

postRequestDispatcherProcess

void postRequestDispatcherProcess(javax.servlet.ServletRequest request,
                                  javax.servlet.ServletResponse response)

toCookie

javax.servlet.http.Cookie toCookie(Session session)
                            throws IOException

Converts the given session into a cookie as a way of persisting it.

Parameters:

session - the session to convert

Returns:

the cookie representation of the given session

Throws:

IOException

checkSessionAttribute

void checkSessionAttribute(String name,
                           Object value)
                    throws IllegalArgumentException

Checks the given session attribute name and value to make sure they comply with any restrictions set forth by this session manager. For example, in the case of cookie-based persistence, session attribute values must be of type String.

Parameters:

name - the session attribute name

value - the session attribute value

Throws:

IllegalArgumentException - if the given session attribute name or value violate any restrictions set forth by this session manager