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