org.springframework.web.bind.annotation Documentation Differences

This file contains all the changes in documentation in the package org.springframework.web.bind.annotation as colored differences. Deletions are shown like this, and additions are shown like this.

If no deletions or additions are shown in an entry, the HTML tags will be what has changed. The new HTML tags are shown in the differences. If no documentation existed, and then some was added in a later version, this change is noted in the appropriate class pages of differences, but the change is not shown on this page. Only changes in existing text are shown here. Similarly, documentation which was inherited from another class or interface is not shown here.

Note that an HTML error in the new documentation may cause the display of other documentation changes to be presented incorrectly. For instance, failure to close a <code> tag will cause all subsequent paragraphs to be displayed differently.

Annotation which indicates that a method parameter should be bound to an HTTP cookie. Supported for annotated handler methods in Servlet and Portlet environments.

The method parameter may be declared as type javax.servlet.http.Cookie or as cookie value type (String, int, etc). @author Juergen Hoeller @since 3.0 @see RequestMapping @see RequestParam @see RequestHeader @see org.springframework.web.bind.annotation.RequestMapping @see org.springframework.web.servlet.mvc.method.annotation.RequestMappingHandlerMethodAdapter RequestMappingHandlerAdapter @see org.springframework.web.servlet.mvc.annotation.AnnotationMethodHandlerAdapter @see org.springframework.web.portlet.mvc.annotation.AnnotationMethodHandlerAdapter

Annotation for handling exceptions in specific handler classes and/or handler methods. Provides consistent style between Servlet and Portlet environments, with the semantics adapting to the concrete environment.

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:

• An exception argument: declared as a general Exception or as a more specific exception. This also serves as a mapping hint if the annotation itself does not narrow the exception types through its .value().
• 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.
• org.springframework.web.context.request.WebRequest or org.springframework.web.context.request.NativeWebRequest. Allows for generic request parameter access as well as request/session attribute access, without ties to the native Servlet/Portlet API.
• java.util.Locale for the current request locale (determined by the most specific locale resolver available, i.e. the configured org.springframework.web.servlet.LocaleResolver in a Servlet environment and the portal locale in a Portlet environment).
• java.io.InputStream / java.io.Reader for access to the request's content. This will be the raw InputStream/Reader as exposed by the Servlet/Portlet API.
• java.io.OutputStream / java.io.Writer for generating the response's content. This will be the raw OutputStream/Writer as exposed by the Servlet/Portlet API.

The following return types are supported for handler methods:

• A ModelAndView object (Servlet MVC or Portlet MVC).
• A Model object, with the view name implicitly determined through a org.springframework.web.servlet.RequestToViewNameTranslator.
• A java.util.Map object for exposing a model, with the view name implicitly determined through a org.springframework.web.servlet.RequestToViewNameTranslator.
• A org.springframework.web.servlet.View object.
• A java.lang.String value which is interpreted as view name.
• @ResponseBody annotated methods (Servlet-only) to set the response content. The return value will be converted to the response stream using org.springframework.http.converter.HttpMessageConverter message converters.
• An HttpEntity<?> or ResponseEntity<?> object (Servlet-only) to set response headers and content. The ResponseEntity body will be converted and written to the response stream using org.springframework.http.converter.HttpMessageConverter 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 org.springframework.web.servlet.RequestToViewNameTranslator (not declaring a response argument in the handler method signature; only applicable in a Servlet environment).

In Servlet environments, you can combine the {@code ExceptionHandler} annotation with @ResponseStatus, to define the response status for the HTTP response.

Note: In Portlet environments, {@code ExceptionHandler} annotated methods will only be called during the render and resource phases - just like org.springframework.web.portlet.HandlerExceptionResolver beans would. Exceptions carried over from the action and event phases will be invoked during the render phase as well, with exception handler methods having to be present on the controller class that defines the applicable render method. @author Arjen Poutsma @author Juergen Hoeller @since 3.0 @see org.springframework.web.context.request.WebRequest @see org.springframework.web.servlet.mvc.annotation.AnnotationMethodHandlerExceptionResolver @see org.springframework.web.portlet.mvc.annotation.AnnotationMethodHandlerExceptionResolver

Annotation which indicates that a method parameter should be bound to a URI template variable. Supported for RequestMapping annotated handler methods in Servlet environments. @author Arjen Poutsma @see RequestMapping @see org.springframework.web.servlet.mvc.method.annotation.RequestMappingHandlerMethodAdapter RequestMappingHandlerAdapter @see org.springframework.web.servlet.mvc.annotation.AnnotationMethodHandlerAdapter @since 3.0

