io.servicetalk.concurrent.api

Class Single<T>

Object

Single<T>

Type Parameters:

T - Type of the result of the single.

public abstract class Single<T>
extends Object

An asynchronous computation that either completes with success giving the result or completes with an error.

How to subscribe?

This class does not provide a way to subscribe using a SingleSource.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 SingleSource.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	Single() New instance.

Method Summary

Modifier and Type	Method and Description
Single<T>	afterCancel(Runnable onCancel) Invokes the onCancel Runnable argument after Cancellable.cancel() is called for Subscriptions of the returned Single.
Single<T>	afterFinally(Runnable doFinally) Invokes the whenFinally Runnable argument after any of the following terminal methods are called: SingleSource.Subscriber.onSuccess(Object) SingleSource.Subscriber.onError(Throwable) Cancellable.cancel() for Subscriptions/SingleSource.Subscribers of the returned Single.
Single<T>	afterOnError(Consumer<Throwable> onError) Invokes the onError Consumer argument after SingleSource.Subscriber.onError(Throwable) is called for SingleSource.Subscribers of the returned Single.
Single<T>	afterOnSubscribe(Consumer<Cancellable> onSubscribe) Invokes the onSubscribe Consumer argument after SingleSource.Subscriber.onSubscribe(Cancellable) is called for SingleSource.Subscribers of the returned Single.
Single<T>	afterOnSuccess(Consumer<? super T> onSuccess) Invokes the onSuccess Consumer argument after SingleSource.Subscriber.onSuccess(Object) is called for SingleSource.Subscribers of the returned Single.
Single<T>	afterSubscriber(Supplier<? extends SingleSource.Subscriber<? super T>> subscriberSupplier) Creates a new SingleSource.Subscriber (via the subscriberSupplier argument) on each call to subscribe and invokes all the SingleSource.Subscriber methods after the SingleSource.Subscribers of the returned Single.
Single<T>	beforeCancel(Runnable onCancel) Invokes the onCancel Runnable argument before Cancellable.cancel() is called for Subscriptions of the returned Single.
Single<T>	beforeFinally(Runnable doFinally) Invokes the whenFinally Runnable argument before any of the following terminal methods are called: SingleSource.Subscriber.onSuccess(Object) SingleSource.Subscriber.onError(Throwable) Cancellable.cancel() for Subscriptions/SingleSource.Subscribers of the returned Single.
Single<T>	beforeOnError(Consumer<Throwable> onError) Invokes the onError Consumer argument before SingleSource.Subscriber.onError(Throwable) is called for SingleSource.Subscribers of the returned Single.
Single<T>	beforeOnSubscribe(Consumer<Cancellable> onSubscribe) Invokes the onSubscribe Consumer argument before SingleSource.Subscriber.onSubscribe(Cancellable) is called for SingleSource.Subscribers of the returned Single.
Single<T>	beforeOnSuccess(Consumer<? super T> onSuccess) Invokes the onSuccess Consumer argument before SingleSource.Subscriber.onSuccess(Object) is called for SingleSource.Subscribers of the returned Single.
Single<T>	beforeSubscriber(Supplier<? extends SingleSource.Subscriber<? super T>> subscriberSupplier) Creates a new SingleSource.Subscriber (via the subscriberSupplier argument) on each call to subscribe and invokes all the SingleSource.Subscriber methods before the SingleSource.Subscribers of the returned Single.
static <T> Single<Collection<T>>	collectUnordered(int maxConcurrency, Single<? extends T>... singles) Asynchronously collects results of the passed Singles into a single Collection.
static <T> Single<Collection<T>>	collectUnordered(Iterable<? extends Single<? extends T>> singles) Asynchronously collects results of individual Singles returned by the passed Iterable into a single Collection.
static <T> Single<Collection<T>>	collectUnordered(Iterable<? extends Single<? extends T>> singles, int maxConcurrency) Asynchronously collects results of individual Singles returned by the passed Iterable into a single Collection.
static <T> Single<Collection<T>>	collectUnordered(Single<? extends T>... singles) Asynchronously collects results of the passed Singles into a single Collection.
static <T> Single<Collection<T>>	collectUnorderedDelayError(int maxConcurrency, Single<? extends T>... singles) Asynchronously collects results of the passed Singles into a single Collection.
static <T> Single<Collection<T>>	collectUnorderedDelayError(Iterable<? extends Single<? extends T>> singles) Asynchronously collects results of individual Singles returned by the passed Iterable into a single Collection.
static <T> Single<Collection<T>>	collectUnorderedDelayError(Iterable<? extends Single<? extends T>> singles, int maxConcurrency) Asynchronously collects results of individual Singles returned by the passed Iterable into a single Collection.
static <T> Single<Collection<T>>	collectUnorderedDelayError(Single<? extends T>... singles) Asynchronously collects results of the passed Singles into a single Collection.
Single<T>	concat(Completable next) Returns a Single that emits the result of this Single after next Completable terminates successfully.
Publisher<T>	concat(Publisher<? extends T> next) Returns a Publisher that first emits the result of this Single and then subscribes and emits all elements from next Publisher.
Publisher<T>	concat(Single<? extends T> next) Returns a Publisher that first emits the result of this Single and then subscribes and emits result of next Single.
static <T> Single<T>	defer(Supplier<? extends Single<? extends T>> singleSupplier) Defer creation of a Single till it is subscribed to.
static <T> Single<T>	failed(Throwable cause) Creates a realized Single which always completes with the provided error cause.
<R> Single<R>	flatMap(Function<? super T,? extends Single<? extends R>> next) Returns a Single that mirrors emissions from the Single returned by next.
Completable	flatMapCompletable(Function<? super T,? extends Completable> next) Returns a Completable that mirrors emissions from the Completable returned by next.
<R> Publisher<R>	flatMapPublisher(Function<? super T,? extends Publisher<? extends R>> next) Returns a Publisher that mirrors emissions from the Publisher returned by next.
static <T> Single<T>	fromCallable(Callable<T> callable) Creates a Single which when subscribed will invoke Callable.call() on the passed Callable and emit the value returned by that invocation from the returned Single.
static <T> Single<T>	fromFuture(Future<? extends T> future) Convert from a Future to a Single via Future.get().
static <T> Single<T>	fromStage(CompletionStage<? extends T> stage) Convert from a CompletionStage to a Single.
static <T> Single<T>	fromSupplier(Supplier<T> supplier) Creates a Single which when subscribed will invoke Supplier.get() on the passed Supplier and emit the value returned by that invocation from the returned Single.
protected abstract void	handleSubscribe(SingleSource.Subscriber<? super T> subscriber) Handles a subscriber to this Single.
Single<T>	idleTimeout(Duration duration) Creates a new Single that will mimic the signals of this Single but will terminate with a with a TimeoutException if time duration elapses between subscribe and termination.
Single<T>	idleTimeout(Duration duration, Executor timeoutExecutor) Creates a new Single that will mimic the signals of this Single but will terminate with a with a TimeoutException if time duration elapses between subscribe and termination.
Single<T>	idleTimeout(long duration, TimeUnit unit) Creates a new Single that will mimic the signals of this Single but will terminate with a with a TimeoutException if time duration elapses between subscribe and termination.
Single<T>	idleTimeout(long duration, TimeUnit unit, Executor timeoutExecutor) Creates a new Single that will mimic the signals of this Single but will terminate with a with a TimeoutException if time duration elapses between subscribe and termination.
Completable	ignoreElement() Ignores the result of this Single and forwards the termination signal to the returned Completable.
<R> Single<R>	liftAsync(SingleOperator<? super T,? extends R> operator) This method requires advanced knowledge of building operators.
<R> Single<R>	liftSync(SingleOperator<? super T,? extends R> operator) This method requires advanced knowledge of building operators.
<R> Single<R>	map(Function<? super T,? extends R> mapper) Maps the result of this single to a different type.
static <T> Single<T>	never() Creates a Single that never terminates.
Single<T>	publishAndSubscribeOn(Executor executor) Creates a new Single that will use the passed Executor to invoke the following methods: All SingleSource.Subscriber methods. All Cancellable methods. The handleSubscribe(SingleSource.Subscriber) method. This method does not override preceding Executors, if any, specified for this Single.
Single<T>	publishAndSubscribeOnOverride(Executor executor) Creates a new Single that will use the passed Executor to invoke the following methods: All SingleSource.Subscriber methods. All Cancellable methods. The handleSubscribe(SingleSource.Subscriber) method. This method overrides preceding Executors, if any, specified for this Single.
Single<T>	publishOn(Executor executor) Creates a new Single that will use the passed Executor to invoke all SingleSource.Subscriber methods.
Single<T>	publishOnOverride(Executor executor) Creates a new Single that will use the passed Executor to invoke all SingleSource.Subscriber methods.
Single<T>	recoverWith(Function<Throwable,? extends Single<? extends T>> nextFactory) Recover from any error emitted by this Single by using another Single provided by the passed nextFactory.
Publisher<T>	repeat(IntPredicate shouldRepeat) Re-subscribes to this Single when it completes and the passed IntPredicate returns true.
Publisher<T>	repeatWhen(IntFunction<? extends Completable> repeatWhen) Re-subscribes to this Single when it completes and the Completable returned by the supplied IntFunction completes successfully.
Single<T>	retry(BiIntPredicate<Throwable> shouldRetry) Re-subscribes to this Single if an error is emitted and the passed BiIntPredicate returns true.
Single<T>	retryWhen(BiIntFunction<Throwable,? extends Completable> retryWhen) Re-subscribes to this Single if an error is emitted and the Completable returned by the supplied BiIntFunction completes successfully.
Cancellable	subscribe(Consumer<? super T> resultConsumer) Subscribe to this Single, emits the result to the passed Consumer and log any SingleSource.Subscriber.onError(Throwable).
protected void	subscribeInternal(SingleSource.Subscriber<? super T> subscriber) A internal subscribe method similar to SingleSource.subscribe(Subscriber) which can be used by different implementations to subscribe.
Single<T>	subscribeOn(Executor executor) Creates a new Single that will use the passed Executor to invoke the following methods: All Cancellable methods. The handleSubscribe(SingleSource.Subscriber) method. This method does not override preceding Executors, if any, specified for this Single.
Single<T>	subscribeOnOverride(Executor executor) Creates a new Single that will use the passed Executor to invoke the following methods: All Cancellable methods. The handleSubscribe(SingleSource.Subscriber) method. This method overrides preceding Executors, if any, specified for this Single.
Single<T>	subscribeShareContext() Signifies that when the returned Single is subscribed to, the AsyncContext will be shared instead of making a copy.
static <T> Single<T>	succeeded(T value) Creates a realized Single which always completes successfully with the provided value.
Completable	toCompletable() Ignores the result of this Single and forwards the termination signal to the returned Completable.
CompletionStage<T>	toCompletionStage() Convert this Single to a CompletionStage.
Future<T>	toFuture() Convert this Single to a Future.
Publisher<T>	toPublisher() Converts this Single to a Publisher.
Single<T>	whenCancel(Runnable onCancel) Invokes the onCancel Runnable argument when Cancellable.cancel() is called for Subscriptions of the returned Single.
Single<T>	whenFinally(Runnable doFinally) Invokes the whenFinally Runnable argument exactly once, when any of the following terminal methods are called: SingleSource.Subscriber.onSuccess(Object) SingleSource.Subscriber.onError(Throwable) Cancellable.cancel() for Subscriptions/SingleSource.Subscribers of the returned Single.
Single<T>	whenOnError(Consumer<Throwable> onError) Invokes the onError Consumer argument when SingleSource.Subscriber.onError(Throwable) is called for SingleSource.Subscribers of the returned Single.
Single<T>	whenOnSubscribe(Consumer<Cancellable> onSubscribe) Invokes the onSubscribe Consumer argument when SingleSource.Subscriber.onSubscribe(Cancellable) is called for SingleSource.Subscribers of the returned Single.
Single<T>	whenOnSuccess(Consumer<? super T> onSuccess) Invokes the onSuccess Consumer argument when SingleSource.Subscriber.onSuccess(Object) is called for SingleSource.Subscribers of the returned Single.
Single<T>	whenSubscriber(Supplier<? extends SingleSource.Subscriber<? super T>> subscriberSupplier) Creates a new SingleSource.Subscriber (via the subscriberSupplier argument) for each new subscribe and invokes methods on that SingleSource.Subscriber when the corresponding methods are called for SingleSource.Subscribers of the returned Single.

