org.springframework.web.servlet.mvc.method.annotation Documentation Differences

This file contains all the changes in documentation in the package org.springframework.web.servlet.mvc.method.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.

A base class for resolving method argument values by reading from the body ofof a request with HttpMessageConverters. @author Arjen Poutsma @author Rossen Stoyanchev @since 3.1

Extends AbstractMessageConverterMethodArgumentResolver with the ability to handle method returnreturn values by writing to the response with HttpMessageConverters. @author Arjen Poutsma @author Rossen Stoyanchev @since 3.1

An AbstractHandlerMethodExceptionResolver that resolves exceptions through {@code @ExceptionHandler} methods.

Support for custom argument and return value types can be added via .setCustomArgumentResolvers and .setCustomReturnValueHandlers. Or alternatively to re-configure all argument and return value types use .setArgumentResolvers and .setReturnValueHandlers(List). @author Rossen Stoyanchev @since 3.1

Find an {@code @ExceptionHandler} method and invoke it to handle the raised exception.

Return the configured argument resolvers, or possibly {@code null} ifif not initialized yet via .afterPropertiesSet().

Return the list of return value handlers to use including built-in andand custom handlers provided via .setReturnValueHandlers.

Find thean {@code @ExceptionHandler} method for the given exception. The defaultdefault implementation searches @ExceptionHandler methods in the class hierarchy of the method that raised thecontroller first and if exceptionnot found, it continues searching for additional {@code @ExceptionHandler} methods assuming some ControllerAdvice @ControllerAdvice Spring-managed beans were detected. @param handlerMethod the method where the exception was raised raised, possibly {@code null} @param exception the raised exception @return a method to handle the exception, or {@code null}

Return the configured handlers, or possibly {@code null} if notnot initialized yet via .afterPropertiesSet().

Provide resolvers for custom argument types. Custom resolvers are ordered after built-in ones. To override the built-in support for argument argument resolution use .setArgumentResolvers instead.

Configure the complete list of supported return value types thusthus overriding handlers that would otherwise be configured by default.

AddMerge URI template variables tointo the property values usedto use for data binding.

Resolves HttpEntity method argument values and also handles both HttpEntity and ResponseEntity return values.

An HttpEntity return type has a set purpose. Therefore this this handler should be configured ahead of handlers that support any return return value type annotated with {@code @ModelAttribute} or {@code @ResponseBody} to ensure they don't take over. @author Arjen Poutsma @author Rossen Stoyanchev @since 3.1

Handles return values of type ModelAndView copying view and modelmodel information to the ModelAndViewContainer.

If the return value is {@code null}, the the ModelAndViewContainer.setRequestHandled(boolean) flag is set to to {@code false} to indicate the request was handled directly.

A ModelAndView return type has a set purpose. Therefore thisthis handler should be configured ahead of handlers that support any return return value type annotated with {@code @ModelAttribute} or {@code @ResponseBody} to ensure they don't take over. @author Rossen Stoyanchev @since 3.1

This return value handler is intended to be ordered after all others as it it attempts to handle _any_ return value type (i.e. returns {@code true} for all return types).

The return value is handled either with a ModelAndViewResolver or otherwise by regarding it as a model attribute if it is a non-simplesimple type. If neither of these succeeds (essentially simple type other than than String), UnsupportedOperationException is raised.

Note: This class is primarily needed to supportsupport ModelAndViewResolver, which unfortunately cannot be properly adapted to the HandlerMethodReturnValueHandler contract since the the HandlerMethodReturnValueHandler.supportsReturnType method cannot be implemented. Hence {@code ModelAndViewResolver}s are limited to always being invoked at the end after all other return value value handlers have been given a chance. It is recommended to re-implement implement a {@code ModelAndViewResolver} as {@code HandlerMethodReturnValueHandler}, which also provides better access to the return type and method information. @author Rossen Stoyanchev @since 3.1

Resolves method arguments annotated with an @PathVariable.

An @PathVariable is a named value that gets resolved from a URIURI template variable. It is always required and does not have a default valuevalue to fall back on. See the base classclass org.springframework.web.method.annotation.AbstractNamedValueMethodArgumentResolver for more information on how named values are processed.

