org.apache.xerces.dom

## Class CoreDocumentImpl

- java.lang.Object
- - org.apache.xerces.dom.NodeImpl
  - - org.apache.xerces.dom.ChildNode
    - - org.apache.xerces.dom.ParentNode
      - - org.apache.xerces.dom.CoreDocumentImpl

- All Implemented Interfaces:
    java.io.Serializable, java.lang.Cloneable, org.w3c.dom.Document, org.w3c.dom.events.EventTarget, org.w3c.dom.Node, org.w3c.dom.NodeList
  Direct Known Subclasses:
    DocumentImpl

      public class CoreDocumentImpl
      extends ParentNode
      implements org.w3c.dom.Document

  The Document interface represents the entire HTML or XML document. Conceptually, it is the root of the document tree, and provides the primary access to the document's data.

  Since elements, text nodes, comments, processing instructions, etc. cannot exist outside the context of a Document, the Document interface also contains the factory methods needed to create these objects. The Node objects created have a ownerDocument attribute which associates them with the Document within whose context they were created.

  The CoreDocumentImpl class only implements the DOM Core. Additional modules are supported by the more complete DocumentImpl subclass.

  Note: When any node in the document is serialized, the entire document is serialized along with it.

  Since:
    PR-DOM-Level-1-19980818.
  Version:
    $Id: CoreDocumentImpl.java 950602 2010-06-02 15:39:30Z mrglavas $
  Author:
    Arnaud Le Hors, IBM, Joe Kesselman, IBM, Andy Clark, IBM, Ralf Pfeiffer, IBM
  See Also:
    Serialized Form

  # INTERNAL:

    Usage of this class is not supported. It may be altered or removed at any time.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected java.lang.String` | `actualEncoding` Experimental DOM Level 3 feature: Document actualEncoding
    `protected boolean` | `allowGrammarAccess` Allow grammar access.
    `protected int` | `changes` Number of alterations made to this document since its creation.
    `protected ElementImpl` | `docElement` Document element.
    `protected DocumentTypeImpl` | `docType` Document type.
    `protected java.lang.String` | `encoding` Experimental DOM Level 3 feature: Document encoding
    `protected boolean` | `errorChecking` Bypass error checking.
    `protected java.lang.String` | `fDocumentURI` Experimental DOM Level 3 feature: documentURI
    `protected java.util.Hashtable` | `identifiers` Identifiers.
    `protected boolean` | `standalone` Experimental DOM Level 3 feature: Document standalone
    `protected java.util.Map` | `userData` Table for user data attached to this document nodes.
    `protected java.lang.String` | `version` Experimental DOM Level 3 feature: Document version
    `protected boolean` | `xmlVersionChanged`

    - ### Fields inherited from class org.apache.xerces.dom.ParentNode

      `firstChild, fNodeListCache, ownerDocument`

    - ### Fields inherited from class org.apache.xerces.dom.ChildNode

      `nextSibling, previousSibling`

    - ### Fields inherited from class org.apache.xerces.dom.NodeImpl

      `DOCUMENT_POSITION_CONTAINS, DOCUMENT_POSITION_DISCONNECTED, DOCUMENT_POSITION_FOLLOWING, DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC, DOCUMENT_POSITION_IS_CONTAINED, DOCUMENT_POSITION_PRECEDING, ELEMENT_DEFINITION_NODE, FIRSTCHILD, flags, HASSTRING, ID, IGNORABLEWS, NORMALIZED, OWNED, ownerNode, READONLY, SPECIFIED, SYNCCHILDREN, SYNCDATA, TREE_POSITION_ANCESTOR, TREE_POSITION_DESCENDANT, TREE_POSITION_DISCONNECTED, TREE_POSITION_EQUIVALENT, TREE_POSITION_FOLLOWING, TREE_POSITION_PRECEDING, TREE_POSITION_SAME_NODE`

    - ### Fields inherited from interface org.w3c.dom.Node

      `ATTRIBUTE_NODE, CDATA_SECTION_NODE, COMMENT_NODE, DOCUMENT_FRAGMENT_NODE, DOCUMENT_NODE, DOCUMENT_POSITION_CONTAINED_BY, DOCUMENT_POSITION_CONTAINS, DOCUMENT_POSITION_DISCONNECTED, DOCUMENT_POSITION_FOLLOWING, DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC, DOCUMENT_POSITION_PRECEDING, DOCUMENT_TYPE_NODE, ELEMENT_NODE, ENTITY_NODE, ENTITY_REFERENCE_NODE, NOTATION_NODE, PROCESSING_INSTRUCTION_NODE, TEXT_NODE`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `CoreDocumentImpl()` NON-DOM: Actually creating a Document is outside the DOM's spec, since it has to operate in terms of a particular implementation.
    `CoreDocumentImpl(boolean grammarAccess)` Constructor.
    `CoreDocumentImpl(org.w3c.dom.DocumentType doctype)` For DOM2 support.
    `CoreDocumentImpl(org.w3c.dom.DocumentType doctype, boolean grammarAccess)` For DOM2 support.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `abort()` DOM Level 3 WD - Experimental.
    `protected void` | `addEventListener(NodeImpl node, java.lang.String type, org.w3c.dom.events.EventListener listener, boolean useCapture)`
    `org.w3c.dom.Node` | `adoptNode(org.w3c.dom.Node source)` DOM Level 3 WD - Experimental Change the node's ownerDocument, and its subtree, to this Document
    `protected void` | `callUserDataHandlers(org.w3c.dom.Node n, org.w3c.dom.Node c, short operation)` Call user data handlers when a node is deleted (finalized)
    `protected boolean` | `canRenameElements(java.lang.String newNamespaceURI, java.lang.String newNodeName, ElementImpl el)`
    `protected void` | `changed()` Denotes that this node has changed.
    `protected int` | `changes()` Returns the number of changes to this node.
    `protected void` | `checkDOMNSErr(java.lang.String prefix, java.lang.String namespace)`
    `protected void` | `checkNamespaceWF(java.lang.String qname, int colon1, int colon2)` Call user data handlers to let them know the nodes they are related to are being deleted.
    `protected void` | `checkQName(java.lang.String prefix, java.lang.String local)` Checks if the given qualified name is legal with respect to the version of XML to which this document must conform.
    `protected void` | `clearIdentifiers()` Remove all identifiers from the ID table
    `java.lang.Object` | `clone()` Clone.
    `org.w3c.dom.Node` | `cloneNode(boolean deep)` Deep-clone a document, including fixing ownerDoc for the cloned children.
    `protected void` | `cloneNode(CoreDocumentImpl newdoc, boolean deep)` internal method to share code with subclass
    `protected void` | `copyEventListeners(NodeImpl src, NodeImpl tgt)`
    `org.w3c.dom.Attr` | `createAttribute(java.lang.String name)` Factory method; creates an Attribute having this Document as its OwnerDoc.
    `org.w3c.dom.Attr` | `createAttributeNS(java.lang.String namespaceURI, java.lang.String qualifiedName)` Introduced in DOM Level 2.
    `org.w3c.dom.Attr` | `createAttributeNS(java.lang.String namespaceURI, java.lang.String qualifiedName, java.lang.String localpart)` NON-DOM: a factory method used by the Xerces DOM parser to create an element.
    `org.w3c.dom.CDATASection` | `createCDATASection(java.lang.String data)` Factory method; creates a CDATASection having this Document as its OwnerDoc.
    `org.w3c.dom.Comment` | `createComment(java.lang.String data)` Factory method; creates a Comment having this Document as its OwnerDoc.
    `org.w3c.dom.DocumentFragment` | `createDocumentFragment()` Factory method; creates a DocumentFragment having this Document as its OwnerDoc.
    `org.w3c.dom.DocumentType` | `createDocumentType(java.lang.String qualifiedName, java.lang.String publicID, java.lang.String systemID)` NON-DOM Factory method; creates a DocumentType having this Document as its OwnerDoc.
    `org.w3c.dom.Element` | `createElement(java.lang.String tagName)` Factory method; creates an Element having this Document as its OwnerDoc.
    `ElementDefinitionImpl` | `createElementDefinition(java.lang.String name)` NON-DOM Factory method: creates an element definition.
    `org.w3c.dom.Element` | `createElementNS(java.lang.String namespaceURI, java.lang.String qualifiedName)` Introduced in DOM Level 2.
    `org.w3c.dom.Element` | `createElementNS(java.lang.String namespaceURI, java.lang.String qualifiedName, java.lang.String localpart)` NON-DOM: a factory method used by the Xerces DOM parser to create an element.
    `org.w3c.dom.Entity` | `createEntity(java.lang.String name)` NON-DOM Factory method; creates an Entity having this Document as its OwnerDoc.
    `org.w3c.dom.EntityReference` | `createEntityReference(java.lang.String name)` Factory method; creates an EntityReference having this Document as its OwnerDoc.
    `org.w3c.dom.Notation` | `createNotation(java.lang.String name)` NON-DOM Factory method; creates a Notation having this Document as its OwnerDoc.
    `org.w3c.dom.ProcessingInstruction` | `createProcessingInstruction(java.lang.String target, java.lang.String data)` Factory method; creates a ProcessingInstruction having this Document as its OwnerDoc.
    `org.w3c.dom.Text` | `createTextNode(java.lang.String data)` Factory method; creates a Text node having this Document as its OwnerDoc.
    `protected boolean` | `dispatchEvent(NodeImpl node, org.w3c.dom.events.Event event)`
    `boolean` | `getAsync()` DOM Level 3 WD - Experimental.
    `java.lang.String` | `getBaseURI()` Returns the absolute base URI of this node or null if the implementation wasn't able to obtain an absolute URI.
    `org.w3c.dom.DocumentType` | `getDoctype()` For XML, this provides access to the Document Type Definition.
    `org.w3c.dom.Element` | `getDocumentElement()` Convenience method, allowing direct access to the child node which is considered the root of the actual document content.
    `java.lang.String` | `getDocumentURI()` DOM Level 3 WD - Experimental.
    `org.w3c.dom.DOMConfiguration` | `getDomConfig()` DOM Level 3 CR - Experimental The configuration used when `Document.normalizeDocument` is invoked.
    `org.w3c.dom.Element` | `getElementById(java.lang.String elementId)` Introduced in DOM Level 2 Returns the Element whose ID is given by elementId.
    `org.w3c.dom.NodeList` | `getElementsByTagName(java.lang.String tagname)` Return a live collection of all descendent Elements (not just immediate children) having the specified tag name.
    `org.w3c.dom.NodeList` | `getElementsByTagNameNS(java.lang.String namespaceURI, java.lang.String localName)` Introduced in DOM Level 2.
    `java.lang.String` | `getEncoding()` Deprecated. This method is internal and only exists for compatibility with older applications. New applications should never call this method.
    `boolean` | `getErrorChecking()` Returns true if the DOM implementation performs error checking.
    `java.lang.Object` | `getFeature(java.lang.String feature, java.lang.String version)` This method returns a specialized object which implements the specialized APIs of the specified feature and version, as specified in .
    `org.w3c.dom.Element` | `getIdentifier(java.lang.String idName)` Returns a previously registered element with the specified identifier name, or null if no element is registered.
    `java.util.Enumeration` | `getIdentifiers()` Returns an enumeration registered of identifier names.
    `org.w3c.dom.DOMImplementation` | `getImplementation()` Retrieve information describing the abilities of this particular DOM implementation.
    `java.lang.String` | `getInputEncoding()` DOM Level 3 CR - Experimental.
    `java.lang.String` | `getNodeName()` Returns the node name.
    `protected int` | `getNodeNumber()` NON-DOM: Get the number associated with this document.
    `protected int` | `getNodeNumber(org.w3c.dom.Node node)` NON-DOM: Get a number associated with a node created with respect to this document.
    `short` | `getNodeType()` Returns the node type.
    `org.w3c.dom.Document` | `getOwnerDocument()` Find the Document that this Node belongs to (the document in whose context the Node was created).
    `boolean` | `getStandalone()` Deprecated. This method is internal and only exists for compatibility with older applications. New applications should never call this method.
    `boolean` | `getStrictErrorChecking()` An attribute specifying whether error checking is enforced or not.
    `java.lang.String` | `getTextContent()` This attribute returns the text content of this node and its descendants.
    `protected java.lang.Object` | `getUserData(NodeImpl n)` NON-DOM: kept for backward compatibility Retreive user data related to a given node
    `java.lang.Object` | `getUserData(org.w3c.dom.Node n, java.lang.String key)` Retrieves the object associated to a key on a this node.
    `protected java.util.Hashtable` | `getUserDataRecord(org.w3c.dom.Node n)`
    `java.lang.String` | `getVersion()` Deprecated. This method is internal and only exists for compatibility with older applications. New applications should never call this method.
    `java.lang.String` | `getXmlEncoding()` DOM Level 3 WD - Experimental.
    `boolean` | `getXmlStandalone()` DOM Level 3 WD - Experimental.
    `java.lang.String` | `getXmlVersion()` DOM Level 3 WD - Experimental.
    `org.w3c.dom.Node` | `importNode(org.w3c.dom.Node source, boolean deep)` Copies a node from another document to this document.
    `org.w3c.dom.Node` | `insertBefore(org.w3c.dom.Node newChild, org.w3c.dom.Node refChild)` Since a Document may contain at most one top-level Element child, and at most one DocumentType declaraction, we need to subclass our add-children methods to implement this constraint.
    `protected boolean` | `isKidOK(org.w3c.dom.Node parent, org.w3c.dom.Node child)` Uses the kidOK lookup table to check whether the proposed tree structure is legal.
    `static boolean` | `isValidQName(java.lang.String prefix, java.lang.String local, boolean xml11Version)` Checks if the given qualified name is legal with respect to the version of XML to which this document must conform.
    `static boolean` | `isXMLName(java.lang.String s, boolean xml11Version)` Check the string against XML's definition of acceptable names for elements and attributes and so on using the XMLCharacterProperties utility class
    `boolean` | `load(java.lang.String uri)` DOM Level 3 WD - Experimental.
    `boolean` | `loadXML(java.lang.String source)` DOM Level 3 WD - Experimental.
    `void` | `normalizeDocument()` DOM Level 3 WD - Experimental Normalize document.
    `void` | `putIdentifier(java.lang.String idName, org.w3c.dom.Element element)` Registers an identifier name with a specified element node.
    `org.w3c.dom.Node` | `removeChild(org.w3c.dom.Node oldChild)` Since insertBefore caches the docElement (and, currently, docType), removeChild has to know how to undo the cache REVISIT: According to the spec it is not allowed to alter neither the document element nor the document type in any way
    `protected void` | `removeEventListener(NodeImpl node, java.lang.String type, org.w3c.dom.events.EventListener listener, boolean useCapture)`
    `void` | `removeIdentifier(java.lang.String idName)` Removes a previously registered element with the specified identifier name.
    `org.w3c.dom.Node` | `renameNode(org.w3c.dom.Node n, java.lang.String namespaceURI, java.lang.String name)` DOM Level 3 WD - Experimental.
    `org.w3c.dom.Node` | `replaceChild(org.w3c.dom.Node newChild, org.w3c.dom.Node oldChild)` Since we cache the docElement (and, currently, docType), replaceChild has to update the cache REVISIT: According to the spec it is not allowed to alter neither the document element nor the document type in any way
    `java.lang.String` | `saveXML(org.w3c.dom.Node node)` DOM Level 3 WD - Experimental.
    `void` | `setAsync(boolean async)` DOM Level 3 WD - Experimental.
    `void` | `setDocumentURI(java.lang.String documentURI)` DOM Level 3 WD - Experimental.
    `void` | `setEncoding(java.lang.String value)` Deprecated. This method is internal and only exists for compatibility with older applications. New applications should never call this method.
    `void` | `setErrorChecking(boolean check)` Sets whether the DOM implementation performs error checking upon operations.
    `void` | `setInputEncoding(java.lang.String value)` DOM Internal (Was a DOM L3 Core WD public interface method setActualEncoding ) An attribute specifying the actual encoding of this document.
    `void` | `setStandalone(boolean value)` Deprecated. This method is internal and only exists for compatibility with older applications. New applications should never call this method.
    `void` | `setStrictErrorChecking(boolean check)` An attribute specifying whether error checking is enforced or not.
    `void` | `setTextContent(java.lang.String textContent)` This attribute returns the text content of this node and its descendants.
    `protected void` | `setUserData(NodeImpl n, java.lang.Object data)` NON-DOM: kept for backward compatibility Store user data related to a given node This is a place where we could use weak references! Indeed, the node here won't be GC'ed as long as some user data is attached to it, since the userData table will have a reference to the node.
    `java.lang.Object` | `setUserData(org.w3c.dom.Node n, java.lang.String key, java.lang.Object data, org.w3c.dom.UserDataHandler handler)` Associate an object to a key on this node.
    `void` | `setVersion(java.lang.String value)` Deprecated. This method is internal and only exists for compatibility with older applications. New applications should never call this method.
    `void` | `setXmlEncoding(java.lang.String value)` DOM Internal (Was a DOM L3 Core WD public interface method setXMLEncoding ) An attribute specifying, as part of the XML declaration, the encoding of this document.
    `void` | `setXmlStandalone(boolean value)` DOM Level 3 CR - Experimental.
    `void` | `setXmlVersion(java.lang.String value)` DOM Level 3 CR - Experimental.
    `protected void` | `undeferChildren(org.w3c.dom.Node node)` Traverses the DOM Tree and expands deferred nodes and their children.

    - ### Methods inherited from class org.apache.xerces.dom.ParentNode

      `getChildNodes, getChildNodesUnoptimized, getFirstChild, getLastChild, getLength, hasChildNodes, isEqualNode, item, normalize, setOwnerDocument, setReadOnly, synchronizeChildren`

    - ### Methods inherited from class org.apache.xerces.dom.ChildNode

      `getNextSibling, getParentNode, getPreviousSibling`

    - ### Methods inherited from class org.apache.xerces.dom.NodeImpl

      `addEventListener, appendChild, compareDocumentPosition, compareTreePosition, dispatchEvent, getAttributes, getContainer, getLocalName, getNamespaceURI, getNodeValue, getPrefix, getReadOnly, getUserData, getUserData, getUserDataRecord, hasAttributes, isDefaultNamespace, isSameNode, isSupported, lookupNamespaceURI, lookupPrefix, needsSyncChildren, removeEventListener, setNodeValue, setPrefix, setUserData, setUserData, synchronizeData, toString`

    - ### Methods inherited from class java.lang.Object

      `equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

    - ### Methods inherited from interface org.w3c.dom.Node

      `appendChild, compareDocumentPosition, getAttributes, getChildNodes, getFirstChild, getLastChild, getLocalName, getNamespaceURI, getNextSibling, getNodeValue, getParentNode, getPrefix, getPreviousSibling, getUserData, hasAttributes, hasChildNodes, isDefaultNamespace, isEqualNode, isSameNode, isSupported, lookupNamespaceURI, lookupPrefix, normalize, setNodeValue, setPrefix, setUserData`

