0
# Embedded Tomcat API
1

2
Simplified API for programmatically creating, configuring, and managing embedded Tomcat server instances. Ideal for standalone applications, microservices, testing environments, and development tools that need a lightweight servlet container without external dependencies.
3

4
## Capabilities
5

6
### Tomcat Class
7

8
Primary class for creating and managing embedded Tomcat instances.
9

10
```java { .api }
11
public class Tomcat {
12
    // Constructor
13
    public Tomcat();
14
    
15
    // Server configuration
16
    public void setPort(int port);
17
    public void setBaseDir(String basedir);
18
    public void setHostname(String s);
19
    
20
    // Web application management
21
    public Context addWebapp(String contextPath, String docBase);
22
    public Context addWebapp(String contextPath, URL source) throws IOException;
23
    public Context addWebapp(Host host, String contextPath, String docBase);
24
    public Context addWebapp(Host host, String contextPath, String docBase, LifecycleListener config);
25
    public Context addContext(String contextPath, String docBase);
26
    public Context addContext(Host host, String contextPath, String docBase);
27
    public Context addContext(Host host, String contextPath, String contextName, String dir);
28
    
29
    // Servlet management
30
    public Wrapper addServlet(String contextPath, String servletName, String servletClass);
31
    public static Wrapper addServlet(Context ctx, String servletName, String servletClass);
32
    public Wrapper addServlet(String contextPath, String servletName, Servlet servlet);
33
    public static Wrapper addServlet(Context ctx, String servletName, Servlet servlet);
34
    
35
    // Webapp defaults and configuration
36
    public void enableNaming();
37
    public void setSilent(boolean silent);
38
    public void setAddDefaultWebXmlToWebapp(boolean addDefaultWebXmlToWebapp);
39
    public LifecycleListener getDefaultWebXmlListener();
40
    public String noDefaultWebXmlPath();
41
    public void initWebappDefaults(String contextPath);
42
    public static void initWebappDefaults(Context ctx);
43
    public static void addDefaultMimeTypeMappings(Context context);
44
    
45
    // User/role management
46
    public void addUser(String user, String pass);
47
    public void addRole(String user, String role);
48
    
49
    // Lifecycle management
50
    public void init() throws LifecycleException;
51
    public void init(ConfigurationSource source) throws LifecycleException;
52
    public void init(ConfigurationSource source, String[] catalinaArguments) throws LifecycleException;
53
    public void start() throws LifecycleException;
54
    public void stop() throws LifecycleException;
55
    public void destroy() throws LifecycleException;
56
    
57
    // Component access
58
    public Server getServer();
59
    public Service getService();
60
    public Engine getEngine();
61
    public Host getHost();
62
    public void setHost(Host host);
63
    public Connector getConnector();
64
    public void setConnector(Connector connector);
65

66
    // Command line execution
67
    public static void main(String[] args) throws Exception;
68
}
69
```
70

71
### Context Interface
72

73
Represents a web application context with servlets, filters, and resources.
74

