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 */
21package 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 */
44public 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   */
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   */
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   */
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   */
115  public abstract int next(int context, int current, int extendedTypeID);
116}
117