0
# Descriptor Classes
1

2
Jetty WebApp provides comprehensive support for parsing and processing various XML descriptors that configure web applications. These descriptor classes handle web.xml, web-fragment.xml, and Jetty-specific configuration files.
3

4
## Capabilities
5

6
### Descriptor Base Class
7

8
Abstract base class for all XML descriptor implementations.
9

10
```java { .api }
11
/**
12
 * Base class for XML descriptor parsing and representation.
13
 * Provides common functionality for parsing XML configuration files.
14
 */
15
public abstract class Descriptor {
16
    
17
    /**
18
     * Create descriptor with XML resource
19
     */
20
    protected Descriptor(Resource xml);
21
    
22
    /**
23
     * Parse descriptor with XML parser
24
     */
25
    public void parse(XmlParser parser) throws Exception;
26
    
27
    /**
28
     * Check if descriptor has been parsed
29
     */
30
    public boolean isParsed();
31
    
32
    /**
33
     * Get descriptor resource
34
     */
35
    public Resource getResource();
36
    
37
    /**
38
     * Get root XML node after parsing
39
     */
40
    public XmlParser.Node getRoot();
41
    
42
    /**
43
     * Get the validated XML if validation was performed
44
     */
45
    public String getValidatedXML();
46
    
47
    /**
48
     * Process the descriptor with standard processing
49
     */
50
    public void processDocumentTree(XmlParser.Node root);
51
}
52
```
53

54
### WebDescriptor
55

56
Primary descriptor for web.xml files with servlet specification compliance.
57

58
```java { .api }
59
/**
60
 * Descriptor for web.xml files supporting servlet specification versions.
61
 * Handles metadata-complete, distributable, and ordering configurations.
62
 */
63
public class WebDescriptor extends Descriptor {
64
    
65
    /**
66
     * Create web descriptor with XML resource
67
     */
68
    public WebDescriptor(Resource xml);
69
    
70
    /**
71
     * Get servlet specification major version
72
     */
73
    public int getMajorVersion();
74
    
75
    /**
76
     * Get servlet specification minor version
77
     */
78
    public int getMinorVersion();
79
    
80
    /**
81
     * Check if metadata is complete (no annotation scanning needed)
82
     */
83
    public MetaData.Complete getMetaDataComplete();
84
    
85
    /**
86
     * Check if webapp is distributable
87
     */
88
    public boolean isDistributable();
89
    
90
    /**
91
     * Check if fragments are ordered
92
     */
93
    public boolean isOrdered();
94
    
95
    /**
96
     * Get fragment ordering configuration
97
     */
98
    public Ordering getOrdering();
99
}
100
```
101

102
**Static Utility Methods:**
103

104
```java { .api }
105
/**
106
 * Check if a web descriptor specifies metadata-complete
107
 */
108
public static boolean isMetaDataComplete(WebDescriptor descriptor);
109

110
/**
111
 * Create standard XML parser for web descriptors
112
 */
113
public static XmlParser getParser(boolean validating);
114

115
/**
116
 * Create new XML parser instance
117
 */
118
public static XmlParser newParser(boolean validating);
119
```
120

121
### FragmentDescriptor
122

123
Descriptor for web-fragment.xml files with fragment ordering support.
124

125
```java { .api }
126
/**
127
 * Descriptor for web-fragment.xml files with support for fragment
128
 * ordering via before/after relationships.
129
 */
130
public class FragmentDescriptor extends WebDescriptor {
131
    
132
    /**
133
     * Fragment ordering types
134
     */
135
    public enum OtherType { None, Before, After }
136
    
137
    /**
138
     * Create fragment descriptor with XML resource
139
     */
140
    public FragmentDescriptor(Resource xml);
141
    
142
    /**
143
     * Get the fragment name
144
     */
145
    public String getName();
146
    
147
    /**
148
     * Get list of fragment names this fragment should come before
149
     */
150
    public List<String> getBefores();
151
    
152
    /**
153
     * Get list of fragment names this fragment should come after
154
     */
155
    public List<String> getAfters();
156
    
157
    /**
158
     * Get the type of "others" ordering relationship
159
     */
160
    public OtherType getOtherType();
161
    
162
    /**
163
     * Get enumeration values if specified
164
     */
165
    public List<String> getEnums();
166
}
167
```
168

169
**Usage Examples:**
170

171
```java
172
// Create and parse fragment descriptor
173
Resource fragmentXml = Resource.newResource("META-INF/web-fragment.xml");
174
FragmentDescriptor fragment = new FragmentDescriptor(fragmentXml);
175
fragment.parse(WebDescriptor.newParser(true));
176

177
// Check fragment ordering
178
String name = fragment.getName();
179
List<String> before = fragment.getBefores();
180
List<String> after = fragment.getAfters();
181

182
if (fragment.getOtherType() == FragmentDescriptor.OtherType.Before) {
183
    // This fragment should come before all others not explicitly ordered
184
}
185
```
186

187
### DefaultsDescriptor
188

189
Descriptor for web-defaults.xml providing default servlet configurations.
190

191
```java { .api }
192
/**
193
 * Descriptor for web-defaults.xml files that provide default
194
 * servlet and filter configurations applied to all webapps.
195
 */
196
public class DefaultsDescriptor extends WebDescriptor {
197
    
198
    /**
199
     * Create defaults descriptor with XML resource
200
     */
201
    public DefaultsDescriptor(Resource xml);
202
}
203
```
204

205
### OverrideDescriptor
206

207
Descriptor for override configuration files that override webapp settings.
208

209
```java { .api }
210
/**
211
 * Descriptor for override configuration files that can override
212
 * settings from web.xml and web-fragment.xml files.
213
 */
214
public class OverrideDescriptor extends WebDescriptor {
215
    
216
    /**
217
     * Create override descriptor with XML resource
218
     */
219
    public OverrideDescriptor(Resource xml);
220
}
221
```
222

223
## Descriptor Processing Interface
224

225
### DescriptorProcessor
226

227
Interface for processing parsed descriptors and applying them to webapp contexts.
228

229
```java { .api }
230
/**
231
 * Interface for processing XML descriptors and applying their
232
 * configuration to webapp contexts.
233
 */
234
public interface DescriptorProcessor {
235
    
236
    /**
237
     * Process descriptor and apply configuration to webapp context
238
     */
239
    void process(WebAppContext context, Descriptor descriptor) throws Exception;
240
}
241
```
242

243
### Built-in Processor Implementations
244

245
Standard implementations for descriptor processing.
246

247
```java { .api }
248
/**
249
 * Standard processor for web.xml descriptors
250
 */
251
public class StandardDescriptorProcessor implements DescriptorProcessor {
252
    
253
    /**
254
     * Process standard web.xml descriptor
255
     */
256
    public void process(WebAppContext context, Descriptor descriptor) throws Exception;
257
}
258

259
/**
260
 * Iterative processor for complex descriptor processing
261
 */
262
public class IterativeDescriptorProcessor implements DescriptorProcessor {
263
    
264
    /**
265
     * Process descriptor with iterative approach
266
     */
267
    public void process(WebAppContext context, Descriptor descriptor) throws Exception;
268
}
269
```
270

271
### Fragment Ordering Interface
272

273
Interface for implementing fragment ordering strategies.
274

275
```java { .api }
276
/**
277
 * Interface for ordering web fragments according to servlet specification
278
 * or custom ordering strategies.
279
 */
280
public interface Ordering {
281
    
282
    /**
283
     * Order fragment resources according to ordering rules
284
     * 
285
     * @param fragments List of fragment resources to order
286
     * @return Ordered list of fragment resources
287
     */
288
    List<Resource> order(List<Resource> fragments);
289
}
290
```
291

292
## Usage Patterns
293

294
### Basic Descriptor Processing
295

296
```java
297
// Process web.xml
298
Resource webXml = webAppContext.getWebInf().addPath("web.xml");
299
if (webXml.exists()) {
300
    WebDescriptor webDescriptor = new WebDescriptor(webXml);
301
    webDescriptor.parse(WebDescriptor.newParser(true));
302
    
303
    // Check configuration
304
    if (webDescriptor.isDistributable()) {
305
        webAppContext.setDistributable(true);
306
    }
307
    
308
    // Add to metadata
309
    metaData.setWebDescriptor(webDescriptor);
310
}
311
```
312

313
### Fragment Discovery and Processing
314

315
```java
316
// Discover fragments in WEB-INF/lib
317
List<FragmentDescriptor> fragments = new ArrayList<>();
318
for (Resource jar : webInfLibJars) {
319
    Resource fragmentXml = jar.addPath("META-INF/web-fragment.xml");
320
    if (fragmentXml.exists()) {
321
        FragmentDescriptor fragment = new FragmentDescriptor(fragmentXml);
322
        fragment.parse(WebDescriptor.newParser(true));
323
        fragments.add(fragment);
324
        
325
        // Add to metadata with jar association
326
        metaData.addFragmentDescriptor(jar, fragment);
327
    }
328
}
329

330
// Process ordering
331
metaData.orderFragments();
332
```
333

334
### Custom Descriptor Processing
335

336
```java
337
// Implement custom descriptor processor
338
public class CustomDescriptorProcessor implements DescriptorProcessor {
339
    @Override
340
    public void process(WebAppContext context, Descriptor descriptor) throws Exception {
341
        if (descriptor instanceof WebDescriptor) {
342
            WebDescriptor webDesc = (WebDescriptor) descriptor;
343
            
344
            // Custom processing logic
345
            XmlParser.Node root = webDesc.getRoot();
346
            processCustomElements(context, root);
347
        }
348
    }
349
    
350
    private void processCustomElements(WebAppContext context, XmlParser.Node root) {
351
        // Process custom XML elements
352
        for (XmlParser.Node node : root.nodes("custom-config")) {
353
            String value = node.getString("value", "default");
354
            context.setAttribute("custom.config", value);
355
        }
356
    }
357
}
358

359
// Register custom processor
360
metaData.addDescriptorProcessor(new CustomDescriptorProcessor());
361
```
362

363
### Override Descriptor Usage
364

365
```java
366
// Apply override descriptor to modify webapp configuration
367
Resource overrideXml = Resource.newResource("conf/webapp-override.xml");
368
if (overrideXml.exists()) {
369
    OverrideDescriptor override = new OverrideDescriptor(overrideXml);
370
    override.parse(WebDescriptor.newParser(true));
371
    
372
    // Add to metadata - will be processed after main web.xml
373
    metaData.addOverrideDescriptor(override);
374
}
375
```