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}