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

org.springframework.web.bind.annotation

## Annotation Type RequestMapping

-     @Target(value={METHOD,TYPE})
      @Retention(value=RUNTIME)
      @Documented
      public @interface RequestMapping

  Annotation for mapping web requests onto specific handler classes and/or handler methods. Provides a consistent style between Servlet and Portlet environments, with the semantics adapting to the concrete environment.

  NOTE: The set of features supported for Servlets is a superset of the set of features supported for Portlets. The places where this applies are marked with the label "Servlet-only" in this source file. For Servlet environments there are some further distinctions depending on whether an application is configured with "@MVC 3.0" or "@MVC 3.1" support classes. The places where this applies are marked with "@MVC 3.1-only" in this source file. For more details see the note on the new support classes added in Spring MVC 3.1 further below.

  Handler methods which are annotated with this annotation are allowed to have very flexible signatures. They may have arguments of the following types, in arbitrary order (except for validation results, which need to follow right after the corresponding command object, if desired):

  - Request and/or response objects (Servlet API or Portlet API). You may choose any specific request/response type, e.g. `ServletRequest` / `HttpServletRequest` or `PortletRequest` / `ActionRequest` / `RenderRequest`. Note that in the Portlet case, an explicitly declared action/render argument is also used for mapping specific request types onto a handler method (in case of no other information given that differentiates between action and render requests).
  - Session object (Servlet API or Portlet API): either `HttpSession` or `PortletSession`. An argument of this type will enforce the presence of a corresponding session. As a consequence, such an argument will never be `null`. Note that session access may not be thread-safe, in particular in a Servlet environment: Consider switching the `"synchronizeOnSession"` flag to "true" if multiple requests are allowed to access a session concurrently.
  - `WebRequest` or `NativeWebRequest`. Allows for generic request parameter access as well as request/session attribute access, without ties to the native Servlet/Portlet API.
  - `Locale` for the current request locale (determined by the most specific locale resolver available, i.e. the configured `LocaleResolver` in a Servlet environment and the portal locale in a Portlet environment).
  - `InputStream` / `Reader` for access to the request's content. This will be the raw InputStream/Reader as exposed by the Servlet/Portlet API.
  - `OutputStream` / `Writer` for generating the response's content. This will be the raw OutputStream/Writer as exposed by the Servlet/Portlet API.
  - `@PathVariable` annotated parameters (Servlet-only) for access to URI template values (i.e. /hotels/{hotel}). Variable values will be converted to the declared method argument type. By default, the URI template will match against the regular expression `[^\.]*` (i.e. any character other than period), but this can be changed by specifying another regular expression, like so: /hotels/{hotel:\d+}. Additionally, `@PathVariable` can be used on a `Map<String, String>` to gain access to all URI template variables.
  - `@MatrixVariable` annotated parameters (Servlet-only) for access to name-value pairs located in URI path segments. Matrix variables must be represented with a URI template variable. For example /hotels/{hotel} where the incoming URL may be "/hotels/42;q=1". Additionally, `@MatrixVariable` can be used on a `Map<String, String>` to gain access to all matrix variables in the URL or to those in a specific path variable.
  - `@RequestParam` annotated parameters for access to specific Servlet/Portlet request parameters. Parameter values will be converted to the declared method argument type. Additionally, `@RequestParam` can be used on a `Map<String, String>` or `MultiValueMap<String, String>` method parameter to gain access to all request parameters.
  - `@RequestHeader` annotated parameters for access to specific Servlet/Portlet request HTTP headers. Parameter values will be converted to the declared method argument type. Additionally, `@RequestHeader` can be used on a `Map<String, String>`, `MultiValueMap<String, String>`, or `HttpHeaders` method parameter to gain access to all request headers.
  - `@RequestBody` annotated parameters (Servlet-only) for access to the Servlet request HTTP contents. The request stream will be converted to the declared method argument type using message converters. Such parameters may optionally be annotated with `@Valid` and also support access to validation results through an `Errors` argument. Instead a `MethodArgumentNotValidException` exception is raised.
  - `@RequestPart` annotated parameters (Servlet-only, @MVC 3.1-only) for access to the content of a part of "multipart/form-data" request. The request part stream will be converted to the declared method argument type using message converters. Such parameters may optionally be annotated with `@Valid` and support access to validation results through a `Errors` argument. Instead a `MethodArgumentNotValidException` exception is raised.
  - `HttpEntity<?>` parameters (Servlet-only) for access to the Servlet request HTTP headers and contents. The request stream will be converted to the entity body using message converters.
  - `Map` / `Model` / `ModelMap` for enriching the implicit model that will be exposed to the web view.
  - `RedirectAttributes` (Servlet-only, @MVC 3.1-only) to specify the exact set of attributes to use in case of a redirect and also to add flash attributes (attributes stored temporarily on the server-side to make them available to the request after the redirect). `RedirectAttributes` is used instead of the implicit model if the method returns a "redirect:" prefixed view name or `RedirectView`.
  - Command/form objects to bind parameters to: as bean properties or fields, with customizable type conversion, depending on `InitBinder` methods and/or the HandlerAdapter configuration - see the "webBindingInitializer" property on RequestMappingHandlerMethodAdapter. Such command objects along with their validation results will be exposed as model attributes, by default using the non-qualified command class name in property notation (e.g. "orderAddress" for type "mypackage.OrderAddress"). Specify a parameter-level `ModelAttribute` annotation for declaring a specific model attribute name.
  - `Errors` / `BindingResult` validation results for a preceding command/form object (the immediate preceding argument).
  - `SessionStatus` status handle for marking form processing as complete (triggering the cleanup of session attributes that have been indicated by the `SessionAttributes` annotation at the handler type level).
  - `UriComponentsBuilder` (Servlet-only, @MVC 3.1-only) for preparing a URL relative to the current request's host, port, scheme, context path, and the literal part of the servlet mapping.

  The following return types are supported for handler methods:

  - A `ModelAndView` object (Servlet MVC or Portlet MVC), with the model implicitly enriched with command objects and the results of `ModelAttribute` annotated reference data accessor methods.
  - A `Model` object, with the view name implicitly determined through a `RequestToViewNameTranslator` and the model implicitly enriched with command objects and the results of `ModelAttribute` annotated reference data accessor methods.
  - A `Map` object for exposing a model, with the view name implicitly determined through a `RequestToViewNameTranslator` and the model implicitly enriched with command objects and the results of `ModelAttribute` annotated reference data accessor methods.
  - A `View` object, with the model implicitly determined through command objects and `ModelAttribute` annotated reference data accessor methods. The handler method may also programmatically enrich the model by declaring a `Model` argument (see above).
  - A `String` value which is interpreted as view name, with the model implicitly determined through command objects and `ModelAttribute` annotated reference data accessor methods. The handler method may also programmatically enrich the model by declaring a `ModelMap` argument (see above).
  - `@ResponseBody` annotated methods (Servlet-only) for access to the Servlet response HTTP contents. The return value will be converted to the response stream using message converters.
  - An `HttpEntity<?>` or `ResponseEntity<?>` object (Servlet-only) to access to the Servlet response HTTP headers and contents. The entity body will be converted to the response stream using message converters.
  - A `Callable` which is used by Spring MVC to obtain the return value asynchronously in a separate thread transparently managed by Spring MVC on behalf of the application.
  - A `org.springframework.web.context.request.async.DeferredResult` which the application uses to produce a return value in a separate thread of its own choosing, as an alternative to returning a Callable.
  - `void` if the method handles the response itself (by writing the response content directly, declaring an argument of type `ServletResponse` / `HttpServletResponse` / `RenderResponse` for that purpose) or if the view name is supposed to be implicitly determined through a `RequestToViewNameTranslator` (not declaring a response argument in the handler method signature; only applicable in a Servlet environment).
  - Any other return type will be considered as single model attribute to be exposed to the view, using the attribute name specified through `ModelAttribute` at the method level (or the default attribute name based on the return type's class name otherwise). The model will be implicitly enriched with command objects and the results of `ModelAttribute` annotated reference data accessor methods.

  NOTE: `@RequestMapping` will only be processed if an an appropriate `HandlerMapping`-`HandlerAdapter` pair is configured. This is the case by default in both the `DispatcherServlet` and the `DispatcherPortlet`. However, if you are defining custom `HandlerMappings` or `HandlerAdapters`, then you need to add `DefaultAnnotationHandlerMapping` and `AnnotationMethodHandlerAdapter` to your configuration..

  NOTE: Spring 3.1 introduced a new set of support classes for `@RequestMapping` methods in Servlet environments called `RequestMappingHandlerMapping` and `RequestMappingHandlerAdapter`. They are recommended for use and even required to take advantage of new features in Spring MVC 3.1 (search "@MVC 3.1-only" in this source file) and going forward. The new support classes are enabled by default from the MVC namespace and with use of the MVC Java config (`@EnableWebMvc`) but must be configured explicitly if using neither.

  NOTE: When using controller interfaces (e.g. for AOP proxying), make sure to consistently put all your mapping annotations - such as `@RequestMapping` and `@SessionAttributes` - on the controller interface rather than on the implementation class.

  Since:
    2.5
  Author:
    Juergen Hoeller, Arjen Poutsma, Sam Brannen
  See Also:
    `RequestParam`, `ModelAttribute`, `SessionAttributes`, `InitBinder`, `WebRequest`, `RequestMappingHandlerAdapter`, `DefaultAnnotationHandlerMapping`, `AnnotationMethodHandlerAdapter`

- - ### Optional Element Summary

    Optional Elements
    Modifier and Type | Optional Element and Description
    --- | ---
    `String[]` | `consumes` The consumable media types of the mapped request, narrowing the primary mapping.
    `String[]` | `headers` The headers of the mapped request, narrowing the primary mapping.
    `RequestMethod[]` | `method` The HTTP request methods to map to, narrowing the primary mapping: GET, POST, HEAD, OPTIONS, PUT, PATCH, DELETE, TRACE.
    `String[]` | `params` The parameters of the mapped request, narrowing the primary mapping.
    `String[]` | `produces` The producible media types of the mapped request, narrowing the primary mapping.
    `String[]` | `value` The primary mapping expressed by this annotation.

- - ### Element Detail

    - #### value

          public abstract String[] value

      The primary mapping expressed by this annotation.

      In a Servlet environment: the path mapping URIs (e.g. "/myPath.do"). Ant-style path patterns are also supported (e.g. "/myPath/*.do"). At the method level, relative paths (e.g. "edit.do") are supported within the primary mapping expressed at the type level. Path mapping URIs may contain placeholders (e.g. "/${connect}")

      In a Portlet environment: the mapped portlet modes (i.e. "EDIT", "VIEW", "HELP" or any custom modes).

      Supported at the type level as well as at the method level! When used at the type level, all method-level mappings inherit this primary mapping, narrowing it for a specific handler method.

      Default:
        {}

    - #### method

          public abstract RequestMethod[] method

      The HTTP request methods to map to, narrowing the primary mapping: GET, POST, HEAD, OPTIONS, PUT, PATCH, DELETE, TRACE.

      Supported at the type level as well as at the method level! When used at the type level, all method-level mappings inherit this HTTP method restriction (i.e. the type-level restriction gets checked before the handler method is even resolved).

      Supported for Servlet environments as well as Portlet 2.0 environments.

      Default:
        {}

    - #### params

          public abstract String[] params

      The parameters of the mapped request, narrowing the primary mapping.

      Same format for any environment: a sequence of "myParam=myValue" style expressions, with a request only mapped if each such parameter is found to have the given value. Expressions can be negated by using the "!=" operator, as in "myParam!=myValue". "myParam" style expressions are also supported, with such parameters having to be present in the request (allowed to have any value). Finally, "!myParam" style expressions indicate that the specified parameter is not supposed to be present in the request.

      Supported at the type level as well as at the method level! When used at the type level, all method-level mappings inherit this parameter restriction (i.e. the type-level restriction gets checked before the handler method is even resolved).

      In a Servlet environment, parameter mappings are considered as restrictions that are enforced at the type level. The primary path mapping (i.e. the specified URI value) still has to uniquely identify the target handler, with parameter mappings simply expressing preconditions for invoking the handler.

      In a Portlet environment, parameters are taken into account as mapping differentiators, i.e. the primary portlet mode mapping plus the parameter conditions uniquely identify the target handler. Different handlers may be mapped onto the same portlet mode, as long as their parameter mappings differ.

      Default:
        {}

    - #### headers

          public abstract String[] headers

      The headers of the mapped request, narrowing the primary mapping.

      Same format for any environment: a sequence of "My-Header=myValue" style expressions, with a request only mapped if each such header is found to have the given value. Expressions can be negated by using the "!=" operator, as in "My-Header!=myValue". "My-Header" style expressions are also supported, with such headers having to be present in the request (allowed to have any value). Finally, "!My-Header" style expressions indicate that the specified header is not supposed to be present in the request.

      Also supports media type wildcards (*), for headers such as Accept and Content-Type. For instance,

           @RequestMapping(value = "/something", headers = "content-type=text/*")

      will match requests with a Content-Type of "text/html", "text/plain", etc.

      Supported at the type level as well as at the method level! When used at the type level, all method-level mappings inherit this header restriction (i.e. the type-level restriction gets checked before the handler method is even resolved).

      Maps against HttpServletRequest headers in a Servlet environment, and against PortletRequest properties in a Portlet 2.0 environment.

      See Also:
        `MediaType`
      Default:
        {}

    - #### consumes

          public abstract String[] consumes

      The consumable media types of the mapped request, narrowing the primary mapping.

      The format is a single media type or a sequence of media types, with a request only mapped if the `Content-Type` matches one of these media types. Examples:

           consumes = "text/plain"
           consumes = {"text/plain", "application/*"}

      Expressions can be negated by using the "!" operator, as in "!text/plain", which matches all requests with a `Content-Type` other than "text/plain".

      Supported at the type level as well as at the method level! When used at the type level, all method-level mappings override this consumes restriction.

      See Also:
        `MediaType`, `ServletRequest.getContentType()`
      Default:
        {}

    - #### produces

          public abstract String[] produces

      The producible media types of the mapped request, narrowing the primary mapping.

      The format is a single media type or a sequence of media types, with a request only mapped if the `Accept` matches one of these media types. Examples:

           produces = "text/plain"
           produces = {"text/plain", "application/*"}

      Expressions can be negated by using the "!" operator, as in "!text/plain", which matches all requests with a `Accept` other than "text/plain".

      Supported at the type level as well as at the method level! When used at the type level, all method-level mappings override this consumes restriction.

      See Also:
        `MediaType`
      Default:
        {}