Package org.eclipse.microprofile.reactive.streams.operators

Interface PublisherBuilder<T>

Type Parameters:

T - The type of the elements that the publisher emits.

All Superinterfaces:

ConnectingOperators<T>, ConsumingOperators<T>, ErrorHandlingOperators<T>, FilteringOperators<T>, PeekingOperators<T>, TransformingOperators<T>

public interface PublisherBuilder<T>
extends TransformingOperators<T>, FilteringOperators<T>, PeekingOperators<T>, ConsumingOperators<T>, ErrorHandlingOperators<T>, ConnectingOperators<T>

A builder for a Publisher.

The documentation for each operator uses marble diagrams to visualize how the operator functions. Each element flowing in and out of the stream is represented as a coloured marble that has a value, with the operator applying some transformation or some side effect, termination and error signals potentially being passed, and for operators that subscribe to the stream, an output value being redeemed at the end.

Below is an example diagram labelling all the parts of the stream.

See Also:

ReactiveStreams

Method Summary

Modifier and Type	Method	Description
org.reactivestreams.Publisher<T>	buildRs()	Build this stream, using the first ReactiveStreamsEngine found by the ServiceLoader.
org.reactivestreams.Publisher<T>	buildRs(ReactiveStreamsEngine engine)	Build this stream, using the supplied ReactiveStreamsEngine.
CompletionRunner<java.lang.Void>	cancel()	Cancels the stream as soon as it is run.
<R> CompletionRunner<R>	collect(java.util.function.Supplier<R> supplier, java.util.function.BiConsumer<R,? super T> accumulator)	Collect the elements emitted by this stream using a Collector built from the given supplier and accumulator.
<R,A> CompletionRunner<R>	collect(java.util.stream.Collector<? super T,A,R> collector)	Collect the elements emitted by this stream using the given Collector.
PublisherBuilder<T>	distinct()	Creates a stream consisting of the distinct elements (according to Object.equals(Object)) of this stream.
PublisherBuilder<T>	dropWhile(java.util.function.Predicate<? super T> predicate)	Drop the longest prefix of elements from this stream that satisfy the given predicate.
PublisherBuilder<T>	filter(java.util.function.Predicate<? super T> predicate)	Filter elements emitted by this publisher using the given Predicate.
CompletionRunner<java.util.Optional<T>>	findFirst()	Find the first element emitted by the Publisher, and return it in a CompletionStage.
<S> PublisherBuilder<S>	flatMap(java.util.function.Function<? super T,? extends PublisherBuilder<? extends S>> mapper)	Map the elements to publishers, and flatten so that the elements emitted by publishers produced by the mapper function are emitted from this stream.
<S> PublisherBuilder<S>	flatMapCompletionStage(java.util.function.Function<? super T,? extends java.util.concurrent.CompletionStage<? extends S>> mapper)	Map the elements to CompletionStage, and flatten so that the elements the values redeemed by each CompletionStage are emitted from this stream.
<S> PublisherBuilder<S>	flatMapIterable(java.util.function.Function<? super T,? extends java.lang.Iterable<? extends S>> mapper)	Map the elements to Iterable's, and flatten so that the elements contained in each iterable are emitted by this stream.
<S> PublisherBuilder<S>	flatMapRsPublisher(java.util.function.Function<? super T,? extends org.reactivestreams.Publisher<? extends S>> mapper)	Map the elements to publishers, and flatten so that the elements emitted by publishers produced by the mapper function are emitted from this stream.
CompletionRunner<java.lang.Void>	forEach(java.util.function.Consumer<? super T> action)	Performs an action for each element on this stream.
CompletionRunner<java.lang.Void>	ignore()	Ignores each element of this stream.
PublisherBuilder<T>	limit(long maxSize)	Truncate this stream, ensuring the stream is no longer than maxSize elements in length.
<R> PublisherBuilder<R>	map(java.util.function.Function<? super T,? extends R> mapper)	Map the elements emitted by this stream using the mapper function.
PublisherBuilder<T>	onComplete(java.lang.Runnable action)	Returns a stream containing all the elements from this stream, additionally performing the provided action when this stream completes.
PublisherBuilder<T>	onError(java.util.function.Consumer<java.lang.Throwable> errorHandler)	Returns a stream containing all the elements from this stream, additionally performing the provided action if this stream conveys an error.
PublisherBuilder<T>	onErrorResume(java.util.function.Function<java.lang.Throwable,? extends T> errorHandler)	Returns a stream containing all the elements from this stream.
PublisherBuilder<T>	onErrorResumeWith(java.util.function.Function<java.lang.Throwable,? extends PublisherBuilder<? extends T>> errorHandler)	Returns a stream containing all the elements from this stream.
PublisherBuilder<T>	onErrorResumeWithRsPublisher(java.util.function.Function<java.lang.Throwable,? extends org.reactivestreams.Publisher<? extends T>> errorHandler)	Returns a stream containing all the elements from this stream.
PublisherBuilder<T>	onTerminate(java.lang.Runnable action)	Returns a stream containing all the elements from this stream, additionally performing the provided action when this stream completes or failed.
PublisherBuilder<T>	peek(java.util.function.Consumer<? super T> consumer)	Returns a stream containing all the elements from this stream, additionally performing the provided action on each element.
CompletionRunner<java.util.Optional<T>>	reduce(java.util.function.BinaryOperator<T> accumulator)	Perform a reduction on the elements of this stream, using the provided accumulation function.
CompletionRunner<T>	reduce(T identity, java.util.function.BinaryOperator<T> accumulator)	Perform a reduction on the elements of this stream, using the provided identity value and the accumulation function.
PublisherBuilder<T>	skip(long n)	Discard the first n of this stream.
PublisherBuilder<T>	takeWhile(java.util.function.Predicate<? super T> predicate)	Take the longest prefix of elements from this stream that satisfy the given predicate.
<R> CompletionRunner<R>	to(SubscriberBuilder<? super T,? extends R> subscriber)	Connect the outlet of this stream to the given SubscriberBuilder graph.
CompletionRunner<java.lang.Void>	to(org.reactivestreams.Subscriber<? super T> subscriber)	Connect the outlet of the Publisher built by this builder to the given Subscriber.
CompletionRunner<java.util.List<T>>	toList()	Collect the elements emitted by this stream into a List.
<R> PublisherBuilder<R>	via(ProcessorBuilder<? super T,? extends R> processor)	Connect the outlet of the Publisher built by this builder to the given ProcessorBuilder.
<R> PublisherBuilder<R>	via(org.reactivestreams.Processor<? super T,? extends R> processor)	Connect the outlet of this stream to the given Processor.

