View Javadoc

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