0
# Build-time API
1

2
The build-time API provides extension points for registering servlets, filters, listeners, and other servlet components during application build. This API is primarily used by extension developers and advanced application developers who need to programmatically configure servlet components.
3

4
## Core Imports
5

6
```java
7
import io.quarkus.undertow.spi.ServletBuildItem;
8
import io.quarkus.undertow.spi.FilterBuildItem;
9
import io.quarkus.undertow.spi.ListenerBuildItem;
10
import io.quarkus.undertow.spi.ServletExtensionBuildItem;
11
import io.quarkus.undertow.spi.UndertowBuildItem;
12
import io.quarkus.deployment.annotations.BuildStep;
13
import io.quarkus.deployment.builditem.MultiBuildItem;
14
```
15

16
## Build Items
17

18
### ServletBuildItem
19

20
Build item for registering servlets during application build.
21

22
```java { .api }
23
public class ServletBuildItem extends MultiBuildItem {
24
    /**
25
     * Create a builder for ServletBuildItem
26
     */
27
    public static Builder builder(String name, String servletClass);
28
    
29
    /**
30
     * Get servlet name
31
     */
32
    public String getName();
33
    
34
    /**
35
     * Get servlet class name
36
     */
37
    public String getServletClass();
38
    
39
    /**
40
     * Get URL mappings
41
     */
42
    public List<String> getMappings();
43
    
44
    /**
45
     * Get load on startup value
46
     */
47
    public int getLoadOnStartup();
48
    
49
    /**
50
     * Check if async is supported
51
     */
52
    public boolean isAsyncSupported();
53
    
54
    /**
55
     * Get initialization parameters
56
     */
57
    public Map<String, String> getInitParams();
58
    
59
    /**
60
     * Get instance factory for servlet creation
61
     */
62
    public InstanceFactory<? extends Servlet> getInstanceFactory();
63
    
64
    /**
65
     * Get multipart configuration
66
     */
67
    public MultipartConfigElement getMultipartConfig();
68
}
69
```
70

71
#### ServletBuildItem.Builder
72

73
Builder class for creating ServletBuildItem instances.
74

75
```java { .api }
76
public static class Builder {
77
    /**
78
     * Set load on startup order
79
     */
80
    public Builder setLoadOnStartup(int loadOnStartup);
81
    
82
    /**
83
     * Enable or disable async support
84
     */
85
    public Builder setAsyncSupported(boolean asyncSupported);
86
    
87
    /**
88
     * Set URL mappings
89
     */
90
    public Builder setMappings(List<String> mappings);
91
    
92
    /**
93
     * Add single URL mapping
94
     */
95
    public Builder addMapping(String mapping);
96
    
97
    /**
98
     * Add initialization parameter
99
     */
100
    public Builder addInitParam(String name, String value);
101
    
102
    /**
103
     * Set instance factory for servlet creation
104
     */
105
    public Builder setInstanceFactory(InstanceFactory<? extends Servlet> instanceFactory);
106
    
107
    /**
108
     * Set multipart configuration
109
     */
110
    public Builder setMultipartConfig(MultipartConfigElement multipartConfig);
111
    
112
    /**
113
     * Build the ServletBuildItem
114
     */
115
    public ServletBuildItem build();
116
}
117
```
118

119
#### Usage Example
120

121
```java
122
@BuildStep
123
ServletBuildItem createApiServlet() {
124
    return ServletBuildItem.builder("api-servlet", ApiServlet.class.getName())
125
            .addMapping("/api/*")
126
            .setAsyncSupported(true)
127
            .setLoadOnStartup(1)
128
            .addInitParam("debug", "true")
129
            .build();
130
}
131
```
132

133
### FilterBuildItem
134

135
Build item for registering filters during application build.
136

137
```java { .api }
138
public class FilterBuildItem extends MultiBuildItem {
139
    /**
140
     * Create a builder for FilterBuildItem
141
     */
142
    public static Builder builder(String name, String filterClass);
143
    
144
    /**
145
     * Get filter name
146
     */
147
    public String getName();
148
    
149
    /**
150
     * Get filter class name
151
     */
152
    public String getFilterClass();
153
    
154
    /**
155
     * Get filter mappings
156
     */
157
    public List<FilterMappingInfo> getMappings();
158
    
159
    /**
160
     * Get load on startup value
161
     */
162
    public int getLoadOnStartup();
163
    
164
    /**
165
     * Check if async is supported
166
     */
167
    public boolean isAsyncSupported();
168
    
169
    /**
170
     * Get initialization parameters
171
     */
172
    public Map<String, String> getInitParams();
173
    
174
    /**
175
     * Get instance factory for filter creation
176
     */
177
    public InstanceFactory<? extends Filter> getInstanceFactory();
178
}
179
```
180

