1
2
3
4
5
6
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 }