1
2
3
4
5
6
7
8
9
10 package org.dom4j;
11
12 import java.io.IOException;
13 import java.io.Writer;
14 import java.util.List;
15
16 /*** <p><code>Node</code> defines the polymorphic behavior
17 * for all XML nodes in a dom4j tree.</p>
18 *
19 * <p>A node can be output as its XML format, can be detached from its position in
20 * a document and can have XPath expressions evaluated on itself.</p>
21 *
22 * <p>A node may optionally support the parent relationship and may be
23 * read only.</p>
24 *
25 * @see #supportsParent
26 * @see #isReadOnly
27 *
28 * @author <a href="mailto:jstrachan@apache.org">James Strachan</a>
29 * @version $Revision: 1.29 $
30 */
31 public interface Node extends Cloneable {
32
33
34
35 /*** Matches Element nodes */
36 public static final short ANY_NODE = 0;
37 /*** Matches Element nodes */
38 public static final short ELEMENT_NODE = 1;
39 /*** Matches elements nodes */
40 public static final short ATTRIBUTE_NODE = 2;
41 /*** Matches elements nodes */
42 public static final short TEXT_NODE = 3;
43 /*** Matches elements nodes */
44 public static final short CDATA_SECTION_NODE = 4;
45 /*** Matches elements nodes */
46 public static final short ENTITY_REFERENCE_NODE = 5;
47 /*** Matches elements nodes */
48
49 /*** Matches ProcessingInstruction */
50 public static final short PROCESSING_INSTRUCTION_NODE = 7;
51 /*** Matches Comments nodes */
52 public static final short COMMENT_NODE = 8;
53 /*** Matches Document nodes */
54 public static final short DOCUMENT_NODE = 9;
55 /*** Matches DocumentType nodes */
56 public static final short DOCUMENT_TYPE_NODE = 10;
57
58
59
60 /*** Matchs a Namespace Node - NOTE this differs from DOM */
61
62 public static final short NAMESPACE_NODE = 13;
63
64 /*** Does not match any valid node */
65 public static final short UNKNOWN_NODE = 14;
66
67 /*** The maximum number of node types for sizing purposes */
68 public static final short MAX_NODE_TYPE = 14;
69
70
71 /*** <p><code>supportsParent</code> returns true if this node supports the
72 * parent relationship.</p>
73 *
74 * <p>Some XML tree implementations are singly linked and only support
75 * downward navigation through children relationships.
76 * The default case is that both parent and children relationships are
77 * supported though for memory and performance reasons the parent
78 * relationship may not be supported.
79 * </p>
80 *
81 * @return true if this node supports the parent relationship
82 * or false it is not supported
83 */
84 public boolean supportsParent();
85
86 /*** <p><code>getParent</code> returns the parent <code>Element</code>
87 * if this node supports the parent relationship or null if it is
88 * the root element or does not support the parent relationship.</p>
89 *
90 * <p>This method is an optional feature and may not be supported
91 * for all <code>Node</code> implementations.</p>
92 *
93 * @return the parent of this node or null if it is the root of the
94 * tree or the parent relationship is not supported.
95 */
96 public Element getParent();
97
98 /*** <p><code>setParent</code> sets the parent relationship of
99 * this node if the parent relationship is supported or does nothing
100 * if the parent relationship is not supported.</p>
101 *
102 * <p>This method should only be called from inside an
103 * <code>Element</code> implementation method and is not intended for
104 * general use.</p>
105 *
106 * @param parent is the new parent of this node.
107 */
108 public void setParent(Element parent);
109
110
111 /*** <p><code>getDocument</code> returns the <code>Document</code>
112 * that this <code>Node</code> is part of if this node supports
113 * the parent relationship.</p>
114 *
115 * <p>This method is an optional feature and may not be supported
116 * for all <code>Node</code> implementations.</p>
117 *
118 * @return the document of this node or null if this feature is not
119 * supported or the node is not associated with a <code>Document</code>
120 */
121 public Document getDocument();
122
123 /*** <p><code>setDocument</code> sets the document of this node if the
124 * parent relationship is supported or does nothing if the parent
125 * relationship is not supported.</p>
126 *
127 * <p>This method should only be called from inside a
128 * <code>Document</code> implementation method and is not intended for
129 * general use.</p>
130 *
131 * @param document is the new document of this node.
132 */
133 public void setDocument(Document document);
134
135
136 /*** <p><code>isReadOnly</code> returns true if this node is read only
137 * and cannot be modified.
138 * Any attempt to modify a read-only <code>Node</code> will result in
139 * an <code>UnsupportedOperationException</code> being thrown.</p>
140 *
141 * @return true if this <code>Node</code> is read only
142 * and cannot be modified otherwise false.
143 */
144 public boolean isReadOnly();
145
146 /*** <p><code>hasContent</code> returns true if this node is a Branch
147 * (either an Element or a Document) and it contains at least one
148 * content node such as a child Element or Text node.</p>
149 *
150 * @return true if this <code>Node</code> is a Branch
151 * with a nodeCount() of one or more.
152 */
153 public boolean hasContent();
154
155
156
157 /*** <p><code>getName</code> returns the name of this node.
158 * This is the XML local name of the element, attribute, entity or
159 * processing instruction.
160 * For CDATA and Text nodes this method will return null.</p>
161 *
162 * @return the XML name of this node
163 */
164 public String getName();
165
166
167 /*** <p>Sets the text data of this node or this method will
168 * throw an <code>UnsupportedOperationException</code> if it is
169 * read-only.</p>
170 *
171 * @param name is the new name of this node
172 */
173 public void setName(String name);
174
175 /*** <p>Returns the text of this node.</p>
176 *
177 * @return the text for this node.
178 */
179 public String getText();
180
181 /*** <p>Sets the text data of this node or this method will
182 * throw an <code>UnsupportedOperationException</code> if it is
183 * read-only.</p>
184 *
185 * @param text is the new textual value of this node
186 */
187 public void setText(String text);
188
189 /*** Returns the XPath string-value of this node.
190 * The behaviour of this method is defined in the
191 * <a href="http://www.w3.org/TR/xpath">XPath specification</a>.
192 *
193 * @return the text from all the child Text and Element nodes appended
194 * together.
195 */
196 public String getStringValue();
197
198 /*** <p>Returns the XPath expression which will return a node set
199 * containing the given node such as /a/b/@c. No indexing will
200 * be used to restrict the path if multiple elements with the
201 * same name occur on the path.</p>
202 *
203 * @return the XPath expression which will return a nodeset
204 * containing at least this node.
205 */
206 public String getPath();
207
208 /*** <p>Returns the relative XPath expression which will return a node set
209 * containing the given node such as a/b/@c. No indexing will
210 * be used to restrict the path if multiple elements with the
211 * same name occur on the path.
212 *
213 * @param context is the parent context from which the relative path should
214 * start. If the context is null or the context is not an ancestor of
215 * this node then the path will be absolute and start from the document and so
216 * begin with the '/' character.
217 *
218 * @return the XPath expression relative to the given context
219 * which will return a nodeset containing at least this node.
220 */
221 public String getPath(Element context);
222
223 /*** <p>Returns the XPath expression which will return a nodeset
224 * of one node which is the current node. This method will use
225 * the XPath index operator to restrict the path if
226 * multiple elements with the same name occur on the path.</p>
227 *
228 * @return the XPath expression which will return a nodeset
229 * containing just this node.
230 */
231 public String getUniquePath();
232
233 /*** <p>Returns the relative unique XPath expression from the given context
234 * which will return a nodeset
235 * of one node which is the current node.
236 * This method will use the XPath index operator to restrict the
237 * path if multiple elements with the same name occur on the path.
238 * </p>
239 *
240 * @param context is the parent context from which the path should
241 * start. If the context is null or the context is not an ancestor of
242 * this node then the path will start from the document and so
243 * begin with the '/' character.
244 *
245 * @return the XPath expression relative to the given context
246 * which will return a nodeset containing just this node.
247 */
248 public String getUniquePath(Element context);
249
250
251 /*** <p><code>asXML</code> returns the textual XML representation of this
252 * node.</p>
253 *
254 * @return the XML representation of this node
255 */
256 public String asXML();
257
258 /*** <p><code>write</code> writes this node as the default XML
259 * notation for this node. If you wish to control the XML output
260 * (such as for pretty printing, changing the indentation policy etc.)
261 * then please use {@link org.dom4j.io.XMLWriter} or its derivations.
262 *
263 * @param writer is the <code>Writer</code> to output the XML to
264 */
265 public void write(Writer writer) throws IOException;
266
267
268 /*** Returns the code according to the type of node.
269 * This makes processing nodes polymorphically much easier as the
270 * switch statement can be used instead of multiple if (instanceof)
271 * statements.
272 *
273 * @return a W3C DOM complient code for the node type such as
274 * ELEMENT_NODE or ATTRIBUTE_NODE
275 */
276 public short getNodeType();
277
278 /*** @return the name of the type of node such as "Document", "Element", "Attribute" or "Text"
279 */
280 public String getNodeTypeName();
281
282
283 /*** <p>Removes this node from its parent if there is one.
284 * If this node is the root element of a document then it is removed
285 * from the document as well.</p>
286 *
287 * <p>This method is useful if you want to remove
288 * a node from its source document and add it to another document.
289 * For example</p>
290 *
291 * <code>
292 * Node node = ...;
293 * Element someOtherElement = ...;
294 * someOtherElement.add( node.detach() );
295 * </code>
296 *
297 * @return the node that has been removed from its parent node if
298 * any and its document if any.
299 */
300 public Node detach();
301
302
303
304 /*** <p><code>selectNodes</code> evaluates an XPath expression and returns
305 * the result as a <code>List</code> of <code>Node</code> instances or
306 * <code>String</code> instances depending on the XPath expression.</p>
307 *
308 * @param xpathExpression is the XPath expression to be evaluated
309 * @return the list of <code>Node</code> or <code>String</code> instances
310 * depending on the XPath expression
311 */
312 public List selectNodes(String xpathExpression);
313
314 /*** <p><code>selectObject</code> evaluates an XPath expression and returns
315 * the result as an {@link Object}. The object returned can
316 * either be a {@link List} of one or more {@link Node} instances
317 * or a scalar object like a {@link String} or a {@link Number}
318 * instance depending on the XPath expression.
319 *
320 * @param xpathExpression is the XPath expression to be evaluated
321 * @return the value of the XPath expression as a
322 * {@link List} of {@link Node} instances, a {@link String} or
323 * a {@link Number} instance depending on the XPath expression.
324 */
325 public Object selectObject(String xpathExpression);
326
327 /*** <p><code>selectNodes</code> evaluates an XPath expression then
328 * sorts the results using a secondary XPath expression
329 * Returns a sorted <code>List</code> of <code>Node</code> instances.</p>
330 *
331 * @param xpathExpression is the XPath expression to be evaluated
332 * @param comparisonXPathExpression is the XPath expression used
333 * to compare the results by for sorting
334 * @return the list of <code>Node</code> instances
335 * sorted by the comparisonXPathExpression
336 */
337 public List selectNodes(
338 String xpathExpression,
339 String comparisonXPathExpression
340 );
341
342 /*** <p><code>selectNodes</code> evaluates an XPath expression then
343 * sorts the results using a secondary XPath expression
344 * Returns a sorted <code>List</code> of <code>Node</code> instances.</p>
345 *
346 * @param xpathExpression is the XPath expression to be evaluated
347 * @param comparisonXPathExpression is the XPath expression used
348 * to compare the results by for sorting
349 * @param removeDuplicates if this parameter is true then duplicate
350 * values (using the comparisonXPathExpression) are removed from
351 * the result List.
352 * @return the list of <code>Node</code> instances
353 * sorted by the comparisonXPathExpression
354 */
355 public List selectNodes(
356 String xpathExpression,
357 String comparisonXPathExpression,
358 boolean removeDuplicates
359 );
360
361 /*** <p><code>selectSingleNode</code> evaluates an XPath expression
362 * and returns the result as a single <code>Node</code> instance.</p>
363 *
364 * @param xpathExpression is the XPath expression to be evaluated
365 * @return the <code>Node</code> matching the XPath expression
366 */
367 public Node selectSingleNode(String xpathExpression);
368
369 /*** <p><code>valueOf</code> evaluates an XPath expression
370 * and returns the textual representation of the results the XPath
371 * string-value of this node.
372 * The string-value for a given node type is defined in the
373 * <a href="http://www.w3.org/TR/xpath">XPath specification</a>.
374 *
375 * @param xpathExpression is the XPath expression to be evaluated
376 * @return the string-value representation of the results of the XPath
377 * expression
378 */
379 public String valueOf(String xpathExpression);
380
381 /*** <p><code>numberValueOf</code> evaluates an XPath expression
382 * and returns the numeric value of the XPath expression if the XPath
383 * expression results in a number, or null if the result is not a number.
384 *
385 * @param xpathExpression is the XPath expression to be evaluated
386 * @return the numeric result of the XPath expression or null
387 * if the result is not a number.
388 */
389 public Number numberValueOf(String xpathExpression);
390
391
392 /*** <p><code>matches</code> returns true if evaluating the given
393 * XPath expression on this node returns a non-empty node set containing this node.</p>
394 *
395 * <p>This method does not behave like the <xsl:if> element - if you want
396 * that behaviour, to evaluate if an XPath expression matches something, then
397 * you can use the following code to be equivalent...
398 * </p>
399 * <code>if ( node.selectSingleNode( "/some/path" ) != nulll )</code>
400 *
401 * @param xpathExpression is an XPath expression
402 * @return true if this node is returned by the given XPath expression
403 */
404 public boolean matches(String xpathExpression);
405
406 /*** <p><code>createXPath</code> creates an XPath object for
407 * the given xpathExpression.
408 * The XPath object allows the variable context to be specified.</p>
409 *
410 * @param xpathExpression is the XPath expression to be evaluated
411 * @return an XPath object represeting the given expression
412 * @throws InvalidXPathException if the XPath expression is invalid
413 */
414 public XPath createXPath(String xpathExpression) throws InvalidXPathException;
415
416 /*** <p><code>asXPathResult</code> returns a version of this node which is
417 * capable of being an XPath result.
418 * The result of an XPath expression should always support the parent
419 * relationship, whether the original XML tree was singly or doubly linked.
420 * If the node does not support the parent relationship then a new node
421 * will be created which is linked to its parent and returned.
422 *
423 * @return a <code>Node</code> which supports the parent relationship
424 */
425 public Node asXPathResult(Element parent);
426
427
428 /*** <p><code>accept</code> is the method used in the Visitor Pattern.</p>
429 *
430 * @param visitor is the visitor in the Visitor Pattern
431 */
432 public void accept(Visitor visitor);
433
434
435
436 /*** <p><code>clone</code> will return a deep clone or if this node is
437 * read-only then clone will return the same instance.
438 *
439 * @return a deep clone of myself or myself if I am read only.
440 */
441 public Object clone();
442 }
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490