0
# Runtime API
1

2
The runtime module provides the core servlet container integration, CDI support, and session management capabilities for Quarkus applications.
3

4
## Core Imports
5

6
```java
7
import io.quarkus.undertow.runtime.ServletRuntimeConfig;
8
import io.quarkus.undertow.runtime.UndertowDeploymentRecorder;
9
import io.quarkus.undertow.runtime.ServletProducer;
10
import io.quarkus.undertow.runtime.HttpSessionContext;
11
```
12

13
## Configuration
14

15
### ServletRuntimeConfig
16

17
Runtime configuration interface for servlet settings.
18

19
```java { .api }
20
@ConfigMapping(prefix = "quarkus.servlet")
21
public interface ServletRuntimeConfig {
22
    /**
23
     * Buffer size for servlet operations
24
     */
25
    Optional<MemorySize> bufferSize();
26
    
27
    /**
28
     * Use direct buffers setting
29
     */
30
    Optional<Boolean> directBuffers();
31
    
32
    /**
33
     * Maximum HTTP request parameters (default: 1000)
34
     */
35
    @WithDefault("1000")
36
    int maxParameters();
37
}
38
```
39

40
## Core Runtime Classes
41

42
### UndertowDeploymentRecorder
43

44
Main recorder class responsible for servlet deployment and configuration during application startup.
45

46
```java { .api }
47
public class UndertowDeploymentRecorder {
48
    public static final HttpHandler ROOT_HANDLER;
49
    public static final int DEFAULT_BUFFER_SIZE;
50
    public static final boolean DEFAULT_DIRECT_BUFFERS;
51
    
52
    /**
53
     * Create servlet deployment
54
     */
55
    public void createDeployment(DeploymentInfo deploymentInfo, 
56
                               Map<String, Object> servletConfig);
57
    
58
    /**
59
     * Register servlet instance
60
     */
61
    public void registerServlet(String name, String servletClass, 
62
                              List<String> mappings, Map<String, String> initParams,
63
                              boolean asyncSupported, int loadOnStartup);
64
    
65
    /**
66
     * Register filter instance
67
     */
68
    public void registerFilter(String name, String filterClass,
69
                             List<FilterMappingInfo> mappings,
70
                             Map<String, String> initParams,
71
                             boolean asyncSupported);
72
    
73
    /**
74
     * Register listener
75
     */
76
    public void registerListener(String listenerClass);
77
    
78
    /**
79
     * Start Undertow server
80
     */
81
    public void startUndertow(Supplier<Undertow> undertowSupplier);
82
    
83
    /**
84
     * Boot servlet container
85
     */
86
    public void bootServletContainer(DeploymentManager manager);
87
    
88
    /**
89
     * Configure security
90
     */
91
    public void setupSecurity(SecurityDomain securityDomain);
92
    
93
    /**
94
     * Get servlet context supplier
95
     */
96
    public Supplier<ServletContext> servletContextSupplier();
97
}
98
```
99

100
### ServletProducer
101

102
CDI producers for servlet objects, enabling dependency injection of servlet components.
103

104
```java { .api }
105
@Singleton
106
public class ServletProducer {
107
    /**
108
     * Produce servlet request for injection
109
     */
110
    @Produces
111
    @RequestScoped
112
    public HttpServletRequest request();
113
    
114
    /**
115
     * Produce servlet response for injection
116
     */
117
    @Produces
118
    @RequestScoped
119
    public HttpServletResponse response();
120
    
121
    /**
122
     * Produce HTTP session for injection
123
     */
124
    @Produces
125
    @RequestScoped
126
    public HttpSession session();
127
}
128
```
129

130
#### Usage Example
131

132
```java
133
@ApplicationScoped
134
public class MyService {
135
    
136
    @Inject
137
    HttpServletRequest request;
138
    
139
    @Inject
140
    HttpServletResponse response;
141
    
142
    public void processRequest() {
143
        String method = request.getMethod();
144
        String userAgent = request.getHeader("User-Agent");
145
        
146
        response.setHeader("X-Processed-By", "Quarkus");
147
        response.setContentType("application/json");
148
    }
149
}
150
```
151

