Node


1   /*
2    * Copyright (c) 2004 World Wide Web Consortium,
3    *
4    * (Massachusetts Institute of Technology, European Research Consortium for
5    * Informatics and Mathematics, Keio University). All Rights Reserved. This
6    * work is distributed under the W3C(r) Software License [1] in the hope that
7    * it will be useful, but WITHOUT ANY WARRANTY; without even the implied
8    * warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
9    *
10   * [1] http://www.w3.org/Consortium/Legal/2002/copyright-software-20021231
11   */
12  
13  package org.w3c.dom;
14  
15  /**
16   * The <code>Node</code> interface is the primary datatype for the entire 
17   * Document Object Model. It represents a single node in the document tree. 
18   * While all objects implementing the <code>Node</code> interface expose 
19   * methods for dealing with children, not all objects implementing the 
20   * <code>Node</code> interface may have children. For example, 
21   * <code>Text</code> nodes may not have children, and adding children to 
22   * such nodes results in a <code>DOMException</code> being raised.
23   * <p>The attributes <code>nodeName</code>, <code>nodeValue</code> and 
24   * <code>attributes</code> are included as a mechanism to get at node 
25   * information without casting down to the specific derived interface. In 
26   * cases where there is no obvious mapping of these attributes for a 
27   * specific <code>nodeType</code> (e.g., <code>nodeValue</code> for an 
28   * <code>Element</code> or <code>attributes</code> for a <code>Comment</code>
29   * ), this returns <code>null</code>. Note that the specialized interfaces 
30   * may contain additional and more convenient mechanisms to get and set the 
31   * relevant information.
32   * <p>The values of <code>nodeName</code>, 
33   * <code>nodeValue</code>, and <code>attributes</code> vary according to the 
34   * node type as follows: 
35   * <table border='1' cellpadding='3'>
36   * <tr>
37   * <th>Interface</th>
38   * <th>nodeName</th>
39   * <th>nodeValue</th>
40   * <th>attributes</th>
41   * </tr>
42   * <tr>
43   * <td valign='top' rowspan='1' colspan='1'>
44   * <code>Attr</code></td>
45   * <td valign='top' rowspan='1' colspan='1'>same as <code>Attr.name</code></td>
46   * <td valign='top' rowspan='1' colspan='1'>same as 
47   * <code>Attr.value</code></td>
48   * <td valign='top' rowspan='1' colspan='1'><code>null</code></td>
49   * </tr>
50   * <tr>
51   * <td valign='top' rowspan='1' colspan='1'><code>CDATASection</code></td>
52   * <td valign='top' rowspan='1' colspan='1'>
53   * <code>"#cdata-section"</code></td>
54   * <td valign='top' rowspan='1' colspan='1'>same as <code>CharacterData.data</code>, the 
55   * content of the CDATA Section</td>
56   * <td valign='top' rowspan='1' colspan='1'><code>null</code></td>
57   * </tr>
58   * <tr>
59   * <td valign='top' rowspan='1' colspan='1'><code>Comment</code></td>
60   * <td valign='top' rowspan='1' colspan='1'>
61   * <code>"#comment"</code></td>
62   * <td valign='top' rowspan='1' colspan='1'>same as <code>CharacterData.data</code>, the 
63   * content of the comment</td>
64   * <td valign='top' rowspan='1' colspan='1'><code>null</code></td>
65   * </tr>
66   * <tr>
67   * <td valign='top' rowspan='1' colspan='1'><code>Document</code></td>
68   * <td valign='top' rowspan='1' colspan='1'>
69   * <code>"#document"</code></td>
70   * <td valign='top' rowspan='1' colspan='1'><code>null</code></td>
71   * <td valign='top' rowspan='1' colspan='1'><code>null</code></td>
72   * </tr>
73   * <tr>
74   * <td valign='top' rowspan='1' colspan='1'>
75   * <code>DocumentFragment</code></td>
76   * <td valign='top' rowspan='1' colspan='1'><code>"#document-fragment"</code></td>
77   * <td valign='top' rowspan='1' colspan='1'>
78   * <code>null</code></td>
79   * <td valign='top' rowspan='1' colspan='1'><code>null</code></td>
80   * </tr>
81   * <tr>
82   * <td valign='top' rowspan='1' colspan='1'><code>DocumentType</code></td>
83   * <td valign='top' rowspan='1' colspan='1'>same as 
84   * <code>DocumentType.name</code></td>
85   * <td valign='top' rowspan='1' colspan='1'><code>null</code></td>
86   * <td valign='top' rowspan='1' colspan='1'><code>null</code></td>
87   * </tr>
88   * <tr>
89   * <td valign='top' rowspan='1' colspan='1'>
90   * <code>Element</code></td>
91   * <td valign='top' rowspan='1' colspan='1'>same as <code>Element.tagName</code></td>
92   * <td valign='top' rowspan='1' colspan='1'><code>null</code></td>
93   * <td valign='top' rowspan='1' colspan='1'>
94   * <code>NamedNodeMap</code></td>
95   * </tr>
96   * <tr>
97   * <td valign='top' rowspan='1' colspan='1'><code>Entity</code></td>
98   * <td valign='top' rowspan='1' colspan='1'>entity name</td>
99   * <td valign='top' rowspan='1' colspan='1'><code>null</code></td>
100  * <td valign='top' rowspan='1' colspan='1'>
101  * <code>null</code></td>
102  * </tr>
103  * <tr>
104  * <td valign='top' rowspan='1' colspan='1'><code>EntityReference</code></td>
105  * <td valign='top' rowspan='1' colspan='1'>name of entity referenced</td>
106  * <td valign='top' rowspan='1' colspan='1'>
107  * <code>null</code></td>
108  * <td valign='top' rowspan='1' colspan='1'><code>null</code></td>
109  * </tr>
110  * <tr>
111  * <td valign='top' rowspan='1' colspan='1'><code>Notation</code></td>
112  * <td valign='top' rowspan='1' colspan='1'>notation name</td>
113  * <td valign='top' rowspan='1' colspan='1'>
114  * <code>null</code></td>
115  * <td valign='top' rowspan='1' colspan='1'><code>null</code></td>
116  * </tr>
117  * <tr>
118  * <td valign='top' rowspan='1' colspan='1'><code>ProcessingInstruction</code></td>
119  * <td valign='top' rowspan='1' colspan='1'>same 
120  * as <code>ProcessingInstruction.target</code></td>
121  * <td valign='top' rowspan='1' colspan='1'>same as 
122  * <code>ProcessingInstruction.data</code></td>
123  * <td valign='top' rowspan='1' colspan='1'><code>null</code></td>
124  * </tr>
125  * <tr>
126  * <td valign='top' rowspan='1' colspan='1'><code>Text</code></td>
127  * <td valign='top' rowspan='1' colspan='1'>
128  * <code>"#text"</code></td>
129  * <td valign='top' rowspan='1' colspan='1'>same as <code>CharacterData.data</code>, the content 
130  * of the text node</td>
131  * <td valign='top' rowspan='1' colspan='1'><code>null</code></td>
132  * </tr>
133  * </table> 
134  * <p>See also the <a HREF='http://www.w3.org/TR/2004/REC-DOM-Level-3-Core-20040407'>Document Object Model (DOM) Level 3 Core Specification</a>.
135  */
136 public interface Node {
137     // NodeType
138     /**
139      * The node is an <code>Element</code>.
140      */
141     public static final short ELEMENT_NODE              = 1;
142     /**
143      * The node is an <code>Attr</code>.
144      */
145     public static final short ATTRIBUTE_NODE            = 2;
146     /**
147      * The node is a <code>Text</code> node.
148      */
149     public static final short TEXT_NODE                 = 3;
150     /**
151      * The node is a <code>CDATASection</code>.
152      */
153     public static final short CDATA_SECTION_NODE        = 4;
154     /**
155      * The node is an <code>EntityReference</code>.
156      */
157     public static final short ENTITY_REFERENCE_NODE     = 5;
158     /**
159      * The node is an <code>Entity</code>.
160      */
161     public static final short ENTITY_NODE               = 6;
162     /**
163      * The node is a <code>ProcessingInstruction</code>.
164      */
165     public static final short PROCESSING_INSTRUCTION_NODE = 7;
166     /**
167      * The node is a <code>Comment</code>.
168      */
169     public static final short COMMENT_NODE              = 8;
170     /**
171      * The node is a <code>Document</code>.
172      */
173     public static final short DOCUMENT_NODE             = 9;
174     /**
175      * The node is a <code>DocumentType</code>.
176      */
177     public static final short DOCUMENT_TYPE_NODE        = 10;
178     /**
179      * The node is a <code>DocumentFragment</code>.
180      */
181     public static final short DOCUMENT_FRAGMENT_NODE    = 11;
182     /**
183      * The node is a <code>Notation</code>.
184      */
185     public static final short NOTATION_NODE             = 12;
186 
187     /**
188      * The name of this node, depending on its type; see the table above.
189      */
190     public String   getNodeName();
191 
192     /**
193      * The value of this node, depending on its type; see the table above. 
194      * When it is defined to be <code>null</code>, setting it has no effect, 
195      * including if the node is read-only.
196      * @exception DOMException
197      *   DOMSTRING_SIZE_ERR: Raised when it would return more characters than 
198      *   fit in a <code>DOMString</code> variable on the implementation 
199      *   platform.
200      */
201     public String   getNodeValue()
202                               throws DOMException  ;
203     /**
204      * The value of this node, depending on its type; see the table above. 
205      * When it is defined to be <code>null</code>, setting it has no effect, 
206      * including if the node is read-only.
207      * @exception DOMException
208      *   NO_MODIFICATION_ALLOWED_ERR: Raised when the node is readonly and if 
209      *   it is not defined to be <code>null</code>.
210      */
211     public void setNodeValue(String   nodeValue)
212                               throws DOMException  ;
213 
214     /**
215      * A code representing the type of the underlying object, as defined above.
216      */
217     public short getNodeType();
218 
219     /**
220      * The parent of this node. All nodes, except <code>Attr</code>, 
221      * <code>Document</code>, <code>DocumentFragment</code>, 
222      * <code>Entity</code>, and <code>Notation</code> may have a parent. 
223      * However, if a node has just been created and not yet added to the 
224      * tree, or if it has been removed from the tree, this is 
225      * <code>null</code>. 
226      */
227     public Node   getParentNode();
228 
229     /**
230      * A <code>NodeList</code> that contains all children of this node. If 
231      * there are no children, this is a <code>NodeList</code> containing no 
232      * nodes.
233      */
234     public NodeList   getChildNodes();
235 
236     /**
237      * The first child of this node. If there is no such node, this returns 
238      * <code>null</code>.
239      */
240     public Node   getFirstChild();
241 
242     /**
243      * The last child of this node. If there is no such node, this returns 
244      * <code>null</code>.
245      */
246     public Node   getLastChild();
247 
248     /**
249      * The node immediately preceding this node. If there is no such node, 
250      * this returns <code>null</code>.
251      */
252     public Node   getPreviousSibling();
253 
254     /**
255      * The node immediately following this node. If there is no such node, 
256      * this returns <code>null</code>.
257      */
258     public Node   getNextSibling();
259 
260     /**
261      * A <code>NamedNodeMap</code> containing the attributes of this node (if 
262      * it is an <code>Element</code>) or <code>null</code> otherwise.
263      */
264     public NamedNodeMap   getAttributes();
265 
266     /**
267      * The <code>Document</code> object associated with this node. This is 
268      * also the <code>Document</code> object used to create new nodes. When 
269      * this node is a <code>Document</code> or a <code>DocumentType</code> 
270      * which is not used with any <code>Document</code> yet, this is 
271      * <code>null</code>.
272      * @version DOM Level 2
273      */
274     public Document   getOwnerDocument();
275 
276     /**
277      * Inserts the node <code>newChild</code> before the existing child node 
278      * <code>refChild</code>. If <code>refChild</code> is <code>null</code>, 
279      * insert <code>newChild</code> at the end of the list of children.
280      * <br>If <code>newChild</code> is a <code>DocumentFragment</code> object, 
281      * all of its children are inserted, in the same order, before 
282      * <code>refChild</code>. If the <code>newChild</code> is already in the 
283      * tree, it is first removed.
284      * <p ><b>Note:</b>  Inserting a node before itself is implementation 
285      * dependent. 
286      * @param newChild The node to insert.
287      * @param refChild The reference node, i.e., the node before which the 
288      *   new node must be inserted.
289      * @return The node being inserted.
290      * @exception DOMException
291      *   HIERARCHY_REQUEST_ERR: Raised if this node is of a type that does not 
292      *   allow children of the type of the <code>newChild</code> node, or if 
293      *   the node to insert is one of this node's ancestors or this node 
294      *   itself, or if this node is of type <code>Document</code> and the 
295      *   DOM application attempts to insert a second 
296      *   <code>DocumentType</code> or <code>Element</code> node.
297      *   <br>WRONG_DOCUMENT_ERR: Raised if <code>newChild</code> was created 
298      *   from a different document than the one that created this node.
299      *   <br>NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly or 
300      *   if the parent of the node being inserted is readonly.
301      *   <br>NOT_FOUND_ERR: Raised if <code>refChild</code> is not a child of 
302      *   this node.
303      *   <br>NOT_SUPPORTED_ERR: if this node is of type <code>Document</code>, 
304      *   this exception might be raised if the DOM implementation doesn't 
305      *   support the insertion of a <code>DocumentType</code> or 
306      *   <code>Element</code> node.
307      * @version DOM Level 3
308      */
309     public Node   insertBefore(Node   newChild, 
310                              Node   refChild)
311                              throws DOMException  ;
312 
313     /**
314      * Replaces the child node <code>oldChild</code> with <code>newChild</code>
315      *  in the list of children, and returns the <code>oldChild</code> node.
316      * <br>If <code>newChild</code> is a <code>DocumentFragment</code> object, 
317      * <code>oldChild</code> is replaced by all of the 
318      * <code>DocumentFragment</code> children, which are inserted in the 
319      * same order. If the <code>newChild</code> is already in the tree, it 
320      * is first removed.
321      * <p ><b>Note:</b>  Replacing a node with itself is implementation 
322      * dependent. 
323      * @param newChild The new node to put in the child list.
324      * @param oldChild The node being replaced in the list.
325      * @return The node replaced.
326      * @exception DOMException
327      *   HIERARCHY_REQUEST_ERR: Raised if this node is of a type that does not 
328      *   allow children of the type of the <code>newChild</code> node, or if 
329      *   the node to put in is one of this node's ancestors or this node 
330      *   itself, or if this node is of type <code>Document</code> and the 
331      *   result of the replacement operation would add a second 
332      *   <code>DocumentType</code> or <code>Element</code> on the 
333      *   <code>Document</code> node.
334      *   <br>WRONG_DOCUMENT_ERR: Raised if <code>newChild</code> was created 
335      *   from a different document than the one that created this node.
336      *   <br>NO_MODIFICATION_ALLOWED_ERR: Raised if this node or the parent of 
337      *   the new node is readonly.
338      *   <br>NOT_FOUND_ERR: Raised if <code>oldChild</code> is not a child of 
339      *   this node.
340      *   <br>NOT_SUPPORTED_ERR: if this node is of type <code>Document</code>, 
341      *   this exception might be raised if the DOM implementation doesn't 
342      *   support the replacement of the <code>DocumentType</code> child or 
343      *   <code>Element</code> child.
344      * @version DOM Level 3
345      */
346     public Node   replaceChild(Node   newChild, 
347                              Node   oldChild)
348                              throws DOMException  ;
349 
350     /**
351      * Removes the child node indicated by <code>oldChild</code> from the list 
352      * of children, and returns it.
353      * @param oldChild The node being removed.
354      * @return The node removed.
355      * @exception DOMException
356      *   NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
357      *   <br>NOT_FOUND_ERR: Raised if <code>oldChild</code> is not a child of 
358      *   this node.
359      *   <br>NOT_SUPPORTED_ERR: if this node is of type <code>Document</code>, 
360      *   this exception might be raised if the DOM implementation doesn't 
361      *   support the removal of the <code>DocumentType</code> child or the 
362      *   <code>Element</code> child.
363      * @version DOM Level 3
364      */
365     public Node   removeChild(Node   oldChild)
366                             throws DOMException  ;
367 
368     /**
369      * Adds the node <code>newChild</code> to the end of the list of children 
370      * of this node. If the <code>newChild</code> is already in the tree, it 
371      * is first removed.
372      * @param newChild The node to add.If it is a 
373      *   <code>DocumentFragment</code> object, the entire contents of the 
374      *   document fragment are moved into the child list of this node
375      * @return The node added.
376      * @exception DOMException
377      *   HIERARCHY_REQUEST_ERR: Raised if this node is of a type that does not 
378      *   allow children of the type of the <code>newChild</code> node, or if 
379      *   the node to append is one of this node's ancestors or this node 
380      *   itself, or if this node is of type <code>Document</code> and the 
381      *   DOM application attempts to append a second 
382      *   <code>DocumentType</code> or <code>Element</code> node.
383      *   <br>WRONG_DOCUMENT_ERR: Raised if <code>newChild</code> was created 
384      *   from a different document than the one that created this node.
385      *   <br>NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly or 
386      *   if the previous parent of the node being inserted is readonly.
387      *   <br>NOT_SUPPORTED_ERR: if the <code>newChild</code> node is a child 
388      *   of the <code>Document</code> node, this exception might be raised 
389      *   if the DOM implementation doesn't support the removal of the 
390      *   <code>DocumentType</code> child or <code>Element</code> child.
391      * @version DOM Level 3
392      */
393     public Node   appendChild(Node   newChild)
394                             throws DOMException  ;
395 
396     /**
397      * Returns whether this node has any children.
398      * @return Returns <code>true</code> if this node has any children, 
399      *   <code>false</code> otherwise.
400      */
401     public boolean hasChildNodes();
402 
403     /**
404      * Returns a duplicate of this node, i.e., serves as a generic copy 
405      * constructor for nodes. The duplicate node has no parent (
406      * <code>parentNode</code> is <code>null</code>) and no user data. User 
407      * data associated to the imported node is not carried over. However, if 
408      * any <code>UserDataHandlers</code> has been specified along with the 
409      * associated data these handlers will be called with the appropriate 
410      * parameters before this method returns.
411      * <br>Cloning an <code>Element</code> copies all attributes and their 
412      * values, including those generated by the XML processor to represent 
413      * defaulted attributes, but this method does not copy any children it 
414      * contains unless it is a deep clone. This includes text contained in 
415      * an the <code>Element</code> since the text is contained in a child 
416      * <code>Text</code> node. Cloning an <code>Attr</code> directly, as 
417      * opposed to be cloned as part of an <code>Element</code> cloning 
418      * operation, returns a specified attribute (<code>specified</code> is 
419      * <code>true</code>). Cloning an <code>Attr</code> always clones its 
420      * children, since they represent its value, no matter whether this is a 
421      * deep clone or not. Cloning an <code>EntityReference</code> 
422      * automatically constructs its subtree if a corresponding 
423      * <code>Entity</code> is available, no matter whether this is a deep 
424      * clone or not. Cloning any other type of node simply returns a copy of 
425      * this node.
426      * <br>Note that cloning an immutable subtree results in a mutable copy, 
427      * but the children of an <code>EntityReference</code> clone are readonly
428      * . In addition, clones of unspecified <code>Attr</code> nodes are 
429      * specified. And, cloning <code>Document</code>, 
430      * <code>DocumentType</code>, <code>Entity</code>, and 
431      * <code>Notation</code> nodes is implementation dependent.
432      * @param deep If <code>true</code>, recursively clone the subtree under 
433      *   the specified node; if <code>false</code>, clone only the node 
434      *   itself (and its attributes, if it is an <code>Element</code>).
435      * @return The duplicate node.
436      */
437     public Node   cloneNode(boolean deep);
438 
439     /**
440      *  Puts all <code>Text</code> nodes in the full depth of the sub-tree 
441      * underneath this <code>Node</code>, including attribute nodes, into a 
442      * "normal" form where only structure (e.g., elements, comments, 
443      * processing instructions, CDATA sections, and entity references) 
444      * separates <code>Text</code> nodes, i.e., there are neither adjacent 
445      * <code>Text</code> nodes nor empty <code>Text</code> nodes. This can 
446      * be used to ensure that the DOM view of a document is the same as if 
447      * it were saved and re-loaded, and is useful when operations (such as 
448      * XPointer [<a HREF='http://www.w3.org/TR/2003/REC-xptr-framework-20030325/'>XPointer</a>]
449      *  lookups) that depend on a particular document tree structure are to 
450      * be used. If the parameter "normalize-characters" of the 
451      * <code>DOMConfiguration</code> object attached to the 
452      * <code>Node.ownerDocument</code> is <code>true</code>, this method 
453      * will also fully normalize the characters of the <code>Text</code> 
454      * nodes. 
455      * <p ><b>Note:</b> In cases where the document contains 
456      * <code>CDATASections</code>, the normalize operation alone may not be 
457      * sufficient, since XPointers do not differentiate between 
458      * <code>Text</code> nodes and <code>CDATASection</code> nodes.
459      * @version DOM Level 3
460      */
461     public void normalize();
462 
463     /**
464      *  Tests whether the DOM implementation implements a specific feature and 
465      * that feature is supported by this node, as specified in . 
466      * @param feature  The name of the feature to test. 
467      * @param version  This is the version number of the feature to test. 
468      * @return Returns <code>true</code> if the specified feature is 
469      *   supported on this node, <code>false</code> otherwise.
470      * @since DOM Level 2
471      */
472     public boolean isSupported(String   feature, 
473                                String   version);
474 
475     /**
476      * The namespace URI of this node, or <code>null</code> if it is 
477      * unspecified (see ).
478      * <br>This is not a computed value that is the result of a namespace 
479      * lookup based on an examination of the namespace declarations in 
480      * scope. It is merely the namespace URI given at creation time.
481      * <br>For nodes of any type other than <code>ELEMENT_NODE</code> and 
482      * <code>ATTRIBUTE_NODE</code> and nodes created with a DOM Level 1 
483      * method, such as <code>Document.createElement()</code>, this is always 
484      * <code>null</code>.
485      * <p ><b>Note:</b> Per the <em>Namespaces in XML</em> Specification [<a HREF='http://www.w3.org/TR/1999/REC-xml-names-19990114/'>XML Namespaces</a>]
486      *  an attribute does not inherit its namespace from the element it is 
487      * attached to. If an attribute is not explicitly given a namespace, it 
488      * simply has no namespace.
489      * @since DOM Level 2
490      */
491     public String   getNamespaceURI();
492 
493     /**
494      * The namespace prefix of this node, or <code>null</code> if it is 
495      * unspecified. When it is defined to be <code>null</code>, setting it 
496      * has no effect, including if the node is read-only.
497      * <br>Note that setting this attribute, when permitted, changes the 
498      * <code>nodeName</code> attribute, which holds the qualified name, as 
499      * well as the <code>tagName</code> and <code>name</code> attributes of 
500      * the <code>Element</code> and <code>Attr</code> interfaces, when 
501      * applicable.
502      * <br>Setting the prefix to <code>null</code> makes it unspecified, 
503      * setting it to an empty string is implementation dependent.
504      * <br>Note also that changing the prefix of an attribute that is known to 
505      * have a default value, does not make a new attribute with the default 
506      * value and the original prefix appear, since the 
507      * <code>namespaceURI</code> and <code>localName</code> do not change.
508      * <br>For nodes of any type other than <code>ELEMENT_NODE</code> and 
509      * <code>ATTRIBUTE_NODE</code> and nodes created with a DOM Level 1 
510      * method, such as <code>createElement</code> from the 
511      * <code>Document</code> interface, this is always <code>null</code>.
512      * @since DOM Level 2
513      */
514     public String   getPrefix();
515     /**
516      * The namespace prefix of this node, or <code>null</code> if it is 
517      * unspecified. When it is defined to be <code>null</code>, setting it 
518      * has no effect, including if the node is read-only.
519      * <br>Note that setting this attribute, when permitted, changes the 
520      * <code>nodeName</code> attribute, which holds the qualified name, as 
521      * well as the <code>tagName</code> and <code>name</code> attributes of 
522      * the <code>Element</code> and <code>Attr</code> interfaces, when 
523      * applicable.
524      * <br>Setting the prefix to <code>null</code> makes it unspecified, 
525      * setting it to an empty string is implementation dependent.
526      * <br>Note also that changing the prefix of an attribute that is known to 
527      * have a default value, does not make a new attribute with the default 
528      * value and the original prefix appear, since the 
529      * <code>namespaceURI</code> and <code>localName</code> do not change.
530      * <br>For nodes of any type other than <code>ELEMENT_NODE</code> and 
531      * <code>ATTRIBUTE_NODE</code> and nodes created with a DOM Level 1 
532      * method, such as <code>createElement</code> from the 
533      * <code>Document</code> interface, this is always <code>null</code>.
534      * @exception DOMException
535      *   INVALID_CHARACTER_ERR: Raised if the specified prefix contains an 
536      *   illegal character according to the XML version in use specified in 
537      *   the <code>Document.xmlVersion</code> attribute.
538      *   <br>NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
539      *   <br>NAMESPACE_ERR: Raised if the specified <code>prefix</code> is 
540      *   malformed per the Namespaces in XML specification, if the 
541      *   <code>namespaceURI</code> of this node is <code>null</code>, if the 
542      *   specified prefix is "xml" and the <code>namespaceURI</code> of this 
543      *   node is different from "<a HREF='http://www.w3.org/XML/1998/namespace'>
544      *   http://www.w3.org/XML/1998/namespace</a>", if this node is an attribute and the specified prefix is "xmlns" and 
545      *   the <code>namespaceURI</code> of this node is different from "<a HREF='http://www.w3.org/2000/xmlns/'>http://www.w3.org/2000/xmlns/</a>", or if this node is an attribute and the <code>qualifiedName</code> of 
546      *   this node is "xmlns" [<a HREF='http://www.w3.org/TR/1999/REC-xml-names-19990114/'>XML Namespaces</a>]
547      *   .
548      * @since DOM Level 2
549      */
550     public void setPrefix(String   prefix)
551                                throws DOMException  ;
552 
553     /**
554      * Returns the local part of the qualified name of this node.
555      * <br>For nodes of any type other than <code>ELEMENT_NODE</code> and 
556      * <code>ATTRIBUTE_NODE</code> and nodes created with a DOM Level 1 
557      * method, such as <code>Document.createElement()</code>, this is always 
558      * <code>null</code>.
559      * @since DOM Level 2
560      */
561     public String   getLocalName();
562 
563     /**
564      * Returns whether this node (if it is an element) has any attributes.
565      * @return Returns <code>true</code> if this node has any attributes, 
566      *   <code>false</code> otherwise.
567      * @since DOM Level 2
568      */
569     public boolean hasAttributes();
570 
571     /**
572      * The absolute base URI of this node or <code>null</code> if the 
573      * implementation wasn't able to obtain an absolute URI. This value is 
574      * computed as described in . However, when the <code>Document</code> 
575      * supports the feature "HTML" [<a HREF='http://www.w3.org/TR/2003/REC-DOM-Level-2-HTML-20030109'>DOM Level 2 HTML</a>]
576      * , the base URI is computed using first the value of the href 
577      * attribute of the HTML BASE element if any, and the value of the 
578      * <code>documentURI</code> attribute from the <code>Document</code> 
579      * interface otherwise.
580      * @since DOM Level 3
581      */
582     public String   getBaseURI();
583 
584     // DocumentPosition
585     /**
586      * The two nodes are disconnected. Order between disconnected nodes is 
587      * always implementation-specific.
588      */
589     public static final short DOCUMENT_POSITION_DISCONNECTED = 0x01;
590     /**
591      * The second node precedes the reference node.
592      */
593     public static final short DOCUMENT_POSITION_PRECEDING = 0x02;
594     /**
595      * The node follows the reference node.
596      */
597     public static final short DOCUMENT_POSITION_FOLLOWING = 0x04;
598     /**
599      * The node contains the reference node. A node which contains is always 
600      * preceding, too.
601      */
602     public static final short DOCUMENT_POSITION_CONTAINS = 0x08;
603     /**
604      * The node is contained by the reference node. A node which is contained 
605      * is always following, too.
606      */
607     public static final short DOCUMENT_POSITION_CONTAINED_BY = 0x10;
608     /**
609      * The determination of preceding versus following is 
610      * implementation-specific.
611      */
612     public static final short DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC = 0x20;
613 
614     /**
615      * Compares the reference node, i.e. the node on which this method is 
616      * being called, with a node, i.e. the one passed as a parameter, with 
617      * regard to their position in the document and according to the 
618      * document order.
619      * @param other The node to compare against the reference node.
620      * @return Returns how the node is positioned relatively to the reference 
621      *   node.
622      * @exception DOMException
623      *   NOT_SUPPORTED_ERR: when the compared nodes are from different DOM 
624      *   implementations that do not coordinate to return consistent 
625      *   implementation-specific results.
626      * @since DOM Level 3
627      */
628     public short compareDocumentPosition(Node   other)
629                                          throws DOMException  ;
630 
631     /**
632      * This attribute returns the text content of this node and its 
633      * descendants. When it is defined to be <code>null</code>, setting it 
634      * has no effect. On setting, any possible children this node may have 
635      * are removed and, if it the new string is not empty or 
636      * <code>null</code>, replaced by a single <code>Text</code> node 
637      * containing the string this attribute is set to. 
638      * <br> On getting, no serialization is performed, the returned string 
639      * does not contain any markup. No whitespace normalization is performed 
640      * and the returned string does not contain the white spaces in element 
641      * content (see the attribute 
642      * <code>Text.isElementContentWhitespace</code>). Similarly, on setting, 
643      * no parsing is performed either, the input string is taken as pure 
644      * textual content. 
645      * <br>The string returned is made of the text content of this node 
646      * depending on its type, as defined below: 
647      * <table border='1' cellpadding='3'>
648      * <tr>
649      * <th>Node type</th>
650      * <th>Content</th>
651      * </tr>
652      * <tr>
653      * <td valign='top' rowspan='1' colspan='1'>
654      * ELEMENT_NODE, ATTRIBUTE_NODE, ENTITY_NODE, ENTITY_REFERENCE_NODE, 
655      * DOCUMENT_FRAGMENT_NODE</td>
656      * <td valign='top' rowspan='1' colspan='1'>concatenation of the <code>textContent</code> 
657      * attribute value of every child node, excluding COMMENT_NODE and 
658      * PROCESSING_INSTRUCTION_NODE nodes. This is the empty string if the 
659      * node has no children.</td>
660      * </tr>
661      * <tr>
662      * <td valign='top' rowspan='1' colspan='1'>TEXT_NODE, CDATA_SECTION_NODE, COMMENT_NODE, 
663      * PROCESSING_INSTRUCTION_NODE</td>
664      * <td valign='top' rowspan='1' colspan='1'><code>nodeValue</code></td>
665      * </tr>
666      * <tr>
667      * <td valign='top' rowspan='1' colspan='1'>DOCUMENT_NODE, 
668      * DOCUMENT_TYPE_NODE, NOTATION_NODE</td>
669      * <td valign='top' rowspan='1' colspan='1'><em>null</em></td>
670      * </tr>
671      * </table>
672      * @exception DOMException
673      *   DOMSTRING_SIZE_ERR: Raised when it would return more characters than 
674      *   fit in a <code>DOMString</code> variable on the implementation 
675      *   platform.
676      * @since DOM Level 3
677      */
678     public String   getTextContent()
679                                          throws DOMException  ;
680     /**
681      * This attribute returns the text content of this node and its 
682      * descendants. When it is defined to be <code>null</code>, setting it 
683      * has no effect. On setting, any possible children this node may have 
684      * are removed and, if it the new string is not empty or 
685      * <code>null</code>, replaced by a single <code>Text</code> node 
686      * containing the string this attribute is set to. 
687      * <br> On getting, no serialization is performed, the returned string 
688      * does not contain any markup. No whitespace normalization is performed 
689      * and the returned string does not contain the white spaces in element 
690      * content (see the attribute 
691      * <code>Text.isElementContentWhitespace</code>). Similarly, on setting, 
692      * no parsing is performed either, the input string is taken as pure 
693      * textual content. 
694      * <br>The string returned is made of the text content of this node 
695      * depending on its type, as defined below: 
696      * <table border='1' cellpadding='3'>
697      * <tr>
698      * <th>Node type</th>
699      * <th>Content</th>
700      * </tr>
701      * <tr>
702      * <td valign='top' rowspan='1' colspan='1'>
703      * ELEMENT_NODE, ATTRIBUTE_NODE, ENTITY_NODE, ENTITY_REFERENCE_NODE, 
704      * DOCUMENT_FRAGMENT_NODE</td>
705      * <td valign='top' rowspan='1' colspan='1'>concatenation of the <code>textContent</code> 
706      * attribute value of every child node, excluding COMMENT_NODE and 
707      * PROCESSING_INSTRUCTION_NODE nodes. This is the empty string if the 
708      * node has no children.</td>
709      * </tr>
710      * <tr>
711      * <td valign='top' rowspan='1' colspan='1'>TEXT_NODE, CDATA_SECTION_NODE, COMMENT_NODE, 
712      * PROCESSING_INSTRUCTION_NODE</td>
713      * <td valign='top' rowspan='1' colspan='1'><code>nodeValue</code></td>
714      * </tr>
715      * <tr>
716      * <td valign='top' rowspan='1' colspan='1'>DOCUMENT_NODE, 
717      * DOCUMENT_TYPE_NODE, NOTATION_NODE</td>
718      * <td valign='top' rowspan='1' colspan='1'><em>null</em></td>
719      * </tr>
720      * </table>
721      * @exception DOMException
722      *   NO_MODIFICATION_ALLOWED_ERR: Raised when the node is readonly.
723      * @since DOM Level 3
724      */
725     public void setTextContent(String   textContent)
726                                          throws DOMException  ;
727 
728     /**
729      * Returns whether this node is the same node as the given one.
730      * <br>This method provides a way to determine whether two 
731      * <code>Node</code> references returned by the implementation reference 
732      * the same object. When two <code>Node</code> references are references 
733      * to the same object, even if through a proxy, the references may be 
734      * used completely interchangeably, such that all attributes have the 
735      * same values and calling the same DOM method on either reference 
736      * always has exactly the same effect.
737      * @param other The node to test against.
738      * @return Returns <code>true</code> if the nodes are the same, 
739      *   <code>false</code> otherwise.
740      * @since DOM Level 3
741      */
742     public boolean isSameNode(Node   other);
743 
744     /**
745      * Look up the prefix associated to the given namespace URI, starting from 
746      * this node. The default namespace declarations are ignored by this 
747      * method.
748      * <br>See  for details on the algorithm used by this method.
749      * @param namespaceURI The namespace URI to look for.
750      * @return Returns an associated namespace prefix if found or 
751      *   <code>null</code> if none is found. If more than one prefix are 
752      *   associated to the namespace prefix, the returned namespace prefix 
753      *   is implementation dependent.
754      * @since DOM Level 3
755      */
756     public String   lookupPrefix(String   namespaceURI);
757 
758     /**
759      *  This method checks if the specified <code>namespaceURI</code> is the 
760      * default namespace or not. 
761      * @param namespaceURI The namespace URI to look for.
762      * @return Returns <code>true</code> if the specified 
763      *   <code>namespaceURI</code> is the default namespace, 
764      *   <code>false</code> otherwise. 
765      * @since DOM Level 3
766      */
767     public boolean isDefaultNamespace(String   namespaceURI);
768 
769     /**
770      * Look up the namespace URI associated to the given prefix, starting from 
771      * this node.
772      * <br>See  for details on the algorithm used by this method.
773      * @param prefix The prefix to look for. If this parameter is 
774      *   <code>null</code>, the method will return the default namespace URI 
775      *   if any.
776      * @return Returns the associated namespace URI or <code>null</code> if 
777      *   none is found.
778      * @since DOM Level 3
779      */
780     public String   lookupNamespaceURI(String   prefix);
781 
782     /**
783      * Tests whether two nodes are equal.
784      * <br>This method tests for equality of nodes, not sameness (i.e., 
785      * whether the two nodes are references to the same object) which can be 
786      * tested with <code>Node.isSameNode()</code>. All nodes that are the 
787      * same will also be equal, though the reverse may not be true.
788      * <br>Two nodes are equal if and only if the following conditions are 
789      * satisfied: 
790      * <ul>
791      * <li>The two nodes are of the same type.
792      * </li>
793      * <li>The following string 
794      * attributes are equal: <code>nodeName</code>, <code>localName</code>, 
795      * <code>namespaceURI</code>, <code>prefix</code>, <code>nodeValue</code>
796      * . This is: they are both <code>null</code>, or they have the same 
797      * length and are character for character identical.
798      * </li>
799      * <li>The 
800      * <code>attributes</code> <code>NamedNodeMaps</code> are equal. This 
801      * is: they are both <code>null</code>, or they have the same length and 
802      * for each node that exists in one map there is a node that exists in 
803      * the other map and is equal, although not necessarily at the same 
804      * index.
805      * </li>
806      * <li>The <code>childNodes</code> <code>NodeLists</code> are equal. 
807      * This is: they are both <code>null</code>, or they have the same 
808      * length and contain equal nodes at the same index. Note that 
809      * normalization can affect equality; to avoid this, nodes should be 
810      * normalized before being compared.
811      * </li>
812      * </ul> 
813      * <br>For two <code>DocumentType</code> nodes to be equal, the following 
814      * conditions must also be satisfied: 
815      * <ul>
816      * <li>The following string attributes 
817      * are equal: <code>publicId</code>, <code>systemId</code>, 
818      * <code>internalSubset</code>.
819      * </li>
820      * <li>The <code>entities</code> 
821      * <code>NamedNodeMaps</code> are equal.
822      * </li>
823      * <li>The <code>notations</code> 
824      * <code>NamedNodeMaps</code> are equal.
825      * </li>
826      * </ul> 
827      * <br>On the other hand, the following do not affect equality: the 
828      * <code>ownerDocument</code>, <code>baseURI</code>, and 
829      * <code>parentNode</code> attributes, the <code>specified</code> 
830      * attribute for <code>Attr</code> nodes, the <code>schemaTypeInfo</code>
831      *  attribute for <code>Attr</code> and <code>Element</code> nodes, the 
832      * <code>Text.isElementContentWhitespace</code> attribute for 
833      * <code>Text</code> nodes, as well as any user data or event listeners 
834      * registered on the nodes. 
835      * <p ><b>Note:</b>  As a general rule, anything not mentioned in the 
836      * description above is not significant in consideration of equality 
837      * checking. Note that future versions of this specification may take 
838      * into account more attributes and implementations conform to this 
839      * specification are expected to be updated accordingly. 
840      * @param arg The node to compare equality with.
841      * @return Returns <code>true</code> if the nodes are equal, 
842      *   <code>false</code> otherwise.
843      * @since DOM Level 3
844      */
845     public boolean isEqualNode(Node   arg);
846 
847     /**
848      *  This method returns a specialized object which implements the 
849      * specialized APIs of the specified feature and version, as specified 
850      * in . The specialized object may also be obtained by using 
851      * binding-specific casting methods but is not necessarily expected to, 
852      * as discussed in . This method also allow the implementation to 
853      * provide specialized objects which do not support the <code>Node</code>
854      *  interface. 
855      * @param feature  The name of the feature requested. Note that any plus 
856      *   sign "+" prepended to the name of the feature will be ignored since 
857      *   it is not significant in the context of this method. 
858      * @param version  This is the version number of the feature to test. 
859      * @return  Returns an object which implements the specialized APIs of 
860      *   the specified feature and version, if any, or <code>null</code> if 
861      *   there is no object which implements interfaces associated with that 
862      *   feature. If the <code>DOMObject</code> returned by this method 
863      *   implements the <code>Node</code> interface, it must delegate to the 
864      *   primary core <code>Node</code> and not return results inconsistent 
865      *   with the primary core <code>Node</code> such as attributes, 
866      *   childNodes, etc. 
867      * @since DOM Level 3
868      */
869     public Object   getFeature(String   feature, 
870                              String   version);
871 
872     /**
873      * Associate an object to a key on this node. The object can later be 
874      * retrieved from this node by calling <code>getUserData</code> with the 
875      * same key.
876      * @param key The key to associate the object to.
877      * @param data The object to associate to the given key, or 
878      *   <code>null</code> to remove any existing association to that key.
879      * @param handler The handler to associate to that key, or 
880      *   <code>null</code>.
881      * @return Returns the <code>DOMUserData</code> previously associated to 
882      *   the given key on this node, or <code>null</code> if there was none.
883      * @since DOM Level 3
884      */
885     public Object   setUserData(String   key, 
886                               Object   data, 
887                               UserDataHandler   handler);
888 
889     /**
890      * Retrieves the object associated to a key on a this node. The object 
891      * must first have been set to this node by calling 
892      * <code>setUserData</code> with the same key.
893      * @param key The key the object is associated to.
894      * @return Returns the <code>DOMUserData</code> associated to the given 
895      *   key on this node, or <code>null</code> if there was none.
896      * @since DOM Level 3
897      */
898     public Object   getUserData(String   key);
899 
900 }
901
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags