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 — HTTP abstractions, Reactive Streams server adapters, reactive codecs, and a core Web API whose role is comparable to the Servlet API but with non-blocking semantics.

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:

You can also deploy as a WAR to any Servlet 3.1 container by wrapping the handler with ServletHttpHandlerAdapter as a Servlet.

HttpHandler is the basis for running on different servers. On that base the WebHandler API provides a slightly higher level processing chain of exception handlers (WebExceptionHandler), filters (WebFilter), and a target handler (WebHandler).

All components work on ServerWebExchange — a container for the HTTP request and response that also adds request attributes, session attributes, access to form data, multipart data, and more.

The processing chain can be put together with WebHttpHandlerBuilder which builds an HttpHandler that in turn can be run with a server adapter. To use the builder either add components individually or point to an ApplicationContext to have the following detected:

The spring-web module provides HttpMessageReader and HttpMessageWriter for encoding and decoding the HTTP request and response body with Reactive Streams. It builds on lower level contracts from spring-core:

Basic Encoder and Decoder implementations exist in spring-core but spring-web adds more for JSON, XML, and other formats. You can wrap any Encoder and Decoder as a reader or writer with EncoderHttpMessageWriter and DecoderHttpMessageReader. There are some additional, web-only reader and writer implementations for server-sent events, form data, and more.

Finally, ClientCodecConfigurer and ServerCodecConfigurer can be used to initialize a list of readers and writers. They include support for classpath detection and a of defaults along with the ability to override or replace those defaults.

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 one of the framework contracts listed in the table below. Spring WebFlux provides built-in implementations of these contracts but you can also customize, extend, or replace them.

Same in Spring MVC

The DispatcherHandler processes requests as follows:

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:

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 shortcut variants are composed annotations — themselves annotated with @RequestMapping. They are commonly used at the method level. At the class level an @RequestMapping is more useful for expressing shared 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.

Incoming HTTP requests are handled by a HandlerFunction, which is essentially a function that takes a ServerRequest and returns a Mono<ServerResponse>. The annotation counterpart to a handler function is 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 (see Reactive Libraries).

ServerRequest gives access to various HTTP request elements: the method, URI, query parameters, and — through the separate ServerRequest.Headers interface — the headers. 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 above — bodyToMono and bodyToFlux, 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 be replaced with:

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; otherwise it returns an empty Mono. The RouterFunction has a similar purpose as the @RequestMapping annotation in @Controller classes.

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 via RouterFunctions.toHttpHandler(RouterFunction). The HttpHandler can then be used with a number of servers adapters. See HttpHandler for server-specific instructions.

it is also possible to run with a DispatcherHandler setup — side by side with annotated controllers. The easiest way to do that is through the WebFlux Java Config which creates the necessary configuration to handle requests with router and handler functions.

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

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:

Note that FreeMarker also requires configuration of the underlying view technology:

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 ResourceResolver'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 transparely rewrite static resource URLs since the 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.

The retrieve() method is the easiest way to get a response body and decode it:

You can also get a stream of objects decoded from the response:

By default, responses with 4xx or 5xx status codes result in an error of type WebClientResponseException but you can customize that:

The exchange() method provides more control. The below example is equivalent to retrieve() but also provides access to the ClientResponse:

At this level you can also create a full ResponseEntity:

Note that unlike retrieve(), with exchange() there are no automatic error signals for 4xx and 5xx responses. You have to check the status code and decide how to proceed.

The request body can be encoded from an Object:

You can also have a stream of objects encoded:

Or if you have the actual value, use the syncBody shortcut method:

A simple way to create WebClient is through the static factory methods create() and create(String) with a base URL for all requests. You can also use WebClient.builder() for access to more options.

To customize the underlying HTTP client:

To customize the HTTP codecs used for encoding and decoding HTTP messages:

The builder can be used to insert Filters.

Explore the WebClient.Builder in your IDE for other options related to URI building, default headers (and cookies), and more.

After the WebClient is built, you can always obtain a new builder from it, in order to build a new WebClient, based on, but without affecting the current instance:

WebClient supports interception style request filtering:

ExchangeFilterFunctions provides a filter for basic authentication:

You can also mutate an existing WebClient instance without affecting the original: