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 */ 017 018package org.apache.commons.configuration; 019 020import java.math.BigDecimal; 021import java.math.BigInteger; 022import java.util.Iterator; 023import java.util.List; 024import java.util.Properties; 025 026/** 027 * <p>The main Configuration interface.</p> 028 * <p>This interface allows accessing and manipulating a configuration object. 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 * <p>With the {@code addProperty()} and {@code setProperty()} methods 049 * new properties can be added to a configuration or the values of properties 050 * can be changed. With {@code clearProperty()} a property can be removed. 051 * Other methods allow to iterate over the contained properties or to create 052 * a subset configuration.</p> 053 * 054 * @author Commons Configuration team 055 * @version $Id: Configuration.java 1534064 2013-10-21 08:44:33Z henning $ 056 */ 057public interface Configuration 058{ 059 /** 060 * Return a decorator Configuration containing every key from the current 061 * Configuration that starts with the specified prefix. The prefix is 062 * removed from the keys in the subset. For example, if the configuration 063 * contains the following properties: 064 * 065 * <pre> 066 * prefix.number = 1 067 * prefix.string = Apache 068 * prefixed.foo = bar 069 * prefix = Jakarta</pre> 070 * 071 * the Configuration returned by {@code subset("prefix")} will contain 072 * the properties: 073 * 074 * <pre> 075 * number = 1 076 * string = Apache 077 * = Jakarta</pre> 078 * 079 * (The key for the value "Jakarta" is an empty string) 080 * <p> 081 * Since the subset is a decorator and not a modified copy of the initial 082 * Configuration, any change made to the subset is available to the 083 * Configuration, and reciprocally. 084 * 085 * @param prefix The prefix used to select the properties. 086 * @return a subset configuration 087 * 088 * @see SubsetConfiguration 089 */ 090 Configuration subset(String prefix); 091 092 /** 093 * Check if the configuration is empty. 094 * 095 * @return {@code true} if the configuration contains no property, 096 * {@code false} otherwise. 097 */ 098 boolean isEmpty(); 099 100 /** 101 * Check if the configuration contains the specified key. 102 * 103 * @param key the key whose presence in this configuration is to be tested 104 * 105 * @return {@code true} if the configuration contains a value for this 106 * key, {@code false} otherwise 107 */ 108 boolean containsKey(String key); 109 110 /** 111 * Add a property to the configuration. If it already exists then the value 112 * stated here will be added to the configuration entry. For example, if 113 * the property: 114 * 115 * <pre>resource.loader = file</pre> 116 * 117 * is already present in the configuration and you call 118 * 119 * <pre>addProperty("resource.loader", "classpath")</pre> 120 * 121 * Then you will end up with a List like the following: 122 * 123 * <pre>["file", "classpath"]</pre> 124 * 125 * @param key The key to add the property to. 126 * @param value The value to add. 127 */ 128 void addProperty(String key, Object value); 129 130 /** 131 * Set a property, this will replace any previously set values. Set values 132 * is implicitly a call to clearProperty(key), addProperty(key, value). 133 * 134 * @param key The key of the property to change 135 * @param value The new value 136 */ 137 void setProperty(String key, Object value); 138 139 /** 140 * Remove a property from the configuration. 141 * 142 * @param key the key to remove along with corresponding value. 143 */ 144 void clearProperty(String key); 145 146 /** 147 * Remove all properties from the configuration. 148 */ 149 void clear(); 150 151 /** 152 * Gets a property from the configuration. This is the most basic get 153 * method for retrieving values of properties. In a typical implementation 154 * of the {@code Configuration} interface the other get methods (that 155 * return specific data types) will internally make use of this method. On 156 * this level variable substitution is not yet performed. The returned 157 * object is an internal representation of the property value for the passed 158 * in key. It is owned by the {@code Configuration} object. So a caller 159 * should not modify this object. It cannot be guaranteed that this object 160 * will stay constant over time (i.e. further update operations on the 161 * configuration may change its internal state). 162 * 163 * @param key property to retrieve 164 * @return the value to which this configuration maps the specified key, or 165 * null if the configuration contains no mapping for this key. 166 */ 167 Object getProperty(String key); 168 169 /** 170 * Get the list of the keys contained in the configuration that match the 171 * specified prefix. For instance, if the configuration contains the 172 * following keys:<br> 173 * {@code db.user, db.pwd, db.url, window.xpos, window.ypos},<br> 174 * an invocation of {@code getKeys("db");}<br> 175 * will return the keys below:<br> 176 * {@code db.user, db.pwd, db.url}.<br> 177 * Note that the prefix itself is included in the result set if there is a 178 * matching key. The exact behavior - how the prefix is actually 179 * interpreted - depends on a concrete implementation. 180 * 181 * @param prefix The prefix to test against. 182 * @return An Iterator of keys that match the prefix. 183 * @see #getKeys() 184 */ 185 Iterator<String> getKeys(String prefix); 186 187 /** 188 * Get the list of the keys contained in the configuration. The returned 189 * iterator can be used to obtain all defined keys. Note that the exact 190 * behavior of the iterator's {@code remove()} method is specific to 191 * a concrete implementation. It <em>may</em> remove the corresponding 192 * property from the configuration, but this is not guaranteed. In any case 193 * it is no replacement for calling 194 * {@link #clearProperty(String)} for this property. So it is 195 * highly recommended to avoid using the iterator's {@code remove()} 196 * method. 197 * 198 * @return An Iterator. 199 */ 200 Iterator<String> getKeys(); 201 202 /** 203 * Get a list of properties associated with the given configuration key. 204 * This method expects the given key to have an arbitrary number of String 205 * values, each of which is of the form {code key=value}. These 206 * strings are split at the equals sign, and the key parts will become 207 * keys of the returned {@code Properties} object, the value parts 208 * become values. 209 * 210 * @param key The configuration key. 211 * @return The associated properties if key is found. 212 * 213 * @throws ConversionException is thrown if the key maps to an 214 * object that is not a String/List. 215 * 216 * @throws IllegalArgumentException if one of the tokens is 217 * malformed (does not contain an equals sign). 218 */ 219 Properties getProperties(String key); 220 221 /** 222 * Get a boolean associated with the given configuration key. 223 * 224 * @param key The configuration key. 225 * @return The associated boolean. 226 * 227 * @throws ConversionException is thrown if the key maps to an 228 * object that is not a Boolean. 229 */ 230 boolean getBoolean(String key); 231 232 /** 233 * Get a boolean associated with the given configuration key. 234 * If the key doesn't map to an existing object, the default value 235 * is returned. 236 * 237 * @param key The configuration key. 238 * @param defaultValue The default value. 239 * @return The associated boolean. 240 * 241 * @throws ConversionException is thrown if the key maps to an 242 * object that is not a Boolean. 243 */ 244 boolean getBoolean(String key, boolean defaultValue); 245 246 /** 247 * Get a {@link Boolean} associated with the given configuration key. 248 * 249 * @param key The configuration key. 250 * @param defaultValue The default value. 251 * @return The associated boolean if key is found and has valid 252 * format, default value otherwise. 253 * 254 * @throws ConversionException is thrown if the key maps to an 255 * object that is not a Boolean. 256 */ 257 Boolean getBoolean(String key, Boolean defaultValue); 258 259 /** 260 * Get a byte associated with the given configuration key. 261 * 262 * @param key The configuration key. 263 * @return The associated byte. 264 * 265 * @throws ConversionException is thrown if the key maps to an 266 * object that is not a Byte. 267 */ 268 byte getByte(String key); 269 270 /** 271 * Get a byte associated with the given configuration key. 272 * If the key doesn't map to an existing object, the default value 273 * is returned. 274 * 275 * @param key The configuration key. 276 * @param defaultValue The default value. 277 * @return The associated byte. 278 * 279 * @throws ConversionException is thrown if the key maps to an 280 * object that is not a Byte. 281 */ 282 byte getByte(String key, byte defaultValue); 283 284 /** 285 * Get a {@link Byte} associated with the given configuration key. 286 * 287 * @param key The configuration key. 288 * @param defaultValue The default value. 289 * @return The associated byte if key is found and has valid format, default 290 * value otherwise. 291 * 292 * @throws ConversionException is thrown if the key maps to an object that 293 * is not a Byte. 294 */ 295 Byte getByte(String key, Byte defaultValue); 296 297 /** 298 * Get a double associated with the given configuration key. 299 * 300 * @param key The configuration key. 301 * @return The associated double. 302 * 303 * @throws ConversionException is thrown if the key maps to an 304 * object that is not a Double. 305 */ 306 double getDouble(String key); 307 308 /** 309 * Get a double associated with the given configuration key. 310 * If the key doesn't map to an existing object, the default value 311 * is returned. 312 * 313 * @param key The configuration key. 314 * @param defaultValue The default value. 315 * @return The associated double. 316 * 317 * @throws ConversionException is thrown if the key maps to an 318 * object that is not a Double. 319 */ 320 double getDouble(String key, double defaultValue); 321 322 /** 323 * Get a {@link Double} associated with the given configuration key. 324 * 325 * @param key The configuration key. 326 * @param defaultValue The default value. 327 * @return The associated double if key is found and has valid 328 * format, default value otherwise. 329 * 330 * @throws ConversionException is thrown if the key maps to an 331 * object that is not a Double. 332 */ 333 Double getDouble(String key, Double defaultValue); 334 335 /** 336 * Get a float associated with the given configuration key. 337 * 338 * @param key The configuration key. 339 * @return The associated float. 340 * @throws ConversionException is thrown if the key maps to an 341 * object that is not a Float. 342 */ 343 float getFloat(String key); 344 345 /** 346 * Get a float associated with the given configuration key. 347 * If the key doesn't map to an existing object, the default value 348 * is returned. 349 * 350 * @param key The configuration key. 351 * @param defaultValue The default value. 352 * @return The associated float. 353 * 354 * @throws ConversionException is thrown if the key maps to an 355 * object that is not a Float. 356 */ 357 float getFloat(String key, float defaultValue); 358 359 /** 360 * Get a {@link Float} associated with the given configuration key. 361 * If the key doesn't map to an existing object, the default value 362 * is returned. 363 * 364 * @param key The configuration key. 365 * @param defaultValue The default value. 366 * @return The associated float if key is found and has valid 367 * format, default value otherwise. 368 * 369 * @throws ConversionException is thrown if the key maps to an 370 * object that is not a Float. 371 */ 372 Float getFloat(String key, Float defaultValue); 373 374 /** 375 * Get a int associated with the given configuration key. 376 * 377 * @param key The configuration key. 378 * @return The associated int. 379 * 380 * @throws ConversionException is thrown if the key maps to an 381 * object that is not a Integer. 382 */ 383 int getInt(String key); 384 385 /** 386 * Get a int associated with the given configuration key. 387 * If the key doesn't map to an existing object, the default value 388 * is returned. 389 * 390 * @param key The configuration key. 391 * @param defaultValue The default value. 392 * @return The associated int. 393 * 394 * @throws ConversionException is thrown if the key maps to an 395 * object that is not a Integer. 396 */ 397 int getInt(String key, int defaultValue); 398 399 /** 400 * Get an {@link Integer} associated with the given configuration key. 401 * If the key doesn't map to an existing object, the default value 402 * is returned. 403 * 404 * @param key The configuration key. 405 * @param defaultValue The default value. 406 * @return The associated int if key is found and has valid format, default 407 * value otherwise. 408 * 409 * @throws ConversionException is thrown if the key maps to an object that 410 * is not a Integer. 411 */ 412 Integer getInteger(String key, Integer defaultValue); 413 414 /** 415 * Get a long associated with the given configuration key. 416 * 417 * @param key The configuration key. 418 * @return The associated long. 419 * 420 * @throws ConversionException is thrown if the key maps to an 421 * object that is not a Long. 422 */ 423 long getLong(String key); 424 425 /** 426 * Get a long 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 * @return The associated long. 433 * 434 * @throws ConversionException is thrown if the key maps to an 435 * object that is not a Long. 436 */ 437 long getLong(String key, long defaultValue); 438 439 /** 440 * Get a {@link Long} associated with the given configuration key. 441 * If the key doesn't map to an existing object, the default value 442 * is returned. 443 * 444 * @param key The configuration key. 445 * @param defaultValue The default value. 446 * @return The associated long if key is found and has valid 447 * format, default value otherwise. 448 * 449 * @throws ConversionException is thrown if the key maps to an 450 * object that is not a Long. 451 */ 452 Long getLong(String key, Long defaultValue); 453 454 /** 455 * Get a short associated with the given configuration key. 456 * 457 * @param key The configuration key. 458 * @return The associated short. 459 * 460 * @throws ConversionException is thrown if the key maps to an 461 * object that is not a Short. 462 */ 463 short getShort(String key); 464 465 /** 466 * Get a short associated with the given configuration key. 467 * 468 * @param key The configuration key. 469 * @param defaultValue The default value. 470 * @return The associated short. 471 * 472 * @throws ConversionException is thrown if the key maps to an 473 * object that is not a Short. 474 */ 475 short getShort(String key, short defaultValue); 476 477 /** 478 * Get a {@link Short} associated with the given configuration key. 479 * If the key doesn't map to an existing object, the default value 480 * is returned. 481 * 482 * @param key The configuration key. 483 * @param defaultValue The default value. 484 * @return The associated short if key is found and has valid 485 * format, default value otherwise. 486 * 487 * @throws ConversionException is thrown if the key maps to an 488 * object that is not a Short. 489 */ 490 Short getShort(String key, Short defaultValue); 491 492 /** 493 * Get a {@link BigDecimal} associated with the given configuration key. 494 * 495 * @param key The configuration key. 496 * @return The associated BigDecimal if key is found and has valid format 497 */ 498 BigDecimal getBigDecimal(String key); 499 500 /** 501 * Get a {@link BigDecimal} associated with the given configuration key. 502 * If the key doesn't map to an existing object, the default value 503 * is returned. 504 * 505 * @param key The configuration key. 506 * @param defaultValue The default value. 507 * 508 * @return The associated BigDecimal if key is found and has valid 509 * format, default value otherwise. 510 */ 511 BigDecimal getBigDecimal(String key, BigDecimal defaultValue); 512 513 /** 514 * Get a {@link BigInteger} associated with the given configuration key. 515 * 516 * @param key The configuration key. 517 * 518 * @return The associated BigInteger if key is found and has valid format 519 */ 520 BigInteger getBigInteger(String key); 521 522 /** 523 * Get a {@link BigInteger} associated with the given configuration key. 524 * If the key doesn't map to an existing object, the default value 525 * is returned. 526 * 527 * @param key The configuration key. 528 * @param defaultValue The default value. 529 * 530 * @return The associated BigInteger if key is found and has valid 531 * format, default value otherwise. 532 */ 533 BigInteger getBigInteger(String key, BigInteger defaultValue); 534 535 /** 536 * Get a string associated with the given configuration key. 537 * 538 * @param key The configuration key. 539 * @return The associated string. 540 * 541 * @throws ConversionException is thrown if the key maps to an object that 542 * is not a String. 543 */ 544 String getString(String key); 545 546 /** 547 * Get a string associated with the given configuration key. 548 * If the key doesn't map to an existing object, the default value 549 * is returned. 550 * 551 * @param key The configuration key. 552 * @param defaultValue The default value. 553 * @return The associated string if key is found and has valid 554 * format, default value otherwise. 555 * 556 * @throws ConversionException is thrown if the key maps to an object that 557 * is not a String. 558 */ 559 String getString(String key, String defaultValue); 560 561 /** 562 * Get an array of strings associated with the given configuration key. 563 * If the key doesn't map to an existing object an empty array is returned 564 * 565 * @param key The configuration key. 566 * @return The associated string array if key is found. 567 * 568 * @throws ConversionException is thrown if the key maps to an 569 * object that is not a String/List of Strings. 570 */ 571 String[] getStringArray(String key); 572 573 /** 574 * Get a List of strings associated with the given configuration key. 575 * If the key doesn't map to an existing object an empty List is returned. 576 * 577 * @param key The configuration key. 578 * @return The associated List. 579 * 580 * @throws ConversionException is thrown if the key maps to an 581 * object that is not a List. 582 */ 583 List<Object> getList(String key); 584 585 /** 586 * Get a List of strings associated with the given configuration key. 587 * If the key doesn't map to an existing object, the default value 588 * is returned. 589 * 590 * @param key The configuration key. 591 * @param defaultValue The default value. 592 * @return The associated List of strings. 593 * 594 * @throws ConversionException is thrown if the key maps to an 595 * object that is not a List. 596 */ 597 List<Object> getList(String key, List<?> defaultValue); 598}