org.jsecurity.session.mgt
Interface SessionManager

All Known Subinterfaces:

ValidatingSessionManager, WebSessionManager

All Known Implementing Classes:

AbstractSessionManager, AbstractValidatingSessionManager, DefaultSessionManager, DefaultWebSessionManager, ServletContainerSessionManager

public interface SessionManager

A SessionManager manages the creation, maintenance, and clean-up of all application Sessions.

Since:

0.1

Author:

Les Hazlewood

Method Summary

Object	getAttribute(Serializable sessionId, Object key) Returns the object bound to the specified session identified by the specified key.
Collection<Object>	getAttributeKeys(Serializable sessionId) Returns the keys of all the attributes stored under the session identified by sessionId.
InetAddress	getHostAddress(Serializable sessionId) Returns the IP address of the host where the session was started, if known.
Date	getLastAccessTime(Serializable sessionId) Returns the time the Session identified by the specified sessionId last interacted with the system.
Date	getStartTimestamp(Serializable sessionId) Returns the time the Session identified by the specified sessionId was started in the system.
long	getTimeout(Serializable sessionId) Returns the time in milliseconds that the specified session may remain idle before expiring.
boolean	isValid(Serializable sessionId) Returns true if the session is valid (it exists and is not stopped nor expired), false otherwise.
Object	removeAttribute(Serializable sessionId, Object key) Removes (unbinds) the object bound to this session under the specified key name.
void	setAttribute(Serializable sessionId, Object key, Object value) Binds the specified value to the specified session uniquely identified by the specifed key name.
void	setTimeout(Serializable sessionId, long maxIdleTimeInMillis) Sets the time in milliseconds that the specified session may remain idle before expiring.
Serializable	start(InetAddress originatingHost) Starts a new session within the system for the host with the specified originating IP address.
void	stop(Serializable sessionId) Explicitly stops the session identified by sessionId, thereby releasing all associated resources.
void	touch(Serializable sessionId) Updates the last accessed time of the session identified by sessionId.

Method Detail

start

Serializable start(InetAddress originatingHost)
                   throws HostUnauthorizedException,
                          IllegalArgumentException

Starts a new session within the system for the host with the specified originating IP address.

Note: see the SessionFactory.init(InetAddress) method about the implications of using InetAddresses in access control policies.

Parameters:

originatingHost - the originating host InetAddress of the external party (user, 3rd party product, etc) that is attempting to interact with the system.

Returns:

the system identifier of the newly created session.

Throws:

IllegalArgumentException - if the host specified is not valid.

HostUnauthorizedException - if the host specified is not allowed to start sessions.

See Also:

SessionFactory.start(InetAddress)

getStartTimestamp

Date getStartTimestamp(Serializable sessionId)

Returns the time the Session identified by the specified sessionId was started in the system.

Parameters:

sessionId - the system identifier for the session of interest.

Returns:

the system time the specified session was started (i.e. created).

See Also:

Session.getStartTimestamp()

getLastAccessTime

Date getLastAccessTime(Serializable sessionId)

Returns the time the Session identified by the specified sessionId last interacted with the system.

Parameters:

sessionId - the system identifier for the session of interest

Returns:

tye time the session last accessed the system

See Also:

Session.getLastAccessTime(), Session.touch()

isValid

boolean isValid(Serializable sessionId)

Returns true if the session is valid (it exists and is not stopped nor expired), false otherwise.

Parameters:

sessionId - the id of the session to check

Returns:

true if the session is valid (exists and is not stopped or expired), false otherwise.

getTimeout

long getTimeout(Serializable sessionId)
                throws InvalidSessionException

Returns the time in milliseconds that the specified session may remain idle before expiring.

• A negative return value means the session will never expire.
• A non-negative return value (0 or greater) means the session expiration will occur if idle for that length of time.

Parameters:

sessionId - the system identifier of the session of interest.

Returns:

