public class DocumentImpl
implements DocumentTraversal, DocumentEvent, DocumentRange
The Document interface represents the entire HTML or XML document.
Conceptually, it is the root of the document tree, and provides the
primary access to the document's data.
Since elements, text nodes, comments, processing instructions,
etc. cannot exist outside the context of a Document, the Document
interface also contains the factory methods needed to create these
objects. The Node objects created have a ownerDocument attribute
which associates them with the Document within whose context they
were created.
The DocumentImpl class also implements the DOM Level 2 DocumentTraversal
interface. This interface is comprised of factory methods needed to
create NodeIterators and TreeWalkers. The process of creating NodeIterator
objects also adds these references to this document.
After finishing with an iterator it is important to remove the object
using the remove methods in this implementation. This allows the release of
the references from the iterator objects to the DOM Nodes.
Note: When any node in the document is serialized, the
entire document is serialized along with it.
addEventListener
protected void addEventListener(NodeImpl node,
String type,
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.
- addEventListener in interface CoreDocumentImpl
node
- node to add listener totype
- Event name (NOT event group!) to listen for.listener
- Who gets called when event is dispatcheduseCapture
- True iff listener is registered on
capturing phase rather than at-target or bubbling
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.
- cloneNode in interface CoreDocumentImpl
deep
- boolean, iff true replicate children
createEvent
public Event createEvent(String type)
throws DOMException
Introduced in DOM Level 2. Optional.
Create and return Event objects.
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.
createNodeIterator
public NodeIterator createNodeIterator(Node root,
int whatToShow,
NodeFilter filter,
boolean entityReferenceExpansion)
Create and return a NodeIterator. The NodeIterator is
added to a list of NodeIterators so that it can be
removed to free up the DOM Nodes it references.
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
createNodeIterator
public NodeIterator createNodeIterator(Node root,
short whatToShow,
NodeFilter filter)
NON-DOM extension:
Create and return a NodeIterator. The NodeIterator is
added to a list of NodeIterators so that it can be
removed to free up the DOM Nodes it references.
root
- The root of the iterator.whatToShow
- The whatToShow mask.filter
- The NodeFilter installed. Null means no filter.
createRange
public Range createRange()
createTreeWalker
public TreeWalker createTreeWalker(Node root,
int whatToShow,
NodeFilter filter,
boolean entityReferenceExpansion)
Create and return a TreeWalker.
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
createTreeWalker
public TreeWalker createTreeWalker(Node root,
short whatToShow,
NodeFilter filter)
NON-DOM extension:
Create and return a TreeWalker.
root
- The root of the iterator.whatToShow
- The whatToShow mask.filter
- The NodeFilter installed. Null means no filter.
dispatchAggregateEvents
protected void dispatchAggregateEvents(NodeImpl node,
AttrImpl enclosingAttr,
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.
node
- The node to dispatch toenclosingAttr
- The Attr node (if any) whose value has been changed
as a result of the DOM operation. Null if none such.change
- Type of modification to the attr. See
MutationEvent.attrChange
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
.
node
- node to dispatch toea
- description of Attr affected by current operation
dispatchEvent
protected boolean dispatchEvent(NodeImpl node,
Event event)
Introduced in DOM Level 2.
Distribution engine for DOM Level 2 Events.
Event propagation runs as follows:
- 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.
- 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.
- CAPTURING_PHASE: Ancestors are scanned, root to target, for
Capturing listeners. If found, they are invoked (see below).
- AT_TARGET:
Event is dispatched to NON-CAPTURING listeners on the
target node. Note that capturing listeners on this node are _not_
invoked.
- BUBBLING_PHASE: Ancestors are scanned, target to root, for
non-capturing listeners.
- 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.
- dispatchEvent in interface CoreDocumentImpl
node
- node to dispatch toevent
- the event object to be dispatched to
registered EventListeners
- true if the event's
preventDefault()
method was invoked by an EventListener; otherwise false.
dispatchEventToSubtree
protected void dispatchEventToSubtree(Node n,
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.
n
- target node (that was directly inserted or removed)e
- event to be sent to that node and its subtree
dispatchingEventToSubtree
protected void dispatchingEventToSubtree(Node n,
Event e)
Dispatches event to the target node's descendents recursively
n
- node to dispatch toe
- event to be sent to that node and its subtree
getEventListeners
protected Vector getEventListeners(NodeImpl n)
Retreive event listener registered on a given node
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.
- getImplementation in interface CoreDocumentImpl
removeEventListener
protected void removeEventListener(NodeImpl node,
String type,
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.
- removeEventListener in interface CoreDocumentImpl
node
- node to remove listener fromtype
- Event name (NOT event group!) to listen for.listener
- Who gets called when event is dispatcheduseCapture
- True iff listener is registered on
capturing phase rather than at-target or bubbling
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
node
- node to get enclosing attribute for
setEventListeners
protected void setEventListeners(NodeImpl n,
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.