Class XdmStream<T extends XdmItem>

java.lang.Object
net.sf.saxon.s9api.streams.XdmStream<T>
Type Parameters:
T - The type of items delivered by the stream.
All Implemented Interfaces:
AutoCloseable, BaseStream<T,Stream<T>>, Stream<T>

public class XdmStream<T extends XdmItem> extends Object implements Stream<T>
XdmStream extends the capabilities of the standard JDK Stream.

The extensions are:

  • Additional terminal operations are provided, allowing the results of the stream to be delivered for example as a List<XdmNode> or an Optional<XdmNode> more conveniently than using the general-purpose Collector interface.
  • Many of these terminal operations are short-circuiting, that is, they stop processing input when no further input is required.
  • The additional terminal operations throw a checked exception if a dynamic error occurs while generating the content of the stream.

The implementation is customized to streams of XdmItems.

Note: This class is implemented by wrapping a base stream. Generally, the methods on this class delegate to the base stream; those methods that return a stream wrap the stream returned by the base class. The context object can be used by a terminal method on the XdmStream to signal to the originator of the stream that no further input is required.

  • Field Details

  • Constructor Details

    • XdmStream

      public XdmStream(Stream<T> base)
      Create an XdmStream from a general Stream that returns XDM items.
      Parameters:
      base - the stream of items
    • XdmStream

      public XdmStream(Optional<T> input)
      Create an XdmStream consisting of zero or one items, supplied in the form of an Optional<XdmItem>
      Parameters:
      input - the optional item
  • Method Details

    • filter

      public XdmStream<T> filter(Predicate<? super T> predicate)
      Filter a stream of items, to create a new stream containing only those items that satisfy a supplied condition
      Specified by:
      filter in interface Stream<T extends XdmItem>
      Parameters:
      predicate - the supplied condition
      Returns:
      the filtered stream
    • map

      public <R> Stream<R> map(Function<? super T,? extends R> mapper)
      Specified by:
      map in interface Stream<T extends XdmItem>
    • mapToInt

      public IntStream mapToInt(ToIntFunction<? super T> mapper)
      Specified by:
      mapToInt in interface Stream<T extends XdmItem>
    • mapToLong

      public LongStream mapToLong(ToLongFunction<? super T> mapper)
      Specified by:
      mapToLong in interface Stream<T extends XdmItem>
    • mapToDouble

      public DoubleStream mapToDouble(ToDoubleFunction<? super T> mapper)
      Specified by:
      mapToDouble in interface Stream<T extends XdmItem>
    • flatMap

      public <R> Stream<R> flatMap(Function<? super T,? extends Stream<? extends R>> mapper)
      Specified by:
      flatMap in interface Stream<T extends XdmItem>
    • flatMapToXdm

      public <U extends XdmItem> XdmStream<U> flatMapToXdm(Step<U> mapper)
      Create a new XdmStream by applying a mapping function (specifically, a Step) to each item in the stream. The Step returns a sequence of items, which are inserted into the result sequence in place of the original item.
      Type Parameters:
      U - the type of items returned by the mapping function
      Parameters:
      mapper - the mapping function
      Returns:
      a new stream of items
    • flatMapToInt

      public IntStream flatMapToInt(Function<? super T,? extends IntStream> mapper)
      Specified by:
      flatMapToInt in interface Stream<T extends XdmItem>
    • flatMapToLong

      public LongStream flatMapToLong(Function<? super T,? extends LongStream> mapper)
      Specified by:
      flatMapToLong in interface Stream<T extends XdmItem>
    • flatMapToDouble

      public DoubleStream flatMapToDouble(Function<? super T,? extends DoubleStream> mapper)
      Specified by:
      flatMapToDouble in interface Stream<T extends XdmItem>
    • distinct

      public XdmStream<T> distinct()
      Specified by:
      distinct in interface Stream<T extends XdmItem>
    • sorted

      public XdmStream<T> sorted()
      Specified by:
      sorted in interface Stream<T extends XdmItem>
    • sorted

      public XdmStream<T> sorted(Comparator<? super T> comparator)
      Specified by:
      sorted in interface Stream<T extends XdmItem>
    • peek

      public XdmStream<T> peek(Consumer<? super T> action)
      Specified by:
      peek in interface Stream<T extends XdmItem>
    • limit

      public XdmStream<T> limit(long maxSize)
      Specified by:
      limit in interface Stream<T extends XdmItem>
    • skip

      public XdmStream<T> skip(long n)
      Specified by:
      skip in interface Stream<T extends XdmItem>
    • forEach

      public void forEach(Consumer<? super T> action)
      Specified by:
      forEach in interface Stream<T extends XdmItem>
    • forEachOrdered

      public void forEachOrdered(Consumer<? super T> action)
      Specified by:
      forEachOrdered in interface Stream<T extends XdmItem>
    • toArray

      public Object[] toArray()
      Specified by:
      toArray in interface Stream<T extends XdmItem>
    • toArray

      public <A> A[] toArray(IntFunction<A[]> generator)
      Specified by:
      toArray in interface Stream<T extends XdmItem>
    • reduce

      public T reduce(T identity, BinaryOperator<T> accumulator)
      Specified by:
      reduce in interface Stream<T extends XdmItem>
    • reduce

      public Optional<T> reduce(BinaryOperator<T> accumulator)
      Specified by:
      reduce in interface Stream<T extends XdmItem>
    • reduce

      public <U> U reduce(U identity, BiFunction<U,? super T,U> accumulator, BinaryOperator<U> combiner)
      Specified by:
      reduce in interface Stream<T extends XdmItem>
    • collect

      public <R> R collect(Supplier<R> supplier, BiConsumer<R,? super T> accumulator, BiConsumer<R,R> combiner)
      Specified by:
      collect in interface Stream<T extends XdmItem>
    • collect

      public <R, A> R collect(Collector<? super T,A,R> collector)
      Specified by:
      collect in interface Stream<T extends XdmItem>
    • min

      public Optional<T> min(Comparator<? super T> comparator)
      Specified by:
      min in interface Stream<T extends XdmItem>
    • max

      public Optional<T> max(Comparator<? super T> comparator)
      Specified by:
      max in interface Stream<T extends XdmItem>
    • count

      public long count()
      Specified by:
      count in interface Stream<T extends XdmItem>
    • anyMatch

      public boolean anyMatch(Predicate<? super T> predicate)
      Specified by:
      anyMatch in interface Stream<T extends XdmItem>
    • allMatch

      public boolean allMatch(Predicate<? super T> predicate)
      Specified by:
      allMatch in interface Stream<T extends XdmItem>
    • noneMatch

      public boolean noneMatch(Predicate<? super T> predicate)
      Specified by:
      noneMatch in interface Stream<T extends XdmItem>
    • findFirst

      public Optional<T> findFirst()
      Specified by:
      findFirst in interface Stream<T extends XdmItem>
    • findAny

      public Optional<T> findAny()
      Specified by:
      findAny in interface Stream<T extends XdmItem>
    • iterator

      public Iterator<T> iterator()
      Specified by:
      iterator in interface BaseStream<T extends XdmItem,Stream<T extends XdmItem>>
    • spliterator

      public Spliterator<T> spliterator()
      Specified by:
      spliterator in interface BaseStream<T extends XdmItem,Stream<T extends XdmItem>>
    • isParallel

      public boolean isParallel()
      Specified by:
      isParallel in interface BaseStream<T extends XdmItem,Stream<T extends XdmItem>>
    • sequential

      public Stream<T> sequential()
      Specified by:
      sequential in interface BaseStream<T extends XdmItem,Stream<T extends XdmItem>>
    • parallel

      public Stream<T> parallel()
      Specified by:
      parallel in interface BaseStream<T extends XdmItem,Stream<T extends XdmItem>>
    • unordered

      public Stream<T> unordered()
      Specified by:
      unordered in interface BaseStream<T extends XdmItem,Stream<T extends XdmItem>>
    • onClose

      public Stream<T> onClose(Runnable closeHandler)
      Specified by:
      onClose in interface BaseStream<T extends XdmItem,Stream<T extends XdmItem>>
    • close

      public void close()
      Specified by:
      close in interface AutoCloseable
      Specified by:
      close in interface BaseStream<T extends XdmItem,Stream<T extends XdmItem>>
    • asXdmValue

      public XdmValue asXdmValue()
      Return the result of the stream as an XdmValue. This is a terminal operation.
      Returns:
      the contents of the stream, as an XdmValue.
    • asList

      public List<T> asList()
      Return the result of the stream as a List<XdmItem>. This is a terminal operation.
      Returns:
      the contents of the stream, as a List<XdmItem>.
    • asListOfNodes

      public List<XdmNode> asListOfNodes()
      Return the result of the stream as a List<XdmNode>. This is a terminal operation.
      Returns:
      the list of nodes delivered by the stream
      Throws:
      ClassCastException - if the stream contains an item that is not a node
    • asOptionalNode

      public Optional<XdmNode> asOptionalNode()
      Return the result of the stream as an Optional<XdmNode>. This is a terminal operation.
      Returns:
      the single node delivered by the stream, or absent if the stream is empty
      Throws:
      XdmCollectors.MultipleItemException - if the stream contains more than one node
      ClassCastException - if the stream contains an item that is not a node
    • asNode

      public XdmNode asNode()
      Return the result of the stream as an XdmNode. This is a terminal operation.
      Returns:
      the single node delivered by the stream
      Throws:
      ClassCastException - if the stream contains an item that is not a node
      XdmCollectors.MultipleItemException - if the stream contains more than one item
      NoSuchElementException - if the stream is empty
    • asListOfAtomic

      public List<XdmAtomicValue> asListOfAtomic()
      Return the result of the stream as a List<XdmAtomicValue>. This is a terminal operation.
      Returns:
      the list of atomic values delivered by the stream
      Throws:
      ClassCastException - if the stream contains an item that is not an atomic value
    • asOptionalAtomic

      public Optional<XdmAtomicValue> asOptionalAtomic()
      Return the result of the stream as an Optional<XdmAtomicValue>. This is a terminal operation.
      Returns:
      the string value of the single item delivered by the stream, or absent if the stream is empty
      Throws:
      XdmCollectors.MultipleItemException - if the stream contains more than one item
      ClassCastException - if the stream contains an item that is not an atomic value
    • asAtomic

      public XdmAtomicValue asAtomic()
      Return the result of the stream as an XdmAtomicValue. This is a terminal operation.
      Returns:
      the string value of the single item delivered by the stream, or a zero-length string if the stream is empty
      Throws:
      ClassCastException - if the stream contains an item that is not atomic
      XdmCollectors.MultipleItemException - if the stream contains more than one item
      NoSuchElementException - if the stream is empty
    • asOptionalString

      public Optional<String> asOptionalString()
      Return the result of the stream as an Optional<String>. This is a terminal operation.
      Returns:
      the string value of the single item delivered by the stream, or absent if the stream is empty
      Throws:
      XdmCollectors.MultipleItemException - if the stream contains more than one item
      UnsupportedOperationException - if the stream contains an item that has no string value, for example a function item
    • asString

      public String asString()
      Return the result of the stream as an String. This is a terminal operation.
      Returns:
      the string value of the single item delivered by the stream
      Throws:
      UnsupportedOperationException - if the stream contains an item that has no string value, for example a function item
      XdmCollectors.MultipleItemException - if the stream contains more than one item
      NoSuchElementException - if the stream is empty
    • first

      public XdmStream<T> first()
      Return the first item of this stream, if there is one, discarding the remainder. This is a short-circuiting operation similar to findFirst(), but it returns XdmStream<T> rather than Optional<T> so that further operations such as atomize() can be applied, and so that a typed result can be returned using a method such as asOptionalNode() or asOptionalString()
    • exists

      public boolean exists()
      Return true if the stream is non-empty. This is a short-circuiting terminal operation.
      Returns:
      true if at least one item is present in the stream.
    • last

      public XdmStream<T> last()
      Return the last item of this stream, if there is one, discarding the remainder. This is a short-circuiting operation similar to first(); it returns XdmStream<T> rather than Optional<T> so that further operations such atomize() can be applied, and so that a typed result can be returned using a method such as asOptionalNode() or asOptionalString()
      Returns:
      a stream containing only the last item in the stream, or an empty stream if the input is empty.
    • at

      public Optional<T> at(int position)
      Return the item at a given position in the stream. This is a short-circuiting terminal operation.
      Parameters:
      position - the required position; items in the stream are numbered from zero.
      Returns:
      the item at the given position if there is one; otherwise, Optional.empty()
    • subStream

      public XdmStream<T> subStream(int start, int end)
      Return the items at a given range of positions in the stream. For example, subStream(0, 3) returns the first three items in the stream. This is a short-circuiting terminal operation.
      Parameters:
      start - the position of the first required item; items in the stream are numbered from zero.
      end - the position immediately after the last required item.
      Returns:
      a stream containing those items whose zero-based position is greater-than-or-equal-to start, and less-than end. No error occurs if either start or end is out of range, or if end is less than start.
    • untilFirstInclusive

      public XdmStream<T> untilFirstInclusive(Predicate<? super XdmItem> predicate)
      Experimental method to return the content of a stream up to the first item that satisfies a given predicate, including that item
      Parameters:
      predicate - a condition that determines when the stream should stop
      Returns:
      a stream containing all items in the base stream up to and including the first item that satisfies a given predicate.
    • untilFirstExclusive

      public XdmStream<T> untilFirstExclusive(Predicate<? super XdmItem> predicate)
      Experimental method to return the content of a stream up to the first item that satisfies a given predicate, excluding that item
      Parameters:
      predicate - a condition that determines when the stream should stop
      Returns:
      a stream containing all items in the base stream up to the item immediately before the first item that satisfies a given predicate.