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