Methods inherited from class Object

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

Constructor Detail

Single

protected Single()

New instance.

Method Detail

map

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

Maps the result of this single to a different type. Error, if any is forwarded to the returned Single.

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

     T tResult = resultOfThisSingle();
     R rResult = mapper.apply(tResult);
 

Type Parameters:

R - Type of the returned Single.

Parameters:

mapper - To convert this result to other.

Returns:

A new Single that will now have the result of type R.

recoverWith

public final Single<T> recoverWith(Function<Throwable,? extends Single<? extends T>> nextFactory)

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

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

     T result;
     try {
         result = resultOfThisSingle();
     } catch (Throwable cause) {
         // Note that nextFactory returning a error Single is like re-throwing (nextFactory shouldn't throw).
         result = nextFactory.apply(cause);
     }
     return result;
 

Parameters:

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

Returns:

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

flatMap

public final <R> Single<R> flatMap(Function<? super T,? extends Single<? extends R>> next)

Returns a Single that mirrors emissions from the Single returned by next. Any error emitted by this Single is forwarded to the returned Single.

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

     T tResult = resultOfThisSingle();
     R rResult = mapper.apply(tResult); // Asynchronous result is flatten into a value by this operator.
 

Type Parameters:

R - Type of the result of the resulting Single.

Parameters:

next - Function to give the next Single.

Returns:

New Single that switches to the Single returned by next after this Single completes successfully.

flatMapCompletable

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

Returns a Completable that mirrors emissions from the Completable returned by next. Any error emitted by this Single is forwarded to the returned Completable.

This method is similar to map(Function) but the result is asynchronous with either complete/error status in sequential programming similar to:

     T tResult = resultOfThisSingle();
     mapper.apply(tResult); // Asynchronous result is flatten into a error or completion by this operator.
 

Parameters:

next - Function to give the next Completable.

Returns:

New Completable that switches to the Completable returned by next after this Single completes successfully.

flatMapPublisher

public final <R> Publisher<R> flatMapPublisher(Function<? super T,? extends Publisher<? extends R>> next)

Returns a Publisher that mirrors emissions from the Publisher returned by next. Any error emitted by this Single is forwarded to the returned Publisher.

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

     T tResult = resultOfThisSingle();
     // Asynchronous result from mapper is flatten into collection of values.
     for (R rResult : mapper.apply(tResult)) {
          // process rResult
     }
 

Type Parameters:

R - Type of objects emitted by the returned Publisher.

Parameters:

next - Function to give the next Publisher.

Returns:

New Publisher that switches to the Publisher returned by next after this Single completes successfully.

whenOnSuccess

public final Single<T> whenOnSuccess(Consumer<? super T> onSuccess)

Invokes the onSuccess Consumer argument when SingleSource.Subscriber.onSuccess(Object) is called for SingleSource.Subscribers of the returned Single.

The order in which onSuccess will be invoked relative to SingleSource.Subscriber.onSuccess(Object) is undefined. If you need strict ordering see beforeOnSuccess(Consumer) and afterOnSuccess(Consumer).

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

  T result = resultOfThisSingle();
  // NOTE: The order of operations here is not guaranteed by this method!
  nextOperation(result);
  onSuccess.accept(result);
 

Parameters:

onSuccess - Invoked when SingleSource.Subscriber.onSuccess(Object) is called for SingleSource.Subscribers of the returned Single. MUST NOT throw.

Returns:

The new Single.

See Also:

beforeOnSuccess(Consumer), afterOnSuccess(Consumer)

whenOnError

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

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

The order in which onError will be invoked relative to SingleSource.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 {
    T result = resultOfThisSingle();
  } catch (Throwable cause) {
      // NOTE: The order of operations here is not guaranteed by this method!
      nextOperation(cause);
      onError.accept(cause);
  }
 

Parameters:

onError - Invoked when SingleSource.Subscriber.onError(Throwable) is called for SingleSource.Subscribers of the returned Single. MUST NOT throw.

Returns:

The new Single.

See Also:

beforeOnError(Consumer), afterOnError(Consumer)

whenFinally

public final Single<T> whenFinally(Runnable doFinally)

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

• SingleSource.Subscriber.onSuccess(Object)
• SingleSource.Subscriber.onError(Throwable)
• Cancellable.cancel()

for Subscriptions/SingleSource.Subscribers of the returned Single.

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 {
      T result = resultOfThisSingle();
  } finally {
      // NOTE: The order of operations here is not guaranteed by this method!
      nextOperation(); // Maybe notifying of cancellation, or termination
      whenFinally.run();
  }
 

Parameters:

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

• SingleSource.Subscriber.onSuccess(Object)
• SingleSource.Subscriber.onError(Throwable)
• Cancellable.cancel()

for Subscriptions/SingleSource.Subscribers of the returned Single. MUST NOT throw.

Returns:

The new Single.

See Also:

afterFinally(Runnable), beforeFinally(Runnable)

whenCancel

public final Single<T> whenCancel(Runnable onCancel)

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

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 Single. MUST NOT throw.

Returns:

The new Single.

See Also:

beforeCancel(Runnable), afterCancel(Runnable)

idleTimeout

public final Single<T> idleTimeout(long duration,
                                   TimeUnit unit)

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

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

Parameters:

duration - The time duration which is allowed to elapse before SingleSource.Subscriber.onSuccess(Object).

unit - The units for duration.

Returns:

