public abstract @interface

RequestMapping

implements Annotation
org.springframework.web.bind.annotation.RequestMapping

Class Overview

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

NOTE: Method-level mappings are only allowed to narrow the mapping expressed at the class level (if any). In the Servlet case, an HTTP path needs to uniquely map onto one specific handler bean (not spread across multiple handler beans); the remaining mapping parameters and conditions are effectively assertions only. In the Portlet case, a portlet mode in combination with specific parameter conditions needs to uniquely map onto one specific handler bean, with all conditions evaluated for mapping purposes. It is strongly recommended to co-locate related handler methods into the same bean and therefore keep the mappings simple and intuitive.

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. javax.servlet.ServletRequest / javax.servlet.http.HttpServletRequest or javax.portlet.PortletRequest / javax.portlet.ActionRequest / javax.portlet.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 javax.servlet.http.HttpSession or javax.portlet.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 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+}.
  • @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 for access to the Servlet request HTTP contents. The request stream will be converted to the declared method argument type using message converters.
  • HttpEntity<?> parameters 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.
  • 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 AnnotationMethodHandlerAdapter. 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).

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 for access to the Servlet response HTTP contents. The return value will be converted to the response stream using message converters.
  • A HttpEntity<?> or ResponseEntity<?> object to access to the Servlet reponse HTTP headers and contents. The entity body will be converted to the response stream using message converters.
  • void if the method handles the response itself (by writing the response content directly, declaring an argument of type javax.servlet.ServletResponse / javax.servlet.http.HttpServletResponse / javax.portlet.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 a corresponding HandlerMapping (for type level annotations) and/or HandlerAdapter (for method level annotations) is present in the dispatcher. This is the case by default in both DispatcherServlet and DispatcherPortlet. However, if you are defining custom HandlerMappings or HandlerAdapters, then you need to make sure that a corresponding custom DefaultAnnotationHandlerMapping and/or AnnotationMethodHandlerAdapter is defined as well - provided that you intend to use @RequestMapping.

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.

See Also

Summary

[Expand]
Inherited Methods
From interface java.lang.annotation.Annotation