Package io.servicetalk.concurrent.api

Class Publisher<T>

java.lang.Object

io.servicetalk.concurrent.api.Publisher<T>

Type Parameters:

T - Type of items emitted.

Direct Known Subclasses:

GroupedPublisher, SubscribablePublisher

public abstract class Publisher<T>
extends Object

An asynchronous computation that produces 0, 1 or more elements and may or may not terminate successfully or with an error.

How to subscribe?

This class does not provide a way to subscribe using a PublisherSource.Subscriber as such calls are ambiguous about the intent whether the subscribe is part of the same source (a.k.a an operator) or it is a terminal subscribe. If it is required to subscribe to a source, then a source adapter can be used to convert to a PublisherSource.

Constructor Summary

Constructors

Modifier	Constructor	Description
protected	Publisher()	New instance.

Method Summary

Modifier and Type	Method	Description
final Publisher<T>	afterCancel(Runnable onCancel)	Invokes the onCancel Runnable argument after Cancellable.cancel() is called for PublisherSource.Subscriptions of the returned Publisher.
final Publisher<T>	afterFinally(TerminalSignalConsumer doFinally)	Invokes the corresponding method on afterFinally TerminalSignalConsumer argument after any of the following terminal methods are called: PublisherSource.Subscriber.onComplete() - invokes TerminalSignalConsumer.onComplete() PublisherSource.Subscriber.onError(Throwable) - invokes TerminalSignalConsumer.onError(Throwable) Cancellable.cancel() - invokes TerminalSignalConsumer.cancel() for PublisherSource.Subscriptions/PublisherSource.Subscribers of the returned Publisher.
final Publisher<T>	afterFinally(Runnable doFinally)	Invokes the afterFinally Runnable argument after any of the following terminal methods are called: PublisherSource.Subscriber.onComplete() PublisherSource.Subscriber.onError(Throwable) Cancellable.cancel() for PublisherSource.Subscriptions/PublisherSource.Subscribers of the returned Publisher.
final Publisher<T>	afterOnComplete(Runnable onComplete)	Invokes the onComplete Runnable argument after PublisherSource.Subscriber.onComplete() is called for PublisherSource.Subscribers of the returned Publisher.
final Publisher<T>	afterOnError(Consumer<Throwable> onError)	Invokes the onError Consumer argument after PublisherSource.Subscriber.onError(Throwable) is called for PublisherSource.Subscribers of the returned Publisher.
final Publisher<T>	afterOnNext(Consumer<? super T> onNext)	Invokes the onNext Consumer argument after PublisherSource.Subscriber.onNext(Object) is called for PublisherSource.Subscribers of the returned Publisher.
final Publisher<T>	afterOnSubscribe(Consumer<? super PublisherSource.Subscription> onSubscribe)	Invokes the onSubscribe Consumer argument after PublisherSource.Subscriber.onSubscribe(PublisherSource.Subscription) is called for PublisherSource.Subscribers of the returned Publisher.
final Publisher<T>	afterRequest(LongConsumer onRequest)	Invokes the onRequest LongConsumer argument after PublisherSource.Subscription.request(long) is called for PublisherSource.Subscriptions of the returned Publisher.
final Publisher<T>	afterSubscriber(Supplier<? extends PublisherSource.Subscriber<? super T>> subscriberSupplier)	Creates a new PublisherSource.Subscriber (via the subscriberSupplier argument) for each new subscribe and invokes all the PublisherSource.Subscriber methods after the PublisherSource.Subscribers of the returned Publisher.
final Publisher<T>	afterSubscription(Supplier<? extends PublisherSource.Subscription> subscriptionSupplier)	Creates a new PublisherSource.Subscription (via the subscriptionSupplier argument) for each new subscribe and invokes all the PublisherSource.Subscription methods after the PublisherSource.Subscriptions of the returned Publisher.
final Publisher<T>	beforeCancel(Runnable onCancel)	Invokes the onCancel Runnable argument before Cancellable.cancel() is called for PublisherSource.Subscriptions of the returned Publisher.
final Publisher<T>	beforeFinally(TerminalSignalConsumer doFinally)	Invokes the corresponding method on beforeFinally TerminalSignalConsumer argument before any of the following terminal methods are called: PublisherSource.Subscriber.onComplete() - invokes TerminalSignalConsumer.onComplete() PublisherSource.Subscriber.onError(Throwable) - invokes TerminalSignalConsumer.onError(Throwable) Cancellable.cancel() - invokes TerminalSignalConsumer.cancel() for PublisherSource.Subscriptions/PublisherSource.Subscribers of the returned Publisher.
final Publisher<T>	beforeFinally(Runnable doFinally)	Invokes the beforeFinally Runnable argument before any of the following terminal methods are called: PublisherSource.Subscriber.onComplete() PublisherSource.Subscriber.onError(Throwable) Cancellable.cancel() for PublisherSource.Subscriptions/PublisherSource.Subscribers of the returned Publisher.
final Publisher<T>	beforeOnComplete(Runnable onComplete)	Invokes the onComplete Runnable argument before PublisherSource.Subscriber.onComplete() is called for PublisherSource.Subscribers of the returned Publisher.
final Publisher<T>	beforeOnError(Consumer<Throwable> onError)	Invokes the onError Consumer argument before PublisherSource.Subscriber.onError(Throwable) is called for PublisherSource.Subscribers of the returned Publisher.
final Publisher<T>	beforeOnNext(Consumer<? super T> onNext)	Invokes the onNext Consumer argument before PublisherSource.Subscriber.onNext(Object) is called for PublisherSource.Subscribers of the returned Publisher.
final Publisher<T>	beforeOnSubscribe(Consumer<? super PublisherSource.Subscription> onSubscribe)	Invokes the onSubscribe Consumer argument before PublisherSource.Subscriber.onSubscribe(PublisherSource.Subscription) is called for PublisherSource.Subscribers of the returned Publisher.
final Publisher<T>	beforeRequest(LongConsumer onRequest)	Invokes the onRequest LongConsumer argument before PublisherSource.Subscription.request(long) is called for PublisherSource.Subscriptions of the returned Publisher.
final Publisher<T>	beforeSubscriber(Supplier<? extends PublisherSource.Subscriber<? super T>> subscriberSupplier)	Creates a new PublisherSource.Subscriber (via the subscriberSupplier argument) on each call to subscribe and invokes all the PublisherSource.Subscriber methods before the PublisherSource.Subscribers of the returned Publisher.
final Publisher<T>	beforeSubscription(Supplier<? extends PublisherSource.Subscription> subscriptionSupplier)	Creates a new PublisherSource.Subscription (via the subscriptionSupplier argument) on each call to subscribe and invokes all the PublisherSource.Subscription methods before the PublisherSource.Subscriptions of the returned Publisher.
final <BC extends BufferStrategy.Accumulator<T, B>, B> Publisher<B>	buffer(BufferStrategy<T,BC,B> strategy)	Create a Publisher that buffers items from this Publisher and emit those buffers instead of the individual items.
final <R> Publisher<R>	cast(Class<R> clazz)	Cast this Publisher from type Publisher to type Publisher.
final <R> Single<R>	collect(Supplier<? extends R> resultFactory, BiFunction<? super R,? super T,R> collector)	Collects all items emitted by this Publisher into a single item.
final Completable	completableOrError()	Converts this Publisher to a Completable.
final Publisher<T>	concat(Completable next)	Listens for completion of next Completable after this Publisher terminates successfully.
final Publisher<T>	concat(Publisher<? extends T> next)	Emits items emitted by next Publisher after this Publisher terminates successfully.
final Publisher<T>	concat(Single<? extends T> next)	Listens and emits the result of next Single after this Publisher terminates successfully.
final Publisher<T>	concatPropagateCancel(Completable next)	This method is like concat(Completable) except next will be subscribed to and cancelled if this Publisher is cancelled or terminates with PublisherSource.Subscriber.onError(Throwable).
static <T> Publisher<T>	defer(Supplier<? extends Publisher<? extends T>> publisherSupplier)	Defers creation of a Publisher till it is subscribed.
final Publisher<T>	distinct()	Only emits distinct signals observed by this Publisher.
static <T> Publisher<T>	empty()	Creates a new Publisher that completes when subscribed without emitting any item to its PublisherSource.Subscriber.
static <T> Publisher<T>	failed(Throwable cause)	Creates a new Publisher that terminates its PublisherSource.Subscriber with an error without emitting any item to it.
final Publisher<T>	filter(Predicate<? super T> predicate)	Filters items emitted by this Publisher.
final Single<T>	firstOrElse(Supplier<T> defaultValueSupplier)	Converts this Publisher to a Single.
final Single<T>	firstOrError()	Converts this Publisher to a Single and ensures that it emits exactly a single element before completion.
final Completable	flatMapCompletable(Function<? super T,? extends Completable> mapper)	Map each element of this Publisher into a Completable and flatten all signals such that the returned Completable terminates when all mapped Completables have terminated successfully or any one of them has terminated with a failure.
final Completable	flatMapCompletable(Function<? super T,? extends Completable> mapper, int maxConcurrency)	Map each element of this Publisher into a Completable and flatten all signals such that the returned Completable terminates when all mapped Completables have terminated successfully or any one of them has terminated with a failure.
final Completable	flatMapCompletableDelayError(Function<? super T,? extends Completable> mapper)	Map each element of this Publisher into a Completable and flatten all signals such that the returned Completable terminates when all mapped Completables have terminated successfully or any one of them has terminated with a failure.
final Completable	flatMapCompletableDelayError(Function<? super T,? extends Completable> mapper, int maxConcurrency)	Map each element of this Publisher into a Completable and flatten all signals such that the returned Completable terminates when all mapped Completables have terminated successfully or any one of them has terminated with a failure.
final Completable	flatMapCompletableDelayError(Function<? super T,? extends Completable> mapper, int maxConcurrency, int maxDelayedErrorsHint)	Map each element of this Publisher into a Completable and flatten all signals such that the returned Completable terminates when all mapped Completables have terminated successfully or any one of them has terminated with a failure.
final <R> Publisher<R>	flatMapConcatIterable(Function<? super T,? extends Iterable<? extends R>> mapper)	Create a Publisher that flattens each element returned by the Iterable.iterator() from mapper.
final <R> Publisher<R>	flatMapConcatSingle(Function<? super T,? extends Single<? extends R>> mapper)	This method is similar to map(Function) but the result is asynchronous.
final <R> Publisher<R>	flatMapConcatSingle(Function<? super T,? extends Single<? extends R>> mapper, int maxConcurrency)	This method is similar to map(Function) but the result is asynchronous.
final <R> Publisher<R>	flatMapConcatSingleDelayError(Function<? super T,? extends Single<? extends R>> mapper)	This method is similar to map(Function) but the result is asynchronous.
final <R> Publisher<R>	flatMapConcatSingleDelayError(Function<? super T,? extends Single<? extends R>> mapper, int maxConcurrency)	This method is similar to map(Function) but the result is asynchronous.
final <R> Publisher<R>	flatMapMerge(Function<? super T,? extends Publisher<? extends R>> mapper)	Map each element of this Publisher into a Publisher<Publisher> and flatten all signals emitted from each mapped Publisher<Publisher> into the returned Publisher<Publisher>.
final <R> Publisher<R>	flatMapMerge(Function<? super T,? extends Publisher<? extends R>> mapper, int maxConcurrency)	Map each element of this Publisher into a Publisher<Publisher> and flatten all signals emitted from each mapped Publisher<Publisher> into the returned Publisher<Publisher>.
final <R> Publisher<R>	flatMapMergeDelayError(Function<? super T,? extends Publisher<? extends R>> mapper)	Map each element of this Publisher into a Publisher<Publisher> and flatten all signals emitted from each mapped Publisher<Publisher> into the returned Publisher<Publisher>.
final <R> Publisher<R>	flatMapMergeDelayError(Function<? super T,? extends Publisher<? extends R>> mapper, int maxConcurrency)	Map each element of this Publisher into a Publisher<Publisher> and flatten all signals emitted from each mapped Publisher<Publisher> into the returned Publisher<Publisher>.
final <R> Publisher<R>	flatMapMergeDelayError(Function<? super T,? extends Publisher<? extends R>> mapper, int maxConcurrency, int maxDelayedErrorsHint)	Map each element of this Publisher into a Publisher<Publisher> and flatten all signals emitted from each mapped Publisher<Publisher> into the returned Publisher<Publisher>.
final <R> Publisher<R>	flatMapMergeSingle(Function<? super T,? extends Single<? extends R>> mapper)	This method is similar to map(Function) but the result is asynchronous and results are unordered.
final <R> Publisher<R>	flatMapMergeSingle(Function<? super T,? extends Single<? extends R>> mapper, int maxConcurrency)	This method is similar to map(Function) but the result is asynchronous and results are unordered.
final <R> Publisher<R>	flatMapMergeSingleDelayError(Function<? super T,? extends Single<? extends R>> mapper)	Map each element of this Publisher into a Single<Publisher> and flatten all signals emitted from each mapped Single<Publisher> into the returned Publisher<Publisher>.
final <R> Publisher<R>	flatMapMergeSingleDelayError(Function<? super T,? extends Single<? extends R>> mapper, int maxConcurrency)	This method is similar to map(Function) but the result is asynchronous and results are unordered.
final <R> Publisher<R>	flatMapMergeSingleDelayError(Function<? super T,? extends Single<? extends R>> mapper, int maxConcurrency, int maxDelayedErrorsHint)	This method is similar to map(Function) but the result is asynchronous and results are unordered.
final Cancellable	forEach(Consumer<? super T> forEach)	Subscribes to this Publisher and invokes forEach Consumer for each item emitted by this Publisher.
static <T> Publisher<T>	from(T value)	Creates a new Publisher that emits value to its PublisherSource.Subscriber and then PublisherSource.Subscriber.onComplete().
static <T> Publisher<T>	from(T... values)	Creates a new Publisher that emits all values to its PublisherSource.Subscriber and then PublisherSource.Subscriber.onComplete().
static <T> Publisher<T>	from(T v1, T v2)	Creates a new Publisher that emits v1 and v2 to its PublisherSource.Subscriber and then PublisherSource.Subscriber.onComplete().
static <T> Publisher<T>	from(T v1, T v2, T v3)	Creates a new Publisher that emits v1, v2, and v3 to its PublisherSource.Subscriber and then PublisherSource.Subscriber.onComplete().
static <T> Publisher<T>	fromBlockingIterable(BlockingIterable<? extends T> iterable, LongSupplier timeoutSupplier, TimeUnit unit)	Create a new Publisher that when subscribed will get a BlockingIterator via BlockingIterable.iterator() and emit all values to the PublisherSource.Subscriber and then PublisherSource.Subscriber.onComplete().
static Publisher<byte[]>	fromInputStream(InputStream stream)	Deprecated. Use fromInputStream(InputStream, ByteArrayMapper) with ByteArrayMapper.toByteArray().
static Publisher<byte[]>	fromInputStream(InputStream stream, int readChunkSize)	Deprecated. Use fromInputStream(InputStream, ByteArrayMapper) with ByteArrayMapper.toByteArray(int).
static <T> Publisher<T>	fromInputStream(InputStream stream, ByteArrayMapper<T> mapper)	Create a new Publisher that when subscribed will emit all data from the InputStream to the PublisherSource.Subscriber as a mapped type T and then PublisherSource.Subscriber.onComplete().
static <T> Publisher<T>	fromIterable(Iterable<? extends T> iterable)	Create a new Publisher that when subscribed will get an Iterator via Iterable.iterator() and emit all values to the PublisherSource.Subscriber and then PublisherSource.Subscriber.onComplete().
final <Key> Publisher<GroupedPublisher<Key,T>>	groupBy(Function<? super T,? extends Key> keySelector)	Splits items from this Publisher into dynamically generated GroupedPublishers.
final <Key> Publisher<GroupedPublisher<Key,T>>	groupBy(Function<? super T,? extends Key> keySelector, int queueLimit)	Splits items from this Publisher into dynamically generated GroupedPublishers.
final <Key> Publisher<GroupedPublisher<Key,T>>	groupBy(Function<? super T,? extends Key> keySelector, int queueLimit, int expectedGroupCountHint)	Splits items from this Publisher into dynamically generated GroupedPublishers.
final <Key> Publisher<GroupedPublisher<Key,T>>	groupToMany(Function<? super T,? extends Iterator<? extends Key>> keySelector, int queueLimit)	The semantics are identical to groupBy(Function, int) except that the keySelector can map each data to multiple keys.
final <Key> Publisher<GroupedPublisher<Key,T>>	groupToMany(Function<? super T,? extends Iterator<? extends Key>> keySelector, int queueLimit, int expectedGroupCountHint)	The semantics are identical to groupBy(Function, int) except that the keySelector can map each data to multiple keys.
protected abstract void	handleSubscribe(PublisherSource.Subscriber<? super T> subscriber)	Handles a subscriber to this Publisher.
final Completable	ignoreElements()	Ignores all elements emitted by this Publisher and forwards the termination signal to the returned Completable.
final <R> Publisher<R>	liftAsync(PublisherOperator<? super T,? extends R> operator)	This method requires advanced knowledge of building operators.

Methods inherited from class java.lang.Object

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

Constructor Details

Publisher

protected Publisher()

New instance.

Method Details

map

public final <R> Publisher<R> map(Function<? super T,? extends R> mapper)

Transforms elements emitted by this Publisher into a different type.

This method provides a data transformation in sequential programming similar to:

     List<R> results = ...;
     for (T t : resultOfThisPublisher()) {
         results.add(mapper.apply(t));
     }
     return results;
 

Type Parameters:

R - Type of the items emitted by the returned Publisher.

Parameters:

mapper - Function to transform each item emitted by this Publisher.

Returns:

A Publisher that transforms elements emitted by this Publisher into a different type.

See Also:

• ReactiveX map operator.

cast

public final <R> Publisher<R> cast(Class<R> clazz)

Cast this Publisher from type Publisher to type Publisher.

This method provides a data transformation in sequential programming similar to:

     List<R> results = ...;
     for (T t : resultOfThisPublisher()) {
         results.add(clazz.cast(t));
     }
     return results;
 

Type Parameters:

R - The resulting type of the cast operation.

Parameters:

clazz - The type to cast to.

Returns:

The cast of this Publisher to type Publisher. Terminates with a ClassCastException if signals cannot be cast to type Publisher.

See Also:

• ReactiveX cast operator.

filter

public final Publisher<T> filter(Predicate<? super T> predicate)

Filters items emitted by this Publisher.

This method provides a data transformation in sequential programming similar to:

     List<T> results = ...;
     for (T t : resultOfThisPublisher()) {
         if (predicate.test(t)) {
             results.add(t);
         }
     }
     return results;
 

Parameters:

predicate - for the filter.

Returns:

A Publisher that only emits the items that pass the predicate.

See Also:

• ReactiveX filter operator.

ofType

public final <R> Publisher<R> ofType(Class<R> clazz)

Filters items so that only non-null items of type Publisher are emitted by the return value.

This method provides a data transformation in sequential programming similar to:

     List<R> results = ...;
     for (T t : resultOfThisPublisher()) {
         if (clazz.isInstance(t)) {
             results.add((R) t);
         }
     }
     return results;
 

Type Parameters:

R - The resulting type of the cast operation.

Parameters:

clazz - The type to filter and cast to.

Returns:

a Publisher that only emits

See Also:

• ReactiveX ofType operator.

distinct

public final Publisher<T> distinct()

Only emits distinct signals observed by this Publisher. Signals are compared using Object.hashCode() and Object.equals(Object).

This method provides a data transformation in sequential programming similar to:

     Set<T> results = ...;
     for (T t : resultOfThisPublisher()) {
         results.add(t);
     }
     return results;
 

Returns:

A Publisher that emits distinct signals observed by this Publisher.

See Also:

• ReactiveX distinct operator.

scanWith

public final <R> Publisher<R> scanWith(Supplier<R> initial,
 BiFunction<R,? super T,R> accumulator)

Apply a BiFunction to each PublisherSource.Subscriber.onNext(Object) emitted by this Publisher and an accumulated state.

This method provides a data transformation in sequential programming similar to:

     List<R> results = ...;
     R state = initial.get();
     for (T t : resultOfThisPublisher()) {
       state = accumulator.apply(state, t);
       results.add(state);
     }
     return results;
 

Type Parameters:

R - Type of the items emitted by the returned Publisher.

Parameters:

initial - Invoked on each PublisherSource.subscribe(Subscriber) and provides the initial state for each PublisherSource.Subscriber.

accumulator - Used to accumulate the current state in combination with each PublisherSource.Subscriber.onNext(Object) from this Publisher.

Returns:

A Publisher that transforms elements emitted by this Publisher into a different type.

See Also:

• ReactiveX scan operator.

scanWith

@Deprecated
public final <R> Publisher<R> scanWith(Supplier<? extends ScanWithMapper<? super T,? extends R>> mapperSupplier)

Deprecated.

Use scanWithMapper(Supplier).

Apply a function to each PublisherSource.Subscriber.onNext(Object) emitted by this Publisher as well as optionally concat one PublisherSource.Subscriber.onNext(Object) signal before the terminal signal is emitted downstream.

This method provides a data transformation in sequential programming similar to:

     List<R> results = ...;
     ScanWithMapper<T, R> mapper = mapperSupplier.get();
     try {
       for (T t : resultOfThisPublisher()) {
         results.add(mapper.mapOnNext(t));
       }
     } catch (Throwable cause) {
       if (mapTerminal.test(state)) {
         results.add(mapper.mapOnError(cause));
         return;
       }
       throw cause;
     }
     if (mapTerminal.test(state)) {
       results.add(mapper.mapOnComplete());
     }
     return results;
 

Type Parameters:

R - Type of the items emitted by the returned Publisher.

Parameters:

mapperSupplier - Invoked on each PublisherSource.subscribe(Subscriber) and maintains any necessary state for the mapping/accumulation for each PublisherSource.Subscriber.

Returns:

A Publisher that transforms elements emitted by this Publisher into a different type.

See Also:

• ReactiveX scan operator.

scanWithMapper

public final <R> Publisher<R> scanWithMapper(Supplier<? extends ScanMapper<? super T,? extends R>> mapperSupplier)

Apply a function to each PublisherSource.Subscriber.onNext(Object) emitted by this Publisher as well as optionally concat one PublisherSource.Subscriber.onNext(Object) signal before the terminal signal is emitted downstream.

This method provides a data transformation in sequential programming similar to:

     List<R> results = ...;
     ScanWithLifetimeMapperExt<T, R> mapper = mapperSupplier.get();
     MappedTerminal<R> mapped = null;
     try {
       for (T t : resultOfThisPublisher()) {
         results.add(mapper.mapOnNext(t));
       }
     } catch (Throwable cause) {
       mapped = mapper.mapOnError(cause);
       if (mapped == null) {
         throw cause;
       }
     }
     if (mapped == null) {
       mapped = mapper.mapOnComplete();
     }
     if (mapped.onNextValid()) {
       results.add(mapped.onNext());
     }
     if (mapped.terminal() != null) {
       throw mapped.terminal();
     }
     return results;
 

Type Parameters:

R - Type of the items emitted by the returned Publisher.

Parameters:

