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()}
 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} 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  
  * {@link AbstractConfiguration} 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  
  * {@link AbstractConfiguration#setThrowExceptionOnMissing(boolean)
 43  
  * setThrowExceptionOnMissing()}
 44  
  * method, with which it can be configured to throw a {@code NoSuchElementException}
 45  
  * exception in that case. (Note that getter methods for primitive types in
 46  
  * {@code AbstractConfiguration} 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()} and {@code setProperty()} methods
 49  
  * new properties can be added to a configuration or the values of properties
 50  
  * can be changed. With {@code clearProperty()} 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 1534064 2013-10-21 08:44:33Z henning $
 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")} 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} if the configuration contains no property,
 96  
      *         {@code false} 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} 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  
 }