Package org.apache.tapestry5.http.services

# Interface Session

All Known Implementing Classes:
  `ClusteredSessionImpl`, `PageTesterSession`, `SessionImpl`

public interface Session
Generic version of `HttpSession`, used to bridge the gaps between the Servlet API and the Portlet API.

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Interface
  Description
  `static enum`
  `Session.LockMode`
  The type of lock used to access atttributes in the `Session`.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `boolean`
  `containsAttribute(String name)`
  Checks if the a value is stored in the session with the specified name.
  `boolean`
  `containsAttribute(String name, Session.LockMode lockMode)`
  Checks if the a value is stored in the session with the specified name.
  `Object`
  `getAttribute(String name)`
  Returns the value previously stored in the session.
  `Object`
  `getAttribute(String name, Session.LockMode lockMode)`
  Returns the value previously stored in the session.
  `List<String>`
  `getAttributeNames()`
  Returns a list of the names of all attributes stored in the session.
  `List<String>`
  `getAttributeNames(String prefix)`
  Returns a list of the names of all attributes stored in the session whose name has the provided prefix.
  `List<String>`
  `getAttributeNames(String prefix, Session.LockMode lockMode)`
  Returns a list of the names of all attributes stored in the session whose name has the provided prefix.
  `List<String>`
  `getAttributeNames(Session.LockMode lockMode)`
  Returns a list of the names of all attributes stored in the session.
  `int`
  `getMaxInactiveInterval()`
  Returns the maximum time interval, in seconds, that the servlet container will keep this session open between client accesses.
  `void`
  `invalidate()`
  Invalidates this session then unbinds any objects bound to it.
  `boolean`
  `isInvalidated()`
  Checks to see if the session has been invalidated.
  `void`
  `restoreDirtyObjects()`
  Re-stores dirty objects back into the session.
  `void`
  `setAttribute(String name, Object value)`
  Sets the value of an attribute.
  `void`
  `setMaxInactiveInterval(int seconds)`
  Specifies the time, in seconds, between client requests before the servlet container will invalidate this session.

- ## Method Details

  - ### getAttributeNames

    List<String> getAttributeNames()
    Returns a list of the names of all attributes stored in the session.

    The names are returned sorted alphabetically.

    By default, a `READ` lock is requested.

  - ### getAttributeNames

    List<String> getAttributeNames(Session.LockMode lockMode)
    Returns a list of the names of all attributes stored in the session.

    Uses the requested `Session.LockMode` to acquire an appropiate lock.

    Parameters:
      `lockMode` - The requested minimum lock mode. If null, `READ` is used.
    Returns:
      Alphabetically sorted list of all attributes
    Since:
      5.9

  - ### getAttributeNames

    List<String> getAttributeNames(String prefix)
    Returns a list of the names of all attributes stored in the session whose name has the provided prefix.

    By default, a `READ` lock is requested.

    Parameters:
      `prefix` - The attribute prefix
    Returns:
      Alphabetically sorted list of attributes matching the prefix
    Throws:
      `NullPointerException` - if prefix is `null`

  - ### getAttributeNames

    List<String> getAttributeNames(String prefix, Session.LockMode lockMode)
    Returns a list of the names of all attributes stored in the session whose name has the provided prefix.

    Uses the requested `Session.LockMode` to acquire an appropriate lock.

    Parameters:
      `prefix` - The attribute prefix
    Returns:
      Alphabetically sorted list of attributes matching the prefix
    Throws:
      `NullPointerException` - if prefix is `null`
    Since:
      5.9

  - ### getAttribute

    Object getAttribute(String name)
    Returns the value previously stored in the session.

    By default, a `WRITE` lock is requested.

    Parameters:
      `name` - The name of the attribute
    Throws:
      `NullPointerException` - if name is `null`

  - ### getAttribute

    Object getAttribute(String name, Session.LockMode lockMode)
    Returns the value previously stored in the session.

    Uses the requested `Session.LockMode` to acquire an appropriate lock.

    Parameters:
      `name` - The name of the attribute
    Throws:
      `NullPointerException` - if name is `null`
    Since:
      5.9

  - ### setAttribute

    void setAttribute(String name, Object value)
    Sets the value of an attribute. If the value is `null`, then the attribute is deleted.
    Parameters:
      `name` - The name of the attribute
      `value` - The new value of the attribute; `null` deletes the attribute.
    Throws:
      `NullPointerException` - if name is `null`

  - ### containsAttribute

    boolean containsAttribute(String name)
    Checks if the a value is stored in the session with the specified name.

    By default, a `READ` lock is requested.

    Parameters:
      `name` - The name of the attribute
    Throws:
      `NullPointerException` - if name is `null`
    Since:
      5.9

  - ### containsAttribute

    boolean containsAttribute(String name, Session.LockMode lockMode)
    Checks if the a value is stored in the session with the specified name.

    Uses the requested `Session.LockMode` to acquire an appropriate lock.

    Parameters:
      `name` - The name of the attribute
    Throws:
      `NullPointerException` - if name is `null`
    Since:
      5.9

  - ### getMaxInactiveInterval

    int getMaxInactiveInterval()
    Returns the maximum time interval, in seconds, that the servlet container will keep this session open between client accesses. After this interval, the servlet container will invalidate the session.

    The maximum time interval can be set with the setMaxInactiveInterval method.

    A negative time indicates the session should never timeout.

  - ### setMaxInactiveInterval

    void setMaxInactiveInterval(int seconds)
    Specifies the time, in seconds, between client requests before the servlet container will invalidate this session.

    A negative time indicates the session should never timeout.

  - ### invalidate

    void invalidate()
    Invalidates this session then unbinds any objects bound to it.
    Throws:
      `IllegalStateException` - if this method is called on an already invalidated session

  - ### isInvalidated

    boolean isInvalidated()
    Checks to see if the session has been invalidated. Note: since 5.3 this will also catch calls to `HttpSession.invalidate()`.
    Since:
      5.1.0.0

  - ### restoreDirtyObjects

    void restoreDirtyObjects()
    Re-stores dirty objects back into the session. This is necessary to support clustering, because (in most application servers) session objects are only broadcast around the cluster from setAttribute(). If a mutable session object is read and changed, those changes will be limited to a single server in the cluster, which can cause confusing application failures in the event of a failover. Does nothing if there are no changes, or the session has been invalidated.
    Since:
      5.1.0.0
    See Also:
      - `OptimizedSessionPersistedObject`
      - `OptimizedSessionPersistedObjectAnalyzer`
      - `ImmutableSessionPersistedObject`