• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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