Method Detail

map

<R> PublisherBuilder<R> map(java.util.function.Function<? super T,? extends R> mapper)

Map the elements emitted by this stream using the mapper function.

Specified by:

map in interface TransformingOperators<T>

Type Parameters:

R - The type of elements that the mapper function emits.

Parameters:

mapper - The function to use to map the elements.

Returns:

A new stream builder that emits the mapped elements.

flatMap

<S> PublisherBuilder<S> flatMap(java.util.function.Function<? super T,? extends PublisherBuilder<? extends S>> mapper)

Map the elements to publishers, and flatten so that the elements emitted by publishers produced by the mapper function are emitted from this stream.

This method operates on one publisher at a time. The result is a concatenation of elements emitted from all the publishers produced by the mapper function.

Unlike TransformingOperators.flatMapRsPublisher(Function)}, the mapper function returns a org.eclipse.microprofile.reactive.streams type instead of an org.reactivestreams type.

Specified by:

flatMap in interface TransformingOperators<T>

Type Parameters:

S - The type of the elements emitted from the new stream.

Parameters:

mapper - The mapper function.

Returns:

A new stream builder.

flatMapRsPublisher

<S> PublisherBuilder<S> flatMapRsPublisher(java.util.function.Function<? super T,? extends org.reactivestreams.Publisher<? extends S>> mapper)

