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