Spring Framework

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):

The following return types are supported for handler 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
 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, DELETE, TRACE.
 java.lang.String[] params
          The parameters of the mapped request, narrowing the primary mapping.
 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.
 

value

public abstract java.lang.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.

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, 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 java.lang.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 java.lang.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 java.lang.String[] consumes
The consumable media types of the mapped request, narrowing the primary mapping.

The format is a sequence of media types ("text/plain", "application/*), with a request only mapped if the Content-Type matches one of these media types. 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 java.lang.String[] produces
The producible media types of the mapped request, narrowing the primary mapping.

The format is a sequence of media types ("text/plain", "application/*), with a request only mapped if the Accept matches one of these media types. 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:
{}

Spring Framework