org.apache.xerces.dom

Class CoreDocumentImpl

Implemented Interfaces:
Cloneable, org.w3c.dom.Document, org.w3c.dom.events.EventTarget, org.w3c.dom.Node, org.w3c.dom.NodeList, Serializable
Known Direct Subclasses:
DocumentImpl

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

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

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

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

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

Version:
$Id: CoreDocumentImpl.java 439176 2006-09-01 04:45:24Z mrglavas $
Authors:
Arnaud Le Hors, IBM
Joe Kesselman, IBM
Andy Clark, IBM
Ralf Pfeiffer, IBM
Since:
PR-DOM-Level-1-19980818.

Field Summary

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

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

fNodeListCache, firstChild, ownerDocument

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

nextSibling, previousSibling

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

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

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(org.w3c.dom.DocumentType doctype)
For DOM2 support.
CoreDocumentImpl(org.w3c.dom.DocumentType doctype, boolean grammarAccess)
For DOM2 support.

Method Summary

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

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

cloneNode, getChildNodes, getChildNodesUnoptimized, getFirstChild, getLastChild, getLength, getOwnerDocument, getTextContent, hasChildNodes, insertBefore, isEqualNode, item, normalize, removeChild, replaceChild, setOwnerDocument, setReadOnly, setTextContent, synchronizeChildren

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

cloneNode, getNextSibling, getParentNode, getPreviousSibling

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

addEventListener, appendChild, changed, changes, cloneNode, compareDocumentPosition, compareTreePosition, dispatchEvent, getAttributes, getBaseURI, getChildNodes, getContainer, getFeature, getFirstChild, getLastChild, getLength, getLocalName, getNamespaceURI, getNextSibling, getNodeName, getNodeNumber, getNodeType, getNodeValue, getOwnerDocument, getParentNode, getPrefix, getPreviousSibling, getReadOnly, getTextContent, getUserData, getUserData, getUserDataRecord, hasAttributes, hasChildNodes, insertBefore, isDefaultNamespace, isEqualNode, isSameNode, isSupported, item, lookupNamespaceURI, lookupPrefix, needsSyncChildren, normalize, removeChild, removeEventListener, replaceChild, setNodeValue, setOwnerDocument, setPrefix, setReadOnly, setTextContent, setUserData, setUserData, synchronizeData, toString

Field Details

actualEncoding

protected String actualEncoding
Experimental DOM Level 3 feature: Document actualEncoding

allowGrammarAccess

protected boolean allowGrammarAccess
Allow grammar access.

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.


docElement

protected ElementImpl docElement
Document element.

docType

protected DocumentTypeImpl docType
Document type.

encoding

protected String encoding
Experimental DOM Level 3 feature: Document encoding

errorChecking

protected boolean errorChecking
Bypass error checking.

fDocumentURI

protected String fDocumentURI
Experimental DOM Level 3 feature: documentURI

identifiers

protected Hashtable identifiers
Identifiers.

standalone

protected boolean standalone
Experimental DOM Level 3 feature: Document standalone

userData

protected Hashtable userData
Table for user data attached to this document nodes.

version

protected String version
Experimental DOM Level 3 feature: Document version

xmlVersionChanged

protected boolean xmlVersionChanged

Constructor Details

CoreDocumentImpl

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

CoreDocumentImpl

public CoreDocumentImpl(boolean grammarAccess)
Constructor.

CoreDocumentImpl

public CoreDocumentImpl(org.w3c.dom.DocumentType doctype)
For DOM2 support. The createDocument factory method is in DOMImplementation.

CoreDocumentImpl

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

Method Details

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.

addEventListener

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

adoptNode

public org.w3c.dom.Node adoptNode(org.w3c.dom.Node source)
DOM Level 3 WD - Experimental Change the node's ownerDocument, and its subtree, to this Document
Specified by:
adoptNode in interface org.w3c.dom.Document
Parameters:
source - The node to adopt.

callUserDataHandlers

protected void callUserDataHandlers(org.w3c.dom.Node n,
                                    org.w3c.dom.Node c,
                                    short operation)
Call user data handlers when a node is deleted (finalized)
Parameters:
n - The node this operation applies to.
c - The copy node or null.
operation - The operation - import, clone, or delete.

changed

protected void changed()
Denotes that this node has changed.
Overrides:
changed in interface NodeImpl

changes

protected int changes()
Returns the number of changes to this node.
Overrides:
changes in interface NodeImpl

checkDOMNSErr

protected final void checkDOMNSErr(String prefix,
                                   String namespace)

checkNamespaceWF

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

checkQName

protected final void checkQName(String prefix,
                                String local)
Checks if the given qualified name is legal with respect to the version of XML to which this document must conform.
Parameters:
prefix - prefix of qualified name
local - local part of qualified name

clearIdentifiers

protected final void clearIdentifiers()
Remove all identifiers from the ID table

clone

public Object clone()
            throws CloneNotSupportedException
Clone.

cloneNode

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

cloneNode

protected void cloneNode(CoreDocumentImpl newdoc,
                         boolean deep)
internal method to share code with subclass

copyEventListeners

protected void copyEventListeners(NodeImpl src,
                                  NodeImpl tgt)

createAttribute

public org.w3c.dom.Attr createAttribute(String name)
            throws org.w3c.dom.DOMException
Factory method; creates an Attribute having this Document as its OwnerDoc.
Specified by:
createAttribute in interface org.w3c.dom.Document
Parameters:
name - The name of the attribute. Note that the attribute's value is _not_ established at the factory; remember to set it!

createAttributeNS

public org.w3c.dom.Attr createAttributeNS(String namespaceURI,
                                          String qualifiedName)
            throws org.w3c.dom.DOMException
Introduced in DOM Level 2.

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

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

createAttributeNS

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

createCDATASection

public org.w3c.dom.CDATASection createCDATASection(String data)
            throws org.w3c.dom.DOMException
Factory method; creates a CDATASection having this Document as its OwnerDoc.
Specified by:
createCDATASection in interface org.w3c.dom.Document
Parameters:
data - The initial contents of the CDATA

createComment

public org.w3c.dom.Comment createComment(String data)
Factory method; creates a Comment having this Document as its OwnerDoc.
Specified by:
createComment in interface org.w3c.dom.Document
Parameters:
data - The initial contents of the Comment.

createDocumentFragment

public org.w3c.dom.DocumentFragment createDocumentFragment()
Factory method; creates a DocumentFragment having this Document as its OwnerDoc.
Specified by:
createDocumentFragment in interface org.w3c.dom.Document

createDocumentType

public org.w3c.dom.DocumentType createDocumentType(String qualifiedName,
                                                   String publicID,
                                                   String systemID)
            throws org.w3c.dom.DOMException
NON-DOM Factory method; creates a DocumentType having this Document as its OwnerDoc. (REC-DOM-Level-1-19981001 left the process of building DTD information unspecified.)
Parameters:

createElement

public org.w3c.dom.Element createElement(String tagName)
            throws org.w3c.dom.DOMException
Factory method; creates an Element having this Document as its OwnerDoc.
Specified by:
createElement in interface org.w3c.dom.Document
Parameters:
tagName - The name of the element type to instantiate. For XML, this is case-sensitive. For HTML, the tagName parameter may be provided in any case, but it must be mapped to the canonical uppercase form by the DOM implementation.

createElementDefinition

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

createElementNS

public org.w3c.dom.Element createElementNS(String namespaceURI,
                                           String qualifiedName)
            throws org.w3c.dom.DOMException
Introduced in DOM Level 2.

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

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

createElementNS

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

createEntity

public org.w3c.dom.Entity createEntity(String name)
            throws org.w3c.dom.DOMException
NON-DOM Factory method; creates an Entity having this Document as its OwnerDoc. (REC-DOM-Level-1-19981001 left the process of building DTD information unspecified.)
Parameters:
name - The name of the Entity we wish to provide a value for.

createEntityReference

