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 - - - -
coverage
 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    */