CompositeConfiguration.java

/*
 * 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.configuration2;

import java.util.ArrayList;
import java.util.Collection;
import java.util.Iterator;
import java.util.LinkedHashSet;
import java.util.LinkedList;
import java.util.List;
import java.util.ListIterator;
import java.util.Set;

import org.apache.commons.configuration2.convert.ListDelimiterHandler;
import org.apache.commons.configuration2.ex.ConfigurationRuntimeException;

/**
 * <p>
 * {@code CompositeConfiguration} allows you to add multiple {@code Configuration} objects to an aggregated
 * configuration. If you add Configuration1, and then Configuration2, any properties shared will mean that the value
 * defined by Configuration1 will be returned. If Configuration1 doesn't have the property, then Configuration2 will be
 * checked. You can add multiple different types or the same type of properties file.
 * </p>
 * <p>
 * When querying properties the order in which child configurations have been added is relevant. To deal with property
 * updates, a so-called <em>in-memory configuration</em> is used. Per default, such a configuration is created
 * automatically. All property writes target this special configuration. There are constructors which allow you to
 * provide a specific in-memory configuration. If used that way, the in-memory configuration is always the last one in
 * the list of child configurations. This means that for query operations all other configurations take precedence.
 * </p>
 * <p>
 * Alternatively it is possible to mark a child configuration as in-memory configuration when it is added. In this case
 * the treatment of the in-memory configuration is slightly different: it remains in the list of child configurations at
 * the position it was added, i.e. its priority for property queries can be defined by adding the child configurations
 * in the correct order.
 * </p>
 * <p>
 * This configuration class uses a {@code Synchronizer} to control concurrent access. While all methods for reading and
 * writing configuration properties make use of this {@code Synchronizer} per default, the methods for managing the list
 * of child configurations and the in-memory configuration
 * ({@code addConfiguration(), getNumberOfConfigurations(), removeConfiguration(),
 * getConfiguration(), getInMemoryConfiguration()}) are guarded, too. Because most methods for accessing configuration
 * data delegate to the list of child configurations, the thread-safety of a {@code CompositeConfiguration} object also
 * depends on the {@code Synchronizer} objects used by these children.
 * </p>
 */
public class CompositeConfiguration extends AbstractConfiguration implements Cloneable {

    /** List holding all the configuration */
    private List<Configuration> configList = new LinkedList<>();

    /**
     * Configuration that holds in memory stuff. Inserted as first so any setProperty() override anything else added.
     */
    private Configuration inMemoryConfiguration;

    /**
     * Stores a flag whether the current in-memory configuration is also a child configuration.
     */
    private boolean inMemoryConfigIsChild;

    /**
     * Creates an empty CompositeConfiguration object which can then be added some other Configuration files
     */
    public CompositeConfiguration() {
        clear();
    }

    /**
     * Create a CompositeConfiguration with an empty in memory configuration and adds the collection of configurations
     * specified.
     *
     * @param configurations the collection of configurations to add
     */
    public CompositeConfiguration(final Collection<? extends Configuration> configurations) {
        this(new BaseConfiguration(), configurations);
    }

    /**
     * Creates a CompositeConfiguration object with a specified <em>in-memory configuration</em>. This configuration will
     * store any changes made to the {@code CompositeConfiguration}. Note: Use this constructor if you want to set a special
     * type of in-memory configuration. If you have a configuration which should act as both a child configuration and as
     * in-memory configuration, use {@link #addConfiguration(Configuration, boolean)} with a value of <strong>true</strong> instead.
     *
     * @param inMemoryConfiguration the in memory configuration to use
     */
    public CompositeConfiguration(final Configuration inMemoryConfiguration) {
        this.configList.clear();
        this.inMemoryConfiguration = inMemoryConfiguration;
        this.configList.add(inMemoryConfiguration);
    }