- - ### Field Detail

    - #### docType

          protected DocumentTypeImpl docType

      Document type.

    - #### docElement

          protected ElementImpl docElement

      Document element.

    - #### encoding

          protected java.lang.String encoding

      Experimental DOM Level 3 feature: Document encoding

    - #### actualEncoding

          protected java.lang.String actualEncoding

      Experimental DOM Level 3 feature: Document actualEncoding

    - #### version

          protected java.lang.String version

      Experimental DOM Level 3 feature: Document version

    - #### standalone

          protected boolean standalone

      Experimental DOM Level 3 feature: Document standalone

    - #### fDocumentURI

          protected java.lang.String fDocumentURI

      Experimental DOM Level 3 feature: documentURI

    - #### userData

          protected java.util.Map userData

      Table for user data attached to this document nodes.

    - #### identifiers

          protected java.util.Hashtable identifiers

      Identifiers.

    - #### changes

          protected int changes

      Number of alterations made to this document since its creation. Serves as a "dirty bit" so that live objects such as NodeList can recognize when an alteration has been made and discard its cached state information.

      Any method that alters the tree structure MUST cause or be accompanied by a call to changed(), to inform it that any outstanding NodeLists may have to be updated.

      (Required because NodeList is simultaneously "live" and integer- indexed -- a bad decision in the DOM's design.)

      Note that changes which do not affect the tree's structure -- changing the node's name, for example -- do _not_ have to call changed().

      Alternative implementation would be to use a cryptographic Digest value rather than a count. This would have the advantage that "harmless" changes (those producing equal() trees) would not force NodeList to resynchronize. Disadvantage is that it's slightly more prone to "false negatives", though that's the difference between "wildly unlikely" and "absurdly unlikely". IF we start maintaining digests, we should consider taking advantage of them. Note: This used to be done a node basis, so that we knew what subtree changed. But since only DeepNodeList really use this today, the gain appears to be really small compared to the cost of having an int on every (parent) node plus having to walk up the tree all the way to the root to mark the branch as changed everytime a node is changed. So we now have a single counter global to the document. It means that some objects may flush their cache more often than necessary, but this makes nodes smaller and only the document needs to be marked as changed.

    - #### allowGrammarAccess

          protected boolean allowGrammarAccess

      Allow grammar access.

    - #### errorChecking

          protected boolean errorChecking

      Bypass error checking.

    - #### xmlVersionChanged

          protected boolean xmlVersionChanged

  - ### Constructor Detail

    - #### CoreDocumentImpl

          public CoreDocumentImpl()

      NON-DOM: Actually creating a Document is outside the DOM's spec, since it has to operate in terms of a particular implementation.

    - #### CoreDocumentImpl

          public CoreDocumentImpl(boolean grammarAccess)

      Constructor.

    - #### CoreDocumentImpl

          public CoreDocumentImpl(org.w3c.dom.DocumentType doctype)

      For DOM2 support. The createDocument factory method is in DOMImplementation.

    - #### CoreDocumentImpl

          public CoreDocumentImpl(org.w3c.dom.DocumentType doctype,
                          boolean grammarAccess)

      For DOM2 support.

  - ### Method Detail

    - #### getOwnerDocument

          public final org.w3c.dom.Document getOwnerDocument()

      Description copied from class: `ParentNode`
      Find the Document that this Node belongs to (the document in whose context the Node was created). The Node may or may not currently be part of that Document's actual contents.
      Specified by:
        `getOwnerDocument` in interface `org.w3c.dom.Node`
      Overrides:
        `getOwnerDocument` in class `ParentNode`

    - #### getNodeType

          public short getNodeType()

      Returns the node type.
      Specified by:
        `getNodeType` in interface `org.w3c.dom.Node`
      Specified by:
        `getNodeType` in class `NodeImpl`

    - #### getNodeName

          public java.lang.String getNodeName()

      Returns the node name.
      Specified by:
        `getNodeName` in interface `org.w3c.dom.Node`
      Specified by:
        `getNodeName` in class `NodeImpl`

    - #### cloneNode

          public org.w3c.dom.Node cloneNode(boolean deep)

      Deep-clone a document, including fixing ownerDoc for the cloned children. Note that this requires bypassing the WRONG_DOCUMENT_ERR protection. I've chosen to implement it by calling importNode which is DOM Level 2.
      Specified by:
        `cloneNode` in interface `org.w3c.dom.Node`
      Overrides:
        `cloneNode` in class `ParentNode`
      Parameters:
        `deep` - boolean, iff true replicate children
      Returns:
        org.w3c.dom.Node
      See Also:
        `

        Example: Cloning a Text node will copy both the node and the text it contains.

        Example: Cloning something that has children -- Element or Attr, for example -- will _not_ clone those children unless a "deep clone" has been requested. A shallow clone of an Attr node will yield an empty Attr of the same name.

        NOTE: Clones will always be read/write, even if the node being cloned is read-only, to permit applications using only the DOM API to obtain editable copies of locked portions of the tree.

        `

    - #### cloneNode

          protected void cloneNode(CoreDocumentImpl newdoc,
                       boolean deep)

      internal method to share code with subclass

    - #### insertBefore

          public org.w3c.dom.Node insertBefore(org.w3c.dom.Node newChild,
                                      org.w3c.dom.Node refChild)
                                        throws org.w3c.dom.DOMException

      Since a Document may contain at most one top-level Element child, and at most one DocumentType declaraction, we need to subclass our add-children methods to implement this constraint. Since appendChild() is implemented as insertBefore(,null), altering the latter fixes both.

      While I'm doing so, I've taken advantage of the opportunity to cache documentElement and docType so we don't have to search for them. REVISIT: According to the spec it is not allowed to alter neither the document element nor the document type in any way

      Specified by:
        `insertBefore` in interface `org.w3c.dom.Node`
      Overrides:
        `insertBefore` in class `ParentNode`
      Parameters:
        `newChild` - The Node to be moved to our subtree. As a convenience feature, inserting a DocumentNode will instead insert all its children.
        `refChild` - Current child which newChild should be placed immediately before. If refChild is null, the insertion occurs after all existing Nodes, like appendChild().
      Returns:
        newChild, in its new state (relocated, or emptied in the case of DocumentNode.)
      Throws:
        `org.w3c.dom.DOMException` - HIERARCHY_REQUEST_ERR: Raised if this node is of a type that does not allow children of the type of the `newChild` node, or if the node to insert is one of this node's ancestors or this node itself, or if this node is of type `Document` and the DOM application attempts to insert a second `DocumentType` or `Element` node.
        WRONG_DOCUMENT_ERR: Raised if `newChild` was created from a different document than the one that created this node.
        NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly or if the parent of the node being inserted is readonly.
        NOT_FOUND_ERR: Raised if `refChild` is not a child of this node.
        NOT_SUPPORTED_ERR: if this node is of type `Document`, this exception might be raised if the DOM implementation doesn't support the insertion of a `DocumentType` or `Element` node.
      See Also:
        `ParentNode`

    - #### removeChild

          public org.w3c.dom.Node removeChild(org.w3c.dom.Node oldChild)
                                       throws org.w3c.dom.DOMException

      Since insertBefore caches the docElement (and, currently, docType), removeChild has to know how to undo the cache REVISIT: According to the spec it is not allowed to alter neither the document element nor the document type in any way
      Specified by:
        `removeChild` in interface `org.w3c.dom.Node`
      Overrides:
        `removeChild` in class `ParentNode`
      Parameters:
        `oldChild` - The node being removed.
      Returns:
        oldChild, in its new state (removed).
      Throws:
        `org.w3c.dom.DOMException` - NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
        NOT_FOUND_ERR: Raised if `oldChild` is not a child of this node.
        NOT_SUPPORTED_ERR: if this node is of type `Document`, this exception might be raised if the DOM implementation doesn't support the removal of the `DocumentType` child or the `Element` child.
      See Also:
        `ParentNode`

    - #### replaceChild

          public org.w3c.dom.Node replaceChild(org.w3c.dom.Node newChild,
                                      org.w3c.dom.Node oldChild)
                                        throws org.w3c.dom.DOMException

      Since we cache the docElement (and, currently, docType), replaceChild has to update the cache REVISIT: According to the spec it is not allowed to alter neither the document element nor the document type in any way
      Specified by:
        `replaceChild` in interface `org.w3c.dom.Node`
      Overrides:
        `replaceChild` in class `ParentNode`
      Parameters:
        `newChild` - The new node to put in the child list.
        `oldChild` - The node being replaced in the list.
      Returns:
        oldChild, in its new state (removed).
      Throws:
        `org.w3c.dom.DOMException` - HIERARCHY_REQUEST_ERR: Raised if this node is of a type that does not allow children of the type of the `newChild` node, or if the node to put in is one of this node's ancestors or this node itself, or if this node is of type `Document` and the result of the replacement operation would add a second `DocumentType` or `Element` on the `Document` node.
        WRONG_DOCUMENT_ERR: Raised if `newChild` was created from a different document than the one that created this node.
        NO_MODIFICATION_ALLOWED_ERR: Raised if this node or the parent of the new node is readonly.
        NOT_FOUND_ERR: Raised if `oldChild` is not a child of this node.
        NOT_SUPPORTED_ERR: if this node is of type `Document`, this exception might be raised if the DOM implementation doesn't support the replacement of the `DocumentType` child or `Element` child.
      See Also:
        `ParentNode`

    - #### getTextContent

          public java.lang.String getTextContent()
                                          throws org.w3c.dom.DOMException

      Description copied from class: `NodeImpl`
      This attribute returns the text content of this node and its descendants. When it is defined to be null, setting it has no effect. When set, any possible children this node may have are removed and replaced by a single `Text` node containing the string this attribute is set to. On getting, no serialization is performed, the returned string does not contain any markup. No whitespace normalization is performed, the returned string does not contain the element content whitespaces . Similarly, on setting, no parsing is performed either, the input string is taken as pure textual content.
      The string returned is made of the text content of this node depending on its type, as defined below:

      Node type | Content
      --- | ---
      /** This attribute returns the text content of this node and its descendants. When it is defined to be null, setting it has no effect. When set, any possible children this node may have are removed and replaced by a single `Text` node containing the string this attribute is set to. On getting, no serialization is performed, the returned string does not contain any markup. No whitespace normalization is performed, the returned string does not contain the element content whitespaces . Similarly, on setting, no parsing is performed either, the input string is taken as pure textual content.
      The string returned is made of the text content of this node depending on its type, as defined below:

      Node type | Content
      --- | ---
      ELEMENT_NODE, ENTITY_NODE, ENTITY_REFERENCE_NODE, DOCUMENT_FRAGMENT_NODE | concatenation of the `textContent` attribute value of every child node, excluding COMMENT_NODE and PROCESSING_INSTRUCTION_NODE nodes
      ATTRIBUTE_NODE, TEXT_NODE, CDATA_SECTION_NODE, COMMENT_NODE, PROCESSING_INSTRUCTION_NODE | `nodeValue`
      DOCUMENT_NODE, DOCUMENT_TYPE_NODE, NOTATION_NODE | null

      Specified by:
        `getTextContent` in interface `org.w3c.dom.Node`
      Overrides:
        `getTextContent` in class `ParentNode`
      Throws:
        `org.w3c.dom.DOMException` - NO_MODIFICATION_ALLOWED_ERR: Raised when the node is readonly.

    - #### setTextContent

          public void setTextContent(java.lang.String textContent)
                              throws org.w3c.dom.DOMException

      Description copied from class: `NodeImpl`
      This attribute returns the text content of this node and its descendants. When it is defined to be null, setting it has no effect. When set, any possible children this node may have are removed and replaced by a single `Text` node containing the string this attribute is set to. On getting, no serialization is performed, the returned string does not contain any markup. No whitespace normalization is performed, the returned string does not contain the element content whitespaces . Similarly, on setting, no parsing is performed either, the input string is taken as pure textual content.
      The string returned is made of the text content of this node depending on its type, as defined below:

      Node type | Content
      --- | ---
      ELEMENT_NODE, ENTITY_NODE, ENTITY_REFERENCE_NODE, DOCUMENT_FRAGMENT_NODE | concatenation of the `textContent` attribute value of every child node, excluding COMMENT_NODE and PROCESSING_INSTRUCTION_NODE nodes
      ATTRIBUTE_NODE, TEXT_NODE, CDATA_SECTION_NODE, COMMENT_NODE, PROCESSING_INSTRUCTION_NODE | `nodeValue`
      DOCUMENT_NODE, DOCUMENT_TYPE_NODE, NOTATION_NODE | null

      Specified by:
        `setTextContent` in interface `org.w3c.dom.Node`
      Overrides:
        `setTextContent` in class `ParentNode`
      Throws:
        `org.w3c.dom.DOMException` - NO_MODIFICATION_ALLOWED_ERR: Raised when the node is readonly.

    - #### getFeature

          public java.lang.Object getFeature(java.lang.String feature,
                                    java.lang.String version)

      Description copied from interface: `org.w3c.dom.Node`
      This method returns a specialized object which implements the specialized APIs of the specified feature and version, as specified in . The specialized object may also be obtained by using binding-specific casting methods but is not necessarily expected to, as discussed in . This method also allow the implementation to provide specialized objects which do not support the `Node` interface.
      Specified by:
        `getFeature` in interface `org.w3c.dom.Node`
      Overrides:
        `getFeature` in class `NodeImpl`
      Parameters:
        `feature` - The name of the feature requested. Note that any plus sign "+" prepended to the name of the feature will be ignored since it is not significant in the context of this method.
        `version` - This is the version number of the feature to test.
      Returns:
        Returns an object which implements the specialized APIs of the specified feature and version, if any, or `null` if there is no object which implements interfaces associated with that feature. If the `DOMObject` returned by this method implements the `Node` interface, it must delegate to the primary core `Node` and not return results inconsistent with the primary core `Node` such as attributes, childNodes, etc.
      Since:
        DOM Level 3

    - #### createAttribute

          public org.w3c.dom.Attr createAttribute(java.lang.String name)
                                           throws org.w3c.dom.DOMException

      Factory method; creates an Attribute having this Document as its OwnerDoc.
      Specified by:
        `createAttribute` in interface `org.w3c.dom.Document`
      Parameters:
        `name` - The name of the attribute. Note that the attribute's value is _not_ established at the factory; remember to set it!
      Returns:
        A new `Attr` object with the `nodeName` attribute set to `name`, and `localName`, `prefix`, and `namespaceURI` set to `null`. The value of the attribute is the empty string.
      Throws:
        `DOMException(INVALID_NAME_ERR)` - if the attribute name is not acceptable.
        `org.w3c.dom.DOMException` - INVALID_CHARACTER_ERR: Raised if the specified name is not an XML name according to the XML version in use specified in the `Document.xmlVersion` attribute.

    - #### createCDATASection

          public org.w3c.dom.CDATASection createCDATASection(java.lang.String data)
                                                      throws org.w3c.dom.DOMException

      Factory method; creates a CDATASection having this Document as its OwnerDoc.
      Specified by:
        `createCDATASection` in interface `org.w3c.dom.Document`
      Parameters:
        `data` - The initial contents of the CDATA
      Returns:
        The new `CDATASection` object.
      Throws:
        `DOMException(NOT_SUPPORTED_ERR)` - for HTML documents. (HTML not yet implemented.)
        `org.w3c.dom.DOMException` - NOT_SUPPORTED_ERR: Raised if this document is an HTML document.

    - #### createComment

          public org.w3c.dom.Comment createComment(java.lang.String data)

      Factory method; creates a Comment having this Document as its OwnerDoc.
      Specified by:
        `createComment` in interface `org.w3c.dom.Document`
      Parameters:
        `data` - The initial contents of the Comment.
      Returns:
        The new `Comment` object.

    - #### createDocumentFragment

          public org.w3c.dom.DocumentFragment createDocumentFragment()

      Factory method; creates a DocumentFragment having this Document as its OwnerDoc.
      Specified by:
        `createDocumentFragment` in interface `org.w3c.dom.Document`
      Returns:
        A new `DocumentFragment`.

    - #### createElement

          public org.w3c.dom.Element createElement(java.lang.String tagName)
                                            throws org.w3c.dom.DOMException

      Factory method; creates an Element having this Document as its OwnerDoc.
      Specified by:
        `createElement` in interface `org.w3c.dom.Document`
      Parameters:
        `tagName` - The name of the element type to instantiate. For XML, this is case-sensitive. For HTML, the tagName parameter may be provided in any case, but it must be mapped to the canonical uppercase form by the DOM implementation.
      Returns:
        A new `Element` object with the `nodeName` attribute set to `tagName`, and `localName`, `prefix`, and `namespaceURI` set to `null`.
      Throws:
        `DOMException(INVALID_NAME_ERR)` - if the tag name is not acceptable.
        `org.w3c.dom.DOMException` - INVALID_CHARACTER_ERR: Raised if the specified name is not an XML name according to the XML version in use specified in the `Document.xmlVersion` attribute.

    - #### createEntityReference

          public org.w3c.dom.EntityReference createEntityReference(java.lang.String name)
                                                            throws org.w3c.dom.DOMException

      Factory method; creates an EntityReference having this Document as its OwnerDoc.
      Specified by:
        `createEntityReference` in interface `org.w3c.dom.Document`
      Parameters:
        `name` - The name of the Entity we wish to refer to
      Returns:
        The new `EntityReference` object.
      Throws:
        `DOMException(NOT_SUPPORTED_ERR)` - for HTML documents, where nonstandard entities are not permitted. (HTML not yet implemented.)
        `org.w3c.dom.DOMException` - INVALID_CHARACTER_ERR: Raised if the specified name is not an XML name according to the XML version in use specified in the `Document.xmlVersion` attribute.
        NOT_SUPPORTED_ERR: Raised if this document is an HTML document.

    - #### createProcessingInstruction

          public org.w3c.dom.ProcessingInstruction createProcessingInstruction(java.lang.String target,
                                                                      java.lang.String data)
                                                                        throws org.w3c.dom.DOMException

      Factory method; creates a ProcessingInstruction having this Document as its OwnerDoc.
      Specified by:
        `createProcessingInstruction` in interface `org.w3c.dom.Document`
      Parameters:
        `target` - The target "processor channel"
        `data` - Parameter string to be passed to the target.
      Returns:
        The new `ProcessingInstruction` object.
      Throws:
        `DOMException(INVALID_NAME_ERR)` - if the target name is not acceptable.
        `DOMException(NOT_SUPPORTED_ERR)` - for HTML documents. (HTML not yet implemented.)
        `org.w3c.dom.DOMException` - INVALID_CHARACTER_ERR: Raised if the specified target is not an XML name according to the XML version in use specified in the `Document.xmlVersion` attribute.
        NOT_SUPPORTED_ERR: Raised if this document is an HTML document.

    - #### createTextNode

          public org.w3c.dom.Text createTextNode(java.lang.String data)

      Factory method; creates a Text node having this Document as its OwnerDoc.
      Specified by:
        `createTextNode` in interface `org.w3c.dom.Document`
      Parameters:
        `data` - The initial contents of the Text.
      Returns:
        The new `Text` object.

    - #### getDoctype

          public org.w3c.dom.DocumentType getDoctype()

      For XML, this provides access to the Document Type Definition. For HTML documents, and XML documents which don't specify a DTD, it will be null.
      Specified by:
        `getDoctype` in interface `org.w3c.dom.Document`

    - #### getDocumentElement

          public org.w3c.dom.Element getDocumentElement()

      Convenience method, allowing direct access to the child node which is considered the root of the actual document content. For HTML, where it is legal to have more than one Element at the top level of the document, we pick the one with the tagName "HTML". For XML there should be only one top-level (HTML not yet supported.)
      Specified by:
        `getDocumentElement` in interface `org.w3c.dom.Document`

    - #### getElementsByTagName

          public org.w3c.dom.NodeList getElementsByTagName(java.lang.String tagname)

      Return a live collection of all descendent Elements (not just immediate children) having the specified tag name.
      Specified by:
        `getElementsByTagName` in interface `org.w3c.dom.Document`
      Parameters:
        `tagname` - The type of Element we want to gather. "*" will be taken as a wildcard, meaning "all elements in the document."
      Returns:
        A new `NodeList` object containing all the matched `Elements`.
      See Also:
        `DeepNodeListImpl`

    - #### getImplementation

          public org.w3c.dom.DOMImplementation getImplementation()

      Retrieve information describing the abilities of this particular DOM implementation. Intended to support applications that may be using DOMs retrieved from several different sources, potentially with different underlying representations.
      Specified by:
        `getImplementation` in interface `org.w3c.dom.Document`

    - #### setErrorChecking

          public void setErrorChecking(boolean check)

      Sets whether the DOM implementation performs error checking upon operations. Turning off error checking only affects the following DOM checks:
      - Checking strings to make sure that all characters are legal XML characters
      - Hierarchy checking such as allowed children, checks for cycles, etc.

      Turning off error checking does not turn off the following checks:

      - Read only checks
      - Checks related to DOM events

    - #### setStrictErrorChecking

          public void setStrictErrorChecking(boolean check)

      Description copied from interface: `org.w3c.dom.Document`
      An attribute specifying whether error checking is enforced or not. When set to `false`, the implementation is free to not test every possible error case normally defined on DOM operations, and not raise any `DOMException` on DOM operations or report errors while using `Document.normalizeDocument()`. In case of error, the behavior is undefined. This attribute is `true` by default.
      Specified by:
        `setStrictErrorChecking` in interface `org.w3c.dom.Document`

    - #### getErrorChecking

          public boolean getErrorChecking()

      Returns true if the DOM implementation performs error checking.

    - #### getStrictErrorChecking

          public boolean getStrictErrorChecking()

      Description copied from interface: `org.w3c.dom.Document`
      An attribute specifying whether error checking is enforced or not. When set to `false`, the implementation is free to not test every possible error case normally defined on DOM operations, and not raise any `DOMException` on DOM operations or report errors while using `Document.normalizeDocument()`. In case of error, the behavior is undefined. This attribute is `true` by default.
      Specified by:
        `getStrictErrorChecking` in interface `org.w3c.dom.Document`

    - #### getInputEncoding

          public java.lang.String getInputEncoding()

      DOM Level 3 CR - Experimental. (Was getActualEncoding) An attribute specifying the encoding used for this document at the time of the parsing. This is `null` when it is not known, such as when the `Document` was created in memory.
      Specified by:
        `getInputEncoding` in interface `org.w3c.dom.Document`
      Since:
        DOM Level 3

    - #### setInputEncoding

          public void setInputEncoding(java.lang.String value)

      DOM Internal (Was a DOM L3 Core WD public interface method setActualEncoding ) An attribute specifying the actual encoding of this document. This is `null` otherwise.
      This attribute represents the property [character encoding scheme] defined in .

    - #### setXmlEncoding

          public void setXmlEncoding(java.lang.String value)

      DOM Internal (Was a DOM L3 Core WD public interface method setXMLEncoding ) An attribute specifying, as part of the XML declaration, the encoding of this document. This is null when unspecified.

    - #### setEncoding

          public void setEncoding(java.lang.String value)

      Deprecated. This method is internal and only exists for compatibility with older applications. New applications should never call this method.

    - #### getXmlEncoding

          public java.lang.String getXmlEncoding()

      DOM Level 3 WD - Experimental. The encoding of this document (part of XML Declaration)
      Specified by:
        `getXmlEncoding` in interface `org.w3c.dom.Document`

    - #### getEncoding

          public java.lang.String getEncoding()

      Deprecated. This method is internal and only exists for compatibility with older applications. New applications should never call this method.

    - #### setXmlVersion

          public void setXmlVersion(java.lang.String value)

      DOM Level 3 CR - Experimental. version - An attribute specifying, as part of the XML declaration, the version number of this document.
      Specified by:
        `setXmlVersion` in interface `org.w3c.dom.Document`

    - #### setVersion

          public void setVersion(java.lang.String value)

      Deprecated. This method is internal and only exists for compatibility with older applications. New applications should never call this method.

    - #### getXmlVersion

          public java.lang.String getXmlVersion()

      DOM Level 3 WD - Experimental. The version of this document (part of XML Declaration)
      Specified by:
        `getXmlVersion` in interface `org.w3c.dom.Document`

    - #### getVersion

          public java.lang.String getVersion()

      Deprecated. This method is internal and only exists for compatibility with older applications. New applications should never call this method.

    - #### setXmlStandalone

          public void setXmlStandalone(boolean value)
                                throws org.w3c.dom.DOMException

      DOM Level 3 CR - Experimental. Xmlstandalone - An attribute specifying, as part of the XML declaration, whether this document is standalone
      Specified by:
        `setXmlStandalone` in interface `org.w3c.dom.Document`
      Throws:
        `org.w3c.dom.DOMException` - NOT_SUPPORTED_ERR: Raised if this document does not support the "XML" feature.
      Since:
        DOM Level 3

    - #### setStandalone

          public void setStandalone(boolean value)

      Deprecated. This method is internal and only exists for compatibility with older applications. New applications should never call this method.

    - #### getXmlStandalone

          public boolean getXmlStandalone()

      DOM Level 3 WD - Experimental. standalone that specifies whether this document is standalone (part of XML Declaration)
      Specified by:
        `getXmlStandalone` in interface `org.w3c.dom.Document`

    - #### getStandalone

          public boolean getStandalone()

      Deprecated. This method is internal and only exists for compatibility with older applications. New applications should never call this method.

    - #### getDocumentURI

          public java.lang.String getDocumentURI()

      DOM Level 3 WD - Experimental. The location of the document or `null` if undefined.
      Beware that when the `Document` supports the feature "HTML" , the href attribute of the HTML BASE element takes precedence over this attribute.
      Specified by:
        `getDocumentURI` in interface `org.w3c.dom.Document`
      Since:
        DOM Level 3

    - #### canRenameElements

          protected boolean canRenameElements(java.lang.String newNamespaceURI,
                                  java.lang.String newNodeName,
                                  ElementImpl el)

    - #### renameNode

          public org.w3c.dom.Node renameNode(org.w3c.dom.Node n,
                                    java.lang.String namespaceURI,
                                    java.lang.String name)
                                      throws org.w3c.dom.DOMException

      DOM Level 3 WD - Experimental. Renaming node
      Specified by:
        `renameNode` in interface `org.w3c.dom.Document`
      Parameters:
        `n` - The node to rename.
        `namespaceURI` - The new namespace URI.
        `name` - The new qualified name.
      Returns:
        The renamed node. This is either the specified node or the new node that was created to replace the specified node.
      Throws:
        `org.w3c.dom.DOMException` - NOT_SUPPORTED_ERR: Raised when the type of the specified node is neither `ELEMENT_NODE` nor `ATTRIBUTE_NODE`, or if the implementation does not support the renaming of the document element.
        INVALID_CHARACTER_ERR: Raised if the new qualified name is not an XML name according to the XML version in use specified in the `Document.xmlVersion` attribute.
        WRONG_DOCUMENT_ERR: Raised when the specified node was created from a different document than this document.
        NAMESPACE_ERR: Raised if the `qualifiedName` is a malformed qualified name, if the `qualifiedName` has a prefix and the `namespaceURI` is `null`, or if the `qualifiedName` has a prefix that is "xml" and the `namespaceURI` is different from " http://www.w3.org/XML/1998/namespace" [XML Namespaces] . Also raised, when the node being renamed is an attribute, if the `qualifiedName`, or its prefix, is "xmlns" and the `namespaceURI` is different from "http://www.w3.org/2000/xmlns/".

    - #### normalizeDocument

          public void normalizeDocument()

      DOM Level 3 WD - Experimental Normalize document.
      Specified by:
        `normalizeDocument` in interface `org.w3c.dom.Document`

    - #### getDomConfig

          public org.w3c.dom.DOMConfiguration getDomConfig()

      DOM Level 3 CR - Experimental The configuration used when `Document.normalizeDocument` is invoked.
      Specified by:
        `getDomConfig` in interface `org.w3c.dom.Document`
      Since:
        DOM Level 3

    - #### getBaseURI

          public java.lang.String getBaseURI()

      Returns the absolute base URI of this node or null if the implementation wasn't able to obtain an absolute URI. Note: If the URI is malformed, a null is returned.
      Specified by:
        `getBaseURI` in interface `org.w3c.dom.Node`
      Overrides:
        `getBaseURI` in class `NodeImpl`
      Returns:
        The absolute base URI of this node or null.
      Since:
        DOM Level 3

    - #### setDocumentURI

          public void setDocumentURI(java.lang.String documentURI)

      DOM Level 3 WD - Experimental.
      Specified by:
        `setDocumentURI` in interface `org.w3c.dom.Document`

    - #### getAsync

          public boolean getAsync()

      DOM Level 3 WD - Experimental. Indicates whether the method load should be synchronous or asynchronous. When the async attribute is set to `true` the load method returns control to the caller before the document has completed loading. The default value of this property is `false`.
      Setting the value of this attribute might throw NOT_SUPPORTED_ERR if the implementation doesn't support the mode the attribute is being set to. Should the DOM spec define the default value of this property? What if implementing both async and sync IO is impractical in some systems? 2001-09-14. default is `false` but we need to check with Mozilla and IE.

    - #### setAsync

          public void setAsync(boolean async)

      DOM Level 3 WD - Experimental. Indicates whether the method load should be synchronous or asynchronous. When the async attribute is set to `true` the load method returns control to the caller before the document has completed loading. The default value of this property is `false`.
      Setting the value of this attribute might throw NOT_SUPPORTED_ERR if the implementation doesn't support the mode the attribute is being set to. Should the DOM spec define the default value of this property? What if implementing both async and sync IO is impractical in some systems? 2001-09-14. default is `false` but we need to check with Mozilla and IE.

    - #### abort

          public void abort()

      DOM Level 3 WD - Experimental. If the document is currently being loaded as a result of the method `load` being invoked the loading and parsing is immediately aborted. The possibly partial result of parsing the document is discarded and the document is cleared.

    - #### load

          public boolean load(java.lang.String uri)

      DOM Level 3 WD - Experimental. Replaces the content of the document with the result of parsing the given URI. Invoking this method will either block the caller or return to the caller immediately depending on the value of the async attribute. Once the document is fully loaded a "load" event (as defined in [DOM Level 3 Events] , except that the `Event.targetNode` will be the document, not an element) will be dispatched on the document. If an error occurs, an implementation dependent "error" event will be dispatched on the document. If this method is called on a document that is currently loading, the current load is interrupted and the new URI load is initiated.
      When invoking this method the parameters used in the `DOMParser` interface are assumed to have their default values with the exception that the parameters `"entities"` , `"normalize-characters"`, `"check-character-normalization"` are set to `"false"`.
      The result of a call to this method is the same the result of a call to `DOMParser.parseWithContext` with an input stream referencing the URI that was passed to this call, the document as the context node, and the action `ACTION_REPLACE_CHILDREN`.
      Parameters:
        `uri` - The URI reference for the XML file to be loaded. If this is a relative URI, the base URI used by the implementation is implementation dependent.
      Returns:
        If async is set to `true` `load` returns `true` if the document load was successfully initiated. If an error occurred when initiating the document load, `load` returns `false`.If async is set to `false` `load` returns `true` if the document was successfully loaded and parsed. If an error occurred when either loading or parsing the URI, `load` returns `false`.

    - #### loadXML

          public boolean loadXML(java.lang.String source)

      DOM Level 3 WD - Experimental. Replace the content of the document with the result of parsing the input string, this method is always synchronous.
      Parameters:
        `source` - A string containing an XML document.
      Returns:
        `true` if parsing the input string succeeded without errors, otherwise `false`.

    - #### saveXML

          public java.lang.String saveXML(org.w3c.dom.Node node)
                                   throws org.w3c.dom.DOMException

      DOM Level 3 WD - Experimental. Save the document or the given node and all its descendants to a string (i.e. serialize the document or node).
      The parameters used in the `LSSerializer` interface are assumed to have their default values when invoking this method.
      The result of a call to this method is the same the result of a call to `LSSerializer.writeToString` with the document as the node to write.
      Parameters:
        `node` - Specifies what to serialize, if this parameter is `null` the whole document is serialized, if it's non-null the given node is serialized.
      Returns:
        The serialized document or `null` in case an error occurred.
      Throws:
        `org.w3c.dom.DOMException` - WRONG_DOCUMENT_ERR: Raised if the node passed in as the node parameter is from an other document.

    - #### createDocumentType

          public org.w3c.dom.DocumentType createDocumentType(java.lang.String qualifiedName,
                                                    java.lang.String publicID,
                                                    java.lang.String systemID)
                                                      throws org.w3c.dom.DOMException

      NON-DOM Factory method; creates a DocumentType having this Document as its OwnerDoc. (REC-DOM-Level-1-19981001 left the process of building DTD information unspecified.)
      Parameters:
        `qualifiedName` -
        `publicID` -
        `systemID` -
      Throws:
        `DOMException(NOT_SUPPORTED_ERR)` - for HTML documents, where DTDs are not permitted. (HTML not yet implemented.)
        `org.w3c.dom.DOMException`

    - #### createEntity

          public org.w3c.dom.Entity createEntity(java.lang.String name)
                                          throws org.w3c.dom.DOMException

      NON-DOM Factory method; creates an Entity having this Document as its OwnerDoc. (REC-DOM-Level-1-19981001 left the process of building DTD information unspecified.)
      Parameters:
        `name` - The name of the Entity we wish to provide a value for.
      Throws:
        `DOMException(NOT_SUPPORTED_ERR)` - for HTML documents, where nonstandard entities are not permitted. (HTML not yet implemented.)
        `org.w3c.dom.DOMException`

    - #### createNotation

          public org.w3c.dom.Notation createNotation(java.lang.String name)
                                              throws org.w3c.dom.DOMException

      NON-DOM Factory method; creates a Notation having this Document as its OwnerDoc. (REC-DOM-Level-1-19981001 left the process of building DTD information unspecified.)
      Parameters:
        `name` - The name of the Notation we wish to describe
      Throws:
        `DOMException(NOT_SUPPORTED_ERR)` - for HTML documents, where notations are not permitted. (HTML not yet implemented.)
        `org.w3c.dom.DOMException`

    - #### createElementDefinition

          public ElementDefinitionImpl createElementDefinition(java.lang.String name)
                                                        throws org.w3c.dom.DOMException

      NON-DOM Factory method: creates an element definition. Element definitions hold default attribute values.
      Throws:
        `org.w3c.dom.DOMException`

    - #### getNodeNumber

          protected int getNodeNumber()

      NON-DOM: Get the number associated with this document. Used to order documents in the implementation.
      Overrides:
        `getNodeNumber` in class `NodeImpl`

    - #### getNodeNumber

          protected int getNodeNumber(org.w3c.dom.Node node)

      NON-DOM: Get a number associated with a node created with respect to this document. Needed for compareDocumentPosition when nodes are disconnected. This is only used on demand.

    - #### importNode

          public org.w3c.dom.Node importNode(org.w3c.dom.Node source,
                                    boolean deep)
                                      throws org.w3c.dom.DOMException

      Copies a node from another document to this document. The new nodes are created using this document's factory methods and are populated with the data from the source's accessor methods defined by the DOM interfaces. Its behavior is otherwise similar to that of cloneNode.

      According to the DOM specifications, document nodes cannot be imported and a NOT_SUPPORTED_ERR exception is thrown if attempted.

      Specified by:
        `importNode` in interface `org.w3c.dom.Document`
      Parameters:
        `source` - The node to import.
        `deep` - If `true`, recursively import the subtree under the specified node; if `false`, import only the node itself, as explained above. This has no effect on nodes that cannot have any children, and on `Attr`, and `EntityReference` nodes.
      Returns:
        The imported node that belongs to this `Document`.
      Throws:
        `org.w3c.dom.DOMException` - NOT_SUPPORTED_ERR: Raised if the type of node being imported is not supported.
        INVALID_CHARACTER_ERR: Raised if one of the imported names is not an XML name according to the XML version in use specified in the `Document.xmlVersion` attribute. This may happen when importing an XML 1.1 [XML 1.1] element into an XML 1.0 document, for instance.

    - #### adoptNode

          public org.w3c.dom.Node adoptNode(org.w3c.dom.Node source)

      DOM Level 3 WD - Experimental Change the node's ownerDocument, and its subtree, to this Document
      Specified by:
        `adoptNode` in interface `org.w3c.dom.Document`
      Parameters:
        `source` - The node to adopt.
      Returns:
        The adopted node, or `null` if this operation fails, such as when the source node comes from a different implementation.
      See Also:
        `importNode(org.w3c.dom.Node, boolean)`

    - #### undeferChildren

          protected void undeferChildren(org.w3c.dom.Node node)

      Traverses the DOM Tree and expands deferred nodes and their children.

    - #### getElementById

          public org.w3c.dom.Element getElementById(java.lang.String elementId)

      Introduced in DOM Level 2 Returns the Element whose ID is given by elementId. If no such element exists, returns null. Behavior is not defined if more than one element has this ID.

      Note: The DOM implementation must have information that says which attributes are of type ID. Attributes with the name "ID" are not of type ID unless so defined. Implementations that do not know whether attributes are of type ID or not are expected to return null.

      Specified by:
        `getElementById` in interface `org.w3c.dom.Document`
      Parameters:
        `elementId` - The unique `id` value for an element.
      Returns:
        The matching element or `null` if there is none.
      See Also:
        `getIdentifier(java.lang.String)`

    - #### clearIdentifiers

          protected final void clearIdentifiers()

      Remove all identifiers from the ID table

    - #### putIdentifier

          public void putIdentifier(java.lang.String idName,
                           org.w3c.dom.Element element)

      Registers an identifier name with a specified element node. If the identifier is already registered, the new element node replaces the previous node. If the specified element node is null, removeIdentifier() is called.
      See Also:
        `getIdentifier(java.lang.String)`, `removeIdentifier(java.lang.String)`

    - #### getIdentifier

          public org.w3c.dom.Element getIdentifier(java.lang.String idName)

      Returns a previously registered element with the specified identifier name, or null if no element is registered.
      See Also:
        `putIdentifier(java.lang.String, org.w3c.dom.Element)`, `removeIdentifier(java.lang.String)`

    - #### removeIdentifier

          public void removeIdentifier(java.lang.String idName)

      Removes a previously registered element with the specified identifier name.
      See Also:
        `putIdentifier(java.lang.String, org.w3c.dom.Element)`, `getIdentifier(java.lang.String)`

    - #### getIdentifiers

          public java.util.Enumeration getIdentifiers()

      Returns an enumeration registered of identifier names.

    - #### createElementNS

          public org.w3c.dom.Element createElementNS(java.lang.String namespaceURI,
                                            java.lang.String qualifiedName)
                                              throws org.w3c.dom.DOMException

      Introduced in DOM Level 2.

      Creates an element of the given qualified name and namespace URI. If the given namespaceURI is null or an empty string and the qualifiedName has a prefix that is "xml", the created element is bound to the predefined namespace "http://www.w3.org/XML/1998/namespace" [Namespaces].

      Specified by:
        `createElementNS` in interface `org.w3c.dom.Document`
      Parameters:
        `namespaceURI` - The namespace URI of the element to create.
        `qualifiedName` - The qualified name of the element type to instantiate.
      Returns:
        Element A new Element object with the following attributes:
      Throws:
        `org.w3c.dom.DOMException` - INVALID_CHARACTER_ERR: Raised if the specified name contains an invalid character.
        `org.w3c.dom.DOMException` - NAMESPACE_ERR: Raised if the qualifiedName has a prefix that is "xml" and the namespaceURI is neither null nor an empty string nor "http://www.w3.org/XML/1998/namespace", or if the qualifiedName has a prefix different from "xml" and the namespaceURI is null or an empty string.
      Since:
        WD-DOM-Level-2-19990923

    - #### createElementNS

          public org.w3c.dom.Element createElementNS(java.lang.String namespaceURI,
                                            java.lang.String qualifiedName,
                                            java.lang.String localpart)
                                              throws org.w3c.dom.DOMException

      NON-DOM: a factory method used by the Xerces DOM parser to create an element.
      Parameters:
        `namespaceURI` - The namespace URI of the element to create.
        `qualifiedName` - The qualified name of the element type to instantiate.
        `localpart` - The local name of the attribute to instantiate.
      Returns:
        Element A new Element object with the following attributes:
      Throws:
        `org.w3c.dom.DOMException` - INVALID_CHARACTER_ERR: Raised if the specified name contains an invalid character.

    - #### createAttributeNS

          public org.w3c.dom.Attr createAttributeNS(java.lang.String namespaceURI,
                                           java.lang.String qualifiedName)
                                             throws org.w3c.dom.DOMException

      Introduced in DOM Level 2.

      Creates an attribute of the given qualified name and namespace URI. If the given namespaceURI is null or an empty string and the qualifiedName has a prefix that is "xml", the created element is bound to the predefined namespace "http://www.w3.org/XML/1998/namespace" [Namespaces].

      Specified by:
        `createAttributeNS` in interface `org.w3c.dom.Document`
      Parameters:
        `namespaceURI` - The namespace URI of the attribute to create. When it is null or an empty string, this method behaves like createAttribute.
        `qualifiedName` - The qualified name of the attribute to instantiate.
      Returns:
        Attr A new Attr object.
      Throws:
        `org.w3c.dom.DOMException` - INVALID_CHARACTER_ERR: Raised if the specified name contains an invalid character.
      Since:
        WD-DOM-Level-2-19990923

    - #### createAttributeNS

          public org.w3c.dom.Attr createAttributeNS(java.lang.String namespaceURI,
                                           java.lang.String qualifiedName,
                                           java.lang.String localpart)
                                             throws org.w3c.dom.DOMException

      NON-DOM: a factory method used by the Xerces DOM parser to create an element.
      Parameters:
        `namespaceURI` - The namespace URI of the attribute to create. When it is null or an empty string, this method behaves like createAttribute.
        `qualifiedName` - The qualified name of the attribute to instantiate.
        `localpart` - The local name of the attribute to instantiate.
      Returns:
        Attr A new Attr object.
      Throws:
        `org.w3c.dom.DOMException` - INVALID_CHARACTER_ERR: Raised if the specified name contains an invalid character.

    - #### getElementsByTagNameNS

          public org.w3c.dom.NodeList getElementsByTagNameNS(java.lang.String namespaceURI,
                                                    java.lang.String localName)

      Introduced in DOM Level 2.

      Returns a NodeList of all the Elements with a given local name and namespace URI in the order in which they would be encountered in a preorder traversal of the Document tree.

      Specified by:
        `getElementsByTagNameNS` in interface `org.w3c.dom.Document`
      Parameters:
        `namespaceURI` - The namespace URI of the elements to match on. The special value "*" matches all namespaces. When it is null or an empty string, this method behaves like getElementsByTagName.
        `localName` - The local name of the elements to match on. The special value "*" matches all local names.
      Returns:
        NodeList A new NodeList object containing all the matched Elements.
      Since:
        WD-DOM-Level-2-19990923

    - #### clone

          public java.lang.Object clone()
                                 throws java.lang.CloneNotSupportedException

      Clone.
      Overrides:
        `clone` in class `java.lang.Object`
      Throws:
        `java.lang.CloneNotSupportedException`

    - #### isXMLName

          public static final boolean isXMLName(java.lang.String s,
                          boolean xml11Version)

      Check the string against XML's definition of acceptable names for elements and attributes and so on using the XMLCharacterProperties utility class

    - #### isValidQName

          public static final boolean isValidQName(java.lang.String prefix,
                             java.lang.String local,
                             boolean xml11Version)

      Checks if the given qualified name is legal with respect to the version of XML to which this document must conform.
      Parameters:
        `prefix` - prefix of qualified name
        `local` - local part of qualified name

    - #### isKidOK

          protected boolean isKidOK(org.w3c.dom.Node parent,
                        org.w3c.dom.Node child)

      Uses the kidOK lookup table to check whether the proposed tree structure is legal.

    - #### changed

          protected void changed()

      Denotes that this node has changed.
      Overrides:
        `changed` in class `NodeImpl`

    - #### changes

          protected int changes()

      Returns the number of changes to this node.
      Overrides:
        `changes` in class `NodeImpl`

    - #### setUserData

          public java.lang.Object setUserData(org.w3c.dom.Node n,
                                     java.lang.String key,
                                     java.lang.Object data,
                                     org.w3c.dom.UserDataHandler handler)

      Associate an object to a key on this node. The object can later be retrieved from this node by calling `getUserData` with the same key.
      Parameters:
        `n` - The node to associate the object to.
        `key` - The key to associate the object to.
        `data` - The object to associate to the given key, or `null` to remove any existing association to that key.
        `handler` - The handler to associate to that key, or `null`.
      Returns:
        Returns the `DOMObject` previously associated to the given key on this node, or `null` if there was none.
      Since:
        DOM Level 3 REVISIT: we could use a free list of UserDataRecord here

    - #### getUserData

          public java.lang.Object getUserData(org.w3c.dom.Node n,
                                     java.lang.String key)

      Retrieves the object associated to a key on a this node. The object must first have been set to this node by calling `setUserData` with the same key.
      Parameters:
        `n` - The node the object is associated to.
        `key` - The key the object is associated to.
      Returns:
        Returns the `DOMObject` associated to the given key on this node, or `null` if there was none.
      Since:
        DOM Level 3

    - #### getUserDataRecord

          protected java.util.Hashtable getUserDataRecord(org.w3c.dom.Node n)

    - #### callUserDataHandlers

          protected void callUserDataHandlers(org.w3c.dom.Node n,
                                  org.w3c.dom.Node c,
                                  short operation)

      Call user data handlers when a node is deleted (finalized)
      Parameters:
        `n` - The node this operation applies to.
        `c` - The copy node or null.
        `operation` - The operation - import, clone, or delete.

    - #### checkNamespaceWF

          protected final void checkNamespaceWF(java.lang.String qname,
                              int colon1,
                              int colon2)

      Call user data handlers to let them know the nodes they are related to are being deleted. The alternative would be to do that on Node but because the nodes are used as the keys we have a reference to them that prevents them from being gc'ed until the document is. At the same time, doing it here has the advantage of avoiding a finalize() method on Node, which would affect all nodes and not just the ones that have a user data.

    - #### checkDOMNSErr

          protected final void checkDOMNSErr(java.lang.String prefix,
                           java.lang.String namespace)

    - #### checkQName

          protected final void checkQName(java.lang.String prefix,
                        java.lang.String local)

      Checks if the given qualified name is legal with respect to the version of XML to which this document must conform.
      Parameters:
        `prefix` - prefix of qualified name
        `local` - local part of qualified name

    - #### setUserData

          protected void setUserData(NodeImpl n,
                         java.lang.Object data)

      NON-DOM: kept for backward compatibility Store user data related to a given node This is a place where we could use weak references! Indeed, the node here won't be GC'ed as long as some user data is attached to it, since the userData table will have a reference to the node.

    - #### getUserData

          protected java.lang.Object getUserData(NodeImpl n)

      NON-DOM: kept for backward compatibility Retreive user data related to a given node

    - #### addEventListener

          protected void addEventListener(NodeImpl node,
                              java.lang.String type,
                              org.w3c.dom.events.EventListener listener,
                              boolean useCapture)

    - #### removeEventListener

          protected void removeEventListener(NodeImpl node,
                                 java.lang.String type,
                                 org.w3c.dom.events.EventListener listener,
                                 boolean useCapture)

    - #### copyEventListeners

          protected void copyEventListeners(NodeImpl src,
                                NodeImpl tgt)

    - #### dispatchEvent

          protected boolean dispatchEvent(NodeImpl node,
                              org.w3c.dom.events.Event event)

Copyright © 1999-2022 The Apache Software Foundation. All Rights Reserved.