001 /*
002 * Licensed to the Apache Software Foundation (ASF) under one
003 * or more contributor license agreements. See the NOTICE file
004 * distributed with this work for additional information
005 * regarding copyright ownership. The ASF licenses this file
006 * to you under the Apache License, Version 2.0 (the "License");
007 * you may not use this file except in compliance with the License.
008 * You may obtain a copy of the License at
009 *
010 * http://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing, software
013 * distributed under the License is distributed on an "AS IS" BASIS,
014 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
015 * See the License for the specific language governing permissions and
016 * limitations under the License.
017 */
018 /*
019 * $Id: DTMAxisTraverser.java 468653 2006-10-28 07:07:05Z minchau $
020 */
021 package org.apache.xml.dtm;
022
023 /**
024 * A class that implements traverses DTMAxisTraverser interface can traverse
025 * a set of nodes, usually as defined by an XPath axis. It is different from
026 * an iterator, because it does not need to hold state, and, in fact, must not
027 * hold any iteration-based state. It is meant to be implemented as an inner
028 * class of a DTM, and returned by the getAxisTraverser(final int axis)
029 * function.
030 *
031 * <p>A DTMAxisTraverser can probably not traverse a reverse axis in
032 * document order.</p>
033 *
034 * <p>Typical usage:</p>
035 * <pre><code>
036 * for(int nodeHandle=myTraverser.first(myContext);
037 * nodeHandle!=DTM.NULL;
038 * nodeHandle=myTraverser.next(myContext,nodeHandle))
039 * { ... processing for node indicated by nodeHandle goes here ... }
040 * </code></pre>
041 *
042 * @author Scott Boag
043 */
044 public abstract class DTMAxisTraverser
045 {
046
047 /**
048 * By the nature of the stateless traversal, the context node can not be
049 * returned or the iteration will go into an infinate loop. So to traverse
050 * an axis, the first function must be used to get the first node.
051 *
052 * <p>This method needs to be overloaded only by those axis that process
053 * the self node. <\p>
054 *
055 * @param context The context node of this traversal. This is the point
056 * that the traversal starts from.
057 * @return the first node in the traversal.
058 */
059 public int first(int context)
060 {
061 return next(context, context);
062 }
063
064 /**
065 * By the nature of the stateless traversal, the context node can not be
066 * returned or the iteration will go into an infinate loop. So to traverse
067 * an axis, the first function must be used to get the first node.
068 *
069 * <p>This method needs to be overloaded only by those axis that process
070 * the self node. <\p>
071 *
072 * @param context The context node of this traversal. This is the point
073 * of origin for the traversal -- its "root node" or starting point.
074 * @param extendedTypeID The extended type ID that must match.
075 *
076 * @return the first node in the traversal.
077 */
078 public int first(int context, int extendedTypeID)
079 {
080 return next(context, context, extendedTypeID);
081 }
082
083 /**
084 * Traverse to the next node after the current node.
085 *
086 * @param context The context node of this traversal. This is the point
087 * of origin for the traversal -- its "root node" or starting point.
088 * @param current The current node of the traversal. This is the last known
089 * location in the traversal, typically the node-handle returned by the
090 * previous traversal step. For the first traversal step, context
091 * should be set equal to current. Note that in order to test whether
092 * context is in the set, you must use the first() method instead.
093 *
094 * @return the next node in the iteration, or DTM.NULL.
095 * @see #first(int)
096 */
097 public abstract int next(int context, int current);
098
099 /**
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 */
115 public abstract int next(int context, int current, int extendedTypeID);
116 }