1/* 2 * reserved comment block 3 * DO NOT REMOVE OR ALTER! 4 */ 5/* 6 * Licensed to the Apache Software Foundation (ASF) under one or more 7 * contributor license agreements. See the NOTICE file distributed with 8 * this work for additional information regarding copyright ownership. 9 * The ASF licenses this file to You under the Apache License, Version 2.0 10 * (the "License"); you may not use this file except in compliance with 11 * the License. You may obtain a copy of the License at 12 * 13 * http://www.apache.org/licenses/LICENSE-2.0 14 * 15 * Unless required by applicable law or agreed to in writing, software 16 * distributed under the License is distributed on an "AS IS" BASIS, 17 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 18 * See the License for the specific language governing permissions and 19 * limitations under the License. 20 */ 21 22package com.sun.org.apache.xml.internal.dtm; 23 24/** 25 * A class that implements traverses DTMAxisTraverser interface can traverse 26 * a set of nodes, usually as defined by an XPath axis. It is different from 27 * an iterator, because it does not need to hold state, and, in fact, must not 28 * hold any iteration-based state. It is meant to be implemented as an inner 29 * class of a DTM, and returned by the getAxisTraverser(final int axis) 30 * function. 31 * 32 * <p>A DTMAxisTraverser can probably not traverse a reverse axis in 33 * document order.</p> 34 * 35 * <p>Typical usage:</p> 36 * <pre><code> 37 * for(int nodeHandle=myTraverser.first(myContext); 38 * nodeHandle!=DTM.NULL; 39 * nodeHandle=myTraverser.next(myContext,nodeHandle)) 40 * { ... processing for node indicated by nodeHandle goes here ... } 41 * </code></pre> 42 * 43 * @author Scott Boag 44 */ 45public abstract class DTMAxisTraverser 46{ 47 48 /** 49 * By the nature of the stateless traversal, the context node can not be 50 * returned or the iteration will go into an infinate loop. So to traverse 51 * an axis, the first function must be used to get the first node. 52 * 53 * <p>This method needs to be overloaded only by those axis that process 54 * the self node. <\p> 55 * 56 * @param context The context node of this traversal. This is the point 57 * that the traversal starts from. 58 * @return the first node in the traversal. 59 */ 60 public int first(int context) 61 { 62 return next(context, context); 63 } 64 65 /** 66 * By the nature of the stateless traversal, the context node can not be 67 * returned or the iteration will go into an infinate loop. So to traverse 68 * an axis, the first function must be used to get the first node. 69 * 70 * <p>This method needs to be overloaded only by those axis that process 71 * the self node. <\p> 72 * 73 * @param context The context node of this traversal. This is the point 74 * of origin for the traversal -- its "root node" or starting point. 75 * @param extendedTypeID The extended type ID that must match. 76 * 77 * @return the first node in the traversal. 78 */ 79 public int first(int context, int extendedTypeID) 80 { 81 return next(context, context, extendedTypeID); 82 } 83 84 /** 85 * Traverse to the next node after the current node. 86 * 87 * @param context The context node of this traversal. This is the point 88 * of origin for the traversal -- its "root node" or starting point. 89 * @param current The current node of the traversal. This is the last known 90 * location in the traversal, typically the node-handle returned by the 91 * previous traversal step. For the first traversal step, context 92 * should be set equal to current. Note that in order to test whether 93 * context is in the set, you must use the first() method instead. 94 * 95 * @return the next node in the iteration, or DTM.NULL. 96 * @see #first(int) 97 */ 98 public abstract int next(int context, int current); 99 100 /** 101 * Traverse to the next node after the current node that is matched 102 * by the extended type ID. 103 * 104 * @param context The context node of this traversal. This is the point 105 * of origin for the traversal -- its "root node" or starting point. 106 * @param current The current node of the traversal. This is the last known 107 * location in the traversal, typically the node-handle returned by the 108 * previous traversal step. For the first traversal step, context 109 * should be set equal to current. Note that in order to test whether 110 * context is in the set, you must use the first() method instead. 111 * @param extendedTypeID The extended type ID that must match. 112 * 113 * @return the next node in the iteration, or DTM.NULL. 114 * @see #first(int,int) 115 */ 116 public abstract int next(int context, int current, int extendedTypeID); 117} 118