org.apache.xerces.dom
Class DocumentImpl

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
                  extended by org.apache.xerces.dom.DocumentImpl
All Implemented Interfaces:
java.io.Serializable, java.lang.Cloneable, org.w3c.dom.Document, org.w3c.dom.events.DocumentEvent, org.w3c.dom.events.EventTarget, org.w3c.dom.Node, org.w3c.dom.NodeList, org.w3c.dom.ranges.DocumentRange, org.w3c.dom.traversal.DocumentTraversal
Direct Known Subclasses:
DeferredDocumentImpl, PSVIDocumentImpl

public class DocumentImpl
extends CoreDocumentImpl
implements org.w3c.dom.traversal.DocumentTraversal, org.w3c.dom.events.DocumentEvent, org.w3c.dom.ranges.DocumentRange

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

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

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

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

Since:
PR-DOM-Level-1-19980818.
Version:
$Id: DocumentImpl.java 890667 2009-12-15 06:41:08Z mrglavas $
Author:
Arnaud Le Hors, IBM, Joe Kesselman, IBM, Andy Clark, IBM, Ralf Pfeiffer, IBM
See Also:
Serialized Form

INTERNAL:

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

Field Summary
protected  java.util.Hashtable eventListeners
          Table for event listeners registered to this document nodes.
protected  java.lang.ref.ReferenceQueue iteratorReferenceQueue
          Reference queue for cleared Node Iterator references
protected  java.util.List iterators
          Node Iterators
protected  boolean mutationEvents
          Bypass mutation events firing.
protected  java.lang.ref.ReferenceQueue rangeReferenceQueue
          Reference queue for cleared Range references
protected  java.util.List ranges
          Ranges
 
Fields inherited from class org.apache.xerces.dom.CoreDocumentImpl
actualEncoding, allowGrammarAccess, changes, docElement, docType, encoding, errorChecking, fDocumentURI, identifiers, standalone, userData, version, xmlVersionChanged
 
Fields inherited from class org.apache.xerces.dom.ParentNode
firstChild, fNodeListCache, ownerDocument
 
Fields inherited from class org.apache.xerces.dom.ChildNode
nextSibling, previousSibling
 
Fields inherited from class org.apache.xerces.dom.NodeImpl
DOCUMENT_POSITION_CONTAINS, DOCUMENT_POSITION_DISCONNECTED, DOCUMENT_POSITION_FOLLOWING, DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC, DOCUMENT_POSITION_IS_CONTAINED, DOCUMENT_POSITION_PRECEDING, ELEMENT_DEFINITION_NODE, FIRSTCHILD, flags, HASSTRING, ID, IGNORABLEWS, NORMALIZED, OWNED, ownerNode, READONLY, SPECIFIED, SYNCCHILDREN, SYNCDATA, TREE_POSITION_ANCESTOR, TREE_POSITION_DESCENDANT, TREE_POSITION_DISCONNECTED, TREE_POSITION_EQUIVALENT, TREE_POSITION_FOLLOWING, TREE_POSITION_PRECEDING, TREE_POSITION_SAME_NODE
 
Fields inherited from interface org.w3c.dom.Node
ATTRIBUTE_NODE, CDATA_SECTION_NODE, COMMENT_NODE, DOCUMENT_FRAGMENT_NODE, DOCUMENT_NODE, DOCUMENT_POSITION_CONTAINED_BY, DOCUMENT_POSITION_CONTAINS, DOCUMENT_POSITION_DISCONNECTED, DOCUMENT_POSITION_FOLLOWING, DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC, DOCUMENT_POSITION_PRECEDING, DOCUMENT_TYPE_NODE, ELEMENT_NODE, ENTITY_NODE, ENTITY_REFERENCE_NODE, NOTATION_NODE, PROCESSING_INSTRUCTION_NODE, TEXT_NODE
 
Constructor Summary
DocumentImpl()
          NON-DOM: Actually creating a Document is outside the DOM's spec, since it has to operate in terms of a particular implementation.
DocumentImpl(boolean grammarAccess)
          Constructor.
DocumentImpl(org.w3c.dom.DocumentType doctype)
          For DOM2 support.
DocumentImpl(org.w3c.dom.DocumentType doctype, boolean grammarAccess)
          For DOM2 support.
 
Method Summary
protected  void addEventListener(NodeImpl node, java.lang.String type, org.w3c.dom.events.EventListener listener, boolean useCapture)
          Introduced in DOM Level 2.
 org.w3c.dom.Node cloneNode(boolean deep)
          Deep-clone a document, including fixing ownerDoc for the cloned children.
protected  void copyEventListeners(NodeImpl src, NodeImpl tgt)
           
 org.w3c.dom.events.Event createEvent(java.lang.String type)
          Introduced in DOM Level 2.
 org.w3c.dom.traversal.NodeIterator createNodeIterator(org.w3c.dom.Node root, int whatToShow, org.w3c.dom.traversal.NodeFilter filter, boolean entityReferenceExpansion)
          Create and return a NodeIterator.
 org.w3c.dom.traversal.NodeIterator createNodeIterator(org.w3c.dom.Node root, short whatToShow, org.w3c.dom.traversal.NodeFilter filter)
          NON-DOM extension: Create and return a NodeIterator.
 org.w3c.dom.ranges.Range createRange()
           
 org.w3c.dom.traversal.TreeWalker createTreeWalker(org.w3c.dom.Node root, int whatToShow, org.w3c.dom.traversal.NodeFilter filter, boolean entityReferenceExpansion)
          Create and return a TreeWalker.
 org.w3c.dom.traversal.TreeWalker createTreeWalker(org.w3c.dom.Node root, short whatToShow, org.w3c.dom.traversal.NodeFilter filter)
          NON-DOM extension: Create and return a TreeWalker.
protected  void dispatchAggregateEvents(NodeImpl node, AttrImpl enclosingAttr, java.lang.String oldvalue, short change)
          NON-DOM INTERNAL: Generate the "aggregated" post-mutation events DOMAttrModified and DOMSubtreeModified.
protected  void dispatchAggregateEvents(NodeImpl node, org.apache.xerces.dom.DocumentImpl.EnclosingAttr ea)
          NON-DOM INTERNAL: Convenience wrapper for calling dispatchAggregateEvents when the context was established by savedEnclosingAttr.
protected  boolean dispatchEvent(NodeImpl node, org.w3c.dom.events.Event event)
          Introduced in DOM Level 2.
protected  void dispatchEventToSubtree(org.w3c.dom.Node n, org.w3c.dom.events.Event e)
          NON-DOM INTERNAL: DOMNodeInsertedIntoDocument and ...RemovedFrom...
protected  void dispatchingEventToSubtree(org.w3c.dom.Node n, org.w3c.dom.events.Event e)
          Dispatches event to the target node's descendents recursively
protected  java.util.Vector getEventListeners(NodeImpl n)
          Retreive event listener registered on a given node
 org.w3c.dom.DOMImplementation getImplementation()
          Retrieve information describing the abilities of this particular DOM implementation.
protected  void removeEventListener(NodeImpl node, java.lang.String type, org.w3c.dom.events.EventListener listener, boolean useCapture)
          Introduced in DOM Level 2.
protected  void saveEnclosingAttr(NodeImpl node)
          NON-DOM INTERNAL: Pre-mutation context check, in preparation for later generating DOMAttrModified events.
protected  void setEventListeners(NodeImpl n, java.util.Vector listeners)
          Store event listener registered on a given node This is another place where we could use weak references! Indeed, the node here won't be GC'ed as long as some listener is registered on it, since the eventsListeners table will have a reference to the node.
 
Methods inherited from class org.apache.xerces.dom.CoreDocumentImpl
abort, adoptNode, callUserDataHandlers, canRenameElements, changed, changes, checkDOMNSErr, checkNamespaceWF, checkQName, clearIdentifiers, clone, cloneNode, createAttribute, createAttributeNS, createAttributeNS, createCDATASection, createComment, createDocumentFragment, createDocumentType, createElement, createElementDefinition, createElementNS, createElementNS, createEntity, createEntityReference, createNotation, createProcessingInstruction, createTextNode, getAsync, getBaseURI, getDoctype, getDocumentElement, getDocumentURI, getDomConfig, getElementById, getElementsByTagName, getElementsByTagNameNS, getEncoding, getErrorChecking, getFeature, getIdentifier, getIdentifiers, getInputEncoding, getNodeName, getNodeNumber, getNodeNumber, getNodeType, getOwnerDocument, getStandalone, getStrictErrorChecking, getTextContent, getUserData, getUserData, getUserDataRecord, getVersion, getXmlEncoding, getXmlStandalone, getXmlVersion, importNode, insertBefore, isKidOK, isValidQName, isXMLName, load, loadXML, normalizeDocument, putIdentifier, removeChild, removeIdentifier, renameNode, replaceChild, saveXML, setAsync, setDocumentURI, setEncoding, setErrorChecking, setInputEncoding, setStandalone, setStrictErrorChecking, setTextContent, setUserData, setUserData, setVersion, setXmlEncoding, setXmlStandalone, setXmlVersion, undeferChildren
 
Methods inherited from class org.apache.xerces.dom.ParentNode
getChildNodes, getChildNodesUnoptimized, getFirstChild, getLastChild, getLength, hasChildNodes, isEqualNode, item, normalize, setOwnerDocument, setReadOnly, synchronizeChildren
 
Methods inherited from class org.apache.xerces.dom.ChildNode
getNextSibling, getParentNode, getPreviousSibling
 
Methods inherited from class org.apache.xerces.dom.NodeImpl
addEventListener, appendChild, compareDocumentPosition, compareTreePosition, dispatchEvent, getAttributes, getContainer, getLocalName, getNamespaceURI, getNodeValue, getPrefix, getReadOnly, getUserData, getUserData, getUserDataRecord, hasAttributes, isDefaultNamespace, isSameNode, isSupported, lookupNamespaceURI, lookupPrefix, needsSyncChildren, removeEventListener, setNodeValue, setPrefix, setUserData, setUserData, synchronizeData, toString
 
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface org.w3c.dom.Node
appendChild, compareDocumentPosition, getAttributes, getChildNodes, getFirstChild, getLastChild, getLocalName, getNamespaceURI, getNextSibling, getNodeValue, getParentNode, getPrefix, getPreviousSibling, getUserData, hasAttributes, hasChildNodes, isDefaultNamespace, isEqualNode, isSameNode, isSupported, lookupNamespaceURI, lookupPrefix, normalize, setNodeValue, setPrefix, setUserData
 

Field Detail

iterators

protected transient java.util.List iterators
Node Iterators


iteratorReferenceQueue

protected transient java.lang.ref.ReferenceQueue iteratorReferenceQueue
Reference queue for cleared Node Iterator references


ranges

protected transient java.util.List ranges
Ranges


rangeReferenceQueue

protected transient java.lang.ref.ReferenceQueue rangeReferenceQueue
Reference queue for cleared Range references


eventListeners

protected java.util.Hashtable eventListeners
Table for event listeners registered to this document nodes.


mutationEvents

protected boolean mutationEvents
Bypass mutation events firing.

Constructor Detail

DocumentImpl

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


DocumentImpl

public DocumentImpl(boolean grammarAccess)
Constructor.


DocumentImpl

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


DocumentImpl

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

Method Detail

cloneNode

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

Specified by:
cloneNode in interface org.w3c.dom.Node
Overrides:
cloneNode in class CoreDocumentImpl
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.


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
Overrides:
getImplementation in class CoreDocumentImpl

createNodeIterator

public org.w3c.dom.traversal.NodeIterator createNodeIterator(org.w3c.dom.Node root,
                                                             short whatToShow,
                                                             org.w3c.dom.traversal.NodeFilter filter)
NON-DOM extension: Create and return a NodeIterator. The NodeIterator is added to a list of NodeIterators so that it can be removed to free up the DOM Nodes it references.

Parameters:
root - The root of the iterator.
whatToShow - The whatToShow mask.
filter - The NodeFilter installed. Null means no filter.

createNodeIterator

public org.w3c.dom.traversal.NodeIterator createNodeIterator(org.w3c.dom.Node root,
                                                             int whatToShow,
                                                             org.w3c.dom.traversal.NodeFilter filter,
                                                             boolean entityReferenceExpansion)
Create and return a NodeIterator. The NodeIterator is added to a list of NodeIterators so that it can be removed to free up the DOM Nodes it references.

Specified by:
createNodeIterator in interface org.w3c.dom.traversal.DocumentTraversal
Parameters:
root - The root of the iterator.
whatToShow - The whatToShow mask.
filter - The NodeFilter installed. Null means no filter.
entityReferenceExpansion - true to expand the contents of EntityReference nodes
Since:
WD-DOM-Level-2-19990923

createTreeWalker

public org.w3c.dom.traversal.TreeWalker createTreeWalker(org.w3c.dom.Node root,
                                                         short whatToShow,
                                                         org.w3c.dom.traversal.NodeFilter filter)
NON-DOM extension: Create and return a TreeWalker.

Parameters:
root - The root of the iterator.
whatToShow - The whatToShow mask.
filter - The NodeFilter installed. Null means no filter.

createTreeWalker

public org.w3c.dom.traversal.TreeWalker createTreeWalker(org.w3c.dom.Node root,
                                                         int whatToShow,
                                                         org.w3c.dom.traversal.NodeFilter filter,
                                                         boolean entityReferenceExpansion)
Create and return a TreeWalker.

Specified by:
createTreeWalker in interface org.w3c.dom.traversal.DocumentTraversal
Parameters:
root - The root of the iterator.
whatToShow - The whatToShow mask.
filter - The NodeFilter installed. Null means no filter.
entityReferenceExpansion - true to expand the contents of EntityReference nodes
Since:
WD-DOM-Level-2-19990923

createRange

public org.w3c.dom.ranges.Range createRange()
Specified by:
createRange in interface org.w3c.dom.ranges.DocumentRange

createEvent

public org.w3c.dom.events.Event createEvent(java.lang.String type)
                                     throws org.w3c.dom.DOMException
Introduced in DOM Level 2. Optional.

Create and return Event objects.

Specified by:
createEvent in interface org.w3c.dom.events.DocumentEvent
Parameters:
type - The eventType parameter specifies the type of Event interface to be created. If the Event interface specified is supported by the implementation this method will return a new Event of the interface type requested. If the Event is to be dispatched via the dispatchEvent method the appropriate event init method must be called after creation in order to initialize the Event's values. As an example, a user wishing to synthesize some kind of Event would call createEvent with the parameter "Events". The initEvent method could then be called on the newly created Event to set the specific type of Event to be dispatched and set its context information.
Returns:
Newly created Event
Throws:
org.w3c.dom.DOMException - NOT_SUPPORTED_ERR: Raised if the implementation does not support the type of Event interface requested
Since:
WD-DOM-Level-2-19990923

setEventListeners

protected void setEventListeners(NodeImpl n,
                                 java.util.Vector listeners)
Store event listener registered on a given node This is another place where we could use weak references! Indeed, the node here won't be GC'ed as long as some listener is registered on it, since the eventsListeners table will have a reference to the node.


getEventListeners

protected java.util.Vector getEventListeners(NodeImpl n)
Retreive event listener registered on a given node


addEventListener

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

Register an event listener with this Node. A listener may be independently registered as both Capturing and Bubbling, but may only be registered once per role; redundant registrations are ignored.

Overrides:
addEventListener in class CoreDocumentImpl
Parameters:
node - node to add listener to
type - Event name (NOT event group!) to listen for.
listener - Who gets called when event is dispatched
useCapture - True iff listener is registered on capturing phase rather than at-target or bubbling

removeEventListener

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

Deregister an event listener previously registered with this Node. A listener must be independently removed from the Capturing and Bubbling roles. Redundant removals (of listeners not currently registered for this role) are ignored.

Overrides:
removeEventListener in class CoreDocumentImpl
Parameters:
node - node to remove listener from
type - Event name (NOT event group!) to listen for.
listener - Who gets called when event is dispatched
useCapture - True iff listener is registered on capturing phase rather than at-target or bubbling

copyEventListeners

protected void copyEventListeners(NodeImpl src,
                                  NodeImpl tgt)
Overrides:
copyEventListeners in class CoreDocumentImpl

dispatchEvent

protected boolean dispatchEvent(NodeImpl node,
                                org.w3c.dom.events.Event event)
Introduced in DOM Level 2.

Distribution engine for DOM Level 2 Events.

Event propagation runs as follows:

  1. Event is dispatched to a particular target node, which invokes this code. Note that the event's stopPropagation flag is cleared when dispatch begins; thereafter, if it has been set before processing of a node commences, we instead immediately advance to the DEFAULT phase.
  2. The node's ancestors are established as destinations for events. For capture and bubble purposes, node ancestry is determined at the time dispatch starts. If an event handler alters the document tree, that does not change which nodes will be informed of the event.
  3. CAPTURING_PHASE: Ancestors are scanned, root to target, for Capturing listeners. If found, they are invoked (see below).
  4. AT_TARGET: Event is dispatched to NON-CAPTURING listeners on the target node. Note that capturing listeners on this node are _not_ invoked.
  5. BUBBLING_PHASE: Ancestors are scanned, target to root, for non-capturing listeners.
  6. Default processing: Some DOMs have default behaviors bound to specific nodes. If this DOM does, and if the event's preventDefault flag has not been set, we now return to the target node and process its default handler for this event, if any.

Note that registration of handlers during processing of an event does not take effect during this phase of this event; they will not be called until the next time this node is visited by dispatchEvent. On the other hand, removals take effect immediately.

If an event handler itself causes events to be dispatched, they are processed synchronously, before processing resumes on the event which triggered them. Please be aware that this may result in events arriving at listeners "out of order" relative to the actual sequence of requests.

Note that our implementation resets the event's stop/prevent flags when dispatch begins. I believe the DOM's intent is that event objects be redispatchable, though it isn't stated in those terms.

Overrides:
dispatchEvent in class CoreDocumentImpl
Parameters:
node - node to dispatch to
event - the event object to be dispatched to registered EventListeners
Returns:
true if the event's preventDefault() method was invoked by an EventListener; otherwise false.

dispatchEventToSubtree

protected void dispatchEventToSubtree(org.w3c.dom.Node n,
                                      org.w3c.dom.events.Event e)
NON-DOM INTERNAL: DOMNodeInsertedIntoDocument and ...RemovedFrom... are dispatched to an entire subtree. This is the distribution code therefor. They DO NOT bubble, thanks be, but may be captured.

Similar to code in dispatchingEventToSubtree however this method is only used on the target node and does not start a dispatching chain on the sibling of the target node as this is not part of the subtree ***** At the moment I'm being sloppy and using the normal capture dispatcher on every node. This could be optimized hugely by writing a capture engine that tracks our position in the tree to update the capture chain without repeated chases up to root.

Parameters:
n - target node (that was directly inserted or removed)
e - event to be sent to that node and its subtree

dispatchingEventToSubtree

protected void dispatchingEventToSubtree(org.w3c.dom.Node n,
                                         org.w3c.dom.events.Event e)
Dispatches event to the target node's descendents recursively

Parameters:
n - node to dispatch to
e - event to be sent to that node and its subtree

dispatchAggregateEvents

protected void dispatchAggregateEvents(NodeImpl node,
                                       org.apache.xerces.dom.DocumentImpl.EnclosingAttr ea)
NON-DOM INTERNAL: Convenience wrapper for calling dispatchAggregateEvents when the context was established by savedEnclosingAttr.

Parameters:
node - node to dispatch to
ea - description of Attr affected by current operation

dispatchAggregateEvents

protected void dispatchAggregateEvents(NodeImpl node,
                                       AttrImpl enclosingAttr,
                                       java.lang.String oldvalue,
                                       short change)
NON-DOM INTERNAL: Generate the "aggregated" post-mutation events DOMAttrModified and DOMSubtreeModified. Both of these should be issued only once for each user-requested mutation operation, even if that involves multiple changes to the DOM. For example, if a DOM operation makes multiple changes to a single Attr before returning, it would be nice to generate only one DOMAttrModified, and multiple changes over larger scope but within a recognizable single subtree might want to generate only one DOMSubtreeModified, sent to their lowest common ancestor.

To manage this, use the "internal" versions of insert and remove with MUTATION_LOCAL, then make an explicit call to this routine at the higher level. Some examples now exist in our code.

Parameters:
node - The node to dispatch to
enclosingAttr - The Attr node (if any) whose value has been changed as a result of the DOM operation. Null if none such.
oldvalue - The String value previously held by the enclosingAttr. Ignored if none such.
change - Type of modification to the attr. See MutationEvent.attrChange

saveEnclosingAttr

protected void saveEnclosingAttr(NodeImpl node)
NON-DOM INTERNAL: Pre-mutation context check, in preparation for later generating DOMAttrModified events. Determines whether this node is within an Attr

Parameters:
node - node to get enclosing attribute for


Copyright 1999-2010 The Apache Software Foundation. All Rights Reserved.