org.jsecurity.session.mgt
Class DelegatingSession

java.lang.Object
  org.jsecurity.session.mgt.DelegatingSession

All Implemented Interfaces:

Session

public class DelegatingSession
extends Object
implements Session

A DelegatingSession is a client-tier representation of a server side Session. This implementation is basically a proxy to a server-side SessionManager, which will return the proper results for each method call.

A DelegatingSession will cache data when appropriate to avoid a remote method invocation, only communicating with the server when necessary.

Of course, if used in-process with a SessionManager business POJO, as might be the case in a web-based application where the web classes and server-side business pojos exist in the same JVM, a remote method call will not be incurred.

Since:

0.1

Author:

Les Hazlewood, Jeremy Haile

Constructor Summary

DelegatingSession()

DelegatingSession(SessionManager sessionManager, Serializable id)

Method Summary

Object	getAttribute(Object key) Returns the object bound to this session identified by the specified key.
Collection<Object>	getAttributeKeys() Returns the keys of all the attributes stored under this session.
InetAddress	getHostAddress() Returns the InetAddress of the host that originated this session, or null if the host address is unknown.
Serializable	getId() Returns the unique identifier assigned by the system upon session creation.
Date	getLastAccessTime() Returns the last time the user associated with the session interacted with the system.
SessionManager	getSessionManager() Returns the SessionManager used by this handle to invoke all session-related methods.
Date	getStartTimestamp() Returns the time the session was started; that is, the time the system created the instance.
long	getTimeout() Returns the time in milliseconds that the session session may remain idle before expiring.
Object	removeAttribute(Object key) Removes (unbinds) the object bound to this session under the specified key name.
void	setAttribute(Object key, Object value) Binds the specified value to this session, uniquely identified by the specifed key name.
void	setId(Serializable id) Sets the sessionId used by this handle for all future SessionManager method invocations.
void	setSessionManager(SessionManager sessionManager) Sets the SessionManager to which this DelegatingSession will delegate its method calls.
void	setTimeout(long maxIdleTimeInMillis) Sets the time in milliseconds that the session may remain idle before expiring.
void	stop() Explicitly stops (invalidates) this session and releases all associated resources.
void	touch() Explicitly updates the lastAccessTime of this session.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

DelegatingSession

public DelegatingSession()

DelegatingSession

public DelegatingSession(SessionManager sessionManager,
                         Serializable id)

Method Detail

getSessionManager

public SessionManager getSessionManager()

Returns the SessionManager used by this handle to invoke all session-related methods.

Returns:

the SessionManager used by this handle to invoke all session-related methods.

setSessionManager

public void setSessionManager(SessionManager sessionManager)

Sets the SessionManager to which this DelegatingSession will delegate its method calls. In a rich client environment, this SessionManager will probably be a remoting proxy which executes remote method invocations. In a single-process environment (e.g. a web application deployed in the same JVM of the application server), the SessionManager can be the actual business POJO implementation.

You'll notice the Session interface and the SessionManager interface are nearly identical. This is to ensure the SessionManager can support most method calls in the Session interface, via this handle/proxy technique. The session manager is implementated as a stateless business POJO, with the handle passing the session id as necessary.

Parameters:

sessionManager - the SessionManager this handle will use when delegating method calls.

setId

public void setId(Serializable id)

Sets the sessionId used by this handle for all future SessionManager method invocations.

Parameters:

id - the sessionId to use for all SessionManager invocations.

See Also:

setSessionManager(SessionManager sessionManager)

getId

public Serializable getId()

Description copied from interface: Session

Returns the unique identifier assigned by the system upon session creation.

All return values from this method are expected to have proper toString(), equals(), and hashCode() implementations. Good candiadates for such an identifier are UUIDs, Integers, and Strings.

Specified by:

getId in interface Session

Returns:

The unique identifier assigned to the session upon creation.

See Also:

Session.getId()

getStartTimestamp

public Date getStartTimestamp()

Description copied from interface: Session

Returns the time the session was started; that is, the time the system created the instance.

Specified by:

getStartTimestamp in interface Session

Returns:

The time the system created the session.

See Also:

Session.getStartTimestamp()

getLastAccessTime

public Date getLastAccessTime()

Description copied from interface: Session

Returns the last time the user associated with the session interacted with the system.

