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

org.springframework.web.context.request

## Interface RequestAttributes

- All Known Subinterfaces:
    AsyncWebRequest, NativeWebRequest, WebRequest
  All Known Implementing Classes:
    AbstractRequestAttributes, DispatcherServletWebRequest, FacesRequestAttributes, FacesWebRequest, NoSupportAsyncWebRequest, PortletRequestAttributes, PortletWebRequest, ServletRequestAttributes, ServletWebRequest, StandardServletAsyncWebRequest

      public interface RequestAttributes

  Abstraction for accessing attribute objects associated with a request. Supports access to request-scoped attributes as well as to session-scoped attributes, with the optional notion of a "global session".

  Can be implemented for any kind of request/session mechanism, in particular for servlet requests and portlet requests.

  Since:
    2.0
  Author:
    Juergen Hoeller
  See Also:
    `ServletRequestAttributes`, `PortletRequestAttributes`

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static String` | `REFERENCE_REQUEST` Name of the standard reference to the request object: "request".
    `static String` | `REFERENCE_SESSION` Name of the standard reference to the session object: "session".
    `static int` | `SCOPE_GLOBAL_SESSION` Constant that indicates global session scope.
    `static int` | `SCOPE_REQUEST` Constant that indicates request scope.
    `static int` | `SCOPE_SESSION` Constant that indicates session scope.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `Object` | `getAttribute(String name, int scope)` Return the value for the scoped attribute of the given name, if any.
    `String[]` | `getAttributeNames(int scope)` Retrieve the names of all attributes in the scope.
    `String` | `getSessionId()` Return an id for the current underlying session.
    `Object` | `getSessionMutex()` Expose the best available mutex for the underlying session: that is, an object to synchronize on for the underlying session.
    `void` | `registerDestructionCallback(String name, Runnable callback, int scope)` Register a callback to be executed on destruction of the specified attribute in the given scope.
    `void` | `removeAttribute(String name, int scope)` Remove the scoped attribute of the given name, if it exists.
    `Object` | `resolveReference(String key)` Resolve the contextual reference for the given key, if any.
    `void` | `setAttribute(String name, Object value, int scope)` Set the value for the scoped attribute of the given name, replacing an existing value (if any).

- - ### Field Detail

    - #### SCOPE_REQUEST

          static final int SCOPE_REQUEST

      Constant that indicates request scope.
      See Also:
        Constant Field Values

    - #### SCOPE_SESSION

          static final int SCOPE_SESSION

      Constant that indicates session scope.

      This preferably refers to a locally isolated session, if such a distinction is available (for example, in a Portlet environment). Else, it simply refers to the common session.

      See Also:
        Constant Field Values

    - #### SCOPE_GLOBAL_SESSION

          static final int SCOPE_GLOBAL_SESSION

      Constant that indicates global session scope.

      This explicitly refers to a globally shared session, if such a distinction is available (for example, in a Portlet environment). Else, it simply refers to the common session.

      See Also:
        Constant Field Values

    - #### REFERENCE_REQUEST

          static final String REFERENCE_REQUEST

      Name of the standard reference to the request object: "request".
      See Also:
        `resolveReference(java.lang.String)`, Constant Field Values

    - #### REFERENCE_SESSION

          static final String REFERENCE_SESSION

      Name of the standard reference to the session object: "session".
      See Also:
        `resolveReference(java.lang.String)`, Constant Field Values

  - ### Method Detail

    - #### getAttribute

          Object getAttribute(String name,
                            int scope)

      Return the value for the scoped attribute of the given name, if any.
      Parameters:
        `name` - the name of the attribute
        `scope` - the scope identifier
      Returns:
        the current attribute value, or `null` if not found

    - #### setAttribute

          void setAttribute(String name,
                          Object value,
                          int scope)

      Set the value for the scoped attribute of the given name, replacing an existing value (if any).
      Parameters:
        `name` - the name of the attribute
        `scope` - the scope identifier
        `value` - the value for the attribute

    - #### removeAttribute

          void removeAttribute(String name,
                             int scope)

      Remove the scoped attribute of the given name, if it exists.

      Note that an implementation should also remove a registered destruction callback for the specified attribute, 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).

      Parameters:
        `name` - the name of the attribute
        `scope` - the scope identifier

    - #### getAttributeNames

          String[] getAttributeNames(int scope)

      Retrieve the names of all attributes in the scope.
      Parameters:
        `scope` - the scope identifier
      Returns:
        the attribute names as String array

    - #### registerDestructionCallback

          void registerDestructionCallback(String name,
                                         Runnable callback,
                                         int scope)

      Register a callback to be executed on destruction of the specified attribute in the given scope.

      Implementations should do their best to execute the callback at the appropriate time: that is, at request completion or session termination, respectively. If such a callback is not supported by the underlying runtime environment, the callback must be ignored and a corresponding warning should be logged.

      Note that 'destruction' usually corresponds to destruction of the entire scope, not to the individual attribute having been explicitly removed by the application. If an attribute gets removed via this facade's `removeAttribute(String, int)` method, any registered destruction callback should be disabled as well, assuming that the removed object will be reused or manually destroyed.

      NOTE: Callback objects should generally be serializable if they are being registered for a session scope. Otherwise the callback (or even the entire session) might not survive web app restarts.

      Parameters:
        `name` - the name of the attribute to register the callback for
        `callback` - the destruction callback to be executed
        `scope` - the scope identifier

    - #### resolveReference

          Object resolveReference(String key)

      Resolve the contextual reference for the given key, if any.

      At a minimum: the HttpServletRequest/PortletRequest reference for key "request", and the HttpSession/PortletSession reference for key "session".

      Parameters:
        `key` - the contextual key
      Returns:
        the corresponding object, or `null` if none found

    - #### getSessionId

          String getSessionId()

      Return an id for the current underlying session.
      Returns:
        the session id as String (never `null`

    - #### getSessionMutex

          Object getSessionMutex()

      Expose the best available mutex for the underlying session: that is, an object to synchronize on for the underlying session.
      Returns:
        the session mutex to use (never `null`