Undertow — High-Performance Non-Blocking Java Web Server

Introduction

Undertow is a flexible, high-performance web server from Red Hat built on top of Java NIO. It serves as the core web engine inside WildFly and JBoss EAP, but it works equally well as an embedded server in standalone applications. Its handler-chain architecture keeps overhead minimal while supporting servlet deployments, WebSocket, and HTTP/2.

What Undertow Does

• Handles HTTP/1.1 and HTTP/2 with a non-blocking I/O core based on XNIO
• Provides a lightweight handler API for building request processing pipelines
• Implements the Jakarta Servlet 6.0 specification for traditional web applications
• Supports WebSocket with both annotated and programmatic APIs
• Embeds into any Java application as a library with no external dependencies

Architecture Overview

Undertow's request processing is based on a chain of HttpHandler objects. Each handler receives an HttpServerExchange and either completes the response or delegates to the next handler. Listeners (HTTP, HTTPS, AJP) accept connections and route them through the handler chain. The I/O layer uses the XNIO framework for asynchronous socket operations, allowing a small thread pool to serve thousands of concurrent connections. Servlet support is layered on top via a DeploymentManager that wraps servlet filters and servlets as handlers.

Self-Hosting & Configuration

• Add undertow-core and optionally undertow-servlet to your Maven or Gradle project
• Build a server with Undertow.builder(), attach listeners and handlers, then call build().start()
• For servlet apps, use DeploymentInfo to register servlets and filters programmatically
• Configure worker threads, I/O threads, and buffer sizes through builder options
• Enable HTTP/2 by setting setServerOption(UndertowOptions.ENABLE_HTTP2, true) on the listener

Key Features

• Non-blocking I/O core delivers high throughput with low resource consumption
• Composable handler chain replaces monolithic servlet filters with reusable components
• Reverse proxy handler built in for load balancing and routing to backend services
• WebSocket support with per-message compression and sub-protocols
• Small JAR footprint suitable for embedded microservice deployments

Comparison with Similar Tools

• Jetty — Similar embeddable server; Undertow's handler API is lower-level while Jetty offers more built-in servlet tooling
• Tomcat — The most popular standalone servlet container; Undertow is designed as embedded-first
• Netty — General-purpose network framework; Undertow adds HTTP semantics and servlet support on top
• Vert.x — Reactive toolkit with its own HTTP server; Undertow is focused purely on serving HTTP
• Nginx — Native C-based reverse proxy; Undertow is a Java server often placed behind Nginx

FAQ

Q: Is Undertow only for WildFly? A: No. Undertow is a standalone library. WildFly embeds it, but you can use it independently in any Java application.

Q: Can I deploy WAR files on Undertow? A: Yes. Use the servlet deployment API to programmatically deploy servlet-based applications without a full app server.

Q: Does Undertow support HTTP/2? A: Yes. HTTP/2 is supported over both TLS (h2) and cleartext (h2c) via a server option.

Q: How does Undertow handle blocking operations? A: Dispatch the exchange to a worker thread using exchange.dispatch() before performing blocking I/O in the handler.

Sources

• https://github.com/undertow-io/undertow
• https://undertow.io/documentation.html