Descriptor Classes

/**
 * Base class for XML descriptor parsing and representation.
 * Provides common functionality for parsing XML configuration files.
 */
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 after parsing
     */
    public XmlParser.Node getRoot();
    
    /**
     * Get the validated XML if validation was performed
     */
    public String getValidatedXML();
    
    /**
     * Process the descriptor with standard processing
     */
    public void processDocumentTree(XmlParser.Node root);
}

/**
 * Descriptor for web.xml files supporting servlet specification versions.
 * Handles metadata-complete, distributable, and ordering configurations.
 */
public class WebDescriptor extends Descriptor {
    
    /**
     * Create web descriptor with XML resource
     */
    public WebDescriptor(Resource xml);
    
    /**
     * Get servlet specification major version
     */
    public int getMajorVersion();
    
    /**
     * Get servlet specification minor version
     */
    public int getMinorVersion();
    
    /**
     * Check if metadata is complete (no annotation scanning needed)
     */
    public MetaData.Complete getMetaDataComplete();
    
    /**
     * Check if webapp is distributable
     */
    public boolean isDistributable();
    
    /**
     * Check if fragments are ordered
     */
    public boolean isOrdered();
    
    /**
     * Get fragment ordering configuration
     */
    public Ordering getOrdering();
}

/**
 * Check if a web descriptor specifies metadata-complete
 */
public static boolean isMetaDataComplete(WebDescriptor descriptor);

/**
 * Create standard XML parser for web descriptors
 */
public static XmlParser getParser(boolean validating);

/**
 * Create new XML parser instance
 */
public static XmlParser newParser(boolean validating);

/**
 * Descriptor for web-fragment.xml files with support for fragment
 * ordering via before/after relationships.
 */
public class FragmentDescriptor extends WebDescriptor {
    
    /**
     * Fragment ordering types
     */
    public enum OtherType { None, Before, After }
    
    /**
     * Create fragment descriptor with XML resource
     */
    public FragmentDescriptor(Resource xml);
    
    /**
     * Get the fragment name
     */
    public String getName();
    
    /**
     * Get list of fragment names this fragment should come before
     */
    public List<String> getBefores();
    
    /**
     * Get list of fragment names this fragment should come after
     */
    public List<String> getAfters();
    
    /**
     * Get the type of "others" ordering relationship
     */
    public OtherType getOtherType();
    
    /**
     * Get enumeration values if specified
     */
    public List<String> getEnums();
}

// Create and parse fragment descriptor
Resource fragmentXml = Resource.newResource("META-INF/web-fragment.xml");
FragmentDescriptor fragment = new FragmentDescriptor(fragmentXml);
fragment.parse(WebDescriptor.newParser(true));

// Check fragment ordering
String name = fragment.getName();
List<String> before = fragment.getBefores();
List<String> after = fragment.getAfters();

if (fragment.getOtherType() == FragmentDescriptor.OtherType.Before) {
    // This fragment should come before all others not explicitly ordered
}

/**
 * Descriptor for web-defaults.xml files that provide default
 * servlet and filter configurations applied to all webapps.
 */
public class DefaultsDescriptor extends WebDescriptor {
    
    /**
     * Create defaults descriptor with XML resource
     */
    public DefaultsDescriptor(Resource xml);
}

/**
 * Descriptor for override configuration files that can override
 * settings from web.xml and web-fragment.xml files.
 */
public class OverrideDescriptor extends WebDescriptor {
    
    /**
     * Create override descriptor with XML resource
     */
    public OverrideDescriptor(Resource xml);
}

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

/**
 * Standard processor for web.xml descriptors
 */
public class StandardDescriptorProcessor implements DescriptorProcessor {
    
    /**
     * Process standard web.xml descriptor
     */
    public void process(WebAppContext context, Descriptor descriptor) throws Exception;
}

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

/**
 * Interface for ordering web fragments according to servlet specification
 * or custom ordering strategies.
 */
public interface Ordering {
    
    /**
     * Order fragment resources according to ordering rules
     * 
     * @param fragments List of fragment resources to order
     * @return Ordered list of fragment resources
     */
    List<Resource> order(List<Resource> fragments);
}

// Process web.xml
Resource webXml = webAppContext.getWebInf().addPath("web.xml");
if (webXml.exists()) {
    WebDescriptor webDescriptor = new WebDescriptor(webXml);
    webDescriptor.parse(WebDescriptor.newParser(true));
    
    // Check configuration
    if (webDescriptor.isDistributable()) {
        webAppContext.setDistributable(true);
    }
    
    // Add to metadata
    metaData.setWebDescriptor(webDescriptor);
}

// Discover fragments in WEB-INF/lib
List<FragmentDescriptor> fragments = new ArrayList<>();
for (Resource jar : webInfLibJars) {
    Resource fragmentXml = jar.addPath("META-INF/web-fragment.xml");
    if (fragmentXml.exists()) {
        FragmentDescriptor fragment = new FragmentDescriptor(fragmentXml);
        fragment.parse(WebDescriptor.newParser(true));
        fragments.add(fragment);
        
        // Add to metadata with jar association
        metaData.addFragmentDescriptor(jar, fragment);
    }
}

// Process ordering
metaData.orderFragments();

// Implement custom descriptor processor
public class CustomDescriptorProcessor implements DescriptorProcessor {
    @Override
    public void process(WebAppContext context, Descriptor descriptor) throws Exception {
        if (descriptor instanceof WebDescriptor) {
            WebDescriptor webDesc = (WebDescriptor) descriptor;
            
            // Custom processing logic
            XmlParser.Node root = webDesc.getRoot();
            processCustomElements(context, root);
        }
    }
    
    private void processCustomElements(WebAppContext context, XmlParser.Node root) {
        // Process custom XML elements
        for (XmlParser.Node node : root.nodes("custom-config")) {
            String value = node.getString("value", "default");
            context.setAttribute("custom.config", value);
        }
    }
}

// Register custom processor
metaData.addDescriptorProcessor(new CustomDescriptorProcessor());

// Apply override descriptor to modify webapp configuration
Resource overrideXml = Resource.newResource("conf/webapp-override.xml");
if (overrideXml.exists()) {
    OverrideDescriptor override = new OverrideDescriptor(overrideXml);
    override.parse(WebDescriptor.newParser(true));
    
    // Add to metadata - will be processed after main web.xml
    metaData.addOverrideDescriptor(override);
}