View Javadoc
1   /*
2    * reserved comment block
3    * DO NOT REMOVE OR ALTER!
4    */
5   /*
6    * Copyright 1999-2004 The Apache Software Foundation.
7    *
8    * Licensed under the Apache License, Version 2.0 (the "License");
9    * you may not use this file except in compliance with the License.
10   * You may obtain a copy of the License at
11   *
12   *     http://www.apache.org/licenses/LICENSE-2.0
13   *
14   * Unless required by applicable law or agreed to in writing, software
15   * distributed under the License is distributed on an "AS IS" BASIS,
16   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
17   * See the License for the specific language governing permissions and
18   * limitations under the License.
19   */
20  /*
21   * $Id: DTMAxisTraverser.java,v 1.2.4.1 2005/09/15 08:14:52 suresh_emailid Exp $
22   */
23  package com.sun.org.apache.xml.internal.dtm;
24  
25  /**
26   * A class that implements traverses DTMAxisTraverser interface can traverse
27   * a set of nodes, usually as defined by an XPath axis.  It is different from
28   * an iterator, because it does not need to hold state, and, in fact, must not
29   * hold any iteration-based state.  It is meant to be implemented as an inner
30   * class of a DTM, and returned by the getAxisTraverser(final int axis)
31   * function.
32   *
33   * <p>A DTMAxisTraverser can probably not traverse a reverse axis in
34   * document order.</p>
35   *
36   * <p>Typical usage:</p>
37   * <pre><code>
38   * for(int nodeHandle=myTraverser.first(myContext);
39   *     nodeHandle!=DTM.NULL;
40   *     nodeHandle=myTraverser.next(myContext,nodeHandle))
41   * { ... processing for node indicated by nodeHandle goes here ... }
42   * </code></pre>
43   *
44   * @author Scott Boag
45   */
46  public abstract class DTMAxisTraverser
47  {
48  
49    /**
50     * By the nature of the stateless traversal, the context node can not be
51     * returned or the iteration will go into an infinate loop.  So to traverse
52     * an axis, the first function must be used to get the first node.
53     *
54     * <p>This method needs to be overloaded only by those axis that process
55     * the self node. <\p>
56     *
57     * @param context The context node of this traversal. This is the point
58     * that the traversal starts from.
59     * @return the first node in the traversal.
60     */
61    public int first(int context)
62    {
63      return next(context, context);
64    }
65  
66    /**
67     * By the nature of the stateless traversal, the context node can not be
68     * returned or the iteration will go into an infinate loop.  So to traverse
69     * an axis, the first function must be used to get the first node.
70     *
71     * <p>This method needs to be overloaded only by those axis that process
72     * the self node. <\p>
73     *
74     * @param context The context node of this traversal. This is the point
75     * of origin for the traversal -- its "root node" or starting point.
76     * @param extendedTypeID The extended type ID that must match.
77     *
78     * @return the first node in the traversal.
79     */
80    public int first(int context, int extendedTypeID)
81    {
82      return next(context, context, extendedTypeID);
83    }
84  
85    /**
86     * Traverse to the next node after the current node.
87     *
88     * @param context The context node of this traversal. This is the point
89     * of origin for the traversal -- its "root node" or starting point.
90     * @param current The current node of the traversal. This is the last known
91     * location in the traversal, typically the node-handle returned by the
92     * previous traversal step. For the first traversal step, context
93     * should be set equal to current. Note that in order to test whether
94     * context is in the set, you must use the first() method instead.
95     *
96     * @return the next node in the iteration, or DTM.NULL.
97     * @see #first(int)
98     */
99    public abstract int next(int context, int current);
100 
101   /**
102    * Traverse to the next node after the current node that is matched
103    * by the extended type ID.
104    *
105    * @param context The context node of this traversal. This is the point
106    * of origin for the traversal -- its "root node" or starting point.
107    * @param current The current node of the traversal. This is the last known
108    * location in the traversal, typically the node-handle returned by the
109    * previous traversal step. For the first traversal step, context
110    * should be set equal to current. Note that in order to test whether
111    * context is in the set, you must use the first() method instead.
112    * @param extendedTypeID The extended type ID that must match.
113    *
114    * @return the next node in the iteration, or DTM.NULL.
115    * @see #first(int,int)
116    */
117   public abstract int next(int context, int current, int extendedTypeID);
118 }