75
```java { .api }
76
public interface Context extends Container {
77
    // Path configuration
78
    void setPath(String path);
79
    String getPath();
80
    void setDocBase(String docBase);
81
    String getDocBase();
82
    
83
    // Servlet container initializers
84
    void addServletContainerInitializer(ServletContainerInitializer sci, Set<Class<?>> classes);
85
    void setContainerSciFilter(String containerSciFilter);
86
    String getContainerSciFilter();
87
    Set<String> addServletSecurity(ServletRegistration.Dynamic registration,
88
        ServletSecurityElement servletSecurityElement);
89
    
90
    // Listeners
91
    void addApplicationListener(String listener);
92
    void removeApplicationListener(String listener);
93
    String[] findApplicationListeners();
94
    void addApplicationEventListener(Object listener);
95
    void addApplicationLifecycleListener(Object listener);
96
    Object[] getApplicationEventListeners();
97
    void setApplicationEventListeners(Object[] listeners);
98
    Object[] getApplicationLifecycleListeners();
99
    void setApplicationLifecycleListeners(Object[] listeners);
100
    boolean fireRequestInitEvent(ServletRequest request);
101
    boolean fireRequestDestroyEvent(ServletRequest request);
102
    void addWrapperLifecycle(String listener);
103
    void removeWrapperLifecycle(String listener);
104
    String[] findWrapperLifecycles();
105
    void addWrapperListener(String listener);
106
    void removeWrapperListener(String listener);
107
    String[] findWrapperListeners();
108
    
109
    // Servlets and mappings
110
    void addServletMappingDecoded(String pattern, String name);
111
    void addServletMappingDecoded(String pattern, String name, boolean jspWildCard);
112
    void removeServletMapping(String pattern);
113
    String findServletMapping(String pattern);
114
    String[] findServletMappings();
115
    Wrapper createWrapper();
116
    void setWrapperClass(String wrapperClass);
117
    String getWrapperClass();
118
    void setResourceOnlyServlets(String resourceOnlyServlets);
119
    String getResourceOnlyServlets();
120
    boolean isResourceOnlyServlet(String servletName);
121
    
122
    // Filters
123
    void addFilterDef(FilterDef filterDef);
124
    void removeFilterDef(FilterDef filterDef);
125
    FilterDef findFilterDef(String filterName);
126
    FilterDef[] findFilterDefs();
127
    void addFilterMap(FilterMap filterMap);
128
    void addFilterMapBefore(FilterMap filterMap);
129
    void removeFilterMap(FilterMap filterMap);
130
    FilterMap[] findFilterMaps();
131
    
132
    // Security constraints and roles
133
    void addConstraint(SecurityConstraint constraint);
134
    void removeConstraint(SecurityConstraint constraint);
135
    SecurityConstraint[] findConstraints();
136
    void addSecurityRole(String role);
137
    void removeSecurityRole(String role);
138
    boolean findSecurityRole(String role);
139
    String[] findSecurityRoles();
140
    void addRoleMapping(String role, String link);
141
    void removeRoleMapping(String role);
142
    String findRoleMapping(String role);
143
    void setDenyUncoveredHttpMethods(boolean denyUncoveredHttpMethods);
144
    boolean getDenyUncoveredHttpMethods();
145
    LoginConfig getLoginConfig();
146
    void setLoginConfig(LoginConfig config);
147
    Authenticator getAuthenticator();
148
    void setPreemptiveAuthentication(boolean enable);
149
    boolean getPreemptiveAuthentication();
150
    
151
    // Initialization parameters
152
    void addParameter(String name, String value);
153
    String findParameter(String name);
154
    String[] findParameters();
155
    void removeParameter(String name);
156
    
157
    // Error pages
158
    void addErrorPage(ErrorPage errorPage);
159
    void removeErrorPage(ErrorPage errorPage);
160
    ErrorPage findErrorPage(int errorCode);
161
    ErrorPage findErrorPage(Throwable throwable);
162
    ErrorPage[] findErrorPages();
163
    
164
    // MIME mappings
165
    void addMimeMapping(String extension, String mimeType);
166
    String findMimeMapping(String extension);
167
    String[] findMimeMappings();
168
    void removeMimeMapping(String extension);
169
    
170
    // Welcome files
171
    void addWelcomeFile(String name);
172
    boolean findWelcomeFile(String name);
173
    String[] findWelcomeFiles();
174
    void removeWelcomeFile(String name);
175
    
176
    // Configuration
177
    void setCookies(boolean cookies);
178
    boolean getCookies();
179
    void setCrossContext(boolean crossContext);
180
    boolean getCrossContext();
181
    void setReloadable(boolean reloadable);
182
    boolean getReloadable();
183
    void setDisplayName(String displayName);
184
    String getDisplayName();
185
    
186
    // Classloader
187
    void setLoader(Loader loader);
188
    Loader getLoader();
189
    
190
    // Manager
191
    void setManager(Manager manager);
192
    Manager getManager();
193
    
194
    // Resource management
195
    void setResources(WebResourceRoot resources);
196
    WebResourceRoot getResources();
197
    void setAddWebinfClassesResources(boolean addWebinfClassesResources);
198
    boolean getAddWebinfClassesResources();
199
    JarScanner getJarScanner();
200
    void setJarScanner(JarScanner jarScanner);
201
    NamingResourcesImpl getNamingResources();
202
    void setNamingResources(NamingResourcesImpl namingResources);
203
    Object getNamingToken();
204
    
205
    // Session configuration
206
    void setSessionTimeout(int timeout);
207
    int getSessionTimeout();
208
    void setSessionCookieName(String sessionCookieName);
209
    String getSessionCookieName();
210
    void setUseHttpOnly(boolean useHttpOnly);
211
    boolean getUseHttpOnly();
212
    void setUsePartitioned(boolean usePartitioned);
213
    boolean getUsePartitioned();
214
    void setSessionCookieDomain(String sessionCookieDomain);
215
    String getSessionCookieDomain();
216
    void setSessionCookiePath(String sessionCookiePath);
217
    String getSessionCookiePath();
218
    void setSessionCookiePathUsesTrailingSlash(boolean sessionCookiePathUsesTrailingSlash);
219
    boolean getSessionCookiePathUsesTrailingSlash();
220
    void setValidateClientProvidedNewSessionId(boolean validateClientProvidedNewSessionId);
221
    boolean getValidateClientProvidedNewSessionId();
222
    void setAlwaysAccessSession(boolean alwaysAccessSession);
223
    boolean getAlwaysAccessSession();
224
    CookieProcessor getCookieProcessor();
225
    void setCookieProcessor(CookieProcessor cookieProcessor);
226

227
    // Deployment configuration
228
    void setConfigFile(URL configFile);
229
    URL getConfigFile();
230
    Resource findConfigFileResource(String name) throws IOException;
231
    void setAltDDName(String altDDName);
232
    String getAltDDName();
233
    void setPublicId(String publicId);
234
    String getPublicId();
235
    void setConfigured(boolean configured);
236
    boolean getConfigured();
237
    void setPrivileged(boolean privileged);
238
    boolean getPrivileged();
239
    void setDistributable(boolean distributable);
240
    boolean getDistributable();
241
    void setOverride(boolean override);
242
    boolean getOverride();
243
    void setWebappVersion(String webappVersion);
244
    String getWebappVersion();
245
    String getBaseName();
246
    String getEncodedPath();
247
    void reload();
248
    boolean getPaused();
249

250
    // Servlet version
251
    void setEffectiveMajorVersion(int major);
252
    int getEffectiveMajorVersion();
253
    void setEffectiveMinorVersion(int minor);
254
    int getEffectiveMinorVersion();
255
    boolean isServlet22();
256

257
    // Watched resources
258
    void addWatchedResource(String name);
259
    void removeWatchedResource(String name);
260
    String[] findWatchedResources();
261

262
    // Annotation processing
263
    void setIgnoreAnnotations(boolean ignoreAnnotations);
264
    boolean getIgnoreAnnotations();
265
    void setParallelAnnotationScanning(boolean parallelAnnotationScanning);
266
    boolean getParallelAnnotationScanning();
267

268
    // Instance management
269
    InstanceManager getInstanceManager();
270
    void setInstanceManager(InstanceManager instanceManager);
271
    InstanceManager createInstanceManager();
272
    void addPostConstructMethod(String clazz, String method);
273
    void removePostConstructMethod(String clazz);
274
    String findPostConstructMethod(String clazz);
275
    Map<String,String> findPostConstructMethods();
276
    void addPreDestroyMethod(String clazz, String method);
277
    void removePreDestroyMethod(String clazz);
278
    String findPreDestroyMethod(String clazz);
279
    Map<String,String> findPreDestroyMethods();
280

281
    // Application parameters
282
    void addApplicationParameter(ApplicationParameter parameter);
283
    void removeApplicationParameter(String name);
284
    ApplicationParameter[] findApplicationParameters();
285

286
    // Character encoding
287
    void setRequestCharacterEncoding(String encoding);
288
    String getRequestCharacterEncoding();
289
    void setResponseCharacterEncoding(String encoding);
290
    String getResponseCharacterEncoding();
291
    void addLocaleEncodingMappingParameter(String locale, String encoding);
292
    String getCharset(Locale locale);
293

294
    // Multipart configuration
295
    void setAllowCasualMultipartParsing(boolean allowCasualMultipartParsing);
296
    boolean getAllowCasualMultipartParsing();
297
    void setSwallowAbortedUploads(boolean swallowAbortedUploads);
298
    boolean getSwallowAbortedUploads();
299
    void setCreateUploadTargets(boolean createUploadTargets);
300
    boolean getCreateUploadTargets();
301

302
    // Advanced configuration
303
    void setSwallowOutput(boolean swallowOutput);
304
    boolean getSwallowOutput();
305
    ClassLoader getParentClassLoader();
306
    void setParentClassLoader(ClassLoader parent);
307
    void setFailCtxIfServletStartFails(boolean failCtxIfServletStartFails);
308
    boolean getFailCtxIfServletStartFails();
309
    ServletContext getServletContext();
310
    String getRealPath(String path);
311
    JspConfigDescriptor getJspConfigDescriptor();
312
    void setJspConfigDescriptor(JspConfigDescriptor descriptor);
313
    void setTldValidation(boolean tldValidation);
314
    boolean getTldValidation();
315
    void setXmlNamespaceAware(boolean xmlNamespaceAware);
316
    boolean getXmlNamespaceAware();
317
    void setXmlValidation(boolean xmlValidation);
318
    boolean getXmlValidation();
319
    void setXmlBlockExternal(boolean xmlBlockExternal);
320
    boolean getXmlBlockExternal();
321
    void setLogEffectiveWebXml(boolean logEffectiveWebXml);
322
    boolean getLogEffectiveWebXml();
323

324
    // Request processing
325
    void setSendRedirectBody(boolean enable);
326
    boolean getSendRedirectBody();
327
    void setUseRelativeRedirects(boolean useRelativeRedirects);
328
    boolean getUseRelativeRedirects();
329
    void setMapperContextRootRedirectEnabled(boolean mapperContextRootRedirectEnabled);
330
    boolean getMapperContextRootRedirectEnabled();
331
    void setMapperDirectoryRedirectEnabled(boolean mapperDirectoryRedirectEnabled);
332
    boolean getMapperDirectoryRedirectEnabled();
333
    void setDispatchersUseEncodedPaths(boolean dispatchersUseEncodedPaths);
334
    boolean getDispatchersUseEncodedPaths();
335
    void setFireRequestListenersOnForwards(boolean enable);
336
    boolean getFireRequestListenersOnForwards();
337
    void setEncodedSolidusHandling(String encodedSolidusHandling);
338
    String getEncodedSolidusHandling();
339
    EncodedSolidusHandling getEncodedSolidusHandlingEnum();
340
    void setEncodedReverseSolidusHandling(String encodedReverseSolidusHandling);
341
    String getEncodedReverseSolidusHandling();
342
    EncodedSolidusHandling getEncodedReverseSolidusHandlingEnum();
343
    void setContextGetResourceRequiresSlash(boolean contextGetResourceRequiresSlash);
344
    boolean getContextGetResourceRequiresSlash();
345
    void setDispatcherWrapsSameObject(boolean dispatcherWrapsSameObject);
346
    boolean getDispatcherWrapsSameObject();
347
    void setSuspendWrappedResponseAfterForward(boolean suspendWrappedResponseAfterForward);
348
    boolean getSuspendWrappedResponseAfterForward();
349
    void setAllowMultipleLeadingForwardSlashInPath(boolean allowMultipleLeadingForwardSlashInPath);
350
    boolean getAllowMultipleLeadingForwardSlashInPath();
351
    void setThreadBindingListener(ThreadBindingListener threadBindingListener);
352
    ThreadBindingListener getThreadBindingListener();
353

354
    // Async processing
355
    void incrementInProgressAsyncCount();
356
    void decrementInProgressAsyncCount();
357

358
    // Background processing
359
    void backgroundProcess();
360
}
361
```
362

363
### Wrapper Interface
364

365
Represents an individual servlet within a context.
366

367
```java { .api }
368
public interface Wrapper extends Container {
369
    // Servlet class
370
    void setServletClass(String servletClass);
371
    String getServletClass();
372
    void setServlet(Servlet servlet);
373
    Servlet getServlet();
374
    
375
    // Load on startup
376
    void setLoadOnStartup(int value);
377
    int getLoadOnStartup();
378
    
379
    // Run-as role
380
    void setRunAs(String runAs);
381
    String getRunAs();
382
    
383
    // Servlet state
384
    boolean isUnavailable();
385
    long getAvailable();
386
    void setAvailable(long available);
387

388
    // Request monitoring
389
    void incrementErrorCount();
390

391
    // Servlet methods
392
    String[] getServletMethods() throws ServletException;
393

394
    // Multipart configuration
395
    void setMultipartConfigElement(MultipartConfigElement multipartConfig);
396
    MultipartConfigElement getMultipartConfigElement();
397

398
    // Async support
399
    void setAsyncSupported(boolean asyncSupported);
400
    boolean isAsyncSupported();
401

402
    // Enabled
403
    void setEnabled(boolean enabled);
404
    boolean isEnabled();
405

406
    // Overridable
407
    boolean isOverridable();
408
    void setOverridable(boolean overridable);
409

410
    // Servlet lifecycle
411
    Servlet allocate() throws ServletException;
412
    void deallocate(Servlet servlet) throws ServletException;
413
    void load() throws ServletException;
414
    void unload() throws ServletException;
415
    void unavailable(UnavailableException unavailable);
416

417
    // Init parameters
418
    void addInitParameter(String name, String value);
419
    String findInitParameter(String name);
420
    String[] findInitParameters();
421
    void removeInitParameter(String name);
422

423
    // Mappings
424
    void addMapping(String mapping);
425
    String[] findMappings();
426
    void removeMapping(String mapping);
427

428
    // Security references
429
    void addSecurityReference(String name, String link);
430
    String findSecurityReference(String name);
431
    String[] findSecurityReferences();
432
    void removeSecurityReference(String name);
433
}
434
```
435

