0
# Metadata and Descriptor Processing
1

2
Jetty WebApp provides comprehensive metadata management for tracking all aspects of webapp configuration, including descriptor processing, annotation discovery, and origin tracking for configuration elements.
3

4
## Capabilities
5

6
### MetaData Container
7

8
Central container for all webapp configuration and deployment metadata.
9

10
```java { .api }
11
/**
12
 * Container for all webapp configuration and deployment metadata.
13
 * Tracks descriptors, annotations, fragments, and configuration origins.
14
 */
15
public class MetaData {
16
    
17
    /**
18
     * System property for XML validation control
19
     */
20
    public static final String VALIDATE_XML = "org.eclipse.jetty.webapp.validateXml";
21
    
22
    /**
23
     * Context attribute for ordered libraries
24
     */
25
    public static final String ORDERED_LIBS = "jakarta.servlet.context.orderedLibs";
26
    
27
    /**
28
     * Placeholder resource for non-fragment resources
29
     */
30
    public static final Resource NON_FRAG_RESOURCE = EmptyResource.INSTANCE;
31
    
32
    /**
33
     * Create empty metadata container
34
     */
35
    public MetaData();
36
    
37
    /**
38
     * Clear all metadata
39
     */
40
    public void clear();
41
}
42
```
43

44
### Descriptor Management
45

46
Methods for managing XML descriptors that configure the webapp.
47

48
```java { .api }
49
/**
50
 * Set the defaults descriptor (web-defaults.xml)
51
 */
52
public void setDefaultsDescriptor(DefaultsDescriptor descriptor);
53

54
/**
55
 * Set the main web descriptor (web.xml)
56
 */
57
public void setWebDescriptor(WebDescriptor descriptor);
58

59
/**
60
 * Add an override descriptor
61
 */
62
public void addOverrideDescriptor(OverrideDescriptor descriptor);
63

64
/**
65
 * Add a fragment descriptor from a JAR
66
 */
67
public void addFragmentDescriptor(Resource jarResource, FragmentDescriptor descriptor);
68

69
/**
70
 * Get descriptors
71
 */
72
public WebDescriptor getWebDescriptor();
73
public List<WebDescriptor> getOverrideDescriptors();
74
public WebDescriptor getDefaultsDescriptor();
75
```
76

77
**Usage Examples:**
78

79
```java
80
MetaData metaData = new MetaData();
81

82
// Set main descriptors
83
DefaultsDescriptor defaults = new DefaultsDescriptor(defaultsResource);
84
metaData.setDefaultsDescriptor(defaults);
85

86
WebDescriptor webDesc = new WebDescriptor(webXmlResource);
87
metaData.setWebDescriptor(webDesc);
88

89
// Add fragments from JARs
90
FragmentDescriptor fragment = new FragmentDescriptor(fragmentResource);
91
metaData.addFragmentDescriptor(jarResource, fragment);
92
```
93

94
### Annotation Processing
95

96
Methods for managing discovered annotations from classpath scanning.
97

98
```java { .api }
99
/**
100
 * Add discovered annotations from scanning
101
 */
102
public void addDiscoveredAnnotations(List<DiscoveredAnnotation> annotations);
103

104
/**
105
 * Add a single discovered annotation
106
 */
107
public void addDiscoveredAnnotation(DiscoveredAnnotation annotation);
108
```
109

110
**Usage Examples:**
111

112
```java
113
// Add annotations discovered during classpath scanning
114
List<DiscoveredAnnotation> annotations = scanner.scan();
115
metaData.addDiscoveredAnnotations(annotations);
116

117
// Add individual annotation
118
WebServletAnnotation servlet = new WebServletAnnotation(context, "com.example.MyServlet");
119
metaData.addDiscoveredAnnotation(servlet);
120
```
121

122
### Descriptor Processing
123

124
Methods for managing descriptor processors that handle XML parsing.
125

