19f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson/* 29f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * Licensed to the Apache Software Foundation (ASF) under one 39f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * or more contributor license agreements. See the NOTICE file 49f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * distributed with this work for additional information 59f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * regarding copyright ownership. The ASF licenses this file 69f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * to you under the Apache License, Version 2.0 (the "License"); 79f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * you may not use this file except in compliance with the License. 89f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * You may obtain a copy of the License at 99f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * 109f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * http://www.apache.org/licenses/LICENSE-2.0 119f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * 129f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * Unless required by applicable law or agreed to in writing, software 139f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * distributed under the License is distributed on an "AS IS" BASIS, 149f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 159f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * See the License for the specific language governing permissions and 169f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * limitations under the License. 179f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson */ 189f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson/* 199f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * $Id: DTMAxisTraverser.java 468653 2006-10-28 07:07:05Z minchau $ 209f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson */ 219f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilsonpackage org.apache.xml.dtm; 229f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson 239f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson/** 249f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * A class that implements traverses DTMAxisTraverser interface can traverse 259f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * a set of nodes, usually as defined by an XPath axis. It is different from 269f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * an iterator, because it does not need to hold state, and, in fact, must not 279f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * hold any iteration-based state. It is meant to be implemented as an inner 289f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * class of a DTM, and returned by the getAxisTraverser(final int axis) 299f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * function. 309f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * 319f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * <p>A DTMAxisTraverser can probably not traverse a reverse axis in 329f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * document order.</p> 339f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * 349f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * <p>Typical usage:</p> 359f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * <pre><code> 369f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * for(int nodeHandle=myTraverser.first(myContext); 379f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * nodeHandle!=DTM.NULL; 389f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * nodeHandle=myTraverser.next(myContext,nodeHandle)) 399f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * { ... processing for node indicated by nodeHandle goes here ... } 409f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * </code></pre> 419f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * 429f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * @author Scott Boag 439f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson */ 449f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilsonpublic abstract class DTMAxisTraverser 459f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson{ 469f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson 479f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson /** 489f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * By the nature of the stateless traversal, the context node can not be 499f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * returned or the iteration will go into an infinate loop. So to traverse 509f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * an axis, the first function must be used to get the first node. 519f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * 529f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * <p>This method needs to be overloaded only by those axis that process 539f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * the self node. <\p> 549f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * 559f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * @param context The context node of this traversal. This is the point 569f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * that the traversal starts from. 579f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * @return the first node in the traversal. 589f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson */ 599f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson public int first(int context) 609f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson { 619f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson return next(context, context); 629f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson } 639f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson 649f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson /** 659f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * By the nature of the stateless traversal, the context node can not be 669f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * returned or the iteration will go into an infinate loop. So to traverse 679f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * an axis, the first function must be used to get the first node. 689f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * 699f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * <p>This method needs to be overloaded only by those axis that process 709f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * the self node. <\p> 719f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * 729f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * @param context The context node of this traversal. This is the point 739f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * of origin for the traversal -- its "root node" or starting point. 749f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * @param extendedTypeID The extended type ID that must match. 759f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * 769f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * @return the first node in the traversal. 779f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson */ 789f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson public int first(int context, int extendedTypeID) 799f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson { 809f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson return next(context, context, extendedTypeID); 819f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson } 829f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson 839f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson /** 849f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * Traverse to the next node after the current node. 859f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * 869f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * @param context The context node of this traversal. This is the point 879f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * of origin for the traversal -- its "root node" or starting point. 889f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * @param current The current node of the traversal. This is the last known 899f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * location in the traversal, typically the node-handle returned by the 909f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * previous traversal step. For the first traversal step, context 919f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * should be set equal to current. Note that in order to test whether 929f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * context is in the set, you must use the first() method instead. 939f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * 949f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * @return the next node in the iteration, or DTM.NULL. 959f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * @see #first(int) 969f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson */ 979f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson public abstract int next(int context, int current); 989f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson 999f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson /** 1009f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * Traverse to the next node after the current node that is matched 1019f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * by the extended type ID. 1029f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * 1039f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * @param context The context node of this traversal. This is the point 1049f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * of origin for the traversal -- its "root node" or starting point. 1059f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * @param current The current node of the traversal. This is the last known 1069f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * location in the traversal, typically the node-handle returned by the 1079f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * previous traversal step. For the first traversal step, context 1089f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * should be set equal to current. Note that in order to test whether 1099f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * context is in the set, you must use the first() method instead. 1109f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * @param extendedTypeID The extended type ID that must match. 1119f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * 1129f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * @return the next node in the iteration, or DTM.NULL. 1139f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson * @see #first(int,int) 1149f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson */ 1159f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson public abstract int next(int context, int current, int extendedTypeID); 1169f8118474e9513f7a5b7d2a05e4a0fb15d1a6569Jesse Wilson} 117