a new Single that will mimic the signals of this Single but will terminate with a TimeoutException if time duration elapses before SingleSource.Subscriber.onSuccess(Object).

See Also:

ReactiveX timeout operator.

idleTimeout

public final Single<T> idleTimeout(long duration,
                                   TimeUnit unit,
                                   Executor timeoutExecutor)

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

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

Parameters:

duration - The time duration which is allowed to elapse before SingleSource.Subscriber.onSuccess(Object).

unit - The units for duration.

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

Returns:

a new Single that will mimic the signals of this Single but will terminate with a TimeoutException if time duration elapses before SingleSource.Subscriber.onSuccess(Object).

See Also:

ReactiveX timeout operator.

idleTimeout

public final Single<T> idleTimeout(Duration duration)

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

In the event of timeout any Cancellable from SingleSource.Subscriber.onSubscribe(Cancellable) will be cancelled and the associated SingleSource.Subscriber will be terminated. SingleSource.Subscriber will via terminated.

Parameters:

duration - The time duration which is allowed to elapse before SingleSource.Subscriber.onSuccess(Object).

Returns:

a new Single that will mimic the signals of this Single but will terminate with a TimeoutException if time duration elapses before SingleSource.Subscriber.onSuccess(Object).

See Also:

ReactiveX timeout operator.

idleTimeout

public final Single<T> idleTimeout(Duration duration,
                                   Executor timeoutExecutor)

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

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

Parameters:

duration - The time duration which is allowed to elapse before SingleSource.Subscriber.onSuccess(Object).

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

Returns:

a new Single that will mimic the signals of this Single but will terminate with a TimeoutException if time duration elapses before SingleSource.Subscriber.onSuccess(Object).

See Also:

ReactiveX timeout operator.

concat

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

Returns a Publisher that first emits the result of this Single and then subscribes and emits result of next Single. Any error emitted by this Single or next Single 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:

     Pair<T, T> p = new Pair<>();
     p.first = resultOfThisSingle();
     p.second = nextSingle();
     return p;
 

Parameters:

next - Single to concat.

Returns:

New Publisher that first emits the result of this Single and then subscribes and emits result of next Single.

concat

public final Single<T> concat(Completable next)

Returns a Single that emits the result of this Single after next Completable terminates successfully. next Completable will only be subscribed to after this Single terminates successfully. Any error emitted by this Single or next Completable is forwarded to the returned Single.

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

     T result = resultOfThisSingle();
     nextCompletable(); // Note this either completes successfully, or throws an error.
     return result;
 

Parameters:

next - Completable to concat.

Returns:

New Single that emits the result of this Single after next Completable terminates successfully.

concat

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

Returns a Publisher that first emits the result of this Single and then subscribes and emits all elements from next Publisher. Any error emitted by this Single or next Publisher 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 = new ...;
     results.add(resultOfThisSingle());
     results.addAll(nextStream());
     return results;
 

Parameters:

next - Publisher to concat.

Returns:

New Publisher that first emits the result of this Single and then subscribes and emits all elements from next Publisher.

retry

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

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

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

     public T execute() {
         return execute(0);
     }

     private T execute(int attempts) {
         try {
             return resultOfThisSingle();
         } catch (Throwable cause) {
             if (shouldRetry.apply(attempts + 1, cause)) {
                 return execute(attempts + 1);
             } else {
                 throw cause;
             }
         }
     }
 

Parameters:

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

Returns:

A Single that emits the result from this Single or re-subscribes if an error is emitted and if the passed BiIntPredicate returned true.

See Also:

ReactiveX retry operator.

retryWhen

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

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

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 T execute() {
         return execute(0);
     }

     private T execute(int attempts) {
         try {
             return resultOfThisSingle();
         } catch (Throwable cause) {
             try {
                 shouldRetry.apply(attempts + 1, cause); // Either throws or completes normally
                 execute(attempts + 1);
             } catch (Throwable ignored) {
                 throw cause;
             }
         }
     }
 

Parameters:

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

Returns:

A Single that emits the result from this Single or 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 Single when it completes and the passed IntPredicate returns true.

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.add(resultOfThisSingle());
     } 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 Single and from all re-subscriptions whenever the operation is repeated.

See Also:

ReactiveX repeat operator.

repeatWhen

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

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

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.add(resultOfThisSingle());
         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 Single is re-subscribed when this Completable completes.

Returns:

A Publisher that emits all items from this Single and from all re-subscriptions whenever the operation is repeated.

See Also:

ReactiveX retry operator.

beforeOnSubscribe

public final Single<T> beforeOnSubscribe(Consumer<Cancellable> onSubscribe)

Invokes the onSubscribe Consumer argument before SingleSource.Subscriber.onSubscribe(Cancellable) is called for SingleSource.Subscribers of the returned Single.

Parameters:

onSubscribe - Invoked before SingleSource.Subscriber.onSubscribe(Cancellable) is called for SingleSource.Subscribers of the returned Single. MUST NOT throw.

Returns:

The new Single.

beforeOnSuccess

public final Single<T> beforeOnSuccess(Consumer<? super T> onSuccess)

Invokes the onSuccess Consumer argument before SingleSource.Subscriber.onSuccess(Object) is called for SingleSource.Subscribers of the returned Single.

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

  T result = resultOfThisSingle();
  onSuccess.accept(result);
  nextOperation(result);
 

Parameters:

onSuccess - Invoked before SingleSource.Subscriber.onSuccess(Object) is called for SingleSource.Subscribers of the returned Single. MUST NOT throw.

Returns:

The new Single.

beforeOnError

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

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

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

  try {
    T result = resultOfThisSingle();
  } catch (Throwable cause) {
      onError.accept(cause);
      nextOperation(cause);
  }
 

Parameters:

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

Returns:

The new Single.

beforeCancel

public final Single<T> beforeCancel(Runnable onCancel)

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

Parameters:

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

Returns:

The new Single.

beforeFinally

public final Single<T> beforeFinally(Runnable doFinally)

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

• SingleSource.Subscriber.onSuccess(Object)
• SingleSource.Subscriber.onError(Throwable)
• Cancellable.cancel()

for Subscriptions/SingleSource.Subscribers of the returned Single.

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

  try {
      T result = resultOfThisSingle();
  } finally {
      whenFinally.run();
      nextOperation(); // Maybe notifying of cancellation, or termination
  }
 

Parameters:

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

• SingleSource.Subscriber.onSuccess(Object)
• SingleSource.Subscriber.onError(Throwable)
• Cancellable.cancel()

for Subscriptions/SingleSource.Subscribers of the returned Single. MUST NOT throw.

Returns:

The new Single.

beforeSubscriber

public final Single<T> beforeSubscriber(Supplier<? extends SingleSource.Subscriber<? super T>> subscriberSupplier)

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

Parameters:

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

Returns:

The new Single.

afterOnSubscribe

public final Single<T> afterOnSubscribe(Consumer<Cancellable> onSubscribe)

Invokes the onSubscribe Consumer argument after SingleSource.Subscriber.onSubscribe(Cancellable) is called for SingleSource.Subscribers of the returned Single.

Parameters:

onSubscribe - Invoked after SingleSource.Subscriber.onSubscribe(Cancellable) is called for SingleSource.Subscribers of the returned Single. MUST NOT throw.

Returns:

The new Single.

whenOnSubscribe

public final Single<T> whenOnSubscribe(Consumer<Cancellable> onSubscribe)

Invokes the onSubscribe Consumer argument when SingleSource.Subscriber.onSubscribe(Cancellable) is called for SingleSource.Subscribers of the returned Single.

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

Parameters:

onSubscribe - Invoked when SingleSource.Subscriber.onSubscribe(Cancellable) is called for SingleSource.Subscribers of the returned Single. MUST NOT throw.

Returns:

The new Single.

See Also:

beforeOnSubscribe(Consumer), afterOnSubscribe(Consumer)

afterOnSuccess

public final Single<T> afterOnSuccess(Consumer<? super T> onSuccess)

Invokes the onSuccess Consumer argument after SingleSource.Subscriber.onSuccess(Object) is called for SingleSource.Subscribers of the returned Single.

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

  T result = resultOfThisSingle();
  nextOperation(result);
  onSuccess.accept(result);
 

Parameters:

onSuccess - Invoked after SingleSource.Subscriber.onSuccess(Object) is called for SingleSource.Subscribers of the returned Single. MUST NOT throw.

Returns:

The new Single.

afterOnError

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

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

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

  try {
    T result = resultOfThisSingle();
  } catch (Throwable cause) {
      nextOperation(cause);
      onError.accept(cause);
  }
 

Parameters:

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

Returns:

The new Single.

afterCancel

public final Single<T> afterCancel(Runnable onCancel)

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

Parameters:

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

Returns:

The new Single.

afterFinally

public final Single<T> afterFinally(Runnable doFinally)

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

• SingleSource.Subscriber.onSuccess(Object)
• SingleSource.Subscriber.onError(Throwable)
• Cancellable.cancel()

for Subscriptions/SingleSource.Subscribers of the returned Single.

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

  try {
      T result = resultOfThisSingle();
  } finally {
      nextOperation(); // Maybe notifying of cancellation, or termination
      whenFinally.run();
  }
 

Parameters:

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

• SingleSource.Subscriber.onSuccess(Object)
• SingleSource.Subscriber.onError(Throwable)
• Cancellable.cancel()

for Subscriptions/SingleSource.Subscribers of the returned Single. MUST NOT throw.

Returns:

The new Single.

afterSubscriber

public final Single<T> afterSubscriber(Supplier<? extends SingleSource.Subscriber<? super T>> subscriberSupplier)

Creates a new SingleSource.Subscriber (via the subscriberSupplier argument) on each call to subscribe and invokes all the SingleSource.Subscriber methods after the SingleSource.Subscribers of the returned Single.

Parameters:

subscriberSupplier - Creates a new SingleSource.Subscriber on each call to subscribe and invokes all the SingleSource.Subscriber methods after the SingleSource.Subscribers of the returned Single. SingleSource.Subscriber methods MUST NOT throw.

Returns:

The new Single.

whenSubscriber

public final Single<T> whenSubscriber(Supplier<? extends SingleSource.Subscriber<? super T>> subscriberSupplier)

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

Parameters:

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

Returns:

The new Single.

publishOn

public final Single<T> publishOn(Executor executor)

Creates a new Single that will use the passed Executor to invoke all SingleSource.Subscriber methods. This method does not override preceding Executors, if any, specified for this Single. Only subsequent operations, if any, added in this execution chain will use this Executor. If such an override is required, publishOnOverride(Executor) can be used.

Parameters:

executor - Executor to use.

Returns:

A new Single that will use the passed Executor to invoke all methods on the SingleSource.Subscriber.

publishOnOverride

public final Single<T> publishOnOverride(Executor executor)

Creates a new Single that will use the passed Executor to invoke all SingleSource.Subscriber methods. This method overrides preceding Executors, if any, specified for this Single. That is to say preceding and subsequent operations for this execution chain will use this Executor for invoking all SingleSource.Subscriber methods. If such an override is not required, publishOn(Executor) can be used.

Parameters:

executor - Executor to use.

Returns:

A new Single that will use the passed Executor to invoke all methods of SingleSource.Subscriber, Cancellable and handleSubscribe(SingleSource.Subscriber) both for the returned Single as well as this Single.

subscribeOn

public final Single<T> subscribeOn(Executor executor)

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

• All Cancellable methods.
• The handleSubscribe(SingleSource.Subscriber) method.

This method does not override preceding Executors, if any, specified for this Single. Only subsequent operations, if any, added in this execution chain will use this Executor. If such an override is required, subscribeOnOverride(Executor) can be used.

Parameters:

executor - Executor to use.

Returns:

A new Single that will use the passed Executor to invoke all methods of Cancellable and handleSubscribe(SingleSource.Subscriber).

subscribeOnOverride

public final Single<T> subscribeOnOverride(Executor executor)

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

• All Cancellable methods.
• The handleSubscribe(SingleSource.Subscriber) method.

This method overrides preceding Executors, if any, specified for this Single. That is to say preceding and subsequent operations for this execution chain will use this Executor for invoking the above specified methods. If such an override is not required, subscribeOn(Executor) can be used.

Parameters:

executor - Executor to use.

Returns:

A new Single that will use the passed Executor to invoke all methods of Cancellable and handleSubscribe(SingleSource.Subscriber) both for the returned Single as well as this Single.

publishAndSubscribeOn

public final Single<T> publishAndSubscribeOn(Executor executor)

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

• All SingleSource.Subscriber methods.
• All Cancellable methods.
• The handleSubscribe(SingleSource.Subscriber) method.

This method does not override preceding Executors, if any, specified for this Single. Only subsequent operations, if any, added in this execution chain will use this Executor. If such an override is required, publishAndSubscribeOnOverride(Executor) can be used.

Parameters:

executor - Executor to use.

Returns:

A new Single that will use the passed Executor to invoke all methods SingleSource.Subscriber, Cancellable and handleSubscribe(SingleSource.Subscriber).

publishAndSubscribeOnOverride

public final Single<T> publishAndSubscribeOnOverride(Executor executor)

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

• All SingleSource.Subscriber methods.
• All Cancellable methods.
• The handleSubscribe(SingleSource.Subscriber) method.

This method overrides preceding Executors, if any, specified for this Single. That is to say preceding and subsequent operations for this execution chain will use this Executor. If such an override is not required, publishAndSubscribeOn(Executor) can be used.

Parameters:

executor - Executor to use.

Returns:

A new Single that will use the passed Executor to invoke all methods of SingleSource.Subscriber, Cancellable and handleSubscribe(SingleSource.Subscriber) both for the returned Single as well as this Single.

subscribeShareContext

public final Single<T> subscribeShareContext()

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

This operator only impacts behavior if the returned Single 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 Single that will share the AsyncContext instead of making a copy when subscribed to.

liftSync

