0
# Web Application Context
1

2
The WebAppContext is the main entry point for deploying and managing web applications in Jetty EE10. It extends ServletContextHandler and coordinates the construction and configuration of nested handlers including security, session, and servlet handlers.
3

4
## Core WebAppContext Class
5

6
```java { .api }
7
public class WebAppContext extends ServletContextHandler 
8
    implements WebAppClassLoader.Context, Deployable {
9
    
10
    // Constructors
11
    public WebAppContext();
12
    public WebAppContext(String webApp, String contextPath);
13
    public WebAppContext(Resource webApp, String contextPath);
14
    public WebAppContext(SessionHandler sessionHandler, 
15
        SecurityHandler securityHandler, ServletHandler servletHandler, 
16
        ErrorHandler errorHandler);
17
    
18
    // Static methods
19
    public static WebAppContext getCurrentWebAppContext();
20
    
21
    // Configuration methods
22
    public void initializeDefaults(Map<String, String> properties);
23
    public boolean configure() throws Exception;
24
    public void preConfigure() throws Exception;
25
    public void postConfigure() throws Exception;
26
    
27
    // Context path management
28
    public boolean isContextPathDefault();
29
    public void setContextPath(String contextPath);
30
    public void setDefaultContextPath(String contextPath);
31
    
32
    // WAR and resource management
33
    public String getWar();
34
    public void setWar(String war);
35
    public void setWarResource(Resource war);
36
    public Resource getResource(String pathInContext) throws MalformedURLException;
37
    public Resource getWebInf() throws IOException;
38
    
39
    // Resource aliases
40
    public void setResourceAlias(String alias, String uri);
41
    public Map<String, String> getResourceAliases();
42
    public String getResourceAlias(String path);
43
    
44
    // ClassLoader management
45
    public void setClassLoader(ClassLoader classLoader);
46
    public ResourceFactory getResourceFactory();
47
    
48
    // Configuration discovery and management
49
    public boolean isConfigurationDiscovered();
50
    public void setConfigurationDiscovered(boolean discovered);
51
    public String[] getConfigurationClasses();
52
    public Configurations getConfigurations();
53
    
54
    // Descriptor management
55
    public String getDefaultsDescriptor();
56
    public String getOverrideDescriptor();
57
    public List<String> getOverrideDescriptors();
58
    
59
    // Security and permissions
60
    public PermissionCollection getPermissions();
61
    
62
    // Class visibility controls
63
    public void setHiddenClassMatcher(ClassMatcher hiddenClasses);
64
    public void setProtectedClassMatcher(ClassMatcher protectedClasses);
65
    public ClassMatcher getProtectedClassMatcher();
66
    public ClassMatcher getHiddenClassMatcher();
67
    public String[] getProtectedClasses();
68
    public String[] getHiddenClasses();
69
    public boolean isHiddenClass(Class<?> clazz);
70
    public boolean isProtectedClass(Class<?> clazz);
71
    
72
    // Deployment options
73
    public boolean isDistributable();
74
    public boolean isExtractWAR();
75
    public boolean isCopyWebDir();
76
    public boolean isCopyWebInf();
77
    public boolean isParentLoaderPriority();
78
    
79
    // Classpath extensions
80
    public List<Resource> getExtraClasspath();
81
    public void setExtraClasspath(String extraClasspath);
82
    public void setExtraClasspath(List<Resource> extraClasspath);
83
    
84
    // Metadata access
85
    public MetaData getMetaData();
86
    
87
    // Exception handling
88
    public Throwable getUnavailableException();
89
    
90
    // Display name
91
    public void setDisplayName(String servletContextName);
92
}
93
```
94

95
## Usage Examples
96

97
### Basic Web Application Setup
98

99
```java
100
import org.eclipse.jetty.ee10.webapp.WebAppContext;
101
import org.eclipse.jetty.server.Server;
102

103
// Create and configure a web application
104
WebAppContext webapp = new WebAppContext();
105
webapp.setWar("/path/to/myapp.war");
106
webapp.setContextPath("/myapp");
107

108
// Optional: Set resource aliases
109
webapp.setResourceAlias("/docs", "/usr/share/doc/myapp");
110

111
// Add to server
112
Server server = new Server(8080);
113
server.setHandler(webapp);
114
server.start();
115
```
116

117
### Directory-Based Web Application
118

119
```java
120
import org.eclipse.jetty.ee10.webapp.WebAppContext;
121
import org.eclipse.jetty.util.resource.ResourceFactory;
122

123
// Deploy from directory instead of WAR
124
WebAppContext webapp = new WebAppContext();
125
webapp.setWarResource(ResourceFactory.of(webapp).newResource("/path/to/webapp/dir"));
126
webapp.setContextPath("/myapp");
127

128
// Configure extraction options
129
webapp.setExtractWAR(false); // Don't extract since it's already a directory
130
webapp.setCopyWebDir(false);
131
```
132

133
### Custom ClassLoader Configuration
134

