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