public final <R> Single<R> liftSync(SingleOperator<? 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 will wrap the SingleSource.Subscriber using the provided operator argument before subscribing to this Single.

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

The original -> modified "operator" MUST be "synchronous" in that it does not interact with the original SingleSource.Subscriber from outside the modified SingleSource.Subscriber or Cancellable 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(SingleOperator).

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 this Single and the return is the "modified" SingleSource.Subscriber that provides custom operator business logic.

Returns:

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

See Also:

liftAsync(SingleOperator)

liftAsync

public final <R> Single<R> liftAsync(SingleOperator<? 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 will wrap the SingleSource.Subscriber using the provided operator argument before subscribing to this Single.

     Publisher<X> pub = ...;
     pub.map(..) // Aw
        .liftAsync(original -> modified)
        .afterFinally(..) // B
 

The original -> modified "operator" MAY be "asynchronous" in that it may interact with the original SingleSource.Subscriber from outside the modified SingleSource.Subscriber or Cancellable threads. More specifically:

• all of the SingleSource.Subscriber invocations going "downstream" (i.e. from A to B above) MAY be offloaded via an Executor
• all of the Cancellable 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 Single.

Parameters:

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

Returns:

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

See Also:

liftSync(SingleOperator)

toPublisher

public final Publisher<T> toPublisher()

Converts this Single to a Publisher.

Returns:

A Publisher that emits at most a single item which is emitted by this Single.

toCompletable

public final Completable toCompletable()

Ignores the result of this Single and forwards the termination signal to the returned Completable.

Returns:

A Completable that mirrors the terminal signal from this Single.

ignoreElement

public final Completable ignoreElement()

Ignores the result of this Single and forwards the termination signal to the returned Completable.

Returns:

A Completable that mirrors the terminal signal from this Single.

toCompletionStage

public final CompletionStage<T> toCompletionStage()

Convert this Single to a CompletionStage.

Returns:

A CompletionStage that mirrors the terminal signal from this Single.

toFuture

public final Future<T> toFuture()

Convert this Single to a Future.

Returns:

A Future that mirrors the terminal signal from this Single.

subscribeInternal

protected final void subscribeInternal(SingleSource.Subscriber<? super T> subscriber)

A internal subscribe method similar to SingleSource.subscribe(Subscriber) which can be used by different implementations to subscribe.

Parameters:

subscriber - SingleSource.Subscriber to subscribe for the result.

subscribe

public final Cancellable subscribe(Consumer<? super T> resultConsumer)

Subscribe to this Single, emits the result to the passed Consumer and log any SingleSource.Subscriber.onError(Throwable).

Parameters:

resultConsumer - Consumer to accept the result of this Single.

Returns:

Cancellable used to invoke Cancellable.cancel() on the parameter of SingleSource.Subscriber.onSubscribe(Cancellable) for this Single.

handleSubscribe

protected abstract void handleSubscribe(SingleSource.Subscriber<? super T> subscriber)

Handles a subscriber to this Single.

Parameters:

subscriber - the subscriber.

succeeded

public static <T> Single<T> succeeded(@Nullable
                                      T value)

Creates a realized Single which always completes successfully with the provided value.

Type Parameters:

T - Type of the Single.

Parameters:

value - result of the Single.

Returns:

A new Single.

fromCallable

public static <T> Single<T> fromCallable(Callable<T> callable)

Creates a Single which when subscribed will invoke Callable.call() on the passed Callable and emit the value returned by that invocation from the returned Single. Any error emitted by the Callable will terminate the returned Single with the same error.

Blocking inside Callable.call() will in turn block the subscribe call to the returned Single. If this behavior is undesirable then the returned Single should be offloaded using one of the operators that offloads the subscribe call (eg: subscribeOn(Executor), publishAndSubscribeOn(Executor)).

Type Parameters:

T - Type of the Single.

Parameters:

callable - Callable which supplies the result of the Single.

Returns:

A new Single.

fromSupplier

public static <T> Single<T> fromSupplier(Supplier<T> supplier)

Creates a Single which when subscribed will invoke Supplier.get() on the passed Supplier and emit the value returned by that invocation from the returned Single. Any error emitted by the Supplier will terminate the returned Single with the same error.

Blocking inside Supplier.get() will in turn block the subscribe call to the returned Single. If this behavior is undesirable then the returned Single should be offloaded using one of the operators that offloads the subscribe call (eg: subscribeOn(Executor), publishAndSubscribeOn(Executor)).

Type Parameters:

T - Type of the Single.

Parameters:

supplier - Supplier which supplies the result of the Single.

Returns:

A new Single.

failed

public static <T> Single<T> failed(Throwable cause)

Creates a realized Single which always completes with the provided error cause.

Type Parameters:

T - Type of the Single.

Parameters:

cause - result of the Single.

Returns:

A new Single.

never

public static <T> Single<T> never()

Creates a Single that never terminates.

Type Parameters:

T - Type of the Single.

Returns:

A new Single.

defer

public static <T> Single<T> defer(Supplier<? extends Single<? extends T>> singleSupplier)

Defer creation of a Single till it is subscribed to.

Type Parameters:

T - Type of the Single.

Parameters:

singleSupplier - Supplier to create a new Single every time the returned Single is subscribed.

Returns:

A new Single that creates a new Single using singleSupplier every time it is subscribed and forwards all items and terminal events from the newly created Single to its SingleSource.Subscriber.

fromFuture

public static <T> Single<T> fromFuture(Future<? extends T> future)

Convert from a Future to a Single via Future.get().

Note that because Future only presents blocking APIs to extract the result, so the process of getting the results will block. The caller of subscribe is responsible for offloading if necessary, and also offloading if Cancellable.cancel() will be called and this operation may block.

To apply a timeout see idleTimeout(long, TimeUnit) and related methods.

Type Parameters:

T - The data type the Future provides when complete.

Parameters:

future - The Future to convert.

Returns:

A Single that derives results from Future.

See Also:

idleTimeout(long, TimeUnit)

collectUnordered

public static <T> Single<Collection<T>> collectUnordered(Iterable<? extends Single<? extends T>> singles)

Asynchronously collects results of individual Singles returned by the passed Iterable into a single Collection.

This will actively subscribe to a limited number of Singles concurrently, in order to alter the defaults, collectUnordered(Iterable, int) should be used.

If any of the Singles terminate with an error, returned Single will immediately terminate with that error. In such a case, any in progress Singles will be cancelled. In order to delay error termination use collectUnorderedDelayError(Iterable).

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

      List<T> result = ...;// assume this is thread safe
      for (Future<T> ft: futures) { // Provided Futures (analogous to the Singles here)
          // This is an approximation, this operator does not provide any ordering guarantees for the results.
          result.add(ft.get());
      }
      return result;
 

Type Parameters:

T - Type of the result of the individual Singles

Parameters:

singles - Iterable of Singles, results of which are to be collected.

Returns:

A Single producing a Collection of all values produced by the individual Singles. There is no guarantee of the order of the values in the produced Collection as compared to the order of Singles passed to this method.

collectUnordered

@SafeVarargs
public static <T> Single<Collection<T>> collectUnordered(Single<? extends T>... singles)

Asynchronously collects results of the passed Singles into a single Collection.

This will actively subscribe to a limited number of Singles concurrently, in order to alter the defaults, collectUnordered(int, Single[]) should be used.

If any of the Singles terminate with an error, returned Single will immediately terminate with that error. In such a case, any in progress Singles will be cancelled. In order to delay error termination use collectUnorderedDelayError(Single[]).

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

      List<T> result = ...;// assume this is thread safe
      for (Future<T> ft: futures) { // Provided Futures (analogous to the Singles here)
          // This is an approximation, this operator does not provide any ordering guarantees for the results.
          result.add(ft.get());
      }
      return result;
 

Type Parameters:

T - Type of the result of the individual Singles

Parameters:

singles - Singles, results of which are to be collected.

Returns:

A Single producing a Collection of all values produced by the individual Singles. There is no guarantee of the order of the values in the produced Collection as compared to the order of Singles passed to this method.

collectUnordered

public static <T> Single<Collection<T>> collectUnordered(Iterable<? extends Single<? extends T>> singles,
                                                         int maxConcurrency)

Asynchronously collects results of individual Singles returned by the passed Iterable into a single Collection.

If any of the Singles terminate with an error, returned Single will immediately terminate with that error. In such a case, any in progress Singles will be cancelled. In order to delay error termination use collectUnorderedDelayError(Iterable, int).

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

      List<T> result = ...;// assume this is thread safe
      for (Future<T> ft: futures) { // Provided Futures (analogous to the Singles here)
          // This is an approximation, this operator does not provide any ordering guarantees for the results.
          result.add(ft.get());
      }
      return result;
 

Type Parameters:

T - Type of the result of the individual Singles

Parameters:

singles - Iterable of Singles, results of which are to be collected.

maxConcurrency - Maximum number of Singles that will be active at any point in time.

Returns:

A Single producing a Collection of all values produced by the individual Singles. There is no guarantee of the order of the values in the produced Collection as compared to the order of Singles passed to this method.

collectUnordered

@SafeVarargs
public static <T> Single<Collection<T>> collectUnordered(int maxConcurrency,
                                                                      Single<? extends T>... singles)

Asynchronously collects results of the passed Singles into a single Collection.

If any of the Singles terminate with an error, returned Single will immediately terminate with that error. In such a case, any in progress Singles will be cancelled. In order to delay error termination use collectUnorderedDelayError(int, Single[]).

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

      List<T> result = ...;// assume this is thread safe
      for (Future<T> ft: futures) { // Provided Futures (analogous to the Singles here)
          // This is an approximation, this operator does not provide any ordering guarantees for the results.
          result.add(ft.get());
      }
      return result;
 

Type Parameters:

T - Type of the result of the individual Singles

Parameters:

maxConcurrency - Maximum number of Singles that will be active at any point in time.

singles - Singles, results of which are to be collected.

Returns:

A Single producing a Collection of all values produced by the individual Singles. There is no guarantee of the order of the values in the produced Collection as compared to the order of Singles passed to this method.

collectUnorderedDelayError

public static <T> Single<Collection<T>> collectUnorderedDelayError(Iterable<? extends Single<? extends T>> singles)

Asynchronously collects results of individual Singles returned by the passed Iterable into a single Collection.

This will actively subscribe to a limited number of Singles concurrently, in order to alter the defaults, collectUnorderedDelayError(Iterable, int).

If any of the Singles terminate with an error, returned Single will wait for termination till all the other Singles have been subscribed and terminated. If it is expected for the returned Single to terminate on the first failing Single, collectUnordered(Iterable) should be used.

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

      List<T> result = ...;// assume this is thread safe
      List<Throwable> errors = ...;  // assume this is thread safe
      for (Future<T> ft: futures) { // Provided Futures (analogous to the Singles here)
             // This is an approximation, this operator does not provide any ordering guarantees for the results.
             try {
                result.add(ft.get());
             } catch(Throwable t) {
                errors.add(t);
             }
      }
     if (errors.isEmpty()) {
         return rResults;
     }
     createAndThrowACompositeException(errors);
 

Type Parameters:

T - Type of the result of the individual Singles

Parameters:

singles - Iterable of Singles, results of which are to be collected.

Returns:

A Single producing a Collection of all values produced by the individual Singles. There is no guarantee of the order of the values in the produced Collection as compared to the order of Singles passed to this method.

collectUnorderedDelayError

@SafeVarargs
public static <T> Single<Collection<T>> collectUnorderedDelayError(Single<? extends T>... singles)

Asynchronously collects results of the passed Singles into a single Collection.

This will actively subscribe to a limited number of Singles concurrently, in order to alter the defaults, collectUnordered(int, Single[]).

If any of the Singles terminate with an error, returned Single will wait for termination till all the other Singles have been subscribed and terminated. If it is expected for the returned Single to terminate on the first failing Single, collectUnordered(Single[]) should be used.

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

      List<T> result = ...;// assume this is thread safe
      List<Throwable> errors = ...;  // assume this is thread safe
      for (Future<T> ft: futures) { // Provided Futures (analogous to the Singles here)
              // This is an approximation, this operator does not provide any ordering guarantees for the results.
             try {
                result.add(ft.get());
             } catch(Throwable t) {
                errors.add(t);
             }
      }
     if (errors.isEmpty()) {
         return rResults;
     }
     createAndThrowACompositeException(errors);
 

Type Parameters:

T - Type of the result of the individual Singles

Parameters:

singles - Singles, results of which are to be collected.

Returns:

A Single producing a Collection of all values produced by the individual Singles. There is no guarantee of the order of the values in the produced Collection as compared to the order of Singles passed to this method.

collectUnorderedDelayError

public static <T> Single<Collection<T>> collectUnorderedDelayError(Iterable<? extends Single<? extends T>> singles,
                                                                   int maxConcurrency)

Asynchronously collects results of individual Singles returned by the passed Iterable into a single Collection.

If any of the Singles terminate with an error, returned Single will wait for termination till all the other Singles have been subscribed and terminated. If it is expected for the returned Single to terminate on the first failing Single, collectUnordered(Iterable, int) should be used.

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

      List<T> result = ...;// assume this is thread safe
      List<Throwable> errors = ...;  // assume this is thread safe
      for (Future<T> ft: futures) { // Provided Futures (analogous to the Singles here)
             // This is an approximation, this operator does not provide any ordering guarantees for the results.
             try {
                result.add(ft.get());
             } catch(Throwable t) {
                errors.add(t);
             }
      }
     if (errors.isEmpty()) {
         return rResults;
     }
     createAndThrowACompositeException(errors);
 

Type Parameters:

T - Type of the result of the individual Singles

Parameters:

singles - Iterable of Singles, results of which are to be collected.

maxConcurrency - Maximum number of Singles that will be active at any point in time.

Returns:

A Single producing a Collection of all values produced by the individual Singles. There is no guarantee of the order of the values in the produced Collection as compared to the order of Singles passed to this method.

collectUnorderedDelayError

@SafeVarargs
public static <T> Single<Collection<T>> collectUnorderedDelayError(int maxConcurrency,
                                                                                Single<? extends T>... singles)

Asynchronously collects results of the passed Singles into a single Collection.

If any of the Singles terminate with an error, returned Single will wait for termination till all the other Singles have been subscribed and terminated. If it is expected for the returned Single to terminate on the first failing Single, collectUnordered(Iterable, int) should be used.

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

      List<T> result = ...;// assume this is thread safe
      List<Throwable> errors = ...;  // assume this is thread safe
      for (Future<T> ft: futures) { // Provided Futures (analogous to the Singles here)
             // This is an approximation, this operator does not provide any ordering guarantees for the results.
             try {
                result.add(ft.get());
             } catch(Throwable t) {
                errors.add(t);
             }
      }
     if (errors.isEmpty()) {
         return rResults;
     }
     createAndThrowACompositeException(errors);
 

Type Parameters:

T - Type of the result of the individual Singles

Parameters:

maxConcurrency - Maximum number of Singles that will be active at any point in time.

singles - Singles, results of which are to be collected.

Returns:

A Single producing a Collection of all values produced by the individual Singles. There is no guarantee of the order of the values in the produced Collection as compared to the order of Singles passed to this method.

fromStage

public static <T> Single<T> fromStage(CompletionStage<? extends T> stage)

Convert from a CompletionStage to a Single.

A best effort is made to propagate Cancellable.cancel() to the CompletionStage. Cancellation for CompletionStage implementations will result in exceptional completion and invoke user callbacks. If there is any blocking code involved in the cancellation process (including invoking user callbacks) you should investigate if using an Executor is appropriate.

Type Parameters:

T - The data type the CompletionStage provides when complete.

Parameters:

stage - The CompletionStage to convert.

Returns:

A Single that derives results from CompletionStage.