View Javadoc

    1   /*
    2    * Copyright 2001-2004 The Apache Software Foundation.
    3    *
    4    * Licensed under the Apache License, Version 2.0 (the "License")
    5    * you may not use this file except in compliance with the License.
    6    * You may obtain a copy of the License at
    7    *
    8    *     http://www.apache.org/licenses/LICENSE-2.0
    9    *
    10   * Unless required by applicable law or agreed to in writing, software
    11   * distributed under the License is distributed on an "AS IS" BASIS,
    12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    13   * See the License for the specific language governing permissions and
    14   * limitations under the License.
    15   */
    16
    17  package org.apache.commons.configuration;
    18
    19  import java.math.BigDecimal;
    20  import java.math.BigInteger;
    21  import java.util.Iterator;
    22  import java.util.List;
    23  import java.util.Properties;
    24  import java.util.Vector;
    25
    26  /***
    27   * Configuration interface.
    28   *
    29   * @version $Id: Configuration.java,v 1.10 2004/08/16 22:16:31 henning Exp $
    30   */
    31  public interface Configuration
    32  {
    33      /***
    34       * Return a decorator Configuration containing every key from the current
    35       * Configuration that starts with the specified prefix. The prefix is
    36       * removed from the keys in the subset. For example, if the configuration
    37       * contains the following properties:
    38       *
    39       * <pre>
    40       *    prefix.number = 1
    41       *    prefix.string = Apache
    42       *    prefixed.foo = bar
    43       *    prefix = Jakarta</pre>
    44       *
    45       * the Configuration returned by <code>subset("prefix")</code> will contain
    46       * the properties:
    47       *
    48       * <pre>
    49       *    number = 1
    50       *    string = Apache
    51       *    = Jakarta</pre>
    52       *
    53       * (The key for the value "Jakarta" is an empty string)
    54       * <p>
    55       * Since the subset is a decorator and not a modified copy of the initial
    56       * Configuration, any change made to the subset is available to the
    57       * Configuration, and reciprocally.
    58       *
    59       * @param prefix The prefix used to select the properties.
    60       *
    61       * @see SubsetConfiguration
    62       */
    63      Configuration subset(String prefix);
    64
    65      /***
    66       * Check if the configuration is empty.
    67       *
    68       * @return <code>true</code> if the configuration contains no property,
    69       *         <code>false</code> otherwise.
    70       */
    71      boolean isEmpty();
    72
    73      /***
    74       * Check if the configuration contains the specified key.
    75       *
    76       * @param key the key whose presence in this configuration is to be tested
    77       *
    78       * @return <code>true</code> if the configuration contains a value for this
    79       *         key, <code>false</code> otherwise
    80       */
    81      boolean containsKey(String key);
    82
    83      /***
    84       * Add a property to the configuration. If it already exists then the value
    85       * stated here will be added to the configuration entry. For example, if
    86       * the property:
    87       *
    88       * <pre>resource.loader = file</pre>
    89       *
    90       * is already present in the configuration and you call
    91       *
    92       * <pre>addProperty("resource.loader", "classpath")</pre>
    93       *
    94       * Then you will end up with a List like the following:
    95       *
    96       * <pre>["file", "classpath"]</pre>
    97       *
    98       * @param key The key to add the property to.
    99       * @param value The value to add.
    100      */
    101     void addProperty(String key, Object value);
    102
    103     /***
    104      * Set a property, this will replace any previously set values. Set values
    105      * is implicitly a call to clearProperty(key), addProperty(key, value).
    106      *
    107      * @param key The key of the property to change
    108      * @param value The new value
    109      */
    110     void setProperty(String key, Object value);
    111
    112     /***
    113      * Remove a property from the configuration.
    114      *
    115      * @param key the key to remove along with corresponding value.
    116      */
    117     void clearProperty(String key);
    118
    119     /***
    120      * Gets a property from the configuration.
    121      *
    122      * @param key property to retrieve
    123      * @return the value to which this configuration maps the specified key, or
    124      *         null if the configuration contains no mapping for this key.
    125      */
    126     Object getProperty(String key);
    127
    128     /***
    129      * Get the list of the keys contained in the configuration that match the
    130      * specified prefix.
    131      *
    132      * @param prefix The prefix to test against.
    133      * @return An Iterator of keys that match the prefix.
    134      */
    135     Iterator getKeys(String prefix);
    136
    137     /***
    138      * Get the list of the keys contained in the configuration.
    139      *
    140      * @return An Iterator.
    141      */
    142     Iterator getKeys();
    143
    144     /***
    145      * Get a list of properties associated with the given configuration key.
    146      *
    147      * @param key The configuration key.
    148      * @return The associated properties if key is found.
    149      *
    150      * @throws ConversionException is thrown if the key maps to an
    151      *         object that is not a String/List.
    152      *
    153      * @throws IllegalArgumentException if one of the tokens is
    154      *         malformed (does not contain an equals sign).
    155      */
    156     Properties getProperties(String key);
    157
    158     /***
    159      * Get a boolean associated with the given configuration key.
    160      *
    161      * @param key The configuration key.
    162      * @return The associated boolean.
    163      *
    164      * @throws NoSuchElementException is thrown if the key doesn't
    165      *         map to an existing object.
    166      *
    167      * @throws ConversionException is thrown if the key maps to an
    168      *         object that is not a Boolean.
    169      */
    170     boolean getBoolean(String key);
    171
    172     /***
    173      * Get a boolean associated with the given configuration key.
    174      *
    175      * @param key The configuration key.
    176      * @param defaultValue The default value.
    177      * @return The associated boolean.
    178      *
    179      * @throws ConversionException is thrown if the key maps to an
    180      *         object that is not a Boolean.
    181      */
    182     boolean getBoolean(String key, boolean defaultValue);
    183
    184     /***
    185      * Get a {@link Boolean} associated with the given configuration key.
    186      *
    187      * @param key The configuration key.
    188      * @param defaultValue The default value.
    189      * @return The associated boolean if key is found and has valid
    190      *         format, default value otherwise.
    191      *
    192      * @throws ConversionException is thrown if the key maps to an
    193      *         object that is not a Boolean.
    194      */
    195     Boolean getBoolean(String key, Boolean defaultValue) throws NoClassDefFoundError;
    196
    197     /***
    198      * Get a byte associated with the given configuration key.
    199      *
    200      * @param key The configuration key.
    201      * @return The associated byte.
    202      *
    203      * @throws NoSuchElementException is thrown if the key doesn't
    204      *         map to an existing object.
    205      *
    206      * @throws ConversionException is thrown if the key maps to an
    207      *         object that is not a Byte.
    208      */
    209     byte getByte(String key);
    210
    211     /***
    212      * Get a byte associated with the given configuration key.
    213      *
    214      * @param key The configuration key.
    215      * @param defaultValue The default value.
    216      * @return The associated byte.
    217      *
    218      * @throws ConversionException is thrown if the key maps to an
    219      *         object that is not a Byte.
    220      */
    221     byte getByte(String key, byte defaultValue);
    222
    223     /***
    224      * Get a {@link Byte} associated with the given configuration key.
    225      *
    226      * @param key The configuration key.
    227      * @param defaultValue The default value.
    228      * @return The associated byte if key is found and has valid format, default
    229      *         value otherwise.
    230      *
    231      * @throws ConversionException is thrown if the key maps to an object that
    232      *         is not a Byte.
    233      */
    234     Byte getByte(String key, Byte defaultValue);
    235
    236     /***
    237      * Get a double associated with the given configuration key.
    238      *
    239      * @param key The configuration key.
    240      * @return The associated double.
    241      *
    242      * @throws NoSuchElementException is thrown if the key doesn't
    243      *         map to an existing object.
    244      *
    245      * @throws ConversionException is thrown if the key maps to an
    246      *         object that is not a Double.
    247      */
    248     double getDouble(String key);
    249
    250     /***
    251      * Get a double associated with the given configuration key.
    252      *
    253      * @param key The configuration key.
    254      * @param defaultValue The default value.
    255      * @return The associated double.
    256      *
    257      * @throws ConversionException is thrown if the key maps to an
    258      *         object that is not a Double.
    259      */
    260     double getDouble(String key, double defaultValue);
    261
    262     /***
    263      * Get a {@link Double} associated with the given configuration key.
    264      *
    265      * @param key The configuration key.
    266      * @param defaultValue The default value.
    267      * @return The associated double if key is found and has valid
    268      *         format, default value otherwise.
    269      *
    270      * @throws ConversionException is thrown if the key maps to an
    271      *         object that is not a Double.
    272      */
    273     Double getDouble(String key, Double defaultValue);
    274
    275     /***
    276      * Get a float associated with the given configuration key.
    277      *
    278      * @param key The configuration key.
    279      * @return The associated float.
    280      * @throws NoSuchElementException is thrown if the key doesn't
    281      *         map to an existing object.
    282      *
    283      * @throws ConversionException is thrown if the key maps to an
    284      *         object that is not a Float.
    285      */
    286     float getFloat(String key);
    287
    288     /***
    289      * Get a float associated with the given configuration key.
    290      *
    291      * @param key The configuration key.
    292      * @param defaultValue The default value.
    293      * @return The associated float.
    294      *
    295      * @throws ConversionException is thrown if the key maps to an
    296      *         object that is not a Float.
    297      */
    298     float getFloat(String key, float defaultValue);
    299
    300     /***
    301      * Get a {@link Float} associated with the given configuration key.
    302      *
    303      * @param key The configuration key.
    304      * @param defaultValue The default value.
    305      * @return The associated float if key is found and has valid
    306      *         format, default value otherwise.
    307      *
    308      * @throws ConversionException is thrown if the key maps to an
    309      *         object that is not a Float.
    310      */
    311     Float getFloat(String key, Float defaultValue);
    312
    313     /***
    314      * Get a int associated with the given configuration key.
    315      *
    316      * @param key The configuration key.
    317      * @return The associated int.
    318      *
    319      * @throws NoSuchElementException is thrown if the key doesn't
    320      *         map to an existing object.
    321      *
    322      * @throws ConversionException is thrown if the key maps to an
    323      *         object that is not a Integer.
    324      */
    325     int getInt(String key);
    326
    327     /***
    328      * Get a int associated with the given configuration key.
    329      *
    330      * @param key The configuration key.
    331      * @param defaultValue The default value.
    332      * @return The associated int.
    333      *
    334      * @throws ConversionException is thrown if the key maps to an
    335      *         object that is not a Integer.
    336      */
    337     int getInt(String key, int defaultValue);
    338
    339     /***
    340      * Get an {@link Integer} associated with the given configuration key.
    341      *
    342      * @param key The configuration key.
    343      * @param defaultValue The default value.
    344      * @return The associated int if key is found and has valid format, default
    345      *         value otherwise.
    346      *
    347      * @throws ConversionException is thrown if the key maps to an object that
    348      *         is not a Integer.
    349      */
    350     Integer getInteger(String key, Integer defaultValue);
    351
    352     /***
    353      * Get a long associated with the given configuration key.
    354      *
    355      * @param key The configuration key.
    356      * @return The associated long.
    357      *
    358      * @throws NoSuchElementException is thrown if the key doesn't
    359      *         map to an existing object.
    360      *
    361      * @throws ConversionException is thrown if the key maps to an
    362      *         object that is not a Long.
    363      */
    364     long getLong(String key);
    365
    366     /***
    367      * Get a long associated with the given configuration key.
    368      *
    369      * @param key The configuration key.
    370      * @param defaultValue The default value.
    371      * @return The associated long.
    372      *
    373      * @throws ConversionException is thrown if the key maps to an
    374      *         object that is not a Long.
    375      */
    376     long getLong(String key, long defaultValue);
    377
    378     /***
    379      * Get a {@link Long} associated with the given configuration key.
    380      *
    381      * @param key The configuration key.
    382      * @param defaultValue The default value.
    383      * @return The associated long if key is found and has valid
    384      * format, default value otherwise.
    385      *
    386      * @throws ConversionException is thrown if the key maps to an
    387      *         object that is not a Long.
    388      */
    389     Long getLong(String key, Long defaultValue);
    390
    391     /***
    392      * Get a short associated with the given configuration key.
    393      *
    394      * @param key The configuration key.
    395      * @return The associated short.
    396      *
    397      * @throws NoSuchElementException is thrown if the key doesn't
    398      *         map to an existing object.
    399      *
    400      * @throws ConversionException is thrown if the key maps to an
    401      *         object that is not a Short.
    402      */
    403     short getShort(String key);
    404
    405     /***
    406      * Get a short associated with the given configuration key.
    407      *
    408      * @param key The configuration key.
    409      * @param defaultValue The default value.
    410      * @return The associated short.
    411      *
    412      * @throws ConversionException is thrown if the key maps to an
    413      *         object that is not a Short.
    414      */
    415     short getShort(String key, short defaultValue);
    416
    417     /***
    418      * Get a {@link Short} associated with the given configuration key.
    419      *
    420      * @param key The configuration key.
    421      * @param defaultValue The default value.
    422      * @return The associated short if key is found and has valid
    423      *         format, default value otherwise.
    424      *
    425      * @throws ConversionException is thrown if the key maps to an
    426      *         object that is not a Short.
    427      *
    428      * @throws NoSuchElementException is thrown if the key doesn't
    429      *         map to an existing object.
    430      */
    431     Short getShort(String key, Short defaultValue);
    432
    433     /***
    434      * Get a {@link BigDecimal} associated with the given configuration key.
    435      *
    436      * @param key The configuration key.
    437      * @return The associated BigDecimal if key is found and has valid format
    438      *
    439      * @throws NoSuchElementException is thrown if the key doesn't
    440      *         map to an existing object.
    441      */
    442     BigDecimal getBigDecimal(String key);
    443
    444     /***
    445      * Get a {@link BigDecimal} associated with the given configuration key.
    446      *
    447      * @param key          The configuration key.
    448      * @param defaultValue The default value.
    449      *
    450      * @return The associated BigDecimal if key is found and has valid
    451      *         format, default value otherwise.
    452      */
    453     BigDecimal getBigDecimal(String key, BigDecimal defaultValue);
    454
    455     /***
    456      * Get a {@link BigInteger} associated with the given configuration key.
    457      *
    458      * @param key The configuration key.
    459      *
    460      * @return The associated BigInteger if key is found and has valid format
    461      *
    462      * @throws NoSuchElementException is thrown if the key doesn't
    463      *         map to an existing object.
    464      */
    465     BigInteger getBigInteger(String key);
    466
    467     /***
    468      * Get a {@link BigInteger} associated with the given configuration key.
    469      *
    470      * @param key          The configuration key.
    471      * @param defaultValue The default value.
    472      *
    473      * @return The associated BigInteger if key is found and has valid
    474      *         format, default value otherwise.
    475      */
    476     BigInteger getBigInteger(String key, BigInteger defaultValue);
    477
    478     /***
    479      * Get a string associated with the given configuration key.
    480      *
    481      * @param key The configuration key.
    482      * @return The associated string.
    483      *
    484      * @throws ConversionException is thrown if the key maps to an object that
    485      *         is not a String.
    486      *
    487      * @throws NoSuchElementException is thrown if the key doesn't
    488      *         map to an existing object.
    489      */
    490     String getString(String key);
    491
    492     /***
    493      * Get a string associated with the given configuration key.
    494      *
    495      * @param key The configuration key.
    496      * @param defaultValue The default value.
    497      * @return The associated string if key is found and has valid
    498      *         format, default value otherwise.
    499      *
    500      * @throws ConversionException is thrown if the key maps to an object that
    501      *         is not a String.
    502      */
    503     String getString(String key, String defaultValue);
    504
    505     /***
    506      * Get an array of strings associated with the given configuration key.
    507      * If the key doesn't map to an existing object an empty array is returned
    508      *
    509      * @param key The configuration key.
    510      * @return The associated string array if key is found.
    511      *
    512      * @throws ConversionException is thrown if the key maps to an
    513      *         object that is not a String/List of Strings.
    514      */
    515     String[] getStringArray(String key);
    516
    517     /***
    518      * Get a List of strings associated with the given configuration key.
    519      * If the key doesn't map to an existing object an empty List is returned.
    520      *
    521      * @param key The configuration key.
    522      * @return The associated List.
    523      *
    524      * @throws ConversionException is thrown if the key maps to an
    525      *         object that is not a List.
    526      */
    527     List getList(String key);
    528
    529     /***
    530      * Get a List of strings associated with the given configuration key.
    531      *
    532      * @param key The configuration key.
    533      * @param defaultValue The default value.
    534      * @return The associated List.
    535      *
    536      * @throws ConversionException is thrown if the key maps to an
    537      *         object that is not a List.
    538      */
    539     List getList(String key, List defaultValue);
    540
    541     /***
    542      * Get a Vector of strings associated with the given configuration key.
    543      * If the key doesn't map to an existing object an empty Vector is returned.
    544      *
    545      * @param key The configuration key.
    546      * @return The associated Vector.
    547      *
    548      * @deprecated This method is for compatibility with applications that
    549      * use the pre-1.0 versions of commons-configuration. It will be removed
    550      * post 1.0
    551      *
    552      * @throws ConversionException is thrown if the key maps to an
    553      *         object that is not a Vector.
    554      */
    555     Vector getVector(String key);
    556
    557     /***
    558      * Get a Vector of strings associated with the given configuration key.
    559      *
    560      * @param key The configuration key.
    561      * @param defaultValue The default value.
    562      * @return The associated Vector.
    563      *
    564      * @deprecated This method is for compatibility with applications that
    565      * use the pre-1.0 versions of commons-configuration. It will be removed
    566      * post 1.0
    567      *
    568      * @throws ConversionException is thrown if the key maps to an
    569      *         object that is not a Vector.
    570      */
    571     Vector getVector(String key, Vector defaultValue);
    572 }