/*

  * Licensed to the Apache Software Foundation (ASF) under one or more

  * contributor license agreements.  See the NOTICE file distributed with

  * this work for additional information regarding copyright ownership.

  * The ASF licenses this file to You under the Apache License, Version 2.0

  * (the "License"); you may not use this file except in compliance with

  * the License.  You may obtain a copy of the License at

  *

  *     http://www.apache.org/licenses/LICENSE-2.0

  *

  * Unless required by applicable law or agreed to in writing, software

  * distributed under the License is distributed on an "AS IS" BASIS,

  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

  * See the License for the specific language governing permissions and

  * limitations under the License.

  */

 package org.apache.commons.configuration;

 import java.io.File;

 import java.io.IOException;

 import java.io.InputStream;

 import java.io.Reader;

 import java.io.Writer;

 import java.net.URL;

 import java.net.URLConnection;

 import java.util.ArrayList;

 import java.util.Collection;

 import java.util.HashMap;

 import java.util.Iterator;

 import java.util.List;

 import java.util.Map;

 import javax.xml.parsers.DocumentBuilder;

 import javax.xml.parsers.DocumentBuilderFactory;

 import javax.xml.parsers.ParserConfigurationException;

 import javax.xml.transform.OutputKeys;

 import javax.xml.transform.Result;

 import javax.xml.transform.Source;

 import javax.xml.transform.Transformer;

 import javax.xml.transform.TransformerException;

 import javax.xml.transform.TransformerFactory;

 import javax.xml.transform.TransformerFactoryConfigurationError;

 import javax.xml.transform.dom.DOMSource;

 import javax.xml.transform.stream.StreamResult;

 import org.apache.commons.configuration.tree.ConfigurationNode;

 import org.w3c.dom.Attr;

 import org.w3c.dom.CDATASection;

 import org.w3c.dom.DOMException;

 import org.w3c.dom.Document;

 import org.w3c.dom.Element;

 import org.w3c.dom.NamedNodeMap;

 import org.w3c.dom.NodeList;

 import org.w3c.dom.Text;

 import org.xml.sax.EntityResolver;

 import org.xml.sax.InputSource;

 import org.xml.sax.SAXException;

 import org.xml.sax.SAXParseException;

 import org.xml.sax.helpers.DefaultHandler;

 /**

  * <p>A specialized hierarchical configuration class that is able to parse XML

  * documents.</p>

  *

  * <p>The parsed document will be stored keeping its structure. The class also

  * tries to preserve as much information from the loaded XML document as

  * possible, including comments and processing instructions. These will be

  * contained in documents created by the <code>save()</code> methods, too.</p>

  *

  * <p>Like other file based configuration classes this class maintains the name

  * and path to the loaded configuration file. These properties can be altered

  * using several setter methods, but they are not modified by <code>save()</code>

  * and <code>load()</code> methods. If XML documents contain relative paths to

  * other documents (e.g. to a DTD), these references are resolved based on the

  * path set for this configuration.</p>

  *

  * <p>By inheriting from <code>{@link AbstractConfiguration}</code> this class

  * provides some extended functionality, e.g. interpolation of property values.

  * Like in <code>{@link PropertiesConfiguration}</code> property values can

  * contain delimiter characters (the comma ',' per default) and are then split

  * into multiple values. This works for XML attributes and text content of

  * elements as well. The delimiter can be escaped by a backslash. As an example

  * consider the following XML fragment:</p>

  *

  * <p>

  * <pre>

  * <config>

  *   <array>10,20,30,40</array>

  *   <scalar>3\,1415</scalar>

  *   <cite text="To be or not to be\, this is the question!"/>

  * </config>

  * </pre>

  * </p>

  * <p>Here the content of the <code>array</code> element will be split at

  * the commas, so the <code>array</code> key will be assigned 4 values. In the

  * <code>scalar</code> property and the <code>text</code> attribute of the

  * <code>cite</code> element the comma is escaped, so that no splitting is

  * performed.</p>

  *

  * <p>The configuration API allows setting multiple values for a single attribute,

  * e.g. something like the following is legal (assuming that the default

  * expression engine is used):

  * <pre>

  * XMLConfiguration config = new XMLConfiguration();

  * config.addProperty("test.dir[@name]", "C:\\Temp\\");

  * config.addProperty("test.dir[@name]", "D:\\Data\\");

  * </pre></p>

  *

  * <p>Because in XML such a constellation is not directly supported (an attribute

  * can appear only once for a single element), the values are concatenated to a

  * single value. If delimiter parsing is enabled (refer to the

  * <code>{@link #setDelimiterParsingDisabled(boolean)}</code> method), the

  * current list delimiter character will be used as separator. Otherwise the

  * pipe symbol ("|") will be used for this purpose. No matter which character is

  * used as delimiter, it can always be escaped with a backslash. A backslash

  * itself can also be escaped with another backslash. Consider the following

  * example fragment from a configuration file:

  * <pre>

  * <directories names="C:\Temp\\|D:\Data\"/>

  * </pre>

  * Here the backslash after Temp is escaped. This is necessary because it

  * would escape the list delimiter (the pipe symbol assuming that list delimiter

  * parsing is disabled) otherwise. So this attribute would have two values.</p>

  *

  * <p>Note: You should ensure that the <em>delimiter parsing disabled</em>

  * property is always consistent when you load and save a configuration file.

  * Otherwise the values of properties can become corrupted.</p>

  *

  * <p><code>XMLConfiguration</code> implements the <code>{@link FileConfiguration}</code>

  * interface and thus provides full support for loading XML documents from

  * different sources like files, URLs, or streams. A full description of these

  * features can be found in the documentation of

  * <code>{@link AbstractFileConfiguration}</code>.</p>

  *

  * <p><em>Note:</em>Configuration objects of this type can be read concurrently

  * by multiple threads. However if one of these threads modifies the object,

  * synchronization has to be performed manually.</p>

  *

  * @since commons-configuration 1.0

  *

  * @author Jörg Schaible

  * @author Oliver Heger

  * @version $Revision: 589380 $, $Date: 2007-10-28 17:37:35 +0100 (So, 28 Okt 2007) $

  */

 public class XMLConfiguration extends AbstractHierarchicalFileConfiguration

     implements EntityResolver

 {

     /**

      * The serial version UID.

      */

     private static final long serialVersionUID = 2453781111653383552L;

     /** Constant for the default root element name. */

     private static final String DEFAULT_ROOT_NAME = "configuration";

     /** Constant for the delimiter for multiple attribute values.*/

     private static final char ATTR_VALUE_DELIMITER = '|';

     /** The document from this configuration's data source. */

     private Document document;

     /** Stores a map with the registered public IDs.*/

     private Map registeredEntities = new HashMap();

     /** Stores the name of the root element. */

     private String rootElementName;

     /** Stores the public ID from the DOCTYPE.*/

     private String publicID;

     /** Stores the system ID from the DOCTYPE.*/

     private String systemID;

     /** Stores the document builder that should be used for loading.*/

     private DocumentBuilder documentBuilder;

     /** Stores a flag whether DTD validation should be performed.*/

     private boolean validating;

     /**

      * Creates a new instance of <code>XMLConfiguration</code>.

      */

     public XMLConfiguration()

     {

         super();

     }

     /**

      * Creates a new instance of <code>XMLConfiguration</code> and copies the

      * content of the passed in configuration into this object. Note that only

      * the data of the passed in configuration will be copied. If, for instance,

      * the other configuration is a <code>XMLConfiguration</code>, too,

      * things like comments or processing instructions will be lost.

      *

      * @param c the configuration to copy

      * @since 1.4

      */

     public XMLConfiguration(HierarchicalConfiguration c)

     {

         super(c);

         clearReferences(getRootNode());

     }

     /**

      * Creates a new instance of <code>XMLConfiguration</code>. The

      * configuration is loaded from the specified file

      *

      * @param fileName the name of the file to load

      * @throws ConfigurationException if the file cannot be loaded

      */

     public XMLConfiguration(String fileName) throws ConfigurationException

     {

         super(fileName);

     }

     /**

      * Creates a new instance of <code>XMLConfiguration</code>.

      * The configuration is loaded from the specified file.

      *

      * @param file the file

      * @throws ConfigurationException if an error occurs while loading the file

      */

     public XMLConfiguration(File file) throws ConfigurationException

     {

         super(file);

     }

     /**

      * Creates a new instance of <code>XMLConfiguration</code>.

      * The configuration is loaded from the specified URL.

      *

      * @param url the URL

      * @throws ConfigurationException if loading causes an error

      */

     public XMLConfiguration(URL url) throws ConfigurationException

     {

         super(url);

     }

     /**

      * Returns the name of the root element. If this configuration was loaded

      * from a XML document, the name of this document's root element is

      * returned. Otherwise it is possible to set a name for the root element

      * that will be used when this configuration is stored.

      *

      * @return the name of the root element

      */

     public String getRootElementName()

     {

         if (getDocument() == null)

         {

             return (rootElementName == null) ? DEFAULT_ROOT_NAME : rootElementName;

         }

         else

         {

             return getDocument().getDocumentElement().getNodeName();

         }

     }

     /**

      * Sets the name of the root element. This name is used when this

      * configuration object is stored in an XML file. Note that setting the name

      * of the root element works only if this configuration has been newly

      * created. If the configuration was loaded from an XML file, the name

      * cannot be changed and an <code>UnsupportedOperationException</code>

      * exception is thrown. Whether this configuration has been loaded from an

      * XML document or not can be found out using the <code>getDocument()</code>

      * method.

      *

      * @param name the name of the root element

      */

     public void setRootElementName(String name)

     {

         if (getDocument() != null)

         {

             throw new UnsupportedOperationException("The name of the root element "

                     + "cannot be changed when loaded from an XML document!");

         }

         rootElementName = name;

     }

     /**

      * Returns the <code>DocumentBuilder</code> object that is used for

      * loading documents. If no specific builder has been set, this method

      * returns <b>null</b>.

      *

      * @return the <code>DocumentBuilder</code> for loading new documents

      * @since 1.2

      */

     public DocumentBuilder getDocumentBuilder()

     {

         return documentBuilder;

     }

     /**

      * Sets the <code>DocumentBuilder</code> object to be used for loading

      * documents. This method makes it possible to specify the exact document

      * builder. So an application can create a builder, configure it for its

      * special needs, and then pass it to this method.

      *

      * @param documentBuilder the document builder to be used; if undefined, a

      * default builder will be used

      * @since 1.2

      */

     public void setDocumentBuilder(DocumentBuilder documentBuilder)

     {

         this.documentBuilder = documentBuilder;

     }

     /**

      * Returns the public ID of the DOCTYPE declaration from the loaded XML

      * document. This is <b>null</b> if no document has been loaded yet or if

      * the document does not contain a DOCTYPE declaration with a public ID.

      *

      * @return the public ID

      * @since 1.3

      */

     public String getPublicID()

     {

         return publicID;

     }

     /**

      * Sets the public ID of the DOCTYPE declaration. When this configuration is

      * saved, a DOCTYPE declaration will be constructed that contains this

      * public ID.

      *

      * @param publicID the public ID

      * @since 1.3

      */

     public void setPublicID(String publicID)

     {

         this.publicID = publicID;

     }

     /**

      * Returns the system ID of the DOCTYPE declaration from the loaded XML

      * document. This is <b>null</b> if no document has been loaded yet or if

      * the document does not contain a DOCTYPE declaration with a system ID.

      *

      * @return the system ID

      * @since 1.3

      */

     public String getSystemID()

     {

         return systemID;

     }

     /**

      * Sets the system ID of the DOCTYPE declaration. When this configuration is

      * saved, a DOCTYPE declaration will be constructed that contains this

      * system ID.

      *

      * @param systemID the system ID

      * @since 1.3

      */

     public void setSystemID(String systemID)

     {

         this.systemID = systemID;

     }

     /**

      * Returns the value of the validating flag.

      *

      * @return the validating flag

      * @since 1.2

      */

     public boolean isValidating()

     {

         return validating;

     }

     /**

      * Sets the value of the validating flag. This flag determines whether

      * DTD validation should be performed when loading XML documents. This

      * flag is evaluated only if no custom <code>DocumentBuilder</code> was set.

      *

      * @param validating the validating flag

      * @since 1.2

      */

     public void setValidating(boolean validating)

     {

         this.validating = validating;

     }

     /**

      * Returns the XML document this configuration was loaded from. The return

      * value is <b>null</b> if this configuration was not loaded from a XML

      * document.

      *

      * @return the XML document this configuration was loaded from

      */

     public Document getDocument()

     {

         return document;

     }

     /**

      * Removes all properties from this configuration. If this configuration

      * was loaded from a file, the associated DOM document is also cleared.

      */

     public void clear()

     {

         super.clear();

         document = null;

     }

     /**

      * Initializes this configuration from an XML document.

      *

      * @param document the document to be parsed

      * @param elemRefs a flag whether references to the XML elements should be set

      */

     public void initProperties(Document document, boolean elemRefs)

     {

         if (document.getDoctype() != null)

         {

             setPublicID(document.getDoctype().getPublicId());

             setSystemID(document.getDoctype().getSystemId());

         }

         constructHierarchy(getRoot(), document.getDocumentElement(), elemRefs);

         if (elemRefs)

         {

             getRoot().setReference(document.getDocumentElement());

         }

     }

     /**

      * Helper method for building the internal storage hierarchy. The XML

      * elements are transformed into node objects.

      *

      * @param node the actual node

      * @param element the actual XML element

      * @param elemRefs a flag whether references to the XML elements should be set

      */

     private void constructHierarchy(Node node, Element element, boolean elemRefs)

     {

         processAttributes(node, element, elemRefs);

         StringBuffer buffer = new StringBuffer();

         NodeList list = element.getChildNodes();

         for (int i = 0; i < list.getLength(); i++)

         {

             org.w3c.dom.Node w3cNode = list.item(i);

             if (w3cNode instanceof Element)

             {

                 Element child = (Element) w3cNode;

                 Node childNode = new XMLNode(child.getTagName(),

                         elemRefs ? child : null);

                 constructHierarchy(childNode, child, elemRefs);

                 node.addChild(childNode);

                 handleDelimiters(node, childNode);

             }

             else if (w3cNode instanceof Text)

             {

                 Text data = (Text) w3cNode;

                 buffer.append(data.getData());

             }

         }

         String text = buffer.toString().trim();

         if (text.length() > 0 || !node.hasChildren())

         {

             node.setValue(text);

         }

     }

     /**

      * Helper method for constructing node objects for the attributes of the

      * given XML element.

      *

      * @param node the actual node

      * @param element the actual XML element

      * @param elemRefs a flag whether references to the XML elements should be set

      */

     private void processAttributes(Node node, Element element, boolean elemRefs)

     {

         NamedNodeMap attributes = element.getAttributes();

         for (int i = 0; i < attributes.getLength(); ++i)

         {

             org.w3c.dom.Node w3cNode = attributes.item(i);

             if (w3cNode instanceof Attr)

             {

                 Attr attr = (Attr) w3cNode;

                 Iterator it = PropertyConverter.split(

                         attr.getValue(),

                         isDelimiterParsingDisabled() ? ATTR_VALUE_DELIMITER

                                 : getListDelimiter()).iterator();

                 while (it.hasNext())

                 {

                     Node child = new XMLNode(attr.getName(),

                             elemRefs ? element : null);

                     child.setValue(it.next());

                     node.addAttribute(child);

                 }

             }

         }

     }

     /**

      * Deals with elements whose value is a list. In this case multiple child

      * elements must be added.

      *

      * @param parent the parent element

      * @param child the child element

      */

     private void handleDelimiters(Node parent, Node child)

     {

         if (child.getValue() != null)

         {

             List values;

             if (isDelimiterParsingDisabled())

             {

                 values = new ArrayList();

                 values.add(child.getValue().toString());

             }

             else

             {

                 values = PropertyConverter.split(child.getValue().toString(),

                     getListDelimiter());

             }

             if (values.size() > 1)

             {

                 Iterator it = values.iterator();

                 // Create new node for the original child's first value

                 Node c = createNode(child.getName());

                 c.setValue(it.next());

                 // Copy original attributes to the new node

                 for (Iterator itAttrs = child.getAttributes().iterator(); itAttrs

                         .hasNext();)

                 {

                     Node ndAttr = (Node) itAttrs.next();

                     ndAttr.setReference(null);

                     c.addAttribute(ndAttr);

                 }

                 parent.remove(child);

                 parent.addChild(c);

                 // add multiple new children

                 while (it.hasNext())

                 {

                     c = new XMLNode(child.getName(), null);

                     c.setValue(it.next());

                     parent.addChild(c);

                 }

             }

             else if (values.size() == 1)

             {

                 // we will have to replace the value because it might

                 // contain escaped delimiters

                 child.setValue(values.get(0));

             }

         }

     }

     /**

      * Creates the <code>DocumentBuilder</code> to be used for loading files.

      * This implementation checks whether a specific

      * <code>DocumentBuilder</code> has been set. If this is the case, this

      * one is used. Otherwise a default builder is created. Depending on the

      * value of the validating flag this builder will be a validating or a non

      * validating <code>DocumentBuilder</code>.

      *

      * @return the <code>DocumentBuilder</code> for loading configuration

      * files

      * @throws ParserConfigurationException if an error occurs

      * @since 1.2

      */

     protected DocumentBuilder createDocumentBuilder()

             throws ParserConfigurationException

     {

         if (getDocumentBuilder() != null)

         {

             return getDocumentBuilder();

         }

         else

         {

             DocumentBuilderFactory factory = DocumentBuilderFactory

                     .newInstance();

             factory.setValidating(isValidating());

             DocumentBuilder result = factory.newDocumentBuilder();

             result.setEntityResolver(this);

             if (isValidating())

             {

                 // register an error handler which detects validation errors

                 result.setErrorHandler(new DefaultHandler()

                 {

                     public void error(SAXParseException ex) throws SAXException

                     {

                         throw ex;

                     }

                 });

             }

             return result;

         }

     }

     /**

      * Creates a DOM document from the internal tree of configuration nodes.

      *

      * @return the new document

      * @throws ConfigurationException if an error occurs

      */

     protected Document createDocument() throws ConfigurationException

     {

         try

         {

             if (document == null)

             {

                 DocumentBuilder builder = DocumentBuilderFactory.newInstance().newDocumentBuilder();

                 Document newDocument = builder.newDocument();

                 Element rootElem = newDocument.createElement(getRootElementName());

                 newDocument.appendChild(rootElem);

                 document = newDocument;

             }

             XMLBuilderVisitor builder = new XMLBuilderVisitor(document,

                     isDelimiterParsingDisabled() ? (char) 0 : getListDelimiter());

             builder.processDocument(getRoot());

             return document;

         } /* try */

         catch (DOMException domEx)

         {

             throw new ConfigurationException(domEx);

         }

         catch (ParserConfigurationException pex)

         {

             throw new ConfigurationException(pex);

         }

     }

     /**

      * Creates a new node object. This implementation returns an instance of the

      * <code>XMLNode</code> class.

      *

      * @param name the node's name

      * @return the new node

      */

     protected Node createNode(String name)

     {

         return new XMLNode(name, null);

     }

     /**

      * Loads the configuration from the given input stream.

      *

      * @param in the input stream

      * @throws ConfigurationException if an error occurs

      */

     public void load(InputStream in) throws ConfigurationException

     {

         load(new InputSource(in));

     }

     /**

      * Load the configuration from the given reader.

      * Note that the <code>clear()</code> method is not called, so

      * the properties contained in the loaded file will be added to the

      * actual set of properties.

      *

      * @param in An InputStream.

      *

      * @throws ConfigurationException if an error occurs

      */

     public void load(Reader in) throws ConfigurationException

     {

         load(new InputSource(in));

     }

     /**

      * Loads a configuration file from the specified input source.

      * @param source the input source

      * @throws ConfigurationException if an error occurs

      */

     private void load(InputSource source) throws ConfigurationException

     {

         try

         {

             URL sourceURL = getDelegate().getURL();

             if (sourceURL != null)

             {

                 source.setSystemId(sourceURL.toString());

             }

             DocumentBuilder builder = createDocumentBuilder();

             Document newDocument = builder.parse(source);

             Document oldDocument = document;

             document = null;

             initProperties(newDocument, oldDocument == null);

             document = (oldDocument == null) ? newDocument : oldDocument;

         }

         catch (Exception e)

         {

             throw new ConfigurationException(e.getMessage(), e);

         }

     }

     /**

      * Saves the configuration to the specified writer.

      *

      * @param writer the writer used to save the configuration

      * @throws ConfigurationException if an error occurs

      */

     public void save(Writer writer) throws ConfigurationException

     {

         try

         {

             Transformer transformer = createTransformer();

             Source source = new DOMSource(createDocument());

             Result result = new StreamResult(writer);

             transformer.transform(source, result);

         }

         catch (TransformerException e)

         {

             throw new ConfigurationException(e.getMessage(), e);

         }

         catch (TransformerFactoryConfigurationError err)

         {

             throw new ConfigurationException(err.getMessage(), err);

         }

     }

     /**

      * Creates and initializes the transformer used for save operations. This

      * base implementation initializes all of the default settings like

      * indention mode and the DOCTYPE. Derived classes may overload this method

      * if they have specific needs.

      *

      * @return the transformer to use for a save operation

      * @throws TransformerException if an error occurs

      * @since 1.3

      */

     protected Transformer createTransformer() throws TransformerException

     {

         Transformer transformer = TransformerFactory.newInstance()

                 .newTransformer();

         transformer.setOutputProperty(OutputKeys.INDENT, "yes");

         if (getEncoding() != null)

         {

             transformer.setOutputProperty(OutputKeys.ENCODING, getEncoding());

         }

         if (getPublicID() != null)

         {

             transformer.setOutputProperty(OutputKeys.DOCTYPE_PUBLIC,

                     getPublicID());

         }

         if (getSystemID() != null)

         {

             transformer.setOutputProperty(OutputKeys.DOCTYPE_SYSTEM,

                     getSystemID());

         }

         return transformer;

     }

     /**

      * Creates a copy of this object. The new configuration object will contain

      * the same properties as the original, but it will lose any connection to a

      * source document (if one exists). This is to avoid race conditions if both

      * the original and the copy are modified and then saved.

      *

      * @return the copy

      */

     public Object clone()

     {

         XMLConfiguration copy = (XMLConfiguration) super.clone();

         // clear document related properties

         copy.document = null;

         copy.setDelegate(copy.createDelegate());

         // clear all references in the nodes, too

         clearReferences(copy.getRootNode());

         return copy;

     }

     /**

      * Creates the file configuration delegate for this object. This implementation

      * will return an instance of a class derived from <code>FileConfigurationDelegate</code>

      * that deals with some specialities of <code>XMLConfiguration</code>.

      * @return the delegate for this object

      */

     protected FileConfigurationDelegate createDelegate()

     {

         return new XMLFileConfigurationDelegate();

     }

     /**

      * Adds a collection of nodes directly to this configuration. This

      * implementation ensures that the nodes to be added are of the correct node

      * type (they have to be converted to <code>XMLNode</code> if necessary).

      *

      * @param key the key where the nodes are to be added

      * @param nodes the collection with the new nodes

      * @since 1.5

      */

     public void addNodes(String key, Collection nodes)

     {

         Collection xmlNodes;

         if (nodes != null && !nodes.isEmpty())

         {

             xmlNodes = new ArrayList(nodes.size());

             for (Iterator it = nodes.iterator(); it.hasNext();)

             {

                 xmlNodes.add(convertToXMLNode((ConfigurationNode) it.next()));

             }

         }

         else

         {

             xmlNodes = nodes;

         }

         super.addNodes(key, xmlNodes);

     }

     /**

      * Converts the specified node into a <code>XMLNode</code> if necessary.

      * This is required for nodes that are directly added, e.g. by

      * <code>addNodes()</code>. If the passed in node is already an instance

      * of <code>XMLNode</code>, it is directly returned, and conversion

      * stops. Otherwise a new <code>XMLNode</code> is created, and the

      * children are also converted.

      *

      * @param node the node to be converted

      * @return the converted node

      */

     private XMLNode convertToXMLNode(ConfigurationNode node)

     {

         if (node instanceof XMLNode)

         {

             return (XMLNode) node;

         }

         XMLNode nd = (XMLNode) createNode(node.getName());

         nd.setValue(node.getValue());

         for (Iterator it = node.getChildren().iterator(); it.hasNext();)

         {

             nd.addChild(convertToXMLNode((ConfigurationNode) it.next()));

         }

         for (Iterator it = node.getAttributes().iterator(); it.hasNext();)

         {

             nd.addAttribute(convertToXMLNode((ConfigurationNode) it.next()));

         }

         return nd;

     }

     /**

      * <p>

      * Registers the specified DTD URL for the specified public identifier.

      * </p>

      * <p>

      * <code>XMLConfiguration</code> contains an internal

      * <code>EntityResolver</code> implementation. This maps

      * <code>PUBLICID</code>'s to URLs (from which the resource will be

      * loaded). A common use case for this method is to register local URLs

      * (possibly computed at runtime by a class loader) for DTDs. This allows

      * the performance advantage of using a local version without having to

      * ensure every <code>SYSTEM</code> URI on every processed XML document is

      * local. This implementation provides only basic functionality. If more

      * sophisticated features are required, using

      * {@link #setDocumentBuilder(DocumentBuilder)} to set a custom

      * <code>DocumentBuilder</code> (which also can be initialized with a

      * custom <code>EntityResolver</code>) is recommended.

      * </p>

      * <p>

      * <strong>Note:</strong> This method will have no effect when a custom

      * <code>DocumentBuilder</code> has been set. (Setting a custom

      * <code>DocumentBuilder</code> overrides the internal implementation.)

      * </p>

      * <p>

      * <strong>Note:</strong> This method must be called before the

      * configuration is loaded. So the default constructor of

      * <code>XMLConfiguration</code> should be used, the location of the

      * configuration file set, <code>registerEntityId()</code> called, and

      * finally the <code>load()</code> method can be invoked.

      * </p>

      *

      * @param publicId Public identifier of the DTD to be resolved

      * @param entityURL The URL to use for reading this DTD

      * @throws IllegalArgumentException if the public ID is undefined

      * @since 1.5

      */

     public void registerEntityId(String publicId, URL entityURL)

     {

         if (publicId == null)

         {

             throw new IllegalArgumentException("Public ID must not be null!");

         }

         getRegisteredEntities().put(publicId, entityURL);

     }

     /**

      * Resolves the requested external entity. This is the default

      * implementation of the <code>EntityResolver</code> interface. It checks

      * the passed in public ID against the registered entity IDs and uses a

      * local URL if possible.

      *

      * @param publicId the public identifier of the entity being referenced

      * @param systemId the system identifier of the entity being referenced

      * @return an input source for the specified entity

      * @throws SAXException if a parsing exception occurs

      * @since 1.5

      */

     public InputSource resolveEntity(String publicId, String systemId)

             throws SAXException

     {

         // Has this system identifier been registered?

         URL entityURL = null;

         if (publicId != null)

         {

             entityURL = (URL) getRegisteredEntities().get(publicId);

         }

         if (entityURL != null)

         {

             // Obtain an InputSource for this URL. This code is based on the

             // createInputSourceFromURL() method of Commons Digester.

             try

             {

                 URLConnection connection = entityURL.openConnection();

                 connection.setUseCaches(false);

                 InputStream stream = connection.getInputStream();

                 InputSource source = new InputSource(stream);

                 source.setSystemId(entityURL.toExternalForm());

                 return source;

             }

             catch (IOException e)

             {

                 throw new SAXException(e);

             }

         }

         else

         {

             // default processing behavior

             return null;

         }

     }

     /**

      * Returns a map with the entity IDs that have been registered using the

      * <code>registerEntityId()</code> method.

      *

      * @return a map with the registered entity IDs

      */

     Map getRegisteredEntities()

     {

         return registeredEntities;

     }

     /**

      * A specialized <code>Node</code> class that is connected with an XML

      * element. Changes on a node are also performed on the associated element.

      */

     class XMLNode extends Node

     {

         /**

          * The serial version UID.

          */

         private static final long serialVersionUID = -4133988932174596562L;

         /**

          * Creates a new instance of <code>XMLNode</code> and initializes it

          * with a name and the corresponding XML element.

          *

          * @param name the node's name

          * @param elem the XML element

          */

         public XMLNode(String name, Element elem)

         {

             super(name);

             setReference(elem);

         }

         /**

          * Sets the value of this node. If this node is associated with an XML

          * element, this element will be updated, too.

          *

          * @param value the node's new value

          */

         public void setValue(Object value)

         {

             super.setValue(value);

             if (getReference() != null && document != null)

             {

                 if (isAttribute())

                 {

                     updateAttribute();

                 }

                 else

                 {

                     updateElement(value);

                 }

             }

         }

         /**

          * Updates the associated XML elements when a node is removed.

          */

         protected void removeReference()

         {

             if (getReference() != null)

             {

                 Element element = (Element) getReference();

                 if (isAttribute())

                 {

                     updateAttribute();

                 }

                 else

                 {

                     org.w3c.dom.Node parentElem = element.getParentNode();

                     if (parentElem != null)

                     {

                         parentElem.removeChild(element);

                     }

                 }

             }

         }

         /**

          * Updates the node's value if it represents an element node.

          *

          * @param value the new value

          */

         private void updateElement(Object value)

         {

             Text txtNode = findTextNodeForUpdate();

             if (value == null)

             {

                 // remove text

                 if (txtNode != null)

                 {

                     ((Element) getReference()).removeChild(txtNode);

                 }

             }

             else

             {

                 if (txtNode == null)

                 {

                     txtNode = document

                             .createTextNode(PropertyConverter.escapeDelimiters(

                                     value.toString(), getListDelimiter()));

                     if (((Element) getReference()).getFirstChild() != null)

                     {

                         ((Element) getReference()).insertBefore(txtNode,

                                 ((Element) getReference()).getFirstChild());

                     }

                     else

                     {

                         ((Element) getReference()).appendChild(txtNode);

                     }

                 }

                 else

                 {

                     txtNode.setNodeValue(PropertyConverter.escapeDelimiters(

                             value.toString(), getListDelimiter()));

                 }

             }

         }

         /**

          * Updates the node's value if it represents an attribute.

          *

          */

         private void updateAttribute()

         {

             XMLBuilderVisitor.updateAttribute(getParent(), getName(), getListDelimiter());

         }

         /**

          * Returns the only text node of this element for update. This method is

          * called when the element's text changes. Then all text nodes except

          * for the first are removed. A reference to the first is returned or

          * <b>null </b> if there is no text node at all.

          *

          * @return the first and only text node

          */

         private Text findTextNodeForUpdate()

         {

             Text result = null;

             Element elem = (Element) getReference();

             // Find all Text nodes

             NodeList children = elem.getChildNodes();

             Collection textNodes = new ArrayList();

             for (int i = 0; i < children.getLength(); i++)

             {

                 org.w3c.dom.Node nd = children.item(i);

                 if (nd instanceof Text)

                 {

                     if (result == null)

                     {

                         result = (Text) nd;

                     }

                     else

                     {

                         textNodes.add(nd);

                     }

                 }

             }

             // We don't want CDATAs

             if (result instanceof CDATASection)

             {

                 textNodes.add(result);

                 result = null;

             }

             // Remove all but the first Text node

             for (Iterator it = textNodes.iterator(); it.hasNext();)

             {

                 elem.removeChild((org.w3c.dom.Node) it.next());

             }

             return result;

         }

     }

     /**

      * A concrete <code>BuilderVisitor</code> that can construct XML

      * documents.

      */

     static class XMLBuilderVisitor extends BuilderVisitor

     {

         /** Stores the document to be constructed. */

         private Document document;

         /** Stores the list delimiter.*/

         private char listDelimiter = AbstractConfiguration.

                 getDefaultListDelimiter();

         /**

          * Creates a new instance of <code>XMLBuilderVisitor</code>

          *

          * @param doc the document to be created

          * @param listDelimiter the delimiter for attribute properties with multiple values

          */

         public XMLBuilderVisitor(Document doc, char listDelimiter)

         {

             document = doc;

             this.listDelimiter = listDelimiter;

         }

         /**

          * Processes the node hierarchy and adds new nodes to the document.

          *

          * @param rootNode the root node

          */

         public void processDocument(Node rootNode)

         {

             rootNode.visit(this, null);

         }

         /**

          * Inserts a new node. This implementation ensures that the correct

          * XML element is created and inserted between the given siblings.

          *

          * @param newNode the node to insert

          * @param parent the parent node

          * @param sibling1 the first sibling

          * @param sibling2 the second sibling

          * @return the new node

          */

         protected Object insert(Node newNode, Node parent, Node sibling1, Node sibling2)

         {

             if (newNode.isAttribute())

             {

                 updateAttribute(parent, getElement(parent), newNode.getName(), listDelimiter);

                 return null;

             }

             else

             {

                 Element elem = document.createElement(newNode.getName());

                 if (newNode.getValue() != null)

                 {

                     String txt = newNode.getValue().toString();

                     if (listDelimiter != 0)

                     {

                         txt = PropertyConverter.escapeDelimiters(txt, listDelimiter);

                     }

                     elem.appendChild(document.createTextNode(txt));

                 }

                 if (sibling2 == null)

                 {

                     getElement(parent).appendChild(elem);

                 }

                 else if (sibling1 != null)

                 {

                     getElement(parent).insertBefore(elem, getElement(sibling1).getNextSibling());

                 }

                 else

                 {

                     getElement(parent).insertBefore(elem, getElement(parent).getFirstChild());

                 }

                 return elem;

             }

         }

         /**

          * Helper method for updating the value of the specified node's

          * attribute with the given name.

          *

          * @param node the affected node

          * @param elem the element that is associated with this node

          * @param name the name of the affected attribute

          * @param listDelimiter the delimiter for attributes with multiple values

          */

         private static void updateAttribute(Node node, Element elem, String name, char listDelimiter)

         {

             if (node != null && elem != null)

             {

                 List attrs = node.getAttributes(name);

                 StringBuffer buf = new StringBuffer();

                 char delimiter = (listDelimiter != 0) ? listDelimiter : ATTR_VALUE_DELIMITER;

                 for (Iterator it = attrs.iterator(); it.hasNext();)

                 {

                     Node attr = (Node) it.next();

                     if (attr.getValue() != null)

                     {

                         if (buf.length() > 0)

                         {

                             buf.append(delimiter);

                         }

                         buf.append(PropertyConverter.escapeDelimiters(attr

                                 .getValue().toString(), delimiter));

                     }

                     attr.setReference(elem);

                 }

                 if (buf.length() < 1)

                 {

                     elem.removeAttribute(name);

                 }

                 else

                 {

                     elem.setAttribute(name, buf.toString());

                 }

             }

         }

         /**

          * Updates the value of the specified attribute of the given node.

          * Because there can be multiple child nodes representing this attribute

          * the new value is determined by iterating over all those child nodes.

          *

          * @param node the affected node

          * @param name the name of the attribute

          * @param listDelimiter the delimiter for attributes with multiple values

          */

         static void updateAttribute(Node node, String name, char listDelimiter)

         {

             if (node != null)

             {

                 updateAttribute(node, (Element) node.getReference(), name, listDelimiter);

             }

         }

         /**

          * Helper method for accessing the element of the specified node.

          *

          * @param node the node

          * @return the element of this node

          */

         private Element getElement(Node node)

         {

             // special treatement for root node of the hierarchy

             return (node.getName() != null) ? (Element) node.getReference() : document.getDocumentElement();

         }

     }

     /**

      * A special implementation of the <code>FileConfiguration</code> interface that is

      * used internally to implement the <code>FileConfiguration</code> methods

      * for <code>XMLConfiguration</code>, too.

      */

     private class XMLFileConfigurationDelegate extends FileConfigurationDelegate

     {

         public void load(InputStream in) throws ConfigurationException

         {

             XMLConfiguration.this.load(in);

         }

     }

 }