Coverage Report - org.apache.commons.configuration.Configuration
 
Classes in this File Line Coverage Branch Coverage Complexity
Configuration
N/A
N/A
1
 
 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  
 
 18  
 package org.apache.commons.configuration;
 19  
 
 20  
 import java.math.BigDecimal;
 21  
 import java.math.BigInteger;
 22  
 import java.util.Iterator;
 23  
 import java.util.List;
 24  
 import java.util.Properties;
 25  
 
 26  
 /**
 27  
  * <p>The main Configuration interface.</p>
 28  
  * <p>This interface allows accessing and manipulating a configuration object.
 29  
  * The major part of the methods defined in this interface deals with accessing
 30  
  * properties of various data types. There is a generic <code>getProperty()</code>
 31  
  * method, which returns the value of the queried property in its raw data
 32  
  * type. Other getter methods try to convert this raw data type into a specific
 33  
  * data type. If this fails, a <code>ConversionException</code> will be thrown.</p>
 34  
  * <p>For most of the property getter methods an overloaded version exists that
 35  
  * allows to specify a default value, which will be returned if the queried
 36  
  * property cannot be found in the configuration. The behavior of the methods
 37  
  * that do not take a default value in case of a missing property is not defined
 38  
  * by this interface and depends on a concrete implementation. E.g. the
 39  
  * <code>{@link AbstractConfiguration}</code> class, which is the base class
 40  
  * of most configuration implementations provided by this package, per default
 41  
  * returns <b>null</b> if a property is not found, but provides the
 42  
  * <code>{@link org.apache.commons.configuration.AbstractConfiguration#setThrowExceptionOnMissing(boolean)
 43  
  * setThrowExceptionOnMissing()}</code>
 44  
  * method, with which it can be configured to throw a <code>NoSuchElementException</code>
 45  
  * exception in that case. (Note that getter methods for primitive types in
 46  
  * <code>AbstractConfiguration</code> always throw an exception for missing
 47  
  * properties because there is no way of overloading the return value.)</p>
 48  
  * <p>With the <code>addProperty()</code> and <code>setProperty()</code> methods
 49  
  * new properties can be added to a configuration or the values of properties
 50  
  * can be changed. With <code>clearProperty()</code> a property can be removed.
 51  
  * Other methods allow to iterate over the contained properties or to create
 52  
  * a subset configuration.</p>
 53  
  *
 54  
  * @author Commons Configuration team
 55  
  * @version $Id: Configuration.java 449017 2006-09-22 17:27:00Z oheger $
 56  
  */
 57  
 public interface Configuration
 58  
 {
 59  
     /**
 60  
      * Return a decorator Configuration containing every key from the current
 61  
      * Configuration that starts with the specified prefix. The prefix is
 62  
      * removed from the keys in the subset. For example, if the configuration
 63  
      * contains the following properties:
 64  
      *
 65  
      * <pre>
 66  
      *    prefix.number = 1
 67  
      *    prefix.string = Apache
 68  
      *    prefixed.foo = bar
 69  
      *    prefix = Jakarta</pre>
 70  
      *
 71  
      * the Configuration returned by <code>subset("prefix")</code> will contain
 72  
      * the properties:
 73  
      *
 74  
      * <pre>
 75  
      *    number = 1
 76  
      *    string = Apache
 77  
      *    = Jakarta</pre>
 78  
      *
 79  
      * (The key for the value "Jakarta" is an empty string)
 80  
      * <p>
 81  
      * Since the subset is a decorator and not a modified copy of the initial
 82  
      * Configuration, any change made to the subset is available to the
 83  
      * Configuration, and reciprocally.
 84  
      *
 85  
      * @param prefix The prefix used to select the properties.
 86  
      * @return a subset configuration
 87  
      *
 88  
      * @see SubsetConfiguration
 89  
      */
 90  
     Configuration subset(String prefix);
 91  
 
 92  
     /**
 93  
      * Check if the configuration is empty.
 94  
      *
 95  
      * @return <code>true</code> if the configuration contains no property,
 96  
      *         <code>false</code> otherwise.
 97  
      */
 98  
     boolean isEmpty();
 99  
 
 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  
 }