Node


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  */
600
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags