Web on Reactive Stack

Part of the answer is the need for a non-blocking web stack to handle concurrency with a small number of threads and scale with less hardware resources. Servlet 3.1 did provide an API for non-blocking I/O. However, using it leads away from the rest of the Servlet API where contracts are synchronous (Filter, Servlet) or blocking (getParameter, getPart). This was the motivation for a new common API to serve as a foundation across any non-blocking runtime. That is important because of servers such as Netty that are well established in the async, non-blocking space.

The other part of the answer is functional programming. Much like the addition of annotations in Java 5 created opportunities — e.g. annotated REST controllers or unit tests, the addition of lambda expressions in Java 8 created opportunities for functional APIs in Java. This is a boon for non-blocking applications and continuation style APIs — as popularized by CompletableFuture and ReactiveX, that allow declarative composition of asynchronous logic. At the programming model level Java 8 enabled Spring WebFlux to offer functional web endpoints alongside with annotated controllers.

We touched on non-blocking and functional but why reactive and what do we mean?

The term "reactive" refers to programming models that are built around reacting to change — network component reacting to I/O events, UI controller reacting to mouse events, etc. In that sense non-blocking is reactive because instead of being blocked we are now in the mode of reacting to notifications as operations complete or data becomes available.

There is also another important mechanism that we on the Spring team associate with "reactive" and that is non-blocking back pressure. In synchronous, imperative code, blocking calls serve as a natural form of back pressure that forces the caller to wait. In non-blocking code it becomes important to control the rate of events so that a fast producer does not overwhelm its destination.

Reactive Streams is a small spec, also adopted in Java 9, that defines the interaction between asynchronous components with back pressure. For example a data repository — acting as Publisher, can produce data that an HTTP server — acting as Subscriber, can then write to the response. The main purpose of Reactive Streams is to allow the subscriber to control how fast or how slow the publisher will produce data.

Reactive Streams plays an important role for interoperability. It is of interest to libraries and infrastructure components but less useful as an application API because it is too low level. What applications need is a higher level and richer, functional API to compose async logic — similar to the Java 8 Stream API but not only for collections. This is the role that reactive libraries play.

Reactor is the reactive library of choice for Spring WebFlux. It provides the Mono and Flux API types to work on data sequences of 0..1 and 0..N through a rich set of operators aligned with the ReactiveX vocabulary of operators. Reactor is a Reactive Streams library and therefore all of its operators support non-blocking back pressure. Reactor has a strong focus on server-side Java. It is developed in close collaboration with Spring.

WebFlux requires Reactor as a core dependency but it is interoperable with other reactive libraries via Reactive Streams. As a general rule WebFlux APIs accept a plain Publisher as input, adapt it to Reactor types internally, use those, and then return either Flux or Mono as output. So you can pass any Publisher as input and you can apply operations on the output, but you’ll need to adapt the output for use with another reactive library. Whenever feasible — e.g. annotated controllers, WebFlux adapts transparently to the use of RxJava or other reactive library. See Reactive Libraries for more details.

The spring-web module contains the reactive foundation that underlies Spring WebFlux including HTTP abstractions, Reactive Streams adapters for supported servers, codecs, and a core WebHandler API comparable to the Servlet API but with non-blocking contracts.

On that foundation Spring WebFlux provides a choice of two programming models:

Should you use Spring MVC or WebFlux? Let’s cover a few different perspectives.

If you have a Spring MVC application that works fine, there is no need to change. Imperative programming is the easiest way to write, understand, and debug code. You have maximum choice of libraries since historically most are blocking.

If you are already shopping for a non-blocking web stack, Spring WebFlux offers the same execution model benefits as others in this space and also provides a choice of servers — Netty, Tomcat, Jetty, Undertow, Servlet 3.1+ containers, a choice of programming models — annotated controllers and functional web endpoints, and a choice of reactive libraries — Reactor, RxJava, or other.

If you are interested in a lightweight, functional web framework for use with Java 8 lambdas or Kotlin then use the Spring WebFlux functional web endpoints. That can also be a good choice for smaller applications or microservices with less complex requirements that can benefit from greater transparency and control.

In a microservice architecture you can have a mix of applications with either Spring MVC or Spring WebFlux controllers, or with Spring WebFlux functional endpoints. Having support for the same annotation-based programming model in both frameworks makes it easier to re-use knowledge while also selecting the right tool for the right job.

A simple way to evaluate an application is to check its dependencies. If you have blocking persistence APIs (JPA, JDBC), or networking APIs to use, then Spring MVC is the best choice for common architectures at least. It is technically feasible with both Reactor and RxJava to perform blocking calls on a separate thread but you wouldn’t be making the most of a non-blocking web stack.

If you have a Spring MVC application with calls to remote services, try the reactive WebClient. You can return reactive types (Reactor, RxJava, or other) directly from Spring MVC controller methods. The greater the latency per call, or the interdependency among calls, the more dramatic the benefits. Spring MVC controllers can call other reactive components too.

If you have a large team, keep in mind the steep learning curve in the shift to non-blocking, functional, and declarative programming. A practical way to start without a full switch is to use the reactive WebClient. Beyond that start small and measure the benefits. We expect that for a wide range of applications the shift is unnecessary.

If you are unsure what benefits to look for, start by learning about how non-blocking I/O works (e.g. concurrency on single-threaded Node.js is not an oxymoron) and its effects. The tag line is "scale with less hardware" but that effect is not guaranteed, not without some network I/O that can be slow or unpredictable. This Netflix blog post is a good resource.

Spring WebFlux is supported on Netty, Undertow, Tomcat, Jetty, and Servlet 3.1+ containers. Each server is adapted to a common Reactive Streams API. The Spring WebFlux programming models are built on that common API.

Spring Boot 2 uses Netty by default with WebFlux because Netty is more widely used in the async, non-blocking space and also provides both client and server that can share resources. By comparison Servlet 3.1 non-blocking I/O hasn’t seen much use because the bar to use it is so high. Spring WebFlux opens one practical path to adoption.

The default server choice in Spring Boot is mainly about the out-of-the-box experience. Applications can still choose any of the other supported servers which are also highly optimized for performance, fully non-blocking, and adapted to Reactive Streams back pressure. In Spring Boot it is trivial to make the switch.

Performance has many characteristics and meanings. Reactive and non-blocking generally do not make applications run faster. They can, in some cases, for example if using the WebClient to execute remote calls in parallel. On the whole it requires more work to do things the non-blocking way and that can increase slightly the required processing time.

The key expected benefit of reactive and non-blocking is the ability to scale with a small, fixed number of threads and less memory. That makes applications more resilient under load because they scale in a more predictable way. In order to observe those benefits however you need to have some latency including a mix of slow and unpredictable network I/O. That’s where the reactive stack begins to show its strengths and the differences can be dramatic.

Every HTTP server has some API for HTTP request handling. HttpHandler is a simple contract with one method to handle a request and response. It is intentionally minimal. Its main purpose is to provide a common, Reactive Streams based API for HTTP request handling over different servers.

The spring-web module contains adapters for every supported server. The table below shows the server APIs are used and where Reactive Streams support comes from:

Here are required dependencies, supported versions, and code snippets for each server:

Reactor Netty:

Undertow:

Tomcat:

Jetty:

HttpHandler is the lowest level contract for running on different HTTP servers. On top of that foundation, the WebHandler API provides a slightly higher level, but still general purpose, set of components that form a chain of WebExceptionHandler’s, WebFilter’s, and a WebHandler.

All WebHandler API components take ServerWebExchange as input which goes beyond ServerHttpRequest and ServerHttpResponse to provide extra building blocks for use in web applications such as request attributes, session attributes, access to parsed form data, multipart data, and more.

WebHttpHandlerBuilder is used to assemble a request processing chain. You can use methods on the builder to add components manually, or more likely have them detected from a Spring ApplicationContext, with the resulting HttpHandler ready to run via a server adapter:

Same in Spring MVC

The spring-web module defines the HttpMessageReader and HttpMessageWriter contracts for encoding and decoding the body of HTTP requests and responses via Rective Streams Publisher's. These contacts are used on the client side, e.g. in the WebClient, and on the server side, e.g. in annotated controllers and functional endpoints.

The spring-core module defines the Encoder and Decoder contracts that are independent of HTTP and rely on the DataBuffer contract that abstracts different byte buffer representations such as the Netty ByteBuf and java.nio.ByteBuffer (see Data Buffers and Codecs). An Encoder can be wrapped with EncoderHttpMessageWriter to be used as an HttpMessageWriter while a Decoder can be wrapped with DecoderHttpMessageReader to be used as an HttpMessageReader.

