0
# Configuration System
1

2
The Jetty EE10 WebApp configuration system provides a pluggable architecture for handling different aspects of web application setup and servlet specification compliance. Each Configuration implementation handles specific features like web.xml processing, annotation scanning, or security setup.
3

4
## Core Configuration Interface
5

6
```java { .api }
7
public interface Configuration {
8
    
9
    // Optional configuration properties
10
    default boolean isAvailable();
11
    default Class<? extends Configuration> replaces();
12
    default Collection<String> getDependencies();
13
    default Collection<String> getDependents();
14
    default ClassMatcher getProtectedClasses();
15
    default ClassMatcher getHiddenClasses();
16
    
17
    // Required lifecycle methods
18
    void preConfigure(WebAppContext context) throws Exception;
19
    void configure(WebAppContext context) throws Exception;
20
    void postConfigure(WebAppContext context) throws Exception;
21
    void deconfigure(WebAppContext context) throws Exception;
22
    void destroy(WebAppContext context) throws Exception;
23
    
24
    // Configuration behavior
25
    boolean isEnabledByDefault();
26
    boolean abort(WebAppContext context);
27
}
28
```
29

30
## AbstractConfiguration Base Class
31

32
Base implementation providing common functionality and builder pattern support.
33

34
```java { .api }
35
public abstract class AbstractConfiguration implements Configuration {
36
    
37
    // Constructor
38
    protected AbstractConfiguration(Builder builder);
39
    
40
    // Dependency management
41
    public Collection<String> getDependents();
42
    public Collection<String> getDependencies();
43
    public ClassMatcher getProtectedClasses();
44
    public ClassMatcher getHiddenClasses();
45
    
46
    // Lifecycle implementation
47
    public void preConfigure(WebAppContext context) throws Exception;
48
    public void configure(WebAppContext context) throws Exception;
49
    public void postConfigure(WebAppContext context) throws Exception;
50
    public void deconfigure(WebAppContext context) throws Exception;
51
    public void destroy(WebAppContext context) throws Exception;
52
    
53
    // Configuration properties
54
    public boolean isEnabledByDefault();
55
    public boolean abort(WebAppContext context);
56
}
57
```
58

59
## Configuration Builder
60

61
Fluent builder for creating AbstractConfiguration instances.
62

63
```java { .api }
64
public static class AbstractConfiguration.Builder {
65
    
66
    // Configuration properties
67
    public Builder enabledByDefault(boolean enabledByDefault);
68
    
69
    // Dependency management
70
    public Builder addDependencies(String... classes);
71
    public Builder addDependencies(Class<? extends Configuration>... classes);
72
    public Builder addDependents(String... classes);
73
    public Builder addDependents(Class<?>... classes);
74
    
75
    // Class visibility controls
76
    public Builder protect(String... classes);
77
    public Builder hide(String... classes);
78
    public Builder expose(String... classes);
79
    public Builder protectAndExpose(String... classes);
80
}
81
```
82

83
## Configurations Container
84

85
Manages an ordered list of Configuration instances with dependency resolution.
86

87
```java { .api }
88
public class Configurations extends AbstractList<Configuration> 
89
    implements Dumpable {
90
    
91
    // Constructors
92
    public Configurations();
93
    public Configurations(List<Configuration> configurations);
94
    public Configurations(Configuration... configurations);
95
    public Configurations(String... configurationClassNames);
96
    
97
    // Static configuration management
98
    public static List<Configuration> getKnown();
99
    public static void setKnown(String... classes);
100
    public static Configurations setServerDefault(Server server);
101
    public static Configurations getServerDefault(Server server);
102
    
103
    // Configuration manipulation
104
    public boolean add(Configuration configuration);
105
    public void add(Configuration... configurations);
106
    public void add(String... configClass);
107
    public void clear();
108
    public void set(Configuration... configurations);
109
    public void set(String... configClass);
110
    public void remove(Configuration... configurations);
111
    public void remove(Class<? extends Configuration>... configClass);
112
    public void remove(String... configClass);
113
    
114
    // Configuration lookup
115
    public <T> T get(Class<? extends T> configClass);
116
    public <T> List<T> getConfigurations(Class<? extends T> configClass);
117
    
118
    // Dependency resolution
119
    public void sort();
120
    public static void sort(List<Configuration> configurations);
121
    
122
    // Lifecycle execution
123
    public void preConfigure(WebAppContext webapp) throws Exception;
124
    public boolean configure(WebAppContext webapp) throws Exception;
125
    public void postConfigure(WebAppContext webapp) throws Exception;
126
}
127
```
128