Annotation indicating a method parameter should be bound to the body of the web request. The body of the request is passed through an HttpMessageConverter to resolve the the method argument depending on the content type of the request. Optionally, automaticautomatic validation can be applied by annotating the argument with {@code @Valid}.

Supported for annotated handler methods in Servlet environments. @author Arjen Poutsma @see RequestHeader @see ResponseBody @see org.springframework.web.servlet.mvc.method.annotation.RequestMappingHandlerMethodAdapter RequestMappingHandlerAdapter @see org.springframework.web.servlet.mvc.annotation.AnnotationMethodHandlerAdapter @since 3.0

Annotation which indicates that a method parameter should be bound to a web request header. Supported for annotated handler methods in Servlet and Portlet environments. @author Juergen Hoeller @since 3.0 @see RequestMapping @see RequestParam @see CookieValue @see org.springframework.web.servlet.mvc.method.annotation.RequestMappingHandlerMethodAdapter RequestMappingHandlerAdapter @see org.springframework.web.portlet.mvc.annotation.AnnotationMethodHandlerAdapter

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: Method-level mappings are only allowed to narrowThe the mapping expressed at the class levelset of features supported for Servlets is (ifa any).superset Inof the Servlet case,set an HTTP path needsof features supported for to Portlets. uniquely map onto one specific handler beanThe places where this applies are marked (notwith spread acrossthe label multiple"Servlet-only" handlerin beans); this thesource remainingfile. mapping parameters and conditionsFor Servlet environments there are effectivelysome assertionsfurther only. Indistinctions the Portletdepending case,on a portlet mode in combinationwhether an application is configured with specific{@literal parameter"@MVC conditions 3.0"} needsor to{@literal uniquely"@MVC map3.1"} ontosupport oneclasses. specific handlerThe places bean,where with all conditions evaluated forthis applies are marked with mapping{@literal "@MVC purposes3.1-only"} It is stronglyin this source recommendedfile. toFor co-locatemore related handler methods intodetails see the note on the same bean and therefore keep the mappingsnew support classes added in Spring MVC simple3.1 and intuitivefurther 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. 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.
• org.springframework.web.context.request.WebRequest or org.springframework.web.context.request.NativeWebRequest. Allows for generic request parameter access as well as request/session attribute access, without ties to the native Servlet/Portlet API.
• java.util.Locale for the current request locale (determined by the most specific locale resolver available, i.e. the configured org.springframework.web.servlet.LocaleResolver in a Servlet environment and the portal locale in a Portlet environment).
• java.io.InputStream / java.io.Reader for access to the request's content. This will be the raw InputStream/Reader as exposed by the Servlet/Portlet API.
• java.io.OutputStream / java.io.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 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 {@code [^\.]*} (i.e. any character other than period), but this can be changed by specifying another regular expression, like so: /hotels/{hotel:\d+}. Additionally, {@code @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, {@code @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, {@code @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, {@code @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 to the Servlet request HTTP contents. The request stream will be converted to the declared method argument type using using org.springframework.http.converter.HttpMessageConverter message converters. Such parameters may optionally be annotated with {@code @Valid} and also support access to validation results through an org.springframework.validation.Errors argument. Instead a org.springframework.web.servlet.mvc.method.annotation.MethodArgumentNotValidException exception is raised.
• @RequestPart annotated parametersparameters (Servlet-only, {@literal @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 using org.springframework.http.converter.HttpMessageConverter message converters. Such parameters may optionally be annotated with {@code @Valid} and support access to validation results through a org.springframework.validation.Errors argument. Instead a org.springframework.web.servlet.mvc.method.annotation.MethodArgumentNotValidException exception is raised.
• HttpEntity<?> parameters (Servlet-only) for access to the Servlet request HTTP headers and contents. The request stream will be be converted to the entity body using org.springframework.http.converter.HttpMessageConverter message converters.
• java.util.Map / org.springframework.ui.Model / org.springframework.ui.ModelMap for enriching the implicit model that will be exposed to the web view.
• org.springframework.web.servlet.mvc.support.RedirectAttributes (Servlet-only, {@literal @MVC 3.1-only}) to specify the exact set of attributesattributes to use in case of a redirect redirect and also to add flash attributes (attributesattributes stored temporarily on the server-side to make them available to the requestrequest after the redirect). {@code RedirectAttributes} is used instead of thethe implicit model if the method returns a "redirect:" prefixed view name oror {@code 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.
• org.springframework.validation.Errors / org.springframework.validation.BindingResult validation results for a preceding command/form object (the immediate preceding argument).
• org.springframework.web.bind.support.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).
• org.springframework.web.util.UriComponentsBuilder a(Servlet-only, builder{@literal for @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 org.springframework.web.servlet.RequestToViewNameTranslator and the model implicitly enriched with command objects and the results of ModelAttribute annotated reference data accessor methods.
• A java.util.Map object for exposing a model, with the view name implicitly determined through a org.springframework.web.servlet.RequestToViewNameTranslator and the model implicitly enriched with command objects and the results of ModelAttribute annotated reference data accessor methods.
• A org.springframework.web.servlet.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 org.springframework.ui.Model argument (see above).
• A java.lang.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 org.springframework.ui.ModelMap argument (see above).
• @ResponseBody annotated methods (Servlet-only) for access to to the Servlet response HTTP contents. The return value willwill be converted converted to the response stream using org.springframework.http.converter.HttpMessageConverter message converters.
• AAn HttpEntity<?> or ResponseEntity<?> object (Servlet-only) to access to the Servlet response HTTP headers and contents. The entity body will will be converted to the response stream using org.springframework.http.converter.HttpMessageConverter 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 {@code 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 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 org.springframework.web.servlet.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 an correspondingan appropriate HandlerMapping (for type level annotations) and/or -HandlerAdapter (for method level annotations) is present inpair the dispatcheris configured. This is the case by default in both both the DispatcherServlet and the DispatcherPortlet. However, if you are defining custom HandlerMappings or HandlerAdapters, then you need to makeadd sureDefaultAnnotationHandlerMapping thatand a AnnotationMethodHandlerAdapter correspondingto customyour configuration..

NOTE: Spring 3.1 introduced a new set of support classes for RequestMappingHandlerMethodMapping@RequestMapping and/ormethods in Servlet environments called RequestMappingHandlerMethodAdapterRequestMappingHandlerMapping isand RequestMappingHandlerAdapter. defined as well - provided that you intendThey are recommended for use and even required to take advantage of new features in Spring MVC 3.1 (search {@literal "@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 (@RequestMappingEnableWebMvc) 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. @author Juergen Hoeller @author Arjen Poutsma @author Sam Brannen @since 2.5 @see RequestParam @see ModelAttribute @see SessionAttributes @see InitBinder @see org.springframework.web.context.request.WebRequest @see org.springframework.web.servlet.mvc.method.annotation.RequestMappingHandlerMethodMapping @see org.springframework.web.servlet.mvc.method.annotation.RequestMappingHandlerMethodAdapter RequestMappingHandlerAdapter @see org.springframework.web.portlet.mvc.annotation.DefaultAnnotationHandlerMapping @see org.springframework.web.portlet.mvc.annotation.AnnotationMethodHandlerAdapter

Java 5 enumeration of HTTP request methods. Intended for use with the RequestMapping.method() attribute of the RequestMapping annotation.

Note that, by default, org.springframework.web.servlet.DispatcherServlet supports GET, HEAD, POST, PUT, PATCH and DELETE only. DispatcherServlet will process TRACE and OPTIONS with the default HttpServlet behavior unless explicitly told to dispatch those request types as well: Check out the "dispatchOptionsRequest" and "dispatchTraceRequest" properties, switching them to "true" if necessary. @author Juergen Hoeller @since 2.5 @see RequestMapping @see org.springframework.web.servlet.DispatcherServlet#setDispatchOptionsRequest @see org.springframework.web.servlet.DispatcherServlet#setDispatchTraceRequest

Annotation which indicates that a method parameter should be bound to a web request parameter. Supported for annotated handler methods in Servlet and Portlet environments.

If the method parameter type is Map and a request parameter name is specified, then the request parameter value is converted to a Map assuming an appropriate conversion strategy is available.

If the method parameter is Map<String, String> or MultiValueMap<String, String> and a parameter name is not specified, then the map parameter is populated with all request parameter names and values. @author Arjen Poutsma @author Juergen Hoeller @since 2.5 @see RequestMapping @see RequestHeader @see CookieValue @see org.springframework.web.servlet.mvc.method.annotation.RequestMappingHandlerMethodAdapter RequestMappingHandlerAdapter @see org.springframework.web.servlet.mvc.annotation.AnnotationMethodHandlerAdapter @see org.springframework.web.portlet.mvc.annotation.AnnotationMethodHandlerAdapter