181
#### FilterBuildItem.FilterMappingInfo
182

183
Information about filter mappings.
184

185
```java { .api }
186
public static class FilterMappingInfo {
187
    /**
188
     * Constructor for filter mapping
189
     */
190
    public FilterMappingInfo(MappingType mappingType, String mapping, DispatcherType dispatcher);
191
    
192
    /**
193
     * Get mapping type (URL or SERVLET)
194
     */
195
    public MappingType getMappingType();
196
    
197
    /**
198
     * Get mapping value
199
     */
200
    public String getMapping();
201
    
202
    /**
203
     * Get dispatcher type
204
     */
205
    public DispatcherType getDispatcher();
206
    
207
    /**
208
     * Set mapping type
209
     */
210
    public void setMappingType(MappingType mappingType);
211
    
212
    /**
213
     * Set mapping value
214
     */
215
    public void setMapping(String mapping);
216
    
217
    /**
218
     * Set dispatcher type
219
     */
220
    public void setDispatcher(DispatcherType dispatcher);
221
}
222
```
223

224
#### FilterBuildItem.FilterMappingInfo.MappingType
225

226
Enumeration of filter mapping types.
227

228
```java { .api }
229
public enum MappingType {
230
    /**
231
     * URL pattern mapping
232
     */
233
    URL,
234
    
235
    /**
236
     * Servlet name mapping
237
     */
238
    SERVLET
239
}
240
```
241

242
#### FilterBuildItem.Builder
243

244
Builder class for creating FilterBuildItem instances.
245

246
```java { .api }
247
public static class Builder {
248
    /**
249
     * Set load on startup order
250
     */
251
    public Builder setLoadOnStartup(int loadOnStartup);
252
    
253
    /**
254
     * Enable or disable async support
255
     */
256
    public Builder setAsyncSupported(boolean asyncSupported);
257
    
258
    /**
259
     * Set instance factory for filter creation
260
     */
261
    public Builder setInstanceFactory(InstanceFactory<? extends Filter> instanceFactory);
262
    
263
    /**
264
     * Add filter mapping
265
     */
266
    public Builder addMapping(FilterMappingInfo mapping);
267
    
268
    /**
269
     * Add URL pattern mapping
270
     */
271
    public Builder addFilterUrlMapping(String urlPattern, DispatcherType dispatcher);
272
    
273
    /**
274
     * Add servlet name mapping
275
     */
276
    public Builder addFilterServletNameMapping(String servletName, DispatcherType dispatcher);
277
    
278
    /**
279
     * Insert URL mapping at specific position
280
     */
281
    public Builder insertFilterUrlMapping(int index, String urlPattern, DispatcherType dispatcher);
282
    
283
    /**
284
     * Insert servlet name mapping at specific position
285
     */
286
    public Builder insertFilterServletNameMapping(int pos, String filterName, String mapping, 
287
                                                DispatcherType dispatcher);
288
    
289
    /**
290
     * Add initialization parameter
291
     */
292
    public Builder addInitParam(String name, String value);
293
    
294
    /**
295
     * Build the FilterBuildItem
296
     */
297
    public FilterBuildItem build();
298
}
299
```
300

301
#### Usage Example
302

303
```java
304
@BuildStep
305
FilterBuildItem createSecurityFilter() {
306
    return FilterBuildItem.builder("security-filter", SecurityFilter.class.getName())
307
            .addFilterUrlMapping("/*", DispatcherType.REQUEST)
308
            .setAsyncSupported(true)
309
            .addInitParam("enabled", "true")
310
            .build();
311
}
312
```
313

314
### ListenerBuildItem
315

316
Build item for registering servlet listeners during application build.
317

318
```java { .api }
319
public class ListenerBuildItem extends MultiBuildItem {
320
    /**
321
     * Constructor for listener build item
322
     */
323
    public ListenerBuildItem(String listenerClass);
324
    
325
    /**
326
     * Get listener class name
327
     */
328
    public String getListenerClass();
329
}
330
```
331

