0
# Catalina Core Containers
1

2
The Catalina servlet engine provides the hierarchical container architecture that manages web applications and servlets. This includes Server, Service, Engine, Host, Context, and Wrapper containers with full lifecycle management, nested component relationships, and request processing through pipelines.
3

4
## Capabilities
5

6
### Container Hierarchy
7

8
The base container interface and hierarchy for all Tomcat components.
9

10
```java { .api }
11
public interface Container extends Lifecycle {
12
    // Container identification
13
    String getName();
14
    void setName(String name);
15
    String getLogName();
16
    String getDomain();
17
    String getMBeanKeyProperties();
18
    ObjectName getObjectName();
19
    
20
    // Container hierarchy
21
    Container getParent();
22
    void setParent(Container container);
23
    void setParentClassLoader(ClassLoader parent);
24
    ClassLoader getParentClassLoader();
25
    void addChild(Container child);
26
    void removeChild(Container child);
27
    Container findChild(String name);
28
    Container[] findChildren();
29
    
30
    // Background processing
31
    int getBackgroundProcessorDelay();
32
    void setBackgroundProcessorDelay(int delay);
33
    void backgroundProcess();
34
    
35
    // Pipeline and valves
36
    Pipeline getPipeline();
37
    
38
    // Realm (authentication)
39
    Realm getRealm();
40
    void setRealm(Realm realm);
41
    
42
    // Clustering
43
    Cluster getCluster();
44
    void setCluster(Cluster cluster);
45
    
46
    // Event listeners
47
    void addContainerListener(ContainerListener listener);
48
    void removeContainerListener(ContainerListener listener);
49
    ContainerListener[] findContainerListeners();
50
    void fireContainerEvent(String type, Object data);
51
    
52
    // Property change support
53
    void addPropertyChangeListener(PropertyChangeListener listener);
54
    void removePropertyChangeListener(PropertyChangeListener listener);
55
    
56
    // Logging
57
    Log getLogger();
58

59
    // Access logging
60
    void logAccess(Request request, Response response, long time, boolean useDefault);
61
    AccessLog getAccessLog();
62
    
63
    // Child start/stop configuration
64
    int getStartStopThreads();
65
    void setStartStopThreads(int startStopThreads);
66
}
67

68
public interface Contained {
69
    Container getContainer();
70
    void setContainer(Container container);
71
}
72
```
73

74
### Server
75

76
Top-level container representing the entire Tomcat instance.
77

78
```java { .api }
79
public interface Server extends Lifecycle {
80
    // Global naming resources
81
    NamingResourcesImpl getGlobalNamingResources();
82
    void setGlobalNamingResources(NamingResourcesImpl globalNamingResources);
83
    javax.naming.Context getGlobalNamingContext();
84
    
85
    // Shutdown configuration
86
    int getPort();
87
    void setPort(int port);
88
    int getPortOffset();
89
    void setPortOffset(int portOffset);
90
    int getPortWithOffset();
91
    String getAddress();
92
    void setAddress(String address);
93
    String getShutdown();
94
    void setShutdown(String shutdown);
95
    
96
    // Catalina reference
97
    Catalina getCatalina();
98
    void setCatalina(Catalina catalina);
99
    
100
    // Directory configuration
101
    File getCatalinaBase();
102
    void setCatalinaBase(File catalinaBase);
103
    File getCatalinaHome();
104
    void setCatalinaHome(File catalinaHome);
105
    
106
    // Classloader
107
    ClassLoader getParentClassLoader();
108
    void setParentClassLoader(ClassLoader parent);
109
    
110
    // Thread configuration
111
    int getUtilityThreads();
112
    void setUtilityThreads(int utilityThreads);
113
    
114
    // Services
115
    void addService(Service service);
116
    void removeService(Service service);
117
    Service findService(String name);
118
    Service[] findServices();
119
    
120
    // Server lifecycle
121
    void await();
122
    
123
    // JNDI token
124
    Object getNamingToken();
125
    
126
    // Utility executor
127
    ScheduledExecutorService getUtilityExecutor();
128
}
129
```
130

131
### Service
132

133
Groups Connectors with an Engine, managing protocol handlers and the servlet engine.
134

