Java Doc for DocumentImpl.java in  » XML » xerces-2_9_1 » org » apache » xerces » dom » Java Source Code / Java DocumentationJava Source Code and Java Documentation

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.
author:
   Arnaud Le Hors, IBM
author:
   Joe Kesselman, IBM
author:
   Andy Clark, IBM
author:
   Ralf Pfeiffer, IBM
version:
   $Id: DocumentImpl.java 542096 2007-05-28 03:18:11Z mrglavas $
since:
   PR-DOM-Level-1-19980818.

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.
Parameters:
  node - node to add listener to
Parameters:
  type - Event name (NOT event group!) to listen for.
Parameters:
  listener - Who gets called when event is dispatched
Parameters:
  useCapture - True iff listener is registered oncapturing phase rather than at-target or bubbling

Create and return Event objects.
Parameters:
  type - The eventType parameter specifies the type of Eventinterface to be created. If the Event interface specified is supportedby the implementation this method will return a new Event of theinterface type requested. If the Event is to be dispatched via thedispatchEvent method the appropriate event init method must be calledafter creation in order to initialize the Event's values. As anexample, a user wishing to synthesize some kind of Event would callcreateEvent with the parameter "Events". The initEvent method could thenbe called on the newly created Event to set the specific type of Eventto be dispatched and set its context information. Newly created Event
exception:
  DOMException - NOT_SUPPORTED_ERR: Raised if the implementationdoes not support the type of Event interface requested
since:
   WD-DOM-Level-2-19990923

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
Parameters:
  enclosingAttr - The Attr node (if any) whose value has been changedas a result of the DOM operation. Null if none such.
Parameters:
  oldvalue - The String value previously held by theenclosingAttr. Ignored if none such.
Parameters:
  change - Type of modification to the attr. SeeMutationEvent.attrChange

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.
Parameters:
  node - node to dispatch to
Parameters:
  event - the event object to be dispatched to registered EventListeners true if the event's preventDefault()method was invoked by an EventListener; otherwise false.

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)
Parameters:
  e - event to be sent to that node and its subtree

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.
Parameters:
  node - node to remove listener from
Parameters:
  type - Event name (NOT event group!) to listen for.
Parameters:
  listener - Who gets called when event is dispatched
Parameters:
  useCapture - True iff listener is registered oncapturing phase rather than at-target or bubbling

This function is called from the NodeIterator#detach().