Clover coverage report - dom4j - 1.5
Coverage timestamp: vr sep 3 2004 20:47:03 GMT+01:00
file stats: LOC: 490   Methods: 0
NCLOC: 59   Classes: 1
 
 Source file Conditionals Statements Methods TOTAL
Node.java - - - -
coverage
 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    */