436
## Usage Examples
437

438
### Basic Embedded Server
439

440
```java
441
import org.apache.catalina.startup.Tomcat;
442
import org.apache.catalina.Context;
443
import org.apache.catalina.LifecycleException;
444
import java.io.File;
445

446
public class SimpleEmbeddedTomcat {
447
    public static void main(String[] args) throws LifecycleException {
448
        Tomcat tomcat = new Tomcat();
449
        tomcat.setPort(8080);
450
        tomcat.setBaseDir(new File("target/tomcat").getAbsolutePath());
451
        
452
        // Add empty context (for servlets added programmatically)
453
        Context ctx = tomcat.addContext("", new File(".").getAbsolutePath());
454
        
455
        // Start server
456
        tomcat.start();
457
        tomcat.getServer().await();
458
    }
459
}
460
```
461

462
### Adding Servlets Programmatically
463

464
```java
465
import org.apache.catalina.startup.Tomcat;
466
import org.apache.catalina.Context;
467
import jakarta.servlet.http.HttpServlet;
468
import jakarta.servlet.http.HttpServletRequest;
469
import jakarta.servlet.http.HttpServletResponse;
470
import java.io.IOException;
471
import java.io.PrintWriter;
472

473
public class ServletExample {
474
    public static void main(String[] args) throws Exception {
475
        Tomcat tomcat = new Tomcat();
476
        tomcat.setPort(8080);
477
        
478
        Context ctx = tomcat.addContext("", System.getProperty("java.io.tmpdir"));
479
        
480
        // Add servlet instance
481
        HttpServlet servlet = new HttpServlet() {
482
            @Override
483
            protected void doGet(HttpServletRequest req, HttpServletResponse resp) 
484
                    throws IOException {
485
                resp.setContentType("text/html");
486
                PrintWriter writer = resp.getWriter();
487
                writer.println("<h1>Hello from Embedded Tomcat</h1>");
488
            }
489
        };
490
        
491
        Tomcat.addServlet(ctx, "helloServlet", servlet);
492
        ctx.addServletMappingDecoded("/hello", "helloServlet");
493

494
        // Add servlet by class name
495
        Tomcat.addServlet(ctx, "myServlet", "com.example.MyServlet");
496
        ctx.addServletMappingDecoded("/my/*", "myServlet");
497

498
        // Configure async support for async servlets
499
        Wrapper asyncWrapper = Tomcat.addServlet(ctx, "asyncServlet", new AsyncServlet());
500
        asyncWrapper.setAsyncSupported(true);
501
        ctx.addServletMappingDecoded("/async", "asyncServlet");
502

503
        // Configure multipart support for file upload servlets
504
        Wrapper uploadWrapper = Tomcat.addServlet(ctx, "uploadServlet", new FileUploadServlet());
505
        uploadWrapper.setMultipartConfigElement(new MultipartConfigElement("/tmp"));
506
        ctx.addServletMappingDecoded("/upload", "uploadServlet");
507

508
        tomcat.start();
509
        tomcat.getServer().await();
510
    }
511
}
512
```
513

