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