Home | History | Annotate | Download | only in traversal 
      1 /*
      2  * Copyright (c) 2000 World Wide Web Consortium,
      3  * (Massachusetts Institute of Technology, Institut National de
      4  * Recherche en Informatique et en Automatique, Keio University). All
      5  * Rights Reserved. This program is distributed under the W3C's Software
      6  * Intellectual Property License. This program is distributed in the
      7  * hope that it will be useful, but WITHOUT ANY WARRANTY; without even
      8  * the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
      9  * PURPOSE.
     10  * See W3C License http://www.w3.org/Consortium/Legal/ for more details.
     11  */
     12 
     13 package org.w3c.dom.traversal;
     14 
     15 import org.w3c.dom.Node;
     16 
     17 /**
     18  * Filters are objects that know how to "filter out" nodes. If a
     19  * <code>NodeIterator</code> or <code>TreeWalker</code> is given a
     20  * <code>NodeFilter</code>, it applies the filter before it returns the next
     21  * node. If the filter says to accept the node, the traversal logic returns
     22  * it; otherwise, traversal looks for the next node and pretends that the
     23  * node that was rejected was not there.
     24  * <p>The DOM does not provide any filters. <code>NodeFilter</code> is just an
     25  * interface that users can implement to provide their own filters.
     26  * <p><code>NodeFilters</code> do not need to know how to traverse from node
     27  * to node, nor do they need to know anything about the data structure that
     28  * is being traversed. This makes it very easy to write filters, since the
     29  * only thing they have to know how to do is evaluate a single node. One
     30  * filter may be used with a number of different kinds of traversals,
     31  * encouraging code reuse.
     32  * <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>.
     33  * @since DOM Level 2
     34  *
     35  * @hide
     36  */
     37 public interface NodeFilter {
     38     // Constants returned by acceptNode
     39     /**
     40      * Accept the node. Navigation methods defined for
     41      * <code>NodeIterator</code> or <code>TreeWalker</code> will return this
     42      * node.
     43      */
     44     public static final short FILTER_ACCEPT             = 1;
     45     /**
     46      * Reject the node. Navigation methods defined for
     47      * <code>NodeIterator</code> or <code>TreeWalker</code> will not return
     48      * this node. For <code>TreeWalker</code>, the children of this node
     49      * will also be rejected. <code>NodeIterators</code> treat this as a
     50      * synonym for <code>FILTER_SKIP</code>.
     51      */
     52     public static final short FILTER_REJECT             = 2;
     53     /**
     54      * Skip this single node. Navigation methods defined for
     55      * <code>NodeIterator</code> or <code>TreeWalker</code> will not return
     56      * this node. For both <code>NodeIterator</code> and
     57      * <code>TreeWalker</code>, the children of this node will still be
     58      * considered.
     59      */
     60     public static final short FILTER_SKIP               = 3;
     61 
     62     // Constants for whatToShow
     63     /**
     64      * Show all <code>Nodes</code>.
     65      */
     66     public static final int SHOW_ALL                  = 0xFFFFFFFF;
     67     /**
     68      * Show <code>Element</code> nodes.
     69      */
     70     public static final int SHOW_ELEMENT              = 0x00000001;
     71     /**
     72      * Show <code>Attr</code> nodes. This is meaningful only when creating an
     73      * <code>NodeIterator</code> or <code>TreeWalker</code> with an
     74      * attribute node as its <code>root</code>; in this case, it means that
     75      * the attribute node will appear in the first position of the iteration
     76      * or traversal. Since attributes are never children of other nodes,
     77      * they do not appear when traversing over the document tree.
     78      */
     79     public static final int SHOW_ATTRIBUTE            = 0x00000002;
     80     /**
     81      * Show <code>Text</code> nodes.
     82      */
     83     public static final int SHOW_TEXT                 = 0x00000004;
     84     /**
     85      * Show <code>CDATASection</code> nodes.
     86      */
     87     public static final int SHOW_CDATA_SECTION        = 0x00000008;
     88     /**
     89      * Show <code>EntityReference</code> nodes.
     90      */
     91     public static final int SHOW_ENTITY_REFERENCE     = 0x00000010;
     92     /**
     93      * Show <code>Entity</code> nodes. This is meaningful only when creating
     94      * an <code>NodeIterator</code> or <code>TreeWalker</code> with an
     95      * <code>Entity</code> node as its <code>root</code>; in this case, it
     96      * means that the <code>Entity</code> node will appear in the first
     97      * position of the traversal. Since entities are not part of the
     98      * document tree, they do not appear when traversing over the document
     99      * tree.
    100      */
    101     public static final int SHOW_ENTITY               = 0x00000020;
    102     /**
    103      * Show <code>ProcessingInstruction</code> nodes.
    104      */
    105     public static final int SHOW_PROCESSING_INSTRUCTION = 0x00000040;
    106     /**
    107      * Show <code>Comment</code> nodes.
    108      */
    109     public static final int SHOW_COMMENT              = 0x00000080;
    110     /**
    111      * Show <code>Document</code> nodes.
    112      */
    113     public static final int SHOW_DOCUMENT             = 0x00000100;
    114     /**
    115      * Show <code>DocumentType</code> nodes.
    116      */
    117     public static final int SHOW_DOCUMENT_TYPE        = 0x00000200;
    118     /**
    119      * Show <code>DocumentFragment</code> nodes.
    120      */
    121     public static final int SHOW_DOCUMENT_FRAGMENT    = 0x00000400;
    122     /**
    123      * Show <code>Notation</code> nodes. This is meaningful only when creating
    124      * an <code>NodeIterator</code> or <code>TreeWalker</code> with a
    125      * <code>Notation</code> node as its <code>root</code>; in this case, it
    126      * means that the <code>Notation</code> node will appear in the first
    127      * position of the traversal. Since notations are not part of the
    128      * document tree, they do not appear when traversing over the document
    129      * tree.
    130      */
    131     public static final int SHOW_NOTATION             = 0x00000800;
    132 
    133     /**
    134      * Test whether a specified node is visible in the logical view of a
    135      * <code>TreeWalker</code> or <code>NodeIterator</code>. This function
    136      * will be called by the implementation of <code>TreeWalker</code> and
    137      * <code>NodeIterator</code>; it is not normally called directly from
    138      * user code. (Though you could do so if you wanted to use the same
    139      * filter to guide your own application logic.)
    140      * @param n The node to check to see if it passes the filter or not.
    141      * @return A constant to determine whether the node is accepted,
    142      *   rejected, or skipped, as defined above.
    143      */
    144     public short acceptNode(Node n);
    145 
    146 }
    147