From 11f3edc352bbc182418a45e1b7b0c7827d359228 Mon Sep 17 00:00:00 2001 From: Sam Brannen Date: Sat, 17 Dec 2022 13:39:47 +0100 Subject: [PATCH] Change plain 'WebFlux' links to 'See equivalent in the Reactive stack' Closes gh-29694 --- .../asciidoc/integration/rest-clients.adoc | 2 +- .../docs/asciidoc/web/webflux-websocket.adoc | 12 +- .../src/docs/asciidoc/web/webmvc-cors.adoc | 14 +- .../docs/asciidoc/web/webmvc-functional.adoc | 12 +- .../src/docs/asciidoc/web/webmvc-test.adoc | 2 +- .../src/docs/asciidoc/web/webmvc-view.adoc | 24 +-- .../src/docs/asciidoc/web/webmvc.adoc | 156 +++++++++--------- .../src/docs/asciidoc/web/websocket.adoc | 12 +- 8 files changed, 117 insertions(+), 117 deletions(-) diff --git a/framework-docs/src/docs/asciidoc/integration/rest-clients.adoc b/framework-docs/src/docs/asciidoc/integration/rest-clients.adoc index 44dc60cd9b..575f1593e4 100644 --- a/framework-docs/src/docs/asciidoc/integration/rest-clients.adoc +++ b/framework-docs/src/docs/asciidoc/integration/rest-clients.adoc @@ -215,7 +215,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/framework-docs/src/docs/asciidoc/web/webflux-websocket.adoc b/framework-docs/src/docs/asciidoc/web/webflux-websocket.adoc index a1fbd2a32e..d3644cf654 100644 --- a/framework-docs/src/docs/asciidoc/web/webflux-websocket.adoc +++ b/framework-docs/src/docs/asciidoc/web/webflux-websocket.adoc @@ -1,6 +1,6 @@ [[webflux-websocket]] = WebSockets -[.small]#<># +[.small]#<># This part of the reference documentation covers support for reactive-stack WebSocket messaging. @@ -12,7 +12,7 @@ include::websocket-intro.adoc[leveloffset=+1] [[webflux-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. @@ -21,7 +21,7 @@ server-side applications that handle WebSocket messages. [[webflux-websocket-server-handler]] === Server -[.small]#<># +[.small]#<># To create a WebSocket server, you can first create a `WebSocketHandler`. The following example shows how to do so: @@ -339,7 +339,7 @@ subsequently use `DataBufferUtils.release(dataBuffer)` when the buffers are cons [[webflux-websocket-server-handshake]] === Handshake -[.small]#<># +[.small]#<># `WebSocketHandlerAdapter` delegates to a `WebSocketService`. By default, that is an instance of `HandshakeWebSocketService`, which performs basic checks on the WebSocket request and @@ -354,7 +354,7 @@ into the attributes of the `WebSocketSession`. [[webflux-websocket-server-config]] === Server Configuration -[.small]#<># +[.small]#<># The `RequestUpgradeStrategy` for each server exposes configuration specific to the underlying WebSocket server engine. When using the WebFlux Java config you can customize @@ -408,7 +408,7 @@ only Tomcat and Jetty expose such options. [[webflux-websocket-server-cors]] === CORS -[.small]#<># +[.small]#<># The easiest way to configure CORS and restrict access to a WebSocket endpoint is to have your `WebSocketHandler` implement `CorsConfigurationSource` and return a diff --git a/framework-docs/src/docs/asciidoc/web/webmvc-cors.adoc b/framework-docs/src/docs/asciidoc/web/webmvc-cors.adoc index 1c2be4c266..d5a3334a96 100644 --- a/framework-docs/src/docs/asciidoc/web/webmvc-cors.adoc +++ b/framework-docs/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, @@ -226,7 +226,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` @@ -252,7 +252,7 @@ the `allowOriginPatterns` property may be used to match to a dynamic set of orig [[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: @@ -329,7 +329,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/framework-docs/src/docs/asciidoc/web/webmvc-functional.adoc b/framework-docs/src/docs/asciidoc/web/webmvc-functional.adoc index 83ea766ab5..8769048368 100644 --- a/framework-docs/src/docs/asciidoc/web/webmvc-functional.adoc +++ b/framework-docs/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`. @@ -111,7 +111,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. @@ -463,7 +463,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 @@ -672,7 +672,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 @@ -765,7 +765,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/framework-docs/src/docs/asciidoc/web/webmvc-test.adoc b/framework-docs/src/docs/asciidoc/web/webmvc-test.adoc index 87b6a53874..b4584d84a8 100644 --- a/framework-docs/src/docs/asciidoc/web/webmvc-test.adoc +++ b/framework-docs/src/docs/asciidoc/web/webmvc-test.adoc @@ -1,6 +1,6 @@ [[webmvc.test]] = Testing -[.small]#<># +[.small]#<># This section summarizes the options available in `spring-test` for Spring MVC applications. diff --git a/framework-docs/src/docs/asciidoc/web/webmvc-view.adoc b/framework-docs/src/docs/asciidoc/web/webmvc-view.adoc index b0725de35d..6e8ce83734 100644 --- a/framework-docs/src/docs/asciidoc/web/webmvc-view.adoc +++ b/framework-docs/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 of @@ -14,7 +14,7 @@ the templates are editable by external sources, since this can have security imp [[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 @@ -34,7 +34,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 @@ -44,7 +44,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: @@ -125,7 +125,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 @@ -164,7 +164,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. @@ -576,7 +576,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 @@ -602,7 +602,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: @@ -622,7 +622,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. @@ -1965,7 +1965,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. @@ -1973,7 +1973,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 @@ -1992,7 +1992,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/framework-docs/src/docs/asciidoc/web/webmvc.adoc b/framework-docs/src/docs/asciidoc/web/webmvc.adoc index be84a97bfd..4bf1d8f69f 100644 --- a/framework-docs/src/docs/asciidoc/web/webmvc.adoc +++ b/framework-docs/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 @@ -240,7 +240,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 @@ -300,7 +300,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 @@ -503,7 +503,7 @@ override the `createDispatcherServlet` method. [[mvc-servlet-sequence]] === Processing -[.small]#<># +[.small]#<># The `DispatcherServlet` processes requests as follows: @@ -662,7 +662,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` @@ -773,7 +773,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` @@ -825,7 +825,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, @@ -846,7 +846,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 @@ -876,7 +876,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 @@ -1138,7 +1138,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 a container-based @@ -1214,7 +1214,7 @@ javadoc for details and configuration options. [[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 @@ -1230,7 +1230,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 @@ -1294,7 +1294,7 @@ public class MyInitializer [[filters]] == Filters -[.small]#<># +[.small]#<># The `spring-web` module provides some useful filters: @@ -1321,7 +1321,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 @@ -1382,7 +1382,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 @@ -1395,7 +1395,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, @@ -1442,7 +1442,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, @@ -1504,7 +1504,7 @@ directly to the response body versus view resolution and rendering with an HTML [[mvc-ann-requestmapping-proxying]] ==== AOP Proxies -[.small]#<># +[.small]#<># In some cases, you may need to decorate a controller with an AOP proxy at runtime. One example is if you choose to have `@Transactional` annotations directly on the @@ -1526,7 +1526,7 @@ Please, enable class based proxying, or otherwise the interface must also have a [[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 @@ -1591,7 +1591,7 @@ The following example has type and method level mappings: [[mvc-ann-requestmapping-uri-templates]] ==== URI patterns -[.small]#<># +[.small]#<># `@RequestMapping` methods can be mapped using URL patterns. There are two alternatives: @@ -1713,7 +1713,7 @@ some external configuration. [[mvc-ann-requestmapping-pattern-comparison]] ==== Pattern Comparison -[.small]#<># +[.small]#<># When multiple patterns match a URL, the best match must be selected. This is done with one of the following depending on whether use of parsed `PathPattern` is enabled for use or not: @@ -1794,7 +1794,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: @@ -1832,7 +1832,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: @@ -1872,7 +1872,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 @@ -1927,7 +1927,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. @@ -1953,7 +1953,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 @@ -1974,7 +1974,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 @@ -2027,7 +2027,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. @@ -2035,7 +2035,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. @@ -2176,7 +2176,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. @@ -2280,7 +2280,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`) @@ -2313,7 +2313,7 @@ an empty original value, so the corresponding `Missing...Exception` variants wil [[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 @@ -2453,7 +2453,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. @@ -2529,7 +2529,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. @@ -2590,7 +2590,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. @@ -2630,7 +2630,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 @@ -2823,7 +2823,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 @@ -2907,7 +2907,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, @@ -2945,7 +2945,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` @@ -3072,7 +3072,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 @@ -3257,7 +3257,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 <>. @@ -3311,7 +3311,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: @@ -3337,7 +3337,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 @@ -3379,7 +3379,7 @@ See <> for details. [[mvc-ann-responseentity]] ==== ResponseEntity -[.small]#<># +[.small]#<># `ResponseEntity` is like <> but with status and headers. For example: @@ -3423,7 +3423,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], @@ -3563,7 +3563,7 @@ to the model, as the following example shows: [[mvc-ann-modelattrib-methods]] === Model -[.small]#<># +[.small]#<># You can use the `@ModelAttribute` annotation: @@ -3661,7 +3661,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: @@ -3755,14 +3755,14 @@ controller-specific `Formatter` implementations, as the following example shows: [[mvc-ann-initbinder-model-design]] ==== Model Design -[.small]#<># +[.small]#<># include::web-data-binding-model-design.adoc[] [[mvc-ann-exceptionhandler]] === Exceptions -[.small]#<># +[.small]#<># `@Controller` and <> classes can have `@ExceptionHandler` methods to handle exceptions from controller methods, as the following example shows: @@ -3888,7 +3888,7 @@ level, <> mechanism. [[mvc-ann-exceptionhandler-args]] ==== Method Arguments -[.small]#<># +[.small]#<># `@ExceptionHandler` methods support the following arguments: @@ -3953,7 +3953,7 @@ level, <> mechanism. [[mvc-ann-exceptionhandler-return-values]] ==== Return Values -[.small]#<># +[.small]#<># `@ExceptionHandler` methods support the following return values: @@ -4023,7 +4023,7 @@ see <> [[mvc-ann-controller-advice]] === Controller Advice -[.small]#<># +[.small]#<># `@ExceptionHandler`, `@InitBinder`, and `@ModelAttribute` methods apply only to the `@Controller` class, or class hierarchy, in which they are declared. If, instead, they @@ -4087,7 +4087,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. @@ -4562,7 +4562,7 @@ Finally, from a configuration perspective the asynchronous request processing fe [[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 @@ -4715,7 +4715,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). @@ -4790,7 +4790,7 @@ Propagation library. [[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 <> @@ -4856,7 +4856,7 @@ include::webmvc-cors.adoc[leveloffset=+1] [[mvc-ann-rest-exceptions]] == Error Responses -[.small]#<># +[.small]#<># A common requirement for REST services is to include details in the body of error responses. The Spring Framework supports the "Problem Details for HTTP APIs" @@ -4880,7 +4880,7 @@ and any `ErrorResponseException`, and renders an error response with a body. [[mvc-ann-rest-exceptions-render]] === Render -[.small]#<># +[.small]#<># You can return `ProblemDetail` or `ErrorResponse` from any `@ExceptionHandler` or from any `@RequestMapping` method to render an RFC 7807 response. This is processed as follows: @@ -4903,7 +4903,7 @@ use a protected method to map any exception to a `ProblemDetail`. [[mvc-ann-rest-exceptions-non-standard]] === Non-Standard Fields -[.small]#<># +[.small]#<># You can extend an RFC 7807 response with non-standard fields in one of two ways. @@ -4923,7 +4923,7 @@ from an existing `ProblemDetail`. This could be done centrally, e.g. from an [[mvc-ann-rest-exceptions-i18n]] === Internationalization -[.small]#<># +[.small]#<># It is a common requirement to internationalize error response details, and good practice to customize the problem details for Spring MVC exceptions. This is supported as follows: @@ -5033,7 +5033,7 @@ qualified exception class name. [[mvc-ann-rest-exceptions-client]] === Client Handling -[.small]#<># +[.small]#<># A client application can catch `WebClientResponseException`, when using the `WebClient`, or `RestClientResponseException` when using the `RestTemplate`, and use their @@ -5044,7 +5044,7 @@ or `RestClientResponseException` when using the `RestTemplate`, and use their [[mvc-web-security]] == Web Security -[.small]#<># +[.small]#<># The https://spring.io/projects/spring-security[Spring Security] project provides support for protecting web applications from malicious exploits. See the Spring Security @@ -5062,7 +5062,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 @@ -5078,7 +5078,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 @@ -5134,7 +5134,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 @@ -5235,7 +5235,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 <>. @@ -5255,7 +5255,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. @@ -5271,7 +5271,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: @@ -5320,7 +5320,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: @@ -5356,7 +5356,7 @@ sub-elements are available. [[mvc-config-conversion]] === Type Conversion -[.small]#<># +[.small]#<># By default, formatters for various number and date types are installed, along with support for customization via `@NumberFormat` and `@DateTimeFormat` on fields. @@ -5471,7 +5471,7 @@ FormatterRegistrar implementations. [[mvc-config-validation]] === Validation -[.small]#<># +[.small]#<># By default, if <> is present on the classpath (for example, Hibernate Validator), the `LocalValidatorFactoryBean` is @@ -5621,7 +5621,7 @@ unwanted characters in URL paths. [[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). @@ -5685,7 +5685,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()`] @@ -5838,7 +5838,7 @@ splitting URL handling across an annotated controller and a view controller. [[mvc-config-view-resolvers]] === View Resolvers -[.small]#<># +[.small]#<># The MVC configuration simplifies the registration of view resolvers. @@ -5956,7 +5956,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. @@ -6196,7 +6196,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 @@ -6256,7 +6256,7 @@ The following example shows how to customize path matching in XML configuration: [[mvc-config-advanced-java]] === Advanced Java Config -[.small]#<># +[.small]#<># `@EnableWebMvc` imports `DelegatingWebMvcConfiguration`, which: @@ -6331,7 +6331,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/framework-docs/src/docs/asciidoc/web/websocket.adoc b/framework-docs/src/docs/asciidoc/web/websocket.adoc index 16298cf136..48832aa3f3 100644 --- a/framework-docs/src/docs/asciidoc/web/websocket.adoc +++ b/framework-docs/src/docs/asciidoc/web/websocket.adoc @@ -1,6 +1,6 @@ [[websocket]] = WebSockets -[.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 @@ -13,7 +13,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. @@ -22,7 +22,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 @@ -108,7 +108,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. @@ -242,7 +242,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, @@ -365,7 +365,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.