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: DTMAxisIterator.java 468653 2006-10-28 07:07:05Z minchau $
20 */
21package org.apache.xml.dtm;
22
23/**
24 * This class iterates over a single XPath Axis, and returns node handles.
25 */
26public interface DTMAxisIterator extends Cloneable
27{
28
29  /** Specifies the end of the iteration, and is the same as DTM.NULL.  */
30  public static final int END = DTM.NULL;
31
32  /**
33   * Get the next node in the iteration.
34   *
35   * @return The next node handle in the iteration, or END.
36   */
37  public int next();
38
39
40  /**
41   * Resets the iterator to the last start node.
42   *
43   * @return A DTMAxisIterator, which may or may not be the same as this
44   *         iterator.
45   */
46  public DTMAxisIterator reset();
47
48  /**
49   * @return the number of nodes in this iterator.  This may be an expensive
50   * operation when called the first time.
51   */
52  public int getLast();
53
54  /**
55   * @return The position of the current node in the set, as defined by XPath.
56   */
57  public int getPosition();
58
59  /**
60   * Remembers the current node for the next call to gotoMark().
61   */
62  public void setMark();
63
64  /**
65   * Restores the current node remembered by setMark().
66   */
67  public void gotoMark();
68
69  /**
70   * Set start to END should 'close' the iterator,
71   * i.e. subsequent call to next() should return END.
72   *
73   * @param node Sets the root of the iteration.
74   *
75   * @return A DTMAxisIterator set to the start of the iteration.
76   */
77  public DTMAxisIterator setStartNode(int node);
78
79  /**
80   * Get start to END should 'close' the iterator,
81   * i.e. subsequent call to next() should return END.
82   *
83   * @return The root node of the iteration.
84   */
85  public int getStartNode();
86
87  /**
88   * @return true if this iterator has a reversed axis, else false.
89   */
90  public boolean isReverse();
91
92  /**
93   * @return a deep copy of this iterator. The clone should not be reset
94   * from its current position.
95   */
96  public DTMAxisIterator cloneIterator();
97
98  /**
99   * 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}
111