If the method parameter type is Map, the name specified in the annotation is used to resolve the URI variable String value. The value is then converted to a Map via type conversion assuming a suitable Converter or PropertyEditor has been registered. Or if the annotation does not specify name the RequestParamMapMethodArgumentResolver is used instead to provide access to all URI variables in a map.

A WebDataBinder is invoked to apply type conversion to resolved path variable values that that don't yet match the method parameter type. @author Rossen Stoyanchev @author Arjen Poutsma @since 3.1

Resolves method arguments of type RedirectAttributes.

This resolver must be listed ahead of org.springframework.web.method.annotation.ModelMethodProcessor and org.springframework.web.method.annotation.MapMethodProcessor, which support Map and Model arguments both of which are "super" types of {@code RedirectAttributes} and would also attempt to resolve a {@code RedirectAttributes} argument. @author Rossen Stoyanchev @since 3.1

An AbstractHandlerMethodAdapter that supports HandlerMethods with the signature -- method argument and return types, defined inin {@code @RequestMapping}.

Support for custom argument and return value types can be added via .setCustomArgumentResolvers and .setCustomReturnValueHandlers. Or alternatively to re-configure all argument and return value types use .setArgumentResolvers and .setReturnValueHandlers(List). @author Rossen Stoyanchev @since 3.1 @see HandlerMethodArgumentResolver @see HandlerMethodReturnValueHandler

Return the configured argument resolvers, or possibly {@code null} ifif not initialized yet via .afterPropertiesSet().

This implementation always returns -1. An {@code @RequestMapping} method can calculate the lastModified value, call call WebRequest.checkNotModified(long), and return {@code null} if the result of that call is {@code true}.

Return the configured handlers, or possibly {@code null} if notnot initialized yet via .afterPropertiesSet().

{@inheritDoc}

A ConfigurableBeanFactory is expected for resolvingresolving expressions in method argument default values.

Cache content produced by @SessionAttributes annotated handlers for the given number of seconds. Default is 0, preventing caching completely.

In contrast to the "cacheSeconds" property which will apply to all generalgeneral handlers (but not to @SessionAttributes annotated handlers), this setting will apply to @SessionAttributes handlers only. @see #setCacheSeconds @see org.springframework.web.bind.annotation.SessionAttributes

Provide resolvers for custom argument types. Custom resolvers are ordered after built-in ones. To override the built-in support for argument argument resolution use .setArgumentResolvers instead.

By default the content of the "default" model is used both duringduring rendering and redirect scenarios. Alternatively a controller method method can declare a RedirectAttributes argument and use it to provide attributes for a redirect.

Setting this flag to {@code true} guarantees the "default" model is is never used in a redirect scenario even if a RedirectAttributes argument argument is not declared. Setting it to {@code false} means the "default" model model may be used in a redirect if the controller method doesn't declare a a RedirectAttributes argument.

The default setting is {@code false} but new applications should should consider setting it to {@code true}. @see RedirectAttributes

Provide the converters to use in argument resolvers and return valuevalue handlers that support reading and/or writing to the body of the the request and response.

Provide custom ModelAndViewResolvers.

Note: This method is available for backwards backwards compatibility only. However, it is recommended to re-write a a {@code ModelAndViewResolver} as HandlerMethodReturnValueHandler. An adapter between the two interfaces is not possible since the the HandlerMethodReturnValueHandler.supportsReturnType method cannot be implemented. Hence {@code ModelAndViewResolver}s are limited to always being invoked at the end after all other return value value handlers have been given a chance.

A {@code HandlerMethodReturnValueHandler} provides better access to to the return type and controller method information and can be ordered freely relative to other return value handlers.

Set the ParameterNameDiscoverer to use for resolving method parameterparameter names if needed (e.g. for default attribute names). Default is a a org.springframework.core.LocalVariableTableParameterNameDiscoverer.

Configure the complete list of supported return value types thusthus overriding handlers that would otherwise be configured by default.

Specify the strategy to store session attributes with. The default isis org.springframework.web.bind.support.DefaultSessionAttributeStore, storing session attributes in the HttpSession with the same attribute attribute name as in the model.