The spring-core module contains basic Encoder and Decoder implementations for byte[], ByteBuffer, DataBuffer, Resource, and String. The spring-web module adds Encoder's and Decoder's for Jackson JSON, Jackson Smile, and JAXB2. The spring-web module also contains some web-specific readers and writers for server-sent events, form data, and multipart requests.

To configure or customize the readers and writers to use applications will typically use ClientCodecConfigurer or ServerCodecConfigurer.

Same in Spring MVC

The DispatcherHandler delegates to special beans to process requests and render the appropriate responses. By "special beans" we mean Spring-managed, Object instances that implement WebFlux framework contracts. Those usually come with built-in contracts but you can customize their properties, extend then, or replaced.

The table below lists the special beans detected by the DispatcherHandler. Note that there are also some other beans detected at a lower level, see Special bean types in the Web Handler API.

Same in Spring MVC

Applications can declare the infrastructure beans listed under Web Handler API and DispatcherHandler that are required to process requests. However in most cases the WebFlux Config is the best starting point. It declares the required beans and provides a higher level configuration callback API to customize it.

Same in Spring MVC

The DispatcherHandler processes requests as follows:

When DispatcherHandler needs to process the return value from a handler, it finds a HandlerResultHandler that support it and invokes it. The available implementations are listed below with their default order (all are declared in the WebFlux Config):

Same in Spring MVC

View resolution enables rendering to a browser with an HTML template and a model without tying you to a specific view technology. In Spring WebFlux, view resolution is supported through a dedicated HandlerResultHandler that uses ViewResolver's to map a String, representing a logical view name, to a View instance. The View is then used to render the response.

Same in Spring MVC

You can define controller beans using a standard Spring bean definition. The @Controller stereotype allows for auto-detection, aligned with Spring general support for detecting @Component classes in the classpath and auto-registering bean definitions for them. It also acts as a stereotype for the annotated class, indicating its role as a web component.

To enable auto-detection of such @Controller beans, you can add component scanning to your Java configuration:

@RestController is a composed annotation that is itself meta-annotated with @Controller and @ResponseBody indicating a controller whose every method inherits the type-level @ResponseBody annotation and therefore writes directly to the response body vs view resolution and rendering with an HTML template.

Same in Spring MVC

The @RequestMapping annotation is used to map requests to controllers methods. It has various attributes to match by URL, HTTP method, request parameters, headers, and media types. It can be used at the class-level to express shared mappings or at the method level to narrow down to a specific endpoint mapping.

There are also HTTP method specific shortcut variants of @RequestMapping:

The above are Custom Annotations that are provided out of the box because arguably most controller methods should be mapped to a specific HTTP method vs using @RequestMapping which by default matches to all HTTP methods. At the same an @RequestMapping is still needed at the class level to express shared mappings.

Below is an example with type and method level mappings:

Same in Spring MVC

@RequestMapping handler methods have a flexible signature and can choose from a range of supported controller method arguments and return values.

Same in Spring MVC

The @ModelAttribute annotation can be used on @RequestMapping method arguments to create or access an Object from the model and bind it to the request. @ModelAttribute can also be used as a method-level annotation on controller methods whose purpose is not to handle requests but to add commonly needed model attributes prior to request handling.

A controller can have any number of @ModelAttribute methods. All such methods are invoked before @RequestMapping methods in the same controller. A @ModelAttribute method can also be shared across controllers via @ControllerAdvice. See the section on Controller Advice for more details.

@ModelAttribute methods have flexible method signatures. They support many of the same arguments as @RequestMapping methods except for @ModelAttribute itself nor anything related to the request body.

An example @ModelAttribute method:

To add one attribute only:

Spring WebFlux, unlike Spring MVC, explicitly supports reactive types in the model, e.g. Mono<Account> or io.reactivex.Single<Account>. Such asynchronous model attributes may be transparently resolved (and the model updated) to their actual values at the time of @RequestMapping invocation, providing a @ModelAttribute argument is declared without a wrapper, for example:

In addition any model attributes that have a reactive type wrapper are resolved to their actual values (and the model updated) just prior to view rendering.

@ModelAttribute can also be used as a method-level annotation on @RequestMapping methods in which case the return value of the @RequestMapping method is interpreted as a model attribute. This is typically not required, as it is the default behavior in HTML controllers, unless the return value is a String which would otherwise be interpreted as a view name. @ModelAttribute can also help to customize the model attribute name:

Same in Spring MVC

