Java > Open Source Codes > org > apache > commons > configuration > Configuration


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 }
573

A to Z: JavaDoc & Examples

---

Daily Java News & Articles

---

Open Source Projects

---

Open Source Codes

---

Free Computer Books

---

Remove Frame

---

Popular Tags