@Target(value={METHOD,TYPE})
@Retention(value=RUNTIME)
@Documented
public @interface RequestMapping
Handler methods which are annotated with this annotation are allowed to have very flexible signatures. They may have parameters of the following types, in arbitrary order (except for validation results, which need to follow right after the corresponding command object, if desired):
javax.servlet.ServletRequest
/ javax.servlet.http.HttpServletRequest
.
javax.servlet.http.HttpSession
.
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 API.
Locale
for the current request locale
(determined by the most specific locale resolver available,
i.e. the configured LocaleResolver
in a Servlet environment).
InputStream
/ Reader
for access
to the request's content. This will be the raw InputStream/Reader as
exposed by the Servlet API.
OutputStream
/ Writer
for generating
the response's content. This will be the raw OutputStream/Writer as
exposed by the Servlet API.
HttpMethod
for the HTTP request method@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 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 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.
@SessionAttribute
annotated parameters for access
to existing, permanent session attributes (e.g. user authentication object)
as opposed to model attributes temporarily stored in the session as part of
a controller workflow via SessionAttributes
.
@RequestAttribute
annotated parameters for access
to request attributes.
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
.
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.
Note: Java 8's java.util.Optional
is supported
as a method parameter type with annotations that provide a required
attribute (e.g. @RequestParam
, @RequestHeader
, etc.). The use
of java.util.Optional
in those cases is equivalent to having
required=false
.
The following return types are supported for handler methods:
ModelAndView
object (from Servlet MVC),
with the model implicitly enriched with command objects and the results
of @ModelAttribute
annotated reference data accessor methods.
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.
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.
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).
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.
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.
HttpHeaders
object to
return a response with no body.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.
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.
ListenableFuture
which the application uses to produce a return value in a separate
thread of its own choosing, as an alternative to returning a Callable.
CompletionStage
(implemented by
CompletableFuture
for example)
which the application uses to produce a return value in a separate
thread of its own choosing, as an alternative to returning a Callable.
ResponseBodyEmitter
can be used to write multiple objects to the response asynchronously;
also supported as the body within ResponseEntity
.SseEmitter
can be used to write Server-Sent Events to the response asynchronously;
also supported as the body within ResponseEntity
.StreamingResponseBody
can be used to write to the response asynchronously;
also supported as the body within ResponseEntity
.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
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).
@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. If you are defining custom HandlerMappings
or
HandlerAdapters
, then you need to add RequestMappingHandlerMapping
and RequestMappingHandlerAdapter
to your configuration..
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.
GetMapping
,
PostMapping
,
PutMapping
,
DeleteMapping
,
PatchMapping
,
RequestParam
,
RequestAttribute
,
PathVariable
,
ModelAttribute
,
SessionAttribute
,
SessionAttributes
,
InitBinder
,
WebRequest
,
RequestMappingHandlerAdapter
Modifier and Type | Optional Element and Description |
---|---|
java.lang.String[] |
consumes
The consumable media types of the mapped request, narrowing the primary mapping.
|
java.lang.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.
|
java.lang.String |
name
Assign a name to this mapping.
|
java.lang.String[] |
params
The parameters of the mapped request, narrowing the primary mapping.
|
java.lang.String[] |
path
In a Servlet environment only: the path mapping URIs (e.g.
|
java.lang.String[] |
produces
The producible media types of the mapped request, narrowing the primary mapping.
|
java.lang.String[] |
value
The primary mapping expressed by this annotation.
|
public abstract java.lang.String name
Supported at the type level as well as at the method level! When used on both levels, a combined name is derived by concatenation with "#" as separator.
@AliasFor(value="path") public abstract java.lang.String[] value
This is an alias for path()
. For example
@RequestMapping("/foo")
is equivalent to
@RequestMapping(path="/foo")
.
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.
@AliasFor(value="value") public abstract java.lang.String[] path
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.
ValueConstants.DEFAULT_NONE
public abstract RequestMethod[] method
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).
public abstract java.lang.String[] params
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).
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.
public abstract java.lang.String[] headers
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).
MediaType
public abstract java.lang.String[] consumes
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.
MediaType
,
javax.servlet.http.HttpServletRequest#getContentType()
public abstract java.lang.String[] produces
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/*"} produces = "application/json; charset=UTF-8"
It affects the actual content type written, for example to produce a JSON response
with UTF-8 encoding, "application/json; charset=UTF-8"
should be used.
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 produces restriction.
MediaType