    /**
     * Creates a CompositeConfiguration with a specified <em>in-memory configuration</em>, and then adds the given
     * collection of configurations.
     *
     * @param inMemoryConfiguration the in memory configuration to use
     * @param configurations the collection of configurations to add
     * @see #CompositeConfiguration(Configuration)
     */
    public CompositeConfiguration(final Configuration inMemoryConfiguration, final Collection<? extends Configuration> configurations) {
        this(inMemoryConfiguration);
        if (configurations != null) {
            configurations.forEach(this::addConfiguration);
        }
    }

    /**
     * Add a configuration.
     *
     * @param config the configuration to add
     */
    public void addConfiguration(final Configuration config) {
        addConfiguration(config, false);
    }

    /**
     * Adds a child configuration and optionally makes it the <em>in-memory configuration</em>. This means that all future
     * property write operations are executed on this configuration. Note that the current in-memory configuration is
     * replaced by the new one. If it was created automatically or passed to the constructor, it is removed from the list of
     * child configurations! Otherwise, it stays in the list of child configurations at its current position, but it passes
     * its role as in-memory configuration to the new one.
     *
     * @param config the configuration to be added
     * @param asInMemory <strong>true</strong> if this configuration becomes the new <em>in-memory</em> configuration, <strong>false</strong>
     *        otherwise
     * @since 1.8
     */
    public void addConfiguration(final Configuration config, final boolean asInMemory) {
        syncWrite(() -> {
            if (!configList.contains(config)) {
                if (asInMemory) {
                    replaceInMemoryConfiguration(config);
                    inMemoryConfigIsChild = true;
                }
                if (!inMemoryConfigIsChild) {
                    // As the inMemoryConfiguration contains all manually added
                    // keys, we must make sure that it is always last. "Normal", non
                    // composed configurations add their keys at the end of the
                    // configuration and we want to mimic this behavior.
                    configList.add(configList.indexOf(inMemoryConfiguration), config);
                } else {
                    // However, if the in-memory configuration is a regular child,
                    // only the order in which child configurations are added is relevant
                    configList.add(config);
                }
                if (config instanceof AbstractConfiguration) {
                    ((AbstractConfiguration) config).setThrowExceptionOnMissing(isThrowExceptionOnMissing());
                }
            }
        }, false);
    }

    /**
     * Add a configuration to the start of the list of child configurations.
     *
     * @param config the configuration to add
     * @since 2.3
     */
    public void addConfigurationFirst(final Configuration config) {
        addConfigurationFirst(config, false);
    }

    /**
     * Adds a child configuration to the start of the collection and optionally makes it the <em>in-memory
     * configuration</em>. This means that all future property write operations are executed on this configuration. Note
     * that the current in-memory configuration is replaced by the new one. If it was created automatically or passed to the
     * constructor, it is removed from the list of child configurations! Otherwise, it stays in the list of child
     * configurations at its current position, but it passes its role as in-memory configuration to the new one.
     *
     * @param config the configuration to be added
     * @param asInMemory <strong>true</strong> if this configuration becomes the new <em>in-memory</em> configuration, <strong>false</strong>
     *        otherwise
     * @since 2.3
     */
    public void addConfigurationFirst(final Configuration config, final boolean asInMemory) {
        syncWrite(() -> {
            if (!configList.contains(config)) {
                if (asInMemory) {
                    replaceInMemoryConfiguration(config);
                    inMemoryConfigIsChild = true;
                }
                configList.add(0, config);
                if (config instanceof AbstractConfiguration) {
                    ((AbstractConfiguration) config).setThrowExceptionOnMissing(isThrowExceptionOnMissing());
                }
            }
        }, false);
    }

    /**
     * Add this property to the in-memory Configuration.
     *
     * @param key The Key to add the property to.
     * @param token The Value to add.
     */
    @Override
    protected void addPropertyDirect(final String key, final Object token) {
        inMemoryConfiguration.addProperty(key, token);
    }

    /**
     * Adds the value of a property to the given list. This method is used by {@code getList()} for gathering property
     * values from the child configurations.
     *
     * @param dest the list for collecting the data
     * @param config the configuration to query
     * @param key the key of the property
     */
    private void appendListProperty(final List<Object> dest, final Configuration config, final String key) {
        final Object value = interpolate(config.getProperty(key));
        if (value != null) {
            if (value instanceof Collection) {
                final Collection<?> col = (Collection<?>) value;
                dest.addAll(col);
            } else {
                dest.add(value);
            }
        }
    }

