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 }