001: /*
002: * Copyright (C) The DNA Group. All rights reserved.
003: *
004: * This software is published under the terms of the DNA
005: * Software License version 1.1, a copy of which has been included
006: * with this distribution in the LICENSE.txt file.
007: */
008: package org.codehaus.dna;
009:
010: /**
011: * The configuration object represents hierarchial configuration
012: * data. The data represented by this object is a simplified XML
013: * format. Configuration objects are unable to represent namespace
014: * information and elements can not have mixed content. ie
015: * Configuration elements can not have both a value and child
016: * elements.
017: *
018: * @version $Revision: 1.2 $ $Date: 2004/05/01 09:51:48 $
019: */
020: public interface Configuration {
021: /**
022: * Return the name of the configuration element.
023: *
024: * @return the name of the configuration element.
025: */
026: String getName();
027:
028: /**
029: * Return the path to the configuration element.
030: * The path should be in the xpath form but may
031: * be the empty string if unabel to determine path.
032: *
033: * @return the path to the configuration element.
034: */
035: String getPath();
036:
037: /**
038: * Return the location of configuration element.
039: * Usually of the form "uri[:line number[:column number]]"
040: * if possible. ie "file:myFile.xml:80:2". However the line
041: * number and column number may be elided if unavailable.
042: *
043: * @return the location of configuration element.
044: */
045: String getLocation();
046:
047: /**
048: * Return an array of all the child elements.
049: *
050: * @return an array of all the child elements.
051: */
052: Configuration[] getChildren();
053:
054: /**
055: * Return an array of all the child elements with specified name.
056: *
057: * @param name the name of child configuration objects
058: * @return an array of all the child elements with specified name.
059: */
060: Configuration[] getChildren(String name);
061:
062: /**
063: * Return a child Configuration element with specified name.
064: * If no such element exists an element will be autocreated.
065: *
066: * @param name the name of child configuration object
067: * @return a child Configuration element with specified name.
068: */
069: Configuration getChild(String name);
070:
071: /**
072: * Return a child Configuration element with specified name.
073: * If no such element exists and createChild is true then an
074: * element will be autocreated otherwise null will be returned.
075: *
076: * @param name the name of child configuration object
077: * @param createChild true if child should be created if it does not exist
078: * @return a child Configuration element with specified name.
079: */
080: Configuration getChild(String name, boolean createChild);
081:
082: /**
083: * Return text value of element.
084: *
085: * @return the value
086: * @throws ConfigurationException if no value in element
087: */
088: String getValue() throws ConfigurationException;
089:
090: /**
091: * Return text value of element.
092: * Use specified default if no value in element.
093: *
094: * @param defaultValue the default value
095: * @return the value
096: */
097: String getValue(String defaultValue);
098:
099: /**
100: * Return text value of element as an integer.
101: *
102: * @return the value
103: * @throws ConfigurationException if no value in element
104: * or value can not be converted to correct type
105: */
106: int getValueAsInteger() throws ConfigurationException;
107:
108: /**
109: * Return text value of element as an integer.
110: * Use specified default if no value in element or
111: * value can not be converted to correct type.
112: *
113: * @param defaultValue the default value
114: * @return the value
115: */
116: int getValueAsInteger(int defaultValue);
117:
118: /**
119: * Return text value of element as a long.
120: *
121: * @return the value
122: * @throws ConfigurationException if no value in element
123: * or value can not be converted to correct type
124: */
125: long getValueAsLong() throws ConfigurationException;
126:
127: /**
128: * Return text value of element as a long.
129: * Use specified default if no value in element or
130: * value can not be converted to correct type.
131: *
132: * @param defaultValue the default value
133: * @return the value
134: */
135: long getValueAsLong(long defaultValue);
136:
137: /**
138: * Return text value of element as a boolean.
139: *
140: * @return the value
141: * @throws ConfigurationException if no value in element
142: * or value can not be converted to correct type
143: */
144: boolean getValueAsBoolean() throws ConfigurationException;
145:
146: /**
147: * Return text value of element as a boolean.
148: * Use specified default if no value in element or
149: * value can not be converted to correct type.
150: *
151: * @param defaultValue the default value
152: * @return the value
153: */
154: boolean getValueAsBoolean(boolean defaultValue);
155:
156: /**
157: * Return text value of element as a float.
158: *
159: * @return the value
160: * @throws ConfigurationException if no value in element
161: * or value can not be converted to correct type
162: */
163: float getValueAsFloat() throws ConfigurationException;
164:
165: /**
166: * Return text value of element as a float.
167: * Use specified default if no value in element or
168: * value can not be converted to correct type.
169: *
170: * @param defaultValue the default value
171: * @return the value
172: */
173: float getValueAsFloat(float defaultValue);
174:
175: /**
176: * Return an array of all the attribute names.
177: *
178: * @return an array of all the attribute names.
179: */
180: String[] getAttributeNames();
181:
182: /**
183: * Return attribute value with specified name.
184: *
185: * @param name the attribute name
186: * @return the attribute value
187: * @throws ConfigurationException if no attribute with
188: * specified name
189: */
190: String getAttribute(String name) throws ConfigurationException;
191:
192: /**
193: * Return attribute value with specified name.
194: * If no attribute with specified name then return
195: * default value.
196: *
197: * @param name the attribute name
198: * @param defaultValue the default value
199: * @return the attribute value
200: */
201: String getAttribute(String name, String defaultValue);
202:
203: /**
204: * Return attribute value with specified name as an integer.
205: *
206: * @param name the attribute name
207: * @return the attribute value
208: * @throws ConfigurationException if no attribute with
209: * specified name or attribute can not be converted
210: * to correct type
211: */
212: int getAttributeAsInteger(String name)
213: throws ConfigurationException;
214:
215: /**
216: * Return attribute value with specified name as an integer.
217: * If no attribute with specified name or attribute can
218: * not be converted to correct type then return
219: * default value.
220: *
221: * @param name the attribute name
222: * @param defaultValue the default value
223: * @return the attribute value
224: */
225: int getAttributeAsInteger(String name, int defaultValue);
226:
227: /**
228: * Return attribute value with specified name as a long.
229: *
230: * @param name the attribute name
231: * @return the attribute value
232: * @throws ConfigurationException if no attribute with
233: * specified name or attribute can not be converted
234: * to correct type
235: */
236: long getAttributeAsLong(String name) throws ConfigurationException;
237:
238: /**
239: * Return attribute value with specified name as a long.
240: * If no attribute with specified name or attribute can
241: * not be converted to correct type then return
242: * default value.
243: *
244: * @param name the attribute name
245: * @param defaultValue the default value
246: * @return the attribute value
247: */
248: long getAttributeAsLong(String name, long defaultValue);
249:
250: /**
251: * Return attribute value with specified name as a boolean.
252: *
253: * @param name the attribute name
254: * @return the attribute value
255: * @throws ConfigurationException if no attribute with
256: * specified name or attribute can not be converted
257: * to correct type
258: */
259: boolean getAttributeAsBoolean(String name)
260: throws ConfigurationException;
261:
262: /**
263: * Return attribute value with specified name as a boolean.
264: * If no attribute with specified name or attribute can
265: * not be converted to correct type then return
266: * default value.
267: *
268: * @param name the attribute name
269: * @param defaultValue the default value
270: * @return the attribute value
271: */
272: boolean getAttributeAsBoolean(String name, boolean defaultValue);
273:
274: /**
275: * Return attribute value with specified name as afloat.
276: *
277: * @param name the attribute name
278: * @return the attribute value
279: * @throws ConfigurationException if no attribute with
280: * specified name or attribute can not be converted
281: * to correct type
282: */
283: float getAttributeAsFloat(String name)
284: throws ConfigurationException;
285:
286: /**
287: * Return attribute value with specified name as a float.
288: * If no attribute with specified name or attribute can
289: * not be converted to correct type then return
290: * default value.
291: *
292: * @param name the attribute name
293: * @param defaultValue the default value
294: * @return the attribute value
295: */
296: float getAttributeAsFloat(String name, float defaultValue);
297: }
|