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

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