Source for org.w3c.dom.Document

   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>Document</code> interface represents the entire HTML or XML
  17:  * document. Conceptually, it is the root of the document tree, and provides
  18:  * the primary access to the document's data.
  19:  * <p>Since elements, text nodes, comments, processing instructions, etc.
  20:  * cannot exist outside the context of a <code>Document</code>, the
  21:  * <code>Document</code> interface also contains the factory methods needed
  22:  * to create these objects. The <code>Node</code> objects created have a
  23:  * <code>ownerDocument</code> attribute which associates them with the
  24:  * <code>Document</code> within whose context they were created.
  25:  * <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>.
  26:  */
  27: public interface Document extends Node {
  28:     /**
  29:      * The Document Type Declaration (see <code>DocumentType</code>)
  30:      * associated with this document. For XML documents without a document
  31:      * type declaration this returns <code>null</code>. For HTML documents,
  32:      * a <code>DocumentType</code> object may be returned, independently of
  33:      * the presence or absence of document type declaration in the HTML
  34:      * document.
  35:      * <br>This provides direct access to the <code>DocumentType</code> node,
  36:      * child node of this <code>Document</code>. This node can be set at
  37:      * document creation time and later changed through the use of child
  38:      * nodes manipulation methods, such as <code>Node.insertBefore</code>,
  39:      * or <code>Node.replaceChild</code>. Note, however, that while some
  40:      * implementations may instantiate different types of
  41:      * <code>Document</code> objects supporting additional features than the
  42:      * "Core", such as "HTML" [<a href='http://www.w3.org/TR/2003/REC-DOM-Level-2-HTML-20030109'>DOM Level 2 HTML</a>]
  43:      * , based on the <code>DocumentType</code> specified at creation time,
  44:      * changing it afterwards is very unlikely to result in a change of the
  45:      * features supported.
  46:      * @version DOM Level 3
  47:      */
  48:     public DocumentType getDoctype();
  49: 
  50:     /**
  51:      * The <code>DOMImplementation</code> object that handles this document. A
  52:      * DOM application may use objects from multiple implementations.
  53:      */
  54:     public DOMImplementation getImplementation();
  55: 
  56:     /**
  57:      * This is a convenience attribute that allows direct access to the child
  58:      * node that is the document element of the document.
  59:      */
  60:     public Element getDocumentElement();
  61: 
  62:     /**
  63:      * Creates an element of the type specified. Note that the instance
  64:      * returned implements the <code>Element</code> interface, so attributes
  65:      * can be specified directly on the returned object.
  66:      * <br>In addition, if there are known attributes with default values,
  67:      * <code>Attr</code> nodes representing them are automatically created
  68:      * and attached to the element.
  69:      * <br>To create an element with a qualified name and namespace URI, use
  70:      * the <code>createElementNS</code> method.
  71:      * @param tagName The name of the element type to instantiate. For XML,
  72:      *   this is case-sensitive, otherwise it depends on the
  73:      *   case-sensitivity of the markup language in use. In that case, the
  74:      *   name is mapped to the canonical form of that markup by the DOM
  75:      *   implementation.
  76:      * @return A new <code>Element</code> object with the
  77:      *   <code>nodeName</code> attribute set to <code>tagName</code>, and
  78:      *   <code>localName</code>, <code>prefix</code>, and
  79:      *   <code>namespaceURI</code> set to <code>null</code>.
  80:      * @exception DOMException
  81:      *   INVALID_CHARACTER_ERR: Raised if the specified name is not an XML
  82:      *   name according to the XML version in use specified in the
  83:      *   <code>Document.xmlVersion</code> attribute.
  84:      */
  85:     public Element createElement(String tagName)
  86:                                  throws DOMException;
  87: 
  88:     /**
  89:      * Creates an empty <code>DocumentFragment</code> object.
  90:      * @return A new <code>DocumentFragment</code>.
  91:      */
  92:     public DocumentFragment createDocumentFragment();
  93: 
  94:     /**
  95:      * Creates a <code>Text</code> node given the specified string.
  96:      * @param data The data for the node.
  97:      * @return The new <code>Text</code> object.
  98:      */
  99:     public Text createTextNode(String data);
 100: 
 101:     /**
 102:      * Creates a <code>Comment</code> node given the specified string.
 103:      * @param data The data for the node.
 104:      * @return The new <code>Comment</code> object.
 105:      */
 106:     public Comment createComment(String data);
 107: 
 108:     /**
 109:      * Creates a <code>CDATASection</code> node whose value is the specified
 110:      * string.
 111:      * @param data The data for the <code>CDATASection</code> contents.
 112:      * @return The new <code>CDATASection</code> object.
 113:      * @exception DOMException
 114:      *   NOT_SUPPORTED_ERR: Raised if this document is an HTML document.
 115:      */
 116:     public CDATASection createCDATASection(String data)
 117:                                            throws DOMException;
 118: 
 119:     /**
 120:      * Creates a <code>ProcessingInstruction</code> node given the specified
 121:      * name and data strings.
 122:      * @param target The target part of the processing instruction.Unlike
 123:      *   <code>Document.createElementNS</code> or
 124:      *   <code>Document.createAttributeNS</code>, no namespace well-formed
 125:      *   checking is done on the target name. Applications should invoke
 126:      *   <code>Document.normalizeDocument()</code> with the parameter "
 127:      *   namespaces" set to <code>true</code> in order to ensure that the
 128:      *   target name is namespace well-formed.
 129:      * @param data The data for the node.
 130:      * @return The new <code>ProcessingInstruction</code> object.
 131:      * @exception DOMException
 132:      *   INVALID_CHARACTER_ERR: Raised if the specified target is not an XML
 133:      *   name according to the XML version in use specified in the
 134:      *   <code>Document.xmlVersion</code> attribute.
 135:      *   <br>NOT_SUPPORTED_ERR: Raised if this document is an HTML document.
 136:      */
 137:     public ProcessingInstruction createProcessingInstruction(String target,
 138:                                                              String data)
 139:                                                              throws DOMException;
 140: 
 141:     /**
 142:      * Creates an <code>Attr</code> of the given name. Note that the
 143:      * <code>Attr</code> instance can then be set on an <code>Element</code>
 144:      * using the <code>setAttributeNode</code> method.
 145:      * <br>To create an attribute with a qualified name and namespace URI, use
 146:      * the <code>createAttributeNS</code> method.
 147:      * @param name The name of the attribute.
 148:      * @return A new <code>Attr</code> object with the <code>nodeName</code>
 149:      *   attribute set to <code>name</code>, and <code>localName</code>,
 150:      *   <code>prefix</code>, and <code>namespaceURI</code> set to
 151:      *   <code>null</code>. The value of the attribute is the empty string.
 152:      * @exception DOMException
 153:      *   INVALID_CHARACTER_ERR: Raised if the specified name is not an XML
 154:      *   name according to the XML version in use specified in the
 155:      *   <code>Document.xmlVersion</code> attribute.
 156:      */
 157:     public Attr createAttribute(String name)
 158:                                 throws DOMException;
 159: 
 160:     /**
 161:      * Creates an <code>EntityReference</code> object. In addition, if the
 162:      * referenced entity is known, the child list of the
 163:      * <code>EntityReference</code> node is made the same as that of the
 164:      * corresponding <code>Entity</code> node.
 165:      * <p ><b>Note:</b> If any descendant of the <code>Entity</code> node has
 166:      * an unbound namespace prefix, the corresponding descendant of the
 167:      * created <code>EntityReference</code> node is also unbound; (its
 168:      * <code>namespaceURI</code> is <code>null</code>). The DOM Level 2 and
 169:      * 3 do not support any mechanism to resolve namespace prefixes in this
 170:      * case.
 171:      * @param name The name of the entity to reference.Unlike
 172:      *   <code>Document.createElementNS</code> or
 173:      *   <code>Document.createAttributeNS</code>, no namespace well-formed
 174:      *   checking is done on the entity name. Applications should invoke
 175:      *   <code>Document.normalizeDocument()</code> with the parameter "
 176:      *   namespaces" set to <code>true</code> in order to ensure that the
 177:      *   entity name is namespace well-formed.
 178:      * @return The new <code>EntityReference</code> object.
 179:      * @exception DOMException
 180:      *   INVALID_CHARACTER_ERR: Raised if the specified name is not an XML
 181:      *   name according to the XML version in use specified in the
 182:      *   <code>Document.xmlVersion</code> attribute.
 183:      *   <br>NOT_SUPPORTED_ERR: Raised if this document is an HTML document.
 184:      */
 185:     public EntityReference createEntityReference(String name)
 186:                                                  throws DOMException;
 187: 
 188:     /**
 189:      * Returns a <code>NodeList</code> of all the <code>Elements</code> in
 190:      * document order with a given tag name and are contained in the
 191:      * document.
 192:      * @param tagname  The name of the tag to match on. The special value "*"
 193:      *   matches all tags. For XML, the <code>tagname</code> parameter is
 194:      *   case-sensitive, otherwise it depends on the case-sensitivity of the
 195:      *   markup language in use.
 196:      * @return A new <code>NodeList</code> object containing all the matched
 197:      *   <code>Elements</code>.
 198:      */
 199:     public NodeList getElementsByTagName(String tagname);
 200: 
 201:     /**
 202:      * Imports a node from another document to this document, without altering
 203:      * or removing the source node from the original document; this method
 204:      * creates a new copy of the source node. The returned node has no
 205:      * parent; (<code>parentNode</code> is <code>null</code>).
 206:      * <br>For all nodes, importing a node creates a node object owned by the
 207:      * importing document, with attribute values identical to the source
 208:      * node's <code>nodeName</code> and <code>nodeType</code>, plus the
 209:      * attributes related to namespaces (<code>prefix</code>,
 210:      * <code>localName</code>, and <code>namespaceURI</code>). As in the
 211:      * <code>cloneNode</code> operation, the source node is not altered.
 212:      * User data associated to the imported node is not carried over.
 213:      * However, if any <code>UserDataHandlers</code> has been specified
 214:      * along with the associated data these handlers will be called with the
 215:      * appropriate parameters before this method returns.
 216:      * <br>Additional information is copied as appropriate to the
 217:      * <code>nodeType</code>, attempting to mirror the behavior expected if
 218:      * a fragment of XML or HTML source was copied from one document to
 219:      * another, recognizing that the two documents may have different DTDs
 220:      * in the XML case. The following list describes the specifics for each
 221:      * type of node.
 222:      * <dl>
 223:      * <dt>ATTRIBUTE_NODE</dt>
 224:      * <dd>The <code>ownerElement</code> attribute
 225:      * is set to <code>null</code> and the <code>specified</code> flag is
 226:      * set to <code>true</code> on the generated <code>Attr</code>. The
 227:      * descendants of the source <code>Attr</code> are recursively imported
 228:      * and the resulting nodes reassembled to form the corresponding subtree.
 229:      * Note that the <code>deep</code> parameter has no effect on
 230:      * <code>Attr</code> nodes; they always carry their children with them
 231:      * when imported.</dd>
 232:      * <dt>DOCUMENT_FRAGMENT_NODE</dt>
 233:      * <dd>If the <code>deep</code> option
 234:      * was set to <code>true</code>, the descendants of the source
 235:      * <code>DocumentFragment</code> are recursively imported and the
 236:      * resulting nodes reassembled under the imported
 237:      * <code>DocumentFragment</code> to form the corresponding subtree.
 238:      * Otherwise, this simply generates an empty
 239:      * <code>DocumentFragment</code>.</dd>
 240:      * <dt>DOCUMENT_NODE</dt>
 241:      * <dd><code>Document</code>
 242:      * nodes cannot be imported.</dd>
 243:      * <dt>DOCUMENT_TYPE_NODE</dt>
 244:      * <dd><code>DocumentType</code>
 245:      * nodes cannot be imported.</dd>
 246:      * <dt>ELEMENT_NODE</dt>
 247:      * <dd><em>Specified</em> attribute nodes of the source element are imported, and the generated
 248:      * <code>Attr</code> nodes are attached to the generated
 249:      * <code>Element</code>. Default attributes are <em>not</em> copied, though if the document being imported into defines default
 250:      * attributes for this element name, those are assigned. If the
 251:      * <code>importNode</code> <code>deep</code> parameter was set to
 252:      * <code>true</code>, the descendants of the source element are
 253:      * recursively imported and the resulting nodes reassembled to form the
 254:      * corresponding subtree.</dd>
 255:      * <dt>ENTITY_NODE</dt>
 256:      * <dd><code>Entity</code> nodes can be
 257:      * imported, however in the current release of the DOM the
 258:      * <code>DocumentType</code> is readonly. Ability to add these imported
 259:      * nodes to a <code>DocumentType</code> will be considered for addition
 260:      * to a future release of the DOM.On import, the <code>publicId</code>,
 261:      * <code>systemId</code>, and <code>notationName</code> attributes are
 262:      * copied. If a <code>deep</code> import is requested, the descendants
 263:      * of the the source <code>Entity</code> are recursively imported and
 264:      * the resulting nodes reassembled to form the corresponding subtree.</dd>
 265:      * <dt>
 266:      * ENTITY_REFERENCE_NODE</dt>
 267:      * <dd>Only the <code>EntityReference</code> itself is
 268:      * copied, even if a <code>deep</code> import is requested, since the
 269:      * source and destination documents might have defined the entity
 270:      * differently. If the document being imported into provides a
 271:      * definition for this entity name, its value is assigned.</dd>
 272:      * <dt>NOTATION_NODE</dt>
 273:      * <dd>
 274:      * <code>Notation</code> nodes can be imported, however in the current
 275:      * release of the DOM the <code>DocumentType</code> is readonly. Ability
 276:      * to add these imported nodes to a <code>DocumentType</code> will be
 277:      * considered for addition to a future release of the DOM.On import, the
 278:      * <code>publicId</code> and <code>systemId</code> attributes are copied.
 279:      * Note that the <code>deep</code> parameter has no effect on this type
 280:      * of nodes since they cannot have any children.</dd>
 281:      * <dt>
 282:      * PROCESSING_INSTRUCTION_NODE</dt>
 283:      * <dd>The imported node copies its
 284:      * <code>target</code> and <code>data</code> values from those of the
 285:      * source node.Note that the <code>deep</code> parameter has no effect
 286:      * on this type of nodes since they cannot have any children.</dd>
 287:      * <dt>TEXT_NODE,
 288:      * CDATA_SECTION_NODE, COMMENT_NODE</dt>
 289:      * <dd>These three types of nodes inheriting
 290:      * from <code>CharacterData</code> copy their <code>data</code> and
 291:      * <code>length</code> attributes from those of the source node.Note
 292:      * that the <code>deep</code> parameter has no effect on these types of
 293:      * nodes since they cannot have any children.</dd>
 294:      * </dl>
 295:      * @param importedNode The node to import.
 296:      * @param deep If <code>true</code>, recursively import the subtree under
 297:      *   the specified node; if <code>false</code>, import only the node
 298:      *   itself, as explained above. This has no effect on nodes that cannot
 299:      *   have any children, and on <code>Attr</code>, and
 300:      *   <code>EntityReference</code> nodes.
 301:      * @return The imported node that belongs to this <code>Document</code>.
 302:      * @exception DOMException
 303:      *   NOT_SUPPORTED_ERR: Raised if the type of node being imported is not
 304:      *   supported.
 305:      *   <br>INVALID_CHARACTER_ERR: Raised if one of the imported names is not
 306:      *   an XML name according to the XML version in use specified in the
 307:      *   <code>Document.xmlVersion</code> attribute. This may happen when
 308:      *   importing an XML 1.1 [<a href='http://www.w3.org/TR/2004/REC-xml11-20040204/'>XML 1.1</a>] element
 309:      *   into an XML 1.0 document, for instance.
 310:      * @since DOM Level 2
 311:      */
 312:     public Node importNode(Node importedNode,
 313:                            boolean deep)
 314:                            throws DOMException;
 315: 
 316:     /**
 317:      * Creates an element of the given qualified name and namespace URI.
 318:      * <br>Per [<a href='http://www.w3.org/TR/1999/REC-xml-names-19990114/'>XML Namespaces</a>]
 319:      * , applications must use the value <code>null</code> as the
 320:      * namespaceURI parameter for methods if they wish to have no namespace.
 321:      * @param namespaceURI The namespace URI of the element to create.
 322:      * @param qualifiedName The qualified name of the element type to
 323:      *   instantiate.
 324:      * @return A new <code>Element</code> object with the following
 325:      *   attributes:
 326:      * <table border='1' cellpadding='3'>
 327:      * <tr>
 328:      * <th>Attribute</th>
 329:      * <th>Value</th>
 330:      * </tr>
 331:      * <tr>
 332:      * <td valign='top' rowspan='1' colspan='1'><code>Node.nodeName</code></td>
 333:      * <td valign='top' rowspan='1' colspan='1'>
 334:      *   <code>qualifiedName</code></td>
 335:      * </tr>
 336:      * <tr>
 337:      * <td valign='top' rowspan='1' colspan='1'><code>Node.namespaceURI</code></td>
 338:      * <td valign='top' rowspan='1' colspan='1'>
 339:      *   <code>namespaceURI</code></td>
 340:      * </tr>
 341:      * <tr>
 342:      * <td valign='top' rowspan='1' colspan='1'><code>Node.prefix</code></td>
 343:      * <td valign='top' rowspan='1' colspan='1'>prefix, extracted
 344:      *   from <code>qualifiedName</code>, or <code>null</code> if there is
 345:      *   no prefix</td>
 346:      * </tr>
 347:      * <tr>
 348:      * <td valign='top' rowspan='1' colspan='1'><code>Node.localName</code></td>
 349:      * <td valign='top' rowspan='1' colspan='1'>local name, extracted from
 350:      *   <code>qualifiedName</code></td>
 351:      * </tr>
 352:      * <tr>
 353:      * <td valign='top' rowspan='1' colspan='1'><code>Element.tagName</code></td>
 354:      * <td valign='top' rowspan='1' colspan='1'>
 355:      *   <code>qualifiedName</code></td>
 356:      * </tr>
 357:      * </table>
 358:      * @exception DOMException
 359:      *   INVALID_CHARACTER_ERR: Raised if the specified
 360:      *   <code>qualifiedName</code> is not an XML name according to the XML
 361:      *   version in use specified in the <code>Document.xmlVersion</code>
 362:      *   attribute.
 363:      *   <br>NAMESPACE_ERR: Raised if the <code>qualifiedName</code> is a
 364:      *   malformed qualified name, if the <code>qualifiedName</code> has a
 365:      *   prefix and the <code>namespaceURI</code> is <code>null</code>, or
 366:      *   if the <code>qualifiedName</code> has a prefix that is "xml" and
 367:      *   the <code>namespaceURI</code> is different from "<a href='http://www.w3.org/XML/1998/namespace'>
 368:      *   http://www.w3.org/XML/1998/namespace</a>" [<a href='http://www.w3.org/TR/1999/REC-xml-names-19990114/'>XML Namespaces</a>]
 369:      *   , or if the <code>qualifiedName</code> or its prefix is "xmlns" and
 370:      *   the <code>namespaceURI</code> is different from "<a href='http://www.w3.org/2000/xmlns/'>http://www.w3.org/2000/xmlns/</a>", or if the <code>namespaceURI</code> is "<a href='http://www.w3.org/2000/xmlns/'>http://www.w3.org/2000/xmlns/</a>" and neither the <code>qualifiedName</code> nor its prefix is "xmlns".
 371:      *   <br>NOT_SUPPORTED_ERR: Always thrown if the current document does not
 372:      *   support the <code>"XML"</code> feature, since namespaces were
 373:      *   defined by XML.
 374:      * @since DOM Level 2
 375:      */
 376:     public Element createElementNS(String namespaceURI,
 377:                                    String qualifiedName)
 378:                                    throws DOMException;
 379: 
 380:     /**
 381:      * Creates an attribute of the given qualified name and namespace URI.
 382:      * <br>Per [<a href='http://www.w3.org/TR/1999/REC-xml-names-19990114/'>XML Namespaces</a>]
 383:      * , applications must use the value <code>null</code> as the
 384:      * <code>namespaceURI</code> parameter for methods if they wish to have
 385:      * no namespace.
 386:      * @param namespaceURI The namespace URI of the attribute to create.
 387:      * @param qualifiedName The qualified name of the attribute to
 388:      *   instantiate.
 389:      * @return A new <code>Attr</code> object with the following attributes:
 390:      * <table border='1' cellpadding='3'>
 391:      * <tr>
 392:      * <th>
 393:      *   Attribute</th>
 394:      * <th>Value</th>
 395:      * </tr>
 396:      * <tr>
 397:      * <td valign='top' rowspan='1' colspan='1'><code>Node.nodeName</code></td>
 398:      * <td valign='top' rowspan='1' colspan='1'>qualifiedName</td>
 399:      * </tr>
 400:      * <tr>
 401:      * <td valign='top' rowspan='1' colspan='1'>
 402:      *   <code>Node.namespaceURI</code></td>
 403:      * <td valign='top' rowspan='1' colspan='1'><code>namespaceURI</code></td>
 404:      * </tr>
 405:      * <tr>
 406:      * <td valign='top' rowspan='1' colspan='1'>
 407:      *   <code>Node.prefix</code></td>
 408:      * <td valign='top' rowspan='1' colspan='1'>prefix, extracted from
 409:      *   <code>qualifiedName</code>, or <code>null</code> if there is no
 410:      *   prefix</td>
 411:      * </tr>
 412:      * <tr>
 413:      * <td valign='top' rowspan='1' colspan='1'><code>Node.localName</code></td>
 414:      * <td valign='top' rowspan='1' colspan='1'>local name, extracted from
 415:      *   <code>qualifiedName</code></td>
 416:      * </tr>
 417:      * <tr>
 418:      * <td valign='top' rowspan='1' colspan='1'><code>Attr.name</code></td>
 419:      * <td valign='top' rowspan='1' colspan='1'>
 420:      *   <code>qualifiedName</code></td>
 421:      * </tr>
 422:      * <tr>
 423:      * <td valign='top' rowspan='1' colspan='1'><code>Node.nodeValue</code></td>
 424:      * <td valign='top' rowspan='1' colspan='1'>the empty
 425:      *   string</td>
 426:      * </tr>
 427:      * </table>
 428:      * @exception DOMException
 429:      *   INVALID_CHARACTER_ERR: Raised if the specified
 430:      *   <code>qualifiedName</code> is not an XML name according to the XML
 431:      *   version in use specified in the <code>Document.xmlVersion</code>
 432:      *   attribute.
 433:      *   <br>NAMESPACE_ERR: Raised if the <code>qualifiedName</code> is a
 434:      *   malformed qualified name, if the <code>qualifiedName</code> has a
 435:      *   prefix and the <code>namespaceURI</code> is <code>null</code>, if
 436:      *   the <code>qualifiedName</code> has a prefix that is "xml" and the
 437:      *   <code>namespaceURI</code> is different from "<a href='http://www.w3.org/XML/1998/namespace'>
 438:      *   http://www.w3.org/XML/1998/namespace</a>", if the <code>qualifiedName</code> or its prefix is "xmlns" and the
 439:      *   <code>namespaceURI</code> is different from "<a href='http://www.w3.org/2000/xmlns/'>http://www.w3.org/2000/xmlns/</a>", or if the <code>namespaceURI</code> is "<a href='http://www.w3.org/2000/xmlns/'>http://www.w3.org/2000/xmlns/</a>" and neither the <code>qualifiedName</code> nor its prefix is "xmlns".
 440:      *   <br>NOT_SUPPORTED_ERR: Always thrown if the current document does not
 441:      *   support the <code>"XML"</code> feature, since namespaces were
 442:      *   defined by XML.
 443:      * @since DOM Level 2
 444:      */
 445:     public Attr createAttributeNS(String namespaceURI,
 446:                                   String qualifiedName)
 447:                                   throws DOMException;
 448: 
 449:     /**
 450:      * Returns a <code>NodeList</code> of all the <code>Elements</code> with a
 451:      * given local name and namespace URI in document order.
 452:      * @param namespaceURI The namespace URI of the elements to match on. The
 453:      *   special value <code>"*"</code> matches all namespaces.
 454:      * @param localName The local name of the elements to match on. The
 455:      *   special value "*" matches all local names.
 456:      * @return A new <code>NodeList</code> object containing all the matched
 457:      *   <code>Elements</code>.
 458:      * @since DOM Level 2
 459:      */
 460:     public NodeList getElementsByTagNameNS(String namespaceURI,
 461:                                            String localName);
 462: 
 463:     /**
 464:      * Returns the <code>Element</code> that has an ID attribute with the
 465:      * given value. If no such element exists, this returns <code>null</code>
 466:      * . If more than one element has an ID attribute with that value, what
 467:      * is returned is undefined.
 468:      * <br> The DOM implementation is expected to use the attribute
 469:      * <code>Attr.isId</code> to determine if an attribute is of type ID.
 470:      * <p ><b>Note:</b> Attributes with the name "ID" or "id" are not of type
 471:      * ID unless so defined.
 472:      * @param elementId The unique <code>id</code> value for an element.
 473:      * @return The matching element or <code>null</code> if there is none.
 474:      * @since DOM Level 2
 475:      */
 476:     public Element getElementById(String elementId);
 477: 
 478:     /**
 479:      * An attribute specifying the encoding used for this document at the time
 480:      * of the parsing. This is <code>null</code> when it is not known, such
 481:      * as when the <code>Document</code> was created in memory.
 482:      * @since DOM Level 3
 483:      */
 484:     public String getInputEncoding();
 485: 
 486:     /**
 487:      * An attribute specifying, as part of the <a href='http://www.w3.org/TR/2004/REC-xml-20040204#NT-XMLDecl'>XML declaration</a>, the encoding of this document. This is <code>null</code> when
 488:      * unspecified or when it is not known, such as when the
 489:      * <code>Document</code> was created in memory.
 490:      * @since DOM Level 3
 491:      */
 492:     public String getXmlEncoding();
 493: 
 494:     /**
 495:      * An attribute specifying, as part of the <a href='http://www.w3.org/TR/2004/REC-xml-20040204#NT-XMLDecl'>XML declaration</a>, whether this document is standalone. This is <code>false</code> when
 496:      * unspecified.
 497:      * <p ><b>Note:</b>  No verification is done on the value when setting
 498:      * this attribute. Applications should use
 499:      * <code>Document.normalizeDocument()</code> with the "validate"
 500:      * parameter to verify if the value matches the <a href='http://www.w3.org/TR/2004/REC-xml-20040204#sec-rmd'>validity
 501:      * constraint for standalone document declaration</a> as defined in [<a href='http://www.w3.org/TR/2004/REC-xml-20040204'>XML 1.0</a>].
 502:      * @since DOM Level 3
 503:      */
 504:     public boolean getXmlStandalone();
 505:     /**
 506:      * An attribute specifying, as part of the <a href='http://www.w3.org/TR/2004/REC-xml-20040204#NT-XMLDecl'>XML declaration</a>, whether this document is standalone. This is <code>false</code> when
 507:      * unspecified.
 508:      * <p ><b>Note:</b>  No verification is done on the value when setting
 509:      * this attribute. Applications should use
 510:      * <code>Document.normalizeDocument()</code> with the "validate"
 511:      * parameter to verify if the value matches the <a href='http://www.w3.org/TR/2004/REC-xml-20040204#sec-rmd'>validity
 512:      * constraint for standalone document declaration</a> as defined in [<a href='http://www.w3.org/TR/2004/REC-xml-20040204'>XML 1.0</a>].
 513:      * @exception DOMException
 514:      *    NOT_SUPPORTED_ERR: Raised if this document does not support the
 515:      *   "XML" feature.
 516:      * @since DOM Level 3
 517:      */
 518:     public void setXmlStandalone(boolean xmlStandalone)
 519:                                   throws DOMException;
 520: 
 521:     /**
 522:      *  An attribute specifying, as part of the <a href='http://www.w3.org/TR/2004/REC-xml-20040204#NT-XMLDecl'>XML declaration</a>, the version number of this document. If there is no declaration and if
 523:      * this document supports the "XML" feature, the value is
 524:      * <code>"1.0"</code>. If this document does not support the "XML"
 525:      * feature, the value is always <code>null</code>. Changing this
 526:      * attribute will affect methods that check for invalid characters in
 527:      * XML names. Application should invoke
 528:      * <code>Document.normalizeDocument()</code> in order to check for
 529:      * invalid characters in the <code>Node</code>s that are already part of
 530:      * this <code>Document</code>.
 531:      * <br> DOM applications may use the
 532:      * <code>DOMImplementation.hasFeature(feature, version)</code> method
 533:      * with parameter values "XMLVersion" and "1.0" (respectively) to
 534:      * determine if an implementation supports [<a href='http://www.w3.org/TR/2004/REC-xml-20040204'>XML 1.0</a>]. DOM
 535:      * applications may use the same method with parameter values
 536:      * "XMLVersion" and "1.1" (respectively) to determine if an
 537:      * implementation supports [<a href='http://www.w3.org/TR/2004/REC-xml11-20040204/'>XML 1.1</a>]. In both
 538:      * cases, in order to support XML, an implementation must also support
 539:      * the "XML" feature defined in this specification. <code>Document</code>
 540:      *  objects supporting a version of the "XMLVersion" feature must not
 541:      * raise a <code>NOT_SUPPORTED_ERR</code> exception for the same version
 542:      * number when using <code>Document.xmlVersion</code>.
 543:      * @since DOM Level 3
 544:      */
 545:     public String getXmlVersion();
 546:     /**
 547:      *  An attribute specifying, as part of the <a href='http://www.w3.org/TR/2004/REC-xml-20040204#NT-XMLDecl'>XML declaration</a>, the version number of this document. If there is no declaration and if
 548:      * this document supports the "XML" feature, the value is
 549:      * <code>"1.0"</code>. If this document does not support the "XML"
 550:      * feature, the value is always <code>null</code>. Changing this
 551:      * attribute will affect methods that check for invalid characters in
 552:      * XML names. Application should invoke
 553:      * <code>Document.normalizeDocument()</code> in order to check for
 554:      * invalid characters in the <code>Node</code>s that are already part of
 555:      * this <code>Document</code>.
 556:      * <br> DOM applications may use the
 557:      * <code>DOMImplementation.hasFeature(feature, version)</code> method
 558:      * with parameter values "XMLVersion" and "1.0" (respectively) to
 559:      * determine if an implementation supports [<a href='http://www.w3.org/TR/2004/REC-xml-20040204'>XML 1.0</a>]. DOM
 560:      * applications may use the same method with parameter values
 561:      * "XMLVersion" and "1.1" (respectively) to determine if an
 562:      * implementation supports [<a href='http://www.w3.org/TR/2004/REC-xml11-20040204/'>XML 1.1</a>]. In both
 563:      * cases, in order to support XML, an implementation must also support
 564:      * the "XML" feature defined in this specification. <code>Document</code>
 565:      *  objects supporting a version of the "XMLVersion" feature must not
 566:      * raise a <code>NOT_SUPPORTED_ERR</code> exception for the same version
 567:      * number when using <code>Document.xmlVersion</code>.
 568:      * @exception DOMException
 569:      *    NOT_SUPPORTED_ERR: Raised if the version is set to a value that is
 570:      *   not supported by this <code>Document</code> or if this document
 571:      *   does not support the "XML" feature.
 572:      * @since DOM Level 3
 573:      */
 574:     public void setXmlVersion(String xmlVersion)
 575:                                   throws DOMException;
 576: 
 577:     /**
 578:      * An attribute specifying whether error checking is enforced or not. When
 579:      * set to <code>false</code>, the implementation is free to not test
 580:      * every possible error case normally defined on DOM operations, and not
 581:      * raise any <code>DOMException</code> on DOM operations or report
 582:      * errors while using <code>Document.normalizeDocument()</code>. In case
 583:      * of error, the behavior is undefined. This attribute is
 584:      * <code>true</code> by default.
 585:      * @since DOM Level 3
 586:      */
 587:     public boolean getStrictErrorChecking();
 588:     /**
 589:      * An attribute specifying whether error checking is enforced or not. When
 590:      * set to <code>false</code>, the implementation is free to not test
 591:      * every possible error case normally defined on DOM operations, and not
 592:      * raise any <code>DOMException</code> on DOM operations or report
 593:      * errors while using <code>Document.normalizeDocument()</code>. In case
 594:      * of error, the behavior is undefined. This attribute is
 595:      * <code>true</code> by default.
 596:      * @since DOM Level 3
 597:      */
 598:     public void setStrictErrorChecking(boolean strictErrorChecking);
 599: 
 600:     /**
 601:      *  The location of the document or <code>null</code> if undefined or if
 602:      * the <code>Document</code> was created using
 603:      * <code>DOMImplementation.createDocument</code>. No lexical checking is
 604:      * performed when setting this attribute; this could result in a
 605:      * <code>null</code> value returned when using <code>Node.baseURI</code>
 606:      * .
 607:      * <br> Beware that when the <code>Document</code> supports the feature
 608:      * "HTML" [<a href='http://www.w3.org/TR/2003/REC-DOM-Level-2-HTML-20030109'>DOM Level 2 HTML</a>]
 609:      * , the href attribute of the HTML BASE element takes precedence over
 610:      * this attribute when computing <code>Node.baseURI</code>.
 611:      * @since DOM Level 3
 612:      */
 613:     public String getDocumentURI();
 614:     /**
 615:      *  The location of the document or <code>null</code> if undefined or if
 616:      * the <code>Document</code> was created using
 617:      * <code>DOMImplementation.createDocument</code>. No lexical checking is
 618:      * performed when setting this attribute; this could result in a
 619:      * <code>null</code> value returned when using <code>Node.baseURI</code>
 620:      * .
 621:      * <br> Beware that when the <code>Document</code> supports the feature
 622:      * "HTML" [<a href='http://www.w3.org/TR/2003/REC-DOM-Level-2-HTML-20030109'>DOM Level 2 HTML</a>]
 623:      * , the href attribute of the HTML BASE element takes precedence over
 624:      * this attribute when computing <code>Node.baseURI</code>.
 625:      * @since DOM Level 3
 626:      */
 627:     public void setDocumentURI(String documentURI);
 628: 
 629:     /**
 630:      *  Attempts to adopt a node from another document to this document. If
 631:      * supported, it changes the <code>ownerDocument</code> of the source
 632:      * node, its children, as well as the attached attribute nodes if there
 633:      * are any. If the source node has a parent it is first removed from the
 634:      * child list of its parent. This effectively allows moving a subtree
 635:      * from one document to another (unlike <code>importNode()</code> which
 636:      * create a copy of the source node instead of moving it). When it
 637:      * fails, applications should use <code>Document.importNode()</code>
 638:      * instead. Note that if the adopted node is already part of this
 639:      * document (i.e. the source and target document are the same), this
 640:      * method still has the effect of removing the source node from the
 641:      * child list of its parent, if any. The following list describes the
 642:      * specifics for each type of node.
 643:      * <dl>
 644:      * <dt>ATTRIBUTE_NODE</dt>
 645:      * <dd>The
 646:      * <code>ownerElement</code> attribute is set to <code>null</code> and
 647:      * the <code>specified</code> flag is set to <code>true</code> on the
 648:      * adopted <code>Attr</code>. The descendants of the source
 649:      * <code>Attr</code> are recursively adopted.</dd>
 650:      * <dt>DOCUMENT_FRAGMENT_NODE</dt>
 651:      * <dd>The
 652:      * descendants of the source node are recursively adopted.</dd>
 653:      * <dt>DOCUMENT_NODE</dt>
 654:      * <dd>
 655:      * <code>Document</code> nodes cannot be adopted.</dd>
 656:      * <dt>DOCUMENT_TYPE_NODE</dt>
 657:      * <dd>
 658:      * <code>DocumentType</code> nodes cannot be adopted.</dd>
 659:      * <dt>ELEMENT_NODE</dt>
 660:      * <dd><em>Specified</em> attribute nodes of the source element are adopted. Default attributes
 661:      * are discarded, though if the document being adopted into defines
 662:      * default attributes for this element name, those are assigned. The
 663:      * descendants of the source element are recursively adopted.</dd>
 664:      * <dt>ENTITY_NODE</dt>
 665:      * <dd>
 666:      * <code>Entity</code> nodes cannot be adopted.</dd>
 667:      * <dt>ENTITY_REFERENCE_NODE</dt>
 668:      * <dd>Only
 669:      * the <code>EntityReference</code> node itself is adopted, the
 670:      * descendants are discarded, since the source and destination documents
 671:      * might have defined the entity differently. If the document being
 672:      * imported into provides a definition for this entity name, its value
 673:      * is assigned.</dd>
 674:      * <dt>NOTATION_NODE</dt>
 675:      * <dd><code>Notation</code> nodes cannot be
 676:      * adopted.</dd>
 677:      * <dt>PROCESSING_INSTRUCTION_NODE, TEXT_NODE, CDATA_SECTION_NODE,
 678:      * COMMENT_NODE</dt>
 679:      * <dd>These nodes can all be adopted. No specifics.</dd>
 680:      * </dl>
 681:      * <p ><b>Note:</b>  Since it does not create new nodes unlike the
 682:      * <code>Document.importNode()</code> method, this method does not raise
 683:      * an <code>INVALID_CHARACTER_ERR</code> exception, and applications
 684:      * should use the <code>Document.normalizeDocument()</code> method to
 685:      * check if an imported name is not an XML name according to the XML
 686:      * version in use.
 687:      * @param source The node to move into this document.
 688:      * @return The adopted node, or <code>null</code> if this operation
 689:      *   fails, such as when the source node comes from a different
 690:      *   implementation.
 691:      * @exception DOMException
 692:      *   NOT_SUPPORTED_ERR: Raised if the source node is of type
 693:      *   <code>DOCUMENT</code>, <code>DOCUMENT_TYPE</code>.
 694:      *   <br>NO_MODIFICATION_ALLOWED_ERR: Raised when the source node is
 695:      *   readonly.
 696:      * @since DOM Level 3
 697:      */
 698:     public Node adoptNode(Node source)
 699:                           throws DOMException;
 700: 
 701:     /**
 702:      *  The configuration used when <code>Document.normalizeDocument()</code>
 703:      * is invoked.
 704:      * @since DOM Level 3
 705:      */
 706:     public DOMConfiguration getDomConfig();
 707: 
 708:     /**
 709:      *  This method acts as if the document was going through a save and load
 710:      * cycle, putting the document in a "normal" form. As a consequence,
 711:      * this method updates the replacement tree of
 712:      * <code>EntityReference</code> nodes and normalizes <code>Text</code>
 713:      * nodes, as defined in the method <code>Node.normalize()</code>.
 714:      * <br> Otherwise, the actual result depends on the features being set on
 715:      * the <code>Document.domConfig</code> object and governing what
 716:      * operations actually take place. Noticeably this method could also
 717:      * make the document namespace well-formed according to the algorithm
 718:      * described in , check the character normalization, remove the
 719:      * <code>CDATASection</code> nodes, etc. See
 720:      * <code>DOMConfiguration</code> for details.
 721:      * <pre>// Keep in the document
 722:      * the information defined // in the XML Information Set (Java example)
 723:      * DOMConfiguration docConfig = myDocument.getDomConfig();
 724:      * docConfig.setParameter("infoset", Boolean.TRUE);
 725:      * myDocument.normalizeDocument();</pre>
 726:      *
 727:      * <br>Mutation events, when supported, are generated to reflect the
 728:      * changes occurring on the document.
 729:      * <br> If errors occur during the invocation of this method, such as an
 730:      * attempt to update a read-only node or a <code>Node.nodeName</code>
 731:      * contains an invalid character according to the XML version in use,
 732:      * errors or warnings (<code>DOMError.SEVERITY_ERROR</code> or
 733:      * <code>DOMError.SEVERITY_WARNING</code>) will be reported using the
 734:      * <code>DOMErrorHandler</code> object associated with the "error-handler
 735:      * " parameter. Note this method might also report fatal errors (
 736:      * <code>DOMError.SEVERITY_FATAL_ERROR</code>) if an implementation
 737:      * cannot recover from an error.
 738:      * @since DOM Level 3
 739:      */
 740:     public void normalizeDocument();
 741: 
 742:     /**
 743:      * Rename an existing node of type <code>ELEMENT_NODE</code> or
 744:      * <code>ATTRIBUTE_NODE</code>.
 745:      * <br>When possible this simply changes the name of the given node,
 746:      * otherwise this creates a new node with the specified name and
 747:      * replaces the existing node with the new node as described below.
 748:      * <br>If simply changing the name of the given node is not possible, the
 749:      * following operations are performed: a new node is created, any
 750:      * registered event listener is registered on the new node, any user
 751:      * data attached to the old node is removed from that node, the old node
 752:      * is removed from its parent if it has one, the children are moved to
 753:      * the new node, if the renamed node is an <code>Element</code> its
 754:      * attributes are moved to the new node, the new node is inserted at the
 755:      * position the old node used to have in its parent's child nodes list
 756:      * if it has one, the user data that was attached to the old node is
 757:      * attached to the new node.
 758:      * <br>When the node being renamed is an <code>Element</code> only the
 759:      * specified attributes are moved, default attributes originated from
 760:      * the DTD are updated according to the new element name. In addition,
 761:      * the implementation may update default attributes from other schemas.
 762:      * Applications should use <code>Document.normalizeDocument()</code> to
 763:      * guarantee these attributes are up-to-date.
 764:      * <br>When the node being renamed is an <code>Attr</code> that is
 765:      * attached to an <code>Element</code>, the node is first removed from
 766:      * the <code>Element</code> attributes map. Then, once renamed, either
 767:      * by modifying the existing node or creating a new one as described
 768:      * above, it is put back.
 769:      * <br>In addition,
 770:      * <ul>
 771:      * <li> a user data event <code>NODE_RENAMED</code> is fired,
 772:      * </li>
 773:      * <li>
 774:      * when the implementation supports the feature "MutationNameEvents",
 775:      * each mutation operation involved in this method fires the appropriate
 776:      * event, and in the end the event {
 777:      * <code>http://www.w3.org/2001/xml-events</code>,
 778:      * <code>DOMElementNameChanged</code>} or {
 779:      * <code>http://www.w3.org/2001/xml-events</code>,
 780:      * <code>DOMAttributeNameChanged</code>} is fired.
 781:      * </li>
 782:      * </ul>
 783:      * @param n The node to rename.
 784:      * @param namespaceURI The new namespace URI.
 785:      * @param qualifiedName The new qualified name.
 786:      * @return The renamed node. This is either the specified node or the new
 787:      *   node that was created to replace the specified node.
 788:      * @exception DOMException
 789:      *   NOT_SUPPORTED_ERR: Raised when the type of the specified node is
 790:      *   neither <code>ELEMENT_NODE</code> nor <code>ATTRIBUTE_NODE</code>,
 791:      *   or if the implementation does not support the renaming of the
 792:      *   document element.
 793:      *   <br>INVALID_CHARACTER_ERR: Raised if the new qualified name is not an
 794:      *   XML name according to the XML version in use specified in the
 795:      *   <code>Document.xmlVersion</code> attribute.
 796:      *   <br>WRONG_DOCUMENT_ERR: Raised when the specified node was created
 797:      *   from a different document than this document.
 798:      *   <br>NAMESPACE_ERR: Raised if the <code>qualifiedName</code> is a
 799:      *   malformed qualified name, if the <code>qualifiedName</code> has a
 800:      *   prefix and the <code>namespaceURI</code> is <code>null</code>, or
 801:      *   if the <code>qualifiedName</code> has a prefix that is "xml" and
 802:      *   the <code>namespaceURI</code> is different from "<a href='http://www.w3.org/XML/1998/namespace'>
 803:      *   http://www.w3.org/XML/1998/namespace</a>" [<a href='http://www.w3.org/TR/1999/REC-xml-names-19990114/'>XML Namespaces</a>]
 804:      *   . Also raised, when the node being renamed is an attribute, if the
 805:      *   <code>qualifiedName</code>, or its prefix, is "xmlns" and the
 806:      *   <code>namespaceURI</code> is different from "<a href='http://www.w3.org/2000/xmlns/'>http://www.w3.org/2000/xmlns/</a>".
 807:      * @since DOM Level 3
 808:      */
 809:     public Node renameNode(Node n,
 810:                            String namespaceURI,
 811:                            String qualifiedName)
 812:                            throws DOMException;
 813: 
 814: }