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 class.

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.

  • Constructor Details Link icon

    • XdmStream Link icon

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

      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 Link icon

    • filter Link icon

      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.

      For example, body.select(child("*")).filter(n -> n.getNodeName().getLocalName().startsWith("h")) returns a stream of all the child elements of body whose local name starts with "h".

      Note: an alternative to filtering a stream is to use a Step that incorporates a Predicate, for example body.select(child("*").where(n -> n.getNodeName().getLocalName().startsWith("h")))

      Specified by:
      filter in interface Stream<T extends XdmItem>
      Parameters:
      predicate - the supplied condition. Any Predicate can be supplied, but some particularly useful predicates are available by calling static methods on the Predicates class, for example Predicates.empty(Steps.child("author")), which is true for a node that has no child elements with local name "author".
      Returns:
      the filtered stream
    • map Link icon

      public <R> Stream<R> map(Function<? super T,? extends R> mapper)
      Returns a stream consisting of the results of applying the given function to the elements of this stream.

      This is an intermediate operation.

      For example, n.select(child(*)).map(c -> c.getNodeName().getLocalName()) returns a stream delivering the local names of the element children of n, as instances of java.lang.String. Note the result is a Stream, not an XdmStream.

      Specified by:
      map in interface Stream<T extends XdmItem>
      Type Parameters:
      R - The element type of the new stream
      Parameters:
      mapper - a non-interfering, stateless function to apply to each element
      Returns:
      the new stream
    • mapToInt Link icon

      public IntStream mapToInt(ToIntFunction<? super T> mapper)
      Returns an IntStream consisting of the results of applying the given function to the elements of this stream.

      For example, n.select(child(*)).map(c -> c.getStringValue().length()) returns a stream delivering the lengths of the string-values of the element children of n. Note the result is a Stream, not an XdmStream.

      This is an intermediate operation.

      Specified by:
      mapToInt in interface Stream<T extends XdmItem>
      Parameters:
      mapper - a non-interfering, stateless function to apply to each element
      Returns:
      the new stream
    • mapToLong Link icon

      public LongStream mapToLong(ToLongFunction<? super T> mapper)
      Returns a LongStream consisting of the results of applying the given function to the elements of this stream.

      This is an intermediate operation.

      Specified by:
      mapToLong in interface Stream<T extends XdmItem>
      Parameters:
      mapper - a non-interfering, stateless function to apply to each element
      Returns:
      the new stream
    • mapToDouble Link icon

      public DoubleStream mapToDouble(ToDoubleFunction<? super T> mapper)
      Returns a DoubleStream consisting of the results of applying the given function to the elements of this stream.

      This is an intermediate operation.

      Specified by:
      mapToDouble in interface Stream<T extends XdmItem>
      Parameters:
      mapper - a non-interfering, stateless function to apply to each element
      Returns:
      the new stream
    • flatMap Link icon

      public <R> Stream<R> flatMap(Function<? super T,? extends Stream<? extends R>> mapper)
      Returns a stream consisting of the results of replacing each element of this stream with the contents of a mapped stream produced by applying the provided mapping function to each element. Each mapped stream is closed after its contents have been placed into this stream. (If a mapped stream is null an empty stream is used, instead.)

      This is an intermediate operation.

      Note: The flatMap() operation has the effect of applying a one-to-many transformation to the elements of the stream, and then flattening the resulting elements into a new stream. This corresponds to the action of the "!" operator in XPath.

      Specified by:
      flatMap in interface Stream<T extends XdmItem>
      Type Parameters:
      R - The element type of the new stream
      Parameters:
      mapper - a non-interfering, stateless function to apply to each element which produces a stream of new values
      Returns:
      the new stream
    • flatMapToXdm Link icon

      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.

      This method is similar to flatMap(java.util.function.Function<? super T, ? extends java.util.stream.Stream<? extends R>>), but differs in that it returns an XdmStream, making additional methods available.

      Note: XdmValue.select(net.sf.saxon.s9api.streams.Step<T>) is implemented using this method, and in practice it is usually clearer to use that method directly. For example node.select(child("*")).flatMapToXdm(child(*)) can be written as node.select(child("*").then(child("*")). Both expressions return a stream containing all the grandchildren elements of node. The same result can be achieved more concisely by writing node.select(path("*", "*"))

      Type Parameters:
      U - the type of items returned by the mapping function
      Parameters:
      mapper - the mapping function
      Returns:
      a new stream of items
    • flatMapToInt Link icon

      public IntStream flatMapToInt(Function<? super T,? extends IntStream> mapper)
      Returns an IntStream consisting of the results of replacing each element of this stream with the contents of a mapped stream produced by applying the provided mapping function to each element. Each mapped stream is closed after its contents have been placed into this stream. (If a mapped stream is null an empty stream is used, instead.)

      This is an intermediate operation.

      Specified by:
      flatMapToInt in interface Stream<T extends XdmItem>
      Parameters:
      mapper - a non-interfering, stateless function to apply to each element which produces a stream of new values
      Returns:
      the new stream
      See Also:
    • flatMapToLong Link icon

      public LongStream flatMapToLong(Function<? super T,? extends LongStream> mapper)
      Returns an LongStream consisting of the results of replacing each element of this stream with the contents of a mapped stream produced by applying the provided mapping function to each element. Each mapped stream is closed after its contents have been placed into this stream. (If a mapped stream is null an empty stream is used, instead.)

      This is an intermediate operation.

      Specified by:
      flatMapToLong in interface Stream<T extends XdmItem>
      Parameters:
      mapper - a non-interfering, stateless function to apply to each element which produces a stream of new values
      Returns:
      the new stream
      See Also:
    • flatMapToDouble Link icon

      public DoubleStream flatMapToDouble(Function<? super T,? extends DoubleStream> mapper)
      Returns an DoubleStream consisting of the results of replacing each element of this stream with the contents of a mapped stream produced by applying the provided mapping function to each element. Each mapped stream is closed after its contents have placed been into this stream. (If a mapped stream is null an empty stream is used, instead.)

      This is an intermediate operation.

      Specified by:
      flatMapToDouble in interface Stream<T extends XdmItem>
      Parameters:
      mapper - a non-interfering, stateless function to apply to each element which produces a stream of new values
      Returns:
      the new stream
      See Also:
    • distinct Link icon

      public XdmStream<T> distinct()
      Returns a stream consisting of the distinct items present in this stream. Items are compared using Object.equals(java.lang.Object). This means that two XdmNode objects are compared by node identity (so two separate nodes are distinct even if they have the same name and the same content).
      Specified by:
      distinct in interface Stream<T extends XdmItem>
      Returns:
      the new stream, obtained by applying Stream.distinct() to the underlying stream
    • sorted Link icon

      public XdmStream<T> sorted()
      Returns a stream consisting of the elements of this stream, in sorted order.

      Note, this method is unlikely to be useful, because most XdmItem values do not implement Comparable.

      Specified by:
      sorted in interface Stream<T extends XdmItem>
      Returns:
      the new stream, obtained by applying Stream.sorted() to the underlying stream
    • sorted Link icon

      public XdmStream<T> sorted(Comparator<? super T> comparator)
      Returns a stream consisting of the elements of this stream, in sorted order using a supplied Comparator.
      Specified by:
      sorted in interface Stream<T extends XdmItem>
      Returns:
      the new stream, obtained by applying Stream.sorted(Comparator) to the underlying stream
    • peek Link icon

      public XdmStream<T> peek(Consumer<? super T> action)
      Returns the supplied stream, while invoking a supplied action on each element of the stream as it is processed.

      This method is designed primarily for debugging, to allow the contents of a stream to be monitored.

      Specified by:
      peek in interface Stream<T extends XdmItem>
      Parameters:
      action - the (non-interfering) action to be performed on each element of the stream
      Returns:
      the supplied stream, unchanged.
    • limit Link icon

      public XdmStream<T> limit(long maxSize)
      Returns a stream containing the initial items of this stream, up to a maximum size
      Specified by:
      limit in interface Stream<T extends XdmItem>
      Parameters:
      maxSize - the maximum number of items to be included in the returned stream
      Returns:
      a stream containing the initial items of this stream, up to the specified limit
    • skip Link icon

      public XdmStream<T> skip(long n)
      Returns a stream containing the items of this stream after skipping a specified number of items.
      Specified by:
      skip in interface Stream<T extends XdmItem>
      Parameters:
      n - the number of items at the start of the stream to be omitted from the result stream
      Returns:
      the result stream, comprising the input stream except for its first n items.
    • forEach Link icon

      public void forEach(Consumer<? super T> action)
      Performs a given action once for each item of the stream, in non-deterministic order
      Specified by:
      forEach in interface Stream<T extends XdmItem>
      Parameters:
      action - the action to be performed on each item
    • forEachOrdered Link icon

      public void forEachOrdered(Consumer<? super T> action)
      Performs a given action once for each item of the stream, in the order in which the items appear
      Specified by:
      forEachOrdered in interface Stream<T extends XdmItem>
      Parameters:
      action - the action to be performed on each item
    • toArray Link icon

      public Object[] toArray()
      Returns an array containing the items in this stream
      Specified by:
      toArray in interface Stream<T extends XdmItem>
      Returns:
      an array containing all the items in the stream
    • toArray Link icon

      public <A> A[] toArray(IntFunction<A[]> generator)
      Returns an array containing the items in this stream, using a supplied function to generate the array; this allows the type of the returned array to be controlled.
      Specified by:
      toArray in interface Stream<T extends XdmItem>
      Parameters:
      generator - a function that takes an integer as argument and returns an array of the given length
      Returns:
      an array containing all the items in the stream; the type of the array is determined by the generator function
    • reduce Link icon

      public T reduce(T identity, BinaryOperator<T> accumulator)
      Performs a reduction or fold operation on the items in the stream.

      For example, given a sequence of elements of the form <change year="2020" rise="1.03"/> the accumulated rise over a number of years may be computed as

      
          changes.stream().select(attribute("rise"))
            .map(a->a.getTypedValue().getDoubleValue())
            .reduce(1, (x, y) -> x*y)
       
      Specified by:
      reduce in interface Stream<T extends XdmItem>
      Parameters:
      identity - an initial value of an accumulator variable. This must be an identity value for the supplied accumulator function (so if F is the accumulator function, F(identity, V) returns V for any value of V).
      accumulator - the accumulator function: this takes the old value of the accumulator variable and the current item from the stream as arguments, and returns a new value for the accumulator variable. This function must be associative, that is, F(A, F(B, C)) must always give the same result as F(F(A, B), C))
      Returns:
      the final value of the accumulator variable after all items have been processed.
    • reduce Link icon

      public Optional<T> reduce(BinaryOperator<T> accumulator)
      Specified by:
      reduce in interface Stream<T extends XdmItem>
      Parameters:
      accumulator - an associative, stateless, non-interfering value operating on two items in the stream
      Returns:
      the result of the delegated call
    • reduce Link icon

      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 Link icon

      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 Link icon

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

      public Optional<T> min(Comparator<? super T> comparator)
      Returns the minimum item in the stream of items, comparing them using the supplied Comparator.
      Specified by:
      min in interface Stream<T extends XdmItem>
      Parameters:
      comparator - the comparator to be used for comparing items
      Returns:
      the minimum value, or Optional.empty() if the stream is empty.
    • max Link icon

      public Optional<T> max(Comparator<? super T> comparator)
      Returns the maximum item in the stream of items, comparing them using the supplied Comparator.
      Specified by:
      max in interface Stream<T extends XdmItem>
      Parameters:
      comparator - the comparator to be used for comparing items
      Returns:
      the maximum value, or Optional.empty() if the stream is empty.
    • count Link icon

      public long count()
      Returns the number of items in the stream
      Specified by:
      count in interface Stream<T extends XdmItem>
      Returns:
      the length of the stream
    • anyMatch Link icon

      public boolean anyMatch(Predicate<? super T> predicate)
      Returns true if any item in the stream matches a supplied predicate
      Specified by:
      anyMatch in interface Stream<T extends XdmItem>
      Parameters:
      predicate - the predicate to be applied to each item
      Returns:
      true if an item is found for which the predicate function returns true
    • allMatch Link icon

      public boolean allMatch(Predicate<? super T> predicate)
      Returns true if every item in the stream matches a supplied predicate
      Specified by:
      allMatch in interface Stream<T extends XdmItem>
      Parameters:
      predicate - the predicate to be applied to each item
      Returns:
      true if the predicate function returns true for every item in the stream
    • noneMatch Link icon

      public boolean noneMatch(Predicate<? super T> predicate)
      Returns true if no item in the stream matches a supplied predicate
      Specified by:
      noneMatch in interface Stream<T extends XdmItem>
      Parameters:
      predicate - the predicate to be applied to each item
      Returns:
      true if the predicate function returns false for every item in the stream
    • findFirst Link icon

      public Optional<T> findFirst()
      Returns the first item in the stream, or Optional.empty() if the stream is empty
      Specified by:
      findFirst in interface Stream<T extends XdmItem>
      Returns:
      the first item in the stream
    • findAny Link icon

      public Optional<T> findAny()
      Returns an item in the stream, chosen arbitrarily, or Optional.empty() if the stream is empty
      Specified by:
      findAny in interface Stream<T extends XdmItem>
      Returns:
      an arbitrary item from the stream
    • iterator Link icon

      public Iterator<T> iterator()
      Get an iterator over the items in the stream
      Specified by:
      iterator in interface BaseStream<T extends XdmItem,Stream<T extends XdmItem>>
      Returns:
      an iterator over all the items, in order
    • spliterator Link icon

      public Spliterator<T> spliterator()
      Get a Spliterator over the items in the stream
      Specified by:
      spliterator in interface BaseStream<T extends XdmItem,Stream<T extends XdmItem>>
      Returns:
      a Spliterator over all the items, in order
    • isParallel Link icon

      public boolean isParallel()
      Ask whether this stream will be evaluated in parallel
      Specified by:
      isParallel in interface BaseStream<T extends XdmItem,Stream<T extends XdmItem>>
      Returns:
      true if execution is in parallel
    • sequential Link icon

      public Stream<T> sequential()
      Returns an equivalent stream that will be evaluated sequentially
      Specified by:
      sequential in interface BaseStream<T extends XdmItem,Stream<T extends XdmItem>>
      Returns:
      an equivalent sequential stream
    • parallel Link icon

      public Stream<T> parallel()
      Returns an equivalent stream that will (where possible and appropriate) be evaluated in parallel
      Specified by:
      parallel in interface BaseStream<T extends XdmItem,Stream<T extends XdmItem>>
      Returns:
      an equivalent parallel stream
    • unordered Link icon

      public Stream<T> unordered()
      Returns an equivalent stream that offers no guarantee of retaining the order of items
      Specified by:
      unordered in interface BaseStream<T extends XdmItem,Stream<T extends XdmItem>>
      Returns:
      an equivalent stream without guaranteed order
    • onClose Link icon

      public Stream<T> onClose(Runnable closeHandler)
      Returns an equivalent stream with a specified handler to be called when the stream is exhausted
      Specified by:
      onClose in interface BaseStream<T extends XdmItem,Stream<T extends XdmItem>>
      Parameters:
      closeHandler - the code to be executed when the stream is closed
      Returns:
      a stream that returns the same items, augmented with a close handler
    • close Link icon

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

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

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

      public List<XdmNode> asListOfNodes()
      Return the result of the stream as a List<XdmNode>. This is a terminal operation.

      Node: the method makes it convenient to process the contents of a stream using a for-each loop, for example:

      
           for (XdmNode n : start.select(child().where(isText())).asList()) {
                process(n)
           }
       

      A more idiomatic style, however, is to use the forEach(java.util.function.Consumer<? super T>) method:

      start.select(child().where(isText())).forEach(n -> process(n))

      Returns:
      the list of nodes delivered by the stream
      Throws:
      ClassCastException - if the stream contains an item that is not a node
    • asOptionalNode Link icon

      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 Link icon

      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 Link icon

      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 Link icon

      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 Link icon

      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 Link icon

      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 Link icon

      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 Link icon

      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()
      Returns:
      a stream containing the first item in this stream
    • firstItem Link icon

      public T firstItem()
      Return the first item of this stream, if there is one, discarding the remainder; return null if the stream is empty. This is a short-circuiting operation similar to findFirst()
      Returns:
      the first item in this stream, or null if the stream is empty.
    • exists Link icon

      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 Link icon

      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.
    • lastItem Link icon

      public T lastItem()
      Return the last item of this stream, if there is one, discarding the remainder; return null if the stream is empty. This is a short-circuiting operation similar to lastItem().
      Returns:
      the last item in the stream, or null if the input is empty.
    • at Link icon

      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 Link icon

      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 Link icon

      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 Link icon

      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.