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}