This version is still in development and is not considered stable yet. For the latest stable version, please use Spring Framework 6.2.0!

DispatcherHandler

See equivalent in the Servlet stack

Spring WebFlux, similarly to Spring MVC, is designed around the front controller pattern, where a central WebHandler, the DispatcherHandler, provides a shared algorithm for request processing, while actual work is performed by configurable, delegate components. This model is flexible and supports diverse workflows.

DispatcherHandler discovers the delegate components it needs from Spring configuration. It is also designed to be a Spring bean itself and implements ApplicationContextAware for access to the context in which it runs. If DispatcherHandler is declared with a bean name of webHandler, it is, in turn, discovered by WebHttpHandlerBuilder, which puts together a request-processing chain, as described in WebHandler API.

Spring configuration in a WebFlux application typically contains:

The configuration is given to WebHttpHandlerBuilder to build the processing chain, as the following example shows:

  • Java

  • Kotlin

ApplicationContext context = ...
HttpHandler handler = WebHttpHandlerBuilder.applicationContext(context).build();
val context: ApplicationContext = ...
val handler = WebHttpHandlerBuilder.applicationContext(context).build()

The resulting HttpHandler is ready for use with a server adapter.

Special Bean Types

See equivalent in the Servlet stack

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 them, or replace them.

The following table 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).

Bean type Explanation

HandlerMapping

Map a request to a handler. The mapping is based on some criteria, the details of which vary by HandlerMapping implementation — annotated controllers, simple URL pattern mappings, and others.

The main HandlerMapping implementations are RequestMappingHandlerMapping for @RequestMapping annotated methods, RouterFunctionMapping for functional endpoint routes, and SimpleUrlHandlerMapping for explicit registrations of URI path patterns and WebHandler instances.

HandlerAdapter

Help the DispatcherHandler to invoke a handler mapped to a request regardless of how the handler is actually invoked. For example, invoking an annotated controller requires resolving annotations. The main purpose of a HandlerAdapter is to shield the DispatcherHandler from such details.

HandlerResultHandler

Process the result from the handler invocation and finalize the response. See Result Handling.

WebFlux Config

See equivalent in the Servlet stack

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.

Spring Boot relies on the WebFlux config to configure Spring WebFlux and also provides many extra convenient options.

Processing

See equivalent in the Servlet stack

DispatcherHandler processes requests as follows:

  • Each HandlerMapping is asked to find a matching handler, and the first match is used.

  • If a handler is found, it is run through an appropriate HandlerAdapter, which exposes the return value from the execution as HandlerResult.

  • The HandlerResult is given to an appropriate HandlerResultHandler to complete processing by writing to the response directly or by using a view to render.

Result Handling

The return value from the invocation of a handler, through a HandlerAdapter, is wrapped as a HandlerResult, along with some additional context, and passed to the first HandlerResultHandler that claims support for it. The following table shows the available HandlerResultHandler implementations, all of which are declared in the WebFlux Config:

Result Handler Type Return Values Default Order

ResponseEntityResultHandler

ResponseEntity, typically from @Controller instances.

0

ServerResponseResultHandler

ServerResponse, typically from functional endpoints.

0

ResponseBodyResultHandler

Handle return values from @ResponseBody methods or @RestController classes.

100

ViewResolutionResultHandler

CharSequence, View, Model, Map, Rendering, or any other Object is treated as a model attribute.

See also View Resolution.

Integer.MAX_VALUE

Exceptions

See equivalent in the Servlet stack

HandlerAdapter implementations can handle internally exceptions from invoking a request handler, such as a controller method. However, an exception may be deferred if the request handler returns an asynchronous value.

A HandlerAdapter may expose its exception handling mechanism as a DispatchExceptionHandler set on the HandlerResult it returns. When that’s set, DispatcherHandler will also apply it to the handling of the result.

A HandlerAdapter may also choose to implement DispatchExceptionHandler. In that case DispatcherHandler will apply it to exceptions that arise before a handler is mapped, for example, during handler mapping, or earlier, for example, in a WebFilter.

See also Exceptions in the “Annotated Controller” section or Exceptions in the WebHandler API section.

View Resolution

See equivalent in the Servlet stack

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 instances to map a String (representing a logical view name) to a View instance. The View is then used to render the response.

Web applications need to use a View rendering library to support this use case.

Handling

See equivalent in the Servlet stack

The HandlerResult passed into ViewResolutionResultHandler contains the return value from the handler and the model that contains attributes added during request handling. The return value is processed as one of the following:

  • String, CharSequence: A logical view name to be resolved to a View through the list of configured ViewResolver implementations.

  • void: Select a default view name based on the request path, minus the leading and trailing slash, and resolve it to a View. The same also happens when a view name was not provided (for example, model attribute was returned) or an async return value (for example, Mono completed empty).

  • Rendering: API for view resolution scenarios. Explore the options in your IDE with code completion.

  • Model, Map: Extra model attributes to be added to the model for the request.

  • Any other: Any other return value (except for simple types, as determined by BeanUtils#isSimpleProperty) is treated as a model attribute to be added to the model. The attribute name is derived from the class name by using conventions, unless a handler method @ModelAttribute annotation is present.

The model can contain asynchronous, reactive types (for example, from Reactor or RxJava). Prior to rendering, AbstractView resolves such model attributes into concrete values and updates the model. Single-value reactive types are resolved to a single value or no value (if empty), while multi-value reactive types (for example, Flux<T>) are collected and resolved to List<T>.

To configure view resolution is as simple as adding a ViewResolutionResultHandler bean to your Spring configuration. WebFlux Config provides a dedicated configuration API for view resolution.

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

Redirecting

See equivalent in the Servlet stack

The special redirect: prefix in a view name lets you perform a redirect. The UrlBasedViewResolver (and sub-classes) recognize this as an instruction that a redirect is needed. The rest of the view name is the redirect URL.

The net effect is the same as if the controller had returned a RedirectView or Rendering.redirectTo("abc").build(), but now the controller itself can operate in terms of logical view names. A view name such as redirect:/some/resource is relative to the current application, while a view name such as redirect:https://example.com/arbitrary/path redirects to an absolute URL.

Unlike the Servlet stack, Spring WebFlux does not support "FORWARD" dispatches, so forward: prefixes are not supported as a result.

Content Negotiation

See equivalent in the Servlet stack

ViewResolutionResultHandler supports content negotiation. It compares the request media types with the media types supported by each selected View. The first View that supports the requested media type(s) is used.

In order to support media types such as JSON and XML, Spring WebFlux provides HttpMessageWriterView, which is a special View that renders through an HttpMessageWriter. Typically, you would configure these as default views through the WebFlux Configuration. Default views are always selected and used if they match the requested media type.