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