mapperSupplier - Invoked on each PublisherSource.subscribe(Subscriber) and maintains any necessary state for the mapping/accumulation for each PublisherSource.Subscriber.

Returns:

A Publisher that transforms elements emitted by this Publisher into a different type.

See Also:

• ReactiveX scan operator.

scanWithLifetime

@Deprecated
public final <R> Publisher<R> scanWithLifetime(Supplier<? extends ScanWithLifetimeMapper<? super T,? extends R>> mapperSupplier)

Deprecated.

Use scanWithLifetimeMapper(Supplier).

Apply a function to each PublisherSource.Subscriber.onNext(Object) emitted by this Publisher as well as optionally concat one PublisherSource.Subscriber.onNext(Object) signal before the terminal signal is emitted downstream. Additionally the ScanWithLifetimeMapper.afterFinally() method will be invoked on terminal or cancel signals which enables cleanup of state (if required). This provides a similar lifetime management as TerminalSignalConsumer.

This method provides a data transformation in sequential programming similar to:

     List<R> results = ...;
     ScanWithLifetimeMapper<T, R> mapper = mapperSupplier.get();
     try {
         try {
           for (T t : resultOfThisPublisher()) {
             results.add(mapper.mapOnNext(t));
           }
         } catch (Throwable cause) {
           if (mapTerminal.test(state)) {
             results.add(mapper.mapOnError(cause));
             return;
           }
           throw cause;
         }
         if (mapTerminal.test(state)) {
           results.add(mapper.mapOnComplete());
         }
     } finally {
       mapper.afterFinally();
     }
     return results;
 

Type Parameters:

R - Type of the items emitted by the returned Publisher.

Parameters:

mapperSupplier - Invoked on each PublisherSource.subscribe(Subscriber) and maintains any necessary state for the mapping/accumulation for each PublisherSource.Subscriber.

Returns:

A Publisher that transforms elements emitted by this Publisher into a different type.

See Also:

• ReactiveX scan operator.

scanWithLifetimeMapper

public final <R> Publisher<R> scanWithLifetimeMapper(Supplier<? extends ScanLifetimeMapper<? super T,? extends R>> mapperSupplier)

Apply a function to each PublisherSource.Subscriber.onNext(Object) emitted by this Publisher as well as optionally concat one PublisherSource.Subscriber.onNext(Object) signal before the terminal signal is emitted downstream. Additionally the ScanLifetimeMapper.afterFinally() method will be invoked on terminal or cancel signals which enables cleanup of state (if required). This provides a similar lifetime management as TerminalSignalConsumer.

This method provides a data transformation in sequential programming similar to:

     List<R> results = ...;
     ScanWithLifetimeMapperExt<T, R> mapper = mapperSupplier.get();
     try {
       MappedTerminal<R> mapped = null;
       try {
         for (T t : resultOfThisPublisher()) {
           results.add(mapper.mapOnNext(t));
         }
       } catch (Throwable cause) {
         mapped = mapper.mapOnError(cause);
         if (mapped == null) {
           throw cause;
         }
       }
       if (mapped == null) {
         mapped = mapper.mapOnComplete();
       }
       if (mapped.onNextValid()) {
         results.add(mapped.onNext());
       }
       if (mapped.terminal() != null) {
          throw mapped.terminal();
       }
     } finally {
       mapper.afterFinally();
     }
     return results;
 

Type Parameters:

R - Type of the items emitted by the returned Publisher.

Parameters:

mapperSupplier - Invoked on each PublisherSource.subscribe(Subscriber) and maintains any necessary state for the mapping/accumulation for each PublisherSource.Subscriber.

Returns:

A Publisher that transforms elements emitted by this Publisher into a different type.

See Also:

• ReactiveX scan operator.

onErrorComplete

public final Publisher<T> onErrorComplete()

Transform errors emitted on this Publisher into a PublisherSource.Subscriber.onComplete() signal (e.g. swallows the error).

This method provides a data transformation in sequential programming similar to:

     List<T> results = resultOfThisPublisher();
     try {
         terminalOfThisPublisher();
     } catch (Throwable cause) {
         // ignored
     }
     return results;
 

Returns:

A Publisher which transform errors emitted on this Publisher into a PublisherSource.Subscriber.onComplete() signal (e.g. swallows the error).

See Also:

• ReactiveX catch operator.

onErrorComplete

public final <E extends Throwable> Publisher<T> onErrorComplete(Class<E> type)

Transform errors emitted on this Publisher which match type into a PublisherSource.Subscriber.onComplete() signal (e.g. swallows the error).

This method provides a data transformation in sequential programming similar to:

     List<T> results = resultOfThisPublisher();
     try {
         terminalOfThisPublisher();
     } catch (Throwable cause) {
         if (!type.isInstance(cause)) {
           throw cause;
         }
     }
     return results;
 

Type Parameters:

E - The Throwable type.

Parameters:

type - The Throwable type to filter, operator will not apply for errors which don't match this type.

Returns:

A Publisher which transform errors emitted on this Publisher which match type into a PublisherSource.Subscriber.onComplete() signal (e.g. swallows the error).

See Also:

• ReactiveX catch operator.

onErrorComplete

public final Publisher<T> onErrorComplete(Predicate<? super Throwable> predicate)

Transform errors emitted on this Publisher which match predicate into a PublisherSource.Subscriber.onComplete() signal (e.g. swallows the error).

This method provides a data transformation in sequential programming similar to:

     List<T> results = resultOfThisPublisher();
     try {
         terminalOfThisPublisher();
     } catch (Throwable cause) {
         if (!predicate.test(cause)) {
           throw cause;
         }
     }
     return results;
 

Parameters:

predicate - returns true if the Throwable should be transformed to and PublisherSource.Subscriber.onComplete() signal. Returns false to propagate the error.

Returns:

A Publisher which transform errors emitted on this Publisher which match predicate into a PublisherSource.Subscriber.onComplete() signal (e.g. swallows the error).

See Also:

• ReactiveX catch operator.

onErrorReturn

public final Publisher<T> onErrorReturn(Function<? super Throwable,? extends T> itemSupplier)

Transform errors emitted on this Publisher into PublisherSource.Subscriber.onNext(Object) then PublisherSource.Subscriber.onComplete() signals (e.g. swallows the error).

This method provides a data transformation in sequential programming similar to:

     List<T> results = resultOfThisPublisher();
     try {
         terminalOfThisPublisher();
     } catch (Throwable cause) {
         results.add(itemSupplier.apply(cause));
     }
     return results;
 

Parameters:

itemSupplier - returns the element to emit to PublisherSource.Subscriber.onNext(Object).

Returns:

A Publisher which transform errors emitted on this Publisher into PublisherSource.Subscriber.onNext(Object) then PublisherSource.Subscriber.onComplete() signals (e.g. swallows the error).

See Also:

• ReactiveX catch operator.

onErrorReturn

public final <E extends Throwable> Publisher<T> onErrorReturn(Class<E> type,
 Function<? super E,? extends T> itemSupplier)

Transform errors emitted on this Publisher which match type into PublisherSource.Subscriber.onNext(Object) then PublisherSource.Subscriber.onComplete() signals (e.g. swallows the error).

This method provides a data transformation in sequential programming similar to:

     List<T> results = resultOfThisPublisher();
     try {
         terminalOfThisPublisher();
     } catch (Throwable cause) {
         if (!type.isInstance(cause)) {
           throw cause;
         }
         results.add(itemSupplier.apply(cause));
     }
     return results;
 

Type Parameters:

E - The type of Throwable to transform.

Parameters:

type - The Throwable type to filter, operator will not apply for errors which don't match this type.

itemSupplier - returns the element to emit to PublisherSource.Subscriber.onNext(Object).

Returns:

A Publisher which transform errors emitted on this Publisher into PublisherSource.Subscriber.onNext(Object) then PublisherSource.Subscriber.onComplete() signals (e.g. swallows the error).

See Also:

• ReactiveX catch operator.

onCompleteError

public final Publisher<T> onCompleteError(Supplier<? extends Throwable> errorSupplier)

Transform this Publishers PublisherSource.Subscriber.onComplete() signal into PublisherSource.Subscriber.onError(Throwable) signal (unless null error returned from errorSupplier).

This method provides a data transformation in sequential programming similar to:

     List<T> results = resultOfThisPublisher();
     terminalOfThisPublisher();
     Throwable cause = errorSupplier.get()
     if (cause != null) {
       throw cause;
     }
 

Parameters:

errorSupplier - returns the error to emit to PublisherSource.Subscriber.onError(Throwable). if the return value is null then complete with PublisherSource.Subscriber.onComplete().

Returns:

A Publisher which transform this Publishers PublisherSource.Subscriber.onComplete() signal into PublisherSource.Subscriber.onError(Throwable) signal (unless null error returned from errorSupplier).

onErrorReturn

public final Publisher<T> onErrorReturn(Predicate<? super Throwable> predicate,
 Function<? super Throwable,? extends T> itemSupplier)

Transform errors emitted on this Publisher which match predicate into PublisherSource.Subscriber.onNext(Object) then PublisherSource.Subscriber.onComplete() signals (e.g. swallows the error).

This method provides a data transformation in sequential programming similar to:

     List<T> results = resultOfThisPublisher();
     try {
         terminalOfThisPublisher();
     } catch (Throwable cause) {
         if (!predicate.test(cause)) {
           throw cause;
         }
         results.add(itemSupplier.apply(cause));
     }
     return result;
 

Parameters:

predicate - returns true if the Throwable should be transformed to PublisherSource.Subscriber.onNext(Object) then PublisherSource.Subscriber.onComplete() signals. Returns false to propagate the error.

itemSupplier - returns the element to emit to PublisherSource.Subscriber.onNext(Object).

Returns:

A Publisher which transform errors emitted on this Publisher into PublisherSource.Subscriber.onNext(Object) then PublisherSource.Subscriber.onComplete() signals (e.g. swallows the error).

See Also:

• ReactiveX catch operator.

onErrorMap

public final Publisher<T> onErrorMap(Function<? super Throwable,? extends Throwable> mapper)

Transform errors emitted on this Publisher into a different error.

This method provides a data transformation in sequential programming similar to:

     List<T> results = resultOfThisPublisher();
     try {
         terminalOfThisPublisher();
     } catch (Throwable cause) {
         throw mapper.apply(cause);
     }
     return results;
 

Parameters:

mapper - returns the error used to terminate the returned Publisher.

Returns:

A Publisher which transform errors emitted on this Publisher into a different error.

See Also:

• ReactiveX catch operator.

onErrorMap

public final <E extends Throwable> Publisher<T> onErrorMap(Class<E> type,
 Function<? super E,? extends Throwable> mapper)

Transform errors emitted on this Publisher which match type into a different error.

This method provides a data transformation in sequential programming similar to:

     List<T> results = resultOfThisPublisher();
     try {
         terminalOfThisPublisher();
     } catch (Throwable cause) {
         if (type.isInstance(cause)) {
           throw mapper.apply(cause);
         } else {
           throw cause;
         }
     }
     return results;
 

Type Parameters:

E - The type of Throwable to transform.

Parameters:

type - The Throwable type to filter, operator will not apply for errors which don't match this type.

mapper - returns the error used to terminate the returned Publisher.

Returns:

A Publisher which transform errors emitted on this Publisher into a different error.

See Also:

• ReactiveX catch operator.

onErrorMap

public final Publisher<T> onErrorMap(Predicate<? super Throwable> predicate,
 Function<? super Throwable,? extends Throwable> mapper)

Transform errors emitted on this Publisher which match predicate into a different error.

This method provides a data transformation in sequential programming similar to:

     List<T> results = resultOfThisPublisher();
     try {
         terminalOfThisPublisher();
     } catch (Throwable cause) {
         if (predicate.test(cause)) {
           throw mapper.apply(cause);
         } else {
           throw cause;
         }
     }
     return results;
 

Parameters:

predicate - returns true if the Throwable should be transformed via mapper. Returns false to propagate the original error.

mapper - returns the error used to terminate the returned Publisher.

Returns:

A Publisher which transform errors emitted on this Publisher into a different error.

See Also:

• ReactiveX catch operator.

onErrorResume

public final Publisher<T> onErrorResume(Function<? super Throwable,? extends Publisher<? extends T>> nextFactory)

Recover from any error emitted by this Publisher by using another Publisher provided by the passed nextFactory.

This method provides similar capabilities to a try/catch block in sequential programming:

     List<T> results;
     try {
         results = resultOfThisPublisher();
     } catch (Throwable cause) {
         // Note that nextFactory returning a error Publisher is like re-throwing (nextFactory shouldn't throw).
         results = nextFactory.apply(cause);
     }
     return results;
 

Parameters:

nextFactory - Returns the next Publisher, when this Publisher emits an error.

Returns:

A Publisher that recovers from an error from this Publisher by using another Publisher provided by the passed nextFactory.

See Also:

• ReactiveX catch operator.

onErrorResume

public final <E extends Throwable> Publisher<T> onErrorResume(Class<E> type,
 Function<? super E,? extends Publisher<? extends T>> nextFactory)

Recover from errors emitted by this Publisher which match type by using another Publisher provided by the passed nextFactory.

This method provides similar capabilities to a try/catch block in sequential programming:

     List<T> results;
     try {
         results = resultOfThisPublisher();
     } catch (Throwable cause) {
         if (type.isInstance(cause)) {
           // Note that nextFactory returning a error Publisher is like re-throwing (nextFactory shouldn't throw).
           results = nextFactory.apply(cause);
         } else {
           throw cause;
         }
     }
     return results;
 

Type Parameters:

E - The type of Throwable to transform.

Parameters:

type - The Throwable type to filter, operator will not apply for errors which don't match this type.

nextFactory - Returns the next Publisher, when this Publisher emits an error.

Returns:

A Publisher that recovers from an error from this Publisher by using another Publisher provided by the passed nextFactory.

See Also:

• ReactiveX catch operator.

onErrorResume

public final Publisher<T> onErrorResume(Predicate<? super Throwable> predicate,
 Function<? super Throwable,? extends Publisher<? extends T>> nextFactory)

Recover from errors emitted by this Publisher which match predicate by using another Publisher provided by the passed nextFactory.

This method provides similar capabilities to a try/catch block in sequential programming:

     List<T> results;
     try {
         results = resultOfThisPublisher();
     } catch (Throwable cause) {
         if (predicate.test(cause)) {
           // Note that nextFactory returning a error Publisher is like re-throwing (nextFactory shouldn't throw).
           results = nextFactory.apply(cause);
         } else {
           throw cause;
         }
     }
     return results;
 

Parameters:

predicate - returns true if the Throwable should be transformed via nextFactory. Returns false to propagate the original error.

nextFactory - Returns the next Publisher, when this Publisher emits an error.

Returns:

A Publisher that recovers from an error from this Publisher by using another Publisher provided by the passed nextFactory.

See Also:

• ReactiveX catch operator.

flatMapMerge

public final <R> Publisher<R> flatMapMerge(Function<? super T,? extends Publisher<? extends R>> mapper)

Map each element of this Publisher into a Publisher<Publisher> and flatten all signals emitted from each mapped Publisher<Publisher> into the returned Publisher<Publisher>.

To control the amount of concurrent processing done by this operator see flatMapMerge(Function, int).

This method is similar to map(Function) but the result is an asynchronous stream, and provides a data transformation in sequential programming similar to:

     ExecutorService e = ...;
     List<Future<List<R>>> futures = ...; // assume this is thread safe
     for (T t : resultOfThisPublisher()) {
         // Note that flatMap process results in parallel.
         futures.add(e.submit(() -> {
             return mapper.apply(t); // Asynchronous result is flatten into a value by this operator.
         }));
     }
     List<R> results = new ArrayList<>(futures.size());
     // This is an approximation, this operator does not provide any ordering guarantees for the results.
     for (Future<List<R>> future : futures) {
         List<R> rList = future.get(); // Throws if the processing for this item failed.
         results.addAll(rList);
     }
     return results;
 

Type Parameters:

R - The type of mapped Publisher.

Parameters:

mapper - Convert each item emitted by this Publisher into another Publisher.

Returns:

A new Publisher which flattens the emissions from all mapped Publishers.

See Also:

• ReactiveX flatMap operator.

flatMapMerge

public final <R> Publisher<R> flatMapMerge(Function<? super T,? extends Publisher<? extends R>> mapper,
 int maxConcurrency)

Map each element of this Publisher into a Publisher<Publisher> and flatten all signals emitted from each mapped Publisher<Publisher> into the returned Publisher<Publisher>.

This method is similar to map(Function) but the result is an asynchronous stream, and provides a data transformation in sequential programming similar to:

     ExecutorService e = ...;
     List<Future<List<R>>> futures = ...; // assume this is thread safe
     for (T t : resultOfThisPublisher()) {
         // Note that flatMap process results in parallel.
         futures.add(e.submit(() -> {
             return mapper.apply(t); // Asynchronous result is flatten into a value by this operator.
         }));
     }
     List<R> results = new ArrayList<>(futures.size());
     // This is an approximation, this operator does not provide any ordering guarantees for the results.
     for (Future<List<R>> future : futures) {
         List<R> rList = future.get(); // Throws if the processing for this item failed.
         results.addAll(rList);
     }
     return results;
 

Type Parameters:

R - The type of mapped Publisher.

Parameters:

mapper - Convert each item emitted by this Publisher into another Publisher.

maxConcurrency - Maximum amount of outstanding upstream demand.

Returns:

A new Publisher which flattens the emissions from all mapped Publishers.

See Also:

• ReactiveX flatMap operator.

flatMapMergeDelayError

public final <R> Publisher<R> flatMapMergeDelayError(Function<? super T,? extends Publisher<? extends R>> mapper)

Map each element of this Publisher into a Publisher<Publisher> and flatten all signals emitted from each mapped Publisher<Publisher> into the returned Publisher<Publisher>.

This is the same as flatMapMerge(Function) just that if any mapped Publisher returned by mapper, terminates with an error, the returned Publisher will not immediately terminate. Instead, it will wait for this Publisher and all mapped Publishers to terminate and then terminate the returned Publisher with all errors emitted by the mapped Publishers.

To control the amount of concurrent processing done by this operator see flatMapMergeDelayError(Function, int).

This method is similar to map(Function) but the result is an asynchronous stream, and provides a data transformation in sequential programming similar to:

     Executor e = ...;
     List<T> tResults = resultOfThisPublisher();
     List<R> rResults = ...; // assume this is thread safe
     List<Throwable> errors = ...;  // assume this is thread safe
     CountDownLatch latch =  new CountDownLatch(tResults.size());
     for (T t : resultOfThisPublisher()) {
         // Note that flatMap process results in parallel.
         e.execute(() -> {
             try {
                 List<R> rList = mapper.apply(t); // Asynchronous result is flatten into a value by this operator.
                 rResults.addAll(rList);
             } catch (Throwable cause) {
                 errors.add(cause);  // Asynchronous error is flatten into an error by this operator.
             } finally {
                 latch.countdown();
             }
         });
     }
     latch.await();
     if (errors.isEmpty()) {
         return rResults;
     }
     createAndThrowACompositeException(errors);
 

Type Parameters:

R - The type of mapped Publisher.

Parameters:

mapper - Convert each item emitted by this Publisher into another Publisher.

Returns:

A new Publisher which flattens the emissions from all mapped Publishers.

See Also:

• ReactiveX flatMap operator.

flatMapMergeDelayError

public final <R> Publisher<R> flatMapMergeDelayError(Function<? super T,? extends Publisher<? extends R>> mapper,
 int maxConcurrency)

Map each element of this Publisher into a Publisher<Publisher> and flatten all signals emitted from each mapped Publisher<Publisher> into the returned Publisher<Publisher>.

This is the same as flatMapMerge(Function) just that if any mapped Publisher returned by mapper, terminates with an error, the returned Publisher will not immediately terminate. Instead, it will wait for this Publisher and all mapped Publishers to terminate and then terminate the returned Publisher with all errors emitted by the mapped Publishers.

This method is similar to map(Function) but the result is an asynchronous stream, and provides a data transformation in sequential programming similar to:

     Executor e = ...;
     List<T> tResults = resultOfThisPublisher();
     List<R> rResults = ...; // assume this is thread safe
     List<Throwable> errors = ...;  // assume this is thread safe
     CountDownLatch latch =  new CountDownLatch(tResults.size());
     for (T t : resultOfThisPublisher()) {
         // Note that flatMap process results in parallel.
         e.execute(() -> {
             try {
                 List<R> rList = mapper.apply(t); // Asynchronous result is flatten into a value by this operator.
                 rResults.addAll(rList);
             } catch (Throwable cause) {
                 errors.add(cause);  // Asynchronous error is flatten into an error by this operator.
             } finally {
                 latch.countdown();
             }
         });
     }
     latch.await();
     if (errors.isEmpty()) {
         return rResults;
     }
     createAndThrowACompositeException(errors);
 

Type Parameters:

R - The type of mapped Publisher.

Parameters:

mapper - Convert each item emitted by this Publisher into another Publisher.

maxConcurrency - Maximum amount of outstanding upstream demand.

Returns:

A new Publisher which flattens the emissions from all mapped Publishers.

See Also:

• ReactiveX flatMap operator.

flatMapMergeDelayError

public final <R> Publisher<R> flatMapMergeDelayError(Function<? super T,? extends Publisher<? extends R>> mapper,
 int maxConcurrency,
 int maxDelayedErrorsHint)

Map each element of this Publisher into a Publisher<Publisher> and flatten all signals emitted from each mapped Publisher<Publisher> into the returned Publisher<Publisher>.

This is the same as flatMapMerge(Function) just that if any mapped Publisher returned by mapper, terminates with an error, the returned Publisher will not immediately terminate. Instead, it will wait for this Publisher and all mapped Publishers to terminate and then terminate the returned Publisher with all errors emitted by the mapped Publishers.

This method is similar to map(Function) but the result is an asynchronous stream, and provides a data transformation in sequential programming similar to:

     Executor e = ...;
     List<T> tResults = resultOfThisPublisher();
     List<R> rResults = ...; // assume this is thread safe
     List<Throwable> errors = ...;  // assume this is thread safe
     CountDownLatch latch =  new CountDownLatch(tResults.size());
     for (T t : resultOfThisPublisher()) {
         // Note that flatMap process results in parallel.
         e.execute(() -> {
             try {
                 List<R> rList = mapper.apply(t); // Asynchronous result is flatten into a value by this operator.
                 rResults.addAll(rList);
             } catch (Throwable cause) {
                 errors.add(cause);  // Asynchronous error is flatten into an error by this operator.
             } finally {
                 latch.countdown();
             }
         });
     }
     latch.await();
     if (errors.isEmpty()) {
         return rResults;
     }
     createAndThrowACompositeException(errors);
 

Type Parameters:

R - The type of mapped Publisher.

Parameters:

mapper - Convert each item emitted by this Publisher into another Publisher.

maxConcurrency - Maximum amount of outstanding upstream demand.

maxDelayedErrorsHint - The maximum amount of errors that will be queued. After this point exceptions maybe discarded to reduce memory consumption.

Returns:

A new Publisher which flattens the emissions from all mapped Publishers.

See Also:

• ReactiveX flatMap operator.

flatMapMergeSingle

public final <R> Publisher<R> flatMapMergeSingle(Function<? super T,? extends Single<? extends R>> mapper)

