0
# Configuration Framework
1

2
Jetty WebApp uses a pluggable configuration system where different aspects of webapp deployment are handled by separate Configuration implementations. This system uses the ServiceLoader pattern with dependency resolution and lifecycle management.
3

4
## Capabilities
5

6
### Configuration Interface
7

8
The main interface that all configuration components implement.
9

10
```java { .api }
11
/**
12
 * Main interface for pluggable webapp configuration components.
13
 * Configurations are discovered via ServiceLoader and manage specific
14
 * aspects of webapp deployment and setup.
15
 */
16
public interface Configuration {
17
    
18
    /**
19
     * Attribute name for storing configuration list in webapp context
20
     */
21
    String ATTR = "org.eclipse.jetty.webapp.configuration";
22
    
23
    /**
24
     * Pre-configure the webapp (early setup phase)
25
     */
26
    void preConfigure(WebAppContext context) throws Exception;
27
    
28
    /**
29
     * Configure the webapp (main configuration phase)
30
     */
31
    void configure(WebAppContext context) throws Exception;
32
    
33
    /**
34
     * Post-configure the webapp (finalization phase)
35
     */
36
    void postConfigure(WebAppContext context) throws Exception;
37
    
38
    /**
39
     * De-configure the webapp (cleanup phase)
40
     */
41
    void deconfigure(WebAppContext context) throws Exception;
42
    
43
    /**
44
     * Destroy configuration resources
45
     */
46
    void destroy(WebAppContext context) throws Exception;
47
    
48
    /**
49
     * Check if this configuration is enabled by default
50
     */
51
    boolean isEnabledByDefault();
52
    
53
    /**
54
     * Check if configuration should abort further processing
55
     */
56
    boolean abort(WebAppContext context);
57
}
58
```
59

60
### Default Configuration Methods
61

62
Default implementations provided by the Configuration interface.
63

64
```java { .api }
65
/**
66
 * Check if configuration is available for use
67
 */
68
default boolean isAvailable() { return true; }
69

70
/**
71
 * Get the configuration class this one replaces
72
 */
73
default Class<? extends Configuration> replaces() { return null; }
74

75
/**
76
 * Get configuration class names this configuration depends on
77
 */
78
default Collection<String> getDependencies() { return Collections.emptyList(); }
79

80
/**
81
 * Get configuration class names that depend on this configuration
82
 */
83
default Collection<String> getDependents() { return Collections.emptyList(); }
84

85
/**
86
 * Get system classes matcher for this configuration
87
 */
88
default ClassMatcher getSystemClasses() { return null; }
89

90
/**
91
 * Get server classes matcher for this configuration
92
 */
93
default ClassMatcher getServerClasses() { return null; }
94
```
95

96
### AbstractConfiguration
97

98
Base implementation providing common configuration functionality.
99

100
```java { .api }
101
/**
102
 * Abstract base class providing common configuration functionality
103
 * including dependency management and class visibility controls.
104
 */
105
public abstract class AbstractConfiguration implements Configuration {
106
    
107
    /**
108
     * Create configuration enabled by default
109
     */
110
    protected AbstractConfiguration();
111
    
112
    /**
113
     * Create configuration with specific enabled state
114
     */
115
    protected AbstractConfiguration(boolean enabledByDefault);
116
    
117
    /**
118
     * Clone configuration from template to target webapp
119
     */
120
    public void cloneConfigure(WebAppContext template, WebAppContext context) throws Exception;
121
}
122
```
123

124
### Protected Configuration Methods
125

126
Methods available to Configuration implementations for common tasks.
127

128
```java { .api }
129
/**
130
 * Add dependency configuration class names
131
 */
132
protected void addDependencies(String... classes);
133

134
/**
135
 * Add dependency configuration classes
136
 */
137
protected void addDependencies(Class<? extends Configuration>... classes);
138

139
/**
140
 * Add dependent configuration class names
141
 */
142
protected void addDependents(String... classes);
143

144
/**
145
 * Add dependent configuration classes
146
 */
147
protected void addDependents(Class<?>... classes);
148

149
/**
150
 * Add system classes (loaded by system classloader)
151
 */
152
protected void protect(String... classes);
153

154
/**
155
 * Add server classes (hidden from webapp)
156
 */
157
protected void hide(String... classes);
158

159
/**
160
 * Expose server classes to webapp
161
 */
162
protected void expose(String... classes);
163

164
/**
165
 * Both protect and expose classes
166
 */
167
protected void protectAndExpose(String... classes);
168
```
169

170
### Configurations Manager
171

172
Container class that manages an ordered list of Configuration instances.
173

174
```java { .api }
175
/**
176
 * Ordered list of Configuration instances with dependency resolution
177
 * and lifecycle management.
178
 */
179
public class Configurations extends AbstractList<Configuration> implements Dumpable {
180
    
181
    /**
182
     * Create empty configurations list
183
     */
184
    public Configurations();
185
    
186
    /**
187
     * Create configurations from class names
188
     */
189
    public Configurations(String... classes);
190
    
191
    /**
192
     * Create configurations from class name list
193
     */
194
    public Configurations(List<String> classes);
195
    
196
    /**
197
     * Copy constructor
198
     */
199
    public Configurations(Configurations classlist);
200
}
201
```
202

203
### Static Configuration Management
204

205
Static methods for managing known configurations and server defaults.
206

207
```java { .api }
208
/**
209
 * Get all known configuration implementations
210
 */
211
public static List<Configuration> getKnown();
212

213
/**
214
 * Set known configuration class names
215
 */
216
public static void setKnown(String... classes);
217

218
/**
219
 * Set server default configurations
220
 */
221
public static Configurations setServerDefault(Server server);
222

223
/**
224
 * Get server default configurations
225
 */
226
public static Configurations getServerDefault(Server server);
227
```
228

229
### Configuration List Management
230

231
Methods for managing the configuration list.
232

233
```java { .api }
234
/**
235
 * Add configurations to the list
236
 */
237
public void add(Configuration... configurations);
238

239
/**
240
 * Add configuration classes by name
241
 */
242
public void add(String... configClass);
243

244
/**
245
 * Get configuration by type
246
 */
247
public <T> T get(Class<? extends T> configClass);
248

249
/**
250
 * Get all configurations of a specific type
251
 */
252
public <T> List<T> getConfigurations(Class<? extends T> configClass);
253

254
/**
255
 * Set configurations (replace all)
256
 */
257
public void set(Configuration... configurations);
258
public void set(String... configClass);
259

260
/**
261
 * Remove configurations
262
 */
263
public void remove(Configuration... configurations);
264
public void remove(Class<? extends Configuration>... configClass);
265
public void remove(String... configClass);
266

267
/**
268
 * Clear all configurations
269
 */
270
public void clear();
271

272
/**
273
 * Get configuration list
274
 */
275
public List<Configuration> getConfigurations();
276

277
/**
278
 * Convert to string array of class names
279
 */
280
public String[] toArray();
281

282
/**
283
 * Get size of configuration list
284
 */
285
public int size();
286
```
287

288
### Dependency Resolution and Lifecycle
289

290
Methods for dependency resolution and executing configuration lifecycle.
291

292
```java { .api }
293
/**
294
 * Sort configurations based on dependencies
295
 */
296
public void sort();
297

298
/**
299
 * Execute pre-configure phase for all configurations
300
 */
301
public void preConfigure(WebAppContext webapp) throws Exception;
302

303
/**
304
 * Execute configure phase for all configurations
305
 */
306
public boolean configure(WebAppContext webapp) throws Exception;
307

308
/**
309
 * Execute post-configure phase for all configurations
310
 */
311
public void postConfigure(WebAppContext webapp) throws Exception;
312
```
313

314
## Built-in Configuration Implementations
315

316
Jetty WebApp includes numerous built-in Configuration implementations that are discovered via ServiceLoader:
317

318
### Core Configurations
319

320
```java { .api }
321
/**
322
 * Basic webapp configuration - sets up basic webapp structure and context
323
 */
324
public class WebAppConfiguration extends AbstractConfiguration {
325
    public WebAppConfiguration();
326
}
327

328
/**
329
 * Processes web.xml descriptor and applies servlet configuration
330
 */
331
public class WebXmlConfiguration extends AbstractConfiguration {
332
    public WebXmlConfiguration();
333
}
334

335
/**
336
 * Processes WEB-INF directory and sets up classpath from JARs and classes
337
 */
338
public class WebInfConfiguration extends AbstractConfiguration {
339
    public WebInfConfiguration();
340
}
341

342
/**
343
 * Processes META-INF directory and discovers web fragments
344
 */
345
public class MetaInfConfiguration extends AbstractConfiguration {
346
    public MetaInfConfiguration();
347
}
348

349
/**
350
 * Processes web fragments and handles ordering according to servlet spec
351
 */
352
public class FragmentConfiguration extends AbstractConfiguration {
353
    public FragmentConfiguration();
354
}
355

356
/**
357
 * Processes jetty-web.xml descriptor for Jetty-specific configuration
358
 */
359
public class JettyWebXmlConfiguration extends AbstractConfiguration {
360
    public JettyWebXmlConfiguration();
361
}
362

363
/**
364
 * Configures servlets and filters from annotations and descriptors
365
 */
366
public class ServletsConfiguration extends AbstractConfiguration {
367
    public ServletsConfiguration();
368
}
369
```
370

371
### Integration Configurations
372

