0
# Quarkus Undertow Extension
1

2
A Quarkus extension providing servlet support through the Undertow web server. This extension enables traditional Java web applications using servlet APIs (Jakarta Servlet) while maintaining Quarkus' cloud-native features including fast startup times, low memory usage, and native compilation support.
3

4
## Package Information
5

6
- **Package Name**: quarkus-undertow
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Installation**: Add dependency to your Quarkus project:
10

11
```xml
12
<dependency>
13
    <groupId>io.quarkus</groupId>
14
    <artifactId>quarkus-undertow</artifactId>
15
</dependency>
16
```
17

18
## Core Imports
19

20
```java
21
import io.quarkus.undertow.runtime.ServletRuntimeConfig;
22
import io.quarkus.undertow.runtime.UndertowDeploymentRecorder;
23
```
24

25
For CDI integration:
26

27
```java
28
import jakarta.servlet.http.HttpServletRequest;
29
import jakarta.servlet.http.HttpServletResponse;
30
import jakarta.servlet.http.HttpSession;
31
import jakarta.inject.Inject;
32
```
33

34
For build-time configuration:
35

36
```java
37
import io.quarkus.undertow.spi.ServletBuildItem;
38
import io.quarkus.undertow.spi.FilterBuildItem;
39
import io.quarkus.undertow.spi.ListenerBuildItem;
40
```
41

42
## Basic Usage
43

44
### Adding Servlets
45

46
```java
47
@WebServlet(urlPatterns = "/hello")
48
public class HelloServlet extends HttpServlet {
49
    @Override
50
    protected void doGet(HttpServletRequest req, HttpServletResponse resp) 
51
            throws ServletException, IOException {
52
        resp.setContentType("text/plain");
53
        resp.getWriter().write("Hello from Quarkus Undertow!");
54
    }
55
}
56
```
57

58
### CDI Integration
59

60
```java
61
@ApplicationScoped
62
public class ServletService {
63
    
64
    @Inject
65
    HttpServletRequest request;
66
    
67
    @Inject
68
    HttpServletResponse response;
69
    
70
    public void handleRequest() {
71
        // Use injected servlet objects
72
        String method = request.getMethod();
73
        response.setHeader("X-Processed-By", "Quarkus");
74
    }
75
}
76
```
77

78
### Build-time Configuration
79

80
```java
81
@BuildStep
82
ServletBuildItem createServlet() {
83
    return ServletBuildItem.builder("my-servlet", MyServlet.class.getName())
84
            .addMapping("/api/custom")
85
            .setAsyncSupported(true)
86
            .build();
87
}
88
```
89

90
## Architecture
91

92
The Quarkus Undertow extension is structured as a multi-module Maven project with three main components:
93

94
- **Runtime Module**: Provides servlet container integration, CDI producers, and runtime configuration
95
- **SPI Module**: Defines build items for extension developers to register servlets, filters, and listeners
96
- **Deployment Module**: Handles build-time processing and Undertow server configuration
97

98
## Capabilities
99

100
### Runtime API
101

102
Core runtime functionality including servlet container management, CDI integration, and session handling.
103

104
```java { .api }
105
// Runtime configuration interface
106
@ConfigMapping(prefix = "quarkus.servlet")
107
public interface ServletRuntimeConfig {
108
    Optional<MemorySize> bufferSize();
109
    Optional<Boolean> directBuffers();
110
    int maxParameters();
111
}
112

113
// CDI producers for servlet objects  
114
@Singleton
115
public class ServletProducer {
116
    @Produces @RequestScoped
117
    public HttpServletRequest request();
118
    
119
    @Produces @RequestScoped
120
    public HttpServletResponse response();
121
    
122
    @Produces @RequestScoped
123
    public HttpSession session();
124
}
125
```
126

127
[Runtime API](./runtime-api.md)
128

129
### Build-time API
130

131
Extension points for registering servlets, filters, and listeners during application build.
132

133
```java { .api }
134
// Register servlets at build time
135
public class ServletBuildItem extends MultiBuildItem {
136
    public static Builder builder(String name, String servletClass);
137
    public String getName();
138
    public String getServletClass();
139
    public List<String> getMappings();
140
}
141

142
// Register filters at build time
143
public class FilterBuildItem extends MultiBuildItem {
144
    public static Builder builder(String name, String filterClass);
145
    public String getName();
146
    public String getFilterClass();
147
    public List<FilterMappingInfo> getMappings();
148
}
149
```
150

151
[Build-time API](./build-time-api.md)
152

153
### Configuration
154

155
Runtime and build-time configuration options for servlet behavior, security, and performance tuning.
156

157
```java { .api }
158
// Runtime configuration properties (quarkus.servlet.*)
159
public interface ServletRuntimeConfig {
160
    @WithDefault("1000")
161
    int maxParameters();
162
    
163
    Optional<MemorySize> bufferSize();
164
    Optional<Boolean> directBuffers();
165
}
166
```
167

168
[Configuration](./configuration.md)