126
```java { .api }
127
/**
128
 * Add a descriptor processor
129
 */
130
public void addDescriptorProcessor(DescriptorProcessor p);
131

132
/**
133
 * Remove a descriptor processor
134
 */
135
public void removeDescriptorProcessor(DescriptorProcessor p);
136

137
/**
138
 * Get all descriptor processors
139
 */
140
public List<DescriptorProcessor> getDescriptorProcessors();
141
```
142

143
**Usage Examples:**
144

145
```java
146
// Add custom descriptor processor
147
DescriptorProcessor customProcessor = new CustomDescriptorProcessor();
148
metaData.addDescriptorProcessor(customProcessor);
149

150
// Remove processor
151
metaData.removeDescriptorProcessor(customProcessor);
152

153
// Get all processors
154
List<DescriptorProcessor> processors = metaData.getDescriptorProcessors();
155
```
156

157
### Fragment Ordering and Resolution
158

159
Methods for handling fragment ordering and metadata resolution.
160

161
```java { .api }
162
/**
163
 * Order fragment descriptors according to web.xml ordering rules
164
 */
165
public void orderFragments();
166

167
/**
168
 * Resolve all metadata and apply to webapp context
169
 */
170
public void resolve(WebAppContext context) throws Exception;
171

172
/**
173
 * Check if fragments are ordered
174
 */
175
public boolean isOrdered();
176

177
/**
178
 * Get/set ordering configuration
179
 */
180
public Ordering getOrdering();
181
public void setOrdering(Ordering o);
182
```
183

184
**Usage Examples:**
185

186
```java
187
// Order fragments and resolve metadata
188
metaData.orderFragments();
189
metaData.resolve(webAppContext);
190

191
// Check ordering
192
if (!metaData.isOrdered()) {
193
    // Handle unordered fragments
194
}
195
```
196

197
### Fragment Access
198

199
Methods for accessing fragment descriptors and their associated JARs.
200

201
```java { .api }
202
/**
203
 * Get fragment descriptor by name
204
 */
205
public FragmentDescriptor getFragmentDescriptor(String name);
206

207
/**
208
 * Get fragment descriptor by resource
209
 */
210
public FragmentDescriptor getFragmentDescriptor(Resource descriptorResource);
211

212
/**
213
 * Get JAR resource for fragment name
214
 */
215
public Resource getJarForFragmentName(String name);
216

217
/**
218
 * Get fragment descriptor for JAR resource
219
 */
220
public FragmentDescriptor getFragmentDescriptorForJar(Resource jar);
221

222
/**
223
 * Get all named fragment descriptors
224
 */
225
public Map<String, FragmentDescriptor> getNamedFragmentDescriptors();
226
```
227

228
### Origin Tracking
229

230
Methods for tracking where configuration elements were declared.
231

232
```java { .api }
233
/**
234
 * Get origin type for a configuration element
235
 */
236
public Origin getOrigin(String name);
237

238
/**
239
 * Get detailed origin information
240
 */
241
public OriginInfo getOriginInfo(String name);
242

243
/**
244
 * Get the descriptor where element was declared
245
 */
246
public Descriptor getOriginDescriptor(String name);
247

248
/**
249
 * Set origin from descriptor
250
 */
251
public void setOrigin(String name, Descriptor d);
252

253
/**
254
 * Set origin from annotation
255
 */
256
public void setOrigin(String name, Annotation annotation, Class<?> annotated);
257

258
/**
259
 * Set origin as programmatic API
260
 */
261
public void setOriginAPI(String name);
262

263
/**
264
 * Get all origin information
265
 */
266
public Map<String, OriginInfo> getOrigins();
267
```
268

269
**Usage Examples:**
270

271
```java
272
// Track configuration element origins
273
metaData.setOrigin("myServlet", webXmlDescriptor);
274
metaData.setOrigin("myFilter", webServletAnnotation, MyFilter.class);
275
metaData.setOriginAPI("dynamicServlet");
276

277
// Query origins
278
Origin origin = metaData.getOrigin("myServlet");
279
if (origin == Origin.WebXml) {
280
    // Element came from web.xml
281
}
282
```
283

284
### Configuration Properties
285

286
Methods for checking various configuration properties.
287

