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