@InitBinder methods in an @Controller or @ControllerAdvice class can be used to customize type conversion for method arguments that represent String-based request values (e.g. request parameters, path variables, headers, cookies, and others). Type conversion also applies during data binding of request parameters onto @ModelAttribute arguments (i.e. command objects).

@InitBinder methods can register controller-specific java.bean.PropertyEditor, or Spring Converter and Formatter components. In addition, the WebFlux Java config can be used to register Converter and Formatter types in a globally shared FormattingConversionService.

@InitBinder methods support many of the same arguments that a @RequestMapping methods do, except for @ModelAttribute (command object) arguments. Typically they’re are declared with a WebDataBinder argument, for registrations, and a void return value. Below is an example:

Alternatively when using a Formatter-based setup through a shared FormattingConversionService, you could re-use the same approach and register controller-specific Formatter's:

Same in Spring MVC

Typically @ExceptionHandler, @InitBinder, and @ModelAttribute methods apply within the @Controller class (or class hierarchy) they are declared in. If you want such methods to apply more globally, across controllers, you can declare them in a class marked with @ControllerAdvice or @RestControllerAdvice.

@ControllerAdvice is marked with @Component which means such classes can be registered as Spring beans via component scanning. @RestControllerAdvice is also a meta-annotation marked with both @ControllerAdvice and @ResponseBody which essentially means @ExceptionHandler methods are rendered to the response body via message conversion (vs view resolution/template rendering).

On startup, the infrastructure classes for @RequestMapping and @ExceptionHandler methods detect Spring beans of type @ControllerAdvice, and then apply their methods at runtime. Global @ExceptionHandler methods (from an @ControllerAdvice) are applied after local ones (from the @Controller). By contrast global @ModelAttribute and @InitBinder methods are applied before local ones.

By default @ControllerAdvice methods apply to every request, i.e. all controllers, but you can narrow that down to a subset of controllers via attributes on the annotation:

Keep in mind the above selectors are evaluated at runtime and may negatively impact performance if used extensively. See the @ControllerAdvice Javadoc for more details.

Spring MVC and Spring WebFlux

UriComponents is comparable to java.net.URI. However it comes with a dedicated UriComponentsBuilder and supports URI template variables:

The above can be done as a single chain and with a shortcut:

Spring MVC and Spring WebFlux

UriComponentsBuilder is an implementation of UriBuilder. Together UriBuilderFactory and UriBuilder provide a pluggable mechanism for building a URI from a URI template, as well as a way to share common properties such as a base URI, encoding strategy, and others.

Both the RestTemplate and the WebClient can be configured with a UriBuilderFactory in order to customize how URIs are created from URI templates. The default implementation relies on UriComponentsBuilder internally and provides options to configure a common base URI, an alternative encoding mode strategy, and more.

An example of configuring the RestTemplate:

Examples of configuring the WebClient:

You can also use DefaultUriBuilderFactory directly, as you would UriComponentsBuilder. The main difference is that DefaultUriBuilderFactory is stateful and can be re-used to prepare many URLs, sharing common configuration, such as a base URL, while UriComponentsBuilder is stateless and per URI.

An example of using the DefaultUriBuilderFactory:

Spring MVC and Spring WebFlux

The default way of encoding URIs in UriComponents works as follows:

The rules for encoding are as follows: within a URI component, apply percent encoding to all illegal characters, including non-US-ASCII characters, and all other characters that are illegal within the URI component, as defined in RFC 3986.

The above default encoding strategy does not encode all characters with reserved meaning, but only the ones that are illegal within a given URI component. If this is not what you expect, you can use the alternative strategy described next.

When using DefaultUriBuilderFactory — plugged into the WebClient, RestTemplate, or used directly, you can switch to an alternative encoding strategy as shown below:

This alternative encoding strategy applies UriUtils.encode(String, Charset) to each URI variable value prior to expanding it, effectively encoding all non-US-ASCII characters, and all characters with reserved meaning in a URI, which ensures that the expanded URI variables do not have any impact on the structure or meaning of the URI.

Incoming HTTP requests are handled by a HandlerFunction, which is essentially a function that takes a ServerRequest and returns a Mono<ServerResponse>. If you’re familiar with the annotation-based programming model, a handler function is the equivalent of an @RequestMapping method.

ServerRequest and ServerResponse are immutable interfaces that offer JDK-8 friendly access to the underlying HTTP messages with Reactive Streams non-blocking back pressure. The request exposes the body as Reactor Flux or Mono types; the response accepts any Reactive Streams Publisher as body. The rational for this is explained in Reactive Libraries.

