Clover coverage report - dom4j - 1.6.1
Coverage timestamp: ma mei 16 2005 14:23:01 GMT+01:00

file stats: | LOC: | 599 |  | Methods: | 0
| NCLOC: | 53 |  | Classes: | 1

Source file | Conditionals | Statements | Methods | TOTAL

Node.java

-

-

-

-

1 |  | /*
2 |  | * Copyright 2001-2005 (C) MetaStuff, Ltd. All Rights Reserved.
3 |  | *
4 |  | * This software is open source.
5 |  | * See the bottom of this file for the licence.
6 |  | */
7 |  |
8 |  | package org.dom4j;
9 |  |
10 |  | import java.io.IOException;
11 |  | import java.io.Writer;
12 |  | import java.util.List;
13 |  |
14 |  | /**
15 |  | * <p>
16 |  | * <code>Node</code> defines the polymorphic behavior for all XML nodes in a
17 |  | * dom4j tree.
18 |  | * </p>
19 |  | *
20 |  | * <p>
21 |  | * A node can be output as its XML format, can be detached from its position in
22 |  | * a document and can have XPath expressions evaluated on itself.
23 |  | * </p>
24 |  | *
25 |  | * <p>
26 |  | * A node may optionally support the parent relationship and may be read only.
27 |  | * </p>
28 |  | *
29 |  | * @author <a href="mailto:jstrachan@apache.org">James Strachan </a>
30 |  | * @version $Revision: 1.31 $
31 |  | *
32 |  | * @see #supportsParent
33 |  | * @see #isReadOnly
34 |  | */
35 |  | public interface Node extends Cloneable {
36 |  | // W3C DOM complient node type codes
37 |  |
38 |  | /** Matches Element nodes */
39 |  | short ANY_NODE = 0;
40 |  |
41 |  | /** Matches Element nodes */
42 |  | short ELEMENT_NODE = 1;
43 |  |
44 |  | /** Matches elements nodes */
45 |  | short ATTRIBUTE_NODE = 2;
46 |  |
47 |  | /** Matches elements nodes */
48 |  | short TEXT_NODE = 3;
49 |  |
50 |  | /** Matches elements nodes */
51 |  | short CDATA_SECTION_NODE = 4;
52 |  |
53 |  | /** Matches elements nodes */
54 |  | short ENTITY_REFERENCE_NODE = 5;
55 |  |
56 |  | /** Matches elements nodes */
57 |  |
58 |  | // public static final short ENTITY_NODE = 6;
59 |  | /** Matches ProcessingInstruction */
60 |  | short PROCESSING_INSTRUCTION_NODE = 7;
61 |  |
62 |  | /** Matches Comments nodes */
63 |  | short COMMENT_NODE = 8;
64 |  |
65 |  | /** Matches Document nodes */
66 |  | short DOCUMENT_NODE = 9;
67 |  |
68 |  | /** Matches DocumentType nodes */
69 |  | short DOCUMENT_TYPE_NODE = 10;
70 |  |
71 |  | // public static final short DOCUMENT_FRAGMENT_NODE = 11;
72 |  | // public static final short NOTATION_NODE = 12;
73 |  |
74 |  | /** Matchs a Namespace Node - NOTE this differs from DOM */
75 |  |
76 |  | // XXXX: ????
77 |  | short NAMESPACE_NODE = 13;
78 |  |
79 |  | /** Does not match any valid node */
80 |  | short UNKNOWN_NODE = 14;
81 |  |
82 |  | /** The maximum number of node types for sizing purposes */
83 |  | short MAX_NODE_TYPE = 14;
84 |  |
85 |  | /**
86 |  | * <p>
87 |  | * <code>supportsParent</code> returns true if this node supports the
88 |  | * parent relationship.
89 |  | * </p>
90 |  | *
91 |  | * <p>
92 |  | * Some XML tree implementations are singly linked and only support downward
93 |  | * navigation through children relationships. The default case is that both
94 |  | * parent and children relationships are supported though for memory and
95 |  | * performance reasons the parent relationship may not be supported.
96 |  | * </p>
97 |  | *
98 |  | * @return true if this node supports the parent relationship or false it is
99 |  | * not supported
100 |  | */
101 |  | boolean supportsParent();
102 |  |
103 |  | /**
104 |  | * <p>
105 |  | * <code>getParent</code> returns the parent <code>Element</code> if
106 |  | * this node supports the parent relationship or null if it is the root
107 |  | * element or does not support the parent relationship.
108 |  | * </p>
109 |  | *
110 |  | * <p>
111 |  | * This method is an optional feature and may not be supported for all
112 |  | * <code>Node</code> implementations.
113 |  | * </p>
114 |  | *
115 |  | * @return the parent of this node or null if it is the root of the tree or
116 |  | * the parent relationship is not supported.
117 |  | */
118 |  | Element getParent();
119 |  |
120 |  | /**
121 |  | * <p>
122 |  | * <code>setParent</code> sets the parent relationship of this node if the
123 |  | * parent relationship is supported or does nothing if the parent
124 |  | * relationship is not supported.
125 |  | * </p>
126 |  | *
127 |  | * <p>
128 |  | * This method should only be called from inside an <code>Element</code>
129 |  | * implementation method and is not intended for general use.
130 |  | * </p>
131 |  | *
132 |  | * @param parent
133 |  | * is the new parent of this node.
134 |  | */
135 |  | void setParent(Element parent);
136 |  |
137 |  | /**
138 |  | * <p>
139 |  | * <code>getDocument</code> returns the <code>Document</code> that this
140 |  | * <code>Node</code> is part of if this node supports the parent
141 |  | * relationship.
142 |  | * </p>
143 |  | *
144 |  | * <p>
145 |  | * This method is an optional feature and may not be supported for all
146 |  | * <code>Node</code> implementations.
147 |  | * </p>
148 |  | *
149 |  | * @return the document of this node or null if this feature is not
150 |  | * supported or the node is not associated with a
151 |  | * <code>Document</code>
152 |  | */
153 |  | Document getDocument();
154 |  |
155 |  | /**
156 |  | * <p>
157 |  | * <code>setDocument</code> sets the document of this node if the parent
158 |  | * relationship is supported or does nothing if the parent relationship is
159 |  | * not supported.
160 |  | * </p>
161 |  | *
162 |  | * <p>
163 |  | * This method should only be called from inside a <code>Document</code>
164 |  | * implementation method and is not intended for general use.
165 |  | * </p>
166 |  | *
167 |  | * @param document
168 |  | * is the new document of this node.
169 |  | */
170 |  | void setDocument(Document document);
171 |  |
172 |  | /**
173 |  | * <p>
174 |  | * <code>isReadOnly</code> returns true if this node is read only and
175 |  | * cannot be modified. Any attempt to modify a read-only <code>Node</code>
176 |  | * will result in an <code>UnsupportedOperationException</code> being
177 |  | * thrown.
178 |  | * </p>
179 |  | *
180 |  | * @return true if this <code>Node</code> is read only and cannot be
181 |  | * modified otherwise false.
182 |  | */
183 |  | boolean isReadOnly();
184 |  |
185 |  | /**
186 |  | * <p>
187 |  | * <code>hasContent</code> returns true if this node is a Branch (either
188 |  | * an Element or a Document) and it contains at least one content node such
189 |  | * as a child Element or Text node.
190 |  | * </p>
191 |  | *
192 |  | * @return true if this <code>Node</code> is a Branch with a nodeCount()
193 |  | * of one or more.
194 |  | */
195 |  | boolean hasContent();
196 |  |
197 |  | /**
198 |  | * <p>
199 |  | * <code>getName</code> returns the name of this node. This is the XML
200 |  | * local name of the element, attribute, entity or processing instruction.
201 |  | * For CDATA and Text nodes this method will return null.
202 |  | * </p>
203 |  | *
204 |  | * @return the XML name of this node
205 |  | */
206 |  | String getName();
207 |  |
208 |  | /**
209 |  | * <p>
210 |  | * Sets the text data of this node or this method will throw an
211 |  | * <code>UnsupportedOperationException</code> if it is read-only.
212 |  | * </p>
213 |  | *
214 |  | * @param name
215 |  | * is the new name of this node
216 |  | */
217 |  | void setName(String name);
218 |  |
219 |  | /**
220 |  | * <p>
221 |  | * Returns the text of this node.
222 |  | * </p>
223 |  | *
224 |  | * @return the text for this node.
225 |  | */
226 |  | String getText();
227 |  |
228 |  | /**
229 |  | * <p>
230 |  | * Sets the text data of this node or this method will throw an
231 |  | * <code>UnsupportedOperationException</code> if it is read-only.
232 |  | * </p>
233 |  | *
234 |  | * @param text
235 |  | * is the new textual value of this node
236 |  | */
237 |  | void setText(String text);
238 |  |
239 |  | /**
240 |  | * Returns the XPath string-value of this node. The behaviour of this method
241 |  | * is defined in the <a href="http://www.w3.org/TR/xpath">XPath
242 |  | * specification </a>.
243 |  | *
244 |  | * @return the text from all the child Text and Element nodes appended
245 |  | * together.
246 |  | */
247 |  | String getStringValue();
248 |  |
249 |  | /**
250 |  | * <p>
251 |  | * Returns the XPath expression which will return a node set containing the
252 |  | * given node such as /a/b/&#64;c. No indexing will be used to restrict the
253 |  | * path if multiple elements with the same name occur on the path.
254 |  | * </p>
255 |  | *
256 |  | * @return the XPath expression which will return a nodeset containing at
257 |  | * least this node.
258 |  | */
259 |  | String getPath();
260 |  |
261 |  | /**
262 |  | * Returns the relative XPath expression which will return a node set
263 |  | * containing the given node such as a/b/&#64;c. No indexing will be used to
264 |  | * restrict the path if multiple elements with the same name occur on the
265 |  | * path.
266 |  | *
267 |  | * @param context
268 |  | * is the parent context from which the relative path should
269 |  | * start. If the context is null or the context is not an
270 |  | * ancestor of this node then the path will be absolute and start
271 |  | * from the document and so begin with the '/' character.
272 |  | *
273 |  | * @return the XPath expression relative to the given context which will
274 |  | * return a nodeset containing at least this node.
275 |  | */
276 |  | String getPath(Element context);
277 |  |
278 |  | /**
279 |  | * <p>
280 |  | * Returns the XPath expression which will return a nodeset of one node
281 |  | * which is the current node. This method will use the XPath index operator
282 |  | * to restrict the path if multiple elements with the same name occur on the
283 |  | * path.
284 |  | * </p>
285 |  | *
286 |  | * @return the XPath expression which will return a nodeset containing just
287 |  | * this node.
288 |  | */
289 |  | String getUniquePath();
290 |  |
291 |  | /**
292 |  | * <p>
293 |  | * Returns the relative unique XPath expression from the given context which
294 |  | * will return a nodeset of one node which is the current node. This method
295 |  | * will use the XPath index operator to restrict the path if multiple
296 |  | * elements with the same name occur on the path.
297 |  | * </p>
298 |  | *
299 |  | * @param context
300 |  | * is the parent context from which the path should start. If the
301 |  | * context is null or the context is not an ancestor of this node
302 |  | * then the path will start from the document and so begin with
303 |  | * the '/' character.
304 |  | *
305 |  | * @return the XPath expression relative to the given context which will
306 |  | * return a nodeset containing just this node.
307 |  | */
308 |  | String getUniquePath(Element context);
309 |  |
310 |  | /**
311 |  | * <p>
312 |  | * <code>asXML</code> returns the textual XML representation of this node.
313 |  | * </p>
314 |  | *
315 |  | * @return the XML representation of this node
316 |  | */
317 |  | String asXML();
318 |  |
319 |  | /**
320 |  | * <p>
321 |  | * <code>write</code> writes this node as the default XML notation for
322 |  | * this node. If you wish to control the XML output (such as for pretty
323 |  | * printing, changing the indentation policy etc.) then please use {@link
324 |  | * org.dom4j.io.XMLWriter} or its derivations.
325 |  | * </p>
326 |  | *
327 |  | * @param writer
328 |  | * is the <code>Writer</code> to output the XML to
329 |  | *
330 |  | * @throws IOException
331 |  | * DOCUMENT ME!
332 |  | */
333 |  | void write(Writer writer) throws IOException;
334 |  |
335 |  | /**
336 |  | * Returns the code according to the type of node. This makes processing
337 |  | * nodes polymorphically much easier as the switch statement can be used
338 |  | * instead of multiple if (instanceof) statements.
339 |  | *
340 |  | * @return a W3C DOM complient code for the node type such as ELEMENT_NODE
341 |  | * or ATTRIBUTE_NODE
342 |  | */
343 |  | short getNodeType();
344 |  |
345 |  | /**
346 |  | * DOCUMENT ME!
347 |  | *
348 |  | * @return the name of the type of node such as "Document", "Element",
349 |  | * "Attribute" or "Text"
350 |  | */
351 |  | String getNodeTypeName();
352 |  |
353 |  | /**
354 |  | * <p>
355 |  | * Removes this node from its parent if there is one. If this node is the
356 |  | * root element of a document then it is removed from the document as well.
357 |  | * </p>
358 |  | *
359 |  | * <p>
360 |  | * This method is useful if you want to remove a node from its source
361 |  | * document and add it to another document. For example
362 |  | * </p>
363 |  | * <code> Node node = ...; Element someOtherElement = ...;
364 |  | * someOtherElement.add( node.detach() ); </code>
365 |  | *
366 |  | * @return the node that has been removed from its parent node if any and
367 |  | * its document if any.
368 |  | */
369 |  | Node detach();
370 |  |
371 |  | /**
372 |  | * <p>
373 |  | * <code>selectNodes</code> evaluates an XPath expression and returns the
374 |  | * result as a <code>List</code> of <code>Node</code> instances or
375 |  | * <code>String</code> instances depending on the XPath expression.
376 |  | * </p>
377 |  | *
378 |  | * @param xpathExpression
379 |  | * is the XPath expression to be evaluated
380 |  | *
381 |  | * @return the list of <code>Node</code> or <code>String</code>
382 |  | * instances depending on the XPath expression
383 |  | */
384 |  | List selectNodes(String xpathExpression);
385 |  |
386 |  | /**
387 |  | * <p>
388 |  | * <code>selectObject</code> evaluates an XPath expression and returns the
389 |  | * result as an {@link Object}. The object returned can either be a {@link
390 |  | * List} of one or more {@link Node}instances or a scalar object like a
391 |  | * {@link String}or a {@link Number}instance depending on the XPath
392 |  | * expression.
393 |  | * </p>
394 |  | *
395 |  | * @param xpathExpression
396 |  | * is the XPath expression to be evaluated
397 |  | *
398 |  | * @return the value of the XPath expression as a {@link List}of {@link
399 |  | * Node} instances, a {@link String}or a {@link Number}instance
400 |  | * depending on the XPath expression.
401 |  | */
402 |  | Object selectObject(String xpathExpression);
403 |  |
404 |  | /**
405 |  | * <p>
406 |  | * <code>selectNodes</code> evaluates an XPath expression then sorts the
407 |  | * results using a secondary XPath expression Returns a sorted
408 |  | * <code>List</code> of <code>Node</code> instances.
409 |  | * </p>
410 |  | *
411 |  | * @param xpathExpression
412 |  | * is the XPath expression to be evaluated
413 |  | * @param comparisonXPathExpression
414 |  | * is the XPath expression used to compare the results by for
415 |  | * sorting
416 |  | *
417 |  | * @return the list of <code>Node</code> instances sorted by the
418 |  | * comparisonXPathExpression
419 |  | */
420 |  | List selectNodes(String xpathExpression, String comparisonXPathExpression);
421 |  |
422 |  | /**
423 |  | * <p>
424 |  | * <code>selectNodes</code> evaluates an XPath expression then sorts the
425 |  | * results using a secondary XPath expression Returns a sorted
426 |  | * <code>List</code> of <code>Node</code> instances.
427 |  | * </p>
428 |  | *
429 |  | * @param xpathExpression
430 |  | * is the XPath expression to be evaluated
431 |  | * @param comparisonXPathExpression
432 |  | * is the XPath expression used to compare the results by for
433 |  | * sorting
434 |  | * @param removeDuplicates
435 |  | * if this parameter is true then duplicate values (using the
436 |  | * comparisonXPathExpression) are removed from the result List.
437 |  | *
438 |  | * @return the list of <code>Node</code> instances sorted by the
439 |  | * comparisonXPathExpression
440 |  | */
441 |  | List selectNodes(String xpathExpression, String comparisonXPathExpression,
442 |  | boolean removeDuplicates);
443 |  |
444 |  | /**
445 |  | * <p>
446 |  | * <code>selectSingleNode</code> evaluates an XPath expression and returns
447 |  | * the result as a single <code>Node</code> instance.
448 |  | * </p>
449 |  | *
450 |  | * @param xpathExpression
451 |  | * is the XPath expression to be evaluated
452 |  | *
453 |  | * @return the <code>Node</code> matching the XPath expression
454 |  | */
455 |  | Node selectSingleNode(String xpathExpression);
456 |  |
457 |  | /**
458 |  | * <p>
459 |  | * <code>valueOf</code> evaluates an XPath expression and returns the
460 |  | * textual representation of the results the XPath string-value of this
461 |  | * node. The string-value for a given node type is defined in the <a
462 |  | * href="http://www.w3.org/TR/xpath">XPath specification </a>.
463 |  | * </p>
464 |  | *
465 |  | * @param xpathExpression
466 |  | * is the XPath expression to be evaluated
467 |  | *
468 |  | * @return the string-value representation of the results of the XPath
469 |  | * expression
470 |  | */
471 |  | String valueOf(String xpathExpression);
472 |  |
473 |  | /**
474 |  | * <p>
475 |  | * <code>numberValueOf</code> evaluates an XPath expression and returns
476 |  | * the numeric value of the XPath expression if the XPath expression results
477 |  | * in a number, or null if the result is not a number.
478 |  | * </p>
479 |  | *
480 |  | * @param xpathExpression
481 |  | * is the XPath expression to be evaluated
482 |  | *
483 |  | * @return the numeric result of the XPath expression or null if the result
484 |  | * is not a number.
485 |  | */
486 |  | Number numberValueOf(String xpathExpression);
487 |  |
488 |  | /**
489 |  | * <p>
490 |  | * <code>matches</code> returns true if evaluating the given XPath
491 |  | * expression on this node returns a non-empty node set containing this
492 |  | * node.
493 |  | * </p>
494 |  | *
495 |  | * <p>
496 |  | * This method does not behave like the &lt;xsl:if&gt; element - if you want
497 |  | * that behaviour, to evaluate if an XPath expression matches something,
498 |  | * then you can use the following code to be equivalent...
499 |  | * </p>
500 |  | * <code>if ( node.selectSingleNode( "/some/path" ) != nulll )</code>
501 |  | *
502 |  | * @param xpathExpression
503 |  | * is an XPath expression
504 |  | *
505 |  | * @return true if this node is returned by the given XPath expression
506 |  | */
507 |  | boolean matches(String xpathExpression);
508 |  |
509 |  | /**
510 |  | * <p>
511 |  | * <code>createXPath</code> creates an XPath object for the given
512 |  | * xpathExpression. The XPath object allows the variable context to be
513 |  | * specified.
514 |  | * </p>
515 |  | *
516 |  | * @param xpathExpression
517 |  | * is the XPath expression to be evaluated
518 |  | *
519 |  | * @return an XPath object represeting the given expression
520 |  | *
521 |  | * @throws InvalidXPathException
522 |  | * if the XPath expression is invalid
523 |  | */
524 |  | XPath createXPath(String xpathExpression) throws InvalidXPathException;
525 |  |
526 |  | /**
527 |  | * <p>
528 |  | * <code>asXPathResult</code> returns a version of this node which is
529 |  | * capable of being an XPath result. The result of an XPath expression
530 |  | * should always support the parent relationship, whether the original XML
531 |  | * tree was singly or doubly linked. If the node does not support the parent
532 |  | * relationship then a new node will be created which is linked to its
533 |  | * parent and returned.
534 |  | * </p>
535 |  | *
536 |  | * @param parent
537 |  | * DOCUMENT ME!
538 |  | *
539 |  | * @return a <code>Node</code> which supports the parent relationship
540 |  | */
541 |  | Node asXPathResult(Element parent);
542 |  |
543 |  | /**
544 |  | * <p>
545 |  | * <code>accept</code> is the method used in the Visitor Pattern.
546 |  | * </p>
547 |  | *
548 |  | * @param visitor
549 |  | * is the visitor in the Visitor Pattern
550 |  | */
551 |  | void accept(Visitor visitor);
552 |  |
553 |  | /**
554 |  | * <p>
555 |  | * <code>clone</code> will return a deep clone or if this node is
556 |  | * read-only then clone will return the same instance.
557 |  | * </p>
558 |  | *
559 |  | * @return a deep clone of myself or myself if I am read only.
560 |  | */
561 |  | Object clone();
562 |  | }
563 |  |
564 |  | /*
565 |  | * Redistribution and use of this software and associated documentation
566 |  | * ("Software"), with or without modification, are permitted provided that the
567 |  | * following conditions are met:
568 |  | *
569 |  | * 1. Redistributions of source code must retain copyright statements and
570 |  | * notices. Redistributions must also contain a copy of this document.
571 |  | *
572 |  | * 2. Redistributions in binary form must reproduce the above copyright notice,
573 |  | * this list of conditions and the following disclaimer in the documentation
574 |  | * and/or other materials provided with the distribution.
575 |  | *
576 |  | * 3. The name "DOM4J" must not be used to endorse or promote products derived
577 |  | * from this Software without prior written permission of MetaStuff, Ltd. For
578 |  | * written permission, please contact dom4j-info@metastuff.com.
579 |  | *
580 |  | * 4. Products derived from this Software may not be called "DOM4J" nor may
581 |  | * "DOM4J" appear in their names without prior written permission of MetaStuff,
582 |  | * Ltd. DOM4J is a registered trademark of MetaStuff, Ltd.
583 |  | *
584 |  | * 5. Due credit should be given to the DOM4J Project - http://www.dom4j.org
585 |  | *
586 |  | * THIS SOFTWARE IS PROVIDED BY METASTUFF, LTD. AND CONTRIBUTORS ``AS IS'' AND
587 |  | * ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
588 |  | * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
589 |  | * ARE DISCLAIMED. IN NO EVENT SHALL METASTUFF, LTD. OR ITS CONTRIBUTORS BE
590 |  | * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
591 |  | * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
592 |  | * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
593 |  | * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
594 |  | * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
595 |  | * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
596 |  | * POSSIBILITY OF SUCH DAMAGE.
597 |  | *
598 |  | * Copyright 2001-2005 (C) MetaStuff, Ltd. All Rights Reserved.
599 |  | */