514
**Configuration Notes:**
515
- **Async Servlets:** Use `wrapper.setAsyncSupported(true)` to enable asynchronous processing
516
- **File Upload Servlets:** Use `wrapper.setMultipartConfigElement(new MultipartConfigElement("/tmp"))` to enable multipart/form-data processing
517

518
### Adding Web Application
519

520
```java
521
import org.apache.catalina.startup.Tomcat;
522
import org.apache.catalina.Context;
523
import java.io.File;
524

525
public class WebAppExample {
526
    public static void main(String[] args) throws Exception {
527
        Tomcat tomcat = new Tomcat();
528
        tomcat.setPort(8080);
529
        tomcat.setBaseDir(new File("target/tomcat").getAbsolutePath());
530
        
531
        // Add existing web application
532
        String webappDirLocation = "src/main/webapp/";
533
        Context ctx = tomcat.addWebapp("/myapp", 
534
            new File(webappDirLocation).getAbsolutePath());
535
        
536
        tomcat.start();
537
        tomcat.getServer().await();
538
    }
539
}
540
```
541

542
### Multiple Contexts
543

544
```java
545
import org.apache.catalina.startup.Tomcat;
546
import org.apache.catalina.Context;
547
import org.apache.catalina.Host;
548
import java.io.File;
549

550
public class MultiContextExample {
551
    public static void main(String[] args) throws Exception {
552
        Tomcat tomcat = new Tomcat();
553
        tomcat.setPort(8080);
554
        tomcat.setBaseDir(new File("target/tomcat").getAbsolutePath());
555
        
556
        Host host = tomcat.getHost();
557
        
558
        // API context
559
        Context apiCtx = tomcat.addContext(host, "/api", 
560
            new File("target/api").getAbsolutePath());
561
        
562
        // Admin context
563
        Context adminCtx = tomcat.addContext(host, "/admin", 
564
            new File("target/admin").getAbsolutePath());
565
        
566
        // Web context
567
        Context webCtx = tomcat.addWebapp(host, "/", 
568
            new File("src/main/webapp").getAbsolutePath());
569
        
570
        tomcat.start();
571
        tomcat.getServer().await();
572
    }
573
}
574
```
575