288
```java { .api }
289
/**
290
 * Check if webapp is distributable
291
 */
292
public boolean isDistributable();
293

294
/**
295
 * Check if metadata is complete (no annotation scanning needed)
296
 */
297
public boolean isMetaDataComplete();
298

299
/**
300
 * Check if duplicate fragment names are allowed
301
 */
302
public boolean isAllowDuplicateFragmentNames();
303
public void setAllowDuplicateFragmentNames(boolean allowDuplicateFragmentNames);
304

305
/**
306
 * Check if XML validation is enabled
307
 */
308
public boolean isValidateXml();
309
public void setValidateXml(boolean validateXml);
310
```
311

312
### Resource Management
313

314
Methods for managing webapp resources and classpaths.
315

316
```java { .api }
317
/**
318
 * Add WEB-INF resource
319
 */
320
public void addWebInfResource(Resource newResource);
321

322
/**
323
 * Get WEB-INF resources
324
 */
325
public List<Resource> getWebInfResources(boolean withOrdering);
326

327
/**
328
 * Add container resource (from server classpath)
329
 */
330
public void addContainerResource(Resource jar);
331

332
/**
333
 * Get container resources
334
 */
335
public List<Resource> getContainerResources();
336

337
/**
338
 * Set WEB-INF/classes resources
339
 */
340
public void setWebInfClassesResources(List<Resource> dirs);
341

342
/**
343
 * Get WEB-INF/classes resources
344
 */
345
public List<Resource> getWebInfClassesResources();
346
```
347

348
## Origin Tracking Types
349

350
### Origin Enum
351

352
Enumeration representing the source of configuration elements.
353

354
```java { .api }
355
/**
356
 * Enum representing the source of webapp configuration elements
357
 */
358
public enum Origin {
359
    NotSet,      // Origin not determined
360
    WebXml,      // From web.xml
361
    WebDefaults, // From web-defaults.xml
362
    WebOverride, // From override descriptor
363
    WebFragment, // From web-fragment.xml
364
    Annotation,  // From annotation
365
    API;         // From programmatic API
366
    
367
    /**
368
     * Determine origin from object
369
     */
370
    public static Origin of(Object o);
371
}
372
```
373

374
### OriginInfo Class
375

376
Detailed information about configuration element origins.
377

378
```java { .api }
379
/**
380
 * Metadata about where deployable elements were declared
381
 */
382
public static class OriginInfo {
383
    
384
    /**
385
     * Create origin info for annotation
386
     */
387
    public OriginInfo(String n, Annotation a, Class<?> ac);
388
    
389
    /**
390
     * Create origin info for descriptor
391
     */
392
    public OriginInfo(String n, Descriptor d);
393
    
394
    /**
395
     * Create origin info for API
396
     */
397
    public OriginInfo(String n);
398
    
399
    /**
400
     * Get origin name/identifier
401
     */
402
    public String getName();
403
    
404
    /**
405
     * Get origin type
406
     */
407
    public Origin getOriginType();
408
    
409
    /**
410
     * Get descriptor (if origin is descriptor-based)
411
     */
412
    public Descriptor getDescriptor();
413
}
414
```
415

416
### Complete Enum
417

418
Enumeration for metadata completeness status.
419

420
```java { .api }
421
/**
422
 * Metadata completeness status
423
 */
424
public enum Complete {
425
    NotSet,  // Completeness not determined
426
    True,    // Metadata is complete
427
    False    // Metadata is incomplete
428
}
429
```
430

431
## Descriptor Base Classes
432

433
### Descriptor Abstract Class
434

435
Base class for all XML descriptor types.
436

437
```java { .api }
438
/**
439
 * Base class for XML descriptor parsing and representation
440
 */
441
public abstract class Descriptor {
442
    
443
    /**
444
     * Create descriptor with XML resource
445
     */
446
    protected Descriptor(Resource xml);
447
    
448
    /**
449
     * Parse descriptor with XML parser
450
     */
451
    public void parse(XmlParser parser) throws Exception;
452
    
453
    /**
454
     * Check if descriptor has been parsed
455
     */
456
    public boolean isParsed();
457
    
458
    /**
459
     * Get descriptor resource
460
     */
461
    public Resource getResource();
462
    
463
    /**
464
     * Get root XML node
465
     */
466
    public XmlParser.Node getRoot();
467
}
468
```
469

470
### Descriptor Implementations
471

472
Specific descriptor types for different XML files.
473

474
```java { .api }
475
/**
476
 * Web.xml descriptor
477
 */
478
public class WebDescriptor extends Descriptor {
479
    public WebDescriptor(Resource xml);
480
}
481

482
/**
483
 * Web-defaults.xml descriptor
484
 */
485
public class DefaultsDescriptor extends Descriptor {
486
    public DefaultsDescriptor(Resource xml);
487
}
488

489
/**
490
 * Override descriptor
491
 */
492
public class OverrideDescriptor extends Descriptor {
493
    public OverrideDescriptor(Resource xml);
494
}
495

496
/**
497
 * Web-fragment.xml descriptor  
498
 */
499
public class FragmentDescriptor extends Descriptor {
500
    public FragmentDescriptor(Resource xml);
501
    
502
    // Fragment-specific methods
503
    public String getName();
504
    public List<String> getEnums();
505
    // Additional fragment handling methods...
506
}
507
```
508

509
## Descriptor Processing
510

511
### DescriptorProcessor Interface
512

513
Interface for processing XML descriptors.
514

515
```java { .api }
516
/**
517
 * Interface for processing XML descriptors
518
 */
519
public interface DescriptorProcessor {
520
    
521
    /**
522
     * Process descriptor and apply to webapp context
523
     */
524
    void process(WebAppContext context, Descriptor descriptor) throws Exception;
525
}
526
```
527

528
### Processor Implementations
529

530
Built-in descriptor processors.
531

532
```java { .api }
533
/**
534
 * Standard XML descriptor processor
535
 */
536
public class StandardDescriptorProcessor implements DescriptorProcessor {
537
    
538
    public void process(WebAppContext context, Descriptor descriptor) throws Exception;
539
}
540

541
/**
542
 * Iterative descriptor processor for complex processing
543
 */
544
public class IterativeDescriptorProcessor implements DescriptorProcessor {
545
    
546
    public void process(WebAppContext context, Descriptor descriptor) throws Exception;
547
}
548
```
549

550
## Usage Patterns
551

552
### Basic Metadata Setup
553

554
```java
555
// Create and populate metadata
556
MetaData metaData = new MetaData();
557

558
// Set descriptors
559
metaData.setWebDescriptor(new WebDescriptor(webXmlResource));
560
metaData.setDefaultsDescriptor(new DefaultsDescriptor(defaultsResource));
561

562
// Add fragments
563
metaData.addFragmentDescriptor(jarResource, fragmentDescriptor);
564

565
// Order and resolve
566
metaData.orderFragments();
567
metaData.resolve(webAppContext);
568
```
569

570
### Origin Tracking Example
571

572
```java
573
// Track where servlet was configured
574
metaData.setOrigin("myServlet", webXmlDescriptor);
575

576
// Later, check origin
577
Origin origin = metaData.getOrigin("myServlet");
578
switch (origin) {
579
    case WebXml:
580
        // Handle web.xml configuration
581
        break;
582
    case Annotation:
583
        // Handle annotation configuration
584
        break;
585
    case API:
586
        // Handle programmatic configuration
587
        break;
588
}
589
```
590

591
### Fragment Processing
592

593
```java
594
// Process all fragments in WEB-INF/lib
595
for (Resource jar : webInfLibJars) {
596
    Resource fragmentXml = jar.addPath("META-INF/web-fragment.xml");
597
    if (fragmentXml.exists()) {
598
        FragmentDescriptor fragment = new FragmentDescriptor(fragmentXml);
599
        metaData.addFragmentDescriptor(jar, fragment);
600
    }
601
}
602

603
// Order according to web.xml absolute-ordering or fragment before/after
604
metaData.orderFragments();
605

606
// Process ordered fragments
607
for (FragmentDescriptor fragment : metaData.getOrderedFragments()) {
608
    processFragment(fragment);
609
}
610
```