1
2
3
4
5
6
7
8
9
10
11
12
13
14
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 }