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