001: package net.myvietnam.mvncore.configuration;
002:
003: /* ====================================================================
004: * The Apache Software License, Version 1.1
005: *
006: * Copyright (c) 1999-2002 The Apache Software Foundation. All rights
007: * reserved.
008: *
009: * Redistribution and use in source and binary forms, with or without
010: * modification, are permitted provided that the following conditions
011: * are met:
012: *
013: * 1. Redistributions of source code must retain the above copyright
014: * notice, this list of conditions and the following disclaimer.
015: *
016: * 2. Redistributions in binary form must reproduce the above copyright
017: * notice, this list of conditions and the following disclaimer in
018: * the documentation and/or other materials provided with the
019: * distribution.
020: *
021: * 3. The end-user documentation included with the redistribution, if
022: * any, must include the following acknowledgement:
023: * "This product includes software developed by the
024: * Apache Software Foundation (http://www.apache.org/)."
025: * Alternately, this acknowledgement may appear in the software itself,
026: * if and wherever such third-party acknowledgements normally appear.
027: *
028: * 4. The names "The Jakarta Project", "Commons", and "Apache Software
029: * Foundation" must not be used to endorse or promote products derived
030: * from this software without prior written permission. For written
031: * permission, please contact apache@apache.org.
032: *
033: * 5. Products derived from this software may not be called "Apache"
034: * nor may "Apache" appear in their names without prior written
035: * permission of the Apache Software Foundation.
036: *
037: * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
038: * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
039: * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
040: * DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
041: * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
042: * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
043: * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
044: * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
045: * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
046: * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
047: * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
048: * SUCH DAMAGE.
049: * ====================================================================
050: *
051: * This software consists of voluntary contributions made by many
052: * individuals on behalf of the Apache Software Foundation. For more
053: * information on the Apache Software Foundation, please see
054: * <http://www.apache.org/>.
055: */
056:
057: import java.util.Iterator;
058: import java.util.Properties;
059: import java.util.Vector;
060:
061: /**
062: * Configuration interface.
063: * The general idea here is to make something that will work like our
064: * extended properties and be compatible with the preferences API if at all
065: * possible.
066: *
067: * @author <a href="mailto:jvanzyl@apache.org">Jason van Zyl</a>
068: * @author <a href="mailto:mpoeschl@marmot.at">Martin Poeschl</a>
069: * @version $Id: Configuration.java,v 1.3 2004/06/27 01:20:38 skoehler Exp $
070: */
071: public interface Configuration {
072: /**
073: * Create an Configuration object that is a subset
074: * of this one. The new Configuration object contains every key from
075: * the current Configuration that starts with prefix. The prefix is
076: * removed from the keys in the subset.
077: *
078: * @param prefix The prefix used to select the properties.
079: */
080: Configuration subset(String prefix);
081:
082: /**
083: * Check if the configuration is empty.
084: *
085: * @return true is the configuration contains no key/value pair, false otherwise
086: */
087: boolean isEmpty();
088:
089: /**
090: * Check if the configuration contains the key.
091: *
092: * @return true is the configuration contains a value for this key, false otherwise
093: */
094: boolean containsKey(String key);
095:
096: /**
097: * Add a property to the configuration. If it already exists then the value
098: * stated here will be added to the configuration entry. For example, if
099: *
100: * resource.loader = file
101: *
102: * is already present in the configuration and you
103: *
104: * addProperty("resource.loader", "classpath")
105: *
106: * Then you will end up with a Vector like the following:
107: *
108: * ["file", "classpath"]
109: *
110: * @param key The Key to add the property to.
111: * @param value The Value to add.
112: */
113: void addProperty(String key, Object value);
114:
115: /**
116: * Set a property, this will replace any previously
117: * set values. Set values is implicitly a call
118: * to clearProperty(key), addProperty(key,value).
119: *
120: * @param key The key of the property to change
121: * @param value The new value
122: */
123: void setProperty(String key, Object value);
124:
125: /**
126: * Clear a property in the configuration.
127: *
128: * @param key the key to remove along with corresponding value.
129: */
130: void clearProperty(String key);
131:
132: /**
133: * Gets a property from the configuration.
134: *
135: * @param key property to retrieve
136: * @return value as object. Will return user value if exists,
137: * if not then default value if exists, otherwise null
138: */
139: Object getProperty(String key);
140:
141: /**
142: * Get the list of the keys contained in the configuration
143: * repository that match the specified prefix.
144: *
145: * @param prefix The prefix to test against.
146: * @return An Iterator of keys that match the prefix.
147: */
148: Iterator getKeys(String prefix);
149:
150: /**
151: * Get the list of the keys contained in the configuration
152: * repository.
153: *
154: * @return An Iterator.
155: */
156: Iterator getKeys();
157:
158: /**
159: * Get a list of properties associated with the given
160: * configuration key.
161: *
162: * @param key The configuration key.
163: * @return The associated properties if key is found.
164: * @exception ClassCastException is thrown if the key maps to an
165: * object that is not a String/Vector.
166: * @exception IllegalArgumentException if one of the tokens is
167: * malformed (does not contain an equals sign).
168: */
169: Properties getProperties(String key);
170:
171: // We probably want to at least try to be compatible with
172: // the new preferences API.
173:
174: /**
175: * Get a boolean associated with the given configuration key.
176: *
177: * @param key The configuration key.
178: * @return The associated boolean.
179: * @exception java.util.NoSuchElementException is thrown if the key doesn't
180: * map to an existing object.
181: * @exception ClassCastException is thrown if the key maps to an
182: * object that is not a Boolean.
183: */
184: boolean getBoolean(String key);
185:
186: /**
187: * Get a boolean associated with the given configuration key.
188: *
189: * @param key The configuration key.
190: * @param defaultValue The default value.
191: * @return The associated boolean.
192: * @exception ClassCastException is thrown if the key maps to an
193: * object that is not a Boolean.
194: */
195: boolean getBoolean(String key, boolean defaultValue);
196:
197: /**
198: * Get a boolean associated with the given configuration key.
199: *
200: * @param key The configuration key.
201: * @param defaultValue The default value.
202: * @return The associated boolean if key is found and has valid
203: * format, default value otherwise.
204: * @exception ClassCastException is thrown if the key maps to an
205: * object that is not a Boolean.
206: */
207: Boolean getBoolean(String key, Boolean defaultValue);
208:
209: /**
210: * Get a byte associated with the given configuration key.
211: *
212: * @param key The configuration key.
213: * @return The associated byte.
214: * @exception java.util.NoSuchElementException is thrown if the key doesn't
215: * map to an existing object.
216: * @exception ClassCastException is thrown if the key maps to an
217: * object that is not a Byte.
218: * @exception NumberFormatException is thrown if the value mapped
219: * by the key has not a valid number format.
220: */
221: byte getByte(String key);
222:
223: /**
224: * Get a byte associated with the given configuration key.
225: *
226: * @param key The configuration key.
227: * @param defaultValue The default value.
228: * @return The associated byte.
229: * @exception ClassCastException is thrown if the key maps to an
230: * object that is not a Byte.
231: * @exception NumberFormatException is thrown if the value mapped
232: * by the key has not a valid number format.
233: */
234: byte getByte(String key, byte defaultValue);
235:
236: /**
237: * Get a byte associated with the given configuration key.
238: *
239: * @param key The configuration key.
240: * @param defaultValue The default value.
241: * @return The associated byte if key is found and has valid format, default
242: * value otherwise.
243: * @exception ClassCastException is thrown if the key maps to an object that
244: * is not a Byte.
245: * @exception NumberFormatException is thrown if the value mapped by the key
246: * has not a valid number format.
247: */
248: Byte getByte(String key, Byte defaultValue);
249:
250: /**
251: * Get a double associated with the given configuration key.
252: *
253: * @param key The configuration key.
254: * @return The associated double.
255: * @exception java.util.NoSuchElementException is thrown if the key doesn't
256: * map to an existing object.
257: * @exception ClassCastException is thrown if the key maps to an
258: * object that is not a Double.
259: * @exception NumberFormatException is thrown if the value mapped
260: * by the key has not a valid number format.
261: */
262: double getDouble(String key);
263:
264: /**
265: * Get a double associated with the given configuration key.
266: *
267: * @param key The configuration key.
268: * @param defaultValue The default value.
269: * @return The associated double.
270: * @exception ClassCastException is thrown if the key maps to an
271: * object that is not a Double.
272: * @exception NumberFormatException is thrown if the value mapped
273: * by the key has not a valid number format.
274: */
275: double getDouble(String key, double defaultValue);
276:
277: /**
278: * Get a double associated with the given configuration key.
279: *
280: * @param key The configuration key.
281: * @param defaultValue The default value.
282: * @return The associated double if key is found and has valid
283: * format, default value otherwise.
284: * @exception ClassCastException is thrown if the key maps to an
285: * object that is not a Double.
286: * @exception NumberFormatException is thrown if the value mapped
287: * by the key has not a valid number format.
288: */
289: Double getDouble(String key, Double defaultValue);
290:
291: /**
292: * Get a float associated with the given configuration key.
293: *
294: * @param key The configuration key.
295: * @return The associated float.
296: * @exception java.util.NoSuchElementException is thrown if the key doesn't
297: * map to an existing object.
298: * @exception ClassCastException is thrown if the key maps to an
299: * object that is not a Float.
300: * @exception NumberFormatException is thrown if the value mapped
301: * by the key has not a valid number format.
302: */
303: float getFloat(String key);
304:
305: /**
306: * Get a float associated with the given configuration key.
307: *
308: * @param key The configuration key.
309: * @param defaultValue The default value.
310: * @return The associated float.
311: * @exception ClassCastException is thrown if the key maps to an
312: * object that is not a Float.
313: * @exception NumberFormatException is thrown if the value mapped
314: * by the key has not a valid number format.
315: */
316: float getFloat(String key, float defaultValue);
317:
318: /**
319: * Get a float associated with the given configuration key.
320: *
321: * @param key The configuration key.
322: * @param defaultValue The default value.
323: * @return The associated float if key is found and has valid
324: * format, default value otherwise.
325: * @exception ClassCastException is thrown if the key maps to an
326: * object that is not a Float.
327: * @exception NumberFormatException is thrown if the value mapped
328: * by the key has not a valid number format.
329: */
330: Float getFloat(String key, Float defaultValue);
331:
332: /**
333: * Get a int associated with the given configuration key.
334: *
335: * @param key The configuration key.
336: * @return The associated int.
337: * @exception java.util.NoSuchElementException is thrown if the key doesn't
338: * map to an existing object.
339: * @exception ClassCastException is thrown if the key maps to an
340: * object that is not a Integer.
341: * @exception NumberFormatException is thrown if the value mapped
342: * by the key has not a valid number format.
343: */
344: int getInt(String key);
345:
346: /**
347: * Get a int associated with the given configuration key.
348: *
349: * @param key The configuration key.
350: * @param defaultValue The default value.
351: * @return The associated int.
352: * @exception ClassCastException is thrown if the key maps to an
353: * object that is not a Integer.
354: * @exception NumberFormatException is thrown if the value mapped
355: * by the key has not a valid number format.
356: */
357: int getInt(String key, int defaultValue);
358:
359: /**
360: * Get a int associated with the given configuration key.
361: *
362: * @param key The configuration key.
363: * @param defaultValue The default value.
364: * @return The associated int if key is found and has valid format, default
365: * value otherwise.
366: * @exception ClassCastException is thrown if the key maps to an object that
367: * is not a Integer.
368: * @exception NumberFormatException is thrown if the value mapped by the key
369: * has not a valid number format.
370: */
371: Integer getInteger(String key, Integer defaultValue);
372:
373: /**
374: * Get a long associated with the given configuration key.
375: *
376: * @param key The configuration key.
377: * @return The associated long.
378: * @exception java.util.NoSuchElementException is thrown if the key doesn't
379: * map to an existing object.
380: * @exception ClassCastException is thrown if the key maps to an
381: * object that is not a Long.
382: * @exception NumberFormatException is thrown if the value mapped
383: * by the key has not a valid number format.
384: */
385: long getLong(String key);
386:
387: /**
388: * Get a long associated with the given configuration key.
389: *
390: * @param key The configuration key.
391: * @param defaultValue The default value.
392: * @return The associated long.
393: * @exception ClassCastException is thrown if the key maps to an
394: * object that is not a Long.
395: * @exception NumberFormatException is thrown if the value mapped
396: * by the key has not a valid number format.
397: */
398: long getLong(String key, long defaultValue);
399:
400: /**
401: * Get a long associated with the given configuration key.
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: * @exception ClassCastException is thrown if the key maps to an
408: * object that is not a Long.
409: * @exception NumberFormatException is thrown if the value mapped
410: * by the key has not a valid number format.
411: */
412: Long getLong(String key, Long defaultValue);
413:
414: /**
415: * Get a short associated with the given configuration key.
416: *
417: * @param key The configuration key.
418: * @return The associated short.
419: * @exception java.util.NoSuchElementException is thrown if the key doesn't
420: * map to an existing object.
421: * @exception ClassCastException is thrown if the key maps to an
422: * object that is not a Short.
423: * @exception NumberFormatException is thrown if the value mapped
424: * by the key has not a valid number format.
425: */
426: short getShort(String key);
427:
428: /**
429: * Get a short associated with the given configuration key.
430: *
431: * @param key The configuration key.
432: * @param defaultValue The default value.
433: * @return The associated short.
434: * @exception ClassCastException is thrown if the key maps to an
435: * object that is not a Short.
436: * @exception NumberFormatException is thrown if the value mapped
437: * by the key has not a valid number format.
438: */
439: short getShort(String key, short defaultValue);
440:
441: /**
442: * Get a short associated with the given configuration key.
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: * @exception ClassCastException is thrown if the key maps to an
449: * object that is not a Short.
450: * @exception NumberFormatException is thrown if the value mapped
451: * by the key has not a valid number format.
452: * @exception java.util.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 string associated with the given configuration key.
459: *
460: * @param key The configuration key.
461: * @return The associated string.
462: * @exception ClassCastException is thrown if the key maps to an object that
463: * is not a String.
464: * @exception java.util.NoSuchElementException is thrown if the key doesn't
465: * map to an existing object.
466: */
467: String getString(String key);
468:
469: /**
470: * Get a string associated with the given configuration key.
471: *
472: * @param key The configuration key.
473: * @param defaultValue The default value.
474: * @return The associated string if key is found and has valid
475: * format, default value otherwise.
476: * @exception ClassCastException is thrown if the key maps to an object that
477: * is not a String.
478: */
479: String getString(String key, String defaultValue);
480:
481: /**
482: * Get an array of strings associated with the given configuration
483: * key.
484: *
485: * @param key The configuration key.
486: * @return The associated string array if key is found.
487: * @exception ClassCastException is thrown if the key maps to an
488: * object that is not a String/Vector of Strings.
489: */
490: String[] getStringArray(String key);
491:
492: /**
493: * Get a Vector of strings associated with the given configuration key.
494: *
495: * @param key The configuration key.
496: * @return The associated Vector.
497: * @exception ClassCastException is thrown if the key maps to an
498: * object that is not a Vector.
499: */
500: Vector getVector(String key);
501:
502: /**
503: * Get a Vector of strings associated with the given configuration key.
504: *
505: * @param key The configuration key.
506: * @param defaultValue The default value.
507: * @return The associated Vector.
508: * @exception ClassCastException is thrown if the key maps to an
509: * object that is not a Vector.
510: */
511: Vector getVector(String key, Vector defaultValue);
512: }
|