net.sf.saxon.s9api.streams

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.

Nested Class Summary

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

Stream.Builder<T>

Field Summary

Fields

Modifier and Type	Field and Description
(package private) Stream<T>	base

Constructor Summary

Constructors

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

Method Summary

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

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

builder, concat, empty, generate, iterate, of, of

Field Detail

base

Stream<T extends XdmItem> base

Constructor Detail

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 Detail

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.