org.apache.shiro.session.mgt
Class SimpleSession

java.lang.Object
  org.apache.shiro.session.mgt.SimpleSession

All Implemented Interfaces:

Serializable, ValidatingSession, Session

public class SimpleSession
extends Object
implements ValidatingSession, Serializable

Simple Session JavaBeans-compatible POJO implementation, intended to be used on the business/server tier.

Since:

0.1

See Also:

Serialized Form

Field Summary

protected static long	MILLIS_PER_HOUR
protected static long	MILLIS_PER_MINUTE
protected static long	MILLIS_PER_SECOND

Constructor Summary

SimpleSession()

SimpleSession(String host)

Method Summary

boolean	equals(Object obj) Returns true if the specified argument is an instanceof SimpleSession and both ids are equal.
protected void	expire()
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.
Map<Object,Object>	getAttributes()
String	getHost() Returns the host name or IP string of the host that originated this session, or null if the host is unknown.
Serializable	getId() Returns the unique identifier assigned by the system upon session creation.
Date	getLastAccessTime() Returns the last time the application received a request or method invocation from the user associated with this session.
Date	getStartTimestamp() Returns the time the session was started; that is, the time the system created the instance.
Date	getStopTimestamp() Returns the time the session was stopped, or null if the session is still active.
long	getTimeout() Returns the time in milliseconds that the session session may remain idle before expiring.
int	hashCode() Returns the hashCode.
boolean	isExpired() Returns true if this session has expired, false otherwise.
protected boolean	isStopped()
protected boolean	isTimedOut() Determines if this session is expired.
boolean	isValid()
protected boolean	onEquals(SimpleSession ss) Provides an attribute-based comparison (no ID comparison) - incurred only when 'this' or the session object being compared for equality do not have a session id.
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	setAttributes(Map<Object,Object> attributes)
void	setExpired(boolean expired)
void	setHost(String host)
void	setId(Serializable id)
void	setLastAccessTime(Date lastAccessTime)
void	setStartTimestamp(Date startTimestamp)
void	setStopTimestamp(Date stopTimestamp)
void	setTimeout(long timeout) 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.
String	toString() Returns the string representation of this SimpleSession, equal to getClass().getName() + ",id=" + getId().
void	touch() Explicitly updates the lastAccessTime of this session to the current time when this method is invoked.
void	validate()

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

MILLIS_PER_SECOND

protected static final long MILLIS_PER_SECOND

See Also:

Constant Field Values

MILLIS_PER_MINUTE

protected static final long MILLIS_PER_MINUTE

See Also:

Constant Field Values

MILLIS_PER_HOUR

protected static final long MILLIS_PER_HOUR

See Also:

Constant Field Values

Constructor Detail

SimpleSession

public SimpleSession()

SimpleSession

public SimpleSession(String host)

Method Detail

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

setId

public void setId(Serializable id)

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.

setStartTimestamp

public void setStartTimestamp(Date startTimestamp)

getStopTimestamp

public Date getStopTimestamp()

Returns the time the session was stopped, or null if the session is still active.

A session may become stopped under a number of conditions:

• If the user logs out of the system, their current session is terminated (released).
• If the session expires
• The application explicitly calls stop()
• If there is an internal system error and the session state can no longer accurately reflect the user's behavior, such in the case of a system crash

Once stopped, a session may no longer be used. It is locked from all further activity.

Returns:

The time the session was stopped, or null if the session is still active.

setStopTimestamp

public void setStopTimestamp(Date stopTimestamp)

getLastAccessTime

public Date getLastAccessTime()

Description copied from interface: Session

Returns the last time the application received a request or method invocation from the user associated with this session. Application calls to this method do not affect this access time.

Specified by:

getLastAccessTime in interface Session

Returns:

The time the user last interacted with the system.

See Also:

Session.touch()

setLastAccessTime

public void setLastAccessTime(Date lastAccessTime)

