Xerces 3.1.1

## org.apache.xerces.dom
Class DocumentImpl

    java.lang.Object
      |
      +--org.apache.xerces.dom.NodeImpl
            |
            +--org.apache.xerces.dom.ParentNode
                  |
                  +--org.apache.xerces.dom.DocumentImpl

Direct Known Subclasses:
  DeferredDocumentImpl, HTMLDocumentImpl, WMLDocumentImpl

public class DocumentImpl
extends ParentNode
implements Document, DocumentTraversal, DocumentEvent, DocumentRange

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 DocumentImpl class also implements the DOM Level 2 DocumentTraversal interface. This interface is comprised of factory methods needed to create NodeIterators and TreeWalkers. The process of creating NodeIterator objects also adds these references to this document. After finishing with an iterator it is important to remove the object using the remove methods in this implementation. This allows the release of the references from the iterator objects to the DOM Nodes.

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

Since:
  PR-DOM-Level-1-19980818.
Version:
See Also:
  Serialized Form

Field Summary
`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 boolean` `errorChecking` Bypass error checking.
`protected java.util.Hashtable` `eventListeners` Table for event listeners registered to this document nodes.
`protected java.util.Hashtable` `identifiers` Identifiers.
`protected java.util.Vector` `iterators` Iterators
`protected static int[]` `kidOK` Table for quick check of child insertion.
`protected boolean` `mutationEvents` Bypass mutation events firing.
`protected java.util.Vector` `ranges` Ranges
`protected java.util.Hashtable` `userData` Table for user data attached to this document nodes.

Fields inherited from class org.apache.xerces.dom.ParentNode
`firstChild, nodeListIndex, nodeListLength, nodeListNode, ownerDocument`

Fields inherited from class org.apache.xerces.dom.NodeImpl
`ELEMENT_DEFINITION_NODE, FIRSTCHILD, flags, IGNORABLEWS, MUTATION_AGGREGATE, MUTATION_ALL, MUTATION_LOCAL, MUTATION_NONE, MUTATIONEVENTS, OWNED, ownerNode, READONLY, SETVALUE, SPECIFIED, SYNCCHILDREN, SYNCDATA`

Fields inherited from interface org.w3c.dom.Node
`ATTRIBUTE_NODE, CDATA_SECTION_NODE, COMMENT_NODE, DOCUMENT_FRAGMENT_NODE, DOCUMENT_NODE, DOCUMENT_TYPE_NODE, ELEMENT_NODE, ENTITY_NODE, ENTITY_REFERENCE_NODE, NOTATION_NODE, PROCESSING_INSTRUCTION_NODE, TEXT_NODE`

Constructor Summary
`DocumentImpl()` NON-DOM: Actually creating a Document is outside the DOM's spec, since it has to operate in terms of a particular implementation.
`DocumentImpl(boolean grammarAccess)` Experimental constructor.
`DocumentImpl(DocumentType doctype)`
`DocumentImpl(DocumentType doctype, boolean grammarAccess)` Experimental constructor.

Method Summary
`void` `adoptNode(Node source)` NON-DOM: Change the node's ownerDocument, and its subtree, to this Document
`protected void` `changed()` Denotes that this node has changed.
`protected int` `changes()` Returns the number of changes to this node.
`java.lang.Object` `clone()` Clone.
`Node` `cloneNode(boolean deep)` Deep-clone a document, including fixing ownerDoc for the cloned children.
`Attr` `createAttribute(java.lang.String name)` Factory method; creates an Attribute having this Document as its OwnerDoc.
`Attr` `createAttributeNS(java.lang.String namespaceURI, java.lang.String qualifiedName)` Introduced in DOM Level 2.
`CDATASection` `createCDATASection(java.lang.String data)` Factory method; creates a CDATASection having this Document as its OwnerDoc.
`Comment` `createComment(java.lang.String data)` Factory method; creates a Comment having this Document as its OwnerDoc.
`DocumentFragment` `createDocumentFragment()` Factory method; creates a DocumentFragment having this Document as its OwnerDoc.
`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.
`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.
`Element` `createElementNS(java.lang.String namespaceURI, java.lang.String qualifiedName)` Introduced in DOM Level 2.
`Entity` `createEntity(java.lang.String name)` NON-DOM Factory method; creates an Entity having this Document as its OwnerDoc.
`EntityReference` `createEntityReference(java.lang.String name)` Factory method; creates an EntityReference having this Document as its OwnerDoc.
`Event` `createEvent(java.lang.String type)` Introduced in DOM Level 2.
`NodeIterator` `createNodeIterator(Node root, int whatToShow, NodeFilter filter, boolean entityReferenceExpansion)` Create and return a NodeIterator.
`NodeIterator` `createNodeIterator(Node root, short whatToShow, NodeFilter filter)` NON-DOM extension: Create and return a NodeIterator.
`Notation` `createNotation(java.lang.String name)` NON-DOM Factory method; creates a Notation having this Document as its OwnerDoc.
`ProcessingInstruction` `createProcessingInstruction(java.lang.String target, java.lang.String data)` Factory method; creates a ProcessingInstruction having this Document as its OwnerDoc.
`Range` `createRange()` This interface can be obtained from the object implementing the `Document` interface using binding-specific casting methods.
`Text` `createTextNode(java.lang.String data)` Factory method; creates a Text node having this Document as its OwnerDoc.
`TreeWalker` `createTreeWalker(Node root, int whatToShow, NodeFilter filter, boolean entityReferenceExpansion)` Create and return a TreeWalker.
`TreeWalker` `createTreeWalker(Node root, short whatToShow, NodeFilter filter)` NON-DOM extension: Create and return a TreeWalker.
`DocumentType` `getDoctype()` For XML, this provides access to the Document Type Definition.
`Element` `getDocumentElement()` Convenience method, allowing direct access to the child node which is considered the root of the actual document content.
`Element` `getElementById(java.lang.String elementId)` Introduced in DOM Level 2 Returns the Element whose ID is given by elementId.
`NodeList` `getElementsByTagName(java.lang.String tagname)` Return a live collection of all descendent Elements (not just immediate children) having the specified tag name.
`NodeList` `getElementsByTagNameNS(java.lang.String namespaceURI, java.lang.String localName)` Introduced in DOM Level 2.
`boolean` `getErrorChecking()` Returns true if the DOM implementation performs error checking.
`protected java.util.Vector` `getEventListeners(NodeImpl n)` Retreive event listener registered on a given node
`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.
`DOMImplementation` `getImplementation()` Retrieve information describing the abilities of this particular DOM implementation.
`boolean` `getMutationEvents()` Returns true if the DOM implementation generates mutation events.
`java.lang.String` `getNodeName()` Returns the node name.
`short` `getNodeType()` Returns the node type.
`Document` `getOwnerDocument()` The `Document` object associated with this node.
`protected java.lang.Object` `getUserData(NodeImpl n)` Retreive user data related to a given node
`Node` `importNode(Node source, boolean deep)` Copies data from the source node.
`Node` `insertBefore(Node newChild, 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(Node parent, Node child)` Uses the kidOK lookup table to check whether the proposed tree structure is legal.
`static boolean` `isXMLName(java.lang.String s)` Check the string against XML's definition of acceptable names for elements and attributes and so on.
`void` `putIdentifier(java.lang.String idName, Element element)` Registers an identifier name with a specified element node.
`Node` `removeChild(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
`void` `removeIdentifier(java.lang.String idName)` Removes a previously registered element with the specified identifier name.
`Node` `replaceChild(Node newChild, 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
`void` `setErrorChecking(boolean check)` Sets whether the DOM implementation performs error checking upon operations.
`protected void` `setEventListeners(NodeImpl n, java.util.Vector listeners)` Store event listener registered on a given node This is another place where we could use weak references! Indeed, the node here won't be GC'ed as long as some listener is registered on it, since the eventsListeners table will have a reference to the node.
`void` `setMutationEvents(boolean set)` Sets whether the DOM implementation generates mutation events upon operations.
`protected void` `setUserData(NodeImpl n, java.lang.Object data)` 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.

Methods inherited from class org.apache.xerces.dom.ParentNode
`getChildNodes, getFirstChild, getLastChild, getLength, hasChildNodes, item, normalize, setReadOnly, synchronizeChildren, synchronizeChildren`

Methods inherited from class org.apache.xerces.dom.NodeImpl
`addEventListener, appendChild, dispatchEvent, getAttributes, getLocalName, getNamespaceURI, getNextSibling, getNodeValue, getParentNode, getPrefix, getPreviousSibling, getReadOnly, getUserData, hasAttributes, isSupported, removeEventListener, setNodeValue, setPrefix, setUserData, synchronizeData, toString`

Methods inherited from class java.lang.Object
`equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

Field Detail

### docType

    protected DocumentTypeImpl docType

  Document type.

### docElement

    protected ElementImpl docElement

  Document element.

### identifiers

    protected java.util.Hashtable identifiers

  Identifiers.

### iterators

    protected java.util.Vector iterators

  Iterators

### ranges

    protected java.util.Vector ranges

  Ranges

### kidOK

    protected static int[] kidOK

  Table for quick check of child insertion.

### userData

    protected java.util.Hashtable userData

  Table for user data attached to this document nodes.

### eventListeners

    protected java.util.Hashtable eventListeners

  Table for event listeners registered to this document nodes.

### 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.

### mutationEvents

    protected boolean mutationEvents

  Bypass mutation events firing.

Constructor Detail

### DocumentImpl

    public DocumentImpl()

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

### DocumentImpl

    public DocumentImpl(boolean grammarAccess)

  Experimental constructor.

### DocumentImpl

    public DocumentImpl(DocumentType doctype)

### DocumentImpl

    public DocumentImpl(DocumentType doctype,
                        boolean grammarAccess)

  Experimental constructor.

Method Detail

### getOwnerDocument

    public final Document getOwnerDocument()

  Description copied from interface: Node
  The `Document` object associated with this node. This is also the `Document` object used to create new nodes. When this node is a `Document` or a `DocumentType` which is not used with any `Document` yet, this is `null`.
  Overrides:
    getOwnerDocument in class ParentNode

### getNodeType

    public short getNodeType()

  Returns the node type.
  Overrides:
    getNodeType in class NodeImpl

### getNodeName

    public java.lang.String getNodeName()

  Returns the node name.
  Overrides:
    getNodeName in class NodeImpl

### cloneNode

    public 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.
  Overrides:
    cloneNode in class ParentNode
  Parameters:
    `deep` - boolean, iff true replicate children
  Returns:
    org.w3c.dom.Node

### insertBefore

    public Node insertBefore(Node newChild,
                             Node refChild)
                      throws 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

  Overrides:
    insertBefore in class ParentNode
  Tags copied from interface: Node
  Parameters:
    `newChildThe` - node to insert.
    `refChildThe` - reference node, i.e., the node before which the new node must be inserted.
  Returns:
    The node being inserted.
  Throws:
    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.
    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.

### removeChild

    public Node removeChild(Node oldChild)
                     throws 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
  Overrides:
    removeChild in class ParentNode
  Tags copied from interface: Node
  Parameters:
    `oldChildThe` - node being removed.
  Returns:
    The node removed.
  Throws:
    DOMException - NO_MODIFICATION_ALLOWED_ERR: Raised if this node is readonly.
    NOT_FOUND_ERR: Raised if `oldChild` is not a child of this node.

### replaceChild

    public Node replaceChild(Node newChild,
                             Node oldChild)
                      throws 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
  Overrides:
    replaceChild in class ParentNode
  Tags copied from interface: Node
  Parameters:
    `newChildThe` - new node to put in the child list.
    `oldChildThe` - node being replaced in the list.
  Returns:
    The node replaced.
  Throws:
    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.
    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.

### createAttribute

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

  Factory method; creates an Attribute having this Document as its OwnerDoc.
  Specified by:
    createAttribute in interface Document
  Parameters:
    `name` - The name of the attribute. Note that the attribute's value is _not_ established at the factory; remember to set it!
  Throws:
    DOMException(INVALID_NAME_ERR) - if the attribute name is not acceptable.

### createCDATASection

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

  Factory method; creates a CDATASection having this Document as its OwnerDoc.
  Specified by:
    createCDATASection in interface Document
  Parameters:
    `data` - The initial contents of the CDATA
  Throws:
    DOMException(NOT_SUPPORTED_ERR) - for HTML documents. (HTML not yet implemented.)

### createComment

    public Comment createComment(java.lang.String data)

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

### createDocumentFragment

    public DocumentFragment createDocumentFragment()

  Factory method; creates a DocumentFragment having this Document as its OwnerDoc.
  Specified by:
    createDocumentFragment in interface Document
  Tags copied from interface: Document
  Returns:
    A new `DocumentFragment`.

### createElement

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

  Factory method; creates an Element having this Document as its OwnerDoc.
  Specified by:
    createElement in interface 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.
  Throws:
    DOMException(INVALID_NAME_ERR) - if the tag name is not acceptable.

### createEntityReference

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

  Factory method; creates an EntityReference having this Document as its OwnerDoc.
  Specified by:
    createEntityReference in interface Document
  Parameters:
    `name` - The name of the Entity we wish to refer to
  Throws:
    DOMException(NOT_SUPPORTED_ERR) - for HTML documents, where nonstandard entities are not permitted. (HTML not yet implemented.)

### createProcessingInstruction

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

  Factory method; creates a ProcessingInstruction having this Document as its OwnerDoc.
  Specified by:
    createProcessingInstruction in interface Document
  Parameters:
    `target` - The target "processor channel"
    `data` - Parameter string to be passed to the target.
  Throws:
    DOMException(INVALID_NAME_ERR) - if the target name is not acceptable.
    DOMException(NOT_SUPPORTED_ERR) - for HTML documents. (HTML not yet implemented.)

### createTextNode

    public Text createTextNode(java.lang.String data)

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

### getDoctype

    public 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 Document

### getDocumentElement

    public 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 Document

### getElementsByTagName

    public 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 Document
  Parameters:
    `tagname` - The type of Element we want to gather. "*" will be taken as a wildcard, meaning "all elements in the document."
  See Also:
    `DeepNodeListImpl`

### getImplementation

    public 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 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

### getErrorChecking

    public boolean getErrorChecking()

  Returns true if the DOM implementation performs error checking.

### setMutationEvents

    public void setMutationEvents(boolean set)

  Sets whether the DOM implementation generates mutation events upon operations.

### getMutationEvents

    public boolean getMutationEvents()

  Returns true if the DOM implementation generates mutation events.

### createDocumentType

    public DocumentType createDocumentType(java.lang.String qualifiedName,
                                           java.lang.String publicID,
                                           java.lang.String systemID)
                                    throws 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:
    `name` - The name of the Entity we wish to provide a value for.
  Throws:
    DOMException(NOT_SUPPORTED_ERR) - for HTML documents, where DTDs are not permitted. (HTML not yet implemented.)

### createEntity

    public Entity createEntity(java.lang.String name)
                        throws 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.)

### createNotation

    public Notation createNotation(java.lang.String name)
                            throws 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.)

