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