1 /* 2 * Licensed to the Apache Software Foundation (ASF) under one 3 * or more contributor license agreements. See the NOTICE file 4 * distributed with this work for additional information 5 * regarding copyright ownership. The ASF licenses this file 6 * to you under the Apache License, Version 2.0 (the "License"); 7 * you may not use this file except in compliance with the License. 8 * You may obtain a copy of the License at 9 * 10 * http://www.apache.org/licenses/LICENSE-2.0 11 * 12 * Unless required by applicable law or agreed to in writing, software 13 * distributed under the License is distributed on an "AS IS" BASIS, 14 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 15 * See the License for the specific language governing permissions and 16 * limitations under the License. 17 */ 18 /* 19 * $Id: DTMFilter.java 468653 2006-10-28 07:07:05Z minchau $ 20 */ 21 package org.apache.xml.dtm; 22 23 /** 24 * Simple filter for doing node tests. Note the semantics of this are 25 * somewhat different that the DOM's NodeFilter. 26 */ 27 public interface DTMFilter 28 { 29 30 // Constants for whatToShow. These are used to set the node type that will 31 // be traversed. These values may be ORed together before being passed to 32 // the DTMIterator. 33 34 /** 35 * Show all <code>Nodes</code>. 36 */ 37 public static final int SHOW_ALL = 0xFFFFFFFF; 38 39 /** 40 * Show <code>Element</code> nodes. 41 */ 42 public static final int SHOW_ELEMENT = 0x00000001; 43 44 /** 45 * Show <code>Attr</code> nodes. This is meaningful only when creating an 46 * iterator or tree-walker with an attribute node as its 47 * <code>root</code>; in this case, it means that the attribute node 48 * will appear in the first position of the iteration or traversal. 49 * Since attributes are never children of other nodes, they do not 50 * appear when traversing over the main document tree. 51 */ 52 public static final int SHOW_ATTRIBUTE = 0x00000002; 53 54 /** 55 * Show <code>Text</code> nodes. 56 */ 57 public static final int SHOW_TEXT = 0x00000004; 58 59 /** 60 * Show <code>CDATASection</code> nodes. 61 */ 62 public static final int SHOW_CDATA_SECTION = 0x00000008; 63 64 /** 65 * Show <code>EntityReference</code> nodes. Note that if Entity References 66 * have been fully expanded while the tree was being constructed, these 67 * nodes will not appear and this mask has no effect. 68 */ 69 public static final int SHOW_ENTITY_REFERENCE = 0x00000010; 70 71 /** 72 * Show <code>Entity</code> nodes. This is meaningful only when creating 73 * an iterator or tree-walker with an<code> Entity</code> node as its 74 * <code>root</code>; in this case, it means that the <code>Entity</code> 75 * node will appear in the first position of the traversal. Since 76 * entities are not part of the document tree, they do not appear when 77 * traversing over the main document tree. 78 */ 79 public static final int SHOW_ENTITY = 0x00000020; 80 81 /** 82 * Show <code>ProcessingInstruction</code> nodes. 83 */ 84 public static final int SHOW_PROCESSING_INSTRUCTION = 0x00000040; 85 86 /** 87 * Show <code>Comment</code> nodes. 88 */ 89 public static final int SHOW_COMMENT = 0x00000080; 90 91 /** 92 * Show <code>Document</code> nodes. (Of course, as with Attributes 93 * and such, this is meaningful only when the iteration root is the 94 * Document itself, since Document has no parent.) 95 */ 96 public static final int SHOW_DOCUMENT = 0x00000100; 97 98 /** 99 * Show <code>DocumentType</code> nodes. 100 */ 101 public static final int SHOW_DOCUMENT_TYPE = 0x00000200; 102 103 /** 104 * Show <code>DocumentFragment</code> nodes. (Of course, as with 105 * Attributes and such, this is meaningful only when the iteration 106 * root is the Document itself, since DocumentFragment has no parent.) 107 */ 108 public static final int SHOW_DOCUMENT_FRAGMENT = 0x00000400; 109 110 /** 111 * Show <code>Notation</code> nodes. This is meaningful only when creating 112 * an iterator or tree-walker with a <code>Notation</code> node as its 113 * <code>root</code>; in this case, it means that the 114 * <code>Notation</code> node will appear in the first position of the 115 * traversal. Since notations are not part of the document tree, they do 116 * not appear when traversing over the main document tree. 117 */ 118 public static final int SHOW_NOTATION = 0x00000800; 119 120 /** 121 122 * This bit instructs the iterator to show namespace nodes, which 123 * are modeled by DTM but not by the DOM. Make sure this does not 124 * conflict with {@link org.w3c.dom.traversal.NodeFilter}. 125 * <p> 126 * %REVIEW% Might be safer to start from higher bits and work down, 127 * to leave room for the DOM to expand its set of constants... Or, 128 * possibly, to create a DTM-specific field for these additional bits. 129 */ 130 public static final int SHOW_NAMESPACE = 0x00001000; 131 132 /** 133 * Special bit for filters implementing match patterns starting with 134 * a function. Make sure this does not conflict with 135 * {@link org.w3c.dom.traversal.NodeFilter}. 136 * <p> 137 * %REVIEW% Might be safer to start from higher bits and work down, 138 * to leave room for the DOM to expand its set of constants... Or, 139 * possibly, to create a DTM-specific field for these additional bits. 140 */ 141 public static final int SHOW_BYFUNCTION = 0x00010000; 142 143 /** 144 * Test whether a specified node is visible in the logical view of a 145 * <code>DTMIterator</code>. Normally, this function 146 * will be called by the implementation of <code>DTMIterator</code>; 147 * it is not normally called directly from 148 * user code. 149 * 150 * @param nodeHandle int Handle of the node. 151 * @param whatToShow one of SHOW_XXX values. 152 * @return one of FILTER_ACCEPT, FILTER_REJECT, or FILTER_SKIP. 153 */ 154 public short acceptNode(int nodeHandle, int whatToShow); 155 156 /** 157 * Test whether a specified node is visible in the logical view of a 158 * <code>DTMIterator</code>. Normally, this function 159 * will be called by the implementation of <code>DTMIterator</code>; 160 * it is not normally called directly from 161 * user code. 162 * <p> 163 * TODO: Should this be setNameMatch(expandedName) followed by accept()? 164 * Or will we really be testing a different name at every invocation? 165 * 166 * <p>%REVIEW% Under what circumstances will this be used? The cases 167 * I've considered are just as easy and just about as efficient if 168 * the name test is performed in the DTMIterator... -- Joe</p> 169 * 170 * <p>%REVIEW% Should that 0xFFFF have a mnemonic assigned to it? 171 * Also: This representation is assuming the expanded name is indeed 172 * split into high/low 16-bit halfwords. If we ever change the 173 * balance between namespace and localname bits (eg because we 174 * decide there are many more localnames than namespaces, which is 175 * fairly likely), this is going to break. It might be safer to 176 * encapsulate the details with a makeExpandedName method and make 177 * that responsible for setting up the wildcard version as well.</p> 178 * 179 * @param nodeHandle int Handle of the node. 180 * @param whatToShow one of SHOW_XXX values. 181 * @param expandedName a value defining the exanded name as defined in 182 * the DTM interface. Wild cards will be defined 183 * by 0xFFFF in the namespace and/or localname 184 * portion of the expandedName. 185 * @return one of FILTER_ACCEPT, FILTER_REJECT, or FILTER_SKIP. */ 186 public short acceptNode(int nodeHandle, int whatToShow, int expandedName); 187 188 } 189
