001    /*
002     * Licensed to the Apache Software Foundation (ASF) under one
003     * or more contributor license agreements. See the NOTICE file
004     * distributed with this work for additional information
005     * regarding copyright ownership. The ASF licenses this file
006     * to you under the Apache License, Version 2.0 (the  "License");
007     * you may not use this file except in compliance with the License.
008     * You may obtain a copy of the License at
009     *
010     *     http://www.apache.org/licenses/LICENSE-2.0
011     *
012     * Unless required by applicable law or agreed to in writing, software
013     * distributed under the License is distributed on an "AS IS" BASIS,
014     * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
015     * See the License for the specific language governing permissions and
016     * limitations under the License.
017     */
018    /*
019     * $Id: DTMAxisIterator.java 468653 2006-10-28 07:07:05Z minchau $
020     */
021    package org.apache.xml.dtm;
022    
023    /**
024     * This class iterates over a single XPath Axis, and returns node handles.
025     */
026    public interface DTMAxisIterator extends Cloneable
027    {
028    
029      /** Specifies the end of the iteration, and is the same as DTM.NULL.  */
030      public static final int END = DTM.NULL;
031    
032      /**
033       * Get the next node in the iteration.
034       *
035       * @return The next node handle in the iteration, or END.
036       */
037      public int next();  
038      
039    
040      /**
041       * Resets the iterator to the last start node.
042       *
043       * @return A DTMAxisIterator, which may or may not be the same as this 
044       *         iterator.
045       */
046      public DTMAxisIterator reset();
047    
048      /**
049       * @return the number of nodes in this iterator.  This may be an expensive 
050       * operation when called the first time.
051       */
052      public int getLast();
053    
054      /**
055       * @return The position of the current node in the set, as defined by XPath.
056       */
057      public int getPosition();
058    
059      /**
060       * Remembers the current node for the next call to gotoMark().
061       */
062      public void setMark();
063    
064      /**
065       * Restores the current node remembered by setMark().
066       */
067      public void gotoMark();
068    
069      /**
070       * Set start to END should 'close' the iterator,
071       * i.e. subsequent call to next() should return END.
072       *
073       * @param node Sets the root of the iteration.
074       *
075       * @return A DTMAxisIterator set to the start of the iteration.
076       */
077      public DTMAxisIterator setStartNode(int node);
078    
079      /**
080       * Get start to END should 'close' the iterator,
081       * i.e. subsequent call to next() should return END.
082       *
083       * @return The root node of the iteration.
084       */
085      public int getStartNode();
086    
087      /**
088       * @return true if this iterator has a reversed axis, else false.
089       */
090      public boolean isReverse();
091    
092      /**
093       * @return a deep copy of this iterator. The clone should not be reset 
094       * from its current position.
095       */
096      public DTMAxisIterator cloneIterator();
097      
098      /**
099       * Set if restartable.
100       */
101      public void setRestartable(boolean isRestartable);
102    
103      /**
104       * Return the node at the given position.
105       * 
106       * @param position The position
107       * @return The node at the given position.
108       */
109      public int getNodeByPosition(int position);
110    }