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