001/*
002 * Copyright (c) 2000 World Wide Web Consortium,
003 * (Massachusetts Institute of Technology, Institut National de
004 * Recherche en Informatique et en Automatique, Keio University). All
005 * Rights Reserved. This program is distributed under the W3C's Software
006 * Intellectual Property License. This program is distributed in the
007 * hope that it will be useful, but WITHOUT ANY WARRANTY; without even
008 * the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
009 * PURPOSE.
010 * See W3C License http://www.w3.org/Consortium/Legal/ for more details.
011 */
012
013package org.w3c.dom.traversal;
014
015import org.w3c.dom.Node;
016
017/**
018 * Filters are objects that know how to "filter out" nodes. If a 
019 * <code>NodeIterator</code> or <code>TreeWalker</code> is given a 
020 * <code>NodeFilter</code>, it applies the filter before it returns the next 
021 * node. If the filter says to accept the node, the traversal logic returns 
022 * it; otherwise, traversal looks for the next node and pretends that the 
023 * node that was rejected was not there.
024 * <p>The DOM does not provide any filters. <code>NodeFilter</code> is just an 
025 * interface that users can implement to provide their own filters. 
026 * <p><code>NodeFilters</code> do not need to know how to traverse from node 
027 * to node, nor do they need to know anything about the data structure that 
028 * is being traversed. This makes it very easy to write filters, since the 
029 * only thing they have to know how to do is evaluate a single node. One 
030 * filter may be used with a number of different kinds of traversals, 
031 * encouraging code reuse.
032 * <p>See also the <a href='http://www.w3.org/TR/2000/REC-DOM-Level-2-Traversal-Range-20001113'>Document Object Model (DOM) Level 2 Traversal and Range Specification</a>.
033 * @since DOM Level 2
034 */
035public interface NodeFilter {
036    // Constants returned by acceptNode
037    /**
038     * Accept the node. Navigation methods defined for 
039     * <code>NodeIterator</code> or <code>TreeWalker</code> will return this 
040     * node.
041     */
042    public static final short FILTER_ACCEPT             = 1;
043    /**
044     * Reject the node. Navigation methods defined for 
045     * <code>NodeIterator</code> or <code>TreeWalker</code> will not return 
046     * this node. For <code>TreeWalker</code>, the children of this node 
047     * will also be rejected. <code>NodeIterators</code> treat this as a 
048     * synonym for <code>FILTER_SKIP</code>.
049     */
050    public static final short FILTER_REJECT             = 2;
051    /**
052     * Skip this single node. Navigation methods defined for 
053     * <code>NodeIterator</code> or <code>TreeWalker</code> will not return 
054     * this node. For both <code>NodeIterator</code> and 
055     * <code>TreeWalker</code>, the children of this node will still be 
056     * considered. 
057     */
058    public static final short FILTER_SKIP               = 3;
059
060    // Constants for whatToShow
061    /**
062     * Show all <code>Nodes</code>.
063     */
064    public static final int SHOW_ALL                  = 0xFFFFFFFF;
065    /**
066     * Show <code>Element</code> nodes.
067     */
068    public static final int SHOW_ELEMENT              = 0x00000001;
069    /**
070     * Show <code>Attr</code> nodes. This is meaningful only when creating an 
071     * iterator or tree-walker with an attribute node as its 
072     * <code>root</code>; in this case, it means that the attribute node 
073     * will appear in the first position of the iteration or traversal. 
074     * Since attributes are never children of other nodes, they do not 
075     * appear when traversing over the document tree.
076     */
077    public static final int SHOW_ATTRIBUTE            = 0x00000002;
078    /**
079     * Show <code>Text</code> nodes.
080     */
081    public static final int SHOW_TEXT                 = 0x00000004;
082    /**
083     * Show <code>CDATASection</code> nodes.
084     */
085    public static final int SHOW_CDATA_SECTION        = 0x00000008;
086    /**
087     * Show <code>EntityReference</code> nodes.
088     */
089    public static final int SHOW_ENTITY_REFERENCE     = 0x00000010;
090    /**
091     * Show <code>Entity</code> nodes. This is meaningful only when creating 
092     * an iterator or tree-walker with an<code> Entity</code> node as its 
093     * <code>root</code>; in this case, it means that the <code>Entity</code>
094     *  node will appear in the first position of the traversal. Since 
095     * entities are not part of the document tree, they do not appear when 
096     * traversing over the document tree.
097     */
098    public static final int SHOW_ENTITY               = 0x00000020;
099    /**
100     * Show <code>ProcessingInstruction</code> nodes.
101     */
102    public static final int SHOW_PROCESSING_INSTRUCTION = 0x00000040;
103    /**
104     * Show <code>Comment</code> nodes.
105     */
106    public static final int SHOW_COMMENT              = 0x00000080;
107    /**
108     * Show <code>Document</code> nodes.
109     */
110    public static final int SHOW_DOCUMENT             = 0x00000100;
111    /**
112     * Show <code>DocumentType</code> nodes.
113     */
114    public static final int SHOW_DOCUMENT_TYPE        = 0x00000200;
115    /**
116     * Show <code>DocumentFragment</code> nodes.
117     */
118    public static final int SHOW_DOCUMENT_FRAGMENT    = 0x00000400;
119    /**
120     * Show <code>Notation</code> nodes. This is meaningful only when creating 
121     * an iterator or tree-walker with a <code>Notation</code> node as its 
122     * <code>root</code>; in this case, it means that the 
123     * <code>Notation</code> node will appear in the first position of the 
124     * traversal. Since notations are not part of the document tree, they do 
125     * not appear when traversing over the document tree.
126     */
127    public static final int SHOW_NOTATION             = 0x00000800;
128
129    /**
130     * Test whether a specified node is visible in the logical view of a 
131     * <code>TreeWalker</code> or <code>NodeIterator</code>. This function 
132     * will be called by the implementation of <code>TreeWalker</code> and 
133     * <code>NodeIterator</code>; it is not normally called directly from 
134     * user code. (Though you could do so if you wanted to use the same 
135     * filter to guide your own application logic.)
136     * @param nThe node to check to see if it passes the filter or not.
137     * @return a constant to determine whether the node is accepted, 
138     *   rejected, or skipped, as defined above.
139     */
140    public short acceptNode(Node n);
141
142}