Mastering Spring Web Reactive: HttpHandler, WebHandler, and Server Integration

Overview

Spring Web 2.4.12 provides reactive web support through two core abstractions: HttpHandler and WebHandler .

HttpHandler

HttpHandler is a minimal protocol with a single method to process HTTP requests and responses, offering non‑blocking I/O and back‑pressure. It adapts to various server APIs such as Reactor Netty, Undertow, Tomcat, Jetty, and any Servlet 3.1+ container.

Supported server adapters include:

Reactor Netty – ReactorHttpHandlerAdapter

Undertow – UndertowHttpHandlerAdapter

Tomcat – TomcatHttpHandlerAdapter

Jetty – JettyHttpHandlerAdapter

Servlet 3.1+ container – ServletHttpHandlerAdapter via AbstractReactiveWebInitializer

Example for Reactor Netty:

<code>HttpHandler handler = WebHttpHandlerBuilder.applicationContext(this.applicationContext).build();
ReactorHttpHandlerAdapter adapter = new ReactorHttpHandlerAdapter(handler);
HttpServer.create().host(host).port(port).handle(adapter).bind().block();</code>

Example for Undertow:

<code>HttpHandler handler = WebHttpHandlerBuilder.applicationContext(this.applicationContext).build();
UndertowHttpHandlerAdapter adapter = new UndertowHttpHandlerAdapter(handler);
Undertow server = Undertow.builder().addHttpListener(port, host).setHandler(adapter).build();
server.start();</code>

Example for Tomcat:

<code>HttpHandler handler = WebHttpHandlerBuilder.applicationContext(this.applicationContext).build();
Servlet servlet = new TomcatHttpHandlerAdapter(handler);
Tomcat server = new Tomcat();
File base = new File(System.getProperty("java.io.tmpdir"));
Context rootContext = server.addContext("", base.getAbsolutePath());
Tomcat.addServlet(rootContext, "main", servlet);
rootContext.addServletMappingDecoded("/", "main");
server.setHost(host);
server.setPort(port);
server.start();</code>

Example for Jetty:

<code>HttpHandler handler = WebHttpHandlerBuilder.applicationContext(this.applicationContext).build();
Servlet servlet = new JettyHttpHandlerAdapter(handler);
Server server = new Server();
ServletContextHandler contextHandler = new ServletContextHandler(server, "");
contextHandler.addServlet(new ServletHolder(servlet), "/");
contextHandler.start();
ServerConnector connector = new ServerConnector(server);
connector.setHost(host);
connector.setPort(port);
server.addConnector(connector);
server.start();</code>

WebHandler

WebHandler builds on HttpHandler and provides a richer API that includes WebExceptionHandler , WebFilter , and a single WebHandler component. It is assembled by WebHttpHandlerBuilder from the Spring ApplicationContext.

Key capabilities include user session handling, request attributes, locale resolution, access to parsed form data, multipart data, and more.

Special bean types detected by WebHttpHandlerBuilder

WebExceptionHandler (0..N) – handles exceptions from filters and the target handler.

WebFilter (0..N) – intercepts requests before and after the handler.

WebHandler (1) – the core request processor.

WebSessionManager (0..1) – manages WebSession; default is DefaultWebSessionManager .

ServerCodecConfigurer (0..1) – provides HttpMessageReader / HttpMessageWriter for form and multipart data.

LocaleContextResolver (0..1) – resolves LocaleContext ; default is AcceptHeaderLocaleContextResolver .

ForwardedHeaderTransformer (0..1) – processes forwarded headers; not used by default.

Form and multipart data

ServerWebExchange exposes methods to retrieve form and multipart data:

<code>Mono<MultiValueMap<String,String>> getFormData();</code>

<code>Mono<MultiValueMap<String,Part>> getMultipartData();</code>

The default implementation uses FormHttpMessageReader for application/x-www-form-urlencoded and DefaultPartHttpMessageReader (or SynchronossPartHttpMessageReader ) for multipart content, both configured via ServerCodecConfigurer .

Filters and Exception Handlers

WebFilter can be declared as a Spring bean and ordered with @Order or by implementing Ordered . WebExceptionHandler implementations such as ResponseStatusExceptionHandler and WebFluxResponseStatusExceptionHandler map exceptions to HTTP status codes.

Codecs

Spring Web and Spring Core provide non‑blocking Encoder / Decoder abstractions, HttpMessageReader / HttpMessageWriter , and DataBuffer to handle various byte representations (e.g., Netty ByteBuf , java.nio.ByteBuffer ).

Spring Core supplies basic encoders/decoders for byte[] , ByteBuffer , DataBuffer , Resource , and String . Spring Web adds JSON (Jackson), Smile, JAXB2, Protocol Buffers, and specialized readers/writers for form data, multipart content, and server‑sent events.