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 018 package org.apache.commons.configuration; 019 020 import java.math.BigDecimal; 021 import java.math.BigInteger; 022 import java.util.Iterator; 023 import java.util.List; 024 import 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()</code> 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</code> 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 * <code>{@link AbstractConfiguration}</code> 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 * <code>{@link org.apache.commons.configuration.AbstractConfiguration#setThrowExceptionOnMissing(boolean) 043 * setThrowExceptionOnMissing()}</code> 044 * method, with which it can be configured to throw a <code>NoSuchElementException</code> 045 * exception in that case. (Note that getter methods for primitive types in 046 * <code>AbstractConfiguration</code> 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()</code> and <code>setProperty()</code> methods 049 * new properties can be added to a configuration or the values of properties 050 * can be changed. With <code>clearProperty()</code> 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 449017 2006-09-22 17:27:00Z oheger $ 056 */ 057 public 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")</code> 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</code> if the configuration contains no property, 096 * <code>false</code> 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</code> if the configuration contains a value for this 106 * key, <code>false</code> 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</code> 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</code> 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. 172 * 173 * @param prefix The prefix to test against. 174 * @return An Iterator of keys that match the prefix. 175 * @see #getKeys() 176 */ 177 Iterator getKeys(String prefix); 178 179 /** 180 * Get the list of the keys contained in the configuration. The returned 181 * iterator can be used to obtain all defined keys. Note that the exact 182 * behavior of the iterator's <code>remove()</code> method is specific to 183 * a concrete implementation. It <em>may</em> remove the corresponding 184 * property from the configuration, but this is not guaranteed. In any case 185 * it is no replacement for calling 186 * <code>{@link #clearProperty(String)}</code> for this property. So it is 187 * highly recommended to avoid using the iterator's <code>remove()</code> 188 * method. 189 * 190 * @return An Iterator. 191 */ 192 Iterator getKeys(); 193 194 /** 195 * Get a list of properties associated with the given configuration key. 196 * This method expects the given key to have an arbitrary number of String 197 * values, each of which is of the form <code>key=value</code>. These 198 * strings are splitted at the equals sign, and the key parts will become 199 * keys of the returned <code>Properties</code> object, the value parts 200 * become values. 201 * 202 * @param key The configuration key. 203 * @return The associated properties if key is found. 204 * 205 * @throws ConversionException is thrown if the key maps to an 206 * object that is not a String/List. 207 * 208 * @throws IllegalArgumentException if one of the tokens is 209 * malformed (does not contain an equals sign). 210 */ 211 Properties getProperties(String key); 212 213 /** 214 * Get a boolean associated with the given configuration key. 215 * 216 * @param key The configuration key. 217 * @return The associated boolean. 218 * 219 * @throws ConversionException is thrown if the key maps to an 220 * object that is not a Boolean. 221 */ 222 boolean getBoolean(String key); 223 224 /** 225 * Get a boolean associated with the given configuration key. 226 * If the key doesn't map to an existing object, the default value 227 * is returned. 228 * 229 * @param key The configuration key. 230 * @param defaultValue The default value. 231 * @return The associated boolean. 232 * 233 * @throws ConversionException is thrown if the key maps to an 234 * object that is not a Boolean. 235 */ 236 boolean getBoolean(String key, boolean defaultValue); 237 238 /** 239 * Get a {@link Boolean} associated with the given configuration key. 240 * 241 * @param key The configuration key. 242 * @param defaultValue The default value. 243 * @return The associated boolean if key is found and has valid 244 * format, default value otherwise. 245 * 246 * @throws ConversionException is thrown if the key maps to an 247 * object that is not a Boolean. 248 */ 249 Boolean getBoolean(String key, Boolean defaultValue); 250 251 /** 252 * Get a byte associated with the given configuration key. 253 * 254 * @param key The configuration key. 255 * @return The associated byte. 256 * 257 * @throws ConversionException is thrown if the key maps to an 258 * object that is not a Byte. 259 */ 260 byte getByte(String key); 261 262 /** 263 * Get a byte associated with the given configuration key. 264 * If the key doesn't map to an existing object, the default value 265 * is returned. 266 * 267 * @param key The configuration key. 268 * @param defaultValue The default value. 269 * @return The associated byte. 270 * 271 * @throws ConversionException is thrown if the key maps to an 272 * object that is not a Byte. 273 */ 274 byte getByte(String key, byte defaultValue); 275 276 /** 277 * Get a {@link Byte} associated with the given configuration key. 278 * 279 * @param key The configuration key. 280 * @param defaultValue The default value. 281 * @return The associated byte if key is found and has valid format, default 282 * value otherwise. 283 * 284 * @throws ConversionException is thrown if the key maps to an object that 285 * is not a Byte. 286 */ 287 Byte getByte(String key, Byte defaultValue); 288 289 /** 290 * Get a double associated with the given configuration key. 291 * 292 * @param key The configuration key. 293 * @return The associated double. 294 * 295 * @throws ConversionException is thrown if the key maps to an 296 * object that is not a Double. 297 */ 298 double getDouble(String key); 299 300 /** 301 * Get a double associated with the given configuration key. 302 * If the key doesn't map to an existing object, the default value 303 * is returned. 304 * 305 * @param key The configuration key. 306 * @param defaultValue The default value. 307 * @return The associated double. 308 * 309 * @throws ConversionException is thrown if the key maps to an 310 * object that is not a Double. 311 */ 312 double getDouble(String key, double defaultValue); 313 314 /** 315 * Get a {@link Double} associated with the given configuration key. 316 * 317 * @param key The configuration key. 318 * @param defaultValue The default value. 319 * @return The associated double if key is found and has valid 320 * format, default value otherwise. 321 * 322 * @throws ConversionException is thrown if the key maps to an 323 * object that is not a Double. 324 */ 325 Double getDouble(String key, Double defaultValue); 326 327 /** 328 * Get a float associated with the given configuration key. 329 * 330 * @param key The configuration key. 331 * @return The associated float. 332 * @throws ConversionException is thrown if the key maps to an 333 * object that is not a Float. 334 */ 335 float getFloat(String key); 336 337 /** 338 * Get a float associated with the given configuration key. 339 * If the key doesn't map to an existing object, the default value 340 * is returned. 341 * 342 * @param key The configuration key. 343 * @param defaultValue The default value. 344 * @return The associated float. 345 * 346 * @throws ConversionException is thrown if the key maps to an 347 * object that is not a Float. 348 */ 349 float getFloat(String key, float defaultValue); 350 351 /** 352 * Get a {@link Float} associated with the given configuration key. 353 * If the key doesn't map to an existing object, the default value 354 * is returned. 355 * 356 * @param key The configuration key. 357 * @param defaultValue The default value. 358 * @return The associated float if key is found and has valid 359 * format, default value otherwise. 360 * 361 * @throws ConversionException is thrown if the key maps to an 362 * object that is not a Float. 363 */ 364 Float getFloat(String key, Float defaultValue); 365 366 /** 367 * Get a int associated with the given configuration key. 368 * 369 * @param key The configuration key. 370 * @return The associated int. 371 * 372 * @throws ConversionException is thrown if the key maps to an 373 * object that is not a Integer. 374 */ 375 int getInt(String key); 376 377 /** 378 * Get a int associated with the given configuration key. 379 * If the key doesn't map to an existing object, the default value 380 * is returned. 381 * 382 * @param key The configuration key. 383 * @param defaultValue The default value. 384 * @return The associated int. 385 * 386 * @throws ConversionException is thrown if the key maps to an 387 * object that is not a Integer. 388 */ 389 int getInt(String key, int defaultValue); 390 391 /** 392 * Get an {@link Integer} associated with the given configuration key. 393 * If the key doesn't map to an existing object, the default value 394 * is returned. 395 * 396 * @param key The configuration key. 397 * @param defaultValue The default value. 398 * @return The associated int if key is found and has valid format, default 399 * value otherwise. 400 * 401 * @throws ConversionException is thrown if the key maps to an object that 402 * is not a Integer. 403 */ 404 Integer getInteger(String key, Integer defaultValue); 405 406 /** 407 * Get a long associated with the given configuration key. 408 * 409 * @param key The configuration key. 410 * @return The associated long. 411 * 412 * @throws ConversionException is thrown if the key maps to an 413 * object that is not a Long. 414 */ 415 long getLong(String key); 416 417 /** 418 * Get a long associated with the given configuration key. 419 * If the key doesn't map to an existing object, the default value 420 * is returned. 421 * 422 * @param key The configuration key. 423 * @param defaultValue The default value. 424 * @return The associated long. 425 * 426 * @throws ConversionException is thrown if the key maps to an 427 * object that is not a Long. 428 */ 429 long getLong(String key, long defaultValue); 430 431 /** 432 * Get a {@link Long} associated with the given configuration key. 433 * If the key doesn't map to an existing object, the default value 434 * is returned. 435 * 436 * @param key The configuration key. 437 * @param defaultValue The default value. 438 * @return The associated long if key is found and has valid 439 * format, default value otherwise. 440 * 441 * @throws ConversionException is thrown if the key maps to an 442 * object that is not a Long. 443 */ 444 Long getLong(String key, Long defaultValue); 445 446 /** 447 * Get a short associated with the given configuration key. 448 * 449 * @param key The configuration key. 450 * @return The associated short. 451 * 452 * @throws ConversionException is thrown if the key maps to an 453 * object that is not a Short. 454 */ 455 short getShort(String key); 456 457 /** 458 * Get a short associated with the given configuration key. 459 * 460 * @param key The configuration key. 461 * @param defaultValue The default value. 462 * @return The associated short. 463 * 464 * @throws ConversionException is thrown if the key maps to an 465 * object that is not a Short. 466 */ 467 short getShort(String key, short defaultValue); 468 469 /** 470 * Get a {@link Short} associated with the given configuration key. 471 * If the key doesn't map to an existing object, the default value 472 * is returned. 473 * 474 * @param key The configuration key. 475 * @param defaultValue The default value. 476 * @return The associated short if key is found and has valid 477 * format, default value otherwise. 478 * 479 * @throws ConversionException is thrown if the key maps to an 480 * object that is not a Short. 481 */ 482 Short getShort(String key, Short defaultValue); 483 484 /** 485 * Get a {@link BigDecimal} associated with the given configuration key. 486 * 487 * @param key The configuration key. 488 * @return The associated BigDecimal if key is found and has valid format 489 */ 490 BigDecimal getBigDecimal(String key); 491 492 /** 493 * Get a {@link BigDecimal} associated with the given configuration key. 494 * If the key doesn't map to an existing object, the default value 495 * is returned. 496 * 497 * @param key The configuration key. 498 * @param defaultValue The default value. 499 * 500 * @return The associated BigDecimal if key is found and has valid 501 * format, default value otherwise. 502 */ 503 BigDecimal getBigDecimal(String key, BigDecimal defaultValue); 504 505 /** 506 * Get a {@link BigInteger} associated with the given configuration key. 507 * 508 * @param key The configuration key. 509 * 510 * @return The associated BigInteger if key is found and has valid format 511 */ 512 BigInteger getBigInteger(String key); 513 514 /** 515 * Get a {@link BigInteger} associated with the given configuration key. 516 * If the key doesn't map to an existing object, the default value 517 * is returned. 518 * 519 * @param key The configuration key. 520 * @param defaultValue The default value. 521 * 522 * @return The associated BigInteger if key is found and has valid 523 * format, default value otherwise. 524 */ 525 BigInteger getBigInteger(String key, BigInteger defaultValue); 526 527 /** 528 * Get a string associated with the given configuration key. 529 * 530 * @param key The configuration key. 531 * @return The associated string. 532 * 533 * @throws ConversionException is thrown if the key maps to an object that 534 * is not a String. 535 */ 536 String getString(String key); 537 538 /** 539 * Get a string associated with the given configuration key. 540 * If the key doesn't map to an existing object, the default value 541 * is returned. 542 * 543 * @param key The configuration key. 544 * @param defaultValue The default value. 545 * @return The associated string if key is found and has valid 546 * format, default value otherwise. 547 * 548 * @throws ConversionException is thrown if the key maps to an object that 549 * is not a String. 550 */ 551 String getString(String key, String defaultValue); 552 553 /** 554 * Get an array of strings associated with the given configuration key. 555 * If the key doesn't map to an existing object an empty array is returned 556 * 557 * @param key The configuration key. 558 * @return The associated string array if key is found. 559 * 560 * @throws ConversionException is thrown if the key maps to an 561 * object that is not a String/List of Strings. 562 */ 563 String[] getStringArray(String key); 564 565 /** 566 * Get a List of strings associated with the given configuration key. 567 * If the key doesn't map to an existing object an empty List is returned. 568 * 569 * @param key The configuration key. 570 * @return The associated List. 571 * 572 * @throws ConversionException is thrown if the key maps to an 573 * object that is not a List. 574 */ 575 List getList(String key); 576 577 /** 578 * Get a List of strings associated with the given configuration key. 579 * If the key doesn't map to an existing object, the default value 580 * is returned. 581 * 582 * @param key The configuration key. 583 * @param defaultValue The default value. 584 * @return The associated List of strings. 585 * 586 * @throws ConversionException is thrown if the key maps to an 587 * object that is not a List. 588 */ 589 List getList(String key, List defaultValue); 590 }