Map the elements to publishers, and flatten so that the elements emitted by publishers produced by the mapper function are emitted from this stream.

This method operates on one publisher at a time. The result is a concatenation of elements emitted from all the publishers produced by the mapper function.

Unlike TransformingOperators.flatMap(Function), the mapper function returns a org.eclipse.microprofile.reactive.streams builder instead of an org.reactivestreams type.

Specified by:

flatMapRsPublisher in interface TransformingOperators<T>

Type Parameters:

S - The type of the elements emitted from the new stream.

Parameters:

mapper - The mapper function.

Returns:

A new stream builder.

flatMapCompletionStage

<S> PublisherBuilder<S> flatMapCompletionStage(java.util.function.Function<? super T,? extends java.util.concurrent.CompletionStage<? extends S>> mapper)

Map the elements to CompletionStage, and flatten so that the elements the values redeemed by each CompletionStage are emitted from this stream.

This method only works with one element at a time. When an element is received, the mapper function is executed, and the next element is not consumed or passed to the mapper function until the previous CompletionStage is redeemed. Hence this method also guarantees that ordering of the stream is maintained.

Specified by:

flatMapCompletionStage in interface TransformingOperators<T>

Type Parameters:

S - The type of the elements emitted from the new stream.

Parameters:

mapper - The mapper function.

Returns:

A new stream builder.

flatMapIterable

<S> PublisherBuilder<S> flatMapIterable(java.util.function.Function<? super T,? extends java.lang.Iterable<? extends S>> mapper)

Map the elements to Iterable's, and flatten so that the elements contained in each iterable are emitted by this stream.

This method operates on one iterable at a time. The result is a concatenation of elements contain in all the iterables returned by the mapper function.

Specified by:

flatMapIterable in interface TransformingOperators<T>

Type Parameters:

S - The type of the elements emitted from the new stream.

Parameters:

mapper - The mapper function.

Returns:

A new stream builder.

filter

PublisherBuilder<T> filter(java.util.function.Predicate<? super T> predicate)

Filter elements emitted by this publisher using the given Predicate.

Any elements that return true when passed to the Predicate will be emitted, all other elements will be dropped.

Specified by:

filter in interface FilteringOperators<T>

Parameters:

predicate - The predicate to apply to each element.

Returns:

A new stream builder.

distinct

PublisherBuilder<T> distinct()

Creates a stream consisting of the distinct elements (according to Object.equals(Object)) of this stream.

Specified by:

distinct in interface FilteringOperators<T>

Returns:

A new stream builder emitting the distinct elements from this stream.

limit

PublisherBuilder<T> limit(long maxSize)

Truncate this stream, ensuring the stream is no longer than maxSize elements in length.

If maxSize is reached, the stream will be completed, and upstream will be cancelled. Completion of the stream will occur immediately when the element that satisfies the maxSize is received.

Specified by:

limit in interface FilteringOperators<T>

Parameters:

maxSize - The maximum size of the returned stream.

Returns:

A new stream builder.

skip

PublisherBuilder<T> skip(long n)

Discard the first n of this stream. If this stream contains fewer than n elements, this stream will effectively be an empty stream.

Specified by:

skip in interface FilteringOperators<T>

Parameters:

n - The number of elements to discard.

Returns:

A new stream builder.

takeWhile

PublisherBuilder<T> takeWhile(java.util.function.Predicate<? super T> predicate)

Take the longest prefix of elements from this stream that satisfy the given predicate.

When the predicate returns false, the stream will be completed, and upstream will be cancelled.

Specified by:

takeWhile in interface FilteringOperators<T>

Parameters:

predicate - The predicate.

Returns:

A new stream builder.

dropWhile

PublisherBuilder<T> dropWhile(java.util.function.Predicate<? super T> predicate)

Drop the longest prefix of elements from this stream that satisfy the given predicate.

As long as the predicate returns true, no elements will be emitted from this stream. Once the first element is encountered for which the predicate returns false, all subsequent elements will be emitted, and the predicate will no longer be invoked.

