Class Single<T>
- java.lang.Object
-
- io.servicetalk.concurrent.api.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 aSingleSource.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 asource adapter
can be used to convert to aSingleSource
.
-
-
Constructor Summary
Constructors Modifier Constructor Description protected
Single()
New instance.
-
Method Summary
All Methods Static Methods Instance Methods Abstract Methods Concrete Methods Modifier and Type Method Description Single<T>
afterCancel(java.lang.Runnable onCancel)
Invokes theonCancel
Runnable
argument afterCancellable.cancel()
is called for Subscriptions of the returnedSingle
.Single<T>
afterFinally(SingleTerminalSignalConsumer<? super T> doFinally)
Invokes the corresponding method onafterFinally
SingleTerminalSignalConsumer
argument after any of the following terminal methods are called:SingleSource.Subscriber.onSuccess(Object)
- invokesSingleTerminalSignalConsumer.onSuccess(Object)
SingleSource.Subscriber.onError(Throwable)
- invokesSingleTerminalSignalConsumer.onError(Throwable)
Cancellable.cancel()
- invokesSingleTerminalSignalConsumer.cancel()
for Subscriptions/SingleSource.Subscriber
s of the returnedSingle
.Single<T>
afterFinally(TerminalSignalConsumer doFinally)
Invokes the corresponding method onafterFinally
TerminalSignalConsumer
argument after any of the following terminal methods are called:SingleSource.Subscriber.onSuccess(Object)
- invokesTerminalSignalConsumer.onComplete()
SingleSource.Subscriber.onError(Throwable)
- invokesTerminalSignalConsumer.onError(Throwable)
Cancellable.cancel()
- invokesTerminalSignalConsumer.cancel()
for Subscriptions/SingleSource.Subscriber
s of the returnedSingle
.Single<T>
afterFinally(java.lang.Runnable doFinally)
Invokes thewhenFinally
Runnable
argument after any of the following terminal methods are called:SingleSource.Subscriber.onSuccess(Object)
SingleSource.Subscriber.onError(Throwable)
Cancellable.cancel()
for Subscriptions/SingleSource.Subscriber
s of the returnedSingle
.Single<T>
afterOnError(java.util.function.Consumer<java.lang.Throwable> onError)
Invokes theonError
Consumer
argument afterSingleSource.Subscriber.onError(Throwable)
is called forSingleSource.Subscriber
s of the returnedSingle
.Single<T>
afterOnSubscribe(java.util.function.Consumer<Cancellable> onSubscribe)
Invokes theonSubscribe
Consumer
argument afterSingleSource.Subscriber.onSubscribe(Cancellable)
is called forSingleSource.Subscriber
s of the returnedSingle
.Single<T>
afterOnSuccess(java.util.function.Consumer<? super T> onSuccess)
Invokes theonSuccess
Consumer
argument afterSingleSource.Subscriber.onSuccess(Object)
is called forSingleSource.Subscriber
s of the returnedSingle
.Single<T>
afterSubscriber(java.util.function.Supplier<? extends SingleSource.Subscriber<? super T>> subscriberSupplier)
Creates a newSingleSource.Subscriber
(via thesubscriberSupplier
argument) on each call to subscribe and invokes all theSingleSource.Subscriber
methods after theSingleSource.Subscriber
s of the returnedSingle
.static <T> Single<T>
amb(Single<? extends T>... singles)
Creates a newSingle
that terminates with the result (either success or error) of whichever amongst the passedsingles
that terminates first.static <T> Single<T>
amb(java.lang.Iterable<Single<? extends T>> singles)
Creates a newSingle
that terminates with the result (either success or error) of whichever amongst the passedsingles
that terminates first.Single<T>
ambWith(Single<T> other)
static <T> Single<T>
anyOf(Single<? extends T>... singles)
Creates a newSingle
that terminates with the result (either success or error) of whichever amongst the passedsingles
that terminates first.static <T> Single<T>
anyOf(java.lang.Iterable<Single<? extends T>> singles)
Creates a newSingle
that terminates with the result (either success or error) of whichever amongst the passedsingles
that terminates first.Single<T>
beforeCancel(java.lang.Runnable onCancel)
Invokes theonCancel
Runnable
argument beforeCancellable.cancel()
is called for Subscriptions of the returnedSingle
.Single<T>
beforeFinally(SingleTerminalSignalConsumer<? super T> doFinally)
Invokes the corresponding method onbeforeFinally
SingleTerminalSignalConsumer
argument before any of the following terminal methods are called:SingleSource.Subscriber.onSuccess(Object)
- invokesSingleTerminalSignalConsumer.onSuccess(Object)
SingleSource.Subscriber.onError(Throwable)
- invokesSingleTerminalSignalConsumer.onError(Throwable)
Cancellable.cancel()
- invokesSingleTerminalSignalConsumer.cancel()
for Subscriptions/SingleSource.Subscriber
s of the returnedSingle
.Single<T>
beforeFinally(TerminalSignalConsumer doFinally)
Invokes the corresponding method onbeforeFinally
TerminalSignalConsumer
argument before any of the following terminal methods are called:SingleSource.Subscriber.onSuccess(Object)
- invokesTerminalSignalConsumer.onComplete()
SingleSource.Subscriber.onError(Throwable)
- invokesTerminalSignalConsumer.onError(Throwable)
Cancellable.cancel()
- invokesTerminalSignalConsumer.cancel()
for Subscriptions/SingleSource.Subscriber
s of the returnedSingle
.Single<T>
beforeFinally(java.lang.Runnable doFinally)
Invokes thewhenFinally
Runnable
argument before any of the following terminal methods are called:SingleSource.Subscriber.onSuccess(Object)
SingleSource.Subscriber.onError(Throwable)
Cancellable.cancel()
for Subscriptions/SingleSource.Subscriber
s of the returnedSingle
.Single<T>
beforeOnError(java.util.function.Consumer<java.lang.Throwable> onError)
Invokes theonError
Consumer
argument beforeSingleSource.Subscriber.onError(Throwable)
is called forSingleSource.Subscriber
s of the returnedSingle
.Single<T>
beforeOnSubscribe(java.util.function.Consumer<Cancellable> onSubscribe)
Invokes theonSubscribe
Consumer
argument beforeSingleSource.Subscriber.onSubscribe(Cancellable)
is called forSingleSource.Subscriber
s of the returnedSingle
.Single<T>
beforeOnSuccess(java.util.function.Consumer<? super T> onSuccess)
Invokes theonSuccess
Consumer
argument beforeSingleSource.Subscriber.onSuccess(Object)
is called forSingleSource.Subscriber
s of the returnedSingle
.Single<T>
beforeSubscriber(java.util.function.Supplier<? extends SingleSource.Subscriber<? super T>> subscriberSupplier)
Creates a newSingleSource.Subscriber
(via thesubscriberSupplier
argument) on each call to subscribe and invokes all theSingleSource.Subscriber
methods before theSingleSource.Subscriber
s of the returnedSingle
.static <T> Single<java.util.Collection<T>>
collectUnordered(int maxConcurrency, Single<? extends T>... singles)
Asynchronously collects results of the passedSingle
s into a singleCollection
.static <T> Single<java.util.Collection<T>>
collectUnordered(Single<? extends T>... singles)
Asynchronously collects results of the passedSingle
s into a singleCollection
.static <T> Single<java.util.Collection<T>>
collectUnordered(java.lang.Iterable<? extends Single<? extends T>> singles)
Asynchronously collects results of individualSingle
s returned by the passedIterable
into a singleCollection
.static <T> Single<java.util.Collection<T>>
collectUnordered(java.lang.Iterable<? extends Single<? extends T>> singles, int maxConcurrency)
Asynchronously collects results of individualSingle
s returned by the passedIterable
into a singleCollection
.static <T> Single<java.util.Collection<T>>
collectUnorderedDelayError(int maxConcurrency, Single<? extends T>... singles)
Asynchronously collects results of the passedSingle
s into a singleCollection
.static <T> Single<java.util.Collection<T>>
collectUnorderedDelayError(Single<? extends T>... singles)
Asynchronously collects results of the passedSingle
s into a singleCollection
.static <T> Single<java.util.Collection<T>>
collectUnorderedDelayError(java.lang.Iterable<? extends Single<? extends T>> singles)
Asynchronously collects results of individualSingle
s returned by the passedIterable
into a singleCollection
.static <T> Single<java.util.Collection<T>>
collectUnorderedDelayError(java.lang.Iterable<? extends Single<? extends T>> singles, int maxConcurrency)
Asynchronously collects results of individualSingle
s returned by the passedIterable
into a singleCollection
.Single<T>
concat(Completable next)
Returns aSingle
that emits the result of thisSingle
afternext
Completable
terminates successfully.Publisher<T>
concat(Publisher<? extends T> next)
Publisher<T>
concat(Single<? extends T> next)
static <T> Single<T>
defer(java.util.function.Supplier<? extends Single<? extends T>> singleSupplier)
Defer creation of aSingle
till it is subscribed to.static <T> Single<T>
failed(java.lang.Throwable cause)
Creates a realizedSingle
which always completes with the provided errorcause
.<R> Single<R>
flatMap(java.util.function.Function<? super T,? extends Single<? extends R>> next)
Completable
flatMapCompletable(java.util.function.Function<? super T,? extends Completable> next)
<R> Publisher<R>
flatMapPublisher(java.util.function.Function<? super T,? extends Publisher<? extends R>> next)
static <T> Single<T>
fromCallable(java.util.concurrent.Callable<T> callable)
static <T> Single<T>
fromFuture(java.util.concurrent.Future<? extends T> future)
static <T> Single<T>
fromStage(java.util.concurrent.CompletionStage<? extends T> stage)
Convert from aCompletionStage
to aSingle
.static <T> Single<T>
fromSupplier(java.util.function.Supplier<T> supplier)
protected abstract void
handleSubscribe(SingleSource.Subscriber<? super T> subscriber)
Handles a subscriber to thisSingle
.Single<T>
idleTimeout(long duration, java.util.concurrent.TimeUnit unit)
Single<T>
idleTimeout(long duration, java.util.concurrent.TimeUnit unit, Executor timeoutExecutor)
Single<T>
idleTimeout(java.time.Duration duration)
Single<T>
idleTimeout(java.time.Duration duration, Executor timeoutExecutor)
Completable
ignoreElement()
Ignores the result of thisSingle
and forwards the termination signal to the returnedCompletable
.<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(java.util.function.Function<? super T,? extends R> mapper)
Maps the result of this single to a different type.static <T> Single<T>
never()
Creates aSingle
that never terminates.Single<T>
publishAndSubscribeOn(Executor executor)
Creates a newSingle
that will use the passedExecutor
to invoke the following methods: AllSingleSource.Subscriber
methods. AllCancellable
methods. ThehandleSubscribe(SingleSource.Subscriber)
method. This method does not override precedingExecutor
s, if any, specified forthis
Single
.Single<T>
publishAndSubscribeOnOverride(Executor executor)
Creates a newSingle
that will use the passedExecutor
to invoke the following methods: AllSingleSource.Subscriber
methods. AllCancellable
methods. ThehandleSubscribe(SingleSource.Subscriber)
method. This method overrides precedingExecutor
s, if any, specified forthis
Single
.Single<T>
publishOn(Executor executor)
Creates a newSingle
that will use the passedExecutor
to invoke allSingleSource.Subscriber
methods.Single<T>
publishOnOverride(Executor executor)
Creates a newSingle
that will use the passedExecutor
to invoke allSingleSource.Subscriber
methods.Single<T>
recoverWith(java.util.function.Function<java.lang.Throwable,? extends Single<? extends T>> nextFactory)
Publisher<T>
repeat(java.util.function.IntPredicate shouldRepeat)
Publisher<T>
repeatWhen(java.util.function.IntFunction<? extends Completable> repeatWhen)
Re-subscribes to thisSingle
when it completes and theCompletable
returned by the suppliedIntFunction
completes successfully.Single<T>
retry(BiIntPredicate<java.lang.Throwable> shouldRetry)
Single<T>
retryWhen(BiIntFunction<java.lang.Throwable,? extends Completable> retryWhen)
Re-subscribes to thisSingle
if an error is emitted and theCompletable
returned by the suppliedBiIntFunction
completes successfully.Cancellable
subscribe(java.util.function.Consumer<? super T> resultConsumer)
Subscribe to thisSingle
, emits the result to the passedConsumer
and log anySingleSource.Subscriber.onError(Throwable)
.protected void
subscribeInternal(SingleSource.Subscriber<? super T> subscriber)
A internal subscribe method similar toSingleSource.subscribe(Subscriber)
which can be used by different implementations to subscribe.Single<T>
subscribeOn(Executor executor)
Creates a newSingle
that will use the passedExecutor
to invoke the following methods: AllCancellable
methods. ThehandleSubscribe(SingleSource.Subscriber)
method. This method does not override precedingExecutor
s, if any, specified forthis
Single
.Single<T>
subscribeOnOverride(Executor executor)
Creates a newSingle
that will use the passedExecutor
to invoke the following methods: AllCancellable
methods. ThehandleSubscribe(SingleSource.Subscriber)
method. This method overrides precedingExecutor
s, if any, specified forthis
Single
.Single<T>
subscribeShareContext()
Signifies that when the returnedSingle
is subscribed to, theAsyncContext
will be shared instead of making acopy
.static <T> Single<T>
succeeded(T value)
Creates a realizedSingle
which always completes successfully with the providedvalue
.Completable
toCompletable()
Ignores the result of thisSingle
and forwards the termination signal to the returnedCompletable
.java.util.concurrent.CompletionStage<T>
toCompletionStage()
Convert thisSingle
to aCompletionStage
.java.util.concurrent.Future<T>
toFuture()
Convert thisSingle
to aFuture
.Publisher<T>
toPublisher()
Converts thisSingle
to aPublisher
.Single<T>
whenCancel(java.lang.Runnable onCancel)
Invokes theonCancel
Runnable
argument whenCancellable.cancel()
is called for Subscriptions of the returnedSingle
.Single<T>
whenFinally(SingleTerminalSignalConsumer<? super T> doFinally)
Invokes the corresponding method onwhenFinally
SingleTerminalSignalConsumer
argument when any of the following terminal methods are called:SingleSource.Subscriber.onSuccess(Object)
- invokesSingleTerminalSignalConsumer.onSuccess(Object)
SingleSource.Subscriber.onError(Throwable)
- invokesSingleTerminalSignalConsumer.onError(Throwable)
Cancellable.cancel()
- invokesSingleTerminalSignalConsumer.cancel()
for Subscriptions/SingleSource.Subscriber
s of the returnedSingle
.Single<T>
whenFinally(TerminalSignalConsumer doFinally)
Invokes the corresponding method onwhenFinally
TerminalSignalConsumer
argument when any of the following terminal methods are called:SingleSource.Subscriber.onSuccess(Object)
- invokesTerminalSignalConsumer.onComplete()
SingleSource.Subscriber.onError(Throwable)
- invokesTerminalSignalConsumer.onError(Throwable)
Cancellable.cancel()
- invokesTerminalSignalConsumer.cancel()
for Subscriptions/SingleSource.Subscriber
s of the returnedSingle
.Single<T>
whenFinally(java.lang.Runnable doFinally)
Invokes thewhenFinally
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.Subscriber
s of the returnedSingle
.Single<T>
whenOnError(java.util.function.Consumer<java.lang.Throwable> onError)
Invokes theonError
Consumer
argument whenSingleSource.Subscriber.onError(Throwable)
is called forSingleSource.Subscriber
s of the returnedSingle
.Single<T>
whenOnSubscribe(java.util.function.Consumer<Cancellable> onSubscribe)
Invokes theonSubscribe
Consumer
argument whenSingleSource.Subscriber.onSubscribe(Cancellable)
is called forSingleSource.Subscriber
s of the returnedSingle
.Single<T>
whenOnSuccess(java.util.function.Consumer<? super T> onSuccess)
Invokes theonSuccess
Consumer
argument whenSingleSource.Subscriber.onSuccess(Object)
is called forSingleSource.Subscriber
s of the returnedSingle
.Single<T>
whenSubscriber(java.util.function.Supplier<? extends SingleSource.Subscriber<? super T>> subscriberSupplier)
Creates a newSingleSource.Subscriber
(via thesubscriberSupplier
argument) for each new subscribe and invokes methods on thatSingleSource.Subscriber
when the corresponding methods are called forSingleSource.Subscriber
s of the returnedSingle
.
-
-
-
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 returnedSingle
.This method provides a data transformation in sequential programming similar to:
T tResult = resultOfThisSingle(); R rResult = mapper.apply(tResult);
-
recoverWith
public final Single<T> recoverWith(java.util.function.Function<java.lang.Throwable,? extends Single<? extends T>> nextFactory)
Recover from any error emitted by thisSingle
by using anotherSingle
provided by the passednextFactory
.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;
-
flatMap
public final <R> Single<R> flatMap(java.util.function.Function<? super T,? extends Single<? extends R>> next)
Returns aSingle
that mirrors emissions from theSingle
returned bynext
. Any error emitted by thisSingle
is forwarded to the returnedSingle
.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.
-
flatMapCompletable
public final Completable flatMapCompletable(java.util.function.Function<? super T,? extends Completable> next)
Returns aCompletable
that mirrors emissions from theCompletable
returned bynext
. Any error emitted by thisSingle
is forwarded to the returnedCompletable
.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 nextCompletable
.- Returns:
- New
Completable
that switches to theCompletable
returned bynext
after thisSingle
completes successfully.
-
flatMapPublisher
public final <R> Publisher<R> flatMapPublisher(java.util.function.Function<? super T,? extends Publisher<? extends R>> next)
Returns aPublisher
that mirrors emissions from thePublisher
returned bynext
. Any error emitted by thisSingle
is forwarded to the returnedPublisher
.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 }
-
whenOnSuccess
public final Single<T> whenOnSuccess(java.util.function.Consumer<? super T> onSuccess)
Invokes theonSuccess
Consumer
argument whenSingleSource.Subscriber.onSuccess(Object)
is called forSingleSource.Subscriber
s of the returnedSingle
.The order in which
onSuccess
will be invoked relative toSingleSource.Subscriber.onSuccess(Object)
is undefined. If you need strict ordering seebeforeOnSuccess(Consumer)
andafterOnSuccess(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 whenSingleSource.Subscriber.onSuccess(Object)
is called forSingleSource.Subscriber
s of the returnedSingle
. MUST NOT throw.- Returns:
- The new
Single
. - See Also:
beforeOnSuccess(Consumer)
,afterOnSuccess(Consumer)
-
whenOnError
public final Single<T> whenOnError(java.util.function.Consumer<java.lang.Throwable> onError)
Invokes theonError
Consumer
argument whenSingleSource.Subscriber.onError(Throwable)
is called forSingleSource.Subscriber
s of the returnedSingle
.The order in which
onError
will be invoked relative toSingleSource.Subscriber.onError(Throwable)
is undefined. If you need strict ordering seebeforeOnError(Consumer)
andafterOnError(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 whenSingleSource.Subscriber.onError(Throwable)
is called forSingleSource.Subscriber
s of the returnedSingle
. MUST NOT throw.- Returns:
- The new
Single
. - See Also:
beforeOnError(Consumer)
,afterOnError(Consumer)
-
whenFinally
public final Single<T> whenFinally(java.lang.Runnable doFinally)
Invokes thewhenFinally
Runnable
argument exactly once, when any of the following terminal methods are called:SingleSource.Subscriber.onSuccess(Object)
SingleSource.Subscriber.onError(Throwable)
Cancellable.cancel()
SingleSource.Subscriber
s of the returnedSingle
.The order in which
whenFinally
will be invoked relative to the above methods is undefined. If you need strict ordering seebeforeFinally(Runnable)
andafterFinally(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 doFinally.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()
SingleSource.Subscriber
s of the returnedSingle
. MUST NOT throw.- Returns:
- The new
Single
. - See Also:
beforeFinally(Runnable)
,afterFinally(Runnable)
-
whenFinally
public final Single<T> whenFinally(TerminalSignalConsumer doFinally)
Invokes the corresponding method onwhenFinally
TerminalSignalConsumer
argument when any of the following terminal methods are called:SingleSource.Subscriber.onSuccess(Object)
- invokesTerminalSignalConsumer.onComplete()
SingleSource.Subscriber.onError(Throwable)
- invokesTerminalSignalConsumer.onError(Throwable)
Cancellable.cancel()
- invokesTerminalSignalConsumer.cancel()
SingleSource.Subscriber
s of the returnedSingle
.The order in which
whenFinally
will be invoked relative to the above methods is undefined. If you need strict ordering seebeforeFinally(TerminalSignalConsumer)
andafterFinally(TerminalSignalConsumer)
.From a sequential programming point of view this method is roughly equivalent to the following:
T result; try { result = resultOfThisSingle(); } catch(Throwable t) { // NOTE: The order of operations here is not guaranteed by this method! nextOperation(); // Maybe notifying of cancellation, or termination doFinally.onError(t); return; } // NOTE: The order of operations here is not guaranteed by this method! nextOperation(); // Maybe notifying of cancellation, or termination doFinally.onComplete();
- Parameters:
doFinally
- For each subscribe of the returnedSingle
, at most one method of thisTerminalSignalConsumer
will be invoked.- Returns:
- The new
Single
. - See Also:
beforeFinally(TerminalSignalConsumer)
,afterFinally(TerminalSignalConsumer)
-
whenFinally
public final Single<T> whenFinally(SingleTerminalSignalConsumer<? super T> doFinally)
Invokes the corresponding method onwhenFinally
SingleTerminalSignalConsumer
argument when any of the following terminal methods are called:SingleSource.Subscriber.onSuccess(Object)
- invokesSingleTerminalSignalConsumer.onSuccess(Object)
SingleSource.Subscriber.onError(Throwable)
- invokesSingleTerminalSignalConsumer.onError(Throwable)
Cancellable.cancel()
- invokesSingleTerminalSignalConsumer.cancel()
SingleSource.Subscriber
s of the returnedSingle
.The order in which
whenFinally
will be invoked relative to the above methods is undefined. If you need strict ordering seebeforeFinally(SingleTerminalSignalConsumer)
andafterFinally(SingleTerminalSignalConsumer)
.From a sequential programming point of view this method is roughly equivalent to the following:
T result; try { result = resultOfThisSingle(); } catch(Throwable t) { // NOTE: The order of operations here is not guaranteed by this method! nextOperation(); // Maybe notifying of cancellation, or termination doFinally.onError(t); return; } // NOTE: The order of operations here is not guaranteed by this method! nextOperation(); // Maybe notifying of cancellation, or termination doFinally.onSuccess(result);
- Parameters:
doFinally
- For each subscribe of the returnedSingle
, at most one method of thisSingleTerminalSignalConsumer
will be invoked.- Returns:
- The new
Single
. - See Also:
beforeFinally(SingleTerminalSignalConsumer)
,afterFinally(SingleTerminalSignalConsumer)
-
whenCancel
public final Single<T> whenCancel(java.lang.Runnable onCancel)
Invokes theonCancel
Runnable
argument whenCancellable.cancel()
is called for Subscriptions of the returnedSingle
.The order in which
whenFinally
will be invoked relative toCancellable.cancel()
is undefined. If you need strict ordering seebeforeCancel(Runnable)
andafterCancel(Runnable)
.- Parameters:
onCancel
- Invoked whenCancellable.cancel()
is called for Subscriptions of the returnedSingle
. MUST NOT throw.- Returns:
- The new
Single
. - See Also:
beforeCancel(Runnable)
,afterCancel(Runnable)
-
idleTimeout
public final Single<T> idleTimeout(long duration, java.util.concurrent.TimeUnit unit)
Creates a newSingle
that will mimic the signals of thisSingle
but will terminate with a with aTimeoutException
if timeduration
elapses between subscribe and termination. The timer starts when the returnedSingle
is subscribed.In the event of timeout any
Cancellable
fromSingleSource.Subscriber.onSubscribe(Cancellable)
will becancelled
and the associatedSingleSource.Subscriber
will beterminated
.- Parameters:
duration
- The time duration which is allowed to elapse beforeSingleSource.Subscriber.onSuccess(Object)
.unit
- The units forduration
.- Returns:
- a new
Single
that will mimic the signals of thisSingle
but will terminate with aTimeoutException
if timeduration
elapses beforeSingleSource.Subscriber.onSuccess(Object)
. - See Also:
- ReactiveX timeout operator.
-
idleTimeout
public final Single<T> idleTimeout(long duration, java.util.concurrent.TimeUnit unit, Executor timeoutExecutor)
Creates a newSingle
that will mimic the signals of thisSingle
but will terminate with a with aTimeoutException
if timeduration
elapses between subscribe and termination. The timer starts when the returnedSingle
is subscribed.In the event of timeout any
Cancellable
fromSingleSource.Subscriber.onSubscribe(Cancellable)
will becancelled
and the associatedSingleSource.Subscriber
will beterminated
.- Parameters:
duration
- The time duration which is allowed to elapse beforeSingleSource.Subscriber.onSuccess(Object)
.unit
- The units forduration
.timeoutExecutor
- TheExecutor
to use for managing the timer notifications.- Returns:
- a new
Single
that will mimic the signals of thisSingle
but will terminate with aTimeoutException
if timeduration
elapses beforeSingleSource.Subscriber.onSuccess(Object)
. - See Also:
- ReactiveX timeout operator.
-
idleTimeout
public final Single<T> idleTimeout(java.time.Duration duration)
Creates a newSingle
that will mimic the signals of thisSingle
but will terminate with a with aTimeoutException
if timeduration
elapses between subscribe and termination. The timer starts when the returnedSingle
is subscribed.In the event of timeout any
Cancellable
fromSingleSource.Subscriber.onSubscribe(Cancellable)
will becancelled
and the associatedSingleSource.Subscriber
will beterminated
.SingleSource.Subscriber
will viaterminated
.- Parameters:
duration
- The time duration which is allowed to elapse beforeSingleSource.Subscriber.onSuccess(Object)
.- Returns:
- a new
Single
that will mimic the signals of thisSingle
but will terminate with aTimeoutException
if timeduration
elapses beforeSingleSource.Subscriber.onSuccess(Object)
. - See Also:
- ReactiveX timeout operator.
-
idleTimeout
public final Single<T> idleTimeout(java.time.Duration duration, Executor timeoutExecutor)
Creates a newSingle
that will mimic the signals of thisSingle
but will terminate with a with aTimeoutException
if timeduration
elapses between subscribe and termination. The timer starts when the returnedSingle
is subscribed.In the event of timeout any
Cancellable
fromSingleSource.Subscriber.onSubscribe(Cancellable)
will becancelled
and the associatedSingleSource.Subscriber
will beterminated
.- Parameters:
duration
- The time duration which is allowed to elapse beforeSingleSource.Subscriber.onSuccess(Object)
.timeoutExecutor
- TheExecutor
to use for managing the timer notifications.- Returns:
- a new
Single
that will mimic the signals of thisSingle
but will terminate with aTimeoutException
if timeduration
elapses beforeSingleSource.Subscriber.onSuccess(Object)
. - See Also:
- ReactiveX timeout operator.
-
concat
public final Publisher<T> concat(Single<? extends T> next)
Returns aPublisher
that first emits the result of thisSingle
and then subscribes and emits result ofnext
Single
. Any error emitted by thisSingle
ornext
Single
is forwarded to the returnedPublisher
.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;
-
concat
public final Single<T> concat(Completable next)
Returns aSingle
that emits the result of thisSingle
afternext
Completable
terminates successfully.next
Completable
will only be subscribed to after thisSingle
terminates successfully. Any error emitted by thisSingle
ornext
Completable
is forwarded to the returnedSingle
.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 thisSingle
afternext
Completable
terminates successfully.
-
concat
public final Publisher<T> concat(Publisher<? extends T> next)
Returns aPublisher
that first emits the result of thisSingle
and then subscribes and emits all elements fromnext
Publisher
. Any error emitted by thisSingle
ornext
Publisher
is forwarded to the returnedPublisher
.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;
-
retry
public final Single<T> retry(BiIntPredicate<java.lang.Throwable> shouldRetry)
Re-subscribes to thisSingle
if an error is emitted and the passedBiIntPredicate
returnstrue
.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 recentThrowable
emitted from thisSingle
determines if the operation should be retried.- Returns:
- A
Single
that emits the result from thisSingle
or re-subscribes if an error is emitted and if the passedBiIntPredicate
returnedtrue
. - See Also:
- ReactiveX retry operator.
-
retryWhen
public final Single<T> retryWhen(BiIntFunction<java.lang.Throwable,? extends Completable> retryWhen)
Re-subscribes to thisSingle
if an error is emitted and theCompletable
returned by the suppliedBiIntFunction
completes successfully. If the returnedCompletable
emits an error, the returnedSingle
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 recentThrowable
emitted from thisSingle
returns aCompletable
. If thisCompletable
emits an error, that error is emitted from the returnedSingle
, otherwise, originalSingle
is re-subscribed when thisCompletable
completes.- Returns:
- A
Single
that emits the result from thisSingle
or re-subscribes if an error is emitted andCompletable
returned byBiIntFunction
completes successfully. - See Also:
- ReactiveX retry operator.
-
repeat
public final Publisher<T> repeat(java.util.function.IntPredicate shouldRepeat)
Re-subscribes to thisSingle
when it completes and the passedIntPredicate
returnstrue
.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 thisSingle
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 thisSingle
when it completes and theCompletable
returned by the suppliedIntFunction
completes successfully. If the returnedCompletable
emits an error, the returnedSingle
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 aCompletable
. If thisCompletable
emits an error repeat is terminated, otherwise, originalSingle
is re-subscribed when thisCompletable
completes.- Returns:
- A
Publisher
that emits all items from thisSingle
and from all re-subscriptions whenever the operation is repeated. - See Also:
- ReactiveX retry operator.
-
beforeOnSubscribe
public final Single<T> beforeOnSubscribe(java.util.function.Consumer<Cancellable> onSubscribe)
Invokes theonSubscribe
Consumer
argument beforeSingleSource.Subscriber.onSubscribe(Cancellable)
is called forSingleSource.Subscriber
s of the returnedSingle
.- Parameters:
onSubscribe
- Invoked beforeSingleSource.Subscriber.onSubscribe(Cancellable)
is called forSingleSource.Subscriber
s of the returnedSingle
. MUST NOT throw.- Returns:
- The new
Single
.
-
beforeOnSuccess
public final Single<T> beforeOnSuccess(java.util.function.Consumer<? super T> onSuccess)
Invokes theonSuccess
Consumer
argument beforeSingleSource.Subscriber.onSuccess(Object)
is called forSingleSource.Subscriber
s of the returnedSingle
.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 beforeSingleSource.Subscriber.onSuccess(Object)
is called forSingleSource.Subscriber
s of the returnedSingle
. MUST NOT throw.- Returns:
- The new
Single
.
-
beforeOnError
public final Single<T> beforeOnError(java.util.function.Consumer<java.lang.Throwable> onError)
Invokes theonError
Consumer
argument beforeSingleSource.Subscriber.onError(Throwable)
is called forSingleSource.Subscriber
s of the returnedSingle
.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 beforeSingleSource.Subscriber.onError(Throwable)
is called forSingleSource.Subscriber
s of the returnedSingle
. MUST NOT throw.- Returns:
- The new
Single
.
-
beforeCancel
public final Single<T> beforeCancel(java.lang.Runnable onCancel)
Invokes theonCancel
Runnable
argument beforeCancellable.cancel()
is called for Subscriptions of the returnedSingle
.- Parameters:
onCancel
- Invoked beforeCancellable.cancel()
is called for Subscriptions of the returnedSingle
. MUST NOT throw.- Returns:
- The new
Single
.
-
beforeFinally
public final Single<T> beforeFinally(java.lang.Runnable doFinally)
Invokes thewhenFinally
Runnable
argument before any of the following terminal methods are called:SingleSource.Subscriber.onSuccess(Object)
SingleSource.Subscriber.onError(Throwable)
Cancellable.cancel()
SingleSource.Subscriber
s of the returnedSingle
.From a sequential programming point of view this method is roughly equivalent to the following:
try { T result = resultOfThisSingle(); } finally { doFinally.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()
SingleSource.Subscriber
s of the returnedSingle
. MUST NOT throw.- Returns:
- The new
Single
. - See Also:
- ReactiveX do operator.
-
beforeFinally
public final Single<T> beforeFinally(TerminalSignalConsumer doFinally)
Invokes the corresponding method onbeforeFinally
TerminalSignalConsumer
argument before any of the following terminal methods are called:SingleSource.Subscriber.onSuccess(Object)
- invokesTerminalSignalConsumer.onComplete()
SingleSource.Subscriber.onError(Throwable)
- invokesTerminalSignalConsumer.onError(Throwable)
Cancellable.cancel()
- invokesTerminalSignalConsumer.cancel()
SingleSource.Subscriber
s of the returnedSingle
.From a sequential programming point of view this method is roughly equivalent to the following:
T result; try { result = resultOfThisSingle(); } catch(Throwable t) { doFinally.onError(t); nextOperation(); // Maybe notifying of cancellation, or termination return; } doFinally.onComplete(); nextOperation(); // Maybe notifying of cancellation, or termination
- Parameters:
doFinally
- For each subscribe of the returnedSingle
, at most one method of thisTerminalSignalConsumer
will be invoked.- Returns:
- The new
Single
. - See Also:
- ReactiveX do operator.
-
beforeFinally
public final Single<T> beforeFinally(SingleTerminalSignalConsumer<? super T> doFinally)
Invokes the corresponding method onbeforeFinally
SingleTerminalSignalConsumer
argument before any of the following terminal methods are called:SingleSource.Subscriber.onSuccess(Object)
- invokesSingleTerminalSignalConsumer.onSuccess(Object)
SingleSource.Subscriber.onError(Throwable)
- invokesSingleTerminalSignalConsumer.onError(Throwable)
Cancellable.cancel()
- invokesSingleTerminalSignalConsumer.cancel()
SingleSource.Subscriber
s of the returnedSingle
.From a sequential programming point of view this method is roughly equivalent to the following:
T result; try { result = resultOfThisSingle(); } catch(Throwable t) { doFinally.onError(t); nextOperation(); // Maybe notifying of cancellation, or termination return; } doFinally.onSuccess(result); nextOperation(); // Maybe notifying of cancellation, or termination
- Parameters:
doFinally
- For each subscribe of the returnedSingle
, at most one method of thisSingleTerminalSignalConsumer
will be invoked.- Returns:
- The new
Single
. - See Also:
- ReactiveX do operator.
-
beforeSubscriber
public final Single<T> beforeSubscriber(java.util.function.Supplier<? extends SingleSource.Subscriber<? super T>> subscriberSupplier)
Creates a newSingleSource.Subscriber
(via thesubscriberSupplier
argument) on each call to subscribe and invokes all theSingleSource.Subscriber
methods before theSingleSource.Subscriber
s of the returnedSingle
.- Parameters:
subscriberSupplier
- Creates a newSingleSource.Subscriber
on each call to subscribe and invokes all theSingleSource.Subscriber
methods before theSingleSource.Subscriber
s of the returnedSingle
.SingleSource.Subscriber
methods MUST NOT throw.- Returns:
- The new
Single
.
-
afterOnSubscribe
public final Single<T> afterOnSubscribe(java.util.function.Consumer<Cancellable> onSubscribe)
Invokes theonSubscribe
Consumer
argument afterSingleSource.Subscriber.onSubscribe(Cancellable)
is called forSingleSource.Subscriber
s of the returnedSingle
.- Parameters:
onSubscribe
- Invoked afterSingleSource.Subscriber.onSubscribe(Cancellable)
is called forSingleSource.Subscriber
s of the returnedSingle
. MUST NOT throw.- Returns:
- The new
Single
.
-
whenOnSubscribe
public final Single<T> whenOnSubscribe(java.util.function.Consumer<Cancellable> onSubscribe)
Invokes theonSubscribe
Consumer
argument whenSingleSource.Subscriber.onSubscribe(Cancellable)
is called forSingleSource.Subscriber
s of the returnedSingle
.The order in which
onSubscribe
will be invoked relative toSingleSource.Subscriber.onSubscribe(Cancellable)
is undefined. If you need strict ordering seebeforeOnSubscribe(Consumer)
andafterOnSubscribe(Consumer)
.- Parameters:
onSubscribe
- Invoked whenSingleSource.Subscriber.onSubscribe(Cancellable)
is called forSingleSource.Subscriber
s of the returnedSingle
. MUST NOT throw.- Returns:
- The new
Single
. - See Also:
beforeOnSubscribe(Consumer)
,afterOnSubscribe(Consumer)
-
afterOnSuccess
public final Single<T> afterOnSuccess(java.util.function.Consumer<? super T> onSuccess)
Invokes theonSuccess
Consumer
argument afterSingleSource.Subscriber.onSuccess(Object)
is called forSingleSource.Subscriber
s of the returnedSingle
.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 afterSingleSource.Subscriber.onSuccess(Object)
is called forSingleSource.Subscriber
s of the returnedSingle
. MUST NOT throw.- Returns:
- The new
Single
.
-
afterOnError
public final Single<T> afterOnError(java.util.function.Consumer<java.lang.Throwable> onError)
Invokes theonError
Consumer
argument afterSingleSource.Subscriber.onError(Throwable)
is called forSingleSource.Subscriber
s of the returnedSingle
.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 afterSingleSource.Subscriber.onError(Throwable)
is called forSingleSource.Subscriber
s of the returnedSingle
. MUST NOT throw.- Returns:
- The new
Single
.
-
afterCancel
public final Single<T> afterCancel(java.lang.Runnable onCancel)
Invokes theonCancel
Runnable
argument afterCancellable.cancel()
is called for Subscriptions of the returnedSingle
.- Parameters:
onCancel
- Invoked afterCancellable.cancel()
is called for Subscriptions of the returnedSingle
. MUST NOT throw.- Returns:
- The new
Single
.
-
afterFinally
public final Single<T> afterFinally(java.lang.Runnable doFinally)
Invokes thewhenFinally
Runnable
argument after any of the following terminal methods are called:SingleSource.Subscriber.onSuccess(Object)
SingleSource.Subscriber.onError(Throwable)
Cancellable.cancel()
SingleSource.Subscriber
s of the returnedSingle
.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 doFinally.run(); }
- Parameters:
doFinally
- Invoked after any of the following terminal methods are called:SingleSource.Subscriber.onSuccess(Object)
SingleSource.Subscriber.onError(Throwable)
Cancellable.cancel()
SingleSource.Subscriber
s of the returnedSingle
. MUST NOT throw.- Returns:
- The new
Single
. - See Also:
- ReactiveX do operator.
-
afterFinally
public final Single<T> afterFinally(TerminalSignalConsumer doFinally)
Invokes the corresponding method onafterFinally
TerminalSignalConsumer
argument after any of the following terminal methods are called:SingleSource.Subscriber.onSuccess(Object)
- invokesTerminalSignalConsumer.onComplete()
SingleSource.Subscriber.onError(Throwable)
- invokesTerminalSignalConsumer.onError(Throwable)
Cancellable.cancel()
- invokesTerminalSignalConsumer.cancel()
SingleSource.Subscriber
s of the returnedSingle
.From a sequential programming point of view this method is roughly equivalent to the following:
T result; try { result = resultOfThisSingle(); } catch(Throwable t) { nextOperation(); // Maybe notifying of cancellation, or termination doFinally.onError(t); return; } nextOperation(); // Maybe notifying of cancellation, or termination doFinally.onComplete();
- Parameters:
doFinally
- For each subscribe of the returnedSingle
, at most one method of thisTerminalSignalConsumer
will be invoked.- Returns:
- The new
Single
. - See Also:
- ReactiveX do operator.
-
afterFinally
public final Single<T> afterFinally(SingleTerminalSignalConsumer<? super T> doFinally)
Invokes the corresponding method onafterFinally
SingleTerminalSignalConsumer
argument after any of the following terminal methods are called:SingleSource.Subscriber.onSuccess(Object)
- invokesSingleTerminalSignalConsumer.onSuccess(Object)
SingleSource.Subscriber.onError(Throwable)
- invokesSingleTerminalSignalConsumer.onError(Throwable)
Cancellable.cancel()
- invokesSingleTerminalSignalConsumer.cancel()
SingleSource.Subscriber
s of the returnedSingle
.From a sequential programming point of view this method is roughly equivalent to the following:
T result; try { result = resultOfThisSingle(); } catch(Throwable t) { nextOperation(); // Maybe notifying of cancellation, or termination doFinally.onError(t); return; } nextOperation(); // Maybe notifying of cancellation, or termination doFinally.onSuccess(result);
- Parameters:
doFinally
- For each subscribe of the returnedSingle
, at most one method of thisSingleTerminalSignalConsumer
will be invoked.- Returns:
- The new
Single
. - See Also:
- ReactiveX do operator.
-
afterSubscriber
public final Single<T> afterSubscriber(java.util.function.Supplier<? extends SingleSource.Subscriber<? super T>> subscriberSupplier)
Creates a newSingleSource.Subscriber
(via thesubscriberSupplier
argument) on each call to subscribe and invokes all theSingleSource.Subscriber
methods after theSingleSource.Subscriber
s of the returnedSingle
.- Parameters:
subscriberSupplier
- Creates a newSingleSource.Subscriber
on each call to subscribe and invokes all theSingleSource.Subscriber
methods after theSingleSource.Subscriber
s of the returnedSingle
.SingleSource.Subscriber
methods MUST NOT throw.- Returns:
- The new
Single
.
-
whenSubscriber
public final Single<T> whenSubscriber(java.util.function.Supplier<? extends SingleSource.Subscriber<? super T>> subscriberSupplier)
Creates a newSingleSource.Subscriber
(via thesubscriberSupplier
argument) for each new subscribe and invokes methods on thatSingleSource.Subscriber
when the corresponding methods are called forSingleSource.Subscriber
s of the returnedSingle
.- Parameters:
subscriberSupplier
- Creates a newSingleSource.Subscriber
for each new subscribe and invokes methods on thatSingleSource.Subscriber
when the corresponding methods are called forSingleSource.Subscriber
s of the returnedSingle
.SingleSource.Subscriber
methods MUST NOT throw.- Returns:
- The new
Single
.
-
publishOn
public final Single<T> publishOn(Executor executor)
Creates a newSingle
that will use the passedExecutor
to invoke allSingleSource.Subscriber
methods. This method does not override precedingExecutor
s, if any, specified forthis
Single
. Only subsequent operations, if any, added in this execution chain will use thisExecutor
. If such an override is required,publishOnOverride(Executor)
can be used.- Parameters:
executor
-Executor
to use.- Returns:
- A new
Single
that will use the passedExecutor
to invoke all methods on theSingleSource.Subscriber
.
-
publishOnOverride
public final Single<T> publishOnOverride(Executor executor)
Creates a newSingle
that will use the passedExecutor
to invoke allSingleSource.Subscriber
methods. This method overrides precedingExecutor
s, if any, specified forthis
Single
. That is to say preceding and subsequent operations for this execution chain will use thisExecutor
for invoking allSingleSource.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 passedExecutor
to invoke all methods ofSingleSource.Subscriber
,Cancellable
andhandleSubscribe(SingleSource.Subscriber)
both for the returnedSingle
as well asthis
Single
.
-
subscribeOn
public final Single<T> subscribeOn(Executor executor)
Creates a newSingle
that will use the passedExecutor
to invoke the following methods:- All
Cancellable
methods. - The
handleSubscribe(SingleSource.Subscriber)
method.
Executor
s, if any, specified forthis
Single
. Only subsequent operations, if any, added in this execution chain will use thisExecutor
. If such an override is required,subscribeOnOverride(Executor)
can be used.- Parameters:
executor
-Executor
to use.- Returns:
- A new
Single
that will use the passedExecutor
to invoke all methods ofCancellable
andhandleSubscribe(SingleSource.Subscriber)
.
- All
-
subscribeOnOverride
public final Single<T> subscribeOnOverride(Executor executor)
Creates a newSingle
that will use the passedExecutor
to invoke the following methods:- All
Cancellable
methods. - The
handleSubscribe(SingleSource.Subscriber)
method.
Executor
s, if any, specified forthis
Single
. That is to say preceding and subsequent operations for this execution chain will use thisExecutor
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 passedExecutor
to invoke all methods ofCancellable
andhandleSubscribe(SingleSource.Subscriber)
both for the returnedSingle
as well asthis
Single
.
- All
-
publishAndSubscribeOn
public final Single<T> publishAndSubscribeOn(Executor executor)
Creates a newSingle
that will use the passedExecutor
to invoke the following methods:- All
SingleSource.Subscriber
methods. - All
Cancellable
methods. - The
handleSubscribe(SingleSource.Subscriber)
method.
Executor
s, if any, specified forthis
Single
. Only subsequent operations, if any, added in this execution chain will use thisExecutor
. If such an override is required,publishAndSubscribeOnOverride(Executor)
can be used.- Parameters:
executor
-Executor
to use.- Returns:
- A new
Single
that will use the passedExecutor
to invoke all methodsSingleSource.Subscriber
,Cancellable
andhandleSubscribe(SingleSource.Subscriber)
.
- All
-
publishAndSubscribeOnOverride
public final Single<T> publishAndSubscribeOnOverride(Executor executor)
Creates a newSingle
that will use the passedExecutor
to invoke the following methods:- All
SingleSource.Subscriber
methods. - All
Cancellable
methods. - The
handleSubscribe(SingleSource.Subscriber)
method.
Executor
s, if any, specified forthis
Single
. That is to say preceding and subsequent operations for this execution chain will use thisExecutor
. 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 passedExecutor
to invoke all methods ofSingleSource.Subscriber
,Cancellable
andhandleSubscribe(SingleSource.Subscriber)
both for the returnedSingle
as well asthis
Single
.
- All
-
subscribeShareContext
public final Single<T> subscribeShareContext()
Signifies that when the returnedSingle
is subscribed to, theAsyncContext
will be shared instead of making acopy
.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 theAsyncContext
instead of making acopy
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 theSingleSource.Subscriber
using the providedoperator
argument before subscribing to thisSingle
.
TheSingle<X> pub = ...; pub.map(..) // A .liftSync(original -> modified) .afterFinally(..) // B
original -> modified
"operator" MUST be "synchronous" in that it does not interact with the originalSingleSource.Subscriber
from outside the modifiedSingleSource.Subscriber
orCancellable
threads. That is to say this operator will not impact theExecutor
constraints already in place between A and B above. If you need asynchronous behavior, or are unsure, seeliftAsync(SingleOperator)
.- Type Parameters:
R
- Type of the items emitted by the returnedSingle
.- Parameters:
operator
- The custom operator logic. The input is the "original"SingleSource.Subscriber
to thisSingle
and the return is the "modified"SingleSource.Subscriber
that provides custom operator business logic.- Returns:
- a
Single
which when subscribed, theoperator
argument will be used to wrap theSingleSource.Subscriber
before subscribing to thisSingle
. - 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 theSingleSource.Subscriber
using the providedoperator
argument before subscribing to thisSingle
.
ThePublisher<X> pub = ...; pub.map(..) // Aw .liftAsync(original -> modified) .afterFinally(..) // B
original -> modified
"operator" MAY be "asynchronous" in that it may interact with the originalSingleSource.Subscriber
from outside the modifiedSingleSource.Subscriber
orCancellable
threads. More specifically:- all of the
SingleSource.Subscriber
invocations going "downstream" (i.e. from A to B above) MAY be offloaded via anExecutor
- all of the
Cancellable
invocations going "upstream" (i.e. from B to A above) MAY be offloaded via anExecutor
- Type Parameters:
R
- Type of the items emitted by the returnedSingle
.- Parameters:
operator
- The custom operator logic. The input is the "original"SingleSource.Subscriber
to thisSingle
and the return is the "modified"SingleSource.Subscriber
that provides custom operator business logic.- Returns:
- a
Single
which when subscribed, theoperator
argument will be used to wrap theSingleSource.Subscriber
before subscribing to thisSingle
. - See Also:
liftSync(SingleOperator)
- all of the
-
ambWith
public final Single<T> ambWith(Single<T> other)
Creates a newSingle
that terminates with the result (either success or error) of either thisSingle
or the passedother
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(); }
-
toPublisher
public final Publisher<T> toPublisher()
Converts thisSingle
to aPublisher
.- Returns:
- A
Publisher
that emits at most a single item which is emitted by thisSingle
.
-
toCompletable
public final Completable toCompletable()
Ignores the result of thisSingle
and forwards the termination signal to the returnedCompletable
.- Returns:
- A
Completable
that mirrors the terminal signal from thisSingle
.
-
ignoreElement
public final Completable ignoreElement()
Ignores the result of thisSingle
and forwards the termination signal to the returnedCompletable
.- Returns:
- A
Completable
that mirrors the terminal signal from thisSingle
.
-
toCompletionStage
public final java.util.concurrent.CompletionStage<T> toCompletionStage()
Convert thisSingle
to aCompletionStage
.- Returns:
- A
CompletionStage
that mirrors the terminal signal from thisSingle
.
-
toFuture
public final java.util.concurrent.Future<T> toFuture()
Convert thisSingle
to aFuture
.- Returns:
- A
Future
that mirrors the terminal signal from thisSingle
.
-
subscribeInternal
protected final void subscribeInternal(SingleSource.Subscriber<? super T> subscriber)
A internal subscribe method similar toSingleSource.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(java.util.function.Consumer<? super T> resultConsumer)
Subscribe to thisSingle
, emits the result to the passedConsumer
and log anySingleSource.Subscriber.onError(Throwable)
.- Parameters:
resultConsumer
-Consumer
to accept the result of thisSingle
.- Returns:
Cancellable
used to invokeCancellable.cancel()
on the parameter ofSingleSource.Subscriber.onSubscribe(Cancellable)
for thisSingle
.
-
handleSubscribe
protected abstract void handleSubscribe(SingleSource.Subscriber<? super T> subscriber)
Handles a subscriber to thisSingle
.- Parameters:
subscriber
- the subscriber.
-
succeeded
public static <T> Single<T> succeeded(@Nullable T value)
Creates a realizedSingle
which always completes successfully with the providedvalue
.
-
fromCallable
public static <T> Single<T> fromCallable(java.util.concurrent.Callable<T> callable)
Creates aSingle
which when subscribed will invokeCallable.call()
on the passedCallable
and emit the value returned by that invocation from the returnedSingle
. Any error emitted by theCallable
will terminate the returnedSingle
with the same error.Blocking inside
Callable.call()
will in turn block the subscribe call to the returnedSingle
. If this behavior is undesirable then the returnedSingle
should be offloaded using one of the operators that offloads the subscribe call (eg:subscribeOn(Executor)
,publishAndSubscribeOn(Executor)
).
-
fromSupplier
public static <T> Single<T> fromSupplier(java.util.function.Supplier<T> supplier)
Creates aSingle
which when subscribed will invokeSupplier.get()
on the passedSupplier
and emit the value returned by that invocation from the returnedSingle
. Any error emitted by theSupplier
will terminate the returnedSingle
with the same error.Blocking inside
Supplier.get()
will in turn block the subscribe call to the returnedSingle
. If this behavior is undesirable then the returnedSingle
should be offloaded using one of the operators that offloads the subscribe call (eg:subscribeOn(Executor)
,publishAndSubscribeOn(Executor)
).
-
failed
public static <T> Single<T> failed(java.lang.Throwable cause)
Creates a realizedSingle
which always completes with the provided errorcause
.
-
defer
public static <T> Single<T> defer(java.util.function.Supplier<? extends Single<? extends T>> singleSupplier)
Defer creation of aSingle
till it is subscribed to.- Type Parameters:
T
- Type of theSingle
.- Parameters:
singleSupplier
-Supplier
to create a newSingle
every time the returnedSingle
is subscribed.- Returns:
- A new
Single
that creates a newSingle
usingsingleSupplier
every time it is subscribed and forwards all items and terminal events from the newly createdSingle
to itsSingleSource.Subscriber
.
-
fromFuture
public static <T> Single<T> fromFuture(java.util.concurrent.Future<? extends T> future)
Convert from aFuture
to aSingle
viaFuture.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 ifCancellable.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 theFuture
provides when complete.- Parameters:
future
- TheFuture
to convert.- Returns:
- A
Single
that derives results fromFuture
. - See Also:
idleTimeout(long, TimeUnit)
-
collectUnordered
public static <T> Single<java.util.Collection<T>> collectUnordered(java.lang.Iterable<? extends Single<? extends T>> singles)
Asynchronously collects results of individualSingle
s returned by the passedIterable
into a singleCollection
.This will actively subscribe to a limited number of
Single
s concurrently, in order to alter the defaults,collectUnordered(Iterable, int)
should be used.If any of the
Single
s terminate with an error, returnedSingle
will immediately terminate with that error. In such a case, any in progressSingle
s will be cancelled. In order to delay error termination usecollectUnorderedDelayError(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 individualSingle
s- Parameters:
singles
-Iterable
ofSingle
s, results of which are to be collected.- Returns:
- A
Single
producing aCollection
of all values produced by the individualSingle
s. There is no guarantee of the order of the values in the producedCollection
as compared to the order ofSingle
s passed to this method.
-
collectUnordered
@SafeVarargs public static <T> Single<java.util.Collection<T>> collectUnordered(Single<? extends T>... singles)
Asynchronously collects results of the passedSingle
s into a singleCollection
.This will actively subscribe to a limited number of
Single
s concurrently, in order to alter the defaults,collectUnordered(int, Single[])
should be used.If any of the
Single
s terminate with an error, returnedSingle
will immediately terminate with that error. In such a case, any in progressSingle
s will be cancelled. In order to delay error termination usecollectUnorderedDelayError(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 individualSingle
s- Parameters:
singles
-Single
s, results of which are to be collected.- Returns:
- A
Single
producing aCollection
of all values produced by the individualSingle
s. There is no guarantee of the order of the values in the producedCollection
as compared to the order ofSingle
s 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 individualSingle
s returned by the passedIterable
into a singleCollection
.If any of the
Single
s terminate with an error, returnedSingle
will immediately terminate with that error. In such a case, any in progressSingle
s will be cancelled. In order to delay error termination usecollectUnorderedDelayError(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 individualSingle
s- Parameters:
singles
-Iterable
ofSingle
s, results of which are to be collected.maxConcurrency
- Maximum number ofSingle
s that will be active at any point in time.- Returns:
- A
Single
producing aCollection
of all values produced by the individualSingle
s. There is no guarantee of the order of the values in the producedCollection
as compared to the order ofSingle
s 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 passedSingle
s into a singleCollection
.If any of the
Single
s terminate with an error, returnedSingle
will immediately terminate with that error. In such a case, any in progressSingle
s will be cancelled. In order to delay error termination usecollectUnorderedDelayError(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 individualSingle
s- Parameters:
maxConcurrency
- Maximum number ofSingle
s that will be active at any point in time.singles
-Single
s, results of which are to be collected.- Returns:
- A
Single
producing aCollection
of all values produced by the individualSingle
s. There is no guarantee of the order of the values in the producedCollection
as compared to the order ofSingle
s 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 individualSingle
s returned by the passedIterable
into a singleCollection
.This will actively subscribe to a limited number of
Single
s concurrently, in order to alter the defaults,collectUnorderedDelayError(Iterable, int)
.If any of the
Single
s terminate with an error, returnedSingle
will wait for termination till all the otherSingle
s have been subscribed and terminated. If it is expected for the returnedSingle
to terminate on the first failingSingle
,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 individualSingle
s- Parameters:
singles
-Iterable
ofSingle
s, results of which are to be collected.- Returns:
- A
Single
producing aCollection
of all values produced by the individualSingle
s. There is no guarantee of the order of the values in the producedCollection
as compared to the order ofSingle
s passed to this method.
-
collectUnorderedDelayError
@SafeVarargs public static <T> Single<java.util.Collection<T>> collectUnorderedDelayError(Single<? extends T>... singles)
Asynchronously collects results of the passedSingle
s into a singleCollection
.This will actively subscribe to a limited number of
Single
s concurrently, in order to alter the defaults,collectUnordered(int, Single[])
.If any of the
Single
s terminate with an error, returnedSingle
will wait for termination till all the otherSingle
s have been subscribed and terminated. If it is expected for the returnedSingle
to terminate on the first failingSingle
,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 individualSingle
s- Parameters:
singles
-Single
s, results of which are to be collected.- Returns:
- A
Single
producing aCollection
of all values produced by the individualSingle
s. There is no guarantee of the order of the values in the producedCollection
as compared to the order ofSingle
s 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 individualSingle
s returned by the passedIterable
into a singleCollection
.If any of the
Single
s terminate with an error, returnedSingle
will wait for termination till all the otherSingle
s have been subscribed and terminated. If it is expected for the returnedSingle
to terminate on the first failingSingle
,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 individualSingle
s- Parameters:
singles
-Iterable
ofSingle
s, results of which are to be collected.maxConcurrency
- Maximum number ofSingle
s that will be active at any point in time.- Returns:
- A
Single
producing aCollection
of all values produced by the individualSingle
s. There is no guarantee of the order of the values in the producedCollection
as compared to the order ofSingle
s 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 passedSingle
s into a singleCollection
.If any of the
Single
s terminate with an error, returnedSingle
will wait for termination till all the otherSingle
s have been subscribed and terminated. If it is expected for the returnedSingle
to terminate on the first failingSingle
,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 individualSingle
s- Parameters:
maxConcurrency
- Maximum number ofSingle
s that will be active at any point in time.singles
-Single
s, results of which are to be collected.- Returns:
- A
Single
producing aCollection
of all values produced by the individualSingle
s. There is no guarantee of the order of the values in the producedCollection
as compared to the order ofSingle
s passed to this method.
-
fromStage
public static <T> Single<T> fromStage(java.util.concurrent.CompletionStage<? extends T> stage)
Convert from aCompletionStage
to aSingle
.A best effort is made to propagate
Cancellable.cancel()
to theCompletionStage
. Cancellation forCompletionStage
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 anExecutor
is appropriate.- Type Parameters:
T
- The data type theCompletionStage
provides when complete.- Parameters:
stage
- TheCompletionStage
to convert.- Returns:
- A
Single
that derives results fromCompletionStage
.
-
amb
@SafeVarargs public static <T> Single<T> amb(Single<? extends T>... singles)
Creates a newSingle
that terminates with the result (either success or error) of whichever amongst the passedsingles
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 individualSingle
s- Parameters:
singles
-Single
s 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 passedsingles
that terminates first. - See Also:
- ReactiveX amb operator.
-
amb
public static <T> Single<T> amb(java.lang.Iterable<Single<? extends T>> singles)
Creates a newSingle
that terminates with the result (either success or error) of whichever amongst the passedsingles
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 individualSingle
s- Parameters:
singles
-Single
s 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 passedsingles
that terminates first. - See Also:
- ReactiveX amb operator.
-
anyOf
@SafeVarargs public static <T> Single<T> anyOf(Single<? extends T>... singles)
Creates a newSingle
that terminates with the result (either success or error) of whichever amongst the passedsingles
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 individualSingle
s- Parameters:
singles
-Single
s 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 passedsingles
that terminates first. - See Also:
- ReactiveX amb operator.
-
anyOf
public static <T> Single<T> anyOf(java.lang.Iterable<Single<? extends T>> singles)
Creates a newSingle
that terminates with the result (either success or error) of whichever amongst the passedsingles
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 individualSingle
s- Parameters:
singles
-Single
s 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 passedsingles
that terminates first. - See Also:
- ReactiveX amb operator.
-
-