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: DTMIterator.java 468653 2006-10-28 07:07:05Z minchau $ 20 */ 21package org.apache.xml.dtm; 22 23/** 24 25 * <code>DTMIterators</code> are used to step through a (possibly 26 * filtered) set of nodes. Their API is modeled largely after the DOM 27 * NodeIterator. 28 * 29 * <p>A DTMIterator is a somewhat unusual type of iterator, in that it 30 * can serve both single node iteration and random access.</p> 31 * 32 * <p>The DTMIterator's traversal semantics, i.e. how it walks the tree, 33 * are specified when it is created, possibly and probably by an XPath 34 * <a href="http://www.w3.org/TR/xpath#NT-LocationPath>LocationPath</a> or 35 * a <a href="http://www.w3.org/TR/xpath#NT-UnionExpr">UnionExpr</a>.</p> 36 * 37 * <p>A DTMIterator is meant to be created once as a master static object, and 38 * then cloned many times for runtime use. Or the master object itself may 39 * be used for simpler use cases.</p> 40 * 41 * <p>At this time, we do not expect DTMIterator to emulate 42 * NodeIterator's "maintain relative position" semantics under 43 * document mutation. It's likely to respond more like the 44 * TreeWalker's "current node" semantics. However, since the base DTM 45 * is immutable, this issue currently makes no practical 46 * difference.</p> 47 * 48 * <p>State: In progress!!</p> */ 49public interface DTMIterator 50{ 51 52 // Constants returned by acceptNode, borrowed from the DOM Traversal chapter 53 // %REVIEW% Should we explicitly initialize them from, eg, 54 // org.w3c.dom.traversal.NodeFilter.FILTER_ACCEPT? 55 56 /** 57 * Accept the node. 58 */ 59 public static final short FILTER_ACCEPT = 1; 60 61 /** 62 * Reject the node. Same behavior as FILTER_SKIP. (In the DOM these 63 * differ when applied to a TreeWalker but have the same result when 64 * applied to a NodeIterator). 65 */ 66 public static final short FILTER_REJECT = 2; 67 68 /** 69 * Skip this single node. 70 */ 71 public static final short FILTER_SKIP = 3; 72 73 /** 74 * Get an instance of a DTM that "owns" a node handle. Since a node 75 * iterator may be passed without a DTMManager, this allows the 76 * caller to easily get the DTM using just the iterator. 77 * 78 * @param nodeHandle the nodeHandle. 79 * 80 * @return a non-null DTM reference. 81 */ 82 public DTM getDTM(int nodeHandle); 83 84 /** 85 * Get an instance of the DTMManager. Since a node 86 * iterator may be passed without a DTMManager, this allows the 87 * caller to easily get the DTMManager using just the iterator. 88 * 89 * @return a non-null DTMManager reference. 90 */ 91 public DTMManager getDTMManager(); 92 93 /** 94 * The root node of the <code>DTMIterator</code>, as specified when it 95 * was created. Note the root node is not the root node of the 96 * document tree, but the context node from where the iteration 97 * begins and ends. 98 * 99 * @return nodeHandle int Handle of the context node. 100 */ 101 public int getRoot(); 102 103 /** 104 * Reset the root node of the <code>DTMIterator</code>, overriding 105 * the value specified when it was created. Note the root node is 106 * not the root node of the document tree, but the context node from 107 * where the iteration begins. 108 * 109 * @param nodeHandle int Handle of the context node. 110 * @param environment The environment object. 111 * The environment in which this iterator operates, which should provide: 112 * <ul> 113 * <li>a node (the context node... same value as "root" defined below) </li> 114 * <li>a pair of non-zero positive integers (the context position and the context size) </li> 115 * <li>a set of variable bindings </li> 116 * <li>a function library </li> 117 * <li>the set of namespace declarations in scope for the expression.</li> 118 * <ul> 119 * 120 * <p>At this time the exact implementation of this environment is application 121 * dependent. Probably a proper interface will be created fairly soon.</p> 122 * 123 */ 124 public void setRoot(int nodeHandle, Object environment); 125 126 /** 127 * Reset the iterator to the start. After resetting, the next node returned 128 * will be the root node -- or, if that's filtered out, the first node 129 * within the root's subtree which is _not_ skipped by the filters. 130 */ 131 public void reset(); 132 133 /** 134 * This attribute determines which node types are presented via the 135 * iterator. The available set of constants is defined above. 136 * Nodes not accepted by 137 * <code>whatToShow</code> will be skipped, but their children may still 138 * be considered. 139 * 140 * @return one of the SHOW_XXX constants, or several ORed together. 141 */ 142 public int getWhatToShow(); 143 144 /** 145 * <p>The value of this flag determines whether the children of entity 146 * reference nodes are visible to the iterator. If false, they and 147 * their descendants will be rejected. Note that this rejection takes 148 * precedence over <code>whatToShow</code> and the filter. </p> 149 * 150 * <p> To produce a view of the document that has entity references 151 * expanded and does not expose the entity reference node itself, use 152 * the <code>whatToShow</code> flags to hide the entity reference node 153 * and set <code>expandEntityReferences</code> to true when creating the 154 * iterator. To produce a view of the document that has entity reference 155 * nodes but no entity expansion, use the <code>whatToShow</code> flags 156 * to show the entity reference node and set 157 * <code>expandEntityReferences</code> to false.</p> 158 * 159 * <p>NOTE: In Xalan's use of DTM we will generally have fully expanded 160 * entity references when the document tree was built, and thus this 161 * flag will have no effect.</p> 162 * 163 * @return true if entity references will be expanded. */ 164 public boolean getExpandEntityReferences(); 165 166 /** 167 * Returns the next node in the set and advances the position of the 168 * iterator in the set. After a <code>DTMIterator</code> has setRoot called, 169 * the first call to <code>nextNode()</code> returns that root or (if it 170 * is rejected by the filters) the first node within its subtree which is 171 * not filtered out. 172 * @return The next node handle in the set being iterated over, or 173 * <code>DTM.NULL</code> if there are no more members in that set. 174 */ 175 public int nextNode(); 176 177 /** 178 * Returns the previous node in the set and moves the position of the 179 * <code>DTMIterator</code> backwards in the set. 180 * @return The previous node handle in the set being iterated over, 181 * or <code>DTM.NULL</code> if there are no more members in that set. 182 */ 183 public int previousNode(); 184 185 /** 186 * Detaches the <code>DTMIterator</code> from the set which it iterated 187 * over, releasing any computational resources and placing the iterator 188 * in the INVALID state. After <code>detach</code> has been invoked, 189 * calls to <code>nextNode</code> or <code>previousNode</code> will 190 * raise a runtime exception. 191 */ 192 public void detach(); 193 194 /** 195 * Specify if it's OK for detach to release the iterator for reuse. 196 * 197 * @param allowRelease true if it is OK for detach to release this iterator 198 * for pooling. 199 */ 200 public void allowDetachToRelease(boolean allowRelease); 201 202 /** 203 * Get the current node in the iterator. Note that this differs from 204 * the DOM's NodeIterator, where the current position lies between two 205 * nodes (as part of the maintain-relative-position semantic). 206 * 207 * @return The current node handle, or -1. 208 */ 209 public int getCurrentNode(); 210 211 /** 212 * Tells if this NodeSetDTM is "fresh", in other words, if 213 * the first nextNode() that is called will return the 214 * first node in the set. 215 * 216 * @return true if the iteration of this list has not yet begun. 217 */ 218 public boolean isFresh(); 219 220 //========= Random Access ========== 221 222 /** 223 * If setShouldCacheNodes(true) is called, then nodes will 224 * be cached, enabling random access, and giving the ability to do 225 * sorts and the like. They are not cached by default. 226 * 227 * %REVIEW% Shouldn't the other random-access methods throw an exception 228 * if they're called on a DTMIterator with this flag set false? 229 * 230 * @param b true if the nodes should be cached. 231 */ 232 public void setShouldCacheNodes(boolean b); 233 234 /** 235 * Tells if this iterator can have nodes added to it or set via 236 * the <code>setItem(int node, int index)</code> method. 237 * 238 * @return True if the nodelist can be mutated. 239 */ 240 public boolean isMutable(); 241 242 /** Get the current position within the cached list, which is one 243 * less than the next nextNode() call will retrieve. i.e. if you 244 * call getCurrentPos() and the return is 0, the next fetch will 245 * take place at index 1. 246 * 247 * @return The position of the iteration. 248 */ 249 public int getCurrentPos(); 250 251 /** 252 * If an index is requested, NodeSetDTM will call this method 253 * to run the iterator to the index. By default this sets 254 * m_next to the index. If the index argument is -1, this 255 * signals that the iterator should be run to the end and 256 * completely fill the cache. 257 * 258 * @param index The index to run to, or -1 if the iterator should be run 259 * to the end. 260 */ 261 public void runTo(int index); 262 263 /** 264 * Set the current position in the node set. 265 * 266 * @param i Must be a valid index. 267 */ 268 public void setCurrentPos(int i); 269 270 /** 271 * Returns the <code>node handle</code> of an item in the collection. If 272 * <code>index</code> is greater than or equal to the number of nodes in 273 * the list, this returns <code>null</code>. 274 * 275 * @param index of the item. 276 * @return The node handle at the <code>index</code>th position in the 277 * <code>DTMIterator</code>, or <code>-1</code> if that is not a valid 278 * index. 279 */ 280 public int item(int index); 281 282 /** 283 * Sets the node at the specified index of this vector to be the 284 * specified node. The previous component at that position is discarded. 285 * 286 * <p>The index must be a value greater than or equal to 0 and less 287 * than the current size of the vector. 288 * The iterator must be in cached mode.</p> 289 * 290 * <p>Meant to be used for sorted iterators.</p> 291 * 292 * @param node Node to set 293 * @param index Index of where to set the node 294 */ 295 public void setItem(int node, int index); 296 297 /** 298 * The number of nodes in the list. The range of valid child node indices 299 * is 0 to <code>length-1</code> inclusive. Note that this requires running 300 * the iterator to completion, and presumably filling the cache. 301 * 302 * @return The number of nodes in the list. 303 */ 304 public int getLength(); 305 306 //=========== Cloning operations. ============ 307 308 /** 309 * Get a cloned Iterator that is reset to the start of the iteration. 310 * 311 * @return A clone of this iteration that has been reset. 312 * 313 * @throws CloneNotSupportedException 314 */ 315 public DTMIterator cloneWithReset() throws CloneNotSupportedException; 316 317 /** 318 * Get a clone of this iterator, but don't reset the iteration in the 319 * process, so that it may be used from the current position. 320 * 321 * @return A clone of this object. 322 * 323 * @throws CloneNotSupportedException 324 */ 325 public Object clone() throws CloneNotSupportedException; 326 327 /** 328 * Returns true if all the nodes in the iteration well be returned in document 329 * order. 330 * 331 * @return true if all the nodes in the iteration well be returned in document 332 * order. 333 */ 334 public boolean isDocOrdered(); 335 336 /** 337 * Returns the axis being iterated, if it is known. 338 * 339 * @return Axis.CHILD, etc., or -1 if the axis is not known or is of multiple 340 * types. 341 */ 342 public int getAxis(); 343 344} 345