Specified by:

dropWhile in interface FilteringOperators<T>

Parameters:

predicate - The predicate.

Returns:

A new stream builder.

peek

PublisherBuilder<T> peek(java.util.function.Consumer<? super T> consumer)

Returns a stream containing all the elements from this stream, additionally performing the provided action on each element.

Specified by:

peek in interface PeekingOperators<T>

Parameters:

consumer - The function called for every element.

Returns:

A new stream builder that consumes elements of type T and emits the same elements. In between, the given function is called for each element.

onError

PublisherBuilder<T> onError(java.util.function.Consumer<java.lang.Throwable> errorHandler)

Returns a stream containing all the elements from this stream, additionally performing the provided action if this stream conveys an error. The given consumer is called with the failure.

Specified by:

onError in interface PeekingOperators<T>

Parameters:

errorHandler - The function called with the failure.

Returns:

A new stream builder that consumes elements of type T and emits the same elements. If the stream conveys a failure, the given error handler is called.

onTerminate

PublisherBuilder<T> onTerminate(java.lang.Runnable action)

Returns a stream containing all the elements from this stream, additionally performing the provided action when this stream completes or failed. The given action does not know if the stream failed or completed. If you need to distinguish use PeekingOperators.onError(Consumer) and PeekingOperators.onComplete(Runnable). In addition, the action is called if the stream is cancelled downstream.

Specified by:

onTerminate in interface PeekingOperators<T>

Parameters:

action - The function called when the stream completes or failed.

Returns:

A new stream builder that consumes elements of type T and emits the same elements. The given action is called when the stream completes or fails.

onComplete

PublisherBuilder<T> onComplete(java.lang.Runnable action)

Returns a stream containing all the elements from this stream, additionally performing the provided action when this stream completes.

Specified by:

onComplete in interface PeekingOperators<T>

Parameters:

action - The function called when the stream completes.

Returns:

A new stream builder that consumes elements of type T and emits the same elements. The given action is called when the stream completes.

forEach

CompletionRunner<java.lang.Void> forEach(java.util.function.Consumer<? super T> action)

Performs an action for each element on this stream.

The returned CompletionStage will be redeemed when the stream completes, either successfully if the stream completes normally, or with an error if the stream completes with an error or if the action throws an exception.

Specified by:

forEach in interface ConsumingOperators<T>

Parameters:

action - The action.

Returns:

A new CompletionRunner that can be used to run the stream.

ignore

CompletionRunner<java.lang.Void> ignore()

Ignores each element of this stream.

The returned CompletionStage will be redeemed when the stream completes, either successfully if the stream completes normally, or with an error if the stream completes with an error or if the action throws an exception.

Specified by:

ignore in interface ConsumingOperators<T>

Returns:

A new CompletionRunner that can be used to run the stream.

cancel

CompletionRunner<java.lang.Void> cancel()

Cancels the stream as soon as it is run.

The returned CompletionStage will be immediately redeemed as soon as the stream is run.

Specified by:

cancel in interface ConsumingOperators<T>

Returns:

A new CompletionRunner that can be used to run the stream.

reduce

CompletionRunner<T> reduce(T identity,
                           java.util.function.BinaryOperator<T> accumulator)

Perform a reduction on the elements of this stream, using the provided identity value and the accumulation function.

The result of the reduction is returned in the CompletionStage.

Specified by:

reduce in interface ConsumingOperators<T>

Parameters:

identity - The identity value.

accumulator - The accumulator function.

Returns:

A new CompletionRunner that can be used to run the stream.

reduce

CompletionRunner<java.util.Optional<T>> reduce(java.util.function.BinaryOperator<T> accumulator)

Perform a reduction on the elements of this stream, using the provided accumulation function.

The result of the reduction is returned as an Optional<T> in the CompletionStage. If there are no elements in this stream, empty will be returned.

Specified by:

reduce in interface ConsumingOperators<T>

Parameters:

accumulator - The accumulator function.

