Metadata and Descriptor Processing

/**
 * Container for all webapp configuration and deployment metadata.
 * Tracks descriptors, annotations, fragments, and configuration origins.
 */
public class MetaData {
    
    /**
     * System property for XML validation control
     */
    public static final String VALIDATE_XML = "org.eclipse.jetty.webapp.validateXml";
    
    /**
     * Context attribute for ordered libraries
     */
    public static final String ORDERED_LIBS = "jakarta.servlet.context.orderedLibs";
    
    /**
     * Placeholder resource for non-fragment resources
     */
    public static final Resource NON_FRAG_RESOURCE = EmptyResource.INSTANCE;
    
    /**
     * Create empty metadata container
     */
    public MetaData();
    
    /**
     * Clear all metadata
     */
    public void clear();
}

/**
 * Set the defaults descriptor (web-defaults.xml)
 */
public void setDefaultsDescriptor(DefaultsDescriptor descriptor);

/**
 * Set the main web descriptor (web.xml)
 */
public void setWebDescriptor(WebDescriptor descriptor);

/**
 * Add an override descriptor
 */
public void addOverrideDescriptor(OverrideDescriptor descriptor);

/**
 * Add a fragment descriptor from a JAR
 */
public void addFragmentDescriptor(Resource jarResource, FragmentDescriptor descriptor);

/**
 * Get descriptors
 */
public WebDescriptor getWebDescriptor();
public List<WebDescriptor> getOverrideDescriptors();
public WebDescriptor getDefaultsDescriptor();

MetaData metaData = new MetaData();

// Set main descriptors
DefaultsDescriptor defaults = new DefaultsDescriptor(defaultsResource);
metaData.setDefaultsDescriptor(defaults);

WebDescriptor webDesc = new WebDescriptor(webXmlResource);
metaData.setWebDescriptor(webDesc);

// Add fragments from JARs
FragmentDescriptor fragment = new FragmentDescriptor(fragmentResource);
metaData.addFragmentDescriptor(jarResource, fragment);

/**
 * Add discovered annotations from scanning
 */
public void addDiscoveredAnnotations(List<DiscoveredAnnotation> annotations);

/**
 * Add a single discovered annotation
 */
public void addDiscoveredAnnotation(DiscoveredAnnotation annotation);

// Add annotations discovered during classpath scanning
List<DiscoveredAnnotation> annotations = scanner.scan();
metaData.addDiscoveredAnnotations(annotations);

// Add individual annotation
WebServletAnnotation servlet = new WebServletAnnotation(context, "com.example.MyServlet");
metaData.addDiscoveredAnnotation(servlet);

/**
 * Add a descriptor processor
 */
public void addDescriptorProcessor(DescriptorProcessor p);

/**
 * Remove a descriptor processor
 */
public void removeDescriptorProcessor(DescriptorProcessor p);

/**
 * Get all descriptor processors
 */
public List<DescriptorProcessor> getDescriptorProcessors();

// Add custom descriptor processor
DescriptorProcessor customProcessor = new CustomDescriptorProcessor();
metaData.addDescriptorProcessor(customProcessor);

// Remove processor
metaData.removeDescriptorProcessor(customProcessor);

// Get all processors
List<DescriptorProcessor> processors = metaData.getDescriptorProcessors();

/**
 * Order fragment descriptors according to web.xml ordering rules
 */
public void orderFragments();

/**
 * Resolve all metadata and apply to webapp context
 */
public void resolve(WebAppContext context) throws Exception;

/**
 * Check if fragments are ordered
 */
public boolean isOrdered();

/**
 * Get/set ordering configuration
 */
public Ordering getOrdering();
public void setOrdering(Ordering o);

// Order fragments and resolve metadata
metaData.orderFragments();
metaData.resolve(webAppContext);

// Check ordering
if (!metaData.isOrdered()) {
    // Handle unordered fragments
}

/**
 * Get fragment descriptor by name
 */
public FragmentDescriptor getFragmentDescriptor(String name);

/**
 * Get fragment descriptor by resource
 */
public FragmentDescriptor getFragmentDescriptor(Resource descriptorResource);

/**
 * Get JAR resource for fragment name
 */
public Resource getJarForFragmentName(String name);

/**
 * Get fragment descriptor for JAR resource
 */
public FragmentDescriptor getFragmentDescriptorForJar(Resource jar);

/**
 * Get all named fragment descriptors
 */
public Map<String, FragmentDescriptor> getNamedFragmentDescriptors();

/**
 * Get origin type for a configuration element
 */
public Origin getOrigin(String name);

/**
 * Get detailed origin information
 */
public OriginInfo getOriginInfo(String name);

/**
 * Get the descriptor where element was declared
 */
public Descriptor getOriginDescriptor(String name);

/**
 * Set origin from descriptor
 */
public void setOrigin(String name, Descriptor d);

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

/**
 * Set origin as programmatic API
 */
public void setOriginAPI(String name);

/**
 * Get all origin information
 */
public Map<String, OriginInfo> getOrigins();

// Track configuration element origins
metaData.setOrigin("myServlet", webXmlDescriptor);
metaData.setOrigin("myFilter", webServletAnnotation, MyFilter.class);
metaData.setOriginAPI("dynamicServlet");

// Query origins
Origin origin = metaData.getOrigin("myServlet");
if (origin == Origin.WebXml) {
    // Element came from web.xml
}

/**
 * Check if webapp is distributable
 */
public boolean isDistributable();