ServerRequest gives access to various HTTP request elements: the method, URI, query parameters, and headers (via a separate ServerRequest.Headers interface. Access to the body is provided through the body methods. For instance, this is how to extract the request body into a Mono<String>:

And here is how to extract the body into a Flux, where Person is a class that can be deserialised from the contents of the body (i.e. Person is supported by Jackson if the body contains JSON, or JAXB if XML).

The bodyToMono and bodyToFlux used above are in fact convenience methods that use the generic ServerRequest.body(BodyExtractor) method. BodyExtractor is a functional strategy interface that allows you to write your own extraction logic, but common BodyExtractor instances can be found in the BodyExtractors utility class. So, the above examples can also be written as follows:

Similarly, ServerResponse provides access to the HTTP response. Since it is immutable, you create a ServerResponse with a builder. The builder allows you to set the response status, add response headers, and provide a body. For instance, this is how to create a response with a 200 OK status, a JSON content-type, and a body:

And here is how to build a response with a 201 CREATED status, a "Location" header, and empty body:

Putting these together allows us to create a HandlerFunction. For instance, here is an example of a simple "Hello World" handler lambda, that returns a response with a 200 status and a body based on a String:

Writing handler functions as lambda’s, as we do above, is convenient, but perhaps lacks in readability and becomes less maintainable when dealing with multiple functions. Therefore, it is recommended to group related handler functions into a handler or controller class. For example, here is a class that exposes a reactive Person repository:

Incoming requests are routed to handler functions with a RouterFunction, which is a function that takes a ServerRequest, and returns a Mono<HandlerFunction>. If a request matches a particular route, a handler function is returned, or otherwise an empty Mono is returned. RouterFunction has a similar purpose as the @RequestMapping annotation in the annotation-based programming model.

Typically, you do not write router functions yourself, but rather use RouterFunctions.route(RequestPredicate, HandlerFunction) to create one using a request predicate and handler function. If the predicate applies, the request is routed to the given handler function; otherwise no routing is performed, resulting in a 404 Not Found response. Though you can write your own RequestPredicate, you do not have to: the RequestPredicates utility class offers commonly used predicates, such matching based on path, HTTP method, content-type, etc. Using route, we can route to our "Hello World" handler function:

Two router functions can be composed into a new router function that routes to either handler function: if the predicate of the first route does not match, the second is evaluated. Composed router functions are evaluated in order, so it makes sense to put specific functions before generic ones. You can compose two router functions by calling RouterFunction.and(RouterFunction), or by calling RouterFunction.andRoute(RequestPredicate, HandlerFunction), which is a convenient combination of RouterFunction.and() with RouterFunctions.route().

Given the PersonHandler we showed above, we can now define a router function that routes to the respective handler functions. We use method-references to refer to the handler functions:

Besides router functions, you can also compose request predicates, by calling RequestPredicate.and(RequestPredicate) or RequestPredicate.or(RequestPredicate). These work as expected: for and the resulting predicate matches if both given predicates match; or matches if either predicate does. Most of the predicates found in RequestPredicates are compositions. For instance, RequestPredicates.GET(String) is a composition of RequestPredicates.method(HttpMethod) and RequestPredicates.path(String).

How do you run a router function in an HTTP server? A simple option is to convert a router function to an HttpHandler using one of the following:

The returned HttpHandler can then be used with a number of servers adapters by following HttpHandler for server-specific instructions.

A more advanced option is to run with a DispatcherHandler-based setup through the WebFlux Config which uses Spring configuration to declare the components quired to process requests. The WebFlux Java config declares the following infrastructure components to support functional endpoints:

The above components allow functional endpoints to fit within the DispatcherHandler request processing lifecycle, and also potentially run side by side with annotated controllers, if any are declared. It is also how functional endpoints are enabled the Spring Boot WebFlux starter.

Below is example WebFlux Java config (see DispatcherHandler for how to run):

Routes mapped by a router function can be filtered by calling RouterFunction.filter(HandlerFilterFunction), where HandlerFilterFunction is essentially a function that takes a ServerRequest and HandlerFunction, and returns a ServerResponse. The handler function parameter represents the next element in the chain: this is typically the HandlerFunction that is routed to, but can also be another FilterFunction if multiple filters are applied. With annotations, similar functionality can be achieved using @ControllerAdvice and/or a ServletFilter. Let’s add a simple security filter to our route, assuming that we have a SecurityManager that can determine whether a particular path is allowed:

You can see in this example that invoking the next.handle(ServerRequest) is optional: we only allow the handler function to be executed when access is allowed.

Same in Spring MVC

For security reasons browsers prohibit AJAX calls to resources outside the current origin. For example you could have your bank account in one tab and evil.com in another. Scripts from evil.com should not be able to make AJAX requests to your bank API with your credentials, e.g. withdrawing money from your account!

Cross-Origin Resource Sharing (CORS) is a W3C specification implemented by most browsers that allows you to specify what kind of cross domain requests are authorized rather than using less secure and less powerful workarounds based on IFRAME or JSONP.

Same in Spring MVC

The CORS specification distinguishes between preflight, simple, and actual requests. To learn how CORS works, you can read this article, among many others, or refer to the specification for more details.

Spring WebFlux HandlerMapping's provide built-in support for CORS. After successfully mapping a request to a handler, HandlerMapping's check the CORS configuration for the given request and handler and take further actions. Preflight requests are handled directly while simple and actual CORS requests are intercepted, validated, and have required CORS response headers set.

In order to enable cross-origin requests (i.e. the Origin header is present and differs from the host of the request) you need to have some explicitly declared CORS configuration. If no matching CORS configuration is found, preflight requests are rejected. No CORS headers are added to the responses of simple and actual CORS requests and consequently browsers reject them.

Each HandlerMapping can be configured individually with URL pattern based CorsConfiguration mappings. In most cases applications will use the WebFlux Java config to declare such mappings, which results in a single, global map passed to all HadlerMappping's.

Global CORS configuration at the HandlerMapping level can be combined with more fine-grained, handler-level CORS configuration. For example annotated controllers can use class or method-level @CrossOrigin annotations (other handlers can implement CorsConfigurationSource).

The rules for combining global and local configuration are generally additive — e.g. all global and all local origins. For those attributes where only a single value can be accepted such as allowCredentials and maxAge, the local overrides the global value. See CorsConfiguration#combine(CorsConfiguration) for more details.

Same in Spring MVC

The @CrossOrigin annotation enables cross-origin requests on annotated controller methods:

By default @CrossOrigin allows:

@CrossOrigin is supported at the class level too and inherited by all methods:

CrossOrigin can be used at both class and method-level:

Same in Spring MVC

In addition to fine-grained, controller method level configuration you’ll probably want to define some global CORS configuration too. You can set URL-based CorsConfiguration mappings individually on any HandlerMapping. Most applications however will use the WebFlux Java config to do that.

By default global configuration enables the following:

To enable CORS in the WebFlux Java config, use the CorsRegistry callback:

Same in Spring MVC

You can apply CORS support through the built-in CorsWebFilter, which is a good fit with functional endpoints.

To configure the filter, you can declare a CorsWebFilter bean and pass a CorsConfigurationSource to its constructor:

Same in Spring MVC

Thymeleaf is modern server-side Java template engine that emphasizes natural HTML templates that can be previewed in a browser by double-clicking, which is very helpful for independent work on UI templates, e.g. by designer, without the need for a running server. Thymeleaf offers an extensive set of features and it is actively developed and maintained. For a more complete introduction see the Thymeleaf project home page.

The Thymeleaf integration with Spring WebFlux is managed by the Thymeleaf project. The configuration involves a few bean declarations such as SpringResourceTemplateResolver, SpringWebFluxTemplateEngine, and ThymeleafReactiveViewResolver. For more details see Thymeleaf+Spring and the WebFlux integration announcement.

Same in Spring MVC

Apache FreeMarker is a template engine for generating any kind of text output from HTML to email, and others. The Spring Framework has a built-in integration for using Spring WebFlux with FreeMarker templates.

Same in Spring MVC

The Spring Framework has a built-in integration for using Spring WebFlux with any templating library that can run on top of the JSR-223 Java scripting engine. Below is a list of templating libraries we’ve tested on different script engines:

Same in Spring MVC

For Content negotiation purposes it is useful to be able to alternate between rendering a model with an HTML template or as other formats such as JSON or XML, depending on the content type requested by the client. To support this Spring WebFlux provides the HttpMessageWriterView that can be used to plug in any of the available HTTP Message Codecs from spring-web such as Jackson2JsonEncoder, Jackson2SmileEncoder, or Jaxb2XmlEncoder.

Unlike other view technologies, HttpMessageWriterView does not require a ViewResolver, but instead is configured as a default view. You can configure one more such default views, wrapping different HttpMessageWriter's or Encoder's. The one that matches the requested content type is used at runtime.

In most cases a model will contain multiple attributes. In order to determine which one to serialize, HttpMessageWriterView can be configured with the name of the model attribute to use render, of if the model contains only one attribute, it will be used.

Same in Spring MVC

Use the @EnableWebFlux annotation in your Java config:

The above registers a number of Spring WebFlux infrastructure beans also adapting to dependencies available on the classpath — for JSON, XML, etc.

Same in Spring MVC

In your Java config implement the WebFluxConfigurer interface:

Same in Spring MVC

By default formatters for Number and Date types are installed, including support for the @NumberFormat and @DateTimeFormat annotations. Full support for the Joda Time formatting library is also installed if Joda Time is present on the classpath.

To register custom formatters and converters:

Same in Spring MVC

By default if Bean Validation is present on the classpath — e.g. Hibernate Validator, the LocalValidatorFactoryBean is registered as a global Validator for use with @Valid and Validated on @Controller method arguments.

In your Java config, you can customize the global Validator instance:

Note that you can also register Validator's locally:

Same in Spring MVC

You can configure how Spring WebFlux determines the requested media types for @Controller's from the request. By default only the "Accept" header is checked but you can also enable a query parameter based strategy.

To customize the requested content type resolution:

Same in Spring MVC

To customize how the request and response body are read and written:

ServerCodecConfigurer provides a set of default readers and writers. You can use it to add more readers and writers, customize the default ones, or replace the default ones completely.

For Jackson JSON and XML, consider using the Jackson2ObjectMapperBuilder which customizes Jackson’s default properties with the following ones:

It also automatically registers the following well-known modules if they are detected on the classpath:

Same in Spring MVC

To configure view resolution:

The ViewResolverRegistry has shortcuts for view technologies that the Spring Framework integrates with. Here is an example with FreeMarker which also requires configuring the underlying FreeMarker view technology:

You can also plug in any ViewResolver implementation:

To support Content negotiation and rendering other formats through view resolution, besides HTML, you can configure one or more default views based on the HttpMessageWriterView implementation which accepts any of the available HTTP Message Codecs from spring-web:

See View Technologies for more on the view technologies integrated with Spring WebFlux.

Same in Spring MVC

This option provides a convenient way to serve static resources from a list of Resource-based locations.

In the example below, given a request that starts with "/resources", the relative path is used to find and serve static resources relative to "/static" on the classpath. Resources will be served with a 1-year future expiration to ensure maximum use of the browser cache and a reduction in HTTP requests made by the browser. The Last-Modified header is also evaluated and if present a 304 status code is returned.

The resource handler also supports a chain of ResourceResolver's and ResourceTransformer's. which can be used to create a toolchain for working with optimized resources.

The VersionResourceResolver can be used for versioned resource URLs based on an MD5 hash computed from the content, a fixed application version, or other. A ContentVersionStrategy (MD5 hash) is a good choice with some notable exceptions such as JavaScript resources used with a module loader.

For example in your Java config;

You can use ResourceUrlProvider to rewrite URLs and apply the full chain of resolvers and transformers — e.g. to insert versions. The WebFlux config provides a ResourceUrlProvider so it can be injected into others.

Unlike Spring MVC at present in WebFlux there is no way to transparently rewrite static resource URLs since there are no view technologies that can make use of a non-blocking chain of resolvers and transformers (e.g. resources on Amazon S3). When serving only local resources the workaround is to use ResourceUrlProvider directly (e.g. through a custom tag) and block for 0 seconds.

WebJars is also supported via WebJarsResourceResolver and automatically registered when "org.webjars:webjars-locator" is present on the classpath. The resolver can re-write URLs to include the version of the jar and can also match to incoming URLs without versions — e.g. "/jquery/jquery.min.js" to "/jquery/1.2.0/jquery.min.js".

Same in Spring MVC

Spring WebFlux uses parsed representation of path patterns — i.e. PathPattern, and also the incoming request path — i.e. RequestPath, which eliminates the need to indicate whether to decode the request path, or remove semicolon content, since PathPattern can now access decoded path segment values and match safely.

Spring WebFlux also does not support suffix pattern matching so effectively there are only two minor options to customize related to path matching — whether to match trailing slashes (true by default) and whether the match is case-sensitive (false).

To customize those options:

Same in Spring MVC

@EnableWebFlux imports DelegatingWebFluxConfiguration that (1) provides default Spring configuration for WebFlux applications and (2) detects and delegates to WebFluxConfigurer's to customize that configuration.

For advanced mode, remove @EnableWebFlux and extend directly from DelegatingWebFluxConfiguration instead of implementing WebFluxConfigurer:

You can keep existing methods in WebConfig but you can now also override bean declarations from the base class and you can still have any number of other WebMvcConfigurer's on the classpath.

To send form data, provide a MultiValueMap<String, String> as the body. Note that the content is automatically set to "application/x-www-form-urlencoded" by the FormHttpMessageWriter:

You can also supply form data in-line via BodyInserters:

To send multipart data, provide a MultiValueMap<String, ?> where values are either an Object representing the part body, or an HttpEntity representing the part body and headers. MultipartBodyBuilder can be used to build the parts:

Note that the content type for each part is automatically set based on the extension of the file being written or the type of Object. If you prefer you can also be more explicit and specify the content type for each part.

You can also supply multipart data in-line via BodyInserters:

Even though WebSocket is designed to be HTTP compatible and starts with an HTTP request, it is important to understand that the two protocols lead to very different architectures and application programming models.

In HTTP and REST, an application is modeled as many URLs. To interact with the application clients access those URLs, request-response style. Servers route requests to the appropriate handler based on the HTTP URL, method, and headers.

By contrast in WebSockets there is usually just one URL for the initial connect and subsequently all application messages flow on that same TCP connection. This points to an entirely different asynchronous, event-driven, messaging architecture.

WebSocket is also a low-level transport protocol which unlike HTTP does not prescribe any semantics to the content of messages. That means there is no way to route or process a message unless client and server agree on message semantics.

WebSocket clients and servers can negotiate the use of a higher-level, messaging protocol (e.g. STOMP), via the "Sec-WebSocket-Protocol" header on the HTTP handshake request, or in the absence of that they need to come up with their own conventions.

WebSockets can make a web page dynamic and interactive. However in many cases a combination of Ajax and HTTP streaming and/or long polling could provide a simple and effective solution.

For example news, mail, and social feeds need to update dynamically but it may be perfectly okay to do so every few minutes. Collaboration, games, and financial apps on the other hand need to be much closer to real time.

Latency alone is not a deciding factor. If the volume of messages is relatively low (e.g. monitoring network failures) HTTP streaming or polling may provide an effective solution. It is the combination of low latency, high frequency and high volume that make the best case for the use WebSocket.

Keep in mind also that over the Internet, restrictive proxies outside your control, may preclude WebSocket interactions either because they are not configured to pass on the Upgrade header or because they close long lived connections that appear idle? This means that the use of WebSocket for internal applications within the firewall is a more straight-forward decision than it is for public facing applications.

Same in Servlet stack

Creating a WebSocket server is as simple as implementing WebSocketHandler:

Spring WebFlux provides a WebSocketHandlerAdapter that can adapt WebSocket requests and use the above handler to handle the resulting WebSocket session. After the adapter is registered as a bean, you can map requests to your handler, for example using SimpleUrlHandlerMapping. This is shown below:

Same in Servlet stack

WebSocketHandlerAdapter does not perform WebSocket handshakes itself. Instead it delegates to an instance of WebSocketService. The default WebSocketService implementation is HandshakeWebSocketService.

The HandshakeWebSocketService performs basic checks on the WebSocket request and delegates to a server-specific RequestUpgradeStrategy. At present upgrade strategies exist for Reactor Netty, Tomcat, Jetty, and Undertow.

Same in Servlet stack

The RequestUpgradeStrategy for each server exposes the WebSocket-related configuration options available for the underlying WebSocket engine. Below is an example of setting WebSocket options when running on Tomcat:

Check the upgrade strategy for your server to see what options are available. Currently only Tomcat and Jetty expose such options.

Same in Servlet stack

The easiest way to configure CORS and restrict access to a WebSocket endpoint is to have your WebSocketHandler implement CorsConfigurationSource and return a CorsConfiguraiton with allowed origins, headers, etc. If for any reason you can’t do that, you can also set the corsConfigurations property on the SimpleUrlHandler to specify CORS settings by URL pattern. If both are specified they’re combined via the combine method on CorsConfiguration.