152
### HttpSessionContext
153

154
CDI context implementation for HTTP session scope management.
155

156
```java { .api }
157
public class HttpSessionContext implements InjectableContext, HttpSessionListener {
158
    /**
159
     * Get the scope annotation class
160
     */
161
    public Class<? extends Annotation> getScope();
162
    
163
    /**
164
     * Get contextual instance with creation context
165
     */
166
    public <T> T get(Contextual<T> contextual, CreationalContext<T> creationalContext);
167
    
168
    /**
169
     * Get existing contextual instance
170
     */
171
    public <T> T get(Contextual<T> contextual);
172
    
173
    /**
174
     * Check if context is active
175
     */
176
    public boolean isActive();
177
    
178
    /**
179
     * Destroy contextual instance
180
     */
181
    public void destroy(Contextual<?> contextual);
182
    
183
    /**
184
     * Handle session creation event
185
     */
186
    public void sessionCreated(HttpSessionEvent event);
187
    
188
    /**
189
     * Handle session destruction event
190
     */
191
    public void sessionDestroyed(HttpSessionEvent event);
192
}
193
```
194

195
## Error Handling
196

197
### QuarkusErrorServlet
198

199
Error handling servlet for processing application errors.
200

201
```java { .api }
202
public class QuarkusErrorServlet extends HttpServlet {
203
    public static final String SHOW_STACK = "show-stack";
204
    public static final String SHOW_DECORATION = "show-decoration";  
205
    public static final String SRC_MAIN_JAVA = "src-main-java";
206
    public static final String KNOWN_CLASSES = "known-classes";
207
    
208
    /**
209
     * Handle error requests
210
     */
211
    protected void service(HttpServletRequest request, HttpServletResponse response)
212
            throws ServletException, IOException;
213
}
214
```
215

216
## Resource Management
217

218
### KnownPathResourceManager
219

220
Resource manager for handling static resources with known paths.
221

222
```java { .api }
223
public class KnownPathResourceManager implements ResourceManager {
224
    /**
225
     * Constructor with known paths and delegate manager
226
     */
227
    public KnownPathResourceManager(Set<String> files, Set<String> directories, 
228
                                  ResourceManager delegate);
229
    
230
    /**
231
     * Get resource by path
232
     */
233
    public Resource getResource(String path) throws IOException;
234
    
235
    /**
236
     * Close resource manager
237
     */
238
    public void close() throws IOException;
239
}
240
```
241

242
## Security Integration
243

244
### QuarkusUndertowAccount
245

246
Account implementation for Undertow security integration.
247

248
```java { .api }
249
public class QuarkusUndertowAccount implements Account {
250
    public Principal getPrincipal();
251
    public Set<String> getRoles();
252
}
253
```
254

255
### ServletHttpSecurityPolicy
256

257
HTTP security policy implementation for servlet security.
258

259
```java { .api }
260
public class ServletHttpSecurityPolicy implements HttpSecurityPolicy {
261
    public AuthenticationMechanismOutcome authenticate(HttpServerExchange exchange,
262
                                                     SecurityContext securityContext);
263
}
264
```
265

266
## Types
267

268
```java { .api }
269
// Common types used throughout the runtime API
270
import jakarta.servlet.http.HttpServletRequest;
271
import jakarta.servlet.http.HttpServletResponse;
272
import jakarta.servlet.http.HttpSession;
273
import jakarta.servlet.ServletContext;
274
import jakarta.servlet.ServletException;
275

276
import io.undertow.server.HttpHandler;
277
import io.undertow.servlet.api.DeploymentInfo;
278
import io.undertow.servlet.api.DeploymentManager;
279
import io.undertow.Undertow;
280

281
import jakarta.enterprise.context.RequestScoped;
282
import jakarta.enterprise.context.ApplicationScoped;
283
import jakarta.enterprise.inject.Produces;
284
import jakarta.inject.Singleton;
285

286
import java.util.Optional;
287
import java.util.List;
288
import java.util.Map;
289
import java.util.Set;
290
import java.util.function.Supplier;
291
```