Provide a WebBindingInitializer with "global" initialization to applyapply to every DataBinder instance.

ReturnAlways return {@code true} if all arguments and thesince any method argument and return valuevalue type of the given HandlerMethodwill be processed in some areway. A method supportedargument not recognized by the configured resolversany HandlerMethodArgumentResolver is andinterpreted as a request parameter if it is a simple type, or as a model attribute otherwise. A return value not recognized by any HandlerMethodReturnValueHandler will be interpreted as a model handlersattribute.

Creates RequestMappingInfo instances from type and method-levellevel @RequestMapping annotations in in @Controller classes. @author Arjen Poutsma @author Rossen Stoyanchev @since 3.1

Provide a custom method-level request condition. The custom RequestCondition can be of any type so long as the the same condition type is returned from all calls to this method in order to ensure custom request conditions can be combined and compared.

Consider extending AbstractRequestCondition for custom condition types and using CompositeRequestCondition to provide multiple custom conditions. @param method the handler method for which to create the condition @return the condition, or {@code null}

Provide a custom type-level request condition. The custom RequestCondition can be of any type so long as the the same condition type is returned from all calls to this method in order to ensure custom request conditions can be combined and compared.

Consider extending AbstractRequestCondition for custom condition types and using CompositeRequestCondition to provide multiple custom conditions. @param methodhandlerType the handler methodtype for which to create the condition @return the condition, or {@code null}

Uses method and type-level @RequestMapping annotations to create the RequestMappingInfo. @return the created RequestMappingInfo, or {@code null} if the method does not have a {@code @RequestMapping} annotation. @see #getCustomMethodCondition(Method) @see #getCustomTypeCondition(Class)

{@inheritDoc} Expects a handler to have a type-level @Controller annotation.

Resolves the following method arguments:

• Annotated with {@code @RequestPart}
• Of type MultipartFile in conjunction with Spring'ss MultipartResolver abstraction
• Of type {@code javax.servlet.http.Part} in conjunction with with Servlet 3.0 multipart requests

When a parameter is annotated with {@code @RequestPart} the content of the the part is passed through an HttpMessageConverter to resolve the method method argument with the 'Content-Type' of the request part in mind. This is is analogous to what @RequestBody does to resolve an argument based on the content of a regular request.

When a parameter is not annotated or the name of the part is not specified, it is derived from the name of the method argument.

Automatic validation may be applied if the argument is annotated with with {@code @javax.validation.Valid}. In case of validation failure, a a MethodArgumentNotValidException is raised and a 400 response status code returned if DefaultHandlerExceptionResolver is configured. @author Rossen Stoyanchev @since 3.1

Resolves method arguments annotated with {@code @RequestBody} and handleshandles return values from methods annotated with {@code @ResponseBody} by reading and writing to the body of the request or response with an an HttpMessageConverter.

An {@code @RequestBody} method argument is also validated if it is is annotated with {@code @javax.validation.Valid}. In case of validation validation failure, MethodArgumentNotValidException is raised and results results in a 400 response status code if DefaultHandlerExceptionResolver is configured. @author Arjen Poutsma @author Rossen Stoyanchev @since 3.1

Extends InvocableHandlerMethod with the ability to handle the value returned from thereturn method through values through a registered HandlerMethodArgumentResolverHandlerMethodReturnValueHandler thatand also supports setting the given returnresponse status valuebased on a method-level {@code @ResponseStatus} typeannotation. Return

A value{@code handlingnull} may includereturn value writing(including tovoid) the response or updating themay be interpreted as the ModelAndViewContainerend structure. of Ifrequest the underlying method hasprocessing in combination with a {@code @ResponseStatus} instructionannotation, the status ona thenot-modified response ischeck condition set (see accordinglyServletWebRequest.checkNotModified(long)), after theor a method isargument invoked butthat before the return value is handledprovides access to the response stream. @author Rossen Stoyanchev @since 3.1 @see #invokeAndHandle(NativeWebRequest, ModelAndViewContainer, Object...)1

Creates aan ServletInvocableHandlerMethod instance withfrom the given beanhandler and method. @param handler the object handler @param method the method

