You need to configure an application with an XML document.

Use an implementation of XMLConfiguration to load configuration parameters from an XML document. The following XML document contains configuration information that is loaded with a DOMConfiguration object:

<?xml version="1.0" encoding="ISO-8859-1" ?>

<engine-config>
    <start-criteria>
        <criteria type="critical">
            Temperature Above -10 Celsius
        </criteria>
        <criteria>
            Fuel tank is not empty
        </criteria>
    </start-criteria>
    <name>
        <first>Tom</first>
        <last>Payne</last>
    </name>
    <horsepower>42</horsepower>
</engine-config>

A DOMConfiguration object uses the Xerces XML parser to parse an entire XML document into a DOM Document object. Subsequent calls to methods on the Configuration interface cause the DOMConfiguration object to traverse nodes in the Document. The code to read in this XML configuration with DOMConfiguration follows:

import org.apache.commons.configuration.Configuration;
import org.apache.commons.configuration.DOMConfiguration;

String resource = "com/discursive/jccook/configuration/global.xml";
Configuration config = new DOMConfiguration(resource);
        
// Retrieve a list of all Criteria elements
List startCriteria = config.getList("start-criteria.criteria");

// Retrieve the value of the first criteria element
String firstCriteria = config.getString("start-criteria.criteria(0)");

// Retrieve the type attribute of the first criteria element
String firstCriteriaType = config.getString("start-criteria.criteria(0)[@type]");

// Retrieve the horsepower as an int
int horsepower = config.getInt("horsepower");

Passing a String to the constructor of DOMConfiguration loads an XML document from the classpath as a resource. If you need to load XML configuration from a file, pass a File object to the DOMConfiguration constructor. Configuration parameters are retrieved using methods from the Configuration interface, and parameters are referenced using a syntax that resembles XPath. Subelements are referenced by appending a period and the subelement name to the name of an element; in this example, name.first references the subelement first of the element name. Attributes are referenced by prefixing an attribute name with an @ and surrounding the reference with brackets; in this example, start-critera.criteria(0)[@type] references the type attribute of the criteria element. Specific elements in a list of elements are referenced by surrounding the index with parentheses; start-criteria.criteria(0) references the first criteria element.

DOMConfiguration will only work if the Xerces XML parser is available in your classpath. If Xerces is not available, you may use another implementation of XMLConfiguration, DOM4JConfiguration, which is written to parse an XML document using DOM4J. To use the DOM4JConfiguration, make sure that DOM4J is in your classpath, and interchange DOM4JConfiguration with DOMConfiguration from the previous example.

For more information about downloading the Xerces XML parser, see the Xerces project page at http://xml.apache.org/xerces.

For more information about downloading DOM4J, see the DOM4J project page at http://www.dom4j.org.