isExpired

public boolean isExpired()

Returns true if this session has expired, false otherwise. If the session has expired, no further user interaction with the system may be done under this session.

Returns:

true if this session has expired, false otherwise.

setExpired

public void setExpired(boolean expired)

getTimeout

public long getTimeout()

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.

*Note: if you are used to the HttpSession's getMaxInactiveInterval() method, the scale on this method is different: Shiro Sessions use millisecond values for timeout whereas HttpSession.getMaxInactiveInterval uses seconds. Always use millisecond values with Shiro sessions.

Specified by:

getTimeout in interface Session

Returns:

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

setTimeout

public void setTimeout(long timeout)

Description copied from interface: Session

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

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

*Note: if you are used to the HttpSession's getMaxInactiveInterval() method, the scale on this method is different: Shiro Sessions use millisecond values for timeout whereas HttpSession.getMaxInactiveInterval uses seconds. Always use millisecond values with Shiro sessions.

Specified by:

setTimeout in interface Session

Parameters:

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

getHost

public String getHost()

Description copied from interface: Session

Returns the host name or IP string of the host that originated this session, or null if the host is unknown.

Specified by:

getHost in interface Session

Returns:

the host name or IP string of the host that originated this session, or null if the host address is unknown.

setHost

public void setHost(String host)

getAttributes

public Map<Object,Object> getAttributes()

setAttributes

public void setAttributes(Map<Object,Object> attributes)

touch

public void touch()

Description copied from interface: Session

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

Most programmers won't use this method directly and will instead rely on the last access time to be updated automatically as a result of an incoming web request or remote procedure call/method invocation.

However, this method is particularly useful 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. This 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

stop

public void stop()

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

isStopped

protected boolean isStopped()

expire

protected void expire()

isValid

public boolean isValid()

Specified by:

isValid in interface ValidatingSession

Since:

0.9

isTimedOut

protected boolean isTimedOut()

Determines if this session is expired.

Returns:

true if the specified session has expired, false otherwise.

validate

public void validate()
              throws InvalidSessionException

Specified by:

validate in interface ValidatingSession

Throws:

InvalidSessionException

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.

getAttribute

public Object getAttribute(Object key)

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.

setAttribute

public void setAttribute(Object key,
                         Object value)

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

removeAttribute

public Object removeAttribute(Object key)

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.

equals

public boolean equals(Object obj)

Returns true if the specified argument is an instanceof SimpleSession and both ids are equal. If the argument is a SimpleSession and either 'this' or the argument does not yet have an ID assigned, the value of onEquals is returned, which does a necessary attribute-based comparison when IDs are not available.

Do your best to ensure SimpleSession instances receive an ID very early in their lifecycle to avoid the more expensive attributes-based comparison.

Overrides:

equals in class Object

Parameters:

obj - the object to compare with this one for equality.

Returns:

true if this object is equivalent to the specified argument, false otherwise.

onEquals

protected boolean onEquals(SimpleSession ss)

Provides an attribute-based comparison (no ID comparison) - incurred only when 'this' or the session object being compared for equality do not have a session id.

Parameters:

ss - the SimpleSession instance to compare for equality.

Returns:

true if all the attributes, except the id, are equal to this object's attributes.

Since:

1.0

hashCode

public int hashCode()

Returns the hashCode. If the id is not null, its hashcode is returned immediately. If it is null, an attributes-based hashCode will be calculated and returned.

Do your best to ensure SimpleSession instances receive an ID very early in their lifecycle to avoid the more expensive attributes-based calculation.

Overrides:

hashCode in class Object

Returns:

this object's hashCode

Since:

1.0

toString

public String toString()

Returns the string representation of this SimpleSession, equal to getClass().getName() + ",id=" + getId().

Overrides:

toString in class Object

Returns:

the string representation of this SimpleSession, equal to getClass().getName() + ",id=" + getId().

Since:

1.0