Package io.servicetalk.concurrent.api

Class Single<T>

  • Type Parameters:
    T - Type of the result of the single.
    Direct Known Subclasses:
    LegacyTestSingle, SubscribableSingle, TestSingle
    public abstract class Single<T>
extends java.lang.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 Detail

      • Single

        protected Single()
        New instance.

    • Method Detail

      • map

        public final <R> Single<R> map​(java.util.function.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 Single.

      • onErrorReturn

        public final <E extends java.lang.Throwable> Single<T> onErrorReturn​(java.lang.Class<E> type,
                                                                     java.util.function.Function<? super E,​? extends T> itemSupplier)
        Transform errors emitted on this Single which match type into SingleSource.Subscriber.onSuccess(Object) signal (e.g. swallows the error).

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

        
     T result = resultOfThisSingle();
     try {
         terminalOfThisSingle();
     } catch (Throwable cause) {
         if (!type.isInstance(cause)) {
           throw cause;
         }
         return itemSupplier.apply(cause);
     }
     return result;
        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 SingleSource.Subscriber.onSuccess(Object).
        Returns:
        A Single which transform errors emitted on this Single into SingleSource.Subscriber.onSuccess(Object) signal (e.g. swallows the error).
        See Also:
        ReactiveX catch operator.

      • onErrorMap

        public final Single<T> onErrorMap​(java.util.function.Function<? super java.lang.Throwable,​? extends java.lang.Throwable> mapper)
        Transform errors emitted on this Single into a different error.

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

        
     T result = resultOfThisSingle();
     try {
         terminalOfThisSingle();
     } catch (Throwable cause) {
         throw mapper.apply(cause);
     }
     return result;
        Parameters:
        mapper - returns the error used to terminate the returned Single.
        Returns:
        A Single which transform errors emitted on this Single into a different error.
        See Also:
        ReactiveX catch operator.

      • onErrorMap

        public final <E extends java.lang.Throwable> Single<T> onErrorMap​(java.lang.Class<E> type,
                                                                  java.util.function.Function<? super E,​? extends java.lang.Throwable> mapper)
        Transform errors emitted on this Single which match type into a different error.

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

        
     T result = resultOfThisSingle();
     try {
         terminalOfThisSingle();
     } catch (Throwable cause) {
         if (type.isInstance(cause)) {
           throw mapper.apply(cause);
         } else {
           throw cause;
         }
     }
     return result;
        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 Single.
        Returns:
        A Single which transform errors emitted on this Single into a different error.
        See Also:
        ReactiveX catch operator.

      • onErrorMap

        public final Single<T> onErrorMap​(java.util.function.Predicate<? super java.lang.Throwable> predicate,
                                  java.util.function.Function<? super java.lang.Throwable,​? extends java.lang.Throwable> mapper)
        Transform errors emitted on this Single which match predicate into a different error.

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

        
     T results = resultOfThisSingle();
     try {
         terminalOfThisSingle();
     } catch (Throwable cause) {
         if (predicate.test(cause)) {
           throw mapper.apply(cause);
         } else {
           throw cause;
         }
     }
     return result;
        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 Single.
        Returns:
        A Single which transform errors emitted on this Single into a different error.
        See Also:
        ReactiveX catch operator.

      • onErrorResume

        public final Single<T> onErrorResume​(java.util.function.Function<? super java.lang.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.

      • onErrorResume

        public final <E extends java.lang.Throwable> Single<T> onErrorResume​(java.lang.Class<E> type,
                                                                     java.util.function.Function<? super E,​? extends Single<? extends T>> nextFactory)
        Recover from errors emitted by this Single which match type 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) {
       if (type.isInstance(cause)) {
         // Note that nextFactory returning a error Single is like re-throwing (nextFactory shouldn't throw).
         result = nextFactory.apply(cause);
       } else {
           throw cause;
       }
     }
     return result;
        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 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.
        See Also:
        ReactiveX catch operator.

      • onErrorResume

        public final Single<T> onErrorResume​(java.util.function.Predicate<? super java.lang.Throwable> predicate,
                                     java.util.function.Function<? super java.lang.Throwable,​? extends Single<? extends T>> nextFactory)
        Recover from errors emitted by this Single which match predicate 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) {
       if (predicate.test(cause)) {
         // Note that nextFactory returning a error Single is like re-throwing (nextFactory shouldn't throw).
         result = nextFactory.apply(cause);
       } else {
           throw cause;
       }
     }
     return result;
        Parameters:
        predicate - returns true if the Throwable should be transformed via nextFactory. Returns false to propagate the original error.
        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.
        See Also:
        ReactiveX catch operator.

      • recoverWith

        @Deprecated