the time in milliseconds that the specified session may remain idle before expiring.

Throws:

InvalidSessionException - if the session has been stopped or expired prior to calling this method.

Since:

0.2

setTimeout

void setTimeout(Serializable sessionId,
                long maxIdleTimeInMillis)
                throws InvalidSessionException

Sets the time in milliseconds that the specified session may remain idle before expiring.

• A negative return value means the session will never expire.
• A non-negative return value (0 or greater) means the session expiration will occur if idle for that length of time.

Parameters:

sessionId - the system identifier of the session of interest.

maxIdleTimeInMillis - the time in milliseconds that the specified session may remain idle before expiring.

Throws:

InvalidSessionException - if the session has been stopped or expired prior to calling this method.

Since:

0.2

touch

void touch(Serializable sessionId)
           throws InvalidSessionException

Updates the last accessed time of the session identified by sessionId. This can be used to explicitly ensure that a session does not time out.

Parameters:

sessionId - the id of the session to update.

Throws:

InvalidSessionException - if the session has been stopped or expired prior to calling this method.

See Also:

Session.touch()

getHostAddress

InetAddress getHostAddress(Serializable sessionId)

Returns the IP address of the host where the session was started, if known. If no IP was specified when starting the session, this method returns null

Parameters:

sessionId - the id of the session to query.

Returns:

the ip address of the host where the session originated, if known. If unknown, this method returns null.

See Also:

init( InetAddress originatingHost )

stop

void stop(Serializable sessionId)
          throws InvalidSessionException

Explicitly stops the session identified by sessionId, thereby releasing all associated resources.

Parameters:

sessionId - the system identfier of the system to destroy.

Throws:

InvalidSessionException - if the session has stopped or expired prior to calling this method.

See Also:

Session.stop()

getAttributeKeys

Collection<Object> getAttributeKeys(Serializable sessionId)

Returns the keys of all the attributes stored under the session identified by sessionId. If there are no attributes, this returns an empty collection.

Parameters:

sessionId - the system identifier of the system to access.

Returns:

the keys of all attributes stored under the specified session, or an empty collection if there are no session attributes.

Throws:

InvalidSessionException - if the specified session has stopped or expired prior to calling this method.

Since:

0.2

See Also:

Session.getAttributeKeys()

getAttribute

Object getAttribute(Serializable sessionId,
                    Object key)
                    throws InvalidSessionException

Returns the object bound to the specified session identified by the specified key. If there is noobject bound under the key for the given session, null is returned.

Parameters:

sessionId - the system identifier of the session of interest

key - the unique name of the object bound to the specified session

Returns:

the object bound under the specified key name or null if there is no object bound under that name.

Throws:

InvalidSessionException - if the specified session has stopped or expired prior to calling this method.

See Also:

Session.getAttribute(Object key)

setAttribute

void setAttribute(Serializable sessionId,
                  Object key,
                  Object value)
                  throws InvalidSessionException

Binds the specified value to the specified session uniquely identified by the specifed key name. If there is already an object bound under the key name, that existing object will be replaced by the new value.

If the value parameter is null, it has the same effect as if the removeAttribute(Serializable sessionId, Object key) method was called.

Parameters:

sessionId - the system identifier of the session of interest

key - the name under which the value object will be bound in this session

value - the object to bind in this session.

Throws:

InvalidSessionException - if the specified session has stopped or expired prior to calling this method.

See Also:

Session.setAttribute(Object key, Object value)

removeAttribute

Object removeAttribute(Serializable sessionId,
                       Object key)
                       throws InvalidSessionException

Removes (unbinds) the object bound to this session under the specified key name.

Parameters:

sessionId - the system identifier of the session of interest

key - the name uniquely identifying the object to remove

Returns:

the object removed or null if there was no object bound under the specified key name.

Throws:

InvalidSessionException - if the specified session has stopped or expired prior to calling this method.

See Also:

Session.removeAttribute(Object key)