libjava/org/w3c/dom/traversal/NodeFilter.java

   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 public interface NodeFilter {
  36     // Constants returned by acceptNode
  37     /**
  38      * Accept the node. Navigation methods defined for
  39      * <code>NodeIterator</code> or <code>TreeWalker</code> will return this
  40      * node.
  41      */
  42     public static final short FILTER_ACCEPT             = 1;
  43     /**
  44      * Reject the node. Navigation methods defined for
  45      * <code>NodeIterator</code> or <code>TreeWalker</code> will not return
  46      * this node. For <code>TreeWalker</code>, the children of this node
  47      * will also be rejected. <code>NodeIterators</code> treat this as a
  48      * synonym for <code>FILTER_SKIP</code>.
  49      */
  50     public static final short FILTER_REJECT             = 2;
  51     /**
  52      * Skip this single node. Navigation methods defined for
  53      * <code>NodeIterator</code> or <code>TreeWalker</code> will not return
  54      * this node. For both <code>NodeIterator</code> and
  55      * <code>TreeWalker</code>, the children of this node will still be
  56      * considered.
  57      */
  58     public static final short FILTER_SKIP               = 3;
  59
  60     // Constants for whatToShow
  61     /**
  62      * Show all <code>Nodes</code>.
  63      */
  64     public static final int SHOW_ALL                  = 0xFFFFFFFF;
  65     /**
  66      * Show <code>Element</code> nodes.
  67      */
  68     public static final int SHOW_ELEMENT              = 0x00000001;
  69     /**
  70      * Show <code>Attr</code> nodes. This is meaningful only when creating an
  71      * iterator or tree-walker with an attribute node as its
  72      * <code>root</code>; in this case, it means that the attribute node
  73      * will appear in the first position of the iteration or traversal.
  74      * Since attributes are never children of other nodes, they do not
  75      * appear when traversing over the document tree.
  76      */
  77     public static final int SHOW_ATTRIBUTE            = 0x00000002;
  78     /**
  79      * Show <code>Text</code> nodes.
  80      */
  81     public static final int SHOW_TEXT                 = 0x00000004;
  82     /**
  83      * Show <code>CDATASection</code> nodes.
  84      */
  85     public static final int SHOW_CDATA_SECTION        = 0x00000008;
  86     /**
  87      * Show <code>EntityReference</code> nodes.
  88      */
  89     public static final int SHOW_ENTITY_REFERENCE     = 0x00000010;
  90     /**
  91      * Show <code>Entity</code> nodes. This is meaningful only when creating
  92      * an iterator or tree-walker with an<code> Entity</code> node as its
  93      * <code>root</code>; in this case, it means that the <code>Entity</code>
  94      *  node will appear in the first position of the traversal. Since
  95      * entities are not part of the document tree, they do not appear when
  96      * traversing over the document tree.
  97      */
  98     public static final int SHOW_ENTITY               = 0x00000020;
  99     /**
 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 }