KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > avalon > framework > configuration > Configuration


1 /* ====================================================================
2  * The Apache Software License, Version 1.1
3  *
4  * Copyright (c) 1997-2003 The Apache Software Foundation. All rights
5  * reserved.
6  *
7  * Redistribution and use in source and binary forms, with or without
8  * modification, are permitted provided that the following conditions
9  * are met:
10  *
11  * 1. Redistributions of source code must retain the above copyright
12  * notice, this list of conditions and the following disclaimer.
13  *
14  * 2. Redistributions in binary form must reproduce the above copyright
15  * notice, this list of conditions and the following disclaimer in
16  * the documentation and/or other materials provided with the
17  * distribution.
18  *
19  * 3. The end-user documentation included with the redistribution,
20  * if any, must include the following acknowledgment:
21  * "This product includes software developed by the
22  * Apache Software Foundation (http://www.apache.org/)."
23  * Alternately, this acknowledgment may appear in the software
24  * itself, if and wherever such third-party acknowledgments
25  * normally appear.
26  *
27  * 4. The names "Jakarta", "Avalon", and "Apache Software Foundation"
28  * must not be used to endorse or promote products derived from this
29  * software without prior written permission. For written
30  * permission, please contact apache@apache.org.
31  *
32  * 5. Products derived from this software may not be called "Apache",
33  * nor may "Apache" appear in their name, without prior written
34  * permission of the Apache Software Foundation.
35  *
36  * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
37  * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
38  * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
39  * DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
40  * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
41  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
42  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
43  * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
44  * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
45  * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
46  * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
47  * SUCH DAMAGE.
48  * ====================================================================
49  *
50  * This software consists of voluntary contributions made by many
51  * individuals on behalf of the Apache Software Foundation. For more
52  * information on the Apache Software Foundation, please see
53  * <http://www.apache.org/>.
54  */
55 package org.apache.avalon.framework.configuration;
56
57 /**
58  * <code>Configuration</code> is a interface encapsulating a configuration node
59  * used to retrieve configuration values.
60  *
61  * <p>
62  * This is a "read only" interface preventing applications from modifying their
63  * own configurations. Once it is created, the information never changes.
64  * </p>
65  * <h3>Data Model</h3>
66  * <p>
67  * The data model is a subset of XML's; a single-rooted hierarchical tree where each
68  * node can contain multiple <em>attributes</em>, and leaf nodes can also
69  * contain a <em>value</em>. Reflecting this, <code>Configuration</code>s are
70  * usually built from an XML file by the {@link DefaultConfigurationBuilder}
71  * class, or directly by a SAX parser using a {@link SAXConfigurationHandler} or
72  * {@link NamespacedSAXConfigurationHandler} event handler.
73  * </p>
74  * <h4>Namespace support</h4>
75  * <p>
76  * Since version 4.1, each <code>Configuration</code> node has a namespace
77  * associated with it, in the form of a string, accessible through {@link
78  * #getNamespace}. If no namespace is present, <code>getNamespace</code> will
79  * return blank (""). See {@link DefaultConfigurationBuilder} for details on how
80  * XML namespaces are mapped to <code>Configuration</code> namespaces.
81  * </p>
82  * <h3>Example</h3>
83  * <p>
84  * As an example, consider two <code>Configuration</code>s (with and without
85  * namespaces) built from this XML:
86  * </p>
87  * <pre>
88  * &lt;my-system version="1.3" xmlns:doc="http://myco.com/documentation"&gt;
89  * &lt;doc:desc&gt;This is a highly fictitious config file&lt;/doc:desc&gt;
90  * &lt;widget name="fooWidget" initOrder="1" threadsafe="true"/&gt;
91  * &lt;/my-system&gt;
92  * </pre>
93  * <p>If namespace support is enabled (eg through {@link
94  * DefaultConfigurationBuilder#DefaultConfigurationBuilder(boolean) new
95  * DefaultConfigurationBuilder(true)}), then the <code>xmlns:doc</code> element
96  * will not translate into a Configuration attribute, and the
97  * <code>doc:desc</code> element will become a <code>Configuration</code> node
98  * with name "desc" and namespace "http://myco.com/documentation". The
99  * <code>widget</code> element will have namespace "".
100  * </p>
101  * <p>If namespace support is disabled (the default for {@link
102  * DefaultConfigurationBuilder}), the above XML will translate directly to
103  * <code>Configuration</code> nodes. The <code>my-system</code> node will have
104  * an attribute named "xmlns:doc", and a child called "doc:desc".
105  * </p>
106  * <p>
107  * Assuming the <code>Configuration</code> object is named <code>conf</code>,
108  * here is how the data could be retrieved:
109  * </p>
110  * <table border="1">
111  * <tr align="center"><th>Code</th><th>No namespaces</th><th>With namespaces</th></tr>
112  * <tr align="center"><td align="left">
113  * <code>conf.{@link #getName getName}()</code></td><td colspan="2">my-system</td></tr>
114  * <tr align="center"><td align="left">
115  * <code>conf.{@link #getAttributeNames getAttributeNames}().length</code>
116  * </td><td>2</td><td>1</td></tr>
117  * <tr align="center"><td align="left">
118  * <code>conf.{@link #getChildren getChildren}().length</code>
119  * </td><td colspan="2">2</td></tr>
120  * <tr align="center"><td align="left">
121  * <code>conf.{@link #getAttributeAsFloat getAttributeAsFloat}("version")</code>
122  * </td><td colspan="2">1.3</td></tr>
123  * <tr align="center"><td align="left">
124  * <code>conf.{@link #getChild getChild}("widget").{@link #getAttribute getAttribute}("name")</code>
125  * </td><td colspan="2">fooWidget</td></tr>
126  * <tr align="center"><td align="left">
127  * <code>conf.{@link #getChild getChild}("widget")
128  * .{@link #getAttributeAsBoolean getAttributeAsBoolean}("threadsafe")</code></td><td colspan="2">
129  * <code>true</code></td></tr>
130  * <tr align="center"><td align="left">
131  * <code>conf.{@link #getChild getChild}("widget").{@link #getLocation getLocation}()</code>
132  * </td><td colspan="2">file:///home/jeff/tmp/java/avalon/src/java/new.xconf:4:60</td></tr>
133  * <tr align="center"><td align="left">
134  * <code>conf.{@link #getChild getChild}("desc").{@link #getName getName}()</code>
135  * </td><td>desc (see {@link #getChild(String)})</td><td>desc</td></tr>
136  * <tr align="center"><td align="left">
137  * <code>conf.{@link #getChild getChild}("doc:desc").{@link #getName getName}()</code>
138  * </td><td>doc:desc</td><td>doc:desc (see {@link #getChild(String)})</td></tr>
139  * <tr align="center"><td align="left">
140  * <code>conf.{@link #getChild getChild}("desc").{@link #getValue getValue}()</code>
141  * </td><td>{@link ConfigurationException}</td><td>This is a highly fictitious config file</td></tr>
142  * <tr align="center"><td align="left">
143  * <code>conf.{@link #getChild getChild}("doc:desc").{@link #getValue getValue}()</code>
144  * </td><td>This is a highly fictitious config file</td><td>{@link ConfigurationException}</td></tr>
145  * <tr align="center"><td align="left">
146  * <code>conf.{@link #getChild getChild}("desc").{@link #getNamespace getNamespace}()</code>
147  * </td><td>&nbsp;</td><td>http://myco.com/documentation"</td></tr>
148  * </table>
149  * </p>
150  * <p>
151  * Type-safe utility methods are provided for retrieving attribute and element
152  * values as <code>String</code>, <code>int</code>, <code>long</code>,
153  * <code>float</code> and <code>boolean</code>.
154  * </p>
155  * <h3>Miscellanea</h3>
156  * <p>
157  * Currently, the configuration tree can only be traversed one node at a time,
158  * eg., through {@link #getChild getChild("foo")} or {@link #getChildren}. In
159  * a future release, it may be possible to access child nodes with an XPath-like
160  * syntax.
161  * </p>
162  * <p>
163  * Checking for the existence of an attribute can be done as follows:
164  * </p>
165  * <pre>
166  *String value = conf.getAttribute( "myAttribute", null );
167  * if ( null == value )
168  * {
169  * // Do the processing applicable if the attribute isn't present.
170  * }
171  * </pre>
172  *
173  * @author <a HREF="mailto:dev@avalon.apache.org">Avalon Development Team</a>
174  * @version CVS $Revision: 1.27 $ $Date: 2003/02/11 15:58:38 $
175  */
176 public interface Configuration
177 {
178     /**
179      * Return the name of the node.
180      *
181      * @return name of the <code>Configuration</code> node.
182      */
183     String JavaDoc getName();
184
185     /**
186      * Return a string describing location of Configuration.
187      * Location can be different for different mediums (ie "file:line" for normal XML files or
188      * "table:primary-key" for DB based configurations);
189      *
190      * @return a string describing location of Configuration
191      */
192     String JavaDoc getLocation();
193
194     /**
195      * Returns a string indicating which namespace this Configuration node
196      * belongs to.
197      *
198      * <p>
199      * What this returns is dependent on the configuration file and the
200      * Configuration builder. If the Configuration builder does not support
201      * namespaces, this method will return a blank string.
202      * </p>
203      * <p>In the case of {@link DefaultConfigurationBuilder}, the namespace will
204      * be the URI associated with the XML element. Eg.,:</p>
205      * <pre>
206      * &lt;foo xmlns:x="http://blah.com"&gt;
207      * &lt;x:bar/&gt;
208      * &lt;/foo&gt;
209      * </pre>
210      * <p>The namespace of <code>foo</code> will be "", and the namespace of
211      * <code>bar</code> will be "http://blah.com".</p>
212      *
213      * @return a String identifying the namespace of this Configuration.
214      * @throws ConfigurationException if an error occurs
215      * @since 4.1
216      */
217     String JavaDoc getNamespace() throws ConfigurationException;
218
219     /**
220      * Return a new <code>Configuration</code> instance encapsulating the
221      * specified child node.
222      * <p>
223      * If no such child node exists, an empty <code>Configuration</code> will be
224      * returned, allowing constructs such as
225      * <code>conf.getChild("foo").getChild("bar").getChild("baz").{@link
226      * #getValue(String) getValue}("default");</code>
227      * </p>
228      * <p>
229      * If you wish to get a <code>null</code> return when no element is present,
230      * use {@link #getChild(String, boolean) getChild("foo", <b>false</b>)}.
231      * </p>
232      *
233      * @param child The name of the child node.
234      * @return Configuration
235      */
236     Configuration getChild( String JavaDoc child );
237
238     /**
239      * Return a <code>Configuration</code> instance encapsulating the specified
240      * child node.
241      *
242      * @param child The name of the child node.
243      * @param createNew If <code>true</code>, a new <code>Configuration</code>
244      * will be created and returned if the specified child does not exist. If
245      * <code>false</code>, <code>null</code> will be returned when the specified
246      * child doesn't exist.
247      * @return Configuration
248      */
249     Configuration getChild( String JavaDoc child, boolean createNew );
250
251     /**
252      * Return an <code>Array</code> of <code>Configuration</code>
253      * elements containing all node children. The array order will reflect the
254      * order in the source config file.
255      *
256      * @return All child nodes
257      */
258     Configuration[] getChildren();
259
260     /**
261      * Return an <code>Array</code> of <code>Configuration</code>
262      * elements containing all node children with the specified name. The array
263      * order will reflect the order in the source config file.
264      *
265      * @param name The name of the children to get.
266      * @return The child nodes with name <code>name</code>
267      */
268     Configuration[] getChildren( String JavaDoc name );
269
270     /**
271      * Return an array of all attribute names.
272      * <p>
273      * <em>The order of attributes in this array can not be relied on.</em> As
274      * with XML, a <code>Configuration</code>'s attributes are an
275      * <em>unordered</em> set. If your code relies on order, eg
276      * <tt>conf.getAttributeNames()[0]</tt>, then it is liable to break if a
277      * different XML parser is used.
278      * </p>
279      * @return a <code>String[]</code> value
280      */
281     String JavaDoc[] getAttributeNames();
282
283     /**
284      * Return the value of specified attribute.
285      *
286      * @param paramName The name of the parameter you ask the value of.
287      * @return String value of attribute.
288      * @throws ConfigurationException If no attribute with that name exists.
289      */
290     String JavaDoc getAttribute( String JavaDoc paramName ) throws ConfigurationException;
291
292     /**
293      * Return the <code>int</code> value of the specified attribute contained
294      * in this node.
295      *
296      * @param paramName The name of the parameter you ask the value of.
297      * @return int value of attribute
298      * @throws ConfigurationException If no parameter with that name exists.
299      * or if conversion to <code>int</code> fails.
300      *
301      */
302     int getAttributeAsInteger( String JavaDoc paramName ) throws ConfigurationException;
303
304     /**
305      * Returns the value of the attribute specified by its name as a
306      * <code>long</code>.
307      *
308      * @param name The name of the parameter you ask the value of.
309      * @return long value of attribute
310      * @throws ConfigurationException If no parameter with that name exists.
311      * or if conversion to <code>long</code> fails.
312      */
313     long getAttributeAsLong( String JavaDoc name ) throws ConfigurationException;
314
315     /**
316      * Return the <code>float</code> value of the specified parameter contained
317      * in this node.
318      *
319      * @param paramName The name of the parameter you ask the value of.
320      * @return float value of attribute
321      * @throws ConfigurationException If no parameter with that name exists.
322      * or if conversion to <code>float</code> fails.
323      */
324     float getAttributeAsFloat( String JavaDoc paramName ) throws ConfigurationException;
325
326     /**
327      * Return the <code>boolean</code> value of the specified parameter contained
328      * in this node.
329      *
330      * @param paramName The name of the parameter you ask the value of.
331      * @return boolean value of attribute
332      * @throws ConfigurationException If no parameter with that name exists.
333      * or if conversion to <code>boolean</code> fails.
334      */
335     boolean getAttributeAsBoolean( String JavaDoc paramName ) throws ConfigurationException;
336
337     /**
338      * Return the <code>String</code> value of the node.
339      *
340      * @return the value of the node.
341      * @throws ConfigurationException if an error occurs
342      */
343     String JavaDoc getValue() throws ConfigurationException;
344
345     /**
346      * Return the <code>int</code> value of the node.
347      *
348      * @return the value of the node.
349      *
350      * @throws ConfigurationException If conversion to <code>int</code> fails.
351      */
352     int getValueAsInteger() throws ConfigurationException;
353
354     /**
355      * Return the <code>float</code> value of the node.
356      *
357      * @return the value of the node.
358      * @throws ConfigurationException If conversion to <code>float</code> fails.
359      */
360     float getValueAsFloat() throws ConfigurationException;
361
362     /**
363      * Return the <code>boolean</code> value of the node.
364      *
365      * @return the value of the node.
366      * @throws ConfigurationException If conversion to <code>boolean</code> fails.
367      */
368     boolean getValueAsBoolean() throws ConfigurationException;
369
370     /**
371      * Return the <code>long</code> value of the node.
372      *
373      * @return the value of the node.
374      * @throws ConfigurationException If conversion to <code>long</code> fails.
375      */
376     long getValueAsLong() throws ConfigurationException;
377
378     /**
379      * Returns the value of the configuration element as a <code>String</code>.
380      * If the configuration value is not set, the default value will be
381      * used.
382      *
383      * @param defaultValue The default value desired.
384      * @return String value of the <code>Configuration</code>, or default
385      * if none specified.
386      */
387     String JavaDoc getValue( String JavaDoc defaultValue );
388
389     /**
390      * Returns the value of the configuration element as an <code>int</code>.
391      * If the configuration value is not set, the default value will be
392      * used.
393      *
394      * @param defaultValue The default value desired.
395      * @return int value of the <code>Configuration</code>, or default
396      * if none specified.
397      */
398     int getValueAsInteger( int defaultValue );
399
400     /**
401      * Returns the value of the configuration element as a <code>long</code>.
402      * If the configuration value is not set, the default value will be
403      * used.
404      *
405      * @param defaultValue The default value desired.
406      * @return long value of the <code>Configuration</code>, or default
407      * if none specified.
408      */
409     long getValueAsLong( long defaultValue );
410
411     /**
412      * Returns the value of the configuration element as a <code>float</code>.
413      * If the configuration value is not set, the default value will be
414      * used.
415      *
416      * @param defaultValue The default value desired.
417      * @return float value of the <code>Configuration</code>, or default
418      * if none specified.
419      */
420     float getValueAsFloat( float defaultValue );
421
422     /**
423      * Returns the value of the configuration element as a <code>boolean</code>.
424      * If the configuration value is not set, the default value will be
425      * used.
426      *
427      * @param defaultValue The default value desired.
428      * @return boolean value of the <code>Configuration</code>, or default
429      * if none specified.
430      */
431     boolean getValueAsBoolean( boolean defaultValue );
432
433     /**
434      * Returns the value of the attribute specified by its name as a
435      * <code>String</code>, or the default value if no attribute by
436      * that name exists or is empty.
437      *
438      * @param name The name of the attribute you ask the value of.
439      * @param defaultValue The default value desired.
440      * @return String value of attribute. It will return the default
441      * value if the named attribute does not exist, or if
442      * the value is not set.
443      */
444     String JavaDoc getAttribute( String JavaDoc name, String JavaDoc defaultValue );
445
446     /**
447      * Returns the value of the attribute specified by its name as a
448      * <code>int</code>, or the default value if no attribute by
449      * that name exists or is empty.
450      *
451      * @param name The name of the attribute you ask the value of.
452      * @param defaultValue The default value desired.
453      * @return int value of attribute. It will return the default
454      * value if the named attribute does not exist, or if
455      * the value is not set.
456      */
457     int getAttributeAsInteger( String JavaDoc name, int defaultValue );
458
459     /**
460      * Returns the value of the attribute specified by its name as a
461      * <code>long</code>, or the default value if no attribute by
462      * that name exists or is empty.
463      *
464      * @param name The name of the attribute you ask the value of.
465      * @param defaultValue The default value desired.
466      * @return long value of attribute. It will return the default
467      * value if the named attribute does not exist, or if
468      * the value is not set.
469      */
470     long getAttributeAsLong( String JavaDoc name, long defaultValue );
471
472     /**
473      * Returns the value of the attribute specified by its name as a
474      * <code>float</code>, or the default value if no attribute by
475      * that name exists or is empty.
476      *
477      * @param name The name of the attribute you ask the value of.
478      * @param defaultValue The default value desired.
479      * @return float value of attribute. It will return the default
480      * value if the named attribute does not exist, or if
481      * the value is not set.
482      */
483     float getAttributeAsFloat( String JavaDoc name, float defaultValue );
484
485     /**
486      * Returns the value of the attribute specified by its name as a
487      * <code>boolean</code>, or the default value if no attribute by
488      * that name exists or is empty.
489      *
490      * @param name The name of the attribute you ask the value of.
491      * @param defaultValue The default value desired.
492      * @return boolean value of attribute. It will return the default
493      * value if the named attribute does not exist, or if
494      * the value is not set.
495      */
496     boolean getAttributeAsBoolean( String JavaDoc name, boolean defaultValue );
497 }
498
Popular Tags