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}