44 /**
  45  * The <code>Node</code> interface is the primary datatype for the entire
  46  * Document Object Model. It represents a single node in the document tree.
  47  * While all objects implementing the <code>Node</code> interface expose
  48  * methods for dealing with children, not all objects implementing the
  49  * <code>Node</code> interface may have children. For example,
  50  * <code>Text</code> nodes may not have children, and adding children to
  51  * such nodes results in a <code>DOMException</code> being raised.
  52  * <p>The attributes <code>nodeName</code>, <code>nodeValue</code> and
  53  * <code>attributes</code> are included as a mechanism to get at node
  54  * information without casting down to the specific derived interface. In
  55  * cases where there is no obvious mapping of these attributes for a
  56  * specific <code>nodeType</code> (e.g., <code>nodeValue</code> for an
  57  * <code>Element</code> or <code>attributes</code> for a <code>Comment</code>
  58  * ), this returns <code>null</code>. Note that the specialized interfaces
  59  * may contain additional and more convenient mechanisms to get and set the
  60  * relevant information.
  61  * <p>The values of <code>nodeName</code>,
  62  * <code>nodeValue</code>, and <code>attributes</code> vary according to the
  63  * node type as follows:
  64  * <table border='1' cellpadding='3'>


  65  * <tr>
  66  * <th>Interface</th>
  67  * <th>nodeName</th>
  68  * <th>nodeValue</th>
  69  * <th>attributes</th>
  70  * </tr>


  71  * <tr>
  72  * <td valign='top' rowspan='1' colspan='1'>
  73  * <code>Attr</code></td>
  74  * <td valign='top' rowspan='1' colspan='1'>same as <code>Attr.name</code></td>
  75  * <td valign='top' rowspan='1' colspan='1'>same as
  76  * <code>Attr.value</code></td>
  77  * <td valign='top' rowspan='1' colspan='1'><code>null</code></td>
  78  * </tr>
  79  * <tr>
  80  * <td valign='top' rowspan='1' colspan='1'><code>CDATASection</code></td>
  81  * <td valign='top' rowspan='1' colspan='1'>
  82  * <code>"#cdata-section"</code></td>
  83  * <td valign='top' rowspan='1' colspan='1'>same as <code>CharacterData.data</code>, the
  84  * content of the CDATA Section</td>
  85  * <td valign='top' rowspan='1' colspan='1'><code>null</code></td>
  86  * </tr>
  87  * <tr>
  88  * <td valign='top' rowspan='1' colspan='1'><code>Comment</code></td>
  89  * <td valign='top' rowspan='1' colspan='1'>
  90  * <code>"#comment"</code></td>
  91  * <td valign='top' rowspan='1' colspan='1'>same as <code>CharacterData.data</code>, the
  92  * content of the comment</td>
  93  * <td valign='top' rowspan='1' colspan='1'><code>null</code></td>
  94  * </tr>
  95  * <tr>
  96  * <td valign='top' rowspan='1' colspan='1'><code>Document</code></td>
  97  * <td valign='top' rowspan='1' colspan='1'>
  98  * <code>"#document"</code></td>
  99  * <td valign='top' rowspan='1' colspan='1'><code>null</code></td>
 100  * <td valign='top' rowspan='1' colspan='1'><code>null</code></td>
 101  * </tr>
 102  * <tr>
 103  * <td valign='top' rowspan='1' colspan='1'>
 104  * <code>DocumentFragment</code></td>
 105  * <td valign='top' rowspan='1' colspan='1'><code>"#document-fragment"</code></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>DocumentType</code></td>
 112  * <td valign='top' rowspan='1' colspan='1'>same as
 113  * <code>DocumentType.name</code></td>
 114  * <td valign='top' rowspan='1' colspan='1'><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'>
 119  * <code>Element</code></td>
 120  * <td valign='top' rowspan='1' colspan='1'>same as <code>Element.tagName</code></td>
 121  * <td valign='top' rowspan='1' colspan='1'><code>null</code></td>
 122  * <td valign='top' rowspan='1' colspan='1'>
 123  * <code>NamedNodeMap</code></td>
 124  * </tr>
 125  * <tr>
 126  * <td valign='top' rowspan='1' colspan='1'><code>Entity</code></td>
 127  * <td valign='top' rowspan='1' colspan='1'>entity name</td>
 128  * <td valign='top' rowspan='1' colspan='1'><code>null</code></td>
 129  * <td valign='top' rowspan='1' colspan='1'>
 130  * <code>null</code></td>
 131  * </tr>
 132  * <tr>
 133  * <td valign='top' rowspan='1' colspan='1'><code>EntityReference</code></td>
 134  * <td valign='top' rowspan='1' colspan='1'>name of entity referenced</td>
 135  * <td valign='top' rowspan='1' colspan='1'>
 136  * <code>null</code></td>
 137  * <td valign='top' rowspan='1' colspan='1'><code>null</code></td>
 138  * </tr>
 139  * <tr>
 140  * <td valign='top' rowspan='1' colspan='1'><code>Notation</code></td>
 141  * <td valign='top' rowspan='1' colspan='1'>notation name</td>
 142  * <td valign='top' rowspan='1' colspan='1'>
 143  * <code>null</code></td>
 144  * <td valign='top' rowspan='1' colspan='1'><code>null</code></td>
 145  * </tr>
 146  * <tr>
 147  * <td valign='top' rowspan='1' colspan='1'><code>ProcessingInstruction</code></td>
 148  * <td valign='top' rowspan='1' colspan='1'>same
 149  * as <code>ProcessingInstruction.target</code></td>
 150  * <td valign='top' rowspan='1' colspan='1'>same as
 151  * <code>ProcessingInstruction.data</code></td>
 152  * <td valign='top' rowspan='1' colspan='1'><code>null</code></td>
 153  * </tr>
 154  * <tr>
 155  * <td valign='top' rowspan='1' colspan='1'><code>Text</code></td>
 156  * <td valign='top' rowspan='1' colspan='1'>
 157  * <code>"#text"</code></td>
 158  * <td valign='top' rowspan='1' colspan='1'>same as <code>CharacterData.data</code>, the content
 159  * of the text node</td>
 160  * <td valign='top' rowspan='1' colspan='1'><code>null</code></td>
 161  * </tr>

 162  * </table>
 163  * <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>.
 164  */
 165 public interface Node {
 166     // NodeType
 167     /**
 168      * The node is an <code>Element</code>.
 169      */
 170     public static final short ELEMENT_NODE              = 1;
 171     /**
 172      * The node is an <code>Attr</code>.
 173      */
 174     public static final short ATTRIBUTE_NODE            = 2;
 175     /**
 176      * The node is a <code>Text</code> node.
 177      */
 178     public static final short TEXT_NODE                 = 3;
 179     /**
 180      * The node is a <code>CDATASection</code>.
 181      */

 670      */
 671     public short compareDocumentPosition(Node other)
 672                                          throws DOMException;
 673 
 674     /**
 675      * This attribute returns the text content of this node and its
 676      * descendants. When it is defined to be <code>null</code>, setting it
 677      * has no effect. On setting, any possible children this node may have
 678      * are removed and, if it the new string is not empty or
 679      * <code>null</code>, replaced by a single <code>Text</code> node
 680      * containing the string this attribute is set to.
 681      * <br> On getting, no serialization is performed, the returned string
 682      * does not contain any markup. No whitespace normalization is performed
 683      * and the returned string does not contain the white spaces in element
 684      * content (see the attribute
 685      * <code>Text.isElementContentWhitespace</code>). Similarly, on setting,
 686      * no parsing is performed either, the input string is taken as pure
 687      * textual content.
 688      * <br>The string returned is made of the text content of this node
 689      * depending on its type, as defined below:
 690      * <table border='1' cellpadding='3'>


 691      * <tr>
 692      * <th>Node type</th>
 693      * <th>Content</th>
 694      * </tr>


 695      * <tr>
 696      * <td valign='top' rowspan='1' colspan='1'>
 697      * ELEMENT_NODE, ATTRIBUTE_NODE, ENTITY_NODE, ENTITY_REFERENCE_NODE,
 698      * DOCUMENT_FRAGMENT_NODE</td>
 699      * <td valign='top' rowspan='1' colspan='1'>concatenation of the <code>textContent</code>
 700      * attribute value of every child node, excluding COMMENT_NODE and
 701      * PROCESSING_INSTRUCTION_NODE nodes. This is the empty string if the
 702      * node has no children.</td>
 703      * </tr>
 704      * <tr>
 705      * <td valign='top' rowspan='1' colspan='1'>TEXT_NODE, CDATA_SECTION_NODE, COMMENT_NODE,
 706      * PROCESSING_INSTRUCTION_NODE</td>
 707      * <td valign='top' rowspan='1' colspan='1'><code>nodeValue</code></td>
 708      * </tr>
 709      * <tr>
 710      * <td valign='top' rowspan='1' colspan='1'>DOCUMENT_NODE,
 711      * DOCUMENT_TYPE_NODE, NOTATION_NODE</td>
 712      * <td valign='top' rowspan='1' colspan='1'><em>null</em></td>
 713      * </tr>

 714      * </table>
 715      * @exception DOMException
 716      *   DOMSTRING_SIZE_ERR: Raised when it would return more characters than
 717      *   fit in a <code>DOMString</code> variable on the implementation
 718      *   platform.
 719      *
 720      * @since 1.5, DOM Level 3
 721      */
 722     public String getTextContent()
 723                                          throws DOMException;
 724     /**
 725      * This attribute returns the text content of this node and its
 726      * descendants. When it is defined to be <code>null</code>, setting it
 727      * has no effect. On setting, any possible children this node may have
 728      * are removed and, if it the new string is not empty or
 729      * <code>null</code>, replaced by a single <code>Text</code> node
 730      * containing the string this attribute is set to.
 731      * <br> On getting, no serialization is performed, the returned string
 732      * does not contain any markup. No whitespace normalization is performed
 733      * and the returned string does not contain the white spaces in element
 734      * content (see the attribute
 735      * <code>Text.isElementContentWhitespace</code>). Similarly, on setting,
 736      * no parsing is performed either, the input string is taken as pure
 737      * textual content.
 738      * <br>The string returned is made of the text content of this node
 739      * depending on its type, as defined below:
 740      * <table border='1' cellpadding='3'>


 741      * <tr>
 742      * <th>Node type</th>
 743      * <th>Content</th>
 744      * </tr>


 745      * <tr>
 746      * <td valign='top' rowspan='1' colspan='1'>
 747      * ELEMENT_NODE, ATTRIBUTE_NODE, ENTITY_NODE, ENTITY_REFERENCE_NODE,
 748      * DOCUMENT_FRAGMENT_NODE</td>
 749      * <td valign='top' rowspan='1' colspan='1'>concatenation of the <code>textContent</code>
 750      * attribute value of every child node, excluding COMMENT_NODE and
 751      * PROCESSING_INSTRUCTION_NODE nodes. This is the empty string if the
 752      * node has no children.</td>
 753      * </tr>
 754      * <tr>
 755      * <td valign='top' rowspan='1' colspan='1'>TEXT_NODE, CDATA_SECTION_NODE, COMMENT_NODE,
 756      * PROCESSING_INSTRUCTION_NODE</td>
 757      * <td valign='top' rowspan='1' colspan='1'><code>nodeValue</code></td>
 758      * </tr>
 759      * <tr>
 760      * <td valign='top' rowspan='1' colspan='1'>DOCUMENT_NODE,
 761      * DOCUMENT_TYPE_NODE, NOTATION_NODE</td>
 762      * <td valign='top' rowspan='1' colspan='1'><em>null</em></td>
 763      * </tr>

 764      * </table>
 765      * @exception DOMException
 766      *   NO_MODIFICATION_ALLOWED_ERR: Raised when the node is readonly.
 767      *
 768      * @since 1.5, DOM Level 3
 769      */
 770     public void setTextContent(String textContent)
 771                                          throws DOMException;
 772 
 773     /**
 774      * Returns whether this node is the same node as the given one.
 775      * <br>This method provides a way to determine whether two
 776      * <code>Node</code> references returned by the implementation reference
 777      * the same object. When two <code>Node</code> references are references
 778      * to the same object, even if through a proxy, the references may be
 779      * used completely interchangeably, such that all attributes have the
 780      * same values and calling the same DOM method on either reference
 781      * always has exactly the same effect.
 782      * @param other The node to test against.
 783      * @return Returns <code>true</code> if the nodes are the same,

  44 /**
  45  * The <code>Node</code> interface is the primary datatype for the entire
  46  * Document Object Model. It represents a single node in the document tree.
  47  * While all objects implementing the <code>Node</code> interface expose
  48  * methods for dealing with children, not all objects implementing the
  49  * <code>Node</code> interface may have children. For example,
  50  * <code>Text</code> nodes may not have children, and adding children to
  51  * such nodes results in a <code>DOMException</code> being raised.
  52  * <p>The attributes <code>nodeName</code>, <code>nodeValue</code> and
  53  * <code>attributes</code> are included as a mechanism to get at node
  54  * information without casting down to the specific derived interface. In
  55  * cases where there is no obvious mapping of these attributes for a
  56  * specific <code>nodeType</code> (e.g., <code>nodeValue</code> for an
  57  * <code>Element</code> or <code>attributes</code> for a <code>Comment</code>
  58  * ), this returns <code>null</code>. Note that the specialized interfaces
  59  * may contain additional and more convenient mechanisms to get and set the
  60  * relevant information.
  61  * <p>The values of <code>nodeName</code>,
  62  * <code>nodeValue</code>, and <code>attributes</code> vary according to the
  63  * node type as follows:
  64  * <table class="striped">
  65  * <caption style="display:none">Interface table</caption>
  66  * <thead>
  67  * <tr>
  68  * <th>Interface</th>
  69  * <th>nodeName</th>
  70  * <th>nodeValue</th>
  71  * <th>attributes</th>
  72  * </tr>
  73  * </thead>
  74  * <tbody>
  75  * <tr>
  76  * <td>
  77  * <code>Attr</code></td>
  78  * <td>same as <code>Attr.name</code></td>
  79  * <td>same as
  80  * <code>Attr.value</code></td>
  81  * <td><code>null</code></td>
  82  * </tr>
  83  * <tr>
  84  * <td><code>CDATASection</code></td>
  85  * <td>
  86  * <code>"#cdata-section"</code></td>
  87  * <td>same as <code>CharacterData.data</code>, the
  88  * content of the CDATA Section</td>
  89  * <td><code>null</code></td>
  90  * </tr>
  91  * <tr>
  92  * <td><code>Comment</code></td>
  93  * <td>
  94  * <code>"#comment"</code></td>
  95  * <td>same as <code>CharacterData.data</code>, the
  96  * content of the comment</td>
  97  * <td><code>null</code></td>
  98  * </tr>
  99  * <tr>
 100  * <td><code>Document</code></td>
 101  * <td>
 102  * <code>"#document"</code></td>
 103  * <td><code>null</code></td>
 104  * <td><code>null</code></td>
 105  * </tr>
 106  * <tr>
 107  * <td>
 108  * <code>DocumentFragment</code></td>
 109  * <td><code>"#document-fragment"</code></td>
 110  * <td>
 111  * <code>null</code></td>
 112  * <td><code>null</code></td>
 113  * </tr>
 114  * <tr>
 115  * <td><code>DocumentType</code></td>
 116  * <td>same as
 117  * <code>DocumentType.name</code></td>
 118  * <td><code>null</code></td>
 119  * <td><code>null</code></td>
 120  * </tr>
 121  * <tr>
 122  * <td>
 123  * <code>Element</code></td>
 124  * <td>same as <code>Element.tagName</code></td>
 125  * <td><code>null</code></td>
 126  * <td>
 127  * <code>NamedNodeMap</code></td>
 128  * </tr>
 129  * <tr>
 130  * <td><code>Entity</code></td>
 131  * <td>entity name</td>
 132  * <td><code>null</code></td>
 133  * <td>
 134  * <code>null</code></td>
 135  * </tr>
 136  * <tr>
 137  * <td><code>EntityReference</code></td>
 138  * <td>name of entity referenced</td>
 139  * <td>
 140  * <code>null</code></td>
 141  * <td><code>null</code></td>
 142  * </tr>
 143  * <tr>
 144  * <td><code>Notation</code></td>
 145  * <td>notation name</td>
 146  * <td>
 147  * <code>null</code></td>
 148  * <td><code>null</code></td>
 149  * </tr>
 150  * <tr>
 151  * <td><code>ProcessingInstruction</code></td>
 152  * <td>same
 153  * as <code>ProcessingInstruction.target</code></td>
 154  * <td>same as
 155  * <code>ProcessingInstruction.data</code></td>
 156  * <td><code>null</code></td>
 157  * </tr>
 158  * <tr>
 159  * <td><code>Text</code></td>
 160  * <td>
 161  * <code>"#text"</code></td>
 162  * <td>same as <code>CharacterData.data</code>, the content
 163  * of the text node</td>
 164  * <td><code>null</code></td>
 165  * </tr>
 166  * </tbody>
 167  * </table>
 168  * <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>.
 169  */
 170 public interface Node {
 171     // NodeType
 172     /**
 173      * The node is an <code>Element</code>.
 174      */
 175     public static final short ELEMENT_NODE              = 1;
 176     /**
 177      * The node is an <code>Attr</code>.
 178      */
 179     public static final short ATTRIBUTE_NODE            = 2;
 180     /**
 181      * The node is a <code>Text</code> node.
 182      */
 183     public static final short TEXT_NODE                 = 3;
 184     /**
 185      * The node is a <code>CDATASection</code>.
 186      */

 675      */
 676     public short compareDocumentPosition(Node other)
 677                                          throws DOMException;
 678 
 679     /**
 680      * This attribute returns the text content of this node and its
 681      * descendants. When it is defined to be <code>null</code>, setting it
 682      * has no effect. On setting, any possible children this node may have
 683      * are removed and, if it the new string is not empty or
 684      * <code>null</code>, replaced by a single <code>Text</code> node
 685      * containing the string this attribute is set to.
 686      * <br> On getting, no serialization is performed, the returned string
 687      * does not contain any markup. No whitespace normalization is performed
 688      * and the returned string does not contain the white spaces in element
 689      * content (see the attribute
 690      * <code>Text.isElementContentWhitespace</code>). Similarly, on setting,
 691      * no parsing is performed either, the input string is taken as pure
 692      * textual content.
 693      * <br>The string returned is made of the text content of this node
 694      * depending on its type, as defined below:
 695      * <table class="striped">
 696      * <caption style="display:none">Node/Content table</caption>
 697      * <thead>
 698      * <tr>
 699      * <th>Node type</th>
 700      * <th>Content</th>
 701      * </tr>
 702      * </thead>
 703      * <tbody>
 704      * <tr>
 705      * <td>
 706      * ELEMENT_NODE, ATTRIBUTE_NODE, ENTITY_NODE, ENTITY_REFERENCE_NODE,
 707      * DOCUMENT_FRAGMENT_NODE</td>
 708      * <td>concatenation of the <code>textContent</code>
 709      * attribute value of every child node, excluding COMMENT_NODE and
 710      * PROCESSING_INSTRUCTION_NODE nodes. This is the empty string if the
 711      * node has no children.</td>
 712      * </tr>
 713      * <tr>
 714      * <td>TEXT_NODE, CDATA_SECTION_NODE, COMMENT_NODE,
 715      * PROCESSING_INSTRUCTION_NODE</td>
 716      * <td><code>nodeValue</code></td>
 717      * </tr>
 718      * <tr>
 719      * <td>DOCUMENT_NODE,
 720      * DOCUMENT_TYPE_NODE, NOTATION_NODE</td>
 721      * <td><em>null</em></td>
 722      * </tr>
 723      * </tbody>
 724      * </table>
 725      * @exception DOMException
 726      *   DOMSTRING_SIZE_ERR: Raised when it would return more characters than
 727      *   fit in a <code>DOMString</code> variable on the implementation
 728      *   platform.
 729      *
 730      * @since 1.5, DOM Level 3
 731      */
 732     public String getTextContent()
 733                                          throws DOMException;
 734     /**
 735      * This attribute returns the text content of this node and its
 736      * descendants. When it is defined to be <code>null</code>, setting it
 737      * has no effect. On setting, any possible children this node may have
 738      * are removed and, if it the new string is not empty or
 739      * <code>null</code>, replaced by a single <code>Text</code> node
 740      * containing the string this attribute is set to.
 741      * <br> On getting, no serialization is performed, the returned string
 742      * does not contain any markup. No whitespace normalization is performed
 743      * and the returned string does not contain the white spaces in element
 744      * content (see the attribute
 745      * <code>Text.isElementContentWhitespace</code>). Similarly, on setting,
 746      * no parsing is performed either, the input string is taken as pure
 747      * textual content.
 748      * <br>The string returned is made of the text content of this node
 749      * depending on its type, as defined below:
 750      * <table class="striped">
 751      * <caption style="display:none">Node/Content table</caption>
 752      * <thead>
 753      * <tr>
 754      * <th>Node type</th>
 755      * <th>Content</th>
 756      * </tr>
 757      * </thead>
 758      * <tbody>
 759      * <tr>
 760      * <td>
 761      * ELEMENT_NODE, ATTRIBUTE_NODE, ENTITY_NODE, ENTITY_REFERENCE_NODE,
 762      * DOCUMENT_FRAGMENT_NODE</td>
 763      * <td>concatenation of the <code>textContent</code>
 764      * attribute value of every child node, excluding COMMENT_NODE and
 765      * PROCESSING_INSTRUCTION_NODE nodes. This is the empty string if the
 766      * node has no children.</td>
 767      * </tr>
 768      * <tr>
 769      * <td>TEXT_NODE, CDATA_SECTION_NODE, COMMENT_NODE,
 770      * PROCESSING_INSTRUCTION_NODE</td>
 771      * <td><code>nodeValue</code></td>
 772      * </tr>
 773      * <tr>
 774      * <td>DOCUMENT_NODE,
 775      * DOCUMENT_TYPE_NODE, NOTATION_NODE</td>
 776      * <td><em>null</em></td>
 777      * </tr>
 778      * </tbody>
 779      * </table>
 780      * @exception DOMException
 781      *   NO_MODIFICATION_ALLOWED_ERR: Raised when the node is readonly.
 782      *
 783      * @since 1.5, DOM Level 3
 784      */
 785     public void setTextContent(String textContent)
 786                                          throws DOMException;
 787 
 788     /**
 789      * Returns whether this node is the same node as the given one.
 790      * <br>This method provides a way to determine whether two
 791      * <code>Node</code> references returned by the implementation reference
 792      * the same object. When two <code>Node</code> references are references
 793      * to the same object, even if through a proxy, the references may be
 794      * used completely interchangeably, such that all attributes have the
 795      * same values and calling the same DOM method on either reference
 796      * always has exactly the same effect.
 797      * @param other The node to test against.
 798      * @return Returns <code>true</code> if the nodes are the same,