001: /*
002: * Licensed to the Apache Software Foundation (ASF) under one or more
003: * contributor license agreements. See the NOTICE file distributed with
004: * this work for additional information regarding copyright ownership.
005: * The ASF licenses this file to You under the Apache License, Version 2.0
006: * (the "License"); you may not use this file except in compliance with
007: * the License. You may obtain a copy of the License at
008: *
009: * http://www.apache.org/licenses/LICENSE-2.0
010: *
011: * Unless required by applicable law or agreed to in writing, software
012: * distributed under the License is distributed on an "AS IS" BASIS,
013: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014: * See the License for the specific language governing permissions and
015: * limitations under the License.
016: */
017:
018: package org.apache.commons.configuration;
019:
020: import java.math.BigDecimal;
021: import java.math.BigInteger;
022: import java.util.Iterator;
023: import java.util.List;
024: import java.util.Properties;
025:
026: /**
027: * <p>The main Configuration interface.</p>
028: * <p>This interface allows accessing and manipulating a configuration object.
029: * The major part of the methods defined in this interface deals with accessing
030: * properties of various data types. There is a generic <code>getProperty()</code>
031: * method, which returns the value of the queried property in its raw data
032: * type. Other getter methods try to convert this raw data type into a specific
033: * data type. If this fails, a <code>ConversionException</code> will be thrown.</p>
034: * <p>For most of the property getter methods an overloaded version exists that
035: * allows to specify a default value, which will be returned if the queried
036: * property cannot be found in the configuration. The behavior of the methods
037: * that do not take a default value in case of a missing property is not defined
038: * by this interface and depends on a concrete implementation. E.g. the
039: * <code>{@link AbstractConfiguration}</code> class, which is the base class
040: * of most configuration implementations provided by this package, per default
041: * returns <b>null</b> if a property is not found, but provides the
042: * <code>{@link org.apache.commons.configuration.AbstractConfiguration#setThrowExceptionOnMissing(boolean)
043: * setThrowExceptionOnMissing()}</code>
044: * method, with which it can be configured to throw a <code>NoSuchElementException</code>
045: * exception in that case. (Note that getter methods for primitive types in
046: * <code>AbstractConfiguration</code> always throw an exception for missing
047: * properties because there is no way of overloading the return value.)</p>
048: * <p>With the <code>addProperty()</code> and <code>setProperty()</code> methods
049: * new properties can be added to a configuration or the values of properties
050: * can be changed. With <code>clearProperty()</code> a property can be removed.
051: * Other methods allow to iterate over the contained properties or to create
052: * a subset configuration.</p>
053: *
054: * @author Commons Configuration team
055: * @version $Id: Configuration.java 449017 2006-09-22 17:27:00Z oheger $
056: */
057: public interface Configuration {
058: /**
059: * Return a decorator Configuration containing every key from the current
060: * Configuration that starts with the specified prefix. The prefix is
061: * removed from the keys in the subset. For example, if the configuration
062: * contains the following properties:
063: *
064: * <pre>
065: * prefix.number = 1
066: * prefix.string = Apache
067: * prefixed.foo = bar
068: * prefix = Jakarta</pre>
069: *
070: * the Configuration returned by <code>subset("prefix")</code> will contain
071: * the properties:
072: *
073: * <pre>
074: * number = 1
075: * string = Apache
076: * = Jakarta</pre>
077: *
078: * (The key for the value "Jakarta" is an empty string)
079: * <p>
080: * Since the subset is a decorator and not a modified copy of the initial
081: * Configuration, any change made to the subset is available to the
082: * Configuration, and reciprocally.
083: *
084: * @param prefix The prefix used to select the properties.
085: * @return a subset configuration
086: *
087: * @see SubsetConfiguration
088: */
089: Configuration subset(String prefix);
090:
091: /**
092: * Check if the configuration is empty.
093: *
094: * @return <code>true</code> if the configuration contains no property,
095: * <code>false</code> otherwise.
096: */
097: boolean isEmpty();
098:
099: /**
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. This is the most basic get
152: * method for retrieving values of properties. In a typical implementation
153: * of the <code>Configuration</code> interface the other get methods (that
154: * return specific data types) will internally make use of this method. On
155: * this level variable substitution is not yet performed. The returned
156: * object is an internal representation of the property value for the passed
157: * in key. It is owned by the <code>Configuration</code> object. So a caller
158: * should not modify this object. It cannot be guaranteed that this object
159: * will stay constant over time (i.e. further update operations on the
160: * configuration may change its internal state).
161: *
162: * @param key property to retrieve
163: * @return the value to which this configuration maps the specified key, or
164: * null if the configuration contains no mapping for this key.
165: */
166: Object getProperty(String key);
167:
168: /**
169: * Get the list of the keys contained in the configuration that match the
170: * specified prefix.
171: *
172: * @param prefix The prefix to test against.
173: * @return An Iterator of keys that match the prefix.
174: * @see #getKeys()
175: */
176: Iterator getKeys(String prefix);
177:
178: /**
179: * Get the list of the keys contained in the configuration. The returned
180: * iterator can be used to obtain all defined keys. Note that the exact
181: * behavior of the iterator's <code>remove()</code> method is specific to
182: * a concrete implementation. It <em>may</em> remove the corresponding
183: * property from the configuration, but this is not guaranteed. In any case
184: * it is no replacement for calling
185: * <code>{@link #clearProperty(String)}</code> for this property. So it is
186: * highly recommended to avoid using the iterator's <code>remove()</code>
187: * method.
188: *
189: * @return An Iterator.
190: */
191: Iterator getKeys();
192:
193: /**
194: * Get a list of properties associated with the given configuration key.
195: * This method expects the given key to have an arbitrary number of String
196: * values, each of which is of the form <code>key=value</code>. These
197: * strings are splitted at the equals sign, and the key parts will become
198: * keys of the returned <code>Properties</code> object, the value parts
199: * become values.
200: *
201: * @param key The configuration key.
202: * @return The associated properties if key is found.
203: *
204: * @throws ConversionException is thrown if the key maps to an
205: * object that is not a String/List.
206: *
207: * @throws IllegalArgumentException if one of the tokens is
208: * malformed (does not contain an equals sign).
209: */
210: Properties getProperties(String key);
211:
212: /**
213: * Get a boolean associated with the given configuration key.
214: *
215: * @param key The configuration key.
216: * @return The associated boolean.
217: *
218: * @throws ConversionException is thrown if the key maps to an
219: * object that is not a Boolean.
220: */
221: boolean getBoolean(String key);
222:
223: /**
224: * Get a boolean associated with the given configuration key.
225: * If the key doesn't map to an existing object, the default value
226: * is returned.
227: *
228: * @param key The configuration key.
229: * @param defaultValue The default value.
230: * @return The associated boolean.
231: *
232: * @throws ConversionException is thrown if the key maps to an
233: * object that is not a Boolean.
234: */
235: boolean getBoolean(String key, boolean defaultValue);
236:
237: /**
238: * Get a {@link Boolean} associated with the given configuration key.
239: *
240: * @param key The configuration key.
241: * @param defaultValue The default value.
242: * @return The associated boolean if key is found and has valid
243: * format, default value otherwise.
244: *
245: * @throws ConversionException is thrown if the key maps to an
246: * object that is not a Boolean.
247: */
248: Boolean getBoolean(String key, Boolean defaultValue);
249:
250: /**
251: * Get a byte associated with the given configuration key.
252: *
253: * @param key The configuration key.
254: * @return The associated byte.
255: *
256: * @throws ConversionException is thrown if the key maps to an
257: * object that is not a Byte.
258: */
259: byte getByte(String key);
260:
261: /**
262: * Get a byte associated with the given configuration key.
263: * If the key doesn't map to an existing object, the default value
264: * is returned.
265: *
266: * @param key The configuration key.
267: * @param defaultValue The default value.
268: * @return The associated byte.
269: *
270: * @throws ConversionException is thrown if the key maps to an
271: * object that is not a Byte.
272: */
273: byte getByte(String key, byte defaultValue);
274:
275: /**
276: * Get a {@link Byte} associated with the given configuration key.
277: *
278: * @param key The configuration key.
279: * @param defaultValue The default value.
280: * @return The associated byte if key is found and has valid format, default
281: * value otherwise.
282: *
283: * @throws ConversionException is thrown if the key maps to an object that
284: * is not a Byte.
285: */
286: Byte getByte(String key, Byte defaultValue);
287:
288: /**
289: * Get a double associated with the given configuration key.
290: *
291: * @param key The configuration key.
292: * @return The associated double.
293: *
294: * @throws ConversionException is thrown if the key maps to an
295: * object that is not a Double.
296: */
297: double getDouble(String key);
298:
299: /**
300: * Get a double associated with the given configuration key.
301: * If the key doesn't map to an existing object, the default value
302: * is returned.
303: *
304: * @param key The configuration key.
305: * @param defaultValue The default value.
306: * @return The associated double.
307: *
308: * @throws ConversionException is thrown if the key maps to an
309: * object that is not a Double.
310: */
311: double getDouble(String key, double defaultValue);
312:
313: /**
314: * Get a {@link Double} associated with the given configuration key.
315: *
316: * @param key The configuration key.
317: * @param defaultValue The default value.
318: * @return The associated double if key is found and has valid
319: * format, default value otherwise.
320: *
321: * @throws ConversionException is thrown if the key maps to an
322: * object that is not a Double.
323: */
324: Double getDouble(String key, Double defaultValue);
325:
326: /**
327: * Get a float associated with the given configuration key.
328: *
329: * @param key The configuration key.
330: * @return The associated float.
331: * @throws ConversionException is thrown if the key maps to an
332: * object that is not a Float.
333: */
334: float getFloat(String key);
335:
336: /**
337: * Get a float associated with the given configuration key.
338: * If the key doesn't map to an existing object, the default value
339: * is returned.
340: *
341: * @param key The configuration key.
342: * @param defaultValue The default value.
343: * @return The associated float.
344: *
345: * @throws ConversionException is thrown if the key maps to an
346: * object that is not a Float.
347: */
348: float getFloat(String key, float defaultValue);
349:
350: /**
351: * Get a {@link Float} associated with the given configuration key.
352: * If the key doesn't map to an existing object, the default value
353: * is returned.
354: *
355: * @param key The configuration key.
356: * @param defaultValue The default value.
357: * @return The associated float if key is found and has valid
358: * format, default value otherwise.
359: *
360: * @throws ConversionException is thrown if the key maps to an
361: * object that is not a Float.
362: */
363: Float getFloat(String key, Float defaultValue);
364:
365: /**
366: * Get a int associated with the given configuration key.
367: *
368: * @param key The configuration key.
369: * @return The associated int.
370: *
371: * @throws ConversionException is thrown if the key maps to an
372: * object that is not a Integer.
373: */
374: int getInt(String key);
375:
376: /**
377: * Get a int associated with the given configuration key.
378: * If the key doesn't map to an existing object, the default value
379: * is returned.
380: *
381: * @param key The configuration key.
382: * @param defaultValue The default value.
383: * @return The associated int.
384: *
385: * @throws ConversionException is thrown if the key maps to an
386: * object that is not a Integer.
387: */
388: int getInt(String key, int defaultValue);
389:
390: /**
391: * Get an {@link Integer} associated with the given configuration key.
392: * If the key doesn't map to an existing object, the default value
393: * is returned.
394: *
395: * @param key The configuration key.
396: * @param defaultValue The default value.
397: * @return The associated int if key is found and has valid format, default
398: * value otherwise.
399: *
400: * @throws ConversionException is thrown if the key maps to an object that
401: * is not a Integer.
402: */
403: Integer getInteger(String key, Integer defaultValue);
404:
405: /**
406: * Get a long associated with the given configuration key.
407: *
408: * @param key The configuration key.
409: * @return The associated long.
410: *
411: * @throws ConversionException is thrown if the key maps to an
412: * object that is not a Long.
413: */
414: long getLong(String key);
415:
416: /**
417: * Get a long associated with the given configuration key.
418: * If the key doesn't map to an existing object, the default value
419: * is returned.
420: *
421: * @param key The configuration key.
422: * @param defaultValue The default value.
423: * @return The associated long.
424: *
425: * @throws ConversionException is thrown if the key maps to an
426: * object that is not a Long.
427: */
428: long getLong(String key, long defaultValue);
429:
430: /**
431: * Get a {@link Long} associated with the given configuration key.
432: * If the key doesn't map to an existing object, the default value
433: * is returned.
434: *
435: * @param key The configuration key.
436: * @param defaultValue The default value.
437: * @return The associated long if key is found and has valid
438: * format, default value otherwise.
439: *
440: * @throws ConversionException is thrown if the key maps to an
441: * object that is not a Long.
442: */
443: Long getLong(String key, Long defaultValue);
444:
445: /**
446: * Get a short associated with the given configuration key.
447: *
448: * @param key The configuration key.
449: * @return The associated short.
450: *
451: * @throws ConversionException is thrown if the key maps to an
452: * object that is not a Short.
453: */
454: short getShort(String key);
455:
456: /**
457: * Get a short associated with the given configuration key.
458: *
459: * @param key The configuration key.
460: * @param defaultValue The default value.
461: * @return The associated short.
462: *
463: * @throws ConversionException is thrown if the key maps to an
464: * object that is not a Short.
465: */
466: short getShort(String key, short defaultValue);
467:
468: /**
469: * Get a {@link Short} 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: * @return The associated short if key is found and has valid
476: * format, default value otherwise.
477: *
478: * @throws ConversionException is thrown if the key maps to an
479: * object that is not a Short.
480: */
481: Short getShort(String key, Short defaultValue);
482:
483: /**
484: * Get a {@link BigDecimal} associated with the given configuration key.
485: *
486: * @param key The configuration key.
487: * @return The associated BigDecimal if key is found and has valid format
488: */
489: BigDecimal getBigDecimal(String key);
490:
491: /**
492: * Get a {@link BigDecimal} associated with the given configuration key.
493: * If the key doesn't map to an existing object, the default value
494: * is returned.
495: *
496: * @param key The configuration key.
497: * @param defaultValue The default value.
498: *
499: * @return The associated BigDecimal if key is found and has valid
500: * format, default value otherwise.
501: */
502: BigDecimal getBigDecimal(String key, BigDecimal defaultValue);
503:
504: /**
505: * Get a {@link BigInteger} associated with the given configuration key.
506: *
507: * @param key The configuration key.
508: *
509: * @return The associated BigInteger if key is found and has valid format
510: */
511: BigInteger getBigInteger(String key);
512:
513: /**
514: * Get a {@link BigInteger} associated with the given configuration key.
515: * If the key doesn't map to an existing object, the default value
516: * is returned.
517: *
518: * @param key The configuration key.
519: * @param defaultValue The default value.
520: *
521: * @return The associated BigInteger if key is found and has valid
522: * format, default value otherwise.
523: */
524: BigInteger getBigInteger(String key, BigInteger defaultValue);
525:
526: /**
527: * Get a string associated with the given configuration key.
528: *
529: * @param key The configuration key.
530: * @return The associated string.
531: *
532: * @throws ConversionException is thrown if the key maps to an object that
533: * is not a String.
534: */
535: String getString(String key);
536:
537: /**
538: * Get a string associated with the given configuration key.
539: * If the key doesn't map to an existing object, the default value
540: * is returned.
541: *
542: * @param key The configuration key.
543: * @param defaultValue The default value.
544: * @return The associated string if key is found and has valid
545: * format, default value otherwise.
546: *
547: * @throws ConversionException is thrown if the key maps to an object that
548: * is not a String.
549: */
550: String getString(String key, String defaultValue);
551:
552: /**
553: * Get an array of strings associated with the given configuration key.
554: * If the key doesn't map to an existing object an empty array is returned
555: *
556: * @param key The configuration key.
557: * @return The associated string array if key is found.
558: *
559: * @throws ConversionException is thrown if the key maps to an
560: * object that is not a String/List of Strings.
561: */
562: String[] getStringArray(String key);
563:
564: /**
565: * Get a List of strings associated with the given configuration key.
566: * If the key doesn't map to an existing object an empty List is returned.
567: *
568: * @param key The configuration key.
569: * @return The associated List.
570: *
571: * @throws ConversionException is thrown if the key maps to an
572: * object that is not a List.
573: */
574: List getList(String key);
575:
576: /**
577: * Get a List of strings associated with the given configuration key.
578: * If the key doesn't map to an existing object, the default value
579: * is returned.
580: *
581: * @param key The configuration key.
582: * @param defaultValue The default value.
583: * @return The associated List of strings.
584: *
585: * @throws ConversionException is thrown if the key maps to an
586: * object that is not a List.
587: */
588: List getList(String key, List defaultValue);
589: }
|