libjava/org/w3c/dom/Node.java

   1 /*\r
   2  * Copyright (c) 2000 World Wide Web Consortium,\r
   3  * (Massachusetts Institute of Technology, Institut National de\r
   4  * Recherche en Informatique et en Automatique, Keio University). All\r
   5  * Rights Reserved. This program is distributed under the W3C's Software\r
   6  * Intellectual Property License. This program is distributed in the\r
   7  * hope that it will be useful, but WITHOUT ANY WARRANTY; without even\r
   8  * the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR\r
   9  * PURPOSE.\r
  10  * See W3C License http://www.w3.org/Consortium/Legal/ for more details.\r
  11  */\r
  12 \r
  13 package org.w3c.dom;\r
  14 \r
  15 /**\r
  16  * The <code>Node</code> interface is the primary datatype for the entire \r
  17  * Document Object Model. It represents a single node in the document tree. \r
  18  * While all objects implementing the <code>Node</code> interface expose \r
  19  * methods for dealing with children, not all objects implementing the \r
  20  * <code>Node</code> interface may have children. For example, \r
  21  * <code>Text</code> nodes may not have children, and adding children to \r
  22  * such nodes results in a <code>DOMException</code> being raised.\r
  23  * <p>The attributes <code>nodeName</code>, <code>nodeValue</code> and \r
  24  * <code>attributes</code> are included as a mechanism to get at node \r
  25  * information without casting down to the specific derived interface. In \r
  26  * cases where there is no obvious mapping of these attributes for a \r
  27  * specific <code>nodeType</code> (e.g., <code>nodeValue</code> for an \r
  28  * <code>Element</code> or <code>attributes</code> for a <code>Comment</code>\r
  29  * ), this returns <code>null</code>. Note that the specialized interfaces \r
  30  * may contain additional and more convenient mechanisms to get and set the \r
  31  * relevant information.\r
  32  * <p>See also the <a href='http://www.w3.org/TR/2000/REC-DOM-Level-2-Core-20001113'>Document Object Model (DOM) Level 2 Core Specification</a>.\r
  33  */\r
  34 public interface Node {\r
  35     // NodeType\r
  36     /**\r
  37      * The node is an <code>Element</code>.\r
  38      */\r
  39     public static final short ELEMENT_NODE              = 1;\r
  40     /**\r
  41      * The node is an <code>Attr</code>.\r
  42      */\r
  43     public static final short ATTRIBUTE_NODE            = 2;\r
  44     /**\r
  45      * The node is a <code>Text</code> node.\r
  46      */\r
  47     public static final short TEXT_NODE                 = 3;\r
  48     /**\r
  49      * The node is a <code>CDATASection</code>.\r
  50      */\r
  51     public static final short CDATA_SECTION_NODE        = 4;\r
  52     /**\r
  53      * The node is an <code>EntityReference</code>.\r
  54      */\r
  55     public static final short ENTITY_REFERENCE_NODE     = 5;\r
  56     /**\r
  57      * The node is an <code>Entity</code>.\r
  58      */\r
  59     public static final short ENTITY_NODE               = 6;\r
  60     /**\r
  61      * The node is a <code>ProcessingInstruction</code>.\r
  62      */\r
  63     public static final short PROCESSING_INSTRUCTION_NODE = 7;\r
  64     /**\r
  65      * The node is a <code>Comment</code>.\r
  66      */\r
  67     public static final short COMMENT_NODE              = 8;\r
  68     /**\r
  69      * The node is a <code>Document</code>.\r
  70      */\r
  71     public static final short DOCUMENT_NODE             = 9;\r
  72     /**\r
  73      * The node is a <code>DocumentType</code>.\r
  74      */\r
  75     public static final short DOCUMENT_TYPE_NODE        = 10;\r
  76     /**\r
  77      * The node is a <code>DocumentFragment</code>.\r
  78      */\r
  79     public static final short DOCUMENT_FRAGMENT_NODE    = 11;\r
  80     /**\r
  81      * The node is a <code>Notation</code>.\r
  82      */\r
  83     public static final short NOTATION_NODE             = 12;\r
  84 \r
  85     /**\r
  86      * The name of this node, depending on its type; see the table above. \r
  87      */\r
  88     public String getNodeName();\r
  89 \r
  90     /**\r
  91      * The value of this node, depending on its type; see the table above. \r
  92      * When it is defined to be <code>null</code>, setting it has no effect.\r
  93      * @exception DOMException\r
  94      *   NO_MODIFICATION_ALLOWED_ERR: Raised when the node is readonly.\r
  95      * @exception DOMException\r
  96      *   DOMSTRING_SIZE_ERR: Raised when it would return more characters than \r
  97      *   fit in a <code>DOMString</code> variable on the implementation \r
  98      *   platform.\r
  99      */\r
 100     public String getNodeValue()\r
 101                                  throws DOMException;\r
 102     public void setNodeValue(String nodeValue)\r
 103                                  throws DOMException;\r
 104 \r
 105     /**\r
 106      * A code representing the type of the underlying object, as defined above.\r
 107      */\r
 108     public short getNodeType();\r
 109 \r
 110     /**\r
 111      * The parent of this node. All nodes, except <code>Attr</code>, \r
 112      * <code>Document</code>, <code>DocumentFragment</code>, \r
 113      * <code>Entity</code>, and <code>Notation</code> may have a parent. \r
 114      * However, if a node has just been created and not yet added to the \r
 115      * tree, or if it has been removed from the tree, this is \r
 116      * <code>null</code>.\r
 117      */\r
 118     public Node getParentNode();\r
 119 \r
 120     /**\r
 121      * A <code>NodeList</code> that contains all children of this node. If \r
 122      * there are no children, this is a <code>NodeList</code> containing no \r
 123      * nodes.\r
 124      */\r
 125     public NodeList getChildNodes();\r
 126 \r
 127     /**\r
 128      * The first child of this node. If there is no such node, this returns \r
 129      * <code>null</code>.\r
 130      */\r
 131     public Node getFirstChild();\r
 132 \r
 133     /**\r
 134      * The last child of this node. If there is no such node, this returns \r
 135      * <code>null</code>.\r
 136      */\r
 137     public Node getLastChild();\r
 138 \r
 139     /**\r
 140      * The node immediately preceding this node. If there is no such node, \r
 141      * this returns <code>null</code>.\r
 142      */\r
 143     public Node getPreviousSibling();\r
 144 \r
 145     /**\r
 146      * The node immediately following this node. If there is no such node, \r
 147      * this returns <code>null</code>.\r
 148      */\r
 149     public Node getNextSibling();\r
 150 \r
 151     /**\r
 152      * A <code>NamedNodeMap</code> containing the attributes of this node (if \r
 153      * it is an <code>Element</code>) or <code>null</code> otherwise. \r
 154      */\r
 155     public NamedNodeMap getAttributes();\r
 156 \r
 157     /**\r
 158      * The <code>Document</code> object associated with this node. This is \r
 159      * also the <code>Document</code> object used to create new nodes. When \r
 160      * this node is a <code>Document</code> or a <code>DocumentType</code> \r
 161      * which is not used with any <code>Document</code> yet, this is \r
 162      * <code>null</code>.\r
 163      * @version DOM Level 2\r
 164      */\r
 165     public Document getOwnerDocument();\r
 166 \r
 167     /**\r
 168      * Inserts the node <code>newChild</code> before the existing child node \r
 169      * <code>refChild</code>. If <code>refChild</code> is <code>null</code>, \r
 170      * insert <code>newChild</code> at the end of the list of children.\r
 171      * <br>If <code>newChild</code> is a <code>DocumentFragment</code> object, \r
 172      * all of its children are inserted, in the same order, before \r
 173      * <code>refChild</code>. If the <code>newChild</code> is already in the \r
 174      * tree, it is first removed.\r
 175      * @param newChildThe node to insert.\r
 176      * @param refChildThe reference node, i.e., the node before which the new \r
 177      *   node must be inserted.\r
 178      * @return The node being inserted.\r
 179      * @exception DOMException\r
 180      *   HIERARCHY_REQUEST_ERR: Raised if this node is of a type that does not \r
 181      *   allow children of the type of the <code>newChild</code> node, or if \r
 182      *   the node to insert is one of this node's ancestors.\r
 183      *   <br>WRONG_DOCUMENT_ERR: Raised if <code>newChild</code> was created \r
 184      *   from a different document than the one that created this node.\r
 185      *   <br>NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly or \r
 186      *   if the parent of the node being inserted is readonly.\r
 187      *   <br>NOT_FOUND_ERR: Raised if <code>refChild</code> is not a child of \r
 188      *   this node.\r
 189      */\r
 190     public Node insertBefore(Node newChild, \r
 191                              Node refChild)\r
 192                              throws DOMException;\r
 193 \r
 194     /**\r
 195      * Replaces the child node <code>oldChild</code> with <code>newChild</code>\r
 196      *  in the list of children, and returns the <code>oldChild</code> node.\r
 197      * <br>If <code>newChild</code> is a <code>DocumentFragment</code> object, \r
 198      * <code>oldChild</code> is replaced by all of the \r
 199      * <code>DocumentFragment</code> children, which are inserted in the \r
 200      * same order. If the <code>newChild</code> is already in the tree, it \r
 201      * is first removed.\r
 202      * @param newChildThe new node to put in the child list.\r
 203      * @param oldChildThe node being replaced in the list.\r
 204      * @return The node replaced.\r
 205      * @exception DOMException\r
 206      *   HIERARCHY_REQUEST_ERR: Raised if this node is of a type that does not \r
 207      *   allow children of the type of the <code>newChild</code> node, or if \r
 208      *   the node to put in is one of this node's ancestors.\r
 209      *   <br>WRONG_DOCUMENT_ERR: Raised if <code>newChild</code> was created \r
 210      *   from a different document than the one that created this node.\r
 211      *   <br>NO_MODIFICATION_ALLOWED_ERR: Raised if this node or the parent of \r
 212      *   the new node is readonly.\r
 213      *   <br>NOT_FOUND_ERR: Raised if <code>oldChild</code> is not a child of \r
 214      *   this node.\r
 215      */\r
 216     public Node replaceChild(Node newChild, \r
 217                              Node oldChild)\r
 218                              throws DOMException;\r
 219 \r
 220     /**\r
 221      * Removes the child node indicated by <code>oldChild</code> from the list \r
 222      * of children, and returns it.\r
 223      * @param oldChildThe node being removed.\r
 224      * @return The node removed.\r
 225      * @exception DOMException\r
 226      *   NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.\r
 227      *   <br>NOT_FOUND_ERR: Raised if <code>oldChild</code> is not a child of \r
 228      *   this node.\r
 229      */\r
 230     public Node removeChild(Node oldChild)\r
 231                             throws DOMException;\r
 232 \r
 233     /**\r
 234      * Adds the node <code>newChild</code> to the end of the list of children \r
 235      * of this node. If the <code>newChild</code> is already in the tree, it \r
 236      * is first removed.\r
 237      * @param newChildThe node to add.If it is a <code>DocumentFragment</code>\r
 238      *    object, the entire contents of the document fragment are moved \r
 239      *   into the child list of this node\r
 240      * @return The node added.\r
 241      * @exception DOMException\r
 242      *   HIERARCHY_REQUEST_ERR: Raised if this node is of a type that does not \r
 243      *   allow children of the type of the <code>newChild</code> node, or if \r
 244      *   the node to append is one of this node's ancestors.\r
 245      *   <br>WRONG_DOCUMENT_ERR: Raised if <code>newChild</code> was created \r
 246      *   from a different document than the one that created this node.\r
 247      *   <br>NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.\r
 248      */\r
 249     public Node appendChild(Node newChild)\r
 250                             throws DOMException;\r
 251 \r
 252     /**\r
 253      * Returns whether this node has any children.\r
 254      * @return  <code>true</code> if this node has any children, \r
 255      *   <code>false</code> otherwise.\r
 256      */\r
 257     public boolean hasChildNodes();\r
 258 \r
 259     /**\r
 260      * Returns a duplicate of this node, i.e., serves as a generic copy \r
 261      * constructor for nodes. The duplicate node has no parent; (\r
 262      * <code>parentNode</code> is <code>null</code>.).\r
 263      * <br>Cloning an <code>Element</code> copies all attributes and their \r
 264      * values, including those generated by the XML processor to represent \r
 265      * defaulted attributes, but this method does not copy any text it \r
 266      * contains unless it is a deep clone, since the text is contained in a \r
 267      * child <code>Text</code> node. Cloning an <code>Attribute</code> \r
 268      * directly, as opposed to be cloned as part of an <code>Element</code> \r
 269      * cloning operation, returns a specified attribute (\r
 270      * <code>specified</code> is <code>true</code>). Cloning any other type \r
 271      * of node simply returns a copy of this node.\r
 272      * <br>Note that cloning an immutable subtree results in a mutable copy, \r
 273      * but the children of an <code>EntityReference</code> clone are readonly\r
 274      * . In addition, clones of unspecified <code>Attr</code> nodes are \r
 275      * specified. And, cloning <code>Document</code>, \r
 276      * <code>DocumentType</code>, <code>Entity</code>, and \r
 277      * <code>Notation</code> nodes is implementation dependent.\r
 278      * @param deepIf <code>true</code>, recursively clone the subtree under \r
 279      *   the specified node; if <code>false</code>, clone only the node \r
 280      *   itself (and its attributes, if it is an <code>Element</code>). \r
 281      * @return The duplicate node.\r
 282      */\r
 283     public Node cloneNode(boolean deep);\r
 284 \r
 285     /**\r
 286      * Puts all <code>Text</code> nodes in the full depth of the sub-tree \r
 287      * underneath this <code>Node</code>, including attribute nodes, into a \r
 288      * "normal" form where only structure (e.g., elements, comments, \r
 289      * processing instructions, CDATA sections, and entity references) \r
 290      * separates <code>Text</code> nodes, i.e., there are neither adjacent \r
 291      * <code>Text</code> nodes nor empty <code>Text</code> nodes. This can \r
 292      * be used to ensure that the DOM view of a document is the same as if \r
 293      * it were saved and re-loaded, and is useful when operations (such as \r
 294      * XPointer  lookups) that depend on a particular document tree \r
 295      * structure are to be used.In cases where the document contains \r
 296      * <code>CDATASections</code>, the normalize operation alone may not be \r
 297      * sufficient, since XPointers do not differentiate between \r
 298      * <code>Text</code> nodes and <code>CDATASection</code> nodes.\r
 299      * @version DOM Level 2\r
 300      */\r
 301     public void normalize();\r
 302 \r
 303     /**\r
 304      * Tests whether the DOM implementation implements a specific feature and \r
 305      * that feature is supported by this node.\r
 306      * @param featureThe name of the feature to test. This is the same name \r
 307      *   which can be passed to the method <code>hasFeature</code> on \r
 308      *   <code>DOMImplementation</code>.\r
 309      * @param versionThis is the version number of the feature to test. In \r
 310      *   Level 2, version 1, this is the string "2.0". If the version is not \r
 311      *   specified, supporting any version of the feature will cause the \r
 312      *   method to return <code>true</code>.\r
 313      * @return Returns <code>true</code> if the specified feature is \r
 314      *   supported on this node, <code>false</code> otherwise.\r
 315      * @since DOM Level 2\r
 316      */\r
 317     public boolean isSupported(String feature, \r
 318                                String version);\r
 319 \r
 320     /**\r
 321      * The namespace URI of this node, or <code>null</code> if it is \r
 322      * unspecified.\r
 323      * <br>This is not a computed value that is the result of a namespace \r
 324      * lookup based on an examination of the namespace declarations in \r
 325      * scope. It is merely the namespace URI given at creation time.\r
 326      * <br>For nodes of any type other than <code>ELEMENT_NODE</code> and \r
 327      * <code>ATTRIBUTE_NODE</code> and nodes created with a DOM Level 1 \r
 328      * method, such as <code>createElement</code> from the \r
 329      * <code>Document</code> interface, this is always <code>null</code>.Per \r
 330      * the Namespaces in XML Specification  an attribute does not inherit \r
 331      * its namespace from the element it is attached to. If an attribute is \r
 332      * not explicitly given a namespace, it simply has no namespace.\r
 333      * @since DOM Level 2\r
 334      */\r
 335     public String getNamespaceURI();\r
 336 \r
 337     /**\r
 338      * The namespace prefix of this node, or <code>null</code> if it is \r
 339      * unspecified.\r
 340      * <br>Note that setting this attribute, when permitted, changes the \r
 341      * <code>nodeName</code> attribute, which holds the qualified name, as \r
 342      * well as the <code>tagName</code> and <code>name</code> attributes of \r
 343      * the <code>Element</code> and <code>Attr</code> interfaces, when \r
 344      * applicable.\r
 345      * <br>Note also that changing the prefix of an attribute that is known to \r
 346      * have a default value, does not make a new attribute with the default \r
 347      * value and the original prefix appear, since the \r
 348      * <code>namespaceURI</code> and <code>localName</code> do not change.\r
 349      * <br>For nodes of any type other than <code>ELEMENT_NODE</code> and \r
 350      * <code>ATTRIBUTE_NODE</code> and nodes created with a DOM Level 1 \r
 351      * method, such as <code>createElement</code> from the \r
 352      * <code>Document</code> interface, this is always <code>null</code>.\r
 353      * @exception DOMException\r
 354      *   INVALID_CHARACTER_ERR: Raised if the specified prefix contains an \r
 355      *   illegal character.\r
 356      *   <br>NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.\r
 357      *   <br>NAMESPACE_ERR: Raised if the specified <code>prefix</code> is \r
 358      *   malformed, if the <code>namespaceURI</code> of this node is \r
 359      *   <code>null</code>, if the specified prefix is "xml" and the \r
 360      *   <code>namespaceURI</code> of this node is different from "\r
 361      *   http://www.w3.org/XML/1998/namespace", if this node is an attribute \r
 362      *   and the specified prefix is "xmlns" and the \r
 363      *   <code>namespaceURI</code> of this node is different from "\r
 364      *   http://www.w3.org/2000/xmlns/", or if this node is an attribute and \r
 365      *   the <code>qualifiedName</code> of this node is "xmlns" .\r
 366      * @since DOM Level 2\r
 367      */\r
 368     public String getPrefix();\r
 369     public void setPrefix(String prefix)\r
 370                                throws DOMException;\r
 371 \r
 372     /**\r
 373      * Returns the local part of the qualified name of this node.\r
 374      * <br>For nodes of any type other than <code>ELEMENT_NODE</code> and \r
 375      * <code>ATTRIBUTE_NODE</code> and nodes created with a DOM Level 1 \r
 376      * method, such as <code>createElement</code> from the \r
 377      * <code>Document</code> interface, this is always <code>null</code>.\r
 378      * @since DOM Level 2\r
 379      */\r
 380     public String getLocalName();\r
 381 \r
 382     /**\r
 383      * Returns whether this node (if it is an element) has any attributes.\r
 384      * @return <code>true</code> if this node has any attributes, \r
 385      *   <code>false</code> otherwise.\r
 386      * @since DOM Level 2\r
 387      */\r
 388     public boolean hasAttributes();\r
 389 \r
 390 }\r