From 578c04ea17cb3ddd645725284b3392f37ce4661e Mon Sep 17 00:00:00 2001 From: Juergen Hoeller Date: Mon, 19 Mar 2018 12:41:22 +0100 Subject: [PATCH] Consistent table declarations (including fix for disarranged FTL macros) Issue: SPR-16612 --- src/docs/asciidoc/integration.adoc | 18 +- src/docs/asciidoc/web/webflux.adoc | 401 ++++++++++++------------- src/docs/asciidoc/web/webmvc-view.adoc | 4 +- src/docs/asciidoc/web/webmvc.adoc | 388 ++++++++++++------------ 4 files changed, 401 insertions(+), 410 deletions(-) diff --git a/src/docs/asciidoc/integration.adoc b/src/docs/asciidoc/integration.adoc index 0ba5d71c204..427061e326d 100644 --- a/src/docs/asciidoc/integration.adoc +++ b/src/docs/asciidoc/integration.adoc @@ -2738,7 +2738,7 @@ describes all available attributes: .Attributes of the JMS element [cols="1,6"] |=== -| Attribute| Description +| Attribute | Description | id | 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 element [cols="1,6"] |=== -| Attribute| Description +| Attribute | Description | container-type | The type of this listener container. Available options are: `default`, `simple`, @@ -2931,7 +2931,7 @@ table: .Attributes of the JMS element [cols="1,6"] |=== -| Attribute| Description +| Attribute | Description | factory-id | 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 [cols="1,4"] |=== -| Registration behavior| Explanation +| Registration behavior | Explanation | `REGISTRATION_FAIL_ON_EXISTING` | This is the default registration behavior. If an `MBean` instance has already been @@ -3518,7 +3518,7 @@ metadata types: .Source-level metadata parameters [cols="1,3,1"] |=== -| Parameter| Description| Applies to +| Parameter | Description | Applies to | `ObjectName` | 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 [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) | not set @@ -5270,7 +5270,7 @@ The operation object approach uses records in the same manner as the `CciTemplat .Usage of Interaction execute methods [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) | not set @@ -7413,7 +7413,7 @@ javadoc for more details]. .Cache annotation settings [cols="1,1,1,3"] |=== -| XML Attribute| Annotation Attribute| Default| Description +| XML Attribute | Annotation Attribute | Default | Description | `cache-manager` | N/A (See `CachingConfigurer` javadocs) @@ -7597,7 +7597,7 @@ counterpart: .Spring vs. JSR-107 caching annotations [cols="1,1,3"] |=== -| Spring| JSR-107| Remark +| Spring | JSR-107 | Remark | `@Cacheable` | `@CacheResult` diff --git a/src/docs/asciidoc/web/webflux.adoc b/src/docs/asciidoc/web/webflux.adoc index 9e7f41bf8eb..d3a3c3be2a1 100644 --- a/src/docs/asciidoc/web/webflux.adoc +++ b/src/docs/asciidoc/web/webflux.adoc @@ -258,27 +258,27 @@ the server APIs are used and where Reactive Streams support comes from: [cols="1,2,2", options="header"] |=== -|Server name|Server API used|Reactive Streams support +| Server name | Server API used | Reactive Streams support -|Netty -|Netty API -|https://github.com/reactor/reactor-netty[Reactor Netty] +| Netty +| Netty API +| https://github.com/reactor/reactor-netty[Reactor Netty] -|Undertow -|Undertow API -|spring-web: Undertow to Reactive Streams bridge +| Undertow +| Undertow API +| spring-web: Undertow to Reactive Streams bridge -|Tomcat -|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 +| Tomcat +| 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 -|Jetty -|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 +| Jetty +| 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 -|Servlet 3.1 container -|Servlet 3.1 non-blocking I/O -|spring-web: Servlet 3.1 non-blocking I/O to Reactive Streams bridge +| Servlet 3.1 container +| Servlet 3.1 non-blocking I/O +| spring-web: Servlet 3.1 non-blocking I/O to Reactive Streams bridge |=== Here are required dependencies, @@ -406,44 +406,40 @@ The table below lists the components that `WebHttpHandlerBuilder` detects: [cols="2,2,1,3", options="header"] |=== -|Bean name|Bean type|Count|Description - -| -|`WebExceptionHandler` -|0..N -|Exception handlers to apply after all ``WebFilter``'s and the target `WebHandler`. - -| -|`WebFilter` -|0..N -|Filters to invoke before and after the target `WebHandler`. - -|"webHandler" -|`WebHandler` -|1 -|The handler for the request. - -|"webSessionManager" -|`WebSessionManager` -|0..1 -|The manager for ``WebSession``'s exposed through a method on `ServerWebExchange`. - -`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. - -|"localeContextResolver" -|`LocaleContextResolver` -|0..1 -|The resolver for `LocaleContext` exposed through a method on `ServerWebExchange`. - -`AcceptHeaderLocaleContextResolver` by default. +| Bean name | Bean type | Count | Description + +| +| `WebExceptionHandler` +| 0..N +| Exception handlers to apply after all ``WebFilter``'s and the target `WebHandler`. + +| +| `WebFilter` +| 0..N +| Filters to invoke before and after the target `WebHandler`. + +| "webHandler" +| `WebHandler` +| 1 +| The handler for the request. + +| "webSessionManager" +| `WebSessionManager` +| 0..1 +| The manager for ``WebSession``'s exposed through a method on `ServerWebExchange`. + `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. + +| "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]] [cols="1,2", options="header"] |=== -| Bean type| Explanation +| Bean type | Explanation | HandlerMapping | 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 | Process the result from the handler invocation and finalize the response. -See <>. + See <>. |=== @@ -1139,111 +1135,109 @@ etc, and is equivalent to `required=false`. [cols="1,2", options="header"] |=== -|Controller method argument|Description +| Controller method argument | Description -|`ServerWebExchange` -|Access to the full `ServerWebExchange` -- container for the HTTP request and response, -request and session attributes, `checkNotModified` methods, and others. +| `ServerWebExchange` +| Access to the full `ServerWebExchange` -- container for the HTTP request and response, + request and session attributes, `checkNotModified` methods, and others. -|`ServerHttpRequest`, `ServerHttpResponse` -|Access to the HTTP request or response. +| `ServerHttpRequest`, `ServerHttpResponse` +| Access to the HTTP request or response. -|`WebSession` -|Access to the session; this does not force the start of a new session unless attributes -are added. Supports reactive types. +| `WebSession` +| Access to the session; this does not force the start of a new session unless attributes + are added. Supports reactive types. -|`java.security.Principal` -|Currently authenticated user; possibly a specific `Principal` implementation class if known. -Supports reactive types. +| `java.security.Principal` +| Currently authenticated user; possibly a specific `Principal` implementation class if known. + Supports reactive types. -|`org.springframework.http.HttpMethod` -|The HTTP method of the request. +| `org.springframework.http.HttpMethod` +| The HTTP method of the request. - |`java.util.Locale` - |The current request locale, determined by the most specific `LocaleResolver` available, in - effect, the configured `LocaleResolver`/`LocaleContextResolver`. +| `java.util.Locale` +| The current request locale, determined by the most specific `LocaleResolver` available, in + effect, the configured `LocaleResolver`/`LocaleContextResolver`. -|Java 6+: `java.util.TimeZone` + -Java 8+: `java.time.ZoneId` -|The time zone associated with the current request, as determined by a `LocaleContextResolver`. +| `java.util.TimeZone` + `java.time.ZoneId` +| The time zone associated with the current request, as determined by a `LocaleContextResolver`. -|`@PathVariable` -|For access to URI template variables. -See <>. +| `@PathVariable` +| For access to URI template variables. See <>. -|`@MatrixVariable` -|For access to name-value pairs in URI path segments. See <>. +| `@MatrixVariable` +| For access to name-value pairs in URI path segments. See <>. -|`@RequestParam` -|For access to Servlet request parameters. Parameter values are converted to the declared -method argument type. See <>. +| `@RequestParam` +| For access to Servlet request parameters. Parameter values are converted to the declared + method argument type. See <>. -Note that use of `@RequestParam` is optional, e.g. to set its attributes. -See "Any other argument" further below in this table. + Note that use of `@RequestParam` is optional, e.g. to set its attributes. + See "Any other argument" further below in this table. -|`@RequestHeader` -|For access to request headers. Header values are converted to the declared method argument -type. See <>. +| `@RequestHeader` +| For access to request headers. Header values are converted to the declared method argument + type. See <>. -|`@CookieValue` -|For access to cookies. Cookies values are converted to the declared method argument -type. See <>. +| `@CookieValue` +| For access to cookies. Cookies values are converted to the declared method argument type. + See <>. -|`@RequestBody` -|For access to the HTTP request body. Body content is converted to the declared method -argument type using ``HttpMessageReader``'s. Supports reactive types. -<>. +| `@RequestBody` +| For access to the HTTP request body. Body content is converted to the declared method + argument type using ``HttpMessageReader``'s. Supports reactive types. + See <>. -|`HttpEntity` -|For access to request headers and body. The body is converted with ``HttpMessageReader``'s. -Supports reactive types. See <>. +| `HttpEntity` +| For access to request headers and body. The body is converted with ``HttpMessageReader``'s. + Supports reactive types. See <>. -|`@RequestPart` -|For access to a part in a "multipart/form-data" request. Supports reactive types. -See <> and <>. +| `@RequestPart` +| For access to a part in a "multipart/form-data" request. Supports reactive types. + See <> and <>. -|`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 -part of view rendering. +| `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 + part of view rendering. -|`@ModelAttribute` -|For access to an existing attribute in the model (instantiated if not present) with -data binding and validation applied. See <> as well -as <> and <>. +| `@ModelAttribute` +| For access to an existing attribute in the model (instantiated if not present) with + data binding and validation applied. See <> as well + as <> and <>. -Note that use of `@ModelAttribute` is optional, e.g. to set its attributes. -See "Any other argument" further below in this table. - -|`Errors`, `BindingResult` -|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 -`@RequestPart` arguments; an `Errors`, or `BindingResult` argument must be declared -immediately after the validated method argument. - -|`SessionStatus` + class-level `@SessionAttributes` -|For marking form processing complete which triggers cleanup of session attributes -declared through a class-level `@SessionAttributes` annotation. See -<> for more details. - -|`UriComponentsBuilder` -|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 -`X-Forwarded-*` headers. -// See <>. - -|`@SessionAttribute` -|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 -<> for more details. - -|`@RequestAttribute` -|For access to request attributes. See <> for more details. - -|Any other argument -|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 -{api-spring-framework}/beans/BeanUtils.html#isSimpleProperty-java.lang.Class-[BeanUtils#isSimpleProperty], -or as an `@ModelAttribute` otherwise. + Note that use of `@ModelAttribute` is optional, e.g. to set its attributes. + See "Any other argument" further below in this table. + +| `Errors`, `BindingResult` +| 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 + `@RequestPart` arguments; an `Errors`, or `BindingResult` argument must be declared + immediately after the validated method argument. + +| `SessionStatus` + class-level `@SessionAttributes` +| For marking form processing complete which triggers cleanup of session attributes + declared through a class-level `@SessionAttributes` annotation. + See <> for more details. + +| `UriComponentsBuilder` +| 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 + `X-Forwarded-*` headers. + // TODO: See <>. + +| `@SessionAttribute` +| 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 + <> for more details. + +| `@RequestAttribute` +| For access to request attributes. See <> for more details. + +| Any other argument +| 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 + {api-spring-framework}/beans/BeanUtils.html#isSimpleProperty-java.lang.Class-[BeanUtils#isSimpleProperty], + or as an `@ModelAttribute` otherwise. |=== @@ -1257,66 +1251,66 @@ generally supported for all return values. [cols="1,2", options="header"] |=== -|Controller method return value|Description - -|`@ResponseBody` -|The return value is encoded through ``HttpMessageWriter``'s and written to the response. -See <>. - -|`HttpEntity`, `ResponseEntity` -|The return value specifies the full response including HTTP headers and body be encoded -through ``HttpMessageWriter``'s and written to the response. -See <>. - -|`HttpHeaders` -|For returning a response with headers and no body. - -|`String` -|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 -method may also programmatically enrich the model by declaring a `Model` argument (see -above). - -|`View` -|A `View` instance to use for rendering together with the implicit model -- determined -through command objects and `@ModelAttribute` methods. The handler method may also -programmatically enrich the model by declaring a `Model` argument (see above). - -|`java.util.Map`, `org.springframework.ui.Model` -|Attributes to be added to the implicit model with the view name implicitly determined -based on the request path. - -|`@ModelAttribute` -|An attribute to be added to the model with the view name implicitly determined based -on the request path. - -Note that `@ModelAttribute` is optional. See "Any other return value" further below in -this table. - -|`Rendering` -|An API for model and view rendering scenarios. - -|`void` -|A method with a `void`, possibly async (e.g. `Mono`), return type (or a `null` return -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 -if the controller has made a positive ETag or lastModified timestamp check. -// TODO (see <> for details) - -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. - -|`Flux`, `Observable`, or other reactive type -|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 -through the produces attribute). - -|Any other return value -|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 -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] -in which case it remains unresolved. +| Controller method return value | Description + +| `@ResponseBody` +| The return value is encoded through ``HttpMessageWriter``'s and written to the response. + See <>. + +| `HttpEntity`, `ResponseEntity` +| The return value specifies the full response including HTTP headers and body be encoded + through ``HttpMessageWriter``'s and written to the response. + See <>. + +| `HttpHeaders` +| For returning a response with headers and no body. + +| `String` +| 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 + method may also programmatically enrich the model by declaring a `Model` argument + (see above). + +| `View` +| A `View` instance to use for rendering together with the implicit model -- determined + through command objects and `@ModelAttribute` methods. The handler method may also + programmatically enrich the model by declaring a `Model` argument (see above). + +| `java.util.Map`, `org.springframework.ui.Model` +| Attributes to be added to the implicit model with the view name implicitly determined + based on the request path. + +| `@ModelAttribute` +| An attribute to be added to the model with the view name implicitly determined based + on the request path. + + Note that `@ModelAttribute` is optional. See "Any other return value" further below in + this table. + +| `Rendering` +| An API for model and view rendering scenarios. + +| `void` +| A method with a `void`, possibly async (e.g. `Mono`), return type (or a `null` return + 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 + if the controller has made a positive ETag or lastModified timestamp check. + // TODO: See <> for details. + + 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. + +| `Flux`, `Observable`, or other reactive type +| 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 + through the produces attribute). + +| Any other return value +| 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 + 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] + in which case it remains unresolved. |=== @@ -2590,8 +2584,7 @@ evaluated and if present a `304` status code is returned. } ---- -// TODO: -// See also <>. +// TODO: See also <>. The resource handler also supports a chain of {api-spring-framework}/web/reactive/resource/ResourceResolver.html[ResourceResolver]'s and diff --git a/src/docs/asciidoc/web/webmvc-view.adoc b/src/docs/asciidoc/web/webmvc-view.adoc index f546a40637d..a334fe45952 100644 --- a/src/docs/asciidoc/web/webmvc-view.adoc +++ b/src/docs/asciidoc/web/webmvc-view.adoc @@ -214,9 +214,9 @@ parameter list that each takes. [[views-macros-defs-tbl]] .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) | <@spring.message code/> diff --git a/src/docs/asciidoc/web/webmvc.adoc b/src/docs/asciidoc/web/webmvc.adoc index 12aa8e224ce..7381217989f 100644 --- a/src/docs/asciidoc/web/webmvc.adoc +++ b/src/docs/asciidoc/web/webmvc.adoc @@ -520,24 +520,23 @@ The table below lists the available `HandlerExceptionResolver` implementations: [cols="1,2", options="header"] .HandlerExceptionResolver implementations |=== -| HandlerExceptionResolver| Description +| HandlerExceptionResolver | Description | `SimpleMappingExceptionResolver` | 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] | Resolves exceptions raised by Spring MVC and maps them to HTTP status codes. - -Also see alternative `ResponseEntityExceptionHandler` and <>. + Also see alternative `ResponseEntityExceptionHandler` and <>. | `ResponseStatusExceptionResolver` | 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` | Resolves exceptions by invoking an `@ExceptionHandler` method in an `@Controller` or an -`@ControllerAdvice` class. See <>. + `@ControllerAdvice` class. See <>. |=== @@ -811,7 +810,7 @@ maximum age. Find below an example of defining a `CookieLocaleResolver`. .CookieLocaleResolver properties [cols="1,1,4"] |=== -| Property| Default| Description +| Property | Default | Description | cookieName | classname + LOCALE @@ -954,7 +953,7 @@ alter the request's theme. The following theme resolvers are provided by Spring: .ThemeResolver implementations [cols="1,4"] |=== -| Class| Description +| Class | Description | `FixedThemeResolver` | 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"] |=== -|Controller method argument|Description +| Controller method argument | Description -|`WebRequest`, `NativeWebRequest` -|Generic access to request parameters, request & session attributes, without direct -use of the Servlet API. +| `WebRequest`, `NativeWebRequest` +| Generic access to request parameters, request & session attributes, without direct + use of the Servlet API. -|`javax.servlet.ServletRequest`, `javax.servlet.ServletResponse` -|Choose any specific request or response type -- e.g. `ServletRequest`, `HttpServletRequest`, -or Spring's `MultipartRequest`, `MultipartHttpServletRequest`. +| `javax.servlet.ServletRequest`, `javax.servlet.ServletResponse` +| Choose any specific request or response type -- e.g. `ServletRequest`, `HttpServletRequest`, + or Spring's `MultipartRequest`, `MultipartHttpServletRequest`. -|`javax.servlet.http.HttpSession` -|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 -``RequestMappingHandlerAdapter``'s "synchronizeOnSession" flag to "true" if multiple -requests are allowed to access a session concurrently. +| `javax.servlet.http.HttpSession` +| 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 + ``RequestMappingHandlerAdapter``'s "synchronizeOnSession" flag to "true" if multiple + requests are allowed to access a session concurrently. -|`javax.servlet.http.PushBuilder` -|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 - does not support that HTTP/2 feature. +| `javax.servlet.http.PushBuilder` +| 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 + does not support that HTTP/2 feature. -|`java.security.Principal` -|Currently authenticated user; possibly a specific `Principal` implementation class if known. +| `java.security.Principal` +| Currently authenticated user; possibly a specific `Principal` implementation class if known. -|`HttpMethod` -|The HTTP method of the request. +| `HttpMethod` +| The HTTP method of the request. -|`java.util.Locale` -|The current request locale, determined by the most specific `LocaleResolver` available, in -effect, the configured `LocaleResolver`/`LocaleContextResolver`. +| `java.util.Locale` +| The current request locale, determined by the most specific `LocaleResolver` available, in + effect, the configured `LocaleResolver`/`LocaleContextResolver`. -|Java 6+: `java.util.TimeZone` + -Java 8+: `java.time.ZoneId` -|The time zone associated with the current request, as determined by a `LocaleContextResolver`. +| `java.util.TimeZone` + `java.time.ZoneId` +| The time zone associated with the current request, as determined by a `LocaleContextResolver`. -|`java.io.InputStream`, `java.io.Reader` -|For access to the raw request body as exposed by the Servlet API. +| `java.io.InputStream`, `java.io.Reader` +| For access to the raw request body as exposed by the Servlet API. -|`java.io.OutputStream`, `java.io.Writer` -|For access to the raw response body as exposed by the Servlet API. +| `java.io.OutputStream`, `java.io.Writer` +| For access to the raw response body as exposed by the Servlet API. -|`@PathVariable` -|For access to URI template variables. See <>. +| `@PathVariable` +| For access to URI template variables. See <>. -|`@MatrixVariable` -|For access to name-value pairs in URI path segments. See <>. +| `@MatrixVariable` +| For access to name-value pairs in URI path segments. See <>. -|`@RequestParam` -|For access to Servlet request parameters. Parameter values are converted to the declared -method argument type. See <>. +| `@RequestParam` +| For access to Servlet request parameters. Parameter values are converted to the declared + method argument type. See <>. -Note that use of `@RequestParam` is optional, e.g. to set its attributes. -See "Any other argument" further below in this table. + Note that use of `@RequestParam` is optional, e.g. to set its attributes. + See "Any other argument" further below in this table. -|`@RequestHeader` -|For access to request headers. Header values are converted to the declared method argument -type. See <>. +| `@RequestHeader` +| For access to request headers. Header values are converted to the declared method argument + type. See <>. -|`@CookieValue` -|For access to cookies. Cookies values are converted to the declared method argument -type. See <>. +| `@CookieValue` +| For access to cookies. Cookies values are converted to the declared method argument + type. See <>. -|`@RequestBody` -|For access to the HTTP request body. Body content is converted to the declared method -argument type using ``HttpMessageConverter``s. See <>. +| `@RequestBody` +| For access to the HTTP request body. Body content is converted to the declared method + argument type using ``HttpMessageConverter``s. See <>. -|`HttpEntity` -|For access to request headers and body. The body is converted with ``HttpMessageConverter``s. -See <>. +| `HttpEntity` +| For access to request headers and body. The body is converted with ``HttpMessageConverter``s. + See <>. -|`@RequestPart` -|For access to a part in a "multipart/form-data" request. -See <>. +| `@RequestPart` +| For access to a part in a "multipart/form-data" request. + See <>. -|`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 -part of view rendering. +| `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 + part of view rendering. -|`RedirectAttributes` -|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. -See <> and <>. +| `RedirectAttributes` +| 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. + See <> and <>. -|`@ModelAttribute` -|For access to an existing attribute in the model (instantiated if not present) with -data binding and validation applied. See <> as well as -<> and <>. +| `@ModelAttribute` +| For access to an existing attribute in the model (instantiated if not present) with + data binding and validation applied. See <> as well as + <> and <>. -Note that use of `@ModelAttribute` is optional, e.g. to set its attributes. -See "Any other argument" further below in this table. - -|`Errors`, `BindingResult` -|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 -`@RequestPart` arguments; an `Errors`, or `BindingResult` argument must be declared -immediately after the validated method argument. - -|`SessionStatus` + class-level `@SessionAttributes` -|For marking form processing complete which triggers cleanup of session attributes -declared through a class-level `@SessionAttributes` annotation. See -<> for more details. - -|`UriComponentsBuilder` -|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 -`X-Forwarded-*` headers. See <>. - -|`@SessionAttribute` -|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 -<> for more details. - -|`@RequestAttribute` -|For access to request attributes. See <> for more details. - -|Any other argument -|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 -{api-spring-framework}/beans/BeanUtils.html#isSimpleProperty-java.lang.Class-[BeanUtils#isSimpleProperty], -or as an `@ModelAttribute` otherwise. + Note that use of `@ModelAttribute` is optional, e.g. to set its attributes. + See "Any other argument" further below in this table. + +| `Errors`, `BindingResult` +| 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 + `@RequestPart` arguments; an `Errors`, or `BindingResult` argument must be declared + immediately after the validated method argument. + +| `SessionStatus` + class-level `@SessionAttributes` +| For marking form processing complete which triggers cleanup of session attributes + declared through a class-level `@SessionAttributes` annotation. See + <> for more details. + +| `UriComponentsBuilder` +| 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 + `X-Forwarded-*` headers. See <>. + +| `@SessionAttribute` +| 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 + <> for more details. + +| `@RequestAttribute` +| For access to request attributes. See <> for more details. + +| Any other argument +| 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 + {api-spring-framework}/beans/BeanUtils.html#isSimpleProperty-java.lang.Class-[BeanUtils#isSimpleProperty], + or as an `@ModelAttribute` otherwise. |=== @@ -1682,96 +1680,96 @@ supported for all return values, see below for more details. [cols="1,2", options="header"] |=== -|Controller method return value|Description - -|`@ResponseBody` -|The return value is converted through ``HttpMessageConverter``s and written to the -response. See <>. - -|`HttpEntity`, `ResponseEntity` -|The return value specifies the full response including HTTP headers and body be converted -through ``HttpMessageConverter``s and written to the response. -See <>. - -|`HttpHeaders` -|For returning a response with headers and no body. - -|`String` -|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 -method may also programmatically enrich the model by declaring a `Model` argument (see -above). - -|`View` -|A `View` instance to use for rendering together with the implicit model -- determined -through command objects and `@ModelAttribute` methods. The handler method may also -programmatically enrich the model by declaring a `Model` argument (see above). - -|`java.util.Map`, `org.springframework.ui.Model` -|Attributes to be added to the implicit model with the view name implicitly determined -through a `RequestToViewNameTranslator`. - -|`@ModelAttribute` -|An attribute to be added to the model with the view name implicitly determined through -a `RequestToViewNameTranslator`. - -Note that `@ModelAttribute` is optional. See "Any other return value" further below in -this table. - -|`ModelAndView` object -|The view and model attributes to use, and optionally a response status. - -|`void` -|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 -`@ResponseStatus` annotation. The same is true also if the controller has made a positive -ETag or lastModified timestamp check (see <> for details). - -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. - -|`DeferredResult` -|Produce any of the above return values asynchronously from any thread -- e.g. possibly as a -result of some event or callback. See <> and -<>. - -|`Callable` -|Produce any of the above return values asynchronously in a Spring MVC managed thread. -See <> and <>. - -|`ListenableFuture`, -`java.util.concurrent.CompletionStage`, -`java.util.concurrent.CompletableFuture` -|Alternative to `DeferredResult` as a convenience for example when an underlying service -returns one of those. - -|`ResponseBodyEmitter`, `SseEmitter` -|Emit a stream of objects asynchronously to be written to the response with -``HttpMessageConverter``'s; also supported as the body of a `ResponseEntity`. -See <> and <>. - -|`StreamingResponseBody` -|Write to the response `OutputStream` asynchronously; also supported as the body of a -`ResponseEntity`. See <> and <>. - -|Reactive types -- Reactor, RxJava, or others via `ReactiveAdapterRegistry` -|Alternative to ``DeferredResult` with multi-value streams (e.g. `Flux`, `Observable`) -collected to a `List`. - -For streaming scenarios -- .e.g. `text/event-stream`, `application/json+stream`, -`SseEmitter` and `ResponseBodyEmitter` are used instead, where `ServletOutputStream` blocking -I/O is performed on a Spring MVC managed thread and back pressure applied against the -completion of each write. - -See <> and <>. - -|Any other return value -|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 -`RequestToViewNameTranslator` applies); or as a model 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] -in which case it remains unresolved. +| Controller method return value | Description + +| `@ResponseBody` +| The return value is converted through ``HttpMessageConverter``s and written to the + response. See <>. + +| `HttpEntity`, `ResponseEntity` +| The return value specifies the full response including HTTP headers and body be converted + through ``HttpMessageConverter``s and written to the response. + See <>. + +| `HttpHeaders` +| For returning a response with headers and no body. + +| `String` +| 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 + method may also programmatically enrich the model by declaring a `Model` argument + (see above). + +| `View` +| A `View` instance to use for rendering together with the implicit model -- determined + through command objects and `@ModelAttribute` methods. The handler method may also + programmatically enrich the model by declaring a `Model` argument (see above). + +| `java.util.Map`, `org.springframework.ui.Model` +| Attributes to be added to the implicit model with the view name implicitly determined + through a `RequestToViewNameTranslator`. + +| `@ModelAttribute` +| An attribute to be added to the model with the view name implicitly determined through + a `RequestToViewNameTranslator`. + + Note that `@ModelAttribute` is optional. See "Any other return value" further below in + this table. + +| `ModelAndView` object +| The view and model attributes to use, and optionally a response status. + +| `void` +| 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 `@ResponseStatus` annotation. The same is true also if the controller has made a positive + ETag or lastModified timestamp check (see <> for details). + + 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. + +| `DeferredResult` +| Produce any of the above return values asynchronously from any thread -- e.g. possibly as a + result of some event or callback. See <> and + <>. + +| `Callable` +| Produce any of the above return values asynchronously in a Spring MVC managed thread. + See <> and <>. + +| `ListenableFuture`, + `java.util.concurrent.CompletionStage`, + `java.util.concurrent.CompletableFuture` +| Alternative to `DeferredResult` as a convenience for example when an underlying service + returns one of those. + +| `ResponseBodyEmitter`, `SseEmitter` +| Emit a stream of objects asynchronously to be written to the response with + ``HttpMessageConverter``'s; also supported as the body of a `ResponseEntity`. + See <> and <>. + +| `StreamingResponseBody` +| Write to the response `OutputStream` asynchronously; also supported as the body of a + `ResponseEntity`. See <> and <>. + +| Reactive types -- Reactor, RxJava, or others via `ReactiveAdapterRegistry` +| Alternative to ``DeferredResult` with multi-value streams (e.g. `Flux`, `Observable`) + collected to a `List`. + + For streaming scenarios -- e.g. `text/event-stream`, `application/json+stream` -- + `SseEmitter` and `ResponseBodyEmitter` are used instead, where `ServletOutputStream` + blocking I/O is performed on a Spring MVC managed thread and back pressure applied + against the completion of each write. + + See <> and <>. + +| Any other return value +| 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 + `RequestToViewNameTranslator` applies); or as a model 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] + in which case it remains unresolved. |===