Java tutorial
/* * 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.iterators.SingletonIterator; import org.apache.commons.collections.set.ListOrderedSet; 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.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 722238 2008-12-01 21:28:31Z 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() { if (root == null && rootNode != null) { // Dynamically create a snapshot of the root node return new Node(rootNode); } 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 : null; } /** * 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!"); } for (Iterator it = nodes.iterator(); it.hasNext();) { ConfigurationNode child = (ConfigurationNode) it.next(); if (child.isAttribute()) { parent.addAttribute(child); } else { parent.addChild(child); } clearReferences(child); } 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); if (containsKey(prefix)) { // explicitly add the prefix visitor.getKeyList().add(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();) { ConfigurationNode nd = (ConfigurationNode) it.next(); // Don't change the parent node ConfigurationNode parent = nd.getParentNode(); addChild(nd); nd.setParentNode(parent); } for (Iterator it = src.getAttributes().iterator(); it.hasNext();) { ConfigurationNode nd = (ConfigurationNode) it.next(); // Don't change the parent node ConfigurationNode parent = nd.getParentNode(); addAttribute(nd); nd.setParentNode(parent); } } /** * 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); } visitor.visitAfterChildren(this, key); } } /** * <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> * */ 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. * "Defined" in this terms means that the node or at least one of * its sub nodes is associated with a value. * */ static class DefinedVisitor extends ConfigurationNodeVisitorAdapter { /** 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 */ public void visitBeforeChildren(ConfigurationNode node) { 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. */ class DefinedKeysVisitor extends ConfigurationNodeVisitorAdapter { /** Stores the list to be filled. */ private Set keyList; /** A stack with the keys of the already processed nodes. */ private Stack parentKeys; /** * Default constructor. */ public DefinedKeysVisitor() { keyList = new ListOrderedSet(); parentKeys = new Stack(); } /** * Creates a new <code>DefinedKeysVisitor</code> instance and sets the * prefix for the keys to fetch. * * @param prefix the prefix */ public DefinedKeysVisitor(String prefix) { this(); parentKeys.push(prefix); } /** * Returns the list with all defined keys. * * @return the list with the defined keys */ public Set getKeyList() { return keyList; } /** * Visits the node after its children has been processed. Removes this * node's key from the stack. * * @param node the node */ public void visitAfterChildren(ConfigurationNode node) { parentKeys.pop(); } /** * 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 */ public void visitBeforeChildren(ConfigurationNode node) { String parentKey = parentKeys.isEmpty() ? null : (String) parentKeys.peek(); String key = getExpressionEngine().nodeKey(node, parentKey); parentKeys.push(key); if (node.getValue() != null) { keyList.add(key); } } } /** * A specialized visitor that is able to create a deep copy of a node * hierarchy. */ static class CloneVisitor extends ConfigurationNodeVisitorAdapter { /** A stack with the actual object to be copied. */ private Stack copyStack; /** Stores the result of the clone process. */ private ConfigurationNode 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 */ public void visitAfterChildren(ConfigurationNode node) { ConfigurationNode copy = (ConfigurationNode) copyStack.pop(); if (copyStack.isEmpty()) { result = copy; } } /** * Visits and copies the specified node. * * @param node the node */ public void visitBeforeChildren(ConfigurationNode node) { ConfigurationNode copy = (ConfigurationNode) node.clone(); copy.setParentNode(null); if (!copyStack.isEmpty()) { if (node.isAttribute()) { ((ConfigurationNode) copyStack.peek()).addAttribute(copy); } else { ((ConfigurationNode) copyStack.peek()).addChild(copy); } } 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 ConfigurationNode getClone() { return result; } } /** * A specialized visitor base class that can be used for storing the tree of * configuration nodes. The basic idea is that each node can be associated * with a reference object. This reference object has a concrete meaning in * a derived class, e.g. an entry in a JNDI context or an XML element. When * the configuration tree is set up, the <code>load()</code> method is * responsible for setting the reference objects. When the configuration * tree is later modified, new nodes do not have a defined reference object. * This visitor class processes all nodes and finds the ones without a * defined reference object. For those nodes the <code>insert()</code> * method is called, which must be defined in concrete sub classes. This * method can perform all steps to integrate the new node into the original * structure. * */ protected abstract static class BuilderVisitor extends NodeVisitor { /** * Visits the specified node before its children have been traversed. * * @param node the node to visit * @param key the current key */ public void visitBeforeChildren(Node node, ConfigurationKey key) { Collection subNodes = new LinkedList(node.getChildren()); subNodes.addAll(node.getAttributes()); Iterator children = subNodes.iterator(); Node sibling1 = null; Node nd = null; while (children.hasNext()) { // find the next new node do { sibling1 = nd; nd = (Node) children.next(); } while (nd.getReference() != null && children.hasNext()); if (nd.getReference() == null) { // find all following new nodes List newNodes = new LinkedList(); newNodes.add(nd); while (children.hasNext()) { nd = (Node) children.next(); if (nd.getReference() == null) { newNodes.add(nd); } else { break; } } // Insert all new nodes Node sibling2 = (nd.getReference() == null) ? null : nd; for (Iterator it = newNodes.iterator(); it.hasNext();) { Node insertNode = (Node) it.next(); if (insertNode.getReference() == null) { Object ref = insert(insertNode, node, sibling1, sibling2); if (ref != null) { insertNode.setReference(ref); } sibling1 = insertNode; } } } } } /** * Inserts a new node into the structure constructed by this builder. * This method is called for each node that has been added to the * configuration tree after the configuration has been loaded from its * source. These new nodes have to be inserted into the original * structure. The passed in nodes define the position of the node to be * inserted: its parent and the siblings between to insert. The return * value is interpreted as the new reference of the affected * <code>Node</code> object; if it is not <b>null </b>, it is passed * to the node's <code>setReference()</code> method. * * @param newNode the node to be inserted * @param parent the parent node * @param sibling1 the sibling after which the node is to be inserted; * can be <b>null </b> if the new node is going to be the first child * node * @param sibling2 the sibling before which the node is to be inserted; * can be <b>null </b> if the new node is going to be the last child * node * @return the reference object for the node to be inserted */ protected abstract Object insert(Node newNode, Node parent, Node sibling1, Node sibling2); } }