Session (Apache Shiro 1.3.0 API)

All Known Subinterfaces:

ValidatingSession

All Known Implementing Classes:

DelegatingSession, HttpServletSession, ImmutableProxiedSession, ProxiedSession, SimpleSession
```
public interface Session
```
A Session is a stateful data context associated with a single Subject (user, daemon process, etc) who interacts with a software system over a period of time.
A Session is intended to be managed by the business tier and accessible via other tiers without being tied to any given client technology. This is a great benefit to Java systems, since until now, the only viable session mechanisms were the javax.servlet.http.HttpSession or Stateful Session EJB's, which many times unnecessarily coupled applications to web or ejb technologies.

Since:

0.1

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and Description
`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.
`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.
`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`	`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 to the current time when this method is invoked.

- Method Detail
  - getId
```
Serializable getId()
```
    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.
    
    Returns:
    
    The unique identifier assigned to the session upon creation.
  - getStartTimestamp
```
Date getStartTimestamp()
```
    Returns the time the session was started; that is, the time the system created the instance.
    
    Returns:
    
    The time the system created the session.
  - getLastAccessTime
```
Date getLastAccessTime()
```
    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.
    
    Returns:
    
    The time the user last interacted with the system.
    
    See Also:
    
    touch()
  - getTimeout
```
long getTimeout()
         throws InvalidSessionException
```
    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.
    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.
    
    Since:
    
    0.2
  - setTimeout
```
void setTimeout(long maxIdleTimeInMillis)
         throws InvalidSessionException
```
    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.
    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.
    
    Since:
    
    0.2
  - getHost
```
String getHost()
```
    Returns the host name or IP string of the host that originated this session, or null if the host is unknown.
    
    Returns:
    
    the host name or IP string of the host that originated this session, or null if the host address is unknown.
  - touch
```
void touch()
    throws InvalidSessionException
```
    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.
    
    Throws:
    
    InvalidSessionException - if this session has stopped or expired prior to calling this method.
  - stop
```
void stop()
   throws InvalidSessionException
```
    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.
    
    Throws:
    
    InvalidSessionException - if this session has stopped or expired prior to calling this method.
  - getAttributeKeys
```
Collection<Object> getAttributeKeys()
                             throws InvalidSessionException
```
    Returns the keys of all the attributes stored under this session. If there are no attributes, this returns an empty collection.
    
    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.
    
    Since:
    
    0.2
  - getAttribute
```
Object getAttribute(Object key)
             throws InvalidSessionException
```
    Returns the object bound to this session identified by the specified key. If there is no object bound under the key, null is returned.
    
    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.
  - setAttribute
```
void setAttribute(Object key,
                  Object value)
           throws InvalidSessionException
```
    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.
    
    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.
  - removeAttribute
```
Object removeAttribute(Object key)
                throws InvalidSessionException
```
    Removes (unbinds) the object bound to this session under the specified key name.
    
    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.

Interface Session

Method Summary

Method Detail

getId

getStartTimestamp

getLastAccessTime

getTimeout

setTimeout

getHost

touch

stop

getAttributeKeys

getAttribute

setAttribute

removeAttribute