public final Single<T> recoverWith​(java.util.function.Function<? super java.lang.Throwable,​? extends Single<? extends T>> nextFactory)
        Deprecated.
        Use onErrorResume(Function).
        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​(java.util.function.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​(java.util.function.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​(java.util.function.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.

      • 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.

      • zipWith

        public final <T2,​R> Single<R> zipWith​(Single<? extends T2> other,
                                            java.util.function.BiFunction<? super T,​? super T2,​? extends R> zipper)
        Create a new Single that emits the results of a specified zipper BiFunction to items emitted by this and other.

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

        
      CompletableFuture<T> f1 = ...; // this
      CompletableFuture<T2> other = ...;
      CompletableFuture.allOf(f1, other).get(); // wait for all futures to complete
      return zipper.apply(f1.get(), other.get());
        Type Parameters:
        T2 - The type of other.
        R - The result type of the zipper.
        Parameters:
        other - The other Single to zip with.
        zipper - Used to combine the completed results for each item from singles.
        Returns:
        a new Single that emits the results of a specified zipper BiFunction to items emitted by this and other.
        See Also:
        ReactiveX zip operator.

      • zipWithDelayError

        public final <T2,​R> Single<R> zipWithDelayError​(Single<? extends T2> other,
                                                      java.util.function.BiFunction<? super T,​? super T2,​? extends R> zipper)
        Create a new Single that emits the results of a specified zipper BiFunction to items emitted by this and other. If any of the Singles terminate with an error, the returned Single will wait for termination till all the other Singles have been subscribed and terminated, and then terminate with the first error.

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

        
      CompletableFuture<T> f1 = ...; // this
      CompletableFuture<T2> other = ...;
      CompletableFuture.allOf(f1, other).get(); // wait for all futures to complete
      return zipper.apply(f1.get(), other.get());
        Type Parameters:
        T2 - The type of other.
        R - The result type of the zipper.
        Parameters:
        other - The other Single to zip with.
        zipper - Used to combine the completed results for each item from singles.
        Returns:
        a new Single that emits the results of a specified zipper BiFunction to items emitted by this and other.
        See Also:
        ReactiveX zip operator.

      • retry

        public final Single<T> retry​(BiIntPredicate<java.lang.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<java.lang.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​(java.util.function.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​(java.util.function.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.

      • beforeCancel

        public final Single<T> beforeCancel​(java.lang.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.

      • afterCancel

        public final Single<T> afterCancel​(java.lang.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.

      • 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: 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)

      • ambWith

        public final Single<T> ambWith​(Single<T> other)
        Creates a new Single that terminates with the result (either success or error) of either this Single or the passed other Single, whichever terminates first.

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

        
      for (Future<T> ft: futures) { // Provided Futures (analogous to the Singles here)
          // This is an approximation, this operator will pick the first result from either of the futures.
          return ft.get();
      }
        Parameters:
        other - Single with which the result of this Single is to be ambiguated.
        Returns:
        A new Single that terminates with the result (either success or error) of either this Single or the passed other Single, whichever terminates first.
        See Also:
        ReactiveX amb operator.

      • 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 java.util.concurrent.CompletionStage<T> toCompletionStage()
        Convert this Single to a CompletionStage.
        Returns:
        A CompletionStage that mirrors the terminal signal from this Single.

      • toFuture

        public final java.util.concurrent.Future<T> toFuture()
        Convert this Single to a Future.
        Returns:
        A Future that mirrors the terminal signal from 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​(java.util.concurrent.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​(java.util.function.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​(java.lang.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​(java.util.function.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​(java.util.concurrent.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 timeout(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:
        timeout(long, TimeUnit)

      • collectUnordered

        public static <T> Single<java.util.Collection<T>> collectUnordered​(java.lang.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<java.util.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<java.util.Collection<T>> collectUnordered​(java.lang.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<java.util.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<java.util.Collection<T>> collectUnorderedDelayError​(java.lang.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<java.util.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<java.util.Collection<T>> collectUnorderedDelayError​(java.lang.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<java.util.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​(java.util.concurrent.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.

      • amb

        @SafeVarargs
public static <T> Single<T> amb​(Single<? extends T>... singles)
        Creates a new Single that terminates with the result (either success or error) of whichever amongst the passed singles that terminates first.

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

        
      for (Future<T> ft: futures) { // Provided Futures (analogous to the Singles here)
          // This is an approximation, this operator will pick the first result from any of the futures.
          return ft.get();
      }
        Type Parameters:
        T - Type of the result of the individual Singles
        Parameters:
        singles - Singles the result of which are to be ambiguated.
        Returns:
        A new Single that terminates with the result (either success or error) of whichever amongst the passed singles that terminates first.
        See Also:
        ReactiveX amb operator.

      • amb

        public static <T> Single<T> amb​(java.lang.Iterable<Single<? extends T>> singles)
        Creates a new Single that terminates with the result (either success or error) of whichever amongst the passed singles that terminates first.

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

        
      for (Future<T> ft: futures) { // Provided Futures (analogous to the Singles here)
          // This is an approximation, this operator will pick the first result from any of the futures.
          return ft.get();
      }
        Type Parameters:
        T - Type of the result of the individual Singles
        Parameters:
        singles - Singles the result of which are to be ambiguated.
        Returns:
        A new Single that terminates with the result (either success or error) of whichever amongst the passed singles that terminates first.
        See Also:
        ReactiveX amb operator.

      • anyOf

        @SafeVarargs
public static <T> Single<T> anyOf​(Single<? extends T>... singles)
        Creates a new Single that terminates with the result (either success or error) of whichever amongst the passed singles that terminates first.

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

        
      for (Future<T> ft: futures) { // Provided Futures (analogous to the Singles here)
          // This is an approximation, this operator will pick the first result from any of the futures.
          return ft.get();
      }
        Type Parameters:
        T - Type of the result of the individual Singles
        Parameters:
        singles - Singles the result of which are to be ambiguated.
        Returns:
        A new Single that terminates with the result (either success or error) of whichever amongst the passed singles that terminates first.
        See Also:
        ReactiveX amb operator.

      • anyOf

        public static <T> Single<T> anyOf​(java.lang.Iterable<Single<? extends T>> singles)
        Creates a new Single that terminates with the result (either success or error) of whichever amongst the passed singles that terminates first.

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

        
      for (Future<T> ft: futures) { // Provided Futures (analogous to the Singles here)
          // This is an approximation, this operator will pick the first result from any of the futures.
          return ft.get();
      }
        Type Parameters:
        T - Type of the result of the individual Singles
        Parameters:
        singles - Singles the result of which are to be ambiguated.
        Returns:
        A new Single that terminates with the result (either success or error) of whichever amongst the passed singles that terminates first.
        See Also:
        ReactiveX amb operator.

      • zip

        public static <T1,​T2,​R> Single<R> zip​(Single<? extends T1> s1,
                                                  Single<? extends T2> s2,
                                                  java.util.function.BiFunction<? super T1,​? super T2,​? extends R> zipper)
        Create a new Single that emits the results of a specified zipper BiFunction to items emitted by s1 and s2.

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

        
      CompletableFuture<T1> f1 = ...; // s1
      CompletableFuture<T2> f2 = ...; // s2
      CompletableFuture.allOf(f1, f2).get(); // wait for all futures to complete
      return zipper.apply(f1.get(), f2.get());
        Type Parameters:
        T1 - The type for the first Single.
        T2 - The type for the second Single.
        R - The result type of the zipper.
        Parameters:
        s1 - The first Single to zip.
        s2 - The second Single to zip.
        zipper - Used to combine the completed results for each item from singles.
        Returns:
        a new Single that emits the results of a specified zipper BiFunction to items emitted by s1 and s2.
        See Also:
        ReactiveX zip operator.

      • zipDelayError

        public static <T1,​T2,​R> Single<R> zipDelayError​(Single<? extends T1> s1,
                                                            Single<? extends T2> s2,
                                                            java.util.function.BiFunction<? super T1,​? super T2,​? extends R> zipper)
        Create a new Single that emits the results of a specified zipper BiFunction to items emitted by s1 and s2. If any of the Singles terminate with an error, the returned Single will wait for termination till all the other Singles have been subscribed and terminated, and then terminate with the first error.

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

        
      CompletableFuture<T1> f1 = ...; // s1
      CompletableFuture<T2> f2 = ...; // s2
      CompletableFuture.allOf(f1, f2).get(); // wait for all futures to complete
      return zipper.apply(f1.get(), f2.get());
        Type Parameters:
        T1 - The type for the first Single.
        T2 - The type for the second Single.
        R - The result type of the zipper.
        Parameters:
        s1 - The first Single to zip.
        s2 - The second Single to zip.
        zipper - Used to combine the completed results for each item from singles.
        Returns:
        a new Single that emits the results of a specified zipper BiFunction to items emitted by s1 and s2.
        See Also:
        ReactiveX zip operator.

      • zip

        public static <T1,​T2,​T3,​R> Single<R> zip​(Single<? extends T1> s1,
                                                           Single<? extends T2> s2,
                                                           Single<? extends T3> s3,
                                                           Function3<? super T1,​? super T2,​? super T3,​? extends R> zipper)
        Create a new Single that emits the results of a specified zipper Function3 to items emitted by s1, s2, and s3.

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

        
      CompletableFuture<T1> f1 = ...; // s1
      CompletableFuture<T2> f2 = ...; // s2
      CompletableFuture<T3> f3 = ...; // s3
      CompletableFuture.allOf(f1, f2, f3).get(); // wait for all futures to complete
      return zipper.apply(f1.get(), f2.get(), f3.get());
        Type Parameters:
        T1 - The type for the first Single.
        T2 - The type for the second Single.
        T3 - The type for the third Single.
        R - The result type of the zipper.
        Parameters:
        s1 - The first Single to zip.
        s2 - The second Single to zip.
        s3 - The third Single to zip.
        zipper - Used to combine the completed results for each item from singles.
        Returns:
        a new Single that emits the results of a specified zipper Function3 to items emitted by s1, s2, and s3.
        See Also:
        ReactiveX zip operator.

      • zipDelayError

        public static <T1,​T2,​T3,​R> Single<R> zipDelayError​(Single<? extends T1> s1,
                                                                     Single<? extends T2> s2,
                                                                     Single<? extends T3> s3,
                                                                     Function3<? super T1,​? super T2,​? super T3,​? extends R> zipper)
        Create a new Single that emits the results of a specified zipper Function3 to items emitted by s1, s2, and s3. If any of the Singles terminate with an error, the returned Single will wait for termination till all the other Singles have been subscribed and terminated, and then terminate with the first error.

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

        
      CompletableFuture<T1> f1 = ...; // s1
      CompletableFuture<T2> f2 = ...; // s2
      CompletableFuture<T3> f3 = ...; // s3
      CompletableFuture.allOf(f1, f2, f3).get(); // wait for all futures to complete
      return zipper.apply(f1.get(), f2.get(), f3.get());
        Type Parameters:
        T1 - The type for the first Single.
        T2 - The type for the second Single.
        T3 - The type for the third Single.
        R - The result type of the zipper.
        Parameters:
        s1 - The first Single to zip.
        s2 - The second Single to zip.
        s3 - The third Single to zip.
        zipper - Used to combine the completed results for each item from singles.
        Returns:
        a new Single that emits the results of a specified zipper Function3 to items emitted by s1, s2, and s3.
        See Also:
        ReactiveX zip operator.

      • zip

        public static <T1,​T2,​T3,​T4,​R> Single<R> zip​(Single<? extends T1> s1,
                                                                    Single<? extends T2> s2,
                                                                    Single<? extends T3> s3,
                                                                    Single<? extends T4> s4,
                                                                    Function4<? super T1,​? super T2,​? super T3,​? super T4,​? extends R> zipper)
        Create a new Single that emits the results of a specified zipper Function4 to items emitted by s1, s2, s3, and s4.

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

        
      CompletableFuture<T1> f1 = ...; // s1
      CompletableFuture<T2> f2 = ...; // s2
      CompletableFuture<T3> f3 = ...; // s3
      CompletableFuture<T4> f4 = ...; // s3
      CompletableFuture.allOf(f1, f2, f3, f4).get(); // wait for all futures to complete
      return zipper.apply(f1.get(), f2.get(), f3.get(), f4.get());
        Type Parameters:
        T1 - The type for the first Single.
        T2 - The type for the second Single.
        T3 - The type for the third Single.
        T4 - The type for the fourth Single.
        R - The result type of the zipper.
        Parameters:
        s1 - The first Single to zip.
        s2 - The second Single to zip.
        s3 - The third Single to zip.
        s4 - The fourth Single to zip.
        zipper - Used to combine the completed results for each item from singles.
        Returns:
        a new Single that emits the results of a specified zipper Function4 to items emitted by s1, s2, s3, and s4.
        See Also:
        ReactiveX zip operator.

      • zipDelayError

        public static <T1,​T2,​T3,​T4,​R> Single<R> zipDelayError​(Single<? extends T1> s1,
                                                                              Single<? extends T2> s2,
                                                                              Single<? extends T3> s3,
                                                                              Single<? extends T4> s4,
                                                                              Function4<? super T1,​? super T2,​? super T3,​? super T4,​? extends R> zipper)
        Create a new Single that emits the results of a specified zipper Function4 to items emitted by s1, s2, s3, and s4. If any of the Singles terminate with an error, the returned Single will wait for termination till all the other Singles have been subscribed and terminated, and then terminate with the first error.

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

        
      CompletableFuture<T1> f1 = ...; // s1
      CompletableFuture<T2> f2 = ...; // s2
      CompletableFuture<T3> f3 = ...; // s3
      CompletableFuture<T4> f4 = ...; // s3
      CompletableFuture.allOf(f1, f2, f3, f4).get(); // wait for all futures to complete
      return zipper.apply(f1.get(), f2.get(), f3.get(), f4.get());
        Type Parameters:
        T1 - The type for the first Single.
        T2 - The type for the second Single.
        T3 - The type for the third Single.
        T4 - The type for the fourth Single.
        R - The result type of the zipper.
        Parameters:
        s1 - The first Single to zip.
        s2 - The second Single to zip.
        s3 - The third Single to zip.
        s4 - The fourth Single to zip.
        zipper - Used to combine the completed results for each item from singles.
        Returns:
        a new Single that emits the results of a specified zipper Function4 to items emitted by s1, s2, s3, and s4.
        See Also:
        ReactiveX zip operator.

      • zip

        public static <R> Single<R> zip​(java.util.function.Function<? super java.lang.Object[],​? extends R> zipper,
                                Single<?>... singles)
        Create a new Single that emits the results of a specified zipper Function to items emitted by singles.

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

        
      Function<? super CompletableFuture<?>[], ? extends R> zipper = ...;
      CompletableFuture<?>[] futures = ...; // Provided Futures (analogous to the Singles here)
      CompletableFuture.allOf(futures).get(); // wait for all futures to complete
      return zipper.apply(futures);
        Type Parameters:
        R - The result type of the zipper.
        Parameters:
        zipper - Used to combine the completed results for each item from singles.
        singles - The collection of Singles that when complete provides the results to "zip" (aka combine) together.
        Returns:
        a new Single that emits the results of a specified zipper Function to items emitted by singles.
        See Also:
        ReactiveX zip operator.

      • zipDelayError

        public static <R> Single<R> zipDelayError​(java.util.function.Function<? super java.lang.Object[],​? extends R> zipper,
                                          Single<?>... singles)
        Create a new Single that emits the results of a specified zipper Function to items emitted by singles. If any of the Singles terminate with an error, the returned Single will wait for termination till all the other Singles have been subscribed and terminated, and then terminate with the first error.

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

        
      Function<? super CompletableFuture<?>[], ? extends R> zipper = ...;
      CompletableFuture<?>[] futures = ...; // Provided Futures (analogous to the Singles here)
      CompletableFuture.allOf(futures).get(); // wait for all futures to complete
      return zipper.apply(futures);
        Type Parameters:
        R - The result type of the zipper.
        Parameters:
        zipper - Used to combine the completed results for each item from singles.
        singles - The collection of Singles that when complete provides the results to "zip" (aka combine) together.
        Returns:
        a new Single that emits the results of a specified zipper Function to items emitted by singles.
        See Also:
        ReactiveX zip operator.