org.apache.xerces.dom
Class CoreDocumentImpl

java.lang.Object
  extended by org.apache.xerces.dom.NodeImpl
      extended by org.apache.xerces.dom.ChildNode
          extended by org.apache.xerces.dom.ParentNode
              extended by org.apache.xerces.dom.CoreDocumentImpl
All Implemented Interfaces:
java.io.Serializable, java.lang.Cloneable, Document, EventTarget, Node, NodeList
Direct Known Subclasses:
DocumentImpl

public class CoreDocumentImpl
extends ParentNode
implements 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 515302 2007-03-06 21:07:10Z mrglavas $
Author:
Arnaud Le Hors, IBM, Joe Kesselman, IBM, Andy Clark, IBM, Ralf Pfeiffer, IBM
See Also:
Serialized Form

Field Summary
 
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, 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
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(DocumentType doctype)
          For DOM2 support.
CoreDocumentImpl(DocumentType doctype, boolean grammarAccess)
          For DOM2 support.
 
Method Summary
 void abort()
          DOM Level 3 WD - Experimental.
 Node adoptNode(Node source)
          DOM Level 3 WD - Experimental Change the node's ownerDocument, and its subtree, to this Document
 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.
 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.
 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.
 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.
 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.
 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.
 Text createTextNode(java.lang.String data)
          Factory method; creates a Text node having this Document as its OwnerDoc.
 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.
 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.
 java.lang.String getDocumentURI()
          DOM Level 3 WD - Experimental.
 DOMConfiguration getDomConfig()
          DOM Level 3 CR - Experimental The configuration used when Document.normalizeDocument is invoked.
 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.
 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 .
 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.
 java.lang.String getInputEncoding()
          DOM Level 3 CR - Experimental.
 java.lang.String getNodeName()
          Returns the node name.
 short getNodeType()
          Returns the node type.
 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.
 java.lang.Object getUserData(Node n, java.lang.String key)
          Retrieves the object associated to a key on a this node.
 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.
 Node importNode(Node source, boolean deep)
          Copies a node from another document to this document.
 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.
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, 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 renameNode(Node n, java.lang.String namespaceURI, java.lang.String name)
          DOM Level 3 WD - Experimental.
 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
 java.lang.String saveXML(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.
 java.lang.Object setUserData(Node n, java.lang.String key, java.lang.Object data, 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.
 
Methods inherited from class org.apache.xerces.dom.ParentNode
getChildNodes, getFirstChild, getLastChild, getLength, hasChildNodes, isEqualNode, item, normalize, setReadOnly
 
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, getLocalName, getNamespaceURI, getNodeValue, getPrefix, getReadOnly, getUserData, getUserData, hasAttributes, isDefaultNamespace, isSameNode, isSupported, lookupNamespaceURI, lookupPrefix, needsSyncChildren, removeEventListener, setNodeValue, setPrefix, setUserData, setUserData, toString
 
Methods inherited from class java.lang.Object
equals, 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
 

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(DocumentType doctype)
For DOM2 support. The createDocument factory method is in DOMImplementation.


CoreDocumentImpl

public CoreDocumentImpl(DocumentType doctype,
                        boolean grammarAccess)
For DOM2 support.

Method Detail

getOwnerDocument

public final 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 Node
Overrides:
getOwnerDocument in class ParentNode

getNodeType

public short getNodeType()
Returns the node type.

Specified by:
getNodeType in interface Node
Specified by:
getNodeType in class NodeImpl

getNodeName

public java.lang.String getNodeName()
Returns the node name.

Specified by:
getNodeName in interface Node
Specified by:
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.

Specified by:
cloneNode in interface 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.


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

Specified by:
insertBefore in interface 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:
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 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

Specified by:
removeChild in interface Node
Overrides:
removeChild in class ParentNode
Parameters:
oldChild - The node being removed.
Returns:
oldChild, in its new state (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.
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 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

Specified by:
replaceChild in interface 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:
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 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: /** 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
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 Node
Overrides:
getTextContent in class ParentNode
Throws:
DOMException - NO_MODIFICATION_ALLOWED_ERR: Raised when the node is readonly.

setTextContent

public void setTextContent(java.lang.String textContent)
                    throws 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 Node
Overrides:
setTextContent in class ParentNode
Throws:
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: 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 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 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!
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.
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 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
Returns:
The new CDATASection object.
Throws:
DOMException(NOT_SUPPORTED_ERR) - for HTML documents. (HTML not yet implemented.)
DOMException - NOT_SUPPORTED_ERR: Raised if this document is an HTML document.

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.
Returns:
The new Comment object.

createDocumentFragment

public DocumentFragment createDocumentFragment()
Factory method; creates a DocumentFragment having this Document as its OwnerDoc.

Specified by:
createDocumentFragment in 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.
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.
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 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
Returns:
The new EntityReference object.
Throws:
DOMException(NOT_SUPPORTED_ERR) - for HTML documents, where nonstandard entities are not permitted. (HTML not yet implemented.)
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 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.
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.)
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 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.
Returns:
The new Text object.

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."
Returns:
A new NodeList object containing all the matched Elements.
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:

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


setStrictErrorChecking

public void setStrictErrorChecking(boolean check)
Description copied from interface: 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 Document

getErrorChecking

public boolean getErrorChecking()
Returns true if the DOM implementation performs error checking.


getStrictErrorChecking

public boolean getStrictErrorChecking()
Description copied from interface: 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 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 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 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 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 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 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 Document
Throws:
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 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 Document
Since:
DOM Level 3

renameNode

public Node renameNode(Node n,
                       java.lang.String namespaceURI,
                       java.lang.String name)
                throws DOMException
DOM Level 3 WD - Experimental. Renaming node

Specified by:
renameNode in interface 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:
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 Document

getDomConfig

public DOMConfiguration getDomConfig()
DOM Level 3 CR - Experimental The configuration used when Document.normalizeDocument is invoked.

Specified by:
getDomConfig in interface 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 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 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(Node node)
                         throws 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:
DOMException - WRONG_DOCUMENT_ERR: Raised if the node passed in as the node parameter is from an other document.

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:
qualifiedName -
publicID -
systemID -
Throws:
DOMException(NOT_SUPPORTED_ERR) - for HTML documents, where DTDs are not permitted. (HTML not yet implemented.)
DOMException

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.)
DOMException

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.)
DOMException

createElementDefinition

public ElementDefinitionImpl createElementDefinition(java.lang.String name)
                                              throws DOMException
NON-DOM Factory method: creates an element definition. Element definitions hold default attribute values.

Throws:
DOMException

importNode

public Node importNode(Node source,
                       boolean deep)
                throws 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 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:
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 Node adoptNode(Node source)
DOM Level 3 WD - Experimental Change the node's ownerDocument, and its subtree, to this Document

Specified by:
adoptNode in interface 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)

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

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

createElementNS

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

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

createAttributeNS

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

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

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

setUserData

public java.lang.Object setUserData(Node n,
                                    java.lang.String key,
                                    java.lang.Object data,
                                    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(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