001: /*
002: * Copyright (c) 2000 World Wide Web Consortium,
003: * (Massachusetts Institute of Technology, Institut National de
004: * Recherche en Informatique et en Automatique, Keio University). All
005: * Rights Reserved. This program is distributed under the W3C's Software
006: * Intellectual Property License. This program is distributed in the
007: * hope that it will be useful, but WITHOUT ANY WARRANTY; without even
008: * the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
009: * PURPOSE.
010: * See W3C License http://www.w3.org/Consortium/Legal/ for more details.
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'>
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'>Attr</td>
044: * <td valign='top' rowspan='1' colspan='1'>name of
045: * attribute</td>
046: * <td valign='top' rowspan='1' colspan='1'>value of attribute</td>
047: * <td valign='top' rowspan='1' colspan='1'>null</td>
048: * </tr>
049: * <tr>
050: * <td valign='top' rowspan='1' colspan='1'>CDATASection</td>
051: * <td valign='top' rowspan='1' colspan='1'><code>"#cdata-section"</code></td>
052: * <td valign='top' rowspan='1' colspan='1'>
053: * content of the CDATA Section</td>
054: * <td valign='top' rowspan='1' colspan='1'>null</td>
055: * </tr>
056: * <tr>
057: * <td valign='top' rowspan='1' colspan='1'>Comment</td>
058: * <td valign='top' rowspan='1' colspan='1'><code>"#comment"</code></td>
059: * <td valign='top' rowspan='1' colspan='1'>content of
060: * the comment</td>
061: * <td valign='top' rowspan='1' colspan='1'>null</td>
062: * </tr>
063: * <tr>
064: * <td valign='top' rowspan='1' colspan='1'>Document</td>
065: * <td valign='top' rowspan='1' colspan='1'><code>"#document"</code></td>
066: * <td valign='top' rowspan='1' colspan='1'>null</td>
067: * <td valign='top' rowspan='1' colspan='1'>null</td>
068: * </tr>
069: * <tr>
070: * <td valign='top' rowspan='1' colspan='1'>DocumentFragment</td>
071: * <td valign='top' rowspan='1' colspan='1'>
072: * <code>"#document-fragment"</code></td>
073: * <td valign='top' rowspan='1' colspan='1'>null</td>
074: * <td valign='top' rowspan='1' colspan='1'>null</td>
075: * </tr>
076: * <tr>
077: * <td valign='top' rowspan='1' colspan='1'>DocumentType</td>
078: * <td valign='top' rowspan='1' colspan='1'>document type name</td>
079: * <td valign='top' rowspan='1' colspan='1'>
080: * null</td>
081: * <td valign='top' rowspan='1' colspan='1'>null</td>
082: * </tr>
083: * <tr>
084: * <td valign='top' rowspan='1' colspan='1'>Element</td>
085: * <td valign='top' rowspan='1' colspan='1'>tag name</td>
086: * <td valign='top' rowspan='1' colspan='1'>null</td>
087: * <td valign='top' rowspan='1' colspan='1'>NamedNodeMap</td>
088: * </tr>
089: * <tr>
090: * <td valign='top' rowspan='1' colspan='1'>Entity</td>
091: * <td valign='top' rowspan='1' colspan='1'>entity name</td>
092: * <td valign='top' rowspan='1' colspan='1'>null</td>
093: * <td valign='top' rowspan='1' colspan='1'>null</td>
094: * </tr>
095: * <tr>
096: * <td valign='top' rowspan='1' colspan='1'>
097: * EntityReference</td>
098: * <td valign='top' rowspan='1' colspan='1'>name of entity referenced</td>
099: * <td valign='top' rowspan='1' colspan='1'>null</td>
100: * <td valign='top' rowspan='1' colspan='1'>null</td>
101: * </tr>
102: * <tr>
103: * <td valign='top' rowspan='1' colspan='1'>Notation</td>
104: * <td valign='top' rowspan='1' colspan='1'>notation name</td>
105: * <td valign='top' rowspan='1' colspan='1'>null</td>
106: * <td valign='top' rowspan='1' colspan='1'>
107: * null</td>
108: * </tr>
109: * <tr>
110: * <td valign='top' rowspan='1' colspan='1'>ProcessingInstruction</td>
111: * <td valign='top' rowspan='1' colspan='1'>target</td>
112: * <td valign='top' rowspan='1' colspan='1'>entire content excluding the target</td>
113: * <td valign='top' rowspan='1' colspan='1'>null</td>
114: * </tr>
115: * <tr>
116: * <td valign='top' rowspan='1' colspan='1'>Text</td>
117: * <td valign='top' rowspan='1' colspan='1'>
118: * <code>"#text"</code></td>
119: * <td valign='top' rowspan='1' colspan='1'>content of the text node</td>
120: * <td valign='top' rowspan='1' colspan='1'>null</td>
121: * </tr>
122: * </table>
123: * <p>See also the <a href='http://www.w3.org/TR/2000/REC-DOM-Level-2-Core-20001113'>Document Object Model (DOM) Level 2 Core Specification</a>.
124: */
125: public interface Node {
126: // NodeType
127: /**
128: * The node is an <code>Element</code>.
129: */
130: public static final short ELEMENT_NODE = 1;
131: /**
132: * The node is an <code>Attr</code>.
133: */
134: public static final short ATTRIBUTE_NODE = 2;
135: /**
136: * The node is a <code>Text</code> node.
137: */
138: public static final short TEXT_NODE = 3;
139: /**
140: * The node is a <code>CDATASection</code>.
141: */
142: public static final short CDATA_SECTION_NODE = 4;
143: /**
144: * The node is an <code>EntityReference</code>.
145: */
146: public static final short ENTITY_REFERENCE_NODE = 5;
147: /**
148: * The node is an <code>Entity</code>.
149: */
150: public static final short ENTITY_NODE = 6;
151: /**
152: * The node is a <code>ProcessingInstruction</code>.
153: */
154: public static final short PROCESSING_INSTRUCTION_NODE = 7;
155: /**
156: * The node is a <code>Comment</code>.
157: */
158: public static final short COMMENT_NODE = 8;
159: /**
160: * The node is a <code>Document</code>.
161: */
162: public static final short DOCUMENT_NODE = 9;
163: /**
164: * The node is a <code>DocumentType</code>.
165: */
166: public static final short DOCUMENT_TYPE_NODE = 10;
167: /**
168: * The node is a <code>DocumentFragment</code>.
169: */
170: public static final short DOCUMENT_FRAGMENT_NODE = 11;
171: /**
172: * The node is a <code>Notation</code>.
173: */
174: public static final short NOTATION_NODE = 12;
175:
176: /**
177: * The name of this node, depending on its type; see the table above.
178: */
179: public String getNodeName();
180:
181: /**
182: * The value of this node, depending on its type; see the table above.
183: * When it is defined to be <code>null</code>, setting it has no effect.
184: * @exception DOMException
185: * NO_MODIFICATION_ALLOWED_ERR: Raised when the node is readonly.
186: * @exception DOMException
187: * DOMSTRING_SIZE_ERR: Raised when it would return more characters than
188: * fit in a <code>DOMString</code> variable on the implementation
189: * platform.
190: */
191: public String getNodeValue() throws DOMException;
192:
193: /**
194: * The value of this node, depending on its type; see the table above.
195: * When it is defined to be <code>null</code>, setting it has no effect.
196: * @exception DOMException
197: * NO_MODIFICATION_ALLOWED_ERR: Raised when the node is readonly.
198: * @exception DOMException
199: * DOMSTRING_SIZE_ERR: Raised when it would return more characters than
200: * fit in a <code>DOMString</code> variable on the implementation
201: * platform.
202: */
203: public void setNodeValue(String nodeValue) throws DOMException;
204:
205: /**
206: * A code representing the type of the underlying object, as defined above.
207: */
208: public short getNodeType();
209:
210: /**
211: * The parent of this node. All nodes, except <code>Attr</code>,
212: * <code>Document</code>, <code>DocumentFragment</code>,
213: * <code>Entity</code>, and <code>Notation</code> may have a parent.
214: * However, if a node has just been created and not yet added to the
215: * tree, or if it has been removed from the tree, this is
216: * <code>null</code>.
217: */
218: public Node getParentNode();
219:
220: /**
221: * A <code>NodeList</code> that contains all children of this node. If
222: * there are no children, this is a <code>NodeList</code> containing no
223: * nodes.
224: */
225: public NodeList getChildNodes();
226:
227: /**
228: * The first child of this node. If there is no such node, this returns
229: * <code>null</code>.
230: */
231: public Node getFirstChild();
232:
233: /**
234: * The last child of this node. If there is no such node, this returns
235: * <code>null</code>.
236: */
237: public Node getLastChild();
238:
239: /**
240: * The node immediately preceding this node. If there is no such node,
241: * this returns <code>null</code>.
242: */
243: public Node getPreviousSibling();
244:
245: /**
246: * The node immediately following this node. If there is no such node,
247: * this returns <code>null</code>.
248: */
249: public Node getNextSibling();
250:
251: /**
252: * A <code>NamedNodeMap</code> containing the attributes of this node (if
253: * it is an <code>Element</code>) or <code>null</code> otherwise.
254: */
255: public NamedNodeMap getAttributes();
256:
257: /**
258: * The <code>Document</code> object associated with this node. This is
259: * also the <code>Document</code> object used to create new nodes. When
260: * this node is a <code>Document</code> or a <code>DocumentType</code>
261: * which is not used with any <code>Document</code> yet, this is
262: * <code>null</code>.
263: * @version DOM Level 2
264: */
265: public Document getOwnerDocument();
266:
267: /**
268: * Inserts the node <code>newChild</code> before the existing child node
269: * <code>refChild</code>. If <code>refChild</code> is <code>null</code>,
270: * insert <code>newChild</code> at the end of the list of children.
271: * <br>If <code>newChild</code> is a <code>DocumentFragment</code> object,
272: * all of its children are inserted, in the same order, before
273: * <code>refChild</code>. If the <code>newChild</code> is already in the
274: * tree, it is first removed.
275: * @param newChild The node to insert.
276: * @param refChild The reference node, i.e., the node before which the
277: * new node must be inserted.
278: * @return The node being inserted.
279: * @exception DOMException
280: * HIERARCHY_REQUEST_ERR: Raised if this node is of a type that does not
281: * allow children of the type of the <code>newChild</code> node, or if
282: * the node to insert is one of this node's ancestors or this node
283: * itself.
284: * <br>WRONG_DOCUMENT_ERR: Raised if <code>newChild</code> was created
285: * from a different document than the one that created this node.
286: * <br>NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly or
287: * if the parent of the node being inserted is readonly.
288: * <br>NOT_FOUND_ERR: Raised if <code>refChild</code> is not a child of
289: * this node.
290: */
291: public Node insertBefore(Node newChild, Node refChild)
292: throws DOMException;
293:
294: /**
295: * Replaces the child node <code>oldChild</code> with <code>newChild</code>
296: * in the list of children, and returns the <code>oldChild</code> node.
297: * <br>If <code>newChild</code> is a <code>DocumentFragment</code> object,
298: * <code>oldChild</code> is replaced by all of the
299: * <code>DocumentFragment</code> children, which are inserted in the
300: * same order. If the <code>newChild</code> is already in the tree, it
301: * is first removed.
302: * @param newChild The new node to put in the child list.
303: * @param oldChild The node being replaced in the list.
304: * @return The node replaced.
305: * @exception DOMException
306: * HIERARCHY_REQUEST_ERR: Raised if this node is of a type that does not
307: * allow children of the type of the <code>newChild</code> node, or if
308: * the node to put in is one of this node's ancestors or this node
309: * itself.
310: * <br>WRONG_DOCUMENT_ERR: Raised if <code>newChild</code> was created
311: * from a different document than the one that created this node.
312: * <br>NO_MODIFICATION_ALLOWED_ERR: Raised if this node or the parent of
313: * the new node is readonly.
314: * <br>NOT_FOUND_ERR: Raised if <code>oldChild</code> is not a child of
315: * this node.
316: */
317: public Node replaceChild(Node newChild, Node oldChild)
318: throws DOMException;
319:
320: /**
321: * Removes the child node indicated by <code>oldChild</code> from the list
322: * of children, and returns it.
323: * @param oldChild The node being removed.
324: * @return The node removed.
325: * @exception DOMException
326: * NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
327: * <br>NOT_FOUND_ERR: Raised if <code>oldChild</code> is not a child of
328: * this node.
329: */
330: public Node removeChild(Node oldChild) throws DOMException;
331:
332: /**
333: * Adds the node <code>newChild</code> to the end of the list of children
334: * of this node. If the <code>newChild</code> is already in the tree, it
335: * is first removed.
336: * @param newChild The node to add.If it is a
337: * <code>DocumentFragment</code> object, the entire contents of the
338: * document fragment are moved into the child list of this node
339: * @return The node added.
340: * @exception DOMException
341: * HIERARCHY_REQUEST_ERR: Raised if this node is of a type that does not
342: * allow children of the type of the <code>newChild</code> node, or if
343: * the node to append is one of this node's ancestors or this node
344: * itself.
345: * <br>WRONG_DOCUMENT_ERR: Raised if <code>newChild</code> was created
346: * from a different document than the one that created this node.
347: * <br>NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly or
348: * if the previous parent of the node being inserted is readonly.
349: */
350: public Node appendChild(Node newChild) throws DOMException;
351:
352: /**
353: * Returns whether this node has any children.
354: * @return <code>true</code> if this node has any children,
355: * <code>false</code> otherwise.
356: */
357: public boolean hasChildNodes();
358:
359: /**
360: * Returns a duplicate of this node, i.e., serves as a generic copy
361: * constructor for nodes. The duplicate node has no parent; (
362: * <code>parentNode</code> is <code>null</code>.).
363: * <br>Cloning an <code>Element</code> copies all attributes and their
364: * values, including those generated by the XML processor to represent
365: * defaulted attributes, but this method does not copy any text it
366: * contains unless it is a deep clone, since the text is contained in a
367: * child <code>Text</code> node. Cloning an <code>Attribute</code>
368: * directly, as opposed to be cloned as part of an <code>Element</code>
369: * cloning operation, returns a specified attribute (
370: * <code>specified</code> is <code>true</code>). Cloning any other type
371: * of node simply returns a copy of this node.
372: * <br>Note that cloning an immutable subtree results in a mutable copy,
373: * but the children of an <code>EntityReference</code> clone are readonly
374: * . In addition, clones of unspecified <code>Attr</code> nodes are
375: * specified. And, cloning <code>Document</code>,
376: * <code>DocumentType</code>, <code>Entity</code>, and
377: * <code>Notation</code> nodes is implementation dependent.
378: * @param deep If <code>true</code>, recursively clone the subtree under
379: * the specified node; if <code>false</code>, clone only the node
380: * itself (and its attributes, if it is an <code>Element</code>).
381: * @return The duplicate node.
382: */
383: public Node cloneNode(boolean deep);
384:
385: /**
386: * Puts all <code>Text</code> nodes in the full depth of the sub-tree
387: * underneath this <code>Node</code>, including attribute nodes, into a
388: * "normal" form where only structure (e.g., elements, comments,
389: * processing instructions, CDATA sections, and entity references)
390: * separates <code>Text</code> nodes, i.e., there are neither adjacent
391: * <code>Text</code> nodes nor empty <code>Text</code> nodes. This can
392: * be used to ensure that the DOM view of a document is the same as if
393: * it were saved and re-loaded, and is useful when operations (such as
394: * XPointer lookups) that depend on a particular document tree
395: * structure are to be used.In cases where the document contains
396: * <code>CDATASections</code>, the normalize operation alone may not be
397: * sufficient, since XPointers do not differentiate between
398: * <code>Text</code> nodes and <code>CDATASection</code> nodes.
399: * @version DOM Level 2
400: */
401: public void normalize();
402:
403: /**
404: * Tests whether the DOM implementation implements a specific feature and
405: * that feature is supported by this node.
406: * @param feature The name of the feature to test. This is the same name
407: * which can be passed to the method <code>hasFeature</code> on
408: * <code>DOMImplementation</code>.
409: * @param version This is the version number of the feature to test. In
410: * Level 2, version 1, this is the string "2.0". If the version is not
411: * specified, supporting any version of the feature will cause the
412: * method to return <code>true</code>.
413: * @return Returns <code>true</code> if the specified feature is
414: * supported on this node, <code>false</code> otherwise.
415: * @since DOM Level 2
416: */
417: public boolean isSupported(String feature, String version);
418:
419: /**
420: * The namespace URI of this node, or <code>null</code> if it is
421: * unspecified.
422: * <br>This is not a computed value that is the result of a namespace
423: * lookup based on an examination of the namespace declarations in
424: * scope. It is merely the namespace URI given at creation time.
425: * <br>For nodes of any type other than <code>ELEMENT_NODE</code> and
426: * <code>ATTRIBUTE_NODE</code> and nodes created with a DOM Level 1
427: * method, such as <code>createElement</code> from the
428: * <code>Document</code> interface, this is always <code>null</code>.Per
429: * the Namespaces in XML Specification an attribute does not inherit
430: * its namespace from the element it is attached to. If an attribute is
431: * not explicitly given a namespace, it simply has no namespace.
432: * @since DOM Level 2
433: */
434: public String getNamespaceURI();
435:
436: /**
437: * The namespace prefix of this node, or <code>null</code> if it is
438: * unspecified.
439: * <br>Note that setting this attribute, when permitted, changes the
440: * <code>nodeName</code> attribute, which holds the qualified name, as
441: * well as the <code>tagName</code> and <code>name</code> attributes of
442: * the <code>Element</code> and <code>Attr</code> interfaces, when
443: * applicable.
444: * <br>Note also that changing the prefix of an attribute that is known to
445: * have a default value, does not make a new attribute with the default
446: * value and the original prefix appear, since the
447: * <code>namespaceURI</code> and <code>localName</code> do not change.
448: * <br>For nodes of any type other than <code>ELEMENT_NODE</code> and
449: * <code>ATTRIBUTE_NODE</code> and nodes created with a DOM Level 1
450: * method, such as <code>createElement</code> from the
451: * <code>Document</code> interface, this is always <code>null</code>.
452: * @exception DOMException
453: * INVALID_CHARACTER_ERR: Raised if the specified prefix contains an
454: * illegal character, per the XML 1.0 specification .
455: * <br>NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
456: * <br>NAMESPACE_ERR: Raised if the specified <code>prefix</code> is
457: * malformed per the Namespaces in XML specification, if the
458: * <code>namespaceURI</code> of this node is <code>null</code>, if the
459: * specified prefix is "xml" and the <code>namespaceURI</code> of this
460: * node is different from "http://www.w3.org/XML/1998/namespace", if
461: * this node is an attribute and the specified prefix is "xmlns" and
462: * the <code>namespaceURI</code> of this node is different from "
463: * http://www.w3.org/2000/xmlns/", or if this node is an attribute and
464: * the <code>qualifiedName</code> of this node is "xmlns" .
465: * @since DOM Level 2
466: */
467: public String getPrefix();
468:
469: /**
470: * The namespace prefix of this node, or <code>null</code> if it is
471: * unspecified.
472: * <br>Note that setting this attribute, when permitted, changes the
473: * <code>nodeName</code> attribute, which holds the qualified name, as
474: * well as the <code>tagName</code> and <code>name</code> attributes of
475: * the <code>Element</code> and <code>Attr</code> interfaces, when
476: * applicable.
477: * <br>Note also that changing the prefix of an attribute that is known to
478: * have a default value, does not make a new attribute with the default
479: * value and the original prefix appear, since the
480: * <code>namespaceURI</code> and <code>localName</code> do not change.
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>createElement</code> from the
484: * <code>Document</code> interface, this is always <code>null</code>.
485: * @exception DOMException
486: * INVALID_CHARACTER_ERR: Raised if the specified prefix contains an
487: * illegal character, per the XML 1.0 specification .
488: * <br>NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
489: * <br>NAMESPACE_ERR: Raised if the specified <code>prefix</code> is
490: * malformed per the Namespaces in XML specification, if the
491: * <code>namespaceURI</code> of this node is <code>null</code>, if the
492: * specified prefix is "xml" and the <code>namespaceURI</code> of this
493: * node is different from "http://www.w3.org/XML/1998/namespace", if
494: * this node is an attribute and the specified prefix is "xmlns" and
495: * the <code>namespaceURI</code> of this node is different from "
496: * http://www.w3.org/2000/xmlns/", or if this node is an attribute and
497: * the <code>qualifiedName</code> of this node is "xmlns" .
498: * @since DOM Level 2
499: */
500: public void setPrefix(String prefix) throws DOMException;
501:
502: /**
503: * Returns the local part of the qualified name of this node.
504: * <br>For nodes of any type other than <code>ELEMENT_NODE</code> and
505: * <code>ATTRIBUTE_NODE</code> and nodes created with a DOM Level 1
506: * method, such as <code>createElement</code> from the
507: * <code>Document</code> interface, this is always <code>null</code>.
508: * @since DOM Level 2
509: */
510: public String getLocalName();
511:
512: /**
513: * Returns whether this node (if it is an element) has any attributes.
514: * @return <code>true</code> if this node has any attributes,
515: * <code>false</code> otherwise.
516: * @since DOM Level 2
517: */
518: public boolean hasAttributes();
519:
520: }
|