576
### Custom Connector Configuration
577

578
```java
579
import org.apache.catalina.startup.Tomcat;
580
import org.apache.catalina.connector.Connector;
581
import org.apache.coyote.http11.Http11NioProtocol;
582

583
public class CustomConnectorExample {
584
    public static void main(String[] args) throws Exception {
585
        Tomcat tomcat = new Tomcat();
586
        tomcat.setBaseDir("target/tomcat");
587
        
588
        // Create custom HTTP connector
589
        Connector httpConnector = new Connector("HTTP/1.1");
590
        httpConnector.setPort(8080);
591
        httpConnector.setProperty("maxThreads", "200");
592
        httpConnector.setProperty("maxConnections", "10000");
593
        httpConnector.setProperty("connectionTimeout", "20000");
594
        httpConnector.setProperty("compression", "on");
595
        httpConnector.setProperty("compressibleMimeType", 
596
            "text/html,text/xml,text/plain,text/css,text/javascript,application/json");
597
        
598
        tomcat.setConnector(httpConnector);
599
        tomcat.getService().addConnector(httpConnector);
600
        
601
        // Add HTTPS connector
602
        Connector httpsConnector = new Connector("HTTP/1.1");
603
        httpsConnector.setPort(8443);
604
        httpsConnector.setSecure(true);
605
        httpsConnector.setScheme("https");
606
        httpsConnector.setProperty("SSLEnabled", "true");
607
        httpsConnector.setProperty("keystoreFile", "conf/keystore.jks");
608
        httpsConnector.setProperty("keystorePass", "changeit");
609
        
610
        tomcat.getService().addConnector(httpsConnector);
611
        
612
        Context ctx = tomcat.addContext("", System.getProperty("java.io.tmpdir"));
613
        
614
        tomcat.start();
615
        tomcat.getServer().await();
616
    }
617
}
618
```
619

