Source for org.w3c.dom.traversal.NodeFilter

   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:      * <code>NodeIterator</code> or <code>TreeWalker</code> with an 
  72:      * attribute node as its <code>root</code>; in this case, it means that 
  73:      * the attribute node will appear in the first position of the iteration 
  74:      * or traversal. Since attributes are never children of other nodes, 
  75:      * they do not 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 <code>NodeIterator</code> or <code>TreeWalker</code> with an 
  93:      * <code>Entity</code> node as its <code>root</code>; in this case, it 
  94:      * means that the <code>Entity</code> node will appear in the first 
  95:      * position of the traversal. Since entities are not part of the 
  96:      * document tree, they do not appear when traversing over the document 
  97:      * tree.
  98:      */
  99:     public static final int SHOW_ENTITY               = 0x00000020;
 100:     /**
 101:      * Show <code>ProcessingInstruction</code> nodes.
 102:      */
 103:     public static final int SHOW_PROCESSING_INSTRUCTION = 0x00000040;
 104:     /**
 105:      * Show <code>Comment</code> nodes.
 106:      */
 107:     public static final int SHOW_COMMENT              = 0x00000080;
 108:     /**
 109:      * Show <code>Document</code> nodes.
 110:      */
 111:     public static final int SHOW_DOCUMENT             = 0x00000100;
 112:     /**
 113:      * Show <code>DocumentType</code> nodes.
 114:      */
 115:     public static final int SHOW_DOCUMENT_TYPE        = 0x00000200;
 116:     /**
 117:      * Show <code>DocumentFragment</code> nodes.
 118:      */
 119:     public static final int SHOW_DOCUMENT_FRAGMENT    = 0x00000400;
 120:     /**
 121:      * Show <code>Notation</code> nodes. This is meaningful only when creating 
 122:      * an <code>NodeIterator</code> or <code>TreeWalker</code> with a 
 123:      * <code>Notation</code> node as its <code>root</code>; in this case, it 
 124:      * means that the <code>Notation</code> node will appear in the first 
 125:      * position of the traversal. Since notations are not part of the 
 126:      * document tree, they do not appear when traversing over the document 
 127:      * tree.
 128:      */
 129:     public static final int SHOW_NOTATION             = 0x00000800;
 130: 
 131:     /**
 132:      * Test whether a specified node is visible in the logical view of a 
 133:      * <code>TreeWalker</code> or <code>NodeIterator</code>. This function 
 134:      * will be called by the implementation of <code>TreeWalker</code> and 
 135:      * <code>NodeIterator</code>; it is not normally called directly from 
 136:      * user code. (Though you could do so if you wanted to use the same 
 137:      * filter to guide your own application logic.)
 138:      * @param n The node to check to see if it passes the filter or not.
 139:      * @return A constant to determine whether the node is accepted, 
 140:      *   rejected, or skipped, as defined above.
 141:      */
 142:     public short acceptNode(Node n);
 143: 
 144: }