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()} | |
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} 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 | * {@link AbstractConfiguration} 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 | * {@link AbstractConfiguration#setThrowExceptionOnMissing(boolean) | |
43 | * setThrowExceptionOnMissing()} | |
44 | * method, with which it can be configured to throw a {@code NoSuchElementException} | |
45 | * exception in that case. (Note that getter methods for primitive types in | |
46 | * {@code AbstractConfiguration} 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()} and {@code setProperty()} methods | |
49 | * new properties can be added to a configuration or the values of properties | |
50 | * can be changed. With {@code clearProperty()} 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 1204078 2011-11-19 21:28:49Z 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")} 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} if the configuration contains no property, | |
96 | * {@code false} 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} if the configuration contains a value for this | |
106 | * key, {@code false} 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} 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} 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. For instance, if the configuration contains the | |
172 | * following keys:<br> | |
173 | * {@code db.user, db.pwd, db.url, window.xpos, window.ypos},<br> | |
174 | * an invocation of {@code getKeys("db");}<br> | |
175 | * will return the keys below:<br> | |
176 | * {@code db.user, db.pwd, db.url}.<br> | |
177 | * Note that the prefix itself is included in the result set if there is a | |
178 | * matching key. The exact behavior - how the prefix is actually | |
179 | * interpreted - depends on a concrete implementation. | |
180 | * | |
181 | * @param prefix The prefix to test against. | |
182 | * @return An Iterator of keys that match the prefix. | |
183 | * @see #getKeys() | |
184 | */ | |
185 | Iterator<String> getKeys(String prefix); | |
186 | ||
187 | /** | |
188 | * Get the list of the keys contained in the configuration. The returned | |
189 | * iterator can be used to obtain all defined keys. Note that the exact | |
190 | * behavior of the iterator's {@code remove()} method is specific to | |
191 | * a concrete implementation. It <em>may</em> remove the corresponding | |
192 | * property from the configuration, but this is not guaranteed. In any case | |
193 | * it is no replacement for calling | |
194 | * {@link #clearProperty(String)} for this property. So it is | |
195 | * highly recommended to avoid using the iterator's {@code remove()} | |
196 | * method. | |
197 | * | |
198 | * @return An Iterator. | |
199 | */ | |
200 | Iterator<String> getKeys(); | |
201 | ||
202 | /** | |
203 | * Get a list of properties associated with the given configuration key. | |
204 | * This method expects the given key to have an arbitrary number of String | |
205 | * values, each of which is of the form {code key=value}. These | |
206 | * strings are split at the equals sign, and the key parts will become | |
207 | * keys of the returned {@code Properties} object, the value parts | |
208 | * become values. | |
209 | * | |
210 | * @param key The configuration key. | |
211 | * @return The associated properties if key is found. | |
212 | * | |
213 | * @throws ConversionException is thrown if the key maps to an | |
214 | * object that is not a String/List. | |
215 | * | |
216 | * @throws IllegalArgumentException if one of the tokens is | |
217 | * malformed (does not contain an equals sign). | |
218 | */ | |
219 | Properties getProperties(String key); | |
220 | ||
221 | /** | |
222 | * Get a boolean associated with the given configuration key. | |
223 | * | |
224 | * @param key The configuration key. | |
225 | * @return The associated boolean. | |
226 | * | |
227 | * @throws ConversionException is thrown if the key maps to an | |
228 | * object that is not a Boolean. | |
229 | */ | |
230 | boolean getBoolean(String key); | |
231 | ||
232 | /** | |
233 | * Get a boolean associated with the given configuration key. | |
234 | * If the key doesn't map to an existing object, the default value | |
235 | * is returned. | |
236 | * | |
237 | * @param key The configuration key. | |
238 | * @param defaultValue The default value. | |
239 | * @return The associated boolean. | |
240 | * | |
241 | * @throws ConversionException is thrown if the key maps to an | |
242 | * object that is not a Boolean. | |
243 | */ | |
244 | boolean getBoolean(String key, boolean defaultValue); | |
245 | ||
246 | /** | |
247 | * Get a {@link Boolean} associated with the given configuration key. | |
248 | * | |
249 | * @param key The configuration key. | |
250 | * @param defaultValue The default value. | |
251 | * @return The associated boolean if key is found and has valid | |
252 | * format, default value otherwise. | |
253 | * | |
254 | * @throws ConversionException is thrown if the key maps to an | |
255 | * object that is not a Boolean. | |
256 | */ | |
257 | Boolean getBoolean(String key, Boolean defaultValue); | |
258 | ||
259 | /** | |
260 | * Get a byte associated with the given configuration key. | |
261 | * | |
262 | * @param key The configuration key. | |
263 | * @return The associated byte. | |
264 | * | |
265 | * @throws ConversionException is thrown if the key maps to an | |
266 | * object that is not a Byte. | |
267 | */ | |
268 | byte getByte(String key); | |
269 | ||
270 | /** | |
271 | * Get a byte associated with the given configuration key. | |
272 | * If the key doesn't map to an existing object, the default value | |
273 | * is returned. | |
274 | * | |
275 | * @param key The configuration key. | |
276 | * @param defaultValue The default value. | |
277 | * @return The associated byte. | |
278 | * | |
279 | * @throws ConversionException is thrown if the key maps to an | |
280 | * object that is not a Byte. | |
281 | */ | |
282 | byte getByte(String key, byte defaultValue); | |
283 | ||
284 | /** | |
285 | * Get a {@link Byte} associated with the given configuration key. | |
286 | * | |
287 | * @param key The configuration key. | |
288 | * @param defaultValue The default value. | |
289 | * @return The associated byte if key is found and has valid format, default | |
290 | * value otherwise. | |
291 | * | |
292 | * @throws ConversionException is thrown if the key maps to an object that | |
293 | * is not a Byte. | |
294 | */ | |
295 | Byte getByte(String key, Byte defaultValue); | |
296 | ||
297 | /** | |
298 | * Get a double associated with the given configuration key. | |
299 | * | |
300 | * @param key The configuration key. | |
301 | * @return The associated double. | |
302 | * | |
303 | * @throws ConversionException is thrown if the key maps to an | |
304 | * object that is not a Double. | |
305 | */ | |
306 | double getDouble(String key); | |
307 | ||
308 | /** | |
309 | * Get a double associated with the given configuration key. | |
310 | * If the key doesn't map to an existing object, the default value | |
311 | * is returned. | |
312 | * | |
313 | * @param key The configuration key. | |
314 | * @param defaultValue The default value. | |
315 | * @return The associated double. | |
316 | * | |
317 | * @throws ConversionException is thrown if the key maps to an | |
318 | * object that is not a Double. | |
319 | */ | |
320 | double getDouble(String key, double defaultValue); | |
321 | ||
322 | /** | |
323 | * Get a {@link Double} associated with the given configuration key. | |
324 | * | |
325 | * @param key The configuration key. | |
326 | * @param defaultValue The default value. | |
327 | * @return The associated double if key is found and has valid | |
328 | * format, default value otherwise. | |
329 | * | |
330 | * @throws ConversionException is thrown if the key maps to an | |
331 | * object that is not a Double. | |
332 | */ | |
333 | Double getDouble(String key, Double defaultValue); | |
334 | ||
335 | /** | |
336 | * Get a float associated with the given configuration key. | |
337 | * | |
338 | * @param key The configuration key. | |
339 | * @return The associated float. | |
340 | * @throws ConversionException is thrown if the key maps to an | |
341 | * object that is not a Float. | |
342 | */ | |
343 | float getFloat(String key); | |
344 | ||
345 | /** | |
346 | * Get a float associated with the given configuration key. | |
347 | * If the key doesn't map to an existing object, the default value | |
348 | * is returned. | |
349 | * | |
350 | * @param key The configuration key. | |
351 | * @param defaultValue The default value. | |
352 | * @return The associated float. | |
353 | * | |
354 | * @throws ConversionException is thrown if the key maps to an | |
355 | * object that is not a Float. | |
356 | */ | |
357 | float getFloat(String key, float defaultValue); | |
358 | ||
359 | /** | |
360 | * Get a {@link Float} associated with the given configuration key. | |
361 | * If the key doesn't map to an existing object, the default value | |
362 | * is returned. | |
363 | * | |
364 | * @param key The configuration key. | |
365 | * @param defaultValue The default value. | |
366 | * @return The associated float if key is found and has valid | |
367 | * format, default value otherwise. | |
368 | * | |
369 | * @throws ConversionException is thrown if the key maps to an | |
370 | * object that is not a Float. | |
371 | */ | |
372 | Float getFloat(String key, Float defaultValue); | |
373 | ||
374 | /** | |
375 | * Get a int associated with the given configuration key. | |
376 | * | |
377 | * @param key The configuration key. | |
378 | * @return The associated int. | |
379 | * | |
380 | * @throws ConversionException is thrown if the key maps to an | |
381 | * object that is not a Integer. | |
382 | */ | |
383 | int getInt(String key); | |
384 | ||
385 | /** | |
386 | * Get a int associated with the given configuration key. | |
387 | * If the key doesn't map to an existing object, the default value | |
388 | * is returned. | |
389 | * | |
390 | * @param key The configuration key. | |
391 | * @param defaultValue The default value. | |
392 | * @return The associated int. | |
393 | * | |
394 | * @throws ConversionException is thrown if the key maps to an | |
395 | * object that is not a Integer. | |
396 | */ | |
397 | int getInt(String key, int defaultValue); | |
398 | ||
399 | /** | |
400 | * Get an {@link Integer} associated with the given configuration key. | |
401 | * If the key doesn't map to an existing object, the default value | |
402 | * is returned. | |
403 | * | |
404 | * @param key The configuration key. | |
405 | * @param defaultValue The default value. | |
406 | * @return The associated int if key is found and has valid format, default | |
407 | * value otherwise. | |
408 | * | |
409 | * @throws ConversionException is thrown if the key maps to an object that | |
410 | * is not a Integer. | |
411 | */ | |
412 | Integer getInteger(String key, Integer defaultValue); | |
413 | ||
414 | /** | |
415 | * Get a long associated with the given configuration key. | |
416 | * | |
417 | * @param key The configuration key. | |
418 | * @return The associated long. | |
419 | * | |
420 | * @throws ConversionException is thrown if the key maps to an | |
421 | * object that is not a Long. | |
422 | */ | |
423 | long getLong(String key); | |
424 | ||
425 | /** | |
426 | * Get a long associated with the given configuration key. | |
427 | * If the key doesn't map to an existing object, the default value | |
428 | * is returned. | |
429 | * | |
430 | * @param key The configuration key. | |
431 | * @param defaultValue The default value. | |
432 | * @return The associated long. | |
433 | * | |
434 | * @throws ConversionException is thrown if the key maps to an | |
435 | * object that is not a Long. | |
436 | */ | |
437 | long getLong(String key, long defaultValue); | |
438 | ||
439 | /** | |
440 | * Get a {@link Long} 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 long 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 Long. | |
451 | */ | |
452 | Long getLong(String key, Long defaultValue); | |
453 | ||
454 | /** | |
455 | * Get a short associated with the given configuration key. | |
456 | * | |
457 | * @param key The configuration key. | |
458 | * @return The associated short. | |
459 | * | |
460 | * @throws ConversionException is thrown if the key maps to an | |
461 | * object that is not a Short. | |
462 | */ | |
463 | short getShort(String key); | |
464 | ||
465 | /** | |
466 | * Get a short associated with the given configuration key. | |
467 | * | |
468 | * @param key The configuration key. | |
469 | * @param defaultValue The default value. | |
470 | * @return The associated short. | |
471 | * | |
472 | * @throws ConversionException is thrown if the key maps to an | |
473 | * object that is not a Short. | |
474 | */ | |
475 | short getShort(String key, short defaultValue); | |
476 | ||
477 | /** | |
478 | * Get a {@link Short} associated with the given configuration key. | |
479 | * If the key doesn't map to an existing object, the default value | |
480 | * is returned. | |
481 | * | |
482 | * @param key The configuration key. | |
483 | * @param defaultValue The default value. | |
484 | * @return The associated short if key is found and has valid | |
485 | * format, default value otherwise. | |
486 | * | |
487 | * @throws ConversionException is thrown if the key maps to an | |
488 | * object that is not a Short. | |
489 | */ | |
490 | Short getShort(String key, Short defaultValue); | |
491 | ||
492 | /** | |
493 | * Get a {@link BigDecimal} associated with the given configuration key. | |
494 | * | |
495 | * @param key The configuration key. | |
496 | * @return The associated BigDecimal if key is found and has valid format | |
497 | */ | |
498 | BigDecimal getBigDecimal(String key); | |
499 | ||
500 | /** | |
501 | * Get a {@link BigDecimal} associated with the given configuration key. | |
502 | * If the key doesn't map to an existing object, the default value | |
503 | * is returned. | |
504 | * | |
505 | * @param key The configuration key. | |
506 | * @param defaultValue The default value. | |
507 | * | |
508 | * @return The associated BigDecimal if key is found and has valid | |
509 | * format, default value otherwise. | |
510 | */ | |
511 | BigDecimal getBigDecimal(String key, BigDecimal defaultValue); | |
512 | ||
513 | /** | |
514 | * Get a {@link BigInteger} associated with the given configuration key. | |
515 | * | |
516 | * @param key The configuration key. | |
517 | * | |
518 | * @return The associated BigInteger if key is found and has valid format | |
519 | */ | |
520 | BigInteger getBigInteger(String key); | |
521 | ||
522 | /** | |
523 | * Get a {@link BigInteger} associated with the given configuration key. | |
524 | * If the key doesn't map to an existing object, the default value | |
525 | * is returned. | |
526 | * | |
527 | * @param key The configuration key. | |
528 | * @param defaultValue The default value. | |
529 | * | |
530 | * @return The associated BigInteger if key is found and has valid | |
531 | * format, default value otherwise. | |
532 | */ | |
533 | BigInteger getBigInteger(String key, BigInteger defaultValue); | |
534 | ||
535 | /** | |
536 | * Get a string associated with the given configuration key. | |
537 | * | |
538 | * @param key The configuration key. | |
539 | * @return The associated string. | |
540 | * | |
541 | * @throws ConversionException is thrown if the key maps to an object that | |
542 | * is not a String. | |
543 | */ | |
544 | String getString(String key); | |
545 | ||
546 | /** | |
547 | * Get a string associated with the given configuration key. | |
548 | * If the key doesn't map to an existing object, the default value | |
549 | * is returned. | |
550 | * | |
551 | * @param key The configuration key. | |
552 | * @param defaultValue The default value. | |
553 | * @return The associated string if key is found and has valid | |
554 | * format, default value otherwise. | |
555 | * | |
556 | * @throws ConversionException is thrown if the key maps to an object that | |
557 | * is not a String. | |
558 | */ | |
559 | String getString(String key, String defaultValue); | |
560 | ||
561 | /** | |
562 | * Get an array of strings associated with the given configuration key. | |
563 | * If the key doesn't map to an existing object an empty array is returned | |
564 | * | |
565 | * @param key The configuration key. | |
566 | * @return The associated string array if key is found. | |
567 | * | |
568 | * @throws ConversionException is thrown if the key maps to an | |
569 | * object that is not a String/List of Strings. | |
570 | */ | |
571 | String[] getStringArray(String key); | |
572 | ||
573 | /** | |
574 | * Get a List of strings associated with the given configuration key. | |
575 | * If the key doesn't map to an existing object an empty List is returned. | |
576 | * | |
577 | * @param key The configuration key. | |
578 | * @return The associated List. | |
579 | * | |
580 | * @throws ConversionException is thrown if the key maps to an | |
581 | * object that is not a List. | |
582 | */ | |
583 | List<Object> getList(String key); | |
584 | ||
585 | /** | |
586 | * Get a List of strings associated with the given configuration key. | |
587 | * If the key doesn't map to an existing object, the default value | |
588 | * is returned. | |
589 | * | |
590 | * @param key The configuration key. | |
591 | * @param defaultValue The default value. | |
592 | * @return The associated List of strings. | |
593 | * | |
594 | * @throws ConversionException is thrown if the key maps to an | |
595 | * object that is not a List. | |
596 | */ | |
597 | List<Object> getList(String key, List<Object> defaultValue); | |
598 | } |