diff --git a/src/docs/asciidoc/integration.adoc b/src/docs/asciidoc/integration.adoc index 6fbe67b051a..0ca100c30de 100644 --- a/src/docs/asciidoc/integration.adoc +++ b/src/docs/asciidoc/integration.adoc @@ -1113,7 +1113,7 @@ converters to use explicitly. [[rest-message-conversion]] ===== Message Conversion -[.small]#<># +[.small]#<># The `spring-web` module contains the `HttpMessageConverter` contract for reading and writing the body of HTTP requests and responses through `InputStream` and `OutputStream`. diff --git a/src/docs/asciidoc/web/webflux-cors.adoc b/src/docs/asciidoc/web/webflux-cors.adoc index 33bd4b0e403..7d48a60e7a8 100644 --- a/src/docs/asciidoc/web/webflux-cors.adoc +++ b/src/docs/asciidoc/web/webflux-cors.adoc @@ -1,6 +1,6 @@ [[webflux-cors]] = CORS -[.small]#<># +[.small]#<># Spring WebFlux lets you handle CORS (Cross-Origin Resource Sharing). This section describes how to do so. @@ -10,7 +10,7 @@ describes how to do so. [[webflux-cors-intro]] == Introduction -[.small]#<># +[.small]#<># For security reasons, browsers prohibit AJAX calls to resources outside the current origin. For example, you could have your bank account in one tab and evil.com in another. Scripts @@ -27,7 +27,7 @@ powerful workarounds based on IFRAME or JSONP. [[webflux-cors-processing]] == Processing -[.small]#<># +[.small]#<># The CORS specification distinguishes between preflight, simple, and actual requests. To learn how CORS works, you can read @@ -77,7 +77,7 @@ To learn more from the source or to make advanced customizations, see: [[webflux-cors-controller]] == `@CrossOrigin` -[.small]#<># +[.small]#<># The {api-spring-framework}/web/bind/annotation/CrossOrigin.html[`@CrossOrigin`] annotation enables cross-origin requests on annotated controller methods, as the @@ -230,7 +230,7 @@ as the following example shows: [[webflux-cors-global]] == Global Configuration -[.small]#<># +[.small]#<># In addition to fine-grained, controller method-level configuration, you probably want to define some global CORS configuration, too. You can set URL-based `CorsConfiguration` @@ -299,7 +299,7 @@ as the following example shows: [[webflux-cors-webfilter]] == CORS `WebFilter` -[.small]#<># +[.small]#<># You can apply CORS support through the built-in {api-spring-framework}/web/cors/reactive/CorsWebFilter.html[`CorsWebFilter`], which is a diff --git a/src/docs/asciidoc/web/webflux-functional.adoc b/src/docs/asciidoc/web/webflux-functional.adoc index c79290b1398..a69c98976c3 100644 --- a/src/docs/asciidoc/web/webflux-functional.adoc +++ b/src/docs/asciidoc/web/webflux-functional.adoc @@ -1,6 +1,6 @@ [[webflux-fn]] = Functional Endpoints -[.small]#<># +[.small]#<># Spring WebFlux includes WebFlux.fn, a lightweight functional programming model in which functions are used to route and handle requests and contracts are designed for immutability. @@ -12,7 +12,7 @@ the same <> foundation. [[webflux-fn-overview]] == Overview -[.small]#<># +[.small]#<># In WebFlux.fn, an HTTP request is handled with a `HandlerFunction`: a function that takes `ServerRequest` and returns a delayed `ServerResponse` (i.e. `Mono`). @@ -112,7 +112,7 @@ Most applications can run through the WebFlux Java configuration, see <># +[.small]#<># `ServerRequest` and `ServerResponse` are immutable interfaces that offer JDK 8-friendly access to the HTTP request and response. @@ -440,7 +440,7 @@ See <>. [[webflux-fn-router-functions]] == `RouterFunction` -[.small]#<># +[.small]#<># Router functions are used to route the requests to the corresponding `HandlerFunction`. Typically, you do not write router functions yourself, but rather use a method on the @@ -639,7 +639,7 @@ We can further improve by using the `nest` method together with `accept`: [[webflux-fn-running]] == Running a Server -[.small]#<># +[.small]#<># How do you run a router function in an HTTP server? A simple option is to convert a router function to an `HttpHandler` by using one of the following: @@ -745,7 +745,7 @@ The following example shows a WebFlux Java configuration (see [[webflux-fn-handler-filter-function]] == Filtering Handler Functions -[.small]#<># +[.small]#<># You can filter handler functions by using the `before`, `after`, or `filter` methods on the routing function builder. diff --git a/src/docs/asciidoc/web/webflux-view.adoc b/src/docs/asciidoc/web/webflux-view.adoc index 9ab7ec1c1ec..0321f1fd1df 100644 --- a/src/docs/asciidoc/web/webflux-view.adoc +++ b/src/docs/asciidoc/web/webflux-view.adoc @@ -1,6 +1,6 @@ [[webflux-view]] = View Technologies -[.small]#<># +[.small]#<># The use of view technologies in Spring WebFlux is pluggable. Whether you decide to use Thymeleaf, FreeMarker, or some other view technology is primarily a matter of a @@ -12,7 +12,7 @@ WebFlux. We assume you are already familiar with <>. [[webflux-view-thymeleaf]] == Thymeleaf -[.small]#<># +[.small]#<># Thymeleaf is a modern server-side Java template engine that emphasizes natural HTML templates that can be previewed in a browser by double-clicking, which is very @@ -33,7 +33,7 @@ http://forum.thymeleaf.org/Thymeleaf-3-0-8-JUST-PUBLISHED-td4030687.html[announc [[webflux-view-freemarker]] == FreeMarker -[.small]#<># +[.small]#<># https://freemarker.apache.org/[Apache FreeMarker] is a template engine for generating any kind of text output from HTML to email and others. The Spring Framework has built-in @@ -43,7 +43,7 @@ integration for using Spring WebFlux with FreeMarker templates. [[webflux-view-freemarker-contextconfig]] === View Configuration -[.small]#<># +[.small]#<># The following example shows how to configure FreeMarker as a view technology: @@ -98,7 +98,7 @@ returns the view name, `welcome`, the resolver looks for the [[webflux-views-freemarker]] === FreeMarker Configuration -[.small]#<># +[.small]#<># You can pass FreeMarker 'Settings' and 'SharedVariables' directly to the FreeMarker `Configuration` object (which is managed by Spring) by setting the appropriate bean @@ -151,7 +151,7 @@ the `Configuration` object. [[webflux-view-freemarker-forms]] === Form Handling -[.small]#<># +[.small]#<># Spring provides a tag library for use in JSPs that contains, among others, a `` element. This element primarily lets forms display values from @@ -162,7 +162,7 @@ with additional convenience macros for generating form input elements themselves [[webflux-view-bind-macros]] ==== The Bind Macros -[.small]#<># +[.small]#<># A standard set of macros are maintained within the `spring-webflux.jar` file for FreeMarker, so they are always available to a suitably configured application. @@ -193,7 +193,7 @@ sections of the Spring MVC documentation. [[webflux-view-script]] == Script Views -[.small]#<># +[.small]#<># The Spring Framework has a built-in integration for using Spring WebFlux with any templating library that can run on top of the @@ -219,7 +219,7 @@ TIP: The basic rule for integrating any other script engine is that it must impl [[webflux-view-script-dependencies]] === Requirements -[.small]#<># +[.small]#<># You need to have the script engine on your classpath, the details of which vary by script engine: @@ -239,7 +239,7 @@ through https://www.webjars.org/[WebJars]. [[webflux-view-script-integrate]] === Script Templates -[.small]#<># +[.small]#<># You can declare a `ScriptTemplateConfigurer` bean to specify the script engine to use, the script files to load, what function to call to render templates, and so on. @@ -389,7 +389,7 @@ for more configuration examples. [[webflux-view-httpmessagewriter]] == JSON and XML -[.small]#<># +[.small]#<># For <> purposes, it is useful to be able to alternate between rendering a model with an HTML template or as other formats (such as JSON or XML), diff --git a/src/docs/asciidoc/web/webflux.adoc b/src/docs/asciidoc/web/webflux.adoc index 00f71a50baa..b27d5d09143 100644 --- a/src/docs/asciidoc/web/webflux.adoc +++ b/src/docs/asciidoc/web/webflux.adoc @@ -594,7 +594,7 @@ The `DefaultServerWebExchange` uses the configured `HttpMessageReader` to parse [[webflux-multipart]] ==== Multipart Data -[.small]#<># +[.small]#<># `ServerWebExchange` exposes the following method for access to multipart data: @@ -626,7 +626,7 @@ content to `Flux` without collecting to a `MultiValueMap`. [[webflux-forwarded-headers]] ==== Forwarded Headers -[.small]#<># +[.small]#<># As a request goes through proxies (such as load balancers), the host, port, and scheme may change, and that makes it a challenge, from a client perspective, to create links that point to the correct @@ -657,7 +657,7 @@ filters, and `ForwardedHeaderTransformer` is used instead. [[webflux-filters]] === Filters -[.small]#<># +[.small]#<># In the <>, you can use a `WebFilter` to apply interception-style logic before and after the rest of the processing chain of filters and the target @@ -668,7 +668,7 @@ the bean declaration or by implementing `Ordered`. [[webflux-filters-cors]] ==== CORS -[.small]#<># +[.small]#<># Spring WebFlux provides fine-grained support for CORS configuration through annotations on controllers. However, when you use it with Spring Security, we advise relying on the built-in @@ -680,7 +680,7 @@ See the section on <> and the <> for more [[webflux-exception-handler]] === Exceptions -[.small]#<># +[.small]#<># In the <>, you can use a `WebExceptionHandler` to handle exceptions from the chain of `WebFilter` instances and the target `WebHandler`. When using the @@ -711,7 +711,7 @@ The following table describes the available `WebExceptionHandler` implementation [[webflux-codecs]] === Codecs -[.small]#<># +[.small]#<># The `spring-web` and `spring-core` modules provide support for serializing and deserializing byte content to and from higher level objects through non-blocking I/O with @@ -847,7 +847,7 @@ To configure all 3 in WebFlux, you'll need to supply a pre-configured instance o [[webflux-codecs-streaming]] ==== Streaming -[.small]#<># +[.small]#<># When streaming to the HTTP response (for example, `text/event-stream`, `application/stream+json`), it is important to send data periodically, in order to @@ -875,7 +875,7 @@ especially the section on <>. [[webflux-logging]] === Logging -[.small]#<># +[.small]#<># DEBUG level logging in Spring WebFlux is designed to be compact, minimal, and human-friendly. It focuses on high value bits of information that are useful over and @@ -907,7 +907,7 @@ while a fully formatted prefix based on that ID is available from [[webflux-logging-sensitive-data]] ==== Sensitive Data -[.small]#<># +[.small]#<># `DEBUG` and `TRACE` logging can log sensitive information. This is why form parameters and headers are masked by default and you must explicitly enable their logging in full. @@ -967,7 +967,7 @@ The following example shows how to do so for client-side requests: [[webflux-dispatcher-handler]] == `DispatcherHandler` -[.small]#<># +[.small]#<># Spring WebFlux, similarly to Spring MVC, is designed around the front controller pattern, where a central `WebHandler`, the `DispatcherHandler`, provides a shared algorithm for @@ -1010,7 +1010,7 @@ The resulting `HttpHandler` is ready for use with a <># +[.small]#<># The `DispatcherHandler` delegates to special beans to process requests and render the appropriate responses. By "`special beans,`" we mean Spring-managed `Object` instances that @@ -1052,7 +1052,7 @@ there are also some other beans detected at a lower level (see [[webflux-framework-config]] === WebFlux Config -[.small]#<># +[.small]#<># Applications can declare the infrastructure beans (listed under <> and @@ -1067,7 +1067,7 @@ many extra convenient options. [[webflux-dispatcher-handler-sequence]] === Processing -[.small]#<># +[.small]#<># `DispatcherHandler` processes requests as follows: @@ -1118,7 +1118,7 @@ as a `HandlerResult`, along with some additional context, and passed to the firs [[webflux-dispatcher-exceptions]] === Exceptions -[.small]#<># +[.small]#<># The `HandlerResult` returned from a `HandlerAdapter` can expose a function for error handling based on some handler-specific mechanism. This error function is called if: @@ -1141,7 +1141,7 @@ See also <> in the "`Annotated Controller`" s [[webflux-viewresolution]] === View Resolution -[.small]#<># +[.small]#<># View resolution enables rendering to a browser with an HTML template and a model without tying you to a specific view technology. In Spring WebFlux, view resolution is @@ -1152,7 +1152,7 @@ instance. The `View` is then used to render the response. [[webflux-viewresolution-handling]] ==== Handling -[.small]#<># +[.small]#<># The `HandlerResult` passed into `ViewResolutionResultHandler` contains the return value from the handler and the model that contains attributes added during request @@ -1188,7 +1188,7 @@ See <> for more on the view technologies integrated with Spring We [[webflux-redirecting-redirect-prefix]] ==== Redirecting -[.small]#<># +[.small]#<># The special `redirect:` prefix in a view name lets you perform a redirect. The `UrlBasedViewResolver` (and sub-classes) recognize this as an instruction that a @@ -1203,7 +1203,7 @@ operate in terms of logical view names. A view name such as [[webflux-multiple-representations]] ==== Content Negotiation -[.small]#<># +[.small]#<># `ViewResolutionResultHandler` supports content negotiation. It compares the request media types with the media types supported by each selected `View`. The first `View` @@ -1220,7 +1220,7 @@ always selected and used if they match the requested media type. [[webflux-controller]] == Annotated Controllers -[.small]#<># +[.small]#<># Spring WebFlux provides an annotation-based programming model, where `@Controller` and `@RestController` components use annotations to express request mappings, request input, @@ -1258,7 +1258,7 @@ In the preceding example, the method returns a `String` to be written to the res [[webflux-ann-controller]] === `@Controller` -[.small]#<># +[.small]#<># You can define controller beans by using a standard Spring bean definition. The `@Controller` stereotype allows for auto-detection and is aligned with Spring general support @@ -1302,7 +1302,7 @@ directly to the response body versus view resolution and rendering with an HTML [[webflux-ann-requestmapping]] === Request Mapping -[.small]#<># +[.small]#<># The `@RequestMapping` annotation is used to map requests to controllers methods. It has various attributes to match by URL, HTTP method, request parameters, headers, and media @@ -1366,7 +1366,7 @@ The following example uses type and method level mappings: [[webflux-ann-requestmapping-uri-templates]] ==== URI Patterns -[.small]#<># +[.small]#<># You can map requests by using glob patterns and wildcards: @@ -1480,7 +1480,7 @@ explicit, and less vulnerable to URL path based exploits. [[webflux-ann-requestmapping-pattern-comparison]] ==== Pattern Comparison -[.small]#<># +[.small]#<># When multiple patterns match a URL, they must be compared to find the best match. This is done with `PathPattern.SPECIFICITY_COMPARATOR`, which looks for patterns that are more specific. @@ -1495,7 +1495,7 @@ sorted last instead. If two patterns are both catch-all, the longer is chosen. [[webflux-ann-requestmapping-consumes]] ==== Consumable Media Types -[.small]#<># +[.small]#<># You can narrow the request mapping based on the `Content-Type` of the request, as the following example shows: @@ -1530,7 +1530,7 @@ TIP: `MediaType` provides constants for commonly used media types -- for example [[webflux-ann-requestmapping-produces]] ==== Producible Media Types -[.small]#<># +[.small]#<># You can narrow the request mapping based on the `Accept` request header and the list of content types that a controller method produces, as the following example shows: @@ -1567,7 +1567,7 @@ TIP: `MediaType` provides constants for commonly used media types -- e.g. [[webflux-ann-requestmapping-params-and-headers]] ==== Parameters and Headers -[.small]#<># +[.small]#<># You can narrow request mappings based on query parameter conditions. You can test for the presence of a query parameter (`myParam`), for its absence (`!myParam`), or for a @@ -1619,7 +1619,7 @@ You can also use the same with request header conditions, as the follwing exampl [[webflux-ann-requestmapping-head-options]] ==== HTTP HEAD, OPTIONS -[.small]#<># +[.small]#<># `@GetMapping` and `@RequestMapping(method=HttpMethod.GET)` support HTTP HEAD transparently for request mapping purposes. Controller methods need not change. @@ -1640,7 +1640,7 @@ is not necessary in the common case. [[webflux-ann-requestmapping-composed]] ==== Custom Annotations -[.small]#<># +[.small]#<># Spring WebFlux supports the use of <> for request mapping. Those are annotations that are themselves meta-annotated with @@ -1661,7 +1661,7 @@ you can check the custom attribute and return your own `RequestCondition`. [[webflux-ann-requestmapping-registration]] ==== Explicit Registrations -[.small]#<># +[.small]#<># You can programmatically register Handler methods, which can be used for dynamic registrations or for advanced cases, such as different instances of the same handler @@ -1718,7 +1718,7 @@ under different URLs. The following example shows how to do so: [[webflux-ann-methods]] === Handler Methods -[.small]#<># +[.small]#<># `@RequestMapping` handler methods have a flexible signature and can choose from a range of supported controller method arguments and return values. @@ -1726,7 +1726,7 @@ supported controller method arguments and return values. [[webflux-ann-arguments]] ==== Method Arguments -[.small]#<># +[.small]#<># The following table shows the supported controller method arguments. @@ -1847,7 +1847,7 @@ and others) and is equivalent to `required=false`. [[webflux-ann-return-types]] ==== Return Values -[.small]#<># +[.small]#<># The following table shows the supported controller method return values. Note that reactive types from libraries such as Reactor, RxJava, <> are @@ -1921,7 +1921,7 @@ generally supported for all return values. [[webflux-ann-typeconversion]] ==== Type Conversion -[.small]#<># +[.small]#<># Some annotated controller method arguments that represent String-based request input (for example, `@RequestParam`, `@RequestHeader`, `@PathVariable`, `@MatrixVariable`, and `@CookieValue`) @@ -1935,7 +1935,7 @@ can be customized through a `WebDataBinder` (see <>) or by r [[webflux-ann-matrix-variables]] ==== Matrix Variables -[.small]#<># +[.small]#<># https://tools.ietf.org/html/rfc3986#section-3.3[RFC 3986] discusses name-value pairs in path segments. In Spring WebFlux, we refer to those as "`matrix variables`" based on an @@ -2070,7 +2070,7 @@ To get all matrix variables, use a `MultiValueMap`, as the following example sho [[webflux-ann-requestparam]] ==== `@RequestParam` -[.small]#<># +[.small]#<># You can use the `@RequestParam` annotation to bind query parameters to a method argument in a controller. The following code snippet shows the usage: @@ -2145,7 +2145,7 @@ with `@RequestParam`. [[webflux-ann-requestheader]] ==== `@RequestHeader` -[.small]#<># +[.small]#<># You can use the `@RequestHeader` annotation to bind a request header to a method argument in a controller. @@ -2206,7 +2206,7 @@ example, a method parameter annotated with `@RequestHeader("Accept")` may be of [[webflux-ann-cookievalue]] ==== `@CookieValue` -[.small]#<># +[.small]#<># You can use the `@CookieValue` annotation to bind the value of an HTTP cookie to a method argument in a controller. @@ -2247,7 +2247,7 @@ Type conversion is applied automatically if the target method parameter type is [[webflux-ann-modelattrib-method-args]] ==== `@ModelAttribute` -[.small]#<># +[.small]#<># You can use the `@ModelAttribute` annotation on a method argument to access an attribute from the model or have it instantiated if not present. The model attribute is also overlain with @@ -2394,7 +2394,7 @@ with `@ModelAttribute`. [[webflux-ann-sessionattributes]] ==== `@SessionAttributes` -[.small]#<># +[.small]#<># `@SessionAttributes` is used to store model attributes in the `WebSession` between requests. It is a type-level annotation that declares session attributes used by a @@ -2479,7 +2479,7 @@ as the following example shows: [[webflux-ann-sessionattribute]] ==== `@SessionAttribute` -[.small]#<># +[.small]#<># If you need access to pre-existing session attributes that are managed globally (that is, outside the controller -- for example, by a filter) and may or may not be present, @@ -2515,7 +2515,7 @@ workflow, consider using `SessionAttributes`, as described in [[webflux-ann-requestattrib]] ==== `@RequestAttribute` -[.small]#<># +[.small]#<># Similarly to `@SessionAttribute`, you can use the `@RequestAttribute` annotation to access pre-existing request attributes created earlier (for example, by a `WebFilter`), @@ -2544,7 +2544,7 @@ as the following example shows: [[webflux-multipart-forms]] ==== Multipart Content -[.small]#<># +[.small]#<># As explained in <>, `ServerWebExchange` provides access to multipart content. The best way to handle a file upload form (for example, from a browser) in a controller @@ -2745,7 +2745,7 @@ To access multipart data sequentially, in streaming fashion, you can use `@Reque [[webflux-ann-requestbody]] ==== `@RequestBody` -[.small]#<># +[.small]#<># You can use the `@RequestBody` annotation to have the request body read and deserialized into an `Object` through an <>. @@ -2819,7 +2819,7 @@ example uses a `BindingResult` argument`: [[webflux-ann-httpentity]] ==== `HttpEntity` -[.small]#<># +[.small]#<># `HttpEntity` is more or less identical to using <> but is based on a container object that exposes request headers and the body. The following example uses an @@ -2845,7 +2845,7 @@ container object that exposes request headers and the body. The following exampl [[webflux-ann-responsebody]] ==== `@ResponseBody` -[.small]#<># +[.small]#<># You can use the `@ResponseBody` annotation on a method to have the return serialized to the response body through an <>. The following @@ -2888,7 +2888,7 @@ configure or customize message writing. [[webflux-ann-responseentity]] ==== `ResponseEntity` -[.small]#<># +[.small]#<># `ResponseEntity` is like <> but with status and headers. For example: @@ -2925,7 +2925,7 @@ Spring offers support for the Jackson JSON library. [[webflux-ann-jsonview]] ===== JSON Views -[.small]#<># +[.small]#<># Spring WebFlux provides built-in support for https://www.baeldung.com/jackson-json-view-annotation[Jackson's Serialization Views], @@ -3003,7 +3003,7 @@ controller method. Use a composite interface if you need to activate multiple vi [[webflux-ann-modelattrib-methods]] === `Model` -[.small]#<># +[.small]#<># You can use the `@ModelAttribute` annotation: @@ -3142,7 +3142,7 @@ as the following example shows: [[webflux-ann-initbinder]] === `DataBinder` -[.small]#<># +[.small]#<># `@Controller` or `@ControllerAdvice` classes can have `@InitBinder` methods, to initialize instances of `WebDataBinder`. Those, in turn, are used to: @@ -3237,7 +3237,7 @@ controller-specific `Formatter` instances, as the following example shows: [[webflux-ann-controller-exceptions]] === Managing Exceptions -[.small]#<># +[.small]#<># `@Controller` and <> classes can have `@ExceptionHandler` methods to handle exceptions from controller methods. The following @@ -3298,7 +3298,7 @@ for more detail. [[webflux-ann-rest-exceptions]] ==== REST API exceptions -[.small]#<># +[.small]#<># A common requirement for REST services is to include error details in the body of the response. The Spring Framework does not automatically do so, because the representation @@ -3316,7 +3316,7 @@ an HTTP status code. [[webflux-ann-controller-advice]] === Controller Advice -[.small]#<># +[.small]#<># Typically, the `@ExceptionHandler`, `@InitBinder`, and `@ModelAttribute` methods apply within the `@Controller` class (or class hierarchy) in which they are declared. If you @@ -3384,7 +3384,7 @@ include::webflux-functional.adoc[leveloffset=+1] [[webflux-uri-building]] == URI Links -[.small]#<># +[.small]#<># This section describes various options available in the Spring Framework to prepare URIs. @@ -3397,7 +3397,7 @@ include::webflux-cors.adoc[leveloffset=+1] [[webflux-web-security]] == Web Security -[.small]#<># +[.small]#<># The https://projects.spring.io/spring-security/[Spring Security] project provides support for protecting web applications from malicious exploits. See the Spring Security @@ -3415,7 +3415,7 @@ include::webflux-view.adoc[leveloffset=+1] [[webflux-caching]] == HTTP Caching -[.small]#<># +[.small]#<># HTTP caching can significantly improve the performance of a web application. HTTP caching revolves around the `Cache-Control` response header and subsequent conditional request @@ -3431,7 +3431,7 @@ This section describes the HTTP caching related options available in Spring WebF [[webflux-caching-cachecontrol]] === `CacheControl` -[.small]#<># +[.small]#<># {api-spring-framework}/http/CacheControl.html[`CacheControl`] provides support for configuring settings related to the `Cache-Control` header and is accepted as an argument @@ -3479,7 +3479,7 @@ use case-oriented approach that focuses on the common scenarios, as the followin [[webflux-caching-etag-lastmodified]] === Controllers -[.small]#<># +[.small]#<># Controllers can add explicit support for HTTP caching. We recommend doing so, since the `lastModified` or `ETag` value for a resource needs to be calculated before it can be compared @@ -3576,7 +3576,7 @@ to 409 (PRECONDITION_FAILED) to prevent concurrent modification. [[webflux-caching-static-resources]] === Static Resources -[.small]#<># +[.small]#<># You should serve static resources with a `Cache-Control` and conditional response headers for optimal performance. See the section on configuring <>. @@ -3586,7 +3586,7 @@ for optimal performance. See the section on configuring <># +[.small]#<># The WebFlux Java configuration declares the components that are required to process requests with annotated controllers or functional endpoints, and it offers an API to @@ -3603,7 +3603,7 @@ gain full control over the configuration through the [[webflux-config-enable]] === Enabling WebFlux Config -[.small]#<># +[.small]#<># You can use the `@EnableWebFlux` annotation in your Java config, as the following example shows: @@ -3632,7 +3632,7 @@ available on the classpath -- for JSON, XML, and others. [[webflux-config-customize]] === WebFlux config API -[.small]#<># +[.small]#<># In your Java configuration, you can implement the `WebFluxConfigurer` interface, as the following example shows: @@ -3663,7 +3663,7 @@ class WebConfig : WebFluxConfigurer { [[webflux-config-conversion]] === Conversion, formatting -[.small]#<># +[.small]#<># By default, formatters for `Number` and `Date` types are installed, including support for the `@NumberFormat` and `@DateTimeFormat` annotations. Full support for the Joda-Time @@ -3706,7 +3706,7 @@ use `FormatterRegistrar` implementations. [[webflux-config-validation]] === Validation -[.small]#<># +[.small]#<># By default, if <> is present on the classpath (for example, the Hibernate Validator), the `LocalValidatorFactoryBean` @@ -3781,7 +3781,7 @@ mark it with `@Primary` in order to avoid conflict with the one declared in the [[webflux-config-content-negotiation]] === Content Type Resolvers -[.small]#<># +[.small]#<># You can configure how Spring WebFlux determines the requested media types for `@Controller` instances from the request. By default, only the `Accept` header is checked, @@ -3819,7 +3819,7 @@ The following example shows how to customize the requested content type resoluti [[webflux-config-message-codecs]] === HTTP message codecs -[.small]#<># +[.small]#<># The following example shows how to customize how the request and response body are read and written: @@ -3870,7 +3870,7 @@ It also automatically registers the following well-known modules if they are det [[webflux-config-view-resolvers]] === View Resolvers -[.small]#<># +[.small]#<># The following example shows how to configure view resolution: @@ -4027,7 +4027,7 @@ See <> for more on the view technologies that are integrated with [[webflux-config-static-resources]] === Static Resources -[.small]#<># +[.small]#<># This option provides a convenient way to serve static resources from a list of {api-spring-framework}/core/io/Resource.html[`Resource`]-based locations. @@ -4142,7 +4142,7 @@ without versions -- for example, from `/jquery/jquery.min.js` to [[webflux-config-path-matching]] === Path Matching -[.small]#<># +[.small]#<># You can customize options related to path matching. For details on the individual options, see the {api-spring-framework}/web/reactive/config/PathMatchConfigurer.html[`PathMatchConfigurer`] javadoc. @@ -4200,7 +4200,7 @@ reliance on it. [[webflux-config-advanced-java]] === Advanced Configuration Mode -[.small]#<># +[.small]#<># `@EnableWebFlux` imports `DelegatingWebFluxConfiguration` that: @@ -4240,7 +4240,7 @@ the classpath. [[webflux-http2]] == HTTP/2 -[.small]#<># +[.small]#<># Servlet 4 containers are required to support HTTP/2, and Spring Framework 5 is compatible with Servlet API 4. From a programming model perspective, there is nothing specific that diff --git a/src/docs/asciidoc/web/webmvc-cors.adoc b/src/docs/asciidoc/web/webmvc-cors.adoc index ada37bb93d7..a5c60e03dff 100644 --- a/src/docs/asciidoc/web/webmvc-cors.adoc +++ b/src/docs/asciidoc/web/webmvc-cors.adoc @@ -1,6 +1,6 @@ [[mvc-cors]] = CORS -[.small]#<># +[.small]#<># Spring MVC lets you handle CORS (Cross-Origin Resource Sharing). This section describes how to do so. @@ -10,7 +10,7 @@ describes how to do so. [[mvc-cors-intro]] == Introduction -[.small]#<># +[.small]#<># For security reasons, browsers prohibit AJAX calls to resources outside the current origin. For example, you could have your bank account in one tab and evil.com in another. Scripts @@ -27,7 +27,7 @@ powerful workarounds based on IFRAME or JSONP. [[mvc-cors-processing]] == Processing -[.small]#<># +[.small]#<># The CORS specification distinguishes between preflight, simple, and actual requests. To learn how CORS works, you can read @@ -77,7 +77,7 @@ To learn more from the source or make advanced customizations, check the code be [[mvc-cors-controller]] == `@CrossOrigin` -[.small]#<># +[.small]#<># The {api-spring-framework}/web/bind/annotation/CrossOrigin.html[`@CrossOrigin`] annotation enables cross-origin requests on annotated controller methods, @@ -224,7 +224,7 @@ as the following example shows: [[mvc-cors-global]] == Global Configuration -[.small]#<># +[.small]#<># In addition to fine-grained, controller method level configuration, you probably want to define some global CORS configuration, too. You can set URL-based `CorsConfiguration` @@ -248,7 +248,7 @@ should only be used where appropriate. [[mvc-cors-global-java]] === Java Configuration -[.small]#<># +[.small]#<># To enable CORS in the MVC Java config, you can use the `CorsRegistry` callback, as the following example shows: @@ -325,7 +325,7 @@ as the following example shows: [[mvc-cors-filter]] == CORS Filter -[.small]#<># +[.small]#<># You can apply CORS support through the built-in {api-spring-framework}/web/filter/CorsFilter.html[`CorsFilter`]. diff --git a/src/docs/asciidoc/web/webmvc-functional.adoc b/src/docs/asciidoc/web/webmvc-functional.adoc index 0df2d09d7c7..51d8b2b2b05 100644 --- a/src/docs/asciidoc/web/webmvc-functional.adoc +++ b/src/docs/asciidoc/web/webmvc-functional.adoc @@ -1,6 +1,6 @@ [[webmvc-fn]] = Functional Endpoints -[.small]#<># +[.small]#<># Spring Web MVC includes WebMvc.fn, a lightweight functional programming model in which functions are used to route and handle requests and contracts are designed for immutability. @@ -12,7 +12,7 @@ the same <>. [[webmvc-fn-overview]] == Overview -[.small]#<># +[.small]#<># In WebMvc.fn, an HTTP request is handled with a `HandlerFunction`: a function that takes `ServerRequest` and returns a `ServerResponse`. @@ -110,7 +110,7 @@ If you register the `RouterFunction` as a bean, for instance by exposing it in a [[webmvc-fn-handler-functions]] == HandlerFunction -[.small]#<># +[.small]#<># `ServerRequest` and `ServerResponse` are immutable interfaces that offer JDK 8-friendly access to the HTTP request and response, including headers, body, method, and status code. @@ -375,7 +375,7 @@ See <>. [[webmvc-fn-router-functions]] == `RouterFunction` -[.small]#<># +[.small]#<># Router functions are used to route the requests to the corresponding `HandlerFunction`. Typically, you do not write router functions yourself, but rather use a method on the @@ -581,7 +581,7 @@ We can further improve by using the `nest` method together with `accept`: [[webmvc-fn-running]] == Running a Server -[.small]#<># +[.small]#<># You typically run router functions in a <>-based setup through the <>, which uses Spring configuration to declare the @@ -674,7 +674,7 @@ The following example shows a WebFlux Java configuration: [[webmvc-fn-handler-filter-function]] == Filtering Handler Functions -[.small]#<># +[.small]#<># You can filter handler functions by using the `before`, `after`, or `filter` methods on the routing function builder. diff --git a/src/docs/asciidoc/web/webmvc-view.adoc b/src/docs/asciidoc/web/webmvc-view.adoc index c3e2571bcbf..92c4ce95504 100644 --- a/src/docs/asciidoc/web/webmvc-view.adoc +++ b/src/docs/asciidoc/web/webmvc-view.adoc @@ -1,6 +1,6 @@ [[mvc-view]] = View Technologies -[.small]#<># +[.small]#<># The use of view technologies in Spring MVC is pluggable, whether you decide to use Thymeleaf, Groovy Markup Templates, JSPs, or other technologies, is primarily a matter @@ -12,7 +12,7 @@ Spring MVC. We assume you are already familiar with <>. [[mvc-view-thymeleaf]] == Thymeleaf -[.small]#<># +[.small]#<># Thymeleaf is a modern server-side Java template engine that emphasizes natural HTML templates that can be previewed in a browser by double-clicking, which is very helpful @@ -32,7 +32,7 @@ See https://www.thymeleaf.org/documentation.html[Thymeleaf+Spring] for more deta [[mvc-view-freemarker]] == FreeMarker -[.small]#<># +[.small]#<># https://freemarker.apache.org/[Apache FreeMarker] is a template engine for generating any kind of text output from HTML to email and others. The Spring Framework has built-in @@ -42,7 +42,7 @@ integration for using Spring MVC with FreeMarker templates. [[mvc-view-freemarker-contextconfig]] === View Configuration -[.small]#<># +[.small]#<># The following example shows how to configure FreeMarker as a view technology: @@ -123,7 +123,7 @@ returns a view name of `welcome`, the resolver looks for the [[mvc-views-freemarker]] === FreeMarker Configuration -[.small]#<># +[.small]#<># You can pass FreeMarker 'Settings' and 'SharedVariables' directly to the FreeMarker `Configuration` object (which is managed by Spring) by setting the appropriate bean @@ -162,7 +162,7 @@ with additional convenience macros for generating form input elements themselves [[mvc-view-bind-macros]] ==== The Bind Macros -[.small]#<># +[.small]#<># A standard set of macros are maintained within the `spring-webmvc.jar` file for FreeMarker, so they are always available to a suitably configured application. @@ -574,7 +574,7 @@ syntax. The following example shows a sample template for an HTML page: [[mvc-view-script]] == Script Views -[.small]#<># +[.small]#<># The Spring Framework has a built-in integration for using Spring MVC with any templating library that can run on top of the @@ -600,7 +600,7 @@ TIP: The basic rule for integrating any other script engine is that it must impl [[mvc-view-script-dependencies]] === Requirements -[.small]#<># +[.small]#<># You need to have the script engine on your classpath, the details of which vary by script engine: @@ -620,7 +620,7 @@ through https://www.webjars.org/[WebJars]. [[mvc-view-script-integrate]] === Script Templates -[.small]#<># +[.small]#<># You can declare a `ScriptTemplateConfigurer` bean to specify the script engine to use, the script files to load, what function to call to render templates, and so on. @@ -2020,7 +2020,7 @@ an external definition (by name) or as a `View` instance from the handler method [[mvc-view-jackson]] == Jackson -[.small]#<># +[.small]#<># Spring offers support for the Jackson JSON library. @@ -2028,7 +2028,7 @@ Spring offers support for the Jackson JSON library. [[mvc-view-json-mapping]] === Jackson-based JSON MVC Views -[.small]#<># +[.small]#<># The `MappingJackson2JsonView` uses the Jackson library's `ObjectMapper` to render the response content as JSON. By default, the entire contents of the model map (with the exception of @@ -2047,7 +2047,7 @@ serializers and deserializers for specific types. [[mvc-view-xml-mapping]] === Jackson-based XML Views -[.small]#<># +[.small]#<># `MappingJackson2XmlView` uses the https://github.com/FasterXML/jackson-dataformat-xml[Jackson XML extension's] `XmlMapper` diff --git a/src/docs/asciidoc/web/webmvc.adoc b/src/docs/asciidoc/web/webmvc.adoc index 71909cf617d..41be1354b26 100644 --- a/src/docs/asciidoc/web/webmvc.adoc +++ b/src/docs/asciidoc/web/webmvc.adoc @@ -23,7 +23,7 @@ https://github.com/spring-projects/spring-framework/wiki/Spring-Framework-Versio [[mvc-servlet]] == DispatcherServlet -[.small]#<># +[.small]#<># Spring MVC, as many other web frameworks, is designed around the front controller pattern where a central `Servlet`, the `DispatcherServlet`, provides a shared algorithm @@ -237,7 +237,7 @@ TIP: If an application context hierarchy is not required, applications may confi [[mvc-servlet-special-bean-types]] === Special Bean Types -[.small]#<># +[.small]#<># The `DispatcherServlet` delegates to special beans to process requests and render the appropriate responses. By "`special beans`" we mean Spring-managed `Object` instances that @@ -297,7 +297,7 @@ The following table lists the special beans detected by the `DispatcherServlet`: [[mvc-servlet-config]] === Web MVC Config -[.small]#<># +[.small]#<># Applications can declare the infrastructure beans listed in <> that are required to process requests. The `DispatcherServlet` checks the @@ -500,7 +500,7 @@ override the `createDispatcherServlet` method. [[mvc-servlet-sequence]] === Processing -[.small]#<># +[.small]#<># The `DispatcherServlet` processes requests as follows: @@ -610,7 +610,7 @@ declare it as an <> bean or configure it directly on [[mvc-exceptionhandlers]] === Exceptions -[.small]#<># +[.small]#<># If an exception occurs during request mapping or is thrown from a request handler (such as a `@Controller`), the `DispatcherServlet` delegates to a chain of `HandlerExceptionResolver` @@ -721,7 +721,7 @@ however, use both a `WebApplicationInitializer` and a minimal `web.xml`. [[mvc-viewresolver]] === View Resolution -[.small]#<># +[.small]#<># Spring MVC defines the `ViewResolver` and `View` interfaces that let you render models in a browser without tying you to a specific view technology. `ViewResolver` @@ -779,7 +779,7 @@ The following table provides more details on the `ViewResolver` hierarchy: [[mvc-viewresolver-handling]] ==== Handling -[.small]#<># +[.small]#<># You can chain view resolvers by declaring more than one resolver bean and, if necessary, by setting the `order` property to specify ordering. Remember, the higher the order property, @@ -800,7 +800,7 @@ rendering without controller logic. [[mvc-redirecting-redirect-prefix]] ==== Redirecting -[.small]#<># +[.small]#<># The special `redirect:` prefix in a view name lets you perform a redirect. The `UrlBasedViewResolver` (and its subclasses) recognize this as an instruction that a @@ -830,7 +830,7 @@ Servlet/JSP engine. Note that you may also chain multiple view resolvers, instea [[mvc-multiple-representations]] ==== Content Negotiation -[.small]#<># +[.small]#<># {api-spring-framework}/web/servlet/view/ContentNegotiatingViewResolver.html[`ContentNegotiatingViewResolver`] does not resolve views itself but rather delegates @@ -1089,7 +1089,7 @@ request with a simple request parameter. [[mvc-multipart]] === Multipart Resolver -[.small]#<># +[.small]#<># `MultipartResolver` from the `org.springframework.web.multipart` package is a strategy for parsing multipart requests including file uploads. There is one implementation @@ -1162,7 +1162,7 @@ Once the Servlet 3.0 configuration is in place, you can add a bean of type [[mvc-logging]] === Logging -[.small]#<># +[.small]#<># DEBUG-level logging in Spring MVC is designed to be compact, minimal, and human-friendly. It focuses on high-value bits of information that are useful over and @@ -1178,7 +1178,7 @@ not meet the stated goals, please let us know. [[mvc-logging-sensitive-data]] ==== Sensitive Data -[.small]#<># +[.small]#<># DEBUG and TRACE logging may log sensitive information. This is why request parameters and headers are masked by default and their logging in full must be enabled explicitly @@ -1242,7 +1242,7 @@ public class MyInitializer [[filters]] == Filters -[.small]#<># +[.small]#<># The `spring-web` module provides some useful filters: @@ -1269,7 +1269,7 @@ available through the `ServletRequest.getParameter{asterisk}()` family of method [[filters-forwarded-headers]] === Forwarded Headers -[.small]#<># +[.small]#<># As a request goes through proxies (such as load balancers) the host, port, and scheme may change, and that makes it a challenge to create links that point to the correct @@ -1330,7 +1330,7 @@ the filter via `web.xml` or in Spring Boot via a `FilterRegistrationBean` be sur [[filters-cors]] === CORS -[.small]#<># +[.small]#<># Spring MVC provides fine-grained support for CORS configuration through annotations on controllers. However, when used with Spring Security, we advise relying on the built-in @@ -1343,7 +1343,7 @@ See the sections on <> and the <> for more details. [[mvc-controller]] == Annotated Controllers -[.small]#<># +[.small]#<># Spring MVC provides an annotation-based programming model where `@Controller` and `@RestController` components use annotations to express request mappings, request input, @@ -1390,7 +1390,7 @@ programming model described in this section. [[mvc-ann-controller]] === Declaration -[.small]#<># +[.small]#<># You can define controller beans by using a standard Spring bean definition in the Servlet's `WebApplicationContext`. The `@Controller` stereotype allows for auto-detection, @@ -1468,7 +1468,7 @@ change to ``, and with [[mvc-ann-requestmapping]] === Request Mapping -[.small]#<># +[.small]#<># You can use the `@RequestMapping` annotation to map requests to controllers methods. It has various attributes to match by URL, HTTP method, request parameters, headers, and media @@ -1533,7 +1533,7 @@ The following example has type and method level mappings: [[mvc-ann-requestmapping-uri-templates]] ==== URI patterns -[.small]#<># +[.small]#<># You can map requests by using the following global patterns and wildcards: @@ -1633,7 +1633,7 @@ NOTE: Spring MVC uses the `PathMatcher` contract and the `AntPathMatcher` implem [[mvc-ann-requestmapping-pattern-comparison]] ==== Pattern Comparison -[.small]#<># +[.small]#<># When multiple patterns match a URL, they must be compared to find the best match. This is done by using `AntPathMatcher.getPatternComparator(String path)`, which looks for patterns that are more @@ -1714,7 +1714,7 @@ recommendations related to RFD. [[mvc-ann-requestmapping-consumes]] ==== Consumable Media Types -[.small]#<># +[.small]#<># You can narrow the request mapping based on the `Content-Type` of the request, as the following example shows: @@ -1752,7 +1752,7 @@ TIP: `MediaType` provides constants for commonly used media types, such as [[mvc-ann-requestmapping-produces]] ==== Producible Media Types -[.small]#<># +[.small]#<># You can narrow the request mapping based on the `Accept` request header and the list of content types that a controller method produces, as the following example shows: @@ -1792,7 +1792,7 @@ TIP: `MediaType` provides constants for commonly used media types, such as [[mvc-ann-requestmapping-params-and-headers]] ==== Parameters, headers -[.small]#<># +[.small]#<># You can narrow request mappings based on request parameter conditions. You can test for the presence of a request parameter (`myParam`), for the absence of one (`!myParam`), or for a @@ -1846,7 +1846,7 @@ instead. [[mvc-ann-requestmapping-head-options]] ==== HTTP HEAD, OPTIONS -[.small]#<># +[.small]#<># `@GetMapping` (and `@RequestMapping(method=HttpMethod.GET)`) support HTTP HEAD transparently for request mapping. Controller methods do not need to change. @@ -1872,7 +1872,7 @@ is not necessary in the common case. [[mvc-ann-requestmapping-composed]] ==== Custom Annotations -[.small]#<># +[.small]#<># Spring MVC supports the use of <> for request mapping. Those are annotations that are themselves meta-annotated with @@ -1893,7 +1893,7 @@ you can check the custom attribute and return your own `RequestCondition`. [[mvc-ann-requestmapping-registration]] ==== Explicit Registrations -[.small]#<># +[.small]#<># You can programmatically register handler methods, which you can use for dynamic registrations or for advanced cases, such as different instances of the same handler @@ -1946,7 +1946,7 @@ under different URLs. The following example registers a handler method: [[mvc-ann-methods]] === Handler Methods -[.small]#<># +[.small]#<># `@RequestMapping` handler methods have a flexible signature and can choose from a range of supported controller method arguments and return values. @@ -1954,7 +1954,7 @@ supported controller method arguments and return values. [[mvc-ann-arguments]] ==== Method Arguments -[.small]#<># +[.small]#<># The next table describes the supported controller method arguments. Reactive types are not supported for any arguments. @@ -2089,7 +2089,7 @@ and others) and is equivalent to `required=false`. [[mvc-ann-return-types]] ==== Return Values -[.small]#<># +[.small]#<># The next table describes the supported controller method return values. Reactive types are supported for all return values. @@ -2190,7 +2190,7 @@ supported for all return values. [[mvc-ann-typeconversion]] ==== Type Conversion -[.small]#<># +[.small]#<># Some annotated controller method arguments that represent `String`-based request input (such as `@RequestParam`, `@RequestHeader`, `@PathVariable`, `@MatrixVariable`, and `@CookieValue`) @@ -2205,7 +2205,7 @@ See <>. [[mvc-ann-matrix-variables]] ==== Matrix Variables -[.small]#<># +[.small]#<># https://tools.ietf.org/html/rfc3986#section-3.3[RFC 3986] discusses name-value pairs in path segments. In Spring MVC, we refer to those as "`matrix variables`" based on an @@ -2345,7 +2345,7 @@ you need to set a `UrlPathHelper` with `removeSemicolonContent=false` through [[mvc-ann-requestparam]] ==== `@RequestParam` -[.small]#<># +[.small]#<># You can use the `@RequestParam` annotation to bind Servlet request parameters (that is, query parameters or form data) to a method argument in a controller. @@ -2421,7 +2421,7 @@ with `@RequestParam`. [[mvc-ann-requestheader]] ==== `@RequestHeader` -[.small]#<># +[.small]#<># You can use the `@RequestHeader` annotation to bind a request header to a method argument in a controller. @@ -2482,7 +2482,7 @@ example, a method parameter annotated with `@RequestHeader("Accept")` can be of [[mvc-ann-cookievalue]] ==== `@CookieValue` -[.small]#<># +[.small]#<># You can use the `@CookieValue` annotation to bind the value of an HTTP cookie to a method argument in a controller. @@ -2522,7 +2522,7 @@ See <>. [[mvc-ann-modelattrib-method-args]] ==== `@ModelAttribute` -[.small]#<># +[.small]#<># You can use the `@ModelAttribute` annotation on a method argument to access an attribute from the model or have it be instantiated if not present. The model attribute is also overlain with @@ -2701,7 +2701,7 @@ with `@ModelAttribute`. [[mvc-ann-sessionattributes]] ==== `@SessionAttributes` -[.small]#<># +[.small]#<># `@SessionAttributes` is used to store model attributes in the HTTP Servlet session between requests. It is a type-level annotation that declares the session attributes used by a @@ -2786,7 +2786,7 @@ class EditPetForm { [[mvc-ann-sessionattribute]] ==== `@SessionAttribute` -[.small]#<># +[.small]#<># If you need access to pre-existing session attributes that are managed globally (that is, outside the controller -- for example, by a filter) and may or may not be present, @@ -2823,7 +2823,7 @@ workflow, consider using `@SessionAttributes` as described in [[mvc-ann-requestattrib]] ==== `@RequestAttribute` -[.small]#<># +[.small]#<># Similar to `@SessionAttribute`, you can use the `@RequestAttribute` annotations to access pre-existing request attributes created earlier (for example, by a Servlet `Filter` @@ -2950,7 +2950,7 @@ Therefore, we recommend that you use flash attributes mainly for redirect scenar [[mvc-multipart-forms]] ==== Multipart -[.small]#<># +[.small]#<># After a `MultipartResolver` has been <>, the content of POST requests with `multipart/form-data` is parsed and accessible as regular request @@ -3135,7 +3135,7 @@ as the following example shows: [[mvc-ann-requestbody]] ==== `@RequestBody` -[.small]#<># +[.small]#<># You can use the `@RequestBody` annotation to have the request body read and deserialized into an `Object` through an <>. @@ -3189,7 +3189,7 @@ as the following example shows: [[mvc-ann-httpentity]] ==== HttpEntity -[.small]#<># +[.small]#<># `HttpEntity` is more or less identical to using <> but is based on a container object that exposes request headers and body. The following listing shows an example: @@ -3215,7 +3215,7 @@ container object that exposes request headers and body. The following listing sh [[mvc-ann-responsebody]] ==== `@ResponseBody` -[.small]#<># +[.small]#<># You can use the `@ResponseBody` annotation on a method to have the return serialized to the response body through an @@ -3257,7 +3257,7 @@ See <> for details. [[mvc-ann-responseentity]] ==== ResponseEntity -[.small]#<># +[.small]#<># `ResponseEntity` is like <> but with status and headers. For example: @@ -3294,7 +3294,7 @@ Spring offers support for the Jackson JSON library. [[mvc-ann-jsonview]] ===== JSON Views -[.small]#<># +[.small]#<># Spring MVC provides built-in support for https://www.baeldung.com/jackson-json-view-annotation[Jackson's Serialization Views], @@ -3403,7 +3403,7 @@ to the model, as the following example shows: [[mvc-ann-modelattrib-methods]] === Model -[.small]#<># +[.small]#<># You can use the `@ModelAttribute` annotation: @@ -3501,7 +3501,7 @@ unless the return value is a `String` that would otherwise be interpreted as a v [[mvc-ann-initbinder]] === `DataBinder` -[.small]#<># +[.small]#<># `@Controller` or `@ControllerAdvice` classes can have `@InitBinder` methods that initialize instances of `WebDataBinder`, and those, in turn, can: @@ -3595,7 +3595,7 @@ controller-specific `Formatter` implementations, as the following example shows: [[mvc-ann-exceptionhandler]] === Exceptions -[.small]#<># +[.small]#<># `@Controller` and <> classes can have `@ExceptionHandler` methods to handle exceptions from controller methods, as the following example shows: @@ -3844,7 +3844,7 @@ level, <> mechanism. [[mvc-ann-rest-exceptions]] ==== REST API exceptions -[.small]#<># +[.small]#<># A common requirement for REST services is to include error details in the body of the response. The Spring Framework does not automatically do this because the representation @@ -3865,7 +3865,7 @@ necessary methods, and declare it as a Spring bean. [[mvc-ann-controller-advice]] === Controller Advice -[.small]#<># +[.small]#<># Typically `@ExceptionHandler`, `@InitBinder`, and `@ModelAttribute` methods apply within the `@Controller` class (or class hierarchy) in which they are declared. If you want such @@ -3931,7 +3931,7 @@ include::webmvc-functional.adoc[leveloffset=+1] [[mvc-uri-building]] == URI Links -[.small]#<># +[.small]#<># This section describes various options available in the Spring Framework to work with URI's. @@ -4400,7 +4400,7 @@ Spring WebFlux does support all that. [[mvc-ann-async-http-streaming]] === HTTP Streaming -[.small]#<># +[.small]#<># You can use `DeferredResult` and `Callable` for a single asynchronous return value. What if you want to produce multiple asynchronous values and have those written to the @@ -4553,7 +4553,7 @@ customize the status and headers of the response. [[mvc-ann-async-reactive-types]] === Reactive Types -[.small]#<># +[.small]#<># Spring MVC supports use of reactive client libraries in a controller (also read <> in the WebFlux section). @@ -4588,7 +4588,7 @@ suitable under load. If you plan to stream with a reactive type, you should use [[mvc-ann-async-disconnects]] === Disconnects -[.small]#<># +[.small]#<># The Servlet API does not provide any notification when a remote client goes away. Therefore, while streaming to the response, whether through <> @@ -4656,7 +4656,7 @@ include::webmvc-cors.adoc[leveloffset=+1] [[mvc-web-security]] == Web Security -[.small]#<># +[.small]#<># The https://projects.spring.io/spring-security/[Spring Security] project provides support for protecting web applications from malicious exploits. See the Spring Security @@ -4674,7 +4674,7 @@ https://hdiv.org/[HDIV] is another web security framework that integrates with S [[mvc-caching]] == HTTP Caching -[.small]#<># +[.small]#<># HTTP caching can significantly improve the performance of a web application. HTTP caching revolves around the `Cache-Control` response header and, subsequently, conditional request @@ -4690,7 +4690,7 @@ This section describes the HTTP caching-related options that are available in Sp [[mvc-caching-cachecontrol]] === `CacheControl` -[.small]#<># +[.small]#<># {api-spring-framework}/http/CacheControl.html[`CacheControl`] provides support for configuring settings related to the `Cache-Control` header and is accepted as an argument @@ -4746,7 +4746,7 @@ works as follows: [[mvc-caching-etag-lastmodified]] === Controllers -[.small]#<># +[.small]#<># Controllers can add explicit support for HTTP caching. We recommended doing so, since the `lastModified` or `ETag` value for a resource needs to be calculated before it can be compared @@ -4843,7 +4843,7 @@ to 412 (PRECONDITION_FAILED), to prevent concurrent modification. [[mvc-caching-static-resources]] === Static Resources -[.small]#<># +[.small]#<># You should serve static resources with a `Cache-Control` and conditional response headers for optimal performance. See the section on configuring <>. @@ -4863,7 +4863,7 @@ include::webmvc-view.adoc[leveloffset=+1] [[mvc-config]] == MVC Config -[.small]#<># +[.small]#<># The MVC Java configuration and the MVC XML namespace provide default configuration suitable for most applications and a configuration API to customize it. @@ -4879,7 +4879,7 @@ and <>. [[mvc-config-enable]] === Enable MVC Configuration -[.small]#<># +[.small]#<># In Java configuration, you can use the `@EnableWebMvc` annotation to enable MVC configuration, as the following example shows: @@ -4928,7 +4928,7 @@ available on the classpath (for example, payload converters for JSON, XML, and o [[mvc-config-customize]] === MVC Config API -[.small]#<># +[.small]#<># In Java configuration, you can implement the `WebMvcConfigurer` interface, as the following example shows: @@ -4963,7 +4963,7 @@ sub-elements are available. [[mvc-config-conversion]] === Type Conversion -[.small]#<># +[.small]#<># By default formatters, for `Number` and `Date` types are installed, including support for the `@NumberFormat` and `@DateTimeFormat` annotations. Full support for the Joda-Time @@ -5045,7 +5045,7 @@ FormatterRegistrar implementations. [[mvc-config-validation]] === Validation -[.small]#<># +[.small]#<># By default, if <> is present on the classpath (for example, Hibernate Validator), the `LocalValidatorFactoryBean` is @@ -5191,7 +5191,7 @@ The following example shows how to achieve the same configuration in XML: [[mvc-config-content-negotiation]] === Content Types -[.small]#<># +[.small]#<># You can configure how Spring MVC determines the requested media types from the request (for example, `Accept` header, URL path extension, query parameter, and others). @@ -5257,7 +5257,7 @@ The following example shows how to achieve the same configuration in XML: [[mvc-config-message-converters]] === Message Converters -[.small]#<># +[.small]#<># You can customize `HttpMessageConverter` in Java configuration by overriding {api-spring-framework}/web/servlet/config/annotation/WebMvcConfigurer.html#configureMessageConverters-java.util.List-[`configureMessageConverters()`] @@ -5403,7 +5403,7 @@ using the `` element: [[mvc-config-view-resolvers]] === View Resolvers -[.small]#<># +[.small]#<># The MVC configuration simplifies the registration of view resolvers. @@ -5523,7 +5523,7 @@ as the following example shows: [[mvc-config-static-resources]] === Static Resources -[.small]#<># +[.small]#<># This option provides a convenient way to serve static resources from a list of {api-spring-framework}/core/io/Resource.html[`Resource`]-based locations. @@ -5754,7 +5754,7 @@ The following example shows how to achieve the same configuration in XML: [[mvc-config-path-matching]] === Path Matching -[.small]#<># +[.small]#<># You can customize options related to path matching and treatment of the URL. For details on the individual options, see the @@ -5843,7 +5843,7 @@ The following example shows how to achieve the same configuration in XML: [[mvc-config-advanced-java]] === Advanced Java Config -[.small]#<># +[.small]#<># `@EnableWebMvc` imports `DelegatingWebMvcConfiguration`, which: @@ -5918,7 +5918,7 @@ by letting it be detected through a `` declaration. [[mvc-http2]] == HTTP/2 -[.small]#<># +[.small]#<># Servlet 4 containers are required to support HTTP/2, and Spring Framework 5 is compatible with Servlet API 4. From a programming model perspective, there is nothing specific that diff --git a/src/docs/asciidoc/web/websocket.adoc b/src/docs/asciidoc/web/websocket.adoc index ca9dfa19b11..feaebc0d3cc 100644 --- a/src/docs/asciidoc/web/websocket.adoc +++ b/src/docs/asciidoc/web/websocket.adoc @@ -1,7 +1,7 @@ [[websocket]] = WebSockets :doc-spring-security: {doc-root}/spring-security/site/docs/current/reference -[.small]#<># +[.small]#<># This part of the reference documentation covers support for Servlet stack, WebSocket messaging that includes raw WebSocket interactions, WebSocket emulation through SockJS, and @@ -14,7 +14,7 @@ include::websocket-intro.adoc[leveloffset=+1] [[websocket-server]] == WebSocket API -[.small]#<># +[.small]#<># The Spring Framework provides a WebSocket API that you can use to write client- and server-side applications that handle WebSocket messages. @@ -23,7 +23,7 @@ server-side applications that handle WebSocket messages. [[websocket-server-handler]] === `WebSocketHandler` -[.small]#<># +[.small]#<># Creating a WebSocket server is as simple as implementing `WebSocketHandler` or, more likely, extending either `TextWebSocketHandler` or `BinaryWebSocketHandler`. The following @@ -112,7 +112,7 @@ sending. One option is to wrap the `WebSocketSession` with [[websocket-server-handshake]] === WebSocket Handshake -[.small]#<># +[.small]#<># The easiest way to customize the initial HTTP WebSocket handshake request is through a `HandshakeInterceptor`, which exposes methods for "`before`" and "`after`" the handshake. @@ -258,7 +258,7 @@ Java initialization API. The following example shows how to do so: [[websocket-server-runtime-configuration]] === Server Configuration -[.small]#<># +[.small]#<># Each underlying WebSocket engine exposes configuration properties that control runtime characteristics, such as the size of message buffer sizes, idle timeout, @@ -385,7 +385,7 @@ The following example shows the XML configuration equivalent of the preceding ex [[websocket-server-allowed-origins]] === Allowed Origins -[.small]#<># +[.small]#<># As of Spring Framework 4.1.5, the default behavior for WebSocket and SockJS is to accept only same-origin requests. It is also possible to allow all or a specified list of origins.