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.

Instances of this interface are immutable. Methods which return a `PublisherBuilder` will return a new instance.

See Also:
  `ReactiveStreams`

### Method Summary

All Methods Instance Methods Abstract Methods
`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<Void>` `cancel()` Cancels the stream as soon as it is run.
`<R,A> CompletionRunner<R>` `collect(Collector<? super T,A,R> collector)` Collect the elements emitted by this stream using the given `Collector`.
`<R> CompletionRunner<R>` `collect(Supplier<R> supplier, BiConsumer<R,? super T> accumulator)` Collect the elements emitted by this stream using a `Collector` built from the given `supplier` and `accumulator`.
`PublisherBuilder<T>` `distinct()` Creates a stream consisting of the distinct elements (according to `Object.equals(Object)`) of this stream.
`PublisherBuilder<T>` `dropWhile(Predicate<? super T> predicate)` Drop the longest prefix of elements from this stream that satisfy the given `predicate`.
`PublisherBuilder<T>` `filter(Predicate<? super T> predicate)` Filter elements emitted by this publisher using the given `Predicate`.
`CompletionRunner<Optional<T>>` `findFirst()` Find the first element emitted by the `Publisher`, and return it in a `CompletionStage`.
`<S> PublisherBuilder<S>` `flatMap(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(Function<? super T,? extends 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(Function<? super T,? extends 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(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<Void>` `forEach(Consumer<? super T> action)` Performs an action for each element on this stream.
`CompletionRunner<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(Function<? super T,? extends R> mapper)` Map the elements emitted by this stream using the `mapper` function.
`PublisherBuilder<T>` `onComplete(Runnable action)` Returns a stream containing all the elements from this stream, additionally performing the provided action when this stream completes.
`PublisherBuilder<T>` `onError(Consumer<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(Function<Throwable,? extends T> errorHandler)` Returns a stream containing all the elements from this stream.
`PublisherBuilder<T>` `onErrorResumeWith(Function<Throwable,? extends PublisherBuilder<? extends T>> errorHandler)` Returns a stream containing all the elements from this stream.
`PublisherBuilder<T>` `onErrorResumeWithRsPublisher(Function<Throwable,? extends org.reactivestreams.Publisher<? extends T>> errorHandler)` Returns a stream containing all the elements from this stream.
`PublisherBuilder<T>` `onTerminate(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(Consumer<? super T> consumer)` Returns a stream containing all the elements from this stream, additionally performing the provided action on each element.
`CompletionRunner<Optional<T>>` `reduce(BinaryOperator<T> accumulator)` Perform a reduction on the elements of this stream, using the provided accumulation function.
`CompletionRunner<T>` `reduce(T identity, 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(Predicate<? super T> predicate)` Take the longest prefix of elements from this stream that satisfy the given `predicate`.
`CompletionRunner<Void>` `to(org.reactivestreams.Subscriber<? super T> subscriber)` Connect the outlet of the `Publisher` built by this builder to the given `Subscriber`.
`<R> CompletionRunner<R>` `to(SubscriberBuilder<? super T,? extends R> subscriber)` Connect the outlet of this stream to the given `SubscriberBuilder` graph.
`CompletionRunner<List<T>>` `toList()` Collect the elements emitted by this stream into a `List`.
`<R> PublisherBuilder<R>` `via(org.reactivestreams.Processor<? super T,? extends R> processor)` Connect the outlet of this stream to the given `Processor`.
`<R> PublisherBuilder<R>` `via(ProcessorBuilder<? super T,? extends R> processor)` Connect the outlet of the `Publisher` built by this builder to the given `ProcessorBuilder`.

### Method Detail

#### map

    <R> PublisherBuilder<R> map(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(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(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(Function<? super T,? extends 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. If the element is `null`, this operation should be failed with a `NullPointerException`.

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(Function<? super T,? extends 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(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(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(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(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(Consumer<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(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(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<Void> forEach(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<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<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,
                               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<Optional<T>> reduce(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<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(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(Supplier<R> supplier,
                                    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<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(Function<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(Function<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(Function<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<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`. This method is designed for the use case where you have to supply a paritcular `ReactiveStreamsEngine`. Most cases you should use `buildRs()`.

Parameters:
  `engine` - The engine to run the stream with.
Returns:
  A `Publisher` that will run this stream.