135
```java
136
import org.eclipse.jetty.ee10.webapp.WebAppContext;
137
import org.eclipse.jetty.util.ClassMatcher;
138

139
WebAppContext webapp = new WebAppContext();
140
webapp.setWar("/path/to/webapp.war");
141
webapp.setContextPath("/myapp");
142

143
// Configure class visibility
144
ClassMatcher protectedClasses = new ClassMatcher();
145
protectedClasses.add("org.eclipse.jetty.");
146
protectedClasses.add("java.lang.");
147
webapp.setProtectedClassMatcher(protectedClasses);
148

149
ClassMatcher hiddenClasses = new ClassMatcher();
150
hiddenClasses.add("org.eclipse.jetty.util.log.");
151
webapp.setHiddenClassMatcher(hiddenClasses);
152

153
// Add extra classpath entries
154
webapp.setExtraClasspath("/path/to/extra/classes:/path/to/lib/custom.jar");
155
```
156

157
### Configuration Management
158

159
```java
160
import org.eclipse.jetty.ee10.webapp.WebAppContext;
161
import org.eclipse.jetty.ee10.webapp.Configurations;
162
import org.eclipse.jetty.ee10.webapp.WebXmlConfiguration;
163
import org.eclipse.jetty.ee10.webapp.MetaInfConfiguration;
164

165
WebAppContext webapp = new WebAppContext();
166
webapp.setWar("/path/to/webapp.war");
167
webapp.setContextPath("/myapp");
168

169
// Custom configuration set
170
Configurations configs = new Configurations();
171
configs.add(new WebXmlConfiguration());
172
configs.add(new MetaInfConfiguration());
173
webapp.setConfigurations(configs);
174

175
// Alternative: Use default configurations
176
webapp.setConfigurationDiscovered(true);
177
```
178

179
### Programmatic Deployment Lifecycle
180

181
```java
182
import org.eclipse.jetty.ee10.webapp.WebAppContext;
183

184
WebAppContext webapp = new WebAppContext("/path/to/webapp.war", "/myapp");
185

186
try {
187
    // Manual lifecycle management
188
    webapp.preConfigure();
189
    boolean success = webapp.configure();
190
    if (success) {
191
        webapp.postConfigure();
192
        // Web application is now ready
193
    }
194
} catch (Exception e) {
195
    // Handle configuration errors
196
    System.err.println("Failed to configure webapp: " + e.getMessage());
197
}
198
```
199

200
### Resource and Descriptor Override
201

202
```java
203
import org.eclipse.jetty.ee10.webapp.WebAppContext;
204

205
WebAppContext webapp = new WebAppContext();
206
webapp.setWar("/path/to/webapp.war");
207
webapp.setContextPath("/myapp");
208

209
// Override default descriptors
210
webapp.setDefaultsDescriptor("/path/to/custom-webdefault.xml");
211
webapp.setOverrideDescriptor("/path/to/override.xml");
212

213
// Multiple override descriptors
214
List<String> overrides = Arrays.asList(
215
    "/path/to/override1.xml",
216
    "/path/to/override2.xml"
217
);
218
webapp.setOverrideDescriptors(overrides);
219
```
220

221
## WebAppContext.Context Interface
222

223
The WebAppContext implements the Context interface that provides services to the WebAppClassLoader:
224

225
```java { .api }
226
public interface Context {
227
    Resource newResource(String urlOrPath) throws IOException;
228
    PermissionCollection getPermissions();
229
    boolean isParentLoaderPriority();
230
    List<Resource> getExtraClasspath();
231
    boolean isHiddenResource(String name, URL parentUrl);
232
    boolean isProtectedResource(String name, URL webappUrl);
233
}
234
```
235

236
## Key Constants
237

238
```java { .api }
239
public static final String WEB_DEFAULTS_XML = 
240
    "org/eclipse/jetty/ee10/webapp/webdefault-ee10.xml";
241

242
// Deprecated constants (use WebAppClassLoading equivalents)
243
@Deprecated
244
public static final String SERVER_SYS_CLASSES = 
245
    WebAppClassLoading.PROTECTED_CLASSES_ATTRIBUTE;
246
@Deprecated  
247
public static final String SERVER_SRV_CLASSES = 
248
    WebAppClassLoading.HIDDEN_CLASSES_ATTRIBUTE;
249
```
250

251
## Error Handling
252

253
WebAppContext methods can throw various exceptions during configuration and deployment:
254

255
- `Exception` - General configuration errors during configure(), preConfigure(), postConfigure()
256
- `MalformedURLException` - Invalid URL when accessing resources via getResource()
257
- `IOException` - I/O errors when accessing WAR files or directories
258

259
Common error scenarios:
260
- Invalid WAR file path or corrupted WAR
261
- Missing required configuration files
262
- ClassLoader conflicts with protected/hidden class patterns
263
- Insufficient permissions for resource access
264
- Circular dependencies in configuration chain