135
```java { .api }
136
public interface Service extends Lifecycle {
137
    // Engine (container)
138
    Engine getContainer();
139
    void setContainer(Engine engine);
140
    
141
    // Service identification
142
    String getName();
143
    void setName(String name);
144
    
145
    // Server reference
146
    Server getServer();
147
    void setServer(Server server);
148
    
149
    // Classloader
150
    ClassLoader getParentClassLoader();
151
    void setParentClassLoader(ClassLoader parent);
152
    
153
    // Domain (JMX)
154
    String getDomain();
155
    
156
    // Connectors
157
    void addConnector(Connector connector);
158
    Connector[] findConnectors();
159
    void removeConnector(Connector connector);
160
    
161
    // Executors (thread pools)
162
    void addExecutor(Executor ex);
163
    Executor[] findExecutors();
164
    Executor getExecutor(String name);
165
    void removeExecutor(Executor ex);
166
    
167
    // Mapper
168
    Mapper getMapper();
169
}
170
```
171

172
### Engine
173

174
Container managing virtual hosts and routing requests.
175

176
```java { .api }
177
public interface Engine extends Container {
178
    // Default host
179
    String getDefaultHost();
180
    void setDefaultHost(String defaultHost);
181
    
182
    // JVM route (for load balancing)
183
    String getJvmRoute();
184
    void setJvmRoute(String jvmRouteId);
185
    
186
    // Service reference
187
    Service getService();
188
    void setService(Service service);
189
}
190
```
191

192
### Host
193

194
Virtual host container managing web application contexts.
195

196
```java { .api }
197
public interface Host extends Container {
198
    // XML configuration base
199
    String getXmlBase();
200
    void setXmlBase(String xmlBase);
201
    File getConfigBaseFile();
202
    
203
    // Application base directory
204
    String getAppBase();
205
    void setAppBase(String appBase);
206
    File getAppBaseFile();
207
    String getLegacyAppBase();
208
    void setLegacyAppBase(String legacyAppBase);
209
    
210
    // Deployment configuration
211
    boolean getAutoDeploy();
212
    void setAutoDeploy(boolean autoDeploy);
213
    String getConfigClass();
214
    void setConfigClass(String configClass);
215
    boolean getDeployOnStartup();
216
    void setDeployOnStartup(boolean deployOnStartup);
217
    String getDeployIgnore();
218
    void setDeployIgnore(String deployIgnore);
219
    Pattern getDeployIgnorePattern();
220
    boolean getCreateDirs();
221
    void setCreateDirs(boolean createDirs);
222
    boolean getUndeployOldVersions();
223
    void setUndeployOldVersions(boolean undeployOldVersions);
224
    
225
    // Host aliases
226
    void addAlias(String alias);
227
    String[] findAliases();
228
    void removeAlias(String alias);
229
}
230
```
231

232
### Context (detailed in embedded-tomcat.md)
233

234
Represents a web application with servlets, filters, and resources.
235

236
```java { .api }
237
// See embedded-tomcat.md for complete Context interface documentation
238
public interface Context extends Container {
239
    // Basic configuration
240
    void setPath(String path);
241
    String getPath();
242
    void setDocBase(String docBase);
243
    String getDocBase();
244
    
245
    // Servlet management
246
    void addServletMappingDecoded(String pattern, String name, boolean jspWildCard);
247
    
248
    // Lifecycle
249
    void reload();
250
    void backgroundProcess();
251
}
252
```
253

254
### Wrapper (detailed in embedded-tomcat.md)
255

256
Represents an individual servlet.
257

258
```java { .api }
259
// See embedded-tomcat.md for complete Wrapper interface documentation
260
public interface Wrapper extends Container {
261
    void setServletClass(String servletClass);
262
    String getServletClass();
263
    void setLoadOnStartup(int value);
264
    int getLoadOnStartup();
265
}
266
```
267

268
### Lifecycle Management
269

270
Standard lifecycle interface for all Tomcat components.
271

272
```java { .api }
273
public interface Lifecycle {
274
    // Event type constants
275
    String BEFORE_INIT_EVENT = "before_init";
276
    String AFTER_INIT_EVENT = "after_init";
277
    String START_EVENT = "start";
278
    String BEFORE_START_EVENT = "before_start";
279
    String AFTER_START_EVENT = "after_start";
280
    String STOP_EVENT = "stop";
281
    String BEFORE_STOP_EVENT = "before_stop";
282
    String AFTER_STOP_EVENT = "after_stop";
283
    String AFTER_DESTROY_EVENT = "after_destroy";
284
    String BEFORE_DESTROY_EVENT = "before_destroy";
285
    String PERIODIC_EVENT = "periodic";
286
    String CONFIGURE_START_EVENT = "configure_start";
287
    String CONFIGURE_STOP_EVENT = "configure_stop";
288
    
289
    // Lifecycle methods
290
    void addLifecycleListener(LifecycleListener listener);
291
    LifecycleListener[] findLifecycleListeners();
292
    void removeLifecycleListener(LifecycleListener listener);
293
    void init() throws LifecycleException;
294
    void start() throws LifecycleException;
295
    void stop() throws LifecycleException;
296
    void destroy() throws LifecycleException;
297
    
298
    // State management
299
    LifecycleState getState();
300
    String getStateName();
301
}
302

303
public interface LifecycleListener {
304
    void lifecycleEvent(LifecycleEvent event);
305
}
306

307
public class LifecycleEvent extends EventObject {
308
    public LifecycleEvent(Lifecycle lifecycle, String type, Object data);
309

310
    public Object getData();
311
    public Lifecycle getLifecycle();
312
    public String getType();
313
}
314

315
public enum LifecycleState {
316
    NEW(false, null),
317
    INITIALIZING(false, Lifecycle.BEFORE_INIT_EVENT),
318
    INITIALIZED(false, Lifecycle.AFTER_INIT_EVENT),
319
    STARTING_PREP(false, Lifecycle.BEFORE_START_EVENT),
320
    STARTING(true, Lifecycle.START_EVENT),
321
    STARTED(true, Lifecycle.AFTER_START_EVENT),
322
    STOPPING_PREP(true, Lifecycle.BEFORE_STOP_EVENT),
323
    STOPPING(false, Lifecycle.STOP_EVENT),
324
    STOPPED(false, Lifecycle.AFTER_STOP_EVENT),
325
    DESTROYING(false, Lifecycle.BEFORE_DESTROY_EVENT),
326
    DESTROYED(false, Lifecycle.AFTER_DESTROY_EVENT),
327
    FAILED(false, null);
328
    
329
    public boolean isAvailable();
330
    public String getLifecycleEvent();
331
}
332

333
public final class LifecycleException extends Exception {
334
    public LifecycleException();
335
    public LifecycleException(String message);
336
    public LifecycleException(Throwable throwable);
337
    public LifecycleException(String message, Throwable throwable);
338
}
339
```
340

341
### Pipeline and Valve
342

343
Request processing pipeline for each container.
344

345
```java { .api }
346
public interface Pipeline extends Contained {
347
    // Basic valve
348
    Valve getBasic();
349
    void setBasic(Valve valve);
350
    
351
    // Valve chain
352
    void addValve(Valve valve);
353
    Valve[] getValves();
354
    void removeValve(Valve valve);
355
    Valve getFirst();
356
    
357
    // Async support
358
    boolean isAsyncSupported();
359
    void findNonAsyncValves(Set<String> result);
360
}
361

362
public interface Valve {
363
    // Next valve in chain
364
    Valve getNext();
365
    void setNext(Valve valve);
366
    
367
    // Processing
368
    void invoke(Request request, Response response) throws IOException, ServletException;
369
    boolean isAsyncSupported();
370
    
371
    // Background processing
372
    void backgroundProcess();
373
}
374
```
375

376
### Request and Response (Catalina Internal)
377

378
Internal Catalina request and response objects wrapping Coyote objects.
379

380
```java { .api }
381
// Catalina Request (wraps Coyote Request)
382
public class Request implements HttpServletRequest {
383
    public Request(Connector connector);
384
    
385
    // Coyote request
386
    public void setCoyoteRequest(org.apache.coyote.Request coyoteRequest);
387
    public org.apache.coyote.Request getCoyoteRequest();
388
    
389
    // Components
390
    public Connector getConnector();
391
    public Context getContext();
392
    public void setContext(Context context);
393
    public Host getHost();
394
    public Wrapper getWrapper();
395
    public void setWrapper(Wrapper wrapper);
396
    public Response getResponse();
397
    public void setResponse(Response response);
398
    
399
    // Facade
400
    public HttpServletRequest getRequest();
401
    public void setRequest(HttpServletRequest applicationRequest);
402
    
403
    // Filter chain
404
    public FilterChain getFilterChain();
405
    public void setFilterChain(FilterChain filterChain);
406
    
407
    // Lifecycle
408
    public void recycle();
409
    public void finishRequest() throws IOException;
410
    
411
    // Async support
412
    public boolean isAsync();
413
    public void setAsyncSupported(boolean asyncSupported);
414
    
415
    // Notes (internal attributes)
416
    public Object getNote(String name);
417
    public void setNote(String name, Object value);
418
    public void removeNote(String name);
419
    
420
    // Mapping data
421
    public MappingData getMappingData();
422
    
423
    // Discard facades
424
    public boolean getDiscardFacades();
425
}
426

427
// Catalina Response (wraps Coyote Response)
428
public class Response implements HttpServletResponse {
429
    public Response();
430
    public Response(int outputBufferSize);
431
    
432
    // Coyote response
433
    public void setCoyoteResponse(org.apache.coyote.Response coyoteResponse);
434
    public org.apache.coyote.Response getCoyoteResponse();
435
    
436
    // Context
437
    public Context getContext();
438
    public void setContext(Context context);
439
    
440
    // Request
441
    public Request getRequest();
442
    public void setRequest(Request request);
443
    
444
    // Facade
445
    public HttpServletResponse getResponse();
446
    public void setResponse(HttpServletResponse applicationResponse);
447
    
448
    // Lifecycle
449
    public void recycle();
450
    public void finishResponse() throws IOException;
451
    
452
    // Status
453
    public boolean isCommitted();
454
    public boolean isError();
455
    public boolean setError();
456
    public boolean isErrorReportRequired();
457
    public boolean setErrorReported();
458
    public void resetError();
459
    
460
    // Suspension
461
    public void setSuspended(boolean suspended);
462
    public boolean isSuspended();
463
    public boolean isClosed();
464
    
465
    // Application commit
466
    public void setAppCommitted(boolean appCommitted);
467
    public boolean isAppCommitted();
468
    
469
    // Content
470
    public List<Cookie> getCookies();
471
    public long getContentWritten();
472
    public long getBytesWritten(boolean flush);
473
}
474
```
475

