0
# Jetty WebApp
1

2
Jetty WebApp is a comprehensive web application support library for the Eclipse Jetty web server and servlet container. It provides complete infrastructure for deploying, configuring, and managing Java web applications (WAR files) with full servlet specification compliance, advanced class loading capabilities, and extensive customization through a pluggable configuration system.
3

4
## Package Information
5

6
- **Package Name**: org.eclipse.jetty:jetty-webapp
7
- **Package Type**: Maven
8
- **Language**: Java
9
- **Installation**: Add to your Maven `pom.xml`:
10

11
```xml
12
<dependency>
13
    <groupId>org.eclipse.jetty</groupId>
14
    <artifactId>jetty-webapp</artifactId>
15
    <version>11.0.25</version>
16
</dependency>
17
```
18

19
For Gradle:
20

21
```gradle
22
implementation 'org.eclipse.jetty:jetty-webapp:11.0.25'
23
```
24

25
## Core Imports
26

27
```java
28
import org.eclipse.jetty.webapp.WebAppContext;
29
import org.eclipse.jetty.webapp.Configuration;
30
import org.eclipse.jetty.webapp.Configurations;
31
import org.eclipse.jetty.webapp.WebAppClassLoader;
32
```
33

34
## Basic Usage
35

36
```java
37
import org.eclipse.jetty.server.Server;
38
import org.eclipse.jetty.webapp.WebAppContext;
39

40
public class WebAppExample {
41
    public static void main(String[] args) throws Exception {
42
        Server server = new Server(8080);
43
        
44
        // Create webapp context
45
        WebAppContext webapp = new WebAppContext();
46
        webapp.setContextPath("/myapp");
47
        webapp.setWar("path/to/myapp.war");
48
        
49
        // Configure and start
50
        server.setHandler(webapp);
51
        server.start();
52
        server.join();
53
    }
54
}
55
```
56

57
## Architecture
58

59
Jetty WebApp is built around several key architectural components:
60

61
- **WebAppContext**: Central orchestrator that coordinates all aspects of webapp deployment and lifecycle management
62
- **Configuration System**: Pluggable configuration components implementing specific aspects of webapp setup (XML processing, class loading, security, etc.)
63
- **ClassLoader Framework**: Servlet-compliant class loading with fine-grained visibility controls and caching capabilities
64
- **Metadata System**: Comprehensive tracking of configuration sources, descriptor processing, and annotation discovery
65
- **Descriptor Processing**: XML descriptor parsing and processing for web.xml, web-fragment.xml, and Jetty-specific configurations
66

67
## Capabilities
68

69
### Web Application Context Management
70

71
Primary interface for creating, configuring, and managing web application contexts with complete lifecycle control and extensive customization options.
72

73
```java { .api }
74
public class WebAppContext extends ServletContextHandler implements WebAppClassLoader.Context {
75
    // Core constructors
76
    public WebAppContext();
77
    public WebAppContext(String webApp, String contextPath);
78
    public WebAppContext(Resource webApp, String contextPath);
79
    
80
    // Configuration management
81
    public void setConfigurationClasses(String[] configurations);
82
    public Configurations getConfigurations();
83
    public void addConfiguration(Configuration... configuration);
84
    
85
    // WAR and resource management
86
    public void setWar(String war);
87
    public void setWarResource(Resource war);
88
    public String getWar();
89
    
90
    // Lifecycle methods
91
    public void preConfigure() throws Exception;
92
    public boolean configure() throws Exception;
93
    public void postConfigure() throws Exception;
94
}
95
```
96

97
[Web Application Context](./webapp-context.md)
98

99
### ClassLoader Management
100

101
Servlet specification compliant class loading with advanced visibility controls, caching, and transformation capabilities for isolated webapp execution.
102

103
```java { .api }
104
public class WebAppClassLoader extends URLClassLoader implements ClassVisibilityChecker {
105
    public WebAppClassLoader(Context context);
106
    public WebAppClassLoader(ClassLoader parent, Context context);
107
    
108
    // Classpath management
109
    public void addClassPath(Resource resource);
110
    public void addJars(Resource lib);
111
    
112
    // Visibility controls
113
    public boolean isSystemClass(Class<?> clazz);
114
    public boolean isServerClass(Class<?> clazz);
115
    
116
    // Transformation support
117
    public void addTransformer(ClassFileTransformer transformer);
118
}
119

120
public class CachingWebAppClassLoader extends WebAppClassLoader {
121
    public void clearCache();
122
}
123
```
124

125
[ClassLoader Management](./classloader.md)
126

127
### Configuration Framework
128

129
Pluggable system for configuring different aspects of webapp deployment through the ServiceLoader pattern with dependency resolution and lifecycle management.
130

131
```java { .api }
132
public interface Configuration {
133
    void preConfigure(WebAppContext context) throws Exception;
134
    void configure(WebAppContext context) throws Exception;
135
    void postConfigure(WebAppContext context) throws Exception;
136
    void deconfigure(WebAppContext context) throws Exception;
137
    
138
    boolean isEnabledByDefault();
139
    Collection<String> getDependencies();
140
    Collection<String> getDependents();
141
}
142

143
public class Configurations extends AbstractList<Configuration> implements Dumpable {
144
    public static Configurations setServerDefault(Server server);
145
    public static List<Configuration> getKnown();
146
    
147
    public void sort();
148
    public boolean configure(WebAppContext webapp) throws Exception;
149
}
150
```
151

