root
/
spring-framework
mirror of https://github.com/spring-projects/spring-framework.git
1
0
Fork 0
Code Issues Actions 6 Packages Projects Releases Wiki Activity

Consistent table declarations (including fix for disarranged FTL macros) 

Issue: SPR-16612
This commit is contained in:
Juergen Hoeller 2018-03-19 12:41:22 +01:00
parent 702b27e1e4
commit 578c04ea17
4 changed files with 350 additions and 359 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

18
src/docs/asciidoc/integration.adoc
View File

@ -2738,7 +2738,7 @@ describes all available attributes:
.Attributes of the JMS <listener> element .Attributes of the JMS <listener> element
[cols="1,6"] [cols="1,6"]
|=== |===
| Attribute| Description | Attribute | Description
| id | id
| A bean name for the hosting listener container. If not specified, a bean name will be | A bean name for the hosting listener container. If not specified, a bean name will be
@ -2809,7 +2809,7 @@ choices and message redelivery scenarios.
.Attributes of the JMS <listener-container> element .Attributes of the JMS <listener-container> element
[cols="1,6"] [cols="1,6"]
|=== |===
| Attribute| Description | Attribute | Description
| container-type | container-type
| The type of this listener container. Available options are: `default`, `simple`, | The type of this listener container. Available options are: `default`, `simple`,
@ -2931,7 +2931,7 @@ table:
.Attributes of the JMS <jca-listener-container/> element .Attributes of the JMS <jca-listener-container/> element
[cols="1,6"] [cols="1,6"]
|=== |===
| Attribute| Description | Attribute | Description
| factory-id | factory-id
| Exposes the settings defined by this element as a `JmsListenerContainerFactory` | Exposes the settings defined by this element as a `JmsListenerContainerFactory`
@ -3262,7 +3262,7 @@ these registration behaviors are summarized on the following table:
.Registration Behaviors .Registration Behaviors
[cols="1,4"] [cols="1,4"]
|=== |===
| Registration behavior| Explanation | Registration behavior | Explanation
| `REGISTRATION_FAIL_ON_EXISTING` | `REGISTRATION_FAIL_ON_EXISTING`
| This is the default registration behavior. If an `MBean` instance has already been | This is the default registration behavior. If an `MBean` instance has already been
@ -3518,7 +3518,7 @@ metadata types:
.Source-level metadata parameters .Source-level metadata parameters
[cols="1,3,1"] [cols="1,3,1"]
|=== |===
| Parameter| Description| Applies to | Parameter | Description | Applies to
| `ObjectName` | `ObjectName`
| Used by `MetadataNamingStrategy` to determine the `ObjectName` of a managed resource | Used by `MetadataNamingStrategy` to determine the `ObjectName` of a managed resource
@ -4903,7 +4903,7 @@ corresponding methods called on the CCI `Interaction` interface:
.Usage of Interaction execute methods .Usage of Interaction execute methods
[cols="3,1,3"] [cols="3,1,3"]
|=== |===
| CciTemplate method signature| CciTemplate outputRecordCreator property| execute method called on the CCI Interaction | CciTemplate method signature | CciTemplate outputRecordCreator property | execute method called on the CCI Interaction
| Record execute(InteractionSpec, Record) | Record execute(InteractionSpec, Record)
| not set | not set
@ -5270,7 +5270,7 @@ The operation object approach uses records in the same manner as the `CciTemplat
.Usage of Interaction execute methods .Usage of Interaction execute methods
[cols="3,1,3"] [cols="3,1,3"]
|=== |===
| MappingRecordOperation method signature| MappingRecordOperation outputRecordCreator property| execute method called on the CCI Interaction | MappingRecordOperation method signature | MappingRecordOperation outputRecordCreator property | execute method called on the CCI Interaction
| Object execute(Object) | Object execute(Object)
| not set | not set
@ -7413,7 +7413,7 @@ javadoc for more details].
.Cache annotation settings .Cache annotation settings
[cols="1,1,1,3"] [cols="1,1,1,3"]
|=== |===
| XML Attribute| Annotation Attribute| Default| Description | XML Attribute | Annotation Attribute | Default | Description
| `cache-manager` | `cache-manager`
| N/A (See `CachingConfigurer` javadocs) | N/A (See `CachingConfigurer` javadocs)
@ -7597,7 +7597,7 @@ counterpart:
.Spring vs. JSR-107 caching annotations .Spring vs. JSR-107 caching annotations
[cols="1,1,3"] [cols="1,1,3"]
|=== |===
| Spring| JSR-107| Remark | Spring | JSR-107 | Remark
| `@Cacheable` | `@Cacheable`
| `@CacheResult` | `@CacheResult`

351
src/docs/asciidoc/web/webflux.adoc
View File

@ -258,27 +258,27 @@ the server APIs are used and where Reactive Streams support comes from:
[cols="1,2,2", options="header"] [cols="1,2,2", options="header"]
|=== |===
|Server name|Server API used|Reactive Streams support | Server name | Server API used | Reactive Streams support
|Netty | Netty
|Netty API | Netty API
|https://github.com/reactor/reactor-netty[Reactor Netty] | https://github.com/reactor/reactor-netty[Reactor Netty]
|Undertow | Undertow
|Undertow API | Undertow API
|spring-web: Undertow to Reactive Streams bridge | spring-web: Undertow to Reactive Streams bridge
|Tomcat | Tomcat
|Servlet 3.1 non-blocking I/O; Tomcat API to read and write ByteBuffers vs byte[] | Servlet 3.1 non-blocking I/O; Tomcat API to read and write ByteBuffers vs byte[]
|spring-web: Servlet 3.1 non-blocking I/O to Reactive Streams bridge | spring-web: Servlet 3.1 non-blocking I/O to Reactive Streams bridge
|Jetty | Jetty
|Servlet 3.1 non-blocking I/O; Jetty API to write ByteBuffers vs byte[] | Servlet 3.1 non-blocking I/O; Jetty API to write ByteBuffers vs byte[]
|spring-web: Servlet 3.1 non-blocking I/O to Reactive Streams bridge | spring-web: Servlet 3.1 non-blocking I/O to Reactive Streams bridge
|Servlet 3.1 container | Servlet 3.1 container
|Servlet 3.1 non-blocking I/O | Servlet 3.1 non-blocking I/O
|spring-web: Servlet 3.1 non-blocking I/O to Reactive Streams bridge | spring-web: Servlet 3.1 non-blocking I/O to Reactive Streams bridge
|=== |===
Here are required dependencies, Here are required dependencies,
@ -406,44 +406,40 @@ The table below lists the components that `WebHttpHandlerBuilder` detects:
[cols="2,2,1,3", options="header"] [cols="2,2,1,3", options="header"]
|=== |===
|Bean name|Bean type|Count|Description | Bean name | Bean type | Count | Description
|<any> | <any>
|`WebExceptionHandler` | `WebExceptionHandler`
|0..N | 0..N
|Exception handlers to apply after all ``WebFilter``'s and the target `WebHandler`. | Exception handlers to apply after all ``WebFilter``'s and the target `WebHandler`.
|<any> | <any>
|`WebFilter` | `WebFilter`
|0..N | 0..N
|Filters to invoke before and after the target `WebHandler`. | Filters to invoke before and after the target `WebHandler`.
|"webHandler" | "webHandler"
|`WebHandler` | `WebHandler`
|1 | 1
|The handler for the request. | The handler for the request.
|"webSessionManager" | "webSessionManager"
|`WebSessionManager` | `WebSessionManager`
|0..1 | 0..1
|The manager for ``WebSession``'s exposed through a method on `ServerWebExchange`. | The manager for ``WebSession``'s exposed through a method on `ServerWebExchange`.
`DefaultWebSessionManager` by default.
`DefaultWebSessionManager` by default. | "serverCodecConfigurer"
| `ServerCodecConfigurer`
| 0..1
| For access to ``HttpMessageReader``'s for parsing form data and multipart data that's then
exposed through methods on `ServerWebExchange`. `ServerCodecConfigurer.create()` by default.
|"serverCodecConfigurer" | "localeContextResolver"
|`ServerCodecConfigurer` | `LocaleContextResolver`
|0..1 | 0..1
|For access to ``HttpMessageReader``'s for parsing form data and multipart data that's | The resolver for `LocaleContext` exposed through a method on `ServerWebExchange`.
then exposed through methods on `ServerWebExchange`. `AcceptHeaderLocaleContextResolver` by default.
`ServerCodecConfigurer.create()` by default.
|"localeContextResolver"
|`LocaleContextResolver`
|0..1
|The resolver for `LocaleContext` exposed through a method on `ServerWebExchange`.
`AcceptHeaderLocaleContextResolver` by default.
|=== |===
@ -622,7 +618,7 @@ there are also some other beans detected at a lower level, see
[[webflux-special-beans-table]] [[webflux-special-beans-table]]
[cols="1,2", options="header"] [cols="1,2", options="header"]
|=== |===
| Bean type| Explanation | Bean type | Explanation
| HandlerMapping | HandlerMapping
| Map a request to a handler. The mapping is based on some criteria the details of | Map a request to a handler. The mapping is based on some criteria the details of
@ -642,7 +638,7 @@ there are also some other beans detected at a lower level, see
| HandlerResultHandler | HandlerResultHandler
| Process the result from the handler invocation and finalize the response. | Process the result from the handler invocation and finalize the response.
See <<webflux-resulthandling>>. See <<webflux-resulthandling>>.
|=== |===
@ -1139,111 +1135,109 @@ etc, and is equivalent to `required=false`.
[cols="1,2", options="header"] [cols="1,2", options="header"]
|=== |===
|Controller method argument|Description | Controller method argument | Description
|`ServerWebExchange` | `ServerWebExchange`
|Access to the full `ServerWebExchange` -- container for the HTTP request and response, | Access to the full `ServerWebExchange` -- container for the HTTP request and response,
request and session attributes, `checkNotModified` methods, and others. request and session attributes, `checkNotModified` methods, and others.
|`ServerHttpRequest`, `ServerHttpResponse` | `ServerHttpRequest`, `ServerHttpResponse`
|Access to the HTTP request or response. | Access to the HTTP request or response.
|`WebSession` | `WebSession`
|Access to the session; this does not force the start of a new session unless attributes | Access to the session; this does not force the start of a new session unless attributes
are added. Supports reactive types. are added. Supports reactive types.
|`java.security.Principal` | `java.security.Principal`
|Currently authenticated user; possibly a specific `Principal` implementation class if known. | Currently authenticated user; possibly a specific `Principal` implementation class if known.
Supports reactive types. Supports reactive types.
|`org.springframework.http.HttpMethod` | `org.springframework.http.HttpMethod`
|The HTTP method of the request. | The HTTP method of the request.
|`java.util.Locale` | `java.util.Locale`
|The current request locale, determined by the most specific `LocaleResolver` available, in | The current request locale, determined by the most specific `LocaleResolver` available, in
effect, the configured `LocaleResolver`/`LocaleContextResolver`. effect, the configured `LocaleResolver`/`LocaleContextResolver`.
|Java 6+: `java.util.TimeZone` + | `java.util.TimeZone` + `java.time.ZoneId`
Java 8+: `java.time.ZoneId` | The time zone associated with the current request, as determined by a `LocaleContextResolver`.
|The time zone associated with the current request, as determined by a `LocaleContextResolver`.
|`@PathVariable` | `@PathVariable`
|For access to URI template variables. | For access to URI template variables. See <<webflux-ann-requestmapping-uri-templates>>.
See <<webflux-ann-requestmapping-uri-templates>>.
|`@MatrixVariable` | `@MatrixVariable`
|For access to name-value pairs in URI path segments. See <<webflux-ann-matrix-variables>>. | For access to name-value pairs in URI path segments. See <<webflux-ann-matrix-variables>>.
|`@RequestParam` | `@RequestParam`
|For access to Servlet request parameters. Parameter values are converted to the declared | For access to Servlet request parameters. Parameter values are converted to the declared
method argument type. See <<webflux-ann-requestparam>>. method argument type. See <<webflux-ann-requestparam>>.
Note that use of `@RequestParam` is optional, e.g. to set its attributes. Note that use of `@RequestParam` is optional, e.g. to set its attributes.
See "Any other argument" further below in this table. See "Any other argument" further below in this table.
|`@RequestHeader` | `@RequestHeader`
|For access to request headers. Header values are converted to the declared method argument | For access to request headers. Header values are converted to the declared method argument
type. See <<webflux-ann-requestheader>>. type. See <<webflux-ann-requestheader>>.
|`@CookieValue` | `@CookieValue`
|For access to cookies. Cookies values are converted to the declared method argument | For access to cookies. Cookies values are converted to the declared method argument type.
type. See <<webflux-ann-cookievalue>>. See <<webflux-ann-cookievalue>>.
|`@RequestBody` | `@RequestBody`
|For access to the HTTP request body. Body content is converted to the declared method | For access to the HTTP request body. Body content is converted to the declared method
argument type using ``HttpMessageReader``'s. Supports reactive types. argument type using ``HttpMessageReader``'s. Supports reactive types.
<<webflux-ann-requestbody>>. See <<webflux-ann-requestbody>>.
|`HttpEntity<B>` | `HttpEntity<B>`
|For access to request headers and body. The body is converted with ``HttpMessageReader``'s. | For access to request headers and body. The body is converted with ``HttpMessageReader``'s.
Supports reactive types. See <<webflux-ann-httpentity>>. Supports reactive types. See <<webflux-ann-httpentity>>.
|`@RequestPart` | `@RequestPart`
|For access to a part in a "multipart/form-data" request. Supports reactive types. | For access to a part in a "multipart/form-data" request. Supports reactive types.
See <<webflux-multipart-forms>> and <<webflux-multipart>>. See <<webflux-multipart-forms>> and <<webflux-multipart>>.
|`java.util.Map`, `org.springframework.ui.Model`, `org.springframework.ui.ModelMap` | `java.util.Map`, `org.springframework.ui.Model`, `org.springframework.ui.ModelMap`
|For access to the model that is used in HTML controllers and exposed to templates as | For access to the model that is used in HTML controllers and exposed to templates as
part of view rendering. part of view rendering.
|`@ModelAttribute` | `@ModelAttribute`
|For access to an existing attribute in the model (instantiated if not present) with | For access to an existing attribute in the model (instantiated if not present) with
data binding and validation applied. See <<webflux-ann-modelattrib-method-args>> as well data binding and validation applied. See <<webflux-ann-modelattrib-method-args>> as well
as <<webflux-ann-modelattrib-methods>> and <<webflux-ann-initbinder>>. as <<webflux-ann-modelattrib-methods>> and <<webflux-ann-initbinder>>.
Note that use of `@ModelAttribute` is optional, e.g. to set its attributes. Note that use of `@ModelAttribute` is optional, e.g. to set its attributes.
See "Any other argument" further below in this table. See "Any other argument" further below in this table.
|`Errors`, `BindingResult` | `Errors`, `BindingResult`
|For access to errors from validation and data binding for a command object | For access to errors from validation and data binding for a command object
(i.e. `@ModelAttribute` argument), or errors from the validation of an `@RequestBody` or (i.e. `@ModelAttribute` argument), or errors from the validation of an `@RequestBody` or
`@RequestPart` arguments; an `Errors`, or `BindingResult` argument must be declared `@RequestPart` arguments; an `Errors`, or `BindingResult` argument must be declared
immediately after the validated method argument. immediately after the validated method argument.
|`SessionStatus` + class-level `@SessionAttributes` | `SessionStatus` + class-level `@SessionAttributes`
|For marking form processing complete which triggers cleanup of session attributes | For marking form processing complete which triggers cleanup of session attributes
declared through a class-level `@SessionAttributes` annotation. See declared through a class-level `@SessionAttributes` annotation.
<<webflux-ann-sessionattributes>> for more details. See <<webflux-ann-sessionattributes>> for more details.
|`UriComponentsBuilder` | `UriComponentsBuilder`
|For preparing a URL relative to the current request's host, port, scheme, context path, and | For preparing a URL relative to the current request's host, port, scheme, context path, and
the literal part of the servlet mapping also taking into account `Forwarded` and the literal part of the servlet mapping also taking into account `Forwarded` and
`X-Forwarded-*` headers. `X-Forwarded-*` headers.
// See <<webflux-uri-building>>. // TODO: See <<webflux-uri-building>>.
|`@SessionAttribute` | `@SessionAttribute`
|For access to any session attribute; in contrast to model attributes stored in the session | For access to any session attribute; in contrast to model attributes stored in the session
as a result of a class-level `@SessionAttributes` declaration. See as a result of a class-level `@SessionAttributes` declaration. See
<<webflux-ann-sessionattribute>> for more details. <<webflux-ann-sessionattribute>> for more details.
|`@RequestAttribute` | `@RequestAttribute`
|For access to request attributes. See <<webflux-ann-requestattrib>> for more details. | For access to request attributes. See <<webflux-ann-requestattrib>> for more details.
|Any other argument | Any other argument
|If a method argument is not matched to any of the above, by default it is resolved as | If a method argument is not matched to any of the above, by default it is resolved as
an `@RequestParam` if it is a simple type, as determined by an `@RequestParam` if it is a simple type, as determined by
{api-spring-framework}/beans/BeanUtils.html#isSimpleProperty-java.lang.Class-[BeanUtils#isSimpleProperty], {api-spring-framework}/beans/BeanUtils.html#isSimpleProperty-java.lang.Class-[BeanUtils#isSimpleProperty],
or as an `@ModelAttribute` otherwise. or as an `@ModelAttribute` otherwise.
|=== |===
@ -1257,66 +1251,66 @@ generally supported for all return values.
[cols="1,2", options="header"] [cols="1,2", options="header"]
|=== |===
|Controller method return value|Description | Controller method return value | Description
|`@ResponseBody` | `@ResponseBody`
|The return value is encoded through ``HttpMessageWriter``'s and written to the response. | The return value is encoded through ``HttpMessageWriter``'s and written to the response.
See <<webflux-ann-responsebody>>. See <<webflux-ann-responsebody>>.
|`HttpEntity<B>`, `ResponseEntity<B>` | `HttpEntity<B>`, `ResponseEntity<B>`
|The return value specifies the full response including HTTP headers and body be encoded | The return value specifies the full response including HTTP headers and body be encoded
through ``HttpMessageWriter``'s and written to the response. through ``HttpMessageWriter``'s and written to the response.
See <<webflux-ann-responseentity>>. See <<webflux-ann-responseentity>>.
|`HttpHeaders` | `HttpHeaders`
|For returning a response with headers and no body. | For returning a response with headers and no body.
|`String` | `String`
|A view name to be resolved with ``ViewResolver``'s and used together with the implicit | A view name to be resolved with ``ViewResolver``'s and used together with the implicit
model -- determined through command objects and `@ModelAttribute` methods. The handler model -- determined through command objects and `@ModelAttribute` methods. The handler
method may also programmatically enrich the model by declaring a `Model` argument (see method may also programmatically enrich the model by declaring a `Model` argument
above). (see above).
|`View` | `View`
|A `View` instance to use for rendering together with the implicit model -- determined | A `View` instance to use for rendering together with the implicit model -- determined
through command objects and `@ModelAttribute` methods. The handler method may also through command objects and `@ModelAttribute` methods. The handler method may also
programmatically enrich the model by declaring a `Model` argument (see above). programmatically enrich the model by declaring a `Model` argument (see above).
|`java.util.Map`, `org.springframework.ui.Model` | `java.util.Map`, `org.springframework.ui.Model`
|Attributes to be added to the implicit model with the view name implicitly determined | Attributes to be added to the implicit model with the view name implicitly determined
based on the request path. based on the request path.
|`@ModelAttribute` | `@ModelAttribute`
|An attribute to be added to the model with the view name implicitly determined based | An attribute to be added to the model with the view name implicitly determined based
on the request path. on the request path.
Note that `@ModelAttribute` is optional. See "Any other return value" further below in Note that `@ModelAttribute` is optional. See "Any other return value" further below in
this table. this table.
|`Rendering` | `Rendering`
|An API for model and view rendering scenarios. | An API for model and view rendering scenarios.
|`void` | `void`
|A method with a `void`, possibly async (e.g. `Mono<Void>`), return type (or a `null` return | A method with a `void`, possibly async (e.g. `Mono<Void>`), return type (or a `null` return
value) is considered to have fully handled the response if it also has a `ServerHttpResponse`, value) is considered to have fully handled the response if it also has a `ServerHttpResponse`,
or a `ServerWebExchange` argument, or an `@ResponseStatus` annotation. The same is true also or a `ServerWebExchange` argument, or an `@ResponseStatus` annotation. The same is true also
if the controller has made a positive ETag or lastModified timestamp check. if the controller has made a positive ETag or lastModified timestamp check.
// TODO (see <<webflux-caching-etag-lastmodified>> for details) // TODO: See <<webflux-caching-etag-lastmodified>> for details.
If none of the above is true, a `void` return type may also indicate "no response body" for If none of the above is true, a `void` return type may also indicate "no response body" for
REST controllers, or default view name selection for HTML controllers. REST controllers, or default view name selection for HTML controllers.
|`Flux<ServerSentEvent>`, `Observable<ServerSentEvent>`, or other reactive type | `Flux<ServerSentEvent>`, `Observable<ServerSentEvent>`, or other reactive type
|Emit server-sent events; the `SeverSentEvent` wrapper can be omitted when only data needs | Emit server-sent events; the `SeverSentEvent` wrapper can be omitted when only data needs
to be written (however `text/event-stream` must be requested or declared in the mapping to be written (however `text/event-stream` must be requested or declared in the mapping
through the produces attribute). through the produces attribute).
|Any other return value | Any other return value
|If a return value is not matched to any of the above, by default it is treated as a view | If a return value is not matched to any of the above, by default it is treated as a view
name, if it is `String` or `void` (default view name selection applies); or as a model name, if it is `String` or `void` (default view name selection applies); or as a model
attribute to be added to the model, unless it is a simple type, as determined by attribute to be added to the model, unless it is a simple type, as determined by
{api-spring-framework}/beans/BeanUtils.html#isSimpleProperty-java.lang.Class-[BeanUtils#isSimpleProperty] {api-spring-framework}/beans/BeanUtils.html#isSimpleProperty-java.lang.Class-[BeanUtils#isSimpleProperty]
in which case it remains unresolved. in which case it remains unresolved.
|=== |===
@ -2590,8 +2584,7 @@ evaluated and if present a `304` status code is returned.
} }
---- ----
// TODO: // TODO: See also <<webflux-caching-static-resources, HTTP caching support for static resources>>.
// See also <<webflux-caching-static-resources, HTTP caching support for static resources>>.
The resource handler also supports a chain of The resource handler also supports a chain of
{api-spring-framework}/web/reactive/resource/ResourceResolver.html[ResourceResolver]'s and {api-spring-framework}/web/reactive/resource/ResourceResolver.html[ResourceResolver]'s and

4
src/docs/asciidoc/web/webmvc-view.adoc
View File

@ -214,9 +214,9 @@ parameter list that each takes.
[[views-macros-defs-tbl]] [[views-macros-defs-tbl]]
.Table of macro definitions .Table of macro definitions
[cols="3,1,1"] [cols="3,1"]
|=== |===
| macro| FTL definition | macro | FTL definition
| **message** (output a string from a resource bundle based on the code parameter) | **message** (output a string from a resource bundle based on the code parameter)
| <@spring.message code/> | <@spring.message code/>

336
src/docs/asciidoc/web/webmvc.adoc
View File

@ -520,24 +520,23 @@ The table below lists the available `HandlerExceptionResolver` implementations:
[cols="1,2", options="header"] [cols="1,2", options="header"]
.HandlerExceptionResolver implementations .HandlerExceptionResolver implementations
|=== |===
| HandlerExceptionResolver| Description | HandlerExceptionResolver | Description
| `SimpleMappingExceptionResolver` | `SimpleMappingExceptionResolver`
| A mapping between exception class names and error view names. Useful for rendering | A mapping between exception class names and error view names. Useful for rendering
error pages in a browser application. error pages in a browser application.
| {api-spring-framework}/web/servlet/mvc/support/DefaultHandlerExceptionResolver.html[DefaultHandlerExceptionResolver] | {api-spring-framework}/web/servlet/mvc/support/DefaultHandlerExceptionResolver.html[DefaultHandlerExceptionResolver]
| Resolves exceptions raised by Spring MVC and maps them to HTTP status codes. | Resolves exceptions raised by Spring MVC and maps them to HTTP status codes.
Also see alternative `ResponseEntityExceptionHandler` and <<mvc-ann-rest-exceptions>>.
Also see alternative `ResponseEntityExceptionHandler` and <<mvc-ann-rest-exceptions>>.
| `ResponseStatusExceptionResolver` | `ResponseStatusExceptionResolver`
| Resolves exceptions with the `@ResponseStatus` annotation and maps them to HTTP status | Resolves exceptions with the `@ResponseStatus` annotation and maps them to HTTP status
codes based on the value in the annotation. codes based on the value in the annotation.
| `ExceptionHandlerExceptionResolver` | `ExceptionHandlerExceptionResolver`
| Resolves exceptions by invoking an `@ExceptionHandler` method in an `@Controller` or an | Resolves exceptions by invoking an `@ExceptionHandler` method in an `@Controller` or an
`@ControllerAdvice` class. See <<mvc-ann-exceptionhandler>>. `@ControllerAdvice` class. See <<mvc-ann-exceptionhandler>>.
|=== |===
@ -811,7 +810,7 @@ maximum age. Find below an example of defining a `CookieLocaleResolver`.
.CookieLocaleResolver properties .CookieLocaleResolver properties
[cols="1,1,4"] [cols="1,1,4"]
|=== |===
| Property| Default| Description | Property | Default | Description
| cookieName | cookieName
| classname + LOCALE | classname + LOCALE
@ -954,7 +953,7 @@ alter the request's theme. The following theme resolvers are provided by Spring:
.ThemeResolver implementations .ThemeResolver implementations
[cols="1,4"] [cols="1,4"]
|=== |===
| Class| Description | Class | Description
| `FixedThemeResolver` | `FixedThemeResolver`
| Selects a fixed theme, set using the `defaultThemeName` property. | Selects a fixed theme, set using the `defaultThemeName` property.
@ -1550,126 +1549,125 @@ etc, and is equivalent to `required=false`.
[cols="1,2", options="header"] [cols="1,2", options="header"]
|=== |===
|Controller method argument|Description | Controller method argument | Description
|`WebRequest`, `NativeWebRequest` | `WebRequest`, `NativeWebRequest`
|Generic access to request parameters, request & session attributes, without direct | Generic access to request parameters, request & session attributes, without direct
use of the Servlet API. use of the Servlet API.
|`javax.servlet.ServletRequest`, `javax.servlet.ServletResponse` | `javax.servlet.ServletRequest`, `javax.servlet.ServletResponse`
|Choose any specific request or response type -- e.g. `ServletRequest`, `HttpServletRequest`, | Choose any specific request or response type -- e.g. `ServletRequest`, `HttpServletRequest`,
or Spring's `MultipartRequest`, `MultipartHttpServletRequest`. or Spring's `MultipartRequest`, `MultipartHttpServletRequest`.
|`javax.servlet.http.HttpSession` | `javax.servlet.http.HttpSession`
|Enforces the presence of a session. As a consequence, such an argument is never `null`. + | Enforces the presence of a session. As a consequence, such an argument is never `null`. +
**Note:** Session access is not thread-safe. Consider setting the **Note:** Session access is not thread-safe. Consider setting the
``RequestMappingHandlerAdapter``'s "synchronizeOnSession" flag to "true" if multiple ``RequestMappingHandlerAdapter``'s "synchronizeOnSession" flag to "true" if multiple
requests are allowed to access a session concurrently. requests are allowed to access a session concurrently.
|`javax.servlet.http.PushBuilder` | `javax.servlet.http.PushBuilder`
|Servlet 4.0 push builder API for programmatic HTTP/2 resource pushes. | Servlet 4.0 push builder API for programmatic HTTP/2 resource pushes.
Note that per Servlet spec, the injected `PushBuilder` instance can be null if the client Note that per Servlet spec, the injected `PushBuilder` instance can be null if the client
does not support that HTTP/2 feature. does not support that HTTP/2 feature.
|`java.security.Principal` | `java.security.Principal`
|Currently authenticated user; possibly a specific `Principal` implementation class if known. | Currently authenticated user; possibly a specific `Principal` implementation class if known.
|`HttpMethod` | `HttpMethod`
|The HTTP method of the request. | The HTTP method of the request.
|`java.util.Locale` | `java.util.Locale`
|The current request locale, determined by the most specific `LocaleResolver` available, in | The current request locale, determined by the most specific `LocaleResolver` available, in
effect, the configured `LocaleResolver`/`LocaleContextResolver`. effect, the configured `LocaleResolver`/`LocaleContextResolver`.
|Java 6+: `java.util.TimeZone` + | `java.util.TimeZone` + `java.time.ZoneId`
Java 8+: `java.time.ZoneId` | The time zone associated with the current request, as determined by a `LocaleContextResolver`.
|The time zone associated with the current request, as determined by a `LocaleContextResolver`.
|`java.io.InputStream`, `java.io.Reader` | `java.io.InputStream`, `java.io.Reader`
|For access to the raw request body as exposed by the Servlet API. | For access to the raw request body as exposed by the Servlet API.
|`java.io.OutputStream`, `java.io.Writer` | `java.io.OutputStream`, `java.io.Writer`
|For access to the raw response body as exposed by the Servlet API. | For access to the raw response body as exposed by the Servlet API.
|`@PathVariable` | `@PathVariable`
|For access to URI template variables. See <<mvc-ann-requestmapping-uri-templates>>. | For access to URI template variables. See <<mvc-ann-requestmapping-uri-templates>>.
|`@MatrixVariable` | `@MatrixVariable`
|For access to name-value pairs in URI path segments. See <<mvc-ann-matrix-variables>>. | For access to name-value pairs in URI path segments. See <<mvc-ann-matrix-variables>>.
|`@RequestParam` | `@RequestParam`
|For access to Servlet request parameters. Parameter values are converted to the declared | For access to Servlet request parameters. Parameter values are converted to the declared
method argument type. See <<mvc-ann-requestparam>>. method argument type. See <<mvc-ann-requestparam>>.
Note that use of `@RequestParam` is optional, e.g. to set its attributes. Note that use of `@RequestParam` is optional, e.g. to set its attributes.
See "Any other argument" further below in this table. See "Any other argument" further below in this table.
|`@RequestHeader` | `@RequestHeader`
|For access to request headers. Header values are converted to the declared method argument | For access to request headers. Header values are converted to the declared method argument
type. See <<mvc-ann-requestheader>>. type. See <<mvc-ann-requestheader>>.
|`@CookieValue` | `@CookieValue`
|For access to cookies. Cookies values are converted to the declared method argument | For access to cookies. Cookies values are converted to the declared method argument
type. See <<mvc-ann-cookievalue>>. type. See <<mvc-ann-cookievalue>>.
|`@RequestBody` | `@RequestBody`
|For access to the HTTP request body. Body content is converted to the declared method | For access to the HTTP request body. Body content is converted to the declared method
argument type using ``HttpMessageConverter``s. See <<mvc-ann-requestbody>>. argument type using ``HttpMessageConverter``s. See <<mvc-ann-requestbody>>.
|`HttpEntity<B>` | `HttpEntity<B>`
|For access to request headers and body. The body is converted with ``HttpMessageConverter``s. | For access to request headers and body. The body is converted with ``HttpMessageConverter``s.
See <<mvc-ann-httpentity>>. See <<mvc-ann-httpentity>>.
|`@RequestPart` | `@RequestPart`
|For access to a part in a "multipart/form-data" request. | For access to a part in a "multipart/form-data" request.
See <<mvc-multipart-forms>>. See <<mvc-multipart-forms>>.
|`java.util.Map`, `org.springframework.ui.Model`, `org.springframework.ui.ModelMap` | `java.util.Map`, `org.springframework.ui.Model`, `org.springframework.ui.ModelMap`
|For access to the model that is used in HTML controllers and exposed to templates as | For access to the model that is used in HTML controllers and exposed to templates as
part of view rendering. part of view rendering.
|`RedirectAttributes` | `RedirectAttributes`
|Specify attributes to use in case of a redirect -- i.e. to be appended to the query | Specify attributes to use in case of a redirect -- i.e. to be appended to the query
string, and/or flash attributes to be stored temporarily until the request after redirect. string, and/or flash attributes to be stored temporarily until the request after redirect.
See <<mvc-redirecting-passing-data>> and <<mvc-flash-attributes>>. See <<mvc-redirecting-passing-data>> and <<mvc-flash-attributes>>.
|`@ModelAttribute` | `@ModelAttribute`
|For access to an existing attribute in the model (instantiated if not present) with | For access to an existing attribute in the model (instantiated if not present) with
data binding and validation applied. See <<mvc-ann-modelattrib-method-args>> as well as data binding and validation applied. See <<mvc-ann-modelattrib-method-args>> as well as
<<mvc-ann-modelattrib-methods>> and <<mvc-ann-initbinder>>. <<mvc-ann-modelattrib-methods>> and <<mvc-ann-initbinder>>.
Note that use of `@ModelAttribute` is optional, e.g. to set its attributes. Note that use of `@ModelAttribute` is optional, e.g. to set its attributes.
See "Any other argument" further below in this table. See "Any other argument" further below in this table.
|`Errors`, `BindingResult` | `Errors`, `BindingResult`
|For access to errors from validation and data binding for a command object | For access to errors from validation and data binding for a command object
(i.e. `@ModelAttribute` argument), or errors from the validation of an `@RequestBody` or (i.e. `@ModelAttribute` argument), or errors from the validation of an `@RequestBody` or
`@RequestPart` arguments; an `Errors`, or `BindingResult` argument must be declared `@RequestPart` arguments; an `Errors`, or `BindingResult` argument must be declared
immediately after the validated method argument. immediately after the validated method argument.
|`SessionStatus` + class-level `@SessionAttributes` | `SessionStatus` + class-level `@SessionAttributes`
|For marking form processing complete which triggers cleanup of session attributes | For marking form processing complete which triggers cleanup of session attributes
declared through a class-level `@SessionAttributes` annotation. See declared through a class-level `@SessionAttributes` annotation. See
<<mvc-ann-sessionattributes>> for more details. <<mvc-ann-sessionattributes>> for more details.
|`UriComponentsBuilder` | `UriComponentsBuilder`
|For preparing a URL relative to the current request's host, port, scheme, context path, and | For preparing a URL relative to the current request's host, port, scheme, context path, and
the literal part of the servlet mapping also taking into account `Forwarded` and the literal part of the servlet mapping also taking into account `Forwarded` and
`X-Forwarded-*` headers. See <<mvc-uri-building>>. `X-Forwarded-*` headers. See <<mvc-uri-building>>.
|`@SessionAttribute` | `@SessionAttribute`
|For access to any session attribute; in contrast to model attributes stored in the session | For access to any session attribute; in contrast to model attributes stored in the session
as a result of a class-level `@SessionAttributes` declaration. See as a result of a class-level `@SessionAttributes` declaration. See
<<mvc-ann-sessionattribute>> for more details. <<mvc-ann-sessionattribute>> for more details.
|`@RequestAttribute` | `@RequestAttribute`
|For access to request attributes. See <<mvc-ann-requestattrib>> for more details. | For access to request attributes. See <<mvc-ann-requestattrib>> for more details.
|Any other argument | Any other argument
|If a method argument is not matched to any of the above, by default it is resolved as | If a method argument is not matched to any of the above, by default it is resolved as
an `@RequestParam` if it is a simple type, as determined by an `@RequestParam` if it is a simple type, as determined by
{api-spring-framework}/beans/BeanUtils.html#isSimpleProperty-java.lang.Class-[BeanUtils#isSimpleProperty], {api-spring-framework}/beans/BeanUtils.html#isSimpleProperty-java.lang.Class-[BeanUtils#isSimpleProperty],
or as an `@ModelAttribute` otherwise. or as an `@ModelAttribute` otherwise.
|=== |===
@ -1682,96 +1680,96 @@ supported for all return values, see below for more details.
[cols="1,2", options="header"] [cols="1,2", options="header"]
|=== |===
|Controller method return value|Description | Controller method return value | Description
|`@ResponseBody` | `@ResponseBody`
|The return value is converted through ``HttpMessageConverter``s and written to the | The return value is converted through ``HttpMessageConverter``s and written to the
response. See <<mvc-ann-responsebody>>. response. See <<mvc-ann-responsebody>>.
|`HttpEntity<B>`, `ResponseEntity<B>` | `HttpEntity<B>`, `ResponseEntity<B>`
|The return value specifies the full response including HTTP headers and body be converted | The return value specifies the full response including HTTP headers and body be converted
through ``HttpMessageConverter``s and written to the response. through ``HttpMessageConverter``s and written to the response.
See <<mvc-ann-responseentity>>. See <<mvc-ann-responseentity>>.
|`HttpHeaders` | `HttpHeaders`
|For returning a response with headers and no body. | For returning a response with headers and no body.
|`String` | `String`
|A view name to be resolved with ``ViewResolver``'s and used together with the implicit | A view name to be resolved with ``ViewResolver``'s and used together with the implicit
model -- determined through command objects and `@ModelAttribute` methods. The handler model -- determined through command objects and `@ModelAttribute` methods. The handler
method may also programmatically enrich the model by declaring a `Model` argument (see method may also programmatically enrich the model by declaring a `Model` argument
above). (see above).
|`View` | `View`
|A `View` instance to use for rendering together with the implicit model -- determined | A `View` instance to use for rendering together with the implicit model -- determined
through command objects and `@ModelAttribute` methods. The handler method may also through command objects and `@ModelAttribute` methods. The handler method may also
programmatically enrich the model by declaring a `Model` argument (see above). programmatically enrich the model by declaring a `Model` argument (see above).
|`java.util.Map`, `org.springframework.ui.Model` | `java.util.Map`, `org.springframework.ui.Model`
|Attributes to be added to the implicit model with the view name implicitly determined | Attributes to be added to the implicit model with the view name implicitly determined
through a `RequestToViewNameTranslator`. through a `RequestToViewNameTranslator`.
|`@ModelAttribute` | `@ModelAttribute`
|An attribute to be added to the model with the view name implicitly determined through | An attribute to be added to the model with the view name implicitly determined through
a `RequestToViewNameTranslator`. a `RequestToViewNameTranslator`.
Note that `@ModelAttribute` is optional. See "Any other return value" further below in Note that `@ModelAttribute` is optional. See "Any other return value" further below in
this table. this table.
|`ModelAndView` object | `ModelAndView` object
|The view and model attributes to use, and optionally a response status. | The view and model attributes to use, and optionally a response status.
|`void` | `void`
|A method with a `void` return type (or `null` return value) is considered to have fully | A method with a `void` return type (or `null` return value) is considered to have fully
handled the response if it also has a `ServletResponse`, or an `OutputStream` argument, or an handled the response if it also has a `ServletResponse`, or an `OutputStream` argument, or
`@ResponseStatus` annotation. The same is true also if the controller has made a positive an `@ResponseStatus` annotation. The same is true also if the controller has made a positive
ETag or lastModified timestamp check (see <<mvc-caching-etag-lastmodified>> for details). ETag or lastModified timestamp check (see <<mvc-caching-etag-lastmodified>> for details).
If none of the above is true, a `void` return type may also indicate "no response body" for If none of the above is true, a `void` return type may also indicate "no response body" for
REST controllers, or default view name selection for HTML controllers. REST controllers, or default view name selection for HTML controllers.
|`DeferredResult<V>` | `DeferredResult<V>`
|Produce any of the above return values asynchronously from any thread -- e.g. possibly as a | Produce any of the above return values asynchronously from any thread -- e.g. possibly as a
result of some event or callback. See <<mvc-ann-async>> and result of some event or callback. See <<mvc-ann-async>> and
<<mvc-ann-async-deferredresult>>. <<mvc-ann-async-deferredresult>>.
|`Callable<V>` | `Callable<V>`
|Produce any of the above return values asynchronously in a Spring MVC managed thread. | Produce any of the above return values asynchronously in a Spring MVC managed thread.
See <<mvc-ann-async>> and <<mvc-ann-async-callable>>. See <<mvc-ann-async>> and <<mvc-ann-async-callable>>.
|`ListenableFuture<V>`, | `ListenableFuture<V>`,
`java.util.concurrent.CompletionStage<V>`, `java.util.concurrent.CompletionStage<V>`,
`java.util.concurrent.CompletableFuture<V>` `java.util.concurrent.CompletableFuture<V>`
|Alternative to `DeferredResult` as a convenience for example when an underlying service | Alternative to `DeferredResult` as a convenience for example when an underlying service
returns one of those. returns one of those.
|`ResponseBodyEmitter`, `SseEmitter` | `ResponseBodyEmitter`, `SseEmitter`
|Emit a stream of objects asynchronously to be written to the response with | Emit a stream of objects asynchronously to be written to the response with
``HttpMessageConverter``'s; also supported as the body of a `ResponseEntity`. ``HttpMessageConverter``'s; also supported as the body of a `ResponseEntity`.
See <<mvc-ann-async>> and <<mvc-ann-async-http-streaming>>. See <<mvc-ann-async>> and <<mvc-ann-async-http-streaming>>.
|`StreamingResponseBody` | `StreamingResponseBody`
|Write to the response `OutputStream` asynchronously; also supported as the body of a | Write to the response `OutputStream` asynchronously; also supported as the body of a
`ResponseEntity`. See <<mvc-ann-async>> and <<mvc-ann-async-http-streaming>>. `ResponseEntity`. See <<mvc-ann-async>> and <<mvc-ann-async-http-streaming>>.
|Reactive types -- Reactor, RxJava, or others via `ReactiveAdapterRegistry` | Reactive types -- Reactor, RxJava, or others via `ReactiveAdapterRegistry`
|Alternative to ``DeferredResult` with multi-value streams (e.g. `Flux`, `Observable`) | Alternative to ``DeferredResult` with multi-value streams (e.g. `Flux`, `Observable`)
collected to a `List`. collected to a `List`.
For streaming scenarios -- .e.g. `text/event-stream`, `application/json+stream`, For streaming scenarios -- e.g. `text/event-stream`, `application/json+stream` --
`SseEmitter` and `ResponseBodyEmitter` are used instead, where `ServletOutputStream` blocking `SseEmitter` and `ResponseBodyEmitter` are used instead, where `ServletOutputStream`
I/O is performed on a Spring MVC managed thread and back pressure applied against the blocking I/O is performed on a Spring MVC managed thread and back pressure applied
completion of each write. against the completion of each write.
See <<mvc-ann-async>> and <<mvc-ann-async-reactive-types>>. See <<mvc-ann-async>> and <<mvc-ann-async-reactive-types>>.
|Any other return value | Any other return value
|If a return value is not matched to any of the above, by default it is treated as a view | If a return value is not matched to any of the above, by default it is treated as a view
name, if it is `String` or `void` (default view name selection via name, if it is `String` or `void` (default view name selection via
`RequestToViewNameTranslator` applies); or as a model attribute to be added to the model, `RequestToViewNameTranslator` applies); or as a model attribute to be added to the model,
unless it is a simple type, as determined by unless it is a simple type, as determined by
{api-spring-framework}/beans/BeanUtils.html#isSimpleProperty-java.lang.Class-[BeanUtils#isSimpleProperty] {api-spring-framework}/beans/BeanUtils.html#isSimpleProperty-java.lang.Class-[BeanUtils#isSimpleProperty]
in which case it remains unresolved. in which case it remains unresolved.
|=== |===