476
## Usage Examples
477

478
### Lifecycle Listener
479

480
```java
481
import org.apache.catalina.Lifecycle;
482
import org.apache.catalina.LifecycleEvent;
483
import org.apache.catalina.LifecycleListener;
484

485
public class CustomLifecycleListener implements LifecycleListener {
486
    @Override
487
    public void lifecycleEvent(LifecycleEvent event) {
488
        if (Lifecycle.BEFORE_START_EVENT.equals(event.getType())) {
489
            System.out.println("Container starting: " + event.getLifecycle());
490
        } else if (Lifecycle.AFTER_START_EVENT.equals(event.getType())) {
491
            System.out.println("Container started: " + event.getLifecycle());
492
        } else if (Lifecycle.BEFORE_STOP_EVENT.equals(event.getType())) {
493
            System.out.println("Container stopping: " + event.getLifecycle());
494
        } else if (Lifecycle.AFTER_STOP_EVENT.equals(event.getType())) {
495
            System.out.println("Container stopped: " + event.getLifecycle());
496
        }
497
    }
498
}
499
```
500

501
### Container Listener
502

503
```java
504
import org.apache.catalina.Container;
505
import org.apache.catalina.ContainerEvent;
506
import org.apache.catalina.ContainerListener;
507

508
public class CustomContainerListener implements ContainerListener {
509
    @Override
510
    public void containerEvent(ContainerEvent event) {
511
        Container container = event.getContainer();
512
        String type = event.getType();
513
        Object data = event.getData();
514
        
515
        if ("addChild".equals(type)) {
516
            System.out.println("Child added to " + container.getName() + ": " + data);
517
        } else if ("removeChild".equals(type)) {
518
            System.out.println("Child removed from " + container.getName() + ": " + data);
519
        }
520
    }
521
}
522
```
523

524
### Accessing Container Hierarchy
525

526
```java
527
import org.apache.catalina.startup.Tomcat;
528
import org.apache.catalina.*;
529

530
public class ContainerHierarchyExample {
531
    public static void main(String[] args) throws Exception {
532
        Tomcat tomcat = new Tomcat();
533
        tomcat.setPort(8080);
534
        
535
        // Access hierarchy
536
        Server server = tomcat.getServer();
537
        Service service = tomcat.getService();
538
        Engine engine = tomcat.getEngine();
539
        Host host = tomcat.getHost();
540
        
541
        Context ctx = tomcat.addContext("/myapp", "/path/to/webapp");
542
        
543
        // Navigate hierarchy
544
        System.out.println("Context parent: " + ctx.getParent().getName()); // Host
545
        System.out.println("Host parent: " + host.getParent().getName()); // Engine
546
        System.out.println("Engine service: " + engine.getService().getName());
547
        
548
        // Enumerate children
549
        Container[] hosts = engine.findChildren();
550
        for (Container h : hosts) {
551
            System.out.println("Host: " + h.getName());
552
            Container[] contexts = h.findChildren();
553
            for (Container c : contexts) {
554
                System.out.println("  Context: " + c.getName());
555
            }
556
        }
557
        
558
        tomcat.start();
559
    }
560
}
561
```
562