    /**
     * Removes all child configurations and reinitializes the <em>in-memory configuration</em>. <strong>Attention:</strong>
     * A new in-memory configuration is created; the old one is lost.
     */
    @Override
    protected void clearInternal() {
        configList.clear();
        // recreate the in memory configuration
        inMemoryConfiguration = new BaseConfiguration();
        ((BaseConfiguration) inMemoryConfiguration).setThrowExceptionOnMissing(isThrowExceptionOnMissing());
        ((BaseConfiguration) inMemoryConfiguration).setListDelimiterHandler(getListDelimiterHandler());
        configList.add(inMemoryConfiguration);
        inMemoryConfigIsChild = false;
    }

    @Override
    protected void clearPropertyDirect(final String key) {
        configList.forEach(config -> config.clearProperty(key));
    }

    /**
     * Returns a copy of this object. This implementation will create a deep clone, i.e. all configurations contained in
     * this composite will also be cloned. This only works if all contained configurations support cloning; otherwise a
     * runtime exception will be thrown. Registered event handlers won't get cloned.
     *
     * @return the copy
     * @since 1.3
     */
    @Override
    public Object clone() {
        try {
            final CompositeConfiguration copy = (CompositeConfiguration) super.clone();
            copy.configList = new LinkedList<>();
            copy.inMemoryConfiguration = ConfigurationUtils.cloneConfiguration(getInMemoryConfiguration());
            copy.configList.add(copy.inMemoryConfiguration);

            configList.forEach(config -> {
                if (config != getInMemoryConfiguration()) {
                    copy.addConfiguration(ConfigurationUtils.cloneConfiguration(config));
                }
            });

            copy.cloneInterpolator(this);
            return copy;
        } catch (final CloneNotSupportedException cnex) {
            // cannot happen
            throw new ConfigurationRuntimeException(cnex);
        }
    }

    @Override
    protected boolean containsKeyInternal(final String key) {
        return configList.stream().anyMatch(config -> config.containsKey(key));
    }

    /**
     * Tests whether this configuration contains one or more matches to this value. This operation stops at first
     * match but may be more expensive than the containsKey method.
     * @since 2.11.0
     */
    @Override
    protected boolean containsValueInternal(final Object value) {
        return configList.stream().anyMatch(config -> config.containsValue(value));
    }

    /**
     * Gets the configuration at the specified index.
     *
     * @param index The index of the configuration to retrieve
     * @return the configuration at this index
     */
    public Configuration getConfiguration(final int index) {
        return syncRead(() -> configList.get(index), false);
    }

    /**
     * Gets the &quot;in memory configuration&quot;. In this configuration changes are stored.
     *
     * @return the in memory configuration
     */
    public Configuration getInMemoryConfiguration() {
        return syncReadValue(inMemoryConfiguration, false);
    }

    @Override
    protected Iterator<String> getKeysInternal() {
        final Set<String> keys = new LinkedHashSet<>();
        configList.forEach(config -> config.getKeys().forEachRemaining(keys::add));
        return keys.iterator();
    }

    @Override
    protected Iterator<String> getKeysInternal(final String key) {
        final Set<String> keys = new LinkedHashSet<>();
        configList.forEach(config -> config.getKeys(key).forEachRemaining(keys::add));
        return keys.iterator();
    }

    @Override
    protected Iterator<String> getKeysInternal(final String key, final String delimiter) {
        final Set<String> keys = new LinkedHashSet<>();
        configList.forEach(config -> config.getKeys(key, delimiter).forEachRemaining(keys::add));
        return keys.iterator();
    }