332
#### Usage Example
333

334
```java
335
@BuildStep
336
ListenerBuildItem createSessionListener() {
337
    return new ListenerBuildItem(MySessionListener.class.getName());
338
}
339
```
340

341
### ServletExtensionBuildItem
342

343
Build item for registering servlet extensions.
344

345
```java { .api }
346
public class ServletExtensionBuildItem extends MultiBuildItem {
347
    /**
348
     * Constructor for servlet extension build item
349
     */
350
    public ServletExtensionBuildItem(ServletExtension extension);
351
    
352
    /**
353
     * Get servlet extension instance
354
     */
355
    public ServletExtension getValue();
356
}
357
```
358

359
### ServletContainerInitializerBuildItem
360

361
Build item for registering servlet container initializers.
362

363
```java { .api }
364
public class ServletContainerInitializerBuildItem extends MultiBuildItem {
365
    /**
366
     * Constructor for servlet container initializer
367
     */
368
    public ServletContainerInitializerBuildItem(String sciClass, Set<String> handlesTypes);
369
    
370
    /**
371
     * Get servlet container initializer class name
372
     */
373
    public String getSciClass();
374
    
375
    /**
376
     * Get handled types
377
     */
378
    public Set<String> getHandlesTypes();
379
}
380
```
381

382
### UndertowBuildItem
383

384
Build item providing access to the Undertow server instance.
385

386
```java { .api }
387
public class UndertowBuildItem extends SimpleBuildItem {
388
    /**
389
     * Constructor for Undertow build item
390
     */
391
    public UndertowBuildItem(RuntimeValue<Undertow> undertow);
392
    
393
    /**
394
     * Get Undertow server instance
395
     */
396
    public RuntimeValue<Undertow> getUndertow();
397
}
398
```
399

400
### ServletContextPathBuildItem
401

402
Build item for servlet context path configuration.
403

404
```java { .api }
405
public class ServletContextPathBuildItem extends SimpleBuildItem {
406
    /**
407
     * Constructor for servlet context path
408
     */
409
    public ServletContextPathBuildItem(String contextPath);
410
    
411
    /**
412
     * Get context path
413
     */
414
    public String getContextPath();
415
}
416
```
417

418
### Additional Build Items
419

420
#### HttpHandlerWrapperBuildItem
421

422
Build item for registering HTTP handler wrappers.
423

424
```java { .api }
425
public class HttpHandlerWrapperBuildItem extends MultiBuildItem {
426
    /**
427
     * Constructor for HTTP handler wrapper
428
     */
429
    public HttpHandlerWrapperBuildItem(HandlerWrapper value);
430
    
431
    /**
432
     * Get handler wrapper
433
     */
434
    public HandlerWrapper getValue();
435
}
436
```
437

438
#### ServletContextAttributeBuildItem
439

440
Build item for setting servlet context attributes.
441

442
```java { .api }
443
public class ServletContextAttributeBuildItem extends MultiBuildItem {
444
    /**
445
     * Constructor for servlet context attribute
446
     */
447
    public ServletContextAttributeBuildItem(String key, Object value);
448
    
449
    /**
450
     * Get attribute key
451
     */
452
    public String getKey();
453
    
454
    /**
455
     * Get attribute value
456
     */
457
    public Object getValue();
458
}
459
```
460

461
#### ServletDeploymentManagerBuildItem
462

463
Build item providing access to the deployment manager.
464

465
```java { .api }
466
public class ServletDeploymentManagerBuildItem extends SimpleBuildItem {
467
    /**
468
     * Constructor for servlet deployment manager
469
     */
470
    public ServletDeploymentManagerBuildItem(DeploymentManager deploymentManager);
471
    
472
    /**
473
     * Get deployment manager
474
     */
475
    public DeploymentManager getDeploymentManager();
476
}
477
```
478

479
#### ServletInitParamBuildItem
480

481
Build item for setting servlet initialization parameters.
482

483
```java { .api }
484
public class ServletInitParamBuildItem extends MultiBuildItem {
485
    /**
486
     * Constructor for servlet init parameter
487
     */
488
    public ServletInitParamBuildItem(String key, String value);
489
    
490
    /**
491
     * Get parameter key
492
     */
493
    public String getKey();
494
    
495
    /**
496
     * Get parameter value
497
     */
498
    public String getValue();
499
}
500
```
501

