/**
         * Returns a list with the child nodes of this node.
         * @return a list with the children (can be empty, but never
         * <b>null</b>)
         */
        public Container getChildren()
        {
            Container result = new Container();

            if (children != null)
            {
                for (Iterator it = children.values().iterator(); it.hasNext();)
                {
                    addContainer(result, (Collection) it.next());
                } /* for */
            } /* if */

            return result;
        }

        /**
         * Returns a list with this node's children with the given name.
         * @param name the name of the children
         * @return a list with all chidren with this name; may be empty, but
         * never <b>null</b>
         */
        public Container getChildren(String name)
        {
            if (name == null || children == null)
            {
                return getChildren();
            } /* if */

            Container cont = new Container();
            List c = (List) children.get(name);
            if (c != null)
            {
                addContainer(cont, c);
            } /* if */

            return cont;
        }

        /**
         * 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)
        {
            if (children == null)
            {
                return false;
            } /* if */

            List c = (List) children.get(child.getName());
            if (c == null)
            {
                return false;
            } /* if */

            else
            {
                if (c.remove(child))
                {
                    if (c.isEmpty())
                    {
                        children.remove(child.getName());
                    } /* if */
                    return true;
                } /* if */
                else
                {
                    return false;
                } /* else */
            } /* else */
        }

        /**
         * 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)
        {
            if (children == null)
            {
                return false;
            } /* if */

            return children.remove(name) != null;
        }

        /**
         * Removes all children of this node.
         */
        public void removeChildren()
        {
            children = null;
        }

        /**
         * 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(getName());
                } /* if */
            } /* if */

            visitor.visitBeforeChildren(this, key);

            if (children != null)
            {
                for (Iterator it = children.values().iterator();
                    it.hasNext() && !visitor.terminate();
                    )
                {
                    Collection col = (Collection) it.next();
                    for (Iterator it2 = col.iterator();
                        it2.hasNext() && !visitor.terminate();
                        )
                    {
                        ((Node) it2.next()).visit(visitor, key);
                    } /* for */
                } /* for */
            } /* if */

            if (key != null)
            {
                key.setLength(length);
            } /* if */
            visitor.visitAfterChildren(this, key);
        }

        /**
         * Creates a copy of this object. This is not a deep copy, the children
         * are not cloned.
         * @return a copy of this object
         */
        protected Object clone()
        {
            try
            {
                return super.clone();
            } /* try */
            catch (CloneNotSupportedException cex)
            {
                return null; // should not happen
            } /* catch */
        }
    }

    /**
     * <p>Definition of a visitor class for traversing a node and all of its
     * children.</p>
     * <p>This class defines the interface of a visitor for <code>Node</code>
     * objects and provides a default implementation. The method
     * <code>visit()</code> of <code>Node</code> implements a generic
     * iteration algorithm based on the <em>Visitor</em> pattern. By
     * providing different implementations of visitors it is possible to
     * collect different data during the iteration process.</p>
     *
     * @author <a href="mailto:oliver.heger@t-online.de">Oliver Heger</a>
     */
    public static class NodeVisitor
    {
        /**
         * Visits the specified node. This method is called during iteration
         * for each node before its children have been visited.
         * @param node the actual node
         * @param key the key of this node (may be <b>null</b>)
         */
        public void visitBeforeChildren(Node node, ConfigurationKey key)
        {
        }

        /**
         * Visits the specified node after its children have been processed.
         * This gives a visitor the opportunity of collecting additional data
         * after the child nodes have been visited.
         * @param node the node to be visited
         * @param key the key of this node (may be <b>null</b>)
         */
        public void visitAfterChildren(Node node, ConfigurationKey key)
        {
        }

        /**
         * Returns a flag that indicates if iteration should be stopped. This
         * method is called after each visited node. It can be useful for
         * visitors that search a specific node. If this node is found, the
         * whole process can be stopped. This base implementation always
         * returns <b>false</b>.
         * @return a flag if iteration should be stopped
         */
        public boolean terminate()
        {
            return false;
        }
    }

    /**
     * A specialized visitor that checks if a node is defined.
     * &quot;Defined&quot; in this terms means that the node or at least one
     * of its sub nodes is associated with a value.
     *
     * @author <a href="mailto:oliver.heger@t-online.de">Oliver Heger</a>
     */
    static class DefinedVisitor extends NodeVisitor
    {
        /** Stores the defined flag.*/
        private boolean defined;

        /**
         * Checks if iteration should be stopped. This can be done if the first
         * defined node is found.
         * @return a flag if iteration should be stopped
         */
        public boolean terminate()
        {
            return isDefined();
        }

        /**
         * Visits the node. Checks if a value is defined.
         * @param node the actual node
         * @param key the key of this node
         */
        public void visitBeforeChildren(Node node, ConfigurationKey key)
        {
            defined = node.getValue() != null;
        }

        /**
         * Returns the defined flag.
         * @return the defined flag
         */
        public boolean isDefined()
        {
            return defined;
        }
    }

    /**
     * A specialized visitor that fills a list with keys that are defined in
     * a node hierarchy.
     *
     * @author <a href="mailto:oliver.heger@t-online.de">Oliver Heger</a>
     */
    static class DefinedKeysVisitor extends NodeVisitor
    {
        /** Stores the list to be filled.*/
        private Set keyList;

        /**
         * Default constructor.
         */
        public DefinedKeysVisitor()
        {
            keyList = new HashSet();
        }

        /**
         * Returns the list with all defined keys.
         * @return the list with the defined keys
         */
        public Set getKeyList()
        {
            return keyList;
        }

        /**
         * Visits the specified node. If this node has a value, its key is
         * added to the internal list.
         * @param node the node to be visited
         * @param key the key of this node
         */
        public void visitBeforeChildren(Node node, ConfigurationKey key)
        {
            if (node.getValue() != null && key != null)
            {
                keyList.add(key.toString());
            } /* if */
        }
    }

    /**
     * A specialized visitor that is able to create a deep copy of a node
     * hierarchy.
     *
     * @author <a href="mailto:oliver.heger@t-online.de">Oliver Heger</a>
     */
    static class CloneVisitor extends NodeVisitor
    {
        /** A stack with the actual object to be copied.*/
        private Stack copyStack;

        /** Stores the result of the clone process.*/
        private Node result;

        /**
         * Creates a new instance of <code>CloneVisitor</code>.
         */
        public CloneVisitor()
        {
            copyStack = new Stack();
        }

        /**
         * Visits the specified node after its children have been processed.
         * @param node the node
         * @param key the key of this node
         */
        public void visitAfterChildren(Node node, ConfigurationKey key)
        {
            copyStack.pop();
            if (copyStack.isEmpty())
            {
                result = node;
            } /* if */
        }

        /**
         * Visits and copies the specified node.
         * @param node the node
         * @param key the key of this node
         */
        public void visitBeforeChildren(Node node, ConfigurationKey key)
        {
            Node copy = (Node) node.clone();
            copy.removeChildren();

            if (!copyStack.isEmpty())
            {
                ((Node) copyStack.peek()).addChild(copy);
            } /* if */

            copyStack.push(copy);
        }

        /**
         * Returns the result of the clone process. This is the root node of
         * the cloned node hierarchy.
         * @return the cloned root node
         */
        public Node getClone()
        {
            return result;
        }
    }
}