public org.w3c.dom.EntityReference createEntityReference(String name)
            throws org.w3c.dom.DOMException
Factory method; creates an EntityReference having this Document as its OwnerDoc.
Specified by:
createEntityReference in interface org.w3c.dom.Document
Parameters:
name - The name of the Entity we wish to refer to

createNotation

public org.w3c.dom.Notation createNotation(String name)
            throws org.w3c.dom.DOMException
NON-DOM Factory method; creates a Notation having this Document as its OwnerDoc. (REC-DOM-Level-1-19981001 left the process of building DTD information unspecified.)
Parameters:
name - The name of the Notation we wish to describe

createProcessingInstruction

public org.w3c.dom.ProcessingInstruction createProcessingInstruction(String target,
                                                                     String data)
            throws org.w3c.dom.DOMException
Factory method; creates a ProcessingInstruction having this Document as its OwnerDoc.
Specified by:
createProcessingInstruction in interface org.w3c.dom.Document
Parameters:
target - The target "processor channel"
data - Parameter string to be passed to the target.

createTextNode

public org.w3c.dom.Text createTextNode(String data)
Factory method; creates a Text node having this Document as its OwnerDoc.
Specified by:
createTextNode in interface org.w3c.dom.Document
Parameters:
data - The initial contents of the Text.

dispatchEvent

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

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.

getBaseURI

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

getDoctype

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

getDocumentElement

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

getDocumentURI

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

getDomConfig

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

getElementById

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

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

Specified by:
getElementById in interface org.w3c.dom.Document

getElementsByTagName

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

getElementsByTagNameNS

public org.w3c.dom.NodeList getElementsByTagNameNS(String namespaceURI,
                                                   String localName)
Introduced in DOM Level 2.

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

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

getEncoding

public String getEncoding()

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


getErrorChecking

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

getFeature

public Object getFeature(String feature,
                         String version)
Specified by:
getFeature in interface org.w3c.dom.Node
Overrides:
getFeature in interface NodeImpl
Since:
DOM Level 3

getIdentifier

public org.w3c.dom.Element getIdentifier(String idName)
Returns a previously registered element with the specified identifier name, or null if no element is registered.

getIdentifiers

public Enumeration getIdentifiers()
Returns an enumeration registered of identifier names.

getImplementation

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

getInputEncoding

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

getNodeName

public String getNodeName()
Returns the node name.
Specified by:
getNodeName in interface org.w3c.dom.Node
Overrides:
getNodeName in interface NodeImpl

getNodeNumber

protected int getNodeNumber()
NON-DOM: Get the number associated with this document. Used to order documents in the implementation.
Overrides:
getNodeNumber in interface NodeImpl

getNodeNumber

protected int getNodeNumber(org.w3c.dom.Node node)
NON-DOM: Get a number associated with a node created with respect to this document. Needed for compareDocumentPosition when nodes are disconnected. This is only used on demand.

getNodeType

public short getNodeType()
Returns the node type.
Specified by:
getNodeType in interface org.w3c.dom.Node
Overrides:
getNodeType in interface NodeImpl

getOwnerDocument

public final org.w3c.dom.Document getOwnerDocument()
Specified by:
getOwnerDocument in interface org.w3c.dom.Node
Overrides:
getOwnerDocument in interface ParentNode

getStandalone

public boolean getStandalone()

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


getStrictErrorChecking

public boolean getStrictErrorChecking()
Specified by:
getStrictErrorChecking in interface org.w3c.dom.Document

getTextContent

public String getTextContent()
            throws org.w3c.dom.DOMException
Specified by:
getTextContent in interface org.w3c.dom.Node
Overrides:
getTextContent in interface ParentNode

getUserData

protected Object getUserData(NodeImpl n)
NON-DOM: kept for backward compatibility Retreive user data related to a given node

getUserData

public Object getUserData(org.w3c.dom.Node n,
                          String key)
Retrieves the object associated to a key on a this node. The object must first have been set to this node by calling setUserData with the same key.
Parameters:
n - The node the object is associated to.
key - The key the object is associated to.
Returns:
Returns the DOMObject associated to the given key on this node, or null if there was none.
Since:
DOM Level 3

