Package net.sf.saxon.tree.iter

Interface GroundedIterator

All Superinterfaces:
AutoCloseable, Closeable, SequenceIterator
All Known Implementing Classes:
ArrayIterator, ArrayIterator.Of, ArrayIterator.OfNodes, AscendingRangeIterator, BigRangeIterator, DescendingRangeIterator, EmptyIterator, FocusTrackingIterator, ListIterator, ListIterator.Of, ListIterator.OfAtomic, ManualGroupIterator, ManualIterator, ManualRegexIterator, MemoSequence.ProgressiveIterator, MultithreadedFocusTrackingIterator, NodeListIterator, RangeIterator, ReportingSingletonIterator, 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
    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, next

  • Method Details

    • 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