Invokes the method and handles the return value through a registeredregistered HandlerMethodReturnValueHandler. Return value handling may be skipped entirely when the method returns {@code null} (also possibly due to a {@code void} return type) and one of the following additional conditions is true: A HandlerMethodArgumentResolver has set the ModelAndViewContainer.setRequestHandled(boolean) flag to {@code false} -- e.g. method arguments providing access to the response. The request qualifies as "not modified" as defined in ServletWebRequest.checkNotModified(long) and ServletWebRequest.checkNotModified(String). In this case a response with "not modified" response headers will be automatically generated without the need for return value handling. The status on the response is set due to a @ResponseStatus instruction. After the return value is handled, callers of this method can use the ModelAndViewContainer to gain access to model attributes, view selection choices, and to check if view resolution is even needed. @param requestwebRequest the current request @param mavContainer the ModelAndViewContainer for the currentthis request @param providedArgs argument values to try to use"given" without the needarguments matched by fortype, view resolutionnot resolved

A Servlet-specific org.springframework.web.method.annotation.ModelAttributeMethodProcessor that applies data binding through a WebDataBinder of type ServletRequestDataBinder.

Also adds a fall-back strategy to instantiate the model attribute from a URI template variable or from a request parameter if the name matches the model attribute name and there is an appropriate type conversion strategy. @author Rossen Stoyanchev @since 3.1

@param annotationNotRequired if "true", non-simple method arguments and return values are considered model attributes with or without aa {@code @ModelAttribute} annotation.

Instantiate the model attribute from a URI template variable or from a request parameter if the name matches to the model attribute name and if there is an appropriate type conversion strategy. If none of these are true delegate back to the base class. @see #createAttributeFromUriValuecreateAttributeFromRequestValue(String, String, MethodParameter, WebDataBinderFactory, NativeWebRequest)

Create a model attribute from a String request value (e.g. URI template variable, request parameter) using type conversion.

The default implementation converts only if there a registeredregistered Converter that can perform the conversion. @param sourceValue the source value to create the model attribute from @param attributeName the name of the attribute, never {@code null} @param parameter the method parameter @param binderFactory for creating WebDataBinder instance @param request the current request @return the created model attribute, or {@code null} @throws Exception

Obtain a value from the request that may be used to instantiate the model attribute through type conversion from String to the target type.

The default implementation looks for the attribute name to match a URI variable first and then a request parameter. @param attributeName the model attribute name @param request the current request @return the request value to try to convert or {@code null}

Resolves request-related method argument values of the following types:

• WebRequest
• ServletRequest
• MultipartRequest
• HttpSession
• Principal
• Locale
• InputStream
• Reader

@author Arjen Poutsma @author Rossen Stoyanchev @since 3.1

Set ModelAndViewContainer.setRequestHandled(boolean) to to {@code false} to indicate that the method signature provides accessaccess to the response. If subsequently the underlying method returns returns {@code null}, the request is considered directly handled.

Resolvers argument values of type UriComponentsBuilder.

The returned instance is initialized via ServletUriComponentsBuilder.fromServletMapping(HttpServletRequest). @author Rossen Stoyanchev @since 3.1

Handles return values that are of type View.

A {@code null} return value is left as-is leaving it to the configured configured RequestToViewNameTranslator to select a view name by convention.

A View return type has a set purpose. Therefore this handler handler should be configured ahead of handlers that support any return value type type annotated with {@code @ModelAttribute} or {@code @ResponseBody} to ensure they don't take over. @author Rossen Stoyanchev @since 3.1

Handles return values of types {@code void} and {@code String} interpreting them as view name reference.

A {@code null} return value, either due to a {@code void} return type oror as the actual return value is left as-is allowing the configured configured RequestToViewNameTranslator to select a view name by convention.

A String return value can be interpreted in more than one ways dependingdepending on the presence of annotations like {@code @ModelAttribute} or or {@code @ResponseBody}. Therefore this handler should be configured after the handlers that support these annotations. @author Rossen Stoyanchev @since 3.1

Whether the given view name is a redirect view reference. @param viewName the view name to check, never {@code null} @return "true" if the given view name is recognized as a redirect view view reference; "false" otherwise.