libcore/luni/src/main/java/org/apache/xml/dtm/DTMAxisTraverser.java

   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    */
  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 }