    001/*
    002 * Licensed to the Apache Software Foundation (ASF) under one or more
    003 * contributor license agreements.  See the NOTICE file distributed with
    004 * this work for additional information regarding copyright ownership.
    005 * The ASF licenses this file to You under the Apache License, Version 2.0
    006 * (the "License"); you may not use this file except in compliance with
    007 * the License.  You may obtain a copy of the License at
    008 *
    009 *     http://www.apache.org/licenses/LICENSE-2.0
    010 *
    011 * Unless required by applicable law or agreed to in writing, software
    012 * distributed under the License is distributed on an "AS IS" BASIS,
    013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    014 * See the License for the specific language governing permissions and
    015 * limitations under the License.
    016 */
    017
    018package org.apache.commons.configuration2;
    019
    020import java.util.Collection;
    021import java.util.Map;
    022
    023import org.apache.commons.configuration2.interpol.ConfigurationInterpolator;
    024import org.apache.commons.configuration2.interpol.Lookup;
    025import org.apache.commons.configuration2.sync.SynchronizerSupport;
    026
    027
    028/**
    029 * <p>The main Configuration interface.</p>
    030 * <p>This interface allows accessing and manipulating a configuration object.
    031 * The major part of the methods defined in this interface deals with accessing
    032 * properties of various data types. There is a generic {@code getProperty()}
    033 * method, which returns the value of the queried property in its raw data
    034 * type. Other getter methods try to convert this raw data type into a specific
    035 * data type. If this fails, a {@code ConversionException} will be thrown.</p>
    036 * <p>For most of the property getter methods an overloaded version exists that
    037 * allows to specify a default value, which will be returned if the queried
    038 * property cannot be found in the configuration. The behavior of the methods
    039 * that do not take a default value in case of a missing property is not defined
    040 * by this interface and depends on a concrete implementation. E.g. the
    041 * {@link AbstractConfiguration} class, which is the base class
    042 * of most configuration implementations provided by this package, per default
    043 * returns <b>null</b> if a property is not found, but provides the
    044 * {@link AbstractConfiguration#setThrowExceptionOnMissing(boolean)
    045 * setThrowExceptionOnMissing()}
    046 * method, with which it can be configured to throw a {@code NoSuchElementException}
    047 * exception in that case. (Note that getter methods for primitive types in
    048 * {@code AbstractConfiguration} always throw an exception for missing
    049 * properties because there is no way of overloading the return value.)</p>
    050 * <p>With the {@code addProperty()} and {@code setProperty()} methods
    051 * new properties can be added to a configuration or the values of properties
    052 * can be changed. With {@code clearProperty()} a property can be removed.
    053 * Other methods allow to iterate over the contained properties or to create
    054 * a subset configuration.</p>
    055 *
    056 * @author Commons Configuration team
    057 * @version $Id: Configuration.java 1679755 2015-05-16 17:34:50Z oheger $
    058 */
    059public interface Configuration extends ImmutableConfiguration, SynchronizerSupport
    060{
    061    /**
    062     * Return a decorator Configuration containing every key from the current
    063     * Configuration that starts with the specified prefix. The prefix is
    064     * removed from the keys in the subset. For example, if the configuration
    065     * contains the following properties:
    066     *
    067     * <pre>
    068     *    prefix.number = 1
    069     *    prefix.string = Apache
    070     *    prefixed.foo = bar
    071     *    prefix = Jakarta</pre>
    072     *
    073     * the Configuration returned by {@code subset("prefix")} will contain
    074     * the properties:
    075     *
    076     * <pre>
    077     *    number = 1
    078     *    string = Apache
    079     *    = Jakarta</pre>
    080     *
    081     * (The key for the value "Jakarta" is an empty string)
    082     * <p>
    083     * Since the subset is a decorator and not a modified copy of the initial
    084     * Configuration, any change made to the subset is available to the
    085     * Configuration, and reciprocally.
    086     *
    087     * @param prefix The prefix used to select the properties.
    088     * @return a subset configuration
    089     *
    090     * @see SubsetConfiguration
    091     */
    092    Configuration subset(String prefix);
    093
    094    /**
    095     * Add a property to the configuration. If it already exists then the value
    096     * stated here will be added to the configuration entry. For example, if
    097     * the property:
    098     *
    099     * <pre>resource.loader = file</pre>
    100     *
    101     * is already present in the configuration and you call
    102     *
    103     * <pre>addProperty("resource.loader", "classpath")</pre>
    104     *
    105     * Then you will end up with a List like the following:
    106     *
    107     * <pre>["file", "classpath"]</pre>
    108     *
    109     * @param key The key to add the property to.
    110     * @param value The value to add.
    111     */
    112    void addProperty(String key, Object value);
    113
    114    /**
    115     * Set a property, this will replace any previously set values. Set values
    116     * is implicitly a call to clearProperty(key), addProperty(key, value).
    117     *
    118     * @param key The key of the property to change
    119     * @param value The new value
    120     */
    121    void setProperty(String key, Object value);
    122
    123    /**
    124     * Remove a property from the configuration.
    125     *
    126     * @param key the key to remove along with corresponding value.
    127     */
    128    void clearProperty(String key);
    129
    130    /**
    131     * Remove all properties from the configuration.
    132     */
    133    void clear();
    134
    135    /**
    136     * Returns the {@code ConfigurationInterpolator} object used by this
    137     * {@code Configuration}. This object is responsible for variable
    138     * substitution.
    139     *
    140     * @return the {@code ConfigurationInterpolator} (can be <b>null</b>)
    141     */
    142    ConfigurationInterpolator getInterpolator();
    143
    144    /**
    145     * Sets the {@code ConfigurationInterpolator} object to be used by this
    146     * {@code Configuration}. This object is invoked for each access of a string
    147     * property in order to substitute variables which may be contained. The
    148     * argument can be <b>null</b> to disable interpolation at all.
    149     *
    150     * @param ci the new {@code ConfigurationInterpolator}
    151     */
    152    void setInterpolator(ConfigurationInterpolator ci);
    153
    154    /**
    155     * Creates and installs a new {@code ConfigurationInterpolator} for this
    156     * {@code Configuration} based on the passed in arguments. This method
    157     * creates a default {@code ConfigurationInterpolator} instance and
    158     * initializes it with the passed in {@code Lookup} objects. It also adds a
    159     * special default {@code Lookup} object that tries to resolve variables by
    160     * matching them with properties contained in this {@code Configuration}.
    161     * This is also the main difference to the
    162     * {@link #setInterpolator(ConfigurationInterpolator)} method
    163     * which sets the passed in object as is without adding this special lookup.
    164     *
    165     * @param prefixLookups the map with {@code Lookup} objects associated with
    166     *        specific prefixes (can be <b>null</b>)
    167     * @param defLookups a collection with default {@code Lookup} objects (can
    168     *        be <b>null</b>)
    169     * @see ConfigurationInterpolator
    170     */
    171    void installInterpolator(Map<String, ? extends Lookup> prefixLookups,
    172            Collection<? extends Lookup> defLookups);
    173}