Clover coverage report - dom4j - 1.6.1
Coverage timestamp: ma mei 16 2005 14:23:01 GMT+01:00
file stats: LOC: 885   Methods: 0
NCLOC: 75   Classes: 1
 
 Source file Conditionals Statements Methods TOTAL
Element.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.util.Iterator;
 11    import java.util.List;
 12    import java.util.Map;
 13   
 14    /**
 15    * <p>
 16    * <code>Element</code> interface defines an XML element. An element can have
 17    * declared namespaces, attributes, child nodes and textual content.
 18    * </p>
 19    *
 20    * <p>
 21    * Some of this interface is optional. Some implementations may be read-only and
 22    * not support being modified. Some implementations may not support the parent
 23    * relationship and methods such as {@link #getParent}or {@link#getDocument}.
 24    * </p>
 25    *
 26    * @author <a href="mailto:jstrachan@apache.org">James Strachan </a>
 27    * @version $Revision: 1.47 $
 28    */
 29    public interface Element extends Branch {
 30    // Name and namespace related methods
 31    // -------------------------------------------------------------------------
 32   
 33    /**
 34    * <p>
 35    * Returns the <code>QName</code> of this element which represents the
 36    * local name, the qualified name and the <code>Namespace</code>.
 37    * </p>
 38    *
 39    * @return the <code>QName</code> associated with this element
 40    */
 41    QName getQName();
 42   
 43    /**
 44    * <p>
 45    * Sets the <code>QName</code> of this element which represents the local
 46    * name, the qualified name and the <code>Namespace</code>.
 47    * </p>
 48    *
 49    * @param qname
 50    * is the <code>QName</code> to be associated with this element
 51    */
 52    void setQName(QName qname);
 53   
 54    /**
 55    * <p>
 56    * Returns the <code>Namespace</code> of this element if one exists
 57    * otherwise <code>Namespace.NO_NAMESPACE</code> is returned.
 58    * </p>
 59    *
 60    * @return the <code>Namespace</code> associated with this element
 61    */
 62    Namespace getNamespace();
 63   
 64    /**
 65    * <p>
 66    * Returns the <code>QName</code> for the given qualified name, using the
 67    * namespace URI in scope for the given prefix of the qualified name or the
 68    * default namespace if the qualified name has no prefix.
 69    * </p>
 70    *
 71    * @param qualifiedName
 72    * DOCUMENT ME!
 73    *
 74    * @return the <code>QName</code> for the given qualified name
 75    */
 76    QName getQName(String qualifiedName);
 77   
 78    /**
 79    * <p>
 80    * Returns the <code>Namespace</code> which is mapped to the given prefix
 81    * or null if it could not be found.
 82    * </p>
 83    *
 84    * @param prefix
 85    * DOCUMENT ME!
 86    *
 87    * @return the <code>Namespace</code> associated with the given prefix
 88    */
 89    Namespace getNamespaceForPrefix(String prefix);
 90   
 91    /**
 92    * <p>
 93    * Returns the <code>Namespace</code> which is mapped to the given URI or
 94    * null if it could not be found. If there is more than one
 95    * <code>Namespace</code> mapped to the URI, which of them will be
 96    * returned is undetermined.
 97    * </p>
 98    *
 99    * @param uri
 100    * DOCUMENT ME!
 101    *
 102    * @return the <code>Namespace</code> associated with the given URI
 103    */
 104    Namespace getNamespaceForURI(String uri);
 105   
 106    /**
 107    * <p>
 108    * Returns the all namespaces which are mapped to the given URI or an empty
 109    * list if no such namespaces could be found.
 110    * </p>
 111    *
 112    * @param uri
 113    * DOCUMENT ME!
 114    *
 115    * @return the namespaces associated with the given URI
 116    *
 117    * @since 1.5
 118    */
 119    List getNamespacesForURI(String uri);
 120   
 121    /**
 122    * <p>
 123    * Returns the namespace prefix of this element if one exists otherwise an
 124    * empty <code>String</code> is returned.
 125    * </p>
 126    *
 127    * @return the prefix of the <code>Namespace</code> of this element or an
 128    * empty <code>String</code>
 129    */
 130    String getNamespacePrefix();
 131   
 132    /**
 133    * <p>
 134    * Returns the URI mapped to the namespace of this element if one exists
 135    * otherwise an empty <code>String</code> is returned.
 136    * </p>
 137    *
 138    * @return the URI for the <code>Namespace</code> of this element or an
 139    * empty <code>String</code>
 140    */
 141    String getNamespaceURI();
 142   
 143    /**
 144    * <p>
 145    * Returns the fully qualified name of this element. This will be the same
 146    * as the value returned from {@link #getName}if this element has no
 147    * namespace attached to this element or an expression of the form
 148    *
 149    * <pre>
 150    * getNamespacePrefix() + &quot;:&quot; + getName()
 151    * </pre>
 152    *
 153    * will be returned.
 154    * </p>
 155    *
 156    * @return the fully qualified name of the element.
 157    */
 158    String getQualifiedName();
 159   
 160    /**
 161    * <p>
 162    * Returns any additional namespaces declarations for this element other
 163    * than namespace returned via the {@link #getNamespace()}method. If no
 164    * additional namespace declarations are present for this element then an
 165    * empty list will be returned. The list is backed by the element such that
 166    * changes to the list will be reflected in the element though the reverse
 167    * is not the case.
 168    * </p>
 169    *
 170    * @return a list of any additional namespace declarations.
 171    */
 172    List additionalNamespaces();
 173   
 174    /**
 175    * <p>
 176    * Returns all the namespaces declared by this element. If no namespaces are
 177    * declared for this element then an empty list will be returned. The list
 178    * is backed by the element such that changes to the list will be reflected
 179    * in the element though the reverse is not the case.
 180    * </p>
 181    *
 182    * @return a list of namespaces declared for this element.
 183    */
 184    List declaredNamespaces();
 185   
 186    // Builder methods
 187    // -------------------------------------------------------------------------
 188   
 189    /**
 190    * <p>
 191    * Adds the attribute value of the given local name. If an attribute already
 192    * exists for the given name it will be replaced. Attributes with null
 193    * values are silently ignored. If the value of the attribute is null then
 194    * this method call will remove any attributes with the given name.
 195    * </p>
 196    *
 197    * @param name
 198    * is the name of the attribute whose value is to be added or
 199    * updated
 200    * @param value
 201    * is the attribute's value
 202    *
 203    * @return this <code>Element</code> instance.
 204    */
 205    Element addAttribute(String name, String value);
 206   
 207    /**
 208    * <p>
 209    * Adds the attribute value of the given fully qualified name. If an
 210    * attribute already exists for the given name it will be replaced.
 211    * Attributes with null values are silently ignored. If the value of the
 212    * attribute is null then this method call will remove any attributes with
 213    * the given name.
 214    * </p>
 215    *
 216    * @param qName
 217    * is the fully qualified name of the attribute whose value is to
 218    * be added or updated
 219    * @param value
 220    * is the attribute's value
 221    *
 222    * @return this <code>Element</code> instance.
 223    */
 224    Element addAttribute(QName qName, String value);
 225   
 226    /**
 227    * Adds a new <code>Comment</code> node with the given text to this
 228    * element.
 229    *
 230    * @param comment
 231    * is the text for the <code>Comment</code> node.
 232    *
 233    * @return this <code>Element</code> instance.
 234    */
 235    Element addComment(String comment);
 236   
 237    /**
 238    * Adds a new <code>CDATA</code> node with the given text to this element.
 239    *
 240    * @param cdata
 241    * is the text for the <code>CDATA</code> node.
 242    *
 243    * @return this <code>Element</code> instance.
 244    */
 245    Element addCDATA(String cdata);
 246   
 247    /**
 248    * Adds a new <code>Entity</code> node with the given name and text to
 249    * this element and returns a reference to the new node.
 250    *
 251    * @param name
 252    * is the name for the <code>Entity</code> node.
 253    * @param text
 254    * is the text for the <code>Entity</code> node.
 255    *
 256    * @return this <code>Element</code> instance.
 257    */
 258    Element addEntity(String name, String text);
 259   
 260    /**
 261    * Adds a namespace to this element for use by its child content
 262    *
 263    * @param prefix
 264    * is the prefix to use, which should not be null or blank
 265    * @param uri
 266    * is the namespace URI
 267    *
 268    * @return this <code>Element</code> instance.
 269    */
 270    Element addNamespace(String prefix, String uri);
 271   
 272    /**
 273    * Adds a processing instruction for the given target
 274    *
 275    * @param target
 276    * is the target of the processing instruction
 277    * @param text
 278    * is the textual data (key/value pairs) of the processing
 279    * instruction
 280    *
 281    * @return this <code>Element</code> instance.
 282    */
 283    Element addProcessingInstruction(String target, String text);
 284   
 285    /**
 286    * Adds a processing instruction for the given target
 287    *
 288    * @param target
 289    * is the target of the processing instruction
 290    * @param data
 291    * is a Map of the key / value pairs of the processing
 292    * instruction
 293    *
 294    * @return this <code>Element</code> instance.
 295    */
 296    Element addProcessingInstruction(String target, Map data);
 297   
 298    /**
 299    * Adds a new <code>Text</code> node with the given text to this element.
 300    *
 301    * @param text
 302    * is the text for the <code>Text</code> node.
 303    *
 304    * @return this <code>Element</code> instance.
 305    */
 306    Element addText(String text);
 307   
 308    // Typesafe modifying methods
 309    // -------------------------------------------------------------------------
 310   
 311    /**
 312    * Adds the given <code>Attribute</code> to this element. If the given
 313    * node already has a parent defined then an
 314    * <code>IllegalAddException</code> will be thrown. Attributes with null
 315    * values are silently ignored.
 316    *
 317    * <p>
 318    * If the value of the attribute is null then this method call will remove
 319    * any attributes with the QName of this attribute.
 320    * </p>
 321    *
 322    * @param attribute
 323    * is the attribute to be added
 324    */
 325    void add(Attribute attribute);
 326   
 327    /**
 328    * Adds the given <code>CDATA</code> to this element. If the given node
 329    * already has a parent defined then an <code>IllegalAddException</code>
 330    * will be thrown.
 331    *
 332    * @param cdata
 333    * is the CDATA to be added
 334    */
 335    void add(CDATA cdata);
 336   
 337    /**
 338    * Adds the given <code>Entity</code> to this element. If the given node
 339    * already has a parent defined then an <code>IllegalAddException</code>
 340    * will be thrown.
 341    *
 342    * @param entity
 343    * is the entity to be added
 344    */
 345    void add(Entity entity);
 346   
 347    /**
 348    * Adds the given <code>Text</code> to this element. If the given node
 349    * already has a parent defined then an <code>IllegalAddException</code>
 350    * will be thrown.
 351    *
 352    * @param text
 353    * is the text to be added
 354    */
 355    void add(Text text);
 356   
 357    /**
 358    * Adds the given <code>Namespace</code> to this element. If the given
 359    * node already has a parent defined then an
 360    * <code>IllegalAddException</code> will be thrown.
 361    *
 362    * @param namespace
 363    * is the namespace to be added
 364    */
 365    void add(Namespace namespace);
 366   
 367    /**
 368    * Removes the given <code>Attribute</code> from this element.
 369    *
 370    * @param attribute
 371    * is the attribute to be removed
 372    *
 373    * @return true if the attribute was removed
 374    */
 375    boolean remove(Attribute attribute);
 376   
 377    /**
 378    * Removes the given <code>CDATA</code> if the node is an immediate child
 379    * of this element. If the given node is not an immediate child of this
 380    * element then the {@link Node#detach()}method should be used instead.
 381    *
 382    * @param cdata
 383    * is the CDATA to be removed
 384    *
 385    * @return true if the cdata was removed
 386    */
 387    boolean remove(CDATA cdata);
 388   
 389    /**
 390    * Removes the given <code>Entity</code> if the node is an immediate child
 391    * of this element. If the given node is not an immediate child of this
 392    * element then the {@link Node#detach()}method should be used instead.
 393    *
 394    * @param entity
 395    * is the entity to be removed
 396    *
 397    * @return true if the entity was removed
 398    */
 399    boolean remove(Entity entity);
 400   
 401    /**
 402    * Removes the given <code>Namespace</code> if the node is an immediate
 403    * child of this element. If the given node is not an immediate child of
 404    * this element then the {@link Node#detach()}method should be used
 405    * instead.
 406    *
 407    * @param namespace
 408    * is the namespace to be removed
 409    *
 410    * @return true if the namespace was removed
 411    */
 412    boolean remove(Namespace namespace);
 413   
 414    /**
 415    * Removes the given <code>Text</code> if the node is an immediate child
 416    * of this element. If the given node is not an immediate child of this
 417    * element then the {@link Node#detach()}method should be used instead.
 418    *
 419    * @param text
 420    * is the text to be removed
 421    *
 422    * @return true if the text was removed
 423    */
 424    boolean remove(Text text);
 425   
 426    // Text methods
 427    // -------------------------------------------------------------------------
 428   
 429    /**
 430    * Returns the text value of this element without recursing through child
 431    * elements. This method iterates through all {@link Text},{@link CDATA}
 432    * and {@link Entity}nodes that this element contains and appends the text
 433    * values together.
 434    *
 435    * @return the textual content of this Element. Child elements are not
 436    * navigated. This method does not return null;
 437    */
 438    String getText();
 439   
 440    /**
 441    * DOCUMENT ME!
 442    *
 443    * @return the trimmed text value where whitespace is trimmed and normalised
 444    * into single spaces. This method does not return null.
 445    */
 446    String getTextTrim();
 447   
 448    /**
 449    * Returns the XPath string-value of this node. The behaviour of this method
 450    * is defined in the <a href="http://www.w3.org/TR/xpath">XPath
 451    * specification </a>. This method returns the string-value of all the
 452    * contained {@link Text},{@link CDATA},{@link Entity}and {@link
 453    * Element} nodes all appended together.
 454    *
 455    * @return the text from all the child Text and Element nodes appended
 456    * together.
 457    */
 458    String getStringValue();
 459   
 460    /**
 461    * Accesses the data of this element which may implement data typing
 462    * bindings such as XML Schema or Java Bean bindings or will return the same
 463    * value as {@link #getText}
 464    *
 465    * @return DOCUMENT ME!
 466    */
 467    Object getData();
 468   
 469    /**
 470    * Sets the data value of this element if this element supports data binding
 471    * or calls {@link #setText}if it doesn't
 472    *
 473    * @param data
 474    * DOCUMENT ME!
 475    */
 476    void setData(Object data);
 477   
 478    // Attribute methods
 479    // -------------------------------------------------------------------------
 480   
 481    /**
 482    * <p>
 483    * Returns the {@link Attribute}instances this element contains as a backed
 484    * {@link List}so that the attributes may be modified directly using the
 485    * {@link List}interface. The <code>List</code> is backed by the
 486    * <code>Element</code> so that changes to the list are reflected in the
 487    * element and vice versa.
 488    * </p>
 489    *
 490    * @return the attributes that this element contains as a <code>List</code>
 491    */
 492    List attributes();
 493   
 494    /**
 495    * Sets the attributes that this element contains
 496    *
 497    * @param attributes
 498    * DOCUMENT ME!
 499    */
 500    void setAttributes(List attributes);
 501   
 502    /**
 503    * DOCUMENT ME!
 504    *
 505    * @return the number of attributes this element contains
 506    */
 507    int attributeCount();
 508   
 509    /**
 510    * DOCUMENT ME!
 511    *
 512    * @return an iterator over the attributes of this element
 513    */
 514    Iterator attributeIterator();
 515   
 516    /**
 517    * Returns the attribute at the specified indexGets the
 518    *
 519    * @param index
 520    * DOCUMENT ME!
 521    *
 522    * @return the attribute at the specified index where index &gt;= 0 and
 523    * index &lt; number of attributes or throws an
 524    * IndexOutOfBoundsException if the index is not within the
 525    * allowable range
 526    */
 527    Attribute attribute(int index);
 528   
 529    /**
 530    * Returns the attribute with the given name
 531    *
 532    * @param name
 533    * DOCUMENT ME!
 534    *
 535    * @return the attribute for the given local name in any namespace. If there
 536    * are more than one attributes with the given local name in
 537    * different namespaces then the first one is returned.
 538    */
 539    Attribute attribute(String name);
 540   
 541    /**
 542    * DOCUMENT ME!
 543    *
 544    * @param qName
 545    * is the fully qualified name
 546    *
 547    * @return the attribute for the given fully qualified name or null if it
 548    * could not be found.
 549    */
 550    Attribute attribute(QName qName);
 551   
 552    /**
 553    * <p>
 554    * This returns the attribute value for the attribute with the given name
 555    * and any namespace or null if there is no such attribute or the empty
 556    * string if the attribute value is empty.
 557    * </p>
 558    *
 559    * @param name
 560    * is the name of the attribute value to be returnd
 561    *
 562    * @return the value of the attribute, null if the attribute does not exist
 563    * or the empty string
 564    */
 565    String attributeValue(String name);
 566   
 567    /**
 568    * <p>
 569    * This returns the attribute value for the attribute with the given name
 570    * and any namespace or the default value if there is no such attribute
 571    * value.
 572    * </p>
 573    *
 574    * @param name
 575    * is the name of the attribute value to be returnd
 576    * @param defaultValue
 577    * is the default value to be returned if the attribute has no
 578    * value defined.
 579    *
 580    * @return the value of the attribute or the defaultValue if the attribute
 581    * has no value defined.
 582    */
 583    String attributeValue(String name, String defaultValue);
 584   
 585    /**
 586    * <p>
 587    * This returns the attribute value for the attribute with the given fully
 588    * qualified name or null if there is no such attribute or the empty string
 589    * if the attribute value is empty.
 590    * </p>
 591    *
 592    * @param qName
 593    * is the fully qualified name
 594    *
 595    * @return the value of the attribute, null if the attribute does not exist
 596    * or the empty string
 597    */
 598    String attributeValue(QName qName);
 599   
 600    /**
 601    * <p>
 602    * This returns the attribute value for the attribute with the given fully
 603    * qualified name or the default value if there is no such attribute value.
 604    * </p>
 605    *
 606    * @param qName
 607    * is the fully qualified name
 608    * @param defaultValue
 609    * is the default value to be returned if the attribute has no
 610    * value defined.
 611    *
 612    * @return the value of the attribute or the defaultValue if the attribute
 613    * has no value defined.
 614    */
 615    String attributeValue(QName qName, String defaultValue);
 616   
 617    /**
 618    * <p>
 619    * Sets the attribute value of the given local name.
 620    * </p>
 621    *
 622    * @param name
 623    * is the name of the attribute whose value is to be added or
 624    * updated
 625    * @param value
 626    * is the attribute's value
 627    *
 628    * @deprecated As of version 0.5. Please use {@link
 629    * #addAttribute(String,String)} instead. WILL BE REMOVED IN
 630    * dom4j-1.6 !!
 631    */
 632    void setAttributeValue(String name, String value);
 633   
 634    /**
 635    * <p>
 636    * Sets the attribute value of the given fully qualified name.
 637    * </p>
 638    *
 639    * @param qName
 640    * is the fully qualified name of the attribute whose value is to
 641    * be added or updated
 642    * @param value
 643    * is the attribute's value
 644    *
 645    * @deprecated As of version 0.5. Please use {@link
 646    * #addAttribute(QName,String)} instead. WILL BE REMOVED IN
 647    * dom4j-1.6 !!
 648    */
 649    void setAttributeValue(QName qName, String value);
 650   
 651    // Content methods
 652    // -------------------------------------------------------------------------
 653   
 654    /**
 655    * Returns the first element for the given local name and any namespace.
 656    *
 657    * @param name
 658    * DOCUMENT ME!
 659    *
 660    * @return the first element with the given local name
 661    */
 662    Element element(String name);
 663   
 664    /**
 665    * Returns the first element for the given fully qualified name.
 666    *
 667    * @param qName
 668    * is the fully qualified name to search for
 669    *
 670    * @return the first element with the given fully qualified name
 671    */
 672    Element element(QName qName);
 673   
 674    /**
 675    * <p>
 676    * Returns the elements contained in this element. If this element does not
 677    * contain any elements then this method returns an empty list. The list is
 678    * backed by the element such that changes to the list will be reflected in
 679    * the element though the reverse is not the case.
 680    * </p>
 681    *
 682    * @return a list of all the elements in this element.
 683    */
 684    List elements();
 685   
 686    /**
 687    * <p>
 688    * Returns the elements contained in this element with the given local name
 689    * and any namespace. If no elements are found then this method returns an
 690    * empty list. The list is backed by the element such that changes to the
 691    * list will be reflected in the element though the reverse is not the case.
 692    * </p>
 693    *
 694    * @param name
 695    * DOCUMENT ME!
 696    *
 697    * @return a list of all the elements in this element for the given local
 698    * name
 699    */
 700    List elements(String name);
 701   
 702    /**
 703    * <p>
 704    * Returns the elements contained in this element with the given fully
 705    * qualified name. If no elements are found then this method returns an
 706    * empty list. The list is backed by the element such that changes to the
 707    * list will be reflected in the element though the reverse is not the case.
 708    * </p>
 709    *
 710    * @param qName
 711    * is the fully qualified name to search for
 712    *
 713    * @return a list of all the elements in this element for the given fully
 714    * qualified name.
 715    */
 716    List elements(QName qName);
 717   
 718    /**
 719    * Returns an iterator over all this elements child elements.
 720    *
 721    * @return an iterator over the contained elements
 722    */
 723    Iterator elementIterator();
 724   
 725    /**
 726    * Returns an iterator over the elements contained in this element which
 727    * match the given local name and any namespace.
 728    *
 729    * @param name
 730    * DOCUMENT ME!
 731    *
 732    * @return an iterator over the contained elements matching the given local
 733    * name
 734    */
 735    Iterator elementIterator(String name);
 736   
 737    /**
 738    * Returns an iterator over the elements contained in this element which
 739    * match the given fully qualified name.
 740    *
 741    * @param qName
 742    * is the fully qualified name to search for
 743    *
 744    * @return an iterator over the contained elements matching the given fully
 745    * qualified name
 746    */
 747    Iterator elementIterator(QName qName);
 748   
 749    // Helper methods
 750    // -------------------------------------------------------------------------
 751   
 752    /**
 753    * DOCUMENT ME!
 754    *
 755    * @return true if this element is the root element of a document and this
 756    * element supports the parent relationship else false.
 757    */
 758    boolean isRootElement();
 759   
 760    /**
 761    * <p>
 762    * Returns true if this <code>Element</code> has mixed content. Mixed
 763    * content means that an element contains both textual data and child
 764    * elements.
 765    * </p>
 766    *
 767    * @return true if this element contains mixed content.
 768    */
 769    boolean hasMixedContent();
 770   
 771    /**
 772    * <p>
 773    * Returns true if this <code>Element</code> has text only content.
 774    * </p>
 775    *
 776    * @return true if this element is empty or only contains text content.
 777    */
 778    boolean isTextOnly();
 779   
 780    /**
 781    * Appends the attributes of the given element to me. This method behaves
 782    * like the {@link java.util.Collection#addAll(java.util.Collection)}
 783    * method.
 784    *
 785    * @param element
 786    * is the element whose attributes will be added to me.
 787    */
 788    void appendAttributes(Element element);
 789   
 790    /**
 791    * <p>
 792    * Creates a deep copy of this element The new element is detached from its
 793    * parent, and getParent() on the clone will return null.
 794    * </p>
 795    *
 796    * @return a new deep copy Element
 797    */
 798    Element createCopy();
 799   
 800    /**
 801    * <p>
 802    * Creates a deep copy of this element with the given local name The new
 803    * element is detached from its parent, and getParent() on the clone will
 804    * return null.
 805    * </p>
 806    *
 807    * @param name
 808    * DOCUMENT ME!
 809    *
 810    * @return a new deep copy Element
 811    */
 812    Element createCopy(String name);
 813   
 814    /**
 815    * <p>
 816    * Creates a deep copy of this element with the given fully qualified name.
 817    * The new element is detached from its parent, and getParent() on the clone
 818    * will return null.
 819    * </p>
 820    *
 821    * @param qName
 822    * DOCUMENT ME!
 823    *
 824    * @return a new deep copy Element
 825    */
 826    Element createCopy(QName qName);
 827   
 828    String elementText(String name);
 829   
 830    String elementText(QName qname);
 831   
 832    String elementTextTrim(String name);
 833   
 834    String elementTextTrim(QName qname);
 835   
 836    /**
 837    * Returns a node at the given index suitable for an XPath result set. This
 838    * means the resulting Node will either be null or it will support the
 839    * parent relationship.
 840    *
 841    * @param index
 842    * DOCUMENT ME!
 843    *
 844    * @return the Node for the given index which will support the parent
 845    * relationship or null if there is not a node at the given index.
 846    */
 847    Node getXPathResult(int index);
 848    }
 849   
 850    /*
 851    * Redistribution and use of this software and associated documentation
 852    * ("Software"), with or without modification, are permitted provided that the
 853    * following conditions are met:
 854    *
 855    * 1. Redistributions of source code must retain copyright statements and
 856    * notices. Redistributions must also contain a copy of this document.
 857    *
 858    * 2. Redistributions in binary form must reproduce the above copyright notice,
 859    * this list of conditions and the following disclaimer in the documentation
 860    * and/or other materials provided with the distribution.
 861    *
 862    * 3. The name "DOM4J" must not be used to endorse or promote products derived
 863    * from this Software without prior written permission of MetaStuff, Ltd. For
 864    * written permission, please contact dom4j-info@metastuff.com.
 865    *
 866    * 4. Products derived from this Software may not be called "DOM4J" nor may
 867    * "DOM4J" appear in their names without prior written permission of MetaStuff,
 868    * Ltd. DOM4J is a registered trademark of MetaStuff, Ltd.
 869    *
 870    * 5. Due credit should be given to the DOM4J Project - http://www.dom4j.org
 871    *
 872    * THIS SOFTWARE IS PROVIDED BY METASTUFF, LTD. AND CONTRIBUTORS ``AS IS'' AND
 873    * ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 874    * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 875    * ARE DISCLAIMED. IN NO EVENT SHALL METASTUFF, LTD. OR ITS CONTRIBUTORS BE
 876    * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
 877    * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
 878    * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
 879    * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
 880    * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
 881    * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 882    * POSSIBILITY OF SUCH DAMAGE.
 883    *
 884    * Copyright 2001-2005 (C) MetaStuff, Ltd. All Rights Reserved.
 885    */