/**
 * Check if metadata is complete (no annotation scanning needed)
 */
public boolean isMetaDataComplete();

/**
 * Check if duplicate fragment names are allowed
 */
public boolean isAllowDuplicateFragmentNames();
public void setAllowDuplicateFragmentNames(boolean allowDuplicateFragmentNames);

/**
 * Check if XML validation is enabled
 */
public boolean isValidateXml();
public void setValidateXml(boolean validateXml);

/**
 * Add WEB-INF resource
 */
public void addWebInfResource(Resource newResource);

/**
 * Get WEB-INF resources
 */
public List<Resource> getWebInfResources(boolean withOrdering);

/**
 * Add container resource (from server classpath)
 */
public void addContainerResource(Resource jar);

/**
 * Get container resources
 */
public List<Resource> getContainerResources();

/**
 * Set WEB-INF/classes resources
 */
public void setWebInfClassesResources(List<Resource> dirs);

/**
 * Get WEB-INF/classes resources
 */
public List<Resource> getWebInfClassesResources();

/**
 * Enum representing the source of webapp configuration elements
 */
public enum Origin {
    NotSet,      // Origin not determined
    WebXml,      // From web.xml
    WebDefaults, // From web-defaults.xml
    WebOverride, // From override descriptor
    WebFragment, // From web-fragment.xml
    Annotation,  // From annotation
    API;         // From programmatic API
    
    /**
     * Determine origin from object
     */
    public static Origin of(Object o);
}

/**
 * Metadata about where deployable elements were declared
 */
public static class OriginInfo {
    
    /**
     * Create origin info for annotation
     */
    public OriginInfo(String n, Annotation a, Class<?> ac);
    
    /**
     * Create origin info for descriptor
     */
    public OriginInfo(String n, Descriptor d);
    
    /**
     * Create origin info for API
     */
    public OriginInfo(String n);
    
    /**
     * Get origin name/identifier
     */
    public String getName();
    
    /**
     * Get origin type
     */
    public Origin getOriginType();
    
    /**
     * Get descriptor (if origin is descriptor-based)
     */
    public Descriptor getDescriptor();
}

/**
 * Metadata completeness status
 */
public enum Complete {
    NotSet,  // Completeness not determined
    True,    // Metadata is complete
    False    // Metadata is incomplete
}

/**
 * Base class for XML descriptor parsing and representation
 */
public abstract class Descriptor {
    
    /**
     * Create descriptor with XML resource
     */
    protected Descriptor(Resource xml);
    
    /**
     * Parse descriptor with XML parser
     */
    public void parse(XmlParser parser) throws Exception;
    
    /**
     * Check if descriptor has been parsed
     */
    public boolean isParsed();
    
    /**
     * Get descriptor resource
     */
    public Resource getResource();
    
    /**
     * Get root XML node
     */
    public XmlParser.Node getRoot();
}

/**
 * Web.xml descriptor
 */
public class WebDescriptor extends Descriptor {
    public WebDescriptor(Resource xml);
}

/**
 * Web-defaults.xml descriptor
 */
public class DefaultsDescriptor extends Descriptor {
    public DefaultsDescriptor(Resource xml);
}

/**
 * Override descriptor
 */
public class OverrideDescriptor extends Descriptor {
    public OverrideDescriptor(Resource xml);
}

/**
 * Web-fragment.xml descriptor  
 */
public class FragmentDescriptor extends Descriptor {
    public FragmentDescriptor(Resource xml);
    
    // Fragment-specific methods
    public String getName();
    public List<String> getEnums();
    // Additional fragment handling methods...
}

/**
 * Interface for processing XML descriptors
 */
public interface DescriptorProcessor {
    
    /**
     * Process descriptor and apply to webapp context
     */
    void process(WebAppContext context, Descriptor descriptor) throws Exception;
}

/**
 * Standard XML descriptor processor
 */
public class StandardDescriptorProcessor implements DescriptorProcessor {
    
    public void process(WebAppContext context, Descriptor descriptor) throws Exception;
}

/**
 * Iterative descriptor processor for complex processing
 */
public class IterativeDescriptorProcessor implements DescriptorProcessor {
    
    public void process(WebAppContext context, Descriptor descriptor) throws Exception;
}

// Create and populate metadata
MetaData metaData = new MetaData();

// Set descriptors
metaData.setWebDescriptor(new WebDescriptor(webXmlResource));
metaData.setDefaultsDescriptor(new DefaultsDescriptor(defaultsResource));

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

// Order and resolve
metaData.orderFragments();
metaData.resolve(webAppContext);

// Track where servlet was configured
metaData.setOrigin("myServlet", webXmlDescriptor);

// Later, check origin
Origin origin = metaData.getOrigin("myServlet");
switch (origin) {
    case WebXml:
        // Handle web.xml configuration
        break;
    case Annotation:
        // Handle annotation configuration
        break;
    case API:
        // Handle programmatic configuration
        break;
}

// Process all fragments in WEB-INF/lib
for (Resource jar : webInfLibJars) {
    Resource fragmentXml = jar.addPath("META-INF/web-fragment.xml");
    if (fragmentXml.exists()) {
        FragmentDescriptor fragment = new FragmentDescriptor(fragmentXml);
        metaData.addFragmentDescriptor(jar, fragment);
    }
}

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

// Process ordered fragments
for (FragmentDescriptor fragment : metaData.getOrderedFragments()) {
    processFragment(fragment);
}