lib/classpath/external/w3c_dom/org/w3c/dom/Node.java

   1 /*
   2  * Copyright (c) 2004 World Wide Web Consortium,
   3  *
   4  * (Massachusetts Institute of Technology, European Research Consortium for
   5  * Informatics and Mathematics, Keio University). All Rights Reserved. This
   6  * work is distributed under the W3C(r) Software License [1] in the hope that
   7  * it will be useful, but WITHOUT ANY WARRANTY; without even the implied
   8  * warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
   9  *
  10  * [1] http://www.w3.org/Consortium/Legal/2002/copyright-software-20021231
  11  */
  12
  13 package org.w3c.dom;
  14
  15 /**
  16  * The <code>Node</code> interface is the primary datatype for the entire
  17  * Document Object Model. It represents a single node in the document tree.
  18  * While all objects implementing the <code>Node</code> interface expose
  19  * methods for dealing with children, not all objects implementing the
  20  * <code>Node</code> interface may have children. For example,
  21  * <code>Text</code> nodes may not have children, and adding children to
  22  * such nodes results in a <code>DOMException</code> being raised.
  23  * <p>The attributes <code>nodeName</code>, <code>nodeValue</code> and
  24  * <code>attributes</code> are included as a mechanism to get at node
  25  * information without casting down to the specific derived interface. In
  26  * cases where there is no obvious mapping of these attributes for a
  27  * specific <code>nodeType</code> (e.g., <code>nodeValue</code> for an
  28  * <code>Element</code> or <code>attributes</code> for a <code>Comment</code>
  29  * ), this returns <code>null</code>. Note that the specialized interfaces
  30  * may contain additional and more convenient mechanisms to get and set the
  31  * relevant information.
  32  * <p>The values of <code>nodeName</code>,
  33  * <code>nodeValue</code>, and <code>attributes</code> vary according to the
  34  * node type as follows:
  35  * <table border='1' cellpadding='3'>
  36  * <tr>
  37  * <th>Interface</th>
  38  * <th>nodeName</th>
  39  * <th>nodeValue</th>
  40  * <th>attributes</th>
  41  * </tr>
  42  * <tr>
  43  * <td valign='top' rowspan='1' colspan='1'>
  44  * <code>Attr</code></td>
  45  * <td valign='top' rowspan='1' colspan='1'>same as <code>Attr.name</code></td>
  46  * <td valign='top' rowspan='1' colspan='1'>same as
  47  * <code>Attr.value</code></td>
  48  * <td valign='top' rowspan='1' colspan='1'><code>null</code></td>
  49  * </tr>
  50  * <tr>
  51  * <td valign='top' rowspan='1' colspan='1'><code>CDATASection</code></td>
  52  * <td valign='top' rowspan='1' colspan='1'>
  53  * <code>"#cdata-section"</code></td>
  54  * <td valign='top' rowspan='1' colspan='1'>same as <code>CharacterData.data</code>, the
  55  * content of the CDATA Section</td>
  56  * <td valign='top' rowspan='1' colspan='1'><code>null</code></td>
  57  * </tr>
  58  * <tr>
  59  * <td valign='top' rowspan='1' colspan='1'><code>Comment</code></td>
  60  * <td valign='top' rowspan='1' colspan='1'>
  61  * <code>"#comment"</code></td>
  62  * <td valign='top' rowspan='1' colspan='1'>same as <code>CharacterData.data</code>, the
  63  * content of the comment</td>
  64  * <td valign='top' rowspan='1' colspan='1'><code>null</code></td>
  65  * </tr>
  66  * <tr>
  67  * <td valign='top' rowspan='1' colspan='1'><code>Document</code></td>
  68  * <td valign='top' rowspan='1' colspan='1'>
  69  * <code>"#document"</code></td>
  70  * <td valign='top' rowspan='1' colspan='1'><code>null</code></td>
  71  * <td valign='top' rowspan='1' colspan='1'><code>null</code></td>
  72  * </tr>
  73  * <tr>
  74  * <td valign='top' rowspan='1' colspan='1'>
  75  * <code>DocumentFragment</code></td>
  76  * <td valign='top' rowspan='1' colspan='1'><code>"#document-fragment"</code></td>
  77  * <td valign='top' rowspan='1' colspan='1'>
  78  * <code>null</code></td>
  79  * <td valign='top' rowspan='1' colspan='1'><code>null</code></td>
  80  * </tr>
  81  * <tr>
  82  * <td valign='top' rowspan='1' colspan='1'><code>DocumentType</code></td>
  83  * <td valign='top' rowspan='1' colspan='1'>same as
  84  * <code>DocumentType.name</code></td>
  85  * <td valign='top' rowspan='1' colspan='1'><code>null</code></td>
  86  * <td valign='top' rowspan='1' colspan='1'><code>null</code></td>
  87  * </tr>
  88  * <tr>
  89  * <td valign='top' rowspan='1' colspan='1'>
  90  * <code>Element</code></td>
  91  * <td valign='top' rowspan='1' colspan='1'>same as <code>Element.tagName</code></td>
  92  * <td valign='top' rowspan='1' colspan='1'><code>null</code></td>
  93  * <td valign='top' rowspan='1' colspan='1'>
  94  * <code>NamedNodeMap</code></td>
  95  * </tr>
  96  * <tr>
  97  * <td valign='top' rowspan='1' colspan='1'><code>Entity</code></td>
  98  * <td valign='top' rowspan='1' colspan='1'>entity name</td>
  99  * <td valign='top' rowspan='1' colspan='1'><code>null</code></td>
 100  * <td valign='top' rowspan='1' colspan='1'>
 101  * <code>null</code></td>
 102  * </tr>
 103  * <tr>
 104  * <td valign='top' rowspan='1' colspan='1'><code>EntityReference</code></td>
 105  * <td valign='top' rowspan='1' colspan='1'>name of entity referenced</td>
 106  * <td valign='top' rowspan='1' colspan='1'>
 107  * <code>null</code></td>
 108  * <td valign='top' rowspan='1' colspan='1'><code>null</code></td>
 109  * </tr>
 110  * <tr>
 111  * <td valign='top' rowspan='1' colspan='1'><code>Notation</code></td>
 112  * <td valign='top' rowspan='1' colspan='1'>notation name</td>
 113  * <td valign='top' rowspan='1' colspan='1'>
 114  * <code>null</code></td>
 115  * <td valign='top' rowspan='1' colspan='1'><code>null</code></td>
 116  * </tr>
 117  * <tr>
 118  * <td valign='top' rowspan='1' colspan='1'><code>ProcessingInstruction</code></td>
 119  * <td valign='top' rowspan='1' colspan='1'>same
 120  * as <code>ProcessingInstruction.target</code></td>
 121  * <td valign='top' rowspan='1' colspan='1'>same as
 122  * <code>ProcessingInstruction.data</code></td>
 123  * <td valign='top' rowspan='1' colspan='1'><code>null</code></td>
 124  * </tr>
 125  * <tr>
 126  * <td valign='top' rowspan='1' colspan='1'><code>Text</code></td>
 127  * <td valign='top' rowspan='1' colspan='1'>
 128  * <code>"#text"</code></td>
 129  * <td valign='top' rowspan='1' colspan='1'>same as <code>CharacterData.data</code>, the content
 130  * of the text node</td>
 131  * <td valign='top' rowspan='1' colspan='1'><code>null</code></td>
 132  * </tr>
 133  * </table>
 134  * <p>See also the <a href='http://www.w3.org/TR/2004/REC-DOM-Level-3-Core-20040407'>Document Object Model (DOM) Level 3 Core Specification</a>.
 135  */
 136 public interface Node {
 137     // NodeType
 138     /**
 139      * The node is an <code>Element</code>.
 140      */
 141     public static final short ELEMENT_NODE              = 1;
 142     /**
 143      * The node is an <code>Attr</code>.
 144      */
 145     public static final short ATTRIBUTE_NODE            = 2;
 146     /**
 147      * The node is a <code>Text</code> node.
 148      */
 149     public static final short TEXT_NODE                 = 3;
 150     /**
 151      * The node is a <code>CDATASection</code>.
 152      */
 153     public static final short CDATA_SECTION_NODE        = 4;
 154     /**
 155      * The node is an <code>EntityReference</code>.
 156      */
 157     public static final short ENTITY_REFERENCE_NODE     = 5;
 158     /**
 159      * The node is an <code>Entity</code>.
 160      */
 161     public static final short ENTITY_NODE               = 6;
 162     /**
 163      * The node is a <code>ProcessingInstruction</code>.
 164      */
 165     public static final short PROCESSING_INSTRUCTION_NODE = 7;
 166     /**
 167      * The node is a <code>Comment</code>.
 168      */
 169     public static final short COMMENT_NODE              = 8;
 170     /**
 171      * The node is a <code>Document</code>.
 172      */
 173     public static final short DOCUMENT_NODE             = 9;
 174     /**
 175      * The node is a <code>DocumentType</code>.
 176      */
 177     public static final short DOCUMENT_TYPE_NODE        = 10;
 178     /**
 179      * The node is a <code>DocumentFragment</code>.
 180      */
 181     public static final short DOCUMENT_FRAGMENT_NODE    = 11;
 182     /**
 183      * The node is a <code>Notation</code>.
 184      */
 185     public static final short NOTATION_NODE             = 12;
 186
 187     /**
 188      * The name of this node, depending on its type; see the table above.
 189      */
 190     public String getNodeName();
 191
 192     /**
 193      * The value of this node, depending on its type; see the table above.
 194      * When it is defined to be <code>null</code>, setting it has no effect,
 195      * including if the node is read-only.
 196      * @exception DOMException
 197      *   DOMSTRING_SIZE_ERR: Raised when it would return more characters than
 198      *   fit in a <code>DOMString</code> variable on the implementation
 199      *   platform.
 200      */
 201     public String getNodeValue()
 202                               throws DOMException;
 203     /**
 204      * The value of this node, depending on its type; see the table above.
 205      * When it is defined to be <code>null</code>, setting it has no effect,
 206      * including if the node is read-only.
 207      * @exception DOMException
 208      *   NO_MODIFICATION_ALLOWED_ERR: Raised when the node is readonly and if
 209      *   it is not defined to be <code>null</code>.
 210      */
 211     public void setNodeValue(String nodeValue)
 212                               throws DOMException;
 213
 214     /**
 215      * A code representing the type of the underlying object, as defined above.
 216      */
 217     public short getNodeType();
 218
 219     /**
 220      * The parent of this node. All nodes, except <code>Attr</code>,
 221      * <code>Document</code>, <code>DocumentFragment</code>,
 222      * <code>Entity</code>, and <code>Notation</code> may have a parent.
 223      * However, if a node has just been created and not yet added to the
 224      * tree, or if it has been removed from the tree, this is
 225      * <code>null</code>.
 226      */
 227     public Node getParentNode();
 228
 229     /**
 230      * A <code>NodeList</code> that contains all children of this node. If
 231      * there are no children, this is a <code>NodeList</code> containing no
 232      * nodes.
 233      */
 234     public NodeList getChildNodes();
 235
 236     /**
 237      * The first child of this node. If there is no such node, this returns
 238      * <code>null</code>.
 239      */
 240     public Node getFirstChild();
 241
 242     /**
 243      * The last child of this node. If there is no such node, this returns
 244      * <code>null</code>.
 245      */
 246     public Node getLastChild();
 247
 248     /**
 249      * The node immediately preceding this node. If there is no such node,
 250      * this returns <code>null</code>.
 251      */
 252     public Node getPreviousSibling();
 253
 254     /**
 255      * The node immediately following this node. If there is no such node,
 256      * this returns <code>null</code>.
 257      */
 258     public Node getNextSibling();
 259
 260     /**
 261      * A <code>NamedNodeMap</code> containing the attributes of this node (if
 262      * it is an <code>Element</code>) or <code>null</code> otherwise.
 263      */
 264     public NamedNodeMap getAttributes();
 265
 266     /**
 267      * The <code>Document</code> object associated with this node. This is
 268      * also the <code>Document</code> object used to create new nodes. When
 269      * this node is a <code>Document</code> or a <code>DocumentType</code>
 270      * which is not used with any <code>Document</code> yet, this is
 271      * <code>null</code>.
 272      * @version DOM Level 2
 273      */
 274     public Document getOwnerDocument();
 275
 276     /**
 277      * Inserts the node <code>newChild</code> before the existing child node
 278      * <code>refChild</code>. If <code>refChild</code> is <code>null</code>,
 279      * insert <code>newChild</code> at the end of the list of children.
 280      * <br>If <code>newChild</code> is a <code>DocumentFragment</code> object,
 281      * all of its children are inserted, in the same order, before
 282      * <code>refChild</code>. If the <code>newChild</code> is already in the
 283      * tree, it is first removed.
 284      * <p ><b>Note:</b>  Inserting a node before itself is implementation
 285      * dependent.
 286      * @param newChild The node to insert.
 287      * @param refChild The reference node, i.e., the node before which the
 288      *   new node must be inserted.
 289      * @return The node being inserted.
 290      * @exception DOMException
 291      *   HIERARCHY_REQUEST_ERR: Raised if this node is of a type that does not
 292      *   allow children of the type of the <code>newChild</code> node, or if
 293      *   the node to insert is one of this node's ancestors or this node
 294      *   itself, or if this node is of type <code>Document</code> and the
 295      *   DOM application attempts to insert a second
 296      *   <code>DocumentType</code> or <code>Element</code> node.
 297      *   <br>WRONG_DOCUMENT_ERR: Raised if <code>newChild</code> was created
 298      *   from a different document than the one that created this node.
 299      *   <br>NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly or
 300      *   if the parent of the node being inserted is readonly.
 301      *   <br>NOT_FOUND_ERR: Raised if <code>refChild</code> is not a child of
 302      *   this node.
 303      *   <br>NOT_SUPPORTED_ERR: if this node is of type <code>Document</code>,
 304      *   this exception might be raised if the DOM implementation doesn't
 305      *   support the insertion of a <code>DocumentType</code> or
 306      *   <code>Element</code> node.
 307      * @version DOM Level 3
 308      */
 309     public Node insertBefore(Node newChild,
 310                              Node refChild)
 311                              throws DOMException;
 312
 313     /**
 314      * Replaces the child node <code>oldChild</code> with <code>newChild</code>
 315      *  in the list of children, and returns the <code>oldChild</code> node.
 316      * <br>If <code>newChild</code> is a <code>DocumentFragment</code> object,
 317      * <code>oldChild</code> is replaced by all of the
 318      * <code>DocumentFragment</code> children, which are inserted in the
 319      * same order. If the <code>newChild</code> is already in the tree, it
 320      * is first removed.
 321      * <p ><b>Note:</b>  Replacing a node with itself is implementation
 322      * dependent.
 323      * @param newChild The new node to put in the child list.
 324      * @param oldChild The node being replaced in the list.
 325      * @return The node replaced.
 326      * @exception DOMException
 327      *   HIERARCHY_REQUEST_ERR: Raised if this node is of a type that does not
 328      *   allow children of the type of the <code>newChild</code> node, or if
 329      *   the node to put in is one of this node's ancestors or this node
 330      *   itself, or if this node is of type <code>Document</code> and the
 331      *   result of the replacement operation would add a second
 332      *   <code>DocumentType</code> or <code>Element</code> on the
 333      *   <code>Document</code> node.
 334      *   <br>WRONG_DOCUMENT_ERR: Raised if <code>newChild</code> was created
 335      *   from a different document than the one that created this node.
 336      *   <br>NO_MODIFICATION_ALLOWED_ERR: Raised if this node or the parent of
 337      *   the new node is readonly.
 338      *   <br>NOT_FOUND_ERR: Raised if <code>oldChild</code> is not a child of
 339      *   this node.
 340      *   <br>NOT_SUPPORTED_ERR: if this node is of type <code>Document</code>,
 341      *   this exception might be raised if the DOM implementation doesn't
 342      *   support the replacement of the <code>DocumentType</code> child or
 343      *   <code>Element</code> child.
 344      * @version DOM Level 3
 345      */
 346     public Node replaceChild(Node newChild,
 347                              Node oldChild)
 348                              throws DOMException;
 349
 350     /**
 351      * Removes the child node indicated by <code>oldChild</code> from the list
 352      * of children, and returns it.
 353      * @param oldChild The node being removed.
 354      * @return The node removed.
 355      * @exception DOMException
 356      *   NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
 357      *   <br>NOT_FOUND_ERR: Raised if <code>oldChild</code> is not a child of
 358      *   this node.
 359      *   <br>NOT_SUPPORTED_ERR: if this node is of type <code>Document</code>,
 360      *   this exception might be raised if the DOM implementation doesn't
 361      *   support the removal of the <code>DocumentType</code> child or the
 362      *   <code>Element</code> child.
 363      * @version DOM Level 3
 364      */
 365     public Node removeChild(Node oldChild)
 366                             throws DOMException;
 367
 368     /**
 369      * Adds the node <code>newChild</code> to the end of the list of children
 370      * of this node. If the <code>newChild</code> is already in the tree, it
 371      * is first removed.
 372      * @param newChild The node to add.If it is a
 373      *   <code>DocumentFragment</code> object, the entire contents of the
 374      *   document fragment are moved into the child list of this node
 375      * @return The node added.
 376      * @exception DOMException
 377      *   HIERARCHY_REQUEST_ERR: Raised if this node is of a type that does not
 378      *   allow children of the type of the <code>newChild</code> node, or if
 379      *   the node to append is one of this node's ancestors or this node
 380      *   itself, or if this node is of type <code>Document</code> and the
 381      *   DOM application attempts to append a second
 382      *   <code>DocumentType</code> or <code>Element</code> node.
 383      *   <br>WRONG_DOCUMENT_ERR: Raised if <code>newChild</code> was created
 384      *   from a different document than the one that created this node.
 385      *   <br>NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly or
 386      *   if the previous parent of the node being inserted is readonly.
 387      *   <br>NOT_SUPPORTED_ERR: if the <code>newChild</code> node is a child
 388      *   of the <code>Document</code> node, this exception might be raised
 389      *   if the DOM implementation doesn't support the removal of the
 390      *   <code>DocumentType</code> child or <code>Element</code> child.
 391      * @version DOM Level 3
 392      */
 393     public Node appendChild(Node newChild)
 394                             throws DOMException;
 395
 396     /**
 397      * Returns whether this node has any children.
 398      * @return Returns <code>true</code> if this node has any children,
 399      *   <code>false</code> otherwise.
 400      */
 401     public boolean hasChildNodes();
 402
 403     /**
 404      * Returns a duplicate of this node, i.e., serves as a generic copy
 405      * constructor for nodes. The duplicate node has no parent (
 406      * <code>parentNode</code> is <code>null</code>) and no user data. User
 407      * data associated to the imported node is not carried over. However, if
 408      * any <code>UserDataHandlers</code> has been specified along with the
 409      * associated data these handlers will be called with the appropriate
 410      * parameters before this method returns.
 411      * <br>Cloning an <code>Element</code> copies all attributes and their
 412      * values, including those generated by the XML processor to represent
 413      * defaulted attributes, but this method does not copy any children it
 414      * contains unless it is a deep clone. This includes text contained in
 415      * an the <code>Element</code> since the text is contained in a child
 416      * <code>Text</code> node. Cloning an <code>Attr</code> directly, as
 417      * opposed to be cloned as part of an <code>Element</code> cloning
 418      * operation, returns a specified attribute (<code>specified</code> is
 419      * <code>true</code>). Cloning an <code>Attr</code> always clones its
 420      * children, since they represent its value, no matter whether this is a
 421      * deep clone or not. Cloning an <code>EntityReference</code>
 422      * automatically constructs its subtree if a corresponding
 423      * <code>Entity</code> is available, no matter whether this is a deep
 424      * clone or not. Cloning any other type of node simply returns a copy of
 425      * this node.
 426      * <br>Note that cloning an immutable subtree results in a mutable copy,
 427      * but the children of an <code>EntityReference</code> clone are readonly
 428      * . In addition, clones of unspecified <code>Attr</code> nodes are
 429      * specified. And, cloning <code>Document</code>,
 430      * <code>DocumentType</code>, <code>Entity</code>, and
 431      * <code>Notation</code> nodes is implementation dependent.
 432      * @param deep If <code>true</code>, recursively clone the subtree under
 433      *   the specified node; if <code>false</code>, clone only the node
 434      *   itself (and its attributes, if it is an <code>Element</code>).
 435      * @return The duplicate node.
 436      */
 437     public Node cloneNode(boolean deep);
 438
 439     /**
 440      *  Puts all <code>Text</code> nodes in the full depth of the sub-tree
 441      * underneath this <code>Node</code>, including attribute nodes, into a
 442      * "normal" form where only structure (e.g., elements, comments,
 443      * processing instructions, CDATA sections, and entity references)
 444      * separates <code>Text</code> nodes, i.e., there are neither adjacent
 445      * <code>Text</code> nodes nor empty <code>Text</code> nodes. This can
 446      * be used to ensure that the DOM view of a document is the same as if
 447      * it were saved and re-loaded, and is useful when operations (such as
 448      * XPointer [<a href='http://www.w3.org/TR/2003/REC-xptr-framework-20030325/'>XPointer</a>]
 449      *  lookups) that depend on a particular document tree structure are to
 450      * be used. If the parameter "normalize-characters" of the
 451      * <code>DOMConfiguration</code> object attached to the
 452      * <code>Node.ownerDocument</code> is <code>true</code>, this method
 453      * will also fully normalize the characters of the <code>Text</code>
 454      * nodes.
 455      * <p ><b>Note:</b> In cases where the document contains
 456      * <code>CDATASections</code>, the normalize operation alone may not be
 457      * sufficient, since XPointers do not differentiate between
 458      * <code>Text</code> nodes and <code>CDATASection</code> nodes.
 459      * @version DOM Level 3
 460      */
 461     public void normalize();
 462
 463     /**
 464      *  Tests whether the DOM implementation implements a specific feature and
 465      * that feature is supported by this node, as specified in .
 466      * @param feature  The name of the feature to test.
 467      * @param version  This is the version number of the feature to test.
 468      * @return Returns <code>true</code> if the specified feature is
 469      *   supported on this node, <code>false</code> otherwise.
 470      * @since DOM Level 2
 471      */
 472     public boolean isSupported(String feature,
 473                                String version);
 474
 475     /**
 476      * The namespace URI of this node, or <code>null</code> if it is
 477      * unspecified (see ).
 478      * <br>This is not a computed value that is the result of a namespace
 479      * lookup based on an examination of the namespace declarations in
 480      * scope. It is merely the namespace URI given at creation time.
 481      * <br>For nodes of any type other than <code>ELEMENT_NODE</code> and
 482      * <code>ATTRIBUTE_NODE</code> and nodes created with a DOM Level 1
 483      * method, such as <code>Document.createElement()</code>, this is always
 484      * <code>null</code>.
 485      * <p ><b>Note:</b> Per the <em>Namespaces in XML</em> Specification [<a href='http://www.w3.org/TR/1999/REC-xml-names-19990114/'>XML Namespaces</a>]
 486      *  an attribute does not inherit its namespace from the element it is
 487      * attached to. If an attribute is not explicitly given a namespace, it
 488      * simply has no namespace.
 489      * @since DOM Level 2
 490      */
 491     public String getNamespaceURI();
 492
 493     /**
 494      * The namespace prefix of this node, or <code>null</code> if it is
 495      * unspecified. When it is defined to be <code>null</code>, setting it
 496      * has no effect, including if the node is read-only.
 497      * <br>Note that setting this attribute, when permitted, changes the
 498      * <code>nodeName</code> attribute, which holds the qualified name, as
 499      * well as the <code>tagName</code> and <code>name</code> attributes of
 500      * the <code>Element</code> and <code>Attr</code> interfaces, when
 501      * applicable.
 502      * <br>Setting the prefix to <code>null</code> makes it unspecified,
 503      * setting it to an empty string is implementation dependent.
 504      * <br>Note also that changing the prefix of an attribute that is known to
 505      * have a default value, does not make a new attribute with the default
 506      * value and the original prefix appear, since the
 507      * <code>namespaceURI</code> and <code>localName</code> do not change.
 508      * <br>For nodes of any type other than <code>ELEMENT_NODE</code> and
 509      * <code>ATTRIBUTE_NODE</code> and nodes created with a DOM Level 1
 510      * method, such as <code>createElement</code> from the
 511      * <code>Document</code> interface, this is always <code>null</code>.
 512      * @since DOM Level 2
 513      */
 514     public String getPrefix();
 515     /**
 516      * The namespace prefix of this node, or <code>null</code> if it is
 517      * unspecified. When it is defined to be <code>null</code>, setting it
 518      * has no effect, including if the node is read-only.
 519      * <br>Note that setting this attribute, when permitted, changes the
 520      * <code>nodeName</code> attribute, which holds the qualified name, as
 521      * well as the <code>tagName</code> and <code>name</code> attributes of
 522      * the <code>Element</code> and <code>Attr</code> interfaces, when
 523      * applicable.
 524      * <br>Setting the prefix to <code>null</code> makes it unspecified,
 525      * setting it to an empty string is implementation dependent.
 526      * <br>Note also that changing the prefix of an attribute that is known to
 527      * have a default value, does not make a new attribute with the default
 528      * value and the original prefix appear, since the
 529      * <code>namespaceURI</code> and <code>localName</code> do not change.
 530      * <br>For nodes of any type other than <code>ELEMENT_NODE</code> and
 531      * <code>ATTRIBUTE_NODE</code> and nodes created with a DOM Level 1
 532      * method, such as <code>createElement</code> from the
 533      * <code>Document</code> interface, this is always <code>null</code>.
 534      * @exception DOMException
 535      *   INVALID_CHARACTER_ERR: Raised if the specified prefix contains an
 536      *   illegal character according to the XML version in use specified in
 537      *   the <code>Document.xmlVersion</code> attribute.
 538      *   <br>NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
 539      *   <br>NAMESPACE_ERR: Raised if the specified <code>prefix</code> is
 540      *   malformed per the Namespaces in XML specification, if the
 541      *   <code>namespaceURI</code> of this node is <code>null</code>, if the
 542      *   specified prefix is "xml" and the <code>namespaceURI</code> of this
 543      *   node is different from "<a href='http://www.w3.org/XML/1998/namespace'>
 544      *   http://www.w3.org/XML/1998/namespace</a>", if this node is an attribute and the specified prefix is "xmlns" and
 545      *   the <code>namespaceURI</code> of this node is different from "<a href='http://www.w3.org/2000/xmlns/'>http://www.w3.org/2000/xmlns/</a>", or if this node is an attribute and the <code>qualifiedName</code> of
 546      *   this node is "xmlns" [<a href='http://www.w3.org/TR/1999/REC-xml-names-19990114/'>XML Namespaces</a>]
 547      *   .
 548      * @since DOM Level 2
 549      */
 550     public void setPrefix(String prefix)
 551                                throws DOMException;
 552
 553     /**
 554      * Returns the local part of the qualified name of this node.
 555      * <br>For nodes of any type other than <code>ELEMENT_NODE</code> and
 556      * <code>ATTRIBUTE_NODE</code> and nodes created with a DOM Level 1
 557      * method, such as <code>Document.createElement()</code>, this is always
 558      * <code>null</code>.
 559      * @since DOM Level 2
 560      */
 561     public String getLocalName();
 562
 563     /**
 564      * Returns whether this node (if it is an element) has any attributes.
 565      * @return Returns <code>true</code> if this node has any attributes,
 566      *   <code>false</code> otherwise.
 567      * @since DOM Level 2
 568      */
 569     public boolean hasAttributes();
 570
 571     /**
 572      * The absolute base URI of this node or <code>null</code> if the
 573      * implementation wasn't able to obtain an absolute URI. This value is
 574      * computed as described in . However, when the <code>Document</code>
 575      * supports the feature "HTML" [<a href='http://www.w3.org/TR/2003/REC-DOM-Level-2-HTML-20030109'>DOM Level 2 HTML</a>]
 576      * , the base URI is computed using first the value of the href
 577      * attribute of the HTML BASE element if any, and the value of the
 578      * <code>documentURI</code> attribute from the <code>Document</code>
 579      * interface otherwise.
 580      * @since DOM Level 3
 581      */
 582     public String getBaseURI();
 583
 584     // DocumentPosition
 585     /**
 586      * The two nodes are disconnected. Order between disconnected nodes is
 587      * always implementation-specific.
 588      */
 589     public static final short DOCUMENT_POSITION_DISCONNECTED = 0x01;
 590     /**
 591      * The second node precedes the reference node.
 592      */
 593     public static final short DOCUMENT_POSITION_PRECEDING = 0x02;
 594     /**
 595      * The node follows the reference node.
 596      */
 597     public static final short DOCUMENT_POSITION_FOLLOWING = 0x04;
 598     /**
 599      * The node contains the reference node. A node which contains is always
 600      * preceding, too.
 601      */
 602     public static final short DOCUMENT_POSITION_CONTAINS = 0x08;
 603     /**
 604      * The node is contained by the reference node. A node which is contained
 605      * is always following, too.
 606      */
 607     public static final short DOCUMENT_POSITION_CONTAINED_BY = 0x10;
 608     /**
 609      * The determination of preceding versus following is
 610      * implementation-specific.
 611      */
 612     public static final short DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC = 0x20;
 613
 614     /**
 615      * Compares the reference node, i.e. the node on which this method is
 616      * being called, with a node, i.e. the one passed as a parameter, with
 617      * regard to their position in the document and according to the
 618      * document order.
 619      * @param other The node to compare against the reference node.
 620      * @return Returns how the node is positioned relatively to the reference
 621      *   node.
 622      * @exception DOMException
 623      *   NOT_SUPPORTED_ERR: when the compared nodes are from different DOM
 624      *   implementations that do not coordinate to return consistent
 625      *   implementation-specific results.
 626      * @since DOM Level 3
 627      */
 628     public short compareDocumentPosition(Node other)
 629                                          throws DOMException;
 630
 631     /**
 632      * This attribute returns the text content of this node and its
 633      * descendants. When it is defined to be <code>null</code>, setting it
 634      * has no effect. On setting, any possible children this node may have
 635      * are removed and, if it the new string is not empty or
 636      * <code>null</code>, replaced by a single <code>Text</code> node
 637      * containing the string this attribute is set to.
 638      * <br> On getting, no serialization is performed, the returned string
 639      * does not contain any markup. No whitespace normalization is performed
 640      * and the returned string does not contain the white spaces in element
 641      * content (see the attribute
 642      * <code>Text.isElementContentWhitespace</code>). Similarly, on setting,
 643      * no parsing is performed either, the input string is taken as pure
 644      * textual content.
 645      * <br>The string returned is made of the text content of this node
 646      * depending on its type, as defined below:
 647      * <table border='1' cellpadding='3'>
 648      * <tr>
 649      * <th>Node type</th>
 650      * <th>Content</th>
 651      * </tr>
 652      * <tr>
 653      * <td valign='top' rowspan='1' colspan='1'>
 654      * ELEMENT_NODE, ATTRIBUTE_NODE, ENTITY_NODE, ENTITY_REFERENCE_NODE,
 655      * DOCUMENT_FRAGMENT_NODE</td>
 656      * <td valign='top' rowspan='1' colspan='1'>concatenation of the <code>textContent</code>
 657      * attribute value of every child node, excluding COMMENT_NODE and
 658      * PROCESSING_INSTRUCTION_NODE nodes. This is the empty string if the
 659      * node has no children.</td>
 660      * </tr>
 661      * <tr>
 662      * <td valign='top' rowspan='1' colspan='1'>TEXT_NODE, CDATA_SECTION_NODE, COMMENT_NODE,
 663      * PROCESSING_INSTRUCTION_NODE</td>
 664      * <td valign='top' rowspan='1' colspan='1'><code>nodeValue</code></td>
 665      * </tr>
 666      * <tr>
 667      * <td valign='top' rowspan='1' colspan='1'>DOCUMENT_NODE,
 668      * DOCUMENT_TYPE_NODE, NOTATION_NODE</td>
 669      * <td valign='top' rowspan='1' colspan='1'><em>null</em></td>
 670      * </tr>
 671      * </table>
 672      * @exception DOMException
 673      *   DOMSTRING_SIZE_ERR: Raised when it would return more characters than
 674      *   fit in a <code>DOMString</code> variable on the implementation
 675      *   platform.
 676      * @since DOM Level 3
 677      */
 678     public String getTextContent()
 679                                          throws DOMException;
 680     /**
 681      * This attribute returns the text content of this node and its
 682      * descendants. When it is defined to be <code>null</code>, setting it
 683      * has no effect. On setting, any possible children this node may have
 684      * are removed and, if it the new string is not empty or
 685      * <code>null</code>, replaced by a single <code>Text</code> node
 686      * containing the string this attribute is set to.
 687      * <br> On getting, no serialization is performed, the returned string
 688      * does not contain any markup. No whitespace normalization is performed
 689      * and the returned string does not contain the white spaces in element
 690      * content (see the attribute
 691      * <code>Text.isElementContentWhitespace</code>). Similarly, on setting,
 692      * no parsing is performed either, the input string is taken as pure
 693      * textual content.
 694      * <br>The string returned is made of the text content of this node
 695      * depending on its type, as defined below:
 696      * <table border='1' cellpadding='3'>
 697      * <tr>
 698      * <th>Node type</th>
 699      * <th>Content</th>
 700      * </tr>
 701      * <tr>
 702      * <td valign='top' rowspan='1' colspan='1'>
 703      * ELEMENT_NODE, ATTRIBUTE_NODE, ENTITY_NODE, ENTITY_REFERENCE_NODE,
 704      * DOCUMENT_FRAGMENT_NODE</td>
 705      * <td valign='top' rowspan='1' colspan='1'>concatenation of the <code>textContent</code>
 706      * attribute value of every child node, excluding COMMENT_NODE and
 707      * PROCESSING_INSTRUCTION_NODE nodes. This is the empty string if the
 708      * node has no children.</td>
 709      * </tr>
 710      * <tr>
 711      * <td valign='top' rowspan='1' colspan='1'>TEXT_NODE, CDATA_SECTION_NODE, COMMENT_NODE,
 712      * PROCESSING_INSTRUCTION_NODE</td>
 713      * <td valign='top' rowspan='1' colspan='1'><code>nodeValue</code></td>
 714      * </tr>
 715      * <tr>
 716      * <td valign='top' rowspan='1' colspan='1'>DOCUMENT_NODE,
 717      * DOCUMENT_TYPE_NODE, NOTATION_NODE</td>
 718      * <td valign='top' rowspan='1' colspan='1'><em>null</em></td>
 719      * </tr>
 720      * </table>
 721      * @exception DOMException
 722      *   NO_MODIFICATION_ALLOWED_ERR: Raised when the node is readonly.
 723      * @since DOM Level 3
 724      */
 725     public void setTextContent(String textContent)
 726                                          throws DOMException;
 727
 728     /**
 729      * Returns whether this node is the same node as the given one.
 730      * <br>This method provides a way to determine whether two
 731      * <code>Node</code> references returned by the implementation reference
 732      * the same object. When two <code>Node</code> references are references
 733      * to the same object, even if through a proxy, the references may be
 734      * used completely interchangeably, such that all attributes have the
 735      * same values and calling the same DOM method on either reference
 736      * always has exactly the same effect.
 737      * @param other The node to test against.
 738      * @return Returns <code>true</code> if the nodes are the same,
 739      *   <code>false</code> otherwise.
 740      * @since DOM Level 3
 741      */
 742     public boolean isSameNode(Node other);
 743
 744     /**
 745      * Look up the prefix associated to the given namespace URI, starting from
 746      * this node. The default namespace declarations are ignored by this
 747      * method.
 748      * <br>See  for details on the algorithm used by this method.
 749      * @param namespaceURI The namespace URI to look for.
 750      * @return Returns an associated namespace prefix if found or
 751      *   <code>null</code> if none is found. If more than one prefix are
 752      *   associated to the namespace prefix, the returned namespace prefix
 753      *   is implementation dependent.
 754      * @since DOM Level 3
 755      */
 756     public String lookupPrefix(String namespaceURI);
 757
 758     /**
 759      *  This method checks if the specified <code>namespaceURI</code> is the
 760      * default namespace or not.
 761      * @param namespaceURI The namespace URI to look for.
 762      * @return Returns <code>true</code> if the specified
 763      *   <code>namespaceURI</code> is the default namespace,
 764      *   <code>false</code> otherwise.
 765      * @since DOM Level 3
 766      */
 767     public boolean isDefaultNamespace(String namespaceURI);
 768
 769     /**
 770      * Look up the namespace URI associated to the given prefix, starting from
 771      * this node.
 772      * <br>See  for details on the algorithm used by this method.
 773      * @param prefix The prefix to look for. If this parameter is
 774      *   <code>null</code>, the method will return the default namespace URI
 775      *   if any.
 776      * @return Returns the associated namespace URI or <code>null</code> if
 777      *   none is found.
 778      * @since DOM Level 3
 779      */
 780     public String lookupNamespaceURI(String prefix);
 781
 782     /**
 783      * Tests whether two nodes are equal.
 784      * <br>This method tests for equality of nodes, not sameness (i.e.,
 785      * whether the two nodes are references to the same object) which can be
 786      * tested with <code>Node.isSameNode()</code>. All nodes that are the
 787      * same will also be equal, though the reverse may not be true.
 788      * <br>Two nodes are equal if and only if the following conditions are
 789      * satisfied:
 790      * <ul>
 791      * <li>The two nodes are of the same type.
 792      * </li>
 793      * <li>The following string
 794      * attributes are equal: <code>nodeName</code>, <code>localName</code>,
 795      * <code>namespaceURI</code>, <code>prefix</code>, <code>nodeValue</code>
 796      * . This is: they are both <code>null</code>, or they have the same
 797      * length and are character for character identical.
 798      * </li>
 799      * <li>The
 800      * <code>attributes</code> <code>NamedNodeMaps</code> are equal. This
 801      * is: they are both <code>null</code>, or they have the same length and
 802      * for each node that exists in one map there is a node that exists in
 803      * the other map and is equal, although not necessarily at the same
 804      * index.
 805      * </li>
 806      * <li>The <code>childNodes</code> <code>NodeLists</code> are equal.
 807      * This is: they are both <code>null</code>, or they have the same
 808      * length and contain equal nodes at the same index. Note that
 809      * normalization can affect equality; to avoid this, nodes should be
 810      * normalized before being compared.
 811      * </li>
 812      * </ul>
 813      * <br>For two <code>DocumentType</code> nodes to be equal, the following
 814      * conditions must also be satisfied:
 815      * <ul>
 816      * <li>The following string attributes
 817      * are equal: <code>publicId</code>, <code>systemId</code>,
 818      * <code>internalSubset</code>.
 819      * </li>
 820      * <li>The <code>entities</code>
 821      * <code>NamedNodeMaps</code> are equal.
 822      * </li>
 823      * <li>The <code>notations</code>
 824      * <code>NamedNodeMaps</code> are equal.
 825      * </li>
 826      * </ul>
 827      * <br>On the other hand, the following do not affect equality: the
 828      * <code>ownerDocument</code>, <code>baseURI</code>, and
 829      * <code>parentNode</code> attributes, the <code>specified</code>
 830      * attribute for <code>Attr</code> nodes, the <code>schemaTypeInfo</code>
 831      *  attribute for <code>Attr</code> and <code>Element</code> nodes, the
 832      * <code>Text.isElementContentWhitespace</code> attribute for
 833      * <code>Text</code> nodes, as well as any user data or event listeners
 834      * registered on the nodes.
 835      * <p ><b>Note:</b>  As a general rule, anything not mentioned in the
 836      * description above is not significant in consideration of equality
 837      * checking. Note that future versions of this specification may take
 838      * into account more attributes and implementations conform to this
 839      * specification are expected to be updated accordingly.
 840      * @param arg The node to compare equality with.
 841      * @return Returns <code>true</code> if the nodes are equal,
 842      *   <code>false</code> otherwise.
 843      * @since DOM Level 3
 844      */
 845     public boolean isEqualNode(Node arg);
 846
 847     /**
 848      *  This method returns a specialized object which implements the
 849      * specialized APIs of the specified feature and version, as specified
 850      * in . The specialized object may also be obtained by using
 851      * binding-specific casting methods but is not necessarily expected to,
 852      * as discussed in . This method also allow the implementation to
 853      * provide specialized objects which do not support the <code>Node</code>
 854      *  interface.
 855      * @param feature  The name of the feature requested. Note that any plus
 856      *   sign "+" prepended to the name of the feature will be ignored since
 857      *   it is not significant in the context of this method.
 858      * @param version  This is the version number of the feature to test.
 859      * @return  Returns an object which implements the specialized APIs of
 860      *   the specified feature and version, if any, or <code>null</code> if
 861      *   there is no object which implements interfaces associated with that
 862      *   feature. If the <code>DOMObject</code> returned by this method
 863      *   implements the <code>Node</code> interface, it must delegate to the
 864      *   primary core <code>Node</code> and not return results inconsistent
 865      *   with the primary core <code>Node</code> such as attributes,
 866      *   childNodes, etc.
 867      * @since DOM Level 3
 868      */
 869     public Object getFeature(String feature,
 870                              String version);
 871
 872     /**
 873      * Associate an object to a key on this node. The object can later be
 874      * retrieved from this node by calling <code>getUserData</code> with the
 875      * same key.
 876      * @param key The key to associate the object to.
 877      * @param data The object to associate to the given key, or
 878      *   <code>null</code> to remove any existing association to that key.
 879      * @param handler The handler to associate to that key, or
 880      *   <code>null</code>.
 881      * @return Returns the <code>DOMUserData</code> previously associated to
 882      *   the given key on this node, or <code>null</code> if there was none.
 883      * @since DOM Level 3
 884      */
 885     public Object setUserData(String key,
 886                               Object data,
 887                               UserDataHandler handler);
 888
 889     /**
 890      * Retrieves the object associated to a key on a this node. The object
 891      * must first have been set to this node by calling
 892      * <code>setUserData</code> with the same key.
 893      * @param key The key the object is associated to.
 894      * @return Returns the <code>DOMUserData</code> associated to the given
 895      *   key on this node, or <code>null</code> if there was none.
 896      * @since DOM Level 3
 897      */
 898     public Object getUserData(String key);
 899
 900 }