0
# Web Application Context
1

2
WebAppContext is the central component for managing web application deployment in Jetty. It orchestrates the complete lifecycle of a web application, from initial configuration through deployment and runtime management.
3

4
## Capabilities
5

6
### Core WebAppContext Class
7

8
The main entry point for creating and managing web application contexts.
9

10
```java { .api }
11
/**
12
 * Web application context that coordinates construction and configuration of
13
 * nested handlers including security, session, and servlet handlers.
14
 */
15
public class WebAppContext extends ServletContextHandler implements WebAppClassLoader.Context {
16
    
17
    // Core constructors
18
    public WebAppContext();
19
    public WebAppContext(String webApp, String contextPath);
20
    public WebAppContext(Resource webApp, String contextPath);
21
    public WebAppContext(HandlerContainer parent, String webApp, String contextPath);
22
    public WebAppContext(HandlerContainer parent, Resource webApp, String contextPath);
23
    
24
    // Full constructor for custom handler configuration
25
    public WebAppContext(HandlerContainer parent, String contextPath, 
26
                        SessionHandler sessionHandler, SecurityHandler securityHandler, 
27
                        ServletHandler servletHandler, ErrorHandler errorHandler, int options);
28
}
29
```
30

31
**Usage Examples:**
32

33
```java
34
// Basic webapp setup
35
WebAppContext webapp = new WebAppContext();
36
webapp.setContextPath("/myapp");
37
webapp.setWar("myapp.war");
38

39
// With parent container
40
WebAppContext webapp = new WebAppContext(server, "myapp.war", "/myapp");
41

42
// With custom handlers
43
WebAppContext webapp = new WebAppContext(
44
    server, "/myapp",
45
    new SessionHandler(),
46
    new ConstraintSecurityHandler(),
47
    new ServletHandler(),
48
    new ErrorPageErrorHandler(),
49
    ServletContextHandler.SESSIONS | ServletContextHandler.SECURITY
50
);
51
```
52

53
### Configuration Management
54

55
Methods for managing the pluggable configuration system.
56

57
```java { .api }
58
/**
59
 * Get the configuration class names
60
 */
61
public String[] getConfigurationClasses();
62

63
/**
64
 * Get the configurations object managing all configuration instances
65
 */
66
public Configurations getConfigurations();
67

68
/**
69
 * Set configuration classes by name
70
 */
71
public void setConfigurationClasses(String[] configurations);
72
public void setConfigurationClasses(List<String> configurations);
73

74
/**
75
 * Set configuration instances directly
76
 */
77
public void setConfigurations(Configuration[] configurations);
78

79
/**
80
 * Add configurations to the existing set
81
 */
82
public void addConfiguration(Configuration... configuration);
83

84
/**
85
 * Get configuration by type
86
 */
87
public <T> T getConfiguration(Class<? extends T> configClass);
88

89
/**
90
 * Remove configurations
91
 */
92
public void removeConfiguration(Configuration... configurations);
93
public void removeConfiguration(Class<? extends Configuration>... configurations);
94
```
95

96
**Usage Examples:**
97

98
```java
99
// Set standard configurations
100
webapp.setConfigurationClasses(new String[] {
101
    "org.eclipse.jetty.webapp.WebInfConfiguration",
102
    "org.eclipse.jetty.webapp.WebXmlConfiguration",
103
    "org.eclipse.jetty.webapp.MetaInfConfiguration"
104
});
105

106
// Add custom configuration
107
webapp.addConfiguration(new MyCustomConfiguration());
108

109
// Get specific configuration
110
WebXmlConfiguration webXml = webapp.getConfiguration(WebXmlConfiguration.class);
111
```
112

113
### WAR and Resource Management
114

115
Methods for specifying and managing webapp resources.
116

117
```java { .api }
118
/**
119
 * Set the web application WAR file or directory
120
 */
121
public void setWar(String war);
122
public void setWarResource(Resource war);
123
public String getWar();
124

125
/**
126
 * Get the WEB-INF directory resource
127
 */
128
public Resource getWebInf();
129

130
/**
131
 * Manage resource aliases for virtual paths
132
 */
133
public Map<String, String> getResourceAliases();
134
public void setResourceAliases(Map<String, String> map);
135
public void setResourceAlias(String alias, String uri);
136
public String getResourceAlias(String path);
137
public String removeResourceAlias(String alias);
138

139
/**
140
 * Manage extra classpath resources
141
 */
142
public List<Resource> getExtraClasspath();
143
public void setExtraClasspath(String extraClasspath);
144
public void setExtraClasspath(List<Resource> extraClasspath);
145
```
146

