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