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: DTMAxisTraverser.java 468653 2006-10-28 07:07:05Z minchau $ 20 */ 21 package org.apache.xml.dtm; 22 23 /** 24 * A class that implements traverses DTMAxisTraverser interface can traverse 25 * a set of nodes, usually as defined by an XPath axis. It is different from 26 * an iterator, because it does not need to hold state, and, in fact, must not 27 * hold any iteration-based state. It is meant to be implemented as an inner 28 * class of a DTM, and returned by the getAxisTraverser(final int axis) 29 * function. 30 * 31 * <p>A DTMAxisTraverser can probably not traverse a reverse axis in 32 * document order.</p> 33 * 34 * <p>Typical usage:</p> 35 * <pre><code> 36 * for(int nodeHandle=myTraverser.first(myContext); 37 * nodeHandle!=DTM.NULL; 38 * nodeHandle=myTraverser.next(myContext,nodeHandle)) 39 * { ... processing for node indicated by nodeHandle goes here ... } 40 * </code></pre> 41 * 42 * @author Scott Boag 43 */ 44 public abstract class DTMAxisTraverser 45 { 46 47 /** 48 * By the nature of the stateless traversal, the context node can not be 49 * returned or the iteration will go into an infinate loop. So to traverse 50 * an axis, the first function must be used to get the first node. 51 * 52 * <p>This method needs to be overloaded only by those axis that process 53 * the self node. <\p> 54 * 55 * @param context The context node of this traversal. This is the point 56 * that the traversal starts from. 57 * @return the first node in the traversal. 58 */ first(int context)59 public int first(int context) 60 { 61 return next(context, context); 62 } 63 64 /** 65 * By the nature of the stateless traversal, the context node can not be 66 * returned or the iteration will go into an infinate loop. So to traverse 67 * an axis, the first function must be used to get the first node. 68 * 69 * <p>This method needs to be overloaded only by those axis that process 70 * the self node. <\p> 71 * 72 * @param context The context node of this traversal. This is the point 73 * of origin for the traversal -- its "root node" or starting point. 74 * @param extendedTypeID The extended type ID that must match. 75 * 76 * @return the first node in the traversal. 77 */ first(int context, int extendedTypeID)78 public int first(int context, int extendedTypeID) 79 { 80 return next(context, context, extendedTypeID); 81 } 82 83 /** 84 * Traverse to the next node after the current node. 85 * 86 * @param context The context node of this traversal. This is the point 87 * of origin for the traversal -- its "root node" or starting point. 88 * @param current The current node of the traversal. This is the last known 89 * location in the traversal, typically the node-handle returned by the 90 * previous traversal step. For the first traversal step, context 91 * should be set equal to current. Note that in order to test whether 92 * context is in the set, you must use the first() method instead. 93 * 94 * @return the next node in the iteration, or DTM.NULL. 95 * @see #first(int) 96 */ next(int context, int current)97 public abstract int next(int context, int current); 98 99 /** 100 * Traverse to the next node after the current node that is matched 101 * by the extended type ID. 102 * 103 * @param context The context node of this traversal. This is the point 104 * of origin for the traversal -- its "root node" or starting point. 105 * @param current The current node of the traversal. This is the last known 106 * location in the traversal, typically the node-handle returned by the 107 * previous traversal step. For the first traversal step, context 108 * should be set equal to current. Note that in order to test whether 109 * context is in the set, you must use the first() method instead. 110 * @param extendedTypeID The extended type ID that must match. 111 * 112 * @return the next node in the iteration, or DTM.NULL. 113 * @see #first(int,int) 114 */ next(int context, int current, int extendedTypeID)115 public abstract int next(int context, int current, int extendedTypeID); 116 } 117