    @Override
    public List<Object> getList(final String key, final List<?> defaultValue) {
        final List<Object> list = new ArrayList<>();

        // add all elements from the first configuration containing the requested key
        final Iterator<Configuration> it = configList.iterator();
        while (it.hasNext() && list.isEmpty()) {
            final Configuration config = it.next();
            if (config != inMemoryConfiguration && config.containsKey(key)) {
                appendListProperty(list, config, key);
            }
        }

        // add all elements from the in memory configuration
        appendListProperty(list, inMemoryConfiguration, key);

        if (list.isEmpty()) {
            // This is okay because we just return this list to the caller
            @SuppressWarnings("unchecked")
            final List<Object> resultList = (List<Object>) defaultValue;
            return resultList;
        }

        final ListIterator<Object> lit = list.listIterator();
        while (lit.hasNext()) {
            lit.set(interpolate(lit.next()));
        }

        return list;
    }

    /**
     * Gets the number of configurations.
     *
     * @return the number of configuration
     */
    public int getNumberOfConfigurations() {
        return syncRead(configList::size, false);
    }

    /**
     * Reads property from underlying composite
     *
     * @param key key to use for mapping
     * @return object associated with the given configuration key.
     */
    @Override
    protected Object getPropertyInternal(final String key) {
        return configList.stream().filter(config -> config.containsKey(key)).findFirst().map(config -> config.getProperty(key)).orElse(null);
    }

    /**
     * Gets the configuration source, in which the specified key is defined. This method will iterate over all existing
     * child configurations and check whether they contain the specified key. The following constellations are possible:
     * <ul>
     * <li>If exactly one child configuration contains the key, this configuration is returned as the source configuration.
     * This may be the <em>in memory configuration</em> (this has to be explicitly checked by the calling application).</li>
     * <li>If none of the child configurations contain the key, <strong>null</strong> is returned.</li>
     * <li>If the key is contained in multiple child configurations or if the key is <strong>null</strong>, a
     * {@code IllegalArgumentException} is thrown. In this case the source configuration cannot be determined.</li>
     * </ul>
     *
     * @param key the key to be checked
     * @return the source configuration of this key
     * @throws IllegalArgumentException if the source configuration cannot be determined
     * @since 1.5
     */
    public Configuration getSource(final String key) {
        if (key == null) {
            throw new IllegalArgumentException("Key must not be null!");
        }

        Configuration source = null;
        for (final Configuration conf : configList) {
            if (conf.containsKey(key)) {
                if (source != null) {
                    throw new IllegalArgumentException("The key " + key + " is defined by multiple sources!");
                }
                source = conf;
            }
        }

        return source;
    }

    @Override
    public String[] getStringArray(final String key) {
        final List<Object> list = getList(key);

        // transform property values into strings
        final String[] tokens = new String[list.size()];

        for (int i = 0; i < tokens.length; i++) {
            tokens[i] = String.valueOf(list.get(i));
        }

        return tokens;
    }

    @Override
    protected boolean isEmptyInternal() {
        return configList.stream().allMatch(Configuration::isEmpty);
    }

    /**
     * Remove a configuration. The in memory configuration cannot be removed.
     *
     * @param config The configuration to remove
     */
    public void removeConfiguration(final Configuration config) {
        syncWrite(() -> {
            // Make sure that you can't remove the inMemoryConfiguration from
            // the CompositeConfiguration object
            if (!config.equals(inMemoryConfiguration)) {
                configList.remove(config);
            }
        }, false);
    }

    /**
     * Replaces the current in-memory configuration by the given one.
     *
     * @param config the new in-memory configuration
     */
    private void replaceInMemoryConfiguration(final Configuration config) {
        if (!inMemoryConfigIsChild) {
            // remove current in-memory configuration
            configList.remove(inMemoryConfiguration);
        }
        inMemoryConfiguration = config;
    }

    /**
     * {@inheritDoc} This implementation ensures that the in memory configuration is correctly initialized.
     */
    @Override
    public void setListDelimiterHandler(final ListDelimiterHandler listDelimiterHandler) {
        if (inMemoryConfiguration instanceof AbstractConfiguration) {
            ((AbstractConfiguration) inMemoryConfiguration).setListDelimiterHandler(listDelimiterHandler);
        }
        super.setListDelimiterHandler(listDelimiterHandler);
    }
}