### createElementDefinition

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

  NON-DOM Factory method: creates an element definition. Element definitions hold default attribute values.

### importNode

    public Node importNode(Node source,
                           boolean deep)
                    throws DOMException

  Copies data from the source node. Unlike cloneNode, this _can_ copy data from another document. If the source document is also based on org.apache.xerces.dom, we will attempt to preserve the domimpl- internal data by doing a clone-and-reparent. If not, we will use the source's public methods, and this document's Factory methods, to copy data defined by the DOM interfaces. Its behavior is otherwise similar to that of cloneNode. Attempting to import a Document into another Document is meaningless -- a new Document would not improve matters much, and a DocumentFragment couldn't carry the DocumentType child (if any). Best thing we can do is throw a HIERARCHY_REQUEST_ERR. ????? Should we push some of this down to copy-ctors, so subclassed DOMs have the option of special-casing each other (as we do for ourself)?
  Specified by:
    importNode in interface Document
  Tags copied from interface: Document
  Parameters:
    `importedNodeThe` - node to import.
    `deepIf` - `true`, recursively import the subtree under the specified node; if `false`, import only the node itself, as explained above. This has no effect on `Attr` , `EntityReference`, and `Notation` nodes.
  Returns:
    The imported node that belongs to this `Document`.
  Throws:
    DOMException - NOT_SUPPORTED_ERR: Raised if the type of node being imported is not supported.

