Package net.sf.saxon.s9api.streams

Class XdmStream<T extends XdmItem>

  • Type Parameters:
    T - The type of items delivered by the stream.
    All Implemented Interfaces:
    java.lang.AutoCloseable, java.util.stream.BaseStream<T,​java.util.stream.Stream<T>>, java.util.stream.Stream<T>
    public class XdmStream<T extends XdmItem>
extends java.lang.Object
implements java.util.stream.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.

    • Nested Class Summary

      • Nested classes/interfaces inherited from interface java.util.stream.Stream

        java.util.stream.Stream.Builder<T extends java.lang.Object>

    • Constructor Summary

      Constructors 
      Constructor Description
      XdmStream​(java.util.Optional<T> input)
      Create an XdmStream consisting of zero or one items, supplied in the form of an Optional<XdmItem>
      XdmStream​(java.util.stream.Stream<T> base)
      Create an XdmStream from a general Stream that returns XDM items.

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      boolean allMatch​(java.util.function.Predicate<? super T> predicate)  
      boolean anyMatch​(java.util.function.Predicate<? super T> predicate)  
      XdmAtomicValue asAtomic()
      Return the result of the stream as an XdmAtomicValue.
      java.util.List<T> asList()
      Return the result of the stream as a List<XdmItem>.
      java.util.List<XdmAtomicValue> asListOfAtomic()
      Return the result of the stream as a List<XdmAtomicValue>.
      java.util.List<XdmNode> asListOfNodes()
      Return the result of the stream as a List<XdmNode>.
      XdmNode asNode()
      Return the result of the stream as an XdmNode.
      java.util.Optional<XdmAtomicValue> asOptionalAtomic()
      Return the result of the stream as an Optional<XdmAtomicValue>.
      java.util.Optional<XdmNode> asOptionalNode()
      Return the result of the stream as an Optional<XdmNode>.
      java.util.Optional<java.lang.String> asOptionalString()
      Return the result of the stream as an Optional<String>.
      java.lang.String asString()
      Return the result of the stream as an String.
      XdmValue asXdmValue()
      Return the result of the stream as an XdmValue.
      java.util.Optional<T> at​(int position)
      Return the item at a given position in the stream.
      void close()  
      <R> R collect​(java.util.function.Supplier<R> supplier, java.util.function.BiConsumer<R,​? super T> accumulator, java.util.function.BiConsumer<R,​R> combiner)  
      <R,​A>
      R      		 collect​(java.util.stream.Collector<? super T,​A,​R> collector)  
      long count()  
      XdmStream<T> distinct()  
      boolean exists()
      Return true if the stream is non-empty.
      XdmStream<T> filter​(java.util.function.Predicate<? super T> predicate)
      Filter a stream of items, to create a new stream containing only those items that satisfy a supplied condition
      java.util.Optional<T> findAny()  
      java.util.Optional<T> findFirst()  
      XdmStream<T> first()
      Return the first item of this stream, if there is one, discarding the remainder.
      <R> java.util.stream.Stream<R> flatMap​(java.util.function.Function<? super T,​? extends java.util.stream.Stream<? extends R>> mapper)  
      java.util.stream.DoubleStream flatMapToDouble​(java.util.function.Function<? super T,​? extends java.util.stream.DoubleStream> mapper)  
      java.util.stream.IntStream flatMapToInt​(java.util.function.Function<? super T,​? extends java.util.stream.IntStream> mapper)  
      java.util.stream.LongStream flatMapToLong​(java.util.function.Function<? super T,​? extends java.util.stream.LongStream> mapper)  
      <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.
      void forEach​(java.util.function.Consumer<? super T> action)  
      void forEachOrdered​(java.util.function.Consumer<? super T> action)  
      boolean isParallel()  
      java.util.Iterator<T> iterator()  
      XdmStream<T> last()
      Return the last item of this stream, if there is one, discarding the remainder.
      XdmStream<T> limit​(long maxSize)  
      <R> java.util.stream.Stream<R> map​(java.util.function.Function<? super T,​? extends R> mapper)  
      java.util.stream.DoubleStream mapToDouble​(java.util.function.ToDoubleFunction<? super T> mapper)  
      java.util.stream.IntStream mapToInt​(java.util.function.ToIntFunction<? super T> mapper)  
      java.util.stream.LongStream mapToLong​(java.util.function.ToLongFunction<? super T> mapper)  
      java.util.Optional<T> max​(java.util.Comparator<? super T> comparator)  
      java.util.Optional<T> min​(java.util.Comparator<? super T> comparator)  
      boolean noneMatch​(java.util.function.Predicate<? super T> predicate)  
      java.util.stream.Stream<T> onClose​(java.lang.Runnable closeHandler)  
      java.util.stream.Stream<T> parallel()  
      XdmStream<T> peek​(java.util.function.Consumer<? super T> action)  
      java.util.Optional<T> reduce​(java.util.function.BinaryOperator<T> accumulator)  
      T reduce​(T identity, java.util.function.BinaryOperator<T> accumulator)  
      <U> U reduce​(U identity, java.util.function.BiFunction<U,​? super T,​U> accumulator, java.util.function.BinaryOperator<U> combiner)  
      java.util.stream.Stream<T> sequential()  
      XdmStream<T> skip​(long n)  
      XdmStream<T> sorted()  
      XdmStream<T> sorted​(java.util.Comparator<? super T> comparator)  
      java.util.Spliterator<T> spliterator()  
      XdmStream<T> subStream​(int start, int end)
      Return the items at a given range of positions in the stream.
      java.lang.Object[] toArray()  
      <A> A[] toArray​(java.util.function.IntFunction<A[]> generator)  
      java.util.stream.Stream<T> unordered()  
      XdmStream<T> untilFirstExclusive​(java.util.function.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
      XdmStream<T> untilFirstInclusive​(java.util.function.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

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

      • Methods inherited from interface java.util.stream.Stream

        dropWhile, takeWhile

    • Constructor Detail

      • XdmStream

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

      • XdmStream

        public XdmStream​(java.util.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 Detail

      • filter

        public XdmStream<T> filter​(java.util.function.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 java.util.stream.Stream<T extends XdmItem>
        Parameters:
        predicate - the supplied condition
        Returns:
        the filtered stream

      • map

        public <R> java.util.stream.Stream<R> map​(java.util.function.Function<? super T,​? extends R> mapper)
        Specified by:
        map in interface java.util.stream.Stream<T extends XdmItem>

      • mapToInt

        public java.util.stream.IntStream mapToInt​(java.util.function.ToIntFunction<? super T> mapper)
        Specified by:
        mapToInt in interface java.util.stream.Stream<T extends XdmItem>

      • mapToLong

        public java.util.stream.LongStream mapToLong​(java.util.function.ToLongFunction<? super T> mapper)
        Specified by:
        mapToLong in interface java.util.stream.Stream<T extends XdmItem>

      • mapToDouble

        public java.util.stream.DoubleStream mapToDouble​(java.util.function.ToDoubleFunction<? super T> mapper)
        Specified by:
        mapToDouble in interface java.util.stream.Stream<T extends XdmItem>

      • flatMap

        public <R> java.util.stream.Stream<R> flatMap​(java.util.function.Function<? super T,​? extends java.util.stream.Stream<? extends R>> mapper)
        Specified by:
        flatMap in interface java.util.stream.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 java.util.stream.IntStream flatMapToInt​(java.util.function.Function<? super T,​? extends java.util.stream.IntStream> mapper)
        Specified by:
        flatMapToInt in interface java.util.stream.Stream<T extends XdmItem>

      • flatMapToLong

        public java.util.stream.LongStream flatMapToLong​(java.util.function.Function<? super T,​? extends java.util.stream.LongStream> mapper)
        Specified by:
        flatMapToLong in interface java.util.stream.Stream<T extends XdmItem>

      • flatMapToDouble

        public java.util.stream.DoubleStream flatMapToDouble​(java.util.function.Function<? super T,​? extends java.util.stream.DoubleStream> mapper)
        Specified by:
        flatMapToDouble in interface java.util.stream.Stream<T extends XdmItem>

      • distinct

        public XdmStream<T> distinct()
        Specified by:
        distinct in interface java.util.stream.Stream<T extends XdmItem>

      • sorted

        public XdmStream<T> sorted()
        Specified by:
        sorted in interface java.util.stream.Stream<T extends XdmItem>

      • sorted

        public XdmStream<T> sorted​(java.util.Comparator<? super T> comparator)
        Specified by:
        sorted in interface java.util.stream.Stream<T extends XdmItem>

      • peek

        public XdmStream<T> peek​(java.util.function.Consumer<? super T> action)
        Specified by:
        peek in interface java.util.stream.Stream<T extends XdmItem>

      • limit

        public XdmStream<T> limit​(long maxSize)
        Specified by:
        limit in interface java.util.stream.Stream<T extends XdmItem>

      • skip

        public XdmStream<T> skip​(long n)
        Specified by:
        skip in interface java.util.stream.Stream<T extends XdmItem>

      • forEach

        public void forEach​(java.util.function.Consumer<? super T> action)
        Specified by:
        forEach in interface java.util.stream.Stream<T extends XdmItem>

      • forEachOrdered

        public void forEachOrdered​(java.util.function.Consumer<? super T> action)
        Specified by:
        forEachOrdered in interface java.util.stream.Stream<T extends XdmItem>

      • toArray

        public java.lang.Object[] toArray()
        Specified by:
        toArray in interface java.util.stream.Stream<T extends XdmItem>

      • toArray

        public <A> A[] toArray​(java.util.function.IntFunction<A[]> generator)
        Specified by:
        toArray in interface java.util.stream.Stream<T extends XdmItem>

      • reduce

        public T reduce​(T identity,
                java.util.function.BinaryOperator<T> accumulator)
        Specified by:
        reduce in interface java.util.stream.Stream<T extends XdmItem>

      • reduce

        public java.util.Optional<T> reduce​(java.util.function.BinaryOperator<T> accumulator)
        Specified by:
        reduce in interface java.util.stream.Stream<T extends XdmItem>

      • reduce

        public <U> U reduce​(U identity,
                    java.util.function.BiFunction<U,​? super T,​U> accumulator,
                    java.util.function.BinaryOperator<U> combiner)
        Specified by:
        reduce in interface java.util.stream.Stream<T extends XdmItem>

      • collect

        public <R> R collect​(java.util.function.Supplier<R> supplier,
                     java.util.function.BiConsumer<R,​? super T> accumulator,
                     java.util.function.BiConsumer<R,​R> combiner)
        Specified by:
        collect in interface java.util.stream.Stream<T extends XdmItem>

      • collect

        public <R,​A> R collect​(java.util.stream.Collector<? super T,​A,​R> collector)
        Specified by:
        collect in interface java.util.stream.Stream<T extends XdmItem>

      • min

        public java.util.Optional<T> min​(java.util.Comparator<? super T> comparator)
        Specified by:
        min in interface java.util.stream.Stream<T extends XdmItem>

      • max

        public java.util.Optional<T> max​(java.util.Comparator<? super T> comparator)
        Specified by:
        max in interface java.util.stream.Stream<T extends XdmItem>

      • count

        public long count()
        Specified by:
        count in interface java.util.stream.Stream<T extends XdmItem>

      • anyMatch

        public boolean anyMatch​(java.util.function.Predicate<? super T> predicate)
        Specified by:
        anyMatch in interface java.util.stream.Stream<T extends XdmItem>

      • allMatch

        public boolean allMatch​(java.util.function.Predicate<? super T> predicate)
        Specified by:
        allMatch in interface java.util.stream.Stream<T extends XdmItem>

      • noneMatch

        public boolean noneMatch​(java.util.function.Predicate<? super T> predicate)
        Specified by:
        noneMatch in interface java.util.stream.Stream<T extends XdmItem>

      • findFirst

        public java.util.Optional<T> findFirst()
        Specified by:
        findFirst in interface java.util.stream.Stream<T extends XdmItem>

      • findAny

        public java.util.Optional<T> findAny()
        Specified by:
        findAny in interface java.util.stream.Stream<T extends XdmItem>

      • iterator

        public java.util.Iterator<T> iterator()
        Specified by:
        iterator in interface java.util.stream.BaseStream<T extends XdmItem,​java.util.stream.Stream<T extends XdmItem>>

      • spliterator

        public java.util.Spliterator<T> spliterator()
        Specified by:
        spliterator in interface java.util.stream.BaseStream<T extends XdmItem,​java.util.stream.Stream<T extends XdmItem>>

      • isParallel

        public boolean isParallel()
        Specified by:
        isParallel in interface java.util.stream.BaseStream<T extends XdmItem,​java.util.stream.Stream<T extends XdmItem>>

      • sequential

        public java.util.stream.Stream<T> sequential()
        Specified by:
        sequential in interface java.util.stream.BaseStream<T extends XdmItem,​java.util.stream.Stream<T extends XdmItem>>

      • parallel

        public java.util.stream.Stream<T> parallel()
        Specified by:
        parallel in interface java.util.stream.BaseStream<T extends XdmItem,​java.util.stream.Stream<T extends XdmItem>>

      • unordered

        public java.util.stream.Stream<T> unordered()
        Specified by:
        unordered in interface java.util.stream.BaseStream<T extends XdmItem,​java.util.stream.Stream<T extends XdmItem>>

      • onClose

        public java.util.stream.Stream<T> onClose​(java.lang.Runnable closeHandler)
        Specified by:
        onClose in interface java.util.stream.BaseStream<T extends XdmItem,​java.util.stream.Stream<T extends XdmItem>>

      • close

        public void close()
        Specified by:
        close in interface java.lang.AutoCloseable
        Specified by:
        close in interface java.util.stream.BaseStream<T extends XdmItem,​java.util.stream.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 java.util.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 java.util.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:
        java.lang.ClassCastException - if the stream contains an item that is not a node

      • asOptionalNode

        public java.util.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
        java.lang.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:
        java.lang.ClassCastException - if the stream contains an item that is not a node
        XdmCollectors.MultipleItemException - if the stream contains more than one item
        java.util.NoSuchElementException - if the stream is empty

      • asListOfAtomic

        public java.util.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:
        java.lang.ClassCastException - if the stream contains an item that is not an atomic value

      • asOptionalAtomic

        public java.util.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
        java.lang.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:
        java.lang.ClassCastException - if the stream contains an item that is not atomic
        XdmCollectors.MultipleItemException - if the stream contains more than one item
        java.util.NoSuchElementException - if the stream is empty

      • asOptionalString

        public java.util.Optional<java.lang.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
        java.lang.UnsupportedOperationException - if the stream contains an item that has no string value, for example a function item

      • asString

        public java.lang.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:
        java.lang.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
        java.util.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 java.util.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​(java.util.function.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​(java.util.function.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.