Spring Web Reactive | 1. Spring WebFlux | 1.3. DispatcherHandler

Tags:

Web MVC

Like Spring MVC, Spring WebFlux is designed around the front-controller pattern. Its central WebHandler, DispatcherHandler, provides a shared request-processing algorithm while configurable delegate components perform the actual work.

DispatcherHandler discovers required delegate components from Spring configuration. It is a Spring bean and implements ApplicationContextAware to access its runtime context. When declared with the bean name webHandler, WebHttpHandlerBuilder assembles a request-processing chain according to the WebHandler API.

WebFlux configuration typically includes:

Java:

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

Kotlin:

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

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

1.3.1. Special Bean Types

DispatcherHandler delegates request processing and response rendering to special Spring-managed beans. Built-in implementations are provided, but you can customize, extend, or replace them.

Bean type Description
HandlerMapping Maps requests to handlers according to implementation-specific criteria. Main implementations include RequestMappingHandlerMapping for @RequestMapping, RouterFunctionMapping for functional endpoints, and SimpleUrlHandlerMapping for explicit URI-pattern mappings.
HandlerAdapter Lets DispatcherHandler invoke a mapped handler without depending on invocation details, such as annotation resolvers for annotated controllers.
HandlerResultHandler Processes invocation results and finalizes responses. See Result Handling.

1.3.2. WebFlux Configuration

Applications can declare the infrastructure beans needed for request handling directly, but WebFlux configuration is usually the best starting point. It declares required beans and provides high-level callbacks for customization.

Spring Boot configures Spring WebFlux based on WebFlux configuration and provides additional convenient options.

1.3.3. Processing

DispatcherHandler processes requests as follows:

  • Ask each HandlerMapping for a matching handler and use the first match.
  • Invoke the handler through an appropriate HandlerAdapter, which returns a HandlerResult.
  • Pass the result to an appropriate HandlerResultHandler to create a response directly or render a view.

1.3.4. Result Handling

The return value from a handler invocation is wrapped in a HandlerResult with additional context and passed to the first supporting HandlerResultHandler.

Result handler type Return values Default order
ResponseEntityResultHandler ResponseEntity, usually from @Controller instances. 0
ServerResponseResultHandler ServerResponse, usually from functional endpoints. 0
ResponseBodyResultHandler Return values from @ResponseBody methods or @RestController classes. 100
ViewResolutionResultHandler CharSequence, View, Model, Map, Rendering, or other objects treated as model attributes. Integer.MAX_VALUE

1.3.5. Exceptions

A HandlerResult returned by a HandlerAdapter exposes an error-handling function for failures while invoking a handler or processing its return value. If an error signal occurs before a reactive return type produces data, the function can change the response status.

This supports @ExceptionHandler methods in @Controller classes. Unlike Spring MVC, WebFlux cannot use @ControllerAdvice to handle exceptions raised before a handler is selected.

1.3.6. View Resolution

View resolution renders browser responses with HTML templates and models without coupling to a specific view technology. A dedicated HandlerResultHandler maps logical view-name strings to View instances through ViewResolver.

Handling

A HandlerResult passed to ViewResolutionResultHandler includes the handler return value and model attributes accumulated during request processing. Return values are handled as follows:

  • String, CharSequence: A logical view name resolved through configured ViewResolver implementations.
  • void: Use a default view name based on the request path. This also applies when no view name is provided or an asynchronous return value completes empty.
  • Rendering: API for view-resolution scenarios.
  • Model, Map: Additional model attributes.
  • Other objects: Non-simple values become model attributes. Unless @ModelAttribute specifies a name, it is derived from the class name through Conventions.

Models can contain asynchronous reactive types. AbstractView resolves them before rendering: a single-value type becomes one value or no value, while a multi-value type such as Flux<T> becomes a collected List<T>.

Add a ViewResolutionResultHandler bean to configure view resolution. WebFlux configuration also provides a dedicated API.

Redirecting

The special redirect: prefix redirects to the remaining URL. redirect:/some/resource is relative to the current application, while redirect:https://example.com/arbitrary/path redirects to an absolute URL. This has the same effect as returning RedirectView or Rendering.redirectTo("abc").build().

Content Negotiation

ViewResolutionResultHandler compares the requested media type with supported types and selects the first matching View. For formats such as JSON or XML, Spring WebFlux provides HttpMessageWriterView, which renders through an HttpMessageWriter.