This method is similar to map(Function) but the result is asynchronous and results are unordered. More specifically, map each element of this Publisher into a Single<Publisher> and flatten all signals emitted from each mapped Single<Publisher> into the returned Publisher<Publisher>.

To control the amount of concurrent processing done by this operator see flatMapMergeSingle(Function, int).

Provides a data transformation in sequential programming similar to:

     ExecutorService e = ...;
     List<Future<R>> futures = ...; // assume this is thread safe
     for (T t : resultOfThisPublisher()) {
         // Note that flatMap process results in parallel.
         futures.add(e.submit(() -> {
             return mapper.apply(t); // Asynchronous result is flatten into a value by this operator.
         }));
     }
     List<R> results = new ArrayList<>(futures.size());
     // This is an approximation, this operator does not provide any ordering guarantees for the results.
     for (Future<R> future : futures) {
         R r = future.get(); // Throws if the processing for this item failed.
         results.add(r);
     }
     return results;
 

Type Parameters:

R - Type of items emitted by the returned Publisher.

Parameters:

mapper - Function to convert each item emitted by this Publisher into a Single.

Returns:

A new Publisher that emits all items emitted by each single produced by mapper.

See Also:

• ReactiveX flatMap operator.
• flatMapMergeSingle(Function, int)
• flatMapConcatSingle(Function)

flatMapMergeSingle

public final <R> Publisher<R> flatMapMergeSingle(Function<? super T,? extends Single<? extends R>> mapper,
 int maxConcurrency)

This method is similar to map(Function) but the result is asynchronous and results are unordered. More specifically, map each element of this Publisher into a Single<Publisher> and flatten all signals emitted from each mapped Single<Publisher> into the returned Publisher<Publisher>.

Provides a data transformation in sequential programming similar to:

     ExecutorService e = ...;
     List<Future<R>> futures = ...; // assume this is thread safe
     for (T t : resultOfThisPublisher()) {
         // Note that flatMap process results in parallel.
         futures.add(e.submit(() -> {
             return mapper.apply(t); // Asynchronous result is flatten into a value by this operator.
         }));
     }
     List<R> results = new ArrayList<>(futures.size());
     // This is an approximation, this operator does not provide any ordering guarantees for the results.
     for (Future<R> future : futures) {
         R r = future.get(); // Throws if the processing for this item failed.
         results.add(r);
     }
     return results;
 

Type Parameters:

R - Type of items emitted by the returned Publisher.

Parameters:

mapper - Function to convert each item emitted by this Publisher into a Single.

maxConcurrency - Maximum active Singles at any time. Even if the number of items requested by a PublisherSource.Subscriber is more than this number, this will never request more than this number at any point.

Returns:

A new Publisher that emits all items emitted by each single produced by mapper.

See Also:

• ReactiveX flatMap operator.
• flatMapConcatSingle(Function, int)

flatMapMergeSingleDelayError

public final <R> Publisher<R> flatMapMergeSingleDelayError(Function<? super T,? extends Single<? extends R>> mapper)

Map each element of this Publisher into a Single<Publisher> and flatten all signals emitted from each mapped Single<Publisher> into the returned Publisher<Publisher>.

The behavior is the same as flatMapMergeSingle(Function, int) with the exception that if any Single returned by mapper, terminates with an error, the returned Publisher will not immediately terminate. Instead, it will wait for this Publisher and all Singles to terminate and then terminate the returned Publisher with errors emitted by the Singles produced by the mapper.

To control the amount of concurrent processing done by this operator see flatMapMergeSingleDelayError(Function, int).

This method is similar to map(Function) but the result is asynchronous, unordered, and provides a data transformation in sequential programming similar to:

     ExecutorService e = ...;
     List<Future<R>> futures = ...; // assume this is thread safe
     for (T t : resultOfThisPublisher()) {
         // Note that flatMap process results in parallel.
         futures.add(e.submit(() -> {
             processResult(mapper.apply(t));
             return null;
         }));
     }
     List<Throwable> errors = ...;
     for (Future<R> future : futures) {
         try {
           future.get(); // Throws if the processing for this item failed.
         } catch (Throwable cause) {
           errors.add(cause);
         }
     }
     throwExceptionIfNotEmpty(errors);
 

Type Parameters:

R - Type of items emitted by the returned Publisher.

Parameters:

mapper - Function to convert each item emitted by this Publisher into a Single.

Returns:

A new Publisher that emits all items emitted by each single produced by mapper.

See Also:

• ReactiveX flatMap operator.
• flatMapMergeSingleDelayError(Function, int)
• flatMapConcatSingleDelayError(Function)

flatMapMergeSingleDelayError

public final <R> Publisher<R> flatMapMergeSingleDelayError(Function<? super T,? extends Single<? extends R>> mapper,
 int maxConcurrency)

This method is similar to map(Function) but the result is asynchronous and results are unordered. More specifically, map each element of this Publisher into a Single<Publisher> and flatten all signals emitted from each mapped Single<Publisher> into the returned Publisher<Publisher>.

The behavior is the same as flatMapMergeSingle(Function, int) with the exception that if any Single returned by mapper, terminates with an error, the returned Publisher will not immediately terminate. Instead, it will wait for this Publisher and all Singles to terminate and then terminate the returned Publisher with all errors emitted by the Singles produced by the mapper.

Provides a data transformation in sequential programming similar to:

     ExecutorService e = ...;
     List<Future<R>> futures = ...; // assume this is thread safe
     for (T t : resultOfThisPublisher()) {
         // Note that flatMap process results in parallel.
         futures.add(e.submit(() -> {
             processResult(mapper.apply(t));
             return null;
         }));
     }
     List<Throwable> errors = ...;
     for (Future<R> future : futures) {
         try {
           future.get(); // Throws if the processing for this item failed.
         } catch (Throwable cause) {
           errors.add(cause);
         }
     }
     throwExceptionIfNotEmpty(errors);
 

Type Parameters:

R - Type of items emitted by the returned Publisher.

Parameters:

mapper - Function to convert each item emitted by this Publisher into a Single.

maxConcurrency - Maximum active Singles at any time. Even if the number of items requested by a PublisherSource.Subscriber is more than this number, this will never request more than this number at any point.

Returns:

A new Publisher that emits all items emitted by each single produced by mapper.

See Also:

• ReactiveX flatMap operator.
• flatMapConcatSingleDelayError(Function, int)

flatMapMergeSingleDelayError

public final <R> Publisher<R> flatMapMergeSingleDelayError(Function<? super T,? extends Single<? extends R>> mapper,
 int maxConcurrency,
 int maxDelayedErrorsHint)

This method is similar to map(Function) but the result is asynchronous and results are unordered. More specifically, map each element of this Publisher into a Single<Publisher> and flatten all signals emitted from each mapped Single<Publisher> into the returned Publisher<Publisher>.

The behavior is the same as flatMapMergeSingle(Function, int) with the exception that if any Single returned by mapper, terminates with an error, the returned Publisher will not immediately terminate. Instead, it will wait for this Publisher and all Singles to terminate and then terminate the returned Publisher with errors emitted by the Singles produced by the mapper.

Provides a data transformation in sequential programming similar to:

     ExecutorService e = ...;
     List<Future<R>> futures = ...; // assume this is thread safe
     for (T t : resultOfThisPublisher()) {
         // Note that flatMap process results in parallel.
         futures.add(e.submit(() -> {
             processResult(mapper.apply(t));
             return null;
         }));
     }
     List<Throwable> errors = ...;
     for (Future<R> future : futures) {
         try {
           future.get(); // Throws if the processing for this item failed.
         } catch (Throwable cause) {
           errors.add(cause);
         }
     }
     throwExceptionIfNotEmpty(errors);
 

Type Parameters:

R - Type of items emitted by the returned Publisher.

Parameters:

mapper - Function to convert each item emitted by this Publisher into a Single.

maxConcurrency - Maximum active Singles at any time. Even if the number of items requested by a PublisherSource.Subscriber is more than this number, this will never request more than this number at any point.

maxDelayedErrorsHint - The maximum amount of errors that will be queued. After this point exceptions maybe discarded to reduce memory consumption.

Returns:

A new Publisher that emits all items emitted by each single produced by mapper.

See Also:

• ReactiveX flatMap operator.
• flatMapConcatSingleDelayError(Function, int)

flatMapCompletable

public final Completable flatMapCompletable(Function<? super T,? extends Completable> mapper)

Map each element of this Publisher into a Completable and flatten all signals such that the returned Completable terminates when all mapped Completables have terminated successfully or any one of them has terminated with a failure.

If the returned Completable should wait for the termination of all mapped Completables when any one of them terminates with a failure, flatMapCompletableDelayError(Function) should be used.

To control the amount of concurrent processing done by this operator see flatMapCompletable(Function, int).

This method is similar to map(Function) but the result is asynchronous, and provides a data transformation in sequential programming similar to:

     ExecutorService e = ...;
     List<Future<Void>> futures = ...; // assume this is thread safe
     for (T t : resultOfThisPublisher()) {
         // Note that flatMap process results in parallel.
         futures.add(e.submit(() -> {
             return mapper.apply(t); // Asynchronous result is flatten into a value by this operator.
         }));
     }
     // This is an approximation, this operator does not provide any ordering guarantees for the results.
     for (Future<R> future : futures) {
         future.get(); // Throws if the processing for this item failed.
     }
 

Parameters:

mapper - Function to convert each item emitted by this Publisher into a Completable.

Returns:

A new Completable that terminates successfully if all the intermediate Completables have terminated successfully or any one of them has terminated with a failure.

See Also:

• ReactiveX flatMap operator.
• flatMapCompletable(Function, int)
• flatMapCompletableDelayError(Function)

flatMapCompletable

public final Completable flatMapCompletable(Function<? super T,? extends Completable> mapper,
 int maxConcurrency)

Map each element of this Publisher into a Completable and flatten all signals such that the returned Completable terminates when all mapped Completables have terminated successfully or any one of them has terminated with a failure.

If the returned Completable should wait for the termination of all mapped Completables when any one of them terminates with a failure, flatMapCompletableDelayError(Function) should be used.

This method is similar to map(Function) but the result is asynchronous, and provides a data transformation in sequential programming similar to:

     ExecutorService e = ...;
     List<Future<Void>> futures = ...; // assume this is thread safe
     for (T t : resultOfThisPublisher()) {
         // Note that flatMap process results in parallel.
         futures.add(e.submit(() -> {
             return mapper.apply(t); // Asynchronous result is flatten into a value by this operator.
         }));
     }
     // This is an approximation, this operator does not provide any ordering guarantees for the results.
     for (Future<R> future : futures) {
         future.get(); // Throws if the processing for this item failed.
     }
 

Parameters:

mapper - Function to convert each item emitted by this Publisher into a Completable.

maxConcurrency - Maximum active Completables at any time.

Returns:

A new Completable that terminates successfully if all the intermediate Completables have terminated successfully or any one of them has terminated with a failure.

See Also:

• ReactiveX flatMap operator.
• flatMapCompletable(Function)
• flatMapCompletableDelayError(Function, int)

flatMapCompletableDelayError

public final Completable flatMapCompletableDelayError(Function<? super T,? extends Completable> mapper)

Map each element of this Publisher into a Completable and flatten all signals such that the returned Completable terminates when all mapped Completables have terminated successfully or any one of them has terminated with a failure.

If any mapped Completable terminates with an error the returned Completable will not immediately terminate. Instead, it will wait for this Publisher and all mapped Completables to terminate.

To control the amount of concurrent processing done by this operator see flatMapCompletableDelayError(Function, int).

This method is similar to map(Function) but the result is asynchronous, and provides a data transformation in sequential programming similar to:

     ExecutorService e = ...;
     List<Future<R>> futures = ...; // assume this is thread safe
     for (T t : resultOfThisPublisher()) {
         // Note that flatMap process results in parallel.
         futures.add(e.submit(() -> {
             mapper.apply(t);
             return null;
         }));
     }
     List<Throwable> errors = ...;
     for (Future<R> future : futures) {
         try {
           future.get(); // Throws if the processing for this item failed.
         } catch (Throwable cause) {
           errors.add(cause);
         }
     }
     throwExceptionIfNotEmpty(errors);
 

Parameters:

mapper - Function to convert each item emitted by this Publisher into a Completable.

Returns:

A new Completable that terminates successfully if all the intermediate Completables have terminated successfully or any one of them has terminated with a failure.

See Also:

• ReactiveX flatMap operator.
• flatMapMergeSingleDelayError(Function, int)

flatMapCompletableDelayError

public final Completable flatMapCompletableDelayError(Function<? super T,? extends Completable> mapper,
 int maxConcurrency)

Map each element of this Publisher into a Completable and flatten all signals such that the returned Completable terminates when all mapped Completables have terminated successfully or any one of them has terminated with a failure.

If any mapped Completable terminates with an error the returned Completable will not immediately terminate. Instead, it will wait for this Publisher and all mapped Completables to terminate.

This method is similar to map(Function) but the result is asynchronous, and provides a data transformation in sequential programming similar to:

     ExecutorService e = ...;
     List<Future<R>> futures = ...; // assume this is thread safe
     for (T t : resultOfThisPublisher()) {
         // Note that flatMap process results in parallel.
         futures.add(e.submit(() -> {
             mapper.apply(t);
             return null;
         }));
     }
     List<Throwable> errors = ...;
     for (Future<R> future : futures) {
         try {
           future.get(); // Throws if the processing for this item failed.
         } catch (Throwable cause) {
           errors.add(cause);
         }
     }
     throwExceptionIfNotEmpty(errors);
 

Parameters:

mapper - Function to convert each item emitted by this Publisher into a Completable.

maxConcurrency - Maximum active Completables at any time.

Returns:

A new Completable that terminates successfully if all the intermediate Completables have terminated successfully or any one of them has terminated with a failure.

See Also:

• ReactiveX flatMap operator.
• flatMapMergeSingleDelayError(Function, int)

flatMapCompletableDelayError

public final Completable flatMapCompletableDelayError(Function<? super T,? extends Completable> mapper,
 int maxConcurrency,
 int maxDelayedErrorsHint)

Map each element of this Publisher into a Completable and flatten all signals such that the returned Completable terminates when all mapped Completables have terminated successfully or any one of them has terminated with a failure.

If any mapped Completable terminates with an error the returned Completable will not immediately terminate. Instead, it will wait for this Publisher and all mapped Completables to terminate.

This method is similar to map(Function) but the result is asynchronous, and provides a data transformation in sequential programming similar to:

     ExecutorService e = ...;
     List<Future<R>> futures = ...; // assume this is thread safe
     for (T t : resultOfThisPublisher()) {
         // Note that flatMap process results in parallel.
         futures.add(e.submit(() -> {
             mapper.apply(t);
             return null;
         }));
     }
     List<Throwable> errors = ...;
     for (Future<R> future : futures) {
         try {
           future.get(); // Throws if the processing for this item failed.
         } catch (Throwable cause) {
           errors.add(cause);
         }
     }
     throwExceptionIfNotEmpty(errors);
 

Parameters:

mapper - Function to convert each item emitted by this Publisher into a Completable.

maxConcurrency - Maximum active Completables at any time.

maxDelayedErrorsHint - The maximum amount of errors that will be queued. After this point exceptions maybe discarded to reduce memory consumption.

Returns:

A new Completable that terminates successfully if all the intermediate Completables have terminated successfully or any one of them has terminated with a failure.

See Also:

• ReactiveX flatMap operator.
• flatMapMergeSingleDelayError(Function, int)

flatMapConcatSingle

public final <R> Publisher<R> flatMapConcatSingle(Function<? super T,? extends Single<? extends R>> mapper)

This method is similar to map(Function) but the result is asynchronous. More specifically, map each element of this Publisher into a Single<Publisher> and flatten all signals emitted from each mapped Single<Publisher> into the returned Publisher<Publisher>. Each mapped Single<Publisher> maybe subscribed to concurrently but the results are emitted in the same order as this Publisher.

To control the amount of concurrent processing done by this operator see flatMapConcatSingle(Function, int).

Provides a data transformation in sequential programming similar to:

     ExecutorService e = ...;
     List<Future<R>> futures = ...; // assume this is thread safe
     for (T t : resultOfThisPublisher()) {
         // Note that flatMap process results in parallel.
         futures.add(e.submit(() -> {
             return mapper.apply(t); // Asynchronous result is flatten into a value by this operator.
         }));
     }
     for (Future<R> future : futures) {
         processResult(future.get()); // Throws if the processing for this item failed.
     }
 

Type Parameters:

R - Type of items emitted by the returned Publisher.

Parameters:

mapper - Function to convert each item emitted by this Publisher into a Single.

Returns:

A new Publisher that emits all items emitted by each single produced by mapper.

See Also:

• ReactiveX flatMap operator.
• flatMapConcatSingle(Function, int)
• flatMapMergeSingle(Function)

flatMapConcatSingle

public final <R> Publisher<R> flatMapConcatSingle(Function<? super T,? extends Single<? extends R>> mapper,
 int maxConcurrency)

This method is similar to map(Function) but the result is asynchronous. More specifically, map each element of this Publisher into a Single<Publisher> and flatten all signals emitted from each mapped Single<Publisher> into the returned Publisher<Publisher>. Each mapped Single<Publisher> maybe subscribed to concurrently but the results are emitted in the same order as this Publisher.

Provides a data transformation in sequential programming similar to:

     ExecutorService e = ...;
     List<Future<R>> futures = ...; // assume this is thread safe
     for (T t : resultOfThisPublisher()) {
         // Note that flatMap process results in parallel.
         futures.add(e.submit(() -> {
             return mapper.apply(t); // Asynchronous result is flatten into a value by this operator.
         }));
     }
     for (Future<R> future : futures) {
         processResult(future.get()); // Throws if the processing for this item failed.
     }
 

Type Parameters:

R - Type of items emitted by the returned Publisher.

Parameters:

mapper - Function to convert each item emitted by this Publisher into a Single.

maxConcurrency - Maximum active Singles at any time. Even if the number of items requested by a PublisherSource.Subscriber is more than this number, this will never request more than this number at any point.

Returns:

A new Publisher that emits all items emitted by each single produced by mapper.

See Also:

• ReactiveX flatMap operator.
• flatMapMergeSingle(Function, int)

flatMapConcatSingleDelayError

public final <R> Publisher<R> flatMapConcatSingleDelayError(Function<? super T,? extends Single<? extends R>> mapper)

This method is similar to map(Function) but the result is asynchronous. More specifically, map each element of this Publisher into a Single<Publisher> and flatten all signals emitted from each mapped Single<Publisher> into the returned Publisher<Publisher>. Each mapped Single<Publisher> maybe subscribed to concurrently but the results are emitted in the same order as this Publisher.

The behavior is the same as flatMapConcatSingle(Function) with the exception that if any Single returned by mapper, terminates with an error, the returned Publisher will not terminate until this Publisher and all Singles to terminate.

Provides a data transformation in sequential programming similar to:

     ExecutorService e = ...;
     List<Future<R>> futures = ...; // assume this is thread safe
     for (T t : resultOfThisPublisher()) {
         // Note that flatMap process results in parallel.
         futures.add(e.submit(() -> {
             return mapper.apply(t); // Asynchronous result is flatten into a value by this operator.
         }));
     }
     List<Throwable> errors = ...;
     for (Future<R> future : futures) {
         try {
           processResult(future.get()); // Throws if the processing for this item failed.
         } catch (Throwable cause) {
           errors.add(cause);
         }
     }
     throwExceptionIfNotEmpty(errors);
 

Type Parameters:

R - Type of items emitted by the returned Publisher.

Parameters:

mapper - Function to convert each item emitted by this Publisher into a Single.

Returns:

A new Publisher that emits all items emitted by each single produced by mapper.

See Also:

• ReactiveX flatMap operator.
• flatMapConcatSingleDelayError(Function, int)
• flatMapMergeSingleDelayError(Function)

flatMapConcatSingleDelayError

public final <R> Publisher<R> flatMapConcatSingleDelayError(Function<? super T,? extends Single<? extends R>> mapper,
 int maxConcurrency)

This method is similar to map(Function) but the result is asynchronous. More specifically, map each element of this Publisher into a Single<Publisher> and flatten all signals emitted from each mapped Single<Publisher> into the returned Publisher<Publisher>. Each mapped Single<Publisher> maybe subscribed to concurrently but the results are emitted in the same order as this Publisher.

The behavior is the same as flatMapConcatSingle(Function) with the exception that if any Single returned by mapper, terminates with an error, the returned Publisher will not terminate until this Publisher and all Singles to terminate.

Provides a data transformation in sequential programming similar to:

     ExecutorService e = ...;
     List<Future<R>> futures = ...; // assume this is thread safe
     for (T t : resultOfThisPublisher()) {
         // Note that flatMap process results in parallel.
         futures.add(e.submit(() -> {
             return mapper.apply(t); // Asynchronous result is flatten into a value by this operator.
         }));
     }
     List<Throwable> errors = ...;
     for (Future<R> future : futures) {
         try {
           processResult(future.get()); // Throws if the processing for this item failed.
         } catch (Throwable cause) {
           errors.add(cause);
         }
     }
     throwExceptionIfNotEmpty(errors);
 

Type Parameters:

R - Type of items emitted by the returned Publisher.

Parameters:

mapper - Function to convert each item emitted by this Publisher into a Single.

maxConcurrency - Maximum active Singles at any time. Even if the number of items requested by a PublisherSource.Subscriber is more than this number, this will never request more than this number at any point.

Returns:

A new Publisher that emits all items emitted by each single produced by mapper.

See Also:

• ReactiveX flatMap operator.
• flatMapMergeSingleDelayError(Function, int)

flatMapConcatIterable

public final <R> Publisher<R> flatMapConcatIterable(Function<? super T,? extends Iterable<? extends R>> mapper)

Create a Publisher that flattens each element returned by the Iterable.iterator() from mapper.

The mapper Function will only be called when the previously returned Iterator has returned false from Iterator.hasNext().

This method provides similar capabilities as expanding each result into a collection and concatenating each collection in sequential programming:

     List<R> results = ...;
     for (T t : resultOfThisPublisher()) {
         Iterable<? extends R> itr = mapper.apply(t);
         itr.forEach(results::add);
     }
     return results;
 

Type Parameters:

R - The elements returned by the Iterable.

Parameters:

mapper - A Function that returns an Iterable for each element.

Returns:

a Publisher that flattens each element returned by the Iterable.iterator() from mapper. The results will be sequential for each Iterator, and overall for all calls to Iterable.iterator()

switchMap

public final <R> Publisher<R> switchMap(Function<? super T,? extends Publisher<? extends R>> mapper)

Return a Publisher that will switch to the latest Publisher emitted from mapper and the prior Publisher will be cancelled. Both upstream and the last switched Publisher must complete before the returned Publisher completes. If either upstream or the currently active Publisher terminate in error the returned Publisher is terminated with that error.

     ExecutorService e = ...;
     List<Future<List<R>>> futures = ...; // assume this is thread safe

     for (T t : resultOfThisPublisher()) {
         // Note that flatMap process results in parallel.
         futures.add(e.submit(() -> {
             // Approximation: control flow is simplified here but when a later mapper is applied any incomplete
             // results from a previous mapper are cancelled and result in empty results.
             return mapper.apply(t); // Asynchronous result is flatten into a value by this operator.
         }));
     }
     List<R> results = new ArrayList<>(futures.size());
     // This is an approximation, this operator does not provide any ordering guarantees for the results.
     for (Future<List<R>> future : futures) {
         List<R> rList = future.get(); // Throws if the processing for this item failed.
         results.addAll(rList);
     }
     return results;
 