502
### IgnoredServletContainerInitializerBuildItem
503

504
Build item for ignoring specific servlet container initializers during scanning.
505

506
```java { .api }
507
public class IgnoredServletContainerInitializerBuildItem extends MultiBuildItem {
508
    /**
509
     * Constructor for ignored servlet container initializer
510
     */
511
    public IgnoredServletContainerInitializerBuildItem(String sciClass);
512
    
513
    /**
514
     * Get servlet container initializer class name
515
     */
516
    public String getSciClass();
517
}
518
```
519

520
### WebMetadataBuildItem
521

522
Build item providing access to web application metadata.
523

524
```java { .api }
525
public class WebMetadataBuildItem extends SimpleBuildItem {
526
    /**
527
     * Constructor for web metadata build item
528
     */
529
    public WebMetadataBuildItem(WebMetaData webMetaData);
530
    
531
    /**
532
     * Get web metadata
533
     */
534
    public WebMetaData getWebMetaData();
535
}
536
```
537

538
### GeneratedWebResourceBuildItem
539

540
Build item for generated static resources that will be served by the web container.
541

542
```java { .api }
543
public class GeneratedWebResourceBuildItem extends MultiBuildItem {
544
    /**
545
     * Constructor for generated web resource
546
     */
547
    public GeneratedWebResourceBuildItem(String name, byte[] classData);
548
    
549
    /**
550
     * Get resource name
551
     */
552
    public String getName();
553
    
554
    /**
555
     * Get resource data
556
     */
557
    public byte[] getClassData();
558
}
559
```
560

561
### KnownPathsBuildItem
562

563
Build item containing known paths for static resource optimization.
564

565
```java { .api }
566
public class KnownPathsBuildItem extends SimpleBuildItem {
567
    /**
568
     * Constructor for known paths build item (package-private)
569
     */
570
    KnownPathsBuildItem(Set<String> knownFiles, Set<String> knownDirectories);
571
    
572
    /**
573
     * Set of known file paths
574
     */
575
    public final Set<String> knownFiles;
576
    
577
    /**
578
     * Set of known directory paths
579
     */
580
    public final Set<String> knownDirectories;
581
}
582
```
583

584
## Extension Development Example
585

586
Complete example of a Quarkus extension that registers servlet components:
587

588
```java
589
@BuildStep
590
void registerServletComponents(BuildProducer<ServletBuildItem> servlets,
591
                              BuildProducer<FilterBuildItem> filters,
592
                              BuildProducer<ListenerBuildItem> listeners) {
593
    
594
    // Register a servlet
595
    servlets.produce(ServletBuildItem.builder("api", "com.example.ApiServlet")
596
            .addMapping("/api/*")
597
            .setAsyncSupported(true)
598
            .build());
599
    
600
    // Register a filter
601
    filters.produce(FilterBuildItem.builder("cors", "com.example.CorsFilter")
602
            .addFilterUrlMapping("/*", DispatcherType.REQUEST)
603
            .build());
604
    
605
    // Register a listener
606
    listeners.produce(new ListenerBuildItem("com.example.AppContextListener"));
607
}
608
```
609

610
## Types
611

612
```java { .api }
613
// Core servlet types
614
import jakarta.servlet.Servlet;
615
import jakarta.servlet.Filter;
616
import jakarta.servlet.ServletExtension;
617
import jakarta.servlet.DispatcherType;
618
import jakarta.servlet.MultipartConfigElement;
619

620
// Quarkus build-time types
621
import io.quarkus.deployment.builditem.SimpleBuildItem;
622
import io.quarkus.deployment.builditem.MultiBuildItem;
623
import io.quarkus.deployment.BuildProducer;
624
import io.quarkus.runtime.RuntimeValue;
625

626
// Undertow types
627
import io.undertow.Undertow;
628
import io.undertow.servlet.api.InstanceFactory;
629
import io.undertow.servlet.api.DeploymentManager;
630
import io.undertow.server.HandlerWrapper;
631

632
// Web metadata types
633
import org.jboss.metadata.web.spec.WebMetaData;
634

635
// Standard Java types
636
import java.util.List;
637
import java.util.Map;
638
import java.util.Set;
639
```