    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 */
    017package org.apache.commons.configuration2;
    018
    019import java.math.BigDecimal;
    020import java.math.BigInteger;
    021import java.util.Collection;
    022import java.util.Iterator;
    023import java.util.List;
    024import java.util.Properties;
    025
    026/**
    027 * <p>The main interface for accessing configuration data in a read-only fashion.</p>
    028 * <p>
    029 * The major part of the methods defined in this interface deals with accessing
    030 * properties of various data types. There is a generic {@code getProperty()}
    031 * method, which returns the value of the queried property in its raw data
    032 * type. Other getter methods try to convert this raw data type into a specific
    033 * data type. If this fails, a {@code ConversionException} will be thrown.</p>
    034 * <p>For most of the property getter methods an overloaded version exists that
    035 * allows to specify a default value, which will be returned if the queried
    036 * property cannot be found in the configuration. The behavior of the methods
    037 * that do not take a default value in case of a missing property is not defined
    038 * by this interface and depends on a concrete implementation. E.g. the
    039 * {@link AbstractConfiguration} class, which is the base class
    040 * of most configuration implementations provided by this package, per default
    041 * returns <b>null</b> if a property is not found, but provides the
    042 * {@link AbstractConfiguration#setThrowExceptionOnMissing(boolean)
    043 * setThrowExceptionOnMissing()}
    044 * method, with which it can be configured to throw a {@code NoSuchElementException}
    045 * exception in that case. (Note that getter methods for primitive types in
    046 * {@code AbstractConfiguration} always throw an exception for missing
    047 * properties because there is no way of overloading the return value.)</p>
    048 *
    049 * @version $Id: ImmutableConfiguration.java 1819882 2018-01-02 19:59:19Z oheger $
    050 * @since 2.0
    051 */
    052public interface ImmutableConfiguration
    053{
    054    /**
    055     * Check if the configuration is empty.
    056     *
    057     * @return {@code true} if the configuration contains no property,
    058     *         {@code false} otherwise.
    059     */
    060    boolean isEmpty();
    061
    062    /**
    063     * Returns the number of keys stored in this configuration. Note that a
    064     * concrete implementation is not guaranteed to be efficient; for some
    065     * implementations it may be expensive to determine the size. Especially, if
    066     * you just want to check whether a configuration is empty, it is preferable
    067     * to use the {@link #isEmpty()} method.
    068     *
    069     * @return the number of keys stored in this configuration
    070     */
    071    int size();
    072
    073    /**
    074     * Check if the configuration contains the specified key.
    075     *
    076     * @param key the key whose presence in this configuration is to be tested
    077     *
    078     * @return {@code true} if the configuration contains a value for this
    079     *         key, {@code false} otherwise
    080     */
    081    boolean containsKey(String key);
    082
    083    /**
    084     * Gets a property from the configuration. This is the most basic get
    085     * method for retrieving values of properties. In a typical implementation
    086     * of the {@code Configuration} interface the other get methods (that
    087     * return specific data types) will internally make use of this method. On
    088     * this level variable substitution is not yet performed. The returned
    089     * object is an internal representation of the property value for the passed
    090     * in key. It is owned by the {@code Configuration} object. So a caller
    091     * should not modify this object. It cannot be guaranteed that this object
    092     * will stay constant over time (i.e. further update operations on the
    093     * configuration may change its internal state).
    094     *
    095     * @param key property to retrieve
    096     * @return the value to which this configuration maps the specified key, or
    097     *         null if the configuration contains no mapping for this key.
    098     */
    099    Object getProperty(String key);
    100
    101    /**
    102     * Get the list of the keys contained in the configuration that match the
    103     * specified prefix. For instance, if the configuration contains the
    104     * following keys:<br>
    105     * {@code db.user, db.pwd, db.url, window.xpos, window.ypos},<br>
    106     * an invocation of {@code getKeys("db");}<br>
    107     * will return the keys below:<br>
    108     * {@code db.user, db.pwd, db.url}.<br>
    109     * Note that the prefix itself is included in the result set if there is a
    110     * matching key. The exact behavior - how the prefix is actually
    111     * interpreted - depends on a concrete implementation.
    112     *
    113     * @param prefix The prefix to test against.
    114     * @return An Iterator of keys that match the prefix.
    115     * @see #getKeys()
    116     */
    117    Iterator<String> getKeys(String prefix);
    118
    119    /**
    120     * Get the list of the keys contained in the configuration. The returned
    121     * iterator can be used to obtain all defined keys. It does not allow
    122     * removing elements from this configuration via its {@code remove()}
    123     * method. Note that the keys of this configuration are returned in a form,
    124     * so that they can be directly evaluated; escaping of special characters
    125     * (if necessary) has already been performed.
    126     *
    127     * @return An Iterator.
    128     */
    129    Iterator<String> getKeys();
    130
    131    /**
    132     * Get a list of properties associated with the given configuration key. This method
    133     * expects the given key to have an arbitrary number of String values, each of which
    134     * is of the form {@code key=value}. These strings are split at the equals sign, and
    135     * the key parts will become keys of the returned {@code Properties} object, the value
    136     * parts become values.
    137     *
    138     * @param key The configuration key.
    139     * @return The associated properties if key is found.
    140     * @throws org.apache.commons.configuration2.ex.ConversionException is thrown if the
    141     * key maps to an object that is not a String/List.
    142     * @throws IllegalArgumentException if one of the tokens is malformed (does not contain
    143     * an equals sign).
    144     */
    145    Properties getProperties(String key);
    146
    147    /**
    148     * Get a boolean associated with the given configuration key.
    149     *
    150     * @param key The configuration key.
    151     * @return The associated boolean.
    152     * @throws org.apache.commons.configuration2.ex.ConversionException is thrown if the
    153     * key maps to an object that is not a Boolean.
    154     */
    155    boolean getBoolean(String key);
    156
    157    /**
    158     * Get a boolean associated with the given configuration key. If the key doesn't map
    159     * to an existing object, the default value is returned.
    160     *
    161     * @param key The configuration key.
    162     * @param defaultValue The default value.
    163     * @return The associated boolean.
    164     * @throws org.apache.commons.configuration2.ex.ConversionException is thrown if the
    165     * key maps to an object that is not a Boolean.
    166     */
    167    boolean getBoolean(String key, boolean defaultValue);
    168
    169    /**
    170     * Get a {@link Boolean} associated with the given configuration key.
    171     *
    172     * @param key The configuration key.
    173     * @param defaultValue The default value.
    174     * @return The associated boolean if key is found and has valid format, default value
    175     * otherwise.
    176     * @throws org.apache.commons.configuration2.ex.ConversionException is thrown if the
    177     * key maps to an object that is not a Boolean.
    178     */
    179    Boolean getBoolean(String key, Boolean defaultValue);
    180
    181    /**
    182     * Get a byte associated with the given configuration key.
    183     *
    184     * @param key The configuration key.
    185     * @return The associated byte.
    186     * @throws org.apache.commons.configuration2.ex.ConversionException is thrown if the
    187     * key maps to an object that is not a Byte.
    188     */
    189    byte getByte(String key);
    190
    191    /**
    192     * Get a byte associated with the given configuration key. If the key doesn't map to
    193     * an existing object, the default value is returned.
    194     *
    195     * @param key The configuration key.
    196     * @param defaultValue The default value.
    197     * @return The associated byte.
    198     * @throws org.apache.commons.configuration2.ex.ConversionException is thrown if the
    199     * key maps to an object that is not a Byte.
    200     */
    201    byte getByte(String key, byte defaultValue);
    202
    203    /**
    204     * Get a {@link Byte} associated with the given configuration key.
    205     *
    206     * @param key The configuration key.
    207     * @param defaultValue The default value.
    208     * @return The associated byte if key is found and has valid format, default value
    209     * otherwise.
    210     * @throws org.apache.commons.configuration2.ex.ConversionException is thrown if the
    211     * key maps to an object that is not a Byte.
    212     */
    213    Byte getByte(String key, Byte defaultValue);
    214
    215    /**
    216     * Get a double associated with the given configuration key.
    217     *
    218     * @param key The configuration key.
    219     * @return The associated double.
    220     * @throws org.apache.commons.configuration2.ex.ConversionException is thrown if the
    221     * key maps to an object that is not a Double.
    222     */
    223    double getDouble(String key);
    224
    225    /**
    226     * Get a double associated with the given configuration key. If the key doesn't map to
    227     * an existing object, the default value is returned.
    228     *
    229     * @param key The configuration key.
    230     * @param defaultValue The default value.
    231     * @return The associated double.
    232     * @throws org.apache.commons.configuration2.ex.ConversionException is thrown if the
    233     * key maps to an object that is not a Double.
    234     */
    235    double getDouble(String key, double defaultValue);
    236
    237    /**
    238     * Get a {@link Double} associated with the given configuration key.
    239     *
    240     * @param key The configuration key.
    241     * @param defaultValue The default value.
    242     * @return The associated double if key is found and has valid format, default value
    243     * otherwise.
    244     * @throws org.apache.commons.configuration2.ex.ConversionException is thrown if the
    245     * key maps to an object that is not a Double.
    246     */
    247    Double getDouble(String key, Double defaultValue);
    248
    249    /**
    250     * Get a float associated with the given configuration key.
    251     *
    252     * @param key The configuration key.
    253     * @return The associated float.
    254     * @throws org.apache.commons.configuration2.ex.ConversionException is thrown if the
    255     * key maps to an object that is not a Float.
    256     */
    257    float getFloat(String key);
    258
    259    /**
    260     * Get a float associated with the given configuration key. If the key doesn't map to
    261     * an existing object, the default value is returned.
    262     *
    263     * @param key The configuration key.
    264     * @param defaultValue The default value.
    265     * @return The associated float.
    266     * @throws org.apache.commons.configuration2.ex.ConversionException is thrown if the
    267     * key maps to an object that is not a Float.
    268     */
    269    float getFloat(String key, float defaultValue);
    270
    271    /**
    272     * Get a {@link Float} associated with the given configuration key. If the key doesn't
    273     * map to an existing object, the default value is returned.
    274     *
    275     * @param key The configuration key.
    276     * @param defaultValue The default value.
    277     * @return The associated float if key is found and has valid format, default value
    278     * otherwise.
    279     * @throws org.apache.commons.configuration2.ex.ConversionException is thrown if the
    280     * key maps to an object that is not a Float.
    281     */
    282    Float getFloat(String key, Float defaultValue);
    283
    284    /**
    285     * Get a int associated with the given configuration key.
    286     *
    287     * @param key The configuration key.
    288     * @return The associated int.
    289     * @throws org.apache.commons.configuration2.ex.ConversionException is thrown if the
    290     * key maps to an object that is not a Integer.
    291     */
    292    int getInt(String key);
    293
    294    /**
    295     * Get a int associated with the given configuration key. If the key doesn't map to an
    296     * existing object, the default value is returned.
    297     *
    298     * @param key The configuration key.
    299     * @param defaultValue The default value.
    300     * @return The associated int.
    301     * @throws org.apache.commons.configuration2.ex.ConversionException is thrown if the
    302     * key maps to an object that is not a Integer.
    303     */
    304    int getInt(String key, int defaultValue);
    305
    306    /**
    307     * Get an {@link Integer} associated with the given configuration key. If the key
    308     * doesn't map to an existing object, the default value is returned.
    309     *
    310     * @param key The configuration key.
    311     * @param defaultValue The default value.
    312     * @return The associated int if key is found and has valid format, default value
    313     * otherwise.
    314     * @throws org.apache.commons.configuration2.ex.ConversionException is thrown if the
    315     * key maps to an object that is not a Integer.
    316     */
    317    Integer getInteger(String key, Integer defaultValue);
    318
    319    /**
    320     * Get a long associated with the given configuration key.
    321     *
    322     * @param key The configuration key.
    323     * @return The associated long.
    324     * @throws org.apache.commons.configuration2.ex.ConversionException is thrown if the
    325     * key maps to an object that is not a Long.
    326     */
    327    long getLong(String key);
    328
    329    /**
    330     * Get a long associated with the given configuration key.
    331     * If the key doesn't map to an existing object, the default value
    332     * is returned.
    333     *
    334     * @param key The configuration key.
    335     * @param defaultValue The default value.
    336     * @return The associated long.
    337     *
    338     * @throws org.apache.commons.configuration2.ex.ConversionException is thrown if the key maps to an
    339     *         object that is not a Long.
    340     */
    341    long getLong(String key, long defaultValue);
    342
    343    /**
    344     * Get a {@link Long} associated with the given configuration key.
    345     * If the key doesn't map to an existing object, the default value
    346     * is returned.
    347     *
    348     * @param key The configuration key.
    349     * @param defaultValue The default value.
    350     * @return The associated long if key is found and has valid
    351     * format, default value otherwise.
    352     *
    353     * @throws org.apache.commons.configuration2.ex.ConversionException is thrown if the key maps to an
    354     *         object that is not a Long.
    355     */
    356    Long getLong(String key, Long defaultValue);
    357
    358    /**
    359     * Get a short associated with the given configuration key.
    360     *
    361     * @param key The configuration key.
    362     * @return The associated short.
    363     *
    364     * @throws org.apache.commons.configuration2.ex.ConversionException is thrown if the key maps to an
    365     *         object that is not a Short.
    366     */
    367    short getShort(String key);
    368
    369    /**
    370     * Get a short associated with the given configuration key.
    371     *
    372     * @param key The configuration key.
    373     * @param defaultValue The default value.
    374     * @return The associated short.
    375     *
    376     * @throws org.apache.commons.configuration2.ex.ConversionException is thrown if the key maps to an
    377     *         object that is not a Short.
    378     */
    379    short getShort(String key, short defaultValue);
    380
    381    /**
    382     * Get a {@link Short} associated with the given configuration key.
    383     * If the key doesn't map to an existing object, the default value
    384     * is returned.
    385     *
    386     * @param key The configuration key.
    387     * @param defaultValue The default value.
    388     * @return The associated short if key is found and has valid
    389     *         format, default value otherwise.
    390     *
    391     * @throws org.apache.commons.configuration2.ex.ConversionException is thrown if the key maps to an
    392     *         object that is not a Short.
    393     */
    394    Short getShort(String key, Short defaultValue);
    395
    396    /**
    397     * Get a {@link BigDecimal} associated with the given configuration key.
    398     *
    399     * @param key The configuration key.
    400     * @return The associated BigDecimal if key is found and has valid format
    401     */
    402    BigDecimal getBigDecimal(String key);
    403
    404    /**
    405     * Get a {@link BigDecimal} associated with the given configuration key.
    406     * If the key doesn't map to an existing object, the default value
    407     * is returned.
    408     *
    409     * @param key          The configuration key.
    410     * @param defaultValue The default value.
    411     *
    412     * @return The associated BigDecimal if key is found and has valid
    413     *         format, default value otherwise.
    414     */
    415    BigDecimal getBigDecimal(String key, BigDecimal defaultValue);
    416
    417    /**
    418     * Get a {@link BigInteger} associated with the given configuration key.
    419     *
    420     * @param key The configuration key.
    421     *
    422     * @return The associated BigInteger if key is found and has valid format
    423     */
    424    BigInteger getBigInteger(String key);
    425
    426    /**
    427     * Get a {@link BigInteger} associated with the given configuration key.
    428     * If the key doesn't map to an existing object, the default value
    429     * is returned.
    430     *
    431     * @param key          The configuration key.
    432     * @param defaultValue The default value.
    433     *
    434     * @return The associated BigInteger if key is found and has valid
    435     *         format, default value otherwise.
    436     */
    437    BigInteger getBigInteger(String key, BigInteger defaultValue);
    438
    439    /**
    440     * Get a string associated with the given configuration key.
    441     *
    442     * @param key The configuration key.
    443     * @return The associated string.
    444     *
    445     * @throws org.apache.commons.configuration2.ex.ConversionException is thrown if the key maps to an object that
    446     *         is not a String.
    447     */
    448    String getString(String key);
    449
    450    /**
    451     * Get a string associated with the given configuration key.
    452     * If the key doesn't map to an existing object, the default value
    453     * is returned.
    454     *
    455     * @param key The configuration key.
    456     * @param defaultValue The default value.
    457     * @return The associated string if key is found and has valid
    458     *         format, default value otherwise.
    459     *
    460     * @throws org.apache.commons.configuration2.ex.ConversionException is thrown if the key maps to an object that
    461     *         is not a String.
    462     */
    463    String getString(String key, String defaultValue);
    464
    465    /**
    466     * Get the value of a string property that is stored in encoded form in this
    467     * configuration. This method obtains the value of the string property
    468     * identified by the given key. This value is then passed to the provided
    469     * {@code ConfigurationDecoder}. The value returned by the
    470     * {@code ConfigurationDecoder} is passed to the caller. If the key is not
    471     * associated with a value, the decoder is not invoked; depending on this
    472     * configuration's settings either <b>null</b> is returned or an exception
    473     * is thrown.
    474     *
    475     * @param key the configuration key
    476     * @param decoder the {@code ConfigurationDecoder} (must not be <b>null</b>)
    477     * @return the plain string value of the specified encoded property
    478     * @throws IllegalArgumentException if a <b>null</b> decoder is passed
    479     */
    480    String getEncodedString(String key, ConfigurationDecoder decoder);
    481
    482    /**
    483     * Get the value of a string property that is stored in encoded form in this
    484     * configuration using a default {@code ConfigurationDecoder}. This method
    485     * works like the method with the same name, but it uses a default
    486     * {@code ConfigurationDecoder} associated with this configuration. It
    487     * depends on a specific implementation how this default decoder is
    488     * obtained.
    489     *
    490     * @param key the configuration key
    491     * @return the plain string value of the specified encoded property
    492     */
    493    String getEncodedString(String key);
    494
    495    /**
    496     * Get an array of strings associated with the given configuration key.
    497     * If the key doesn't map to an existing object an empty array is returned
    498     *
    499     * @param key The configuration key.
    500     * @return The associated string array if key is found.
    501     *
    502     * @throws org.apache.commons.configuration2.ex.ConversionException is thrown if the key maps to an
    503     *         object that is not a String/List of Strings.
    504     */
    505    String[] getStringArray(String key);
    506
    507    /**
    508     * Get a List of the values associated with the given configuration key.
    509     * This method is different from the generic {@code getList()} method in
    510     * that it does not recursively obtain all values stored for the specified
    511     * property key. Rather, only the first level of the hierarchy is processed.
    512     * So the resulting list may contain complex objects like arrays or
    513     * collections - depending on the storage structure used by a concrete
    514     * subclass. If the key doesn't map to an existing object, an empty List is
    515     * returned.
    516     *
    517     * @param key The configuration key.
    518     * @return The associated List.
    519     *
    520     * @throws org.apache.commons.configuration2.ex.ConversionException is thrown if the key maps to an
    521     *         object that is not a List.
    522     */
    523    List<Object> getList(String key);
    524
    525    /**
    526     * Get a List of strings associated with the given configuration key.
    527     * If the key doesn't map to an existing object, the default value
    528     * is returned.
    529     *
    530     * @param key The configuration key.
    531     * @param defaultValue The default value.
    532     * @return The associated List of strings.
    533     *
    534     * @throws org.apache.commons.configuration2.ex.ConversionException is thrown if the key maps to an
    535     *         object that is not a List.
    536     * @see #getList(Class, String, List)
    537     */
    538    List<Object> getList(String key, List<?> defaultValue);
    539
    540    /**
    541     * Get an object of the specified type associated with the given
    542     * configuration key. If the key doesn't map to an existing object, the
    543     * method returns null unless
    544     * {@link AbstractConfiguration#isThrowExceptionOnMissing()} is set to
    545     * {@code true}.
    546     *
    547     * @param <T> the target type of the value
    548     * @param cls the target class of the value
    549     * @param key the key of the value
    550     * @return the value of the requested type for the key
    551     * @throws java.util.NoSuchElementException if the key doesn't map to an existing
    552     *         object and {@code throwExceptionOnMissing=true}
    553     * @throws org.apache.commons.configuration2.ex.ConversionException if the value is not compatible with the
    554     *         requested type
    555     * @since 2.0
    556     */
    557    <T> T get(Class<T> cls, String key);
    558
    559    /**
    560     * Get an object of the specified type associated with the given
    561     * configuration key using a default value. If the key doesn't map to an
    562     * existing object, the default value is returned.
    563     *
    564     * @param <T>          the target type of the value
    565     * @param cls          the target class of the value
    566     * @param key          the key of the value
    567     * @param defaultValue the default value
    568     *
    569     * @return the value of the requested type for the key
    570     *
    571     * @throws org.apache.commons.configuration2.ex.ConversionException if the value is not
    572     * compatible with the requested type
    573     *
    574     * @since 2.0
    575     */
    576    <T> T get(Class<T> cls, String key, T defaultValue);
    577
    578    /**
    579     * Get an array of typed objects associated with the given configuration key.
    580     * If the key doesn't map to an existing object, an empty list is returned.
    581     *
    582     * @param cls the type expected for the elements of the array
    583     * @param key The configuration key.
    584     * @return The associated array if the key is found, and the value compatible with the type specified.
    585     *
    586     * @throws org.apache.commons.configuration2.ex.ConversionException is thrown if the key maps to an object that
    587     *     is not compatible with a list of the specified class.
    588     *
    589     * @since 2.0
    590     */
    591    Object getArray(Class<?> cls, String key);
    592
    593    /**
    594     * Get an array of typed objects associated with the given configuration key.
    595     * If the key doesn't map to an existing object, the default value is returned.
    596     *
    597     * @param cls          the type expected for the elements of the array
    598     * @param key          the configuration key.
    599     * @param defaultValue the default value
    600     * @return The associated array if the key is found, and the value compatible with the type specified.
    601     *
    602     * @throws org.apache.commons.configuration2.ex.ConversionException is thrown if the key maps to an object that
    603     *     is not compatible with an array of the specified class.
    604     * @throws IllegalArgumentException if the default value is not an array of the specified type
    605     *
    606     * @since 2.0
    607     * @deprecated This method should not be used any more because its signature
    608     * does not allow type-safe invocations; use {@link #get(Class, String, Object)}
    609     * instead which offers the same functionality; for instance, to query for an
    610     * array of ints use
    611     * {@code int[] result = config.get(int[].class, "myArrayKey", someDefault);}.
    612     */
    613    @Deprecated
    614    Object getArray(Class<?> cls, String key, Object defaultValue);
    615
    616    /**
    617     * Get a list of typed objects associated with the given configuration key
    618     * returning an empty list if the key doesn't map to an existing object.
    619     *
    620     * @param <T> the type expected for the elements of the list
    621     * @param cls the class expected for the elements of the list
    622     * @param key The configuration key.
    623     * @return The associated list if the key is found.
    624     *
    625     * @throws org.apache.commons.configuration2.ex.ConversionException is thrown if the key maps to an object that
    626     *     is not compatible with a list of the specified class.
    627     *
    628     * @since 2.0
    629     */
    630    <T> List<T> getList(Class<T> cls, String key);
    631
    632    /**
    633     * Get a list of typed objects associated with the given configuration key
    634     * returning the specified default value if the key doesn't map to an
    635     * existing object. This method recursively retrieves all values stored
    636     * for the passed in key, i.e. if one of these values is again a complex
    637     * object like an array or a collection (which may be the case for some
    638     * concrete subclasses), all values are extracted and added to the
    639     * resulting list - performing a type conversion if necessary.
    640     *
    641     * @param <T>          the type expected for the elements of the list
    642     * @param cls          the class expected for the elements of the list
    643     * @param key          the configuration key.
    644     * @param defaultValue the default value.
    645     * @return The associated List.
    646     *
    647     * @throws org.apache.commons.configuration2.ex.ConversionException is thrown if the key maps to an object that
    648     *     is not compatible with a list of the specified class.
    649     *
    650     * @since 2.0
    651     */
    652    <T> List<T> getList(Class<T> cls, String key, List<T> defaultValue);
    653
    654    /**
    655     * Get a collection of typed objects associated with the given configuration
    656     * key. This method works like
    657     * {@link #getCollection(Class, String, Collection, Collection)} passing in
    658     * <b>null</b> as default value.
    659     *
    660     * @param <T> the element type of the result list
    661     * @param cls the the element class of the result list
    662     * @param key the configuration key
    663     * @param target the target collection (may be <b>null</b>)
    664     * @return the collection to which data was added
    665     * @throws org.apache.commons.configuration2.ex.ConversionException if the conversion is not possible
    666     * @since 2.0
    667     */
    668    <T> Collection<T> getCollection(Class<T> cls, String key,
    669            Collection<T> target);
    670
    671    /**
    672     * Get a collection of typed objects associated with the given configuration
    673     * key using the values in the specified default collection if the key does
    674     * not map to an existing object. This method is similar to
    675     * {@code getList()}, however, it allows specifying a target collection.
    676     * Results are added to this collection. This is useful if the data
    677     * retrieved should be added to a specific kind of collection, e.g. a set to
    678     * remove duplicates. The return value is as follows:
    679     * <ul>
    680     * <li>If the key does not map to an existing object and the default value
    681     * is <b>null</b>, the method returns <b>null</b>.</li>
    682     * <li>If the target collection is not <b>null</b> and data has been added
    683     * (either from the resolved property value or from the default collection),
    684     * the target collection is returned.</li>
    685     * <li>If the target collection is <b>null</b> and data has been added
    686     * (either from the resolved property value or from the default collection),
    687     * return value is the target collection created by this method.</li>
    688     * </ul>
    689     *
    690     * @param <T> the element type of the result list
    691     * @param cls the the element class of the result list
    692     * @param key the configuration key
    693     * @param target the target collection (may be <b>null</b>)
    694     * @param defaultValue the default value (may be <b>null</b>)
    695     * @return the collection to which data was added
    696     * @throws org.apache.commons.configuration2.ex.ConversionException if the conversion is not possible
    697     * @since 2.0
    698     */
    699    <T> Collection<T> getCollection(Class<T> cls, String key,
    700            Collection<T> target, Collection<T> defaultValue);
    701
    702    /**
    703     * Return a decorator immutable Configuration containing every key from the current
    704     * Configuration that starts with the specified prefix. The prefix is
    705     * removed from the keys in the subset. For example, if the configuration
    706     * contains the following properties:
    707     *
    708     * <pre>
    709     *    prefix.number = 1
    710     *    prefix.string = Apache
    711     *    prefixed.foo = bar
    712     *    prefix = Jakarta</pre>
    713     *
    714     * the immutable Configuration returned by {@code subset("prefix")} will contain
    715     * the properties:
    716     *
    717     * <pre>
    718     *    number = 1
    719     *    string = Apache
    720     *    = Jakarta</pre>
    721     *
    722     * (The key for the value "Jakarta" is an empty string)
    723     *
    724     * @param prefix The prefix used to select the properties.
    725     * @return a subset immutable configuration
    726     */
    727    ImmutableConfiguration immutableSubset(String prefix);
    728
    729
    730}