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.util.ArrayList; import java.util.Collections; import java.util.Iterator; import java.util.List; import org.apache.commons.configuration.tree.ConfigurationNode; /** * <p> * A specialized hierarchical configuration class that wraps a single node of * its parent configuration. * </p> * <p> * Configurations of this type are initialized with a parent configuration and a * configuration node of this configuration. This node becomes the root node of * the subnode configuration. All property accessor methods are evaluated * relative to this root node. A good use case for a * <code>SubnodeConfiguration</code> is when multiple properties from a * specific sub tree of the whole configuration need to be accessed. Then a * <code>SubnodeConfiguration</code> can be created with the parent node of * the affected sub tree as root node. This allows for simpler property keys and * is also more efficient. * </p> * <p> * A subnode configuration and its parent configuration operate on the same * hierarchy of configuration nodes. So if modifications are performed at the * subnode configuration, these changes are immideately visible in the parent * configuration. Analogously will updates of the parent configuration affect * the subnode configuration if the sub tree spanned by the subnode * configuration's root node is involved. * </p> * <p> * There are however changes at the parent configuration, which cause the * subnode configuration to become detached. An example for such a change is a * reload operation of a file-based configuration, which replaces all nodes of * the parent configuration. The subnode configuration per default still * references the old nodes. Another example are list structures: a subnode * configuration can be created to point on the <em>i</em>th element of the * list. Now list elements can be added or removed, so that the list elements' * indices change. In such a scenario the subnode configuration would always * point to the same list element, regardless of its current index. * </p> * <p> * To solve these problems and make a subnode configuration aware of * such structural changes of its parent, it is possible to associate a * subnode configuration with a configuration key. This can be done by calling * the <code>setSubnodeKey()</code> method. If here a key is set, the subnode * configuration will evaluate it on each access, thus ensuring that it is * always in sync with its parent. In this mode the subnode configuration really * behaves like a live-view on its parent. The price for this is a decreased * performance because now an additional evaluation has to be performed on each * property access. So this mode should only be used if necessary; if for * instance a subnode configuration is only used for a temporary convenient * access to a complex configuration, there is no need to make it aware for * structural changes of its parent. If a subnode configuration is created * using the <code>{@link HierarchicalConfiguration#configurationAt(String, boolean) * configurationAt()}</code> method of <code>HierarchicalConfiguration</code> * (which should be the preferred way), with an additional boolean parameter it * can be specified whether the resulting subnode configuration should be * aware of structural changes or not. Then the configuration key will be * automatically set. * </p> * <p> * <em>Note:</em> At the moment support for creating a subnode configuration * that is aware of structural changes of its parent from another subnode * configuration (a "sub subnode configuration") is limited. This only works if * <ol><li>the subnode configuration that serves as the parent for the new * subnode configuration is itself associated with a configuration key and</li> * <li>the key passed in to create the new subnode configuration is not too * complex (if configuration keys are used that contain indices, a corresponding * key that is valid from the parent configuration's point of view cannot be * constructed).</li></ol> * </p> * <p> * When a subnode configuration is created, it inherits the settings of its * parent configuration, e.g. some flags like the * <code>throwExceptionOnMissing</code> flag or the settings for handling list * delimiters) or the expression engine. If these settings are changed later in * either the subnode or the parent configuration, the changes are not visible * for each other. So you could create a subnode configuration, change its * expression engine without affecting the parent configuration. * </p> * <p> * From its purpose this class is quite similar to * <code>{@link SubsetConfiguration}</code>. The difference is that a subset * configuration of a hierarchical configuration may combine multiple * configuration nodes from different sub trees of the configuration, while all * nodes in a subnode configuration belong to the same sub tree. If an * application can live with this limitation, it is recommended to use this * class instead of <code>SubsetConfiguration</code> because creating a subset * configuration is more expensive than creating a subnode configuration. * </p> * * @since 1.3 * @author Oliver Heger * @version $Id: SubnodeConfiguration.java 531254 2007-04-22 18:54:57Z oheger $ */ public class SubnodeConfiguration extends HierarchicalConfiguration { /** * The serial version UID. */ private static final long serialVersionUID = 3105734147019386480L; /** Stores the parent configuration. */ private HierarchicalConfiguration parent; /** Stores the key that was used to construct this configuration.*/ private String subnodeKey; /** * Creates a new instance of <code>SubnodeConfiguration</code> and * initializes it with the parent configuration and the new root node. * * @param parent the parent configuration * @param root the root node of this subnode configuration */ public SubnodeConfiguration(HierarchicalConfiguration parent, ConfigurationNode root) { if (parent == null) { throw new IllegalArgumentException("Parent configuration must not be null!"); } if (root == null) { throw new IllegalArgumentException("Root node must not be null!"); } setRootNode(root); this.parent = parent; initFromParent(parent); } /** * Returns the parent configuration of this subnode configuration. * * @return the parent configuration */ public HierarchicalConfiguration getParent() { return parent; } /** * Returns the key that was used to construct this configuration. If here a * non-<b>null</b> value is returned, the subnode configuration will * always check its parent for structural changes and reconstruct itself if * necessary. * * @return the key for selecting this configuration's root node * @since 1.5 */ public String getSubnodeKey() { return subnodeKey; } /** * Sets the key to the root node of this subnode configuration. If here a * key is set, the subnode configuration will behave like a live-view on its * parent for this key. See the class comment for more details. * * @param subnodeKey the key used to construct this configuration * @since 1.5 */ public void setSubnodeKey(String subnodeKey) { this.subnodeKey = subnodeKey; } /** * Returns the root node for this configuration. If a subnode key is set, * this implementation re-evaluates this key to find out if this subnode * configuration needs to be reconstructed. This ensures that the subnode * configuration is always synchronized with its parent configuration. * * @return the root node of this configuration * @since 1.5 * @see #setSubnodeKey(String) */ public ConfigurationNode getRootNode() { if (getSubnodeKey() != null) { try { List nodes = getParent().fetchNodeList(getSubnodeKey()); if (nodes.size() != 1) { // key is invalid, so detach this subnode configuration setSubnodeKey(null); } else { ConfigurationNode currentRoot = (ConfigurationNode) nodes.get(0); if (currentRoot != super.getRootNode()) { // the root node was changed due to a change of the // parent setRootNode(currentRoot); } return currentRoot; } } catch (Exception ex) { // Evaluation of the key caused an exception. Probably the // expression engine has changed on the parent. Detach this // configuration, there is not much we can do about this. setSubnodeKey(null); } } return super.getRootNode(); // use stored root node } /** * Returns a hierarchical configuration object for the given sub node. * This implementation will ensure that the returned * <code>SubnodeConfiguration</code> object will have the same parent than * this object. * * @param node the sub node, for which the configuration is to be created * @return a hierarchical configuration for this sub node */ protected SubnodeConfiguration createSubnodeConfiguration(ConfigurationNode node) { SubnodeConfiguration result = new SubnodeConfiguration(getParent(), node); getParent().registerSubnodeConfiguration(result); return result; } /** * Returns a hierarchical configuration object for the given sub node that * is aware of structural changes of its parent. Works like the method with * the same name, but also sets the subnode key for the new subnode * configuration, so it can check whether the parent has been changed. This * only works if this subnode configuration has itself a valid subnode key. * So if a subnode configuration that should be aware of structural changes * is created from an already existing subnode configuration, this subnode * configuration must also be aware of such changes. * * @param node the sub node, for which the configuration is to be created * @param subnodeKey the construction key * @return a hierarchical configuration for this sub node * @since 1.5 */ protected SubnodeConfiguration createSubnodeConfiguration(ConfigurationNode node, String subnodeKey) { SubnodeConfiguration result = createSubnodeConfiguration(node); if (getSubnodeKey() != null) { // construct the correct subnode key // determine path to root node List lstPathToRoot = new ArrayList(); ConfigurationNode top = super.getRootNode(); ConfigurationNode nd = node; while (nd != top) { lstPathToRoot.add(nd); nd = nd.getParentNode(); } // construct the keys for the nodes on this path Collections.reverse(lstPathToRoot); String key = getSubnodeKey(); for (Iterator it = lstPathToRoot.iterator(); it.hasNext();) { key = getParent().getExpressionEngine().nodeKey((ConfigurationNode) it.next(), key); } result.setSubnodeKey(key); } return result; } /** * Creates a new node. This task is delegated to the parent. * * @param name the node's name * @return the new node */ protected Node createNode(String name) { return getParent().createNode(name); } /** * Initializes this subnode configuration from the given parent * configuration. This method is called by the constructor. It will copy * many settings from the parent. * * @param parentConfig the parent configuration */ protected void initFromParent(HierarchicalConfiguration parentConfig) { setExpressionEngine(parentConfig.getExpressionEngine()); setListDelimiter(parentConfig.getListDelimiter()); setDelimiterParsingDisabled(parentConfig.isDelimiterParsingDisabled()); setThrowExceptionOnMissing(parentConfig.isThrowExceptionOnMissing()); } /** * Performs interpolation. This implementation will ask the parent * configuration to perform the interpolation so that variables can be * evaluated in the global context. * * @param value the value to be interpolated */ protected Object interpolate(Object value) { return getParent().interpolate(value); } }