001: /*
002: * GeoTools - OpenSource mapping toolkit
003: * http://geotools.org
004: * (C) 2002-2006, GeoTools Project Managment Committee (PMC)
005: *
006: * This library is free software; you can redistribute it and/or
007: * modify it under the terms of the GNU Lesser General Public
008: * License as published by the Free Software Foundation;
009: * version 2.1 of the License.
010: *
011: * This library is distributed in the hope that it will be useful,
012: * but WITHOUT ANY WARRANTY; without even the implied warranty of
013: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
014: * Lesser General Public License for more details.
015: */
016: package org.geotools.xml;
017:
018: import java.util.List;
019:
020: /**
021: * Represents a value in the parse tree. A node has a corresponds to a
022: * particular instance component of a document (element or attribute). Each node
023: * contains a parsed value, as well as a reference to the instance.
024: *
025: * @author Justin Deoliveira,Refractions Research Inc.,jdeolive@refractions.net
026: *
027: */
028: public interface Node {
029: /**
030: * @return The component instance.
031: */
032: InstanceComponent getComponent();
033:
034: /**
035: * @return The parsed value of the instance component.
036: */
037: Object getValue();
038:
039: /**
040: * Sets the value of the node.
041: *
042: * @param value The new parse value.
043: */
044: void setValue(Object value);
045:
046: /**
047: * Determines if the node has a child with the specified name.
048: *
049: * @param name The name of a child node.
050: *
051: * @return <code>true</code> if a child node exists with the name, otehrwise <code>false</code>.
052: */
053: boolean hasChild(String name);
054:
055: /**
056: * Determines if the node has a child whose value is of the specified class.
057: *
058: * @param clazz The class of the child node value.
059: *
060: * @return <code>true</code> if a child node exists with the class, otherwise <code>false</code>.
061: */
062: boolean hasChild(Class clazz);
063:
064: /**
065: * Returns all nodes corresponding child elements.
066: *
067: * @return A list containing objects of type Node.
068: */
069: List getChildren();
070:
071: /**
072: * Returns all nodes corresponding child elements with the specified name.
073: * This method returns an empty list if it finds no nodes corresponding to
074: * the specified name.
075: *
076: * @param name The name of a child element.
077: *
078: * @return A list containing objects of type Node.
079: */
080: List getChildren(String name);
081:
082: /**
083: * Returns all nodes corresponding to child elements with the parsed values
084: * that are instances of <code>clazz</code>
085: *
086: * @param clazz The class of parsed child values.
087: *
088: * @return A list containing objects of type Node, such that node#getValue()
089: * is an instance of <code>clazz<code>, or an empty list.
090: */
091: List getChildren(Class clazz);
092:
093: /**
094: * Returns a node corresponding to a child element. This method returns the
095: * first such node it finds and no order is guaranteed, it is provided for
096: * convenience. This method returns null if it finds no such child node
097: * matching the specified name.
098: *
099: * @param name The name of a child element.
100: *
101: * @return The first node that matches a child element with the specified
102: * name.
103: */
104: Node getChild(String name);
105:
106: /**
107: * Returns a node corresponding to a child element which has a parsed value
108: * which is an instance of <code>clazz</code>. This method returns the
109: * first such node it finds an dno order is guarenteed, it is providedd
110: * for convenience. This method returns <code>null</codee> if it finds no
111: * such child mathing the above criteria.
112: *
113: * @param clazz The class of the parsed value of a child element.
114: *
115: * @return The first node found, or null.
116: */
117: Node getChild(Class clazz);
118:
119: /**
120: * Helper method for access to child's parsed contents.
121: * <p>
122: * Should be in the range of getChildren().size()
123: * <p>
124: * Simple helper method for the contents of getChildren:
125: * <code>
126: * return ((Node)getChildren.get( index )).getValue();
127: * </code>
128: * </p>
129: * @param index
130: * @return the value of the child at the given index
131: */
132: Object getChildValue(int index);
133:
134: /**
135: * Helper method for access to child's parsed contents by element name.
136: * <p>
137: * In the event that the node has multiple children mathing <code>name</name>
138: * the first encountered is returned, there is no guarantee of order. For a
139: * list of all values matching name use {@link #getChildValues(String)}.
140: * </p>
141: *
142: * @return the value of the child with the given name, or null if the child
143: * does not exist.
144: */
145: Object getChildValue(String name);
146:
147: /**
148: * Helper method for access to child's parsed contents by class.
149: * <p>
150: * In the event that the node has multiple children which are instances of
151: * <code>clazz</code>, the first is returned, there is no guarantee of
152: * order. For a list of all values which are instances of <code>clazz</code>
153: * use {@link #getChildValues(Class)}.
154: * </p>
155: *
156: * @return the value of the child which is an instance of <code>clazz</code>,
157: * or null if no such child exists.
158: * @param clazz
159: */
160: Object getChildValue(Class clazz);
161:
162: /**
163: * Helper method for access to the set of parse child values with the
164: * specified name.
165: *
166: * @param name The name of the child element in which to retreive the
167: * parsed value.
168: *
169: * @return A list of values representing the parsed values of the children,
170: * or an empty list of no such values exist.
171: */
172: List getChildValues(String name);
173:
174: /**
175: * Helper method for access to the set of parsed child values which are
176: * instances of the specified class.
177: *
178: * @param clazz The class of the child values.
179: *
180: * @return A list of child values which are instances of <code>class<code>,
181: * or an empty list if no such values exist.
182: */
183: List getChildValues(Class clazz);
184:
185: /**
186: * Determines if the node has an attribute with the specified name.
187: *
188: * @param name The name of an attribute
189: *
190: * @return <code>true</code> if am attribute exists with the name, otehrwise <code>false</code>.
191: */
192: boolean hasAttribute(String name);
193:
194: /**
195: * Determines if the node has an attribute whose value is of the specified class.
196: *
197: * @param clazz The class of the attribute value
198: *
199: * @return <code>true</code> if an attribute exists with the class, otherwise <code>false</code>.
200: */
201: boolean hasAttribute(Class clazz);
202:
203: /**
204: * Returns all nodes corresponding to attributes.
205: *
206: * @return A list containing objects of type node.
207: */
208: List getAttributes();
209:
210: /**
211: * Returns all nodes corresponding to attributes which has a parsed values
212: * which are instances of <code>clazz</code>.
213: *
214: * @param clazz The class of parsed attribute values.
215: *
216: * @return A list of attribute nodes whose parsed values are instances of
217: * <code>clazz</code>, or an empty list.
218: */
219: List getAttributes(Class clazz);
220:
221: /**
222: * Returns the node corresonding to the attribute with the specified name.
223: * This method returns null if it finds no such attribute node matching the
224: * specified name.
225: *
226: * @param name The name of the attribute.
227: *
228: */
229: Node getAttribute(String name);
230:
231: /**
232: * Returns the node corresponding to the attribute which has a parsed value
233: * which is an instance of <code>clazz</code>. In the event that the node
234: * contains multple attributes matching the above criteria, the first
235: * encountered is returned, with no guaratnee of order. For all nodes
236: * matching this criteria use {@link #getAttributes(Class)}.
237: *
238: * @param clazz The class of parsed attribute values.
239: *
240: * @return The attribute node whose parsed value is an instance of
241: * <code>clazz</code>, or <code>null</code> if no such node exists.
242: */
243: Node getAttribute(Class clazz);
244:
245: /**
246: * Helper method for access to the parsed value of the attribute with
247: * the specified name.
248: *
249: * @param name The name of the attribute in which to retreive the parsed
250: * value from.
251: *
252: * @return the parsed value of the attribute matching the criteria, or
253: * <code>null</code> if no such attribute is found.
254: */
255: Object getAttributeValue(String name);
256:
257: /**
258: * Helper method for access to the parsed value of the attribute whose
259: * parsed value is an instance of <code>clazz</code>. In the event that the
260: * node contains multple attributes matching the above criteria, the first
261: * encountered is returned, with no guaratnee of order. For all values
262: * matching this criteria use {@link #getAttributeValues(Class)}.
263: *
264: * @param clazz The class of parsed attribute values.
265: *
266: * @return the parsed value of the attribute matching the criteria, or
267: * <code>null</code> if no such attribute is found.
268: */
269: Object getAttributeValue(Class clazz);
270:
271: /**
272: * Helper method for access ot the parsed values of attribute nodes whose
273: * parsed values are instances of <code>clazz</code>.
274: *
275: * @param clazz The class of parsed attribute values.
276: *
277: * @return The list of attribute values which are instances of
278: * <code>clazz</code>, or an empty list.
279: */
280: List getAttributeValues(Class clazz);
281: }
|