### adoptNode

    public void adoptNode(Node source)

  NON-DOM: Change the node's ownerDocument, and its subtree, to this Document
  Parameters:
    `source` - The node to move in to this document.
  Throws:
    NOT_SUPPORTED_ERR - DOMException, raised if the implementation cannot handle the request, such as when the source node comes from a different DOMImplementation
  See Also:
    `DocumentImpl.importNode`

### getElementById

    public 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 Document
  See Also:
    `getIdentifier(java.lang.String)`

### putIdentifier

    public void putIdentifier(java.lang.String idName,
                              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 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 Element createElementNS(java.lang.String namespaceURI,
                                   java.lang.String qualifiedName)
                            throws 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 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:
    DOMException - INVALID_CHARACTER_ERR: Raised if the specified name contains an invalid character.
    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

### createAttributeNS

    public Attr createAttributeNS(java.lang.String namespaceURI,
                                  java.lang.String qualifiedName)
                           throws 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 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:
    DOMException - INVALID_CHARACTER_ERR: Raised if the specified name contains an invalid character.
  Since:
    WD-DOM-Level-2-19990923

### getElementsByTagNameNS

    public 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 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

### createNodeIterator

    public NodeIterator createNodeIterator(Node root,
                                           short whatToShow,
                                           NodeFilter filter)

  NON-DOM extension: Create and return a NodeIterator. The NodeIterator is added to a list of NodeIterators so that it can be removed to free up the DOM Nodes it references.
  Parameters:
    `root` - The root of the iterator.
    `whatToShow` - The whatToShow mask.
    `filter` - The NodeFilter installed. Null means no filter.
  See Also:
    `#removeNodeIterator`, `#removeNodeIterators`

### createNodeIterator

    public NodeIterator createNodeIterator(Node root,
                                           int whatToShow,
                                           NodeFilter filter,
                                           boolean entityReferenceExpansion)

  Create and return a NodeIterator. The NodeIterator is added to a list of NodeIterators so that it can be removed to free up the DOM Nodes it references.
  Specified by:
    createNodeIterator in interface DocumentTraversal
  Parameters:
    `root` - The root of the iterator.
    `whatToShow` - The whatToShow mask.
    `filter` - The NodeFilter installed. Null means no filter.
    `entityReferenceExpansion` - true to expand the contents of EntityReference nodes
  Since:
    WD-DOM-Level-2-19990923
  See Also:
    `#removeNodeIterator`, `#removeNodeIterators`

### createTreeWalker

    public TreeWalker createTreeWalker(Node root,
                                       short whatToShow,
                                       NodeFilter filter)

  NON-DOM extension: Create and return a TreeWalker.
  Parameters:
    `root` - The root of the iterator.
    `whatToShow` - The whatToShow mask.
    `filter` - The NodeFilter installed. Null means no filter.

### createTreeWalker

    public TreeWalker createTreeWalker(Node root,
                                       int whatToShow,
                                       NodeFilter filter,
                                       boolean entityReferenceExpansion)

  Create and return a TreeWalker.
  Specified by:
    createTreeWalker in interface DocumentTraversal
  Parameters:
    `root` - The root of the iterator.
    `whatToShow` - The whatToShow mask.
    `filter` - The NodeFilter installed. Null means no filter.
    `entityReferenceExpansion` - true to expand the contents of EntityReference nodes
  Since:
    WD-DOM-Level-2-19990923

### createRange

    public Range createRange()

  Description copied from interface: DocumentRange
  This interface can be obtained from the object implementing the `Document` interface using binding-specific casting methods.
  Specified by:
    createRange in interface DocumentRange
  Tags copied from interface: DocumentRange
  Returns:
    The initial state of the range returned from this method is such that both of its boundary-points are positioned at the beginning of the corresponding Document, before any content. The range returned can only be used to select content associated with this Document, or with DocumentFragments and Attrs for which this Document is the `ownerDocument` .

### createEvent

    public Event createEvent(java.lang.String type)
                      throws DOMException

  Introduced in DOM Level 2. Optional.

  Create and return Event objects.

  Specified by:
    createEvent in interface DocumentEvent
  Parameters:
    `type` - The event set name, defined as the interface name minus package qualifiers. For example, to create a DOMNodeInserted event you'd call `createEvent("MutationEvent")`, then use its initMutationEvent() method to configure it properly as DOMNodeInserted. This parameter is case-sensitive.
  Returns:
    an uninitialized Event object. Call the appropriate `init...Event()` method before dispatching it.
  Throws:
    DOMException - NOT_SUPPORTED_ERR if the requested event type is not supported in this DOM.
  Since:
    WD-DOM-Level-2-19990923

### clone

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

  Clone.
  Overrides:
    clone in class java.lang.Object

### isXMLName

    public static boolean isXMLName(java.lang.String s)

  Check the string against XML's definition of acceptable names for elements and attributes and so on. From the XML spec:

  [Definition:] A Name is a token beginning with a letter or one of a few punctuation characters, and continuing with letters, digits, hyphens,underscores, colons, or full stops, together known as name characters.

  Unfortunately, that spec goes on to say that after the first character, names may use "combining characters" and "extender characters", which are explicitly listed rather than defined in terms of Java's Unicode character types... and which in fact can't be expressed solely in terms of those types.

  I've empirically derived some tests which are partly based on the Java Unicode space (which simplifies them considerably), but they still wind up having to be further qualified. This may not remain valid if future extensions of Java and/or Unicode introduce other characters having these type numbers.

  Suggestions for alternative implementations would be welcome.

### setUserData

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

  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)

  Retreive user data related to a given node

### setEventListeners

    protected void setEventListeners(NodeImpl n,
                                     java.util.Vector listeners)

  Store event listener registered on a given node This is another place where we could use weak references! Indeed, the node here won't be GC'ed as long as some listener is registered on it, since the eventsListeners table will have a reference to the node.

### getEventListeners

    protected java.util.Vector getEventListeners(NodeImpl n)

  Retreive event listener registered on a given node

### isKidOK

    protected boolean isKidOK(Node parent,
                              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

Xerces 3.1.1