152
[Configuration Framework](./configuration.md)
153

154
### Metadata and Descriptor Processing
155

156
Complete metadata container for webapp configuration with descriptor processing, annotation discovery, and origin tracking for all configuration elements.
157

158
```java { .api }
159
public class MetaData {
160
    // Descriptor management
161
    public void setWebDescriptor(WebDescriptor descriptor);
162
    public void addFragmentDescriptor(Resource jarResource, FragmentDescriptor descriptor);
163
    public void addOverrideDescriptor(OverrideDescriptor descriptor);
164
    
165
    // Annotation processing
166
    public void addDiscoveredAnnotations(List<DiscoveredAnnotation> annotations);
167
    
168
    // Resolution and ordering
169
    public void orderFragments();
170
    public void resolve(WebAppContext context) throws Exception;
171
    
172
    // Origin tracking
173
    public Origin getOrigin(String name);
174
    public void setOrigin(String name, Descriptor d);
175
}
176
```
177

178
[Metadata and Descriptors](./metadata.md)
179

180
### Descriptor Classes
181

182
XML descriptor parsing and processing for web.xml, web-fragment.xml, and Jetty configuration files.
183

184
```java { .api }
185
public abstract class Descriptor {
186
    public void parse(XmlParser parser) throws Exception;
187
    public boolean isParsed();
188
    public Resource getResource();
189
    public XmlParser.Node getRoot();
190
}
191

192
public class WebDescriptor extends Descriptor {
193
    public int getMajorVersion();
194
    public int getMinorVersion();
195
    public MetaData.Complete getMetaDataComplete();
196
    public boolean isDistributable();
197
}
198

199
public class FragmentDescriptor extends WebDescriptor {
200
    public String getName();
201
    public List<String> getBefores();
202
    public List<String> getAfters();
203
    public OtherType getOtherType();
204
}
205
```
206

207
[Descriptor Classes](./descriptors.md)
208

209
### Class Visibility Controls
210

211
Pattern-based system for controlling class visibility between webapp, server, and system classloaders with support for inclusion/exclusion patterns.
212

213
```java { .api }
214
public class ClassMatcher extends AbstractSet<String> {
215
    public ClassMatcher();
216
    public ClassMatcher(String... patterns);
217
    
218
    public boolean include(String name);
219
    public boolean exclude(String name);
220
    public boolean match(String name);
221
    public boolean match(Class<?> clazz);
222
    public boolean match(String name, URL url);
223
    
224
    public String[] getInclusions();
225
    public String[] getExclusions();
226
}
227
```
228

229
[Class Visibility](./class-visibility.md)
230

231
## Types
232

233
### Core Context Types
234

235
```java { .api }
236
public interface WebAppClassLoader.Context extends ClassVisibilityChecker {
237
    Resource newResource(String urlOrPath) throws IOException;
238
    PermissionCollection getPermissions();
239
    boolean isParentLoaderPriority();
240
    List<Resource> getExtraClasspath();
241
    boolean isServerResource(String name, URL parentUrl);
242
    boolean isSystemResource(String name, URL webappUrl);
243
}
244
```
245

246
### Configuration Types
247

248
```java { .api }
249
public abstract class AbstractConfiguration implements Configuration {
250
    protected AbstractConfiguration();
251
    protected AbstractConfiguration(boolean enabledByDefault);
252
    
253
    protected void addDependencies(String... classes);
254
    protected void protect(String... classes);
255
    protected void hide(String... classes);
256
    protected void expose(String... classes);
257
}
258

259
public interface Configuration.WrapperFunction {
260
    Configuration wrapConfiguration(Configuration configuration);
261
}
262
```
263

264
### Metadata Types
265

266
```java { .api }
267
public enum Origin {
268
    NotSet, WebXml, WebDefaults, WebOverride, WebFragment, Annotation, API;
269
    
270
    public static Origin of(Object o);
271
}
272

273
public static class MetaData.OriginInfo {
274
    public OriginInfo(String n, Annotation a, Class<?> ac);
275
    public OriginInfo(String n, Descriptor d);
276
    public OriginInfo(String n);
277
    
278
    public String getName();
279
    public Origin getOriginType();
280
    public Descriptor getDescriptor();
281
}
282

283
public enum MetaData.Complete {
284
    NotSet, True, False
285
}
286
```
287

288
### Descriptor Types
289

290
```java { .api }
291
public abstract class Descriptor {
292
    protected Descriptor(Resource xml);
293
    
294
    public void parse(XmlParser parser) throws Exception;
295
    public boolean isParsed();
296
    public Resource getResource();
297
    public XmlParser.Node getRoot();
298
}
299

300
public interface DescriptorProcessor {
301
    void process(WebAppContext context, Descriptor descriptor) throws Exception;
302
}
303
```
304

305
### Utility Types
306

307
```java { .api }
308
public interface Ordering {
309
    List<Resource> order(List<Resource> fragments);
310
}
311

312
public abstract class DiscoveredAnnotation {
313
    public DiscoveredAnnotation(WebAppContext context, String className);
314
    public DiscoveredAnnotation(WebAppContext context, String className, Resource resource);
315
    
316
    public abstract void apply();
317
    public String getClassName();
318
    public Class<?> getTargetClass();
319
}
320
```