org.apache.xerces.dom3.ls
Interface DOMBuilderFilter


public interface DOMBuilderFilter

DOMBuilderFilters provide applications the ability to examine nodes as they are being constructed during a parse. As each node is examined, it may be modified or removed, or the entire parse may be terminated early.

At the time any of the filter methods are called by the parser, the owner Document and DOMImplementation objects exist and are accessible. The document element is never passed to the DOMBuilderFilter methods, i.e. it is not possible to filter out the document element.

All validity checking while reading a document occurs on the source document as it appears on the input stream, not on the DOM document as it is built in memory. With filters, the document in memory may be a subset of the document on the stream, and its validity may have been affected by the filtering.The description of these methods is not complete

See also the Document Object Model (DOM) Level 3 Abstract Schemas and Load and Save Specification.


Method Summary
 int endNode(org.w3c.dom.Node enode)
          This method will be called by the parser at the completion of the parse of each node.
 int getWhatToShow()
          Tells the DOMBuilder what types of nodes to show to the filter.
 int startNode(org.w3c.dom.Node snode)
          This method will be called by the parser after each Element start tag has been scanned, but before the remainder of the Element is processed.
 

Method Detail

startNode

public int startNode(org.w3c.dom.Node snode)
This method will be called by the parser after each Element start tag has been scanned, but before the remainder of the Element is processed. The intent is to allow the element, including any children, to be efficiently skipped. Note that only element nodes are passed to the startNode function.
The element node passed to startNode for filtering will include all of the Element's attributes, but none of the children nodes. The Element may not yet be in place in the document being constructed (it may not have a parent node.)
A startNode filter function may access or change the attributers for the Element. Changing Namespace declarations will have no effect on namespace resolution by the parser.
For efficiency, the Element node passed to the filter may not be the same one as is actually placed in the tree if the node is accepted. And the actual node (node object identity) may be reused during the process of reading in and filtering a document.
Parameters:
snode - The newly encountered element. At the time this method is called, the element is incomplete - it will have its attributes, but no children. Should the parameter be an Element since we only passed elements to startNode?
Returns:
ACCEPT if this Element should be included in the DOM document being built. REJECT if the Element and all of its children should be rejected. SKIP if the Element should be rejected. All of its children are inserted in place of the rejected Element node.

endNode

public int endNode(org.w3c.dom.Node enode)
This method will be called by the parser at the completion of the parse of each node. The node will exist and be complete, as will all of its children, and their children, recursively. The parent node will also exist, although that node may be incomplete, as it may have additional children that have not yet been parsed. Attribute nodes are never passed to this function.
From within this method, the new node may be freely modified - children may be added or removed, text nodes modified, etc. This node may also be removed from its parent node, which will prevent it from appearing in the final document at the completion of the parse. Aside from this one operation on the node's parent, the state of the rest of the document outside of this node is not defined, and the affect of any attempt to navigate to or modify any other part of the document is undefined.
For validating parsers, the checks are made on the original document, before any modification by the filter. No validity checks are made on any document modifications made by the filter.
Parameters:
enode - The newly constructed element. At the time this method is called, the element is complete - it has all of its children (and their children, recursively) and attributes, and is attached as a child to its parent.
Returns:
ACCEPT if this Node should be included in the DOM document being built. REJECT if the Node and all of its children should be rejected.

getWhatToShow

public int getWhatToShow()
Tells the DOMBuilder what types of nodes to show to the filter. See NodeFilter for definition of the constants. The constant SHOW_ATTRIBUTE is meaningless here, attribute nodes will never be passed to a DOMBuilderFilter.


Copyright © 1999-2002 Apache XML Project. All Rights Reserved.