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.Collection; import java.util.HashMap; import java.util.Iterator; import java.util.List; import java.util.Map; import java.util.Set; 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.DefaultConfigurationKey; 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.NodeCombiner; import org.apache.commons.configuration.tree.UnionCombiner; import org.apache.commons.configuration.tree.ViewNode; /** * <p> * A hierarchical composite configuration class. * </p> * <p> * This class maintains a list of configuration objects, which can be added * using the divers <code>addConfiguration()</code> methods. After that the * configurations can be accessed either by name (if one was provided when the * configuration was added) or by index. For the whole set of managed * configurations a logical node structure is constructed. For this purpose a * <code>{@link org.apache.commons.configuration.tree.NodeCombiner NodeCombiner}</code> * object can be set. This makes it possible to specify different algorithms for * the combination process. * </p> * <p> * The big advantage of this class is that it creates a truly hierarchical * structure of all the properties stored in the contained configurations - even * if some of them are no hierarchical configurations per se. So all enhanced * features provided by a hierarchical configuration (e.g. choosing an * expression engine) are applicable. * </p> * <p> * The class works by registering itself as an event listener at all added * configurations. So it gets notified whenever one of these configurations is * changed and can invalidate its internal node structure. The next time a * property is accessed the node structure will be re-constructed using the * current state of the managed configurations. Note that, depending on the used * <code>NodeCombiner</code>, this may be a complex operation. * </p> * <p> * Because of the way a <code>CombinedConfiguration</code> is working it has * more or less view character: it provides a logic view on the configurations * it contains. In this constellation not all methods defined for hierarchical * configurations - especially methods that update the stored properties - can * be implemented in a consistent manner. Using such methods (like * <code>addProperty()</code>, or <code>clearProperty()</code> on a * <code>CombinedConfiguration</code> is not strictly forbidden, however, * depending on the current <code>{@link NodeCombiner}</code> and the involved * properties, the results may be different than expected. Some examples may * illustrate this: * </p> * <p> * <ul> * <li>Imagine a <code>CombinedConfiguration</code> <em>cc</em> containing * two child configurations with the following content: * <dl> * <dt>user.properties</dt> * <dd> * * <pre> * gui.background = blue * gui.position = (10, 10, 400, 200) * </pre> * * </dd> * <dt>default.properties</dt> * <dd> * * <pre> * gui.background = black * gui.foreground = white * home.dir = /data * </pre> * * </dd> * </dl> * As a <code>NodeCombiner</code> a * <code>{@link org.apache.commons.configuration.tree.OverrideCombiner OverrideCombiner}</code> * is used. This combiner will ensure that defined user settings take precedence * over the default values. If the resulting <code>CombinedConfiguration</code> * is queried for the background color, <code>blue</code> will be returned * because this value is defined in <code>user.properties</code>. Now * consider what happens if the key <code>gui.background</code> is removed * from the <code>CombinedConfiguration</code>: * * <pre>cc.clearProperty("gui.background");</pre> * * Will a <code>cc.containsKey("gui.background")</code> now return <b>false</b>? * No, it won't! The <code>clearProperty()</code> operation is executed on the * node set of the combined configuration, which was constructed from the nodes * of the two child configurations. It causes the value of the * <em>background</em> node to be cleared, which is also part of the first * child configuration. This modification of one of its child configurations * causes the <code>CombinedConfiguration</code> to be re-constructed. This * time the <code>OverrideCombiner</code> cannot find a * <code>gui.background</code> property in the first child configuration, but * it finds one in the second, and adds it to the resulting combined * configuration. So the property is still present (with a different value now).</li> * <li><code>addProperty()</code> can also be problematic: Most node * combiners use special view nodes for linking parts of the original * configurations' data together. If new properties are added to such a special * node, they do not belong to any of the managed configurations and thus hang * in the air. Using the same configurations as in the last example, the * statement * * <pre> * addProperty("database.user", "scott"); * </pre> * * would cause such a hanging property. If now one of the child configurations * is changed and the <code>CombinedConfiguration</code> is re-constructed, * this property will disappear! (Add operations are not problematic if they * result in a child configuration being updated. For instance an * <code>addProperty("home.url", "localhost");</code> will alter the second * child configuration - because the prefix <em>home</em> is here already * present; when the <code>CombinedConfiguration</code> is re-constructed, * this change is taken into account.)</li> * </ul> * Because of such problems it is recommended to perform updates only on the * managed child configurations. * </p> * <p> * Whenever the node structure of a <code>CombinedConfiguration</code> becomes * invalid (either because one of the contained configurations was modified or * because the <code>invalidate()</code> method was directly called) an event * is generated. So this can be detected by interested event listeners. This * also makes it possible to add a combined configuration into another one. * </p> * <p> * Implementation note: Adding and removing configurations to and from a * combined configuration is not thread-safe. If a combined configuration is * manipulated by multiple threads, the developer has to take care about * properly synchronization. * </p> * * @author <a * href="http://commons.apache.org/configuration/team-list.html">Commons * Configuration team</a> * @since 1.3 * @version $Id: CombinedConfiguration.java 712401 2008-11-08 15:29:56Z oheger $ */ public class CombinedConfiguration extends HierarchicalConfiguration implements ConfigurationListener, Cloneable { /** * Constant for the invalidate event that is fired when the internal node * structure becomes invalid. */ public static final int EVENT_COMBINED_INVALIDATE = 40; /** * The serial version ID. */ private static final long serialVersionUID = 8338574525528692307L; /** Constant for the expression engine for parsing the at path. */ private static final DefaultExpressionEngine AT_ENGINE = new DefaultExpressionEngine(); /** Constant for the default node combiner. */ private static final NodeCombiner DEFAULT_COMBINER = new UnionCombiner(); /** Constant for the name of the property used for the reload check.*/ private static final String PROP_RELOAD_CHECK = "CombinedConfigurationReloadCheck"; /** Stores the combiner. */ private NodeCombiner nodeCombiner; /** Stores the combined root node. */ private volatile ConfigurationNode combinedRoot; /** Stores a list with the contained configurations. */ private List configurations; /** Stores a map with the named configurations. */ private Map namedConfigurations; /** * An expression engine used for converting child configurations to * hierarchical ones. */ private ExpressionEngine conversionExpressionEngine; /** A flag whether an enhanced reload check is to be performed.*/ private boolean forceReloadCheck; /** * Creates a new instance of <code>CombinedConfiguration</code> and * initializes the combiner to be used. * * @param comb the node combiner (can be <b>null</b>, then a union combiner * is used as default) */ public CombinedConfiguration(NodeCombiner comb) { setNodeCombiner((comb != null) ? comb : DEFAULT_COMBINER); clear(); } /** * Creates a new instance of <code>CombinedConfiguration</code> that uses * a union combiner. * * @see org.apache.commons.configuration.tree.UnionCombiner */ public CombinedConfiguration() { this(null); } /** * Returns the node combiner that is used for creating the combined node * structure. * * @return the node combiner */ public NodeCombiner getNodeCombiner() { return nodeCombiner; } /** * Sets the node combiner. This object will be used when the combined node * structure is to be constructed. It must not be <b>null</b>, otherwise an * <code>IllegalArgumentException</code> exception is thrown. Changing the * node combiner causes an invalidation of this combined configuration, so * that the new combiner immediately takes effect. * * @param nodeCombiner the node combiner */ public void setNodeCombiner(NodeCombiner nodeCombiner) { if (nodeCombiner == null) { throw new IllegalArgumentException("Node combiner must not be null!"); } this.nodeCombiner = nodeCombiner; invalidate(); } /** * Returns a flag whether an enhanced reload check must be performed. * * @return the force reload check flag * @since 1.4 */ public boolean isForceReloadCheck() { return forceReloadCheck; } /** * Sets the force reload check flag. If this flag is set, each property * access on this configuration will cause a reload check on the contained * configurations. This is a workaround for a problem with some reload * implementations that only check if a reload is required when they are * triggered. Per default this mode is disabled. If the force reload check * flag is set to <b>true</b>, accessing properties will be less * performant, but reloads on contained configurations will be detected. * * @param forceReloadCheck the value of the flag * @since 1.4 */ public void setForceReloadCheck(boolean forceReloadCheck) { this.forceReloadCheck = forceReloadCheck; } /** * Returns the <code>ExpressionEngine</code> for converting flat child * configurations to hierarchical ones. * * @return the conversion expression engine * @since 1.6 */ public ExpressionEngine getConversionExpressionEngine() { return conversionExpressionEngine; } /** * Sets the <code>ExpressionEngine</code> for converting flat child * configurations to hierarchical ones. When constructing the root node for * this combined configuration the properties of all child configurations * must be combined to a single hierarchical node structure. In this * process, non hierarchical configurations are converted to hierarchical * ones first. This can be problematic if a child configuration contains * keys that are no compatible with the default expression engine used by * hierarchical configurations. Therefore it is possible to specify a * specific expression engine to be used for this purpose. * * @param conversionExpressionEngine the conversion expression engine * @see ConfigurationUtils#convertToHierarchical(Configuration, ExpressionEngine) * @since 1.6 */ public void setConversionExpressionEngine(ExpressionEngine conversionExpressionEngine) { this.conversionExpressionEngine = conversionExpressionEngine; } /** * Adds a new configuration to this combined configuration. It is possible * (but not mandatory) to give the new configuration a name. This name must * be unique, otherwise a <code>ConfigurationRuntimeException</code> will * be thrown. With the optional <code>at</code> argument you can specify * where in the resulting node structure the content of the added * configuration should appear. This is a string that uses dots as property * delimiters (independent on the current expression engine). For instance * if you pass in the string <code>"database.tables"</code>, * all properties of the added configuration will occur in this branch. * * @param config the configuration to add (must not be <b>null</b>) * @param name the name of this configuration (can be <b>null</b>) * @param at the position of this configuration in the combined tree (can be * <b>null</b>) */ public void addConfiguration(AbstractConfiguration config, String name, String at) { if (config == null) { throw new IllegalArgumentException("Added configuration must not be null!"); } if (name != null && namedConfigurations.containsKey(name)) { throw new ConfigurationRuntimeException( "A configuration with the name '" + name + "' already exists in this combined configuration!"); } ConfigData cd = new ConfigData(config, name, at); configurations.add(cd); if (name != null) { namedConfigurations.put(name, config); } config.addConfigurationListener(this); invalidate(); } /** * Adds a new configuration to this combined configuration with an optional * name. The new configuration's properties will be added under the root of * the combined node structure. * * @param config the configuration to add (must not be <b>null</b>) * @param name the name of this configuration (can be <b>null</b>) */ public void addConfiguration(AbstractConfiguration config, String name) { addConfiguration(config, name, null); } /** * Adds a new configuration to this combined configuration. The new * configuration is not given a name. Its properties will be added under the * root of the combined node structure. * * @param config the configuration to add (must not be <b>null</b>) */ public void addConfiguration(AbstractConfiguration config) { addConfiguration(config, null, null); } /** * Returns the number of configurations that are contained in this combined * configuration. * * @return the number of contained configurations */ public int getNumberOfConfigurations() { return configurations.size(); } /** * Returns the configuration at the specified index. The contained * configurations are numbered in the order they were added to this combined * configuration. The index of the first configuration is 0. * * @param index the index * @return the configuration at this index */ public Configuration getConfiguration(int index) { ConfigData cd = (ConfigData) configurations.get(index); return cd.getConfiguration(); } /** * Returns the configuration with the given name. This can be <b>null</b> * if no such configuration exists. * * @param name the name of the configuration * @return the configuration with this name */ public Configuration getConfiguration(String name) { return (Configuration) namedConfigurations.get(name); } /** * Removes the specified configuration from this combined configuration. * * @param config the configuration to be removed * @return a flag whether this configuration was found and could be removed */ public boolean removeConfiguration(Configuration config) { for (int index = 0; index < getNumberOfConfigurations(); index++) { if (((ConfigData) configurations.get(index)).getConfiguration() == config) { removeConfigurationAt(index); return true; } } return false; } /** * Removes the configuration at the specified index. * * @param index the index * @return the removed configuration */ public Configuration removeConfigurationAt(int index) { ConfigData cd = (ConfigData) configurations.remove(index); if (cd.getName() != null) { namedConfigurations.remove(cd.getName()); } cd.getConfiguration().removeConfigurationListener(this); invalidate(); return cd.getConfiguration(); } /** * Removes the configuration with the specified name. * * @param name the name of the configuration to be removed * @return the removed configuration (<b>null</b> if this configuration * was not found) */ public Configuration removeConfiguration(String name) { Configuration conf = getConfiguration(name); if (conf != null) { removeConfiguration(conf); } return conf; } /** * Returns a set with the names of all configurations contained in this * combined configuration. Of course here are only these configurations * listed, for which a name was specified when they were added. * * @return a set with the names of the contained configurations (never * <b>null</b>) */ public Set getConfigurationNames() { return namedConfigurations.keySet(); } /** * Invalidates this combined configuration. This means that the next time a * property is accessed the combined node structure must be re-constructed. * Invalidation of a combined configuration also means that an event of type * <code>EVENT_COMBINED_INVALIDATE</code> is fired. Note that while other * events most times appear twice (once before and once after an update), * this event is only fired once (after update). */ public void invalidate() { combinedRoot = null; fireEvent(EVENT_COMBINED_INVALIDATE, null, null, false); } /** * Event listener call back for configuration update events. This method is * called whenever one of the contained configurations was modified. It * invalidates this combined configuration. * * @param event the update event */ public void configurationChanged(ConfigurationEvent event) { if (!event.isBeforeUpdate()) { invalidate(); } } /** * Returns the configuration root node of this combined configuration. This * method will construct a combined node structure using the current node * combiner if necessary. * * @return the combined root node */ public ConfigurationNode getRootNode() { if (combinedRoot == null) { combinedRoot = constructCombinedNode(); } return combinedRoot; } /** * Clears this configuration. All contained configurations will be removed. */ public void clear() { fireEvent(EVENT_CLEAR, null, null, true); configurations = new ArrayList(); namedConfigurations = new HashMap(); fireEvent(EVENT_CLEAR, null, null, false); invalidate(); } /** * Returns a copy of this object. This implementation performs a deep clone, * i.e. all contained configurations will be cloned, too. For this to work, * all contained configurations must be cloneable. Registered event * listeners won't be cloned. The clone will use the same node combiner than * the original. * * @return the copied object */ public Object clone() { CombinedConfiguration copy = (CombinedConfiguration) super.clone(); copy.clear(); for (Iterator it = configurations.iterator(); it.hasNext();) { ConfigData cd = (ConfigData) it.next(); copy.addConfiguration( (AbstractConfiguration) ConfigurationUtils.cloneConfiguration(cd.getConfiguration()), cd.getName(), cd.getAt()); } copy.setRootNode(new DefaultConfigurationNode()); return copy; } /** * Returns the configuration source, in which the specified key is defined. * This method will determine the configuration node that is identified by * the given key. The following constellations are possible: * <ul> * <li>If no node object is found for this key, <b>null</b> is returned.</li> * <li>If the key maps to multiple nodes belonging to different * configuration sources, a <code>IllegalArgumentException</code> is * thrown (in this case no unique source can be determined).</li> * <li>If exactly one node is found for the key, the (child) configuration * object, to which the node belongs is determined and returned.</li> * <li>For keys that have been added directly to this combined * configuration and that do not belong to the namespaces defined by * existing child configurations this configuration will be returned.</li> * </ul> * * @param key the key of a configuration property * @return the configuration, to which this property belongs or <b>null</b> * if the key cannot be resolved * @throws IllegalArgumentException if the key maps to multiple properties * and the source cannot be determined, or if the key is <b>null</b> * @since 1.5 */ public Configuration getSource(String key) { if (key == null) { throw new IllegalArgumentException("Key must not be null!"); } List nodes = fetchNodeList(key); if (nodes.isEmpty()) { return null; } Iterator it = nodes.iterator(); Configuration source = findSourceConfiguration((ConfigurationNode) it.next()); while (it.hasNext()) { Configuration src = findSourceConfiguration((ConfigurationNode) it.next()); if (src != source) { throw new IllegalArgumentException("The key " + key + " is defined by multiple sources!"); } } return source; } /** * Evaluates the passed in property key and returns a list with the matching * configuration nodes. This implementation also evaluates the * <em>force reload check</em> flag. If it is set, * <code>performReloadCheck()</code> is invoked. * * @param key the property key * @return a list with the matching configuration nodes */ protected List fetchNodeList(String key) { if (isForceReloadCheck()) { performReloadCheck(); } return super.fetchNodeList(key); } /** * Triggers the contained configurations to perform a reload check if * necessary. This method is called when a property of this combined * configuration is accessed and the <code>forceReloadCheck</code> property * is set to <b>true</b>. * * @see #setForceReloadCheck(boolean) * @since 1.6 */ protected void performReloadCheck() { for (Iterator it = configurations.iterator(); it.hasNext();) { try { // simply retrieve a property; this is enough for // triggering a reload ((ConfigData) it.next()).getConfiguration().getProperty(PROP_RELOAD_CHECK); } catch (Exception ex) { // ignore all exceptions, e.g. missing property exceptions ; } } } /** * Creates the root node of this combined configuration. * * @return the combined root node */ private ConfigurationNode constructCombinedNode() { if (getNumberOfConfigurations() < 1) { return new ViewNode(); } else { Iterator it = configurations.iterator(); ConfigurationNode node = ((ConfigData) it.next()).getTransformedRoot(); while (it.hasNext()) { node = getNodeCombiner().combine(node, ((ConfigData) it.next()).getTransformedRoot()); } return node; } } /** * Determines the configuration that owns the specified node. * * @param node the node * @return the owning configuration */ private Configuration findSourceConfiguration(ConfigurationNode node) { ConfigurationNode root = null; ConfigurationNode current = node; // find the root node in this hierarchy while (current != null) { root = current; current = current.getParentNode(); } // Check with the root nodes of the child configurations for (Iterator it = configurations.iterator(); it.hasNext();) { ConfigData cd = (ConfigData) it.next(); if (root == cd.getRootNode()) { return cd.getConfiguration(); } } return this; } /** * An internal helper class for storing information about contained * configurations. */ class ConfigData { /** Stores a reference to the configuration. */ private AbstractConfiguration configuration; /** Stores the name under which the configuration is stored. */ private String name; /** Stores the at information as path of nodes. */ private Collection atPath; /** Stores the at string.*/ private String at; /** Stores the root node for this child configuration.*/ private ConfigurationNode rootNode; /** * Creates a new instance of <code>ConfigData</code> and initializes * it. * * @param config the configuration * @param n the name * @param at the at position */ public ConfigData(AbstractConfiguration config, String n, String at) { configuration = config; name = n; atPath = parseAt(at); this.at = at; } /** * Returns the stored configuration. * * @return the configuration */ public AbstractConfiguration getConfiguration() { return configuration; } /** * Returns the configuration's name. * * @return the name */ public String getName() { return name; } /** * Returns the at position of this configuration. * * @return the at position */ public String getAt() { return at; } /** * Returns the root node for this child configuration. * * @return the root node of this child configuration * @since 1.5 */ public ConfigurationNode getRootNode() { return rootNode; } /** * Returns the transformed root node of the stored configuration. The * term "transformed" means that an eventually defined at path * has been applied. * * @return the transformed root node */ public ConfigurationNode getTransformedRoot() { ViewNode result = new ViewNode(); ViewNode atParent = result; if (atPath != null) { // Build the complete path for (Iterator it = atPath.iterator(); it.hasNext();) { ViewNode node = new ViewNode(); node.setName((String) it.next()); atParent.addChild(node); atParent = node; } } // Copy data of the root node to the new path HierarchicalConfiguration hc = ConfigurationUtils.convertToHierarchical(getConfiguration(), getConversionExpressionEngine()); atParent.appendChildren(hc.getRootNode()); atParent.appendAttributes(hc.getRootNode()); rootNode = hc.getRootNode(); return result; } /** * Splits the at path into its components. * * @param at the at string * @return a collection with the names of the single components */ private Collection parseAt(String at) { if (at == null) { return null; } Collection result = new ArrayList(); DefaultConfigurationKey.KeyIterator it = new DefaultConfigurationKey(AT_ENGINE, at).iterator(); while (it.hasNext()) { result.add(it.nextKey()); } return result; } } }