Specified by:

getLastAccessTime in interface Session

Returns:

The time the user last interacted with the system.

See Also:

Session.getLastAccessTime()

getTimeout

public long getTimeout()
                throws InvalidSessionException

Description copied from interface: Session

Returns the time in milliseconds that the session 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.

Specified by:

getTimeout in interface Session

Returns:

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

Throws:

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

setTimeout

public void setTimeout(long maxIdleTimeInMillis)
                throws InvalidSessionException

Description copied from interface: Session

Sets the time in milliseconds that the 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.

Specified by:

setTimeout in interface Session

Parameters:

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

Throws:

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

getHostAddress

public InetAddress getHostAddress()

Description copied from interface: Session

Returns the InetAddress of the host that originated this session, or null if the host address is unknown.

Specified by:

getHostAddress in interface Session

Returns:

the InetAddress of the host that originated this session, or null if the host address is unknown.

See Also:

Session.getHostAddress()

touch

public void touch()
           throws InvalidSessionException

Description copied from interface: Session

Explicitly updates the lastAccessTime of this session. This method can be used to ensure a session does not time out.

Most programmers won't use this method explicitly and will instead rely calling the other Session methods to update the time transparently, or on a framework during a remote procedure call or upon a web request.

This method is particularly useful however when supporting rich-client applications such as Java Web Start appp, Java or Flash applets, etc. Although rare, it is possible in a rich-client environment that a user continuously interacts with the client-side application without a server-side method call ever being invoked. If this happens over a long enough period of time, the user's server-side session could time-out. Again, such cases are rare since most rich-clients frequently require server-side method invocations.

In this example though, the user's session might still be considered valid because the user is actively "using" the application, just not communicating with the server. But because no server-side method calls are invoked, there is no way for the server to know if the user is sitting idle or not, so it must assume so to maintain session integrity. The touch method could be invoked by the rich-client application code during those times to ensure that the next time a server-side method is invoked, the invocation will not throw an ExpiredSessionException. In short terms, it could be used periodically to ensure a session does not time out.

How often this rich-client "maintenance" might occur is entirely dependent upon the application and would be based on variables such as session timeout configuration, usage characteristics of the client application, network utilization and application server performance.

Specified by:

touch in interface Session

Throws:

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

See Also:

Session.touch()

stop

public void stop()
          throws InvalidSessionException

Description copied from interface: Session

Explicitly stops (invalidates) this session and releases all associated resources.

If this session has already been authenticated (i.e. the Subject that owns this session has logged-in), calling this method explicitly might have undesired side effects:

It is common for a Subject implementation to retain authentication state in the Session. If the session is explicitly stopped by application code by calling this method directly, it could clear out any authentication state that might exist, thereby effectively "unauthenticating" the Subject.

As such, you might consider logging-out the 'owning' Subject instead of manually calling this method, as a log out is expected to stop the corresponding session automatically, and also allows framework code to execute additional cleanup logic.

Specified by:

stop in interface Session

Throws:

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

See Also:

Session.stop()

getAttributeKeys

public Collection<Object> getAttributeKeys()
                                    throws InvalidSessionException

Description copied from interface: Session

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

Specified by:

getAttributeKeys in interface Session

Returns:

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

Throws:

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

See Also:

Session.getAttributeKeys()

getAttribute

public Object getAttribute(Object key)
                    throws InvalidSessionException

Description copied from interface: Session

Returns the object bound to this session identified by the specified key. If there is no object bound under the key, null is returned.

Specified by:

getAttribute in interface Session

Parameters:

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

Returns:

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

Throws:

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

See Also:

Session.getAttribute(Object key)

setAttribute

public void setAttribute(Object key,
                         Object value)
                  throws InvalidSessionException

Description copied from interface: Session

Binds the specified value to this 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 removeAttribute(key) was called.

Specified by:

setAttribute in interface Session

Parameters:

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 this session has stopped or expired prior to calling this method.

See Also:

Session.setAttribute(Object key, Object value)

removeAttribute

public Object removeAttribute(Object key)
                       throws InvalidSessionException

Description copied from interface: Session

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

Specified by:

removeAttribute in interface Session

Parameters:

key - the name uniquely identifying the object to remove

Returns:

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

Throws:

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

See Also:

Session.removeAttribute(Object key)