Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.w3c.dom.ls
Interface DOMBuilderFilter

public interface DOMBuilderFilter

DOM Level 3 WD Experimental: The DOM Level 3 specification is at the stage of Working Draft, which represents work in progress and thus may be updated, replaced, or obsoleted by other documents at any time. `DOMBuilderFilter`s 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. The `Document`, `DocumentType`, `Notation`, and `Entity` nodes are not passed to the filter.

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.

All default content, including default attributes, must be passed to the filter methods.

Any exception raised in the filter are ignored by the `DOMBuilder`.

Note: The description of these methods is not complete

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

Field Summary
`static short` | `FILTER_ACCEPT` Accept the node.
`static short` | `FILTER_INTERRUPT` Interrupt the normal processing of the document.
`static short` | `FILTER_REJECT` Reject the node abd its children.
`static short` | `FILTER_SKIP` Skip this single node.

Method Summary
`short` | `acceptNode(Node enode)` This method will be called by the parser at the completion of the parsing of each node.
`int` | `getWhatToShow()` Tells the `DOMBuilder` what types of nodes to show to the filter.
`short` | `startElement(Element elt)` 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.

Field Detail

### FILTER_ACCEPT

    public static final short FILTER_ACCEPT

  Accept the node.

### FILTER_REJECT

    public static final short FILTER_REJECT

  Reject the node abd its children.

### FILTER_SKIP

    public static final short FILTER_SKIP

  Skip this single node. The children of this node will still be considered.

### FILTER_INTERRUPT

    public static final short FILTER_INTERRUPT

  Interrupt the normal processing of the document.

Method Detail

### startElement

    public short startElement(Element elt)

  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 `startElement` function.
  The element node passed to `startElement` 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 `startElement` filter function may access or change the attributes 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:
    `elt` - The newly encountered element. At the time this method is called, the element is incomplete - it will have its attributes, but no children.
  Returns:
    - `FILTER_ACCEPT` if this `Element` should be included in the DOM document being built.
    - `FILTER_REJECT` if the `Element` and all of its children should be rejected. This return value will be ignored if `elt` is the documentElement, the documentElement can not be rejected.
    - `FILTER_SKIP` if the `Element` should be rejected. All of its children are inserted in place of the rejected `Element` node. This return value will be ignored if `elt` is the documentElement, the documentElement can not be rejected nor skipped.
    - `FILTER_INTERRUPT` if the filter wants to stop the processing of the document. Interrupting the processing of the document does no longer guarantee that the entire is XML well-formed .
    Returning any other values will result in unspecified behavior.

### acceptNode

    public short acceptNode(Node enode)

  This method will be called by the parser at the completion of the parsing of each node. The node and all of its descendants will exist and be complete. The parent node will also exist, although it may be incomplete, i.e. 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. The state of the rest of the document outside this node is not defined, and the affect of any attempt to navigate to, or to 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.
  If this new node is rejected, the parser might reuse the new node or any of its descendants.
  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:
    - `FILTER_ACCEPT` if this `Node` should be included in the DOM document being built.
    - `FILTER_REJECT` if the `Node` and all of its children should be rejected.
    - `FILTER_SKIP` if the `Node` should be skipped and the `Node` should be replaced by all the children of the `Node`.
    - `FILTER_INTERRUPT` if the filter wants to stop the processing of the document. Interrupting the processing of the document does no longer guarantee that the entire is XML well-formed .

### 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`.

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

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