14c7a0d97cf2b27790e6236965a1d798d710d7ec7Jesse Wilson/* 24c7a0d97cf2b27790e6236965a1d798d710d7ec7Jesse Wilson * Licensed to the Apache Software Foundation (ASF) under one 34c7a0d97cf2b27790e6236965a1d798d710d7ec7Jesse Wilson * or more contributor license agreements. See the NOTICE file 44c7a0d97cf2b27790e6236965a1d798d710d7ec7Jesse Wilson * distributed with this work for additional information 54c7a0d97cf2b27790e6236965a1d798d710d7ec7Jesse Wilson * regarding copyright ownership. The ASF licenses this file 64c7a0d97cf2b27790e6236965a1d798d710d7ec7Jesse Wilson * to you under the Apache License, Version 2.0 (the "License"); 74c7a0d97cf2b27790e6236965a1d798d710d7ec7Jesse Wilson * you may not use this file except in compliance with the License. 84c7a0d97cf2b27790e6236965a1d798d710d7ec7Jesse Wilson * You may obtain a copy of the License at 94c7a0d97cf2b27790e6236965a1d798d710d7ec7Jesse Wilson * 104c7a0d97cf2b27790e6236965a1d798d710d7ec7Jesse Wilson * http://www.apache.org/licenses/LICENSE-2.0 114c7a0d97cf2b27790e6236965a1d798d710d7ec7Jesse Wilson * 124c7a0d97cf2b27790e6236965a1d798d710d7ec7Jesse Wilson * Unless required by applicable law or agreed to in writing, software 134c7a0d97cf2b27790e6236965a1d798d710d7ec7Jesse Wilson * distributed under the License is distributed on an "AS IS" BASIS, 144c7a0d97cf2b27790e6236965a1d798d710d7ec7Jesse Wilson * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 154c7a0d97cf2b27790e6236965a1d798d710d7ec7Jesse Wilson * See the License for the specific language governing permissions and 164c7a0d97cf2b27790e6236965a1d798d710d7ec7Jesse Wilson * limitations under the License. 174c7a0d97cf2b27790e6236965a1d798d710d7ec7Jesse Wilson */ 184c7a0d97cf2b27790e6236965a1d798d710d7ec7Jesse Wilson/* 194c7a0d97cf2b27790e6236965a1d798d710d7ec7Jesse Wilson * $Id: DTMAxisTraverser.java 468653 2006-10-28 07:07:05Z minchau $ 204c7a0d97cf2b27790e6236965a1d798d710d7ec7Jesse Wilson */ 214c7a0d97cf2b27790e6236965a1d798d710d7ec7Jesse Wilsonpackage org.apache.xml.dtm; 224c7a0d97cf2b27790e6236965a1d798d710d7ec7Jesse Wilson 234c7a0d97cf2b27790e6236965a1d798d710d7ec7Jesse Wilson/** 244c7a0d97cf2b27790e6236965a1d798d710d7ec7Jesse Wilson * A class that implements traverses DTMAxisTraverser interface can traverse 254c7a0d97cf2b27790e6236965a1d798d710d7ec7Jesse Wilson * a set of nodes, usually as defined by an XPath axis. It is different from 264c7a0d97cf2b27790e6236965a1d798d710d7ec7Jesse Wilson * an iterator, because it does not need to hold state, and, in fact, must not 274c7a0d97cf2b27790e6236965a1d798d710d7ec7Jesse Wilson * hold any iteration-based state. It is meant to be implemented as an inner 284c7a0d97cf2b27790e6236965a1d798d710d7ec7Jesse Wilson * class of a DTM, and returned by the getAxisTraverser(final int axis) 294c7a0d97cf2b27790e6236965a1d798d710d7ec7Jesse Wilson * function. 304c7a0d97cf2b27790e6236965a1d798d710d7ec7Jesse Wilson * 314c7a0d97cf2b27790e6236965a1d798d710d7ec7Jesse Wilson * <p>A DTMAxisTraverser can probably not traverse a reverse axis in 324c7a0d97cf2b27790e6236965a1d798d710d7ec7Jesse Wilson * document order.</p> 334c7a0d97cf2b27790e6236965a1d798d710d7ec7Jesse Wilson * 344c7a0d97cf2b27790e6236965a1d798d710d7ec7Jesse Wilson * <p>Typical usage:</p> 354c7a0d97cf2b27790e6236965a1d798d710d7ec7Jesse Wilson * <pre><code> 364c7a0d97cf2b27790e6236965a1d798d710d7ec7Jesse Wilson * for(int nodeHandle=myTraverser.first(myContext); 374c7a0d97cf2b27790e6236965a1d798d710d7ec7Jesse Wilson * nodeHandle!=DTM.NULL; 384c7a0d97cf2b27790e6236965a1d798d710d7ec7Jesse Wilson * nodeHandle=myTraverser.next(myContext,nodeHandle)) 394c7a0d97cf2b27790e6236965a1d798d710d7ec7Jesse Wilson * { ... processing for node indicated by nodeHandle goes here ... } 404c7a0d97cf2b27790e6236965a1d798d710d7ec7Jesse Wilson * </code></pre> 414c7a0d97cf2b27790e6236965a1d798d710d7ec7Jesse Wilson * 424c7a0d97cf2b27790e6236965a1d798d710d7ec7Jesse Wilson * @author Scott Boag 434c7a0d97cf2b27790e6236965a1d798d710d7ec7Jesse Wilson */ 444c7a0d97cf2b27790e6236965a1d798d710d7ec7Jesse Wilsonpublic abstract class DTMAxisTraverser 454c7a0d97cf2b27790e6236965a1d798d710d7ec7Jesse Wilson{ 464c7a0d97cf2b27790e6236965a1d798d710d7ec7Jesse Wilson 474c7a0d97cf2b27790e6236965a1d798d710d7ec7Jesse Wilson /** 484c7a0d97cf2b27790e6236965a1d798d710d7ec7Jesse Wilson * By the nature of the stateless traversal, the context node can not be 494c7a0d97cf2b27790e6236965a1d798d710d7ec7Jesse Wilson * returned or the iteration will go into an infinate loop. So to traverse 504c7a0d97cf2b27790e6236965a1d798d710d7ec7Jesse Wilson * an axis, the first function must be used to get the first node. 514c7a0d97cf2b27790e6236965a1d798d710d7ec7Jesse Wilson * 524c7a0d97cf2b27790e6236965a1d798d710d7ec7Jesse Wilson * <p>This method needs to be overloaded only by those axis that process 534c7a0d97cf2b27790e6236965a1d798d710d7ec7Jesse Wilson * the self node. <\p> 544c7a0d97cf2b27790e6236965a1d798d710d7ec7Jesse Wilson * 554c7a0d97cf2b27790e6236965a1d798d710d7ec7Jesse Wilson * @param context The context node of this traversal. This is the point 564c7a0d97cf2b27790e6236965a1d798d710d7ec7Jesse Wilson * that the traversal starts from. 574c7a0d97cf2b27790e6236965a1d798d710d7ec7Jesse Wilson * @return the first node in the traversal. 584c7a0d97cf2b27790e6236965a1d798d710d7ec7Jesse Wilson */ 594c7a0d97cf2b27790e6236965a1d798d710d7ec7Jesse Wilson public int first(int context) 604c7a0d97cf2b27790e6236965a1d798d710d7ec7Jesse Wilson { 614c7a0d97cf2b27790e6236965a1d798d710d7ec7Jesse Wilson return next(context, context); 624c7a0d97cf2b27790e6236965a1d798d710d7ec7Jesse Wilson } 634c7a0d97cf2b27790e6236965a1d798d710d7ec7Jesse Wilson 644c7a0d97cf2b27790e6236965a1d798d710d7ec7Jesse Wilson /** 654c7a0d97cf2b27790e6236965a1d798d710d7ec7Jesse Wilson * By the nature of the stateless traversal, the context node can not be 664c7a0d97cf2b27790e6236965a1d798d710d7ec7Jesse Wilson * returned or the iteration will go into an infinate loop. So to traverse 674c7a0d97cf2b27790e6236965a1d798d710d7ec7Jesse Wilson * an axis, the first function must be used to get the first node. 684c7a0d97cf2b27790e6236965a1d798d710d7ec7Jesse Wilson * 694c7a0d97cf2b27790e6236965a1d798d710d7ec7Jesse Wilson * <p>This method needs to be overloaded only by those axis that process 704c7a0d97cf2b27790e6236965a1d798d710d7ec7Jesse Wilson * the self node. <\p> 714c7a0d97cf2b27790e6236965a1d798d710d7ec7Jesse Wilson * 724c7a0d97cf2b27790e6236965a1d798d710d7ec7Jesse Wilson * @param context The context node of this traversal. This is the point 734c7a0d97cf2b27790e6236965a1d798d710d7ec7Jesse Wilson * of origin for the traversal -- its "root node" or starting point. 744c7a0d97cf2b27790e6236965a1d798d710d7ec7Jesse Wilson * @param extendedTypeID The extended type ID that must match. 754c7a0d97cf2b27790e6236965a1d798d710d7ec7Jesse Wilson * 764c7a0d97cf2b27790e6236965a1d798d710d7ec7Jesse Wilson * @return the first node in the traversal. 774c7a0d97cf2b27790e6236965a1d798d710d7ec7Jesse Wilson */ 784c7a0d97cf2b27790e6236965a1d798d710d7ec7Jesse Wilson public int first(int context, int extendedTypeID) 794c7a0d97cf2b27790e6236965a1d798d710d7ec7Jesse Wilson { 804c7a0d97cf2b27790e6236965a1d798d710d7ec7Jesse Wilson return next(context, context, extendedTypeID); 814c7a0d97cf2b27790e6236965a1d798d710d7ec7Jesse Wilson } 824c7a0d97cf2b27790e6236965a1d798d710d7ec7Jesse Wilson 834c7a0d97cf2b27790e6236965a1d798d710d7ec7Jesse Wilson /** 844c7a0d97cf2b27790e6236965a1d798d710d7ec7Jesse Wilson * Traverse to the next node after the current node. 854c7a0d97cf2b27790e6236965a1d798d710d7ec7Jesse Wilson * 864c7a0d97cf2b27790e6236965a1d798d710d7ec7Jesse Wilson * @param context The context node of this traversal. This is the point 874c7a0d97cf2b27790e6236965a1d798d710d7ec7Jesse Wilson * of origin for the traversal -- its "root node" or starting point. 884c7a0d97cf2b27790e6236965a1d798d710d7ec7Jesse Wilson * @param current The current node of the traversal. This is the last known 894c7a0d97cf2b27790e6236965a1d798d710d7ec7Jesse Wilson * location in the traversal, typically the node-handle returned by the 904c7a0d97cf2b27790e6236965a1d798d710d7ec7Jesse Wilson * previous traversal step. For the first traversal step, context 914c7a0d97cf2b27790e6236965a1d798d710d7ec7Jesse Wilson * should be set equal to current. Note that in order to test whether 924c7a0d97cf2b27790e6236965a1d798d710d7ec7Jesse Wilson * context is in the set, you must use the first() method instead. 934c7a0d97cf2b27790e6236965a1d798d710d7ec7Jesse Wilson * 944c7a0d97cf2b27790e6236965a1d798d710d7ec7Jesse Wilson * @return the next node in the iteration, or DTM.NULL. 954c7a0d97cf2b27790e6236965a1d798d710d7ec7Jesse Wilson * @see #first(int) 964c7a0d97cf2b27790e6236965a1d798d710d7ec7Jesse Wilson */ 974c7a0d97cf2b27790e6236965a1d798d710d7ec7Jesse Wilson public abstract int next(int context, int current); 984c7a0d97cf2b27790e6236965a1d798d710d7ec7Jesse Wilson 994c7a0d97cf2b27790e6236965a1d798d710d7ec7Jesse Wilson /** 1004c7a0d97cf2b27790e6236965a1d798d710d7ec7Jesse Wilson * Traverse to the next node after the current node that is matched 1014c7a0d97cf2b27790e6236965a1d798d710d7ec7Jesse Wilson * by the extended type ID. 1024c7a0d97cf2b27790e6236965a1d798d710d7ec7Jesse Wilson * 1034c7a0d97cf2b27790e6236965a1d798d710d7ec7Jesse Wilson * @param context The context node of this traversal. This is the point 1044c7a0d97cf2b27790e6236965a1d798d710d7ec7Jesse Wilson * of origin for the traversal -- its "root node" or starting point. 1054c7a0d97cf2b27790e6236965a1d798d710d7ec7Jesse Wilson * @param current The current node of the traversal. This is the last known 1064c7a0d97cf2b27790e6236965a1d798d710d7ec7Jesse Wilson * location in the traversal, typically the node-handle returned by the 1074c7a0d97cf2b27790e6236965a1d798d710d7ec7Jesse Wilson * previous traversal step. For the first traversal step, context 1084c7a0d97cf2b27790e6236965a1d798d710d7ec7Jesse Wilson * should be set equal to current. Note that in order to test whether 1094c7a0d97cf2b27790e6236965a1d798d710d7ec7Jesse Wilson * context is in the set, you must use the first() method instead. 1104c7a0d97cf2b27790e6236965a1d798d710d7ec7Jesse Wilson * @param extendedTypeID The extended type ID that must match. 1114c7a0d97cf2b27790e6236965a1d798d710d7ec7Jesse Wilson * 1124c7a0d97cf2b27790e6236965a1d798d710d7ec7Jesse Wilson * @return the next node in the iteration, or DTM.NULL. 1134c7a0d97cf2b27790e6236965a1d798d710d7ec7Jesse Wilson * @see #first(int,int) 1144c7a0d97cf2b27790e6236965a1d798d710d7ec7Jesse Wilson */ 1154c7a0d97cf2b27790e6236965a1d798d710d7ec7Jesse Wilson public abstract int next(int context, int current, int extendedTypeID); 1164c7a0d97cf2b27790e6236965a1d798d710d7ec7Jesse Wilson} 117