View Javadoc

1   /*
2    * Copyright 2001-2004 (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    * $Id: Node.java,v 1.29 2004/06/25 12:34:47 maartenc Exp $
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      // W3C DOM complient node type codes
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      //public static final short ENTITY_NODE = 6;
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      //public static final short DOCUMENT_FRAGMENT_NODE = 11;
58      //public static final short NOTATION_NODE = 12;
59      
60      /*** Matchs a Namespace Node - NOTE this differs from DOM */
61      // XXXX: ????
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 &lt;xsl:if&gt; 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  * Redistribution and use of this software and associated documentation
449  * ("Software"), with or without modification, are permitted provided
450  * that the following conditions are met:
451  *
452  * 1. Redistributions of source code must retain copyright
453  *    statements and notices.  Redistributions must also contain a
454  *    copy of this document.
455  *
456  * 2. Redistributions in binary form must reproduce the
457  *    above copyright notice, this list of conditions and the
458  *    following disclaimer in the documentation and/or other
459  *    materials provided with the distribution.
460  *
461  * 3. The name "DOM4J" must not be used to endorse or promote
462  *    products derived from this Software without prior written
463  *    permission of MetaStuff, Ltd.  For written permission,
464  *    please contact dom4j-info@metastuff.com.
465  *
466  * 4. Products derived from this Software may not be called "DOM4J"
467  *    nor may "DOM4J" appear in their names without prior written
468  *    permission of MetaStuff, Ltd. DOM4J is a registered
469  *    trademark of MetaStuff, Ltd.
470  *
471  * 5. Due credit should be given to the DOM4J Project - 
472  *    http://www.dom4j.org
473  *
474  * THIS SOFTWARE IS PROVIDED BY METASTUFF, LTD. AND CONTRIBUTORS
475  * ``AS IS'' AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT
476  * NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
477  * FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL
478  * METASTUFF, LTD. OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
479  * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
480  * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
481  * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
482  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
483  * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
484  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
485  * OF THE POSSIBILITY OF SUCH DAMAGE.
486  *
487  * Copyright 2001-2004 (C) MetaStuff, Ltd. All Rights Reserved.
488  *
489  * $Id: Node.java,v 1.29 2004/06/25 12:34:47 maartenc Exp $
490  */