Type Parameters:

R - The type of mapped Publisher.

Parameters:

mapper - Convert each item emitted by this Publisher into another Publisher.

Returns:

A Publisher that will switch to the latest Publisher emitted from mapper and the prior Publisher will be cancelled.

See Also:

• ReactiveX switch operator.
• Kotlin flatMapLatest
• switchMapDelayError(Function)

switchMapDelayError

public final <R> Publisher<R> switchMapDelayError(Function<? super T,? extends Publisher<? extends R>> mapper)

Return a Publisher that will switch to the latest Publisher emitted from mapper and the prior Publisher will be cancelled. Both upstream and the last switched Publisher must terminate before the returned Publisher terminates (including errors).

Type Parameters:

R - The type of mapped Publisher.

Parameters:

mapper - Convert each item emitted by this Publisher into another Publisher.

Returns:

A Publisher that will switch to the latest Publisher emitted from mapper and the prior Publisher will be cancelled.

See Also:

• ReactiveX switch operator.
• Kotlin flatMapLatest
• switchMap(Function)
• switchMapDelayError(Function, int)

switchMapDelayError

public final <R> Publisher<R> switchMapDelayError(Function<? super T,? extends Publisher<? extends R>> mapper,
 int maxDelayedErrorsHint)

Return a Publisher that will switch to the latest Publisher emitted from mapper and the prior Publisher will be cancelled. Both upstream and the last switched Publisher must terminate before the returned Publisher terminates (including errors).

Type Parameters:

R - The type of mapped Publisher.

Parameters:

mapper - Convert each item emitted by this Publisher into another Publisher.

maxDelayedErrorsHint - The maximum amount of errors that will be queued. After this point exceptions maybe discarded to reduce memory consumption.

Returns:

A Publisher that will switch to the latest Publisher emitted from mapper and the prior Publisher will be cancelled.

See Also:

• ReactiveX switch operator.
• Kotlin flatMapLatest
• switchMap(Function)
• switchMapDelayError(Function)

merge

public final Publisher<T> merge(Publisher<? extends T> other)

Merge two Publishers together. There is no guaranteed ordering of events emitted from the returned Publisher.

This method provides similar capabilities as expanding each result into a collection and concatenating each collection in sequential programming:

     List<T> mergedResults = ...; // concurrent safe list
     for (T t : resultOfThisPublisher()) {
         futures.add(e.submit(() -> {
             return mergedResults.add(t);
         }));
     }
     for (T t : resultOfOtherPublisher()) {
         futures.add(e.submit(() -> {
             return mergedResults.add(t);
         }));
     }
     for (Future<R> future : futures) {
         future.get(); // Throws if the processing for this item failed.
     }
     return mergedResults;
 

Parameters:

other - The Publisher to merge with.

Returns:

A Publisher which is the result of this Publisher and other merged together.

See Also:

• ReactiveX merge operator
• mergeDelayError(Publisher)
• mergeAll(Publisher[])

mergeDelayError

public final Publisher<T> mergeDelayError(Publisher<? extends T> other)

Merge two Publishers together. There is no guaranteed ordering of events emitted from the returned Publisher. If either Publisher fails the error propagation will be delayed until both terminate.

This method provides similar capabilities as expanding each result into a collection and concatenating each collection in sequential programming:

     List<T> mergedResults = ...; // concurrent safe list
     for (T t : resultOfThisPublisher()) {
         futures.add(e.submit(() -> {
             return mergedResults.add(t);
         }));
     }
     for (T t : resultOfOtherPublisher()) {
         futures.add(e.submit(() -> {
             return mergedResults.add(t);
         }));
     }
     List<Throwable> errors = ...;
     for (Future<R> future : futures) {
         try {
           future.get(); // Throws if the processing for this item failed.
         } catch (Throwable cause) {
           errors.add(cause);
         }
     }
     throwExceptionIfNotEmpty(errors);
     return mergedResults;
 

Parameters:

other - The Publisher to merge with,

Returns:

A Publisher which is the result of this Publisher and other merged together.

See Also:

• ReactiveX merge operator
• merge(Publisher)
• mergeAllDelayError(Publisher[])

whenOnSubscribe

public final Publisher<T> whenOnSubscribe(Consumer<? super PublisherSource.Subscription> onSubscribe)

Invokes the onSubscribe Consumer argument when PublisherSource.Subscriber.onSubscribe(PublisherSource.Subscription) is called for PublisherSource.Subscribers of the returned Publisher.

The order in which onSubscribe will be invoked relative to PublisherSource.Subscriber.onSubscribe(PublisherSource.Subscription) is undefined. If you need strict ordering see beforeOnSubscribe(Consumer) and afterOnSubscribe(Consumer).

Parameters:

onSubscribe - Invoked when PublisherSource.Subscriber.onSubscribe(PublisherSource.Subscription) is called for PublisherSource.Subscribers of the returned Publisher. MUST NOT throw.

Returns:

The new Publisher.

See Also:

• beforeOnNext(Consumer)
• afterOnNext(Consumer)

whenOnNext

public final Publisher<T> whenOnNext(Consumer<? super T> onNext)

Invokes the onNext Consumer argument when PublisherSource.Subscriber.onNext(Object) is called for PublisherSource.Subscribers of the returned Publisher.

The order in which onNext will be invoked relative to PublisherSource.Subscriber.onNext(Object) is undefined. If you need strict ordering see beforeOnNext(Consumer) and afterOnNext(Consumer).

From a sequential programming point of view this method is roughly equivalent to the following:

  for (T t: resultOfThisPublisher()) {
      // NOTE: The order of operations here is not guaranteed by this method!
      processNext(t);
      onNext.accept(t);
  }
 

Parameters:

onNext - Invoked when PublisherSource.Subscriber.onNext(Object) is called for PublisherSource.Subscribers of the returned Publisher. MUST NOT throw.

Returns:

The new Publisher.

See Also:

• beforeOnNext(Consumer)
• afterOnNext(Consumer)

whenOnComplete

public final Publisher<T> whenOnComplete(Runnable onComplete)

Invokes the onComplete Runnable argument when PublisherSource.Subscriber.onComplete() is called for PublisherSource.Subscribers of the returned Publisher.

The order in which onComplete will be invoked relative to PublisherSource.Subscriber.onComplete() is undefined. If you need strict ordering see beforeOnComplete(Runnable) and afterOnComplete(Runnable).

From a sequential programming point of view this method is roughly equivalent to the following:

  List<T> results = resultOfThisPublisher();
  // NOTE: The order of operations here is not guaranteed by this method!
  onSuccess.accept(results);
  nextOperation(results);
 

Parameters:

onComplete - Invoked when PublisherSource.Subscriber.onComplete() is called for PublisherSource.Subscribers of the returned Publisher. MUST NOT throw.

Returns:

The new Publisher.

See Also:

• beforeOnComplete(Runnable)
• afterOnComplete(Runnable)

whenOnError

public final Publisher<T> whenOnError(Consumer<Throwable> onError)

Invokes the onError Consumer argument when PublisherSource.Subscriber.onError(Throwable) is called for PublisherSource.Subscribers of the returned Publisher.

The order in which onError will be invoked relative to PublisherSource.Subscriber.onError(Throwable) is undefined. If you need strict ordering see beforeOnError(Consumer) and afterOnError(Consumer).

From a sequential programming point of view this method is roughly equivalent to the following:

  try {
    List<T> results = resultOfThisPublisher();
  } catch (Throwable cause) {
      // NOTE: The order of operations here is not guaranteed by this method!
      nextOperation(cause);
      onError.accept(cause);
  }
 

Parameters:

onError - Invoked before PublisherSource.Subscriber.onError(Throwable) is called for PublisherSource.Subscribers of the returned Publisher. MUST NOT throw.

Returns:

The new Publisher.

See Also:

• beforeOnError(Consumer)
• afterOnError(Consumer)

whenFinally

public final Publisher<T> whenFinally(Runnable doFinally)

Invokes the whenFinally Runnable argument exactly once, when any of the following terminal methods are called:

• PublisherSource.Subscriber.onComplete()
• PublisherSource.Subscriber.onError(Throwable)
• Cancellable.cancel()

for PublisherSource.Subscriptions/PublisherSource.Subscribers of the returned Publisher.

The order in which whenFinally will be invoked relative to the above methods is undefined. If you need strict ordering see beforeFinally(Runnable) and afterFinally(Runnable).

From a sequential programming point of view this method is roughly equivalent to the following:

  try {
      List<T> results = resultOfThisPublisher();
  } finally {
      // NOTE: The order of operations here is not guaranteed by this method!
      nextOperation(); // Maybe notifying of cancellation, or termination
      doFinally.run();
  }
 

Parameters:

doFinally - Invoked exactly once, when any of the following terminal methods are called:

• PublisherSource.Subscriber.onComplete()
• PublisherSource.Subscriber.onError(Throwable)
• Cancellable.cancel()

for PublisherSource.Subscriptions/PublisherSource.Subscribers of the returned Publisher. MUST NOT throw.

Returns:

The new Publisher.

See Also:

• beforeFinally(Runnable)
• afterFinally(Runnable)

whenFinally

public final Publisher<T> whenFinally(TerminalSignalConsumer doFinally)

Invokes the corresponding method on whenFinally TerminalSignalConsumer argument when any of the following terminal methods are called:

• PublisherSource.Subscriber.onComplete() - invokes TerminalSignalConsumer.onComplete()
• PublisherSource.Subscriber.onError(Throwable) - invokes TerminalSignalConsumer.onError(Throwable)
• Cancellable.cancel() - invokes TerminalSignalConsumer.cancel()

for PublisherSource.Subscriptions/PublisherSource.Subscribers of the returned Publisher.

The order in which whenFinally will be invoked relative to the above methods is undefined. If you need strict ordering see beforeFinally(TerminalSignalConsumer) and afterFinally(TerminalSignalConsumer).

From a sequential programming point of view this method is roughly equivalent to the following:

  try {
      List<T> results = resultOfThisPublisher();
  } catch(Throwable t) {
      // NOTE: The order of operations here is not guaranteed by this method!
      nextOperation(); // Maybe notifying of cancellation, or termination
      doFinally.onError(t);
      return;
  }
  // NOTE: The order of operations here is not guaranteed by this method!
  nextOperation(); // Maybe notifying of cancellation, or termination
  doFinally.onComplete();
 

Parameters:

doFinally - For each subscribe of the returned Publisher, at most one method of this TerminalSignalConsumer will be invoked.

Returns:

The new Publisher.

See Also:

• beforeFinally(TerminalSignalConsumer)
• afterFinally(TerminalSignalConsumer)

whenRequest

public final Publisher<T> whenRequest(LongConsumer onRequest)

Invokes the onRequest LongConsumer argument when PublisherSource.Subscription.request(long) is called for PublisherSource.Subscriptions of the returned Publisher.

Parameters:

onRequest - Invoked when PublisherSource.Subscription.request(long) is called for PublisherSource.Subscriptions of the returned Publisher. MUST NOT throw.

Returns:

The new Publisher.

See Also:

• ReactiveX do operator.

whenCancel

public final Publisher<T> whenCancel(Runnable onCancel)

Invokes the onCancel Runnable argument when Cancellable.cancel() is called for Subscriptions of the returned Publisher.

The order in which whenFinally will be invoked relative to Cancellable.cancel() is undefined. If you need strict ordering see beforeCancel(Runnable) and afterCancel(Runnable).

Parameters:

onCancel - Invoked when Cancellable.cancel() is called for Subscriptions of the returned Publisher. MUST NOT throw.

Returns:

The new Publisher.

See Also:

• beforeCancel(Runnable)
• afterCancel(Runnable)

validateOutstandingDemand

public final Publisher<T> validateOutstandingDemand()

Validate the outstanding demand (PublisherSource.Subscription.request(long) minus PublisherSource.Subscriber.onNext(Object)) does not go negative. This can be a useful diagnostic tool if custom operators or async sources are in use to ensure outstanding demand is always non-negative.

Invalid PublisherSource.Subscription.request(long) maybe propagated by this operator, and is still the responsibility of upstream source to terminate in error.

Here is pseudo-code demonstrating the functionality of this operator:

   request(1);
   onNext(t1);
   onNext(t2); // throws an Exception because outstanding demand is 0
 

Returns:

The new Publisher.

See Also:

• validateOutstandingDemand(ObjLongConsumer, LongBinaryConsumer)

validateOutstandingDemand

public final Publisher<T> validateOutstandingDemand(ObjLongConsumer<T> onNextConsumer,
 LongBinaryConsumer requestConsumer)

Validate the outstanding demand (PublisherSource.Subscription.request(long) minus PublisherSource.Subscriber.onNext(Object)) does not go negative. This can be a useful diagnostic tool if custom operators or async sources are in use to ensure outstanding demand is always non-negative.

ReactiveStreams specification allows PublisherSource.Subscriber and PublisherSource.Subscription to be concurrent, therefore the arguments of this function maybe invoked concurrently.

Invalid PublisherSource.Subscription.request(long) maybe propagated by this operator, and is still the responsibility of upstream source to terminate in error.

Here is pseudo-code demonstrating the functionality of this operator:

   request(1); // calls requestConsumer(1, 1)
   onNext(t1); // calls onNextConsumer(t1, 0)
   onNext(t2); // calls onNextConsumer(t1, -1), throws an Exception because outstanding demand is 0
 

Parameters:

onNextConsumer - Called when PublisherSource.Subscriber.onNext(Object) is invoked with first argument is the signal and second argument is demand (after decrementing). This consumer is meant to be used for observability purposes, and is assumed to not throw.

requestConsumer - Called when PublisherSource.Subscription.request(long) is invoked with first argument of n and second argument of current demand (after incrementing). This method may only be called if n is valid. This consumer is meant to be used for observability purposes, and is assumed to not throw.

Returns:

The new Publisher.

timeout

public final Publisher<T> timeout(long duration,
 TimeUnit unit)

Creates a new Publisher that will mimic the signals of this Publisher but will terminate with a TimeoutException if time duration elapses between adjacent PublisherSource.Subscriber.onNext(Object) calls. The timer starts when the returned Publisher is subscribed.

In the event of timeout any PublisherSource.Subscription from PublisherSource.Subscriber.onSubscribe(PublisherSource.Subscription) will be cancelled and the associated PublisherSource.Subscriber will be terminated.

Parameters:

duration - The time duration which is allowed to elapse between PublisherSource.Subscriber.onNext(Object) calls.

unit - The units for duration.

Returns:

a new Publisher that will mimic the signals of this Publisher but will terminate with a TimeoutException if time duration elapses between PublisherSource.Subscriber.onNext(Object) calls.

See Also:

• ReactiveX timeout operator.
• timeout(long, TimeUnit, io.servicetalk.concurrent.Executor)

timeout

public final Publisher<T> timeout(Duration duration)

Creates a new Publisher that will mimic the signals of this Publisher but will terminate with a TimeoutException if time duration elapses between adjacent PublisherSource.Subscriber.onNext(Object) calls. The timer starts when the returned Publisher is subscribed.

In the event of timeout any PublisherSource.Subscription from PublisherSource.Subscriber.onSubscribe(PublisherSource.Subscription) will be cancelled and the associated PublisherSource.Subscriber will be terminated.

Parameters:

duration - The time duration which is allowed to elapse between PublisherSource.Subscriber.onNext(Object) calls.

Returns:

a new Publisher that will mimic the signals of this Publisher but will terminate with a TimeoutException if time duration elapses between PublisherSource.Subscriber.onNext(Object) calls.

See Also:

• ReactiveX timeout operator.
• timeout(long, TimeUnit, io.servicetalk.concurrent.Executor)

timeout

public final Publisher<T> timeout(long duration,
 TimeUnit unit,
 Executor timeoutExecutor)

Creates a new Publisher that will mimic the signals of this Publisher but will terminate with a TimeoutException if time duration elapses between adjacent PublisherSource.Subscriber.onNext(Object) calls. The timer starts when the returned Publisher is subscribed.

In the event of timeout any PublisherSource.Subscription from PublisherSource.Subscriber.onSubscribe(PublisherSource.Subscription) will be cancelled and the associated PublisherSource.Subscriber will be terminated.

Parameters:

duration - The time duration which is allowed to elapse between PublisherSource.Subscriber.onNext(Object) calls.

unit - The units for duration.

timeoutExecutor - The Executor to use for managing the timer notifications.

Returns:

a new Publisher that will mimic the signals of this Publisher but will terminate with a TimeoutException if time duration elapses between PublisherSource.Subscriber.onNext(Object) calls.

See Also:

• ReactiveX timeout operator.

timeout

public final Publisher<T> timeout(Duration duration,
 Executor timeoutExecutor)

Creates a new Publisher that will mimic the signals of this Publisher but will terminate with a TimeoutException if time duration elapses between adjacent PublisherSource.Subscriber.onNext(Object) calls. The timer starts when the returned Publisher is subscribed.

In the event of timeout any PublisherSource.Subscription from PublisherSource.Subscriber.onSubscribe(PublisherSource.Subscription) will be cancelled and the associated PublisherSource.Subscriber will be terminated.

Parameters:

duration - The time duration which is allowed to elapse between PublisherSource.Subscriber.onNext(Object) calls.

timeoutExecutor - The Executor to use for managing the timer notifications.

Returns:

a new Publisher that will mimic the signals of this Publisher but will terminate with a TimeoutException if time duration elapses between PublisherSource.Subscriber.onNext(Object) calls.

See Also:

• ReactiveX timeout operator.

timeoutTerminal

public final Publisher<T> timeoutTerminal(Duration duration)

Creates a new Publisher that will mimic the signals of this Publisher but will terminate with a TimeoutException if time duration elapses between subscribe and termination. The timer starts when the returned Publisher is subscribed.

In the event of timeout any PublisherSource.Subscription from PublisherSource.Subscriber.onSubscribe(PublisherSource.Subscription) will be cancelled and the associated PublisherSource.Subscriber will be terminated.

Parameters:

duration - The time duration during which the Publisher must complete.

Returns:

a new Publisher that will mimic the signals of this Publisher but will terminate with a TimeoutException if time duration elapses between subscribe and termination.

See Also:

• ReactiveX timeout operator.

timeoutTerminal

public final Publisher<T> timeoutTerminal(Duration duration,
 Executor timeoutExecutor)

Creates a new Publisher that will mimic the signals of this Publisher but will terminate with a TimeoutException if time duration elapses between subscribe and termination. The timer starts when the returned Publisher is subscribed.

In the event of timeout any PublisherSource.Subscription from PublisherSource.Subscriber.onSubscribe(PublisherSource.Subscription) will be cancelled and the associated PublisherSource.Subscriber will be terminated.

Parameters:

duration - The time duration during which the Publisher must complete.

timeoutExecutor - The Executor to use for managing the timer notifications.

Returns:

a new Publisher that will mimic the signals of this Publisher but will terminate with a TimeoutException if time duration elapses between subscribe and termination.

See Also:

• ReactiveX timeout operator.

timeoutTerminal

public final Publisher<T> timeoutTerminal(long duration,
 TimeUnit unit)

Creates a new Publisher that will mimic the signals of this Publisher but will terminate with a TimeoutException if time duration elapses between subscribe and termination. The timer starts when the returned Publisher is subscribed.

In the event of timeout any PublisherSource.Subscription from PublisherSource.Subscriber.onSubscribe(PublisherSource.Subscription) will be cancelled and the associated PublisherSource.Subscriber will be terminated.

Parameters:

duration - The time duration during which the Publisher must complete.

unit - The units for duration.

Returns:

a new Publisher that will mimic the signals of this Publisher but will terminate with a TimeoutException if time duration elapses between subscribe and termination.

See Also:

• ReactiveX timeout operator.

timeoutTerminal

public final Publisher<T> timeoutTerminal(long duration,
 TimeUnit unit,
 Executor timeoutExecutor)

Creates a new Publisher that will mimic the signals of this Publisher but will terminate with a TimeoutException if time duration elapses between subscribe and termination. The timer starts when the returned Publisher is subscribed.

In the event of timeout any PublisherSource.Subscription from PublisherSource.Subscriber.onSubscribe(PublisherSource.Subscription) will be cancelled and the associated PublisherSource.Subscriber will be terminated.

Parameters:

duration - The time duration during which the Publisher must complete.

unit - The units for duration.

timeoutExecutor - The Executor to use for managing the timer notifications.

Returns:

a new Publisher that will mimic the signals of this Publisher but will terminate with a TimeoutException if time duration elapses between subscribe and termination.

See Also:

• ReactiveX timeout operator.

timeoutDemand

public final Publisher<T> timeoutDemand(long duration,
 TimeUnit unit)

Creates a new Publisher that will mimic the signals of this Publisher but will terminate with a TimeoutException if time duration elapses while there is 0 outstanding demand.

In the event of timeout any PublisherSource.Subscription from PublisherSource.Subscriber.onSubscribe(PublisherSource.Subscription) will be cancelled and the associated PublisherSource.Subscriber will be terminated.

Parameters:

duration - The time duration which is allowed to elapse between PublisherSource.Subscriber.onNext(Object) calls.

unit - The units for duration.

Returns:

a new Publisher that will mimic the signals of this Publisher but will terminate with a TimeoutException if time duration elapses between PublisherSource.Subscriber.onNext(Object) calls.

See Also:

• ReactiveX timeout operator.
• timeoutDemand(long, TimeUnit, io.servicetalk.concurrent.Executor)

timeoutDemand

public final Publisher<T> timeoutDemand(long duration,
 TimeUnit unit,
 Executor executor)

Creates a new Publisher that will mimic the signals of this Publisher but will terminate with a TimeoutException if time duration elapses while there is 0 outstanding demand.

In the event of timeout any PublisherSource.Subscription from PublisherSource.Subscriber.onSubscribe(PublisherSource.Subscription) will be cancelled and the associated PublisherSource.Subscriber will be terminated.

Parameters:

duration - The time duration which is allowed to elapse between PublisherSource.Subscriber.onNext(Object) calls.

unit - The units for duration.

executor - The Executor to use for managing the timer notifications.

Returns:

a new Publisher that will mimic the signals of this Publisher but will terminate with a TimeoutException if time duration elapses between PublisherSource.Subscriber.onNext(Object) calls.

See Also:

• ReactiveX timeout operator.

timeoutDemand

public final Publisher<T> timeoutDemand(Duration duration)

Creates a new Publisher that will mimic the signals of this Publisher but will terminate with a TimeoutException if time duration elapses while there is 0 outstanding demand.

In the event of timeout any PublisherSource.Subscription from PublisherSource.Subscriber.onSubscribe(PublisherSource.Subscription) will be cancelled and the associated PublisherSource.Subscriber will be terminated.

Parameters:

duration - The time duration which is allowed to elapse between PublisherSource.Subscriber.onNext(Object) calls.

Returns:

a new Publisher that will mimic the signals of this Publisher but will terminate with a TimeoutException if time duration elapses between PublisherSource.Subscriber.onNext(Object) calls.

See Also:

• ReactiveX timeout operator.
• timeoutDemand(Duration, io.servicetalk.concurrent.Executor)

timeoutDemand

public final Publisher<T> timeoutDemand(Duration duration,
 Executor executor)

Creates a new Publisher that will mimic the signals of this Publisher but will terminate with a TimeoutException if time duration elapses while there is 0 outstanding demand.

In the event of timeout any PublisherSource.Subscription from PublisherSource.Subscriber.onSubscribe(PublisherSource.Subscription) will be cancelled and the associated PublisherSource.Subscriber will be terminated.

Parameters:

duration - The time duration which is allowed to elapse between PublisherSource.Subscriber.onNext(Object) calls.

executor - The Executor to use for managing the timer notifications.

Returns:

a new Publisher that will mimic the signals of this Publisher but will terminate with a TimeoutException if time duration elapses between PublisherSource.Subscriber.onNext(Object) calls.

See Also:

• ReactiveX timeout operator.

concat

public final Publisher<T> concat(Publisher<? extends T> next)

Emits items emitted by next Publisher after this Publisher terminates successfully.

This method provides a means to sequence the execution of two asynchronous sources and in sequential programming is similar to:

     List<T> results = resultOfThisPublisher();
     results.addAll(resultOfPublisher(next));
     return results;
 

Parameters:

next - Publisher's items that are emitted after this Publisher terminates successfully.

Returns:

A Publisher that emits all items from this Publisher and next Publisher.

See Also:

• ReactiveX concat operator.

concat

public final Publisher<T> concat(Single<? extends T> next)

Listens and emits the result of next Single after this Publisher terminates successfully.

This method provides a means to sequence the execution of two asynchronous sources and in sequential programming is similar to:

     List<T> results = resultOfThisPublisher();
     results.add(resultOfSingle(next));
     return results;
 

Parameters:

next - Single's result that is emitted after this Publisher terminates successfully.

Returns:

A Publisher that emits all items from this Publisher and the result of next Single.

See Also:

• ReactiveX concat operator.

concat

public final Publisher<T> concat(Completable next)

Listens for completion of next Completable after this Publisher terminates successfully. Any error from this Publisher and next Completable is forwarded to the returned Publisher.

This method provides a means to sequence the execution of two asynchronous sources and in sequential programming is similar to:

     List<T> results = resultOfThisPublisher();
     resultOfCompletable(next);
     return results;
 

Parameters:

next - Completable to wait for completion after this Publisher terminates successfully.

Returns:

A Publisher that emits all items from this Publisher and then awaits successful completion of next Completable.

See Also:

• ReactiveX concat operator.
• concatPropagateCancel(Completable)

concatPropagateCancel

public final Publisher<T> concatPropagateCancel(Completable next)

This method is like concat(Completable) except next will be subscribed to and cancelled if this Publisher is cancelled or terminates with PublisherSource.Subscriber.onError(Throwable).

This method provides a means to sequence the execution of two asynchronous sources and in sequential programming is similar to:

     List<T> results = resultOfThisPublisher();
     resultOfCompletable(next);
     return results;
 

Parameters:

next - Completable to wait for completion after this Publisher terminates successfully. Will be subscribed to and cancelled if this Publisher is cancelled or terminates with PublisherSource.Subscriber.onError(Throwable).

Returns:

A Publisher that emits all items from this Publisher and then awaits successful completion of next Completable.

See Also:

• ReactiveX concat operator.
• concat(Completable)

retry

public final Publisher<T> retry(BiIntPredicate<Throwable> shouldRetry)

Re-subscribes to this Publisher if an error is emitted and the passed BiIntPredicate returns true.

 This method may result in a StackOverflowError if too many consecutive calls are made. This can be
 avoided by trampolining the call stack onto an Executor. For example:
   retryWhen((i, cause) -> i % 10 == 0 ? executor.submit(() -> { }) : Completable.completed())
 

This method provides a means to retry an operation under certain failure conditions and in sequential programming is similar to:

     public List<T> execute() {
         List<T> results = ...;
         return execute(0, results);
     }

     private List<T> execute(int attempts, List<T> results) {
         try {
             Iterator<T> itr = resultOfThisPublisher();
             while (itr.hasNext()) {
                 T t = itr.next(); // Any iteration with the Iterator may throw
                 results.add(t);
             }
             return results;
         } catch (Throwable cause) {
             if (shouldRetry.apply(attempts + 1, cause)) {
                 return execute(attempts + 1, results);
             } else {
                 throw cause;
             }
         }
     }
 

Parameters:

shouldRetry - BiIntPredicate that given the retry count and the most recent Throwable emitted from this Publisher determines if the operation should be retried.

Returns:

A Publisher that emits all items from this Publisher and re-subscribes if an error is emitted if the passed BiIntPredicate returned true.

See Also:

• ReactiveX retry operator.
• retry(boolean, BiIntPredicate)

retry

public final Publisher<T> retry(boolean terminateOnNextException,
 BiIntPredicate<Throwable> shouldRetry)

Re-subscribes to this Publisher if an error is emitted and the passed BiIntPredicate returns true.

 This method may result in a StackOverflowError if too many consecutive calls are made. This can be
 avoided by trampolining the call stack onto an Executor. For example:
   retryWhen((i, cause) -> i % 10 == 0 ? executor.submit(() -> { }) : Completable.completed())
 

This method provides a means to retry an operation under certain failure conditions and in sequential programming is similar to:

     public List<T> execute() {
         List<T> results = ...;
         return execute(0, results);
     }

     private List<T> execute(int attempts, List<T> results) {
         try {
             Iterator<T> itr = resultOfThisPublisher();
             while (itr.hasNext()) {
                 T t = itr.next(); // Any iteration with the Iterator may throw
                 results.add(t);
             }
             return results;
         } catch (Throwable cause) {
             if (!terminateOnNextException && shouldRetry.apply(attempts + 1, cause)) {
                 return execute(attempts + 1, results);
             } else {
                 throw cause;
             }
         }
     }
 

Parameters:

terminateOnNextException -

• true means that exceptions thrown from downstream PublisherSource.Subscriber.onNext(Object) will be caught, cancel the PublisherSource.Subscription, propagate a PublisherSource.Subscriber.onError(Throwable) downstream, and no retry will be attempted.
• false means that exceptions thrown from downstream PublisherSource.Subscriber.onNext(Object) will NOT be caught and will propagate upstream. May lead to incorrect demand accounting and "hangs" if this operator isn't the last in the chain.

shouldRetry - BiIntPredicate that given the retry count and the most recent Throwable emitted from this Publisher determines if the operation should be retried.

Returns:

A Publisher that emits all items from this Publisher and re-subscribes if an error is emitted if the passed BiIntPredicate returned true.

See Also:

• ReactiveX retry operator.

retryWhen

public final Publisher<T> retryWhen(BiIntFunction<Throwable,? extends Completable> retryWhen)

Re-subscribes to this Publisher if an error is emitted and the Completable returned by the supplied BiIntFunction completes successfully. If the returned Completable emits an error, the returned Publisher terminates with that error.

 This method may result in a StackOverflowError if too many consecutive calls are made. This can be
 avoided by trampolining the call stack onto an Executor. For example:
   retryWhen((i, cause) -> i % 10 == 0 ? executor.submit(() -> { }) : Completable.completed())
 

This method provides a means to retry an operation under certain failure conditions in an asynchronous fashion and in sequential programming is similar to:

     public List<T> execute() {
         List<T> results = ...;
         return execute(0, results);
     }

     private List<T> execute(int attempts, List<T> results) {
         try {
             Iterator<T> itr = resultOfThisPublisher();
             while (itr.hasNext()) {
                 T t = itr.next(); // Any iteration with the Iterator may throw
                 results.add(t);
             }
             return results;
         } catch (Throwable cause) {
             try {
                 shouldRetry.apply(attempts + 1, cause); // Either throws or completes normally
                 execute(attempts + 1, results);
             } catch (Throwable ignored) {
                 throw cause;
             }
         }
     }
 

Parameters:

retryWhen - BiIntFunction that given the retry count and the most recent Throwable emitted from this Publisher returns a Completable. If this Completable emits an error, that error is emitted from the returned Publisher, otherwise, original Publisher is re-subscribed when this Completable completes.

Returns:

A Publisher that emits all items from this Publisher and re-subscribes if an error is emitted and Completable returned by BiIntFunction completes successfully.

See Also:

• ReactiveX retry operator.
• retryWhen(boolean, BiIntFunction)

retryWhen

public final Publisher<T> retryWhen(boolean terminateOnNextException,
 BiIntFunction<Throwable,? extends Completable> retryWhen)

Re-subscribes to this Publisher if an error is emitted and the Completable returned by the supplied BiIntFunction completes successfully. If the returned Completable emits an error, the returned Publisher terminates with that error.

 This method may result in a StackOverflowError if too many consecutive calls are made. This can be
 avoided by trampolining the call stack onto an Executor. For example:
   retryWhen((i, cause) -> i % 10 == 0 ? executor.submit(() -> { }) : Completable.completed())
 

This method provides a means to retry an operation under certain failure conditions in an asynchronous fashion and in sequential programming is similar to:

     public List<T> execute() {
         List<T> results = ...;
         return execute(0, results);
     }

     private List<T> execute(int attempts, List<T> results) {
         try {
             Iterator<T> itr = resultOfThisPublisher();
             while (itr.hasNext()) {
                 T t = itr.next(); // Any iteration with the Iterator may throw
                 results.add(t);
             }
             return results;
         } catch (Throwable cause) {
             if (terminateOnNextException) {
               throw cause;
             }
             try {
                 shouldRetry.apply(attempts + 1, cause); // Either throws or completes normally
                 execute(attempts + 1, results);
             } catch (Throwable ignored) {
                 throw cause;
             }
         }
     }
 

Parameters:

terminateOnNextException -

• true means that exceptions thrown from downstream PublisherSource.Subscriber.onNext(Object) will be caught, cancel the PublisherSource.Subscription, propagate a PublisherSource.Subscriber.onError(Throwable) downstream, and no retry will be attempted.
• false means that exceptions thrown from downstream PublisherSource.Subscriber.onNext(Object) will NOT be caught and will propagate upstream. May lead to incorrect demand accounting and "hangs" if this operator isn't the last in the chain.

retryWhen - BiIntFunction that given the retry count and the most recent Throwable emitted from this Publisher returns a Completable. If this Completable emits an error, that error is emitted from the returned Publisher, otherwise, original Publisher is re-subscribed when this Completable completes.

Returns:

A Publisher that emits all items from this Publisher and re-subscribes if an error is emitted and Completable returned by BiIntFunction completes successfully.

See Also:

• ReactiveX retry operator.

repeat

public final Publisher<T> repeat(IntPredicate shouldRepeat)

Re-subscribes to this Publisher when it completes and the passed IntPredicate returns true.

 This method may result in a StackOverflowError if too many consecutive calls are made. This can be
 avoided by trampolining the call stack onto an Executor. For example:
   repeatWhen(i -> i % 10 == 0 ? executor.submit(() -> { }) : Completable.completed())
 

This method provides a means to repeat an operation multiple times and in sequential programming is similar to:

     List<T> results = new ...;
     int i = 0;
     do {
         results.addAll(resultOfThisPublisher());
     } while (shouldRepeat.test(++i));
     return results;
 

Parameters:

shouldRepeat - IntPredicate that given the repeat count determines if the operation should be repeated.

Returns:

A Publisher that emits all items from this Publisher and re-subscribes when it completes if the passed IntPredicate returns true.

See Also:

• ReactiveX repeat operator.

repeatWhen

public final Publisher<T> repeatWhen(IntFunction<? extends Completable> repeatWhen)

Re-subscribes to this Publisher when it completes and the Completable returned by the supplied IntFunction completes successfully. If the returned Completable emits an error, the returned Publisher is completed.

 This method may result in a StackOverflowError if too many consecutive calls are made. This can be
 avoided by trampolining the call stack onto an Executor. For example:
   repeatWhen(i -> i % 10 == 0 ? executor.submit(() -> { }) : Completable.completed())
 

This method provides a means to repeat an operation multiple times when in an asynchronous fashion and in sequential programming is similar to:

     List<T> results = new ...;
     int i = 0;
     while (true) {
         results.addAll(resultOfThisPublisher());
         try {
             repeatWhen.apply(++i); // Either throws or completes normally
         } catch (Throwable cause) {
             break;
         }
     }
     return results;
 

Parameters:

repeatWhen - IntFunction that given the repeat count returns a Completable. If this Completable emits an error repeat is terminated, otherwise, original Publisher is re-subscribed when this Completable completes.

Returns:

A Publisher that emits all items from this Publisher and re-subscribes if an error is emitted and Completable returned by IntFunction completes successfully.

See Also:

• ReactiveX retry operator.

skipWhile

public final Publisher<T> skipWhile(Predicate<? super T> predicate)

Skip items emitted by this Publisher until the first time the predicate is not satisfied.

This method provides a data transformation in sequential programming similar to:

     List<T> results = ...;
     boolean skipping = true;
     for (T t : resultOfThisPublisher()) {
         if (skipping) {
             skipping = predicate.test(t);
         }
         if (!skipping) {
             results.add(t);
         }
     }
     return results;
 

Parameters:

predicate - for evaluating whether to continue skipping items.

Returns:

A Publisher that skips items until the predicate returns false predicate.

See Also:

• ReactiveX SkipWhile operator.

takeAtMost

public final Publisher<T> takeAtMost(long numElements)

Takes at most numElements elements from this Publisher.

If no terminal event is received before receiving numElements elements, PublisherSource.Subscription for the PublisherSource.Subscriber is cancelled.

This method provides a means to take a limited number of results from this Publisher and in sequential programming is similar to:

     List<T> results = ...;
     int i = 0;
     for (T t : resultOfThisPublisher()) {
         if (++i > numElements) {
             break;
         }
         results.add(t);
     }
     return results;
 

Parameters:

numElements - Number of elements to take.

Returns:

A Publisher that emits at most numElements elements from this Publisher.

See Also:

• ReactiveX take operator.

takeWhile

public final Publisher<T> takeWhile(Predicate<? super T> predicate)

Takes elements while Predicate is true and then cancel PublisherSource.Subscription of this Publisher once it returns false.

This method provides a means to take a limited number of results from this Publisher and in sequential programming is similar to:

     List<T> results = ...;
     for (T t : resultOfThisPublisher()) {
         if (!predicate.test(result)) {
             break;
         }
         results.add(t);
     }
     return results;
 

Parameters:

predicate - Predicate that is checked before emitting any item to a PublisherSource.Subscriber. If this predicate returns true, that item is emitted, else PublisherSource.Subscription is cancelled.

Returns:

A Publisher that only emits the items as long as the Predicate.test(Object) method returns true.

See Also:

• ReactiveX takeWhile operator.

takeUntil

public final Publisher<T> takeUntil(Completable until)

Takes elements until Completable is terminated successfully or with failure.

This method provides a means to take a limited number of results from this Publisher and in sequential programming is similar to:

     List<T> results = ...;
     for (T t : resultOfThisPublisher()) {
         if (isCompleted(until)) {
             break;
         }
         takeResults.add(t);
     }
     return results;
 

Parameters:

until - Completable, termination of which, terminates the returned Publisher. If this Publisher maybe resubscribed the Completable should be also, or use defer(Supplier) to create a new Completable on each subscribe.

Returns:

A Publisher that only emits the items till until Completable is completed.

See Also:

• ReactiveX takeUntil operator.

groupBy

public final <Key>
Publisher<GroupedPublisher<Key,T>> groupBy(Function<? super T,? extends Key> keySelector)

Splits items from this Publisher into dynamically generated GroupedPublishers. Item to group association is done by keySelector Function. If the selector selects a key which is previously seen and its associated PublisherSource.Subscriber has not yet cancelled its PublisherSource.Subscription, this item is sent to that PublisherSource.Subscriber. Otherwise a new GroupedPublisher is created and emitted from the returned Publisher.

Flow control

Multiple PublisherSource.Subscribers (for multiple GroupedPublishers) request items individually from this Publisher. Since, there is no way for a PublisherSource.Subscriber to only request elements for its group, elements requested by one group may end up producing items for a different group, which has not yet requested enough. This will cause items to be queued per group which can not be emitted due to lack of demand. This queue size can be controlled via groupBy(Function, int).

Cancellation

If the PublisherSource.Subscriber of the returned Publisher cancels its PublisherSource.Subscription, and there are no active GroupedPublishers PublisherSource.Subscribers then upstream will be cancelled.

PublisherSource.Subscribers of individual GroupedPublishers can cancel their PublisherSource.Subscriptions at any point. If any new item is emitted for the cancelled GroupedPublisher, a new GroupedPublisher will be emitted from the returned Publisher. Any queued items for a cancelled PublisherSource.Subscriber for a GroupedPublisher will be discarded and hence will not be emitted if the same GroupedPublisher is emitted again.

In sequential programming this is similar to the following:

     Map<Key, List<T>> results = ...;
     for (T t : resultOfThisPublisher()) {
         Key k = keySelector.apply(result);
         List<T> v = results.get(k);
         if (v == null) {
             v = // new List
             results.put(k, v);
         }
         v.add(result);
     }
     return results;
 

Type Parameters:

Key - Type of GroupedPublisher keys.

Parameters:

keySelector - Function to assign an item emitted by this Publisher to a GroupedPublisher.

Returns:

A Publisher that emits GroupedPublishers for new keys as emitted by keySelector Function.

See Also:

• ReactiveX groupBy operator.

groupBy

public final <Key>
Publisher<GroupedPublisher<Key,T>> groupBy(Function<? super T,? extends Key> keySelector,
 int queueLimit)

Splits items from this Publisher into dynamically generated GroupedPublishers. Item to group association is done by keySelector Function. If the selector selects a key which is previously seen and its associated PublisherSource.Subscriber has not yet cancelled its PublisherSource.Subscription, this item is sent to that PublisherSource.Subscriber. Otherwise a new GroupedPublisher is created and emitted from the returned Publisher.

Flow control

Multiple PublisherSource.Subscribers (for multiple GroupedPublishers) request items individually from this Publisher. Since, there is no way for a PublisherSource.Subscriber to only request elements for its group, elements requested by one group may end up producing items for a different group, which has not yet requested enough. This will cause items to be queued per group which can not be emitted due to lack of demand. This queue size can be controlled with the queueLimit argument.

Cancellation

If the PublisherSource.Subscriber of the returned Publisher cancels its PublisherSource.Subscription, and there are no active GroupedPublishers PublisherSource.Subscribers then upstream will be cancelled.

PublisherSource.Subscribers of individual GroupedPublishers can cancel their PublisherSource.Subscriptions at any point. If any new item is emitted for the cancelled GroupedPublisher, a new GroupedPublisher will be emitted from the returned Publisher. Any queued items for a cancelled PublisherSource.Subscriber for a GroupedPublisher will be discarded and hence will not be emitted if the same GroupedPublisher is emitted again.

In sequential programming this is similar to the following:

     Map<Key, List<T>> results = ...;
     for (T t : resultOfThisPublisher()) {
         Key k = keySelector.apply(result);
         List<T> v = results.get(k);
         if (v == null) {
             v = // new List
             results.put(k, v);
         }
         v.add(result);
     }
     return results;
 

Type Parameters:

Key - Type of GroupedPublisher keys.

Parameters:

keySelector - Function to assign an item emitted by this Publisher to a GroupedPublisher.

queueLimit - The number of elements which will be queued for each grouped PublisherSource.Subscriber in order to compensate for unequal demand. This also applies to the returned Publisher which may also have to queue signals.

Returns:

A Publisher that emits GroupedPublishers for new keys as emitted by keySelector Function.

See Also:

• ReactiveX groupBy operator.

groupBy

public final <Key>
Publisher<GroupedPublisher<Key,T>> groupBy(Function<? super T,? extends Key> keySelector,
 int queueLimit,
 int expectedGroupCountHint)

Splits items from this Publisher into dynamically generated GroupedPublishers. Item to group association is done by keySelector Function. If the selector selects a key which is previously seen and its associated PublisherSource.Subscriber has not yet cancelled its PublisherSource.Subscription, this item is sent to that PublisherSource.Subscriber. Otherwise a new GroupedPublisher is created and emitted from the returned Publisher.

Flow control

Multiple PublisherSource.Subscribers (for multiple GroupedPublishers) request items individually from this Publisher. Since, there is no way for a PublisherSource.Subscriber to only request elements for its group, elements requested by one group may end up producing items for a different group, which has not yet requested enough. This will cause items to be queued per group which can not be emitted due to lack of demand. This queue size can be controlled with the queueLimit argument.

Cancellation

If the PublisherSource.Subscriber of the returned Publisher cancels its PublisherSource.Subscription, and there are no active GroupedPublishers PublisherSource.Subscribers then upstream will be cancelled.

PublisherSource.Subscribers of individual GroupedPublishers can cancel their PublisherSource.Subscriptions at any point. If any new item is emitted for the cancelled GroupedPublisher, a new GroupedPublisher will be emitted from the returned Publisher. Any queued items for a cancelled PublisherSource.Subscriber for a GroupedPublisher will be discarded and hence will not be emitted if the same GroupedPublisher is emitted again.

In sequential programming this is similar to the following:

     Map<Key, List<T>> results = ...;
     for (T t : resultOfThisPublisher()) {
         Key k = keySelector.apply(result);
         List<T> v = results.get(k);
         if (v == null) {
             v = // new List
             results.put(k, v);
         }
         v.add(result);
     }
     return results;
 

Type Parameters:

Key - Type of GroupedPublisher keys.

Parameters:

keySelector - Function to assign an item emitted by this Publisher to a GroupedPublisher.

queueLimit - The number of elements which will be queued for each grouped PublisherSource.Subscriber in order to compensate for unequal demand. This also applies to the returned Publisher which may also have to queue signals.

expectedGroupCountHint - Expected number of groups that would be emitted by this Publisher. This is just a hint for internal data structures and does not have to be precise.

Returns:

A Publisher that emits GroupedPublishers for new keys as emitted by keySelector Function.

See Also:

• ReactiveX groupBy operator.

groupToMany

public final <Key>
Publisher<GroupedPublisher<Key,T>> groupToMany(Function<? super T,? extends Iterator<? extends Key>> keySelector,
 int queueLimit)

The semantics are identical to groupBy(Function, int) except that the keySelector can map each data to multiple keys.

In sequential programming this is similar to the following:

     Map<Key, List<T>> results = ...;
     for (T t : resultOfThisPublisher()) {
         Iterator<Key> keys = keySelector.apply(result);
         for (Key key : keys) {
             List<T> v = results.get(key);
             if (v == null) {
                 v = // new List
                 results.put(key, v);
             }
             v.add(result);
         }
     }
     return results;
 

Type Parameters:

Key - Type of GroupedPublisher keys.

Parameters:

keySelector - Function to assign an item emitted by this Publisher to multiple GroupedPublishers.

queueLimit - The number of elements which will be queued for each grouped PublisherSource.Subscriber in order to compensate for unequal demand. This also applies to the returned Publisher which may also have to queue signals. Publisher returned from this method not requesting enough via PublisherSource.Subscription.request(long).

Returns:

A Publisher that emits GroupedPublishers for new keys as emitted by keySelector Function.

See Also:

• groupBy(Function, int)

groupToMany

public final <Key>
Publisher<GroupedPublisher<Key,T>> groupToMany(Function<? super T,? extends Iterator<? extends Key>> keySelector,
 int queueLimit,
 int expectedGroupCountHint)

The semantics are identical to groupBy(Function, int) except that the keySelector can map each data to multiple keys.

In sequential programming this is similar to the following:

     Map<Key, List<T>> results = ...;
     for (T t : resultOfThisPublisher()) {
         Iterator<Key> keys = keySelector.apply(result);
         for (Key key : keys) {
             List<T> v = results.get(key);
             if (v == null) {
                 v = // new List
                 results.put(key, v);
             }
             v.add(result);
         }
     }
     return results;
 

Type Parameters:

Key - Type of GroupedPublisher keys.

Parameters:

keySelector - Function to assign an item emitted by this Publisher to multiple GroupedPublishers.

queueLimit - The number of elements which will be queued for each grouped PublisherSource.Subscriber in order to compensate for unequal demand. This also applies to the returned Publisher which may also have to queue signals.

expectedGroupCountHint - Expected number of groups that would be emitted by this Publisher. This is just a hint for internal data structures and does not have to be precise.

Returns:

A Publisher that emits GroupedPublishers for new keys as emitted by keySelector Function.

See Also:

• groupBy(Function, int)

multicastToExactly

@Deprecated
public final Publisher<T> multicastToExactly(int expectedSubscribers)

Deprecated.

Use multicast(int).

Create a Publisher that multicasts all the signals to exactly expectedSubscribers.

Depending on PublisherSource.Subscription.request(long) demand it is possible that data maybe queued before being delivered to each PublisherSource.Subscriber! For example if there are 2 PublisherSource.Subscribers and the first calls request(10), and the second only calls request(1), then 9 elements will be queued to deliver to second when more PublisherSource.Subscription.request(long) demand is made.

In sequential programming this is similar to the following:

     List<T> results = resultOfThisPublisher();
     List<List<T>> multiResults = ...;
     for (int i = 0; i < expectedSubscribers; ++i) {
         multiResults.add(results);
     }
     return multiResults;
 

Parameters:

expectedSubscribers - The number of expected subscribe calls required on the returned Publisher before subscribing to this Publisher.

Returns:

a Publisher that allows exactly expectedSubscribers subscribes.

multicastToExactly

@Deprecated
public final Publisher<T> multicastToExactly(int expectedSubscribers,
 int queueLimit)

Deprecated.

Use multicast(int, int).

Create a Publisher that allows exactly expectedSubscribers subscribes. The events from this Publisher object will be delivered to each PublisherSource.Subscriber.

Depending on PublisherSource.Subscription.request(long) demand it is possible that data maybe queued before being delivered to each PublisherSource.Subscriber! For example if there are 2 PublisherSource.Subscribers and the first calls request(10), and the second only calls request(1), then 9 elements will be queued to deliver to second when more PublisherSource.Subscription.request(long) demand is made.

In sequential programming this is similar to the following:

     List<T> results = resultOfThisPublisher();
     List<List<T>> multiResults = ...;
     for (int i = 0; i < expectedSubscribers; ++i) {
         multiResults.add(results);
     }
     return multiResults;
 

Parameters:

expectedSubscribers - The number of expected subscribe calls required on the returned Publisher before subscribing to this Publisher.

queueLimit - The number of elements which will be queued for each PublisherSource.Subscriber in order to compensate for unequal demand.

Returns:

a Publisher that allows exactly expectedSubscribers subscribes.

multicast

public final Publisher<T> multicast(int minSubscribers)

Create a Publisher that subscribes a single time upstream but allows for multiple downstream PublisherSource.Subscribers. Signals from upstream will be multicast to each downstream PublisherSource.Subscriber.

Downstream PublisherSource.Subscribers may subscribe after the upstream subscribe, but signals that were delivered before the downstream PublisherSource.Subscriber subscribed will not be queued.

Upstream outstanding Subscription demand may be limited to provide an upper bound on queue sizes (e.g. demand from downstream PublisherSource.Subscribers will vary). In sequential programming this is similar to the following:

     List<T> results = resultOfThisPublisher();
     List<List<T>> multiResults = ...; // simulating multiple Subscribers
     for (int i = 0; i < expectedSubscribers; ++i) {
         multiResults.add(results);
     }
     return multiResults;
 

Parameters:

minSubscribers - The upstream subscribe operation will not happen until after this many PublisherSource.Subscriber subscribe to the return value.

Returns:

a Publisher that subscribes a single time upstream but allows for multiple downstream PublisherSource.Subscribers. Signals from upstream will be multicast to each downstream PublisherSource.Subscriber.

See Also:

• ReactiveX multicast operator

multicast

public final Publisher<T> multicast(int minSubscribers,
 boolean cancelUpstream)

Create a Publisher that subscribes a single time upstream but allows for multiple downstream PublisherSource.Subscribers. Signals from upstream will be multicast to each downstream PublisherSource.Subscriber.

Downstream PublisherSource.Subscribers may subscribe after the upstream subscribe, but signals that were delivered before the downstream PublisherSource.Subscriber subscribed will not be queued.

Upstream outstanding Subscription demand may be limited to provide an upper bound on queue sizes (e.g. demand from downstream PublisherSource.Subscribers will vary). In sequential programming this is similar to the following:

     List<T> results = resultOfThisPublisher();
     List<List<T>> multiResults = ...; // simulating multiple Subscribers
     for (int i = 0; i < expectedSubscribers; ++i) {
         multiResults.add(results);
     }
     return multiResults;
 

Parameters:

minSubscribers - The upstream subscribe operation will not happen until after this many PublisherSource.Subscriber subscribe to the return value.

cancelUpstream - true if upstream should be cancelled when all downstream PublisherSource.Subscribers cancel. false means that cancel will not be propagated upstream even if all downstream PublisherSource.Subscribers cancel, and the upstream Subscription will stay valid until termination.

Returns:

a Publisher that subscribes a single time upstream but allows for multiple downstream PublisherSource.Subscribers. Signals from upstream will be multicast to each downstream PublisherSource.Subscriber.

See Also:

• ReactiveX multicast operator

multicast

public final Publisher<T> multicast(int minSubscribers,
 int queueLimit)

Create a Publisher that subscribes a single time upstream but allows for multiple downstream PublisherSource.Subscribers. Signals from upstream will be multicast to each downstream PublisherSource.Subscriber.

Downstream PublisherSource.Subscribers may subscribe after the upstream subscribe, but signals that were delivered before the downstream PublisherSource.Subscriber subscribed will not be queued.

Upstream outstanding Subscription demand may be limited to provide an upper bound on queue sizes (e.g. demand from downstream PublisherSource.Subscribers will vary). In sequential programming this is similar to the following:

     List<T> results = resultOfThisPublisher();
     List<List<T>> multiResults = ...; // simulating multiple Subscribers
     for (int i = 0; i < expectedSubscribers; ++i) {
         multiResults.add(results);
     }
     return multiResults;
 

Parameters:

minSubscribers - The upstream subscribe operation will not happen until after this many PublisherSource.Subscriber subscribe to the return value.

queueLimit - The number of elements which will be queued for each PublisherSource.Subscriber in order to compensate for unequal demand.

Returns:

a Publisher that subscribes a single time upstream but allows for multiple downstream PublisherSource.Subscribers. Signals from upstream will be multicast to each downstream PublisherSource.Subscriber.

See Also:

• ReactiveX multicast operator

multicast

public final Publisher<T> multicast(int minSubscribers,
 int queueLimit,
 boolean cancelUpstream)

Create a Publisher that subscribes a single time upstream but allows for multiple downstream PublisherSource.Subscribers. Signals from upstream will be multicast to each downstream PublisherSource.Subscriber.

Downstream PublisherSource.Subscribers may subscribe after the upstream subscribe, but signals that were delivered before the downstream PublisherSource.Subscriber subscribed will not be queued.

Upstream outstanding Subscription demand may be limited to provide an upper bound on queue sizes (e.g. demand from downstream PublisherSource.Subscribers will vary). In sequential programming this is similar to the following:

     List<T> results = resultOfThisPublisher();
     List<List<T>> multiResults = ...; // simulating multiple Subscribers
     for (int i = 0; i < expectedSubscribers; ++i) {
         multiResults.add(results);
     }
     return multiResults;
 

Parameters:

minSubscribers - The upstream subscribe operation will not happen until after this many PublisherSource.Subscriber subscribe to the return value.

queueLimit - The number of elements which will be queued for each PublisherSource.Subscriber in order to compensate for unequal demand.

cancelUpstream - true if upstream should be cancelled when all downstream PublisherSource.Subscribers cancel.false means that cancel will not be propagated upstream even if all downstream PublisherSource.Subscribers cancel, and the upstream Subscription will stay valid until termination.

Returns:

a Publisher that subscribes a single time upstream but allows for multiple downstream PublisherSource.Subscribers. Signals from upstream will be multicast to each downstream PublisherSource.Subscriber.

See Also:

• ReactiveX multicast operator

multicast

public final Publisher<T> multicast(int minSubscribers,
 int queueLimit,
 Function<Throwable,Completable> terminalResubscribe)

Create a Publisher that subscribes a single time upstream but allows for multiple downstream PublisherSource.Subscribers. Signals from upstream will be multicast to each downstream PublisherSource.Subscriber.

Downstream PublisherSource.Subscribers may subscribe after the upstream subscribe, but signals that were delivered before the downstream PublisherSource.Subscriber subscribed will not be queued.

Upstream outstanding Subscription demand may be limited to provide an upper bound on queue sizes (e.g. demand from downstream PublisherSource.Subscribers will vary). In sequential programming this is similar to the following:

     List<T> results = resultOfThisPublisher();
     List<List<T>> multiResults = ...; // simulating multiple Subscribers
     for (int i = 0; i < expectedSubscribers; ++i) {
         multiResults.add(results);
     }
     return multiResults;
 

Parameters:

minSubscribers - The upstream subscribe operation will not happen until after this many PublisherSource.Subscriber subscribe to the return value.

queueLimit - The number of elements which will be queued for each PublisherSource.Subscriber in order to compensate for unequal demand.

terminalResubscribe - A Function that is invoked when a terminal signal arrives from upstream, and returns a Completable whose termination resets the state of the returned Publisher and allows for downstream resubscribing. The argument to this function is as follows:

• null if upstream terminates with PublisherSource.Subscriber.onComplete()
• otherwise the Throwable from PublisherSource.Subscriber.onError(Throwable)

Returns:

a Publisher that subscribes a single time upstream but allows for multiple downstream PublisherSource.Subscribers. Signals from upstream will be multicast to each downstream PublisherSource.Subscriber.

See Also:

• ReactiveX multicast operator

multicast

public final Publisher<T> multicast(int minSubscribers,
 int queueLimit,
 boolean cancelUpstream,
 Function<Throwable,Completable> terminalResubscribe)

Create a Publisher that subscribes a single time upstream but allows for multiple downstream PublisherSource.Subscribers. Signals from upstream will be multicast to each downstream PublisherSource.Subscriber.

Downstream PublisherSource.Subscribers may subscribe after the upstream subscribe, but signals that were delivered before the downstream PublisherSource.Subscriber subscribed will not be queued.

Upstream outstanding Subscription demand may be limited to provide an upper bound on queue sizes (e.g. demand from downstream PublisherSource.Subscribers will vary). In sequential programming this is similar to the following:

     List<T> results = resultOfThisPublisher();
     List<List<T>> multiResults = ...; // simulating multiple Subscribers
     for (int i = 0; i < expectedSubscribers; ++i) {
         multiResults.add(results);
     }
     return multiResults;
 

Parameters:

minSubscribers - The upstream subscribe operation will not happen until after this many PublisherSource.Subscriber subscribe to the return value.

queueLimit - The number of elements which will be queued for each PublisherSource.Subscriber in order to compensate for unequal demand.

cancelUpstream - true if upstream should be cancelled when all downstream PublisherSource.Subscribers cancel. false means that cancel will not be propagated upstream even if all downstream PublisherSource.Subscribers cancel, and the upstream Subscription will stay valid until termination.

terminalResubscribe - A Function that is invoked when a terminal signal arrives from upstream, and returns a Completable whose termination resets the state of the returned Publisher and allows for downstream resubscribing. The argument to this function is as follows:

• null if upstream terminates with PublisherSource.Subscriber.onComplete()
• otherwise the Throwable from PublisherSource.Subscriber.onError(Throwable)

Returns:

a Publisher that subscribes a single time upstream but allows for multiple downstream PublisherSource.Subscribers. Signals from upstream will be multicast to each downstream PublisherSource.Subscriber.

See Also:

• ReactiveX multicast operator

replay

public final Publisher<T> replay(int history)

Similar to multicast(int) in that multiple downstream PublisherSource.Subscribers are enabled on the returned Publisher but also retains history of the most recently emitted signals from PublisherSource.Subscriber.onNext(Object) which are emitted to new downstream PublisherSource.Subscribers before emitting new signals.

Parameters:

history - max number of signals (excluding PublisherSource.Subscriber.onComplete() and PublisherSource.Subscriber.onError(Throwable)) to retain.

Returns:

A Publisher that allows for multiple downstream subscribers and emits the previous history PublisherSource.Subscriber.onNext(Object) signals to each new subscriber.

See Also:

• ReactiveX replay operator
• ReplayStrategies.historyBuilder(int)
• replay(ReplayStrategy)

replay

public final Publisher<T> replay(int historyHint,
 Duration ttl,
 Executor executor)

Similar to multicast(int) in that multiple downstream PublisherSource.Subscribers are enabled on the returned Publisher but also retains historyHint of the most recently emitted signals from PublisherSource.Subscriber.onNext(Object) which are emitted to new downstream PublisherSource.Subscribers before emitting new signals. Each item is only retained for ttl duration of time.

Parameters:

historyHint - hint for max number of signals (excluding PublisherSource.Subscriber.onComplete() and PublisherSource.Subscriber.onError(Throwable)) to retain. Due to concurrency between threads (timer, accumulation, subscribe) the maximum number of signals delivered to new subscribers may potentially be more but this hint provides a general bound for memory when concurrency subsides.

ttl - duration each element will be retained before being removed.

executor - used to enforce the ttl argument.

Returns:

A Publisher that allows for multiple downstream subscribers and emits the previous historyHint PublisherSource.Subscriber.onNext(Object) signals to each new subscriber.

See Also:

• ReactiveX replay operator
• ReplayStrategies.historyTtlBuilder(int, Duration, io.servicetalk.concurrent.Executor)
• ReplayStrategies.historyTtlBuilder(int, Duration, io.servicetalk.concurrent.Executor, boolean)
• replay(ReplayStrategy)

replay

public final Publisher<T> replay(Supplier<ReplayAccumulator<T>> accumulatorSupplier)

Similar to multicast(int) in that multiple downstream PublisherSource.Subscribers are enabled on the returned Publisher but will also retain some history of PublisherSource.Subscriber.onNext(Object) signals according to the ReplayAccumulator accumulatorSupplier.

Parameters:

accumulatorSupplier - supplies a ReplayAccumulator on each subscribe to upstream that can retain history of PublisherSource.Subscriber.onNext(Object) signals to deliver to new downstream subscribers.

Returns:

A Publisher that allows for multiple downstream subscribers that can retain history of PublisherSource.Subscriber.onNext(Object) signals to deliver to new downstream subscribers.

See Also:

• ReactiveX replay operator
• replay(ReplayStrategy)

replay

public final Publisher<T> replay(ReplayStrategy<T> replayStrategy)

Similar to multicast(int) in that multiple downstream PublisherSource.Subscribers are enabled on the returned Publisher but will also retain some history of PublisherSource.Subscriber.onNext(Object) signals according to the ReplayStrategy replayStrategy.

Parameters:

replayStrategy - a ReplayStrategy that determines the replay behavior and history retention logic.

Returns:

A Publisher that allows for multiple downstream subscribers that can retain history of PublisherSource.Subscriber.onNext(Object) signals to deliver to new downstream subscribers.

See Also:

• ReactiveX replay operator
• ReplayStrategyBuilder
• ReplayStrategies

buffer

public final <BC extends BufferStrategy.Accumulator<T,
B>,
B>
Publisher<B> buffer(BufferStrategy<T,BC,B> strategy)

Create a Publisher that buffers items from this Publisher and emit those buffers instead of the individual items.

In sequential programming this is similar to the following:

     List accumulators = strategy.boundaries();
     List buffers = ...;
     BC currentAccumulator;
     for (T t : resultOfThisPublisher()) {
         // This is an approximation; accumulators are emitted asynchronously.
         BC nextAccumulator = accumulators.remove(0).get();
         buffers.add(currentAccumulator.finish());
         currentAccumulator = nextAccumulator;
         currentAccumulator.add(t);
     }
     return buffers;
 

Notes:

1. If this Publisher does not emit items within the boundary, it's expected it will emit an empty accumulated value as the result of accumulating nothing. Use filter(Predicate) operator if empty accumulations have to be discarded.
2. If more than one boundary is emitted while this operator accumulates or emits the next result of accumulation, those boundaries will be discarded without invoking BufferStrategy.Accumulator.finish() method.

Type Parameters:

BC - Type of the BufferStrategy.Accumulator to buffer items from this Publisher.

B - Type of the buffer emitted from the returned Publisher.

Parameters:

strategy - A BufferStrategy to use for buffering items from this Publisher.

Returns:

a Publisher that buffers items from this Publisher and emit those buffers instead of the individual items.

See Also:

• ReactiveX buffer operator.

beforeOnSubscribe

public final Publisher<T> beforeOnSubscribe(Consumer<? super PublisherSource.Subscription> onSubscribe)

Invokes the onSubscribe Consumer argument before PublisherSource.Subscriber.onSubscribe(PublisherSource.Subscription) is called for PublisherSource.Subscribers of the returned Publisher.

Parameters:

onSubscribe - Invoked before PublisherSource.Subscriber.onSubscribe(PublisherSource.Subscription) is called for PublisherSource.Subscribers of the returned Publisher. MUST NOT throw.

Returns:

The new Publisher.

See Also:

• ReactiveX do operator.

beforeOnNext

public final Publisher<T> beforeOnNext(Consumer<? super T> onNext)

Invokes the onNext Consumer argument before PublisherSource.Subscriber.onNext(Object) is called for PublisherSource.Subscribers of the returned Publisher.

From a sequential programming point of view this method is roughly equivalent to the following:

  List<T> results = resultOfThisPublisher();
  for (T result : results) {
      onNext.accept(result);
  }
  nextOperation(results);
 

Parameters:

onNext - Invoked before PublisherSource.Subscriber.onNext(Object) is called for PublisherSource.Subscribers of the returned Publisher. MUST NOT throw.

Returns:

The new Publisher.

See Also:

• ReactiveX do operator.

beforeOnError

public final Publisher<T> beforeOnError(Consumer<Throwable> onError)

Invokes the onError Consumer argument before PublisherSource.Subscriber.onError(Throwable) is called for PublisherSource.Subscribers of the returned Publisher.

From a sequential programming point of view this method is roughly equivalent to the following:

  try {
    List<T> results = resultOfThisPublisher();
  } catch (Throwable cause) {
      onError.accept(cause);
      nextOperation(cause);
  }
 

Parameters:

onError - Invoked before PublisherSource.Subscriber.onError(Throwable) is called for PublisherSource.Subscribers of the returned Publisher. MUST NOT throw.

Returns:

The new Publisher.

See Also:

• ReactiveX do operator.

beforeOnComplete

public final Publisher<T> beforeOnComplete(Runnable onComplete)

Invokes the onComplete Runnable argument before PublisherSource.Subscriber.onComplete() is called for PublisherSource.Subscribers of the returned Publisher.

From a sequential programming point of view this method is roughly equivalent to the following:

   List<T> results = resultOfThisPublisher();
   onComplete.run();
   nextOperation(results);
 

Parameters:

onComplete - Invoked before PublisherSource.Subscriber.onComplete() is called for PublisherSource.Subscribers of the returned Publisher. MUST NOT throw.

Returns:

The new Publisher.

See Also:

• ReactiveX do operator.

beforeRequest

public final Publisher<T> beforeRequest(LongConsumer onRequest)

Invokes the onRequest LongConsumer argument before PublisherSource.Subscription.request(long) is called for PublisherSource.Subscriptions of the returned Publisher.

Parameters:

onRequest - Invoked before PublisherSource.Subscription.request(long) is called for PublisherSource.Subscriptions of the returned Publisher. MUST NOT throw.

Returns:

The new Publisher.

See Also:

• ReactiveX do operator.

beforeCancel

public final Publisher<T> beforeCancel(Runnable onCancel)

Invokes the onCancel Runnable argument before Cancellable.cancel() is called for PublisherSource.Subscriptions of the returned Publisher.

Parameters:

onCancel - Invoked before Cancellable.cancel() is called for PublisherSource.Subscriptions of the returned Publisher. MUST NOT throw.

Returns:

The new Publisher.

See Also:

• ReactiveX do operator.

beforeFinally

public final Publisher<T> beforeFinally(Runnable doFinally)

Invokes the beforeFinally Runnable argument before any of the following terminal methods are called:

• PublisherSource.Subscriber.onComplete()
• PublisherSource.Subscriber.onError(Throwable)
• Cancellable.cancel()

for PublisherSource.Subscriptions/PublisherSource.Subscribers of the returned Publisher.

From a sequential programming point of view this method is roughly equivalent to the following:

  try {
      List<T> results = resultOfThisPublisher();
  } finally {
      doFinally.run();
      nextOperation(); // Maybe notifying of cancellation, or termination
  }
 

Parameters:

doFinally - Invoked before any of the following terminal methods are called:

• PublisherSource.Subscriber.onComplete()
• PublisherSource.Subscriber.onError(Throwable)
• Cancellable.cancel()

for PublisherSource.Subscriptions/PublisherSource.Subscribers of the returned Publisher. MUST NOT throw.

Returns:

The new Publisher.

See Also:

• ReactiveX do operator.

beforeFinally

public final Publisher<T> beforeFinally(TerminalSignalConsumer doFinally)

Invokes the corresponding method on beforeFinally TerminalSignalConsumer argument before any of the following terminal methods are called:

• PublisherSource.Subscriber.onComplete() - invokes TerminalSignalConsumer.onComplete()
• PublisherSource.Subscriber.onError(Throwable) - invokes TerminalSignalConsumer.onError(Throwable)
• Cancellable.cancel() - invokes TerminalSignalConsumer.cancel()

for PublisherSource.Subscriptions/PublisherSource.Subscribers of the returned Publisher.

From a sequential programming point of view this method is roughly equivalent to the following:

  try {
      List<T> results = resultOfThisPublisher();
  } catch(Throwable t) {
      doFinally.onError(t);
      nextOperation(); // Maybe notifying of cancellation, or termination
      return;
  }
  doFinally.onComplete();
  nextOperation(); // Maybe notifying of cancellation, or termination
 

Parameters:

doFinally - For each subscribe of the returned Publisher, at most one method of this TerminalSignalConsumer will be invoked.

Returns:

The new Publisher.

See Also:

• ReactiveX do operator.

beforeSubscriber

public final Publisher<T> beforeSubscriber(Supplier<? extends PublisherSource.Subscriber<? super T>> subscriberSupplier)

Creates a new PublisherSource.Subscriber (via the subscriberSupplier argument) on each call to subscribe and invokes all the PublisherSource.Subscriber methods before the PublisherSource.Subscribers of the returned Publisher.

Parameters:

subscriberSupplier - Creates a new PublisherSource.Subscriber on each call to subscribe and invokes all the PublisherSource.Subscriber methods before the PublisherSource.Subscribers of the returned Publisher. PublisherSource.Subscriber methods MUST NOT throw.

Returns:

The new Publisher.

See Also:

• ReactiveX do operator.

beforeSubscription

public final Publisher<T> beforeSubscription(Supplier<? extends PublisherSource.Subscription> subscriptionSupplier)

Creates a new PublisherSource.Subscription (via the subscriptionSupplier argument) on each call to subscribe and invokes all the PublisherSource.Subscription methods before the PublisherSource.Subscriptions of the returned Publisher.

Parameters:

subscriptionSupplier - Creates a new PublisherSource.Subscription on each call to subscribe and invokes all the PublisherSource.Subscription methods before the PublisherSource.Subscriptions of the returned Publisher. PublisherSource.Subscription methods MUST NOT throw.

Returns:

The new Publisher.

See Also:

• ReactiveX do operator.

afterOnSubscribe

public final Publisher<T> afterOnSubscribe(Consumer<? super PublisherSource.Subscription> onSubscribe)

Invokes the onSubscribe Consumer argument after PublisherSource.Subscriber.onSubscribe(PublisherSource.Subscription) is called for PublisherSource.Subscribers of the returned Publisher.

Parameters:

onSubscribe - Invoked after PublisherSource.Subscriber.onSubscribe(PublisherSource.Subscription) is called for PublisherSource.Subscribers of the returned Publisher. MUST NOT throw.

Returns:

The new Publisher.

See Also:

• ReactiveX do operator.

afterOnNext

public final Publisher<T> afterOnNext(Consumer<? super T> onNext)

Invokes the onNext Consumer argument after PublisherSource.Subscriber.onNext(Object) is called for PublisherSource.Subscribers of the returned Publisher.

From a sequential programming point of view this method is roughly equivalent to the following:

  List<T> results = resultOfThisPublisher();
  nextOperation(results);
  for (T result : results) {
      onNext.accept(result);
  }
 

Parameters:

onNext - Invoked after PublisherSource.Subscriber.onNext(Object) is called for PublisherSource.Subscribers of the returned Publisher. MUST NOT throw.

Returns:

The new Publisher.

See Also:

• ReactiveX do operator.

afterOnError

public final Publisher<T> afterOnError(Consumer<Throwable> onError)

Invokes the onError Consumer argument after PublisherSource.Subscriber.onError(Throwable) is called for PublisherSource.Subscribers of the returned Publisher.

From a sequential programming point of view this method is roughly equivalent to the following:

  try {
    List<T> results = resultOfThisPublisher();
  } catch (Throwable cause) {
      nextOperation(cause);
      onError.accept(cause);
  }
 

Parameters:

onError - Invoked after PublisherSource.Subscriber.onError(Throwable) is called for PublisherSource.Subscribers of the returned Publisher. MUST NOT throw.

Returns:

The new Publisher.

See Also:

• ReactiveX do operator.

afterOnComplete

public final Publisher<T> afterOnComplete(Runnable onComplete)

Invokes the onComplete Runnable argument after PublisherSource.Subscriber.onComplete() is called for PublisherSource.Subscribers of the returned Publisher.

From a sequential programming point of view this method is roughly equivalent to the following:

   List<T> results = resultOfThisPublisher();
   nextOperation(results);
   onComplete.run();
 

Parameters:

onComplete - Invoked after PublisherSource.Subscriber.onComplete() is called for PublisherSource.Subscribers of the returned Publisher. MUST NOT throw.

Returns:

The new Publisher.

See Also:

• ReactiveX do operator.

afterRequest

public final Publisher<T> afterRequest(LongConsumer onRequest)

Invokes the onRequest LongConsumer argument after PublisherSource.Subscription.request(long) is called for PublisherSource.Subscriptions of the returned Publisher.

Parameters:

onRequest - Invoked after PublisherSource.Subscription.request(long) is called for PublisherSource.Subscriptions of the returned Publisher. MUST NOT throw.

Returns:

The new Publisher.

See Also:

• ReactiveX do operator.

afterCancel

public final Publisher<T> afterCancel(Runnable onCancel)

Invokes the onCancel Runnable argument after Cancellable.cancel() is called for PublisherSource.Subscriptions of the returned Publisher.

Parameters:

onCancel - Invoked after Cancellable.cancel() is called for PublisherSource.Subscriptions of the returned Publisher. MUST NOT throw.

Returns:

The new Publisher.

See Also:

• ReactiveX do operator.

afterFinally

public final Publisher<T> afterFinally(Runnable doFinally)

Invokes the afterFinally Runnable argument after any of the following terminal methods are called:

• PublisherSource.Subscriber.onComplete()
• PublisherSource.Subscriber.onError(Throwable)
• Cancellable.cancel()

for PublisherSource.Subscriptions/PublisherSource.Subscribers of the returned Publisher.

From a sequential programming point of view this method is roughly equivalent to the following:

  try {
      List<T> results = resultOfThisPublisher();
  } finally {
      nextOperation(); // Maybe notifying of cancellation, or termination
      doFinally.run();
  }
 

Parameters:

doFinally - Invoked after any of the following terminal methods are called:

• PublisherSource.Subscriber.onComplete()
• PublisherSource.Subscriber.onError(Throwable)
• Cancellable.cancel()

for PublisherSource.Subscriptions/PublisherSource.Subscribers of the returned Publisher. MUST NOT throw.

Returns:

The new Publisher.

See Also:

• ReactiveX do operator.

afterFinally

public final Publisher<T> afterFinally(TerminalSignalConsumer doFinally)

Invokes the corresponding method on afterFinally TerminalSignalConsumer argument after any of the following terminal methods are called:

• PublisherSource.Subscriber.onComplete() - invokes TerminalSignalConsumer.onComplete()
• PublisherSource.Subscriber.onError(Throwable) - invokes TerminalSignalConsumer.onError(Throwable)
• Cancellable.cancel() - invokes TerminalSignalConsumer.cancel()

for PublisherSource.Subscriptions/PublisherSource.Subscribers of the returned Publisher.

From a sequential programming point of view this method is roughly equivalent to the following:

  try {
      List<T> results = resultOfThisPublisher();
  } catch(Throwable t) {
      nextOperation(); // Maybe notifying of cancellation, or termination
      doFinally.onError(t);
      return;
  }
  nextOperation(); // Maybe notifying of cancellation, or termination
  doFinally.onComplete();
 

Parameters:

doFinally - For each subscribe of the returned Publisher, at most one method of this TerminalSignalConsumer will be invoked.

Returns:

The new Publisher.

See Also:

• ReactiveX do operator.

afterSubscriber

public final Publisher<T> afterSubscriber(Supplier<? extends PublisherSource.Subscriber<? super T>> subscriberSupplier)

Creates a new PublisherSource.Subscriber (via the subscriberSupplier argument) for each new subscribe and invokes all the PublisherSource.Subscriber methods after the PublisherSource.Subscribers of the returned Publisher.

Parameters:

subscriberSupplier - Creates a new PublisherSource.Subscriber for each new subscribe and invokes all the PublisherSource.Subscriber methods after the PublisherSource.Subscribers of the returned Publisher. PublisherSource.Subscriber methods MUST NOT throw.

Returns:

The new Publisher.

See Also:

• ReactiveX do operator.

whenSubscriber

public final Publisher<T> whenSubscriber(Supplier<? extends PublisherSource.Subscriber<? super T>> subscriberSupplier)

Creates a new PublisherSource.Subscriber (via the subscriberSupplier argument) for each new subscribe and invokes methods on that PublisherSource.Subscriber when the corresponding methods are called for PublisherSource.Subscribers of the returned Publisher.

Parameters:

subscriberSupplier - Creates a new PublisherSource.Subscriber for each new subscribe and invokes methods on that PublisherSource.Subscriber when the corresponding methods are called for PublisherSource.Subscribers of the returned Publisher. PublisherSource.Subscriber methods MUST NOT throw.

Returns:

The new Publisher.

afterSubscription

public final Publisher<T> afterSubscription(Supplier<? extends PublisherSource.Subscription> subscriptionSupplier)

Creates a new PublisherSource.Subscription (via the subscriptionSupplier argument) for each new subscribe and invokes all the PublisherSource.Subscription methods after the PublisherSource.Subscriptions of the returned Publisher.

Parameters:

subscriptionSupplier - Creates a new PublisherSource.Subscription for each new subscribe and invokes all the PublisherSource.Subscription methods after the PublisherSource.Subscriptions of the returned Publisher. PublisherSource.Subscription methods MUST NOT throw.

Returns:

The new Publisher.

See Also:

• ReactiveX do operator.

whenSubscription

public final Publisher<T> whenSubscription(Supplier<? extends PublisherSource.Subscription> subscriptionSupplier)

Creates a new PublisherSource.Subscription (via the subscriptionSupplier argument) for each new subscribe and invokes all the PublisherSource.Subscription methods when the corresponding methods are called for PublisherSource.Subscriptions of the returned Publisher.

Parameters:

subscriptionSupplier - Creates a new PublisherSource.Subscription for each new subscribe and invokes all the PublisherSource.Subscription methods when the PublisherSource.Subscriptions of the returned Publisher. PublisherSource.Subscription methods MUST NOT throw.

Returns:

The new Publisher.

See Also:

• ReactiveX do operator.

forEach

public final Cancellable forEach(Consumer<? super T> forEach)

Subscribes to this Publisher and invokes forEach Consumer for each item emitted by this Publisher.

This will request Long.MAX_VALUE from the PublisherSource.Subscription.

From a sequential programming point of view this method is roughly equivalent to the following:

  List<T> results = resultOfThisPublisher();
  results.iterator().forEachRemaining(forEach);
 

Parameters:

forEach - Consumer to invoke for each PublisherSource.Subscriber.onNext(Object).

Returns:

Cancellable used to invoke Cancellable.cancel() on the parameter of PublisherSource.Subscriber.onSubscribe(PublisherSource.Subscription) for this Publisher.

publishOn

public final Publisher<T> publishOn(Executor executor)

Creates a new Publisher that will use the passed Executor to invoke all PublisherSource.Subscriber methods. This method does not override preceding Executors, if any, specified for this Publisher. Only subsequent operations, if any, added in this execution chain will use this Executor.

Note: unlike publishOn(io.servicetalk.concurrent.Executor, BooleanSupplier), current operator always enforces offloading to the passed Executor.

Parameters:

executor - Executor to use.

Returns:

A new Publisher that will use the passed Executor to invoke all PublisherSource.Subscriber methods.

See Also:

• publishOn(io.servicetalk.concurrent.Executor, BooleanSupplier)

publishOn

public final Publisher<T> publishOn(Executor executor,
 BooleanSupplier shouldOffload)

Creates a new Publisher that may use the passed Executor to invoke all PublisherSource.Subscriber methods. This method does not override preceding Executors, if any, specified for this Publisher. Only subsequent operations, if any, added in this execution chain will use this Executor.

Note: unlike publishOn(io.servicetalk.concurrent.Executor), current operator may skip offloading to the passed Executor, depending on the result of the BooleanSupplier hint.

Parameters:

executor - Executor to use.

shouldOffload - Provides a hint whether offloading to the executor can be omitted or not. Offloading may still occur even if false is returned in order to preserve signal ordering.

Returns:

A new Publisher that may use the passed Executor to invoke all PublisherSource.Subscriber methods.

See Also:

• publishOn(io.servicetalk.concurrent.Executor)

subscribeOn

public final Publisher<T> subscribeOn(Executor executor)

Creates a new Publisher that will use the passed Executor to invoke the following methods:

• All PublisherSource.Subscription methods.
• The handleSubscribe(PublisherSource.Subscriber) method.

This method does not override preceding Executors, if any, specified for this Publisher. Only subsequent operations, if any, added in this execution chain will use this Executor.

Note: unlike subscribeOn(io.servicetalk.concurrent.Executor, BooleanSupplier), current operator always enforces offloading to the passed Executor.

Parameters:

executor - Executor to use.

Returns:

A new Publisher that will use the passed Executor to invoke all methods of PublisherSource.Subscription and handleSubscribe(PublisherSource.Subscriber).

See Also:

• subscribeOn(io.servicetalk.concurrent.Executor, BooleanSupplier)

subscribeOn

public final Publisher<T> subscribeOn(Executor executor,
 BooleanSupplier shouldOffload)

Creates a new Publisher that may use the passed Executor to invoke the following methods:

• All PublisherSource.Subscription methods.
• The handleSubscribe(PublisherSource.Subscriber) method.

This method does not override preceding Executors, if any, specified for this Publisher. Only subsequent operations, if any, added in this execution chain will use this Executor.

Note: unlike subscribeOn(io.servicetalk.concurrent.Executor), current operator may skip offloading to the passed Executor, depending on the result of the BooleanSupplier hint.

Parameters:

executor - Executor to use.

shouldOffload - Provides a hint whether offloading to the executor can be omitted or not. Offloading may still occur even if false is returned in order to preserve signal ordering.

Returns:

A new Publisher that may use the passed Executor to invoke all methods of PublisherSource.Subscription and handleSubscribe(PublisherSource.Subscriber).

See Also:

• subscribeOn(io.servicetalk.concurrent.Executor)

shareContextOnSubscribe

public final Publisher<T> shareContextOnSubscribe()

Signifies that when the returned Publisher is subscribed to, the AsyncContext will be shared instead of making a copy.

This operator only impacts behavior if the returned Publisher is subscribed directly after this operator, that means this must be the "last operator" in the chain for this to have an impact.

Returns:

A Publisher that will share the AsyncContext instead of making a copy when subscribed to.

setContextOnSubscribe

public final Publisher<T> setContextOnSubscribe(ContextMap context)

Specify the ContextMap to use for AsyncContext when the returned Publisher is subscribed to.

This operator only impacts behavior if the returned Publisher is subscribed directly after this operator, that means this must be the "last operator" in the chain for this to have an impact.

Parameters:

context - The ContextMap to use for AsyncContext when subscribed.

Returns:

A Completable that will use the ContextMap for AsyncContext when subscribed.

liftSync

public final <R> Publisher<R> liftSync(PublisherOperator<? super T,? extends R> operator)

This method requires advanced knowledge of building operators. Before using this method please attempt to compose existing operator(s) to satisfy your use case.

Returns a Publisher which when subscribed, the operator argument will be used to wrap the PublisherSource.Subscriber before subscribing to this Publisher.

     Publisher<X> pub = ...;
     pub.map(..) // A
        .liftSync(original -> modified)
        .filter(..) // B
 

The original -> modified "operator" MUST be "synchronous" in that it does not interact with the original PublisherSource.Subscriber from outside the modified PublisherSource.Subscriber or PublisherSource.Subscription threads. That is to say this operator will not impact the Executor constraints already in place between A and B above. If you need asynchronous behavior, or are unsure, see liftAsync(PublisherOperator).

Type Parameters:

R - Type of the items emitted by the returned Publisher.

Parameters:

operator - The custom operator logic. The input is the "original" PublisherSource.Subscriber to this Publisher and the return is the "modified" PublisherSource.Subscriber that provides custom operator business logic.

Returns:

a Publisher which when subscribed, the operator argument will be used to wrap the PublisherSource.Subscriber before subscribing to this Publisher.

See Also:

• liftAsync(PublisherOperator)

liftSyncToSingle

public final <R> Single<R> liftSyncToSingle(PublisherToSingleOperator<? super T,? extends R> operator)

This method requires advanced knowledge of building operators. Before using this method please attempt to compose existing operator(s) to satisfy your use case.

Returns a Single which when subscribed, the operator argument will be used to convert between the SingleSource.Subscriber to a PublisherSource.Subscriber before subscribing to this Publisher.

     Publisher<X> pub = ...;
     pub.map(..) // A
        .liftSync(original -> modified)
        .filter(..) // B - we have converted to Single now!
 

The original -> modified "operator" MUST be "synchronous" in that it does not interact with the original PublisherSource.Subscriber from outside the modified PublisherSource.Subscriber or PublisherSource.Subscription threads. That is to say this operator will not impact the Executor constraints already in place between A and B above. If you need asynchronous behavior, or are unsure, don't use this operator.

Type Parameters:

R - Type of the items emitted by the returned Single.

Parameters:

operator - The custom operator logic. The input is the "original" SingleSource.Subscriber to the returned Single and the return is the "modified" PublisherSource.Subscriber that provides custom operator business logic on this Publisher.

Returns:

a Single which when subscribed, the operator argument will be used to convert the SingleSource.Subscriber to a PublisherSource.Subscriber before subscribing to this Publisher.

liftAsync

public final <R> Publisher<R> liftAsync(PublisherOperator<? super T,? extends R> operator)

This method requires advanced knowledge of building operators. Before using this method please attempt to compose existing operator(s) to satisfy your use case.

Returns a Publisher which will wrap the PublisherSource.Subscriber using the provided operator argument before subscribing to this Publisher.

     Publisher<X> pub = ...;
     pub.map(..) // A
        .liftAsync(original -> modified)
        .filter(..) // B
 

The original -> modified "operator" MAY be "asynchronous" in that it may interact with the original PublisherSource.Subscriber from outside the modified PublisherSource.Subscriber or PublisherSource.Subscription threads. More specifically:

• all of the PublisherSource.Subscriber invocations going "downstream" (i.e. from A to B above) MAY be offloaded via an Executor
• all of the PublisherSource.Subscription invocations going "upstream" (i.e. from B to A above) MAY be offloaded via an Executor

This behavior exists to prevent blocking code negatively impacting the thread that powers the upstream source of data (e.g. an EventLoop).

Type Parameters:

R - Type of the items emitted by the returned Publisher.

Parameters:

operator - The custom operator logic. The input is the "original" PublisherSource.Subscriber to this Publisher and the return is the "modified" PublisherSource.Subscriber that provides custom operator business logic.

Returns:

a Publisher which when subscribed, the operator argument will be used to wrap the PublisherSource.Subscriber before subscribing to this Publisher.

See Also:

• liftSync(PublisherOperator)

firstOrElse

public final Single<T> firstOrElse(Supplier<T> defaultValueSupplier)

Converts this Publisher to a Single.

This operator is useful if the Publisher that is being converted is potentially empty (in which case the defaultValueSupplier will be triggered) or may emit multiple elements (in which case it will be cancelled after receiving the first element). If a conversion to Single is needed where it is expected that the Publisher returns exactly one element, consider using firstOrError() instead.

Parameters:

defaultValueSupplier - A Supplier of default value if this Publisher did not emit any item.

Returns:

A Single that will contain the first item emitted from the this Publisher. If the source Publisher does not emit any item, then the returned Single will contain the value as returned by the passed Supplier.

See Also:

• ReactiveX first operator.
• firstOrError()

firstOrError

public final Single<T> firstOrError()

Converts this Publisher to a Single and ensures that it emits exactly a single element before completion.

This operator ensures that the Publisher emits exactly a single PublisherSource.Subscriber.onNext(Object) to its PublisherSource.Subscriber. If this Publisher terminates without emitting any items a NoSuchElementException will be signaled and if this Publisher emits more than one item, an IllegalArgumentException will be signaled. Any error emitted by this Publisher will be forwarded to the returned Single.

To uphold the guarantees laid out in the previous paragraph, this operator requests two items from the Publisher. This means that if the Publisher does not complete after signaling one element, this operator will not complete. If "one element and then complete" semantics are desired, consider chaining the takeAtMost(1) operator beforehand. This will ensure a completion signal after one item is propagated from the Publisher.

Returns:

A Single that will contain the first item emitted from the this Publisher. If the source Publisher does not emit any item, then the returned Single will terminate with NoSuchElementException.

See Also:

• firstOrElse(Supplier)

ignoreElements

public final Completable ignoreElements()

Ignores all elements emitted by this Publisher and forwards the termination signal to the returned Completable.

Returns:

A Completable that mirrors the terminal signal from this Publisher.

See Also:

• ReactiveX ignoreElements operator.

completableOrError

public final Completable completableOrError()

Converts this Publisher to a Completable. If this Publisher emits any PublisherSource.Subscriber.onNext(Object) signals the resulting Completable will be terminated with a IllegalArgumentException.

Returns:

A Completable that mirrors the terminal signal from this Publisher, and terminates in error if an PublisherSource.Subscriber.onNext(Object) signals.

collect

public final <R> Single<R> collect(Supplier<? extends R> resultFactory,
 BiFunction<? super R,? super T,R> collector)

Collects all items emitted by this Publisher into a single item.

Type Parameters:

R - Type of the reduced item.

Parameters:

resultFactory - Factory for the result which collects all items emitted by this Publisher. This will be called every time the returned Single is subscribed.

collector - Invoked for every item emitted by the source Publisher and returns the same or altered result object.

Returns:

A Single that completes with the single result or any error emitted by the source Publisher.

See Also:

• ReactiveX reduce operator.

toFuture

public final Future<Collection<T>> toFuture()

Convert this Publisher into a Future with a Collection containing the elements of this Publisher upon successful termination. If this Publisher terminates in an error, then the intermediate Collection will be discarded and the Future will complete exceptionally.

Returns:

a Future with a Collection containing the elements of this Publisher upon successful termination.

See Also:

• toFuture(Supplier, BiFunction)

toFuture

public final <R> Future<R> toFuture(Supplier<? extends R> resultFactory,
 BiFunction<? super R,? super T,R> reducer)

Convert this Publisher into a Future of type Publisher which represents all elements of this Publisher upon successful termination. If this Publisher terminates in an error, then the intermediate Publisher will be discarded and the Future will complete exceptionally.

Type Parameters:

R - Type of the reduced item.

Parameters:

resultFactory - Factory for the result which collects all items emitted by this Publisher.

reducer - Invoked for every item emitted by the source Publisher and returns the same or altered result object.

Returns:

a Future of type Publisher which represents all elements of this Publisher upon successful termination.

toCompletionStage

public final CompletionStage<Collection<T>> toCompletionStage()

Convert this Publisher into a CompletionStage with a Collection containing the elements of this Publisher upon successful termination. If this Publisher terminates in an error, then the intermediate Collection will be discarded and the CompletionStage will complete exceptionally.

Returns:

a CompletionStage with a Collection containing the elements of this Publisher upon successful termination.

See Also:

• toCompletionStage(Supplier, BiFunction)

toCompletionStage

public final <R> CompletionStage<R> toCompletionStage(Supplier<? extends R> resultFactory,
 BiFunction<? super R,? super T,R> reducer)

Convert this Publisher into a CompletionStage of type Publisher which represents all elements of this Publisher upon successful termination. If this Publisher terminates in an error, then the intermediate Publisher will be discarded and the CompletionStage will complete exceptionally.

Type Parameters:

R - Type of the reduced item.

Parameters:

resultFactory - Factory for the result which collects all items emitted by this Publisher.

