(window.webpackJsonp=window.webpackJsonp||[]).push([[100],{529:function(e,t,a){"use strict";a.r(t);var n=a(56),r=Object(n.a)({},(function(){var e=this,t=e.$createElement,a=e._self._c||t;return a("ContentSlotsDistributor",{attrs:{"slot-key":e.$parent.slotKey}},[a("h1",{attrs:{id:"web-on-reactive-stack"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#web-on-reactive-stack"}},[e._v("#")]),e._v(" Web on Reactive Stack")]),e._v(" "),a("p",[e._v("This part of the documentation covers support for reactive-stack web applications built\non a "),a("a",{attrs:{href:"https://www.reactive-streams.org/",target:"_blank",rel:"noopener noreferrer"}},[e._v("Reactive Streams"),a("OutboundLink")],1),e._v(" API to run on non-blocking\nservers, such as Netty, Undertow, and Servlet 3.1+ containers. Individual chapters cover\nthe "),a("RouterLink",{attrs:{to:"/en/spring-framework/webflux.html#webflux"}},[e._v("Spring WebFlux")]),e._v(" framework,\nthe reactive "),a("a",{attrs:{href:"#webflux-client"}},[a("code",[e._v("WebClient")])]),e._v(", support for "),a("a",{attrs:{href:"#webflux-test"}},[e._v("testing")]),e._v(",\nand "),a("a",{attrs:{href:"#webflux-reactive-libraries"}},[e._v("reactive libraries")]),e._v(". For Servlet-stack web applications,\nsee "),a("RouterLink",{attrs:{to:"/en/spring-framework/web.html#spring-web"}},[e._v("Web on Servlet Stack")]),e._v(".")],1),e._v(" "),a("h2",{attrs:{id:"_1-spring-webflux"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_1-spring-webflux"}},[e._v("#")]),e._v(" 1. Spring WebFlux")]),e._v(" "),a("p",[e._v("The original web framework included in the Spring Framework, Spring Web MVC, was\npurpose-built for the Servlet API and Servlet containers. The reactive-stack web framework,\nSpring WebFlux, was added later in version 5.0. It is fully non-blocking, supports"),a("a",{attrs:{href:"https://www.reactive-streams.org/",target:"_blank",rel:"noopener noreferrer"}},[e._v("Reactive Streams"),a("OutboundLink")],1),e._v(" back pressure, and runs on such servers as\nNetty, Undertow, and Servlet 3.1+ containers.")]),e._v(" "),a("p",[e._v("Both web frameworks mirror the names of their source modules\n("),a("a",{attrs:{href:"https://github.com/spring-projects/spring-framework/tree/main/spring-webmvc",target:"_blank",rel:"noopener noreferrer"}},[e._v("spring-webmvc"),a("OutboundLink")],1),e._v(" and"),a("a",{attrs:{href:"https://github.com/spring-projects/spring-framework/tree/main/spring-webflux",target:"_blank",rel:"noopener noreferrer"}},[e._v("spring-webflux"),a("OutboundLink")],1),e._v(") and co-exist side by side in the\nSpring Framework. Each module is optional. Applications can use one or the other module or,\nin some cases, both — for example, Spring MVC controllers with the reactive "),a("code",[e._v("WebClient")]),e._v(".")]),e._v(" "),a("h3",{attrs:{id:"_1-1-overview"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_1-1-overview"}},[e._v("#")]),e._v(" 1.1. Overview")]),e._v(" "),a("p",[e._v("Why was Spring WebFlux created?")]),e._v(" "),a("p",[e._v("Part of the answer is the need for a non-blocking web stack to handle concurrency with a\nsmall number of threads and scale with fewer hardware resources. Servlet 3.1 did provide\nan API for non-blocking I/O. However, using it leads away from the rest of the Servlet API,\nwhere contracts are synchronous ("),a("code",[e._v("Filter")]),e._v(", "),a("code",[e._v("Servlet")]),e._v(") or blocking ("),a("code",[e._v("getParameter")]),e._v(","),a("code",[e._v("getPart")]),e._v("). This was the motivation for a new common API to serve as a foundation across\nany non-blocking runtime. That is important because of servers (such as Netty) that are\nwell-established in the async, non-blocking space.")]),e._v(" "),a("p",[e._v("The other part of the answer is functional programming. Much as the addition of annotations\nin Java 5 created opportunities (such as annotated REST controllers or unit tests), the addition\nof lambda expressions in Java 8 created opportunities for functional APIs in Java.\nThis is a boon for non-blocking applications and continuation-style APIs (as popularized\nby "),a("code",[e._v("CompletableFuture")]),e._v(" and "),a("a",{attrs:{href:"http://reactivex.io/",target:"_blank",rel:"noopener noreferrer"}},[e._v("ReactiveX"),a("OutboundLink")],1),e._v(") that allow declarative\ncomposition of asynchronous logic. At the programming-model level, Java 8 enabled Spring\nWebFlux to offer functional web endpoints alongside annotated controllers.")]),e._v(" "),a("h4",{attrs:{id:"_1-1-1-define-reactive"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_1-1-1-define-reactive"}},[e._v("#")]),e._v(" 1.1.1. Define “Reactive”")]),e._v(" "),a("p",[e._v("We touched on “non-blocking” and “functional” but what does reactive mean?")]),e._v(" "),a("p",[e._v("The term, “reactive,” refers to programming models that are built around reacting to change — network components reacting to I/O events, UI controllers reacting to mouse events, and others.\nIn that sense, non-blocking is reactive, because, instead of being blocked, we are now in the mode\nof reacting to notifications as operations complete or data becomes available.")]),e._v(" "),a("p",[e._v("There is also another important mechanism that we on the Spring team associate with “reactive”\nand that is non-blocking back pressure. In synchronous, imperative code, blocking calls\nserve as a natural form of back pressure that forces the caller to wait. In non-blocking\ncode, it becomes important to control the rate of events so that a fast producer does not\noverwhelm its destination.")]),e._v(" "),a("p",[e._v("Reactive Streams is a"),a("a",{attrs:{href:"https://github.com/reactive-streams/reactive-streams-jvm/blob/master/README.md#specification",target:"_blank",rel:"noopener noreferrer"}},[e._v("small spec"),a("OutboundLink")],1),e._v("(also "),a("a",{attrs:{href:"https://docs.oracle.com/javase/9/docs/api/java/util/concurrent/Flow.html",target:"_blank",rel:"noopener noreferrer"}},[e._v("adopted"),a("OutboundLink")],1),e._v(" in Java 9)\nthat defines the interaction between asynchronous components with back pressure.\nFor example a data repository (acting as"),a("a",{attrs:{href:"https://www.reactive-streams.org/reactive-streams-1.0.1-javadoc/org/reactivestreams/Publisher.html",target:"_blank",rel:"noopener noreferrer"}},[e._v("Publisher"),a("OutboundLink")],1),e._v(")\ncan produce data that an HTTP server (acting as"),a("a",{attrs:{href:"https://www.reactive-streams.org/reactive-streams-1.0.1-javadoc/org/reactivestreams/Subscriber.html",target:"_blank",rel:"noopener noreferrer"}},[e._v("Subscriber"),a("OutboundLink")],1),e._v(")\ncan then write to the response. The main purpose of Reactive Streams is to let the\nsubscriber control how quickly or how slowly the publisher produces data.")]),e._v(" "),a("table",[a("thead",[a("tr",[a("th"),e._v(" "),a("th",[a("strong",[e._v("Common question: what if a publisher cannot slow down?")]),e._v(" "),a("br"),e._v("The purpose of Reactive Streams is only to establish the mechanism and a boundary."),a("br"),e._v("If a publisher cannot slow down, it has to decide whether to buffer, drop, or fail.")])])]),e._v(" "),a("tbody")]),e._v(" "),a("h4",{attrs:{id:"_1-1-2-reactive-api"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_1-1-2-reactive-api"}},[e._v("#")]),e._v(" 1.1.2. Reactive API")]),e._v(" "),a("p",[e._v("Reactive Streams plays an important role for interoperability. It is of interest to libraries\nand infrastructure components but less useful as an application API, because it is too\nlow-level. Applications need a higher-level and richer, functional API to\ncompose async logic — similar to the Java 8 "),a("code",[e._v("Stream")]),e._v(" API but not only for collections.\nThis is the role that reactive libraries play.")]),e._v(" "),a("p",[a("a",{attrs:{href:"https://github.com/reactor/reactor",target:"_blank",rel:"noopener noreferrer"}},[e._v("Reactor"),a("OutboundLink")],1),e._v(" is the reactive library of choice for\nSpring WebFlux. It provides the"),a("a",{attrs:{href:"https://projectreactor.io/docs/core/release/api/reactor/core/publisher/Mono.html",target:"_blank",rel:"noopener noreferrer"}},[a("code",[e._v("Mono")]),a("OutboundLink")],1),e._v(" and"),a("a",{attrs:{href:"https://projectreactor.io/docs/core/release/api/reactor/core/publisher/Flux.html",target:"_blank",rel:"noopener noreferrer"}},[a("code",[e._v("Flux")]),a("OutboundLink")],1),e._v(" API types\nto work on data sequences of 0..1 ("),a("code",[e._v("Mono")]),e._v(") and 0..N ("),a("code",[e._v("Flux")]),e._v(") through a rich set of operators aligned with the\nReactiveX "),a("a",{attrs:{href:"http://reactivex.io/documentation/operators.html",target:"_blank",rel:"noopener noreferrer"}},[e._v("vocabulary of operators"),a("OutboundLink")],1),e._v(".\nReactor is a Reactive Streams library and, therefore, all of its operators support non-blocking back pressure.\nReactor has a strong focus on server-side Java. It is developed in close collaboration\nwith Spring.")]),e._v(" "),a("p",[e._v("WebFlux requires Reactor as a core dependency but it is interoperable with other reactive\nlibraries via Reactive Streams. As a general rule, a WebFlux API accepts a plain "),a("code",[e._v("Publisher")]),e._v("as input, adapts it to a Reactor type internally, uses that, and returns either a"),a("code",[e._v("Flux")]),e._v(" or a "),a("code",[e._v("Mono")]),e._v(" as output. So, you can pass any "),a("code",[e._v("Publisher")]),e._v(" as input and you can apply\noperations on the output, but you need to adapt the output for use with another reactive library.\nWhenever feasible (for example, annotated controllers), WebFlux adapts transparently to the use\nof RxJava or another reactive library. See "),a("a",{attrs:{href:"#webflux-reactive-libraries"}},[e._v("Reactive Libraries")]),e._v(" for more details.")]),e._v(" "),a("table",[a("thead",[a("tr",[a("th"),e._v(" "),a("th",[e._v("In addition to Reactive APIs, WebFlux can also be used with"),a("RouterLink",{attrs:{to:"/en/spring-framework/languages.html#coroutines"}},[e._v("Coroutines")]),e._v(" APIs in Kotlin which provides a more imperative style of programming."),a("br"),e._v("The following Kotlin code samples will be provided with Coroutines APIs.")],1)])]),e._v(" "),a("tbody")]),e._v(" "),a("h4",{attrs:{id:"_1-1-3-programming-models"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_1-1-3-programming-models"}},[e._v("#")]),e._v(" 1.1.3. Programming Models")]),e._v(" "),a("p",[e._v("The "),a("code",[e._v("spring-web")]),e._v(" module contains the reactive foundation that underlies Spring WebFlux,\nincluding HTTP abstractions, Reactive Streams "),a("a",{attrs:{href:"#webflux-httphandler"}},[e._v("adapters")]),e._v(" for supported\nservers, "),a("a",{attrs:{href:"#webflux-codecs"}},[e._v("codecs")]),e._v(", and a core "),a("a",{attrs:{href:"#webflux-web-handler-api"}},[a("code",[e._v("WebHandler")]),e._v(" API")]),e._v(" comparable to\nthe Servlet API but with non-blocking contracts.")]),e._v(" "),a("p",[e._v("On that foundation, Spring WebFlux provides a choice of two programming models:")]),e._v(" "),a("ul",[a("li",[a("p",[a("a",{attrs:{href:"#webflux-controller"}},[e._v("Annotated Controllers")]),e._v(": Consistent with Spring MVC and based on the same annotations\nfrom the "),a("code",[e._v("spring-web")]),e._v(" module. Both Spring MVC and WebFlux controllers support reactive\n(Reactor and RxJava) return types, and, as a result, it is not easy to tell them apart. One notable\ndifference is that WebFlux also supports reactive "),a("code",[e._v("@RequestBody")]),e._v(" arguments.")])]),e._v(" "),a("li",[a("p",[a("a",{attrs:{href:"#webflux-fn"}},[e._v("Functional Endpoints")]),e._v(": Lambda-based, lightweight, and functional programming model. You can think of\nthis as a small library or a set of utilities that an application can use to route and\nhandle requests. The big difference with annotated controllers is that the application\nis in charge of request handling from start to finish versus declaring intent through\nannotations and being called back.")])])]),e._v(" "),a("h4",{attrs:{id:"_1-1-4-applicability"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_1-1-4-applicability"}},[e._v("#")]),e._v(" 1.1.4. Applicability")]),e._v(" "),a("p",[e._v("Spring MVC or WebFlux?")]),e._v(" "),a("p",[e._v("A natural question to ask but one that sets up an unsound dichotomy. Actually, both\nwork together to expand the range of available options. The two are designed for\ncontinuity and consistency with each other, they are available side by side, and feedback\nfrom each side benefits both sides. The following diagram shows how the two relate, what they\nhave in common, and what each supports uniquely:")]),e._v(" "),a("p",[a("img",{attrs:{src:"images/spring-mvc-and-webflux-venn.png",alt:"spring mvc and webflux venn"}})]),e._v(" "),a("p",[e._v("We suggest that you consider the following specific points:")]),e._v(" "),a("ul",[a("li",[a("p",[e._v("If you have a Spring MVC application that works fine, there is no need to change.\nImperative programming is the easiest way to write, understand, and debug code.\nYou have maximum choice of libraries, since, historically, most are blocking.")])]),e._v(" "),a("li",[a("p",[e._v("If you are already shopping for a non-blocking web stack, Spring WebFlux offers the same\nexecution model benefits as others in this space and also provides a choice of servers\n(Netty, Tomcat, Jetty, Undertow, and Servlet 3.1+ containers), a choice of programming models\n(annotated controllers and functional web endpoints), and a choice of reactive libraries\n(Reactor, RxJava, or other).")])]),e._v(" "),a("li",[a("p",[e._v("If you are interested in a lightweight, functional web framework for use with Java 8 lambdas\nor Kotlin, you can use the Spring WebFlux functional web endpoints. That can also be a good choice\nfor smaller applications or microservices with less complex requirements that can benefit\nfrom greater transparency and control.")])]),e._v(" "),a("li",[a("p",[e._v("In a microservice architecture, you can have a mix of applications with either Spring MVC\nor Spring WebFlux controllers or with Spring WebFlux functional endpoints. Having support\nfor the same annotation-based programming model in both frameworks makes it easier to\nre-use knowledge while also selecting the right tool for the right job.")])]),e._v(" "),a("li",[a("p",[e._v("A simple way to evaluate an application is to check its dependencies. If you have blocking\npersistence APIs (JPA, JDBC) or networking APIs to use, Spring MVC is the best choice\nfor common architectures at least. It is technically feasible with both Reactor and\nRxJava to perform blocking calls on a separate thread but you would not be making the\nmost of a non-blocking web stack.")])]),e._v(" "),a("li",[a("p",[e._v("If you have a Spring MVC application with calls to remote services, try the reactive "),a("code",[e._v("WebClient")]),e._v(".\nYou can return reactive types (Reactor, RxJava, "),a("a",{attrs:{href:"#webflux-reactive-libraries"}},[e._v("or other")]),e._v(")\ndirectly from Spring MVC controller methods. The greater the latency per call or the\ninterdependency among calls, the more dramatic the benefits. Spring MVC controllers\ncan call other reactive components too.")])]),e._v(" "),a("li",[a("p",[e._v("If you have a large team, keep in mind the steep learning curve in the shift to non-blocking,\nfunctional, and declarative programming. A practical way to start without a full switch\nis to use the reactive "),a("code",[e._v("WebClient")]),e._v(". Beyond that, start small and measure the benefits.\nWe expect that, for a wide range of applications, the shift is unnecessary. If you are\nunsure what benefits to look for, start by learning about how non-blocking I/O works\n(for example, concurrency on single-threaded Node.js) and its effects.")])])]),e._v(" "),a("h4",{attrs:{id:"_1-1-5-servers"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_1-1-5-servers"}},[e._v("#")]),e._v(" 1.1.5. Servers")]),e._v(" "),a("p",[e._v("Spring WebFlux is supported on Tomcat, Jetty, Servlet 3.1+ containers, as well as on\nnon-Servlet runtimes such as Netty and Undertow. All servers are adapted to a low-level,"),a("a",{attrs:{href:"#webflux-httphandler"}},[e._v("common API")]),e._v(" so that higher-level"),a("a",{attrs:{href:"#webflux-programming-models"}},[e._v("programming models")]),e._v(" can be supported across servers.")]),e._v(" "),a("p",[e._v("Spring WebFlux does not have built-in support to start or stop a server. However, it is\neasy to "),a("a",{attrs:{href:"#webflux-web-handler-api"}},[e._v("assemble")]),e._v(" an application from Spring configuration and"),a("a",{attrs:{href:"#webflux-config"}},[e._v("WebFlux infrastructure")]),e._v(" and "),a("a",{attrs:{href:"#webflux-httphandler"}},[e._v("run it")]),e._v(" with a few\nlines of code.")]),e._v(" "),a("p",[e._v("Spring Boot has a WebFlux starter that automates these steps. By default, the starter uses\nNetty, but it is easy to switch to Tomcat, Jetty, or Undertow by changing your\nMaven or Gradle dependencies. Spring Boot defaults to Netty, because it is more widely\nused in the asynchronous, non-blocking space and lets a client and a server share resources.")]),e._v(" "),a("p",[e._v("Tomcat and Jetty can be used with both Spring MVC and WebFlux. Keep in mind, however, that\nthe way they are used is very different. Spring MVC relies on Servlet blocking I/O and\nlets applications use the Servlet API directly if they need to. Spring WebFlux\nrelies on Servlet 3.1 non-blocking I/O and uses the Servlet API behind a low-level\nadapter. It is not exposed for direct use.")]),e._v(" "),a("p",[e._v("For Undertow, Spring WebFlux uses Undertow APIs directly without the Servlet API.")]),e._v(" "),a("h4",{attrs:{id:"_1-1-6-performance"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_1-1-6-performance"}},[e._v("#")]),e._v(" 1.1.6. Performance")]),e._v(" "),a("p",[e._v("Performance has many characteristics and meanings. Reactive and non-blocking generally\ndo not make applications run faster. They can, in some cases, (for example, if using the"),a("code",[e._v("WebClient")]),e._v(" to run remote calls in parallel). On the whole, it requires more work to do\nthings the non-blocking way and that can slightly increase the required processing time.")]),e._v(" "),a("p",[e._v("The key expected benefit of reactive and non-blocking is the ability to scale with a small,\nfixed number of threads and less memory. That makes applications more resilient under load,\nbecause they scale in a more predictable way. In order to observe those benefits, however, you\nneed to have some latency (including a mix of slow and unpredictable network I/O).\nThat is where the reactive stack begins to show its strengths, and the differences can be\ndramatic.")]),e._v(" "),a("h4",{attrs:{id:"_1-1-7-concurrency-model"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_1-1-7-concurrency-model"}},[e._v("#")]),e._v(" 1.1.7. Concurrency Model")]),e._v(" "),a("p",[e._v("Both Spring MVC and Spring WebFlux support annotated controllers, but there is a key\ndifference in the concurrency model and the default assumptions for blocking and threads.")]),e._v(" "),a("p",[e._v("In Spring MVC (and servlet applications in general), it is assumed that applications can\nblock the current thread, (for example, for remote calls). For this reason, servlet containers\nuse a large thread pool to absorb potential blocking during request handling.")]),e._v(" "),a("p",[e._v("In Spring WebFlux (and non-blocking servers in general), it is assumed that applications\ndo not block. Therefore, non-blocking servers use a small, fixed-size thread pool\n(event loop workers) to handle requests.")]),e._v(" "),a("table",[a("thead",[a("tr",[a("th"),e._v(" "),a("th",[e._v("“To scale” and “small number of threads” may sound contradictory but to never block the"),a("br"),e._v("current thread (and rely on callbacks instead) means that you do not need extra threads, as"),a("br"),e._v("there are no blocking calls to absorb.")])])]),e._v(" "),a("tbody")]),e._v(" "),a("p",[e._v("Invoking a Blocking API")]),e._v(" "),a("p",[e._v("What if you do need to use a blocking library? Both Reactor and RxJava provide the"),a("code",[e._v("publishOn")]),e._v(" operator to continue processing on a different thread. That means there is an\neasy escape hatch. Keep in mind, however, that blocking APIs are not a good fit for\nthis concurrency model.")]),e._v(" "),a("p",[e._v("Mutable State")]),e._v(" "),a("p",[e._v("In Reactor and RxJava, you declare logic through operators. At runtime, a reactive\npipeline is formed where data is processed sequentially, in distinct stages. A key benefit\nof this is that it frees applications from having to protect mutable state because\napplication code within that pipeline is never invoked concurrently.")]),e._v(" "),a("p",[e._v("Threading Model")]),e._v(" "),a("p",[e._v("What threads should you expect to see on a server running with Spring WebFlux?")]),e._v(" "),a("ul",[a("li",[a("p",[e._v("On a “vanilla” Spring WebFlux server (for example, no data access nor other optional\ndependencies), you can expect one thread for the server and several others for request\nprocessing (typically as many as the number of CPU cores). Servlet containers, however,\nmay start with more threads (for example, 10 on Tomcat), in support of both servlet (blocking) I/O\nand servlet 3.1 (non-blocking) I/O usage.")])]),e._v(" "),a("li",[a("p",[e._v("The reactive "),a("code",[e._v("WebClient")]),e._v(" operates in event loop style. So you can see a small, fixed\nnumber of processing threads related to that (for example, "),a("code",[e._v("reactor-http-nio-")]),e._v(" with the Reactor\nNetty connector). However, if Reactor Netty is used for both client and server, the two\nshare event loop resources by default.")])]),e._v(" "),a("li",[a("p",[e._v("Reactor and RxJava provide thread pool abstractions, called schedulers, to use with the"),a("code",[e._v("publishOn")]),e._v(" operator that is used to switch processing to a different thread pool.\nThe schedulers have names that suggest a specific concurrency strategy — for example, “parallel”\n(for CPU-bound work with a limited number of threads) or “elastic” (for I/O-bound work with\na large number of threads). If you see such threads, it means some code is using a\nspecific thread pool "),a("code",[e._v("Scheduler")]),e._v(" strategy.")])]),e._v(" "),a("li",[a("p",[e._v("Data access libraries and other third party dependencies can also create and use threads\nof their own.")])])]),e._v(" "),a("p",[e._v("Configuring")]),e._v(" "),a("p",[e._v("The Spring Framework does not provide support for starting and stopping"),a("a",{attrs:{href:"#webflux-server-choice"}},[e._v("servers")]),e._v(". To configure the threading model for a server,\nyou need to use server-specific configuration APIs, or, if you use Spring Boot,\ncheck the Spring Boot configuration options for each server. You can"),a("a",{attrs:{href:"#webflux-client-builder"}},[e._v("configure")]),e._v(" the "),a("code",[e._v("WebClient")]),e._v(" directly.\nFor all other libraries, see their respective documentation.")]),e._v(" "),a("h3",{attrs:{id:"_1-2-reactive-core"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_1-2-reactive-core"}},[e._v("#")]),e._v(" 1.2. Reactive Core")]),e._v(" "),a("p",[e._v("The "),a("code",[e._v("spring-web")]),e._v(" module contains the following foundational support for reactive web\napplications:")]),e._v(" "),a("ul",[a("li",[a("p",[e._v("For server request processing there are two levels of support.")]),e._v(" "),a("ul",[a("li",[a("p",[a("a",{attrs:{href:"#webflux-httphandler"}},[e._v("HttpHandler")]),e._v(": Basic contract for HTTP request handling with\nnon-blocking I/O and Reactive Streams back pressure, along with adapters for Reactor Netty,\nUndertow, Tomcat, Jetty, and any Servlet 3.1+ container.")])]),e._v(" "),a("li",[a("p",[a("a",{attrs:{href:"#webflux-web-handler-api"}},[a("code",[e._v("WebHandler")]),e._v(" API")]),e._v(": Slightly higher level, general-purpose web API for\nrequest handling, on top of which concrete programming models such as annotated\ncontrollers and functional endpoints are built.")])])])]),e._v(" "),a("li",[a("p",[e._v("For the client side, there is a basic "),a("code",[e._v("ClientHttpConnector")]),e._v(" contract to perform HTTP\nrequests with non-blocking I/O and Reactive Streams back pressure, along with adapters for"),a("a",{attrs:{href:"https://github.com/reactor/reactor-netty",target:"_blank",rel:"noopener noreferrer"}},[e._v("Reactor Netty"),a("OutboundLink")],1),e._v(", reactive"),a("a",{attrs:{href:"https://github.com/jetty-project/jetty-reactive-httpclient",target:"_blank",rel:"noopener noreferrer"}},[e._v("Jetty HttpClient"),a("OutboundLink")],1),e._v("and "),a("a",{attrs:{href:"https://hc.apache.org/",target:"_blank",rel:"noopener noreferrer"}},[e._v("Apache HttpComponents"),a("OutboundLink")],1),e._v(".\nThe higher level "),a("a",{attrs:{href:"#webflux-client"}},[e._v("WebClient")]),e._v(" used in applications\nbuilds on this basic contract.")])]),e._v(" "),a("li",[a("p",[e._v("For client and server, "),a("a",{attrs:{href:"#webflux-codecs"}},[e._v("codecs")]),e._v(" for serialization and\ndeserialization of HTTP request and response content.")])])]),e._v(" "),a("h4",{attrs:{id:"_1-2-1-httphandler"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_1-2-1-httphandler"}},[e._v("#")]),e._v(" 1.2.1. "),a("code",[e._v("HttpHandler")])]),e._v(" "),a("p",[a("a",{attrs:{href:"https://docs.spring.io/spring-framework/docs/5.3.16/javadoc-api/org/springframework/http/server/reactive/HttpHandler.html",target:"_blank",rel:"noopener noreferrer"}},[e._v("HttpHandler"),a("OutboundLink")],1),e._v("is a simple contract with a single method to handle a request and a response. It is\nintentionally minimal, and its main and only purpose is to be a minimal abstraction\nover different HTTP server APIs.")]),e._v(" "),a("p",[e._v("The following table describes the supported server APIs:")]),e._v(" "),a("table",[a("thead",[a("tr",[a("th",[e._v("Server name")]),e._v(" "),a("th",[e._v("Server API used")]),e._v(" "),a("th",[e._v("Reactive Streams support")])])]),e._v(" "),a("tbody",[a("tr",[a("td",[e._v("Netty")]),e._v(" "),a("td",[e._v("Netty API")]),e._v(" "),a("td",[a("a",{attrs:{href:"https://github.com/reactor/reactor-netty",target:"_blank",rel:"noopener noreferrer"}},[e._v("Reactor Netty"),a("OutboundLink")],1)])]),e._v(" "),a("tr",[a("td",[e._v("Undertow")]),e._v(" "),a("td",[e._v("Undertow API")]),e._v(" "),a("td",[e._v("spring-web: Undertow to Reactive Streams bridge")])]),e._v(" "),a("tr",[a("td",[e._v("Tomcat")]),e._v(" "),a("td",[e._v("Servlet 3.1 non-blocking I/O; Tomcat API to read and write ByteBuffers vs byte[]")]),e._v(" "),a("td",[e._v("spring-web: Servlet 3.1 non-blocking I/O to Reactive Streams bridge")])]),e._v(" "),a("tr",[a("td",[e._v("Jetty")]),e._v(" "),a("td",[e._v("Servlet 3.1 non-blocking I/O; Jetty API to write ByteBuffers vs byte[]")]),e._v(" "),a("td",[e._v("spring-web: Servlet 3.1 non-blocking I/O to Reactive Streams bridge")])]),e._v(" "),a("tr",[a("td",[e._v("Servlet 3.1 container")]),e._v(" "),a("td",[e._v("Servlet 3.1 non-blocking I/O")]),e._v(" "),a("td",[e._v("spring-web: Servlet 3.1 non-blocking I/O to Reactive Streams bridge")])])])]),e._v(" "),a("p",[e._v("The following table describes server dependencies (also see"),a("a",{attrs:{href:"https://github.com/spring-projects/spring-framework/wiki/What%27s-New-in-the-Spring-Framework",target:"_blank",rel:"noopener noreferrer"}},[e._v("supported versions"),a("OutboundLink")],1),e._v("):")]),e._v(" "),a("table",[a("thead",[a("tr",[a("th",[e._v("Server name")]),e._v(" "),a("th",[e._v("Group id")]),e._v(" "),a("th",[e._v("Artifact name")])])]),e._v(" "),a("tbody",[a("tr",[a("td",[e._v("Reactor Netty")]),e._v(" "),a("td",[e._v("io.projectreactor.netty")]),e._v(" "),a("td",[e._v("reactor-netty")])]),e._v(" "),a("tr",[a("td",[e._v("Undertow")]),e._v(" "),a("td",[e._v("io.undertow")]),e._v(" "),a("td",[e._v("undertow-core")])]),e._v(" "),a("tr",[a("td",[e._v("Tomcat")]),e._v(" "),a("td",[e._v("org.apache.tomcat.embed")]),e._v(" "),a("td",[e._v("tomcat-embed-core")])]),e._v(" "),a("tr",[a("td",[e._v("Jetty")]),e._v(" "),a("td",[e._v("org.eclipse.jetty")]),e._v(" "),a("td",[e._v("jetty-server, jetty-servlet")])])])]),e._v(" "),a("p",[e._v("The code snippets below show using the "),a("code",[e._v("HttpHandler")]),e._v(" adapters with each server API:")]),e._v(" "),a("p",[a("strong",[e._v("Reactor Netty")])]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("HttpHandler handler = ...\nReactorHttpHandlerAdapter adapter = new ReactorHttpHandlerAdapter(handler);\nHttpServer.create().host(host).port(port).handle(adapter).bind().block();\n")])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("val handler: HttpHandler = ...\nval adapter = ReactorHttpHandlerAdapter(handler)\nHttpServer.create().host(host).port(port).handle(adapter).bind().block()\n")])])]),a("p",[a("strong",[e._v("Undertow")])]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("HttpHandler handler = ...\nUndertowHttpHandlerAdapter adapter = new UndertowHttpHandlerAdapter(handler);\nUndertow server = Undertow.builder().addHttpListener(port, host).setHandler(adapter).build();\nserver.start();\n")])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("val handler: HttpHandler = ...\nval adapter = UndertowHttpHandlerAdapter(handler)\nval server = Undertow.builder().addHttpListener(port, host).setHandler(adapter).build()\nserver.start()\n")])])]),a("p",[a("strong",[e._v("Tomcat")])]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('HttpHandler handler = ...\nServlet servlet = new TomcatHttpHandlerAdapter(handler);\n\nTomcat server = new Tomcat();\nFile base = new File(System.getProperty("java.io.tmpdir"));\nContext rootContext = server.addContext("", base.getAbsolutePath());\nTomcat.addServlet(rootContext, "main", servlet);\nrootContext.addServletMappingDecoded("/", "main");\nserver.setHost(host);\nserver.setPort(port);\nserver.start();\n')])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('val handler: HttpHandler = ...\nval servlet = TomcatHttpHandlerAdapter(handler)\n\nval server = Tomcat()\nval base = File(System.getProperty("java.io.tmpdir"))\nval rootContext = server.addContext("", base.absolutePath)\nTomcat.addServlet(rootContext, "main", servlet)\nrootContext.addServletMappingDecoded("/", "main")\nserver.host = host\nserver.setPort(port)\nserver.start()\n')])])]),a("p",[a("strong",[e._v("Jetty")])]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('HttpHandler handler = ...\nServlet servlet = new JettyHttpHandlerAdapter(handler);\n\nServer server = new Server();\nServletContextHandler contextHandler = new ServletContextHandler(server, "");\ncontextHandler.addServlet(new ServletHolder(servlet), "/");\ncontextHandler.start();\n\nServerConnector connector = new ServerConnector(server);\nconnector.setHost(host);\nconnector.setPort(port);\nserver.addConnector(connector);\nserver.start();\n')])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('val handler: HttpHandler = ...\nval servlet = JettyHttpHandlerAdapter(handler)\n\nval server = Server()\nval contextHandler = ServletContextHandler(server, "")\ncontextHandler.addServlet(ServletHolder(servlet), "/")\ncontextHandler.start();\n\nval connector = ServerConnector(server)\nconnector.host = host\nconnector.port = port\nserver.addConnector(connector)\nserver.start()\n')])])]),a("p",[a("strong",[e._v("Servlet 3.1+ Container")])]),e._v(" "),a("p",[e._v("To deploy as a WAR to any Servlet 3.1+ container, you can extend and include"),a("a",{attrs:{href:"https://docs.spring.io/spring-framework/docs/5.3.16/javadoc-api/org/springframework/web/server/adapter/AbstractReactiveWebInitializer.html",target:"_blank",rel:"noopener noreferrer"}},[a("code",[e._v("AbstractReactiveWebInitializer")]),a("OutboundLink")],1),e._v("in the WAR. That class wraps an "),a("code",[e._v("HttpHandler")]),e._v(" with "),a("code",[e._v("ServletHttpHandlerAdapter")]),e._v(" and registers\nthat as a "),a("code",[e._v("Servlet")]),e._v(".")]),e._v(" "),a("h4",{attrs:{id:"_1-2-2-webhandler-api"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_1-2-2-webhandler-api"}},[e._v("#")]),e._v(" 1.2.2. "),a("code",[e._v("WebHandler")]),e._v(" API")]),e._v(" "),a("p",[e._v("The "),a("code",[e._v("org.springframework.web.server")]),e._v(" package builds on the "),a("a",{attrs:{href:"#webflux-httphandler"}},[a("code",[e._v("HttpHandler")])]),e._v(" contract\nto provide a general-purpose web API for processing requests through a chain of multiple"),a("a",{attrs:{href:"https://docs.spring.io/spring-framework/docs/5.3.16/javadoc-api/org/springframework/web/server/WebExceptionHandler.html",target:"_blank",rel:"noopener noreferrer"}},[a("code",[e._v("WebExceptionHandler")]),a("OutboundLink")],1),e._v(", multiple"),a("a",{attrs:{href:"https://docs.spring.io/spring-framework/docs/5.3.16/javadoc-api/org/springframework/web/server/WebFilter.html",target:"_blank",rel:"noopener noreferrer"}},[a("code",[e._v("WebFilter")]),a("OutboundLink")],1),e._v(", and a single"),a("a",{attrs:{href:"https://docs.spring.io/spring-framework/docs/5.3.16/javadoc-api/org/springframework/web/server/WebHandler.html",target:"_blank",rel:"noopener noreferrer"}},[a("code",[e._v("WebHandler")]),a("OutboundLink")],1),e._v(" component. The chain can\nbe put together with "),a("code",[e._v("WebHttpHandlerBuilder")]),e._v(" by simply pointing to a Spring"),a("code",[e._v("ApplicationContext")]),e._v(" where components are"),a("a",{attrs:{href:"#webflux-web-handler-api-special-beans"}},[e._v("auto-detected")]),e._v(", and/or by registering components\nwith the builder.")]),e._v(" "),a("p",[e._v("While "),a("code",[e._v("HttpHandler")]),e._v(" has a simple goal to abstract the use of different HTTP servers, the"),a("code",[e._v("WebHandler")]),e._v(" API aims to provide a broader set of features commonly used in web applications\nsuch as:")]),e._v(" "),a("ul",[a("li",[a("p",[e._v("User session with attributes.")])]),e._v(" "),a("li",[a("p",[e._v("Request attributes.")])]),e._v(" "),a("li",[a("p",[e._v("Resolved "),a("code",[e._v("Locale")]),e._v(" or "),a("code",[e._v("Principal")]),e._v(" for the request.")])]),e._v(" "),a("li",[a("p",[e._v("Access to parsed and cached form data.")])]),e._v(" "),a("li",[a("p",[e._v("Abstractions for multipart data.")])]),e._v(" "),a("li",[a("p",[e._v("and more..")])])]),e._v(" "),a("h5",{attrs:{id:"special-bean-types"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#special-bean-types"}},[e._v("#")]),e._v(" Special bean types")]),e._v(" "),a("p",[e._v("The table below lists the components that "),a("code",[e._v("WebHttpHandlerBuilder")]),e._v(" can auto-detect in a\nSpring ApplicationContext, or that can be registered directly with it:")]),e._v(" "),a("table",[a("thead",[a("tr",[a("th",[e._v("Bean name")]),e._v(" "),a("th",[e._v("Bean type")]),e._v(" "),a("th",[e._v("Count")]),e._v(" "),a("th",[e._v("Description")])])]),e._v(" "),a("tbody",[a("tr",[a("td",[e._v("<any>")]),e._v(" "),a("td",[a("code",[e._v("WebExceptionHandler")])]),e._v(" "),a("td",[e._v("0..N")]),e._v(" "),a("td",[e._v("Provide handling for exceptions from the chain of "),a("code",[e._v("WebFilter")]),e._v(" instances and the target"),a("code",[e._v("WebHandler")]),e._v(". For more details, see "),a("a",{attrs:{href:"#webflux-exception-handler"}},[e._v("Exceptions")]),e._v(".")])]),e._v(" "),a("tr",[a("td",[e._v("<any>")]),e._v(" "),a("td",[a("code",[e._v("WebFilter")])]),e._v(" "),a("td",[e._v("0..N")]),e._v(" "),a("td",[e._v("Apply interception style logic to before and after the rest of the filter chain and"),a("br"),e._v("the target "),a("code",[e._v("WebHandler")]),e._v(". For more details, see "),a("a",{attrs:{href:"#webflux-filters"}},[e._v("Filters")]),e._v(".")])]),e._v(" "),a("tr",[a("td",[a("code",[e._v("webHandler")])]),e._v(" "),a("td",[a("code",[e._v("WebHandler")])]),e._v(" "),a("td",[e._v("1")]),e._v(" "),a("td",[e._v("The handler for the request.")])]),e._v(" "),a("tr",[a("td",[a("code",[e._v("webSessionManager")])]),e._v(" "),a("td",[a("code",[e._v("WebSessionManager")])]),e._v(" "),a("td",[e._v("0..1")]),e._v(" "),a("td",[e._v("The manager for "),a("code",[e._v("WebSession")]),e._v(" instances exposed through a method on "),a("code",[e._v("ServerWebExchange")]),e._v("."),a("code",[e._v("DefaultWebSessionManager")]),e._v(" by default.")])]),e._v(" "),a("tr",[a("td",[a("code",[e._v("serverCodecConfigurer")])]),e._v(" "),a("td",[a("code",[e._v("ServerCodecConfigurer")])]),e._v(" "),a("td",[e._v("0..1")]),e._v(" "),a("td",[e._v("For access to "),a("code",[e._v("HttpMessageReader")]),e._v(" instances for parsing form data and multipart data that is then"),a("br"),e._v("exposed through methods on "),a("code",[e._v("ServerWebExchange")]),e._v(". "),a("code",[e._v("ServerCodecConfigurer.create()")]),e._v(" by default.")])]),e._v(" "),a("tr",[a("td",[a("code",[e._v("localeContextResolver")])]),e._v(" "),a("td",[a("code",[e._v("LocaleContextResolver")])]),e._v(" "),a("td",[e._v("0..1")]),e._v(" "),a("td",[e._v("The resolver for "),a("code",[e._v("LocaleContext")]),e._v(" exposed through a method on "),a("code",[e._v("ServerWebExchange")]),e._v("."),a("code",[e._v("AcceptHeaderLocaleContextResolver")]),e._v(" by default.")])]),e._v(" "),a("tr",[a("td",[a("code",[e._v("forwardedHeaderTransformer")])]),e._v(" "),a("td",[a("code",[e._v("ForwardedHeaderTransformer")])]),e._v(" "),a("td",[e._v("0..1")]),e._v(" "),a("td",[e._v("For processing forwarded type headers, either by extracting and removing them or by removing them only."),a("br"),e._v("Not used by default.")])])])]),e._v(" "),a("h5",{attrs:{id:"form-data"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#form-data"}},[e._v("#")]),e._v(" Form Data")]),e._v(" "),a("p",[a("code",[e._v("ServerWebExchange")]),e._v(" exposes the following method for accessing form data:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("Mono<MultiValueMap<String, String>> getFormData();\n")])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("suspend fun getFormData(): MultiValueMap<String, String>\n")])])]),a("p",[e._v("The "),a("code",[e._v("DefaultServerWebExchange")]),e._v(" uses the configured "),a("code",[e._v("HttpMessageReader")]),e._v(" to parse form data\n("),a("code",[e._v("application/x-www-form-urlencoded")]),e._v(") into a "),a("code",[e._v("MultiValueMap")]),e._v(". By default,"),a("code",[e._v("FormHttpMessageReader")]),e._v(" is configured for use by the "),a("code",[e._v("ServerCodecConfigurer")]),e._v(" bean\n(see the "),a("a",{attrs:{href:"#webflux-web-handler-api"}},[e._v("Web Handler API")]),e._v(").")]),e._v(" "),a("h5",{attrs:{id:"multipart-data"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#multipart-data"}},[e._v("#")]),e._v(" Multipart Data")]),e._v(" "),a("p",[a("RouterLink",{attrs:{to:"/en/spring-framework/web.html#mvc-multipart"}},[e._v("Web MVC")])],1),e._v(" "),a("p",[a("code",[e._v("ServerWebExchange")]),e._v(" exposes the following method for accessing multipart data:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("Mono<MultiValueMap<String, Part>> getMultipartData();\n")])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("suspend fun getMultipartData(): MultiValueMap<String, Part>\n")])])]),a("p",[e._v("The "),a("code",[e._v("DefaultServerWebExchange")]),e._v(" uses the configured"),a("code",[e._v("HttpMessageReader<MultiValueMap<String, Part>>")]),e._v(" to parse "),a("code",[e._v("multipart/form-data")]),e._v(" content\ninto a "),a("code",[e._v("MultiValueMap")]),e._v(".\nBy default, this is the "),a("code",[e._v("DefaultPartHttpMessageReader")]),e._v(", which does not have any third-party\ndependencies.\nAlternatively, the "),a("code",[e._v("SynchronossPartHttpMessageReader")]),e._v(" can be used, which is based on the"),a("a",{attrs:{href:"https://github.com/synchronoss/nio-multipart",target:"_blank",rel:"noopener noreferrer"}},[e._v("Synchronoss NIO Multipart"),a("OutboundLink")],1),e._v(" library.\nBoth are configured through the "),a("code",[e._v("ServerCodecConfigurer")]),e._v(" bean\n(see the "),a("a",{attrs:{href:"#webflux-web-handler-api"}},[e._v("Web Handler API")]),e._v(").")]),e._v(" "),a("p",[e._v("To parse multipart data in streaming fashion, you can use the "),a("code",[e._v("Flux<Part>")]),e._v(" returned from an"),a("code",[e._v("HttpMessageReader<Part>")]),e._v(" instead. For example, in an annotated controller, use of"),a("code",[e._v("@RequestPart")]),e._v(" implies "),a("code",[e._v("Map")]),e._v("-like access to individual parts by name and, hence, requires\nparsing multipart data in full. By contrast, you can use "),a("code",[e._v("@RequestBody")]),e._v(" to decode the\ncontent to "),a("code",[e._v("Flux<Part>")]),e._v(" without collecting to a "),a("code",[e._v("MultiValueMap")]),e._v(".")]),e._v(" "),a("h5",{attrs:{id:"forwarded-headers"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#forwarded-headers"}},[e._v("#")]),e._v(" Forwarded Headers")]),e._v(" "),a("p",[a("RouterLink",{attrs:{to:"/en/spring-framework/web.html#filters-forwarded-headers"}},[e._v("Web MVC")])],1),e._v(" "),a("p",[e._v("As a request goes through proxies (such as load balancers), the host, port, and\nscheme may change. That makes it a challenge, from a client perspective, to create links that point to the correct\nhost, port, and scheme.")]),e._v(" "),a("p",[a("a",{attrs:{href:"https://tools.ietf.org/html/rfc7239",target:"_blank",rel:"noopener noreferrer"}},[e._v("RFC 7239"),a("OutboundLink")],1),e._v(" defines the "),a("code",[e._v("Forwarded")]),e._v(" HTTP header\nthat proxies can use to provide information about the original request. There are other\nnon-standard headers, too, including "),a("code",[e._v("X-Forwarded-Host")]),e._v(", "),a("code",[e._v("X-Forwarded-Port")]),e._v(","),a("code",[e._v("X-Forwarded-Proto")]),e._v(", "),a("code",[e._v("X-Forwarded-Ssl")]),e._v(", and "),a("code",[e._v("X-Forwarded-Prefix")]),e._v(".")]),e._v(" "),a("p",[a("code",[e._v("ForwardedHeaderTransformer")]),e._v(" is a component that modifies the host, port, and scheme of\nthe request, based on forwarded headers, and then removes those headers. If you declare\nit as a bean with the name "),a("code",[e._v("forwardedHeaderTransformer")]),e._v(", it will be"),a("a",{attrs:{href:"#webflux-web-handler-api-special-beans"}},[e._v("detected")]),e._v(" and used.")]),e._v(" "),a("p",[e._v("There are security considerations for forwarded headers, since an application cannot know\nif the headers were added by a proxy, as intended, or by a malicious client. This is why\na proxy at the boundary of trust should be configured to remove untrusted forwarded traffic coming\nfrom the outside. You can also configure the "),a("code",[e._v("ForwardedHeaderTransformer")]),e._v(" with"),a("code",[e._v("removeOnly=true")]),e._v(", in which case it removes but does not use the headers.")]),e._v(" "),a("table",[a("thead",[a("tr",[a("th"),e._v(" "),a("th",[e._v("In 5.1 "),a("code",[e._v("ForwardedHeaderFilter")]),e._v(" was deprecated and superceded by"),a("code",[e._v("ForwardedHeaderTransformer")]),e._v(" so forwarded headers can be processed earlier, before the"),a("br"),e._v("exchange is created. If the filter is configured anyway, it is taken out of the list of"),a("br"),e._v("filters, and "),a("code",[e._v("ForwardedHeaderTransformer")]),e._v(" is used instead.")])])]),e._v(" "),a("tbody")]),e._v(" "),a("h4",{attrs:{id:"_1-2-3-filters"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_1-2-3-filters"}},[e._v("#")]),e._v(" 1.2.3. Filters")]),e._v(" "),a("p",[a("RouterLink",{attrs:{to:"/en/spring-framework/web.html#filters"}},[e._v("Web MVC")])],1),e._v(" "),a("p",[e._v("In the "),a("a",{attrs:{href:"#webflux-web-handler-api"}},[a("code",[e._v("WebHandler")]),e._v(" API")]),e._v(", you can use a "),a("code",[e._v("WebFilter")]),e._v(" to apply interception-style\nlogic before and after the rest of the processing chain of filters and the target"),a("code",[e._v("WebHandler")]),e._v(". When using the "),a("a",{attrs:{href:"#webflux-config"}},[e._v("WebFlux Config")]),e._v(", registering a "),a("code",[e._v("WebFilter")]),e._v(" is as simple\nas declaring it as a Spring bean and (optionally) expressing precedence by using "),a("code",[e._v("@Order")]),e._v(" on\nthe bean declaration or by implementing "),a("code",[e._v("Ordered")]),e._v(".")]),e._v(" "),a("h5",{attrs:{id:"cors"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#cors"}},[e._v("#")]),e._v(" CORS")]),e._v(" "),a("p",[a("RouterLink",{attrs:{to:"/en/spring-framework/web.html#filters-cors"}},[e._v("Web MVC")])],1),e._v(" "),a("p",[e._v("Spring WebFlux provides fine-grained support for CORS configuration through annotations on\ncontrollers. However, when you use it with Spring Security, we advise relying on the built-in"),a("code",[e._v("CorsFilter")]),e._v(", which must be ordered ahead of Spring Security’s chain of filters.")]),e._v(" "),a("p",[e._v("See the section on "),a("a",{attrs:{href:"#webflux-cors"}},[e._v("CORS")]),e._v(" and the "),a("RouterLink",{attrs:{to:"/en/spring-framework/webflux-cors.html#webflux-cors-webfilter"}},[e._v("webflux-cors.html")]),e._v(" for more details.")],1),e._v(" "),a("h4",{attrs:{id:"_1-2-4-exceptions"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_1-2-4-exceptions"}},[e._v("#")]),e._v(" 1.2.4. Exceptions")]),e._v(" "),a("p",[a("RouterLink",{attrs:{to:"/en/spring-framework/web.html#mvc-ann-customer-servlet-container-error-page"}},[e._v("Web MVC")])],1),e._v(" "),a("p",[e._v("In the "),a("a",{attrs:{href:"#webflux-web-handler-api"}},[a("code",[e._v("WebHandler")]),e._v(" API")]),e._v(", you can use a "),a("code",[e._v("WebExceptionHandler")]),e._v(" to handle\nexceptions from the chain of "),a("code",[e._v("WebFilter")]),e._v(" instances and the target "),a("code",[e._v("WebHandler")]),e._v(". When using the"),a("a",{attrs:{href:"#webflux-config"}},[e._v("WebFlux Config")]),e._v(", registering a "),a("code",[e._v("WebExceptionHandler")]),e._v(" is as simple as declaring it as a\nSpring bean and (optionally) expressing precedence by using "),a("code",[e._v("@Order")]),e._v(" on the bean declaration or\nby implementing "),a("code",[e._v("Ordered")]),e._v(".")]),e._v(" "),a("p",[e._v("The following table describes the available "),a("code",[e._v("WebExceptionHandler")]),e._v(" implementations:")]),e._v(" "),a("table",[a("thead",[a("tr",[a("th",[e._v("Exception Handler")]),e._v(" "),a("th",[e._v("Description")])])]),e._v(" "),a("tbody",[a("tr",[a("td",[a("code",[e._v("ResponseStatusExceptionHandler")])]),e._v(" "),a("td",[e._v("Provides handling for exceptions of type"),a("a",{attrs:{href:"https://docs.spring.io/spring-framework/docs/5.3.16/javadoc-api/org/springframework/web/server/ResponseStatusException.html",target:"_blank",rel:"noopener noreferrer"}},[a("code",[e._v("ResponseStatusException")]),a("OutboundLink")],1),e._v("by setting the response to the HTTP status code of the exception.")])]),e._v(" "),a("tr",[a("td",[a("code",[e._v("WebFluxResponseStatusExceptionHandler")])]),e._v(" "),a("td",[e._v("Extension of "),a("code",[e._v("ResponseStatusExceptionHandler")]),e._v(" that can also determine the HTTP status"),a("br"),e._v("code of a "),a("code",[e._v("@ResponseStatus")]),e._v(" annotation on any exception."),a("br"),a("br"),e._v(" This handler is declared in the "),a("a",{attrs:{href:"#webflux-config"}},[e._v("WebFlux Config")]),e._v(".")])])])]),e._v(" "),a("h4",{attrs:{id:"_1-2-5-codecs"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_1-2-5-codecs"}},[e._v("#")]),e._v(" 1.2.5. Codecs")]),e._v(" "),a("p",[a("RouterLink",{attrs:{to:"/en/spring-framework/integration.html#rest-message-conversion"}},[e._v("Web MVC")])],1),e._v(" "),a("p",[e._v("The "),a("code",[e._v("spring-web")]),e._v(" and "),a("code",[e._v("spring-core")]),e._v(" modules provide support for serializing and\ndeserializing byte content to and from higher level objects through non-blocking I/O with\nReactive Streams back pressure. The following describes this support:")]),e._v(" "),a("ul",[a("li",[a("p",[a("a",{attrs:{href:"https://docs.spring.io/spring-framework/docs/5.3.16/javadoc-api/org/springframework/core/codec/Encoder.html",target:"_blank",rel:"noopener noreferrer"}},[a("code",[e._v("Encoder")]),a("OutboundLink")],1),e._v(" and"),a("a",{attrs:{href:"https://docs.spring.io/spring-framework/docs/5.3.16/javadoc-api/org/springframework/core/codec/Decoder.html",target:"_blank",rel:"noopener noreferrer"}},[a("code",[e._v("Decoder")]),a("OutboundLink")],1),e._v(" are low level contracts to\nencode and decode content independent of HTTP.")])]),e._v(" "),a("li",[a("p",[a("a",{attrs:{href:"https://docs.spring.io/spring-framework/docs/5.3.16/javadoc-api/org/springframework/http/codec/HttpMessageReader.html",target:"_blank",rel:"noopener noreferrer"}},[a("code",[e._v("HttpMessageReader")]),a("OutboundLink")],1),e._v(" and"),a("a",{attrs:{href:"https://docs.spring.io/spring-framework/docs/5.3.16/javadoc-api/org/springframework/http/codec/HttpMessageWriter.html",target:"_blank",rel:"noopener noreferrer"}},[a("code",[e._v("HttpMessageWriter")]),a("OutboundLink")],1),e._v(" are contracts\nto encode and decode HTTP message content.")])]),e._v(" "),a("li",[a("p",[e._v("An "),a("code",[e._v("Encoder")]),e._v(" can be wrapped with "),a("code",[e._v("EncoderHttpMessageWriter")]),e._v(" to adapt it for use in a web\napplication, while a "),a("code",[e._v("Decoder")]),e._v(" can be wrapped with "),a("code",[e._v("DecoderHttpMessageReader")]),e._v(".")])]),e._v(" "),a("li",[a("p",[a("a",{attrs:{href:"https://docs.spring.io/spring-framework/docs/5.3.16/javadoc-api/org/springframework/core/io/buffer/DataBuffer.html",target:"_blank",rel:"noopener noreferrer"}},[a("code",[e._v("DataBuffer")]),a("OutboundLink")],1),e._v(" abstracts different\nbyte buffer representations (e.g. Netty "),a("code",[e._v("ByteBuf")]),e._v(", "),a("code",[e._v("java.nio.ByteBuffer")]),e._v(", etc.) and is\nwhat all codecs work on. See "),a("RouterLink",{attrs:{to:"/en/spring-framework/core.html#databuffers"}},[e._v("Data Buffers and Codecs")]),e._v(' in the\n"Spring Core" section for more on this topic.')],1)])]),e._v(" "),a("p",[e._v("The "),a("code",[e._v("spring-core")]),e._v(" module provides "),a("code",[e._v("byte[]")]),e._v(", "),a("code",[e._v("ByteBuffer")]),e._v(", "),a("code",[e._v("DataBuffer")]),e._v(", "),a("code",[e._v("Resource")]),e._v(", and"),a("code",[e._v("String")]),e._v(" encoder and decoder implementations. The "),a("code",[e._v("spring-web")]),e._v(" module provides Jackson\nJSON, Jackson Smile, JAXB2, Protocol Buffers and other encoders and decoders along with\nweb-only HTTP message reader and writer implementations for form data, multipart content,\nserver-sent events, and others.")]),e._v(" "),a("p",[a("code",[e._v("ClientCodecConfigurer")]),e._v(" and "),a("code",[e._v("ServerCodecConfigurer")]),e._v(" are typically used to configure and\ncustomize the codecs to use in an application. See the section on configuring"),a("a",{attrs:{href:"#webflux-config-message-codecs"}},[e._v("HTTP message codecs")]),e._v(".")]),e._v(" "),a("h5",{attrs:{id:"jackson-json"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#jackson-json"}},[e._v("#")]),e._v(" Jackson JSON")]),e._v(" "),a("p",[e._v("JSON and binary JSON ("),a("a",{attrs:{href:"https://github.com/FasterXML/smile-format-specification",target:"_blank",rel:"noopener noreferrer"}},[e._v("Smile"),a("OutboundLink")],1),e._v(") are\nboth supported when the Jackson library is present.")]),e._v(" "),a("p",[e._v("The "),a("code",[e._v("Jackson2Decoder")]),e._v(" works as follows:")]),e._v(" "),a("ul",[a("li",[a("p",[e._v("Jackson’s asynchronous, non-blocking parser is used to aggregate a stream of byte chunks\ninto "),a("code",[e._v("TokenBuffer")]),e._v("'s each representing a JSON object.")])]),e._v(" "),a("li",[a("p",[e._v("Each "),a("code",[e._v("TokenBuffer")]),e._v(" is passed to Jackson’s "),a("code",[e._v("ObjectMapper")]),e._v(" to create a higher level object.")])]),e._v(" "),a("li",[a("p",[e._v("When decoding to a single-value publisher (e.g. "),a("code",[e._v("Mono")]),e._v("), there is one "),a("code",[e._v("TokenBuffer")]),e._v(".")])]),e._v(" "),a("li",[a("p",[e._v("When decoding to a multi-value publisher (e.g. "),a("code",[e._v("Flux")]),e._v("), each "),a("code",[e._v("TokenBuffer")]),e._v(" is passed to\nthe "),a("code",[e._v("ObjectMapper")]),e._v(" as soon as enough bytes are received for a fully formed object. The\ninput content can be a JSON array, or any"),a("a",{attrs:{href:"https://en.wikipedia.org/wiki/JSON_streaming",target:"_blank",rel:"noopener noreferrer"}},[e._v("line-delimited JSON"),a("OutboundLink")],1),e._v(" format such as NDJSON,\nJSON Lines, or JSON Text Sequences.")])])]),e._v(" "),a("p",[e._v("The "),a("code",[e._v("Jackson2Encoder")]),e._v(" works as follows:")]),e._v(" "),a("ul",[a("li",[a("p",[e._v("For a single value publisher (e.g. "),a("code",[e._v("Mono")]),e._v("), simply serialize it through the"),a("code",[e._v("ObjectMapper")]),e._v(".")])]),e._v(" "),a("li",[a("p",[e._v("For a multi-value publisher with "),a("code",[e._v("application/json")]),e._v(", by default collect the values with"),a("code",[e._v("Flux#collectToList()")]),e._v(" and then serialize the resulting collection.")])]),e._v(" "),a("li",[a("p",[e._v("For a multi-value publisher with a streaming media type such as"),a("code",[e._v("application/x-ndjson")]),e._v(" or "),a("code",[e._v("application/stream+x-jackson-smile")]),e._v(", encode, write, and\nflush each value individually using a"),a("a",{attrs:{href:"https://en.wikipedia.org/wiki/JSON_streaming",target:"_blank",rel:"noopener noreferrer"}},[e._v("line-delimited JSON"),a("OutboundLink")],1),e._v(" format. Other\nstreaming media types may be registered with the encoder.")])]),e._v(" "),a("li",[a("p",[e._v("For SSE the "),a("code",[e._v("Jackson2Encoder")]),e._v(" is invoked per event and the output is flushed to ensure\ndelivery without delay.")])])]),e._v(" "),a("table",[a("thead",[a("tr",[a("th"),e._v(" "),a("th",[e._v("By default both "),a("code",[e._v("Jackson2Encoder")]),e._v(" and "),a("code",[e._v("Jackson2Decoder")]),e._v(" do not support elements of type"),a("code",[e._v("String")]),e._v(". Instead the default assumption is that a string or a sequence of strings"),a("br"),e._v("represent serialized JSON content, to be rendered by the "),a("code",[e._v("CharSequenceEncoder")]),e._v(". If what"),a("br"),e._v("you need is to render a JSON array from "),a("code",[e._v("Flux<String>")]),e._v(", use "),a("code",[e._v("Flux#collectToList()")]),e._v(" and"),a("br"),e._v("encode a "),a("code",[e._v("Mono<List<String>>")]),e._v(".")])])]),e._v(" "),a("tbody")]),e._v(" "),a("h5",{attrs:{id:"form-data-2"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#form-data-2"}},[e._v("#")]),e._v(" Form Data")]),e._v(" "),a("p",[a("code",[e._v("FormHttpMessageReader")]),e._v(" and "),a("code",[e._v("FormHttpMessageWriter")]),e._v(" support decoding and encoding"),a("code",[e._v("application/x-www-form-urlencoded")]),e._v(" content.")]),e._v(" "),a("p",[e._v("On the server side where form content often needs to be accessed from multiple places,"),a("code",[e._v("ServerWebExchange")]),e._v(" provides a dedicated "),a("code",[e._v("getFormData()")]),e._v(" method that parses the content\nthrough "),a("code",[e._v("FormHttpMessageReader")]),e._v(" and then caches the result for repeated access.\nSee "),a("a",{attrs:{href:"#webflux-form-data"}},[e._v("Form Data")]),e._v(" in the "),a("a",{attrs:{href:"#webflux-web-handler-api"}},[a("code",[e._v("WebHandler")]),e._v(" API")]),e._v(" section.")]),e._v(" "),a("p",[e._v("Once "),a("code",[e._v("getFormData()")]),e._v(" is used, the original raw content can no longer be read from the\nrequest body. For this reason, applications are expected to go through "),a("code",[e._v("ServerWebExchange")]),e._v("consistently for access to the cached form data versus reading from the raw request body.")]),e._v(" "),a("h5",{attrs:{id:"multipart"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#multipart"}},[e._v("#")]),e._v(" Multipart")]),e._v(" "),a("p",[a("code",[e._v("MultipartHttpMessageReader")]),e._v(" and "),a("code",[e._v("MultipartHttpMessageWriter")]),e._v(' support decoding and\nencoding "multipart/form-data" content. In turn '),a("code",[e._v("MultipartHttpMessageReader")]),e._v(" delegates to\nanother "),a("code",[e._v("HttpMessageReader")]),e._v(" for the actual parsing to a "),a("code",[e._v("Flux<Part>")]),e._v(" and then simply\ncollects the parts into a "),a("code",[e._v("MultiValueMap")]),e._v(".\nBy default, the "),a("code",[e._v("DefaultPartHttpMessageReader")]),e._v(" is used, but this can be changed through the"),a("code",[e._v("ServerCodecConfigurer")]),e._v(".\nFor more information about the "),a("code",[e._v("DefaultPartHttpMessageReader")]),e._v(", refer to to the"),a("a",{attrs:{href:"https://docs.spring.io/spring-framework/docs/5.3.16/javadoc-api/org/springframework/http/codec/multipart/DefaultPartHttpMessageReader.html",target:"_blank",rel:"noopener noreferrer"}},[e._v("javadoc of "),a("code",[e._v("DefaultPartHttpMessageReader")]),a("OutboundLink")],1),e._v(".")]),e._v(" "),a("p",[e._v("On the server side where multipart form content may need to be accessed from multiple\nplaces, "),a("code",[e._v("ServerWebExchange")]),e._v(" provides a dedicated "),a("code",[e._v("getMultipartData()")]),e._v(" method that parses\nthe content through "),a("code",[e._v("MultipartHttpMessageReader")]),e._v(" and then caches the result for repeated access.\nSee "),a("a",{attrs:{href:"#webflux-multipart"}},[e._v("Multipart Data")]),e._v(" in the "),a("a",{attrs:{href:"#webflux-web-handler-api"}},[a("code",[e._v("WebHandler")]),e._v(" API")]),e._v(" section.")]),e._v(" "),a("p",[e._v("Once "),a("code",[e._v("getMultipartData()")]),e._v(" is used, the original raw content can no longer be read from the\nrequest body. For this reason applications have to consistently use "),a("code",[e._v("getMultipartData()")]),e._v("for repeated, map-like access to parts, or otherwise rely on the"),a("code",[e._v("SynchronossPartHttpMessageReader")]),e._v(" for a one-time access to "),a("code",[e._v("Flux<Part>")]),e._v(".")]),e._v(" "),a("h5",{attrs:{id:"limits"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#limits"}},[e._v("#")]),e._v(" Limits")]),e._v(" "),a("p",[a("code",[e._v("Decoder")]),e._v(" and "),a("code",[e._v("HttpMessageReader")]),e._v(" implementations that buffer some or all of the input\nstream can be configured with a limit on the maximum number of bytes to buffer in memory.\nIn some cases buffering occurs because input is aggregated and represented as a single\nobject — for example, a controller method with "),a("code",[e._v("@RequestBody byte[]")]),e._v(","),a("code",[e._v("x-www-form-urlencoded")]),e._v(" data, and so on. Buffering can also occur with streaming, when\nsplitting the input stream — for example, delimited text, a stream of JSON objects, and\nso on. For those streaming cases, the limit applies to the number of bytes associated\nwith one object in the stream.")]),e._v(" "),a("p",[e._v("To configure buffer sizes, you can check if a given "),a("code",[e._v("Decoder")]),e._v(" or "),a("code",[e._v("HttpMessageReader")]),e._v("exposes a "),a("code",[e._v("maxInMemorySize")]),e._v(" property and if so the Javadoc will have details about default\nvalues. On the server side, "),a("code",[e._v("ServerCodecConfigurer")]),e._v(" provides a single place from where to\nset all codecs, see "),a("a",{attrs:{href:"#webflux-config-message-codecs"}},[e._v("HTTP message codecs")]),e._v(". On the client side, the limit for\nall codecs can be changed in"),a("a",{attrs:{href:"#webflux-client-builder-maxinmemorysize"}},[e._v("WebClient.Builder")]),e._v(".")]),e._v(" "),a("p",[e._v("For "),a("a",{attrs:{href:"#webflux-codecs-multipart"}},[e._v("Multipart parsing")]),e._v(" the "),a("code",[e._v("maxInMemorySize")]),e._v(" property limits\nthe size of non-file parts. For file parts, it determines the threshold at which the part\nis written to disk. For file parts written to disk, there is an additional"),a("code",[e._v("maxDiskUsagePerPart")]),e._v(" property to limit the amount of disk space per part. There is also\na "),a("code",[e._v("maxParts")]),e._v(" property to limit the overall number of parts in a multipart request.\nTo configure all three in WebFlux, you’ll need to supply a pre-configured instance of"),a("code",[e._v("MultipartHttpMessageReader")]),e._v(" to "),a("code",[e._v("ServerCodecConfigurer")]),e._v(".")]),e._v(" "),a("h5",{attrs:{id:"streaming"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#streaming"}},[e._v("#")]),e._v(" Streaming")]),e._v(" "),a("p",[a("RouterLink",{attrs:{to:"/en/spring-framework/web.html#mvc-ann-async-http-streaming"}},[e._v("Web MVC")])],1),e._v(" "),a("p",[e._v("When streaming to the HTTP response (for example, "),a("code",[e._v("text/event-stream")]),e._v(","),a("code",[e._v("application/x-ndjson")]),e._v('), it is important to send data periodically, in order to\nreliably detect a disconnected client sooner rather than later. Such a send could be a\ncomment-only, empty SSE event or any other "no-op" data that would effectively serve as\na heartbeat.')]),e._v(" "),a("h5",{attrs:{id:"databuffer"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#databuffer"}},[e._v("#")]),e._v(" "),a("code",[e._v("DataBuffer")])]),e._v(" "),a("p",[a("code",[e._v("DataBuffer")]),e._v(" is the representation for a byte buffer in WebFlux. The Spring Core part of\nthis reference has more on that in the section on"),a("RouterLink",{attrs:{to:"/en/spring-framework/core.html#databuffers"}},[e._v("Data Buffers and Codecs")]),e._v(". The key point to understand is that on some\nservers like Netty, byte buffers are pooled and reference counted, and must be released\nwhen consumed to avoid memory leaks.")],1),e._v(" "),a("p",[e._v("WebFlux applications generally do not need to be concerned with such issues, unless they\nconsume or produce data buffers directly, as opposed to relying on codecs to convert to\nand from higher level objects, or unless they choose to create custom codecs. For such\ncases please review the information in "),a("RouterLink",{attrs:{to:"/en/spring-framework/core.html#databuffers"}},[e._v("Data Buffers and Codecs")]),e._v(",\nespecially the section on "),a("RouterLink",{attrs:{to:"/en/spring-framework/core.html#databuffers-using"}},[e._v("Using DataBuffer")]),e._v(".")],1),e._v(" "),a("h4",{attrs:{id:"_1-2-6-logging"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_1-2-6-logging"}},[e._v("#")]),e._v(" 1.2.6. Logging")]),e._v(" "),a("p",[a("RouterLink",{attrs:{to:"/en/spring-framework/web.html#mvc-logging"}},[e._v("Web MVC")])],1),e._v(" "),a("p",[a("code",[e._v("DEBUG")]),e._v(" level logging in Spring WebFlux is designed to be compact, minimal, and\nhuman-friendly. It focuses on high value bits of information that are useful over and\nover again vs others that are useful only when debugging a specific issue.")]),e._v(" "),a("p",[a("code",[e._v("TRACE")]),e._v(" level logging generally follows the same principles as "),a("code",[e._v("DEBUG")]),e._v(" (and for example also\nshould not be a firehose) but can be used for debugging any issue. In addition, some log\nmessages may show a different level of detail at "),a("code",[e._v("TRACE")]),e._v(" vs "),a("code",[e._v("DEBUG")]),e._v(".")]),e._v(" "),a("p",[e._v("Good logging comes from the experience of using the logs. If you spot anything that does\nnot meet the stated goals, please let us know.")]),e._v(" "),a("h5",{attrs:{id:"log-id"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#log-id"}},[e._v("#")]),e._v(" Log Id")]),e._v(" "),a("p",[e._v("In WebFlux, a single request can be run over multiple threads and the thread ID\nis not useful for correlating log messages that belong to a specific request. This is why\nWebFlux log messages are prefixed with a request-specific ID by default.")]),e._v(" "),a("p",[e._v("On the server side, the log ID is stored in the "),a("code",[e._v("ServerWebExchange")]),e._v(" attribute\n("),a("a",{attrs:{href:"https://docs.spring.io/spring-framework/docs/5.3.16/javadoc-api/org/springframework/web/server/ServerWebExchange.html#LOG_ID_ATTRIBUTE",target:"_blank",rel:"noopener noreferrer"}},[a("code",[e._v("LOG_ID_ATTRIBUTE")]),a("OutboundLink")],1),e._v("),\nwhile a fully formatted prefix based on that ID is available from"),a("code",[e._v("ServerWebExchange#getLogPrefix()")]),e._v(". On the "),a("code",[e._v("WebClient")]),e._v(" side, the log ID is stored in the"),a("code",[e._v("ClientRequest")]),e._v(" attribute\n("),a("a",{attrs:{href:"https://docs.spring.io/spring-framework/docs/5.3.16/javadoc-api/org/springframework/web/reactive/function/client/ClientRequest.html#LOG_ID_ATTRIBUTE",target:"_blank",rel:"noopener noreferrer"}},[a("code",[e._v("LOG_ID_ATTRIBUTE")]),a("OutboundLink")],1),e._v(")\n,while a fully formatted prefix is available from "),a("code",[e._v("ClientRequest#logPrefix()")]),e._v(".")]),e._v(" "),a("h5",{attrs:{id:"sensitive-data"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#sensitive-data"}},[e._v("#")]),e._v(" Sensitive Data")]),e._v(" "),a("p",[a("RouterLink",{attrs:{to:"/en/spring-framework/web.html#mvc-logging-sensitive-data"}},[e._v("Web MVC")])],1),e._v(" "),a("p",[a("code",[e._v("DEBUG")]),e._v(" and "),a("code",[e._v("TRACE")]),e._v(" logging can log sensitive information. This is why form parameters and\nheaders are masked by default and you must explicitly enable their logging in full.")]),e._v(" "),a("p",[e._v("The following example shows how to do so for server-side requests:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("@Configuration\n@EnableWebFlux\nclass MyConfig implements WebFluxConfigurer {\n\n    @Override\n    public void configureHttpMessageCodecs(ServerCodecConfigurer configurer) {\n        configurer.defaultCodecs().enableLoggingRequestDetails(true);\n    }\n}\n")])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("@Configuration\n@EnableWebFlux\nclass MyConfig : WebFluxConfigurer {\n\n    override fun configureHttpMessageCodecs(configurer: ServerCodecConfigurer) {\n        configurer.defaultCodecs().enableLoggingRequestDetails(true)\n    }\n}\n")])])]),a("p",[e._v("The following example shows how to do so for client-side requests:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("Consumer<ClientCodecConfigurer> consumer = configurer ->\n        configurer.defaultCodecs().enableLoggingRequestDetails(true);\n\nWebClient webClient = WebClient.builder()\n        .exchangeStrategies(strategies -> strategies.codecs(consumer))\n        .build();\n")])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("val consumer: (ClientCodecConfigurer) -> Unit  = { configurer -> configurer.defaultCodecs().enableLoggingRequestDetails(true) }\n\nval webClient = WebClient.builder()\n        .exchangeStrategies({ strategies -> strategies.codecs(consumer) })\n        .build()\n")])])]),a("h5",{attrs:{id:"appenders"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#appenders"}},[e._v("#")]),e._v(" Appenders")]),e._v(" "),a("p",[e._v("Logging libraries such as SLF4J and Log4J 2 provide asynchronous loggers that avoid\nblocking. While those have their own drawbacks such as potentially dropping messages\nthat could not be queued for logging, they are the best available options currently\nfor use in a reactive, non-blocking application.")]),e._v(" "),a("h5",{attrs:{id:"custom-codecs"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#custom-codecs"}},[e._v("#")]),e._v(" Custom codecs")]),e._v(" "),a("p",[e._v("Applications can register custom codecs for supporting additional media types,\nor specific behaviors that are not supported by the default codecs.")]),e._v(" "),a("p",[e._v("Some configuration options expressed by developers are enforced on default codecs.\nCustom codecs might want to get a chance to align with those preferences,\nlike "),a("a",{attrs:{href:"#webflux-codecs-limits"}},[e._v("enforcing buffering limits")]),e._v("or "),a("a",{attrs:{href:"#webflux-logging-sensitive-data"}},[e._v("logging sensitive data")]),e._v(".")]),e._v(" "),a("p",[e._v("The following example shows how to do so for client-side requests:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("WebClient webClient = WebClient.builder()\n        .codecs(configurer -> {\n                CustomDecoder decoder = new CustomDecoder();\n                configurer.customCodecs().registerWithDefaultConfig(decoder);\n        })\n        .build();\n")])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("val webClient = WebClient.builder()\n        .codecs({ configurer ->\n                val decoder = CustomDecoder()\n                configurer.customCodecs().registerWithDefaultConfig(decoder)\n         })\n        .build()\n")])])]),a("h3",{attrs:{id:"_1-3-dispatcherhandler"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_1-3-dispatcherhandler"}},[e._v("#")]),e._v(" 1.3. "),a("code",[e._v("DispatcherHandler")])]),e._v(" "),a("p",[a("RouterLink",{attrs:{to:"/en/spring-framework/web.html#mvc-servlet"}},[e._v("Web MVC")])],1),e._v(" "),a("p",[e._v("Spring WebFlux, similarly to Spring MVC, is designed around the front controller pattern,\nwhere a central "),a("code",[e._v("WebHandler")]),e._v(", the "),a("code",[e._v("DispatcherHandler")]),e._v(", provides a shared algorithm for\nrequest processing, while actual work is performed by configurable, delegate components.\nThis model is flexible and supports diverse workflows.")]),e._v(" "),a("p",[a("code",[e._v("DispatcherHandler")]),e._v(" discovers the delegate components it needs from Spring configuration.\nIt is also designed to be a Spring bean itself and implements "),a("code",[e._v("ApplicationContextAware")]),e._v("for access to the context in which it runs. If "),a("code",[e._v("DispatcherHandler")]),e._v(" is declared with a bean\nname of "),a("code",[e._v("webHandler")]),e._v(", it is, in turn, discovered by"),a("a",{attrs:{href:"https://docs.spring.io/spring-framework/docs/5.3.16/javadoc-api/org/springframework/web/server/adapter/WebHttpHandlerBuilder.html",target:"_blank",rel:"noopener noreferrer"}},[a("code",[e._v("WebHttpHandlerBuilder")]),a("OutboundLink")],1),e._v(",\nwhich puts together a request-processing chain, as described in "),a("a",{attrs:{href:"#webflux-web-handler-api"}},[a("code",[e._v("WebHandler")]),e._v(" API")]),e._v(".")]),e._v(" "),a("p",[e._v("Spring configuration in a WebFlux application typically contains:")]),e._v(" "),a("ul",[a("li",[a("p",[a("code",[e._v("DispatcherHandler")]),e._v(" with the bean name "),a("code",[e._v("webHandler")])])]),e._v(" "),a("li",[a("p",[a("code",[e._v("WebFilter")]),e._v(" and "),a("code",[e._v("WebExceptionHandler")]),e._v(" beans")])]),e._v(" "),a("li",[a("p",[a("a",{attrs:{href:"#webflux-special-bean-types"}},[a("code",[e._v("DispatcherHandler")]),e._v(" special beans")])])]),e._v(" "),a("li",[a("p",[e._v("Others")])])]),e._v(" "),a("p",[e._v("The configuration is given to "),a("code",[e._v("WebHttpHandlerBuilder")]),e._v(" to build the processing chain,\nas the following example shows:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("ApplicationContext context = ...\nHttpHandler handler = WebHttpHandlerBuilder.applicationContext(context).build();\n")])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("val context: ApplicationContext = ...\nval handler = WebHttpHandlerBuilder.applicationContext(context).build()\n")])])]),a("p",[e._v("The resulting "),a("code",[e._v("HttpHandler")]),e._v(" is ready for use with a "),a("a",{attrs:{href:"#webflux-httphandler"}},[e._v("server adapter")]),e._v(".")]),e._v(" "),a("h4",{attrs:{id:"_1-3-1-special-bean-types"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_1-3-1-special-bean-types"}},[e._v("#")]),e._v(" 1.3.1. Special Bean Types")]),e._v(" "),a("p",[a("RouterLink",{attrs:{to:"/en/spring-framework/web.html#mvc-servlet-special-bean-types"}},[e._v("Web MVC")])],1),e._v(" "),a("p",[e._v("The "),a("code",[e._v("DispatcherHandler")]),e._v(" delegates to special beans to process requests and render the\nappropriate responses. By “special beans,” we mean Spring-managed "),a("code",[e._v("Object")]),e._v(" instances that\nimplement WebFlux framework contracts. Those usually come with built-in contracts, but\nyou can customize their properties, extend them, or replace them.")]),e._v(" "),a("p",[e._v("The following table lists the special beans detected by the "),a("code",[e._v("DispatcherHandler")]),e._v(". Note that\nthere are also some other beans detected at a lower level (see"),a("a",{attrs:{href:"#webflux-web-handler-api-special-beans"}},[e._v("Special bean types")]),e._v(" in the Web Handler API).")]),e._v(" "),a("table",[a("thead",[a("tr",[a("th",[e._v("Bean type")]),e._v(" "),a("th",[e._v("Explanation")])])]),e._v(" "),a("tbody",[a("tr",[a("td",[a("code",[e._v("HandlerMapping")])]),e._v(" "),a("td",[e._v("Map a request to a handler. The mapping is based on some criteria, the details of"),a("br"),e._v("which vary by "),a("code",[e._v("HandlerMapping")]),e._v(" implementation — annotated controllers, simple"),a("br"),e._v("URL pattern mappings, and others."),a("br"),a("br"),e._v(" The main "),a("code",[e._v("HandlerMapping")]),e._v(" implementations are "),a("code",[e._v("RequestMappingHandlerMapping")]),e._v(" for"),a("code",[e._v("@RequestMapping")]),e._v(" annotated methods, "),a("code",[e._v("RouterFunctionMapping")]),e._v(" for functional endpoint"),a("br"),e._v("routes, and "),a("code",[e._v("SimpleUrlHandlerMapping")]),e._v(" for explicit registrations of URI path patterns"),a("br"),e._v("and "),a("code",[e._v("WebHandler")]),e._v(" instances.")])]),e._v(" "),a("tr",[a("td",[a("code",[e._v("HandlerAdapter")])]),e._v(" "),a("td",[e._v("Help the "),a("code",[e._v("DispatcherHandler")]),e._v(" to invoke a handler mapped to a request regardless of"),a("br"),e._v("how the handler is actually invoked. For example, invoking an annotated controller"),a("br"),e._v("requires resolving annotations. The main purpose of a "),a("code",[e._v("HandlerAdapter")]),e._v(" is to shield the"),a("code",[e._v("DispatcherHandler")]),e._v(" from such details.")])]),e._v(" "),a("tr",[a("td",[a("code",[e._v("HandlerResultHandler")])]),e._v(" "),a("td",[e._v("Process the result from the handler invocation and finalize the response."),a("br"),e._v("See "),a("a",{attrs:{href:"#webflux-resulthandling"}},[e._v("Result Handling")]),e._v(".")])])])]),e._v(" "),a("h4",{attrs:{id:"_1-3-2-webflux-config"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_1-3-2-webflux-config"}},[e._v("#")]),e._v(" 1.3.2. WebFlux Config")]),e._v(" "),a("p",[a("RouterLink",{attrs:{to:"/en/spring-framework/web.html#mvc-servlet-config"}},[e._v("Web MVC")])],1),e._v(" "),a("p",[e._v("Applications can declare the infrastructure beans (listed under"),a("a",{attrs:{href:"#webflux-web-handler-api-special-beans"}},[e._v("Web Handler API")]),e._v(" and"),a("a",{attrs:{href:"#webflux-special-bean-types"}},[a("code",[e._v("DispatcherHandler")])]),e._v(") that are required to process requests.\nHowever, in most cases, the "),a("a",{attrs:{href:"#webflux-config"}},[e._v("WebFlux Config")]),e._v(" is the best starting point. It declares the\nrequired beans and provides a higher-level configuration callback API to customize it.")]),e._v(" "),a("table",[a("thead",[a("tr",[a("th"),e._v(" "),a("th",[e._v("Spring Boot relies on the WebFlux config to configure Spring WebFlux and also provides"),a("br"),e._v("many extra convenient options.")])])]),e._v(" "),a("tbody")]),e._v(" "),a("h4",{attrs:{id:"_1-3-3-processing"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_1-3-3-processing"}},[e._v("#")]),e._v(" 1.3.3. Processing")]),e._v(" "),a("p",[a("RouterLink",{attrs:{to:"/en/spring-framework/web.html#mvc-servlet-sequence"}},[e._v("Web MVC")])],1),e._v(" "),a("p",[a("code",[e._v("DispatcherHandler")]),e._v(" processes requests as follows:")]),e._v(" "),a("ul",[a("li",[a("p",[e._v("Each "),a("code",[e._v("HandlerMapping")]),e._v(" is asked to find a matching handler, and the first match is used.")])]),e._v(" "),a("li",[a("p",[e._v("If a handler is found, it is run through an appropriate "),a("code",[e._v("HandlerAdapter")]),e._v(", which\nexposes the return value from the execution as "),a("code",[e._v("HandlerResult")]),e._v(".")])]),e._v(" "),a("li",[a("p",[e._v("The "),a("code",[e._v("HandlerResult")]),e._v(" is given to an appropriate "),a("code",[e._v("HandlerResultHandler")]),e._v(" to complete\nprocessing by writing to the response directly or by using a view to render.")])])]),e._v(" "),a("h4",{attrs:{id:"_1-3-4-result-handling"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_1-3-4-result-handling"}},[e._v("#")]),e._v(" 1.3.4. Result Handling")]),e._v(" "),a("p",[e._v("The return value from the invocation of a handler, through a "),a("code",[e._v("HandlerAdapter")]),e._v(", is wrapped\nas a "),a("code",[e._v("HandlerResult")]),e._v(", along with some additional context, and passed to the first"),a("code",[e._v("HandlerResultHandler")]),e._v(" that claims support for it. The following table shows the available"),a("code",[e._v("HandlerResultHandler")]),e._v(" implementations, all of which are declared in the "),a("a",{attrs:{href:"#webflux-config"}},[e._v("WebFlux Config")]),e._v(":")]),e._v(" "),a("table",[a("thead",[a("tr",[a("th",[e._v("Result Handler Type")]),e._v(" "),a("th",[e._v("Return Values")]),e._v(" "),a("th",[e._v("Default Order")])])]),e._v(" "),a("tbody",[a("tr",[a("td",[a("code",[e._v("ResponseEntityResultHandler")])]),e._v(" "),a("td",[a("code",[e._v("ResponseEntity")]),e._v(", typically from "),a("code",[e._v("@Controller")]),e._v(" instances.")]),e._v(" "),a("td",[e._v("0")])]),e._v(" "),a("tr",[a("td",[a("code",[e._v("ServerResponseResultHandler")])]),e._v(" "),a("td",[a("code",[e._v("ServerResponse")]),e._v(", typically from functional endpoints.")]),e._v(" "),a("td",[e._v("0")])]),e._v(" "),a("tr",[a("td",[a("code",[e._v("ResponseBodyResultHandler")])]),e._v(" "),a("td",[e._v("Handle return values from "),a("code",[e._v("@ResponseBody")]),e._v(" methods or "),a("code",[e._v("@RestController")]),e._v(" classes.")]),e._v(" "),a("td",[e._v("100")])]),e._v(" "),a("tr",[a("td",[a("code",[e._v("ViewResolutionResultHandler")])]),e._v(" "),a("td",[a("code",[e._v("CharSequence")]),e._v(", "),a("a",{attrs:{href:"https://docs.spring.io/spring-framework/docs/5.3.16/javadoc-api/org/springframework/web/reactive/result/view/View.html",target:"_blank",rel:"noopener noreferrer"}},[a("code",[e._v("View")]),a("OutboundLink")],1),e._v(","),a("a",{attrs:{href:"https://docs.spring.io/spring-framework/docs/5.3.16/javadoc-api/org/springframework/ui/Model.html",target:"_blank",rel:"noopener noreferrer"}},[e._v("Model"),a("OutboundLink")],1),e._v(", "),a("code",[e._v("Map")]),e._v(","),a("a",{attrs:{href:"https://docs.spring.io/spring-framework/docs/5.3.16/javadoc-api/org/springframework/web/reactive/result/view/Rendering.html",target:"_blank",rel:"noopener noreferrer"}},[e._v("Rendering"),a("OutboundLink")],1),e._v(","),a("br"),e._v("or any other "),a("code",[e._v("Object")]),e._v(" is treated as a model attribute."),a("br"),a("br"),e._v(" See also "),a("a",{attrs:{href:"#webflux-viewresolution"}},[e._v("View Resolution")]),e._v(".")]),e._v(" "),a("td",[a("code",[e._v("Integer.MAX_VALUE")])])])])]),e._v(" "),a("h4",{attrs:{id:"_1-3-5-exceptions"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_1-3-5-exceptions"}},[e._v("#")]),e._v(" 1.3.5. Exceptions")]),e._v(" "),a("p",[a("RouterLink",{attrs:{to:"/en/spring-framework/web.html#mvc-exceptionhandlers"}},[e._v("Web MVC")])],1),e._v(" "),a("p",[e._v("The "),a("code",[e._v("HandlerResult")]),e._v(" returned from a "),a("code",[e._v("HandlerAdapter")]),e._v(" can expose a function for error\nhandling based on some handler-specific mechanism. This error function is called if:")]),e._v(" "),a("ul",[a("li",[a("p",[e._v("The handler (for example, "),a("code",[e._v("@Controller")]),e._v(") invocation fails.")])]),e._v(" "),a("li",[a("p",[e._v("The handling of the handler return value through a "),a("code",[e._v("HandlerResultHandler")]),e._v(" fails.")])])]),e._v(" "),a("p",[e._v("The error function can change the response (for example, to an error status), as long as an error\nsignal occurs before the reactive type returned from the handler produces any data items.")]),e._v(" "),a("p",[e._v("This is how "),a("code",[e._v("@ExceptionHandler")]),e._v(" methods in "),a("code",[e._v("@Controller")]),e._v(" classes are supported.\nBy contrast, support for the same in Spring MVC is built on a "),a("code",[e._v("HandlerExceptionResolver")]),e._v(".\nThis generally should not matter. However, keep in mind that, in WebFlux, you cannot use a"),a("code",[e._v("@ControllerAdvice")]),e._v(" to handle exceptions that occur before a handler is chosen.")]),e._v(" "),a("p",[e._v("See also "),a("a",{attrs:{href:"#webflux-ann-controller-exceptions"}},[e._v("Managing Exceptions")]),e._v(" in the “Annotated Controller” section or"),a("a",{attrs:{href:"#webflux-exception-handler"}},[e._v("Exceptions")]),e._v(" in the WebHandler API section.")]),e._v(" "),a("h4",{attrs:{id:"_1-3-6-view-resolution"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_1-3-6-view-resolution"}},[e._v("#")]),e._v(" 1.3.6. View Resolution")]),e._v(" "),a("p",[a("RouterLink",{attrs:{to:"/en/spring-framework/web.html#mvc-viewresolver"}},[e._v("Web MVC")])],1),e._v(" "),a("p",[e._v("View resolution enables rendering to a browser with an HTML template and a model without\ntying you to a specific view technology. In Spring WebFlux, view resolution is\nsupported through a dedicated "),a("a",{attrs:{href:"#webflux-resulthandling"}},[e._v("HandlerResultHandler")]),e._v(" that uses"),a("code",[e._v("ViewResolver")]),e._v(" instances to map a String (representing a logical view name) to a "),a("code",[e._v("View")]),e._v("instance. The "),a("code",[e._v("View")]),e._v(" is then used to render the response.")]),e._v(" "),a("h5",{attrs:{id:"handling"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#handling"}},[e._v("#")]),e._v(" Handling")]),e._v(" "),a("p",[a("RouterLink",{attrs:{to:"/en/spring-framework/web.html#mvc-handling"}},[e._v("Web MVC")])],1),e._v(" "),a("p",[e._v("The "),a("code",[e._v("HandlerResult")]),e._v(" passed into "),a("code",[e._v("ViewResolutionResultHandler")]),e._v(" contains the return value\nfrom the handler and the model that contains attributes added during request\nhandling. The return value is processed as one of the following:")]),e._v(" "),a("ul",[a("li",[a("p",[a("code",[e._v("String")]),e._v(", "),a("code",[e._v("CharSequence")]),e._v(": A logical view name to be resolved to a "),a("code",[e._v("View")]),e._v(" through\nthe list of configured "),a("code",[e._v("ViewResolver")]),e._v(" implementations.")])]),e._v(" "),a("li",[a("p",[a("code",[e._v("void")]),e._v(": Select a default view name based on the request path, minus the leading and\ntrailing slash, and resolve it to a "),a("code",[e._v("View")]),e._v(". The same also happens when a view name\nwas not provided (for example, model attribute was returned) or an async return value\n(for example, "),a("code",[e._v("Mono")]),e._v(" completed empty).")])]),e._v(" "),a("li",[a("p",[a("a",{attrs:{href:"https://docs.spring.io/spring-framework/docs/5.3.16/javadoc-api/org/springframework/web/reactive/result/view/Rendering.html",target:"_blank",rel:"noopener noreferrer"}},[e._v("Rendering"),a("OutboundLink")],1),e._v(": API for\nview resolution scenarios. Explore the options in your IDE with code completion.")])]),e._v(" "),a("li",[a("p",[a("code",[e._v("Model")]),e._v(", "),a("code",[e._v("Map")]),e._v(": Extra model attributes to be added to the model for the request.")])]),e._v(" "),a("li",[a("p",[e._v("Any other: Any other return value (except for simple types, as determined by"),a("a",{attrs:{href:"https://docs.spring.io/spring-framework/docs/5.3.16/javadoc-api/org/springframework/beans/BeanUtils.html#isSimpleProperty-java.lang.Class-",target:"_blank",rel:"noopener noreferrer"}},[e._v("BeanUtils#isSimpleProperty"),a("OutboundLink")],1),e._v(")\nis treated as a model attribute to be added to the model. The attribute name is derived\nfrom the class name by using "),a("a",{attrs:{href:"https://docs.spring.io/spring-framework/docs/5.3.16/javadoc-api/org/springframework/core/Conventions.html",target:"_blank",rel:"noopener noreferrer"}},[e._v("conventions"),a("OutboundLink")],1),e._v(",\nunless a handler method "),a("code",[e._v("@ModelAttribute")]),e._v(" annotation is present.")])])]),e._v(" "),a("p",[e._v("The model can contain asynchronous, reactive types (for example, from Reactor or RxJava). Prior\nto rendering, "),a("code",[e._v("AbstractView")]),e._v(" resolves such model attributes into concrete values\nand updates the model. Single-value reactive types are resolved to a single\nvalue or no value (if empty), while multi-value reactive types (for example, "),a("code",[e._v("Flux<T>")]),e._v(") are\ncollected and resolved to "),a("code",[e._v("List<T>")]),e._v(".")]),e._v(" "),a("p",[e._v("To configure view resolution is as simple as adding a "),a("code",[e._v("ViewResolutionResultHandler")]),e._v(" bean\nto your Spring configuration. "),a("a",{attrs:{href:"#webflux-config-view-resolvers"}},[e._v("WebFlux Config")]),e._v(" provides a\ndedicated configuration API for view resolution.")]),e._v(" "),a("p",[e._v("See "),a("a",{attrs:{href:"#webflux-view"}},[e._v("View Technologies")]),e._v(" for more on the view technologies integrated with Spring WebFlux.")]),e._v(" "),a("h5",{attrs:{id:"redirecting"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#redirecting"}},[e._v("#")]),e._v(" Redirecting")]),e._v(" "),a("p",[a("RouterLink",{attrs:{to:"/en/spring-framework/web.html#mvc-redirecting-redirect-prefix"}},[e._v("Web MVC")])],1),e._v(" "),a("p",[e._v("The special "),a("code",[e._v("redirect:")]),e._v(" prefix in a view name lets you perform a redirect. The"),a("code",[e._v("UrlBasedViewResolver")]),e._v(" (and sub-classes) recognize this as an instruction that a\nredirect is needed. The rest of the view name is the redirect URL.")]),e._v(" "),a("p",[e._v("The net effect is the same as if the controller had returned a "),a("code",[e._v("RedirectView")]),e._v(" or"),a("code",[e._v('Rendering.redirectTo("abc").build()')]),e._v(", but now the controller itself can\noperate in terms of logical view names. A view name such as"),a("code",[e._v("redirect:/some/resource")]),e._v(" is relative to the current application, while a view name such as"),a("code",[e._v("redirect:https://example.com/arbitrary/path")]),e._v(" redirects to an absolute URL.")]),e._v(" "),a("h5",{attrs:{id:"content-negotiation"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#content-negotiation"}},[e._v("#")]),e._v(" Content Negotiation")]),e._v(" "),a("p",[a("RouterLink",{attrs:{to:"/en/spring-framework/web.html#mvc-multiple-representations"}},[e._v("Web MVC")])],1),e._v(" "),a("p",[a("code",[e._v("ViewResolutionResultHandler")]),e._v(" supports content negotiation. It compares the request\nmedia types with the media types supported by each selected "),a("code",[e._v("View")]),e._v(". The first "),a("code",[e._v("View")]),e._v("that supports the requested media type(s) is used.")]),e._v(" "),a("p",[e._v("In order to support media types such as JSON and XML, Spring WebFlux provides"),a("code",[e._v("HttpMessageWriterView")]),e._v(", which is a special "),a("code",[e._v("View")]),e._v(" that renders through an"),a("a",{attrs:{href:"#webflux-codecs"}},[e._v("HttpMessageWriter")]),e._v(". Typically, you would configure these as default\nviews through the "),a("a",{attrs:{href:"#webflux-config-view-resolvers"}},[e._v("WebFlux Configuration")]),e._v(". Default views are\nalways selected and used if they match the requested media type.")]),e._v(" "),a("h3",{attrs:{id:"_1-4-annotated-controllers"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_1-4-annotated-controllers"}},[e._v("#")]),e._v(" 1.4. Annotated Controllers")]),e._v(" "),a("p",[a("RouterLink",{attrs:{to:"/en/spring-framework/web.html#mvc-controller"}},[e._v("Web MVC")])],1),e._v(" "),a("p",[e._v("Spring WebFlux provides an annotation-based programming model, where "),a("code",[e._v("@Controller")]),e._v(" and"),a("code",[e._v("@RestController")]),e._v(" components use annotations to express request mappings, request input,\nhandle exceptions, and more. Annotated controllers have flexible method signatures and\ndo not have to extend base classes nor implement specific interfaces.")]),e._v(" "),a("p",[e._v("The following listing shows a basic example:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('@RestController\npublic class HelloController {\n\n    @GetMapping("/hello")\n    public String handle() {\n        return "Hello WebFlux";\n    }\n}\n')])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('@RestController\nclass HelloController {\n\n    @GetMapping("/hello")\n    fun handle() = "Hello WebFlux"\n}\n')])])]),a("p",[e._v("In the preceding example, the method returns a "),a("code",[e._v("String")]),e._v(" to be written to the response body.")]),e._v(" "),a("h4",{attrs:{id:"_1-4-1-controller"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_1-4-1-controller"}},[e._v("#")]),e._v(" 1.4.1. "),a("code",[e._v("@Controller")])]),e._v(" "),a("p",[a("RouterLink",{attrs:{to:"/en/spring-framework/web.html#mvc-ann-controller"}},[e._v("Web MVC")])],1),e._v(" "),a("p",[e._v("You can define controller beans by using a standard Spring bean definition.\nThe "),a("code",[e._v("@Controller")]),e._v(" stereotype allows for auto-detection and is aligned with Spring general support\nfor detecting "),a("code",[e._v("@Component")]),e._v(" classes in the classpath and auto-registering bean definitions\nfor them. It also acts as a stereotype for the annotated class, indicating its role as\na web component.")]),e._v(" "),a("p",[e._v("To enable auto-detection of such "),a("code",[e._v("@Controller")]),e._v(" beans, you can add component scanning to\nyour Java configuration, as the following example shows:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('@Configuration\n@ComponentScan("org.example.web") (1)\npublic class WebConfig {\n\n    // ...\n}\n')])])]),a("table",[a("thead",[a("tr",[a("th",[a("strong",[e._v("1")])]),e._v(" "),a("th",[e._v("Scan the "),a("code",[e._v("org.example.web")]),e._v(" package.")])])]),e._v(" "),a("tbody")]),e._v(" "),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('@Configuration\n@ComponentScan("org.example.web") (1)\nclass WebConfig {\n\n    // ...\n}\n')])])]),a("table",[a("thead",[a("tr",[a("th",[a("strong",[e._v("1")])]),e._v(" "),a("th",[e._v("Scan the "),a("code",[e._v("org.example.web")]),e._v(" package.")])])]),e._v(" "),a("tbody")]),e._v(" "),a("p",[a("code",[e._v("@RestController")]),e._v(" is a "),a("RouterLink",{attrs:{to:"/en/spring-framework/core.html#beans-meta-annotations"}},[e._v("composed annotation")]),e._v(" that is\nitself meta-annotated with "),a("code",[e._v("@Controller")]),e._v(" and "),a("code",[e._v("@ResponseBody")]),e._v(", indicating a controller whose\nevery method inherits the type-level "),a("code",[e._v("@ResponseBody")]),e._v(" annotation and, therefore, writes\ndirectly to the response body versus view resolution and rendering with an HTML template.")],1),e._v(" "),a("h4",{attrs:{id:"_1-4-2-request-mapping"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_1-4-2-request-mapping"}},[e._v("#")]),e._v(" 1.4.2. Request Mapping")]),e._v(" "),a("p",[a("RouterLink",{attrs:{to:"/en/spring-framework/web.html#mvc-ann-requestmapping"}},[e._v("Web MVC")])],1),e._v(" "),a("p",[e._v("The "),a("code",[e._v("@RequestMapping")]),e._v(" annotation is used to map requests to controllers methods. It has\nvarious attributes to match by URL, HTTP method, request parameters, headers, and media\ntypes. You can use it at the class level to express shared mappings or at the method level\nto narrow down to a specific endpoint mapping.")]),e._v(" "),a("p",[e._v("There are also HTTP method specific shortcut variants of "),a("code",[e._v("@RequestMapping")]),e._v(":")]),e._v(" "),a("ul",[a("li",[a("p",[a("code",[e._v("@GetMapping")])])]),e._v(" "),a("li",[a("p",[a("code",[e._v("@PostMapping")])])]),e._v(" "),a("li",[a("p",[a("code",[e._v("@PutMapping")])])]),e._v(" "),a("li",[a("p",[a("code",[e._v("@DeleteMapping")])])]),e._v(" "),a("li",[a("p",[a("code",[e._v("@PatchMapping")])])])]),e._v(" "),a("p",[e._v("The preceding annotations are "),a("a",{attrs:{href:"#webflux-ann-requestmapping-composed"}},[e._v("Custom Annotations")]),e._v(" that are provided\nbecause, arguably, most controller methods should be mapped to a specific HTTP method versus\nusing "),a("code",[e._v("@RequestMapping")]),e._v(", which, by default, matches to all HTTP methods. At the same time, a"),a("code",[e._v("@RequestMapping")]),e._v(" is still needed at the class level to express shared mappings.")]),e._v(" "),a("p",[e._v("The following example uses type and method level mappings:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('@RestController\n@RequestMapping("/persons")\nclass PersonController {\n\n    @GetMapping("/{id}")\n    public Person getPerson(@PathVariable Long id) {\n        // ...\n    }\n\n    @PostMapping\n    @ResponseStatus(HttpStatus.CREATED)\n    public void add(@RequestBody Person person) {\n        // ...\n    }\n}\n')])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('@RestController\n@RequestMapping("/persons")\nclass PersonController {\n\n    @GetMapping("/{id}")\n    fun getPerson(@PathVariable id: Long): Person {\n        // ...\n    }\n\n    @PostMapping\n    @ResponseStatus(HttpStatus.CREATED)\n    fun add(@RequestBody person: Person) {\n        // ...\n    }\n}\n')])])]),a("h5",{attrs:{id:"uri-patterns"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#uri-patterns"}},[e._v("#")]),e._v(" URI Patterns")]),e._v(" "),a("p",[a("RouterLink",{attrs:{to:"/en/spring-framework/web.html#mvc-ann-requestmapping-uri-templates"}},[e._v("Web MVC")])],1),e._v(" "),a("p",[e._v("You can map requests by using glob patterns and wildcards:")]),e._v(" "),a("table",[a("thead",[a("tr",[a("th",[e._v("Pattern")]),e._v(" "),a("th",[e._v("Description")]),e._v(" "),a("th",[e._v("Example")])])]),e._v(" "),a("tbody",[a("tr",[a("td",[a("code",[e._v("?")])]),e._v(" "),a("td",[e._v("Matches one character")]),e._v(" "),a("td",[a("code",[e._v('"/pages/t?st.html"')]),e._v(" matches "),a("code",[e._v('"/pages/test.html"')]),e._v(" and "),a("code",[e._v('"/pages/t3st.html"')])])]),e._v(" "),a("tr",[a("td",[a("code",[e._v("*")])]),e._v(" "),a("td",[e._v("Matches zero or more characters within a path segment")]),e._v(" "),a("td",[a("code",[e._v('"/resources/*.png"')]),e._v(" matches "),a("code",[e._v('"/resources/file.png"')]),a("br"),a("br"),a("code",[e._v('"/projects/*/versions"')]),e._v(" matches "),a("code",[e._v('"/projects/spring/versions"')]),e._v(" but does not match "),a("code",[e._v('"/projects/spring/boot/versions"')])])]),e._v(" "),a("tr",[a("td",[a("code",[e._v("**")])]),e._v(" "),a("td",[e._v("Matches zero or more path segments until the end of the path")]),e._v(" "),a("td",[a("code",[e._v('"/resources/**"')]),e._v(" matches "),a("code",[e._v('"/resources/file.png"')]),e._v(" and "),a("code",[e._v('"/resources/images/file.png"')]),a("br"),a("br"),a("code",[e._v('"/resources/**/file.png"')]),e._v(" is invalid as "),a("code",[e._v("**")]),e._v(" is only allowed at the end of the path.")])]),e._v(" "),a("tr",[a("td",[a("code",[e._v("{name}")])]),e._v(" "),a("td",[e._v('Matches a path segment and captures it as a variable named "name"')]),e._v(" "),a("td",[a("code",[e._v('"/projects/{project}/versions"')]),e._v(" matches "),a("code",[e._v('"/projects/spring/versions"')]),e._v(" and captures "),a("code",[e._v("project=spring")])])]),e._v(" "),a("tr",[a("td",[a("code",[e._v("{name:[a-z]+}")])]),e._v(" "),a("td",[e._v("Matches the regexp "),a("code",[e._v('"[a-z]+"')]),e._v(' as a path variable named "name"')]),e._v(" "),a("td",[a("code",[e._v('"/projects/{project:[a-z]+}/versions"')]),e._v(" matches "),a("code",[e._v('"/projects/spring/versions"')]),e._v(" but not "),a("code",[e._v('"/projects/spring1/versions"')])])]),e._v(" "),a("tr",[a("td",[a("code",[e._v("{*path}")])]),e._v(" "),a("td",[e._v('Matches zero or more path segments until the end of the path and captures it as a variable named "path"')]),e._v(" "),a("td",[a("code",[e._v('"/resources/{*file}"')]),e._v(" matches "),a("code",[e._v('"/resources/images/file.png"')]),e._v(" and captures "),a("code",[e._v("file=/images/file.png")])])])])]),e._v(" "),a("p",[e._v("Captured URI variables can be accessed with "),a("code",[e._v("@PathVariable")]),e._v(", as the following example shows:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('@GetMapping("/owners/{ownerId}/pets/{petId}")\npublic Pet findPet(@PathVariable Long ownerId, @PathVariable Long petId) {\n    // ...\n}\n')])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('@GetMapping("/owners/{ownerId}/pets/{petId}")\nfun findPet(@PathVariable ownerId: Long, @PathVariable petId: Long): Pet {\n    // ...\n}\n')])])]),a("p",[e._v("You can declare URI variables at the class and method levels, as the following example shows:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('@Controller\n@RequestMapping("/owners/{ownerId}") (1)\npublic class OwnerController {\n\n    @GetMapping("/pets/{petId}") (2)\n    public Pet findPet(@PathVariable Long ownerId, @PathVariable Long petId) {\n        // ...\n    }\n}\n')])])]),a("table",[a("thead",[a("tr",[a("th",[a("strong",[e._v("1")])]),e._v(" "),a("th",[e._v("Class-level URI mapping.")])])]),e._v(" "),a("tbody",[a("tr",[a("td",[a("strong",[e._v("2")])]),e._v(" "),a("td",[e._v("Method-level URI mapping.")])])])]),e._v(" "),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('@Controller\n@RequestMapping("/owners/{ownerId}") (1)\nclass OwnerController {\n\n    @GetMapping("/pets/{petId}") (2)\n    fun findPet(@PathVariable ownerId: Long, @PathVariable petId: Long): Pet {\n        // ...\n    }\n}\n')])])]),a("table",[a("thead",[a("tr",[a("th",[a("strong",[e._v("1")])]),e._v(" "),a("th",[e._v("Class-level URI mapping.")])])]),e._v(" "),a("tbody",[a("tr",[a("td",[a("strong",[e._v("2")])]),e._v(" "),a("td",[e._v("Method-level URI mapping.")])])])]),e._v(" "),a("p",[e._v("URI variables are automatically converted to the appropriate type or a "),a("code",[e._v("TypeMismatchException")]),e._v("is raised. Simple types ("),a("code",[e._v("int")]),e._v(", "),a("code",[e._v("long")]),e._v(", "),a("code",[e._v("Date")]),e._v(", and so on) are supported by default and you can\nregister support for any other data type.\nSee "),a("a",{attrs:{href:"#webflux-ann-typeconversion"}},[e._v("Type Conversion")]),e._v(" and "),a("a",{attrs:{href:"#webflux-ann-initbinder"}},[a("code",[e._v("DataBinder")])]),e._v(".")]),e._v(" "),a("p",[e._v("URI variables can be named explicitly (for example, "),a("code",[e._v('@PathVariable("customId")')]),e._v("), but you can\nleave that detail out if the names are the same and you compile your code with debugging\ninformation or with the "),a("code",[e._v("-parameters")]),e._v(" compiler flag on Java 8.")]),e._v(" "),a("p",[e._v("The syntax "),a("code",[e._v("{*varName}")]),e._v(" declares a URI variable that matches zero or more remaining path\nsegments. For example "),a("code",[e._v("/resources/{*path}")]),e._v(" matches all files under "),a("code",[e._v("/resources/")]),e._v(", and the"),a("code",[e._v('"path"')]),e._v(" variable captures the complete path under "),a("code",[e._v("/resources")]),e._v(".")]),e._v(" "),a("p",[e._v("The syntax "),a("code",[e._v("{varName:regex}")]),e._v(" declares a URI variable with a regular expression that has the\nsyntax: "),a("code",[e._v("{varName:regex}")]),e._v(". For example, given a URL of "),a("code",[e._v("/spring-web-3.0.5.jar")]),e._v(", the following method\nextracts the name, version, and file extension:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('@GetMapping("/{name:[a-z-]+}-{version:\\\\d\\\\.\\\\d\\\\.\\\\d}{ext:\\\\.[a-z]+}")\npublic void handle(@PathVariable String version, @PathVariable String ext) {\n    // ...\n}\n')])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('@GetMapping("/{name:[a-z-]+}-{version:\\\\d\\\\.\\\\d\\\\.\\\\d}{ext:\\\\.[a-z]+}")\nfun handle(@PathVariable version: String, @PathVariable ext: String) {\n    // ...\n}\n')])])]),a("p",[e._v("URI path patterns can also have embedded "),a("code",[e._v("${…​}")]),e._v(" placeholders that are resolved on startup\nthrough "),a("code",[e._v("PropertyPlaceHolderConfigurer")]),e._v(" against local, system, environment, and other property\nsources. You ca use this to, for example, parameterize a base URL based on some external\nconfiguration.")]),e._v(" "),a("table",[a("thead",[a("tr",[a("th"),e._v(" "),a("th",[e._v("Spring WebFlux uses "),a("code",[e._v("PathPattern")]),e._v(" and the "),a("code",[e._v("PathPatternParser")]),e._v(" for URI path matching support."),a("br"),e._v("Both classes are located in "),a("code",[e._v("spring-web")]),e._v(" and are expressly designed for use with HTTP URL"),a("br"),e._v("paths in web applications where a large number of URI path patterns are matched at runtime.")])])]),e._v(" "),a("tbody")]),e._v(" "),a("p",[e._v("Spring WebFlux does not support suffix pattern matching — unlike Spring MVC, where a\nmapping such as "),a("code",[e._v("/person")]),e._v(" also matches to "),a("code",[e._v("/person.*")]),e._v(". For URL-based content\nnegotiation, if needed, we recommend using a query parameter, which is simpler, more\nexplicit, and less vulnerable to URL path based exploits.")]),e._v(" "),a("h5",{attrs:{id:"pattern-comparison"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#pattern-comparison"}},[e._v("#")]),e._v(" Pattern Comparison")]),e._v(" "),a("p",[a("RouterLink",{attrs:{to:"/en/spring-framework/web.html#mvc-ann-requestmapping-pattern-comparison"}},[e._v("Web MVC")])],1),e._v(" "),a("p",[e._v("When multiple patterns match a URL, they must be compared to find the best match. This is done\nwith "),a("code",[e._v("PathPattern.SPECIFICITY_COMPARATOR")]),e._v(", which looks for patterns that are more specific.")]),e._v(" "),a("p",[e._v("For every pattern, a score is computed, based on the number of URI variables and wildcards,\nwhere a URI variable scores lower than a wildcard. A pattern with a lower total score\nwins. If two patterns have the same score, the longer is chosen.")]),e._v(" "),a("p",[e._v("Catch-all patterns (for example, "),a("code",[e._v("**")]),e._v(", "),a("code",[e._v("{*varName}")]),e._v(") are excluded from the scoring and are always\nsorted last instead. If two patterns are both catch-all, the longer is chosen.")]),e._v(" "),a("h5",{attrs:{id:"consumable-media-types"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#consumable-media-types"}},[e._v("#")]),e._v(" Consumable Media Types")]),e._v(" "),a("p",[a("RouterLink",{attrs:{to:"/en/spring-framework/web.html#mvc-ann-requestmapping-consumes"}},[e._v("Web MVC")])],1),e._v(" "),a("p",[e._v("You can narrow the request mapping based on the "),a("code",[e._v("Content-Type")]),e._v(" of the request,\nas the following example shows:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('@PostMapping(path = "/pets", consumes = "application/json")\npublic void addPet(@RequestBody Pet pet) {\n    // ...\n}\n')])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('@PostMapping("/pets", consumes = ["application/json"])\nfun addPet(@RequestBody pet: Pet) {\n    // ...\n}\n')])])]),a("p",[e._v("The consumes attribute also supports negation expressions — for example, "),a("code",[e._v("!text/plain")]),e._v(" means any\ncontent type other than "),a("code",[e._v("text/plain")]),e._v(".")]),e._v(" "),a("p",[e._v("You can declare a shared "),a("code",[e._v("consumes")]),e._v(" attribute at the class level. Unlike most other request\nmapping attributes, however, when used at the class level, a method-level "),a("code",[e._v("consumes")]),e._v(" attribute\noverrides rather than extends the class-level declaration.")]),e._v(" "),a("table",[a("thead",[a("tr",[a("th"),e._v(" "),a("th",[a("code",[e._v("MediaType")]),e._v(" provides constants for commonly used media types — for example,"),a("code",[e._v("APPLICATION_JSON_VALUE")]),e._v(" and "),a("code",[e._v("APPLICATION_XML_VALUE")]),e._v(".")])])]),e._v(" "),a("tbody")]),e._v(" "),a("h5",{attrs:{id:"producible-media-types"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#producible-media-types"}},[e._v("#")]),e._v(" Producible Media Types")]),e._v(" "),a("p",[a("RouterLink",{attrs:{to:"/en/spring-framework/web.html#mvc-ann-requestmapping-produces"}},[e._v("Web MVC")])],1),e._v(" "),a("p",[e._v("You can narrow the request mapping based on the "),a("code",[e._v("Accept")]),e._v(" request header and the list of\ncontent types that a controller method produces, as the following example shows:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('@GetMapping(path = "/pets/{petId}", produces = "application/json")\n@ResponseBody\npublic Pet getPet(@PathVariable String petId) {\n    // ...\n}\n')])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('@GetMapping("/pets/{petId}", produces = ["application/json"])\n@ResponseBody\nfun getPet(@PathVariable String petId): Pet {\n    // ...\n}\n')])])]),a("p",[e._v("The media type can specify a character set. Negated expressions are supported — for example,"),a("code",[e._v("!text/plain")]),e._v(" means any content type other than "),a("code",[e._v("text/plain")]),e._v(".")]),e._v(" "),a("p",[e._v("You can declare a shared "),a("code",[e._v("produces")]),e._v(" attribute at the class level. Unlike most other request\nmapping attributes, however, when used at the class level, a method-level "),a("code",[e._v("produces")]),e._v(" attribute\noverrides rather than extend the class level declaration.")]),e._v(" "),a("table",[a("thead",[a("tr",[a("th"),e._v(" "),a("th",[a("code",[e._v("MediaType")]),e._v(" provides constants for commonly used media types — e.g."),a("code",[e._v("APPLICATION_JSON_VALUE")]),e._v(", "),a("code",[e._v("APPLICATION_XML_VALUE")]),e._v(".")])])]),e._v(" "),a("tbody")]),e._v(" "),a("h5",{attrs:{id:"parameters-and-headers"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#parameters-and-headers"}},[e._v("#")]),e._v(" Parameters and Headers")]),e._v(" "),a("p",[a("RouterLink",{attrs:{to:"/en/spring-framework/web.html#mvc-ann-requestmapping-params-and-headers"}},[e._v("Web MVC")])],1),e._v(" "),a("p",[e._v("You can narrow request mappings based on query parameter conditions. You can test for the\npresence of a query parameter ("),a("code",[e._v("myParam")]),e._v("), for its absence ("),a("code",[e._v("!myParam")]),e._v("), or for a\nspecific value ("),a("code",[e._v("myParam=myValue")]),e._v("). The following examples tests for a parameter with a value:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('@GetMapping(path = "/pets/{petId}", params = "myParam=myValue") (1)\npublic void findPet(@PathVariable String petId) {\n    // ...\n}\n')])])]),a("table",[a("thead",[a("tr",[a("th",[a("strong",[e._v("1")])]),e._v(" "),a("th",[e._v("Check that "),a("code",[e._v("myParam")]),e._v(" equals "),a("code",[e._v("myValue")]),e._v(".")])])]),e._v(" "),a("tbody")]),e._v(" "),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('@GetMapping("/pets/{petId}", params = ["myParam=myValue"]) (1)\nfun findPet(@PathVariable petId: String) {\n    // ...\n}\n')])])]),a("table",[a("thead",[a("tr",[a("th",[a("strong",[e._v("1")])]),e._v(" "),a("th",[e._v("Check that "),a("code",[e._v("myParam")]),e._v(" equals "),a("code",[e._v("myValue")]),e._v(".")])])]),e._v(" "),a("tbody")]),e._v(" "),a("p",[e._v("You can also use the same with request header conditions, as the follwing example shows:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('@GetMapping(path = "/pets", headers = "myHeader=myValue") (1)\npublic void findPet(@PathVariable String petId) {\n    // ...\n}\n')])])]),a("table",[a("thead",[a("tr",[a("th",[a("strong",[e._v("1")])]),e._v(" "),a("th",[e._v("Check that "),a("code",[e._v("myHeader")]),e._v(" equals "),a("code",[e._v("myValue")]),e._v(".")])])]),e._v(" "),a("tbody")]),e._v(" "),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('@GetMapping("/pets", headers = ["myHeader=myValue"]) (1)\nfun findPet(@PathVariable petId: String) {\n    // ...\n}\n')])])]),a("table",[a("thead",[a("tr",[a("th",[a("strong",[e._v("1")])]),e._v(" "),a("th",[e._v("Check that "),a("code",[e._v("myHeader")]),e._v(" equals "),a("code",[e._v("myValue")]),e._v(".")])])]),e._v(" "),a("tbody")]),e._v(" "),a("h5",{attrs:{id:"http-head-options"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#http-head-options"}},[e._v("#")]),e._v(" HTTP HEAD, OPTIONS")]),e._v(" "),a("p",[a("RouterLink",{attrs:{to:"/en/spring-framework/web.html#mvc-ann-requestmapping-head-options"}},[e._v("Web MVC")])],1),e._v(" "),a("p",[a("code",[e._v("@GetMapping")]),e._v(" and "),a("code",[e._v("@RequestMapping(method=HttpMethod.GET)")]),e._v(" support HTTP HEAD\ntransparently for request mapping purposes. Controller methods need not change.\nA response wrapper, applied in the "),a("code",[e._v("HttpHandler")]),e._v(" server adapter, ensures a "),a("code",[e._v("Content-Length")]),e._v("header is set to the number of bytes written without actually writing to the response.")]),e._v(" "),a("p",[e._v("By default, HTTP OPTIONS is handled by setting the "),a("code",[e._v("Allow")]),e._v(" response header to the list of HTTP\nmethods listed in all "),a("code",[e._v("@RequestMapping")]),e._v(" methods with matching URL patterns.")]),e._v(" "),a("p",[e._v("For a "),a("code",[e._v("@RequestMapping")]),e._v(" without HTTP method declarations, the "),a("code",[e._v("Allow")]),e._v(" header is set to"),a("code",[e._v("GET,HEAD,POST,PUT,PATCH,DELETE,OPTIONS")]),e._v(". Controller methods should always declare the\nsupported HTTP methods (for example, by using the HTTP method specific variants — "),a("code",[e._v("@GetMapping")]),e._v(", "),a("code",[e._v("@PostMapping")]),e._v(", and others).")]),e._v(" "),a("p",[e._v("You can explicitly map a "),a("code",[e._v("@RequestMapping")]),e._v(" method to HTTP HEAD and HTTP OPTIONS, but that\nis not necessary in the common case.")]),e._v(" "),a("h5",{attrs:{id:"custom-annotations"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#custom-annotations"}},[e._v("#")]),e._v(" Custom Annotations")]),e._v(" "),a("p",[a("RouterLink",{attrs:{to:"/en/spring-framework/web.html#mvc-ann-requestmapping-composed"}},[e._v("Web MVC")])],1),e._v(" "),a("p",[e._v("Spring WebFlux supports the use of "),a("RouterLink",{attrs:{to:"/en/spring-framework/core.html#beans-meta-annotations"}},[e._v("composed annotations")]),e._v("for request mapping. Those are annotations that are themselves meta-annotated with"),a("code",[e._v("@RequestMapping")]),e._v(" and composed to redeclare a subset (or all) of the "),a("code",[e._v("@RequestMapping")]),e._v("attributes with a narrower, more specific purpose.")],1),e._v(" "),a("p",[a("code",[e._v("@GetMapping")]),e._v(", "),a("code",[e._v("@PostMapping")]),e._v(", "),a("code",[e._v("@PutMapping")]),e._v(", "),a("code",[e._v("@DeleteMapping")]),e._v(", and "),a("code",[e._v("@PatchMapping")]),e._v(" are\nexamples of composed annotations. They are provided, because, arguably, most\ncontroller methods should be mapped to a specific HTTP method versus using "),a("code",[e._v("@RequestMapping")]),e._v(",\nwhich, by default, matches to all HTTP methods. If you need an example of composed\nannotations, look at how those are declared.")]),e._v(" "),a("p",[e._v("Spring WebFlux also supports custom request mapping attributes with custom request matching\nlogic. This is a more advanced option that requires sub-classing"),a("code",[e._v("RequestMappingHandlerMapping")]),e._v(" and overriding the "),a("code",[e._v("getCustomMethodCondition")]),e._v(" method, where\nyou can check the custom attribute and return your own "),a("code",[e._v("RequestCondition")]),e._v(".")]),e._v(" "),a("h5",{attrs:{id:"explicit-registrations"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#explicit-registrations"}},[e._v("#")]),e._v(" Explicit Registrations")]),e._v(" "),a("p",[a("RouterLink",{attrs:{to:"/en/spring-framework/web.html#mvc-ann-requestmapping-registration"}},[e._v("Web MVC")])],1),e._v(" "),a("p",[e._v("You can programmatically register Handler methods, which can be used for dynamic\nregistrations or for advanced cases, such as different instances of the same handler\nunder different URLs. The following example shows how to do so:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('@Configuration\npublic class MyConfig {\n\n    @Autowired\n    public void setHandlerMapping(RequestMappingHandlerMapping mapping, UserHandler handler) (1)\n            throws NoSuchMethodException {\n\n        RequestMappingInfo info = RequestMappingInfo\n                .paths("/user/{id}").methods(RequestMethod.GET).build(); (2)\n\n        Method method = UserHandler.class.getMethod("getUser", Long.class); (3)\n\n        mapping.registerMapping(info, handler, method); (4)\n    }\n\n}\n')])])]),a("table",[a("thead",[a("tr",[a("th",[a("strong",[e._v("1")])]),e._v(" "),a("th",[e._v("Inject target handlers and the handler mapping for controllers.")])])]),e._v(" "),a("tbody",[a("tr",[a("td",[a("strong",[e._v("2")])]),e._v(" "),a("td",[e._v("Prepare the request mapping metadata.")])]),e._v(" "),a("tr",[a("td",[a("strong",[e._v("3")])]),e._v(" "),a("td",[e._v("Get the handler method.")])]),e._v(" "),a("tr",[a("td",[a("strong",[e._v("4")])]),e._v(" "),a("td",[e._v("Add the registration.")])])])]),e._v(" "),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('@Configuration\nclass MyConfig {\n\n    @Autowired\n    fun setHandlerMapping(mapping: RequestMappingHandlerMapping, handler: UserHandler) { (1)\n\n        val info = RequestMappingInfo.paths("/user/{id}").methods(RequestMethod.GET).build() (2)\n\n        val method = UserHandler::class.java.getMethod("getUser", Long::class.java) (3)\n\n        mapping.registerMapping(info, handler, method) (4)\n    }\n}\n')])])]),a("table",[a("thead",[a("tr",[a("th",[a("strong",[e._v("1")])]),e._v(" "),a("th",[e._v("Inject target handlers and the handler mapping for controllers.")])])]),e._v(" "),a("tbody",[a("tr",[a("td",[a("strong",[e._v("2")])]),e._v(" "),a("td",[e._v("Prepare the request mapping metadata.")])]),e._v(" "),a("tr",[a("td",[a("strong",[e._v("3")])]),e._v(" "),a("td",[e._v("Get the handler method.")])]),e._v(" "),a("tr",[a("td",[a("strong",[e._v("4")])]),e._v(" "),a("td",[e._v("Add the registration.")])])])]),e._v(" "),a("h4",{attrs:{id:"_1-4-3-handler-methods"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_1-4-3-handler-methods"}},[e._v("#")]),e._v(" 1.4.3. Handler Methods")]),e._v(" "),a("p",[a("RouterLink",{attrs:{to:"/en/spring-framework/web.html#mvc-ann-methods"}},[e._v("Web MVC")])],1),e._v(" "),a("p",[a("code",[e._v("@RequestMapping")]),e._v(" handler methods have a flexible signature and can choose from a range of\nsupported controller method arguments and return values.")]),e._v(" "),a("h5",{attrs:{id:"method-arguments"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#method-arguments"}},[e._v("#")]),e._v(" Method Arguments")]),e._v(" "),a("p",[a("RouterLink",{attrs:{to:"/en/spring-framework/web.html#mvc-ann-arguments"}},[e._v("Web MVC")])],1),e._v(" "),a("p",[e._v("The following table shows the supported controller method arguments.")]),e._v(" "),a("p",[e._v("Reactive types (Reactor, RxJava, "),a("a",{attrs:{href:"#webflux-reactive-libraries"}},[e._v("or other")]),e._v(") are\nsupported on arguments that require blocking I/O (for example, reading the request body) to\nbe resolved. This is marked in the Description column. Reactive types are not expected\non arguments that do not require blocking.")]),e._v(" "),a("p",[e._v("JDK 1.8’s "),a("code",[e._v("java.util.Optional")]),e._v(" is supported as a method argument in combination with\nannotations that have a "),a("code",[e._v("required")]),e._v(" attribute (for example, "),a("code",[e._v("@RequestParam")]),e._v(", "),a("code",[e._v("@RequestHeader")]),e._v(",\nand others) and is equivalent to "),a("code",[e._v("required=false")]),e._v(".")]),e._v(" "),a("table",[a("thead",[a("tr",[a("th",[e._v("Controller method argument")]),e._v(" "),a("th",[e._v("Description")])])]),e._v(" "),a("tbody",[a("tr",[a("td",[a("code",[e._v("ServerWebExchange")])]),e._v(" "),a("td",[e._v("Access to the full "),a("code",[e._v("ServerWebExchange")]),e._v(" — container for the HTTP request and response,"),a("br"),e._v("request and session attributes, "),a("code",[e._v("checkNotModified")]),e._v(" methods, and others.")])]),e._v(" "),a("tr",[a("td",[a("code",[e._v("ServerHttpRequest")]),e._v(", "),a("code",[e._v("ServerHttpResponse")])]),e._v(" "),a("td",[e._v("Access to the HTTP request or response.")])]),e._v(" "),a("tr",[a("td",[a("code",[e._v("WebSession")])]),e._v(" "),a("td",[e._v("Access to the session. This does not force the start of a new session unless attributes"),a("br"),e._v("are added. Supports reactive types.")])]),e._v(" "),a("tr",[a("td",[a("code",[e._v("java.security.Principal")])]),e._v(" "),a("td",[e._v("The currently authenticated user — possibly a specific "),a("code",[e._v("Principal")]),e._v(" implementation class if known."),a("br"),e._v("Supports reactive types.")])]),e._v(" "),a("tr",[a("td",[a("code",[e._v("org.springframework.http.HttpMethod")])]),e._v(" "),a("td",[e._v("The HTTP method of the request.")])]),e._v(" "),a("tr",[a("td",[a("code",[e._v("java.util.Locale")])]),e._v(" "),a("td",[e._v("The current request locale, determined by the most specific "),a("code",[e._v("LocaleResolver")]),e._v(" available — in"),a("br"),e._v("effect, the configured "),a("code",[e._v("LocaleResolver")]),e._v("/"),a("code",[e._v("LocaleContextResolver")]),e._v(".")])]),e._v(" "),a("tr",[a("td",[a("code",[e._v("java.util.TimeZone")]),e._v(" + "),a("code",[e._v("java.time.ZoneId")])]),e._v(" "),a("td",[e._v("The time zone associated with the current request, as determined by a "),a("code",[e._v("LocaleContextResolver")]),e._v(".")])]),e._v(" "),a("tr",[a("td",[a("code",[e._v("@PathVariable")])]),e._v(" "),a("td",[e._v("For access to URI template variables. See "),a("a",{attrs:{href:"#webflux-ann-requestmapping-uri-templates"}},[e._v("URI Patterns")]),e._v(".")])]),e._v(" "),a("tr",[a("td",[a("code",[e._v("@MatrixVariable")])]),e._v(" "),a("td",[e._v("For access to name-value pairs in URI path segments. See "),a("a",{attrs:{href:"#webflux-ann-matrix-variables"}},[e._v("Matrix Variables")]),e._v(".")])]),e._v(" "),a("tr",[a("td",[a("code",[e._v("@RequestParam")])]),e._v(" "),a("td",[e._v("For access to Servlet request parameters. Parameter values are converted to the declared"),a("br"),e._v("method argument type. See "),a("a",{attrs:{href:"#webflux-ann-requestparam"}},[a("code",[e._v("@RequestParam")])]),e._v("."),a("br"),a("br"),e._v(" Note that use of "),a("code",[e._v("@RequestParam")]),e._v(" is optional — for example, to set its attributes."),a("br"),e._v("See “Any other argument” later in this table.")])]),e._v(" "),a("tr",[a("td",[a("code",[e._v("@RequestHeader")])]),e._v(" "),a("td",[e._v("For access to request headers. Header values are converted to the declared method argument"),a("br"),e._v("type. See "),a("a",{attrs:{href:"#webflux-ann-requestheader"}},[a("code",[e._v("@RequestHeader")])]),e._v(".")])]),e._v(" "),a("tr",[a("td",[a("code",[e._v("@CookieValue")])]),e._v(" "),a("td",[e._v("For access to cookies. Cookie values are converted to the declared method argument type."),a("br"),e._v("See "),a("a",{attrs:{href:"#webflux-ann-cookievalue"}},[a("code",[e._v("@CookieValue")])]),e._v(".")])]),e._v(" "),a("tr",[a("td",[a("code",[e._v("@RequestBody")])]),e._v(" "),a("td",[e._v("For access to the HTTP request body. Body content is converted to the declared method"),a("br"),e._v("argument type by using "),a("code",[e._v("HttpMessageReader")]),e._v(" instances. Supports reactive types."),a("br"),e._v("See "),a("a",{attrs:{href:"#webflux-ann-requestbody"}},[a("code",[e._v("@RequestBody")])]),e._v(".")])]),e._v(" "),a("tr",[a("td",[a("code",[e._v("HttpEntity<B>")])]),e._v(" "),a("td",[e._v("For access to request headers and body. The body is converted with "),a("code",[e._v("HttpMessageReader")]),e._v(" instances."),a("br"),e._v("Supports reactive types. See "),a("a",{attrs:{href:"#webflux-ann-httpentity"}},[a("code",[e._v("HttpEntity")])]),e._v(".")])]),e._v(" "),a("tr",[a("td",[a("code",[e._v("@RequestPart")])]),e._v(" "),a("td",[e._v("For access to a part in a "),a("code",[e._v("multipart/form-data")]),e._v(" request. Supports reactive types."),a("br"),e._v("See "),a("a",{attrs:{href:"#webflux-multipart-forms"}},[e._v("Multipart Content")]),e._v(" and "),a("a",{attrs:{href:"#webflux-multipart"}},[e._v("Multipart Data")]),e._v(".")])]),e._v(" "),a("tr",[a("td",[a("code",[e._v("java.util.Map")]),e._v(", "),a("code",[e._v("org.springframework.ui.Model")]),e._v(", and "),a("code",[e._v("org.springframework.ui.ModelMap")]),e._v(".")]),e._v(" "),a("td",[e._v("For access to the model that is used in HTML controllers and is exposed to templates as"),a("br"),e._v("part of view rendering.")])]),e._v(" "),a("tr",[a("td",[a("code",[e._v("@ModelAttribute")])]),e._v(" "),a("td",[e._v("For access to an existing attribute in the model (instantiated if not present) with"),a("br"),e._v("data binding and validation applied. See "),a("a",{attrs:{href:"#webflux-ann-modelattrib-method-args"}},[a("code",[e._v("@ModelAttribute")])]),e._v(" as well"),a("br"),e._v("as "),a("a",{attrs:{href:"#webflux-ann-modelattrib-methods"}},[a("code",[e._v("Model")])]),e._v(" and "),a("a",{attrs:{href:"#webflux-ann-initbinder"}},[a("code",[e._v("DataBinder")])]),e._v("."),a("br"),a("br"),e._v(" Note that use of "),a("code",[e._v("@ModelAttribute")]),e._v(" is optional — for example, to set its attributes."),a("br"),e._v("See “Any other argument” later in this table.")])]),e._v(" "),a("tr",[a("td",[a("code",[e._v("Errors")]),e._v(", "),a("code",[e._v("BindingResult")])]),e._v(" "),a("td",[e._v("For access to errors from validation and data binding for a command object, i.e. a"),a("code",[e._v("@ModelAttribute")]),e._v(" argument. An "),a("code",[e._v("Errors")]),e._v(", or "),a("code",[e._v("BindingResult")]),e._v(" argument must be declared"),a("br"),e._v("immediately after the validated method argument.")])]),e._v(" "),a("tr",[a("td",[a("code",[e._v("SessionStatus")]),e._v(" + class-level "),a("code",[e._v("@SessionAttributes")])]),e._v(" "),a("td",[e._v("For marking form processing complete, which triggers cleanup of session attributes"),a("br"),e._v("declared through a class-level "),a("code",[e._v("@SessionAttributes")]),e._v(" annotation."),a("br"),e._v("See "),a("a",{attrs:{href:"#webflux-ann-sessionattributes"}},[a("code",[e._v("@SessionAttributes")])]),e._v(" for more details.")])]),e._v(" "),a("tr",[a("td",[a("code",[e._v("UriComponentsBuilder")])]),e._v(" "),a("td",[e._v("For preparing a URL relative to the current request’s host, port, scheme, and"),a("br"),e._v("context path. See "),a("a",{attrs:{href:"#webflux-uri-building"}},[e._v("URI Links")]),e._v(".")])]),e._v(" "),a("tr",[a("td",[a("code",[e._v("@SessionAttribute")])]),e._v(" "),a("td",[e._v("For access to any session attribute — in contrast to model attributes stored in the session"),a("br"),e._v("as a result of a class-level "),a("code",[e._v("@SessionAttributes")]),e._v(" declaration. See"),a("a",{attrs:{href:"#webflux-ann-sessionattribute"}},[a("code",[e._v("@SessionAttribute")])]),e._v(" for more details.")])]),e._v(" "),a("tr",[a("td",[a("code",[e._v("@RequestAttribute")])]),e._v(" "),a("td",[e._v("For access to request attributes. See "),a("a",{attrs:{href:"#webflux-ann-requestattrib"}},[a("code",[e._v("@RequestAttribute")])]),e._v(" for more details.")])]),e._v(" "),a("tr",[a("td",[e._v("Any other argument")]),e._v(" "),a("td",[e._v("If a method argument is not matched to any of the above, it is, by default, resolved as"),a("br"),e._v("a "),a("code",[e._v("@RequestParam")]),e._v(" if it is a simple type, as determined by"),a("a",{attrs:{href:"https://docs.spring.io/spring-framework/docs/5.3.16/javadoc-api/org/springframework/beans/BeanUtils.html#isSimpleProperty-java.lang.Class-",target:"_blank",rel:"noopener noreferrer"}},[e._v("BeanUtils#isSimpleProperty"),a("OutboundLink")],1),e._v(","),a("br"),e._v("or as a "),a("code",[e._v("@ModelAttribute")]),e._v(", otherwise.")])])])]),e._v(" "),a("h5",{attrs:{id:"return-values"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#return-values"}},[e._v("#")]),e._v(" Return Values")]),e._v(" "),a("p",[a("RouterLink",{attrs:{to:"/en/spring-framework/web.html#mvc-ann-return-types"}},[e._v("Web MVC")])],1),e._v(" "),a("p",[e._v("The following table shows the supported controller method return values. Note that reactive\ntypes from libraries such as Reactor, RxJava, "),a("a",{attrs:{href:"#webflux-reactive-libraries"}},[e._v("or other")]),e._v(" are\ngenerally supported for all return values.")]),e._v(" "),a("table",[a("thead",[a("tr",[a("th",[e._v("Controller method return value")]),e._v(" "),a("th",[e._v("Description")])])]),e._v(" "),a("tbody",[a("tr",[a("td",[a("code",[e._v("@ResponseBody")])]),e._v(" "),a("td",[e._v("The return value is encoded through "),a("code",[e._v("HttpMessageWriter")]),e._v(" instances and written to the response."),a("br"),e._v("See "),a("a",{attrs:{href:"#webflux-ann-responsebody"}},[a("code",[e._v("@ResponseBody")])]),e._v(".")])]),e._v(" "),a("tr",[a("td",[a("code",[e._v("HttpEntity<B>")]),e._v(", "),a("code",[e._v("ResponseEntity<B>")])]),e._v(" "),a("td",[e._v("The return value specifies the full response, including HTTP headers, and the body is encoded"),a("br"),e._v("through "),a("code",[e._v("HttpMessageWriter")]),e._v(" instances and written to the response."),a("br"),e._v("See "),a("a",{attrs:{href:"#webflux-ann-responseentity"}},[a("code",[e._v("ResponseEntity")])]),e._v(".")])]),e._v(" "),a("tr",[a("td",[a("code",[e._v("HttpHeaders")])]),e._v(" "),a("td",[e._v("For returning a response with headers and no body.")])]),e._v(" "),a("tr",[a("td",[a("code",[e._v("String")])]),e._v(" "),a("td",[e._v("A view name to be resolved with "),a("code",[e._v("ViewResolver")]),e._v(" instances and used together with the implicit"),a("br"),e._v("model — determined through command objects and "),a("code",[e._v("@ModelAttribute")]),e._v(" methods. The handler"),a("br"),e._v("method can also programmatically enrich the model by declaring a "),a("code",[e._v("Model")]),e._v(" argument"),a("br"),e._v("(described "),a("a",{attrs:{href:"#webflux-viewresolution-handling"}},[e._v("earlier")]),e._v(").")])]),e._v(" "),a("tr",[a("td",[a("code",[e._v("View")])]),e._v(" "),a("td",[e._v("A "),a("code",[e._v("View")]),e._v(" instance to use for rendering together with the implicit model — determined"),a("br"),e._v("through command objects and "),a("code",[e._v("@ModelAttribute")]),e._v(" methods. The handler method can also"),a("br"),e._v("programmatically enrich the model by declaring a "),a("code",[e._v("Model")]),e._v(" argument"),a("br"),e._v("(described "),a("a",{attrs:{href:"#webflux-viewresolution-handling"}},[e._v("earlier")]),e._v(").")])]),e._v(" "),a("tr",[a("td",[a("code",[e._v("java.util.Map")]),e._v(", "),a("code",[e._v("org.springframework.ui.Model")])]),e._v(" "),a("td",[e._v("Attributes to be added to the implicit model, with the view name implicitly determined"),a("br"),e._v("based on the request path.")])]),e._v(" "),a("tr",[a("td",[a("code",[e._v("@ModelAttribute")])]),e._v(" "),a("td",[e._v("An attribute to be added to the model, with the view name implicitly determined based"),a("br"),e._v("on the request path."),a("br"),a("br"),e._v(" Note that "),a("code",[e._v("@ModelAttribute")]),e._v(" is optional. See “Any other return value” later in"),a("br"),e._v("this table.")])]),e._v(" "),a("tr",[a("td",[a("code",[e._v("Rendering")])]),e._v(" "),a("td",[e._v("An API for model and view rendering scenarios.")])]),e._v(" "),a("tr",[a("td",[a("code",[e._v("void")])]),e._v(" "),a("td",[e._v("A method with a "),a("code",[e._v("void")]),e._v(", possibly asynchronous (for example, "),a("code",[e._v("Mono<Void>")]),e._v("), return type (or a "),a("code",[e._v("null")]),e._v(" return"),a("br"),e._v("value) is considered to have fully handled the response if it also has a "),a("code",[e._v("ServerHttpResponse")]),e._v(","),a("br"),e._v("a "),a("code",[e._v("ServerWebExchange")]),e._v(" argument, or an "),a("code",[e._v("@ResponseStatus")]),e._v(" annotation. The same is also true"),a("br"),e._v("if the controller has made a positive ETag or "),a("code",[e._v("lastModified")]),e._v(" timestamp check."),a("br"),e._v("// TODO: See "),a("a",{attrs:{href:"#webflux-caching-etag-lastmodified"}},[e._v("Controllers")]),e._v(" for details."),a("br"),a("br"),e._v(" If none of the above is true, a "),a("code",[e._v("void")]),e._v(" return type can also indicate “no response body” for"),a("br"),e._v("REST controllers or default view name selection for HTML controllers.")])]),e._v(" "),a("tr",[a("td",[a("code",[e._v("Flux<ServerSentEvent>")]),e._v(", "),a("code",[e._v("Observable<ServerSentEvent>")]),e._v(", or other reactive type")]),e._v(" "),a("td",[e._v("Emit server-sent events. The "),a("code",[e._v("ServerSentEvent")]),e._v(" wrapper can be omitted when only data needs"),a("br"),e._v("to be written (however, "),a("code",[e._v("text/event-stream")]),e._v(" must be requested or declared in the mapping"),a("br"),e._v("through the "),a("code",[e._v("produces")]),e._v(" attribute).")])]),e._v(" "),a("tr",[a("td",[e._v("Any other return value")]),e._v(" "),a("td",[e._v("If a return value is not matched to any of the above, it is, by default, treated as a view"),a("br"),e._v("name, if it is "),a("code",[e._v("String")]),e._v(" or "),a("code",[e._v("void")]),e._v(" (default view name selection applies), or as a model"),a("br"),e._v("attribute to be added to the model, unless it is a simple type, as determined by"),a("a",{attrs:{href:"https://docs.spring.io/spring-framework/docs/5.3.16/javadoc-api/org/springframework/beans/BeanUtils.html#isSimpleProperty-java.lang.Class-",target:"_blank",rel:"noopener noreferrer"}},[e._v("BeanUtils#isSimpleProperty"),a("OutboundLink")],1),e._v(","),a("br"),e._v("in which case it remains unresolved.")])])])]),e._v(" "),a("h5",{attrs:{id:"type-conversion"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#type-conversion"}},[e._v("#")]),e._v(" Type Conversion")]),e._v(" "),a("p",[a("RouterLink",{attrs:{to:"/en/spring-framework/web.html#mvc-ann-typeconversion"}},[e._v("Web MVC")])],1),e._v(" "),a("p",[e._v("Some annotated controller method arguments that represent String-based request input (for example,"),a("code",[e._v("@RequestParam")]),e._v(", "),a("code",[e._v("@RequestHeader")]),e._v(", "),a("code",[e._v("@PathVariable")]),e._v(", "),a("code",[e._v("@MatrixVariable")]),e._v(", and "),a("code",[e._v("@CookieValue")]),e._v(")\ncan require type conversion if the argument is declared as something other than "),a("code",[e._v("String")]),e._v(".")]),e._v(" "),a("p",[e._v("For such cases, type conversion is automatically applied based on the configured converters.\nBy default, simple types (such as "),a("code",[e._v("int")]),e._v(", "),a("code",[e._v("long")]),e._v(", "),a("code",[e._v("Date")]),e._v(", and others) are supported. Type conversion\ncan be customized through a "),a("code",[e._v("WebDataBinder")]),e._v(" (see "),a("a",{attrs:{href:"#webflux-ann-initbinder"}},[a("code",[e._v("DataBinder")])]),e._v(") or by registering"),a("code",[e._v("Formatters")]),e._v(" with the "),a("code",[e._v("FormattingConversionService")]),e._v(" (see "),a("RouterLink",{attrs:{to:"/en/spring-framework/core.html#format"}},[e._v("Spring Field Formatting")]),e._v(").")],1),e._v(" "),a("p",[e._v("A practical issue in type conversion is the treatment of an empty String source value.\nSuch a value is treated as missing if it becomes "),a("code",[e._v("null")]),e._v(" as a result of type conversion.\nThis can be the case for "),a("code",[e._v("Long")]),e._v(", "),a("code",[e._v("UUID")]),e._v(", and other target types. If you want to allow "),a("code",[e._v("null")]),e._v("to be injected, either use the "),a("code",[e._v("required")]),e._v(" flag on the argument annotation, or declare the\nargument as "),a("code",[e._v("@Nullable")]),e._v(".")]),e._v(" "),a("h5",{attrs:{id:"matrix-variables"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#matrix-variables"}},[e._v("#")]),e._v(" Matrix Variables")]),e._v(" "),a("p",[a("RouterLink",{attrs:{to:"/en/spring-framework/web.html#mvc-ann-matrix-variables"}},[e._v("Web MVC")])],1),e._v(" "),a("p",[a("a",{attrs:{href:"https://tools.ietf.org/html/rfc3986#section-3.3",target:"_blank",rel:"noopener noreferrer"}},[e._v("RFC 3986"),a("OutboundLink")],1),e._v(" discusses name-value pairs in\npath segments. In Spring WebFlux, we refer to those as “matrix variables” based on an"),a("a",{attrs:{href:"https://www.w3.org/DesignIssues/MatrixURIs.html",target:"_blank",rel:"noopener noreferrer"}},[e._v("“old post”"),a("OutboundLink")],1),e._v(" by Tim Berners-Lee, but they\ncan be also be referred to as URI path parameters.")]),e._v(" "),a("p",[e._v("Matrix variables can appear in any path segment, with each variable separated by a semicolon and\nmultiple values separated by commas — for example, "),a("code",[e._v('"/cars;color=red,green;year=2012"')]),e._v(". Multiple\nvalues can also be specified through repeated variable names — for example,"),a("code",[e._v('"color=red;color=green;color=blue"')]),e._v(".")]),e._v(" "),a("p",[e._v("Unlike Spring MVC, in WebFlux, the presence or absence of matrix variables in a URL does\nnot affect request mappings. In other words, you are not required to use a URI variable\nto mask variable content. That said, if you want to access matrix variables from a\ncontroller method, you need to add a URI variable to the path segment where matrix\nvariables are expected. The following example shows how to do so:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('// GET /pets/42;q=11;r=22\n\n@GetMapping("/pets/{petId}")\npublic void findPet(@PathVariable String petId, @MatrixVariable int q) {\n\n    // petId == 42\n    // q == 11\n}\n')])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('// GET /pets/42;q=11;r=22\n\n@GetMapping("/pets/{petId}")\nfun findPet(@PathVariable petId: String, @MatrixVariable q: Int) {\n\n    // petId == 42\n    // q == 11\n}\n')])])]),a("p",[e._v("Given that all path segments can contain matrix variables, you may sometimes need to\ndisambiguate which path variable the matrix variable is expected to be in,\nas the following example shows:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('// GET /owners/42;q=11/pets/21;q=22\n\n@GetMapping("/owners/{ownerId}/pets/{petId}")\npublic void findPet(\n        @MatrixVariable(name="q", pathVar="ownerId") int q1,\n        @MatrixVariable(name="q", pathVar="petId") int q2) {\n\n    // q1 == 11\n    // q2 == 22\n}\n')])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('@GetMapping("/owners/{ownerId}/pets/{petId}")\nfun findPet(\n        @MatrixVariable(name = "q", pathVar = "ownerId") q1: Int,\n        @MatrixVariable(name = "q", pathVar = "petId") q2: Int) {\n\n    // q1 == 11\n    // q2 == 22\n}\n')])])]),a("p",[e._v("You can define a matrix variable may be defined as optional and specify a default value\nas the following example shows:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('// GET /pets/42\n\n@GetMapping("/pets/{petId}")\npublic void findPet(@MatrixVariable(required=false, defaultValue="1") int q) {\n\n    // q == 1\n}\n')])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('// GET /pets/42\n\n@GetMapping("/pets/{petId}")\nfun findPet(@MatrixVariable(required = false, defaultValue = "1") q: Int) {\n\n    // q == 1\n}\n')])])]),a("p",[e._v("To get all matrix variables, use a "),a("code",[e._v("MultiValueMap")]),e._v(", as the following example shows:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('// GET /owners/42;q=11;r=12/pets/21;q=22;s=23\n\n@GetMapping("/owners/{ownerId}/pets/{petId}")\npublic void findPet(\n        @MatrixVariable MultiValueMap<String, String> matrixVars,\n        @MatrixVariable(pathVar="petId") MultiValueMap<String, String> petMatrixVars) {\n\n    // matrixVars: ["q" : [11,22], "r" : 12, "s" : 23]\n    // petMatrixVars: ["q" : 22, "s" : 23]\n}\n')])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('// GET /owners/42;q=11;r=12/pets/21;q=22;s=23\n\n@GetMapping("/owners/{ownerId}/pets/{petId}")\nfun findPet(\n        @MatrixVariable matrixVars: MultiValueMap<String, String>,\n        @MatrixVariable(pathVar="petId") petMatrixVars: MultiValueMap<String, String>) {\n\n    // matrixVars: ["q" : [11,22], "r" : 12, "s" : 23]\n    // petMatrixVars: ["q" : 22, "s" : 23]\n}\n')])])]),a("h5",{attrs:{id:"requestparam"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#requestparam"}},[e._v("#")]),e._v(" "),a("code",[e._v("@RequestParam")])]),e._v(" "),a("p",[a("RouterLink",{attrs:{to:"/en/spring-framework/web.html#mvc-ann-requestparam"}},[e._v("Web MVC")])],1),e._v(" "),a("p",[e._v("You can use the "),a("code",[e._v("@RequestParam")]),e._v(" annotation to bind query parameters to a method argument in a\ncontroller. The following code snippet shows the usage:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('@Controller\n@RequestMapping("/pets")\npublic class EditPetForm {\n\n    // ...\n\n    @GetMapping\n    public String setupForm(@RequestParam("petId") int petId, Model model) { (1)\n        Pet pet = this.clinic.loadPet(petId);\n        model.addAttribute("pet", pet);\n        return "petForm";\n    }\n\n    // ...\n}\n')])])]),a("table",[a("thead",[a("tr",[a("th",[a("strong",[e._v("1")])]),e._v(" "),a("th",[e._v("Using "),a("code",[e._v("@RequestParam")]),e._v(".")])])]),e._v(" "),a("tbody")]),e._v(" "),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('import org.springframework.ui.set\n\n@Controller\n@RequestMapping("/pets")\nclass EditPetForm {\n\n    // ...\n\n    @GetMapping\n    fun setupForm(@RequestParam("petId") petId: Int, model: Model): String { (1)\n        val pet = clinic.loadPet(petId)\n        model["pet"] = pet\n        return "petForm"\n    }\n\n    // ...\n}\n')])])]),a("table",[a("thead",[a("tr",[a("th",[a("strong",[e._v("1")])]),e._v(" "),a("th",[e._v("Using "),a("code",[e._v("@RequestParam")]),e._v(".")])])]),e._v(" "),a("tbody")]),e._v(" "),a("table",[a("thead",[a("tr",[a("th"),e._v(" "),a("th",[e._v("The Servlet API “request parameter” concept conflates query parameters, form"),a("br"),e._v("data, and multiparts into one. However, in WebFlux, each is accessed individually through"),a("code",[e._v("ServerWebExchange")]),e._v(". While "),a("code",[e._v("@RequestParam")]),e._v(" binds to query parameters only, you can use"),a("br"),e._v("data binding to apply query parameters, form data, and multiparts to a"),a("a",{attrs:{href:"#webflux-ann-modelattrib-method-args"}},[e._v("command object")]),e._v(".")])])]),e._v(" "),a("tbody")]),e._v(" "),a("p",[e._v("Method parameters that use the "),a("code",[e._v("@RequestParam")]),e._v(" annotation are required by default, but\nyou can specify that a method parameter is optional by setting the required flag of a "),a("code",[e._v("@RequestParam")]),e._v("to "),a("code",[e._v("false")]),e._v(" or by declaring the argument with a "),a("code",[e._v("java.util.Optional")]),e._v("wrapper.")]),e._v(" "),a("p",[e._v("Type conversion is applied automatically if the target method parameter type is not"),a("code",[e._v("String")]),e._v(". See "),a("a",{attrs:{href:"#webflux-ann-typeconversion"}},[e._v("Type Conversion")]),e._v(".")]),e._v(" "),a("p",[e._v("When a "),a("code",[e._v("@RequestParam")]),e._v(" annotation is declared on a "),a("code",[e._v("Map<String, String>")]),e._v(" or"),a("code",[e._v("MultiValueMap<String, String>")]),e._v(" argument, the map is populated with all query parameters.")]),e._v(" "),a("p",[e._v("Note that use of "),a("code",[e._v("@RequestParam")]),e._v(" is optional — for example, to set its attributes. By\ndefault, any argument that is a simple value type (as determined by"),a("a",{attrs:{href:"https://docs.spring.io/spring-framework/docs/5.3.16/javadoc-api/org/springframework/beans/BeanUtils.html#isSimpleProperty-java.lang.Class-",target:"_blank",rel:"noopener noreferrer"}},[e._v("BeanUtils#isSimpleProperty"),a("OutboundLink")],1),e._v(")\nand is not resolved by any other argument resolver is treated as if it were annotated\nwith "),a("code",[e._v("@RequestParam")]),e._v(".")]),e._v(" "),a("h5",{attrs:{id:"requestheader"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#requestheader"}},[e._v("#")]),e._v(" "),a("code",[e._v("@RequestHeader")])]),e._v(" "),a("p",[a("RouterLink",{attrs:{to:"/en/spring-framework/web.html#mvc-ann-requestheader"}},[e._v("Web MVC")])],1),e._v(" "),a("p",[e._v("You can use the "),a("code",[e._v("@RequestHeader")]),e._v(" annotation to bind a request header to a method argument in a\ncontroller.")]),e._v(" "),a("p",[e._v("The following example shows a request with headers:")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("Host                    localhost:8080\nAccept                  text/html,application/xhtml+xml,application/xml;q=0.9\nAccept-Language         fr,en-gb;q=0.7,en;q=0.3\nAccept-Encoding         gzip,deflate\nAccept-Charset          ISO-8859-1,utf-8;q=0.7,*;q=0.7\nKeep-Alive              300\n")])])]),a("p",[e._v("The following example gets the value of the "),a("code",[e._v("Accept-Encoding")]),e._v(" and "),a("code",[e._v("Keep-Alive")]),e._v(" headers:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('@GetMapping("/demo")\npublic void handle(\n        @RequestHeader("Accept-Encoding") String encoding, (1)\n        @RequestHeader("Keep-Alive") long keepAlive) { (2)\n    //...\n}\n')])])]),a("table",[a("thead",[a("tr",[a("th",[a("strong",[e._v("1")])]),e._v(" "),a("th",[e._v("Get the value of the "),a("code",[e._v("Accept-Encoging")]),e._v(" header.")])])]),e._v(" "),a("tbody",[a("tr",[a("td",[a("strong",[e._v("2")])]),e._v(" "),a("td",[e._v("Get the value of the "),a("code",[e._v("Keep-Alive")]),e._v(" header.")])])])]),e._v(" "),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('@GetMapping("/demo")\nfun handle(\n        @RequestHeader("Accept-Encoding") encoding: String, (1)\n        @RequestHeader("Keep-Alive") keepAlive: Long) { (2)\n    //...\n}\n')])])]),a("table",[a("thead",[a("tr",[a("th",[a("strong",[e._v("1")])]),e._v(" "),a("th",[e._v("Get the value of the "),a("code",[e._v("Accept-Encoging")]),e._v(" header.")])])]),e._v(" "),a("tbody",[a("tr",[a("td",[a("strong",[e._v("2")])]),e._v(" "),a("td",[e._v("Get the value of the "),a("code",[e._v("Keep-Alive")]),e._v(" header.")])])])]),e._v(" "),a("p",[e._v("Type conversion is applied automatically if the target method parameter type is not"),a("code",[e._v("String")]),e._v(". See "),a("a",{attrs:{href:"#webflux-ann-typeconversion"}},[e._v("Type Conversion")]),e._v(".")]),e._v(" "),a("p",[e._v("When a "),a("code",[e._v("@RequestHeader")]),e._v(" annotation is used on a "),a("code",[e._v("Map<String, String>")]),e._v(","),a("code",[e._v("MultiValueMap<String, String>")]),e._v(", or "),a("code",[e._v("HttpHeaders")]),e._v(" argument, the map is populated\nwith all header values.")]),e._v(" "),a("table",[a("thead",[a("tr",[a("th"),e._v(" "),a("th",[e._v("Built-in support is available for converting a comma-separated string into an"),a("br"),e._v("array or collection of strings or other types known to the type conversion system. For"),a("br"),e._v("example, a method parameter annotated with "),a("code",[e._v('@RequestHeader("Accept")')]),e._v(" may be of type"),a("code",[e._v("String")]),e._v(" but also of "),a("code",[e._v("String[]")]),e._v(" or "),a("code",[e._v("List<String>")]),e._v(".")])])]),e._v(" "),a("tbody")]),e._v(" "),a("h5",{attrs:{id:"cookievalue"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#cookievalue"}},[e._v("#")]),e._v(" "),a("code",[e._v("@CookieValue")])]),e._v(" "),a("p",[a("RouterLink",{attrs:{to:"/en/spring-framework/web.html#mvc-ann-cookievalue"}},[e._v("Web MVC")])],1),e._v(" "),a("p",[e._v("You can use the "),a("code",[e._v("@CookieValue")]),e._v(" annotation to bind the value of an HTTP cookie to a method argument\nin a controller.")]),e._v(" "),a("p",[e._v("The following example shows a request with a cookie:")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("JSESSIONID=415A4AC178C59DACE0B2C9CA727CDD84\n")])])]),a("p",[e._v("The following code sample demonstrates how to get the cookie value:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('@GetMapping("/demo")\npublic void handle(@CookieValue("JSESSIONID") String cookie) { (1)\n    //...\n}\n')])])]),a("table",[a("thead",[a("tr",[a("th",[a("strong",[e._v("1")])]),e._v(" "),a("th",[e._v("Get the cookie value.")])])]),e._v(" "),a("tbody")]),e._v(" "),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('@GetMapping("/demo")\nfun handle(@CookieValue("JSESSIONID") cookie: String) { (1)\n    //...\n}\n')])])]),a("table",[a("thead",[a("tr",[a("th",[a("strong",[e._v("1")])]),e._v(" "),a("th",[e._v("Get the cookie value.")])])]),e._v(" "),a("tbody")]),e._v(" "),a("p",[e._v("Type conversion is applied automatically if the target method parameter type is not"),a("code",[e._v("String")]),e._v(". See "),a("a",{attrs:{href:"#webflux-ann-typeconversion"}},[e._v("Type Conversion")]),e._v(".")]),e._v(" "),a("h5",{attrs:{id:"modelattribute"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#modelattribute"}},[e._v("#")]),e._v(" "),a("code",[e._v("@ModelAttribute")])]),e._v(" "),a("p",[a("RouterLink",{attrs:{to:"/en/spring-framework/web.html#mvc-ann-modelattrib-method-args"}},[e._v("Web MVC")])],1),e._v(" "),a("p",[e._v("You can use the "),a("code",[e._v("@ModelAttribute")]),e._v(" annotation on a method argument to access an attribute from the\nmodel or have it instantiated if not present. The model attribute is also overlaid with\nthe values of query parameters and form fields whose names match to field names. This is\nreferred to as data binding, and it saves you from having to deal with parsing and\nconverting individual query parameters and form fields. The following example binds an instance of "),a("code",[e._v("Pet")]),e._v(":")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('@PostMapping("/owners/{ownerId}/pets/{petId}/edit")\npublic String processSubmit(@ModelAttribute Pet pet) { } (1)\n')])])]),a("table",[a("thead",[a("tr",[a("th",[a("strong",[e._v("1")])]),e._v(" "),a("th",[e._v("Bind an instance of "),a("code",[e._v("Pet")]),e._v(".")])])]),e._v(" "),a("tbody")]),e._v(" "),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('@PostMapping("/owners/{ownerId}/pets/{petId}/edit")\nfun processSubmit(@ModelAttribute pet: Pet): String { } (1)\n')])])]),a("table",[a("thead",[a("tr",[a("th",[a("strong",[e._v("1")])]),e._v(" "),a("th",[e._v("Bind an instance of "),a("code",[e._v("Pet")]),e._v(".")])])]),e._v(" "),a("tbody")]),e._v(" "),a("p",[e._v("The "),a("code",[e._v("Pet")]),e._v(" instance in the preceding example is resolved as follows:")]),e._v(" "),a("ul",[a("li",[a("p",[e._v("From the model if already added through "),a("a",{attrs:{href:"#webflux-ann-modelattrib-methods"}},[a("code",[e._v("Model")])]),e._v(".")])]),e._v(" "),a("li",[a("p",[e._v("From the HTTP session through "),a("a",{attrs:{href:"#webflux-ann-sessionattributes"}},[a("code",[e._v("@SessionAttributes")])]),e._v(".")])]),e._v(" "),a("li",[a("p",[e._v("From the invocation of a default constructor.")])]),e._v(" "),a("li",[a("p",[e._v("From the invocation of a “primary constructor” with arguments that match query\nparameters or form fields. Argument names are determined through JavaBeans"),a("code",[e._v("@ConstructorProperties")]),e._v(" or through runtime-retained parameter names in the bytecode.")])])]),e._v(" "),a("p",[e._v("After the model attribute instance is obtained, data binding is applied. The"),a("code",[e._v("WebExchangeDataBinder")]),e._v(" class matches names of query parameters and form fields to field\nnames on the target "),a("code",[e._v("Object")]),e._v(". Matching fields are populated after type conversion is applied\nwhere necessary. For more on data binding (and validation), see"),a("RouterLink",{attrs:{to:"/en/spring-framework/core.html#validation"}},[e._v("Validation")]),e._v(". For more on customizing data binding, see"),a("a",{attrs:{href:"#webflux-ann-initbinder"}},[a("code",[e._v("DataBinder")])]),e._v(".")],1),e._v(" "),a("p",[e._v("Data binding can result in errors. By default, a "),a("code",[e._v("WebExchangeBindException")]),e._v(" is raised, but,\nto check for such errors in the controller method, you can add a "),a("code",[e._v("BindingResult")]),e._v(" argument\nimmediately next to the "),a("code",[e._v("@ModelAttribute")]),e._v(", as the following example shows:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('@PostMapping("/owners/{ownerId}/pets/{petId}/edit")\npublic String processSubmit(@ModelAttribute("pet") Pet pet, BindingResult result) { (1)\n    if (result.hasErrors()) {\n        return "petForm";\n    }\n    // ...\n}\n')])])]),a("table",[a("thead",[a("tr",[a("th",[a("strong",[e._v("1")])]),e._v(" "),a("th",[e._v("Adding a "),a("code",[e._v("BindingResult")]),e._v(".")])])]),e._v(" "),a("tbody")]),e._v(" "),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('@PostMapping("/owners/{ownerId}/pets/{petId}/edit")\nfun processSubmit(@ModelAttribute("pet") pet: Pet, result: BindingResult): String { (1)\n    if (result.hasErrors()) {\n        return "petForm"\n    }\n    // ...\n}\n')])])]),a("table",[a("thead",[a("tr",[a("th",[a("strong",[e._v("1")])]),e._v(" "),a("th",[e._v("Adding a "),a("code",[e._v("BindingResult")]),e._v(".")])])]),e._v(" "),a("tbody")]),e._v(" "),a("p",[e._v("You can automatically apply validation after data binding by adding the"),a("code",[e._v("javax.validation.Valid")]),e._v(" annotation or Spring’s "),a("code",[e._v("@Validated")]),e._v(" annotation (see also"),a("RouterLink",{attrs:{to:"/en/spring-framework/core.html#validation-beanvalidation"}},[e._v("Bean Validation")]),e._v(" and"),a("RouterLink",{attrs:{to:"/en/spring-framework/core.html#validation"}},[e._v("Spring validation")]),e._v("). The following example uses the "),a("code",[e._v("@Valid")]),e._v(" annotation:")],1),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('@PostMapping("/owners/{ownerId}/pets/{petId}/edit")\npublic String processSubmit(@Valid @ModelAttribute("pet") Pet pet, BindingResult result) { (1)\n    if (result.hasErrors()) {\n        return "petForm";\n    }\n    // ...\n}\n')])])]),a("table",[a("thead",[a("tr",[a("th",[a("strong",[e._v("1")])]),e._v(" "),a("th",[e._v("Using "),a("code",[e._v("@Valid")]),e._v(" on a model attribute argument.")])])]),e._v(" "),a("tbody")]),e._v(" "),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('@PostMapping("/owners/{ownerId}/pets/{petId}/edit")\nfun processSubmit(@Valid @ModelAttribute("pet") pet: Pet, result: BindingResult): String { (1)\n    if (result.hasErrors()) {\n        return "petForm"\n    }\n    // ...\n}\n')])])]),a("table",[a("thead",[a("tr",[a("th",[a("strong",[e._v("1")])]),e._v(" "),a("th",[e._v("Using "),a("code",[e._v("@Valid")]),e._v(" on a model attribute argument.")])])]),e._v(" "),a("tbody")]),e._v(" "),a("p",[e._v("Spring WebFlux, unlike Spring MVC, supports reactive types in the model — for example,"),a("code",[e._v("Mono<Account>")]),e._v(" or "),a("code",[e._v("io.reactivex.Single<Account>")]),e._v(". You can declare a "),a("code",[e._v("@ModelAttribute")]),e._v(" argument\nwith or without a reactive type wrapper, and it will be resolved accordingly,\nto the actual value if necessary. However, note that, to use a "),a("code",[e._v("BindingResult")]),e._v("argument, you must declare the "),a("code",[e._v("@ModelAttribute")]),e._v(" argument before it without a reactive\ntype wrapper, as shown earlier. Alternatively, you can handle any errors through the\nreactive type, as the following example shows:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('@PostMapping("/owners/{ownerId}/pets/{petId}/edit")\npublic Mono<String> processSubmit(@Valid @ModelAttribute("pet") Mono<Pet> petMono) {\n    return petMono\n        .flatMap(pet -> {\n            // ...\n        })\n        .onErrorResume(ex -> {\n            // ...\n        });\n}\n')])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('@PostMapping("/owners/{ownerId}/pets/{petId}/edit")\nfun processSubmit(@Valid @ModelAttribute("pet") petMono: Mono<Pet>): Mono<String> {\n    return petMono\n            .flatMap { pet ->\n                // ...\n            }\n            .onErrorResume{ ex ->\n                // ...\n            }\n}\n')])])]),a("p",[e._v("Note that use of "),a("code",[e._v("@ModelAttribute")]),e._v(" is optional — for example, to set its attributes.\nBy default, any argument that is not a simple value type( as determined by"),a("a",{attrs:{href:"https://docs.spring.io/spring-framework/docs/5.3.16/javadoc-api/org/springframework/beans/BeanUtils.html#isSimpleProperty-java.lang.Class-",target:"_blank",rel:"noopener noreferrer"}},[e._v("BeanUtils#isSimpleProperty"),a("OutboundLink")],1),e._v(")\nand is not resolved by any other argument resolver is treated as if it were annotated\nwith "),a("code",[e._v("@ModelAttribute")]),e._v(".")]),e._v(" "),a("h5",{attrs:{id:"sessionattributes"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#sessionattributes"}},[e._v("#")]),e._v(" "),a("code",[e._v("@SessionAttributes")])]),e._v(" "),a("p",[a("RouterLink",{attrs:{to:"/en/spring-framework/web.html#mvc-ann-sessionattributes"}},[e._v("Web MVC")])],1),e._v(" "),a("p",[a("code",[e._v("@SessionAttributes")]),e._v(" is used to store model attributes in the "),a("code",[e._v("WebSession")]),e._v(" between\nrequests. It is a type-level annotation that declares session attributes used by a\nspecific controller. This typically lists the names of model attributes or types of\nmodel attributes that should be transparently stored in the session for subsequent\nrequests to access.")]),e._v(" "),a("p",[e._v("Consider the following example:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('@Controller\n@SessionAttributes("pet") (1)\npublic class EditPetForm {\n    // ...\n}\n')])])]),a("table",[a("thead",[a("tr",[a("th",[a("strong",[e._v("1")])]),e._v(" "),a("th",[e._v("Using the "),a("code",[e._v("@SessionAttributes")]),e._v(" annotation.")])])]),e._v(" "),a("tbody")]),e._v(" "),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('@Controller\n@SessionAttributes("pet") (1)\nclass EditPetForm {\n    // ...\n}\n')])])]),a("table",[a("thead",[a("tr",[a("th",[a("strong",[e._v("1")])]),e._v(" "),a("th",[e._v("Using the "),a("code",[e._v("@SessionAttributes")]),e._v(" annotation.")])])]),e._v(" "),a("tbody")]),e._v(" "),a("p",[e._v("On the first request, when a model attribute with the name, "),a("code",[e._v("pet")]),e._v(", is added to the model,\nit is automatically promoted to and saved in the "),a("code",[e._v("WebSession")]),e._v(". It remains there until\nanother controller method uses a "),a("code",[e._v("SessionStatus")]),e._v(" method argument to clear the storage,\nas the following example shows:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('@Controller\n@SessionAttributes("pet") (1)\npublic class EditPetForm {\n\n    // ...\n\n    @PostMapping("/pets/{id}")\n    public String handle(Pet pet, BindingResult errors, SessionStatus status) { (2)\n        if (errors.hasErrors()) {\n            // ...\n        }\n            status.setComplete();\n            // ...\n        }\n    }\n}\n')])])]),a("table",[a("thead",[a("tr",[a("th",[a("strong",[e._v("1")])]),e._v(" "),a("th",[e._v("Using the "),a("code",[e._v("@SessionAttributes")]),e._v(" annotation.")])])]),e._v(" "),a("tbody",[a("tr",[a("td",[a("strong",[e._v("2")])]),e._v(" "),a("td",[e._v("Using a "),a("code",[e._v("SessionStatus")]),e._v(" variable.")])])])]),e._v(" "),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('@Controller\n@SessionAttributes("pet") (1)\nclass EditPetForm {\n\n    // ...\n\n    @PostMapping("/pets/{id}")\n    fun handle(pet: Pet, errors: BindingResult, status: SessionStatus): String { (2)\n        if (errors.hasErrors()) {\n            // ...\n        }\n        status.setComplete()\n        // ...\n    }\n}\n')])])]),a("table",[a("thead",[a("tr",[a("th",[a("strong",[e._v("1")])]),e._v(" "),a("th",[e._v("Using the "),a("code",[e._v("@SessionAttributes")]),e._v(" annotation.")])])]),e._v(" "),a("tbody",[a("tr",[a("td",[a("strong",[e._v("2")])]),e._v(" "),a("td",[e._v("Using a "),a("code",[e._v("SessionStatus")]),e._v(" variable.")])])])]),e._v(" "),a("h5",{attrs:{id:"sessionattribute"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#sessionattribute"}},[e._v("#")]),e._v(" "),a("code",[e._v("@SessionAttribute")])]),e._v(" "),a("p",[a("RouterLink",{attrs:{to:"/en/spring-framework/web.html#mvc-ann-sessionattribute"}},[e._v("Web MVC")])],1),e._v(" "),a("p",[e._v("If you need access to pre-existing session attributes that are managed globally\n(that is, outside the controller — for example, by a filter) and may or may not be present,\nyou can use the "),a("code",[e._v("@SessionAttribute")]),e._v(" annotation on a method parameter, as the following example shows:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('@GetMapping("/")\npublic String handle(@SessionAttribute User user) { (1)\n    // ...\n}\n')])])]),a("table",[a("thead",[a("tr",[a("th",[a("strong",[e._v("1")])]),e._v(" "),a("th",[e._v("Using "),a("code",[e._v("@SessionAttribute")]),e._v(".")])])]),e._v(" "),a("tbody")]),e._v(" "),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('@GetMapping("/")\nfun handle(@SessionAttribute user: User): String { (1)\n    // ...\n}\n')])])]),a("table",[a("thead",[a("tr",[a("th",[a("strong",[e._v("1")])]),e._v(" "),a("th",[e._v("Using "),a("code",[e._v("@SessionAttribute")]),e._v(".")])])]),e._v(" "),a("tbody")]),e._v(" "),a("p",[e._v("For use cases that require adding or removing session attributes, consider injecting"),a("code",[e._v("WebSession")]),e._v(" into the controller method.")]),e._v(" "),a("p",[e._v("For temporary storage of model attributes in the session as part of a controller\nworkflow, consider using "),a("code",[e._v("SessionAttributes")]),e._v(", as described in"),a("a",{attrs:{href:"#webflux-ann-sessionattributes"}},[a("code",[e._v("@SessionAttributes")])]),e._v(".")]),e._v(" "),a("h5",{attrs:{id:"requestattribute"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#requestattribute"}},[e._v("#")]),e._v(" "),a("code",[e._v("@RequestAttribute")])]),e._v(" "),a("p",[a("RouterLink",{attrs:{to:"/en/spring-framework/web.html#mvc-ann-requestattrib"}},[e._v("Web MVC")])],1),e._v(" "),a("p",[e._v("Similarly to "),a("code",[e._v("@SessionAttribute")]),e._v(", you can use the "),a("code",[e._v("@RequestAttribute")]),e._v(" annotation to\naccess pre-existing request attributes created earlier (for example, by a "),a("code",[e._v("WebFilter")]),e._v("),\nas the following example shows:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('@GetMapping("/")\npublic String handle(@RequestAttribute Client client) { (1)\n    // ...\n}\n')])])]),a("table",[a("thead",[a("tr",[a("th",[a("strong",[e._v("1")])]),e._v(" "),a("th",[e._v("Using "),a("code",[e._v("@RequestAttribute")]),e._v(".")])])]),e._v(" "),a("tbody")]),e._v(" "),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('@GetMapping("/")\nfun handle(@RequestAttribute client: Client): String { (1)\n    // ...\n}\n')])])]),a("table",[a("thead",[a("tr",[a("th",[a("strong",[e._v("1")])]),e._v(" "),a("th",[e._v("Using "),a("code",[e._v("@RequestAttribute")]),e._v(".")])])]),e._v(" "),a("tbody")]),e._v(" "),a("h5",{attrs:{id:"multipart-content"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#multipart-content"}},[e._v("#")]),e._v(" Multipart Content")]),e._v(" "),a("p",[a("RouterLink",{attrs:{to:"/en/spring-framework/web.html#mvc-multipart-forms"}},[e._v("Web MVC")])],1),e._v(" "),a("p",[e._v("As explained in "),a("a",{attrs:{href:"#webflux-multipart"}},[e._v("Multipart Data")]),e._v(", "),a("code",[e._v("ServerWebExchange")]),e._v(" provides access to multipart\ncontent. The best way to handle a file upload form (for example, from a browser) in a controller\nis through data binding to a "),a("a",{attrs:{href:"#webflux-ann-modelattrib-method-args"}},[e._v("command object")]),e._v(",\nas the following example shows:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('class MyForm {\n\n    private String name;\n\n    private MultipartFile file;\n\n    // ...\n\n}\n\n@Controller\npublic class FileUploadController {\n\n    @PostMapping("/form")\n    public String handleFormUpload(MyForm form, BindingResult errors) {\n        // ...\n    }\n\n}\n')])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('class MyForm(\n        val name: String,\n        val file: MultipartFile)\n\n@Controller\nclass FileUploadController {\n\n    @PostMapping("/form")\n    fun handleFormUpload(form: MyForm, errors: BindingResult): String {\n        // ...\n    }\n\n}\n')])])]),a("p",[e._v("You can also submit multipart requests from non-browser clients in a RESTful service\nscenario. The following example uses a file along with JSON:")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('POST /someUrl\nContent-Type: multipart/mixed\n\n--edt7Tfrdusa7r3lNQc79vXuhIIMlatb7PQg7Vp\nContent-Disposition: form-data; name="meta-data"\nContent-Type: application/json; charset=UTF-8\nContent-Transfer-Encoding: 8bit\n\n{\n    "name": "value"\n}\n--edt7Tfrdusa7r3lNQc79vXuhIIMlatb7PQg7Vp\nContent-Disposition: form-data; name="file-data"; filename="file.properties"\nContent-Type: text/xml\nContent-Transfer-Encoding: 8bit\n... File Data ...\n')])])]),a("p",[e._v("You can access individual parts with "),a("code",[e._v("@RequestPart")]),e._v(", as the following example shows:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('@PostMapping("/")\npublic String handle(@RequestPart("meta-data") Part metadata, (1)\n        @RequestPart("file-data") FilePart file) { (2)\n    // ...\n}\n')])])]),a("table",[a("thead",[a("tr",[a("th",[a("strong",[e._v("1")])]),e._v(" "),a("th",[e._v("Using "),a("code",[e._v("@RequestPart")]),e._v(" to get the metadata.")])])]),e._v(" "),a("tbody",[a("tr",[a("td",[a("strong",[e._v("2")])]),e._v(" "),a("td",[e._v("Using "),a("code",[e._v("@RequestPart")]),e._v(" to get the file.")])])])]),e._v(" "),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('@PostMapping("/")\nfun handle(@RequestPart("meta-data") Part metadata, (1)\n        @RequestPart("file-data") FilePart file): String { (2)\n    // ...\n}\n')])])]),a("table",[a("thead",[a("tr",[a("th",[a("strong",[e._v("1")])]),e._v(" "),a("th",[e._v("Using "),a("code",[e._v("@RequestPart")]),e._v(" to get the metadata.")])])]),e._v(" "),a("tbody",[a("tr",[a("td",[a("strong",[e._v("2")])]),e._v(" "),a("td",[e._v("Using "),a("code",[e._v("@RequestPart")]),e._v(" to get the file.")])])])]),e._v(" "),a("p",[e._v("To deserialize the raw part content (for example, to JSON — similar to "),a("code",[e._v("@RequestBody")]),e._v("),\nyou can declare a concrete target "),a("code",[e._v("Object")]),e._v(", instead of "),a("code",[e._v("Part")]),e._v(", as the following example shows:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('@PostMapping("/")\npublic String handle(@RequestPart("meta-data") MetaData metadata) { (1)\n    // ...\n}\n')])])]),a("table",[a("thead",[a("tr",[a("th",[a("strong",[e._v("1")])]),e._v(" "),a("th",[e._v("Using "),a("code",[e._v("@RequestPart")]),e._v(" to get the metadata.")])])]),e._v(" "),a("tbody")]),e._v(" "),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('@PostMapping("/")\nfun handle(@RequestPart("meta-data") metadata: MetaData): String { (1)\n    // ...\n}\n')])])]),a("table",[a("thead",[a("tr",[a("th",[a("strong",[e._v("1")])]),e._v(" "),a("th",[e._v("Using "),a("code",[e._v("@RequestPart")]),e._v(" to get the metadata.")])])]),e._v(" "),a("tbody")]),e._v(" "),a("p",[e._v("You can use "),a("code",[e._v("@RequestPart")]),e._v(" in combination with "),a("code",[e._v("javax.validation.Valid")]),e._v(" or Spring’s"),a("code",[e._v("@Validated")]),e._v(" annotation, which causes Standard Bean Validation to be applied. Validation\nerrors lead to a "),a("code",[e._v("WebExchangeBindException")]),e._v(" that results in a 400 (BAD_REQUEST) response.\nThe exception contains a "),a("code",[e._v("BindingResult")]),e._v(" with the error details and can also be handled\nin the controller method by declaring the argument with an async wrapper and then using\nerror related operators:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('@PostMapping("/")\npublic String handle(@Valid @RequestPart("meta-data") Mono<MetaData> metadata) {\n    // use one of the onError* operators...\n}\n')])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('@PostMapping("/")\nfun handle(@Valid @RequestPart("meta-data") metadata: MetaData): String {\n    // ...\n}\n')])])]),a("p",[e._v("To access all multipart data as a "),a("code",[e._v("MultiValueMap")]),e._v(", you can use "),a("code",[e._v("@RequestBody")]),e._v(",\nas the following example shows:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('@PostMapping("/")\npublic String handle(@RequestBody Mono<MultiValueMap<String, Part>> parts) { (1)\n    // ...\n}\n')])])]),a("table",[a("thead",[a("tr",[a("th",[a("strong",[e._v("1")])]),e._v(" "),a("th",[e._v("Using "),a("code",[e._v("@RequestBody")]),e._v(".")])])]),e._v(" "),a("tbody")]),e._v(" "),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('@PostMapping("/")\nfun handle(@RequestBody parts: MultiValueMap<String, Part>): String { (1)\n    // ...\n}\n')])])]),a("table",[a("thead",[a("tr",[a("th",[a("strong",[e._v("1")])]),e._v(" "),a("th",[e._v("Using "),a("code",[e._v("@RequestBody")]),e._v(".")])])]),e._v(" "),a("tbody")]),e._v(" "),a("p",[e._v("To access multipart data sequentially, in streaming fashion, you can use "),a("code",[e._v("@RequestBody")]),e._v(" with"),a("code",[e._v("Flux<Part>")]),e._v(" (or "),a("code",[e._v("Flow<Part>")]),e._v(" in Kotlin) instead, as the following example shows:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('@PostMapping("/")\npublic String handle(@RequestBody Flux<Part> parts) { (1)\n    // ...\n}\n')])])]),a("table",[a("thead",[a("tr",[a("th",[a("strong",[e._v("1")])]),e._v(" "),a("th",[e._v("Using "),a("code",[e._v("@RequestBody")]),e._v(".")])])]),e._v(" "),a("tbody")]),e._v(" "),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('@PostMapping("/")\nfun handle(@RequestBody parts: Flow<Part>): String { (1)\n    // ...\n}\n')])])]),a("table",[a("thead",[a("tr",[a("th",[a("strong",[e._v("1")])]),e._v(" "),a("th",[e._v("Using "),a("code",[e._v("@RequestBody")]),e._v(".")])])]),e._v(" "),a("tbody")]),e._v(" "),a("h5",{attrs:{id:"requestbody"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#requestbody"}},[e._v("#")]),e._v(" "),a("code",[e._v("@RequestBody")])]),e._v(" "),a("p",[a("RouterLink",{attrs:{to:"/en/spring-framework/web.html#mvc-ann-requestbody"}},[e._v("Web MVC")])],1),e._v(" "),a("p",[e._v("You can use the "),a("code",[e._v("@RequestBody")]),e._v(" annotation to have the request body read and deserialized into an"),a("code",[e._v("Object")]),e._v(" through an "),a("a",{attrs:{href:"#webflux-codecs"}},[e._v("HttpMessageReader")]),e._v(".\nThe following example uses a "),a("code",[e._v("@RequestBody")]),e._v(" argument:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('@PostMapping("/accounts")\npublic void handle(@RequestBody Account account) {\n    // ...\n}\n')])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('@PostMapping("/accounts")\nfun handle(@RequestBody account: Account) {\n    // ...\n}\n')])])]),a("p",[e._v("Unlike Spring MVC, in WebFlux, the "),a("code",[e._v("@RequestBody")]),e._v(" method argument supports reactive types\nand fully non-blocking reading and (client-to-server) streaming.")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('@PostMapping("/accounts")\npublic void handle(@RequestBody Mono<Account> account) {\n    // ...\n}\n')])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('@PostMapping("/accounts")\nfun handle(@RequestBody accounts: Flow<Account>) {\n    // ...\n}\n')])])]),a("p",[e._v("You can use the "),a("a",{attrs:{href:"#webflux-config-message-codecs"}},[e._v("HTTP message codecs")]),e._v(" option of the "),a("a",{attrs:{href:"#webflux-config"}},[e._v("WebFlux Config")]),e._v(" to\nconfigure or customize message readers.")]),e._v(" "),a("p",[e._v("You can use "),a("code",[e._v("@RequestBody")]),e._v(" in combination with "),a("code",[e._v("javax.validation.Valid")]),e._v(" or Spring’s"),a("code",[e._v("@Validated")]),e._v(" annotation, which causes Standard Bean Validation to be applied. Validation\nerrors cause a "),a("code",[e._v("WebExchangeBindException")]),e._v(", which results in a 400 (BAD_REQUEST) response.\nThe exception contains a "),a("code",[e._v("BindingResult")]),e._v(" with error details and can be handled in the\ncontroller method by declaring the argument with an async wrapper and then using error\nrelated operators:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('@PostMapping("/accounts")\npublic void handle(@Valid @RequestBody Mono<Account> account) {\n    // use one of the onError* operators...\n}\n')])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('@PostMapping("/accounts")\nfun handle(@Valid @RequestBody account: Mono<Account>) {\n    // ...\n}\n')])])]),a("h5",{attrs:{id:"httpentity"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#httpentity"}},[e._v("#")]),e._v(" "),a("code",[e._v("HttpEntity")])]),e._v(" "),a("p",[a("RouterLink",{attrs:{to:"/en/spring-framework/web.html#mvc-ann-httpentity"}},[e._v("Web MVC")])],1),e._v(" "),a("p",[a("code",[e._v("HttpEntity")]),e._v(" is more or less identical to using "),a("a",{attrs:{href:"#webflux-ann-requestbody"}},[a("code",[e._v("@RequestBody")])]),e._v(" but is based on a\ncontainer object that exposes request headers and the body. The following example uses an"),a("code",[e._v("HttpEntity")]),e._v(":")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('@PostMapping("/accounts")\npublic void handle(HttpEntity<Account> entity) {\n    // ...\n}\n')])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('@PostMapping("/accounts")\nfun handle(entity: HttpEntity<Account>) {\n    // ...\n}\n')])])]),a("h5",{attrs:{id:"responsebody"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#responsebody"}},[e._v("#")]),e._v(" "),a("code",[e._v("@ResponseBody")])]),e._v(" "),a("p",[a("RouterLink",{attrs:{to:"/en/spring-framework/web.html#mvc-ann-responsebody"}},[e._v("Web MVC")])],1),e._v(" "),a("p",[e._v("You can use the "),a("code",[e._v("@ResponseBody")]),e._v(" annotation on a method to have the return serialized\nto the response body through an "),a("a",{attrs:{href:"#webflux-codecs"}},[e._v("HttpMessageWriter")]),e._v(". The following\nexample shows how to do so:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('@GetMapping("/accounts/{id}")\n@ResponseBody\npublic Account handle() {\n    // ...\n}\n')])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('@GetMapping("/accounts/{id}")\n@ResponseBody\nfun handle(): Account {\n    // ...\n}\n')])])]),a("p",[a("code",[e._v("@ResponseBody")]),e._v(" is also supported at the class level, in which case it is inherited by\nall controller methods. This is the effect of "),a("code",[e._v("@RestController")]),e._v(", which is nothing more\nthan a meta-annotation marked with "),a("code",[e._v("@Controller")]),e._v(" and "),a("code",[e._v("@ResponseBody")]),e._v(".")]),e._v(" "),a("p",[a("code",[e._v("@ResponseBody")]),e._v(" supports reactive types, which means you can return Reactor or RxJava\ntypes and have the asynchronous values they produce rendered to the response.\nFor additional details, see "),a("a",{attrs:{href:"#webflux-codecs-streaming"}},[e._v("Streaming")]),e._v(" and"),a("a",{attrs:{href:"#webflux-codecs-jackson"}},[e._v("JSON rendering")]),e._v(".")]),e._v(" "),a("p",[e._v("You can combine "),a("code",[e._v("@ResponseBody")]),e._v(" methods with JSON serialization views.\nSee "),a("a",{attrs:{href:"#webflux-ann-jackson"}},[e._v("Jackson JSON")]),e._v(" for details.")]),e._v(" "),a("p",[e._v("You can use the "),a("a",{attrs:{href:"#webflux-config-message-codecs"}},[e._v("HTTP message codecs")]),e._v(" option of the "),a("a",{attrs:{href:"#webflux-config"}},[e._v("WebFlux Config")]),e._v(" to\nconfigure or customize message writing.")]),e._v(" "),a("h5",{attrs:{id:"responseentity"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#responseentity"}},[e._v("#")]),e._v(" "),a("code",[e._v("ResponseEntity")])]),e._v(" "),a("p",[a("RouterLink",{attrs:{to:"/en/spring-framework/web.html#mvc-ann-responseentity"}},[e._v("Web MVC")])],1),e._v(" "),a("p",[a("code",[e._v("ResponseEntity")]),e._v(" is like "),a("a",{attrs:{href:"#webflux-ann-responsebody"}},[a("code",[e._v("@ResponseBody")])]),e._v(" but with status and headers. For example:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('@GetMapping("/something")\npublic ResponseEntity<String> handle() {\n    String body = ... ;\n    String etag = ... ;\n    return ResponseEntity.ok().eTag(etag).build(body);\n}\n')])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('@GetMapping("/something")\nfun handle(): ResponseEntity<String> {\n    val body: String = ...\n    val etag: String = ...\n    return ResponseEntity.ok().eTag(etag).build(body)\n}\n')])])]),a("p",[e._v("WebFlux supports using a single value "),a("a",{attrs:{href:"#webflux-reactive-libraries"}},[e._v("reactive type")]),e._v(" to\nproduce the "),a("code",[e._v("ResponseEntity")]),e._v(" asynchronously, and/or single and multi-value reactive types\nfor the body. This allows a variety of async responses with "),a("code",[e._v("ResponseEntity")]),e._v(" as follows:")]),e._v(" "),a("ul",[a("li",[a("p",[a("code",[e._v("ResponseEntity<Mono<T>>")]),e._v(" or "),a("code",[e._v("ResponseEntity<Flux<T>>")]),e._v(" make the response status and\nheaders known immediately while the body is provided asynchronously at a later point.\nUse "),a("code",[e._v("Mono")]),e._v(" if the body consists of 0..1 values or "),a("code",[e._v("Flux")]),e._v(" if it can produce multiple values.")])]),e._v(" "),a("li",[a("p",[a("code",[e._v("Mono<ResponseEntity<T>>")]),e._v(" provides all three — response status, headers, and body,\nasynchronously at a later point. This allows the response status and headers to vary\ndepending on the outcome of asynchronous request handling.")])]),e._v(" "),a("li",[a("p",[a("code",[e._v("Mono<ResponseEntity<Mono<T>>>")]),e._v(" or "),a("code",[e._v("Mono<ResponseEntity<Flux<T>>>")]),e._v(" are yet another\npossible, albeit less common alternative. They provide the response status and headers\nasynchronously first and then the response body, also asynchronously, second.")])])]),e._v(" "),a("h5",{attrs:{id:"jackson-json-2"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#jackson-json-2"}},[e._v("#")]),e._v(" Jackson JSON")]),e._v(" "),a("p",[e._v("Spring offers support for the Jackson JSON library.")]),e._v(" "),a("h5",{attrs:{id:"json-views"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#json-views"}},[e._v("#")]),e._v(" JSON Views#")]),e._v(" "),a("p",[a("RouterLink",{attrs:{to:"/en/spring-framework/web.html#mvc-ann-jackson"}},[e._v("Web MVC")])],1),e._v(" "),a("p",[e._v("Spring WebFlux provides built-in support for"),a("a",{attrs:{href:"https://www.baeldung.com/jackson-json-view-annotation",target:"_blank",rel:"noopener noreferrer"}},[e._v("Jackson’s Serialization Views"),a("OutboundLink")],1),e._v(",\nwhich allows rendering only a subset of all fields in an "),a("code",[e._v("Object")]),e._v(". To use it with"),a("code",[e._v("@ResponseBody")]),e._v(" or "),a("code",[e._v("ResponseEntity")]),e._v(" controller methods, you can use Jackson’s"),a("code",[e._v("@JsonView")]),e._v(" annotation to activate a serialization view class, as the following example shows:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('@RestController\npublic class UserController {\n\n    @GetMapping("/user")\n    @JsonView(User.WithoutPasswordView.class)\n    public User getUser() {\n        return new User("eric", "7!jd#h23");\n    }\n}\n\npublic class User {\n\n    public interface WithoutPasswordView {};\n    public interface WithPasswordView extends WithoutPasswordView {};\n\n    private String username;\n    private String password;\n\n    public User() {\n    }\n\n    public User(String username, String password) {\n        this.username = username;\n        this.password = password;\n    }\n\n    @JsonView(WithoutPasswordView.class)\n    public String getUsername() {\n        return this.username;\n    }\n\n    @JsonView(WithPasswordView.class)\n    public String getPassword() {\n        return this.password;\n    }\n}\n')])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('@RestController\nclass UserController {\n\n    @GetMapping("/user")\n    @JsonView(User.WithoutPasswordView::class)\n    fun getUser(): User {\n        return User("eric", "7!jd#h23")\n    }\n}\n\nclass User(\n        @JsonView(WithoutPasswordView::class) val username: String,\n        @JsonView(WithPasswordView::class) val password: String\n) {\n    interface WithoutPasswordView\n    interface WithPasswordView : WithoutPasswordView\n}\n')])])]),a("table",[a("thead",[a("tr",[a("th"),e._v(" "),a("th",[a("code",[e._v("@JsonView")]),e._v(" allows an array of view classes but you can only specify only one per"),a("br"),e._v("controller method. Use a composite interface if you need to activate multiple views.")])])]),e._v(" "),a("tbody")]),e._v(" "),a("h4",{attrs:{id:"_1-4-4-model"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_1-4-4-model"}},[e._v("#")]),e._v(" 1.4.4. "),a("code",[e._v("Model")])]),e._v(" "),a("p",[a("RouterLink",{attrs:{to:"/en/spring-framework/web.html#mvc-ann-modelattrib-methods"}},[e._v("Web MVC")])],1),e._v(" "),a("p",[e._v("You can use the "),a("code",[e._v("@ModelAttribute")]),e._v(" annotation:")]),e._v(" "),a("ul",[a("li",[a("p",[e._v("On a "),a("a",{attrs:{href:"#webflux-ann-modelattrib-method-args"}},[e._v("method argument")]),e._v(" in "),a("code",[e._v("@RequestMapping")]),e._v(" methods\nto create or access an Object from the model and to bind it to the request through a"),a("code",[e._v("WebDataBinder")]),e._v(".")])]),e._v(" "),a("li",[a("p",[e._v("As a method-level annotation in "),a("code",[e._v("@Controller")]),e._v(" or "),a("code",[e._v("@ControllerAdvice")]),e._v(" classes, helping\nto initialize the model prior to any "),a("code",[e._v("@RequestMapping")]),e._v(" method invocation.")])]),e._v(" "),a("li",[a("p",[e._v("On a "),a("code",[e._v("@RequestMapping")]),e._v(" method to mark its return value as a model attribute.")])])]),e._v(" "),a("p",[e._v("This section discusses "),a("code",[e._v("@ModelAttribute")]),e._v(" methods, or the second item from the preceding list.\nA controller can have any number of "),a("code",[e._v("@ModelAttribute")]),e._v(" methods. All such methods are\ninvoked before "),a("code",[e._v("@RequestMapping")]),e._v(" methods in the same controller. A "),a("code",[e._v("@ModelAttribute")]),e._v("method can also be shared across controllers through "),a("code",[e._v("@ControllerAdvice")]),e._v(". See the section on"),a("a",{attrs:{href:"#webflux-ann-controller-advice"}},[e._v("Controller Advice")]),e._v(" for more details.")]),e._v(" "),a("p",[a("code",[e._v("@ModelAttribute")]),e._v(" methods have flexible method signatures. They support many of the same\narguments as "),a("code",[e._v("@RequestMapping")]),e._v(" methods (except for "),a("code",[e._v("@ModelAttribute")]),e._v(" itself and anything\nrelated to the request body).")]),e._v(" "),a("p",[e._v("The following example uses a "),a("code",[e._v("@ModelAttribute")]),e._v(" method:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("@ModelAttribute\npublic void populateModel(@RequestParam String number, Model model) {\n    model.addAttribute(accountRepository.findAccount(number));\n    // add more ...\n}\n")])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("@ModelAttribute\nfun populateModel(@RequestParam number: String, model: Model) {\n    model.addAttribute(accountRepository.findAccount(number))\n    // add more ...\n}\n")])])]),a("p",[e._v("The following example adds one attribute only:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("@ModelAttribute\npublic Account addAccount(@RequestParam String number) {\n    return accountRepository.findAccount(number);\n}\n")])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("@ModelAttribute\nfun addAccount(@RequestParam number: String): Account {\n    return accountRepository.findAccount(number);\n}\n")])])]),a("table",[a("thead",[a("tr",[a("th"),e._v(" "),a("th",[e._v("When a name is not explicitly specified, a default name is chosen based on the type,"),a("br"),e._v("as explained in the javadoc for "),a("a",{attrs:{href:"https://docs.spring.io/spring-framework/docs/5.3.16/javadoc-api/org/springframework/core/Conventions.html",target:"_blank",rel:"noopener noreferrer"}},[a("code",[e._v("Conventions")]),a("OutboundLink")],1),e._v("."),a("br"),e._v("You can always assign an explicit name by using the overloaded "),a("code",[e._v("addAttribute")]),e._v(" method or"),a("br"),e._v("through the name attribute on "),a("code",[e._v("@ModelAttribute")]),e._v(" (for a return value).")])])]),e._v(" "),a("tbody")]),e._v(" "),a("p",[e._v("Spring WebFlux, unlike Spring MVC, explicitly supports reactive types in the model\n(for example, "),a("code",[e._v("Mono<Account>")]),e._v(" or "),a("code",[e._v("io.reactivex.Single<Account>")]),e._v("). Such asynchronous model\nattributes can be transparently resolved (and the model updated) to their actual values\nat the time of "),a("code",[e._v("@RequestMapping")]),e._v(" invocation, provided a "),a("code",[e._v("@ModelAttribute")]),e._v(" argument is\ndeclared without a wrapper, as the following example shows:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('@ModelAttribute\npublic void addAccount(@RequestParam String number) {\n    Mono<Account> accountMono = accountRepository.findAccount(number);\n    model.addAttribute("account", accountMono);\n}\n\n@PostMapping("/accounts")\npublic String handle(@ModelAttribute Account account, BindingResult errors) {\n    // ...\n}\n')])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('import org.springframework.ui.set\n\n@ModelAttribute\nfun addAccount(@RequestParam number: String) {\n    val accountMono: Mono<Account> = accountRepository.findAccount(number)\n    model["account"] = accountMono\n}\n\n@PostMapping("/accounts")\nfun handle(@ModelAttribute account: Account, errors: BindingResult): String {\n    // ...\n}\n')])])]),a("p",[e._v("In addition, any model attributes that have a reactive type wrapper are resolved to their\nactual values (and the model updated) just prior to view rendering.")]),e._v(" "),a("p",[e._v("You can also use "),a("code",[e._v("@ModelAttribute")]),e._v(" as a method-level annotation on "),a("code",[e._v("@RequestMapping")]),e._v("methods, in which case the return value of the "),a("code",[e._v("@RequestMapping")]),e._v(" method is interpreted as a\nmodel attribute. This is typically not required, as it is the default behavior in HTML\ncontrollers, unless the return value is a "),a("code",[e._v("String")]),e._v(" that would otherwise be interpreted\nas a view name. "),a("code",[e._v("@ModelAttribute")]),e._v(" can also help to customize the model attribute name,\nas the following example shows:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('@GetMapping("/accounts/{id}")\n@ModelAttribute("myAccount")\npublic Account handle() {\n    // ...\n    return account;\n}\n')])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('@GetMapping("/accounts/{id}")\n@ModelAttribute("myAccount")\nfun handle(): Account {\n    // ...\n    return account\n}\n')])])]),a("h4",{attrs:{id:"_1-4-5-databinder"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_1-4-5-databinder"}},[e._v("#")]),e._v(" 1.4.5. "),a("code",[e._v("DataBinder")])]),e._v(" "),a("p",[a("RouterLink",{attrs:{to:"/en/spring-framework/web.html#mvc-ann-initbinder"}},[e._v("Web MVC")])],1),e._v(" "),a("p",[a("code",[e._v("@Controller")]),e._v(" or "),a("code",[e._v("@ControllerAdvice")]),e._v(" classes can have "),a("code",[e._v("@InitBinder")]),e._v(" methods, to\ninitialize instances of "),a("code",[e._v("WebDataBinder")]),e._v(". Those, in turn, are used to:")]),e._v(" "),a("ul",[a("li",[a("p",[e._v("Bind request parameters (that is, form data or query) to a model object.")])]),e._v(" "),a("li",[a("p",[e._v("Convert "),a("code",[e._v("String")]),e._v("-based request values (such as request parameters, path variables,\nheaders, cookies, and others) to the target type of controller method arguments.")])]),e._v(" "),a("li",[a("p",[e._v("Format model object values as "),a("code",[e._v("String")]),e._v(" values when rendering HTML forms.")])])]),e._v(" "),a("p",[a("code",[e._v("@InitBinder")]),e._v(" methods can register controller-specific "),a("code",[e._v("java.beans.PropertyEditor")]),e._v(" or\nSpring "),a("code",[e._v("Converter")]),e._v(" and "),a("code",[e._v("Formatter")]),e._v(" components. In addition, you can use the"),a("a",{attrs:{href:"#webflux-config-conversion"}},[e._v("WebFlux Java configuration")]),e._v(" to register "),a("code",[e._v("Converter")]),e._v(" and"),a("code",[e._v("Formatter")]),e._v(" types in a globally shared "),a("code",[e._v("FormattingConversionService")]),e._v(".")]),e._v(" "),a("p",[a("code",[e._v("@InitBinder")]),e._v(" methods support many of the same arguments that "),a("code",[e._v("@RequestMapping")]),e._v(" methods\ndo, except for "),a("code",[e._v("@ModelAttribute")]),e._v(" (command object) arguments. Typically, they are declared\nwith a "),a("code",[e._v("WebDataBinder")]),e._v(" argument, for registrations, and a "),a("code",[e._v("void")]),e._v(" return value.\nThe following example uses the "),a("code",[e._v("@InitBinder")]),e._v(" annotation:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('@Controller\npublic class FormController {\n\n    @InitBinder (1)\n    public void initBinder(WebDataBinder binder) {\n        SimpleDateFormat dateFormat = new SimpleDateFormat("yyyy-MM-dd");\n        dateFormat.setLenient(false);\n        binder.registerCustomEditor(Date.class, new CustomDateEditor(dateFormat, false));\n    }\n\n    // ...\n}\n')])])]),a("table",[a("thead",[a("tr",[a("th",[a("strong",[e._v("1")])]),e._v(" "),a("th",[e._v("Using the "),a("code",[e._v("@InitBinder")]),e._v(" annotation.")])])]),e._v(" "),a("tbody")]),e._v(" "),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('@Controller\nclass FormController {\n\n    @InitBinder (1)\n    fun initBinder(binder: WebDataBinder) {\n        val dateFormat = SimpleDateFormat("yyyy-MM-dd")\n        dateFormat.isLenient = false\n        binder.registerCustomEditor(Date::class.java, CustomDateEditor(dateFormat, false))\n    }\n\n    // ...\n}\n')])])]),a("p",[e._v("Alternatively, when using a "),a("code",[e._v("Formatter")]),e._v("-based setup through a shared"),a("code",[e._v("FormattingConversionService")]),e._v(", you could re-use the same approach and register\ncontroller-specific "),a("code",[e._v("Formatter")]),e._v(" instances, as the following example shows:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('@Controller\npublic class FormController {\n\n    @InitBinder\n    protected void initBinder(WebDataBinder binder) {\n        binder.addCustomFormatter(new DateFormatter("yyyy-MM-dd")); (1)\n    }\n\n    // ...\n}\n')])])]),a("table",[a("thead",[a("tr",[a("th",[a("strong",[e._v("1")])]),e._v(" "),a("th",[e._v("Adding a custom formatter (a "),a("code",[e._v("DateFormatter")]),e._v(", in this case).")])])]),e._v(" "),a("tbody")]),e._v(" "),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('@Controller\nclass FormController {\n\n    @InitBinder\n    fun initBinder(binder: WebDataBinder) {\n        binder.addCustomFormatter(DateFormatter("yyyy-MM-dd")) (1)\n    }\n\n    // ...\n}\n')])])]),a("table",[a("thead",[a("tr",[a("th",[a("strong",[e._v("1")])]),e._v(" "),a("th",[e._v("Adding a custom formatter (a "),a("code",[e._v("DateFormatter")]),e._v(", in this case).")])])]),e._v(" "),a("tbody")]),e._v(" "),a("h4",{attrs:{id:"_1-4-6-managing-exceptions"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_1-4-6-managing-exceptions"}},[e._v("#")]),e._v(" 1.4.6. Managing Exceptions")]),e._v(" "),a("p",[a("RouterLink",{attrs:{to:"/en/spring-framework/web.html#mvc-ann-exceptionhandler"}},[e._v("Web MVC")])],1),e._v(" "),a("p",[a("code",[e._v("@Controller")]),e._v(" and "),a("a",{attrs:{href:"#webflux-ann-controller-advice"}},[e._v("@ControllerAdvice")]),e._v(" classes can have"),a("code",[e._v("@ExceptionHandler")]),e._v(" methods to handle exceptions from controller methods. The following\nexample includes such a handler method:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("@Controller\npublic class SimpleController {\n\n    // ...\n\n    @ExceptionHandler (1)\n    public ResponseEntity<String> handle(IOException ex) {\n        // ...\n    }\n}\n")])])]),a("table",[a("thead",[a("tr",[a("th",[a("strong",[e._v("1")])]),e._v(" "),a("th",[e._v("Declaring an "),a("code",[e._v("@ExceptionHandler")]),e._v(".")])])]),e._v(" "),a("tbody")]),e._v(" "),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("@Controller\nclass SimpleController {\n\n    // ...\n\n    @ExceptionHandler (1)\n    fun handle(ex: IOException): ResponseEntity<String> {\n        // ...\n    }\n}\n")])])]),a("table",[a("thead",[a("tr",[a("th",[a("strong",[e._v("1")])]),e._v(" "),a("th",[e._v("Declaring an "),a("code",[e._v("@ExceptionHandler")]),e._v(".")])])]),e._v(" "),a("tbody")]),e._v(" "),a("p",[e._v("The exception can match against a top-level exception being propagated (that is, a direct"),a("code",[e._v("IOException")]),e._v(" being thrown) or against the immediate cause within a top-level wrapper\nexception (for example, an "),a("code",[e._v("IOException")]),e._v(" wrapped inside an "),a("code",[e._v("IllegalStateException")]),e._v(").")]),e._v(" "),a("p",[e._v("For matching exception types, preferably declare the target exception as a method argument,\nas shown in the preceding example. Alternatively, the annotation declaration can narrow the\nexception types to match. We generally recommend being as specific as possible in the\nargument signature and to declare your primary root exception mappings on a"),a("code",[e._v("@ControllerAdvice")]),e._v(" prioritized with a corresponding order.\nSee "),a("RouterLink",{attrs:{to:"/en/spring-framework/web.html#mvc-ann-exceptionhandler"}},[e._v("the MVC section")]),e._v(" for details.")],1),e._v(" "),a("table",[a("thead",[a("tr",[a("th"),e._v(" "),a("th",[e._v("An "),a("code",[e._v("@ExceptionHandler")]),e._v(" method in WebFlux supports the same method arguments and"),a("br"),e._v("return values as a "),a("code",[e._v("@RequestMapping")]),e._v(" method, with the exception of request body-"),a("br"),e._v("and "),a("code",[e._v("@ModelAttribute")]),e._v("-related method arguments.")])])]),e._v(" "),a("tbody")]),e._v(" "),a("p",[e._v("Support for "),a("code",[e._v("@ExceptionHandler")]),e._v(" methods in Spring WebFlux is provided by the"),a("code",[e._v("HandlerAdapter")]),e._v(" for "),a("code",[e._v("@RequestMapping")]),e._v(" methods. See "),a("a",{attrs:{href:"#webflux-dispatcher-handler"}},[a("code",[e._v("DispatcherHandler")])]),e._v("for more detail.")]),e._v(" "),a("h5",{attrs:{id:"rest-api-exceptions"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#rest-api-exceptions"}},[e._v("#")]),e._v(" REST API exceptions")]),e._v(" "),a("p",[a("RouterLink",{attrs:{to:"/en/spring-framework/web.html#mvc-ann-rest-exceptions"}},[e._v("Web MVC")])],1),e._v(" "),a("p",[e._v("A common requirement for REST services is to include error details in the body of the\nresponse. The Spring Framework does not automatically do so, because the representation\nof error details in the response body is application-specific. However, a"),a("code",[e._v("@RestController")]),e._v(" can use "),a("code",[e._v("@ExceptionHandler")]),e._v(" methods with a "),a("code",[e._v("ResponseEntity")]),e._v(" return\nvalue to set the status and the body of the response. Such methods can also be declared\nin "),a("code",[e._v("@ControllerAdvice")]),e._v(" classes to apply them globally.")]),e._v(" "),a("table",[a("thead",[a("tr",[a("th"),e._v(" "),a("th",[e._v("Note that Spring WebFlux does not have an equivalent for the Spring MVC"),a("code",[e._v("ResponseEntityExceptionHandler")]),e._v(", because WebFlux raises only "),a("code",[e._v("ResponseStatusException")]),e._v("(or subclasses thereof), and those do not need to be translated to"),a("br"),e._v("an HTTP status code.")])])]),e._v(" "),a("tbody")]),e._v(" "),a("h4",{attrs:{id:"_1-4-7-controller-advice"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_1-4-7-controller-advice"}},[e._v("#")]),e._v(" 1.4.7. Controller Advice")]),e._v(" "),a("p",[a("RouterLink",{attrs:{to:"/en/spring-framework/web.html#mvc-ann-controller-advice"}},[e._v("Web MVC")])],1),e._v(" "),a("p",[e._v("Typically, the "),a("code",[e._v("@ExceptionHandler")]),e._v(", "),a("code",[e._v("@InitBinder")]),e._v(", and "),a("code",[e._v("@ModelAttribute")]),e._v(" methods apply\nwithin the "),a("code",[e._v("@Controller")]),e._v(" class (or class hierarchy) in which they are declared. If you\nwant such methods to apply more globally (across controllers), you can declare them in a\nclass annotated with "),a("code",[e._v("@ControllerAdvice")]),e._v(" or "),a("code",[e._v("@RestControllerAdvice")]),e._v(".")]),e._v(" "),a("p",[a("code",[e._v("@ControllerAdvice")]),e._v(" is annotated with "),a("code",[e._v("@Component")]),e._v(", which means that such classes can be\nregistered as Spring beans through "),a("RouterLink",{attrs:{to:"/en/spring-framework/core.html#beans-java-instantiating-container-scan"}},[e._v("component scanning")]),e._v(". "),a("code",[e._v("@RestControllerAdvice")]),e._v(" is a composed annotation that is annotated\nwith both "),a("code",[e._v("@ControllerAdvice")]),e._v(" and "),a("code",[e._v("@ResponseBody")]),e._v(", which essentially means"),a("code",[e._v("@ExceptionHandler")]),e._v(" methods are rendered to the response body through message conversion\n(versus view resolution or template rendering).")],1),e._v(" "),a("p",[e._v("On startup, the infrastructure classes for "),a("code",[e._v("@RequestMapping")]),e._v(" and "),a("code",[e._v("@ExceptionHandler")]),e._v("methods detect Spring beans annotated with "),a("code",[e._v("@ControllerAdvice")]),e._v(" and then apply their\nmethods at runtime. Global "),a("code",[e._v("@ExceptionHandler")]),e._v(" methods (from a "),a("code",[e._v("@ControllerAdvice")]),e._v(") are\napplied "),a("em",[e._v("after")]),e._v(" local ones (from the "),a("code",[e._v("@Controller")]),e._v("). By contrast, global "),a("code",[e._v("@ModelAttribute")]),e._v("and "),a("code",[e._v("@InitBinder")]),e._v(" methods are applied "),a("em",[e._v("before")]),e._v(" local ones.")]),e._v(" "),a("p",[e._v("By default, "),a("code",[e._v("@ControllerAdvice")]),e._v(" methods apply to every request (that is, all controllers),\nbut you can narrow that down to a subset of controllers by using attributes on the\nannotation, as the following example shows:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('// Target all Controllers annotated with @RestController\n@ControllerAdvice(annotations = RestController.class)\npublic class ExampleAdvice1 {}\n\n// Target all Controllers within specific packages\n@ControllerAdvice("org.example.controllers")\npublic class ExampleAdvice2 {}\n\n// Target all Controllers assignable to specific classes\n@ControllerAdvice(assignableTypes = {ControllerInterface.class, AbstractController.class})\npublic class ExampleAdvice3 {}\n')])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('// Target all Controllers annotated with @RestController\n@ControllerAdvice(annotations = [RestController::class])\npublic class ExampleAdvice1 {}\n\n// Target all Controllers within specific packages\n@ControllerAdvice("org.example.controllers")\npublic class ExampleAdvice2 {}\n\n// Target all Controllers assignable to specific classes\n@ControllerAdvice(assignableTypes = [ControllerInterface::class, AbstractController::class])\npublic class ExampleAdvice3 {}\n')])])]),a("p",[e._v("The selectors in the preceding example are evaluated at runtime and may negatively impact\nperformance if used extensively. See the"),a("a",{attrs:{href:"https://docs.spring.io/spring-framework/docs/5.3.16/javadoc-api/org/springframework/web/bind/annotation/ControllerAdvice.html",target:"_blank",rel:"noopener noreferrer"}},[a("code",[e._v("@ControllerAdvice")]),a("OutboundLink")],1),e._v("javadoc for more details.")]),e._v(" "),a("h3",{attrs:{id:"_1-5-functional-endpoints"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_1-5-functional-endpoints"}},[e._v("#")]),e._v(" 1.5. Functional Endpoints")]),e._v(" "),a("p",[a("RouterLink",{attrs:{to:"/en/spring-framework/web.html#webmvc-fn"}},[e._v("Web MVC")])],1),e._v(" "),a("p",[e._v("Spring WebFlux includes WebFlux.fn, a lightweight functional programming model in which functions\nare used to route and handle requests and contracts are designed for immutability.\nIt is an alternative to the annotation-based programming model but otherwise runs on\nthe same "),a("a",{attrs:{href:"#webflux-reactive-spring-web"}},[e._v("Reactive Core")]),e._v(" foundation.")]),e._v(" "),a("h4",{attrs:{id:"_1-5-1-overview"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_1-5-1-overview"}},[e._v("#")]),e._v(" 1.5.1. Overview")]),e._v(" "),a("p",[a("RouterLink",{attrs:{to:"/en/spring-framework/web.html#webmvc-fn-overview"}},[e._v("Web MVC")])],1),e._v(" "),a("p",[e._v("In WebFlux.fn, an HTTP request is handled with a "),a("code",[e._v("HandlerFunction")]),e._v(": a function that takes"),a("code",[e._v("ServerRequest")]),e._v(" and returns a delayed "),a("code",[e._v("ServerResponse")]),e._v(" (i.e. "),a("code",[e._v("Mono<ServerResponse>")]),e._v(").\nBoth the request and the response object have immutable contracts that offer JDK 8-friendly\naccess to the HTTP request and response."),a("code",[e._v("HandlerFunction")]),e._v(" is the equivalent of the body of a "),a("code",[e._v("@RequestMapping")]),e._v(" method in the\nannotation-based programming model.")]),e._v(" "),a("p",[e._v("Incoming requests are routed to a handler function with a "),a("code",[e._v("RouterFunction")]),e._v(": a function that\ntakes "),a("code",[e._v("ServerRequest")]),e._v(" and returns a delayed "),a("code",[e._v("HandlerFunction")]),e._v(" (i.e. "),a("code",[e._v("Mono<HandlerFunction>")]),e._v(").\nWhen the router function matches, a handler function is returned; otherwise an empty Mono."),a("code",[e._v("RouterFunction")]),e._v(" is the equivalent of a "),a("code",[e._v("@RequestMapping")]),e._v(" annotation, but with the major\ndifference that router functions provide not just data, but also behavior.")]),e._v(" "),a("p",[a("code",[e._v("RouterFunctions.route()")]),e._v(" provides a router builder that facilitates the creation of routers,\nas the following example shows:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('import static org.springframework.http.MediaType.APPLICATION_JSON;\nimport static org.springframework.web.reactive.function.server.RequestPredicates.*;\nimport static org.springframework.web.reactive.function.server.RouterFunctions.route;\n\nPersonRepository repository = ...\nPersonHandler handler = new PersonHandler(repository);\n\nRouterFunction<ServerResponse> route = route()\n    .GET("/person/{id}", accept(APPLICATION_JSON), handler::getPerson)\n    .GET("/person", accept(APPLICATION_JSON), handler::listPeople)\n    .POST("/person", handler::createPerson)\n    .build();\n\npublic class PersonHandler {\n\n    // ...\n\n    public Mono<ServerResponse> listPeople(ServerRequest request) {\n        // ...\n    }\n\n    public Mono<ServerResponse> createPerson(ServerRequest request) {\n        // ...\n    }\n\n    public Mono<ServerResponse> getPerson(ServerRequest request) {\n        // ...\n    }\n}\n')])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('val repository: PersonRepository = ...\nval handler = PersonHandler(repository)\n\nval route = coRouter { (1)\n    accept(APPLICATION_JSON).nest {\n        GET("/person/{id}", handler::getPerson)\n        GET("/person", handler::listPeople)\n    }\n    POST("/person", handler::createPerson)\n}\n\nclass PersonHandler(private val repository: PersonRepository) {\n\n    // ...\n\n    suspend fun listPeople(request: ServerRequest): ServerResponse {\n        // ...\n    }\n\n    suspend fun createPerson(request: ServerRequest): ServerResponse {\n        // ...\n    }\n\n    suspend fun getPerson(request: ServerRequest): ServerResponse {\n        // ...\n    }\n}\n')])])]),a("table",[a("thead",[a("tr",[a("th",[a("strong",[e._v("1")])]),e._v(" "),a("th",[e._v("Create router using Coroutines router DSL, a Reactive alternative is also available via "),a("code",[e._v("router { }")]),e._v(".")])])]),e._v(" "),a("tbody")]),e._v(" "),a("p",[e._v("One way to run a "),a("code",[e._v("RouterFunction")]),e._v(" is to turn it into an "),a("code",[e._v("HttpHandler")]),e._v(" and install it\nthrough one of the built-in "),a("a",{attrs:{href:"#webflux-httphandler"}},[e._v("server adapters")]),e._v(":")]),e._v(" "),a("ul",[a("li",[a("p",[a("code",[e._v("RouterFunctions.toHttpHandler(RouterFunction)")])])]),e._v(" "),a("li",[a("p",[a("code",[e._v("RouterFunctions.toHttpHandler(RouterFunction, HandlerStrategies)")])])])]),e._v(" "),a("p",[e._v("Most applications can run through the WebFlux Java configuration, see "),a("a",{attrs:{href:"#webflux-fn-running"}},[e._v("Running a Server")]),e._v(".")]),e._v(" "),a("h4",{attrs:{id:"_1-5-2-handlerfunction"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_1-5-2-handlerfunction"}},[e._v("#")]),e._v(" 1.5.2. HandlerFunction")]),e._v(" "),a("p",[a("RouterLink",{attrs:{to:"/en/spring-framework/web.html#webmvc-fn-handler-functions"}},[e._v("Web MVC")])],1),e._v(" "),a("p",[a("code",[e._v("ServerRequest")]),e._v(" and "),a("code",[e._v("ServerResponse")]),e._v(" are immutable interfaces that offer JDK 8-friendly\naccess to the HTTP request and response.\nBoth request and response provide "),a("a",{attrs:{href:"https://www.reactive-streams.org",target:"_blank",rel:"noopener noreferrer"}},[e._v("Reactive Streams"),a("OutboundLink")],1),e._v(" back pressure\nagainst the body streams.\nThe request body is represented with a Reactor "),a("code",[e._v("Flux")]),e._v(" or "),a("code",[e._v("Mono")]),e._v(".\nThe response body is represented with any Reactive Streams "),a("code",[e._v("Publisher")]),e._v(", including "),a("code",[e._v("Flux")]),e._v(" and "),a("code",[e._v("Mono")]),e._v(".\nFor more on that, see "),a("a",{attrs:{href:"#webflux-reactive-libraries"}},[e._v("Reactive Libraries")]),e._v(".")]),e._v(" "),a("h5",{attrs:{id:"serverrequest"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#serverrequest"}},[e._v("#")]),e._v(" ServerRequest")]),e._v(" "),a("p",[a("code",[e._v("ServerRequest")]),e._v(" provides access to the HTTP method, URI, headers, and query parameters,\nwhile access to the body is provided through the "),a("code",[e._v("body")]),e._v(" methods.")]),e._v(" "),a("p",[e._v("The following example extracts the request body to a "),a("code",[e._v("Mono<String>")]),e._v(":")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("Mono<String> string = request.bodyToMono(String.class);\n")])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("val string = request.awaitBody<String>()\n")])])]),a("p",[e._v("The following example extracts the body to a "),a("code",[e._v("Flux<Person>")]),e._v(" (or a "),a("code",[e._v("Flow<Person>")]),e._v(" in Kotlin),\nwhere "),a("code",[e._v("Person")]),e._v(" objects are decoded from someserialized form, such as JSON or XML:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("Flux<Person> people = request.bodyToFlux(Person.class);\n")])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("val people = request.bodyToFlow<Person>()\n")])])]),a("p",[e._v("The preceding examples are shortcuts that use the more general "),a("code",[e._v("ServerRequest.body(BodyExtractor)")]),e._v(",\nwhich accepts the "),a("code",[e._v("BodyExtractor")]),e._v(" functional strategy interface. The utility class"),a("code",[e._v("BodyExtractors")]),e._v(" provides access to a number of instances. For example, the preceding examples can\nalso be written as follows:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("Mono<String> string = request.body(BodyExtractors.toMono(String.class));\nFlux<Person> people = request.body(BodyExtractors.toFlux(Person.class));\n")])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("    val string = request.body(BodyExtractors.toMono(String::class.java)).awaitSingle()\n    val people = request.body(BodyExtractors.toFlux(Person::class.java)).asFlow()\n")])])]),a("p",[e._v("The following example shows how to access form data:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("Mono<MultiValueMap<String, String>> map = request.formData();\n")])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("val map = request.awaitFormData()\n")])])]),a("p",[e._v("The following example shows how to access multipart data as a map:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("Mono<MultiValueMap<String, Part>> map = request.multipartData();\n")])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("val map = request.awaitMultipartData()\n")])])]),a("p",[e._v("The following example shows how to access multiparts, one at a time, in streaming fashion:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("Flux<Part> parts = request.body(BodyExtractors.toParts());\n")])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("val parts = request.body(BodyExtractors.toParts()).asFlow()\n")])])]),a("h5",{attrs:{id:"serverresponse"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#serverresponse"}},[e._v("#")]),e._v(" ServerResponse")]),e._v(" "),a("p",[a("code",[e._v("ServerResponse")]),e._v(" provides access to the HTTP response and, since it is immutable, you can use\na "),a("code",[e._v("build")]),e._v(" method to create it. You can use the builder to set the response status, to add response\nheaders, or to provide a body. The following example creates a 200 (OK) response with JSON\ncontent:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("Mono<Person> person = ...\nServerResponse.ok().contentType(MediaType.APPLICATION_JSON).body(person, Person.class);\n")])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("val person: Person = ...\nServerResponse.ok().contentType(MediaType.APPLICATION_JSON).bodyValue(person)\n")])])]),a("p",[e._v("The following example shows how to build a 201 (CREATED) response with a "),a("code",[e._v("Location")]),e._v(" header and no body:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("URI location = ...\nServerResponse.created(location).build();\n")])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("val location: URI = ...\nServerResponse.created(location).build()\n")])])]),a("p",[e._v("Depending on the codec used, it is possible to pass hint parameters to customize how the\nbody is serialized or deserialized. For example, to specify a "),a("a",{attrs:{href:"https://www.baeldung.com/jackson-json-view-annotation",target:"_blank",rel:"noopener noreferrer"}},[e._v("Jackson JSON view"),a("OutboundLink")],1),e._v(":")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("ServerResponse.ok().hint(Jackson2CodecSupport.JSON_VIEW_HINT, MyJacksonView.class).body(...);\n")])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("ServerResponse.ok().hint(Jackson2CodecSupport.JSON_VIEW_HINT, MyJacksonView::class.java).body(...)\n")])])]),a("h5",{attrs:{id:"handler-classes"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#handler-classes"}},[e._v("#")]),e._v(" Handler Classes")]),e._v(" "),a("p",[e._v("We can write a handler function as a lambda, as the following example shows:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('HandlerFunction<ServerResponse> helloWorld =\n  request -> ServerResponse.ok().bodyValue("Hello World");\n')])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('val helloWorld = HandlerFunction<ServerResponse> { ServerResponse.ok().bodyValue("Hello World") }\n')])])]),a("p",[e._v("That is convenient, but in an application we need multiple functions, and multiple inline\nlambda’s can get messy.\nTherefore, it is useful to group related handler functions together into a handler class, which\nhas a similar role as "),a("code",[e._v("@Controller")]),e._v(" in an annotation-based application.\nFor example, the following class exposes a reactive "),a("code",[e._v("Person")]),e._v(" repository:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('import static org.springframework.http.MediaType.APPLICATION_JSON;\nimport static org.springframework.web.reactive.function.server.ServerResponse.ok;\n\npublic class PersonHandler {\n\n    private final PersonRepository repository;\n\n    public PersonHandler(PersonRepository repository) {\n        this.repository = repository;\n    }\n\n    public Mono<ServerResponse> listPeople(ServerRequest request) { (1)\n        Flux<Person> people = repository.allPeople();\n        return ok().contentType(APPLICATION_JSON).body(people, Person.class);\n    }\n\n    public Mono<ServerResponse> createPerson(ServerRequest request) { (2)\n        Mono<Person> person = request.bodyToMono(Person.class);\n        return ok().build(repository.savePerson(person));\n    }\n\n    public Mono<ServerResponse> getPerson(ServerRequest request) { (3)\n        int personId = Integer.valueOf(request.pathVariable("id"));\n        return repository.getPerson(personId)\n            .flatMap(person -> ok().contentType(APPLICATION_JSON).bodyValue(person))\n            .switchIfEmpty(ServerResponse.notFound().build());\n    }\n}\n')])])]),a("table",[a("thead",[a("tr",[a("th",[a("strong",[e._v("1")])]),e._v(" "),a("th",[a("code",[e._v("listPeople")]),e._v(" is a handler function that returns all "),a("code",[e._v("Person")]),e._v(" objects found in the repository as"),a("br"),e._v("JSON.")])])]),e._v(" "),a("tbody",[a("tr",[a("td",[a("strong",[e._v("2")])]),e._v(" "),a("td",[a("code",[e._v("createPerson")]),e._v(" is a handler function that stores a new "),a("code",[e._v("Person")]),e._v(" contained in the request body."),a("br"),e._v("Note that "),a("code",[e._v("PersonRepository.savePerson(Person)")]),e._v(" returns "),a("code",[e._v("Mono<Void>")]),e._v(": an empty "),a("code",[e._v("Mono")]),e._v(" that emits"),a("br"),e._v("a completion signal when the person has been read from the request and stored. So we use the"),a("code",[e._v("build(Publisher<Void>)")]),e._v(" method to send a response when that completion signal is received (that is,"),a("br"),e._v("when the "),a("code",[e._v("Person")]),e._v(" has been saved).")])]),e._v(" "),a("tr",[a("td",[a("strong",[e._v("3")])]),e._v(" "),a("td",[a("code",[e._v("getPerson")]),e._v(" is a handler function that returns a single person, identified by the "),a("code",[e._v("id")]),e._v(" path"),a("br"),e._v("variable. We retrieve that "),a("code",[e._v("Person")]),e._v(" from the repository and create a JSON response, if it is"),a("br"),e._v("found. If it is not found, we use "),a("code",[e._v("switchIfEmpty(Mono<T>)")]),e._v(" to return a 404 Not Found response.")])])])]),e._v(" "),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('class PersonHandler(private val repository: PersonRepository) {\n\n    suspend fun listPeople(request: ServerRequest): ServerResponse { (1)\n        val people: Flow<Person> = repository.allPeople()\n        return ok().contentType(APPLICATION_JSON).bodyAndAwait(people);\n    }\n\n    suspend fun createPerson(request: ServerRequest): ServerResponse { (2)\n        val person = request.awaitBody<Person>()\n        repository.savePerson(person)\n        return ok().buildAndAwait()\n    }\n\n    suspend fun getPerson(request: ServerRequest): ServerResponse { (3)\n        val personId = request.pathVariable("id").toInt()\n        return repository.getPerson(personId)?.let { ok().contentType(APPLICATION_JSON).bodyValueAndAwait(it) }\n                ?: ServerResponse.notFound().buildAndAwait()\n\n    }\n}\n')])])]),a("table",[a("thead",[a("tr",[a("th",[a("strong",[e._v("1")])]),e._v(" "),a("th",[a("code",[e._v("listPeople")]),e._v(" is a handler function that returns all "),a("code",[e._v("Person")]),e._v(" objects found in the repository as"),a("br"),e._v("JSON.")])])]),e._v(" "),a("tbody",[a("tr",[a("td",[a("strong",[e._v("2")])]),e._v(" "),a("td",[a("code",[e._v("createPerson")]),e._v(" is a handler function that stores a new "),a("code",[e._v("Person")]),e._v(" contained in the request body."),a("br"),e._v("Note that "),a("code",[e._v("PersonRepository.savePerson(Person)")]),e._v(" is a suspending function with no return type.")])]),e._v(" "),a("tr",[a("td",[a("strong",[e._v("3")])]),e._v(" "),a("td",[a("code",[e._v("getPerson")]),e._v(" is a handler function that returns a single person, identified by the "),a("code",[e._v("id")]),e._v(" path"),a("br"),e._v("variable. We retrieve that "),a("code",[e._v("Person")]),e._v(" from the repository and create a JSON response, if it is"),a("br"),e._v("found. If it is not found, we return a 404 Not Found response.")])])])]),e._v(" "),a("h5",{attrs:{id:"validation"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#validation"}},[e._v("#")]),e._v(" Validation")]),e._v(" "),a("p",[e._v("A functional endpoint can use Spring’s "),a("RouterLink",{attrs:{to:"/en/spring-framework/core.html#validation"}},[e._v("validation facilities")]),e._v(" to\napply validation to the request body. For example, given a custom Spring"),a("RouterLink",{attrs:{to:"/en/spring-framework/core.html#validation"}},[e._v("Validator")]),e._v(" implementation for a "),a("code",[e._v("Person")]),e._v(":")],1),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('public class PersonHandler {\n\n    private final Validator validator = new PersonValidator(); (1)\n\n    // ...\n\n    public Mono<ServerResponse> createPerson(ServerRequest request) {\n        Mono<Person> person = request.bodyToMono(Person.class).doOnNext(this::validate); (2)\n        return ok().build(repository.savePerson(person));\n    }\n\n    private void validate(Person person) {\n        Errors errors = new BeanPropertyBindingResult(person, "person");\n        validator.validate(person, errors);\n        if (errors.hasErrors()) {\n            throw new ServerWebInputException(errors.toString()); (3)\n        }\n    }\n}\n')])])]),a("table",[a("thead",[a("tr",[a("th",[a("strong",[e._v("1")])]),e._v(" "),a("th",[e._v("Create "),a("code",[e._v("Validator")]),e._v(" instance.")])])]),e._v(" "),a("tbody",[a("tr",[a("td",[a("strong",[e._v("2")])]),e._v(" "),a("td",[e._v("Apply validation.")])]),e._v(" "),a("tr",[a("td",[a("strong",[e._v("3")])]),e._v(" "),a("td",[e._v("Raise exception for a 400 response.")])])])]),e._v(" "),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('class PersonHandler(private val repository: PersonRepository) {\n\n    private val validator = PersonValidator() (1)\n\n    // ...\n\n    suspend fun createPerson(request: ServerRequest): ServerResponse {\n        val person = request.awaitBody<Person>()\n        validate(person) (2)\n        repository.savePerson(person)\n        return ok().buildAndAwait()\n    }\n\n    private fun validate(person: Person) {\n        val errors: Errors = BeanPropertyBindingResult(person, "person");\n        validator.validate(person, errors);\n        if (errors.hasErrors()) {\n            throw ServerWebInputException(errors.toString()) (3)\n        }\n    }\n}\n')])])]),a("table",[a("thead",[a("tr",[a("th",[a("strong",[e._v("1")])]),e._v(" "),a("th",[e._v("Create "),a("code",[e._v("Validator")]),e._v(" instance.")])])]),e._v(" "),a("tbody",[a("tr",[a("td",[a("strong",[e._v("2")])]),e._v(" "),a("td",[e._v("Apply validation.")])]),e._v(" "),a("tr",[a("td",[a("strong",[e._v("3")])]),e._v(" "),a("td",[e._v("Raise exception for a 400 response.")])])])]),e._v(" "),a("p",[e._v("Handlers can also use the standard bean validation API (JSR-303) by creating and injecting\na global "),a("code",[e._v("Validator")]),e._v(" instance based on "),a("code",[e._v("LocalValidatorFactoryBean")]),e._v(".\nSee "),a("RouterLink",{attrs:{to:"/en/spring-framework/core.html#validation-beanvalidation"}},[e._v("Spring Validation")]),e._v(".")],1),e._v(" "),a("h4",{attrs:{id:"_1-5-3-routerfunction"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_1-5-3-routerfunction"}},[e._v("#")]),e._v(" 1.5.3. "),a("code",[e._v("RouterFunction")])]),e._v(" "),a("p",[a("RouterLink",{attrs:{to:"/en/spring-framework/web.html#webmvc-fn-router-functions"}},[e._v("Web MVC")])],1),e._v(" "),a("p",[e._v("Router functions are used to route the requests to the corresponding "),a("code",[e._v("HandlerFunction")]),e._v(".\nTypically, you do not write router functions yourself, but rather use a method on the"),a("code",[e._v("RouterFunctions")]),e._v(" utility class to create one."),a("code",[e._v("RouterFunctions.route()")]),e._v(" (no parameters) provides you with a fluent builder for creating a router\nfunction, whereas "),a("code",[e._v("RouterFunctions.route(RequestPredicate, HandlerFunction)")]),e._v(" offers a direct way\nto create a router.")]),e._v(" "),a("p",[e._v("Generally, it is recommended to use the "),a("code",[e._v("route()")]),e._v(" builder, as it provides\nconvenient short-cuts for typical mapping scenarios without requiring hard-to-discover\nstatic imports.\nFor instance, the router function builder offers the method "),a("code",[e._v("GET(String, HandlerFunction)")]),e._v(" to create a mapping for GET requests; and "),a("code",[e._v("POST(String, HandlerFunction)")]),e._v(" for POSTs.")]),e._v(" "),a("p",[e._v("Besides HTTP method-based mapping, the route builder offers a way to introduce additional\npredicates when mapping to requests.\nFor each HTTP method there is an overloaded variant that takes a "),a("code",[e._v("RequestPredicate")]),e._v(" as a\nparameter, though which additional constraints can be expressed.")]),e._v(" "),a("h5",{attrs:{id:"predicates"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#predicates"}},[e._v("#")]),e._v(" Predicates")]),e._v(" "),a("p",[e._v("You can write your own "),a("code",[e._v("RequestPredicate")]),e._v(", but the "),a("code",[e._v("RequestPredicates")]),e._v(" utility class\noffers commonly used implementations, based on the request path, HTTP method, content-type,\nand so on.\nThe following example uses a request predicate to create a constraint based on the "),a("code",[e._v("Accept")]),e._v("header:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('RouterFunction<ServerResponse> route = RouterFunctions.route()\n    .GET("/hello-world", accept(MediaType.TEXT_PLAIN),\n        request -> ServerResponse.ok().bodyValue("Hello World")).build();\n')])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('val route = coRouter {\n    GET("/hello-world", accept(TEXT_PLAIN)) {\n        ServerResponse.ok().bodyValueAndAwait("Hello World")\n    }\n}\n')])])]),a("p",[e._v("You can compose multiple request predicates together by using:")]),e._v(" "),a("ul",[a("li",[a("p",[a("code",[e._v("RequestPredicate.and(RequestPredicate)")]),e._v(" — both must match.")])]),e._v(" "),a("li",[a("p",[a("code",[e._v("RequestPredicate.or(RequestPredicate)")]),e._v(" — either can match.")])])]),e._v(" "),a("p",[e._v("Many of the predicates from "),a("code",[e._v("RequestPredicates")]),e._v(" are composed.\nFor example, "),a("code",[e._v("RequestPredicates.GET(String)")]),e._v(" is composed from "),a("code",[e._v("RequestPredicates.method(HttpMethod)")]),e._v("and "),a("code",[e._v("RequestPredicates.path(String)")]),e._v(".\nThe example shown above also uses two request predicates, as the builder uses"),a("code",[e._v("RequestPredicates.GET")]),e._v(" internally, and composes that with the "),a("code",[e._v("accept")]),e._v(" predicate.")]),e._v(" "),a("h5",{attrs:{id:"routes"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#routes"}},[e._v("#")]),e._v(" Routes")]),e._v(" "),a("p",[e._v('Router functions are evaluated in order: if the first route does not match, the\nsecond is evaluated, and so on.\nTherefore, it makes sense to declare more specific routes before general ones.\nThis is also important when registering router functions as Spring beans, as will\nbe described later.\nNote that this behavior is different from the annotation-based programming model, where the\n"most specific" controller method is picked automatically.')]),e._v(" "),a("p",[e._v("When using the router function builder, all defined routes are composed into one"),a("code",[e._v("RouterFunction")]),e._v(" that is returned from "),a("code",[e._v("build()")]),e._v(".\nThere are also other ways to compose multiple router functions together:")]),e._v(" "),a("ul",[a("li",[a("p",[a("code",[e._v("add(RouterFunction)")]),e._v(" on the "),a("code",[e._v("RouterFunctions.route()")]),e._v(" builder")])]),e._v(" "),a("li",[a("p",[a("code",[e._v("RouterFunction.and(RouterFunction)")])])]),e._v(" "),a("li",[a("p",[a("code",[e._v("RouterFunction.andRoute(RequestPredicate, HandlerFunction)")]),e._v(" — shortcut for"),a("code",[e._v("RouterFunction.and()")]),e._v(" with nested "),a("code",[e._v("RouterFunctions.route()")]),e._v(".")])])]),e._v(" "),a("p",[e._v("The following example shows the composition of four routes:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('import static org.springframework.http.MediaType.APPLICATION_JSON;\nimport static org.springframework.web.reactive.function.server.RequestPredicates.*;\n\nPersonRepository repository = ...\nPersonHandler handler = new PersonHandler(repository);\n\nRouterFunction<ServerResponse> otherRoute = ...\n\nRouterFunction<ServerResponse> route = route()\n    .GET("/person/{id}", accept(APPLICATION_JSON), handler::getPerson) (1)\n    .GET("/person", accept(APPLICATION_JSON), handler::listPeople) (2)\n    .POST("/person", handler::createPerson) (3)\n    .add(otherRoute) (4)\n    .build();\n')])])]),a("table",[a("thead",[a("tr",[a("th",[a("strong",[e._v("1")])]),e._v(" "),a("th",[a("code",[e._v("GET /person/{id}")]),e._v(" with an "),a("code",[e._v("Accept")]),e._v(" header that matches JSON is routed to"),a("code",[e._v("PersonHandler.getPerson")])])])]),e._v(" "),a("tbody",[a("tr",[a("td",[a("strong",[e._v("2")])]),e._v(" "),a("td",[a("code",[e._v("GET /person")]),e._v(" with an "),a("code",[e._v("Accept")]),e._v(" header that matches JSON is routed to"),a("code",[e._v("PersonHandler.listPeople")])])]),e._v(" "),a("tr",[a("td",[a("strong",[e._v("3")])]),e._v(" "),a("td",[a("code",[e._v("POST /person")]),e._v(" with no additional predicates is mapped to"),a("code",[e._v("PersonHandler.createPerson")]),e._v(", and")])]),e._v(" "),a("tr",[a("td",[a("strong",[e._v("4")])]),e._v(" "),a("td",[a("code",[e._v("otherRoute")]),e._v(" is a router function that is created elsewhere, and added to the route built.")])])])]),e._v(" "),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('import org.springframework.http.MediaType.APPLICATION_JSON\n\nval repository: PersonRepository = ...\nval handler = PersonHandler(repository);\n\nval otherRoute: RouterFunction<ServerResponse> = coRouter {  }\n\nval route = coRouter {\n    GET("/person/{id}", accept(APPLICATION_JSON), handler::getPerson) (1)\n    GET("/person", accept(APPLICATION_JSON), handler::listPeople) (2)\n    POST("/person", handler::createPerson) (3)\n}.and(otherRoute) (4)\n')])])]),a("table",[a("thead",[a("tr",[a("th",[a("strong",[e._v("1")])]),e._v(" "),a("th",[a("code",[e._v("GET /person/{id}")]),e._v(" with an "),a("code",[e._v("Accept")]),e._v(" header that matches JSON is routed to"),a("code",[e._v("PersonHandler.getPerson")])])])]),e._v(" "),a("tbody",[a("tr",[a("td",[a("strong",[e._v("2")])]),e._v(" "),a("td",[a("code",[e._v("GET /person")]),e._v(" with an "),a("code",[e._v("Accept")]),e._v(" header that matches JSON is routed to"),a("code",[e._v("PersonHandler.listPeople")])])]),e._v(" "),a("tr",[a("td",[a("strong",[e._v("3")])]),e._v(" "),a("td",[a("code",[e._v("POST /person")]),e._v(" with no additional predicates is mapped to"),a("code",[e._v("PersonHandler.createPerson")]),e._v(", and")])]),e._v(" "),a("tr",[a("td",[a("strong",[e._v("4")])]),e._v(" "),a("td",[a("code",[e._v("otherRoute")]),e._v(" is a router function that is created elsewhere, and added to the route built.")])])])]),e._v(" "),a("h5",{attrs:{id:"nested-routes"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#nested-routes"}},[e._v("#")]),e._v(" Nested Routes")]),e._v(" "),a("p",[e._v("It is common for a group of router functions to have a shared predicate, for instance a\nshared path. In the example above, the shared predicate would be a path predicate that\nmatches "),a("code",[e._v("/person")]),e._v(", used by three of the routes. When using annotations, you would remove\nthis duplication by using a type-level "),a("code",[e._v("@RequestMapping")]),e._v(" annotation that maps to"),a("code",[e._v("/person")]),e._v(". In WebFlux.fn, path predicates can be shared through the "),a("code",[e._v("path")]),e._v(" method on the\nrouter function builder. For instance, the last few lines of the example above can be\nimproved in the following way by using nested routes:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('RouterFunction<ServerResponse> route = route()\n    .path("/person", builder -> builder (1)\n        .GET("/{id}", accept(APPLICATION_JSON), handler::getPerson)\n        .GET(accept(APPLICATION_JSON), handler::listPeople)\n        .POST("/person", handler::createPerson))\n    .build();\n')])])]),a("table",[a("thead",[a("tr",[a("th",[a("strong",[e._v("1")])]),e._v(" "),a("th",[e._v("Note that second parameter of "),a("code",[e._v("path")]),e._v(" is a consumer that takes the a router builder.")])])]),e._v(" "),a("tbody")]),e._v(" "),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('val route = coRouter {\n    "/person".nest {\n        GET("/{id}", accept(APPLICATION_JSON), handler::getPerson)\n        GET(accept(APPLICATION_JSON), handler::listPeople)\n        POST("/person", handler::createPerson)\n    }\n}\n')])])]),a("p",[e._v("Though path-based nesting is the most common, you can nest on any kind of predicate by using\nthe "),a("code",[e._v("nest")]),e._v(" method on the builder.\nThe above still contains some duplication in the form of the shared "),a("code",[e._v("Accept")]),e._v("-header predicate.\nWe can further improve by using the "),a("code",[e._v("nest")]),e._v(" method together with "),a("code",[e._v("accept")]),e._v(":")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('RouterFunction<ServerResponse> route = route()\n    .path("/person", b1 -> b1\n        .nest(accept(APPLICATION_JSON), b2 -> b2\n            .GET("/{id}", handler::getPerson)\n            .GET(handler::listPeople))\n        .POST("/person", handler::createPerson))\n    .build();\n')])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('val route = coRouter {\n    "/person".nest {\n        accept(APPLICATION_JSON).nest {\n            GET("/{id}", handler::getPerson)\n            GET(handler::listPeople)\n            POST("/person", handler::createPerson)\n        }\n    }\n}\n')])])]),a("h4",{attrs:{id:"_1-5-4-running-a-server"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_1-5-4-running-a-server"}},[e._v("#")]),e._v(" 1.5.4. Running a Server")]),e._v(" "),a("p",[a("RouterLink",{attrs:{to:"/en/spring-framework/web.html#webmvc-fn-running"}},[e._v("Web MVC")])],1),e._v(" "),a("p",[e._v("How do you run a router function in an HTTP server? A simple option is to convert a router\nfunction to an "),a("code",[e._v("HttpHandler")]),e._v(" by using one of the following:")]),e._v(" "),a("ul",[a("li",[a("p",[a("code",[e._v("RouterFunctions.toHttpHandler(RouterFunction)")])])]),e._v(" "),a("li",[a("p",[a("code",[e._v("RouterFunctions.toHttpHandler(RouterFunction, HandlerStrategies)")])])])]),e._v(" "),a("p",[e._v("You can then use the returned "),a("code",[e._v("HttpHandler")]),e._v(" with a number of server adapters by following"),a("a",{attrs:{href:"#webflux-httphandler"}},[e._v("HttpHandler")]),e._v(" for server-specific instructions.")]),e._v(" "),a("p",[e._v("A more typical option, also used by Spring Boot, is to run with a"),a("a",{attrs:{href:"#webflux-dispatcher-handler"}},[a("code",[e._v("DispatcherHandler")])]),e._v("-based setup through the"),a("a",{attrs:{href:"#webflux-config"}},[e._v("WebFlux Config")]),e._v(", which uses Spring configuration to declare the\ncomponents required to process requests. The WebFlux Java configuration declares the following\ninfrastructure components to support functional endpoints:")]),e._v(" "),a("ul",[a("li",[a("p",[a("code",[e._v("RouterFunctionMapping")]),e._v(": Detects one or more "),a("code",[e._v("RouterFunction<?>")]),e._v(" beans in the Spring\nconfiguration, "),a("RouterLink",{attrs:{to:"/en/spring-framework/core.html#beans-factory-ordered"}},[e._v("orders them")]),e._v(", combines them through"),a("code",[e._v("RouterFunction.andOther")]),e._v(", and routes requests to the resulting composed "),a("code",[e._v("RouterFunction")]),e._v(".")],1)]),e._v(" "),a("li",[a("p",[a("code",[e._v("HandlerFunctionAdapter")]),e._v(": Simple adapter that lets "),a("code",[e._v("DispatcherHandler")]),e._v(" invoke\na "),a("code",[e._v("HandlerFunction")]),e._v(" that was mapped to a request.")])]),e._v(" "),a("li",[a("p",[a("code",[e._v("ServerResponseResultHandler")]),e._v(": Handles the result from the invocation of a"),a("code",[e._v("HandlerFunction")]),e._v(" by invoking the "),a("code",[e._v("writeTo")]),e._v(" method of the "),a("code",[e._v("ServerResponse")]),e._v(".")])])]),e._v(" "),a("p",[e._v("The preceding components let functional endpoints fit within the "),a("code",[e._v("DispatcherHandler")]),e._v(" request\nprocessing lifecycle and also (potentially) run side by side with annotated controllers, if\nany are declared. It is also how functional endpoints are enabled by the Spring Boot WebFlux\nstarter.")]),e._v(" "),a("p",[e._v("The following example shows a WebFlux Java configuration (see"),a("a",{attrs:{href:"#webflux-dispatcher-handler"}},[e._v("DispatcherHandler")]),e._v(" for how to run it):")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("@Configuration\n@EnableWebFlux\npublic class WebConfig implements WebFluxConfigurer {\n\n    @Bean\n    public RouterFunction<?> routerFunctionA() {\n        // ...\n    }\n\n    @Bean\n    public RouterFunction<?> routerFunctionB() {\n        // ...\n    }\n\n    // ...\n\n    @Override\n    public void configureHttpMessageCodecs(ServerCodecConfigurer configurer) {\n        // configure message conversion...\n    }\n\n    @Override\n    public void addCorsMappings(CorsRegistry registry) {\n        // configure CORS...\n    }\n\n    @Override\n    public void configureViewResolvers(ViewResolverRegistry registry) {\n        // configure view resolution for HTML rendering...\n    }\n}\n")])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("@Configuration\n@EnableWebFlux\nclass WebConfig : WebFluxConfigurer {\n\n    @Bean\n    fun routerFunctionA(): RouterFunction<*> {\n        // ...\n    }\n\n    @Bean\n    fun routerFunctionB(): RouterFunction<*> {\n        // ...\n    }\n\n    // ...\n\n    override fun configureHttpMessageCodecs(configurer: ServerCodecConfigurer) {\n        // configure message conversion...\n    }\n\n    override fun addCorsMappings(registry: CorsRegistry) {\n        // configure CORS...\n    }\n\n    override fun configureViewResolvers(registry: ViewResolverRegistry) {\n        // configure view resolution for HTML rendering...\n    }\n}\n")])])]),a("h4",{attrs:{id:"_1-5-5-filtering-handler-functions"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_1-5-5-filtering-handler-functions"}},[e._v("#")]),e._v(" 1.5.5. Filtering Handler Functions")]),e._v(" "),a("p",[a("RouterLink",{attrs:{to:"/en/spring-framework/web.html#webmvc-fn-handler-filter-function"}},[e._v("Web MVC")])],1),e._v(" "),a("p",[e._v("You can filter handler functions by using the "),a("code",[e._v("before")]),e._v(", "),a("code",[e._v("after")]),e._v(", or "),a("code",[e._v("filter")]),e._v(" methods on the routing\nfunction builder.\nWith annotations, you can achieve similar functionality by using "),a("code",[e._v("@ControllerAdvice")]),e._v(", a "),a("code",[e._v("ServletFilter")]),e._v(', or both.\nThe filter will apply to all routes that are built by the builder.\nThis means that filters defined in nested routes do not apply to "top-level" routes.\nFor instance, consider the following example:')]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('RouterFunction<ServerResponse> route = route()\n    .path("/person", b1 -> b1\n        .nest(accept(APPLICATION_JSON), b2 -> b2\n            .GET("/{id}", handler::getPerson)\n            .GET(handler::listPeople)\n            .before(request -> ServerRequest.from(request) (1)\n                .header("X-RequestHeader", "Value")\n                .build()))\n        .POST("/person", handler::createPerson))\n    .after((request, response) -> logResponse(response)) (2)\n    .build();\n')])])]),a("table",[a("thead",[a("tr",[a("th",[a("strong",[e._v("1")])]),e._v(" "),a("th",[e._v("The "),a("code",[e._v("before")]),e._v(" filter that adds a custom request header is only applied to the two GET routes.")])])]),e._v(" "),a("tbody",[a("tr",[a("td",[a("strong",[e._v("2")])]),e._v(" "),a("td",[e._v("The "),a("code",[e._v("after")]),e._v(" filter that logs the response is applied to all routes, including the nested ones.")])])])]),e._v(" "),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('val route = router {\n    "/person".nest {\n        GET("/{id}", handler::getPerson)\n        GET("", handler::listPeople)\n        before { (1)\n            ServerRequest.from(it)\n                    .header("X-RequestHeader", "Value").build()\n        }\n        POST("/person", handler::createPerson)\n        after { _, response -> (2)\n            logResponse(response)\n        }\n    }\n}\n')])])]),a("table",[a("thead",[a("tr",[a("th",[a("strong",[e._v("1")])]),e._v(" "),a("th",[e._v("The "),a("code",[e._v("before")]),e._v(" filter that adds a custom request header is only applied to the two GET routes.")])])]),e._v(" "),a("tbody",[a("tr",[a("td",[a("strong",[e._v("2")])]),e._v(" "),a("td",[e._v("The "),a("code",[e._v("after")]),e._v(" filter that logs the response is applied to all routes, including the nested ones.")])])])]),e._v(" "),a("p",[e._v("The "),a("code",[e._v("filter")]),e._v(" method on the router builder takes a "),a("code",[e._v("HandlerFilterFunction")]),e._v(": a\nfunction that takes a "),a("code",[e._v("ServerRequest")]),e._v(" and "),a("code",[e._v("HandlerFunction")]),e._v(" and returns a "),a("code",[e._v("ServerResponse")]),e._v(".\nThe handler function parameter represents the next element in the chain.\nThis is typically the handler that is routed to, but it can also be another\nfilter if multiple are applied.")]),e._v(" "),a("p",[e._v("Now we can add a simple security filter to our route, assuming that we have a "),a("code",[e._v("SecurityManager")]),e._v(" that\ncan determine whether a particular path is allowed.\nThe following example shows how to do so:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('SecurityManager securityManager = ...\n\nRouterFunction<ServerResponse> route = route()\n    .path("/person", b1 -> b1\n        .nest(accept(APPLICATION_JSON), b2 -> b2\n            .GET("/{id}", handler::getPerson)\n            .GET(handler::listPeople))\n        .POST("/person", handler::createPerson))\n    .filter((request, next) -> {\n        if (securityManager.allowAccessTo(request.path())) {\n            return next.handle(request);\n        }\n        else {\n            return ServerResponse.status(UNAUTHORIZED).build();\n        }\n    })\n    .build();\n')])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('val securityManager: SecurityManager = ...\n\nval route = router {\n        ("/person" and accept(APPLICATION_JSON)).nest {\n            GET("/{id}", handler::getPerson)\n            GET("", handler::listPeople)\n            POST("/person", handler::createPerson)\n            filter { request, next ->\n                if (securityManager.allowAccessTo(request.path())) {\n                    next(request)\n                }\n                else {\n                    status(UNAUTHORIZED).build();\n                }\n            }\n        }\n    }\n')])])]),a("p",[e._v("The preceding example demonstrates that invoking the "),a("code",[e._v("next.handle(ServerRequest)")]),e._v(" is optional.\nWe only let the handler function be run when access is allowed.")]),e._v(" "),a("p",[e._v("Besides using the "),a("code",[e._v("filter")]),e._v(" method on the router function builder, it is possible to apply a\nfilter to an existing router function via "),a("code",[e._v("RouterFunction.filter(HandlerFilterFunction)")]),e._v(".")]),e._v(" "),a("table",[a("thead",[a("tr",[a("th"),e._v(" "),a("th",[e._v("CORS support for functional endpoints is provided through a dedicated"),a("RouterLink",{attrs:{to:"/en/spring-framework/webflux-cors.html#webflux-cors-webfilter"}},[a("code",[e._v("CorsWebFilter")])]),e._v(".")],1)])]),e._v(" "),a("tbody")]),e._v(" "),a("h3",{attrs:{id:"_1-6-uri-links"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_1-6-uri-links"}},[e._v("#")]),e._v(" 1.6. URI Links")]),e._v(" "),a("p",[a("RouterLink",{attrs:{to:"/en/spring-framework/web.html#mvc-uri-building"}},[e._v("Web MVC")])],1),e._v(" "),a("p",[e._v("This section describes various options available in the Spring Framework to prepare URIs.")]),e._v(" "),a("h4",{attrs:{id:"_1-6-1-uricomponents"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_1-6-1-uricomponents"}},[e._v("#")]),e._v(" 1.6.1. UriComponents")]),e._v(" "),a("p",[e._v("Spring MVC and Spring WebFlux")]),e._v(" "),a("p",[a("code",[e._v("UriComponentsBuilder")]),e._v(" helps to build URI’s from URI templates with variables, as the following example shows:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('UriComponents uriComponents = UriComponentsBuilder\n        .fromUriString("https://example.com/hotels/{hotel}")  (1)\n        .queryParam("q", "{q}")  (2)\n        .encode() (3)\n        .build(); (4)\n\nURI uri = uriComponents.expand("Westin", "123").toUri();  (5)\n')])])]),a("table",[a("thead",[a("tr",[a("th",[a("strong",[e._v("1")])]),e._v(" "),a("th",[e._v("Static factory method with a URI template.")])])]),e._v(" "),a("tbody",[a("tr",[a("td",[a("strong",[e._v("2")])]),e._v(" "),a("td",[e._v("Add or replace URI components.")])]),e._v(" "),a("tr",[a("td",[a("strong",[e._v("3")])]),e._v(" "),a("td",[e._v("Request to have the URI template and URI variables encoded.")])]),e._v(" "),a("tr",[a("td",[a("strong",[e._v("4")])]),e._v(" "),a("td",[e._v("Build a "),a("code",[e._v("UriComponents")]),e._v(".")])]),e._v(" "),a("tr",[a("td",[a("strong",[e._v("5")])]),e._v(" "),a("td",[e._v("Expand variables and obtain the "),a("code",[e._v("URI")]),e._v(".")])])])]),e._v(" "),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('val uriComponents = UriComponentsBuilder\n        .fromUriString("https://example.com/hotels/{hotel}")  (1)\n        .queryParam("q", "{q}")  (2)\n        .encode() (3)\n        .build() (4)\n\nval uri = uriComponents.expand("Westin", "123").toUri()  (5)\n')])])]),a("table",[a("thead",[a("tr",[a("th",[a("strong",[e._v("1")])]),e._v(" "),a("th",[e._v("Static factory method with a URI template.")])])]),e._v(" "),a("tbody",[a("tr",[a("td",[a("strong",[e._v("2")])]),e._v(" "),a("td",[e._v("Add or replace URI components.")])]),e._v(" "),a("tr",[a("td",[a("strong",[e._v("3")])]),e._v(" "),a("td",[e._v("Request to have the URI template and URI variables encoded.")])]),e._v(" "),a("tr",[a("td",[a("strong",[e._v("4")])]),e._v(" "),a("td",[e._v("Build a "),a("code",[e._v("UriComponents")]),e._v(".")])]),e._v(" "),a("tr",[a("td",[a("strong",[e._v("5")])]),e._v(" "),a("td",[e._v("Expand variables and obtain the "),a("code",[e._v("URI")]),e._v(".")])])])]),e._v(" "),a("p",[e._v("The preceding example can be consolidated into one chain and shortened with "),a("code",[e._v("buildAndExpand")]),e._v(",\nas the following example shows:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('URI uri = UriComponentsBuilder\n        .fromUriString("https://example.com/hotels/{hotel}")\n        .queryParam("q", "{q}")\n        .encode()\n        .buildAndExpand("Westin", "123")\n        .toUri();\n')])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('val uri = UriComponentsBuilder\n        .fromUriString("https://example.com/hotels/{hotel}")\n        .queryParam("q", "{q}")\n        .encode()\n        .buildAndExpand("Westin", "123")\n        .toUri()\n')])])]),a("p",[e._v("You can shorten it further by going directly to a URI (which implies encoding),\nas the following example shows:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('URI uri = UriComponentsBuilder\n        .fromUriString("https://example.com/hotels/{hotel}")\n        .queryParam("q", "{q}")\n        .build("Westin", "123");\n')])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('val uri = UriComponentsBuilder\n        .fromUriString("https://example.com/hotels/{hotel}")\n        .queryParam("q", "{q}")\n        .build("Westin", "123")\n')])])]),a("p",[e._v("You can shorten it further still with a full URI template, as the following example shows:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('URI uri = UriComponentsBuilder\n        .fromUriString("https://example.com/hotels/{hotel}?q={q}")\n        .build("Westin", "123");\n')])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('val uri = UriComponentsBuilder\n        .fromUriString("https://example.com/hotels/{hotel}?q={q}")\n        .build("Westin", "123")\n')])])]),a("h4",{attrs:{id:"_1-6-2-uribuilder"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_1-6-2-uribuilder"}},[e._v("#")]),e._v(" 1.6.2. UriBuilder")]),e._v(" "),a("p",[e._v("Spring MVC and Spring WebFlux")]),e._v(" "),a("p",[a("a",{attrs:{href:"#web-uricomponents"}},[a("code",[e._v("UriComponentsBuilder")])]),e._v(" implements "),a("code",[e._v("UriBuilder")]),e._v(". You can create a"),a("code",[e._v("UriBuilder")]),e._v(", in turn, with a "),a("code",[e._v("UriBuilderFactory")]),e._v(". Together, "),a("code",[e._v("UriBuilderFactory")]),e._v(" and"),a("code",[e._v("UriBuilder")]),e._v(" provide a pluggable mechanism to build URIs from URI templates, based on\nshared configuration, such as a base URL, encoding preferences, and other details.")]),e._v(" "),a("p",[e._v("You can configure "),a("code",[e._v("RestTemplate")]),e._v(" and "),a("code",[e._v("WebClient")]),e._v(" with a "),a("code",[e._v("UriBuilderFactory")]),e._v("to customize the preparation of URIs. "),a("code",[e._v("DefaultUriBuilderFactory")]),e._v(" is a default\nimplementation of "),a("code",[e._v("UriBuilderFactory")]),e._v(" that uses "),a("code",[e._v("UriComponentsBuilder")]),e._v(" internally and\nexposes shared configuration options.")]),e._v(" "),a("p",[e._v("The following example shows how to configure a "),a("code",[e._v("RestTemplate")]),e._v(":")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('// import org.springframework.web.util.DefaultUriBuilderFactory.EncodingMode;\n\nString baseUrl = "https://example.org";\nDefaultUriBuilderFactory factory = new DefaultUriBuilderFactory(baseUrl);\nfactory.setEncodingMode(EncodingMode.TEMPLATE_AND_VALUES);\n\nRestTemplate restTemplate = new RestTemplate();\nrestTemplate.setUriTemplateHandler(factory);\n')])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('// import org.springframework.web.util.DefaultUriBuilderFactory.EncodingMode\n\nval baseUrl = "https://example.org"\nval factory = DefaultUriBuilderFactory(baseUrl)\nfactory.encodingMode = EncodingMode.TEMPLATE_AND_VALUES\n\nval restTemplate = RestTemplate()\nrestTemplate.uriTemplateHandler = factory\n')])])]),a("p",[e._v("The following example configures a "),a("code",[e._v("WebClient")]),e._v(":")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('// import org.springframework.web.util.DefaultUriBuilderFactory.EncodingMode;\n\nString baseUrl = "https://example.org";\nDefaultUriBuilderFactory factory = new DefaultUriBuilderFactory(baseUrl);\nfactory.setEncodingMode(EncodingMode.TEMPLATE_AND_VALUES);\n\nWebClient client = WebClient.builder().uriBuilderFactory(factory).build();\n')])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('// import org.springframework.web.util.DefaultUriBuilderFactory.EncodingMode\n\nval baseUrl = "https://example.org"\nval factory = DefaultUriBuilderFactory(baseUrl)\nfactory.encodingMode = EncodingMode.TEMPLATE_AND_VALUES\n\nval client = WebClient.builder().uriBuilderFactory(factory).build()\n')])])]),a("p",[e._v("In addition, you can also use "),a("code",[e._v("DefaultUriBuilderFactory")]),e._v(" directly. It is similar to using"),a("code",[e._v("UriComponentsBuilder")]),e._v(" but, instead of static factory methods, it is an actual instance\nthat holds configuration and preferences, as the following example shows:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('String baseUrl = "https://example.com";\nDefaultUriBuilderFactory uriBuilderFactory = new DefaultUriBuilderFactory(baseUrl);\n\nURI uri = uriBuilderFactory.uriString("/hotels/{hotel}")\n        .queryParam("q", "{q}")\n        .build("Westin", "123");\n')])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('val baseUrl = "https://example.com"\nval uriBuilderFactory = DefaultUriBuilderFactory(baseUrl)\n\nval uri = uriBuilderFactory.uriString("/hotels/{hotel}")\n        .queryParam("q", "{q}")\n        .build("Westin", "123")\n')])])]),a("h4",{attrs:{id:"_1-6-3-uri-encoding"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_1-6-3-uri-encoding"}},[e._v("#")]),e._v(" 1.6.3. URI Encoding")]),e._v(" "),a("p",[e._v("Spring MVC and Spring WebFlux")]),e._v(" "),a("p",[a("code",[e._v("UriComponentsBuilder")]),e._v(" exposes encoding options at two levels:")]),e._v(" "),a("ul",[a("li",[a("p",[a("a",{attrs:{href:"https://docs.spring.io/spring-framework/docs/5.3.16/javadoc-api/org/springframework/web/util/UriComponentsBuilder.html#encode--",target:"_blank",rel:"noopener noreferrer"}},[e._v("UriComponentsBuilder#encode()"),a("OutboundLink")],1),e._v(":\nPre-encodes the URI template first and then strictly encodes URI variables when expanded.")])]),e._v(" "),a("li",[a("p",[a("a",{attrs:{href:"https://docs.spring.io/spring-framework/docs/5.3.16/javadoc-api/org/springframework/web/util/UriComponents.html#encode--",target:"_blank",rel:"noopener noreferrer"}},[e._v("UriComponents#encode()"),a("OutboundLink")],1),e._v(":\nEncodes URI components "),a("em",[e._v("after")]),e._v(" URI variables are expanded.")])])]),e._v(" "),a("p",[e._v("Both options replace non-ASCII and illegal characters with escaped octets. However, the first option\nalso replaces characters with reserved meaning that appear in URI variables.")]),e._v(" "),a("table",[a("thead",[a("tr",[a("th"),e._v(" "),a("th",[e._v('Consider ";", which is legal in a path but has reserved meaning. The first option replaces'),a("br"),e._v('";" with "%3B" in URI variables but not in the URI template. By contrast, the second option never'),a("br"),e._v('replaces ";", since it is a legal character in a path.')])])]),e._v(" "),a("tbody")]),e._v(" "),a("p",[e._v("For most cases, the first option is likely to give the expected result, because it treats URI\nvariables as opaque data to be fully encoded, while the second option is useful if URI\nvariables do intentionally contain reserved characters. The second option is also useful\nwhen not expanding URI variables at all since that will also encode anything that\nincidentally looks like a URI variable.")]),e._v(" "),a("p",[e._v("The following example uses the first option:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('URI uri = UriComponentsBuilder.fromPath("/hotel list/{city}")\n        .queryParam("q", "{q}")\n        .encode()\n        .buildAndExpand("New York", "foo+bar")\n        .toUri();\n\n// Result is "/hotel%20list/New%20York?q=foo%2Bbar"\n')])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('val uri = UriComponentsBuilder.fromPath("/hotel list/{city}")\n        .queryParam("q", "{q}")\n        .encode()\n        .buildAndExpand("New York", "foo+bar")\n        .toUri()\n\n// Result is "/hotel%20list/New%20York?q=foo%2Bbar"\n')])])]),a("p",[e._v("You can shorten the preceding example by going directly to the URI (which implies encoding),\nas the following example shows:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('URI uri = UriComponentsBuilder.fromPath("/hotel list/{city}")\n        .queryParam("q", "{q}")\n        .build("New York", "foo+bar");\n')])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('val uri = UriComponentsBuilder.fromPath("/hotel list/{city}")\n        .queryParam("q", "{q}")\n        .build("New York", "foo+bar")\n')])])]),a("p",[e._v("You can shorten it further still with a full URI template, as the following example shows:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('URI uri = UriComponentsBuilder.fromUriString("/hotel list/{city}?q={q}")\n        .build("New York", "foo+bar");\n')])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('val uri = UriComponentsBuilder.fromUriString("/hotel list/{city}?q={q}")\n        .build("New York", "foo+bar")\n')])])]),a("p",[e._v("The "),a("code",[e._v("WebClient")]),e._v(" and the "),a("code",[e._v("RestTemplate")]),e._v(" expand and encode URI templates internally through\nthe "),a("code",[e._v("UriBuilderFactory")]),e._v(" strategy. Both can be configured with a custom strategy,\nas the following example shows:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('String baseUrl = "https://example.com";\nDefaultUriBuilderFactory factory = new DefaultUriBuilderFactory(baseUrl)\nfactory.setEncodingMode(EncodingMode.TEMPLATE_AND_VALUES);\n\n// Customize the RestTemplate..\nRestTemplate restTemplate = new RestTemplate();\nrestTemplate.setUriTemplateHandler(factory);\n\n// Customize the WebClient..\nWebClient client = WebClient.builder().uriBuilderFactory(factory).build();\n')])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('val baseUrl = "https://example.com"\nval factory = DefaultUriBuilderFactory(baseUrl).apply {\n    encodingMode = EncodingMode.TEMPLATE_AND_VALUES\n}\n\n// Customize the RestTemplate..\nval restTemplate = RestTemplate().apply {\n    uriTemplateHandler = factory\n}\n\n// Customize the WebClient..\nval client = WebClient.builder().uriBuilderFactory(factory).build()\n')])])]),a("p",[e._v("The "),a("code",[e._v("DefaultUriBuilderFactory")]),e._v(" implementation uses "),a("code",[e._v("UriComponentsBuilder")]),e._v(" internally to\nexpand and encode URI templates. As a factory, it provides a single place to configure\nthe approach to encoding, based on one of the below encoding modes:")]),e._v(" "),a("ul",[a("li",[a("p",[a("code",[e._v("TEMPLATE_AND_VALUES")]),e._v(": Uses "),a("code",[e._v("UriComponentsBuilder#encode()")]),e._v(", corresponding to\nthe first option in the earlier list, to pre-encode the URI template and strictly encode URI variables when\nexpanded.")])]),e._v(" "),a("li",[a("p",[a("code",[e._v("VALUES_ONLY")]),e._v(": Does not encode the URI template and, instead, applies strict encoding\nto URI variables through "),a("code",[e._v("UriUtils#encodeUriVariables")]),e._v(" prior to expanding them into the\ntemplate.")])]),e._v(" "),a("li",[a("p",[a("code",[e._v("URI_COMPONENT")]),e._v(": Uses "),a("code",[e._v("UriComponents#encode()")]),e._v(", corresponding to the second option in the earlier list, to\nencode URI component value "),a("em",[e._v("after")]),e._v(" URI variables are expanded.")])]),e._v(" "),a("li",[a("p",[a("code",[e._v("NONE")]),e._v(": No encoding is applied.")])])]),e._v(" "),a("p",[e._v("The "),a("code",[e._v("RestTemplate")]),e._v(" is set to "),a("code",[e._v("EncodingMode.URI_COMPONENT")]),e._v(" for historic\nreasons and for backwards compatibility. The "),a("code",[e._v("WebClient")]),e._v(" relies on the default value\nin "),a("code",[e._v("DefaultUriBuilderFactory")]),e._v(", which was changed from "),a("code",[e._v("EncodingMode.URI_COMPONENT")]),e._v(" in\n5.0.x to "),a("code",[e._v("EncodingMode.TEMPLATE_AND_VALUES")]),e._v(" in 5.1.")]),e._v(" "),a("h3",{attrs:{id:"_1-7-cors"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_1-7-cors"}},[e._v("#")]),e._v(" 1.7. CORS")]),e._v(" "),a("p",[a("RouterLink",{attrs:{to:"/en/spring-framework/web.html#mvc-cors"}},[e._v("Web MVC")])],1),e._v(" "),a("p",[e._v("Spring WebFlux lets you handle CORS (Cross-Origin Resource Sharing). This section\ndescribes how to do so.")]),e._v(" "),a("h4",{attrs:{id:"_1-7-1-introduction"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_1-7-1-introduction"}},[e._v("#")]),e._v(" 1.7.1. Introduction")]),e._v(" "),a("p",[a("RouterLink",{attrs:{to:"/en/spring-framework/web.html#mvc-cors-intro"}},[e._v("Web MVC")])],1),e._v(" "),a("p",[e._v("For security reasons, browsers prohibit AJAX calls to resources outside the current origin.\nFor example, you could have your bank account in one tab and evil.com in another. Scripts\nfrom evil.com should not be able to make AJAX requests to your bank API with your\ncredentials — for example, withdrawing money from your account!")]),e._v(" "),a("p",[e._v("Cross-Origin Resource Sharing (CORS) is a "),a("a",{attrs:{href:"https://www.w3.org/TR/cors/",target:"_blank",rel:"noopener noreferrer"}},[e._v("W3C specification"),a("OutboundLink")],1),e._v("implemented by "),a("a",{attrs:{href:"https://caniuse.com/#feat=cors",target:"_blank",rel:"noopener noreferrer"}},[e._v("most browsers"),a("OutboundLink")],1),e._v(" that lets you specify\nwhat kind of cross-domain requests are authorized, rather than using less secure and less\npowerful workarounds based on IFRAME or JSONP.")]),e._v(" "),a("h4",{attrs:{id:"_1-7-2-processing"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_1-7-2-processing"}},[e._v("#")]),e._v(" 1.7.2. Processing")]),e._v(" "),a("p",[a("RouterLink",{attrs:{to:"/en/spring-framework/web.html#mvc-cors-processing"}},[e._v("Web MVC")])],1),e._v(" "),a("p",[e._v("The CORS specification distinguishes between preflight, simple, and actual requests.\nTo learn how CORS works, you can read"),a("a",{attrs:{href:"https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS",target:"_blank",rel:"noopener noreferrer"}},[e._v("this article"),a("OutboundLink")],1),e._v(", among\nmany others, or see the specification for more details.")]),e._v(" "),a("p",[e._v("Spring WebFlux "),a("code",[e._v("HandlerMapping")]),e._v(" implementations provide built-in support for CORS. After successfully\nmapping a request to a handler, a "),a("code",[e._v("HandlerMapping")]),e._v(" checks the CORS configuration for the\ngiven request and handler and takes further actions. Preflight requests are handled\ndirectly, while simple and actual CORS requests are intercepted, validated, and have the\nrequired CORS response headers set.")]),e._v(" "),a("p",[e._v("In order to enable cross-origin requests (that is, the "),a("code",[e._v("Origin")]),e._v(" header is present and\ndiffers from the host of the request), you need to have some explicitly declared CORS\nconfiguration. If no matching CORS configuration is found, preflight requests are\nrejected. No CORS headers are added to the responses of simple and actual CORS requests\nand, consequently, browsers reject them.")]),e._v(" "),a("p",[e._v("Each "),a("code",[e._v("HandlerMapping")]),e._v(" can be"),a("a",{attrs:{href:"https://docs.spring.io/spring-framework/docs/5.3.16/javadoc-api/org/springframework/web/reactive/handler/AbstractHandlerMapping.html#setCorsConfigurations-java.util.Map-",target:"_blank",rel:"noopener noreferrer"}},[e._v("configured"),a("OutboundLink")],1),e._v("individually with URL pattern-based "),a("code",[e._v("CorsConfiguration")]),e._v(" mappings. In most cases, applications\nuse the WebFlux Java configuration to declare such mappings, which results in a single,\nglobal map passed to all "),a("code",[e._v("HandlerMapping")]),e._v(" implementations.")]),e._v(" "),a("p",[e._v("You can combine global CORS configuration at the "),a("code",[e._v("HandlerMapping")]),e._v(" level with more\nfine-grained, handler-level CORS configuration. For example, annotated controllers can use\nclass- or method-level "),a("code",[e._v("@CrossOrigin")]),e._v(" annotations (other handlers can implement"),a("code",[e._v("CorsConfigurationSource")]),e._v(").")]),e._v(" "),a("p",[e._v("The rules for combining global and local configuration are generally additive — for example,\nall global and all local origins. For those attributes where only a single value can be\naccepted, such as "),a("code",[e._v("allowCredentials")]),e._v(" and "),a("code",[e._v("maxAge")]),e._v(", the local overrides the global value. See"),a("a",{attrs:{href:"https://docs.spring.io/spring-framework/docs/5.3.16/javadoc-api/org/springframework/web/cors/CorsConfiguration.html#combine-org.springframework.web.cors.CorsConfiguration-",target:"_blank",rel:"noopener noreferrer"}},[a("code",[e._v("CorsConfiguration#combine(CorsConfiguration)")]),a("OutboundLink")],1),e._v("for more details.")]),e._v(" "),a("table",[a("thead",[a("tr",[a("th"),e._v(" "),a("th",[e._v("To learn more from the source or to make advanced customizations, see:"),a("br"),a("br"),e._v("* "),a("code",[e._v("CorsConfiguration")]),a("br"),a("br"),e._v("* "),a("code",[e._v("CorsProcessor")]),e._v(" and "),a("code",[e._v("DefaultCorsProcessor")]),a("br"),a("br"),e._v("* "),a("code",[e._v("AbstractHandlerMapping")])])])]),e._v(" "),a("tbody")]),e._v(" "),a("h4",{attrs:{id:"_1-7-3-crossorigin"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_1-7-3-crossorigin"}},[e._v("#")]),e._v(" 1.7.3. "),a("code",[e._v("@CrossOrigin")])]),e._v(" "),a("p",[a("RouterLink",{attrs:{to:"/en/spring-framework/web.html#mvc-cors-controller"}},[e._v("Web MVC")])],1),e._v(" "),a("p",[e._v("The "),a("a",{attrs:{href:"https://docs.spring.io/spring-framework/docs/5.3.16/javadoc-api/org/springframework/web/bind/annotation/CrossOrigin.html",target:"_blank",rel:"noopener noreferrer"}},[a("code",[e._v("@CrossOrigin")]),a("OutboundLink")],1),e._v("annotation enables cross-origin requests on annotated controller methods, as the\nfollowing example shows:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('@RestController\n@RequestMapping("/account")\npublic class AccountController {\n\n    @CrossOrigin\n    @GetMapping("/{id}")\n    public Mono<Account> retrieve(@PathVariable Long id) {\n        // ...\n    }\n\n    @DeleteMapping("/{id}")\n    public Mono<Void> remove(@PathVariable Long id) {\n        // ...\n    }\n}\n')])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('@RestController\n@RequestMapping("/account")\nclass AccountController {\n\n    @CrossOrigin\n    @GetMapping("/{id}")\n    suspend fun retrieve(@PathVariable id: Long): Account {\n        // ...\n    }\n\n    @DeleteMapping("/{id}")\n    suspend fun remove(@PathVariable id: Long) {\n        // ...\n    }\n}\n')])])]),a("p",[e._v("By default, "),a("code",[e._v("@CrossOrigin")]),e._v(" allows:")]),e._v(" "),a("ul",[a("li",[a("p",[e._v("All origins.")])]),e._v(" "),a("li",[a("p",[e._v("All headers.")])]),e._v(" "),a("li",[a("p",[e._v("All HTTP methods to which the controller method is mapped.")])])]),e._v(" "),a("p",[a("code",[e._v("allowCredentials")]),e._v(" is not enabled by default, since that establishes a trust level\nthat exposes sensitive user-specific information (such as cookies and CSRF tokens) and\nshould be used only where appropriate. When it is enabled either "),a("code",[e._v("allowOrigins")]),e._v(" must be\nset to one or more specific domain (but not the special value "),a("code",[e._v('"*"')]),e._v(") or alternatively\nthe "),a("code",[e._v("allowOriginPatterns")]),e._v(" property may be used to match to a dynamic set of origins.")]),e._v(" "),a("p",[a("code",[e._v("maxAge")]),e._v(" is set to 30 minutes.")]),e._v(" "),a("p",[a("code",[e._v("@CrossOrigin")]),e._v(" is supported at the class level, too, and inherited by all methods.\nThe following example specifies a certain domain and sets "),a("code",[e._v("maxAge")]),e._v(" to an hour:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('@CrossOrigin(origins = "https://domain2.com", maxAge = 3600)\n@RestController\n@RequestMapping("/account")\npublic class AccountController {\n\n    @GetMapping("/{id}")\n    public Mono<Account> retrieve(@PathVariable Long id) {\n        // ...\n    }\n\n    @DeleteMapping("/{id}")\n    public Mono<Void> remove(@PathVariable Long id) {\n        // ...\n    }\n}\n')])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('@CrossOrigin("https://domain2.com", maxAge = 3600)\n@RestController\n@RequestMapping("/account")\nclass AccountController {\n\n    @GetMapping("/{id}")\n    suspend fun retrieve(@PathVariable id: Long): Account {\n        // ...\n    }\n\n    @DeleteMapping("/{id}")\n    suspend fun remove(@PathVariable id: Long) {\n        // ...\n    }\n}\n')])])]),a("p",[e._v("You can use "),a("code",[e._v("@CrossOrigin")]),e._v(" at both the class and the method level,\nas the following example shows:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('@CrossOrigin(maxAge = 3600) (1)\n@RestController\n@RequestMapping("/account")\npublic class AccountController {\n\n    @CrossOrigin("https://domain2.com") (2)\n    @GetMapping("/{id}")\n    public Mono<Account> retrieve(@PathVariable Long id) {\n        // ...\n    }\n\n    @DeleteMapping("/{id}")\n    public Mono<Void> remove(@PathVariable Long id) {\n        // ...\n    }\n}\n')])])]),a("table",[a("thead",[a("tr",[a("th",[a("strong",[e._v("1")])]),e._v(" "),a("th",[e._v("Using "),a("code",[e._v("@CrossOrigin")]),e._v(" at the class level.")])])]),e._v(" "),a("tbody",[a("tr",[a("td",[a("strong",[e._v("2")])]),e._v(" "),a("td",[e._v("Using "),a("code",[e._v("@CrossOrigin")]),e._v(" at the method level.")])])])]),e._v(" "),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('@CrossOrigin(maxAge = 3600) (1)\n@RestController\n@RequestMapping("/account")\nclass AccountController {\n\n    @CrossOrigin("https://domain2.com") (2)\n    @GetMapping("/{id}")\n    suspend fun retrieve(@PathVariable id: Long): Account {\n        // ...\n    }\n\n    @DeleteMapping("/{id}")\n    suspend fun remove(@PathVariable id: Long) {\n        // ...\n    }\n}\n')])])]),a("table",[a("thead",[a("tr",[a("th",[a("strong",[e._v("1")])]),e._v(" "),a("th",[e._v("Using "),a("code",[e._v("@CrossOrigin")]),e._v(" at the class level.")])])]),e._v(" "),a("tbody",[a("tr",[a("td",[a("strong",[e._v("2")])]),e._v(" "),a("td",[e._v("Using "),a("code",[e._v("@CrossOrigin")]),e._v(" at the method level.")])])])]),e._v(" "),a("h4",{attrs:{id:"_1-7-4-global-configuration"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_1-7-4-global-configuration"}},[e._v("#")]),e._v(" 1.7.4. Global Configuration")]),e._v(" "),a("p",[a("RouterLink",{attrs:{to:"/en/spring-framework/web.html#mvc-cors-global"}},[e._v("Web MVC")])],1),e._v(" "),a("p",[e._v("In addition to fine-grained, controller method-level configuration, you probably want to\ndefine some global CORS configuration, too. You can set URL-based "),a("code",[e._v("CorsConfiguration")]),e._v("mappings individually on any "),a("code",[e._v("HandlerMapping")]),e._v(". Most applications, however, use the\nWebFlux Java configuration to do that.")]),e._v(" "),a("p",[e._v("By default global configuration enables the following:")]),e._v(" "),a("ul",[a("li",[a("p",[e._v("All origins.")])]),e._v(" "),a("li",[a("p",[e._v("All headers.")])]),e._v(" "),a("li",[a("p",[a("code",[e._v("GET")]),e._v(", "),a("code",[e._v("HEAD")]),e._v(", and "),a("code",[e._v("POST")]),e._v(" methods.")])])]),e._v(" "),a("p",[a("code",[e._v("allowedCredentials")]),e._v(" is not enabled by default, since that establishes a trust level\nthat exposes sensitive user-specific information( such as cookies and CSRF tokens) and\nshould be used only where appropriate. When it is enabled either "),a("code",[e._v("allowOrigins")]),e._v(" must be\nset to one or more specific domain (but not the special value "),a("code",[e._v('"*"')]),e._v(") or alternatively\nthe "),a("code",[e._v("allowOriginPatterns")]),e._v(" property may be used to match to a dynamic set of origins.")]),e._v(" "),a("p",[a("code",[e._v("maxAge")]),e._v(" is set to 30 minutes.")]),e._v(" "),a("p",[e._v("To enable CORS in the WebFlux Java configuration, you can use the "),a("code",[e._v("CorsRegistry")]),e._v(" callback,\nas the following example shows:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('@Configuration\n@EnableWebFlux\npublic class WebConfig implements WebFluxConfigurer {\n\n    @Override\n    public void addCorsMappings(CorsRegistry registry) {\n\n        registry.addMapping("/api/**")\n            .allowedOrigins("https://domain2.com")\n            .allowedMethods("PUT", "DELETE")\n            .allowedHeaders("header1", "header2", "header3")\n            .exposedHeaders("header1", "header2")\n            .allowCredentials(true).maxAge(3600);\n\n        // Add more mappings...\n    }\n}\n')])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('@Configuration\n@EnableWebFlux\nclass WebConfig : WebFluxConfigurer {\n\n    override fun addCorsMappings(registry: CorsRegistry) {\n\n        registry.addMapping("/api/**")\n                .allowedOrigins("https://domain2.com")\n                .allowedMethods("PUT", "DELETE")\n                .allowedHeaders("header1", "header2", "header3")\n                .exposedHeaders("header1", "header2")\n                .allowCredentials(true).maxAge(3600)\n\n        // Add more mappings...\n    }\n}\n')])])]),a("h4",{attrs:{id:"_1-7-5-cors-webfilter"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_1-7-5-cors-webfilter"}},[e._v("#")]),e._v(" 1.7.5. CORS "),a("code",[e._v("WebFilter")])]),e._v(" "),a("p",[a("RouterLink",{attrs:{to:"/en/spring-framework/web.html#mvc-cors-filter"}},[e._v("Web MVC")])],1),e._v(" "),a("p",[e._v("You can apply CORS support through the built-in"),a("a",{attrs:{href:"https://docs.spring.io/spring-framework/docs/5.3.16/javadoc-api/org/springframework/web/cors/reactive/CorsWebFilter.html",target:"_blank",rel:"noopener noreferrer"}},[a("code",[e._v("CorsWebFilter")]),a("OutboundLink")],1),e._v(", which is a\ngood fit with "),a("a",{attrs:{href:"#webflux-fn"}},[e._v("functional endpoints")]),e._v(".")]),e._v(" "),a("table",[a("thead",[a("tr",[a("th"),e._v(" "),a("th",[e._v("If you try to use the "),a("code",[e._v("CorsFilter")]),e._v(" with Spring Security, keep in mind that Spring"),a("br"),e._v("Security has"),a("a",{attrs:{href:"https://docs.spring.io/spring-security/site/docs/current/reference/htmlsingle/#cors",target:"_blank",rel:"noopener noreferrer"}},[e._v("built-in support"),a("OutboundLink")],1),e._v("for CORS.")])])]),e._v(" "),a("tbody")]),e._v(" "),a("p",[e._v("To configure the filter, you can declare a "),a("code",[e._v("CorsWebFilter")]),e._v(" bean and pass a"),a("code",[e._v("CorsConfigurationSource")]),e._v(" to its constructor, as the following example shows:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('@Bean\nCorsWebFilter corsFilter() {\n\n    CorsConfiguration config = new CorsConfiguration();\n\n    // Possibly...\n    // config.applyPermitDefaultValues()\n\n    config.setAllowCredentials(true);\n    config.addAllowedOrigin("https://domain1.com");\n    config.addAllowedHeader("*");\n    config.addAllowedMethod("*");\n\n    UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource();\n    source.registerCorsConfiguration("/**", config);\n\n    return new CorsWebFilter(source);\n}\n')])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('@Bean\nfun corsFilter(): CorsWebFilter {\n\n    val config = CorsConfiguration()\n\n    // Possibly...\n    // config.applyPermitDefaultValues()\n\n    config.allowCredentials = true\n    config.addAllowedOrigin("https://domain1.com")\n    config.addAllowedHeader("*")\n    config.addAllowedMethod("*")\n\n    val source = UrlBasedCorsConfigurationSource().apply {\n        registerCorsConfiguration("/**", config)\n    }\n    return CorsWebFilter(source)\n}\n')])])]),a("h3",{attrs:{id:"_1-8-web-security"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_1-8-web-security"}},[e._v("#")]),e._v(" 1.8. Web Security")]),e._v(" "),a("p",[a("RouterLink",{attrs:{to:"/en/spring-framework/web.html#mvc-web-security"}},[e._v("Web MVC")])],1),e._v(" "),a("p",[e._v("The "),a("a",{attrs:{href:"https://projects.spring.io/spring-security/",target:"_blank",rel:"noopener noreferrer"}},[e._v("Spring Security"),a("OutboundLink")],1),e._v(" project provides support\nfor protecting web applications from malicious exploits. See the Spring Security\nreference documentation, including:")]),e._v(" "),a("ul",[a("li",[a("p",[a("a",{attrs:{href:"https://docs.spring.io/spring-security/site/docs/current/reference/html5/#jc-webflux",target:"_blank",rel:"noopener noreferrer"}},[e._v("WebFlux Security"),a("OutboundLink")],1)])]),e._v(" "),a("li",[a("p",[a("a",{attrs:{href:"https://docs.spring.io/spring-security/site/docs/current/reference/html5/#test-webflux",target:"_blank",rel:"noopener noreferrer"}},[e._v("WebFlux Testing Support"),a("OutboundLink")],1)])]),e._v(" "),a("li",[a("p",[a("a",{attrs:{href:"https://docs.spring.io/spring-security/site/docs/current/reference/html5/#csrf",target:"_blank",rel:"noopener noreferrer"}},[e._v("CSRF Protection"),a("OutboundLink")],1)])]),e._v(" "),a("li",[a("p",[a("a",{attrs:{href:"https://docs.spring.io/spring-security/site/docs/current/reference/html5/#headers",target:"_blank",rel:"noopener noreferrer"}},[e._v("Security Response Headers"),a("OutboundLink")],1)])])]),e._v(" "),a("h3",{attrs:{id:"_1-9-view-technologies"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_1-9-view-technologies"}},[e._v("#")]),e._v(" 1.9. View Technologies")]),e._v(" "),a("p",[a("RouterLink",{attrs:{to:"/en/spring-framework/web.html#mvc-view"}},[e._v("Web MVC")])],1),e._v(" "),a("p",[e._v("The use of view technologies in Spring WebFlux is pluggable. Whether you decide to\nuse Thymeleaf, FreeMarker, or some other view technology is primarily a matter of a\nconfiguration change. This chapter covers the view technologies integrated with Spring\nWebFlux. We assume you are already familiar with "),a("a",{attrs:{href:"#webflux-viewresolution"}},[e._v("View Resolution")]),e._v(".")]),e._v(" "),a("h4",{attrs:{id:"_1-9-1-thymeleaf"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_1-9-1-thymeleaf"}},[e._v("#")]),e._v(" 1.9.1. Thymeleaf")]),e._v(" "),a("p",[a("RouterLink",{attrs:{to:"/en/spring-framework/web.html#mvc-view-thymeleaf"}},[e._v("Web MVC")])],1),e._v(" "),a("p",[e._v("Thymeleaf is a modern server-side Java template engine that emphasizes natural HTML\ntemplates that can be previewed in a browser by double-clicking, which is very\nhelpful for independent work on UI templates (for example, by a designer) without the need for a\nrunning server. Thymeleaf offers an extensive set of features, and it is actively developed\nand maintained. For a more complete introduction, see the"),a("a",{attrs:{href:"https://www.thymeleaf.org/",target:"_blank",rel:"noopener noreferrer"}},[e._v("Thymeleaf"),a("OutboundLink")],1),e._v(" project home page.")]),e._v(" "),a("p",[e._v("The Thymeleaf integration with Spring WebFlux is managed by the Thymeleaf project. The\nconfiguration involves a few bean declarations, such as"),a("code",[e._v("SpringResourceTemplateResolver")]),e._v(", "),a("code",[e._v("SpringWebFluxTemplateEngine")]),e._v(", and"),a("code",[e._v("ThymeleafReactiveViewResolver")]),e._v(". For more details, see"),a("a",{attrs:{href:"https://www.thymeleaf.org/documentation.html",target:"_blank",rel:"noopener noreferrer"}},[e._v("Thymeleaf+Spring"),a("OutboundLink")],1),e._v(" and the WebFlux integration"),a("a",{attrs:{href:"http://forum.thymeleaf.org/Thymeleaf-3-0-8-JUST-PUBLISHED-td4030687.html",target:"_blank",rel:"noopener noreferrer"}},[e._v("announcement"),a("OutboundLink")],1),e._v(".")]),e._v(" "),a("h4",{attrs:{id:"_1-9-2-freemarker"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_1-9-2-freemarker"}},[e._v("#")]),e._v(" 1.9.2. FreeMarker")]),e._v(" "),a("p",[a("RouterLink",{attrs:{to:"/en/spring-framework/web.html#mvc-view-freemarker"}},[e._v("Web MVC")])],1),e._v(" "),a("p",[a("a",{attrs:{href:"https://freemarker.apache.org/",target:"_blank",rel:"noopener noreferrer"}},[e._v("Apache FreeMarker"),a("OutboundLink")],1),e._v(" is a template engine for generating any\nkind of text output from HTML to email and others. The Spring Framework has built-in\nintegration for using Spring WebFlux with FreeMarker templates.")]),e._v(" "),a("h5",{attrs:{id:"view-configuration"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#view-configuration"}},[e._v("#")]),e._v(" View Configuration")]),e._v(" "),a("p",[a("RouterLink",{attrs:{to:"/en/spring-framework/web.html#mvc-view-freemarker-contextconfig"}},[e._v("Web MVC")])],1),e._v(" "),a("p",[e._v("The following example shows how to configure FreeMarker as a view technology:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('@Configuration\n@EnableWebFlux\npublic class WebConfig implements WebFluxConfigurer {\n\n    @Override\n    public void configureViewResolvers(ViewResolverRegistry registry) {\n        registry.freeMarker();\n    }\n\n    // Configure FreeMarker...\n\n    @Bean\n    public FreeMarkerConfigurer freeMarkerConfigurer() {\n        FreeMarkerConfigurer configurer = new FreeMarkerConfigurer();\n        configurer.setTemplateLoaderPath("classpath:/templates/freemarker");\n        return configurer;\n    }\n}\n')])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('@Configuration\n@EnableWebFlux\nclass WebConfig : WebFluxConfigurer {\n\n    override fun configureViewResolvers(registry: ViewResolverRegistry) {\n        registry.freeMarker()\n    }\n\n    // Configure FreeMarker...\n\n    @Bean\n    fun freeMarkerConfigurer() = FreeMarkerConfigurer().apply {\n        setTemplateLoaderPath("classpath:/templates/freemarker")\n    }\n}\n')])])]),a("p",[e._v("Your templates need to be stored in the directory specified by the "),a("code",[e._v("FreeMarkerConfigurer")]),e._v(",\nshown in the preceding example. Given the preceding configuration, if your controller\nreturns the view name, "),a("code",[e._v("welcome")]),e._v(", the resolver looks for the"),a("code",[e._v("classpath:/templates/freemarker/welcome.ftl")]),e._v(" template.")]),e._v(" "),a("h5",{attrs:{id:"freemarker-configuration"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#freemarker-configuration"}},[e._v("#")]),e._v(" FreeMarker Configuration")]),e._v(" "),a("p",[a("RouterLink",{attrs:{to:"/en/spring-framework/web.html#mvc-views-freemarker"}},[e._v("Web MVC")])],1),e._v(" "),a("p",[e._v("You can pass FreeMarker 'Settings' and 'SharedVariables' directly to the FreeMarker"),a("code",[e._v("Configuration")]),e._v(" object (which is managed by Spring) by setting the appropriate bean\nproperties on the "),a("code",[e._v("FreeMarkerConfigurer")]),e._v(" bean. The "),a("code",[e._v("freemarkerSettings")]),e._v(" property requires\na "),a("code",[e._v("java.util.Properties")]),e._v(" object, and the "),a("code",[e._v("freemarkerVariables")]),e._v(" property requires a"),a("code",[e._v("java.util.Map")]),e._v(". The following example shows how to use a "),a("code",[e._v("FreeMarkerConfigurer")]),e._v(":")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('@Configuration\n@EnableWebFlux\npublic class WebConfig implements WebFluxConfigurer {\n\n    // ...\n\n    @Bean\n    public FreeMarkerConfigurer freeMarkerConfigurer() {\n        Map<String, Object> variables = new HashMap<>();\n        variables.put("xml_escape", new XmlEscape());\n\n        FreeMarkerConfigurer configurer = new FreeMarkerConfigurer();\n        configurer.setTemplateLoaderPath("classpath:/templates");\n        configurer.setFreemarkerVariables(variables);\n        return configurer;\n    }\n}\n')])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('@Configuration\n@EnableWebFlux\nclass WebConfig : WebFluxConfigurer {\n\n    // ...\n\n    @Bean\n    fun freeMarkerConfigurer() = FreeMarkerConfigurer().apply {\n        setTemplateLoaderPath("classpath:/templates")\n        setFreemarkerVariables(mapOf("xml_escape" to XmlEscape()))\n    }\n}\n')])])]),a("p",[e._v("See the FreeMarker documentation for details of settings and variables as they apply to\nthe "),a("code",[e._v("Configuration")]),e._v(" object.")]),e._v(" "),a("h5",{attrs:{id:"form-handling"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#form-handling"}},[e._v("#")]),e._v(" Form Handling")]),e._v(" "),a("p",[a("RouterLink",{attrs:{to:"/en/spring-framework/web.html#mvc-view-freemarker-forms"}},[e._v("Web MVC")])],1),e._v(" "),a("p",[e._v("Spring provides a tag library for use in JSPs that contains, among others, a"),a("code",[e._v("<spring:bind/>")]),e._v(" element. This element primarily lets forms display values from\nform-backing objects and show the results of failed validations from a "),a("code",[e._v("Validator")]),e._v(" in the\nweb or business tier. Spring also has support for the same functionality in FreeMarker,\nwith additional convenience macros for generating form input elements themselves.")]),e._v(" "),a("h5",{attrs:{id:"the-bind-macros"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#the-bind-macros"}},[e._v("#")]),e._v(" The Bind Macros#")]),e._v(" "),a("p",[a("RouterLink",{attrs:{to:"/en/spring-framework/web.html#mvc-view-bind-macros"}},[e._v("Web MVC")])],1),e._v(" "),a("p",[e._v("A standard set of macros are maintained within the "),a("code",[e._v("spring-webflux.jar")]),e._v(" file for\nFreeMarker, so they are always available to a suitably configured application.")]),e._v(" "),a("p",[e._v("Some of the macros defined in the Spring templating libraries are considered internal\n(private), but no such scoping exists in the macro definitions, making all macros visible\nto calling code and user templates. The following sections concentrate only on the macros\nyou need to directly call from within your templates. If you wish to view the macro code\ndirectly, the file is called "),a("code",[e._v("spring.ftl")]),e._v(" and is in the"),a("code",[e._v("org.springframework.web.reactive.result.view.freemarker")]),e._v(" package.")]),e._v(" "),a("p",[e._v("For additional details on binding support, see "),a("RouterLink",{attrs:{to:"/en/spring-framework/web.html#mvc-view-simple-binding"}},[e._v("Simple\nBinding")]),e._v(" for Spring MVC.")],1),e._v(" "),a("h5",{attrs:{id:"form-macros"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#form-macros"}},[e._v("#")]),e._v(" Form Macros#")]),e._v(" "),a("p",[e._v("For details on Spring’s form macro support for FreeMarker templates, consult the following\nsections of the Spring MVC documentation.")]),e._v(" "),a("ul",[a("li",[a("p",[a("RouterLink",{attrs:{to:"/en/spring-framework/web.html#mvc-views-form-macros"}},[e._v("Input Macros")])],1)]),e._v(" "),a("li",[a("p",[a("RouterLink",{attrs:{to:"/en/spring-framework/web.html#mvc-views-form-macros-input"}},[e._v("Input Fields")])],1)]),e._v(" "),a("li",[a("p",[a("RouterLink",{attrs:{to:"/en/spring-framework/web.html#mvc-views-form-macros-select"}},[e._v("Selection Fields")])],1)]),e._v(" "),a("li",[a("p",[a("RouterLink",{attrs:{to:"/en/spring-framework/web.html#mvc-views-form-macros-html-escaping"}},[e._v("HTML Escaping")])],1)])]),e._v(" "),a("h4",{attrs:{id:"_1-9-3-script-views"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_1-9-3-script-views"}},[e._v("#")]),e._v(" 1.9.3. Script Views")]),e._v(" "),a("p",[a("RouterLink",{attrs:{to:"/en/spring-framework/web.html#mvc-view-script"}},[e._v("Web MVC")])],1),e._v(" "),a("p",[e._v("The Spring Framework has a built-in integration for using Spring WebFlux with any\ntemplating library that can run on top of the"),a("a",{attrs:{href:"https://www.jcp.org/en/jsr/detail?id=223",target:"_blank",rel:"noopener noreferrer"}},[e._v("JSR-223"),a("OutboundLink")],1),e._v(" Java scripting engine.\nThe following table shows the templating libraries that we have tested on different script engines:")]),e._v(" "),a("table",[a("thead",[a("tr",[a("th",[e._v("Scripting Library")]),e._v(" "),a("th",[e._v("Scripting Engine")])])]),e._v(" "),a("tbody",[a("tr",[a("td",[a("a",{attrs:{href:"https://handlebarsjs.com/",target:"_blank",rel:"noopener noreferrer"}},[e._v("Handlebars"),a("OutboundLink")],1)]),e._v(" "),a("td",[a("a",{attrs:{href:"https://openjdk.java.net/projects/nashorn/",target:"_blank",rel:"noopener noreferrer"}},[e._v("Nashorn"),a("OutboundLink")],1)])]),e._v(" "),a("tr",[a("td",[a("a",{attrs:{href:"https://mustache.github.io/",target:"_blank",rel:"noopener noreferrer"}},[e._v("Mustache"),a("OutboundLink")],1)]),e._v(" "),a("td",[a("a",{attrs:{href:"https://openjdk.java.net/projects/nashorn/",target:"_blank",rel:"noopener noreferrer"}},[e._v("Nashorn"),a("OutboundLink")],1)])]),e._v(" "),a("tr",[a("td",[a("a",{attrs:{href:"https://facebook.github.io/react/",target:"_blank",rel:"noopener noreferrer"}},[e._v("React"),a("OutboundLink")],1)]),e._v(" "),a("td",[a("a",{attrs:{href:"https://openjdk.java.net/projects/nashorn/",target:"_blank",rel:"noopener noreferrer"}},[e._v("Nashorn"),a("OutboundLink")],1)])]),e._v(" "),a("tr",[a("td",[a("a",{attrs:{href:"https://www.embeddedjs.com/",target:"_blank",rel:"noopener noreferrer"}},[e._v("EJS"),a("OutboundLink")],1)]),e._v(" "),a("td",[a("a",{attrs:{href:"https://openjdk.java.net/projects/nashorn/",target:"_blank",rel:"noopener noreferrer"}},[e._v("Nashorn"),a("OutboundLink")],1)])]),e._v(" "),a("tr",[a("td",[a("a",{attrs:{href:"https://www.stuartellis.name/articles/erb/",target:"_blank",rel:"noopener noreferrer"}},[e._v("ERB"),a("OutboundLink")],1)]),e._v(" "),a("td",[a("a",{attrs:{href:"https://www.jruby.org",target:"_blank",rel:"noopener noreferrer"}},[e._v("JRuby"),a("OutboundLink")],1)])]),e._v(" "),a("tr",[a("td",[a("a",{attrs:{href:"https://docs.python.org/2/library/string.html#template-strings",target:"_blank",rel:"noopener noreferrer"}},[e._v("String templates"),a("OutboundLink")],1)]),e._v(" "),a("td",[a("a",{attrs:{href:"https://www.jython.org/",target:"_blank",rel:"noopener noreferrer"}},[e._v("Jython"),a("OutboundLink")],1)])]),e._v(" "),a("tr",[a("td",[a("a",{attrs:{href:"https://github.com/sdeleuze/kotlin-script-templating",target:"_blank",rel:"noopener noreferrer"}},[e._v("Kotlin Script templating"),a("OutboundLink")],1)]),e._v(" "),a("td",[a("a",{attrs:{href:"https://kotlinlang.org/",target:"_blank",rel:"noopener noreferrer"}},[e._v("Kotlin"),a("OutboundLink")],1)])])])]),e._v(" "),a("table",[a("thead",[a("tr",[a("th"),e._v(" "),a("th",[e._v("The basic rule for integrating any other script engine is that it must implement the"),a("code",[e._v("ScriptEngine")]),e._v(" and "),a("code",[e._v("Invocable")]),e._v(" interfaces.")])])]),e._v(" "),a("tbody")]),e._v(" "),a("h5",{attrs:{id:"requirements"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#requirements"}},[e._v("#")]),e._v(" Requirements")]),e._v(" "),a("p",[a("RouterLink",{attrs:{to:"/en/spring-framework/web.html#mvc-view-script-dependencies"}},[e._v("Web MVC")])],1),e._v(" "),a("p",[e._v("You need to have the script engine on your classpath, the details of which vary by script engine:")]),e._v(" "),a("ul",[a("li",[a("p",[e._v("The "),a("a",{attrs:{href:"https://openjdk.java.net/projects/nashorn/",target:"_blank",rel:"noopener noreferrer"}},[e._v("Nashorn"),a("OutboundLink")],1),e._v(" JavaScript engine is provided with\nJava 8+. Using the latest update release available is highly recommended.")])]),e._v(" "),a("li",[a("p",[a("a",{attrs:{href:"https://www.jruby.org",target:"_blank",rel:"noopener noreferrer"}},[e._v("JRuby"),a("OutboundLink")],1),e._v(" should be added as a dependency for Ruby support.")])]),e._v(" "),a("li",[a("p",[a("a",{attrs:{href:"https://www.jython.org",target:"_blank",rel:"noopener noreferrer"}},[e._v("Jython"),a("OutboundLink")],1),e._v(" should be added as a dependency for Python support.")])]),e._v(" "),a("li",[a("p",[a("code",[e._v("org.jetbrains.kotlin:kotlin-script-util")]),e._v(" dependency and a "),a("code",[e._v("META-INF/services/javax.script.ScriptEngineFactory")]),e._v("file containing a "),a("code",[e._v("org.jetbrains.kotlin.script.jsr223.KotlinJsr223JvmLocalScriptEngineFactory")]),e._v("line should be added for Kotlin script support. See"),a("a",{attrs:{href:"https://github.com/sdeleuze/kotlin-script-templating",target:"_blank",rel:"noopener noreferrer"}},[e._v("this example"),a("OutboundLink")],1),e._v(" for more detail.")])])]),e._v(" "),a("p",[e._v("You need to have the script templating library. One way to do that for JavaScript is\nthrough "),a("a",{attrs:{href:"https://www.webjars.org/",target:"_blank",rel:"noopener noreferrer"}},[e._v("WebJars"),a("OutboundLink")],1),e._v(".")]),e._v(" "),a("h5",{attrs:{id:"script-templates"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#script-templates"}},[e._v("#")]),e._v(" Script Templates")]),e._v(" "),a("p",[a("RouterLink",{attrs:{to:"/en/spring-framework/web.html#mvc-view-script-integrate"}},[e._v("Web MVC")])],1),e._v(" "),a("p",[e._v("You can declare a "),a("code",[e._v("ScriptTemplateConfigurer")]),e._v(" bean to specify the script engine to use,\nthe script files to load, what function to call to render templates, and so on.\nThe following example uses Mustache templates and the Nashorn JavaScript engine:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('@Configuration\n@EnableWebFlux\npublic class WebConfig implements WebFluxConfigurer {\n\n    @Override\n    public void configureViewResolvers(ViewResolverRegistry registry) {\n        registry.scriptTemplate();\n    }\n\n    @Bean\n    public ScriptTemplateConfigurer configurer() {\n        ScriptTemplateConfigurer configurer = new ScriptTemplateConfigurer();\n        configurer.setEngineName("nashorn");\n        configurer.setScripts("mustache.js");\n        configurer.setRenderObject("Mustache");\n        configurer.setRenderFunction("render");\n        return configurer;\n    }\n}\n')])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('@Configuration\n@EnableWebFlux\nclass WebConfig : WebFluxConfigurer {\n\n    override fun configureViewResolvers(registry: ViewResolverRegistry) {\n        registry.scriptTemplate()\n    }\n\n    @Bean\n    fun configurer() = ScriptTemplateConfigurer().apply {\n        engineName = "nashorn"\n        setScripts("mustache.js")\n        renderObject = "Mustache"\n        renderFunction = "render"\n    }\n}\n')])])]),a("p",[e._v("The "),a("code",[e._v("render")]),e._v(" function is called with the following parameters:")]),e._v(" "),a("ul",[a("li",[a("p",[a("code",[e._v("String template")]),e._v(": The template content")])]),e._v(" "),a("li",[a("p",[a("code",[e._v("Map model")]),e._v(": The view model")])]),e._v(" "),a("li",[a("p",[a("code",[e._v("RenderingContext renderingContext")]),e._v(": The"),a("a",{attrs:{href:"https://docs.spring.io/spring-framework/docs/5.3.16/javadoc-api/org/springframework/web/servlet/view/script/RenderingContext.html",target:"_blank",rel:"noopener noreferrer"}},[a("code",[e._v("RenderingContext")]),a("OutboundLink")],1),e._v("that gives access to the application context, the locale, the template loader, and the\nURL (since 5.0)")])])]),e._v(" "),a("p",[a("code",[e._v("Mustache.render()")]),e._v(" is natively compatible with this signature, so you can call it directly.")]),e._v(" "),a("p",[e._v("If your templating technology requires some customization, you can provide a script that\nimplements a custom render function. For example, "),a("a",{attrs:{href:"https://handlebarsjs.com",target:"_blank",rel:"noopener noreferrer"}},[e._v("Handlerbars"),a("OutboundLink")],1),e._v("needs to compile templates before using them and requires a"),a("a",{attrs:{href:"https://en.wikipedia.org/wiki/Polyfill",target:"_blank",rel:"noopener noreferrer"}},[e._v("polyfill"),a("OutboundLink")],1),e._v(" in order to emulate some\nbrowser facilities not available in the server-side script engine.\nThe following example shows how to set a custom render function:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('@Configuration\n@EnableWebFlux\npublic class WebConfig implements WebFluxConfigurer {\n\n    @Override\n    public void configureViewResolvers(ViewResolverRegistry registry) {\n        registry.scriptTemplate();\n    }\n\n    @Bean\n    public ScriptTemplateConfigurer configurer() {\n        ScriptTemplateConfigurer configurer = new ScriptTemplateConfigurer();\n        configurer.setEngineName("nashorn");\n        configurer.setScripts("polyfill.js", "handlebars.js", "render.js");\n        configurer.setRenderFunction("render");\n        configurer.setSharedEngine(false);\n        return configurer;\n    }\n}\n')])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('@Configuration\n@EnableWebFlux\nclass WebConfig : WebFluxConfigurer {\n\n    override fun configureViewResolvers(registry: ViewResolverRegistry) {\n        registry.scriptTemplate()\n    }\n\n    @Bean\n    fun configurer() = ScriptTemplateConfigurer().apply {\n        engineName = "nashorn"\n        setScripts("polyfill.js", "handlebars.js", "render.js")\n        renderFunction = "render"\n        isSharedEngine = false\n    }\n}\n')])])]),a("table",[a("thead",[a("tr",[a("th"),e._v(" "),a("th",[e._v("Setting the "),a("code",[e._v("sharedEngine")]),e._v(" property to "),a("code",[e._v("false")]),e._v(" is required when using non-thread-safe"),a("br"),e._v("script engines with templating libraries not designed for concurrency, such as Handlebars or"),a("br"),e._v("React running on Nashorn. In that case, Java SE 8 update 60 is required, due to"),a("a",{attrs:{href:"https://bugs.openjdk.java.net/browse/JDK-8076099",target:"_blank",rel:"noopener noreferrer"}},[e._v("this bug"),a("OutboundLink")],1),e._v(", but it is generally"),a("br"),e._v("recommended to use a recent Java SE patch release in any case.")])])]),e._v(" "),a("tbody")]),e._v(" "),a("p",[a("code",[e._v("polyfill.js")]),e._v(" defines only the "),a("code",[e._v("window")]),e._v(" object needed by Handlebars to run properly,\nas the following snippet shows:")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("var window = {};\n")])])]),a("p",[e._v("This basic "),a("code",[e._v("render.js")]),e._v(" implementation compiles the template before using it. A production\nready implementation should also store and reused cached templates or pre-compiled templates.\nThis can be done on the script side, as well as any customization you need (managing\ntemplate engine configuration for example).\nThe following example shows how compile a template:")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("function render(template, model) {\n    var compiledTemplate = Handlebars.compile(template);\n    return compiledTemplate(model);\n}\n")])])]),a("p",[e._v("Check out the Spring Framework unit tests,"),a("a",{attrs:{href:"https://github.com/spring-projects/spring-framework/tree/main/spring-webflux/src/test/java/org/springframework/web/reactive/result/view/script",target:"_blank",rel:"noopener noreferrer"}},[e._v("Java"),a("OutboundLink")],1),e._v(", and"),a("a",{attrs:{href:"https://github.com/spring-projects/spring-framework/tree/main/spring-webflux/src/test/resources/org/springframework/web/reactive/result/view/script",target:"_blank",rel:"noopener noreferrer"}},[e._v("resources"),a("OutboundLink")],1),e._v(",\nfor more configuration examples.")]),e._v(" "),a("h4",{attrs:{id:"_1-9-4-json-and-xml"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_1-9-4-json-and-xml"}},[e._v("#")]),e._v(" 1.9.4. JSON and XML")]),e._v(" "),a("p",[a("RouterLink",{attrs:{to:"/en/spring-framework/web.html#mvc-view-jackson"}},[e._v("Web MVC")])],1),e._v(" "),a("p",[e._v("For "),a("a",{attrs:{href:"#webflux-multiple-representations"}},[e._v("Content Negotiation")]),e._v(" purposes, it is useful to be able to alternate\nbetween rendering a model with an HTML template or as other formats (such as JSON or XML),\ndepending on the content type requested by the client. To support doing so, Spring WebFlux\nprovides the "),a("code",[e._v("HttpMessageWriterView")]),e._v(", which you can use to plug in any of the available"),a("a",{attrs:{href:"#webflux-codecs"}},[e._v("Codecs")]),e._v(" from "),a("code",[e._v("spring-web")]),e._v(", such as "),a("code",[e._v("Jackson2JsonEncoder")]),e._v(", "),a("code",[e._v("Jackson2SmileEncoder")]),e._v(",\nor "),a("code",[e._v("Jaxb2XmlEncoder")]),e._v(".")]),e._v(" "),a("p",[e._v("Unlike other view technologies, "),a("code",[e._v("HttpMessageWriterView")]),e._v(" does not require a "),a("code",[e._v("ViewResolver")]),e._v("but is instead "),a("a",{attrs:{href:"#webflux-config-view-resolvers"}},[e._v("configured")]),e._v(" as a default view. You can\nconfigure one or more such default views, wrapping different "),a("code",[e._v("HttpMessageWriter")]),e._v(" instances\nor "),a("code",[e._v("Encoder")]),e._v(" instances. The one that matches the requested content type is used at runtime.")]),e._v(" "),a("p",[e._v("In most cases, a model contains multiple attributes. To determine which one to serialize,\nyou can configure "),a("code",[e._v("HttpMessageWriterView")]),e._v(" with the name of the model attribute to use for\nrendering. If the model contains only one attribute, that one is used.")]),e._v(" "),a("h3",{attrs:{id:"_1-10-http-caching"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_1-10-http-caching"}},[e._v("#")]),e._v(" 1.10. HTTP Caching")]),e._v(" "),a("p",[a("RouterLink",{attrs:{to:"/en/spring-framework/web.html#mvc-caching"}},[e._v("Web MVC")])],1),e._v(" "),a("p",[e._v("HTTP caching can significantly improve the performance of a web application. HTTP caching\nrevolves around the "),a("code",[e._v("Cache-Control")]),e._v(" response header and subsequent conditional request\nheaders, such as "),a("code",[e._v("Last-Modified")]),e._v(" and "),a("code",[e._v("ETag")]),e._v(". "),a("code",[e._v("Cache-Control")]),e._v(" advises private (for example, browser)\nand public (for example, proxy) caches how to cache and re-use responses. An "),a("code",[e._v("ETag")]),e._v(" header is used\nto make a conditional request that may result in a 304 (NOT_MODIFIED) without a body,\nif the content has not changed. "),a("code",[e._v("ETag")]),e._v(" can be seen as a more sophisticated successor to\nthe "),a("code",[e._v("Last-Modified")]),e._v(" header.")]),e._v(" "),a("p",[e._v("This section describes the HTTP caching related options available in Spring WebFlux.")]),e._v(" "),a("h4",{attrs:{id:"_1-10-1-cachecontrol"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_1-10-1-cachecontrol"}},[e._v("#")]),e._v(" 1.10.1. "),a("code",[e._v("CacheControl")])]),e._v(" "),a("p",[a("RouterLink",{attrs:{to:"/en/spring-framework/web.html#mvc-caching-cachecontrol"}},[e._v("Web MVC")])],1),e._v(" "),a("p",[a("a",{attrs:{href:"https://docs.spring.io/spring-framework/docs/5.3.16/javadoc-api/org/springframework/http/CacheControl.html",target:"_blank",rel:"noopener noreferrer"}},[a("code",[e._v("CacheControl")]),a("OutboundLink")],1),e._v(" provides support for\nconfiguring settings related to the "),a("code",[e._v("Cache-Control")]),e._v(" header and is accepted as an argument\nin a number of places:")]),e._v(" "),a("ul",[a("li",[a("p",[a("a",{attrs:{href:"#webflux-caching-etag-lastmodified"}},[e._v("Controllers")])])]),e._v(" "),a("li",[a("p",[a("a",{attrs:{href:"#webflux-caching-static-resources"}},[e._v("Static Resources")])])])]),e._v(" "),a("p",[e._v("While "),a("a",{attrs:{href:"https://tools.ietf.org/html/rfc7234#section-5.2.2",target:"_blank",rel:"noopener noreferrer"}},[e._v("RFC 7234"),a("OutboundLink")],1),e._v(" describes all possible\ndirectives for the "),a("code",[e._v("Cache-Control")]),e._v(" response header, the "),a("code",[e._v("CacheControl")]),e._v(" type takes a\nuse case-oriented approach that focuses on the common scenarios, as the following example shows:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('// Cache for an hour - "Cache-Control: max-age=3600"\nCacheControl ccCacheOneHour = CacheControl.maxAge(1, TimeUnit.HOURS);\n\n// Prevent caching - "Cache-Control: no-store"\nCacheControl ccNoStore = CacheControl.noStore();\n\n// Cache for ten days in public and private caches,\n// public caches should not transform the response\n// "Cache-Control: max-age=864000, public, no-transform"\nCacheControl ccCustom = CacheControl.maxAge(10, TimeUnit.DAYS).noTransform().cachePublic();\n')])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('// Cache for an hour - "Cache-Control: max-age=3600"\nval ccCacheOneHour = CacheControl.maxAge(1, TimeUnit.HOURS)\n\n// Prevent caching - "Cache-Control: no-store"\nval ccNoStore = CacheControl.noStore()\n\n// Cache for ten days in public and private caches,\n// public caches should not transform the response\n// "Cache-Control: max-age=864000, public, no-transform"\nval ccCustom = CacheControl.maxAge(10, TimeUnit.DAYS).noTransform().cachePublic()\n')])])]),a("h4",{attrs:{id:"_1-10-2-controllers"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_1-10-2-controllers"}},[e._v("#")]),e._v(" 1.10.2. Controllers")]),e._v(" "),a("p",[a("RouterLink",{attrs:{to:"/en/spring-framework/web.html#mvc-caching-etag-lastmodified"}},[e._v("Web MVC")])],1),e._v(" "),a("p",[e._v("Controllers can add explicit support for HTTP caching. We recommend doing so, since the"),a("code",[e._v("lastModified")]),e._v(" or "),a("code",[e._v("ETag")]),e._v(" value for a resource needs to be calculated before it can be compared\nagainst conditional request headers. A controller can add an "),a("code",[e._v("ETag")]),e._v(" and "),a("code",[e._v("Cache-Control")]),e._v("settings to a "),a("code",[e._v("ResponseEntity")]),e._v(", as the following example shows:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('@GetMapping("/book/{id}")\npublic ResponseEntity<Book> showBook(@PathVariable Long id) {\n\n    Book book = findBook(id);\n    String version = book.getVersion();\n\n    return ResponseEntity\n            .ok()\n            .cacheControl(CacheControl.maxAge(30, TimeUnit.DAYS))\n            .eTag(version) // lastModified is also available\n            .body(book);\n}\n')])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('@GetMapping("/book/{id}")\nfun showBook(@PathVariable id: Long): ResponseEntity<Book> {\n\n    val book = findBook(id)\n    val version = book.getVersion()\n\n    return ResponseEntity\n            .ok()\n            .cacheControl(CacheControl.maxAge(30, TimeUnit.DAYS))\n            .eTag(version) // lastModified is also available\n            .body(book)\n}\n')])])]),a("p",[e._v("The preceding example sends a 304 (NOT_MODIFIED) response with an empty body if the comparison\nto the conditional request headers indicates the content has not changed. Otherwise, the"),a("code",[e._v("ETag")]),e._v(" and "),a("code",[e._v("Cache-Control")]),e._v(" headers are added to the response.")]),e._v(" "),a("p",[e._v("You can also make the check against conditional request headers in the controller,\nas the following example shows:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('@RequestMapping\npublic String myHandleMethod(ServerWebExchange exchange, Model model) {\n\n    long eTag = ... (1)\n\n    if (exchange.checkNotModified(eTag)) {\n        return null; (2)\n    }\n\n    model.addAttribute(...); (3)\n    return "myViewName";\n}\n')])])]),a("table",[a("thead",[a("tr",[a("th",[a("strong",[e._v("1")])]),e._v(" "),a("th",[e._v("Application-specific calculation.")])])]),e._v(" "),a("tbody",[a("tr",[a("td",[a("strong",[e._v("2")])]),e._v(" "),a("td",[e._v("Response has been set to 304 (NOT_MODIFIED). No further processing.")])]),e._v(" "),a("tr",[a("td",[a("strong",[e._v("3")])]),e._v(" "),a("td",[e._v("Continue with request processing.")])])])]),e._v(" "),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('@RequestMapping\nfun myHandleMethod(exchange: ServerWebExchange, model: Model): String? {\n\n    val eTag: Long = ... (1)\n\n    if (exchange.checkNotModified(eTag)) {\n        return null(2)\n    }\n\n    model.addAttribute(...) (3)\n    return "myViewName"\n}\n')])])]),a("table",[a("thead",[a("tr",[a("th",[a("strong",[e._v("1")])]),e._v(" "),a("th",[e._v("Application-specific calculation.")])])]),e._v(" "),a("tbody",[a("tr",[a("td",[a("strong",[e._v("2")])]),e._v(" "),a("td",[e._v("Response has been set to 304 (NOT_MODIFIED). No further processing.")])]),e._v(" "),a("tr",[a("td",[a("strong",[e._v("3")])]),e._v(" "),a("td",[e._v("Continue with request processing.")])])])]),e._v(" "),a("p",[e._v("There are three variants for checking conditional requests against "),a("code",[e._v("eTag")]),e._v(" values, "),a("code",[e._v("lastModified")]),e._v("values, or both. For conditional "),a("code",[e._v("GET")]),e._v(" and "),a("code",[e._v("HEAD")]),e._v(" requests, you can set the response to\n304 (NOT_MODIFIED). For conditional "),a("code",[e._v("POST")]),e._v(", "),a("code",[e._v("PUT")]),e._v(", and "),a("code",[e._v("DELETE")]),e._v(", you can instead set the response\nto 412 (PRECONDITION_FAILED) to prevent concurrent modification.")]),e._v(" "),a("h4",{attrs:{id:"_1-10-3-static-resources"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_1-10-3-static-resources"}},[e._v("#")]),e._v(" 1.10.3. Static Resources")]),e._v(" "),a("p",[a("RouterLink",{attrs:{to:"/en/spring-framework/web.html#mvc-caching-static-resources"}},[e._v("Web MVC")])],1),e._v(" "),a("p",[e._v("You should serve static resources with a "),a("code",[e._v("Cache-Control")]),e._v(" and conditional response headers\nfor optimal performance. See the section on configuring "),a("a",{attrs:{href:"#webflux-config-static-resources"}},[e._v("Static Resources")]),e._v(".")]),e._v(" "),a("h3",{attrs:{id:"_1-11-webflux-config"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_1-11-webflux-config"}},[e._v("#")]),e._v(" 1.11. WebFlux Config")]),e._v(" "),a("p",[a("RouterLink",{attrs:{to:"/en/spring-framework/web.html#mvc-config"}},[e._v("Web MVC")])],1),e._v(" "),a("p",[e._v("The WebFlux Java configuration declares the components that are required to process\nrequests with annotated controllers or functional endpoints, and it offers an API to\ncustomize the configuration. That means you do not need to understand the underlying\nbeans created by the Java configuration. However, if you want to understand them,\nyou can see them in "),a("code",[e._v("WebFluxConfigurationSupport")]),e._v(" or read more about what they are\nin "),a("a",{attrs:{href:"#webflux-special-bean-types"}},[e._v("Special Bean Types")]),e._v(".")]),e._v(" "),a("p",[e._v("For more advanced customizations, not available in the configuration API, you can\ngain full control over the configuration through the"),a("a",{attrs:{href:"#webflux-config-advanced-java"}},[e._v("Advanced Configuration Mode")]),e._v(".")]),e._v(" "),a("h4",{attrs:{id:"_1-11-1-enabling-webflux-config"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_1-11-1-enabling-webflux-config"}},[e._v("#")]),e._v(" 1.11.1. Enabling WebFlux Config")]),e._v(" "),a("p",[a("RouterLink",{attrs:{to:"/en/spring-framework/web.html#mvc-config-enable"}},[e._v("Web MVC")])],1),e._v(" "),a("p",[e._v("You can use the "),a("code",[e._v("@EnableWebFlux")]),e._v(" annotation in your Java config, as the following example shows:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("@Configuration\n@EnableWebFlux\npublic class WebConfig {\n}\n")])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("@Configuration\n@EnableWebFlux\nclass WebConfig\n")])])]),a("p",[e._v("The preceding example registers a number of Spring WebFlux"),a("a",{attrs:{href:"#webflux-special-bean-types"}},[e._v("infrastructure beans")]),e._v(" and adapts to dependencies\navailable on the classpath — for JSON, XML, and others.")]),e._v(" "),a("h4",{attrs:{id:"_1-11-2-webflux-config-api"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_1-11-2-webflux-config-api"}},[e._v("#")]),e._v(" 1.11.2. WebFlux config API")]),e._v(" "),a("p",[a("RouterLink",{attrs:{to:"/en/spring-framework/web.html#mvc-config-customize"}},[e._v("Web MVC")])],1),e._v(" "),a("p",[e._v("In your Java configuration, you can implement the "),a("code",[e._v("WebFluxConfigurer")]),e._v(" interface,\nas the following example shows:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("@Configuration\n@EnableWebFlux\npublic class WebConfig implements WebFluxConfigurer {\n\n    // Implement configuration methods...\n}\n")])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("@Configuration\n@EnableWebFlux\nclass WebConfig : WebFluxConfigurer {\n\n    // Implement configuration methods...\n}\n")])])]),a("h4",{attrs:{id:"_1-11-3-conversion-formatting"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_1-11-3-conversion-formatting"}},[e._v("#")]),e._v(" 1.11.3. Conversion, formatting")]),e._v(" "),a("p",[a("RouterLink",{attrs:{to:"/en/spring-framework/web.html#mvc-config-conversion"}},[e._v("Web MVC")])],1),e._v(" "),a("p",[e._v("By default, formatters for various number and date types are installed, along with support\nfor customization via "),a("code",[e._v("@NumberFormat")]),e._v(" and "),a("code",[e._v("@DateTimeFormat")]),e._v(" on fields.")]),e._v(" "),a("p",[e._v("To register custom formatters and converters in Java config, use the following:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("@Configuration\n@EnableWebFlux\npublic class WebConfig implements WebFluxConfigurer {\n\n    @Override\n    public void addFormatters(FormatterRegistry registry) {\n        // ...\n    }\n\n}\n")])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("@Configuration\n@EnableWebFlux\nclass WebConfig : WebFluxConfigurer {\n\n    override fun addFormatters(registry: FormatterRegistry) {\n        // ...\n    }\n}\n")])])]),a("p",[e._v('By default Spring WebFlux considers the request Locale when parsing and formatting date\nvalues. This works for forms where dates are represented as Strings with "input" form\nfields. For "date" and "time" form fields, however, browsers use a fixed format defined\nin the HTML spec. For such cases date and time formatting can be customized as follows:')]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("@Configuration\n@EnableWebFlux\npublic class WebConfig implements WebFluxConfigurer {\n\n    @Override\n    public void addFormatters(FormatterRegistry registry) {\n        DateTimeFormatterRegistrar registrar = new DateTimeFormatterRegistrar();\n        registrar.setUseIsoFormat(true);\n        registrar.registerFormatters(registry);\n    }\n}\n")])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("@Configuration\n@EnableWebFlux\nclass WebConfig : WebFluxConfigurer {\n\n    override fun addFormatters(registry: FormatterRegistry) {\n        val registrar = DateTimeFormatterRegistrar()\n        registrar.setUseIsoFormat(true)\n        registrar.registerFormatters(registry)\n    }\n}\n")])])]),a("table",[a("thead",[a("tr",[a("th"),e._v(" "),a("th",[e._v("See "),a("RouterLink",{attrs:{to:"/en/spring-framework/core.html#format-FormatterRegistrar-SPI"}},[a("code",[e._v("FormatterRegistrar")]),e._v(" SPI")]),e._v("and the "),a("code",[e._v("FormattingConversionServiceFactoryBean")]),e._v(" for more information on when to"),a("br"),e._v("use "),a("code",[e._v("FormatterRegistrar")]),e._v(" implementations.")],1)])]),e._v(" "),a("tbody")]),e._v(" "),a("h4",{attrs:{id:"_1-11-4-validation"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_1-11-4-validation"}},[e._v("#")]),e._v(" 1.11.4. Validation")]),e._v(" "),a("p",[a("RouterLink",{attrs:{to:"/en/spring-framework/web.html#mvc-config-validation"}},[e._v("Web MVC")])],1),e._v(" "),a("p",[e._v("By default, if "),a("RouterLink",{attrs:{to:"/en/spring-framework/core.html#validation-beanvalidation-overview"}},[e._v("Bean Validation")]),e._v(" is present\non the classpath (for example, the Hibernate Validator), the "),a("code",[e._v("LocalValidatorFactoryBean")]),e._v("is registered as a global "),a("RouterLink",{attrs:{to:"/en/spring-framework/core.html#validator"}},[e._v("validator")]),e._v(" for use with "),a("code",[e._v("@Valid")]),e._v(" and"),a("code",[e._v("@Validated")]),e._v(" on "),a("code",[e._v("@Controller")]),e._v(" method arguments.")],1),e._v(" "),a("p",[e._v("In your Java configuration, you can customize the global "),a("code",[e._v("Validator")]),e._v(" instance,\nas the following example shows:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("@Configuration\n@EnableWebFlux\npublic class WebConfig implements WebFluxConfigurer {\n\n    @Override\n    public Validator getValidator() {\n        // ...\n    }\n\n}\n")])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("@Configuration\n@EnableWebFlux\nclass WebConfig : WebFluxConfigurer {\n\n    override fun getValidator(): Validator {\n        // ...\n    }\n\n}\n")])])]),a("p",[e._v("Note that you can also register "),a("code",[e._v("Validator")]),e._v(" implementations locally,\nas the following example shows:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("@Controller\npublic class MyController {\n\n    @InitBinder\n    protected void initBinder(WebDataBinder binder) {\n        binder.addValidators(new FooValidator());\n    }\n\n}\n")])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("@Controller\nclass MyController {\n\n    @InitBinder\n    protected fun initBinder(binder: WebDataBinder) {\n        binder.addValidators(FooValidator())\n    }\n}\n")])])]),a("table",[a("thead",[a("tr",[a("th"),e._v(" "),a("th",[e._v("If you need to have a "),a("code",[e._v("LocalValidatorFactoryBean")]),e._v(" injected somewhere, create a bean and"),a("br"),e._v("mark it with "),a("code",[e._v("@Primary")]),e._v(" in order to avoid conflict with the one declared in the MVC config.")])])]),e._v(" "),a("tbody")]),e._v(" "),a("h4",{attrs:{id:"_1-11-5-content-type-resolvers"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_1-11-5-content-type-resolvers"}},[e._v("#")]),e._v(" 1.11.5. Content Type Resolvers")]),e._v(" "),a("p",[a("RouterLink",{attrs:{to:"/en/spring-framework/web.html#mvc-config-content-negotiation"}},[e._v("Web MVC")])],1),e._v(" "),a("p",[e._v("You can configure how Spring WebFlux determines the requested media types for"),a("code",[e._v("@Controller")]),e._v(" instances from the request. By default, only the "),a("code",[e._v("Accept")]),e._v(" header is checked,\nbut you can also enable a query parameter-based strategy.")]),e._v(" "),a("p",[e._v("The following example shows how to customize the requested content type resolution:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("@Configuration\n@EnableWebFlux\npublic class WebConfig implements WebFluxConfigurer {\n\n    @Override\n    public void configureContentTypeResolver(RequestedContentTypeResolverBuilder builder) {\n        // ...\n    }\n}\n")])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("@Configuration\n@EnableWebFlux\nclass WebConfig : WebFluxConfigurer {\n\n    override fun configureContentTypeResolver(builder: RequestedContentTypeResolverBuilder) {\n        // ...\n    }\n}\n")])])]),a("h4",{attrs:{id:"_1-11-6-http-message-codecs"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_1-11-6-http-message-codecs"}},[e._v("#")]),e._v(" 1.11.6. HTTP message codecs")]),e._v(" "),a("p",[a("RouterLink",{attrs:{to:"/en/spring-framework/web.html#mvc-config-message-converters"}},[e._v("Web MVC")])],1),e._v(" "),a("p",[e._v("The following example shows how to customize how the request and response body are read and written:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("@Configuration\n@EnableWebFlux\npublic class WebConfig implements WebFluxConfigurer {\n\n    @Override\n    public void configureHttpMessageCodecs(ServerCodecConfigurer configurer) {\n        configurer.defaultCodecs().maxInMemorySize(512 * 1024);\n    }\n}\n")])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("@Configuration\n@EnableWebFlux\nclass WebConfig : WebFluxConfigurer {\n\n    override fun configureHttpMessageCodecs(configurer: ServerCodecConfigurer) {\n        // ...\n    }\n}\n")])])]),a("p",[a("code",[e._v("ServerCodecConfigurer")]),e._v(" provides a set of default readers and writers. You can use it to add\nmore readers and writers, customize the default ones, or replace the default ones completely.")]),e._v(" "),a("p",[e._v("For Jackson JSON and XML, consider using"),a("a",{attrs:{href:"https://docs.spring.io/spring-framework/docs/5.3.16/javadoc-api/org/springframework/http/converter/json/Jackson2ObjectMapperBuilder.html",target:"_blank",rel:"noopener noreferrer"}},[a("code",[e._v("Jackson2ObjectMapperBuilder")]),a("OutboundLink")],1),e._v(",\nwhich customizes Jackson’s default properties with the following ones:")]),e._v(" "),a("ul",[a("li",[a("p",[a("a",{attrs:{href:"https://fasterxml.github.io/jackson-databind/javadoc/2.6/com/fasterxml/jackson/databind/DeserializationFeature.html#FAIL_ON_UNKNOWN_PROPERTIES",target:"_blank",rel:"noopener noreferrer"}},[a("code",[e._v("DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES")]),a("OutboundLink")],1),e._v(" is disabled.")])]),e._v(" "),a("li",[a("p",[a("a",{attrs:{href:"https://fasterxml.github.io/jackson-databind/javadoc/2.6/com/fasterxml/jackson/databind/MapperFeature.html#DEFAULT_VIEW_INCLUSION",target:"_blank",rel:"noopener noreferrer"}},[a("code",[e._v("MapperFeature.DEFAULT_VIEW_INCLUSION")]),a("OutboundLink")],1),e._v(" is disabled.")])])]),e._v(" "),a("p",[e._v("It also automatically registers the following well-known modules if they are detected on the classpath:")]),e._v(" "),a("ul",[a("li",[a("p",[a("a",{attrs:{href:"https://github.com/FasterXML/jackson-datatype-joda",target:"_blank",rel:"noopener noreferrer"}},[a("code",[e._v("jackson-datatype-joda")]),a("OutboundLink")],1),e._v(": Support for Joda-Time types.")])]),e._v(" "),a("li",[a("p",[a("a",{attrs:{href:"https://github.com/FasterXML/jackson-datatype-jsr310",target:"_blank",rel:"noopener noreferrer"}},[a("code",[e._v("jackson-datatype-jsr310")]),a("OutboundLink")],1),e._v(": Support for Java 8 Date and Time API types.")])]),e._v(" "),a("li",[a("p",[a("a",{attrs:{href:"https://github.com/FasterXML/jackson-datatype-jdk8",target:"_blank",rel:"noopener noreferrer"}},[a("code",[e._v("jackson-datatype-jdk8")]),a("OutboundLink")],1),e._v(": Support for other Java 8 types, such as "),a("code",[e._v("Optional")]),e._v(".")])]),e._v(" "),a("li",[a("p",[a("a",{attrs:{href:"https://github.com/FasterXML/jackson-module-kotlin",target:"_blank",rel:"noopener noreferrer"}},[a("code",[e._v("jackson-module-kotlin")]),a("OutboundLink")],1),e._v(": Support for Kotlin classes and data classes.")])])]),e._v(" "),a("h4",{attrs:{id:"_1-11-7-view-resolvers"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_1-11-7-view-resolvers"}},[e._v("#")]),e._v(" 1.11.7. View Resolvers")]),e._v(" "),a("p",[a("RouterLink",{attrs:{to:"/en/spring-framework/web.html#mvc-config-view-resolvers"}},[e._v("Web MVC")])],1),e._v(" "),a("p",[e._v("The following example shows how to configure view resolution:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("@Configuration\n@EnableWebFlux\npublic class WebConfig implements WebFluxConfigurer {\n\n    @Override\n    public void configureViewResolvers(ViewResolverRegistry registry) {\n        // ...\n    }\n}\n")])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("@Configuration\n@EnableWebFlux\nclass WebConfig : WebFluxConfigurer {\n\n    override fun configureViewResolvers(registry: ViewResolverRegistry) {\n        // ...\n    }\n}\n")])])]),a("p",[e._v("The "),a("code",[e._v("ViewResolverRegistry")]),e._v(" has shortcuts for view technologies with which the Spring Framework\nintegrates. The following example uses FreeMarker (which also requires configuring the\nunderlying FreeMarker view technology):")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('@Configuration\n@EnableWebFlux\npublic class WebConfig implements WebFluxConfigurer {\n\n    @Override\n    public void configureViewResolvers(ViewResolverRegistry registry) {\n        registry.freeMarker();\n    }\n\n    // Configure Freemarker...\n\n    @Bean\n    public FreeMarkerConfigurer freeMarkerConfigurer() {\n        FreeMarkerConfigurer configurer = new FreeMarkerConfigurer();\n        configurer.setTemplateLoaderPath("classpath:/templates");\n        return configurer;\n    }\n}\n')])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('@Configuration\n@EnableWebFlux\nclass WebConfig : WebFluxConfigurer {\n\n    override fun configureViewResolvers(registry: ViewResolverRegistry) {\n        registry.freeMarker()\n    }\n\n    // Configure Freemarker...\n\n    @Bean\n    fun freeMarkerConfigurer() = FreeMarkerConfigurer().apply {\n        setTemplateLoaderPath("classpath:/templates")\n    }\n}\n')])])]),a("p",[e._v("You can also plug in any "),a("code",[e._v("ViewResolver")]),e._v(" implementation, as the following example shows:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("@Configuration\n@EnableWebFlux\npublic class WebConfig implements WebFluxConfigurer {\n\n    @Override\n    public void configureViewResolvers(ViewResolverRegistry registry) {\n        ViewResolver resolver = ... ;\n        registry.viewResolver(resolver);\n    }\n}\n")])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("@Configuration\n@EnableWebFlux\nclass WebConfig : WebFluxConfigurer {\n\n    override fun configureViewResolvers(registry: ViewResolverRegistry) {\n        val resolver: ViewResolver = ...\n        registry.viewResolver(resolver\n    }\n}\n")])])]),a("p",[e._v("To support "),a("a",{attrs:{href:"#webflux-multiple-representations"}},[e._v("Content Negotiation")]),e._v(" and rendering other formats\nthrough view resolution (besides HTML), you can configure one or more default views based\non the "),a("code",[e._v("HttpMessageWriterView")]),e._v(" implementation, which accepts any of the available"),a("a",{attrs:{href:"#webflux-codecs"}},[e._v("Codecs")]),e._v(" from "),a("code",[e._v("spring-web")]),e._v(". The following example shows how to do so:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("@Configuration\n@EnableWebFlux\npublic class WebConfig implements WebFluxConfigurer {\n\n    @Override\n    public void configureViewResolvers(ViewResolverRegistry registry) {\n        registry.freeMarker();\n\n        Jackson2JsonEncoder encoder = new Jackson2JsonEncoder();\n        registry.defaultViews(new HttpMessageWriterView(encoder));\n    }\n\n    // ...\n}\n")])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("@Configuration\n@EnableWebFlux\nclass WebConfig : WebFluxConfigurer {\n\n    override fun configureViewResolvers(registry: ViewResolverRegistry) {\n        registry.freeMarker()\n\n        val encoder = Jackson2JsonEncoder()\n        registry.defaultViews(HttpMessageWriterView(encoder))\n    }\n\n    // ...\n}\n")])])]),a("p",[e._v("See "),a("a",{attrs:{href:"#webflux-view"}},[e._v("View Technologies")]),e._v(" for more on the view technologies that are integrated with Spring WebFlux.")]),e._v(" "),a("h4",{attrs:{id:"_1-11-8-static-resources"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_1-11-8-static-resources"}},[e._v("#")]),e._v(" 1.11.8. Static Resources")]),e._v(" "),a("p",[a("RouterLink",{attrs:{to:"/en/spring-framework/web.html#mvc-config-static-resources"}},[e._v("Web MVC")])],1),e._v(" "),a("p",[e._v("This option provides a convenient way to serve static resources from a list of"),a("a",{attrs:{href:"https://docs.spring.io/spring-framework/docs/5.3.16/javadoc-api/org/springframework/core/io/Resource.html",target:"_blank",rel:"noopener noreferrer"}},[a("code",[e._v("Resource")]),a("OutboundLink")],1),e._v("-based locations.")]),e._v(" "),a("p",[e._v("In the next example, given a request that starts with "),a("code",[e._v("/resources")]),e._v(", the relative path is\nused to find and serve static resources relative to "),a("code",[e._v("/static")]),e._v(" on the classpath. Resources\nare served with a one-year future expiration to ensure maximum use of the browser cache\nand a reduction in HTTP requests made by the browser. The "),a("code",[e._v("Last-Modified")]),e._v(" header is also\nevaluated and, if present, a "),a("code",[e._v("304")]),e._v(" status code is returned. The following list shows\nthe example:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('@Configuration\n@EnableWebFlux\npublic class WebConfig implements WebFluxConfigurer {\n\n    @Override\n    public void addResourceHandlers(ResourceHandlerRegistry registry) {\n        registry.addResourceHandler("/resources/**")\n                .addResourceLocations("/public", "classpath:/static/")\n                .setCacheControl(CacheControl.maxAge(365, TimeUnit.DAYS));\n    }\n\n}\n')])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('@Configuration\n@EnableWebFlux\nclass WebConfig : WebFluxConfigurer {\n\n    override fun addResourceHandlers(registry: ResourceHandlerRegistry) {\n        registry.addResourceHandler("/resources/**")\n                .addResourceLocations("/public", "classpath:/static/")\n                .setCacheControl(CacheControl.maxAge(365, TimeUnit.DAYS))\n    }\n}\n')])])]),a("p",[e._v("The resource handler also supports a chain of"),a("a",{attrs:{href:"https://docs.spring.io/spring-framework/docs/5.3.16/javadoc-api/org/springframework/web/reactive/resource/ResourceResolver.html",target:"_blank",rel:"noopener noreferrer"}},[a("code",[e._v("ResourceResolver")]),a("OutboundLink")],1),e._v(" implementations and"),a("a",{attrs:{href:"https://docs.spring.io/spring-framework/docs/5.3.16/javadoc-api/org/springframework/web/reactive/resource/ResourceTransformer.html",target:"_blank",rel:"noopener noreferrer"}},[a("code",[e._v("ResourceTransformer")]),a("OutboundLink")],1),e._v(" implementations,\nwhich can be used to create a toolchain for working with optimized resources.")]),e._v(" "),a("p",[e._v("You can use the "),a("code",[e._v("VersionResourceResolver")]),e._v(" for versioned resource URLs based on an MD5 hash\ncomputed from the content, a fixed application version, or other information. A"),a("code",[e._v("ContentVersionStrategy")]),e._v(" (MD5 hash) is a good choice with some notable exceptions (such as\nJavaScript resources used with a module loader).")]),e._v(" "),a("p",[e._v("The following example shows how to use "),a("code",[e._v("VersionResourceResolver")]),e._v(" in your Java configuration:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('@Configuration\n@EnableWebFlux\npublic class WebConfig implements WebFluxConfigurer {\n\n    @Override\n    public void addResourceHandlers(ResourceHandlerRegistry registry) {\n        registry.addResourceHandler("/resources/**")\n                .addResourceLocations("/public/")\n                .resourceChain(true)\n                .addResolver(new VersionResourceResolver().addContentVersionStrategy("/**"));\n    }\n\n}\n')])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('@Configuration\n@EnableWebFlux\nclass WebConfig : WebFluxConfigurer {\n\n    override fun addResourceHandlers(registry: ResourceHandlerRegistry) {\n        registry.addResourceHandler("/resources/**")\n                .addResourceLocations("/public/")\n                .resourceChain(true)\n                .addResolver(VersionResourceResolver().addContentVersionStrategy("/**"))\n    }\n\n}\n')])])]),a("p",[e._v("You can use "),a("code",[e._v("ResourceUrlProvider")]),e._v(" to rewrite URLs and apply the full chain of resolvers and\ntransformers (for example, to insert versions). The WebFlux configuration provides a "),a("code",[e._v("ResourceUrlProvider")]),e._v("so that it can be injected into others.")]),e._v(" "),a("p",[e._v("Unlike Spring MVC, at present, in WebFlux, there is no way to transparently rewrite static\nresource URLs, since there are no view technologies that can make use of a non-blocking chain\nof resolvers and transformers. When serving only local resources, the workaround is to use"),a("code",[e._v("ResourceUrlProvider")]),e._v(" directly (for example, through a custom element) and block.")]),e._v(" "),a("p",[e._v("Note that, when using both "),a("code",[e._v("EncodedResourceResolver")]),e._v(" (for example, Gzip, Brotli encoded) and"),a("code",[e._v("VersionedResourceResolver")]),e._v(", they must be registered in that order, to ensure content-based\nversions are always computed reliably based on the unencoded file.")]),e._v(" "),a("p",[a("a",{attrs:{href:"https://www.webjars.org/documentation",target:"_blank",rel:"noopener noreferrer"}},[e._v("WebJars"),a("OutboundLink")],1),e._v(" are also supported through the"),a("code",[e._v("WebJarsResourceResolver")]),e._v(" which is automatically registered when the"),a("code",[e._v("org.webjars:webjars-locator-core")]),e._v(" library is present on the classpath. The resolver can\nre-write URLs to include the version of the jar and can also match against incoming URLs\nwithout versions — for example, from "),a("code",[e._v("/jquery/jquery.min.js")]),e._v(" to"),a("code",[e._v("/jquery/1.2.0/jquery.min.js")]),e._v(".")]),e._v(" "),a("table",[a("thead",[a("tr",[a("th"),e._v(" "),a("th",[e._v("The Java configuration based on "),a("code",[e._v("ResourceHandlerRegistry")]),e._v(" provides further options"),a("br"),e._v("for fine-grained control, e.g. last-modified behavior and optimized resource resolution.")])])]),e._v(" "),a("tbody")]),e._v(" "),a("h4",{attrs:{id:"_1-11-9-path-matching"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_1-11-9-path-matching"}},[e._v("#")]),e._v(" 1.11.9. Path Matching")]),e._v(" "),a("p",[a("RouterLink",{attrs:{to:"/en/spring-framework/web.html#mvc-config-path-matching"}},[e._v("Web MVC")])],1),e._v(" "),a("p",[e._v("You can customize options related to path matching. For details on the individual options, see the"),a("a",{attrs:{href:"https://docs.spring.io/spring-framework/docs/5.3.16/javadoc-api/org/springframework/web/reactive/config/PathMatchConfigurer.html",target:"_blank",rel:"noopener noreferrer"}},[a("code",[e._v("PathMatchConfigurer")]),a("OutboundLink")],1),e._v(" javadoc.\nThe following example shows how to use "),a("code",[e._v("PathMatchConfigurer")]),e._v(":")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('@Configuration\n@EnableWebFlux\npublic class WebConfig implements WebFluxConfigurer {\n\n    @Override\n    public void configurePathMatch(PathMatchConfigurer configurer) {\n        configurer\n            .setUseCaseSensitiveMatch(true)\n            .setUseTrailingSlashMatch(false)\n            .addPathPrefix("/api",\n                    HandlerTypePredicate.forAnnotation(RestController.class));\n    }\n}\n')])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('@Configuration\n@EnableWebFlux\nclass WebConfig : WebFluxConfigurer {\n\n    @Override\n    fun configurePathMatch(configurer: PathMatchConfigurer) {\n        configurer\n            .setUseCaseSensitiveMatch(true)\n            .setUseTrailingSlashMatch(false)\n            .addPathPrefix("/api",\n                    HandlerTypePredicate.forAnnotation(RestController::class.java))\n    }\n}\n')])])]),a("table",[a("thead",[a("tr",[a("th"),e._v(" "),a("th",[e._v("Spring WebFlux relies on a parsed representation of the request path called"),a("code",[e._v("RequestPath")]),e._v(" for access to decoded path segment values, with semicolon content removed"),a("br"),e._v("(that is, path or matrix variables). That means, unlike in Spring MVC, you need not indicate"),a("br"),e._v("whether to decode the request path nor whether to remove semicolon content for"),a("br"),e._v("path matching purposes."),a("br"),a("br"),e._v("Spring WebFlux also does not support suffix pattern matching, unlike in Spring MVC, where we"),a("br"),e._v("are also "),a("RouterLink",{attrs:{to:"/en/spring-framework/web.html#mvc-ann-requestmapping-suffix-pattern-match"}},[e._v("recommend")]),e._v(" moving away from"),a("br"),e._v("reliance on it.")],1)])]),e._v(" "),a("tbody")]),e._v(" "),a("h4",{attrs:{id:"_1-11-10-websocketservice"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_1-11-10-websocketservice"}},[e._v("#")]),e._v(" 1.11.10. WebSocketService")]),e._v(" "),a("p",[e._v("The WebFlux Java config declares of a "),a("code",[e._v("WebSocketHandlerAdapter")]),e._v(" bean which provides\nsupport for the invocation of WebSocket handlers. That means all that remains to do in\norder to handle a WebSocket handshake request is to map a "),a("code",[e._v("WebSocketHandler")]),e._v(" to a URL\nvia "),a("code",[e._v("SimpleUrlHandlerMapping")]),e._v(".")]),e._v(" "),a("p",[e._v("In some cases it may be necessary to create the "),a("code",[e._v("WebSocketHandlerAdapter")]),e._v(" bean with a\nprovided "),a("code",[e._v("WebSocketService")]),e._v(" service which allows configuring WebSocket server properties.\nFor example:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("@Configuration\n@EnableWebFlux\npublic class WebConfig implements WebFluxConfigurer {\n\n    @Override\n    public WebSocketService getWebSocketService() {\n        TomcatRequestUpgradeStrategy strategy = new TomcatRequestUpgradeStrategy();\n        strategy.setMaxSessionIdleTimeout(0L);\n        return new HandshakeWebSocketService(strategy);\n    }\n}\n")])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("@Configuration\n@EnableWebFlux\nclass WebConfig : WebFluxConfigurer {\n\n    @Override\n    fun webSocketService(): WebSocketService {\n        val strategy = TomcatRequestUpgradeStrategy().apply {\n            setMaxSessionIdleTimeout(0L)\n        }\n        return HandshakeWebSocketService(strategy)\n    }\n}\n")])])]),a("h4",{attrs:{id:"_1-11-11-advanced-configuration-mode"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_1-11-11-advanced-configuration-mode"}},[e._v("#")]),e._v(" 1.11.11. Advanced Configuration Mode")]),e._v(" "),a("p",[a("RouterLink",{attrs:{to:"/en/spring-framework/web.html#mvc-config-advanced-java"}},[e._v("Web MVC")])],1),e._v(" "),a("p",[a("code",[e._v("@EnableWebFlux")]),e._v(" imports "),a("code",[e._v("DelegatingWebFluxConfiguration")]),e._v(" that:")]),e._v(" "),a("ul",[a("li",[a("p",[e._v("Provides default Spring configuration for WebFlux applications")])]),e._v(" "),a("li",[a("p",[e._v("detects and delegates to "),a("code",[e._v("WebFluxConfigurer")]),e._v(" implementations to customize that configuration.")])])]),e._v(" "),a("p",[e._v("For advanced mode, you can remove "),a("code",[e._v("@EnableWebFlux")]),e._v(" and extend directly from"),a("code",[e._v("DelegatingWebFluxConfiguration")]),e._v(" instead of implementing "),a("code",[e._v("WebFluxConfigurer")]),e._v(",\nas the following example shows:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("@Configuration\npublic class WebConfig extends DelegatingWebFluxConfiguration {\n\n    // ...\n}\n")])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("@Configuration\nclass WebConfig : DelegatingWebFluxConfiguration {\n\n    // ...\n}\n")])])]),a("p",[e._v("You can keep existing methods in "),a("code",[e._v("WebConfig")]),e._v(", but you can now also override bean declarations\nfrom the base class and still have any number of other "),a("code",[e._v("WebMvcConfigurer")]),e._v(" implementations on\nthe classpath.")]),e._v(" "),a("h3",{attrs:{id:"_1-12-http-2"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_1-12-http-2"}},[e._v("#")]),e._v(" 1.12. HTTP/2")]),e._v(" "),a("p",[a("RouterLink",{attrs:{to:"/en/spring-framework/web.html#mvc-http2"}},[e._v("Web MVC")])],1),e._v(" "),a("p",[e._v("HTTP/2 is supported with Reactor Netty, Tomcat, Jetty, and Undertow. However, there are\nconsiderations related to server configuration. For more details, see the"),a("a",{attrs:{href:"https://github.com/spring-projects/spring-framework/wiki/HTTP-2-support",target:"_blank",rel:"noopener noreferrer"}},[e._v("HTTP/2 wiki page"),a("OutboundLink")],1),e._v(".")]),e._v(" "),a("h2",{attrs:{id:"_2-webclient"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_2-webclient"}},[e._v("#")]),e._v(" 2. WebClient")]),e._v(" "),a("p",[e._v("Spring WebFlux includes a client to perform HTTP requests with. "),a("code",[e._v("WebClient")]),e._v(" has a\nfunctional, fluent API based on Reactor, see "),a("a",{attrs:{href:"#webflux-reactive-libraries"}},[e._v("Reactive Libraries")]),e._v(",\nwhich enables declarative composition of asynchronous logic without the need to deal with\nthreads or concurrency. It is fully non-blocking, it supports streaming, and relies on\nthe same "),a("a",{attrs:{href:"#webflux-codecs"}},[e._v("codecs")]),e._v(" that are also used to encode and\ndecode request and response content on the server side.")]),e._v(" "),a("p",[a("code",[e._v("WebClient")]),e._v(" needs an HTTP client library to perform requests with. There is built-in\nsupport for the following:")]),e._v(" "),a("ul",[a("li",[a("p",[a("a",{attrs:{href:"https://github.com/reactor/reactor-netty",target:"_blank",rel:"noopener noreferrer"}},[e._v("Reactor Netty"),a("OutboundLink")],1)])]),e._v(" "),a("li",[a("p",[a("a",{attrs:{href:"https://github.com/jetty-project/jetty-reactive-httpclient",target:"_blank",rel:"noopener noreferrer"}},[e._v("Jetty Reactive HttpClient"),a("OutboundLink")],1)])]),e._v(" "),a("li",[a("p",[a("a",{attrs:{href:"https://hc.apache.org/index.html",target:"_blank",rel:"noopener noreferrer"}},[e._v("Apache HttpComponents"),a("OutboundLink")],1)])]),e._v(" "),a("li",[a("p",[e._v("Others can be plugged via "),a("code",[e._v("ClientHttpConnector")]),e._v(".")])])]),e._v(" "),a("h3",{attrs:{id:"_2-1-configuration"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_2-1-configuration"}},[e._v("#")]),e._v(" 2.1. Configuration")]),e._v(" "),a("p",[e._v("The simplest way to create a "),a("code",[e._v("WebClient")]),e._v(" is through one of the static factory methods:")]),e._v(" "),a("ul",[a("li",[a("p",[a("code",[e._v("WebClient.create()")])])]),e._v(" "),a("li",[a("p",[a("code",[e._v("WebClient.create(String baseUrl)")])])])]),e._v(" "),a("p",[e._v("You can also use "),a("code",[e._v("WebClient.builder()")]),e._v(" with further options:")]),e._v(" "),a("ul",[a("li",[a("p",[a("code",[e._v("uriBuilderFactory")]),e._v(": Customized "),a("code",[e._v("UriBuilderFactory")]),e._v(" to use as a base URL.")])]),e._v(" "),a("li",[a("p",[a("code",[e._v("defaultUriVariables")]),e._v(": default values to use when expanding URI templates.")])]),e._v(" "),a("li",[a("p",[a("code",[e._v("defaultHeader")]),e._v(": Headers for every request.")])]),e._v(" "),a("li",[a("p",[a("code",[e._v("defaultCookie")]),e._v(": Cookies for every request.")])]),e._v(" "),a("li",[a("p",[a("code",[e._v("defaultRequest")]),e._v(": "),a("code",[e._v("Consumer")]),e._v(" to customize every request.")])]),e._v(" "),a("li",[a("p",[a("code",[e._v("filter")]),e._v(": Client filter for every request.")])]),e._v(" "),a("li",[a("p",[a("code",[e._v("exchangeStrategies")]),e._v(": HTTP message reader/writer customizations.")])]),e._v(" "),a("li",[a("p",[a("code",[e._v("clientConnector")]),e._v(": HTTP client library settings.")])])]),e._v(" "),a("p",[e._v("For example:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("WebClient client = WebClient.builder()\n        .codecs(configurer -> ... )\n        .build();\n")])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("val webClient = WebClient.builder()\n        .codecs { configurer -> ... }\n        .build()\n")])])]),a("p",[e._v("Once built, a "),a("code",[e._v("WebClient")]),e._v(" is immutable. However, you can clone it and build a\nmodified copy as follows:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("WebClient client1 = WebClient.builder()\n        .filter(filterA).filter(filterB).build();\n\nWebClient client2 = client1.mutate()\n        .filter(filterC).filter(filterD).build();\n\n// client1 has filterA, filterB\n\n// client2 has filterA, filterB, filterC, filterD\n")])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("val client1 = WebClient.builder()\n        .filter(filterA).filter(filterB).build()\n\nval client2 = client1.mutate()\n        .filter(filterC).filter(filterD).build()\n\n// client1 has filterA, filterB\n\n// client2 has filterA, filterB, filterC, filterD\n")])])]),a("h4",{attrs:{id:"_2-1-1-maxinmemorysize"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_2-1-1-maxinmemorysize"}},[e._v("#")]),e._v(" 2.1.1. MaxInMemorySize")]),e._v(" "),a("p",[e._v("Codecs have "),a("a",{attrs:{href:"#webflux-codecs-limits"}},[e._v("limits")]),e._v(" for buffering data in\nmemory to avoid application memory issues. By default those are set to 256KB.\nIf that’s not enough you’ll get the following error:")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("org.springframework.core.io.buffer.DataBufferLimitException: Exceeded limit on max bytes to buffer\n")])])]),a("p",[e._v("To change the limit for default codecs, use the following:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("WebClient webClient = WebClient.builder()\n        .codecs(configurer -> configurer.defaultCodecs().maxInMemorySize(2 * 1024 * 1024))\n        .build();\n")])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("val webClient = WebClient.builder()\n        .codecs { configurer -> configurer.defaultCodecs().maxInMemorySize(2 * 1024 * 1024) }\n        .build()\n")])])]),a("h4",{attrs:{id:"_2-1-2-reactor-netty"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_2-1-2-reactor-netty"}},[e._v("#")]),e._v(" 2.1.2. Reactor Netty")]),e._v(" "),a("p",[e._v("To customize Reactor Netty settings, provide a pre-configured "),a("code",[e._v("HttpClient")]),e._v(":")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("HttpClient httpClient = HttpClient.create().secure(sslSpec -> ...);\n\nWebClient webClient = WebClient.builder()\n        .clientConnector(new ReactorClientHttpConnector(httpClient))\n        .build();\n")])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("val httpClient = HttpClient.create().secure { ... }\n\nval webClient = WebClient.builder()\n    .clientConnector(ReactorClientHttpConnector(httpClient))\n    .build()\n")])])]),a("h5",{attrs:{id:"resources"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#resources"}},[e._v("#")]),e._v(" Resources")]),e._v(" "),a("p",[e._v("By default, "),a("code",[e._v("HttpClient")]),e._v(" participates in the global Reactor Netty resources held in"),a("code",[e._v("reactor.netty.http.HttpResources")]),e._v(", including event loop threads and a connection pool.\nThis is the recommended mode, since fixed, shared resources are preferred for event loop\nconcurrency. In this mode global resources remain active until the process exits.")]),e._v(" "),a("p",[e._v("If the server is timed with the process, there is typically no need for an explicit\nshutdown. However, if the server can start or stop in-process (for example, a Spring MVC\napplication deployed as a WAR), you can declare a Spring-managed bean of type"),a("code",[e._v("ReactorResourceFactory")]),e._v(" with "),a("code",[e._v("globalResources=true")]),e._v(" (the default) to ensure that the Reactor\nNetty global resources are shut down when the Spring "),a("code",[e._v("ApplicationContext")]),e._v(" is closed,\nas the following example shows:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("@Bean\npublic ReactorResourceFactory reactorResourceFactory() {\n    return new ReactorResourceFactory();\n}\n")])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("@Bean\nfun reactorResourceFactory() = ReactorResourceFactory()\n")])])]),a("p",[e._v("You can also choose not to participate in the global Reactor Netty resources. However,\nin this mode, the burden is on you to ensure that all Reactor Netty client and server\ninstances use shared resources, as the following example shows:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("@Bean\npublic ReactorResourceFactory resourceFactory() {\n    ReactorResourceFactory factory = new ReactorResourceFactory();\n    factory.setUseGlobalResources(false); (1)\n    return factory;\n}\n\n@Bean\npublic WebClient webClient() {\n\n    Function<HttpClient, HttpClient> mapper = client -> {\n        // Further customizations...\n    };\n\n    ClientHttpConnector connector =\n            new ReactorClientHttpConnector(resourceFactory(), mapper); (2)\n\n    return WebClient.builder().clientConnector(connector).build(); (3)\n}\n")])])]),a("table",[a("thead",[a("tr",[a("th",[a("strong",[e._v("1")])]),e._v(" "),a("th",[e._v("Create resources independent of global ones.")])])]),e._v(" "),a("tbody",[a("tr",[a("td",[a("strong",[e._v("2")])]),e._v(" "),a("td",[e._v("Use the "),a("code",[e._v("ReactorClientHttpConnector")]),e._v(" constructor with resource factory.")])]),e._v(" "),a("tr",[a("td",[a("strong",[e._v("3")])]),e._v(" "),a("td",[e._v("Plug the connector into the "),a("code",[e._v("WebClient.Builder")]),e._v(".")])])])]),e._v(" "),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("@Bean\nfun resourceFactory() = ReactorResourceFactory().apply {\n    isUseGlobalResources = false (1)\n}\n\n@Bean\nfun webClient(): WebClient {\n\n    val mapper: (HttpClient) -> HttpClient = {\n        // Further customizations...\n    }\n\n    val connector = ReactorClientHttpConnector(resourceFactory(), mapper) (2)\n\n    return WebClient.builder().clientConnector(connector).build() (3)\n}\n")])])]),a("table",[a("thead",[a("tr",[a("th",[a("strong",[e._v("1")])]),e._v(" "),a("th",[e._v("Create resources independent of global ones.")])])]),e._v(" "),a("tbody",[a("tr",[a("td",[a("strong",[e._v("2")])]),e._v(" "),a("td",[e._v("Use the "),a("code",[e._v("ReactorClientHttpConnector")]),e._v(" constructor with resource factory.")])]),e._v(" "),a("tr",[a("td",[a("strong",[e._v("3")])]),e._v(" "),a("td",[e._v("Plug the connector into the "),a("code",[e._v("WebClient.Builder")]),e._v(".")])])])]),e._v(" "),a("h5",{attrs:{id:"timeouts"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#timeouts"}},[e._v("#")]),e._v(" Timeouts")]),e._v(" "),a("p",[e._v("To configure a connection timeout:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("import io.netty.channel.ChannelOption;\n\nHttpClient httpClient = HttpClient.create()\n        .option(ChannelOption.CONNECT_TIMEOUT_MILLIS, 10000);\n\nWebClient webClient = WebClient.builder()\n        .clientConnector(new ReactorClientHttpConnector(httpClient))\n        .build();\n")])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("import io.netty.channel.ChannelOption\n\nval httpClient = HttpClient.create()\n        .option(ChannelOption.CONNECT_TIMEOUT_MILLIS, 10000);\n\nval webClient = WebClient.builder()\n        .clientConnector(new ReactorClientHttpConnector(httpClient))\n        .build();\n")])])]),a("p",[e._v("To configure a read or write timeout:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("import io.netty.handler.timeout.ReadTimeoutHandler;\nimport io.netty.handler.timeout.WriteTimeoutHandler;\n\nHttpClient httpClient = HttpClient.create()\n        .doOnConnected(conn -> conn\n                .addHandlerLast(new ReadTimeoutHandler(10))\n                .addHandlerLast(new WriteTimeoutHandler(10)));\n\n// Create WebClient...\n")])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("import io.netty.handler.timeout.ReadTimeoutHandler\nimport io.netty.handler.timeout.WriteTimeoutHandler\n\nval httpClient = HttpClient.create()\n        .doOnConnected { conn -> conn\n                .addHandlerLast(new ReadTimeoutHandler(10))\n                .addHandlerLast(new WriteTimeoutHandler(10))\n        }\n\n// Create WebClient...\n")])])]),a("p",[e._v("To configure a response timeout for all requests:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("HttpClient httpClient = HttpClient.create()\n        .responseTimeout(Duration.ofSeconds(2));\n\n// Create WebClient...\n")])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("val httpClient = HttpClient.create()\n        .responseTimeout(Duration.ofSeconds(2));\n\n// Create WebClient...\n")])])]),a("p",[e._v("To configure a response timeout for a specific request:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('WebClient.create().get()\n        .uri("https://example.org/path")\n        .httpRequest(httpRequest -> {\n            HttpClientRequest reactorRequest = httpRequest.getNativeRequest();\n            reactorRequest.responseTimeout(Duration.ofSeconds(2));\n        })\n        .retrieve()\n        .bodyToMono(String.class);\n')])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('WebClient.create().get()\n        .uri("https://example.org/path")\n        .httpRequest { httpRequest: ClientHttpRequest ->\n            val reactorRequest = httpRequest.getNativeRequest<HttpClientRequest>()\n            reactorRequest.responseTimeout(Duration.ofSeconds(2))\n        }\n        .retrieve()\n        .bodyToMono(String::class.java)\n')])])]),a("h4",{attrs:{id:"_2-1-3-jetty"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_2-1-3-jetty"}},[e._v("#")]),e._v(" 2.1.3. Jetty")]),e._v(" "),a("p",[e._v("The following example shows how to customize Jetty "),a("code",[e._v("HttpClient")]),e._v(" settings:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("HttpClient httpClient = new HttpClient();\nhttpClient.setCookieStore(...);\n\nWebClient webClient = WebClient.builder()\n        .clientConnector(new JettyClientHttpConnector(httpClient))\n        .build();\n")])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("val httpClient = HttpClient()\nhttpClient.cookieStore = ...\n\nval webClient = WebClient.builder()\n        .clientConnector(new JettyClientHttpConnector(httpClient))\n        .build();\n")])])]),a("p",[e._v("By default, "),a("code",[e._v("HttpClient")]),e._v(" creates its own resources ("),a("code",[e._v("Executor")]),e._v(", "),a("code",[e._v("ByteBufferPool")]),e._v(", "),a("code",[e._v("Scheduler")]),e._v("),\nwhich remain active until the process exits or "),a("code",[e._v("stop()")]),e._v(" is called.")]),e._v(" "),a("p",[e._v("You can share resources between multiple instances of the Jetty client (and server) and\nensure that the resources are shut down when the Spring "),a("code",[e._v("ApplicationContext")]),e._v(" is closed by\ndeclaring a Spring-managed bean of type "),a("code",[e._v("JettyResourceFactory")]),e._v(", as the following example\nshows:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("@Bean\npublic JettyResourceFactory resourceFactory() {\n    return new JettyResourceFactory();\n}\n\n@Bean\npublic WebClient webClient() {\n\n    HttpClient httpClient = new HttpClient();\n    // Further customizations...\n\n    ClientHttpConnector connector =\n            new JettyClientHttpConnector(httpClient, resourceFactory()); (1)\n\n    return WebClient.builder().clientConnector(connector).build(); (2)\n}\n")])])]),a("table",[a("thead",[a("tr",[a("th",[a("strong",[e._v("1")])]),e._v(" "),a("th",[e._v("Use the "),a("code",[e._v("JettyClientHttpConnector")]),e._v(" constructor with resource factory.")])])]),e._v(" "),a("tbody",[a("tr",[a("td",[a("strong",[e._v("2")])]),e._v(" "),a("td",[e._v("Plug the connector into the "),a("code",[e._v("WebClient.Builder")]),e._v(".")])])])]),e._v(" "),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("@Bean\nfun resourceFactory() = JettyResourceFactory()\n\n@Bean\nfun webClient(): WebClient {\n\n    val httpClient = HttpClient()\n    // Further customizations...\n\n    val connector = JettyClientHttpConnector(httpClient, resourceFactory()) (1)\n\n    return WebClient.builder().clientConnector(connector).build() (2)\n}\n")])])]),a("table",[a("thead",[a("tr",[a("th",[a("strong",[e._v("1")])]),e._v(" "),a("th",[e._v("Use the "),a("code",[e._v("JettyClientHttpConnector")]),e._v(" constructor with resource factory.")])])]),e._v(" "),a("tbody",[a("tr",[a("td",[a("strong",[e._v("2")])]),e._v(" "),a("td",[e._v("Plug the connector into the "),a("code",[e._v("WebClient.Builder")]),e._v(".")])])])]),e._v(" "),a("h4",{attrs:{id:"_2-1-4-httpcomponents"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_2-1-4-httpcomponents"}},[e._v("#")]),e._v(" 2.1.4. HttpComponents")]),e._v(" "),a("p",[e._v("The following example shows how to customize Apache HttpComponents "),a("code",[e._v("HttpClient")]),e._v(" settings:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("HttpAsyncClientBuilder clientBuilder = HttpAsyncClients.custom();\nclientBuilder.setDefaultRequestConfig(...);\nCloseableHttpAsyncClient client = clientBuilder.build();\nClientHttpConnector connector = new HttpComponentsClientHttpConnector(client);\n\nWebClient webClient = WebClient.builder().clientConnector(connector).build();\n")])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("val client = HttpAsyncClients.custom().apply {\n    setDefaultRequestConfig(...)\n}.build()\nval connector = HttpComponentsClientHttpConnector(client)\nval webClient = WebClient.builder().clientConnector(connector).build()\n")])])]),a("h3",{attrs:{id:"_2-2-retrieve"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_2-2-retrieve"}},[e._v("#")]),e._v(" 2.2. "),a("code",[e._v("retrieve()")])]),e._v(" "),a("p",[e._v("The "),a("code",[e._v("retrieve()")]),e._v(" method can be used to declare how to extract the response. For example:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('WebClient client = WebClient.create("https://example.org");\n\nMono<ResponseEntity<Person>> result = client.get()\n        .uri("/persons/{id}", id).accept(MediaType.APPLICATION_JSON)\n        .retrieve()\n        .toEntity(Person.class);\n')])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('val client = WebClient.create("https://example.org")\n\nval result = client.get()\n        .uri("/persons/{id}", id).accept(MediaType.APPLICATION_JSON)\n        .retrieve()\n        .toEntity<Person>().awaitSingle()\n')])])]),a("p",[e._v("Or to get only the body:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('WebClient client = WebClient.create("https://example.org");\n\nMono<Person> result = client.get()\n        .uri("/persons/{id}", id).accept(MediaType.APPLICATION_JSON)\n        .retrieve()\n        .bodyToMono(Person.class);\n')])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('val client = WebClient.create("https://example.org")\n\nval result = client.get()\n        .uri("/persons/{id}", id).accept(MediaType.APPLICATION_JSON)\n        .retrieve()\n        .awaitBody<Person>()\n')])])]),a("p",[e._v("To get a stream of decoded objects:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('Flux<Quote> result = client.get()\n        .uri("/quotes").accept(MediaType.TEXT_EVENT_STREAM)\n        .retrieve()\n        .bodyToFlux(Quote.class);\n')])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('val result = client.get()\n        .uri("/quotes").accept(MediaType.TEXT_EVENT_STREAM)\n        .retrieve()\n        .bodyToFlow<Quote>()\n')])])]),a("p",[e._v("By default, 4xx or 5xx responses result in an "),a("code",[e._v("WebClientResponseException")]),e._v(", including\nsub-classes for specific HTTP status codes. To customize the handling of error\nresponses, use "),a("code",[e._v("onStatus")]),e._v(" handlers as follows:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('Mono<Person> result = client.get()\n        .uri("/persons/{id}", id).accept(MediaType.APPLICATION_JSON)\n        .retrieve()\n        .onStatus(HttpStatus::is4xxClientError, response -> ...)\n        .onStatus(HttpStatus::is5xxServerError, response -> ...)\n        .bodyToMono(Person.class);\n')])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('val result = client.get()\n        .uri("/persons/{id}", id).accept(MediaType.APPLICATION_JSON)\n        .retrieve()\n        .onStatus(HttpStatus::is4xxClientError) { ... }\n        .onStatus(HttpStatus::is5xxServerError) { ... }\n        .awaitBody<Person>()\n')])])]),a("h3",{attrs:{id:"_2-3-exchange"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_2-3-exchange"}},[e._v("#")]),e._v(" 2.3. Exchange")]),e._v(" "),a("p",[e._v("The "),a("code",[e._v("exchangeToMono()")]),e._v(" and "),a("code",[e._v("exchangeToFlux()")]),e._v(" methods (or "),a("code",[e._v("awaitExchange { }")]),e._v(" and "),a("code",[e._v("exchangeToFlow { }")]),e._v(" in Kotlin)\nare useful for more advanced cases that require more control, such as to decode the response differently\ndepending on the response status:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('Mono<Person> entityMono = client.get()\n        .uri("/persons/1")\n        .accept(MediaType.APPLICATION_JSON)\n        .exchangeToMono(response -> {\n            if (response.statusCode().equals(HttpStatus.OK)) {\n                return response.bodyToMono(Person.class);\n            }\n            else {\n                // Turn to error\n                return response.createException().flatMap(Mono::error);\n            }\n        });\n')])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('val entity = client.get()\n  .uri("/persons/1")\n  .accept(MediaType.APPLICATION_JSON)\n  .awaitExchange {\n        if (response.statusCode() == HttpStatus.OK) {\n             return response.awaitBody<Person>()\n        }\n        else {\n             throw response.createExceptionAndAwait()\n        }\n  }\n')])])]),a("p",[e._v("When using the above, after the returned "),a("code",[e._v("Mono")]),e._v(" or "),a("code",[e._v("Flux")]),e._v(" completes, the response body\nis checked and if not consumed it is released to prevent memory and connection leaks.\nTherefore the response cannot be decoded further downstream. It is up to the provided\nfunction to declare how to decode the response if needed.")]),e._v(" "),a("h3",{attrs:{id:"_2-4-request-body"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_2-4-request-body"}},[e._v("#")]),e._v(" 2.4. Request Body")]),e._v(" "),a("p",[e._v("The request body can be encoded from any asynchronous type handled by "),a("code",[e._v("ReactiveAdapterRegistry")]),e._v(",\nlike "),a("code",[e._v("Mono")]),e._v(" or Kotlin Coroutines "),a("code",[e._v("Deferred")]),e._v(" as the following example shows:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('Mono<Person> personMono = ... ;\n\nMono<Void> result = client.post()\n        .uri("/persons/{id}", id)\n        .contentType(MediaType.APPLICATION_JSON)\n        .body(personMono, Person.class)\n        .retrieve()\n        .bodyToMono(Void.class);\n')])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('val personDeferred: Deferred<Person> = ...\n\nclient.post()\n        .uri("/persons/{id}", id)\n        .contentType(MediaType.APPLICATION_JSON)\n        .body<Person>(personDeferred)\n        .retrieve()\n        .awaitBody<Unit>()\n')])])]),a("p",[e._v("You can also have a stream of objects be encoded, as the following example shows:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('Flux<Person> personFlux = ... ;\n\nMono<Void> result = client.post()\n        .uri("/persons/{id}", id)\n        .contentType(MediaType.APPLICATION_STREAM_JSON)\n        .body(personFlux, Person.class)\n        .retrieve()\n        .bodyToMono(Void.class);\n')])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('val people: Flow<Person> = ...\n\nclient.post()\n        .uri("/persons/{id}", id)\n        .contentType(MediaType.APPLICATION_JSON)\n        .body(people)\n        .retrieve()\n        .awaitBody<Unit>()\n')])])]),a("p",[e._v("Alternatively, if you have the actual value, you can use the "),a("code",[e._v("bodyValue")]),e._v(" shortcut method,\nas the following example shows:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('Person person = ... ;\n\nMono<Void> result = client.post()\n        .uri("/persons/{id}", id)\n        .contentType(MediaType.APPLICATION_JSON)\n        .bodyValue(person)\n        .retrieve()\n        .bodyToMono(Void.class);\n')])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('val person: Person = ...\n\nclient.post()\n        .uri("/persons/{id}", id)\n        .contentType(MediaType.APPLICATION_JSON)\n        .bodyValue(person)\n        .retrieve()\n        .awaitBody<Unit>()\n')])])]),a("h4",{attrs:{id:"_2-4-1-form-data"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_2-4-1-form-data"}},[e._v("#")]),e._v(" 2.4.1. Form Data")]),e._v(" "),a("p",[e._v("To send form data, you can provide a "),a("code",[e._v("MultiValueMap<String, String>")]),e._v(" as the body. Note that the\ncontent is automatically set to "),a("code",[e._v("application/x-www-form-urlencoded")]),e._v(" by the"),a("code",[e._v("FormHttpMessageWriter")]),e._v(". The following example shows how to use "),a("code",[e._v("MultiValueMap<String, String>")]),e._v(":")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('MultiValueMap<String, String> formData = ... ;\n\nMono<Void> result = client.post()\n        .uri("/path", id)\n        .bodyValue(formData)\n        .retrieve()\n        .bodyToMono(Void.class);\n')])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('val formData: MultiValueMap<String, String> = ...\n\nclient.post()\n        .uri("/path", id)\n        .bodyValue(formData)\n        .retrieve()\n        .awaitBody<Unit>()\n')])])]),a("p",[e._v("You can also supply form data in-line by using "),a("code",[e._v("BodyInserters")]),e._v(", as the following example shows:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('import static org.springframework.web.reactive.function.BodyInserters.*;\n\nMono<Void> result = client.post()\n        .uri("/path", id)\n        .body(fromFormData("k1", "v1").with("k2", "v2"))\n        .retrieve()\n        .bodyToMono(Void.class);\n')])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('import org.springframework.web.reactive.function.BodyInserters.*\n\nclient.post()\n        .uri("/path", id)\n        .body(fromFormData("k1", "v1").with("k2", "v2"))\n        .retrieve()\n        .awaitBody<Unit>()\n')])])]),a("h4",{attrs:{id:"_2-4-2-multipart-data"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_2-4-2-multipart-data"}},[e._v("#")]),e._v(" 2.4.2. Multipart Data")]),e._v(" "),a("p",[e._v("To send multipart data, you need to provide a "),a("code",[e._v("MultiValueMap<String, ?>")]),e._v(" whose values are\neither "),a("code",[e._v("Object")]),e._v(" instances that represent part content or "),a("code",[e._v("HttpEntity")]),e._v(" instances that represent the content and\nheaders for a part. "),a("code",[e._v("MultipartBodyBuilder")]),e._v(" provides a convenient API to prepare a\nmultipart request. The following example shows how to create a "),a("code",[e._v("MultiValueMap<String, ?>")]),e._v(":")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('MultipartBodyBuilder builder = new MultipartBodyBuilder();\nbuilder.part("fieldPart", "fieldValue");\nbuilder.part("filePart1", new FileSystemResource("...logo.png"));\nbuilder.part("jsonPart", new Person("Jason"));\nbuilder.part("myPart", part); // Part from a server request\n\nMultiValueMap<String, HttpEntity<?>> parts = builder.build();\n')])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('val builder = MultipartBodyBuilder().apply {\n    part("fieldPart", "fieldValue")\n    part("filePart1", new FileSystemResource("...logo.png"))\n    part("jsonPart", new Person("Jason"))\n    part("myPart", part) // Part from a server request\n}\n\nval parts = builder.build()\n')])])]),a("p",[e._v("In most cases, you do not have to specify the "),a("code",[e._v("Content-Type")]),e._v(" for each part. The content\ntype is determined automatically based on the "),a("code",[e._v("HttpMessageWriter")]),e._v(" chosen to serialize it\nor, in the case of a "),a("code",[e._v("Resource")]),e._v(", based on the file extension. If necessary, you can\nexplicitly provide the "),a("code",[e._v("MediaType")]),e._v(" to use for each part through one of the overloaded\nbuilder "),a("code",[e._v("part")]),e._v(" methods.")]),e._v(" "),a("p",[e._v("Once a "),a("code",[e._v("MultiValueMap")]),e._v(" is prepared, the easiest way to pass it to the "),a("code",[e._v("WebClient")]),e._v(" is\nthrough the "),a("code",[e._v("body")]),e._v(" method, as the following example shows:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('MultipartBodyBuilder builder = ...;\n\nMono<Void> result = client.post()\n        .uri("/path", id)\n        .body(builder.build())\n        .retrieve()\n        .bodyToMono(Void.class);\n')])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('val builder: MultipartBodyBuilder = ...\n\nclient.post()\n        .uri("/path", id)\n        .body(builder.build())\n        .retrieve()\n        .awaitBody<Unit>()\n')])])]),a("p",[e._v("If the "),a("code",[e._v("MultiValueMap")]),e._v(" contains at least one non-"),a("code",[e._v("String")]),e._v(" value, which could also\nrepresent regular form data (that is, "),a("code",[e._v("application/x-www-form-urlencoded")]),e._v("), you need not\nset the "),a("code",[e._v("Content-Type")]),e._v(" to "),a("code",[e._v("multipart/form-data")]),e._v(". This is always the case when using"),a("code",[e._v("MultipartBodyBuilder")]),e._v(", which ensures an "),a("code",[e._v("HttpEntity")]),e._v(" wrapper.")]),e._v(" "),a("p",[e._v("As an alternative to "),a("code",[e._v("MultipartBodyBuilder")]),e._v(", you can also provide multipart content,\ninline-style, through the built-in "),a("code",[e._v("BodyInserters")]),e._v(", as the following example shows:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('import static org.springframework.web.reactive.function.BodyInserters.*;\n\nMono<Void> result = client.post()\n        .uri("/path", id)\n        .body(fromMultipartData("fieldPart", "value").with("filePart", resource))\n        .retrieve()\n        .bodyToMono(Void.class);\n')])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('import org.springframework.web.reactive.function.BodyInserters.*\n\nclient.post()\n        .uri("/path", id)\n        .body(fromMultipartData("fieldPart", "value").with("filePart", resource))\n        .retrieve()\n        .awaitBody<Unit>()\n')])])]),a("h3",{attrs:{id:"_2-5-filters"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_2-5-filters"}},[e._v("#")]),e._v(" 2.5. Filters")]),e._v(" "),a("p",[e._v("You can register a client filter ("),a("code",[e._v("ExchangeFilterFunction")]),e._v(") through the "),a("code",[e._v("WebClient.Builder")]),e._v("in order to intercept and modify requests, as the following example shows:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('WebClient client = WebClient.builder()\n        .filter((request, next) -> {\n\n            ClientRequest filtered = ClientRequest.from(request)\n                    .header("foo", "bar")\n                    .build();\n\n            return next.exchange(filtered);\n        })\n        .build();\n')])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('val client = WebClient.builder()\n        .filter { request, next ->\n\n            val filtered = ClientRequest.from(request)\n                    .header("foo", "bar")\n                    .build()\n\n            next.exchange(filtered)\n        }\n        .build()\n')])])]),a("p",[e._v("This can be used for cross-cutting concerns, such as authentication. The following example uses\na filter for basic authentication through a static factory method:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('import static org.springframework.web.reactive.function.client.ExchangeFilterFunctions.basicAuthentication;\n\nWebClient client = WebClient.builder()\n        .filter(basicAuthentication("user", "password"))\n        .build();\n')])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('import org.springframework.web.reactive.function.client.ExchangeFilterFunctions.basicAuthentication\n\nval client = WebClient.builder()\n        .filter(basicAuthentication("user", "password"))\n        .build()\n')])])]),a("p",[e._v("Filters can be added or removed by mutating an existing "),a("code",[e._v("WebClient")]),e._v(" instance, resulting\nin a new "),a("code",[e._v("WebClient")]),e._v(" instance that does not affect the original one. For example:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('import static org.springframework.web.reactive.function.client.ExchangeFilterFunctions.basicAuthentication;\n\nWebClient client = webClient.mutate()\n        .filters(filterList -> {\n            filterList.add(0, basicAuthentication("user", "password"));\n        })\n        .build();\n')])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('val client = webClient.mutate()\n        .filters { it.add(0, basicAuthentication("user", "password")) }\n        .build()\n')])])]),a("p",[a("code",[e._v("WebClient")]),e._v(" is a thin facade around the chain of filters followed by an"),a("code",[e._v("ExchangeFunction")]),e._v(". It provides a workflow to make requests, to encode to and from higher\nlevel objects, and it helps to ensure that response content is always consumed.\nWhen filters handle the response in some way, extra care must be taken to always consume\nits content or to otherwise propagate it downstream to the "),a("code",[e._v("WebClient")]),e._v(" which will ensure\nthe same. Below is a filter that handles the "),a("code",[e._v("UNAUTHORIZED")]),e._v(" status code but ensures that\nany response content, whether expected or not, is released:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("public ExchangeFilterFunction renewTokenFilter() {\n    return (request, next) -> next.exchange(request).flatMap(response -> {\n        if (response.statusCode().value() == HttpStatus.UNAUTHORIZED.value()) {\n            return response.releaseBody()\n                    .then(renewToken())\n                    .flatMap(token -> {\n                        ClientRequest newRequest = ClientRequest.from(request).build();\n                        return next.exchange(newRequest);\n                    });\n        } else {\n            return Mono.just(response);\n        }\n    });\n}\n")])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("fun renewTokenFilter(): ExchangeFilterFunction? {\n    return ExchangeFilterFunction { request: ClientRequest?, next: ExchangeFunction ->\n        next.exchange(request!!).flatMap { response: ClientResponse ->\n            if (response.statusCode().value() == HttpStatus.UNAUTHORIZED.value()) {\n                [email protected] response.releaseBody()\n                        .then(renewToken())\n                        .flatMap { token: String? ->\n                            val newRequest = ClientRequest.from(request).build()\n                            next.exchange(newRequest)\n                        }\n            } else {\n                [email protected] Mono.just(response)\n            }\n        }\n    }\n}\n")])])]),a("h3",{attrs:{id:"_2-6-attributes"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_2-6-attributes"}},[e._v("#")]),e._v(" 2.6. Attributes")]),e._v(" "),a("p",[e._v("You can add attributes to a request. This is convenient if you want to pass information\nthrough the filter chain and influence the behavior of filters for a given request.\nFor example:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('WebClient client = WebClient.builder()\n        .filter((request, next) -> {\n            Optional<Object> usr = request.attribute("myAttribute");\n            // ...\n        })\n        .build();\n\nclient.get().uri("https://example.org/")\n        .attribute("myAttribute", "...")\n        .retrieve()\n        .bodyToMono(Void.class);\n\n    }\n')])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('val client = WebClient.builder()\n        .filter { request, _ ->\n            val usr = request.attributes()["myAttribute"];\n            // ...\n        }\n        .build()\n\n    client.get().uri("https://example.org/")\n            .attribute("myAttribute", "...")\n            .retrieve()\n            .awaitBody<Unit>()\n')])])]),a("p",[e._v("Note that you can configure a "),a("code",[e._v("defaultRequest")]),e._v(" callback globally at the"),a("code",[e._v("WebClient.Builder")]),e._v(" level which lets you insert attributes into all requests,\nwhich could be used for example in a Spring MVC application to populate\nrequest attributes based on "),a("code",[e._v("ThreadLocal")]),e._v(" data.")]),e._v(" "),a("h3",{attrs:{id:"_2-7-context"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_2-7-context"}},[e._v("#")]),e._v(" 2.7. Context")]),e._v(" "),a("p",[a("a",{attrs:{href:"#webflux-client-attributes"}},[e._v("Attributes")]),e._v(" provide a convenient way to pass information to the filter\nchain but they only influence the current request. If you want to pass information that\npropagates to additional requests that are nested, e.g. via "),a("code",[e._v("flatMap")]),e._v(", or executed after,\ne.g. via "),a("code",[e._v("concatMap")]),e._v(", then you’ll need to use the Reactor "),a("code",[e._v("Context")]),e._v(".")]),e._v(" "),a("p",[e._v("The Reactor "),a("code",[e._v("Context")]),e._v(" needs to be populated at the end of a reactive chain in order to\napply to all operations. For example:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('WebClient client = WebClient.builder()\n        .filter((request, next) ->\n                Mono.deferContextual(contextView -> {\n                    String value = contextView.get("foo");\n                    // ...\n                }))\n        .build();\n\nclient.get().uri("https://example.org/")\n        .retrieve()\n        .bodyToMono(String.class)\n        .flatMap(body -> {\n                // perform nested request (context propagates automatically)...\n        })\n        .contextWrite(context -> context.put("foo", ...));\n')])])]),a("h3",{attrs:{id:"_2-8-synchronous-use"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_2-8-synchronous-use"}},[e._v("#")]),e._v(" 2.8. Synchronous Use")]),e._v(" "),a("p",[a("code",[e._v("WebClient")]),e._v(" can be used in synchronous style by blocking at the end for the result:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('Person person = client.get().uri("/person/{id}", i).retrieve()\n    .bodyToMono(Person.class)\n    .block();\n\nList<Person> persons = client.get().uri("/persons").retrieve()\n    .bodyToFlux(Person.class)\n    .collectList()\n    .block();\n')])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('val person = runBlocking {\n    client.get().uri("/person/{id}", i).retrieve()\n            .awaitBody<Person>()\n}\n\nval persons = runBlocking {\n    client.get().uri("/persons").retrieve()\n            .bodyToFlow<Person>()\n            .toList()\n}\n')])])]),a("p",[e._v("However if multiple calls need to be made, it’s more efficient to avoid blocking on each\nresponse individually, and instead wait for the combined result:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('Mono<Person> personMono = client.get().uri("/person/{id}", personId)\n        .retrieve().bodyToMono(Person.class);\n\nMono<List<Hobby>> hobbiesMono = client.get().uri("/person/{id}/hobbies", personId)\n        .retrieve().bodyToFlux(Hobby.class).collectList();\n\nMap<String, Object> data = Mono.zip(personMono, hobbiesMono, (person, hobbies) -> {\n            Map<String, String> map = new LinkedHashMap<>();\n            map.put("person", person);\n            map.put("hobbies", hobbies);\n            return map;\n        })\n        .block();\n')])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('val data = runBlocking {\n        val personDeferred = async {\n            client.get().uri("/person/{id}", personId)\n                    .retrieve().awaitBody<Person>()\n        }\n\n        val hobbiesDeferred = async {\n            client.get().uri("/person/{id}/hobbies", personId)\n                    .retrieve().bodyToFlow<Hobby>().toList()\n        }\n\n        mapOf("person" to personDeferred.await(), "hobbies" to hobbiesDeferred.await())\n    }\n')])])]),a("p",[e._v("The above is merely one example. There are lots of other patterns and operators for putting\ntogether a reactive pipeline that makes many remote calls, potentially some nested,\ninter-dependent, without ever blocking until the end.")]),e._v(" "),a("table",[a("thead",[a("tr",[a("th"),e._v(" "),a("th",[e._v("With "),a("code",[e._v("Flux")]),e._v(" or "),a("code",[e._v("Mono")]),e._v(", you should never have to block in a Spring MVC or Spring WebFlux controller."),a("br"),e._v("Simply return the resulting reactive type from the controller method. The same principle apply to"),a("br"),e._v("Kotlin Coroutines and Spring WebFlux, just use suspending function or return "),a("code",[e._v("Flow")]),e._v(" in your"),a("br"),e._v("controller method .")])])]),e._v(" "),a("tbody")]),e._v(" "),a("h3",{attrs:{id:"_2-9-testing"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_2-9-testing"}},[e._v("#")]),e._v(" 2.9. Testing")]),e._v(" "),a("p",[e._v("To test code that uses the "),a("code",[e._v("WebClient")]),e._v(", you can use a mock web server, such as the"),a("a",{attrs:{href:"https://github.com/square/okhttp#mockwebserver",target:"_blank",rel:"noopener noreferrer"}},[e._v("OkHttp MockWebServer"),a("OutboundLink")],1),e._v(". To see an example\nof its use, check out"),a("a",{attrs:{href:"https://github.com/spring-projects/spring-framework/tree/main/spring-webflux/src/test/java/org/springframework/web/reactive/function/client/WebClientIntegrationTests.java",target:"_blank",rel:"noopener noreferrer"}},[a("code",[e._v("WebClientIntegrationTests")]),a("OutboundLink")],1),e._v("in the Spring Framework test suite or the"),a("a",{attrs:{href:"https://github.com/square/okhttp/tree/master/samples/static-server",target:"_blank",rel:"noopener noreferrer"}},[a("code",[e._v("static-server")]),a("OutboundLink")],1),e._v("sample in the OkHttp repository.")]),e._v(" "),a("h2",{attrs:{id:"_3-websockets"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_3-websockets"}},[e._v("#")]),e._v(" 3. WebSockets")]),e._v(" "),a("p",[a("RouterLink",{attrs:{to:"/en/spring-framework/web.html#websocket"}},[e._v("Same as in the Servlet stack")])],1),e._v(" "),a("p",[e._v("This part of the reference documentation covers support for reactive-stack WebSocket\nmessaging.")]),e._v(" "),a("h3",{attrs:{id:"_3-1-introduction-to-websocket"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_3-1-introduction-to-websocket"}},[e._v("#")]),e._v(" 3.1. Introduction to WebSocket")]),e._v(" "),a("p",[e._v("The WebSocket protocol, "),a("a",{attrs:{href:"https://tools.ietf.org/html/rfc6455",target:"_blank",rel:"noopener noreferrer"}},[e._v("RFC 6455"),a("OutboundLink")],1),e._v(", provides a standardized\nway to establish a full-duplex, two-way communication channel between client and server\nover a single TCP connection. It is a different TCP protocol from HTTP but is designed to\nwork over HTTP, using ports 80 and 443 and allowing re-use of existing firewall rules.")]),e._v(" "),a("p",[e._v("A WebSocket interaction begins with an HTTP request that uses the HTTP "),a("code",[e._v("Upgrade")]),e._v(" header\nto upgrade or, in this case, to switch to the WebSocket protocol. The following example\nshows such an interaction:")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("GET /spring-websocket-portfolio/portfolio HTTP/1.1\nHost: localhost:8080\nUpgrade: websocket (1)\nConnection: Upgrade (2)\nSec-WebSocket-Key: Uc9l9TMkWGbHFD2qnFHltg==\nSec-WebSocket-Protocol: v10.stomp, v11.stomp\nSec-WebSocket-Version: 13\nOrigin: http://localhost:8080\n")])])]),a("table",[a("thead",[a("tr",[a("th",[a("strong",[e._v("1")])]),e._v(" "),a("th",[e._v("The "),a("code",[e._v("Upgrade")]),e._v(" header.")])])]),e._v(" "),a("tbody",[a("tr",[a("td",[a("strong",[e._v("2")])]),e._v(" "),a("td",[e._v("Using the "),a("code",[e._v("Upgrade")]),e._v(" connection.")])])])]),e._v(" "),a("p",[e._v("Instead of the usual 200 status code, a server with WebSocket support returns output\nsimilar to the following:")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("HTTP/1.1 101 Switching Protocols (1)\nUpgrade: websocket\nConnection: Upgrade\nSec-WebSocket-Accept: 1qVdfYHU9hPOl4JYYNXF623Gzn0=\nSec-WebSocket-Protocol: v10.stomp\n")])])]),a("table",[a("thead",[a("tr",[a("th",[a("strong",[e._v("1")])]),e._v(" "),a("th",[e._v("Protocol switch")])])]),e._v(" "),a("tbody")]),e._v(" "),a("p",[e._v("After a successful handshake, the TCP socket underlying the HTTP upgrade request remains\nopen for both the client and the server to continue to send and receive messages.")]),e._v(" "),a("p",[e._v("A complete introduction of how WebSockets work is beyond the scope of this document.\nSee RFC 6455, the WebSocket chapter of HTML5, or any of the many introductions and\ntutorials on the Web.")]),e._v(" "),a("p",[e._v("Note that, if a WebSocket server is running behind a web server (e.g. nginx), you\nlikely need to configure it to pass WebSocket upgrade requests on to the WebSocket\nserver. Likewise, if the application runs in a cloud environment, check the\ninstructions of the cloud provider related to WebSocket support.")]),e._v(" "),a("h4",{attrs:{id:"_3-1-1-http-versus-websocket"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_3-1-1-http-versus-websocket"}},[e._v("#")]),e._v(" 3.1.1. HTTP Versus WebSocket")]),e._v(" "),a("p",[e._v("Even though WebSocket is designed to be HTTP-compatible and starts with an HTTP request,\nit is important to understand that the two protocols lead to very different\narchitectures and application programming models.")]),e._v(" "),a("p",[e._v("In HTTP and REST, an application is modeled as many URLs. To interact with the application,\nclients access those URLs, request-response style. Servers route requests to the\nappropriate handler based on the HTTP URL, method, and headers.")]),e._v(" "),a("p",[e._v("By contrast, in WebSockets, there is usually only one URL for the initial connect.\nSubsequently, all application messages flow on that same TCP connection. This points to\nan entirely different asynchronous, event-driven, messaging architecture.")]),e._v(" "),a("p",[e._v("WebSocket is also a low-level transport protocol, which, unlike HTTP, does not prescribe\nany semantics to the content of messages. That means that there is no way to route or process\na message unless the client and the server agree on message semantics.")]),e._v(" "),a("p",[e._v("WebSocket clients and servers can negotiate the use of a higher-level, messaging protocol\n(for example, STOMP), through the "),a("code",[e._v("Sec-WebSocket-Protocol")]),e._v(" header on the HTTP handshake request.\nIn the absence of that, they need to come up with their own conventions.")]),e._v(" "),a("h4",{attrs:{id:"_3-1-2-when-to-use-websockets"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_3-1-2-when-to-use-websockets"}},[e._v("#")]),e._v(" 3.1.2. When to Use WebSockets")]),e._v(" "),a("p",[e._v("WebSockets can make a web page be dynamic and interactive. However, in many cases,\na combination of Ajax and HTTP streaming or long polling can provide a simple and\neffective solution.")]),e._v(" "),a("p",[e._v("For example, news, mail, and social feeds need to update dynamically, but it may be\nperfectly okay to do so every few minutes. Collaboration, games, and financial apps, on\nthe other hand, need to be much closer to real-time.")]),e._v(" "),a("p",[e._v("Latency alone is not a deciding factor. If the volume of messages is relatively low (for example,\nmonitoring network failures) HTTP streaming or polling can provide an effective solution.\nIt is the combination of low latency, high frequency, and high volume that make the best\ncase for the use of WebSocket.")]),e._v(" "),a("p",[e._v("Keep in mind also that over the Internet, restrictive proxies that are outside of your control\nmay preclude WebSocket interactions, either because they are not configured to pass on the"),a("code",[e._v("Upgrade")]),e._v(" header or because they close long-lived connections that appear idle. This\nmeans that the use of WebSocket for internal applications within the firewall is a more\nstraightforward decision than it is for public facing applications.")]),e._v(" "),a("h3",{attrs:{id:"_3-2-websocket-api"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_3-2-websocket-api"}},[e._v("#")]),e._v(" 3.2. WebSocket API")]),e._v(" "),a("p",[a("RouterLink",{attrs:{to:"/en/spring-framework/web.html#websocket-server"}},[e._v("Same as in the Servlet stack")])],1),e._v(" "),a("p",[e._v("The Spring Framework provides a WebSocket API that you can use to write client- and\nserver-side applications that handle WebSocket messages.")]),e._v(" "),a("h4",{attrs:{id:"_3-2-1-server"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_3-2-1-server"}},[e._v("#")]),e._v(" 3.2.1. Server")]),e._v(" "),a("p",[a("RouterLink",{attrs:{to:"/en/spring-framework/web.html#websocket-server-handler"}},[e._v("Same as in the Servlet stack")])],1),e._v(" "),a("p",[e._v("To create a WebSocket server, you can first create a "),a("code",[e._v("WebSocketHandler")]),e._v(".\nThe following example shows how to do so:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("import org.springframework.web.reactive.socket.WebSocketHandler;\nimport org.springframework.web.reactive.socket.WebSocketSession;\n\npublic class MyWebSocketHandler implements WebSocketHandler {\n\n    @Override\n    public Mono<Void> handle(WebSocketSession session) {\n        // ...\n    }\n}\n")])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("import org.springframework.web.reactive.socket.WebSocketHandler\nimport org.springframework.web.reactive.socket.WebSocketSession\n\nclass MyWebSocketHandler : WebSocketHandler {\n\n    override fun handle(session: WebSocketSession): Mono<Void> {\n        // ...\n    }\n}\n")])])]),a("p",[e._v("Then you can map it to a URL:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('@Configuration\nclass WebConfig {\n\n    @Bean\n    public HandlerMapping handlerMapping() {\n        Map<String, WebSocketHandler> map = new HashMap<>();\n        map.put("/path", new MyWebSocketHandler());\n        int order = -1; // before annotated controllers\n\n        return new SimpleUrlHandlerMapping(map, order);\n    }\n}\n')])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('@Configuration\nclass WebConfig {\n\n    @Bean\n    fun handlerMapping(): HandlerMapping {\n        val map = mapOf("/path" to MyWebSocketHandler())\n        val order = -1 // before annotated controllers\n\n        return SimpleUrlHandlerMapping(map, order)\n    }\n}\n')])])]),a("p",[e._v("If using the "),a("a",{attrs:{href:"#webflux-config"}},[e._v("WebFlux Config")]),e._v(" there is nothing\nfurther to do, or otherwise if not using the WebFlux config you’ll need to declare a"),a("code",[e._v("WebSocketHandlerAdapter")]),e._v(" as shown below:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("@Configuration\nclass WebConfig {\n\n    // ...\n\n    @Bean\n    public WebSocketHandlerAdapter handlerAdapter() {\n        return new WebSocketHandlerAdapter();\n    }\n}\n")])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("@Configuration\nclass WebConfig {\n\n    // ...\n\n    @Bean\n    fun handlerAdapter() =  WebSocketHandlerAdapter()\n}\n")])])]),a("h4",{attrs:{id:"_3-2-2-websockethandler"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_3-2-2-websockethandler"}},[e._v("#")]),e._v(" 3.2.2. "),a("code",[e._v("WebSocketHandler")])]),e._v(" "),a("p",[e._v("The "),a("code",[e._v("handle")]),e._v(" method of "),a("code",[e._v("WebSocketHandler")]),e._v(" takes "),a("code",[e._v("WebSocketSession")]),e._v(" and returns "),a("code",[e._v("Mono<Void>")]),e._v("to indicate when application handling of the session is complete. The session is handled\nthrough two streams, one for inbound and one for outbound messages. The following table\ndescribes the two methods that handle the streams:")]),e._v(" "),a("table",[a("thead",[a("tr",[a("th",[a("code",[e._v("WebSocketSession")]),e._v(" method")]),e._v(" "),a("th",[e._v("Description")])])]),e._v(" "),a("tbody",[a("tr",[a("td",[a("code",[e._v("Flux<WebSocketMessage> receive()")])]),e._v(" "),a("td",[e._v("Provides access to the inbound message stream and completes when the connection is closed.")])]),e._v(" "),a("tr",[a("td",[a("code",[e._v("Mono<Void> send(Publisher<WebSocketMessage>)")])]),e._v(" "),a("td",[e._v("Takes a source for outgoing messages, writes the messages, and returns a "),a("code",[e._v("Mono<Void>")]),e._v(" that"),a("br"),e._v("completes when the source completes and writing is done.")])])])]),e._v(" "),a("p",[e._v("A "),a("code",[e._v("WebSocketHandler")]),e._v(" must compose the inbound and outbound streams into a unified flow and\nreturn a "),a("code",[e._v("Mono<Void>")]),e._v(" that reflects the completion of that flow. Depending on application\nrequirements, the unified flow completes when:")]),e._v(" "),a("ul",[a("li",[a("p",[e._v("Either the inbound or the outbound message stream completes.")])]),e._v(" "),a("li",[a("p",[e._v("The inbound stream completes (that is, the connection closed), while the outbound stream is infinite.")])]),e._v(" "),a("li",[a("p",[e._v("At a chosen point, through the "),a("code",[e._v("close")]),e._v(" method of "),a("code",[e._v("WebSocketSession")]),e._v(".")])])]),e._v(" "),a("p",[e._v("When inbound and outbound message streams are composed together, there is no need to\ncheck if the connection is open, since Reactive Streams signals end activity.\nThe inbound stream receives a completion or error signal, and the outbound stream\nreceives a cancellation signal.")]),e._v(" "),a("p",[e._v("The most basic implementation of a handler is one that handles the inbound stream. The\nfollowing example shows such an implementation:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("class ExampleHandler implements WebSocketHandler {\n\n    @Override\n    public Mono<Void> handle(WebSocketSession session) {\n        return session.receive()            (1)\n                .doOnNext(message -> {\n                    // ...                  (2)\n                })\n                .concatMap(message -> {\n                    // ...                  (3)\n                })\n                .then();                    (4)\n    }\n}\n")])])]),a("table",[a("thead",[a("tr",[a("th",[a("strong",[e._v("1")])]),e._v(" "),a("th",[e._v("Access the stream of inbound messages.")])])]),e._v(" "),a("tbody",[a("tr",[a("td",[a("strong",[e._v("2")])]),e._v(" "),a("td",[e._v("Do something with each message.")])]),e._v(" "),a("tr",[a("td",[a("strong",[e._v("3")])]),e._v(" "),a("td",[e._v("Perform nested asynchronous operations that use the message content.")])]),e._v(" "),a("tr",[a("td",[a("strong",[e._v("4")])]),e._v(" "),a("td",[e._v("Return a "),a("code",[e._v("Mono<Void>")]),e._v(" that completes when receiving completes.")])])])]),e._v(" "),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("class ExampleHandler : WebSocketHandler {\n\n    override fun handle(session: WebSocketSession): Mono<Void> {\n        return session.receive()            (1)\n                .doOnNext {\n                    // ...                  (2)\n                }\n                .concatMap {\n                    // ...                  (3)\n                }\n                .then()                     (4)\n    }\n}\n")])])]),a("table",[a("thead",[a("tr",[a("th",[a("strong",[e._v("1")])]),e._v(" "),a("th",[e._v("Access the stream of inbound messages.")])])]),e._v(" "),a("tbody",[a("tr",[a("td",[a("strong",[e._v("2")])]),e._v(" "),a("td",[e._v("Do something with each message.")])]),e._v(" "),a("tr",[a("td",[a("strong",[e._v("3")])]),e._v(" "),a("td",[e._v("Perform nested asynchronous operations that use the message content.")])]),e._v(" "),a("tr",[a("td",[a("strong",[e._v("4")])]),e._v(" "),a("td",[e._v("Return a "),a("code",[e._v("Mono<Void>")]),e._v(" that completes when receiving completes.")])])])]),e._v(" "),a("table",[a("thead",[a("tr",[a("th"),e._v(" "),a("th",[e._v("For nested, asynchronous operations, you may need to call "),a("code",[e._v("message.retain()")]),e._v(" on underlying"),a("br"),e._v("servers that use pooled data buffers (for example, Netty). Otherwise, the data buffer may be"),a("br"),e._v("released before you have had a chance to read the data. For more background, see"),a("RouterLink",{attrs:{to:"/en/spring-framework/core.html#databuffers"}},[e._v("Data Buffers and Codecs")]),e._v(".")],1)])]),e._v(" "),a("tbody")]),e._v(" "),a("p",[e._v("The following implementation combines the inbound and outbound streams:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('class ExampleHandler implements WebSocketHandler {\n\n    @Override\n    public Mono<Void> handle(WebSocketSession session) {\n\n        Flux<WebSocketMessage> output = session.receive()               (1)\n                .doOnNext(message -> {\n                    // ...\n                })\n                .concatMap(message -> {\n                    // ...\n                })\n                .map(value -> session.textMessage("Echo " + value));    (2)\n\n        return session.send(output);                                    (3)\n    }\n}\n')])])]),a("table",[a("thead",[a("tr",[a("th",[a("strong",[e._v("1")])]),e._v(" "),a("th",[e._v("Handle the inbound message stream.")])])]),e._v(" "),a("tbody",[a("tr",[a("td",[a("strong",[e._v("2")])]),e._v(" "),a("td",[e._v("Create the outbound message, producing a combined flow.")])]),e._v(" "),a("tr",[a("td",[a("strong",[e._v("3")])]),e._v(" "),a("td",[e._v("Return a "),a("code",[e._v("Mono<Void>")]),e._v(" that does not complete while we continue to receive.")])])])]),e._v(" "),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('class ExampleHandler : WebSocketHandler {\n\n    override fun handle(session: WebSocketSession): Mono<Void> {\n\n        val output = session.receive()                      (1)\n                .doOnNext {\n                    // ...\n                }\n                .concatMap {\n                    // ...\n                }\n                .map { session.textMessage("Echo $it") }    (2)\n\n        return session.send(output)                         (3)\n    }\n}\n')])])]),a("table",[a("thead",[a("tr",[a("th",[a("strong",[e._v("1")])]),e._v(" "),a("th",[e._v("Handle the inbound message stream.")])])]),e._v(" "),a("tbody",[a("tr",[a("td",[a("strong",[e._v("2")])]),e._v(" "),a("td",[e._v("Create the outbound message, producing a combined flow.")])]),e._v(" "),a("tr",[a("td",[a("strong",[e._v("3")])]),e._v(" "),a("td",[e._v("Return a "),a("code",[e._v("Mono<Void>")]),e._v(" that does not complete while we continue to receive.")])])])]),e._v(" "),a("p",[e._v("Inbound and outbound streams can be independent and be joined only for completion,\nas the following example shows:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("class ExampleHandler implements WebSocketHandler {\n\n    @Override\n    public Mono<Void> handle(WebSocketSession session) {\n\n        Mono<Void> input = session.receive()                                (1)\n                .doOnNext(message -> {\n                    // ...\n                })\n                .concatMap(message -> {\n                    // ...\n                })\n                .then();\n\n        Flux<String> source = ... ;\n        Mono<Void> output = session.send(source.map(session::textMessage)); (2)\n\n        return Mono.zip(input, output).then();                              (3)\n    }\n}\n")])])]),a("table",[a("thead",[a("tr",[a("th",[a("strong",[e._v("1")])]),e._v(" "),a("th",[e._v("Handle inbound message stream.")])])]),e._v(" "),a("tbody",[a("tr",[a("td",[a("strong",[e._v("2")])]),e._v(" "),a("td",[e._v("Send outgoing messages.")])]),e._v(" "),a("tr",[a("td",[a("strong",[e._v("3")])]),e._v(" "),a("td",[e._v("Join the streams and return a "),a("code",[e._v("Mono<Void>")]),e._v(" that completes when either stream ends.")])])])]),e._v(" "),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("class ExampleHandler : WebSocketHandler {\n\n    override fun handle(session: WebSocketSession): Mono<Void> {\n\n        val input = session.receive()                                   (1)\n                .doOnNext {\n                    // ...\n                }\n                .concatMap {\n                    // ...\n                }\n                .then()\n\n        val source: Flux<String> = ...\n        val output = session.send(source.map(session::textMessage))     (2)\n\n        return Mono.zip(input, output).then()                           (3)\n    }\n}\n")])])]),a("table",[a("thead",[a("tr",[a("th",[a("strong",[e._v("1")])]),e._v(" "),a("th",[e._v("Handle inbound message stream.")])])]),e._v(" "),a("tbody",[a("tr",[a("td",[a("strong",[e._v("2")])]),e._v(" "),a("td",[e._v("Send outgoing messages.")])]),e._v(" "),a("tr",[a("td",[a("strong",[e._v("3")])]),e._v(" "),a("td",[e._v("Join the streams and return a "),a("code",[e._v("Mono<Void>")]),e._v(" that completes when either stream ends.")])])])]),e._v(" "),a("h4",{attrs:{id:"_3-2-3-databuffer"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_3-2-3-databuffer"}},[e._v("#")]),e._v(" 3.2.3. "),a("code",[e._v("DataBuffer")])]),e._v(" "),a("p",[a("code",[e._v("DataBuffer")]),e._v(" is the representation for a byte buffer in WebFlux. The Spring Core part of\nthe reference has more on that in the section on"),a("RouterLink",{attrs:{to:"/en/spring-framework/core.html#databuffers"}},[e._v("Data Buffers and Codecs")]),e._v(". The key point to understand is that on some\nservers like Netty, byte buffers are pooled and reference counted, and must be released\nwhen consumed to avoid memory leaks.")],1),e._v(" "),a("p",[e._v("When running on Netty, applications must use "),a("code",[e._v("DataBufferUtils.retain(dataBuffer)")]),e._v(" if they\nwish to hold on input data buffers in order to ensure they are not released, and\nsubsequently use "),a("code",[e._v("DataBufferUtils.release(dataBuffer)")]),e._v(" when the buffers are consumed.")]),e._v(" "),a("h4",{attrs:{id:"_3-2-4-handshake"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_3-2-4-handshake"}},[e._v("#")]),e._v(" 3.2.4. Handshake")]),e._v(" "),a("p",[a("RouterLink",{attrs:{to:"/en/spring-framework/web.html#websocket-server-handshake"}},[e._v("Same as in the Servlet stack")])],1),e._v(" "),a("p",[a("code",[e._v("WebSocketHandlerAdapter")]),e._v(" delegates to a "),a("code",[e._v("WebSocketService")]),e._v(". By default, that is an instance\nof "),a("code",[e._v("HandshakeWebSocketService")]),e._v(", which performs basic checks on the WebSocket request and\nthen uses "),a("code",[e._v("RequestUpgradeStrategy")]),e._v(" for the server in use. Currently, there is built-in\nsupport for Reactor Netty, Tomcat, Jetty, and Undertow.")]),e._v(" "),a("p",[a("code",[e._v("HandshakeWebSocketService")]),e._v(" exposes a "),a("code",[e._v("sessionAttributePredicate")]),e._v(" property that allows\nsetting a "),a("code",[e._v("Predicate<String>")]),e._v(" to extract attributes from the "),a("code",[e._v("WebSession")]),e._v(" and insert them\ninto the attributes of the "),a("code",[e._v("WebSocketSession")]),e._v(".")]),e._v(" "),a("h4",{attrs:{id:"_3-2-5-server-configation"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_3-2-5-server-configation"}},[e._v("#")]),e._v(" 3.2.5. Server Configation")]),e._v(" "),a("p",[a("RouterLink",{attrs:{to:"/en/spring-framework/web.html#websocket-server-runtime-configuration"}},[e._v("Same as in the Servlet stack")])],1),e._v(" "),a("p",[e._v("The "),a("code",[e._v("RequestUpgradeStrategy")]),e._v(" for each server exposes configuration specific to the\nunderlying WebSocket server engine. When using the WebFlux Java config you can customize\nsuch properties as shown in the corresponding section of the"),a("a",{attrs:{href:"#webflux-config-websocket-service"}},[e._v("WebFlux Config")]),e._v(", or otherwise if\nnot using the WebFlux config, use the below:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("@Configuration\nclass WebConfig {\n\n    @Bean\n    public WebSocketHandlerAdapter handlerAdapter() {\n        return new WebSocketHandlerAdapter(webSocketService());\n    }\n\n    @Bean\n    public WebSocketService webSocketService() {\n        TomcatRequestUpgradeStrategy strategy = new TomcatRequestUpgradeStrategy();\n        strategy.setMaxSessionIdleTimeout(0L);\n        return new HandshakeWebSocketService(strategy);\n    }\n}\n")])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("@Configuration\nclass WebConfig {\n\n    @Bean\n    fun handlerAdapter() =\n            WebSocketHandlerAdapter(webSocketService())\n\n    @Bean\n    fun webSocketService(): WebSocketService {\n        val strategy = TomcatRequestUpgradeStrategy().apply {\n            setMaxSessionIdleTimeout(0L)\n        }\n        return HandshakeWebSocketService(strategy)\n    }\n}\n")])])]),a("p",[e._v("Check the upgrade strategy for your server to see what options are available. Currently,\nonly Tomcat and Jetty expose such options.")]),e._v(" "),a("h4",{attrs:{id:"_3-2-6-cors"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_3-2-6-cors"}},[e._v("#")]),e._v(" 3.2.6. CORS")]),e._v(" "),a("p",[a("RouterLink",{attrs:{to:"/en/spring-framework/web.html#websocket-server-allowed-origins"}},[e._v("Same as in the Servlet stack")])],1),e._v(" "),a("p",[e._v("The easiest way to configure CORS and restrict access to a WebSocket endpoint is to\nhave your "),a("code",[e._v("WebSocketHandler")]),e._v(" implement "),a("code",[e._v("CorsConfigurationSource")]),e._v(" and return a"),a("code",[e._v("CorsConfiguration")]),e._v(" with allowed origins, headers, and other details. If you cannot do\nthat, you can also set the "),a("code",[e._v("corsConfigurations")]),e._v(" property on the "),a("code",[e._v("SimpleUrlHandler")]),e._v(" to\nspecify CORS settings by URL pattern. If both are specified, they are combined by using the"),a("code",[e._v("combine")]),e._v(" method on "),a("code",[e._v("CorsConfiguration")]),e._v(".")]),e._v(" "),a("h4",{attrs:{id:"_3-2-7-client"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_3-2-7-client"}},[e._v("#")]),e._v(" 3.2.7. Client")]),e._v(" "),a("p",[e._v("Spring WebFlux provides a "),a("code",[e._v("WebSocketClient")]),e._v(" abstraction with implementations for\nReactor Netty, Tomcat, Jetty, Undertow, and standard Java (that is, JSR-356).")]),e._v(" "),a("table",[a("thead",[a("tr",[a("th"),e._v(" "),a("th",[e._v("The Tomcat client is effectively an extension of the standard Java one with some extra"),a("br"),e._v("functionality in the "),a("code",[e._v("WebSocketSession")]),e._v(" handling to take advantage of the Tomcat-specific"),a("br"),e._v("API to suspend receiving messages for back pressure.")])])]),e._v(" "),a("tbody")]),e._v(" "),a("p",[e._v("To start a WebSocket session, you can create an instance of the client and use its "),a("code",[e._v("execute")]),e._v("methods:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('WebSocketClient client = new ReactorNettyWebSocketClient();\n\nURI url = new URI("ws://localhost:8080/path");\nclient.execute(url, session ->\n        session.receive()\n                .doOnNext(System.out::println)\n                .then());\n')])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('val client = ReactorNettyWebSocketClient()\n\n        val url = URI("ws://localhost:8080/path")\n        client.execute(url) { session ->\n            session.receive()\n                    .doOnNext(::println)\n            .then()\n        }\n')])])]),a("p",[e._v("Some clients, such as Jetty, implement "),a("code",[e._v("Lifecycle")]),e._v(" and need to be stopped and started\nbefore you can use them. All clients have constructor options related to configuration\nof the underlying WebSocket client.")]),e._v(" "),a("h2",{attrs:{id:"_4-testing"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_4-testing"}},[e._v("#")]),e._v(" 4. Testing")]),e._v(" "),a("p",[a("RouterLink",{attrs:{to:"/en/spring-framework/web.html#testing"}},[e._v("Same in Spring MVC")])],1),e._v(" "),a("p",[e._v("The "),a("code",[e._v("spring-test")]),e._v(" module provides mock implementations of "),a("code",[e._v("ServerHttpRequest")]),e._v(","),a("code",[e._v("ServerHttpResponse")]),e._v(", and "),a("code",[e._v("ServerWebExchange")]),e._v(".\nSee "),a("RouterLink",{attrs:{to:"/en/spring-framework/testing.html#mock-objects-web-reactive"}},[e._v("Spring Web Reactive")]),e._v(" for a\ndiscussion of mock objects.")],1),e._v(" "),a("p",[a("RouterLink",{attrs:{to:"/en/spring-framework/testing.html#webtestclient"}},[a("code",[e._v("WebTestClient")])]),e._v(" builds on these mock request and\nresponse objects to provide support for testing WebFlux applications without an HTTP\nserver. You can use the "),a("code",[e._v("WebTestClient")]),e._v(" for end-to-end integration tests, too.")],1),e._v(" "),a("h2",{attrs:{id:"_5-rsocket"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_5-rsocket"}},[e._v("#")]),e._v(" 5. RSocket")]),e._v(" "),a("p",[e._v("This section describes Spring Framework’s support for the RSocket protocol.")]),e._v(" "),a("h3",{attrs:{id:"_5-1-overview"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_5-1-overview"}},[e._v("#")]),e._v(" 5.1. Overview")]),e._v(" "),a("p",[e._v("RSocket is an application protocol for multiplexed, duplex communication over TCP,\nWebSocket, and other byte stream transports, using one of the following interaction\nmodels:")]),e._v(" "),a("ul",[a("li",[a("p",[a("code",[e._v("Request-Response")]),e._v(" — send one message and receive one back.")])]),e._v(" "),a("li",[a("p",[a("code",[e._v("Request-Stream")]),e._v(" — send one message and receive a stream of messages back.")])]),e._v(" "),a("li",[a("p",[a("code",[e._v("Channel")]),e._v(" — send streams of messages in both directions.")])]),e._v(" "),a("li",[a("p",[a("code",[e._v("Fire-and-Forget")]),e._v(" — send a one-way message.")])])]),e._v(" "),a("p",[e._v('Once the initial connection is made, the "client" vs "server" distinction is lost as\nboth sides become symmetrical and each side can initiate one of the above interactions.\nThis is why in the protocol calls the participating sides "requester" and "responder"\nwhile the above interactions are called "request streams" or simply "requests".')]),e._v(" "),a("p",[e._v("These are the key features and benefits of the RSocket protocol:")]),e._v(" "),a("ul",[a("li",[a("p",[a("a",{attrs:{href:"https://www.reactive-streams.org/",target:"_blank",rel:"noopener noreferrer"}},[e._v("Reactive Streams"),a("OutboundLink")],1),e._v(" semantics across network boundary — for streaming requests such as "),a("code",[e._v("Request-Stream")]),e._v(" and "),a("code",[e._v("Channel")]),e._v(", back pressure signals\ntravel between requester and responder, allowing a requester to slow down a responder at\nthe source, hence reducing reliance on network layer congestion control, and the need\nfor buffering at the network level or at any level.")])]),e._v(" "),a("li",[a("p",[e._v('Request throttling — this feature is named "Leasing" after the '),a("code",[e._v("LEASE")]),e._v(" frame that\ncan be sent from each end to limit the total number of requests allowed by other end\nfor a given time. Leases are renewed periodically.")])]),e._v(" "),a("li",[a("p",[e._v("Session resumption — this is designed for loss of connectivity and requires some state\nto be maintained. The state management is transparent for applications, and works well\nin combination with back pressure which can stop a producer when possible and reduce\nthe amount of state required.")])]),e._v(" "),a("li",[a("p",[e._v("Fragmentation and re-assembly of large messages.")])]),e._v(" "),a("li",[a("p",[e._v("Keepalive (heartbeats).")])])]),e._v(" "),a("p",[e._v("RSocket has "),a("a",{attrs:{href:"https://github.com/rsocket",target:"_blank",rel:"noopener noreferrer"}},[e._v("implementations"),a("OutboundLink")],1),e._v(" in multiple languages. The"),a("a",{attrs:{href:"https://github.com/rsocket/rsocket-java",target:"_blank",rel:"noopener noreferrer"}},[e._v("Java library"),a("OutboundLink")],1),e._v(" is built on "),a("a",{attrs:{href:"https://projectreactor.io/",target:"_blank",rel:"noopener noreferrer"}},[e._v("Project Reactor"),a("OutboundLink")],1),e._v(",\nand "),a("a",{attrs:{href:"https://github.com/reactor/reactor-netty",target:"_blank",rel:"noopener noreferrer"}},[e._v("Reactor Netty"),a("OutboundLink")],1),e._v(" for the transport. That means\nsignals from Reactive Streams Publishers in your application propagate transparently\nthrough RSocket across the network.")]),e._v(" "),a("h4",{attrs:{id:"_5-1-1-the-protocol"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_5-1-1-the-protocol"}},[e._v("#")]),e._v(" 5.1.1. The Protocol")]),e._v(" "),a("p",[e._v("One of the benefits of RSocket is that it has well defined behavior on the wire and an\neasy to read "),a("a",{attrs:{href:"https://rsocket.io/docs/Protocol",target:"_blank",rel:"noopener noreferrer"}},[e._v("specification"),a("OutboundLink")],1),e._v(" along with some protocol"),a("a",{attrs:{href:"https://github.com/rsocket/rsocket/tree/master/Extensions",target:"_blank",rel:"noopener noreferrer"}},[e._v("extensions"),a("OutboundLink")],1),e._v(". Therefore it is\na good idea to read the spec, independent of language implementations and higher level\nframework APIs. This section provides a succinct overview to establish some context.")]),e._v(" "),a("p",[a("strong",[e._v("Connecting")])]),e._v(" "),a("p",[e._v("Initially a client connects to a server via some low level streaming transport such\nas TCP or WebSocket and sends a "),a("code",[e._v("SETUP")]),e._v(" frame to the server to set parameters for the\nconnection.")]),e._v(" "),a("p",[e._v("The server may reject the "),a("code",[e._v("SETUP")]),e._v(" frame, but generally after it is sent (for the client)\nand received (for the server), both sides can begin to make requests, unless "),a("code",[e._v("SETUP")]),e._v("indicates use of leasing semantics to limit the number of requests, in which case\nboth sides must wait for a "),a("code",[e._v("LEASE")]),e._v(" frame from the other end to permit making requests.")]),e._v(" "),a("p",[a("strong",[e._v("Making Requests")])]),e._v(" "),a("p",[e._v("Once a connection is established, both sides may initiate a request through one of the\nframes "),a("code",[e._v("REQUEST_RESPONSE")]),e._v(", "),a("code",[e._v("REQUEST_STREAM")]),e._v(", "),a("code",[e._v("REQUEST_CHANNEL")]),e._v(", or "),a("code",[e._v("REQUEST_FNF")]),e._v(". Each of\nthose frames carries one message from the requester to the responder.")]),e._v(" "),a("p",[e._v("The responder may then return "),a("code",[e._v("PAYLOAD")]),e._v(" frames with response messages, and in the case\nof "),a("code",[e._v("REQUEST_CHANNEL")]),e._v(" the requester may also send "),a("code",[e._v("PAYLOAD")]),e._v(" frames with more request\nmessages.")]),e._v(" "),a("p",[e._v("When a request involves a stream of messages such as "),a("code",[e._v("Request-Stream")]),e._v(" and "),a("code",[e._v("Channel")]),e._v(",\nthe responder must respect demand signals from the requester. Demand is expressed as a\nnumber of messages. Initial demand is specified in "),a("code",[e._v("REQUEST_STREAM")]),e._v(" and"),a("code",[e._v("REQUEST_CHANNEL")]),e._v(" frames. Subsequent demand is signaled via "),a("code",[e._v("REQUEST_N")]),e._v(" frames.")]),e._v(" "),a("p",[e._v("Each side may also send metadata notifications, via the "),a("code",[e._v("METADATA_PUSH")]),e._v(" frame, that do not\npertain to any individual request but rather to the connection as a whole.")]),e._v(" "),a("p",[a("strong",[e._v("Message Format")])]),e._v(" "),a("p",[e._v("RSocket messages contain data and metadata. Metadata can be used to send a route, a\nsecurity token, etc. Data and metadata can be formatted differently. Mime types for each\nare declared in the "),a("code",[e._v("SETUP")]),e._v(" frame and apply to all requests on a given connection.")]),e._v(" "),a("p",[e._v("While all messages can have metadata, typically metadata such as a route are per-request\nand therefore only included in the first message on a request, i.e. with one of the frames"),a("code",[e._v("REQUEST_RESPONSE")]),e._v(", "),a("code",[e._v("REQUEST_STREAM")]),e._v(", "),a("code",[e._v("REQUEST_CHANNEL")]),e._v(", or "),a("code",[e._v("REQUEST_FNF")]),e._v(".")]),e._v(" "),a("p",[e._v("Protocol extensions define common metadata formats for use in applications:")]),e._v(" "),a("ul",[a("li",[a("p",[a("a",{attrs:{href:"https://github.com/rsocket/rsocket/blob/master/Extensions/CompositeMetadata.md",target:"_blank",rel:"noopener noreferrer"}},[e._v("Composite Metadata"),a("OutboundLink")],1),e._v("-- multiple,\nindependently formatted metadata entries.")])]),e._v(" "),a("li",[a("p",[a("a",{attrs:{href:"https://github.com/rsocket/rsocket/blob/master/Extensions/Routing.md",target:"_blank",rel:"noopener noreferrer"}},[e._v("Routing"),a("OutboundLink")],1),e._v(" — the route for a request.")])])]),e._v(" "),a("h4",{attrs:{id:"_5-1-2-java-implementation"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_5-1-2-java-implementation"}},[e._v("#")]),e._v(" 5.1.2. Java Implementation")]),e._v(" "),a("p",[e._v("The "),a("a",{attrs:{href:"https://github.com/rsocket/rsocket-java",target:"_blank",rel:"noopener noreferrer"}},[e._v("Java implementation"),a("OutboundLink")],1),e._v(" for RSocket is built on"),a("a",{attrs:{href:"https://projectreactor.io/",target:"_blank",rel:"noopener noreferrer"}},[e._v("Project Reactor"),a("OutboundLink")],1),e._v(". The transports for TCP and WebSocket are\nbuilt on "),a("a",{attrs:{href:"https://github.com/reactor/reactor-netty",target:"_blank",rel:"noopener noreferrer"}},[e._v("Reactor Netty"),a("OutboundLink")],1),e._v(". As a Reactive Streams\nlibrary, Reactor simplifies the job of implementing the protocol. For applications it is\na natural fit to use "),a("code",[e._v("Flux")]),e._v(" and "),a("code",[e._v("Mono")]),e._v(" with declarative operators and transparent back\npressure support.")]),e._v(" "),a("p",[e._v("The API in RSocket Java is intentionally minimal and basic. It focuses on protocol\nfeatures and leaves the application programming model (e.g. RPC codegen vs other) as a\nhigher level, independent concern.")]),e._v(" "),a("p",[e._v("The main contract"),a("a",{attrs:{href:"https://github.com/rsocket/rsocket-java/blob/master/rsocket-core/src/main/java/io/rsocket/RSocket.java",target:"_blank",rel:"noopener noreferrer"}},[e._v("io.rsocket.RSocket"),a("OutboundLink")],1),e._v("models the four request interaction types with "),a("code",[e._v("Mono")]),e._v(" representing a promise for a\nsingle message, "),a("code",[e._v("Flux")]),e._v(" a stream of messages, and "),a("code",[e._v("io.rsocket.Payload")]),e._v(" the actual\nmessage with access to data and metadata as byte buffers. The "),a("code",[e._v("RSocket")]),e._v(" contract is used\nsymmetrically. For requesting, the application is given an "),a("code",[e._v("RSocket")]),e._v(" to perform\nrequests with. For responding, the application implements "),a("code",[e._v("RSocket")]),e._v(" to handle requests.")]),e._v(" "),a("p",[e._v("This is not meant to be a thorough introduction. For the most part, Spring applications\nwill not have to use its API directly. However it may be important to see or experiment\nwith RSocket independent of Spring. The RSocket Java repository contains a number of"),a("a",{attrs:{href:"https://github.com/rsocket/rsocket-java/tree/master/rsocket-examples",target:"_blank",rel:"noopener noreferrer"}},[e._v("sample apps"),a("OutboundLink")],1),e._v(" that\ndemonstrate its API and protocol features.")]),e._v(" "),a("h4",{attrs:{id:"_5-1-3-spring-support"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_5-1-3-spring-support"}},[e._v("#")]),e._v(" 5.1.3. Spring Support")]),e._v(" "),a("p",[e._v("The "),a("code",[e._v("spring-messaging")]),e._v(" module contains the following:")]),e._v(" "),a("ul",[a("li",[a("p",[a("a",{attrs:{href:"#rsocket-requester"}},[e._v("RSocketRequester")]),e._v(" — fluent API to make requests through an "),a("code",[e._v("io.rsocket.RSocket")]),e._v("with data and metadata encoding/decoding.")])]),e._v(" "),a("li",[a("p",[a("a",{attrs:{href:"#rsocket-annot-responders"}},[e._v("Annotated Responders")]),e._v(" — "),a("code",[e._v("@MessageMapping")]),e._v(" annotated handler methods for\nresponding.")])])]),e._v(" "),a("p",[e._v("The "),a("code",[e._v("spring-web")]),e._v(" module contains "),a("code",[e._v("Encoder")]),e._v(" and "),a("code",[e._v("Decoder")]),e._v(" implementations such as Jackson\nCBOR/JSON, and Protobuf that RSocket applications will likely need. It also contains the"),a("code",[e._v("PathPatternParser")]),e._v(" that can be plugged in for efficient route matching.")]),e._v(" "),a("p",[e._v("Spring Boot 2.2 supports standing up an RSocket server over TCP or WebSocket, including\nthe option to expose RSocket over WebSocket in a WebFlux server. There is also client\nsupport and auto-configuration for an "),a("code",[e._v("RSocketRequester.Builder")]),e._v(" and "),a("code",[e._v("RSocketStrategies")]),e._v(".\nSee the"),a("a",{attrs:{href:"https://docs.spring.io/spring-boot/docs/current/reference/htmlsingle/#boot-features-rsocket",target:"_blank",rel:"noopener noreferrer"}},[e._v("RSocket section"),a("OutboundLink")],1),e._v("in the Spring Boot reference for more details.")]),e._v(" "),a("p",[e._v("Spring Security 5.2 provides RSocket support.")]),e._v(" "),a("p",[e._v("Spring Integration 5.2 provides inbound and outbound gateways to interact with RSocket\nclients and servers. See the Spring Integration Reference Manual for more details.")]),e._v(" "),a("p",[e._v("Spring Cloud Gateway supports RSocket connections.")]),e._v(" "),a("h3",{attrs:{id:"_5-2-rsocketrequester"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_5-2-rsocketrequester"}},[e._v("#")]),e._v(" 5.2. RSocketRequester")]),e._v(" "),a("p",[a("code",[e._v("RSocketRequester")]),e._v(" provides a fluent API to perform RSocket requests, accepting and\nreturning objects for data and metadata instead of low level data buffers. It can be used\nsymmetrically, to make requests from clients and to make requests from servers.")]),e._v(" "),a("h4",{attrs:{id:"_5-2-1-client-requester"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_5-2-1-client-requester"}},[e._v("#")]),e._v(" 5.2.1. Client Requester")]),e._v(" "),a("p",[e._v("To obtain an "),a("code",[e._v("RSocketRequester")]),e._v(" on the client side is to connect to a server which involves\nsending an RSocket "),a("code",[e._v("SETUP")]),e._v(" frame with connection settings. "),a("code",[e._v("RSocketRequester")]),e._v(" provides a\nbuilder that helps to prepare an "),a("code",[e._v("io.rsocket.core.RSocketConnector")]),e._v(" including connection\nsettings for the "),a("code",[e._v("SETUP")]),e._v(" frame.")]),e._v(" "),a("p",[e._v("This is the most basic way to connect with default settings:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('RSocketRequester requester = RSocketRequester.builder().tcp("localhost", 7000);\n\nURI url = URI.create("https://example.org:8080/rsocket");\nRSocketRequester requester = RSocketRequester.builder().webSocket(url);\n')])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('val requester = RSocketRequester.builder().tcp("localhost", 7000)\n\nURI url = URI.create("https://example.org:8080/rsocket");\nval requester = RSocketRequester.builder().webSocket(url)\n')])])]),a("p",[e._v("The above does not connect immediately. When requests are made, a shared connection is\nestablished transparently and used.")]),e._v(" "),a("h5",{attrs:{id:"connection-setup"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#connection-setup"}},[e._v("#")]),e._v(" Connection Setup")]),e._v(" "),a("p",[a("code",[e._v("RSocketRequester.Builder")]),e._v(" provides the following to customize the initial "),a("code",[e._v("SETUP")]),e._v(" frame:")]),e._v(" "),a("ul",[a("li",[a("p",[a("code",[e._v("dataMimeType(MimeType)")]),e._v(" — set the mime type for data on the connection.")])]),e._v(" "),a("li",[a("p",[a("code",[e._v("metadataMimeType(MimeType)")]),e._v(" — set the mime type for metadata on the connection.")])]),e._v(" "),a("li",[a("p",[a("code",[e._v("setupData(Object)")]),e._v(" — data to include in the "),a("code",[e._v("SETUP")]),e._v(".")])]),e._v(" "),a("li",[a("p",[a("code",[e._v("setupRoute(String, Object…​)")]),e._v(" — route in the metadata to include in the "),a("code",[e._v("SETUP")]),e._v(".")])]),e._v(" "),a("li",[a("p",[a("code",[e._v("setupMetadata(Object, MimeType)")]),e._v(" — other metadata to include in the "),a("code",[e._v("SETUP")]),e._v(".")])])]),e._v(" "),a("p",[e._v("For data, the default mime type is derived from the first configured "),a("code",[e._v("Decoder")]),e._v(". For\nmetadata, the default mime type is"),a("a",{attrs:{href:"https://github.com/rsocket/rsocket/blob/master/Extensions/CompositeMetadata.md",target:"_blank",rel:"noopener noreferrer"}},[e._v("composite metadata"),a("OutboundLink")],1),e._v(" which allows multiple\nmetadata value and mime type pairs per request. Typically both don’t need to be changed.")]),e._v(" "),a("p",[e._v("Data and metadata in the "),a("code",[e._v("SETUP")]),e._v(" frame is optional. On the server side,"),a("a",{attrs:{href:"#rsocket-annot-connectmapping"}},[e._v("@ConnectMapping")]),e._v(" methods can be used to handle the start of a\nconnection and the content of the "),a("code",[e._v("SETUP")]),e._v(" frame. Metadata may be used for connection\nlevel security.")]),e._v(" "),a("h5",{attrs:{id:"strategies"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#strategies"}},[e._v("#")]),e._v(" Strategies")]),e._v(" "),a("p",[a("code",[e._v("RSocketRequester.Builder")]),e._v(" accepts "),a("code",[e._v("RSocketStrategies")]),e._v(" to configure the requester.\nYou’ll need to use this to provide encoders and decoders for (de)-serialization of data and\nmetadata values. By default only the basic codecs from "),a("code",[e._v("spring-core")]),e._v(" for "),a("code",[e._v("String")]),e._v(","),a("code",[e._v("byte[]")]),e._v(", and "),a("code",[e._v("ByteBuffer")]),e._v(" are registered. Adding "),a("code",[e._v("spring-web")]),e._v(" provides access to more that\ncan be registered as follows:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('RSocketStrategies strategies = RSocketStrategies.builder()\n    .encoders(encoders -> encoders.add(new Jackson2CborEncoder()))\n    .decoders(decoders -> decoders.add(new Jackson2CborDecoder()))\n    .build();\n\nRSocketRequester requester = RSocketRequester.builder()\n    .rsocketStrategies(strategies)\n    .tcp("localhost", 7000);\n')])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('val strategies = RSocketStrategies.builder()\n        .encoders { it.add(Jackson2CborEncoder()) }\n        .decoders { it.add(Jackson2CborDecoder()) }\n        .build()\n\nval requester = RSocketRequester.builder()\n        .rsocketStrategies(strategies)\n        .tcp("localhost", 7000)\n')])])]),a("p",[a("code",[e._v("RSocketStrategies")]),e._v(" is designed for re-use. In some scenarios, e.g. client and server in\nthe same application, it may be preferable to declare it in Spring configuration.")]),e._v(" "),a("h5",{attrs:{id:"client-responders"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#client-responders"}},[e._v("#")]),e._v(" Client Responders")]),e._v(" "),a("p",[a("code",[e._v("RSocketRequester.Builder")]),e._v(" can be used to configure responders to requests from the\nserver.")]),e._v(" "),a("p",[e._v("You can use annotated handlers for client-side responding based on the same\ninfrastructure that’s used on a server, but registered programmatically as follows:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('RSocketStrategies strategies = RSocketStrategies.builder()\n    .routeMatcher(new PathPatternRouteMatcher())  (1)\n    .build();\n\nSocketAcceptor responder =\n    RSocketMessageHandler.responder(strategies, new ClientHandler()); (2)\n\nRSocketRequester requester = RSocketRequester.builder()\n    .rsocketConnector(connector -> connector.acceptor(responder)) (3)\n    .tcp("localhost", 7000);\n')])])]),a("table",[a("thead",[a("tr",[a("th",[a("strong",[e._v("1")])]),e._v(" "),a("th",[e._v("Use "),a("code",[e._v("PathPatternRouteMatcher")]),e._v(", if "),a("code",[e._v("spring-web")]),e._v(" is present, for efficient"),a("br"),e._v("route matching.")])])]),e._v(" "),a("tbody",[a("tr",[a("td",[a("strong",[e._v("2")])]),e._v(" "),a("td",[e._v("Create a responder from a class with "),a("code",[e._v("@MessageMaping")]),e._v(" and/or "),a("code",[e._v("@ConnectMapping")]),e._v(" methods.")])]),e._v(" "),a("tr",[a("td",[a("strong",[e._v("3")])]),e._v(" "),a("td",[e._v("Register the responder.")])])])]),e._v(" "),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('val strategies = RSocketStrategies.builder()\n        .routeMatcher(PathPatternRouteMatcher())  (1)\n        .build()\n\nval responder =\n    RSocketMessageHandler.responder(strategies, new ClientHandler()); (2)\n\nval requester = RSocketRequester.builder()\n        .rsocketConnector { it.acceptor(responder) } (3)\n        .tcp("localhost", 7000)\n')])])]),a("table",[a("thead",[a("tr",[a("th",[a("strong",[e._v("1")])]),e._v(" "),a("th",[e._v("Use "),a("code",[e._v("PathPatternRouteMatcher")]),e._v(", if "),a("code",[e._v("spring-web")]),e._v(" is present, for efficient"),a("br"),e._v("route matching.")])])]),e._v(" "),a("tbody",[a("tr",[a("td",[a("strong",[e._v("2")])]),e._v(" "),a("td",[e._v("Create a responder from a class with "),a("code",[e._v("@MessageMaping")]),e._v(" and/or "),a("code",[e._v("@ConnectMapping")]),e._v(" methods.")])]),e._v(" "),a("tr",[a("td",[a("strong",[e._v("3")])]),e._v(" "),a("td",[e._v("Register the responder.")])])])]),e._v(" "),a("p",[e._v("Note the above is only a shortcut designed for programmatic registration of client\nresponders. For alternative scenarios, where client responders are in Spring configuration,\nyou can still declare "),a("code",[e._v("RSocketMessageHandler")]),e._v(" as a Spring bean and then apply as follows:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('ApplicationContext context = ... ;\nRSocketMessageHandler handler = context.getBean(RSocketMessageHandler.class);\n\nRSocketRequester requester = RSocketRequester.builder()\n    .rsocketConnector(connector -> connector.acceptor(handler.responder()))\n    .tcp("localhost", 7000);\n')])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('import org.springframework.beans.factory.getBean\n\nval context: ApplicationContext = ...\nval handler = context.getBean<RSocketMessageHandler>()\n\nval requester = RSocketRequester.builder()\n        .rsocketConnector { it.acceptor(handler.responder()) }\n        .tcp("localhost", 7000)\n')])])]),a("p",[e._v("For the above you may also need to use "),a("code",[e._v("setHandlerPredicate")]),e._v(" in "),a("code",[e._v("RSocketMessageHandler")]),e._v(" to\nswitch to a different strategy for detecting client responders, e.g. based on a custom\nannotation such as "),a("code",[e._v("@RSocketClientResponder")]),e._v(" vs the default "),a("code",[e._v("@Controller")]),e._v(". This\nis necessary in scenarios with client and server, or multiple clients in the same\napplication.")]),e._v(" "),a("p",[e._v("See also "),a("a",{attrs:{href:"#rsocket-annot-responders"}},[e._v("Annotated Responders")]),e._v(", for more on the programming model.")]),e._v(" "),a("h5",{attrs:{id:"advanced"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#advanced"}},[e._v("#")]),e._v(" Advanced")]),e._v(" "),a("p",[a("code",[e._v("RSocketRequesterBuilder")]),e._v(" provides a callback to expose the underlying"),a("code",[e._v("io.rsocket.core.RSocketConnector")]),e._v(" for further configuration options for keepalive\nintervals, session resumption, interceptors, and more. You can configure options\nat that level as follows:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('RSocketRequester requester = RSocketRequester.builder()\n    .rsocketConnector(connector -> {\n        // ...\n    })\n    .tcp("localhost", 7000);\n')])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('val requester = RSocketRequester.builder()\n        .rsocketConnector {\n            //...\n        }\n        .tcp("localhost", 7000)\n')])])]),a("h4",{attrs:{id:"_5-2-2-server-requester"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_5-2-2-server-requester"}},[e._v("#")]),e._v(" 5.2.2. Server Requester")]),e._v(" "),a("p",[e._v("To make requests from a server to connected clients is a matter of obtaining the\nrequester for the connected client from the server.")]),e._v(" "),a("p",[e._v("In "),a("a",{attrs:{href:"#rsocket-annot-responders"}},[e._v("Annotated Responders")]),e._v(", "),a("code",[e._v("@ConnectMapping")]),e._v(" and "),a("code",[e._v("@MessageMapping")]),e._v(" methods support an"),a("code",[e._v("RSocketRequester")]),e._v(" argument. Use it to access the requester for the connection. Keep in\nmind that "),a("code",[e._v("@ConnectMapping")]),e._v(" methods are essentially handlers of the "),a("code",[e._v("SETUP")]),e._v(" frame which\nmust be handled before requests can begin. Therefore, requests at the very start must be\ndecoupled from handling. For example:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('@ConnectMapping\nMono<Void> handle(RSocketRequester requester) {\n    requester.route("status").data("5")\n        .retrieveFlux(StatusReport.class)\n        .subscribe(bar -> { (1)\n            // ...\n        });\n    return ... (2)\n}\n')])])]),a("table",[a("thead",[a("tr",[a("th",[a("strong",[e._v("1")])]),e._v(" "),a("th",[e._v("Start the request asynchronously, independent from handling.")])])]),e._v(" "),a("tbody",[a("tr",[a("td",[a("strong",[e._v("2")])]),e._v(" "),a("td",[e._v("Perform handling and return completion "),a("code",[e._v("Mono<Void>")]),e._v(".")])])])]),e._v(" "),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('@ConnectMapping\nsuspend fun handle(requester: RSocketRequester) {\n    GlobalScope.launch {\n        requester.route("status").data("5").retrieveFlow<StatusReport>().collect { (1)\n            // ...\n        }\n    }\n    /// ... (2)\n}\n')])])]),a("table",[a("thead",[a("tr",[a("th",[a("strong",[e._v("1")])]),e._v(" "),a("th",[e._v("Start the request asynchronously, independent from handling.")])])]),e._v(" "),a("tbody",[a("tr",[a("td",[a("strong",[e._v("2")])]),e._v(" "),a("td",[e._v("Perform handling in the suspending function.")])])])]),e._v(" "),a("h4",{attrs:{id:"_5-2-3-requests"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_5-2-3-requests"}},[e._v("#")]),e._v(" 5.2.3. Requests")]),e._v(" "),a("p",[e._v("Once you have a "),a("a",{attrs:{href:"#rsocket-requester-client"}},[e._v("client")]),e._v(" or"),a("a",{attrs:{href:"#rsocket-requester-server"}},[e._v("server")]),e._v(" requester, you can make requests as follows:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('ViewBox viewBox = ... ;\n\nFlux<AirportLocation> locations = requester.route("locate.radars.within") (1)\n        .data(viewBox) (2)\n        .retrieveFlux(AirportLocation.class); (3)\n')])])]),a("table",[a("thead",[a("tr",[a("th",[a("strong",[e._v("1")])]),e._v(" "),a("th",[e._v("Specify a route to include in the metadata of the request message.")])])]),e._v(" "),a("tbody",[a("tr",[a("td",[a("strong",[e._v("2")])]),e._v(" "),a("td",[e._v("Provide data for the request message.")])]),e._v(" "),a("tr",[a("td",[a("strong",[e._v("3")])]),e._v(" "),a("td",[e._v("Declare the expected response.")])])])]),e._v(" "),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('val viewBox: ViewBox = ...\n\nval locations = requester.route("locate.radars.within") (1)\n        .data(viewBox) (2)\n        .retrieveFlow<AirportLocation>() (3)\n')])])]),a("table",[a("thead",[a("tr",[a("th",[a("strong",[e._v("1")])]),e._v(" "),a("th",[e._v("Specify a route to include in the metadata of the request message.")])])]),e._v(" "),a("tbody",[a("tr",[a("td",[a("strong",[e._v("2")])]),e._v(" "),a("td",[e._v("Provide data for the request message.")])]),e._v(" "),a("tr",[a("td",[a("strong",[e._v("3")])]),e._v(" "),a("td",[e._v("Declare the expected response.")])])])]),e._v(" "),a("p",[e._v("The interaction type is determined implicitly from the cardinality of the input and\noutput. The above example is a "),a("code",[e._v("Request-Stream")]),e._v(" because one value is sent and a stream\nof values is received. For the most part you don’t need to think about this as long as the\nchoice of input and output matches an RSocket interaction type and the types of input and\noutput expected by the responder. The only example of an invalid combination is many-to-one.")]),e._v(" "),a("p",[e._v("The "),a("code",[e._v("data(Object)")]),e._v(" method also accepts any Reactive Streams "),a("code",[e._v("Publisher")]),e._v(", including"),a("code",[e._v("Flux")]),e._v(" and "),a("code",[e._v("Mono")]),e._v(", as well as any other producer of value(s) that is registered in the"),a("code",[e._v("ReactiveAdapterRegistry")]),e._v(". For a multi-value "),a("code",[e._v("Publisher")]),e._v(" such as "),a("code",[e._v("Flux")]),e._v(" which produces the\nsame types of values, consider using one of the overloaded "),a("code",[e._v("data")]),e._v(" methods to avoid having\ntype checks and "),a("code",[e._v("Encoder")]),e._v(" lookup on every element:")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("data(Object producer, Class<?> elementClass);\ndata(Object producer, ParameterizedTypeReference<?> elementTypeRef);\n")])])]),a("p",[e._v("The "),a("code",[e._v("data(Object)")]),e._v(" step is optional. Skip it for requests that don’t send data:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('Mono<AirportLocation> location = requester.route("find.radar.EWR"))\n    .retrieveMono(AirportLocation.class);\n')])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('import org.springframework.messaging.rsocket.retrieveAndAwait\n\nval location = requester.route("find.radar.EWR")\n    .retrieveAndAwait<AirportLocation>()\n')])])]),a("p",[e._v("Extra metadata values can be added if using"),a("a",{attrs:{href:"https://github.com/rsocket/rsocket/blob/master/Extensions/CompositeMetadata.md",target:"_blank",rel:"noopener noreferrer"}},[e._v("composite metadata"),a("OutboundLink")],1),e._v(" (the default) and if the\nvalues are supported by a registered "),a("code",[e._v("Encoder")]),e._v(". For example:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('String securityToken = ... ;\nViewBox viewBox = ... ;\nMimeType mimeType = MimeType.valueOf("message/x.rsocket.authentication.bearer.v0");\n\nFlux<AirportLocation> locations = requester.route("locate.radars.within")\n        .metadata(securityToken, mimeType)\n        .data(viewBox)\n        .retrieveFlux(AirportLocation.class);\n')])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('import org.springframework.messaging.rsocket.retrieveFlow\n\nval requester: RSocketRequester = ...\n\nval securityToken: String = ...\nval viewBox: ViewBox = ...\nval mimeType = MimeType.valueOf("message/x.rsocket.authentication.bearer.v0")\n\nval locations = requester.route("locate.radars.within")\n        .metadata(securityToken, mimeType)\n        .data(viewBox)\n        .retrieveFlow<AirportLocation>()\n')])])]),a("p",[e._v("For "),a("code",[e._v("Fire-and-Forget")]),e._v(" use the "),a("code",[e._v("send()")]),e._v(" method that returns "),a("code",[e._v("Mono<Void>")]),e._v(". Note that the "),a("code",[e._v("Mono")]),e._v("indicates only that the message was successfully sent, and not that it was handled.")]),e._v(" "),a("p",[e._v("For "),a("code",[e._v("Metadata-Push")]),e._v(" use the "),a("code",[e._v("sendMetadata()")]),e._v(" method with a "),a("code",[e._v("Mono<Void>")]),e._v(" return value.")]),e._v(" "),a("h3",{attrs:{id:"_5-3-annotated-responders"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_5-3-annotated-responders"}},[e._v("#")]),e._v(" 5.3. Annotated Responders")]),e._v(" "),a("p",[e._v("RSocket responders can be implemented as "),a("code",[e._v("@MessageMapping")]),e._v(" and "),a("code",[e._v("@ConnectMapping")]),e._v(" methods."),a("code",[e._v("@MessageMapping")]),e._v(" methods handle individual requests while "),a("code",[e._v("@ConnectMapping")]),e._v(" methods handle\nconnection-level events (setup and metadata push). Annotated responders are supported\nsymmetrically, for responding from the server side and for responding from the client side.")]),e._v(" "),a("h4",{attrs:{id:"_5-3-1-server-responders"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_5-3-1-server-responders"}},[e._v("#")]),e._v(" 5.3.1. Server Responders")]),e._v(" "),a("p",[e._v("To use annotated responders on the server side, add "),a("code",[e._v("RSocketMessageHandler")]),e._v(" to your Spring\nconfiguration to detect "),a("code",[e._v("@Controller")]),e._v(" beans with "),a("code",[e._v("@MessageMapping")]),e._v(" and "),a("code",[e._v("@ConnectMapping")]),e._v("methods:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("@Configuration\nstatic class ServerConfig {\n\n    @Bean\n    public RSocketMessageHandler rsocketMessageHandler() {\n        RSocketMessageHandler handler = new RSocketMessageHandler();\n        handler.routeMatcher(new PathPatternRouteMatcher());\n        return handler;\n    }\n}\n")])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("@Configuration\nclass ServerConfig {\n\n    @Bean\n    fun rsocketMessageHandler() = RSocketMessageHandler().apply {\n        routeMatcher = PathPatternRouteMatcher()\n    }\n}\n")])])]),a("p",[e._v("Then start an RSocket server through the Java RSocket API and plug the"),a("code",[e._v("RSocketMessageHandler")]),e._v(" for the responder as follows:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('ApplicationContext context = ... ;\nRSocketMessageHandler handler = context.getBean(RSocketMessageHandler.class);\n\nCloseableChannel server =\n    RSocketServer.create(handler.responder())\n        .bind(TcpServerTransport.create("localhost", 7000))\n        .block();\n')])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('import org.springframework.beans.factory.getBean\n\nval context: ApplicationContext = ...\nval handler = context.getBean<RSocketMessageHandler>()\n\nval server = RSocketServer.create(handler.responder())\n        .bind(TcpServerTransport.create("localhost", 7000))\n        .awaitSingle()\n')])])]),a("p",[a("code",[e._v("RSocketMessageHandler")]),e._v(" supports"),a("a",{attrs:{href:"https://github.com/rsocket/rsocket/blob/master/Extensions/CompositeMetadata.md",target:"_blank",rel:"noopener noreferrer"}},[e._v("composite"),a("OutboundLink")],1),e._v(" and"),a("a",{attrs:{href:"https://github.com/rsocket/rsocket/blob/master/Extensions/Routing.md",target:"_blank",rel:"noopener noreferrer"}},[e._v("routing"),a("OutboundLink")],1),e._v(" metadata by default. You can set its"),a("a",{attrs:{href:"#rsocket-metadata-extractor"}},[e._v("MetadataExtractor")]),e._v(" if you need to switch to a\ndifferent mime type or register additional metadata mime types.")]),e._v(" "),a("p",[e._v("You’ll need to set the "),a("code",[e._v("Encoder")]),e._v(" and "),a("code",[e._v("Decoder")]),e._v(" instances required for metadata and data\nformats to support. You’ll likely need the "),a("code",[e._v("spring-web")]),e._v(" module for codec implementations.")]),e._v(" "),a("p",[e._v("By default "),a("code",[e._v("SimpleRouteMatcher")]),e._v(" is used for matching routes via "),a("code",[e._v("AntPathMatcher")]),e._v(".\nWe recommend plugging in the "),a("code",[e._v("PathPatternRouteMatcher")]),e._v(" from "),a("code",[e._v("spring-web")]),e._v(' for\nefficient route matching. RSocket routes can be hierarchical but are not URL paths.\nBoth route matchers are configured to use "." as separator by default and there is no URL\ndecoding as with HTTP URLs.')]),e._v(" "),a("p",[a("code",[e._v("RSocketMessageHandler")]),e._v(" can be configured via "),a("code",[e._v("RSocketStrategies")]),e._v(" which may be useful if\nyou need to share configuration between a client and a server in the same process:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("@Configuration\nstatic class ServerConfig {\n\n    @Bean\n    public RSocketMessageHandler rsocketMessageHandler() {\n        RSocketMessageHandler handler = new RSocketMessageHandler();\n        handler.setRSocketStrategies(rsocketStrategies());\n        return handler;\n    }\n\n    @Bean\n    public RSocketStrategies rsocketStrategies() {\n        return RSocketStrategies.builder()\n            .encoders(encoders -> encoders.add(new Jackson2CborEncoder()))\n            .decoders(decoders -> decoders.add(new Jackson2CborDecoder()))\n            .routeMatcher(new PathPatternRouteMatcher())\n            .build();\n    }\n}\n")])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v("@Configuration\nclass ServerConfig {\n\n    @Bean\n    fun rsocketMessageHandler() = RSocketMessageHandler().apply {\n        rSocketStrategies = rsocketStrategies()\n    }\n\n    @Bean\n    fun rsocketStrategies() = RSocketStrategies.builder()\n            .encoders { it.add(Jackson2CborEncoder()) }\n            .decoders { it.add(Jackson2CborDecoder()) }\n            .routeMatcher(PathPatternRouteMatcher())\n            .build()\n}\n")])])]),a("h4",{attrs:{id:"_5-3-2-client-responders"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_5-3-2-client-responders"}},[e._v("#")]),e._v(" 5.3.2. Client Responders")]),e._v(" "),a("p",[e._v("Annotated responders on the client side need to be configured in the"),a("code",[e._v("RSocketRequester.Builder")]),e._v(". For details, see"),a("a",{attrs:{href:"#rsocket-requester-client-responder"}},[e._v("Client Responders")]),e._v(".")]),e._v(" "),a("h4",{attrs:{id:"_5-3-3-messagemapping"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_5-3-3-messagemapping"}},[e._v("#")]),e._v(" 5.3.3. @MessageMapping")]),e._v(" "),a("p",[e._v("Once "),a("a",{attrs:{href:"#rsocket-annot-responders-server"}},[e._v("server")]),e._v(" or"),a("a",{attrs:{href:"#rsocket-annot-responders-client"}},[e._v("client")]),e._v(" responder configuration is in place,"),a("code",[e._v("@MessageMapping")]),e._v(" methods can be used as follows:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('@Controller\npublic class RadarsController {\n\n    @MessageMapping("locate.radars.within")\n    public Flux<AirportLocation> radars(MapRequest request) {\n        // ...\n    }\n}\n')])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('@Controller\nclass RadarsController {\n\n    @MessageMapping("locate.radars.within")\n    fun radars(request: MapRequest): Flow<AirportLocation> {\n        // ...\n    }\n}\n')])])]),a("p",[e._v("The above "),a("code",[e._v("@MessageMapping")]),e._v(' method responds to a Request-Stream interaction having the\nroute "locate.radars.within". It supports a flexible method signature with the option to\nuse the following method arguments:')]),e._v(" "),a("table",[a("thead",[a("tr",[a("th",[e._v("Method Argument")]),e._v(" "),a("th",[e._v("Description")])])]),e._v(" "),a("tbody",[a("tr",[a("td",[a("code",[e._v("@Payload")])]),e._v(" "),a("td",[e._v("The payload of the request. This can be a concrete value of asynchronous types like"),a("code",[e._v("Mono")]),e._v(" or "),a("code",[e._v("Flux")]),e._v("."),a("br"),a("br"),a("strong",[e._v("Note:")]),e._v(" Use of the annotation is optional. A method argument that is not a simple type"),a("br"),e._v("and is not any of the other supported arguments, is assumed to be the expected payload.")])]),e._v(" "),a("tr",[a("td",[a("code",[e._v("RSocketRequester")])]),e._v(" "),a("td",[e._v("Requester for making requests to the remote end.")])]),e._v(" "),a("tr",[a("td",[a("code",[e._v("@DestinationVariable")])]),e._v(" "),a("td",[e._v("Value extracted from the route based on variables in the mapping pattern, e.g."),a("code",[e._v('@MessageMapping("find.radar.{id}")')]),e._v(".")])]),e._v(" "),a("tr",[a("td",[a("code",[e._v("@Header")])]),e._v(" "),a("td",[e._v("Metadata value registered for extraction as described in "),a("a",{attrs:{href:"#rsocket-metadata-extractor"}},[e._v("MetadataExtractor")]),e._v(".")])]),e._v(" "),a("tr",[a("td",[a("code",[e._v("@Headers Map<String, Object>")])]),e._v(" "),a("td",[e._v("All metadata values registered for extraction as described in "),a("a",{attrs:{href:"#rsocket-metadata-extractor"}},[e._v("MetadataExtractor")]),e._v(".")])])])]),e._v(" "),a("p",[e._v("The return value is expected to be one or more Objects to be serialized as response\npayloads. That can be asynchronous types like "),a("code",[e._v("Mono")]),e._v(" or "),a("code",[e._v("Flux")]),e._v(", a concrete value, or\neither "),a("code",[e._v("void")]),e._v(" or a no-value asynchronous type such as "),a("code",[e._v("Mono<Void>")]),e._v(".")]),e._v(" "),a("p",[e._v("The RSocket interaction type that an "),a("code",[e._v("@MessageMapping")]),e._v(" method supports is determined from\nthe cardinality of the input (i.e. "),a("code",[e._v("@Payload")]),e._v(" argument) and of the output, where\ncardinality means the following:")]),e._v(" "),a("table",[a("thead",[a("tr",[a("th",[e._v("Cardinality")]),e._v(" "),a("th",[e._v("Description")])])]),e._v(" "),a("tbody",[a("tr",[a("td",[e._v("1")]),e._v(" "),a("td",[e._v("Either an explicit value, or a single-value asynchronous type such as "),a("code",[e._v("Mono<T>")]),e._v(".")])]),e._v(" "),a("tr",[a("td",[e._v("Many")]),e._v(" "),a("td",[e._v("A multi-value asynchronous type such as "),a("code",[e._v("Flux<T>")]),e._v(".")])]),e._v(" "),a("tr",[a("td",[e._v("0")]),e._v(" "),a("td",[e._v("For input this means the method does not have an "),a("code",[e._v("@Payload")]),e._v(" argument."),a("br"),a("br"),e._v(" For output this is "),a("code",[e._v("void")]),e._v(" or a no-value asynchronous type such as "),a("code",[e._v("Mono<Void>")]),e._v(".")])])])]),e._v(" "),a("p",[e._v("The table below shows all input and output cardinality combinations and the corresponding\ninteraction type(s):")]),e._v(" "),a("table",[a("thead",[a("tr",[a("th",[e._v("Input Cardinality")]),e._v(" "),a("th",[e._v("Output Cardinality")]),e._v(" "),a("th",[e._v("Interaction Types")])])]),e._v(" "),a("tbody",[a("tr",[a("td",[e._v("0, 1")]),e._v(" "),a("td",[e._v("0")]),e._v(" "),a("td",[e._v("Fire-and-Forget, Request-Response")])]),e._v(" "),a("tr",[a("td",[e._v("0, 1")]),e._v(" "),a("td",[e._v("1")]),e._v(" "),a("td",[e._v("Request-Response")])]),e._v(" "),a("tr",[a("td",[e._v("0, 1")]),e._v(" "),a("td",[e._v("Many")]),e._v(" "),a("td",[e._v("Request-Stream")])]),e._v(" "),a("tr",[a("td",[e._v("Many")]),e._v(" "),a("td",[e._v("0, 1, Many")]),e._v(" "),a("td",[e._v("Request-Channel")])])])]),e._v(" "),a("h4",{attrs:{id:"_5-3-4-connectmapping"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_5-3-4-connectmapping"}},[e._v("#")]),e._v(" 5.3.4. @ConnectMapping")]),e._v(" "),a("p",[a("code",[e._v("@ConnectMapping")]),e._v(" handles the "),a("code",[e._v("SETUP")]),e._v(" frame at the start of an RSocket connection, and\nany subsequent metadata push notifications through the "),a("code",[e._v("METADATA_PUSH")]),e._v(" frame, i.e."),a("code",[e._v("metadataPush(Payload)")]),e._v(" in "),a("code",[e._v("io.rsocket.RSocket")]),e._v(".")]),e._v(" "),a("p",[a("code",[e._v("@ConnectMapping")]),e._v(" methods support the same arguments as"),a("a",{attrs:{href:"#rsocket-annot-messagemapping"}},[e._v("@MessageMapping")]),e._v(" but based on metadata and data from the "),a("code",[e._v("SETUP")]),e._v(" and"),a("code",[e._v("METADATA_PUSH")]),e._v(" frames. "),a("code",[e._v("@ConnectMapping")]),e._v(" can have a pattern to narrow handling to\nspecific connections that have a route in the metadata, or if no patterns are declared\nthen all connections match.")]),e._v(" "),a("p",[a("code",[e._v("@ConnectMapping")]),e._v(" methods cannot return data and must be declared with "),a("code",[e._v("void")]),e._v(" or"),a("code",[e._v("Mono<Void>")]),e._v(" as the return value. If handling returns an error for a new\nconnection then the connection is rejected. Handling must not be held up to make\nrequests to the "),a("code",[e._v("RSocketRequester")]),e._v(" for the connection. See"),a("a",{attrs:{href:"#rsocket-requester-server"}},[e._v("Server Requester")]),e._v(" for details.")]),e._v(" "),a("h3",{attrs:{id:"_5-4-metadataextractor"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_5-4-metadataextractor"}},[e._v("#")]),e._v(" 5.4. MetadataExtractor")]),e._v(" "),a("p",[e._v("Responders must interpret metadata."),a("a",{attrs:{href:"https://github.com/rsocket/rsocket/blob/master/Extensions/CompositeMetadata.md",target:"_blank",rel:"noopener noreferrer"}},[e._v("Composite metadata"),a("OutboundLink")],1),e._v(" allows independently\nformatted metadata values (e.g. for routing, security, tracing) each with its own mime\ntype. Applications need a way to configure metadata mime types to support, and a way\nto access extracted values.")]),e._v(" "),a("p",[a("code",[e._v("MetadataExtractor")]),e._v(" is a contract to take serialized metadata and return decoded\nname-value pairs that can then be accessed like headers by name, for example via "),a("code",[e._v("@Header")]),e._v("in annotated handler methods.")]),e._v(" "),a("p",[a("code",[e._v("DefaultMetadataExtractor")]),e._v(" can be given "),a("code",[e._v("Decoder")]),e._v(" instances to decode metadata. Out of\nthe box it has built-in support for"),a("a",{attrs:{href:"https://github.com/rsocket/rsocket/blob/master/Extensions/Routing.md",target:"_blank",rel:"noopener noreferrer"}},[e._v('"message/x.rsocket.routing.v0"'),a("OutboundLink")],1),e._v(" which it decodes to"),a("code",[e._v("String")]),e._v(' and saves under the "route" key. For any other mime type you’ll need to provide\na '),a("code",[e._v("Decoder")]),e._v(" and register the mime type as follows:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('DefaultMetadataExtractor extractor = new DefaultMetadataExtractor(metadataDecoders);\nextractor.metadataToExtract(fooMimeType, Foo.class, "foo");\n')])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('import org.springframework.messaging.rsocket.metadataToExtract\n\nval extractor = DefaultMetadataExtractor(metadataDecoders)\nextractor.metadataToExtract<Foo>(fooMimeType, "foo")\n')])])]),a("p",[e._v("Composite metadata works well to combine independent metadata values. However the\nrequester might not support composite metadata, or may choose not to use it. For this,"),a("code",[e._v("DefaultMetadataExtractor")]),e._v(" may needs custom logic to map the decoded value to the output\nmap. Here is an example where JSON is used for metadata:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('DefaultMetadataExtractor extractor = new DefaultMetadataExtractor(metadataDecoders);\nextractor.metadataToExtract(\n    MimeType.valueOf("application/vnd.myapp.metadata+json"),\n    new ParameterizedTypeReference<Map<String,String>>() {},\n    (jsonMap, outputMap) -> {\n        outputMap.putAll(jsonMap);\n    });\n')])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('import org.springframework.messaging.rsocket.metadataToExtract\n\nval extractor = DefaultMetadataExtractor(metadataDecoders)\nextractor.metadataToExtract<Map<String, String>>(MimeType.valueOf("application/vnd.myapp.metadata+json")) { jsonMap, outputMap ->\n    outputMap.putAll(jsonMap)\n}\n')])])]),a("p",[e._v("When configuring "),a("code",[e._v("MetadataExtractor")]),e._v(" through "),a("code",[e._v("RSocketStrategies")]),e._v(", you can let"),a("code",[e._v("RSocketStrategies.Builder")]),e._v(" create the extractor with the configured decoders, and\nsimply use a callback to customize registrations as follows:")]),e._v(" "),a("p",[e._v("Java")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('RSocketStrategies strategies = RSocketStrategies.builder()\n    .metadataExtractorRegistry(registry -> {\n        registry.metadataToExtract(fooMimeType, Foo.class, "foo");\n        // ...\n    })\n    .build();\n')])])]),a("p",[e._v("Kotlin")]),e._v(" "),a("div",{staticClass:"language- extra-class"},[a("pre",{pre:!0,attrs:{class:"language-text"}},[a("code",[e._v('import org.springframework.messaging.rsocket.metadataToExtract\n\nval strategies = RSocketStrategies.builder()\n        .metadataExtractorRegistry { registry: MetadataExtractorRegistry ->\n            registry.metadataToExtract<Foo>(fooMimeType, "foo")\n            // ...\n        }\n        .build()\n')])])]),a("h2",{attrs:{id:"_6-reactive-libraries"}},[a("a",{staticClass:"header-anchor",attrs:{href:"#_6-reactive-libraries"}},[e._v("#")]),e._v(" 6. Reactive Libraries")]),e._v(" "),a("p",[a("code",[e._v("spring-webflux")]),e._v(" depends on "),a("code",[e._v("reactor-core")]),e._v(" and uses it internally to compose asynchronous\nlogic and to provide Reactive Streams support. Generally, WebFlux APIs return "),a("code",[e._v("Flux")]),e._v(" or"),a("code",[e._v("Mono")]),e._v(" (since those are used internally) and leniently accept any Reactive Streams"),a("code",[e._v("Publisher")]),e._v(" implementation as input. The use of "),a("code",[e._v("Flux")]),e._v(" versus "),a("code",[e._v("Mono")]),e._v(" is important, because\nit helps to express cardinality — for example, whether a single or multiple asynchronous\nvalues are expected, and that can be essential for making decisions (for example, when\nencoding or decoding HTTP messages).")]),e._v(" "),a("p",[e._v("For annotated controllers, WebFlux transparently adapts to the reactive library chosen\nby the application. This is done with the help of the"),a("a",{attrs:{href:"https://docs.spring.io/spring-framework/docs/5.3.16/javadoc-api/org/springframework/core/ReactiveAdapterRegistry.html",target:"_blank",rel:"noopener noreferrer"}},[a("code",[e._v("ReactiveAdapterRegistry")]),a("OutboundLink")],1),e._v("which provides pluggable support for reactive library and other asynchronous types.\nThe registry has built-in support for RxJava 3, Kotlin coroutines and SmallRye Mutiny,\nbut you can register other third-party adapters as well.")]),e._v(" "),a("table",[a("thead",[a("tr",[a("th"),e._v(" "),a("th",[e._v("As of Spring Framework 5.3.11, support for RxJava 1 and 2 is deprecated, following"),a("br"),e._v("RxJava’s own EOL advice and the upgrade recommendation towards RxJava 3.")])])]),e._v(" "),a("tbody")]),e._v(" "),a("p",[e._v("For functional APIs (such as "),a("a",{attrs:{href:"#webflux-fn"}},[e._v("Functional Endpoints")]),e._v(", the "),a("code",[e._v("WebClient")]),e._v(", and others), the general\nrules for WebFlux APIs apply — "),a("code",[e._v("Flux")]),e._v(" and "),a("code",[e._v("Mono")]),e._v(" as return values and a Reactive Streams"),a("code",[e._v("Publisher")]),e._v(" as input. When a "),a("code",[e._v("Publisher")]),e._v(", whether custom or from another reactive library,\nis provided, it can be treated only as a stream with unknown semantics (0..N). If, however,\nthe semantics are known, you can wrap it with "),a("code",[e._v("Flux")]),e._v(" or "),a("code",[e._v("Mono.from(Publisher)")]),e._v(" instead\nof passing the raw "),a("code",[e._v("Publisher")]),e._v(".")]),e._v(" "),a("p",[e._v("For example, given a "),a("code",[e._v("Publisher")]),e._v(" that is not a "),a("code",[e._v("Mono")]),e._v(", the Jackson JSON message writer\nexpects multiple values. If the media type implies an infinite stream (for example,"),a("code",[e._v("application/json+stream")]),e._v("), values are written and flushed individually. Otherwise,\nvalues are buffered into a list and rendered as a JSON array.")])])}),[],!1,null,null,null);t.default=r.exports}}]);