129
## Built-in Configuration Implementations
130

131
### WebXmlConfiguration
132

133
Processes web.xml and web-defaults.xml descriptors.
134

135
```java { .api }
136
public class WebXmlConfiguration extends AbstractConfiguration {
137
    // Configures WebApp by parsing default web.xml and web.xml descriptors
138
}
139
```
140

141
### WebInfConfiguration
142

143
Handles WEB-INF directory processing including extraction and temporary directory setup.
144

145
```java { .api }
146
public class WebInfConfiguration extends AbstractConfiguration {
147
    
148
    // Temporary directory and extraction
149
    public void resolveTempDirectory(WebAppContext context) throws Exception;
150
    public void unpack(WebAppContext context) throws IOException;
151
}
152
```
153

154
### MetaInfConfiguration
155

156
Scans META-INF of JARs to find TLDs, web-fragment.xml, and resources.
157

158
```java { .api }
159
public class MetaInfConfiguration extends AbstractConfiguration {
160
    
161
    // JAR scanning methods
162
    public void findAndFilterContainerPaths(WebAppContext context) 
163
        throws Exception;
164
    public void findAndFilterWebAppPaths(WebAppContext context) 
165
        throws Exception;
166
    public void scanJars(WebAppContext context, Collection<Resource> jars, 
167
        boolean useCaches) throws Exception;
168
    public void scanJars(WebAppContext context, Collection<Resource> jars, 
169
        boolean useCaches, List<String> scanTypes) throws Exception;
170
    
171
    // Specific scanning operations
172
    public void scanForResources(WebAppContext context, Resource dir, 
173
        ConcurrentHashMap<Resource, Resource> cache);
174
    public void scanForFragment(WebAppContext context, Resource dir, 
175
        ConcurrentHashMap<Resource, Resource> cache);
176
    public void scanForTlds(WebAppContext context, Resource dir, 
177
        ConcurrentHashMap<Resource, Collection<URL>> cache) throws Exception;
178
}
179
```
180

181
### JettyWebXmlConfiguration
182

183
Processes jetty-web.xml and jetty-ee10-web.xml configuration files.
184

185
```java { .api }
186
public class JettyWebXmlConfiguration extends AbstractConfiguration {
187
    // Processes Jetty-specific configuration files
188
}
189
```
190

191
### FragmentConfiguration
192

193
Processes web-fragments in JARs.
194

195
```java { .api }
196
public class FragmentConfiguration extends AbstractConfiguration {
197
    // Handles web-fragment.xml processing from JAR files
198
}
199
```
200

201
### WebAppConfiguration
202

203
Configures WebAppContext server/system classes to see default servlets.
204

205
```java { .api }
206
public class WebAppConfiguration extends AbstractConfiguration {
207
    // Configures class visibility for default Jetty servlets
208
}
209
```
210

211
### ServletsConfiguration
212

213
Configures WebAppContext to expose Jetty utility servlets if available.
214

215
```java { .api }
216
public class ServletsConfiguration extends AbstractConfiguration {
217
    // Exposes utility servlets like DefaultServlet
218
}
219
```
220

221
### JndiConfiguration
222

223
Configures WebAppContext to access JNDI packages.
224

225
```java { .api }
226
public class JndiConfiguration extends AbstractConfiguration {
227
    // Enables JNDI support for web applications
228
}
229
```
230

231
### Additional Configurations
232

233
```java { .api }
234
public class JaasConfiguration extends AbstractConfiguration {
235
    // JAAS authentication support
236
}
237

238
public class JaspiConfiguration extends AbstractConfiguration {
239
    // JASPI authentication support  
240
}
241

242
public class JmxConfiguration extends AbstractConfiguration {
243
    // JMX monitoring support
244
}
245

246
public class JspConfiguration extends AbstractConfiguration {
247
    // JSP compilation and runtime support
248
}
249
```
250

251
## Configuration Constants
252

253
### MetaInfConfiguration Constants
254

