View Javadoc

1   /*
2    * Copyright (C) The DNA Group. All rights reserved.
3    *
4    * This software is published under the terms of the DNA
5    * Software License version 1.1, a copy of which has been included
6    * with this distribution in the LICENSE.txt file.
7    */
8   package org.codehaus.dna;
9   
10  /***
11   * The configuration object represents hierarchial configuration
12   * data. The data represented by this object is a simplified XML
13   * format. Configuration objects are unable to represent namespace
14   * information and elements can not have mixed content. ie
15   * Configuration elements can not have both a value and child
16   * elements.
17   *
18   * @version $Revision: 1.2 $ $Date: 2004/05/01 09:51:48 $
19   */
20  public interface Configuration
21  {
22      /***
23       * Return the name of the configuration element.
24       *
25       * @return the name of the configuration element.
26       */
27      String getName();
28  
29      /***
30       * Return the path to the configuration element.
31       * The path should be in the xpath form but may
32       * be the empty string if unabel to determine path.
33       *
34       * @return the path to the configuration element.
35       */
36      String getPath();
37  
38      /***
39       * Return the location of configuration element.
40       * Usually of the form "uri[:line number[:column number]]"
41       * if possible. ie "file:myFile.xml:80:2". However the line
42       * number and column number may be elided if unavailable.
43       *
44       * @return the location of configuration element.
45       */
46      String getLocation();
47  
48      /***
49       * Return an array of all the child elements.
50       *
51       * @return an array of all the child elements.
52       */
53      Configuration[] getChildren();
54  
55      /***
56       * Return an array of all the child elements with specified name.
57       *
58       * @param name the name of child configuration objects
59       * @return an array of all the child elements with specified name.
60       */
61      Configuration[] getChildren( String name );
62  
63      /***
64       * Return a child Configuration element with specified name.
65       * If no such element exists an element will be autocreated.
66       *
67       * @param name the name of child configuration object
68       * @return a child Configuration element with specified name.
69       */
70      Configuration getChild( String name );
71  
72      /***
73       * Return a child Configuration element with specified name.
74       * If no such element exists and createChild is true then an
75       * element will be autocreated otherwise null will be returned.
76       *
77       * @param name the name of child configuration object
78       * @param createChild true if child should be created if it does not exist
79       * @return a child Configuration element with specified name.
80       */
81      Configuration getChild( String name, boolean createChild );
82  
83      /***
84       * Return text value of element.
85       *
86       * @return the value
87       * @throws ConfigurationException if no value in element
88       */
89      String getValue()
90          throws ConfigurationException;
91  
92      /***
93       * Return text value of element.
94       * Use specified default if no value in element.
95       *
96       * @param defaultValue the default value
97       * @return the value
98       */
99      String getValue( String defaultValue );
100 
101     /***
102      * Return text value of element as an integer.
103      *
104      * @return the value
105      * @throws ConfigurationException if no value in element
106      *         or value can not be converted to correct type
107      */
108     int getValueAsInteger()
109         throws ConfigurationException;
110 
111     /***
112      * Return text value of element as an integer.
113      * Use specified default if no value in element or
114      * value can not be converted to correct type.
115      *
116      * @param defaultValue the default value
117      * @return the value
118      */
119     int getValueAsInteger( int defaultValue );
120 
121     /***
122      * Return text value of element as a long.
123      *
124      * @return the value
125      * @throws ConfigurationException if no value in element
126      *         or value can not be converted to correct type
127      */
128     long getValueAsLong()
129         throws ConfigurationException;
130 
131     /***
132      * Return text value of element as a long.
133      * Use specified default if no value in element or
134      * value can not be converted to correct type.
135      *
136      * @param defaultValue the default value
137      * @return the value
138      */
139     long getValueAsLong( long defaultValue );
140 
141     /***
142      * Return text value of element as a boolean.
143      *
144      * @return the value
145      * @throws ConfigurationException if no value in element
146      *         or value can not be converted to correct type
147      */
148     boolean getValueAsBoolean()
149         throws ConfigurationException;
150 
151     /***
152      * Return text value of element as a boolean.
153      * Use specified default if no value in element or
154      * value can not be converted to correct type.
155      *
156      * @param defaultValue the default value
157      * @return the value
158      */
159     boolean getValueAsBoolean( boolean defaultValue );
160 
161     /***
162      * Return text value of element as a float.
163      *
164      * @return the value
165      * @throws ConfigurationException if no value in element
166      *         or value can not be converted to correct type
167      */
168     float getValueAsFloat()
169         throws ConfigurationException;
170 
171     /***
172      * Return text value of element as a float.
173      * Use specified default if no value in element or
174      * value can not be converted to correct type.
175      *
176      * @param defaultValue the default value
177      * @return the value
178      */
179     float getValueAsFloat( float defaultValue );
180 
181     /***
182      * Return an array of all the attribute names.
183      *
184      * @return an array of all the attribute names.
185      */
186     String[] getAttributeNames();
187 
188     /***
189      * Return attribute value with specified name.
190      *
191      * @param name the attribute name
192      * @return the attribute value
193      * @throws ConfigurationException if no attribute with
194      *         specified name
195      */
196     String getAttribute( String name )
197         throws ConfigurationException;
198 
199     /***
200      * Return attribute value with specified name.
201      * If no attribute with specified name then return
202      * default value.
203      *
204      * @param name the attribute name
205      * @param defaultValue the default value
206      * @return the attribute value
207      */
208     String getAttribute( String name, String defaultValue );
209 
210     /***
211      * Return attribute value with specified name as an integer.
212      *
213      * @param name the attribute name
214      * @return the attribute value
215      * @throws ConfigurationException if no attribute with
216      *         specified name or attribute can not be converted
217      *         to correct type
218      */
219     int getAttributeAsInteger( String name )
220         throws ConfigurationException;
221 
222     /***
223      * Return attribute value with specified name as an integer.
224      * If no attribute with specified name or attribute can
225      * not be converted to correct type then return
226      * default value.
227      *
228      * @param name the attribute name
229      * @param defaultValue the default value
230      * @return the attribute value
231      */
232     int getAttributeAsInteger( String name, int defaultValue );
233 
234     /***
235      * Return attribute value with specified name as a long.
236      *
237      * @param name the attribute name
238      * @return the attribute value
239      * @throws ConfigurationException if no attribute with
240      *         specified name or attribute can not be converted
241      *         to correct type
242      */
243     long getAttributeAsLong( String name )
244         throws ConfigurationException;
245 
246     /***
247      * Return attribute value with specified name as a long.
248      * If no attribute with specified name or attribute can
249      * not be converted to correct type then return
250      * default value.
251      *
252      * @param name the attribute name
253      * @param defaultValue the default value
254      * @return the attribute value
255      */
256     long getAttributeAsLong( String name, long defaultValue );
257 
258     /***
259      * Return attribute value with specified name as a boolean.
260      *
261      * @param name the attribute name
262      * @return the attribute value
263      * @throws ConfigurationException if no attribute with
264      *         specified name or attribute can not be converted
265      *         to correct type
266      */
267     boolean getAttributeAsBoolean( String name )
268         throws ConfigurationException;
269 
270     /***
271      * Return attribute value with specified name as a boolean.
272      * If no attribute with specified name or attribute can
273      * not be converted to correct type then return
274      * default value.
275      *
276      * @param name the attribute name
277      * @param defaultValue the default value
278      * @return the attribute value
279      */
280     boolean getAttributeAsBoolean( String name, boolean defaultValue );
281 
282     /***
283      * Return attribute value with specified name as afloat.
284      *
285      * @param name the attribute name
286      * @return the attribute value
287      * @throws ConfigurationException if no attribute with
288      *         specified name or attribute can not be converted
289      *         to correct type
290      */
291     float getAttributeAsFloat( String name )
292         throws ConfigurationException;
293 
294     /***
295      * Return attribute value with specified name as a float.
296      * If no attribute with specified name or attribute can
297      * not be converted to correct type then return
298      * default value.
299      *
300      * @param name the attribute name
301      * @param defaultValue the default value
302      * @return the attribute value
303      */
304     float getAttributeAsFloat( String name, float defaultValue );
305 }