net.sf.saxon.tree.iter

Interface GroundedIterator

All Superinterfaces:

java.lang.AutoCloseable, java.io.Closeable, SequenceIterator

All Known Implementing Classes:

ArrayIterator, ArrayIterator.Of, ArrayIterator.OfNodes, AscendingRangeIterator, BigRangeIterator, DescendingRangeIterator, EmptyIterator, FocusTrackingIterator, GroupByIterator.ManualGroupByIterator, ListIterator, ListIterator.Of, ListIterator.OfAtomic, ManualGroupIterator, ManualIterator, ManualRegexIterator, MemoSequence.ProgressiveIterator, MergeGroupingIterator.ManualMergeGroupingIterator, MultithreadedFocusTrackingIterator, NodeListIterator, RangeIterator, net.sf.saxon.expr.RangeIterator, SingleAtomicIterator, SingleNodeIterator, SingletonIterator, TwoItemIterator, ValueTailIterator, ZenoSequence.ZenoSequenceIterator

public interface GroundedIterator
extends SequenceIterator

This interface is an extension to the SequenceIterator interface; it represents a SequenceIterator that is based on an in-memory representation of a sequence, and that is therefore capable of returning a Sequence containing all the items in the sequence.

We stretch the concept to consider an iterator over a MemoClosure as a grounded iterator, on the basis that the in-memory sequence might exist already or might be created as a side-effect of navigating the iterator. This is why materializing the iterator can raise an exception.

Method Summary

Modifier and Type	Method and Description
GroundedValue	getResidue() Return a GroundedValue containing all the remaining items in the sequence returned by this SequenceIterator, starting at the current position.
boolean	isActuallyGrounded() Ask if the iterator is actually grounded.
default GroundedValue	materialize() Create a GroundedValue (a sequence materialized in memory) containing all the values delivered by this SequenceIterator.

Methods inherited from interface net.sf.saxon.om.SequenceIterator

close, discharge, next

Method Detail

isActuallyGrounded

boolean isActuallyGrounded()

Ask if the iterator is actually grounded. This method must be called before calling materialize() or getResidue(), because the iterator might be grounded under some conditions and not others (usually when it delegates to another iterator)

Returns:

true if this iterator is grounded

getResidue

GroundedValue getResidue()

Return a GroundedValue containing all the remaining items in the sequence returned by this SequenceIterator, starting at the current position. This should be an "in-memory" value, not a Closure. This method does not change the state of the iterator (in particular, it does not consume the iterator).

Returns:

the corresponding Value

Throws:

UncheckedXPathException - in the cases of subclasses (such as the iterator over a MemoClosure) which cause evaluation of expressions while materializing the value.

materialize

default GroundedValue materialize()

Create a GroundedValue (a sequence materialized in memory) containing all the values delivered by this SequenceIterator. The method must only be used when the SequenceIterator is positioned at the start. If it is not positioned at the start, then it is implementation-dependant whether the returned sequence contains all the nodes delivered by the SequenceIterator from the beginning, or only those delivered starting at the current position.

It is implementation-dependant whether this method consumes the SequenceIterator. (More specifically, in the current implementation: if the iterator is backed by a GroundedValue, then that value is returned and the iterator is not consumed; otherwise, the iterator is consumed and the method returns the remaining items after the current position only).

Returns:

a sequence containing all the items delivered by this SequenceIterator.

Throws:

UncheckedXPathException - if reading the SequenceIterator throws an error