255
```java { .api }
256
public static final String USE_CONTAINER_METAINF_CACHE = 
257
    "org.eclipse.jetty.metainf.useCache";
258
public static final String CACHED_CONTAINER_TLDS = 
259
    "org.eclipse.jetty.ee10.webapp.containerTlds";
260
public static final String CACHED_CONTAINER_FRAGMENTS = 
261
    "org.eclipse.jetty.ee10.webapp.containerFragments";
262
public static final String CACHED_CONTAINER_RESOURCES = 
263
    "org.eclipse.jetty.ee10.webapp.containerResources";
264
public static final String METAINF_TLDS = 
265
    "org.eclipse.jetty.ee10.webapp.MetaInfTlds";
266
public static final String METAINF_FRAGMENTS = 
267
    "org.eclipse.jetty.ee10.webapp.MetaInfFragments";
268
public static final String METAINF_RESOURCES = 
269
    "org.eclipse.jetty.ee10.webapp.MetaInfResources";
270
public static final String CONTAINER_JAR_PATTERN = 
271
    "org.eclipse.jetty.server.webapp.ContainerIncludeJarPattern";
272
public static final String WEBINF_JAR_PATTERN = 
273
    "org.eclipse.jetty.server.webapp.WebInfIncludeJarPattern";
274
public static final String RESOURCE_DIRS = 
275
    "org.eclipse.jetty.ee10.webapp.resourceDirs";
276
```
277

278
### JettyWebXmlConfiguration Constants
279

280
```java { .api }
281
public static final String PROPERTY_WEB_INF_URI = 
282
    "org.eclipse.jetty.ee10.webapp.webInfUri";
283
public static final String PROPERTY_WEB_INF = 
284
    "org.eclipse.jetty.ee10.webapp.webInf";
285
public static final String XML_CONFIGURATION = 
286
    "org.eclipse.jetty.ee10.webapp.configuration";
287
public static final String JETTY_WEB_XML = "jetty-web.xml";
288
public static final String JETTY_EE10_WEB_XML = "jetty-ee10-web.xml";
289
```
290

291
### FragmentConfiguration Constants
292

293
```java { .api }
294
public static final String FRAGMENT_RESOURCES = 
295
    "org.eclipse.jetty.ee10.webapp.fragmentResources";
296
```
297

298
## Usage Examples
299

300
### Basic Configuration Setup
301

302
```java
303
import org.eclipse.jetty.ee10.webapp.*;
304

305
WebAppContext webapp = new WebAppContext();
306
webapp.setWar("/path/to/webapp.war");
307
webapp.setContextPath("/myapp");
308

309
// Use default configurations with automatic discovery
310
webapp.setConfigurationDiscovered(true);
311

312
// Or set specific configurations
313
Configurations configs = new Configurations();
314
configs.add(new WebXmlConfiguration());
315
configs.add(new MetaInfConfiguration());
316
configs.add(new FragmentConfiguration());
317
webapp.setConfigurations(configs);
318
```
319

320
### Custom Configuration Implementation
321

322
```java
323
import org.eclipse.jetty.ee10.webapp.AbstractConfiguration;
324

325
public class CustomConfiguration extends AbstractConfiguration {
326
    
327
    public CustomConfiguration() {
328
        super(new Builder()
329
            .enabledByDefault(true)
330
            .addDependencies(WebXmlConfiguration.class)
331
            .protect("com.mycompany.server.")
332
            .hide("com.mycompany.internal.")
333
        );
334
    }
335
    
336
    @Override
337
    public void preConfigure(WebAppContext context) throws Exception {
338
        // Pre-configuration logic
339
        System.out.println("Pre-configuring custom features");
340
    }
341
    
342
    @Override
343
    public void configure(WebAppContext context) throws Exception {
344
        // Main configuration logic
345
        context.setAttribute("custom.configured", true);
346
    }
347
    
348
    @Override
349
    public void postConfigure(WebAppContext context) throws Exception {
350
        // Post-configuration logic
351
        System.out.println("Custom configuration completed");
352
    }
353
}
354

355
// Use custom configuration
356
WebAppContext webapp = new WebAppContext();
357
Configurations configs = new Configurations();
358
configs.add(new WebXmlConfiguration());
359
configs.add(new CustomConfiguration());
360
webapp.setConfigurations(configs);
361
```
362

363
### Configuration Dependency Management
364

365
```java
366
import org.eclipse.jetty.ee10.webapp.*;
367

368
// Create configurations with explicit dependencies
369
Configurations configs = new Configurations();
370

371
// WebXmlConfiguration has no dependencies
372
configs.add(new WebXmlConfiguration());
373

374
// MetaInfConfiguration depends on WebXmlConfiguration
375
configs.add(new MetaInfConfiguration());
376

377
// FragmentConfiguration depends on both WebXml and MetaInf
378
configs.add(new FragmentConfiguration());
379

380
// JettyWebXmlConfiguration depends on all previous ones
381
configs.add(new JettyWebXmlConfiguration());
382

383
// Sort to resolve dependencies automatically
384
configs.sort();
385

386
WebAppContext webapp = new WebAppContext();
387
webapp.setConfigurations(configs);
388
```
389

