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