Returns:

A new CompletionRunner that can be used to run the stream.

findFirst

CompletionRunner<java.util.Optional<T>> findFirst()

Find the first element emitted by the Publisher, and return it in a CompletionStage.

If the stream is completed before a single element is emitted, then Optional.empty() will be emitted.

Specified by:

findFirst in interface ConsumingOperators<T>

Returns:

A new CompletionRunner that can be used to run the stream.

collect

<R,A> CompletionRunner<R> collect(java.util.stream.Collector<? super T,A,R> collector)

Collect the elements emitted by this stream using the given Collector.

Since Reactive Streams are intrinsically sequential, only the accumulator of the collector will be used, the combiner will not be used.

Specified by:

collect in interface ConsumingOperators<T>

Type Parameters:

R - The result of the collector.

A - The accumulator type.

Parameters:

collector - The collector to collect the elements.

Returns:

A new CompletionRunner that can be used to run the stream, R is the result type of the collector's reduction operation.

collect

<R> CompletionRunner<R> collect(java.util.function.Supplier<R> supplier,
                                java.util.function.BiConsumer<R,? super T> accumulator)

Collect the elements emitted by this stream using a Collector built from the given supplier and accumulator.

Since Reactive Streams are intrinsically sequential, the combiner will not be used. This is why this method does not accept a combiner method.

Specified by:

collect in interface ConsumingOperators<T>

Type Parameters:

R - The result of the collector.

Parameters:

supplier - a function that creates a new result container. It creates objects of type <A>.

accumulator - an associative, non-interfering, stateless function for incorporating an additional element into a result

Returns:

A new CompletionRunner that can be used to run the stream which emits the collected result.

toList

CompletionRunner<java.util.List<T>> toList()

Collect the elements emitted by this stream into a List.

Specified by:

toList in interface ConsumingOperators<T>

Returns:

A new CompletionRunner that can be used to run the stream that emits the list.

onErrorResume

PublisherBuilder<T> onErrorResume(java.util.function.Function<java.lang.Throwable,? extends T> errorHandler)

Returns a stream containing all the elements from this stream. Additionally, in the case of failure, it invokes the given function and emits the result as final event of the stream.

By default, when a stream encounters an error that prevents it from emitting the expected item to its subscriber, the stream invokes its subscriber's onError method, and then terminates without invoking any more of its subscriber's methods. This operator changes this behavior. If the current stream encounters an error, instead of invoking its subscriber's onError method, it will instead emit the return value of the passed function. This operator prevents errors from propagating or to supply fallback data should errors be encountered.

Specified by:

onErrorResume in interface ErrorHandlingOperators<T>

Parameters:

errorHandler - the function returning the value that needs to be emitting instead of the error. The function must not return null.

Returns:

The new stream builder.

onErrorResumeWith

PublisherBuilder<T> onErrorResumeWith(java.util.function.Function<java.lang.Throwable,? extends PublisherBuilder<? extends T>> errorHandler)

Returns a stream containing all the elements from this stream. Additionally, in the case of failure, it invokes the given function and emits the elements from the returned PublisherBuilder instead.

By default, when a stream encounters an error that prevents it from emitting the expected item to its subscriber, the stream invokes its subscriber's onError method, and then terminates without invoking any more of its subscriber's methods. This operator changes this behavior. If the current stream encounters an error, instead of invoking its subscriber's onError method, it will instead relinquish control to the PublisherBuilder returned from the given function, which invokes the subscriber's onNext method if it is able to do so. The subscriber's original Subscription is used to control the flow of elements both before and after any error occurring. In such a case, because no publisher necessarily invokes onError on the stream's subscriber, it may never know that an error happened.

Specified by:

onErrorResumeWith in interface ErrorHandlingOperators<T>

Parameters:

errorHandler - the function returning the stream that needs to be emitting instead of the error. The function must not return null.

Returns:

The new stream builder.

onErrorResumeWithRsPublisher

PublisherBuilder<T> onErrorResumeWithRsPublisher(java.util.function.Function<java.lang.Throwable,? extends org.reactivestreams.Publisher<? extends T>> errorHandler)

Returns a stream containing all the elements from this stream. Additionally, in the case of failure, it invokes the given function and emits the elements from the returned Publisher instead.

By default, when a stream encounters an error that prevents it from emitting the expected item to its subscriber, the stream invokes its subscriber's onError method, and then terminates without invoking any more of its subscriber's methods. This operator changes this behavior. If the current stream encounters an error, instead of invoking its subscriber's onError method, the subscriber will be fed from the Publisher returned from the given function, and the subscriber's onNext method is called as the returned Publisher publishes. The subscriber's original Subscription is used to control the flow of both the original and the onError Publishers' elements. In such a case, because no publisher necessarily invokes onError, the subscriber may never know that an error happened.

Specified by:

onErrorResumeWithRsPublisher in interface ErrorHandlingOperators<T>

Parameters:

errorHandler - the function returning the stream that need to be emitting instead of the error. The function must not return null.

Returns:

The new stream builder.

to

CompletionRunner<java.lang.Void> to(org.reactivestreams.Subscriber<? super T> subscriber)

Connect the outlet of the Publisher built by this builder to the given Subscriber. The Reactive Streams specification states that a subscriber should cancel any new stream subscription it receives if it already has an active subscription. The returned result of this method is a stream that creates a subscription for the subscriber passed in, so the resulting stream should only be run once. For the same reason, the subscriber passed in should not have any active subscriptions and should not be used in more than one call to this method.

Specified by:

to in interface ConnectingOperators<T>

Parameters:

subscriber - The subscriber to connect.

Returns:

A new CompletionRunner that can be used to run the composed stream.

to

<R> CompletionRunner<R> to(SubscriberBuilder<? super T,? extends R> subscriber)

Connect the outlet of this stream to the given SubscriberBuilder graph. The Reactive Streams specification states that a subscriber should cancel any new stream subscription it receives if it already has an active subscription. For this reason, a subscriber builder, particularly any that represents a graph that includes a user supplied Subscriber or Processor stage, should not be used in the creation of more than one stream instance.

Specified by:

to in interface ConnectingOperators<T>

Parameters:

subscriber - The subscriber builder to connect.

Returns:

A new CompletionRunner that can be used to run the composed stream.

via

<R> PublisherBuilder<R> via(ProcessorBuilder<? super T,? extends R> processor)

Connect the outlet of the Publisher built by this builder to the given ProcessorBuilder. The Reactive Streams specification states that a subscribing processor should cancel any new stream subscription it receives if it already has an active subscription. For this reason, a processor builder, particularly any that represents a graph that includes a user supplied Processor stage, should not be used in the creation of more than one stream instance.

Specified by:

via in interface ConnectingOperators<T>

Parameters:

processor - The processor builder to connect.

Returns:

A stream builder that represents the passed in processor's outlet.

via

<R> PublisherBuilder<R> via(org.reactivestreams.Processor<? super T,? extends R> processor)

Connect the outlet of this stream to the given Processor. The Reactive Streams specification states that a subscribing processor should cancel any new stream subscription it receives if it already has an active subscription. The returned result of this method is a stream that creates a subscription for the processor passed in, so the resulting stream should only be run once. For the same reason, the processor passed in should not have any active subscriptions and should not be used in more than one call to this method.

Specified by:

via in interface ConnectingOperators<T>

Parameters:

processor - The processor builder to connect.

Returns:

A stream builder that represents the passed in processor builder's outlet.

buildRs

org.reactivestreams.Publisher<T> buildRs()

Build this stream, using the first ReactiveStreamsEngine found by the ServiceLoader.

Returns:

A Publisher that will run this stream.

buildRs

org.reactivestreams.Publisher<T> buildRs(ReactiveStreamsEngine engine)

Build this stream, using the supplied ReactiveStreamsEngine.

Parameters:

engine - The engine to run the stream with.

Returns:

A Publisher that will run this stream.