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 } 901
