/*

  * 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.Serializable;

 import java.util.ArrayList;

 import java.util.Collection;

 import java.util.Iterator;

 import java.util.LinkedList;

 import java.util.List;

 import java.util.Set;

 import java.util.Stack;

 import org.apache.commons.collections.set.ListOrderedSet;

 import org.apache.commons.collections.iterators.SingletonIterator;

 import org.apache.commons.configuration.event.ConfigurationEvent;

 import org.apache.commons.configuration.event.ConfigurationListener;

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

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

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

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

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

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

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

 import org.apache.commons.lang.StringUtils;

 /**

  * <p>A specialized configuration class that extends its base class by the

  * ability of keeping more structure in the stored properties.</p><p>There

  * are some sources of configuration data that cannot be stored very well in a

  * <code>BaseConfiguration</code> object because then their structure is lost.

  * This is especially true for XML documents. This class can deal with such

  * structured configuration sources by storing the properties in a tree-like

  * organization.</p><p>The internal used storage form allows for a more

  * sophisticated access to single properties. As an example consider the

  * following XML document:</p><p>

  *

  * <pre>

  * <database>

  *   <tables>

  *     <table>

  *       <name>users</name>

  *       <fields>

  *         <field>

  *           <name>lid</name>

  *           <type>long</name>

  *         </field>

  *         <field>

  *           <name>usrName</name>

  *           <type>java.lang.String</type>

  *         </field>

  *        ...

  *       </fields>

  *     </table>

  *     <table>

  *       <name>documents</name>

  *       <fields>

  *         <field>

  *           <name>docid</name>

  *           <type>long</type>

  *         </field>

  *         ...

  *       </fields>

  *     </table>

  *     ...

  *   </tables>

  * </database>

  * </pre>

  *

  * </p><p>If this document is parsed and stored in a

  * <code>HierarchicalConfiguration</code> object (which can be done by one of

  * the sub classes), there are enhanced possibilities of accessing properties.

  * The keys for querying information can contain indices that select a certain

  * element if there are multiple hits.</p><p>For instance the key

  * <code>tables.table(0).name</code> can be used to find out the name of the

  * first table. In opposite <code>tables.table.name</code> would return a

  * collection with the names of all available tables. Similarly the key

  * <code>tables.table(1).fields.field.name</code> returns a collection with

  * the names of all fields of the second table. If another index is added after

  * the <code>field</code> element, a single field can be accessed:

  * <code>tables.table(1).fields.field(0).name</code>.</p><p>There is a

  * <code>getMaxIndex()</code> method that returns the maximum allowed index

  * that can be added to a given property key. This method can be used to iterate

  * over all values defined for a certain property.</p>

  * <p>Since the 1.3 release of <em>Commons Configuration</em> hierarchical

  * configurations support an <em>expression engine</em>. This expression engine

  * is responsible for evaluating the passed in configuration keys and map them

  * to the stored properties. The examples above are valid for the default

  * expression engine, which is used when a new <code>HierarchicalConfiguration</code>

  * instance is created. With the <code>setExpressionEngine()</code> method a

  * different expression engine can be set. For instance with

  * <code>{@link org.apache.commons.configuration.tree.xpath.XPathExpressionEngine}</code>

  * there is an expression engine available that supports configuration keys in

  * XPATH syntax.</p>

  * <p>In addition to the events common for all configuration classes hierarchical

  * configurations support some more events that correspond to some specific

  * methods and features:

  * <dl><dt><em>EVENT_ADD_NODES</em></dt><dd>The <code>addNodes()</code> method

  * was called; the event object contains the key, to which the nodes were added,

  * and a collection with the new nodes as value.</dd>

  * <dt><em>EVENT_CLEAR_TREE</em></dt><dd>The <code>clearTree()</code> method was

  * called; the event object stores the key of the removed sub tree.</dd>

  * <dt><em>EVENT_SUBNODE_CHANGED</em></dt><dd>A <code>SubnodeConfiguration</code>

  * that was created from this configuration has been changed. The value property

  * of the event object contains the original event object as it was sent by the

  * subnode configuration.</dd></dl></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>

  *

  * @author Oliver Heger

  * @version $Id: HierarchicalConfiguration.java 593319 2007-11-08 21:14:21Z oheger $

  */

 public class HierarchicalConfiguration extends AbstractConfiguration implements Serializable, Cloneable

 {

     /**

      * Constant for the clear tree event.

      * @since 1.3

      */

     public static final int EVENT_CLEAR_TREE = 10;

     /**

      * Constant for the add nodes event.

      * @since 1.3

      */

     public static final int EVENT_ADD_NODES = 11;

     /**

      * Constant for the subnode configuration modified event.

      * @since 1.5

      */

     public static final int EVENT_SUBNODE_CHANGED = 12;

     /**

      * The serial version UID.

      */

     private static final long serialVersionUID = 3373812230395363192L;

     /** Stores the default expression engine to be used for new objects.*/

     private static ExpressionEngine defaultExpressionEngine;

     /** Stores the root node of this configuration. This field is required for

      * backwards compatibility only.

      */

     private Node root;

     /** Stores the root configuration node.*/

     private ConfigurationNode rootNode;

     /** Stores the expression engine for this instance.*/

     private transient ExpressionEngine expressionEngine;

     /**

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

      */

     public HierarchicalConfiguration()

     {

         setRootNode(new Node());

     }

     /**

      * Creates a new instance of <code>HierarchicalConfiguration</code> and

      * copies all data contained in the specified configuration into the new

      * one.

      *

      * @param c the configuration that is to be copied (if <b>null</b>, this

      * constructor will behave like the standard constructor)

      * @since 1.4

      */

     public HierarchicalConfiguration(HierarchicalConfiguration c)

     {

         this();

         if (c != null)

         {

             CloneVisitor visitor = new CloneVisitor();

             c.getRootNode().visit(visitor);

             setRootNode(visitor.getClone());

         }

     }

     /**

      * Returns the root node of this hierarchical configuration. This method

      * exists for backwards compatibility only. New code should use the

      * <code>{@link #getRootNode()}</code> method instead, which operates on

      * the preferred data type <code>ConfigurationNode</code>.

      *

      * @return the root node

      */

     public Node getRoot()

     {

         return root;

     }

     /**

      * Sets the root node of this hierarchical configuration. This method

      * exists for backwards compatibility only. New code should use the

      * <code>{@link #setRootNode(ConfigurationNode)}</code> method instead,

      * which operates on the preferred data type <code>ConfigurationNode</code>.

      *

      * @param node the root node

      */

     public void setRoot(Node node)

     {

         if (node == null)

         {

             throw new IllegalArgumentException("Root node must not be null!");

         }

         root = node;

         rootNode = null;

     }

     /**

      * Returns the root node of this hierarchical configuration.

      *

      * @return the root node

      * @since 1.3

      */

     public ConfigurationNode getRootNode()

     {

         return (rootNode != null) ? rootNode : root;

     }

     /**

      * Sets the root node of this hierarchical configuration.

      *

      * @param rootNode the root node

      * @since 1.3

      */

     public void setRootNode(ConfigurationNode rootNode)

     {

         if (rootNode == null)

         {

             throw new IllegalArgumentException("Root node must not be null!");

         }

         this.rootNode = rootNode;

         // For backward compatibility also set the old root field.

         root = (rootNode instanceof Node) ? (Node) rootNode : new Node(rootNode);

     }

     /**

      * Returns the default expression engine.

      *

      * @return the default expression engine

      * @since 1.3

      */

     public static synchronized ExpressionEngine getDefaultExpressionEngine()

     {

         if (defaultExpressionEngine == null)

         {

             defaultExpressionEngine = new DefaultExpressionEngine();

         }

         return defaultExpressionEngine;

     }

     /**

      * Sets the default expression engine. This expression engine will be used

      * if no specific engine was set for an instance. It is shared between all

      * hierarchical configuration instances. So modifying its properties will

      * impact all instances, for which no specific engine is set.

      *

      * @param engine the new default expression engine

      * @since 1.3

      */

     public static synchronized void setDefaultExpressionEngine(ExpressionEngine engine)

     {

         if (engine == null)

         {

             throw new IllegalArgumentException(

                     "Default expression engine must not be null!");

         }

         defaultExpressionEngine = engine;

     }

     /**

      * Returns the expression engine used by this configuration. This method

      * will never return <b>null</b>; if no specific expression engine was set,

      * the default expression engine will be returned.

      *

      * @return the current expression engine

      * @since 1.3

      */

     public ExpressionEngine getExpressionEngine()

     {

         return (expressionEngine != null) ? expressionEngine

                 : getDefaultExpressionEngine();

     }

     /**

      * Sets the expression engine to be used by this configuration. All property

      * keys this configuration has to deal with will be interpreted by this

      * engine.

      *

      * @param expressionEngine the new expression engine; can be <b>null</b>,

      * then the default expression engine will be used

      * @since 1.3

      */

     public void setExpressionEngine(ExpressionEngine expressionEngine)

     {

         this.expressionEngine = expressionEngine;

     }

     /**

      * Fetches the specified property. This task is delegated to the associated

      * expression engine.

      *

      * @param key the key to be looked up

      * @return the found value

      */

     public Object getProperty(String key)

     {

         List nodes = fetchNodeList(key);

         if (nodes.size() == 0)

         {

             return null;

         }

         else

         {

             List list = new ArrayList();

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

             {

                 ConfigurationNode node = (ConfigurationNode) it.next();

                 if (node.getValue() != null)

                 {

                     list.add(node.getValue());

                 }

             }

             if (list.size() < 1)

             {

                 return null;

             }

             else

             {

                 return (list.size() == 1) ? list.get(0) : list;

             }

         }

     }

     /**

      * Adds the property with the specified key. This task will be delegated to

      * the associated <code>ExpressionEngine</code>, so the passed in key

      * must match the requirements of this implementation.

      *

      * @param key the key of the new property

      * @param obj the value of the new property

      */

     protected void addPropertyDirect(String key, Object obj)

     {

         NodeAddData data = getExpressionEngine().prepareAdd(getRootNode(), key);

         ConfigurationNode node = processNodeAddData(data);

         node.setValue(obj);

     }

     /**

      * Adds a collection of nodes at the specified position of the configuration

      * tree. This method works similar to <code>addProperty()</code>, but

      * instead of a single property a whole collection of nodes can be added -

      * and thus complete configuration sub trees. E.g. with this method it is

      * possible to add parts of another <code>HierarchicalConfiguration</code>

      * object to this object. (However be aware that a

      * <code>ConfigurationNode</code> object can only belong to a single

      * configuration. So if nodes from one configuration are directly added to

      * another one using this method, the structure of the source configuration

      * will be broken. In this case you should clone the nodes to be added

      * before calling <code>addNodes()</code>.) If the passed in key refers to

      * an existing and unique node, the new nodes are added to this node.

      * Otherwise a new node will be created at the specified position in the

      * hierarchy.

      *

      * @param key the key where the nodes are to be added; can be <b>null </b>,

      * then they are added to the root node

      * @param nodes a collection with the <code>Node</code> objects to be

      * added

      */

     public void addNodes(String key, Collection nodes)

     {

         if (nodes == null || nodes.isEmpty())

         {

             return;

         }

         fireEvent(EVENT_ADD_NODES, key, nodes, true);

         ConfigurationNode parent;

         List target = fetchNodeList(key);

         if (target.size() == 1)

         {

             // existing unique key

             parent = (ConfigurationNode) target.get(0);

         }

         else

         {

             // otherwise perform an add operation

             parent = processNodeAddData(getExpressionEngine().prepareAdd(

                     getRootNode(), key));

         }

         if (parent.isAttribute())

         {

             throw new IllegalArgumentException(

                     "Cannot add nodes to an attribute node!");

         }

         // a visitor to ensure that the nodes' references are cleared; this is

         // necessary if the nodes are moved from another configuration

         ConfigurationNodeVisitor clearRefVisitor = new ConfigurationNodeVisitorAdapter()

         {

             public void visitBeforeChildren(ConfigurationNode node)

             {

                 node.setReference(null);

             }

         };

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

         {

             ConfigurationNode child = (ConfigurationNode) it.next();

             if (child.isAttribute())

             {

                 parent.addAttribute(child);

             }

             else

             {

                 parent.addChild(child);

             }

             child.visit(clearRefVisitor);

         }

         fireEvent(EVENT_ADD_NODES, key, nodes, false);

     }

     /**

      * Checks if this configuration is empty. Empty means that there are no keys

      * with any values, though there can be some (empty) nodes.

      *

      * @return a flag if this configuration is empty

      */

     public boolean isEmpty()

     {

         return !nodeDefined(getRootNode());

     }

     /**

      * Creates a new <code>Configuration</code> object containing all keys

      * that start with the specified prefix. This implementation will return a

      * <code>HierarchicalConfiguration</code> object so that the structure of

      * the keys will be saved. The nodes selected by the prefix (it is possible

      * that multiple nodes are selected) are mapped to the root node of the

      * returned configuration, i.e. their children and attributes will become

      * children and attributes of the new root node. However a value of the root

      * node is only set if exactly one of the selected nodes contain a value (if

      * multiple nodes have a value, there is simply no way to decide how these

      * values are merged together). Note that the returned

      * <code>Configuration</code> object is not connected to its source

      * configuration: updates on the source configuration are not reflected in

      * the subset and vice versa.

      *

      * @param prefix the prefix of the keys for the subset

      * @return a new configuration object representing the selected subset

      */

     public Configuration subset(String prefix)

     {

         Collection nodes = fetchNodeList(prefix);

         if (nodes.isEmpty())

         {

             return new HierarchicalConfiguration();

         }

         final HierarchicalConfiguration parent = this;

         HierarchicalConfiguration result = new HierarchicalConfiguration()

         {

             // Override interpolate to always interpolate on the parent

             protected Object interpolate(Object value)

             {

                 return parent.interpolate(value);

             }

         };

         CloneVisitor visitor = new CloneVisitor();

         // Initialize the new root node

         Object value = null;

         int valueCount = 0;

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

         {

             ConfigurationNode nd = (ConfigurationNode) it.next();

             if (nd.getValue() != null)

             {

                 value = nd.getValue();

                 valueCount++;

             }

             nd.visit(visitor);

             for (Iterator it2 = visitor.getClone().getChildren().iterator(); it2

                     .hasNext();)

             {

                 result.getRootNode().addChild((ConfigurationNode) it2.next());

             }

             for (Iterator it2 = visitor.getClone().getAttributes().iterator(); it2

                     .hasNext();)

             {

                 result.getRootNode().addAttribute(

                         (ConfigurationNode) it2.next());

             }

         }

         // Determine the value of the new root

         if (valueCount == 1)

         {

             result.getRootNode().setValue(value);

         }

         return (result.isEmpty()) ? new HierarchicalConfiguration() : result;

     }

     /**

      * <p>

      * Returns a hierarchical subnode configuration object that wraps the

      * configuration node specified by the given key. This method provides an

      * easy means of accessing sub trees of a hierarchical configuration. In the

      * returned configuration the sub tree can directly be accessed, it becomes

      * the root node of this configuration. Because of this the passed in key

      * must select exactly one configuration node; otherwise an

      * <code>IllegalArgumentException</code> will be thrown.

      * </p>

      * <p>

      * The difference between this method and the

      * <code>{@link #subset(String)}</code> method is that

      * <code>subset()</code> supports arbitrary subsets of configuration nodes

      * while <code>configurationAt()</code> only returns a single sub tree.

      * Please refer to the documentation of the

      * <code>SubnodeConfiguration</code> class to obtain further information

      * about subnode configurations and when they should be used.

      * </p>

      * <p>

      * With the <code>supportUpdate</code> flag the behavior of the returned

      * <code>SubnodeConfiguration</code> regarding updates of its parent

      * configuration can be determined. A subnode configuration operates on the

      * same nodes as its parent, so changes at one configuration are normally

      * directly visible for the other configuration. There are however changes

      * of the parent configuration, which are not recognized by the subnode

      * configuration per default. An example for this is a reload operation (for

      * file-based configurations): Here the complete node set of the parent

      * configuration is replaced, but the subnode configuration still references

      * the old nodes. If such changes should be detected by the subnode

      * configuration, the <code>supportUpdates</code> flag must be set to

      * <b>true</b>. This causes the subnode configuration to reevaluate the key

      * used for its creation each time it is accessed. This guarantees that the

      * subnode configuration always stays in sync with its key, even if the

      * parent configuration's data significantly changes. If such a change

      * makes the key invalid - because it now no longer points to exactly one

      * node -, the subnode configuration is not reconstructed, but keeps its

      * old data. It is then quasi detached from its parent.

      * </p>

      *

      * @param key the key that selects the sub tree

      * @param supportUpdates a flag whether the returned subnode configuration

      * should be able to handle updates of its parent

      * @return a hierarchical configuration that contains this sub tree

      * @see SubnodeConfiguration

      * @since 1.5

      */

     public SubnodeConfiguration configurationAt(String key,

             boolean supportUpdates)

     {

         List nodes = fetchNodeList(key);

         if (nodes.size() != 1)

         {

             throw new IllegalArgumentException(

                     "Passed in key must select exactly one node: " + key);

         }

         return supportUpdates ? createSubnodeConfiguration(

                 (ConfigurationNode) nodes.get(0), key)

                 : createSubnodeConfiguration((ConfigurationNode) nodes.get(0));

     }

     /**

      * Returns a hierarchical subnode configuration for the node specified by

      * the given key. This is a short form for <code>configurationAt(key,

      * <b>false</b>)</code>.

      *

      * @param key the key that selects the sub tree

      * @return a hierarchical configuration that contains this sub tree

      * @see SubnodeConfiguration

      * @since 1.3

      */

     public SubnodeConfiguration configurationAt(String key)

     {

         return configurationAt(key, false);

     }

     /**

      * Returns a list of sub configurations for all configuration nodes selected

      * by the given key. This method will evaluate the passed in key (using the

      * current <code>ExpressionEngine</code>) and then create a subnode

      * configuration for each returned node (like

      * <code>{@link #configurationAt(String)}</code>}). This is especially

      * useful when dealing with list-like structures. As an example consider the

      * configuration that contains data about database tables and their fields.

      * If you need access to all fields of a certain table, you can simply do

      *

      * <pre>

      * List fields = config.configurationsAt("tables.table(0).fields.field");

      * for(Iterator it = fields.iterator(); it.hasNext();)

      * {

      *     HierarchicalConfiguration sub = (HierarchicalConfiguration) it.next();

      *     // now the children and attributes of the field node can be

      *     // directly accessed

      *     String fieldName = sub.getString("name");

      *     String fieldType = sub.getString("type");

      *     ...

      * </pre>

      *

      * @param key the key for selecting the desired nodes

      * @return a list with hierarchical configuration objects; each

      * configuration represents one of the nodes selected by the passed in key

      * @since 1.3

      */

     public List configurationsAt(String key)

     {

         List nodes = fetchNodeList(key);

         List configs = new ArrayList(nodes.size());

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

         {

             configs.add(createSubnodeConfiguration((ConfigurationNode) it.next()));

         }

         return configs;

     }

     /**

      * Creates a subnode configuration for the specified node. This method is

      * called by <code>configurationAt()</code> and

      * <code>configurationsAt()</code>.

      *

      * @param node the node, for which a subnode configuration is to be created

      * @return the configuration for the given node

      * @since 1.3

      */

     protected SubnodeConfiguration createSubnodeConfiguration(ConfigurationNode node)

     {

         SubnodeConfiguration result = new SubnodeConfiguration(this, node);

         registerSubnodeConfiguration(result);

         return result;

     }

     /**

      * Creates a new subnode configuration for the specified node and sets its

      * construction key. A subnode configuration created this way will be aware

      * of structural changes of its parent.

      *

      * @param node the node, for which a subnode configuration is to be created

      * @param subnodeKey the key used to construct the configuration

      * @return the configuration for the given node

      * @since 1.5

      */

     protected SubnodeConfiguration createSubnodeConfiguration(

             ConfigurationNode node, String subnodeKey)

     {

         SubnodeConfiguration result = createSubnodeConfiguration(node);

         result.setSubnodeKey(subnodeKey);

         return result;

     }

     /**

      * This method is always called when a subnode configuration created from

      * this configuration has been modified. This implementation transforms the

      * received event into an event of type <code>EVENT_SUBNODE_CHANGED</code>

      * and notifies the registered listeners.

      *

      * @param event the event describing the change

      * @since 1.5

      */

     protected void subnodeConfigurationChanged(ConfigurationEvent event)

     {

         fireEvent(EVENT_SUBNODE_CHANGED, null, event, event.isBeforeUpdate());

     }

     /**

      * Registers this instance at the given subnode configuration. This

      * implementation will register a change listener, so that modifications of

      * the subnode configuration can be tracked.

      *

      * @param config the subnode configuration

      * @since 1.5

      */

     void registerSubnodeConfiguration(SubnodeConfiguration config)

     {

         config.addConfigurationListener(new ConfigurationListener()

         {

             public void configurationChanged(ConfigurationEvent event)

             {

                 subnodeConfigurationChanged(event);

             }

         });

     }

     /**

      * Checks if the specified key is contained in this configuration. Note that

      * for this configuration the term "contained" means that the key

      * has an associated value. If there is a node for this key that has no

      * value but children (either defined or undefined), this method will still

      * return <b>false </b>.

      *

      * @param key the key to be chekced

      * @return a flag if this key is contained in this configuration

      */

     public boolean containsKey(String key)

     {

         return getProperty(key) != null;

     }

     /**

      * Sets the value of the specified property.

      *

      * @param key the key of the property to set

      * @param value the new value of this property

      */

     public void setProperty(String key, Object value)

     {

         fireEvent(EVENT_SET_PROPERTY, key, value, true);

         // Update the existing nodes for this property

         Iterator itNodes = fetchNodeList(key).iterator();

         Iterator itValues;

         if (!isDelimiterParsingDisabled())

         {

             itValues = PropertyConverter.toIterator(value, getListDelimiter());

         }

         else

         {

             itValues = new SingletonIterator(value);

         }

         while (itNodes.hasNext() && itValues.hasNext())

         {

             ((ConfigurationNode) itNodes.next()).setValue(itValues.next());

         }

         // Add additional nodes if necessary

         while (itValues.hasNext())

         {

             addPropertyDirect(key, itValues.next());

         }

         // Remove remaining nodes

         while (itNodes.hasNext())

         {

             clearNode((ConfigurationNode) itNodes.next());

         }

         fireEvent(EVENT_SET_PROPERTY, key, value, false);

     }

     /**

      * Removes all values of the property with the given name and of keys that

      * start with this name. So if there is a property with the key

      * "foo" and a property with the key "foo.bar", a call

      * of <code>clearTree("foo")</code> would remove both properties.

      *

      * @param key the key of the property to be removed

      */

     public void clearTree(String key)

     {

         fireEvent(EVENT_CLEAR_TREE, key, null, true);

         List nodes = fetchNodeList(key);

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

         {

             removeNode((ConfigurationNode) it.next());

         }

         fireEvent(EVENT_CLEAR_TREE, key, nodes, false);

     }

     /**

      * Removes the property with the given key. Properties with names that start

      * with the given key (i.e. properties below the specified key in the

      * hierarchy) won't be affected.

      *

      * @param key the key of the property to be removed

      */

     public void clearProperty(String key)

     {

         fireEvent(EVENT_CLEAR_PROPERTY, key, null, true);

         List nodes = fetchNodeList(key);

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

         {

             clearNode((ConfigurationNode) it.next());

         }

         fireEvent(EVENT_CLEAR_PROPERTY, key, null, false);

     }

     /**

      * Returns an iterator with all keys defined in this configuration.

      * Note that the keys returned by this method will not contain any

      * indices. This means that some structure will be lost.</p>

      *

      * @return an iterator with the defined keys in this configuration

      */

     public Iterator getKeys()

     {

         DefinedKeysVisitor visitor = new DefinedKeysVisitor();

         getRootNode().visit(visitor);

         return visitor.getKeyList().iterator();

     }

     /**

      * Returns an iterator with all keys defined in this configuration that

      * start with the given prefix. The returned keys will not contain any

      * indices.

      *

      * @param prefix the prefix of the keys to start with

      * @return an iterator with the found keys

      */

     public Iterator getKeys(String prefix)

     {

         DefinedKeysVisitor visitor = new DefinedKeysVisitor(prefix);

         List nodes = fetchNodeList(prefix);

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

         {

             ConfigurationNode node = (ConfigurationNode) itNodes.next();

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

             {

                 ((ConfigurationNode) it.next()).visit(visitor);

             }

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

             {

                 ((ConfigurationNode) it.next()).visit(visitor);

             }

         }

         return visitor.getKeyList().iterator();

     }

     /**

      * Returns the maximum defined index for the given key. This is useful if

      * there are multiple values for this key. They can then be addressed

      * separately by specifying indices from 0 to the return value of this

      * method.

      *

      * @param key the key to be checked

      * @return the maximum defined index for this key

      */

     public int getMaxIndex(String key)

     {

         return fetchNodeList(key).size() - 1;

     }

     /**

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

      * copies of all nodes in the same structure. Registered event listeners

      * won't be cloned; so they are not registered at the returned copy.

      *

      * @return the copy

      * @since 1.2

      */

     public Object clone()

     {

         try

         {

             HierarchicalConfiguration copy = (HierarchicalConfiguration) super

                     .clone();

             // clone the nodes, too

             CloneVisitor v = new CloneVisitor();

             getRootNode().visit(v);

             copy.setRootNode(v.getClone());

             return copy;

         }

         catch (CloneNotSupportedException cex)

         {

             // should not happen

             throw new ConfigurationRuntimeException(cex);

         }

     }

     /**

      * Returns a configuration with the same content as this configuration, but

      * with all variables replaced by their actual values. This implementation

      * is specific for hierarchical configurations. It clones the current

      * configuration and runs a specialized visitor on the clone, which performs

      * interpolation on the single configuration nodes.

      *

      * @return a configuration with all variables interpolated

      * @since 1.5

      */

     public Configuration interpolatedConfiguration()

     {

         HierarchicalConfiguration c = (HierarchicalConfiguration) clone();

         c.getRootNode().visit(new ConfigurationNodeVisitorAdapter()

         {

             public void visitAfterChildren(ConfigurationNode node)

             {

                 node.setValue(interpolate(node.getValue()));

             }

         });

         return c;

     }

     /**

      * Helper method for fetching a list of all nodes that are addressed by the

      * specified key.

      *

      * @param key the key

      * @return a list with all affected nodes (never <b>null </b>)

      */

     protected List fetchNodeList(String key)

     {

         return getExpressionEngine().query(getRootNode(), key);

     }

     /**

      * Recursive helper method for fetching a property. This method processes

      * all facets of a configuration key, traverses the tree of properties and

      * fetches the the nodes of all matching properties.

      *

      * @param keyPart the configuration key iterator

      * @param node the actual node

      * @param nodes here the found nodes are stored

      * @deprecated Property keys are now evaluated by the expression engine

      * associated with the configuration; this method will no longer be called.

      * If you want to modify the way properties are looked up, consider

      * implementing you own <code>ExpressionEngine</code> implementation.

      */

     protected void findPropertyNodes(ConfigurationKey.KeyIterator keyPart,

             Node node, Collection nodes)

     {

     }

     /**

      * Checks if the specified node is defined.

      *

      * @param node the node to be checked

      * @return a flag if this node is defined

      * @deprecated Use the method <code>{@link #nodeDefined(ConfigurationNode)}</code>

      * instead.

      */

     protected boolean nodeDefined(Node node)

     {

         return nodeDefined((ConfigurationNode) node);

     }

     /**

      * Checks if the specified node is defined.

      *

      * @param node the node to be checked

      * @return a flag if this node is defined

      */

     protected boolean nodeDefined(ConfigurationNode node)

     {

         DefinedVisitor visitor = new DefinedVisitor();

         node.visit(visitor);

         return visitor.isDefined();

     }

     /**

      * Removes the specified node from this configuration. This method ensures

      * that parent nodes that become undefined by this operation are also

      * removed.

      *

      * @param node the node to be removed

      * @deprecated Use the method <code>{@link #removeNode(ConfigurationNode)}</code>

      * instead.

      */

     protected void removeNode(Node node)

     {

         removeNode((ConfigurationNode) node);

     }

     /**

      * Removes the specified node from this configuration. This method ensures

      * that parent nodes that become undefined by this operation are also

      * removed.

      *

      * @param node the node to be removed

      */

     protected void removeNode(ConfigurationNode node)

     {

         ConfigurationNode parent = node.getParentNode();

         if (parent != null)

         {

             parent.removeChild(node);

             if (!nodeDefined(parent))

             {

                 removeNode(parent);

             }

         }

     }

     /**

      * Clears the value of the specified node. If the node becomes undefined by

      * this operation, it is removed from the hierarchy.

      *

      * @param node the node to be cleared

      * @deprecated Use the method <code>{@link #clearNode(ConfigurationNode)}</code>

      * instead

      */

     protected void clearNode(Node node)

     {

         clearNode((ConfigurationNode) node);

     }

     /**

      * Clears the value of the specified node. If the node becomes undefined by

      * this operation, it is removed from the hierarchy.

      *

      * @param node the node to be cleared

      */

     protected void clearNode(ConfigurationNode node)

     {

         node.setValue(null);

         if (!nodeDefined(node))

         {

             removeNode(node);

         }

     }

     /**

      * Returns a reference to the parent node of an add operation. Nodes for new

      * properties can be added as children of this node. If the path for the

      * specified key does not exist so far, it is created now.

      *

      * @param keyIt the iterator for the key of the new property

      * @param startNode the node to start the search with

      * @return the parent node for the add operation

      * @deprecated Adding new properties is now to a major part delegated to the

      * <code>ExpressionEngine</code> associated with this configuration instance.

      * This method will no longer be called. Developers who want to modify the

      * process of adding new properties should consider implementing their own

      * expression engine.

      */

     protected Node fetchAddNode(ConfigurationKey.KeyIterator keyIt, Node startNode)

     {

         return null;

     }

     /**

      * Finds the last existing node for an add operation. This method traverses

      * the configuration tree along the specified key. The last existing node on

      * this path is returned.

      *

      * @param keyIt the key iterator

      * @param node the actual node

      * @return the last existing node on the given path

      * @deprecated Adding new properties is now to a major part delegated to the

      * <code>ExpressionEngine</code> associated with this configuration instance.

      * This method will no longer be called. Developers who want to modify the

      * process of adding new properties should consider implementing their own

      * expression engine.

      */

     protected Node findLastPathNode(ConfigurationKey.KeyIterator keyIt, Node node)

     {

         return null;

     }

     /**

      * Creates the missing nodes for adding a new property. This method ensures

      * that there are corresponding nodes for all components of the specified

      * configuration key.

      *

      * @param keyIt the key iterator

      * @param root the base node of the path to be created

      * @return the last node of the path

      * @deprecated Adding new properties is now to a major part delegated to the

      * <code>ExpressionEngine</code> associated with this configuration instance.

      * This method will no longer be called. Developers who want to modify the

      * process of adding new properties should consider implementing their own

      * expression engine.

      */

     protected Node createAddPath(ConfigurationKey.KeyIterator keyIt, Node root)

     {

         return null;

     }

     /**

      * Creates a new <code>Node</code> object with the specified name. This

      * method can be overloaded in derived classes if a specific node type is

      * needed. This base implementation always returns a new object of the

      * <code>Node</code> class.

      *

      * @param name the name of the new node

      * @return the new node

      */

     protected Node createNode(String name)

     {

         return new Node(name);

     }

     /**

      * Helper method for processing a node add data object obtained from the

      * expression engine. This method will create all new nodes.

      *

      * @param data the data object

      * @return the new node

      * @since 1.3

      */

     private ConfigurationNode processNodeAddData(NodeAddData data)

     {

         ConfigurationNode node = data.getParent();

         // Create missing nodes on the path

         for (Iterator it = data.getPathNodes().iterator(); it.hasNext();)

         {

             ConfigurationNode child = createNode((String) it.next());

             node.addChild(child);

             node = child;

         }

         // Add new target node

         ConfigurationNode child = createNode(data.getNewNodeName());

         if (data.isAttribute())

         {

             node.addAttribute(child);

         }

         else

         {

             node.addChild(child);

         }

         return child;

     }

     /**

      * Clears all reference fields in a node structure. A configuration node can

      * store a so-called "reference". The meaning of this data is

      * determined by a concrete sub class. Typically such references are

      * specific for a configuration instance. If this instance is cloned or

      * copied, they must be cleared. This can be done using this method.

      *

      * @param node the root node of the node hierarchy, in which the references

      * are to be cleared

      * @since 1.4

      */

     protected static void clearReferences(ConfigurationNode node)

     {

         node.visit(new ConfigurationNodeVisitorAdapter()

         {

             public void visitBeforeChildren(ConfigurationNode node)

             {

                 node.setReference(null);

             }

         });

     }

     /**

      * A data class for storing (hierarchical) property information. A property

      * can have a value and an arbitrary number of child properties. From

      * version 1.3 on this class is only a thin wrapper over the

      * <code>{@link org.apache.commons.configuration.tree.DefaultConfigurationNode DefaultconfigurationNode}</code>

      * class that exists mainly for the purpose of backwards compatibility.

      */

     public static class Node extends DefaultConfigurationNode implements Serializable

     {

         /**

          * The serial version UID.

          */

         private static final long serialVersionUID = -6357500633536941775L;

         /**

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

          */

         public Node()

         {

             super();

         }

         /**

          * Creates a new instance of <code>Node</code> and sets the name.

          *

          * @param name the node's name

          */

         public Node(String name)

         {

             super(name);

         }

         /**

          * Creates a new instance of <code>Node</code> and sets the name and the value.

          *

          * @param name the node's name

          * @param value the value

          */

         public Node(String name, Object value)

         {

             super(name, value);

         }

         /**

          * Creates a new instance of <code>Node</code> based on the given

          * source node. All properties of the source node, including its

          * children and attributes, will be copied.

          *

          * @param src the node to be copied

          */

         public Node(ConfigurationNode src)

         {

             this(src.getName(), src.getValue());

             setReference(src.getReference());

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

             {

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

             }

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

             {

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

             }

         }

         /**

          * Returns the parent of this node.

          *

          * @return this node's parent (can be <b>null</b>)

          */

         public Node getParent()

         {

             return (Node) getParentNode();

         }

         /**

          * Sets the parent of this node.

          *

          * @param node the parent node

          */

         public void setParent(Node node)

         {

             setParentNode(node);

         }

         /**

          * Adds the given node to the children of this node.

          *

          * @param node the child to be added

          */

         public void addChild(Node node)

         {

             addChild((ConfigurationNode) node);

         }

         /**

          * Returns a flag whether this node has child elements.

          *

          * @return <b>true</b> if there is a child node, <b>false</b> otherwise

          */

         public boolean hasChildren()

         {

             return getChildrenCount() > 0 || getAttributeCount() > 0;

         }

         /**

          * Removes the specified child from this node.

          *

          * @param child the child node to be removed

          * @return a flag if the child could be found

          */

         public boolean remove(Node child)

         {

             return child.isAttribute() ? removeAttribute(child) : removeChild(child);

         }

         /**

          * Removes all children with the given name.

          *

          * @param name the name of the children to be removed

          * @return a flag if children with this name existed

          */

         public boolean remove(String name)

         {

             boolean childrenRemoved = removeChild(name);

             boolean attrsRemoved = removeAttribute(name);

             return childrenRemoved || attrsRemoved;

         }

         /**

          * A generic method for traversing this node and all of its children.

          * This method sends the passed in visitor to this node and all of its

          * children.

          *

          * @param visitor the visitor

          * @param key here a configuration key with the name of the root node of

          * the iteration can be passed; if this key is not <b>null </b>, the

          * full pathes to the visited nodes are builded and passed to the

          * visitor's <code>visit()</code> methods

          */

         public void visit(NodeVisitor visitor, ConfigurationKey key)

         {

             int length = 0;

             if (key != null)

             {

                 length = key.length();

                 if (getName() != null)

                 {

                     key

                             .append(StringUtils

                                     .replace(

                                             isAttribute() ? ConfigurationKey

                                                     .constructAttributeKey(getName())

                                                     : getName(),

                                             String

                                                     .valueOf(ConfigurationKey.PROPERTY_DELIMITER),

                                             ConfigurationKey.ESCAPED_DELIMITER));

                 }

             }

             visitor.visitBeforeChildren(this, key);

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

                     && !visitor.terminate();)

             {

                 ((Node) it.next()).visit(visitor, key);

             }

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

                     && !visitor.terminate();)

             {

                 ((Node) it.next()).visit(visitor, key);

             }

             if (key != null)

             {

                 key.setLength(length);