001    /*
002     * Copyright (c) 2004 World Wide Web Consortium,
003     *
004     * (Massachusetts Institute of Technology, European Research Consortium for
005     * Informatics and Mathematics, Keio University). All Rights Reserved. This
006     * work is distributed under the W3C(r) Software License [1] in the hope that
007     * it will be useful, but WITHOUT ANY WARRANTY; without even the implied
008     * warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
009     *
010     * [1] http://www.w3.org/Consortium/Legal/2002/copyright-software-20021231
011     */
012    
013    package org.w3c.dom;
014    
015    /**
016     * The <code>Node</code> interface is the primary datatype for the entire
017     * Document Object Model. It represents a single node in the document tree.
018     * While all objects implementing the <code>Node</code> interface expose
019     * methods for dealing with children, not all objects implementing the
020     * <code>Node</code> interface may have children. For example,
021     * <code>Text</code> nodes may not have children, and adding children to
022     * such nodes results in a <code>DOMException</code> being raised.
023     * <p>The attributes <code>nodeName</code>, <code>nodeValue</code> and
024     * <code>attributes</code> are included as a mechanism to get at node
025     * information without casting down to the specific derived interface. In
026     * cases where there is no obvious mapping of these attributes for a
027     * specific <code>nodeType</code> (e.g., <code>nodeValue</code> for an
028     * <code>Element</code> or <code>attributes</code> for a <code>Comment</code>
029     * ), this returns <code>null</code>. Note that the specialized interfaces
030     * may contain additional and more convenient mechanisms to get and set the
031     * relevant information.
032     * <p>The values of <code>nodeName</code>,
033     * <code>nodeValue</code>, and <code>attributes</code> vary according to the
034     * node type as follows:
035     * <table border='1' cellpadding='3'>
036     * <tr>
037     * <th>Interface</th>
038     * <th>nodeName</th>
039     * <th>nodeValue</th>
040     * <th>attributes</th>
041     * </tr>
042     * <tr>
043     * <td valign='top' rowspan='1' colspan='1'>
044     * <code>Attr</code></td>
045     * <td valign='top' rowspan='1' colspan='1'>same as <code>Attr.name</code></td>
046     * <td valign='top' rowspan='1' colspan='1'>same as
047     * <code>Attr.value</code></td>
048     * <td valign='top' rowspan='1' colspan='1'><code>null</code></td>
049     * </tr>
050     * <tr>
051     * <td valign='top' rowspan='1' colspan='1'><code>CDATASection</code></td>
052     * <td valign='top' rowspan='1' colspan='1'>
053     * <code>"#cdata-section"</code></td>
054     * <td valign='top' rowspan='1' colspan='1'>same as <code>CharacterData.data</code>, the
055     * content of the CDATA Section</td>
056     * <td valign='top' rowspan='1' colspan='1'><code>null</code></td>
057     * </tr>
058     * <tr>
059     * <td valign='top' rowspan='1' colspan='1'><code>Comment</code></td>
060     * <td valign='top' rowspan='1' colspan='1'>
061     * <code>"#comment"</code></td>
062     * <td valign='top' rowspan='1' colspan='1'>same as <code>CharacterData.data</code>, the
063     * content of the comment</td>
064     * <td valign='top' rowspan='1' colspan='1'><code>null</code></td>
065     * </tr>
066     * <tr>
067     * <td valign='top' rowspan='1' colspan='1'><code>Document</code></td>
068     * <td valign='top' rowspan='1' colspan='1'>
069     * <code>"#document"</code></td>
070     * <td valign='top' rowspan='1' colspan='1'><code>null</code></td>
071     * <td valign='top' rowspan='1' colspan='1'><code>null</code></td>
072     * </tr>
073     * <tr>
074     * <td valign='top' rowspan='1' colspan='1'>
075     * <code>DocumentFragment</code></td>
076     * <td valign='top' rowspan='1' colspan='1'><code>"#document-fragment"</code></td>
077     * <td valign='top' rowspan='1' colspan='1'>
078     * <code>null</code></td>
079     * <td valign='top' rowspan='1' colspan='1'><code>null</code></td>
080     * </tr>
081     * <tr>
082     * <td valign='top' rowspan='1' colspan='1'><code>DocumentType</code></td>
083     * <td valign='top' rowspan='1' colspan='1'>same as
084     * <code>DocumentType.name</code></td>
085     * <td valign='top' rowspan='1' colspan='1'><code>null</code></td>
086     * <td valign='top' rowspan='1' colspan='1'><code>null</code></td>
087     * </tr>
088     * <tr>
089     * <td valign='top' rowspan='1' colspan='1'>
090     * <code>Element</code></td>
091     * <td valign='top' rowspan='1' colspan='1'>same as <code>Element.tagName</code></td>
092     * <td valign='top' rowspan='1' colspan='1'><code>null</code></td>
093     * <td valign='top' rowspan='1' colspan='1'>
094     * <code>NamedNodeMap</code></td>
095     * </tr>
096     * <tr>
097     * <td valign='top' rowspan='1' colspan='1'><code>Entity</code></td>
098     * <td valign='top' rowspan='1' colspan='1'>entity name</td>
099     * <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    }