373
```java { .api }
374
/**
375
 * Configures JNDI context and resources
376
 */
377
public class JndiConfiguration extends AbstractConfiguration {
378
    public JndiConfiguration();
379
}
380

381
/**
382
 * Configures JAAS authentication and security realms
383
 */
384
public class JaasConfiguration extends AbstractConfiguration {
385
    public JaasConfiguration();
386
}
387

388
/**
389
 * Configures JASPI (Java Authentication Service Provider Interface) authentication
390
 */
391
public class JaspiConfiguration extends AbstractConfiguration {
392
    public JaspiConfiguration();
393
}
394

395
/**
396
 * Configures JMX management and monitoring capabilities
397
 */
398
public class JmxConfiguration extends AbstractConfiguration {
399
    public JmxConfiguration();
400
}
401

402
/**
403
 * Configures JSP compilation and runtime support
404
 */
405
public class JspConfiguration extends AbstractConfiguration {
406
    public JspConfiguration();
407
}
408
```
409

410
### Configuration Dependencies and Ordering
411

412
Each configuration declares dependencies that control execution order:
413

414
```java
415
// Example dependency relationships
416
WebInfConfiguration -> depends on nothing (runs first)
417
WebXmlConfiguration -> depends on WebInfConfiguration  
418
MetaInfConfiguration -> depends on WebInfConfiguration
419
FragmentConfiguration -> depends on WebXmlConfiguration, MetaInfConfiguration
420
ServletsConfiguration -> depends on FragmentConfiguration
421
JettyWebXmlConfiguration -> depends on FragmentConfiguration
422
```
423

424
## Configuration Wrapper System
425

426
System for wrapping and decorating configurations.
427

428
```java { .api }
429
/**
430
 * Functional interface for wrapping configurations
431
 */
432
public interface WrapperFunction {
433
    Configuration wrapConfiguration(Configuration configuration);
434
}
435

436
/**
437
 * Wrapper implementation for Configuration delegation
438
 */
439
public static class Wrapper implements Configuration {
440
    /**
441
     * Create wrapper with delegate configuration
442
     */
443
    public Wrapper(Configuration delegate);
444
    
445
    /**
446
     * Get the wrapped configuration
447
     */
448
    public Configuration getWrapped();
449
    
450
    // All Configuration methods are delegated to wrapped instance
451
}
452
```
453

454
## Usage Patterns
455

456
### Standard Configuration Setup
457

458
```java
459
// Use default configurations
460
WebAppContext webapp = new WebAppContext();
461
// Default configurations are automatically applied
462

463
// Or set specific configurations
464
webapp.setConfigurationClasses(new String[] {
465
    "org.eclipse.jetty.webapp.WebInfConfiguration",
466
    "org.eclipse.jetty.webapp.WebXmlConfiguration",
467
    "org.eclipse.jetty.webapp.MetaInfConfiguration",
468
    "org.eclipse.jetty.webapp.FragmentConfiguration"
469
});
470
```
471

472
### Adding Custom Configuration
473

474
```java
475
public class MyCustomConfiguration extends AbstractConfiguration {
476
    public MyCustomConfiguration() {
477
        super();
478
        // Add dependencies
479
        addDependencies(WebInfConfiguration.class, WebXmlConfiguration.class);
480
        // Hide internal classes
481
        hide("com.mycompany.internal.");
482
    }
483
    
484
    @Override
485
    public void configure(WebAppContext context) throws Exception {
486
        // Custom configuration logic
487
        ServletHolder servlet = new ServletHolder(new MyServlet());
488
        context.getServletHandler().addServlet(servlet);
489
    }
490
}
491

492
// Add to webapp
493
webapp.addConfiguration(new MyCustomConfiguration());
494
```
495

496
### Server-Wide Configuration Defaults
497

498
```java
499
// Set server-wide default configurations
500
Server server = new Server();
501
Configurations.setServerDefault(server);
502

503
// All webapps on this server will use these defaults
504
// Individual webapps can still override
505
```
506

507
### Configuration Ordering and Dependencies
508

509
```java
510
// Configurations are automatically sorted by dependencies
511
Configurations configs = new Configurations(
512
    "org.eclipse.jetty.webapp.WebXmlConfiguration",
513
    "org.eclipse.jetty.webapp.WebInfConfiguration", // Depends on WebXml
514
    "org.eclipse.jetty.webapp.MetaInfConfiguration"
515
);
516

517
// Sort resolves dependencies
518
configs.sort();
519

520
// Execute lifecycle phases
521
configs.preConfigure(webapp);
522
configs.configure(webapp);
523
configs.postConfigure(webapp);
524
```
525

526
### Wrapping Configurations
527

528
```java
529
// Wrap configuration to add behavior
530
Configuration.WrapperFunction wrapper = config -> {
531
    return new Configuration.Wrapper(config) {
532
        @Override
533
        public void configure(WebAppContext context) throws Exception {
534
            System.out.println("Before: " + getWrapped().getClass().getSimpleName());
535
            super.configure(context);
536
            System.out.println("After: " + getWrapped().getClass().getSimpleName());
537
        }
538
    };
539
};
540

541
// Apply wrapper to configurations
542
Configurations configs = webapp.getConfigurations();
543
for (int i = 0; i < configs.size(); i++) {
544
    configs.set(i, wrapper.wrapConfiguration(configs.get(i)));
545
}
546
```