001: package net.sf.saxon.om;
002:
003: import net.sf.saxon.trans.XPathException;
004:
005: /**
006: * A SequenceIterator is used to iterate over any XPath 2 sequence (of values or nodes).
007: * To get the next item in a sequence, call next(); if this returns null, you've
008: * reached the end of the sequence.
009: * <p>
010: * A SequenceIterator keeps track of the current Item and the current position.
011: * The objects returned by the SequenceIterator will always be either nodes
012: * (class NodeInfo) or singleton values (class AtomicValue): these are represented
013: * collectively by the interface Item.
014: * <p>
015: * This interface forms part of the public Saxon API. The JavaDoc "since" flag is used from
016: * release 8.4 onwards to indicate methods that are considered to be a stable part
017: * of the API. Methods without a "since" flag should not be regarded as a stable part
018: * of the API.
019: * <p>
020: * Note that the stability of this interface applies to classes that use the interface,
021: * not to classes that implement it. The interface may be extended in future to add new methods.
022: *
023: * @author Michael H. Kay
024: * @since 8.4
025: */
026:
027: public interface SequenceIterator {
028:
029: /**
030: * Get the next item in the sequence. This method changes the state of the
031: * iterator, in particular it affects the result of subsequent calls of
032: * position() and current().
033: * @throws XPathException if an error occurs retrieving the next item
034: * @return the next item, or null if there are no more items. Once a call
035: * on next() has returned null, no further calls should be made. The preferred
036: * action for an iterator if subsequent calls on next() are made is to return
037: * null again, and all implementations within Saxon follow this rule.
038: * @since 8.4
039: */
040:
041: public Item next() throws XPathException;
042:
043: /**
044: * Get the current value in the sequence (the one returned by the
045: * most recent call on next()). This will be null before the first
046: * call of next(). This method does not change the state of the iterator.
047: *
048: * @return the current item, the one most recently returned by a call on
049: * next(). Returns null if next() has not been called, or if the end
050: * of the sequence has been reached.
051: * @since 8.4
052: */
053:
054: public Item current();
055:
056: /**
057: * Get the current position. This will usually be zero before the first call
058: * on next(), otherwise it will be the number of times that next() has
059: * been called. Once next() has returned null, the preferred action is
060: * for subsequent calls on position() to return -1, but not all existing
061: * implementations follow this practice. (In particular, the EmptyIterator
062: * is stateless, and always returns 0 as the value of position(), whether
063: * or not next() has been called.)
064: * <p>
065: * This method does not change the state of the iterator.
066: *
067: * @return the current position, the position of the item returned by the
068: * most recent call of next(). This is 1 after next() has been successfully
069: * called once, 2 after it has been called twice, and so on. If next() has
070: * never been called, the method returns zero. If the end of the sequence
071: * has been reached, the value returned will always be <= 0; the preferred
072: * value is -1.
073: *
074: * @since 8.4
075: */
076:
077: public int position();
078:
079: /**
080: * Get another SequenceIterator that iterates over the same items as the original,
081: * but which is repositioned at the start of the sequence.
082: * <p>
083: * This method allows access to all the items in the sequence without disturbing the
084: * current position of the iterator. Internally, its main use is in evaluating the last()
085: * function.
086: * <p>
087: * This method does not change the state of the iterator.
088: *
089: * @exception XPathException if any error occurs
090: * @return a SequenceIterator that iterates over the same items,
091: * positioned before the first item
092: * @since 8.4
093: */
094:
095: public SequenceIterator getAnother() throws XPathException;
096:
097: /**
098: * Get properties of this iterator, as a bit-significant integer.
099: * @return the properties of this iterator. This will be some combination of
100: * properties such as {@link GROUNDED}, {@link LAST_POSITION_FINDER},
101: * and {@link LOOKAHEAD}. It is always
102: * acceptable to return the value zero, indicating that there are no known special properties.
103: * It is acceptable for the properties of the iterator to change depending on its state.
104: * @since 8.6
105: */
106:
107: public int getProperties();
108:
109: /**
110: * Property value: the iterator is "grounded". This means that (a) the
111: * iterator must be an instance of {@link GroundedIterator}, and (b) the
112: * implementation of the materialize() method must be efficient (in particular,
113: * it should not involve the creation of new objects)
114: */
115:
116: public static final int GROUNDED = 1 << 0;
117:
118: /**
119: * Property value: the iterator knows the number of items that it will deliver.
120: * This means that (a) the iterator must be an instance of {@link net.sf.saxon.expr.LastPositionFinder},
121: * and (b) the implementation of the getLastPosition() method must be efficient (in particular,
122: * it should take constant time, rather than time proportional to the length of the sequence)
123: */
124:
125: public static final int LAST_POSITION_FINDER = 1 << 1;
126:
127: /**
128: * Property value: the iterator knows whether there are more items still to come. This means
129: * that (a) the iterator must be an instance of {@link LookaheadIterator}, and (b) the
130: * implementation of the hasNext() method must be efficient (more efficient than the client doing
131: * it)
132: */
133:
134: public static final int LOOKAHEAD = 1 << 2;
135:
136: /**
137: * Property value: the iterator supports a setAtomizing() method, which requests (but does not require)
138: * the iterator to atomize any nodes and return their typed values
139: */
140:
141: public static final int ATOMIZABLE = 1 << 3;
142:
143: }
144:
145: //
146: // The contents of this file are subject to the Mozilla Public License Version 1.0 (the "License");
147: // you may not use this file except in compliance with the License. You may obtain a copy of the
148: // License at http://www.mozilla.org/MPL/
149: //
150: // Software distributed under the License is distributed on an "AS IS" basis,
151: // WITHOUT WARRANTY OF ANY KIND, either express or implied.
152: // See the License for the specific language governing rights and limitations under the License.
153: //
154: // The Original Code is: all this file.
155: //
156: // The Initial Developer of the Original Code is Michael H. Kay.
157: //
158: // Portions created by (your name) are Copyright (C) (your legal entity). All Rights Reserved.
159: //
160: // Contributor(s): none.
161: //
|