620
### Adding Users and Roles
621

622
```java
623
import org.apache.catalina.startup.Tomcat;
624
import org.apache.catalina.Context;
625
import java.io.File;
626

627
public class SecurityExample {
628
    public static void main(String[] args) throws Exception {
629
        Tomcat tomcat = new Tomcat();
630
        tomcat.setPort(8080);
631
        tomcat.setBaseDir(new File("target/tomcat").getAbsolutePath());
632
        
633
        // Add users and roles
634
        tomcat.addUser("admin", "admin123");
635
        tomcat.addRole("admin", "manager");
636
        tomcat.addRole("admin", "admin-gui");
637
        
638
        tomcat.addUser("user", "user123");
639
        tomcat.addRole("user", "user");
640
        
641
        Context ctx = tomcat.addContext("", new File(".").getAbsolutePath());
642
        
643
        tomcat.start();
644
        tomcat.getServer().await();
645
    }
646
}
647
```
648

649
### Testing Utility
650

651
```java
652
import org.apache.catalina.startup.Tomcat;
653
import org.apache.catalina.Context;
654
import org.apache.catalina.LifecycleException;
655
import org.junit.jupiter.api.AfterEach;
656
import org.junit.jupiter.api.BeforeEach;
657
import org.junit.jupiter.api.Test;
658
import java.io.File;
659

660
public class TomcatTestHelper {
661
    private Tomcat tomcat;
662
    private int port = 8080;
663

664
    @BeforeEach
665
    public void setUp() throws LifecycleException {
666
        tomcat = new Tomcat();
667
        tomcat.setPort(port);
668
        tomcat.setBaseDir(new File("target/tomcat-test").getAbsolutePath());
669

670
        Context ctx = tomcat.addContext("", new File(".").getAbsolutePath());
671

672
        tomcat.start();
673
    }
674

675
    @AfterEach
676
    public void tearDown() throws LifecycleException {
677
        if (tomcat != null) {
678
            tomcat.stop();
679
            tomcat.destroy();
680
        }
681
    }
682

683
    @Test
684
    public void testServer() throws Exception {
685
        // Test HTTP requests against embedded server
686
        String url = "http://localhost:" + port + "/test";
687
        // ... perform HTTP request testing
688
    }
689
}
690
```
691

