SessionScope (Spring Framework 3.2.1.RELEASE API)
Date: 2013-01-24

org.springframework.web.context.request

## Class SessionScope

- java.lang.Object
- - org.springframework.web.context.request.AbstractRequestAttributesScope
  - - org.springframework.web.context.request.SessionScope

- All Implemented Interfaces:
    Scope

      public class SessionScope
      extends AbstractRequestAttributesScope

  Session-backed `Scope` implementation.

  Relies on a thread-bound `RequestAttributes` instance, which can be exported through `RequestContextListener`, `RequestContextFilter` or `DispatcherServlet`.

  This `Scope` will also work for Portlet environments, through an alternate `RequestAttributes` implementation (as exposed out-of-the-box by Spring's `DispatcherPortlet`.

  Since:
    2.0
  Author:
    Rod Johnson, Juergen Hoeller, Rob Harrop
  See Also:
    `RequestContextHolder.currentRequestAttributes()`, `RequestAttributes.SCOPE_SESSION`, `RequestAttributes.SCOPE_GLOBAL_SESSION`, `RequestContextListener`, `RequestContextFilter`, `DispatcherServlet`, `DispatcherPortlet`

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `SessionScope()` Create a new SessionScope, storing attributes in a locally isolated session (or default session, if there is no distinction between a global session and a component-specific session).
    `SessionScope(boolean globalSession)` Create a new SessionScope, specifying whether to store attributes in the global session, provided that such a distinction is available.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `Object` | `get(String name, ObjectFactory objectFactory)` Return the object with the given name from the underlying scope, `creating it` if not found in the underlying storage mechanism.
    `String` | `getConversationId()` Return the conversation ID for the current underlying scope, if any.
    `protected int` | `getScope()` Template method that determines the actual target scope.
    `Object` | `remove(String name)` Remove the object with the given `name` from the underlying scope.

    - ### Methods inherited from class org.springframework.web.context.request.AbstractRequestAttributesScope

      `registerDestructionCallback, resolveContextualObject`

    - ### Methods inherited from class java.lang.Object

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

- - ### Constructor Detail

    - #### SessionScope

          public SessionScope()

      Create a new SessionScope, storing attributes in a locally isolated session (or default session, if there is no distinction between a global session and a component-specific session).

    - #### SessionScope

          public SessionScope(boolean globalSession)

      Create a new SessionScope, specifying whether to store attributes in the global session, provided that such a distinction is available.

      This distinction is important for Portlet environments, where there are two notions of a session: "portlet scope" and "application scope". If this flag is on, objects will be put into the "application scope" session; else they will end up in the "portlet scope" session (the typical default).

      In a Servlet environment, this flag is effectively ignored.

      Parameters:
        `globalSession` - `true` in case of the global session as target; `false` in case of a component-specific session as target
      See Also:
        `PortletRequestAttributes`, `ServletRequestAttributes`

  - ### Method Detail

    - #### getScope

          protected int getScope()

      Description copied from class: `AbstractRequestAttributesScope`
      Template method that determines the actual target scope.
      Specified by:
        `getScope` in class `AbstractRequestAttributesScope`
      Returns:
        the target scope, in the form of an appropriate `RequestAttributes` constant
      See Also:
        `RequestAttributes.SCOPE_REQUEST`, `RequestAttributes.SCOPE_SESSION`, `RequestAttributes.SCOPE_GLOBAL_SESSION`

    - #### getConversationId

          public String getConversationId()

      Description copied from interface: `Scope`
      Return the conversation ID for the current underlying scope, if any.

      The exact meaning of the conversation ID depends on the underlying storage mechanism. In the case of session-scoped objects, the conversation ID would typically be equal to (or derived from) the `session ID`; in the case of a custom conversation that sits within the overall session, the specific ID for the current conversation would be appropriate.

      Note: This is an optional operation. It is perfectly valid to return `null` in an implementation of this method if the underlying storage mechanism has no obvious candidate for such an ID.

      Returns:
        the conversation ID, or `null` if there is no conversation ID for the current scope

    - #### get

          public Object get(String name,
                   ObjectFactory objectFactory)

      Description copied from interface: `Scope`
      Return the object with the given name from the underlying scope, `creating it` if not found in the underlying storage mechanism.

      This is the central operation of a Scope, and the only operation that is absolutely required.

      Specified by:
        `get` in interface `Scope`
      Overrides:
        `get` in class `AbstractRequestAttributesScope`
      Parameters:
        `name` - the name of the object to retrieve
        `objectFactory` - the `ObjectFactory` to use to create the scoped object if it is not present in the underlying storage mechanism
      Returns:
        the desired object (never `null`)

    - #### remove

          public Object remove(String name)

      Description copied from interface: `Scope`
      Remove the object with the given `name` from the underlying scope.

      Returns `null` if no object was found; otherwise returns the removed `Object`.

      Note that an implementation should also remove a registered destruction callback for the specified object, if any. It does, however, not need to execute a registered destruction callback in this case, since the object will be destroyed by the caller (if appropriate).

      Note: This is an optional operation. Implementations may throw `UnsupportedOperationException` if they do not support explicitly removing an object.

      Specified by:
        `remove` in interface `Scope`
      Overrides:
        `remove` in class `AbstractRequestAttributesScope`
      Parameters:
        `name` - the name of the object to remove
      Returns:
        the removed object, or `null` if no object was present
      See Also:
        `Scope.registerDestructionCallback(java.lang.String, java.lang.Runnable)`