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

org.springframework.web.context.request

## Interface WebRequest

- All Superinterfaces:
    RequestAttributes
  All Known Subinterfaces:
    AsyncWebRequest, NativeWebRequest
  All Known Implementing Classes:
    DispatcherServletWebRequest, FacesWebRequest, NoSupportAsyncWebRequest, PortletWebRequest, ServletWebRequest, StandardServletAsyncWebRequest

      public interface WebRequest
      extends RequestAttributes

  Generic interface for a web request. Mainly intended for generic web request interceptors, giving them access to general request metadata, not for actual handling of the request.
  Since:
    2.0
  Author:
    Juergen Hoeller
  See Also:
    `WebRequestInterceptor`

- - ### Field Summary

    - ### Fields inherited from interface org.springframework.web.context.request.RequestAttributes

      `REFERENCE_REQUEST, REFERENCE_SESSION, SCOPE_GLOBAL_SESSION, SCOPE_REQUEST, SCOPE_SESSION`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `checkNotModified(long lastModifiedTimestamp)` Check whether the request qualifies as not modified given the supplied last-modified timestamp (as determined by the application).
    `boolean` | `checkNotModified(String eTag)` Check whether the request qualifies as not modified given the supplied `ETag` (entity tag), as determined by the application.
    `String` | `getContextPath()` Return the context path for this request (usually the base path that the current web application is mapped to).
    `String` | `getDescription(boolean includeClientInfo)` Get a short description of this request, typically containing request URI and session id.
    `String` | `getHeader(String headerName)` Return the request header of the given name, or `null` if none.
    `Iterator<String>` | `getHeaderNames()` Return a Iterator over request header names.
    `String[]` | `getHeaderValues(String headerName)` Return the request header values for the given header name, or `null` if none.
    `Locale` | `getLocale()` Return the primary Locale for this request.
    `String` | `getParameter(String paramName)` Return the request parameter of the given name, or `null` if none.
    `Map<String,String[]>` | `getParameterMap()` Return a immutable Map of the request parameters, with parameter names as map keys and parameter values as map values.
    `Iterator<String>` | `getParameterNames()` Return a Iterator over request parameter names.
    `String[]` | `getParameterValues(String paramName)` Return the request parameter values for the given parameter name, or `null` if none.
    `String` | `getRemoteUser()` Return the remote user for this request, if any.
    `Principal` | `getUserPrincipal()` Return the user principal for this request, if any.
    `boolean` | `isSecure()` Return whether this request has been sent over a secure transport mechanism (such as SSL).
    `boolean` | `isUserInRole(String role)` Determine whether the user is in the given role for this request.

    - ### Methods inherited from interface org.springframework.web.context.request.RequestAttributes

      `getAttribute, getAttributeNames, getSessionId, getSessionMutex, registerDestructionCallback, removeAttribute, resolveReference, setAttribute`

- - ### Method Detail

    - #### getHeader

          String getHeader(String headerName)

      Return the request header of the given name, or `null` if none.

      Retrieves the first header value in case of a multi-value header.

      Since:
        3.0
      See Also:
        `HttpServletRequest.getHeader(String)`

    - #### getHeaderValues

          String[] getHeaderValues(String headerName)

      Return the request header values for the given header name, or `null` if none.

      A single-value header will be exposed as an array with a single element.

      Since:
        3.0
      See Also:
        `HttpServletRequest.getHeaders(String)`

    - #### getHeaderNames

          Iterator<String> getHeaderNames()

      Return a Iterator over request header names.
      Since:
        3.0
      See Also:
        `HttpServletRequest.getHeaderNames()`

    - #### getParameter

          String getParameter(String paramName)

      Return the request parameter of the given name, or `null` if none.

      Retrieves the first parameter value in case of a multi-value parameter.

      See Also:
        `ServletRequest.getParameter(String)`

    - #### getParameterValues

          String[] getParameterValues(String paramName)

      Return the request parameter values for the given parameter name, or `null` if none.

      A single-value parameter will be exposed as an array with a single element.

      See Also:
        `ServletRequest.getParameterValues(String)`

    - #### getParameterNames

          Iterator<String> getParameterNames()

      Return a Iterator over request parameter names.
      Since:
        3.0
      See Also:
        `ServletRequest.getParameterNames()`

    - #### getParameterMap

          Map<String,String[]> getParameterMap()

      Return a immutable Map of the request parameters, with parameter names as map keys and parameter values as map values. The map values will be of type String array.

      A single-value parameter will be exposed as an array with a single element.

      See Also:
        `ServletRequest.getParameterMap()`

    - #### getLocale

          Locale getLocale()

      Return the primary Locale for this request.
      See Also:
        `ServletRequest.getLocale()`

    - #### getContextPath

          String getContextPath()

      Return the context path for this request (usually the base path that the current web application is mapped to).
      See Also:
        `HttpServletRequest.getContextPath()`

    - #### getRemoteUser

          String getRemoteUser()

      Return the remote user for this request, if any.
      See Also:
        `HttpServletRequest.getRemoteUser()`

    - #### getUserPrincipal

          Principal getUserPrincipal()

      Return the user principal for this request, if any.
      See Also:
        `HttpServletRequest.getUserPrincipal()`

    - #### isUserInRole

          boolean isUserInRole(String role)

      Determine whether the user is in the given role for this request.
      See Also:
        `HttpServletRequest.isUserInRole(String)`

    - #### isSecure

          boolean isSecure()

      Return whether this request has been sent over a secure transport mechanism (such as SSL).
      See Also:
        `ServletRequest.isSecure()`

    - #### checkNotModified

          boolean checkNotModified(long lastModifiedTimestamp)

      Check whether the request qualifies as not modified given the supplied last-modified timestamp (as determined by the application).

      This will also transparently set the appropriate response headers, for both the modified case and the not-modified case.

      Typical usage:

           public String myHandleMethod(WebRequest webRequest, Model model) {
             long lastModified = // application-specific calculation
             if (request.checkNotModified(lastModified)) {
               // shortcut exit - no further processing necessary
               return null;
             }
             // further request processing, actually building content
             model.addAttribute(...);
             return "myViewName";
           }

      Note: that you typically want to use either this `checkNotModified(long)` method; or `checkNotModified(String)`, but not both.

      Parameters:
        `lastModifiedTimestamp` - the last-modified timestamp that the application determined for the underlying resource
      Returns:
        whether the request qualifies as not modified, allowing to abort request processing and relying on the response telling the client that the content has not been modified

    - #### checkNotModified

          boolean checkNotModified(String eTag)

      Check whether the request qualifies as not modified given the supplied `ETag` (entity tag), as determined by the application.

      This will also transparently set the appropriate response headers, for both the modified case and the not-modified case.

      Typical usage:

           public String myHandleMethod(WebRequest webRequest, Model model) {
             String eTag = // application-specific calculation
             if (request.checkNotModified(eTag)) {
               // shortcut exit - no further processing necessary
               return null;
             }
             // further request processing, actually building content
             model.addAttribute(...);
             return "myViewName";
           }

      Note: that you typically want to use either this `checkNotModified(String)` method; or `checkNotModified(long)`, but not both.

      Parameters:
        `eTag` - the entity tag that the application determined for the underlying resource. This parameter will be padded with quotes (") if necessary.
      Returns:
        whether the request qualifies as not modified, allowing to abort request processing and relying on the response telling the client that the content has not been modified

    - #### getDescription

          String getDescription(boolean includeClientInfo)

      Get a short description of this request, typically containing request URI and session id.
      Parameters:
        `includeClientInfo` - whether to include client-specific information such as session id and user name
      Returns:
        the requested description as String