147
**Usage Examples:**
148

149
```java
150
// Set WAR file location
151
webapp.setWar("path/to/myapp.war");
152

153
// Add extra classpath entries
154
webapp.setExtraClasspath("lib/extra.jar:lib/configs");
155

156
// Set resource aliases
157
webapp.setResourceAlias("/images", "/static/img");
158
```
159

160
### Descriptor Management
161

162
Methods for managing XML descriptors that configure the webapp.
163

164
```java { .api }
165
/**
166
 * Get/set the defaults descriptor (web-defaults.xml)
167
 */
168
public String getDefaultsDescriptor();
169
public void setDefaultsDescriptor(String defaultsDescriptor);
170

171
/**
172
 * Get/set the main web descriptor (web.xml)
173
 */
174
public String getDescriptor();
175
public void setDescriptor(String descriptor);
176

177
/**
178
 * Manage override descriptors
179
 */
180
public String getOverrideDescriptor();
181
public List<String> getOverrideDescriptors();
182
public void setOverrideDescriptor(String overrideDescriptor);
183
public void setOverrideDescriptors(List<String> overrideDescriptors);
184
public void addOverrideDescriptor(String overrideDescriptor);
185
```
186

187
**Usage Examples:**
188

189
```java
190
// Use custom web-defaults.xml
191
webapp.setDefaultsDescriptor("config/custom-webdefaults.xml");
192

193
// Add override descriptors
194
webapp.addOverrideDescriptor("config/production-overrides.xml");
195
webapp.addOverrideDescriptor("config/database-overrides.xml");
196
```
197

198
### ClassLoader Configuration
199

200
Methods for configuring the webapp's class loading behavior.
201

202
```java { .api }
203
/**
204
 * Get/set system class patterns (loaded by system classloader)
205
 */
206
public ClassMatcher getSystemClassMatcher();
207
public void setSystemClassMatcher(ClassMatcher systemClasses);
208
public void addSystemClassMatcher(ClassMatcher systemClasses);
209
public String[] getSystemClasses();
210

211
/**
212
 * Get/set server class patterns (loaded by server classloader)
213
 */
214
public ClassMatcher getServerClassMatcher();
215
public void setServerClassMatcher(ClassMatcher serverClasses);
216
public void addServerClassMatcher(ClassMatcher serverClasses);
217
public String[] getServerClasses();
218

219
/**
220
 * Control parent-first vs child-first class loading
221
 */
222
public boolean isParentLoaderPriority();
223
public void setParentLoaderPriority(boolean java2compliant);
224
```
225

226
**Usage Examples:**
227

228
```java
229
// Add system classes (loaded by system classloader)
230
webapp.addSystemClassMatcher(new ClassMatcher("com.mycompany.shared."));
231

232
// Add server classes (hidden from webapp)
233
webapp.addServerClassMatcher(new ClassMatcher("org.eclipse.jetty."));
234

235
// Use parent-first class loading
236
webapp.setParentLoaderPriority(true);
237
```
238

239
### Lifecycle Management
240

241
Methods for managing the webapp deployment lifecycle.
242

243
```java { .api }
244
/**
245
 * Pre-configure the webapp (setup classloader, parse descriptors)
246
 */
247
public void preConfigure() throws Exception;
248

249
/**
250
 * Configure the webapp (process configurations)
251
 */
252
public boolean configure() throws Exception;
253

254
/**
255
 * Post-configure the webapp (finalize setup)
256
 */
257
public void postConfigure() throws Exception;
258

259
/**
260
 * Get any exception that prevented startup
261
 */
262
public Throwable getUnavailableException();
263
```
264

265
**Usage Examples:**
266

267
```java
268
try {
269
    webapp.preConfigure();
270
    if (webapp.configure()) {
271
        webapp.postConfigure();
272
        webapp.start();
273
    }
274
} catch (Exception e) {
275
    Throwable cause = webapp.getUnavailableException();
276
    // Handle startup failure
277
}
278
```
279

280
### Configuration Properties
281

282
Various configuration properties that control webapp behavior.
283

284
```java { .api }
285
/**
286
 * Distributable webapp configuration
287
 */
288
public boolean isDistributable();
289
public void setDistributable(boolean distributable);
290

291
/**
292
 * WAR extraction configuration
293
 */
294
public boolean isExtractWAR();
295
public void setExtractWAR(boolean extractWAR);
296

297
/**
298
 * Directory copying configuration
299
 */
300
public boolean isCopyWebDir();
301
public void setCopyWebDir(boolean copy);
302
public boolean isCopyWebInf();
303
public void setCopyWebInf(boolean copyWebInf);
304

305
/**
306
 * Configuration discovery
307
 */
308
public boolean isConfigurationDiscovered();
309
public void setConfigurationDiscovered(boolean discovered);
310

311
/**
312
 * Fragment handling
313
 */
314
public boolean isAllowDuplicateFragmentNames();
315
public void setAllowDuplicateFragmentNames(boolean allowDuplicateFragmentNames);
316

317
/**
318
 * Exception handling
319
 */
320
public boolean isThrowUnavailableOnStartupException();
321
public void setThrowUnavailableOnStartupException(boolean throwIfStartupException);
322

323
/**
324
 * Logging configuration
325
 */
326
public boolean isLogUrlOnStart();
327
public void setLogUrlOnStart(boolean logOnStart);
328
```
329

330
### Temporary Directory Management
331

332
Methods for managing the webapp's temporary directory.
333

334
```java { .api }
335
/**
336
 * Get/set the temporary directory for the webapp
337
 */
338
public File getTempDirectory();
339
public void setTempDirectory(File dir);
340

341
/**
342
 * Control whether temp directory persists after webapp stops
343
 */
344
public boolean isPersistTempDirectory();
345
public void setPersistTempDirectory(boolean persist);
346
```
347

348
### Security and Permissions
349

350
Methods for managing webapp security and permissions.
351

352
```java { .api }
353
/**
354
 * Get/set permissions for the webapp
355
 */
356
public PermissionCollection getPermissions();
357
public void setPermissions(PermissionCollection permissions);
358

359
/**
360
 * Set context whitelist for cross-context access
361
 */
362
public void setContextWhiteList(String... contextWhiteList);
363
```
364

365
### Static Utility Methods
366

367
Static utility methods for webapp management.
368

369
```java { .api }
370
/**
371
 * Get the current WebAppContext from the current thread
372
 */
373
public static WebAppContext getCurrentWebAppContext();
374

375
/**
376
 * Add server class patterns to all webapps on a server
377
 */
378
public static void addServerClasses(Server server, String... pattern);
379

380
/**
381
 * Add system class patterns to all webapps on a server
382
 */
383
public static void addSystemClasses(Server server, String... pattern);
384
```
385

386
**Usage Examples:**
387

388
```java
389
// Get current webapp context (useful in servlets/filters)
390
WebAppContext currentContext = WebAppContext.getCurrentWebAppContext();
391

392
// Add server-wide class patterns
393
WebAppContext.addServerClasses(server, "com.mycompany.server.");
394
WebAppContext.addSystemClasses(server, "com.mycompany.shared.");
395
```
396

397
### Metadata Access
398

399
Access to the webapp's configuration metadata.
400

401
```java { .api }
402
/**
403
 * Get the metadata object containing all webapp configuration information
404
 */
405
public MetaData getMetaData();
406
```
407

408
### Inner Context Class
409

410
The inner Context class that extends ServletContextHandler.Context with webapp-specific behavior.
411

412
```java { .api }
413
/**
414
 * WebApp-specific servlet context implementation
415
 */
416
public static class Context extends ServletContextHandler.Context {
417
    /**
418
     * Check if a listener class type is valid for this webapp
419
     */
420
    public void checkListener(Class<? extends EventListener> listener) throws IllegalStateException;
421
    
422
    /**
423
     * Get resource URL with webapp-specific resource resolution
424
     */
425
    public URL getResource(String path) throws MalformedURLException;
426
    
427
    /**
428
     * Get servlet context for a URI path (cross-context access)
429
     */
430
    public ServletContext getContext(String uripath);
431
}
432
```
433

434
## Constants
435

436
```java { .api }
437
// Standard servlet context attributes
438
public static final String TEMPDIR = ServletContext.TEMPDIR;
439
public static final String BASETEMPDIR = "org.eclipse.jetty.webapp.basetempdir";
440

441
// Default configuration files
442
public static final String WEB_DEFAULTS_XML = "org/eclipse/jetty/webapp/webdefault.xml";
443

444
// Server configuration attributes
445
public static final String SERVER_SYS_CLASSES = "org.eclipse.jetty.webapp.systemClasses";
446
public static final String SERVER_SRV_CLASSES = "org.eclipse.jetty.webapp.serverClasses";
447

448
// Error handling
449
public static final String ERROR_PAGE = "org.eclipse.jetty.server.error_page";
450

451
// Default class matchers
452
public static final ClassMatcher __dftSystemClasses;
453
public static final ClassMatcher __dftServerClasses;
454
```