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    }