getUserDataRecord

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

getVersion

public String getVersion()

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


getXmlEncoding

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

getXmlStandalone

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

getXmlVersion

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

importNode

public org.w3c.dom.Node importNode(org.w3c.dom.Node source,
                                   boolean deep)
            throws org.w3c.dom.DOMException
Copies a node from another document to this document. The new nodes are created using this document's factory methods and are populated with the data from the source's accessor methods defined by the DOM interfaces. Its behavior is otherwise similar to that of cloneNode.

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

Specified by:
importNode in interface org.w3c.dom.Document

insertBefore

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

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

Specified by:
insertBefore in interface org.w3c.dom.Node
Overrides:
insertBefore in interface ParentNode

isKidOK

protected boolean isKidOK(org.w3c.dom.Node parent,
                          org.w3c.dom.Node child)
Uses the kidOK lookup table to check whether the proposed tree structure is legal.

isValidQName

public static final boolean isValidQName(String prefix,
                                         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

isXMLName

public static final boolean isXMLName(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

load

public boolean load(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(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.

normalizeDocument

public void normalizeDocument()
DOM Level 3 WD - Experimental Normalize document.
Specified by:
normalizeDocument in interface org.w3c.dom.Document

putIdentifier

public void putIdentifier(String idName,
                          org.w3c.dom.Element element)
Registers an identifier name with a specified element node. If the identifier is already registered, the new element node replaces the previous node. If the specified element node is null, removeIdentifier() is called.

removeChild

public org.w3c.dom.Node removeChild(org.w3c.dom.Node oldChild)
            throws org.w3c.dom.DOMException
Since insertBefore caches the docElement (and, currently, docType), removeChild has to know how to undo the cache REVISIT: According to the spec it is not allowed to alter neither the document element nor the document type in any way
Specified by:
removeChild in interface org.w3c.dom.Node
Overrides:
removeChild in interface ParentNode

removeEventListener

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

removeIdentifier

public void removeIdentifier(String idName)
Removes a previously registered element with the specified identifier name.

renameNode

public org.w3c.dom.Node renameNode(org.w3c.dom.Node n,
                                   String namespaceURI,
                                   String name)
            throws org.w3c.dom.DOMException
DOM Level 3 WD - Experimental. Renaming node
Specified by:
renameNode in interface org.w3c.dom.Document

replaceChild

public org.w3c.dom.Node replaceChild(org.w3c.dom.Node newChild,
                                     org.w3c.dom.Node oldChild)
            throws org.w3c.dom.DOMException
Since we cache the docElement (and, currently, docType), replaceChild has to update the cache REVISIT: According to the spec it is not allowed to alter neither the document element nor the document type in any way
Specified by:
replaceChild in interface org.w3c.dom.Node
Overrides:
replaceChild in interface ParentNode

saveXML

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

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.

setDocumentURI

public void setDocumentURI(String documentURI)
DOM Level 3 WD - Experimental.
Specified by:
setDocumentURI in interface org.w3c.dom.Document

setEncoding

public void setEncoding(String value)

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


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

setInputEncoding

public void setInputEncoding(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 .

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.


setStrictErrorChecking

public void setStrictErrorChecking(boolean check)
Specified by:
setStrictErrorChecking in interface org.w3c.dom.Document

setTextContent

public void setTextContent(String textContent)
            throws org.w3c.dom.DOMException
Specified by:
setTextContent in interface org.w3c.dom.Node
Overrides:
setTextContent in interface ParentNode

setUserData

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

setUserData

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

setVersion

public void setVersion(String value)

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


setXmlEncoding

public void setXmlEncoding(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.

setXmlStandalone

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

setXmlVersion

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

undeferChildren

protected void undeferChildren(org.w3c.dom.Node node)
Traverses the DOM Tree and expands deferred nodes and their children.

Copyright B) 1999-2006 The Apache Software Foundation. All Rights Reserved.