reducer - Invoked for every item emitted by the source Publisher and returns the same or altered result object.

Returns:

a CompletionStage of type Publisher which represents all elements of this Publisher upon successful termination.

toInputStream

public final InputStream toInputStream(Function<? super T,byte[]> serializer)

Subscribes to this Publisher and converts all signals received by the PublisherSource.Subscriber to the returned InputStream following the below rules:

• PublisherSource.Subscription received by PublisherSource.Subscriber.onSubscribe(PublisherSource.Subscription) is used to request more data when required. If the returned InputStream is closed, PublisherSource.Subscription is cancelled and any unread data is disposed.
• Any items received by PublisherSource.Subscriber.onNext(Object) are converted to a byte[] using the passed serializer. These bytes are available to be read from the InputStream
• Any Throwable received by PublisherSource.Subscriber.onError(Throwable) is thrown (wrapped in an IOException) when data is read from the returned InputStream. This error will be thrown only after draining all queued data, if any.
• When PublisherSource.Subscriber.onComplete() is called, returned InputStream's read methods will return -1 to indicate end of stream after emitting all received data.

Flow control

This operator may pre-fetch may pre-fetch items from this Publisher if available to reduce blocking for read operations from the returned InputStream. In order to increase responsiveness of the InputStream some amount of buffering may be done. Use toInputStream(Function, int) to manage capacity of this buffer.

Parameters:

serializer - Function that is invoked for every item emitted by this Publisher.

Returns:

InputStream that emits all data emitted by this Publisher. If this Publisher terminates with an error, same error is thrown (wrapped in an IOException) from the returned InputStreams read methods after emitting all received data.

toInputStream

public final InputStream toInputStream(Function<? super T,byte[]> serializer,
 int queueCapacity)

Subscribes to this Publisher and converts all signals received by the PublisherSource.Subscriber to the returned InputStream following the below rules:

• PublisherSource.Subscription received by PublisherSource.Subscriber.onSubscribe(PublisherSource.Subscription) is used to request more data when required. If the returned InputStream is closed, PublisherSource.Subscription is cancelled and any unread data is disposed.
• Any items received by PublisherSource.Subscriber.onNext(Object) are converted to a byte[] using the passed serializer. These bytes are available to be read from the InputStream
• Any Throwable received by PublisherSource.Subscriber.onError(Throwable) is thrown (wrapped in an IOException) when data is read from the returned InputStream. This error will be thrown only after draining all queued data, if any.
• When PublisherSource.Subscriber.onComplete() is called, returned InputStream's read methods will return -1 to indicate end of stream after emitting all received data.

Flow control

This operator may pre-fetch items from this Publisher if available to reduce blocking for read operations from the returned InputStream. In order to increase responsiveness of the InputStream some amount of buffering may be done. queueCapacity can be used to bound this buffer.

Parameters:

serializer - Function that is invoked for every item emitted by this Publisher.

queueCapacity - Hint for the capacity of the intermediary queue that stores items that are emitted by this Publisher but has not yet been read from the returned InputStream.

Returns:

InputStream that emits all data emitted by this Publisher. If this Publisher terminates with an error, same error is thrown (wrapped in an IOException) from the returned InputStreams read methods after emitting all received data.

toIterable

public final BlockingIterable<T> toIterable()

Converts this Publisher to an BlockingIterable. Every time BlockingIterable.iterator() is called on the returned BlockingIterable, this Publisher is subscribed following the below rules:

• PublisherSource.Subscription received by PublisherSource.Subscriber.onSubscribe(PublisherSource.Subscription) is used to request more data when required.
• Any items received by PublisherSource.Subscriber.onNext(Object) is returned from a call to BlockingIterator.next().
• Any Throwable received by PublisherSource.Subscriber.onError(Throwable) is thrown (wrapped in a RuntimeException if required) when BlockingIterator.next() is called. This error will be thrown only after draining all queued data, if any.
• When PublisherSource.Subscriber.onComplete() is called, returned BlockingIterators Iterator.hasNext() will return false BlockingIterator.next() will throw NoSuchElementException. This error will be thrown only after draining all queued data, if any.

Flow control

This operator may pre-fetch items from this Publisher if available to reduce blocking of Iterator.hasNext() from the returned BlockingIterable. In order to increase responsiveness of the Iterator some amount of buffering may be done. Use toIterable(int) to manage capacity of this buffer.

Blocking

The returned BlockingIterator from the returned BlockingIterable will block on Iterator.hasNext() and BlockingIterator.next() if no data is available. This operator may try to reduce this blocking by requesting data ahead of time.

Returns:

BlockingIterable representing this Publisher. Every time BlockingIterable.iterator() is invoked on the BlockingIterable, this Publisher is subscribed. BlockingIterators returned from this BlockingIterable do not support Iterator.remove().

toIterable

public final BlockingIterable<T> toIterable(int queueCapacityHint)

Converts this Publisher to an BlockingIterable. Every time BlockingIterable.iterator() is called on the returned BlockingIterable, this Publisher is subscribed following the below rules:

• PublisherSource.Subscription received by PublisherSource.Subscriber.onSubscribe(PublisherSource.Subscription) is used to request more data when required.
• Any items received by PublisherSource.Subscriber.onNext(Object) is returned from a call to BlockingIterator.next().
• Any Throwable received by PublisherSource.Subscriber.onError(Throwable) is thrown (wrapped in a RuntimeException if required) when BlockingIterator.next(). This error will be thrown only after draining all queued data, if any.
• When PublisherSource.Subscriber.onComplete() is called, returned BlockingIterators Iterator.hasNext() will return false and BlockingIterator.next() will throw NoSuchElementException. This error will be thrown only after draining all queued data, if any.

Flow control

This operator may pre-fetch items from this Publisher if available to reduce blocking of Iterator.hasNext() from the returned BlockingIterable. In order to increase responsiveness of the BlockingIterator some amount of buffering may be done. queueCapacityHint can be used to bound this buffer.

Blocking

The returned BlockingIterator from the returned BlockingIterable will block on Iterator.hasNext() and BlockingIterator.next() if no data is available. This operator may try to reduce this blocking by requesting data ahead of time.

Parameters:

queueCapacityHint - Hint for the capacity of the intermediary queue that stores items that are emitted by this Publisher but has not yet been returned from the BlockingIterator.

Returns:

BlockingIterable representing this Publisher. Every time BlockingIterable.iterator() is invoked on the BlockingIterable, this Publisher is subscribed. BlockingIterators returned from this BlockingIterable do not support Iterator.remove().

subscribeInternal

protected void subscribeInternal(PublisherSource.Subscriber<? super T> subscriber)

A internal subscribe method similar to PublisherSource.subscribe(Subscriber) which can be used by different implementations to subscribe.

Parameters:

subscriber - PublisherSource.Subscriber to subscribe for the result.

handleSubscribe

protected abstract void handleSubscribe(PublisherSource.Subscriber<? super T> subscriber)

Handles a subscriber to this Publisher.

Parameters:

subscriber - the subscriber.

from

public static <T> Publisher<T> from(@Nullable
 T value)

Creates a new Publisher that emits value to its PublisherSource.Subscriber and then PublisherSource.Subscriber.onComplete().

Type Parameters:

T - Type of items emitted by the returned Publisher.

Parameters:

value - Value that the returned Publisher will emit.

Returns:

A new Publisher that emits value to its PublisherSource.Subscriber and then PublisherSource.Subscriber.onComplete().

See Also:

• ReactiveX just operator.

from

public static <T> Publisher<T> from(@Nullable
 T v1,
 @Nullable
 T v2)

Creates a new Publisher that emits v1 and v2 to its PublisherSource.Subscriber and then PublisherSource.Subscriber.onComplete().

Type Parameters:

T - Type of items emitted by the returned Publisher.

Parameters:

v1 - The first value that the returned Publisher will emit.

v2 - The second value that the returned Publisher will emit.

Returns:

A new Publisher that emits v1 and v2 to its PublisherSource.Subscriber and then PublisherSource.Subscriber.onComplete().

See Also:

• ReactiveX just operator.

from

public static <T> Publisher<T> from(@Nullable
 T v1,
 @Nullable
 T v2,
 @Nullable
 T v3)

Creates a new Publisher that emits v1, v2, and v3 to its PublisherSource.Subscriber and then PublisherSource.Subscriber.onComplete().

Type Parameters:

T - Type of items emitted by the returned Publisher.

Parameters:

v1 - The first value that the returned Publisher will emit.

v2 - The second value that the returned Publisher will emit.

v3 - The third value that the returned Publisher will emit.

Returns:

A new Publisher that emits v1, v2, and v3 to its PublisherSource.Subscriber and then PublisherSource.Subscriber.onComplete().

See Also:

• ReactiveX just operator.

from

@SafeVarargs
public static <T> Publisher<T> from(T... values)

Creates a new Publisher that emits all values to its PublisherSource.Subscriber and then PublisherSource.Subscriber.onComplete().

Type Parameters:

T - Type of items emitted by the returned Publisher.

Parameters:

values - Values that the returned Publisher will emit.

Returns:

A new Publisher that emits all values to its PublisherSource.Subscriber and then PublisherSource.Subscriber.onComplete().

See Also:

• ReactiveX from operator.

fromIterable

public static <T> Publisher<T> fromIterable(Iterable<? extends T> iterable)

Create a new Publisher that when subscribed will get an Iterator via Iterable.iterator() and emit all values to the PublisherSource.Subscriber and then PublisherSource.Subscriber.onComplete().

The Reactive Streams specification provides two criteria ( 3.4, and 3.5) stating the PublisherSource.Subscription should be "responsive". The responsiveness of the associated PublisherSource.Subscriptions will depend upon the behavior of the iterable below. Make sure the Executor for this execution chain can tolerate this responsiveness and any blocking behavior.

Type Parameters:

T - Type of items emitted by the returned Publisher.

Parameters:

iterable - used to obtain instances of Iterator to extract data from. Iterable.iterator() must not return null. If this is of type BlockingIterable then any generated BlockingIterators will have their BlockingIterator.close() method called if an error occurs.

Returns:

a new Publisher that when subscribed will get an Iterator via Iterable.iterator() and emit all values to the PublisherSource.Subscriber and then PublisherSource.Subscriber.onComplete().

fromBlockingIterable

public static <T> Publisher<T> fromBlockingIterable(BlockingIterable<? extends T> iterable,
 LongSupplier timeoutSupplier,
 TimeUnit unit)

Create a new Publisher that when subscribed will get a BlockingIterator via BlockingIterable.iterator() and emit all values to the PublisherSource.Subscriber and then PublisherSource.Subscriber.onComplete().

The Reactive Streams specification provides two criteria ( 3.4, and 3.5) stating the PublisherSource.Subscription should be "responsive". The responsiveness of the associated PublisherSource.Subscriptions will depend upon the behavior of the iterable below. Make sure the Executor for this execution chain can tolerate this responsiveness and any blocking behavior.

Type Parameters:

T - Type of items emitted by the returned Publisher.

Parameters:

iterable - used to obtain instances of Iterator to extract data from. Iterable.iterator() must not return null. Any generated BlockingIterators will have their BlockingIterator.close() method called if an error occurs.

timeoutSupplier - A LongSupplier which provides the time duration to wait for each interaction with iterable.

unit - The time units for the timeout duration.

Returns:

a new Publisher that when subscribed will get a BlockingIterator via BlockingIterable.iterator() and emit all values to the PublisherSource.Subscriber and then PublisherSource.Subscriber.onComplete().

fromInputStream

@Deprecated
public static Publisher<byte[]> fromInputStream(InputStream stream)

Deprecated.

Use fromInputStream(InputStream, ByteArrayMapper) with ByteArrayMapper.toByteArray().

Create a new Publisher that when subscribed will emit all data from the InputStream to the PublisherSource.Subscriber and then PublisherSource.Subscriber.onComplete().

The resulting publisher is not replayable and supports only a single PublisherSource.Subscriber.

After a returned Publisher is subscribed, it owns the passed InputStream, meaning that the InputStream will be automatically closed when the Publisher is cancelled or terminated. Not necessary to close the InputStream after subscribe, but it should be closed when control flow never subscribes to the returned Publisher.

The Reactive Streams specification provides two criteria ( 3.4, and 3.5) stating the PublisherSource.Subscription should be "responsive". The responsiveness of the associated PublisherSource.Subscriptions will depend upon the behavior of the stream below. Make sure the Executor for this execution chain can tolerate this responsiveness and any blocking behavior.

Parameters:

stream - provides the data in the form of byte[] to be emitted to the PublisherSource.Subscriber by the returned Publisher. Given the blocking nature of InputStream, assume PublisherSource.Subscription.request(long) can block when the underlying InputStream blocks on InputStream.read(byte[], int, int).

Returns:

a new Publisher that when subscribed will emit all data from the InputStream to the PublisherSource.Subscriber and then PublisherSource.Subscriber.onComplete().

fromInputStream

@Deprecated
public static Publisher<byte[]> fromInputStream(InputStream stream,
 int readChunkSize)

Deprecated.

Use fromInputStream(InputStream, ByteArrayMapper) with ByteArrayMapper.toByteArray(int).

Create a new Publisher that when subscribed will emit all data from the InputStream to the PublisherSource.Subscriber and then PublisherSource.Subscriber.onComplete().

The resulting publisher is not replayable and supports only a single PublisherSource.Subscriber.

After a returned Publisher is subscribed, it owns the passed InputStream, meaning that the InputStream will be automatically closed when the Publisher is cancelled or terminated. Not necessary to close the InputStream after subscribe, but it should be closed when control flow never subscribes to the returned Publisher.

The Reactive Streams specification provides two criteria ( 3.4, and 3.5) stating the PublisherSource.Subscription should be "responsive". The responsiveness of the associated PublisherSource.Subscriptions will depend upon the behavior of the stream below. Make sure the Executor for this execution chain can tolerate this responsiveness and any blocking behavior.

Parameters:

stream - provides the data in the form of byte[] to be emitted to the PublisherSource.Subscriber by the returned Publisher. Given the blocking nature of InputStream, assume PublisherSource.Subscription.request(long) can block when the underlying InputStream blocks on InputStream.read(byte[], int, int).

readChunkSize - the maximum length of byte[] chunks which will be read from the InputStream and emitted by the returned Publisher.

Returns:

a new Publisher that when subscribed will emit all data from the InputStream to the PublisherSource.Subscriber and then PublisherSource.Subscriber.onComplete().

fromInputStream

public static <T> Publisher<T> fromInputStream(InputStream stream,
 ByteArrayMapper<T> mapper)

Create a new Publisher that when subscribed will emit all data from the InputStream to the PublisherSource.Subscriber as a mapped type T and then PublisherSource.Subscriber.onComplete().

The resulting publisher is not replayable and supports only a single PublisherSource.Subscriber.

After a returned Publisher is subscribed, it owns the passed InputStream, meaning that the InputStream will be automatically closed when the Publisher is cancelled or terminated. Not necessary to close the InputStream after subscribe, but it should be closed when control flow never subscribes to the returned Publisher.

The Reactive Streams specification provides two criteria ( 3.4, and 3.5) stating the PublisherSource.Subscription should be "responsive". The responsiveness of the associated PublisherSource.Subscriptions will depend upon the behavior of the stream below. Make sure the Executor for this execution chain can tolerate this responsiveness and any blocking behavior.

Given the blocking nature of InputStream, assume PublisherSource.Subscription.request(long) can block when the underlying InputStream blocks on InputStream.read(byte[], int, int).

Type Parameters:

T - Type of the items emitted by the returned Publisher.

Parameters:

stream - provides the data in the form of byte[] buffer regions for the specified ByteArrayMapper.

mapper - a mapper to transform raw byte[] buffer regions into a desired type T to be emitted to the PublisherSource.Subscriber by the returned Publisher.

Returns:

a new Publisher that when subscribed will emit all data from the InputStream to the PublisherSource.Subscriber as a mapped type T and then PublisherSource.Subscriber.onComplete().

range

public static Publisher<Integer> range(int begin,
 int end)

Create a new Publisher that when subscribed will emit all Integers within the range of [begin, end).

Parameters:

begin - The beginning of the range (inclusive).

end - The end of the range (exclusive).

Returns:

a new Publisher that when subscribed will emit all Integers within the range of [begin, end).

See Also:

• Range.

range

public static Publisher<Integer> range(int begin,
 int end,
 int stride)

Create a new Publisher that when subscribed will emit all Integers within the range of [begin, end) with an increment of stride between each signal.

Parameters:

begin - The beginning of the range (inclusive).

end - The end of the range (exclusive).

stride - The amount to increment in between each signal.

Returns:

a new Publisher that when subscribed will emit all Integers within the range of [begin, end) with an increment of stride between each signal.

See Also:

• Range.

empty

public static <T> Publisher<T> empty()

Creates a new Publisher that completes when subscribed without emitting any item to its PublisherSource.Subscriber.

Type Parameters:

T - Type of items emitted by the returned Publisher.

Returns:

A new Publisher that completes when subscribed without emitting any item to its PublisherSource.Subscriber.

See Also:

• ReactiveX empty operator.

never

public static <T> Publisher<T> never()

Creates a new Publisher that never emits any item to its PublisherSource.Subscriber and never call any terminal methods on it.

Type Parameters:

T - Type of items emitted by the returned Publisher.

Returns:

A new Publisher that never emits any item to its PublisherSource.Subscriber and never call any terminal methods on it.

See Also:

• ReactiveX never operator.

failed

public static <T> Publisher<T> failed(Throwable cause)

Creates a new Publisher that terminates its PublisherSource.Subscriber with an error without emitting any item to it.

Type Parameters:

T - Type of items emitted by the returned Publisher.

Parameters:

cause - The Throwable that is used to terminate the PublisherSource.Subscriber.

Returns:

A new Publisher that terminates its PublisherSource.Subscriber with an error without emitting any item to it.

See Also:

• ReactiveX error operator.

defer

public static <T> Publisher<T> defer(Supplier<? extends Publisher<? extends T>> publisherSupplier)

Defers creation of a Publisher till it is subscribed.

Type Parameters:

T - Type of items emitted by the returned Publisher.

Parameters:

publisherSupplier - Supplier to create a new Publisher every time the returned Publisher is subscribed.

Returns:

A new Publisher that creates a new Publisher using publisherSupplier every time it is subscribed and forwards all items and terminal events from the newly created Publisher to its PublisherSource.Subscriber.

See Also:

• ReactiveX defer operator.

mergeAll

@SafeVarargs
public static <T> Publisher<T> mergeAll(Publisher<? extends T>... publishers)

Merge all Publishers together. There is no guaranteed ordering of events emitted from the returned Publisher.

This method provides similar capabilities as expanding each result into a collection and concatenating each collection in sequential programming:

     List<T> mergedResults = ...; // concurrent safe list
     for (T t : resultOfPublisher1()) {
         futures.add(e.submit(() -> {
             return mergedResults.add(t);
         }));
     }
     for (T t : resultOfOtherPublisher()) {
         futures.add(e.submit(() -> {
             return mergedResults.add(t);
         }));
     }
     for (Future<R> future : futures) {
        future.get(); // Throws if the processing for this item failed.
     }
     return mergedResults;
 

Type Parameters:

T - Type of items emitted by the returned Publisher.

Parameters:

publishers - The Publishers to merge together.

Returns:

A Publisher which is the result of this Publisher and other merged together.

See Also:

• ReactiveX merge operator
• mergeAll(int, Publisher[])
• mergeAllDelayError(Publisher[])

mergeAll

@SafeVarargs
public static <T> Publisher<T> mergeAll(int maxConcurrency,
 Publisher<? extends T>... publishers)

Merge all Publishers together. There is no guaranteed ordering of events emitted from the returned Publisher.

This method provides similar capabilities as expanding each result into a collection and concatenating each collection in sequential programming:

     List<T> mergedResults = ...; // concurrent safe list
     for (T t : resultOfPublisher1()) {
         futures.add(e.submit(() -> {
             return mergedResults.add(t);
         }));
     }
     for (T t : resultOfOtherPublisher()) {
         futures.add(e.submit(() -> {
             return mergedResults.add(t);
         }));
     }
     for (Future<R> future : futures) {
        future.get(); // Throws if the processing for this item failed.
     }
     return mergedResults;
 

Type Parameters:

T - Type of items emitted by the returned Publisher.

Parameters:

maxConcurrency - The maximum amount of Publishers from publishers to subscribe to concurrently.

publishers - The Publishers to merge together.

Returns:

A Publisher which is the result of this Publisher and other merged together.

See Also:

• ReactiveX merge operator
• mergeAllDelayError(int, Publisher[])

mergeAllDelayError

@SafeVarargs
public static <T> Publisher<T> mergeAllDelayError(Publisher<? extends T>... publishers)

Merge all Publishers together. There is no guaranteed ordering of events emitted from the returned Publisher. If any Publisher terminates in an error, the error propagation will be delayed until all terminate.

This method provides similar capabilities as expanding each result into a collection and concatenating each collection in sequential programming:

     List<T> mergedResults = ...; // concurrent safe list
     for (T t : resultOfPublisher1()) {
         futures.add(e.submit(() -> {
             return mergedResults.add(t);
         }));
     }
     for (T t : resultOfOtherPublisher()) {
         futures.add(e.submit(() -> {
             return mergedResults.add(t);
         }));
     }
     List<Throwable> errors = ...;
     for (Future<R> future : futures) {
         try {
           future.get(); // Throws if the processing for this item failed.
         } catch (Throwable cause) {
           errors.add(cause);
         }
     }
     throwExceptionIfNotEmpty(errors);
     return mergedResults;
 

Type Parameters:

T - Type of items emitted by the returned Publisher.

Parameters:

publishers - The Publishers to merge together.

Returns:

A Publisher which is the result of this Publisher and other merged together.

See Also:

• ReactiveX merge operator
• mergeAllDelayError(int, Publisher[])
• mergeAll(Publisher[])

mergeAllDelayError

@SafeVarargs
public static <T> Publisher<T> mergeAllDelayError(int maxConcurrency,
 Publisher<? extends T>... publishers)

Merge all Publishers together. There is no guaranteed ordering of events emitted from the returned Publisher. If any Publisher terminates in an error, the error propagation will be delayed until all terminate.

This method provides similar capabilities as expanding each result into a collection and concatenating each collection in sequential programming:

     List<T> mergedResults = ...; // concurrent safe list
     for (T t : resultOfPublisher1()) {
         futures.add(e.submit(() -> {
             return mergedResults.add(t);
         }));
     }
     for (T t : resultOfOtherPublisher()) {
         futures.add(e.submit(() -> {
             return mergedResults.add(t);
         }));
     }
     List<Throwable> errors = ...;
     for (Future<R> future : futures) {
         try {
           future.get(); // Throws if the processing for this item failed.
         } catch (Throwable cause) {
           errors.add(cause);
         }
     }
     throwExceptionIfNotEmpty(errors);
     return mergedResults;
 

Type Parameters:

T - Type of items emitted by the returned Publisher.

Parameters:

maxConcurrency - The maximum amount of Publishers from publishers to subscribe to concurrently.

publishers - The Publishers to merge together.

Returns:

A Publisher which is the result of this Publisher and other merged together.

See Also:

• ReactiveX merge operator
• mergeAll(Publisher[])