390
### Server-Level Default Configurations
391

392
```java
393
import org.eclipse.jetty.server.Server;
394
import org.eclipse.jetty.ee10.webapp.Configurations;
395

396
Server server = new Server();
397

398
// Set server-wide default configurations
399
Configurations.setServerDefault(server);
400

401
// Or set custom server defaults
402
Configurations serverConfigs = new Configurations();
403
serverConfigs.add(new WebXmlConfiguration());
404
serverConfigs.add(new MetaInfConfiguration());
405
// ... add other configurations
406
Configurations.setServerDefault(server, serverConfigs);
407

408
// WebApps will inherit these configurations by default
409
WebAppContext webapp = new WebAppContext();
410
// Will use server default configurations
411
```
412

413
### Configuration Filtering and Customization
414

415
```java
416
import org.eclipse.jetty.ee10.webapp.*;
417

418
WebAppContext webapp = new WebAppContext();
419

420
// Start with all known configurations
421
Configurations configs = new Configurations(Configurations.getKnown());
422

423
// Remove specific configurations
424
configs.remove(JspConfiguration.class);
425
configs.remove(JmxConfiguration.class);
426

427
// Add custom configuration
428
configs.add(new CustomConfiguration());
429

430
// Get specific configuration type
431
MetaInfConfiguration metaInfConfig = configs.get(MetaInfConfiguration.class);
432
if (metaInfConfig != null) {
433
    // Configure MetaInf-specific settings
434
}
435

436
webapp.setConfigurations(configs);
437
```
438

439
### Manual Configuration Lifecycle
440

441
```java
442
import org.eclipse.jetty.ee10.webapp.*;
443

444
WebAppContext webapp = new WebAppContext();
445
webapp.setWar("/path/to/webapp.war");
446

447
Configurations configs = new Configurations();
448
configs.add(new WebXmlConfiguration());
449
configs.add(new MetaInfConfiguration());
450

451
try {
452
    // Execute configuration phases manually
453
    configs.preConfigure(webapp);
454
    
455
    boolean success = configs.configure(webapp);
456
    if (success) {
457
        configs.postConfigure(webapp);
458
        // Web application is configured and ready
459
    } else {
460
        System.err.println("Configuration was aborted");
461
    }
462
} catch (Exception e) {
463
    System.err.println("Configuration failed: " + e.getMessage());
464
}
465
```
466

467
### Configuration with Custom Class Visibility
468

469
```java
470
import org.eclipse.jetty.ee10.webapp.*;
471

472
public class SecurityConfiguration extends AbstractConfiguration {
473
    
474
    public SecurityConfiguration() {
475
        super(new Builder()
476
            .enabledByDefault(true)
477
            .protect("java.security.", "javax.crypto.")
478
            .hide("org.eclipse.jetty.security.internal.")
479
            .addDependencies(WebXmlConfiguration.class)
480
        );
481
    }
482
    
483
    @Override
484
    public void configure(WebAppContext context) throws Exception {
485
        // Apply security-specific configuration
486
        context.getSecurityHandler().setAuthenticator(new CustomAuthenticator());
487
    }
488
}
489
```
490

491
## Error Handling
492

493
Configuration operations can throw exceptions during the lifecycle phases:
494

495
- `Exception` - General configuration errors during any lifecycle method
496
- `IllegalStateException` - Invalid configuration state or circular dependencies
497
- `ClassNotFoundException` - Missing configuration class when using string-based configuration
498
- `IOException` - I/O errors when processing files or resources
499

500
Common error scenarios:
501
- Missing required configuration dependencies
502
- Circular dependency loops in configuration chain
503
- Invalid or missing configuration files (web.xml, jetty-web.xml)
504
- Insufficient permissions to access configuration resources
505
- Conflicting configuration settings between different implementations
506

507
## Service Provider Integration
508

509
Configurations are discovered using Java's ServiceLoader mechanism:
510

511
```java
512
// META-INF/services/org.eclipse.jetty.ee10.webapp.Configuration
513
org.eclipse.jetty.ee10.webapp.WebXmlConfiguration
514
org.eclipse.jetty.ee10.webapp.MetaInfConfiguration
515
org.eclipse.jetty.ee10.webapp.FragmentConfiguration
516
// ... other configurations
517

518
// Automatic discovery
519
ServiceLoader<Configuration> loader = ServiceLoader.load(Configuration.class);
520
for (Configuration config : loader) {
521
    // Use discovered configurations
522
}
523
```