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