Source for org.w3c.dom.Node

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