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 013 package org.w3c.dom.traversal; 014 015 import 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 */ 035 public 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 * <code>NodeIterator</code> or <code>TreeWalker</code> with an 072 * attribute node as its <code>root</code>; in this case, it means that 073 * the attribute node will appear in the first position of the iteration 074 * or traversal. Since attributes are never children of other nodes, 075 * they do not 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 <code>NodeIterator</code> or <code>TreeWalker</code> with an 093 * <code>Entity</code> node as its <code>root</code>; in this case, it 094 * means that the <code>Entity</code> node will appear in the first 095 * position of the traversal. Since entities are not part of the 096 * document tree, they do not appear when traversing over the document 097 * tree. 098 */ 099 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 }