692
### Advanced Context Configuration
693

694
```java
695
import org.apache.catalina.startup.Tomcat;
696
import org.apache.catalina.Context;
697
import org.apache.catalina.Host;
698
import java.io.File;
699

700
public class AdvancedContextExample {
701
    public static void main(String[] args) throws Exception {
702
        Tomcat tomcat = new Tomcat();
703
        tomcat.setPort(8080);
704
        tomcat.setBaseDir("target/tomcat");
705

706
        Host host = tomcat.getHost();
707

708
        // Create context with explicit name (useful for managing multiple contexts)
709
        Context ctx = tomcat.addContext(host, "/myapp", "myapp-v1",
710
            new File("webapps/myapp").getAbsolutePath());
711

712
        // Initialize with default servlets, JSP support, and MIME types
713
        Tomcat.initWebappDefaults(ctx);
714

715
        tomcat.start();
716
        tomcat.getServer().await();
717
    }
718
}
719
```
720

721
### Custom Webapp Configuration without Default web.xml
722

723
```java
724
import org.apache.catalina.startup.Tomcat;
725
import org.apache.catalina.Context;
726
import org.apache.catalina.LifecycleListener;
727
import org.apache.catalina.startup.ContextConfig;
728
import java.io.File;
729

730
public class CustomWebappConfig {
731
    public static void main(String[] args) throws Exception {
732
        Tomcat tomcat = new Tomcat();
733
        tomcat.setPort(8080);
734
        tomcat.setBaseDir("target/tomcat");
735

736
        // Prevent default web.xml from being applied
737
        tomcat.setAddDefaultWebXmlToWebapp(false);
738

739
        Context ctx = tomcat.addContext("", new File("webapp").getAbsolutePath());
740

741
        // Manually add default web.xml listener for JSP support
742
        LifecycleListener listener = tomcat.getDefaultWebXmlListener();
743
        ctx.addLifecycleListener(listener);
744

745
        // Configure to skip default web.xml processing
746
        String noDefaultWebXml = tomcat.noDefaultWebXmlPath();
747
        for (LifecycleListener l : ctx.findLifecycleListeners()) {
748
            if (l instanceof ContextConfig) {
749
                ((ContextConfig) l).setDefaultWebXml(noDefaultWebXml);
750
            }
751
        }
752

753
        // Add only specific default MIME type mappings
754
        Tomcat.addDefaultMimeTypeMappings(ctx);
755

756
        tomcat.start();
757
        tomcat.getServer().await();
758
    }
759
}
760
```
761

762
## Types
763

764
### EncodedSolidusHandling
765

766
Enum for handling encoded solidus characters in request dispatcher paths.
767

768
```java { .api }
769
public enum EncodedSolidusHandling {
770
    /** Reject requests that contain encoded solidus */
771
    REJECT,
772
    /** Pass encoded solidus through without decoding */
773
    PASS_THROUGH,
774
    /** Decode encoded solidus */
775
    DECODE
776
}
777
```
778

779
### ThreadBindingListener
780

781
Interface for receiving notifications when a request enters/exits the application scope.
782

783
```java { .api }
784
public interface ThreadBindingListener {
785
    /** Called when a thread is bound to the context */
786
    void bind();
787
    /** Called when a thread is unbound from the context */
788
    void unbind();
789
}
790
```
791