public abstract class Completable extends Object implements CompletableSource
Completable
class represents a deferred computation without any value but
only indication for completion or exception.
Completable
behaves similarly to Observable
except that it can only emit either
a completion or error signal (there is no onNext
or onSuccess
as with the other
reactive types).
The Completable
class implements the CompletableSource
base interface and the default consumer
type it interacts with is the CompletableObserver
via the subscribe(CompletableObserver)
method.
The Completable
operates with the following sequential protocol:
onSubscribe (onError | onComplete)?
Note that as with the Observable
protocol, onError
and onComplete
are mutually exclusive events.
Like Observable
, a running Completable
can be stopped through the Disposable
instance
provided to consumers through CompletableObserver.onSubscribe(io.reactivex.rxjava3.disposables.Disposable)
.
Like an Observable
, a Completable
is lazy, can be either "hot" or "cold", synchronous or
asynchronous. Completable
instances returned by the methods of this class are cold
and there is a standard hot implementation in the form of a subject:
CompletableSubject
.
The documentation for this class makes use of marble diagrams. The following legend explains these diagrams:
See Flowable
or Observable
for the
implementation of the Reactive Pattern for a stream or vector of values.
Example:
Disposable d = Completable.complete()
.delay(10, TimeUnit.SECONDS, Schedulers.io())
.subscribeWith(new DisposableCompletableObserver() {
@Override
public void onStart() {
System.out.println("Started");
}
@Override
public void onError(Throwable error) {
error.printStackTrace();
}
@Override
public void onComplete() {
System.out.println("Done!");
}
});
Thread.sleep(5000);
d.dispose();
Note that by design, subscriptions via subscribe(CompletableObserver)
can't be disposed
from the outside (hence the
void
return of the subscribe(CompletableObserver)
method) and it is the
responsibility of the implementor of the CompletableObserver
to allow this to happen.
RxJava supports such usage with the standard
DisposableCompletableObserver
instance.
For convenience, the subscribeWith(CompletableObserver)
method is provided as well to
allow working with a CompletableObserver
(or subclass) instance to be applied with in
a fluent manner (such as in the example above).
DisposableCompletableObserver
Constructor and Description |
---|
Completable() |
Modifier and Type | Method and Description |
---|---|
static @NonNull Completable |
amb(@NonNull Iterable<? extends CompletableSource> sources)
Returns a
Completable which terminates as soon as one of the source Completable s in the Iterable sequence
terminates (normally or with an error) and disposes all other Completable s. |
static @NonNull Completable |
ambArray(CompletableSource... sources)
Returns a
Completable which terminates as soon as one of the source Completable s
terminates (normally or with an error) and disposes all other Completable s. |
@NonNull Completable |
ambWith(@NonNull CompletableSource other)
Returns a
Completable that emits the a terminated event of either this Completable
or the other CompletableSource , whichever fires first. |
@NonNull Completable |
andThen(@NonNull CompletableSource next)
|
<T> @NonNull Maybe<T> |
andThen(@NonNull MaybeSource<T> next)
Returns a
Maybe which will subscribe to this Completable and once that is completed then
will subscribe to the next MaybeSource . |
<T> @NonNull Observable<T> |
andThen(@NonNull ObservableSource<T> next)
Returns an
Observable which will subscribe to this Completable and once that is completed then
will subscribe to the next ObservableSource . |
<T> @NonNull Flowable<T> |
andThen(@NonNull Publisher<T> next)
|
<T> @NonNull Single<T> |
andThen(@NonNull SingleSource<T> next)
Returns a
Single which will subscribe to this Completable and once that is completed then
will subscribe to the next SingleSource . |
void |
blockingAwait()
Subscribes to and awaits the termination of this
Completable instance in a blocking manner and
rethrows any exception emitted. |
boolean |
blockingAwait(long timeout,
@NonNull TimeUnit unit)
Subscribes to and awaits the termination of this
Completable instance in a blocking manner
with a specific timeout and rethrows any exception emitted within the timeout window. |
void |
blockingSubscribe()
Subscribes to the current
Completable and blocks the current thread until it terminates. |
void |
blockingSubscribe(@NonNull Action onComplete)
Subscribes to the current
Completable and calls given onComplete callback on the current thread
when it completes normally. |
void |
blockingSubscribe(@NonNull Action onComplete,
@NonNull Consumer<? super Throwable> onError)
Subscribes to the current
Completable and calls the appropriate callback on the current thread
when it terminates. |
void |
blockingSubscribe(@NonNull CompletableObserver observer)
Subscribes to the current
Completable and calls the appropriate CompletableObserver method on the current thread. |
@NonNull Completable |
cache()
Subscribes to this
Completable only once, when the first CompletableObserver
subscribes to the result Completable , caches its terminal event
and relays/replays it to observers. |
static @NonNull Completable |
complete()
Returns a
Completable instance that completes immediately when subscribed to. |
@NonNull Completable |
compose(@NonNull CompletableTransformer transformer)
Calls the given transformer function with this instance and returns the function's resulting
CompletableSource wrapped with wrap(CompletableSource) . |
static @NonNull Completable |
concat(@NonNull Iterable<? extends CompletableSource> sources)
Returns a
Completable which completes only when all sources complete, one after another. |
static @NonNull Completable |
concat(@NonNull Publisher<? extends CompletableSource> sources)
Returns a
Completable which completes only when all sources complete, one after another. |
static @NonNull Completable |
concat(@NonNull Publisher<? extends CompletableSource> sources,
int prefetch)
Returns a
Completable which completes only when all sources complete, one after another. |
static @NonNull Completable |
concatArray(CompletableSource... sources)
Returns a
Completable which completes only when all sources complete, one after another. |
static @NonNull Completable |
concatArrayDelayError(CompletableSource... sources)
Returns a
Completable which completes only when all sources complete, one after another. |
static @NonNull Completable |
concatDelayError(@NonNull Iterable<? extends CompletableSource> sources)
Returns a
Completable which completes only when all sources complete, one after another. |
static @NonNull Completable |
concatDelayError(@NonNull Publisher<? extends CompletableSource> sources)
Returns a
Completable which completes only when all sources complete, one after another. |
static @NonNull Completable |
concatDelayError(@NonNull Publisher<? extends CompletableSource> sources,
int prefetch)
Returns a
Completable which completes only when all sources complete, one after another. |
@NonNull Completable |
concatWith(@NonNull CompletableSource other)
Concatenates this
Completable with another CompletableSource . |
static @NonNull Completable |
create(@NonNull CompletableOnSubscribe source)
Provides an API (via a cold
Completable ) that bridges the reactive world with the callback-style world. |
static @NonNull Completable |
defer(@NonNull Supplier<? extends CompletableSource> supplier)
Defers the subscription to a
Completable instance returned by a supplier. |
@NonNull Completable |
delay(long time,
@NonNull TimeUnit unit)
Returns a
Completable which delays the emission of the completion event by the given time. |
@NonNull Completable |
delay(long time,
@NonNull TimeUnit unit,
@NonNull Scheduler scheduler)
Returns a
Completable which delays the emission of the completion event by the given time while
running on the specified Scheduler . |
@NonNull Completable |
delay(long time,
@NonNull TimeUnit unit,
@NonNull Scheduler scheduler,
boolean delayError)
Returns a
Completable which delays the emission of the completion event, and optionally the error as well, by the given time while
running on the specified Scheduler . |
@NonNull Completable |
delaySubscription(long time,
@NonNull TimeUnit unit)
Returns a
Completable that delays the subscription to the upstream by a given amount of time. |
@NonNull Completable |
delaySubscription(long time,
@NonNull TimeUnit unit,
@NonNull Scheduler scheduler)
Returns a
Completable that delays the subscription to the upstream by a given amount of time,
both waiting and subscribing on a given Scheduler . |
@NonNull Completable |
doAfterTerminate(@NonNull Action onAfterTerminate)
Returns a
Completable instance that calls the given onAfterTerminate Action after this Completable
completes normally or with an exception. |
@NonNull Completable |
doFinally(@NonNull Action onFinally)
Calls the specified
Action after this Completable signals onError or onComplete or gets disposed by
the downstream. |
@NonNull Completable |
doOnComplete(@NonNull Action onComplete)
|
@NonNull Completable |
doOnDispose(@NonNull Action onDispose)
Calls the shared
Action if a CompletableObserver subscribed to the current
Completable disposes the common Disposable it received via onSubscribe . |
@NonNull Completable |
doOnError(@NonNull Consumer<? super Throwable> onError)
|
@NonNull Completable |
doOnEvent(@NonNull Consumer<? super Throwable> onEvent)
|
@NonNull Completable |
doOnLifecycle(@NonNull Consumer<? super Disposable> onSubscribe,
@NonNull Action onDispose)
Calls the appropriate
onXXX method (shared between all CompletableObserver s) for the lifecycle events of
the sequence (subscription, disposal). |
@NonNull Completable |
doOnSubscribe(@NonNull Consumer<? super Disposable> onSubscribe)
Returns a
Completable instance that calls the given onSubscribe callback with the disposable
that the downstream CompletableObserver s receive upon subscription. |
@NonNull Completable |
doOnTerminate(@NonNull Action onTerminate)
Returns a
Completable instance that calls the given onTerminate Action just before this Completable
completes normally or with an exception. |
static @NonNull Completable |
error(@NonNull Supplier<? extends Throwable> supplier)
Creates a
Completable which calls the given error supplier for each subscriber
and emits its returned Throwable . |
static @NonNull Completable |
error(@NonNull Throwable throwable)
Creates a
Completable instance that emits the given Throwable exception to subscribers. |
static @NonNull Completable |
fromAction(@NonNull Action action)
Returns a
Completable instance that runs the given Action for each CompletableObserver and
emits either an exception or simply completes. |
static @NonNull Completable |
fromCallable(@NonNull Callable<?> callable)
Returns a
Completable which when subscribed, executes the Callable function, ignores its
normal result and emits onError or onComplete only. |
static @NonNull Completable |
fromCompletionStage(@NonNull CompletionStage<?> stage)
Signals completion (or error) when the
CompletionStage terminates. |
static @NonNull Completable |
fromFuture(@NonNull Future<?> future)
Returns a
Completable instance that reacts to the termination of the given Future in a blocking fashion. |
static <T> @NonNull Completable |
fromMaybe(@NonNull MaybeSource<T> maybe)
Returns a
Completable instance that when subscribed to, subscribes to the MaybeSource instance and
emits an onComplete event if the maybe emits onSuccess /onComplete or forwards any
onError events. |
static <T> @NonNull Completable |
fromObservable(@NonNull ObservableSource<T> observable)
Returns a
Completable instance that subscribes to the given ObservableSource , ignores all values and
emits only the terminal event. |
static <T> @NonNull Completable |
fromPublisher(@NonNull Publisher<T> publisher)
Returns a
Completable instance that subscribes to the given Publisher , ignores all values and
emits only the terminal event. |
static @NonNull Completable |
fromRunnable(@NonNull Runnable run)
Returns a
Completable instance that runs the given Runnable for each CompletableObserver and
emits either its unchecked exception or simply completes. |
static <T> @NonNull Completable |
fromSingle(@NonNull SingleSource<T> single)
Returns a
Completable instance that when subscribed to, subscribes to the SingleSource instance and
emits a completion event if the single emits onSuccess or forwards any onError events. |
static @NonNull Completable |
fromSupplier(@NonNull Supplier<?> supplier)
Returns a
Completable which when subscribed, executes the Supplier function, ignores its
normal result and emits onError or onComplete only. |
@NonNull Completable |
hide()
Hides the identity of this
Completable and its Disposable . |
@NonNull Completable |
lift(@NonNull CompletableOperator onLift)
This method requires advanced knowledge about building operators, please consider
other standard composition methods first;
Returns a
Completable which, when subscribed to, invokes the apply(CompletableObserver) method
of the provided CompletableOperator for each individual downstream Completable and allows the
insertion of a custom operator by accessing the downstream's CompletableObserver during this subscription phase
and providing a new CompletableObserver , containing the custom operator's intended business logic, that will be
used in the subscription process going further upstream. |
<T> @NonNull Single<Notification<T>> |
materialize()
Maps the signal types of this
Completable into a Notification of the same kind
and emits it as a single success value to downstream. |
static @NonNull Completable |
merge(@NonNull Iterable<? extends CompletableSource> sources)
Returns a
Completable instance that subscribes to all sources at once and
completes only when all source CompletableSource s complete or one of them emits an error. |
static @NonNull Completable |
merge(@NonNull Publisher<? extends CompletableSource> sources)
Returns a
Completable instance that subscribes to all sources at once and
completes only when all source CompletableSource s complete or one of them emits an error. |
static @NonNull Completable |
merge(@NonNull Publisher<? extends CompletableSource> sources,
int maxConcurrency)
Returns a
Completable instance that keeps subscriptions to a limited number of sources at once and
completes only when all source CompletableSource s complete or one of them emits an error. |
static @NonNull Completable |
mergeArray(CompletableSource... sources)
Returns a
Completable instance that subscribes to all sources at once and
completes only when all source CompletableSource s complete or one of them emits an error. |
static @NonNull Completable |
mergeArrayDelayError(CompletableSource... sources)
Returns a
Completable that subscribes to all CompletableSource s in the source array and delays
any error emitted by any of the inner CompletableSource s until all of
them terminate in a way or another. |
static @NonNull Completable |
mergeDelayError(@NonNull Iterable<? extends CompletableSource> sources)
Returns a
Completable that subscribes to all CompletableSource s in the source sequence and delays
any error emitted by any of the inner CompletableSource s until all of
them terminate in a way or another. |
static @NonNull Completable |
mergeDelayError(@NonNull Publisher<? extends CompletableSource> sources)
Returns a
Completable that subscribes to all CompletableSource s in the source sequence and delays
any error emitted by either the sources Publisher or any of the inner CompletableSource s until all of
them terminate in a way or another. |
static @NonNull Completable |
mergeDelayError(@NonNull Publisher<? extends CompletableSource> sources,
int maxConcurrency)
Returns a
Completable that subscribes to a limited number of inner CompletableSource s at once in
the source sequence and delays any error emitted by either the sources
Publisher or any of the inner CompletableSource s until all of
them terminate in a way or another. |
@NonNull Completable |
mergeWith(@NonNull CompletableSource other)
Returns a
Completable which subscribes to this and the other CompletableSource and completes
when both of them complete or one emits an error. |
static @NonNull Completable |
never()
Returns a
Completable that never calls onError or onComplete . |
@NonNull Completable |
observeOn(@NonNull Scheduler scheduler)
Returns a
Completable which emits the terminal events from the thread of the specified Scheduler . |
@NonNull Completable |
onErrorComplete()
Returns a
Completable instance that if this Completable emits an error, it will emit an onComplete
and swallow the upstream Throwable . |
@NonNull Completable |
onErrorComplete(@NonNull Predicate<? super Throwable> predicate)
|
@NonNull Completable |
onErrorResumeNext(@NonNull Function<? super Throwable,? extends CompletableSource> fallbackSupplier)
Returns a
Completable instance that when encounters an error from this Completable , calls the
specified mapper Function that returns a CompletableSource instance for it and resumes the
execution with it. |
@NonNull Completable |
onErrorResumeWith(@NonNull CompletableSource fallback)
Resumes the flow with the given
CompletableSource when the current Completable fails instead of
signaling the error via onError . |
<T> @NonNull Maybe<T> |
onErrorReturn(@NonNull Function<? super Throwable,? extends T> itemSupplier)
Ends the flow with a success item returned by a function for the
Throwable error signaled by the current
Completable instead of signaling the error via onError . |
<T> @NonNull Maybe<T> |
onErrorReturnItem(T item)
Ends the flow with the given success item when the current
Completable
fails instead of signaling the error via onError . |
@NonNull Completable |
onTerminateDetach()
Nulls out references to the upstream producer and downstream
CompletableObserver if
the sequence is terminated or downstream calls dispose() . |
@NonNull Completable |
repeat()
Returns a
Completable that repeatedly subscribes to this Completable until disposed. |
@NonNull Completable |
repeat(long times)
Returns a
Completable that subscribes repeatedly at most the given number of times to this Completable . |
@NonNull Completable |
repeatUntil(@NonNull BooleanSupplier stop)
Returns a
Completable that repeatedly subscribes to this Completable so long as the given
stop BooleanSupplier returns false . |
@NonNull Completable |
repeatWhen(@NonNull Function<? super Flowable<Object>,? extends Publisher<?>> handler)
|
@NonNull Completable |
retry()
Returns a
Completable that retries this Completable as long as it emits an onError event. |
@NonNull Completable |
retry(@NonNull BiPredicate<? super Integer,? super Throwable> predicate)
Returns a
Completable that retries this Completable in case of an error as long as the predicate
returns true . |
@NonNull Completable |
retry(long times)
Returns a
Completable that when this Completable emits an error, retries at most the given
number of times before giving up and emitting the last error. |
@NonNull Completable |
retry(long times,
@NonNull Predicate<? super Throwable> predicate)
Returns a
Completable that when this Completable emits an error, retries at most times
or until the predicate returns false , whichever happens first and emitting the last error. |
@NonNull Completable |
retry(@NonNull Predicate<? super Throwable> predicate)
Returns a
Completable that when this Completable emits an error, calls the given predicate with
the latest Throwable to decide whether to resubscribe to the upstream or not. |
@NonNull Completable |
retryUntil(@NonNull BooleanSupplier stop)
Retries until the given stop function returns
true . |
@NonNull Completable |
retryWhen(@NonNull Function<? super Flowable<Throwable>,? extends Publisher<?>> handler)
|
void |
safeSubscribe(@NonNull CompletableObserver observer)
Wraps the given
CompletableObserver , catches any RuntimeException s thrown by its
CompletableObserver.onSubscribe(Disposable) , CompletableObserver.onError(Throwable)
or CompletableObserver.onComplete() methods and routes those to the global
error handler via RxJavaPlugins.onError(Throwable) . |
static @NonNull Single<Boolean> |
sequenceEqual(@NonNull CompletableSource source1,
@NonNull CompletableSource source2)
|
@NonNull Completable |
startWith(@NonNull CompletableSource other)
Returns a
Completable which first runs the other CompletableSource
then the current Completable if the other completed normally. |
<T> @NonNull Flowable<T> |
startWith(@NonNull MaybeSource<T> other)
Returns a
Flowable which first runs the other MaybeSource
then the current Completable if the other succeeded or completed normally. |
<T> @NonNull Observable<T> |
startWith(@NonNull ObservableSource<T> other)
Returns an
Observable which first delivers the events
of the other ObservableSource then runs the current Completable . |
<T> @NonNull Flowable<T> |
startWith(@NonNull Publisher<T> other)
|
<T> @NonNull Flowable<T> |
startWith(@NonNull SingleSource<T> other)
Returns a
Flowable which first runs the other SingleSource
then the current Completable if the other succeeded normally. |
@NonNull Disposable |
subscribe()
Subscribes to this
Completable and returns a Disposable which can be used to dispose
the subscription. |
@NonNull Disposable |
subscribe(@NonNull Action onComplete)
|
@NonNull Disposable |
subscribe(@NonNull Action onComplete,
@NonNull Consumer<? super Throwable> onError)
Subscribes to this
Completable and calls back either the onError or onComplete functions. |
@NonNull Disposable |
subscribe(@NonNull Action onComplete,
@NonNull Consumer<? super Throwable> onError,
@NonNull DisposableContainer container)
Wraps the given onXXX callbacks into a
Disposable CompletableObserver ,
adds it to the given DisposableContainer and ensures, that if the upstream
terminates or this particular Disposable is disposed, the CompletableObserver is removed
from the given composite. |
void |
subscribe(@NonNull CompletableObserver observer)
Subscribes the given
CompletableObserver to this CompletableSource instance. |
protected abstract void |
subscribeActual(@NonNull CompletableObserver observer)
Implement this method to handle the incoming
CompletableObserver s and
perform the business logic in your operator. |
@NonNull Completable |
subscribeOn(@NonNull Scheduler scheduler)
Returns a
Completable which subscribes the downstream subscriber on the specified scheduler, making
sure the subscription side-effects happen on that specific thread of the Scheduler . |
<E extends CompletableObserver> |
subscribeWith(E observer)
Subscribes a given
CompletableObserver (subclass) to this Completable and returns the given
CompletableObserver as is. |
static @NonNull Completable |
switchOnNext(@NonNull Publisher<? extends CompletableSource> sources)
Switches between
CompletableSource s emitted by the source Publisher whenever
a new CompletableSource is emitted, disposing the previously running CompletableSource ,
exposing the setup as a Completable sequence. |
static @NonNull Completable |
switchOnNextDelayError(@NonNull Publisher<? extends CompletableSource> sources)
Switches between
CompletableSource s emitted by the source Publisher whenever
a new CompletableSource is emitted, disposing the previously running CompletableSource ,
exposing the setup as a Completable sequence and delaying all errors from
all of them until all terminate. |
@NonNull Completable |
takeUntil(@NonNull CompletableSource other)
Terminates the downstream if this or the other
Completable
terminates (wins the termination race) while disposing the connection to the losing source. |
@NonNull TestObserver<Void> |
test()
Creates a
TestObserver and subscribes
it to this Completable . |
@NonNull TestObserver<Void> |
test(boolean dispose)
Creates a
TestObserver optionally in cancelled state, then subscribes it to this Completable . |
@NonNull Completable |
timeout(long timeout,
@NonNull TimeUnit unit)
Returns a
Completabl e that runs this Completable and emits a TimeoutException in case
this Completable doesn't complete within the given time. |
@NonNull Completable |
timeout(long timeout,
@NonNull TimeUnit unit,
@NonNull CompletableSource fallback)
Returns a
Completable that runs this Completable and switches to the other CompletableSource
in case this Completable doesn't complete within the given time. |
@NonNull Completable |
timeout(long timeout,
@NonNull TimeUnit unit,
@NonNull Scheduler scheduler)
Returns a
Completable that runs this Completable and emits a TimeoutException in case
this Completable doesn't complete within the given time while "waiting" on the specified
Scheduler . |
@NonNull Completable |
timeout(long timeout,
@NonNull TimeUnit unit,
@NonNull Scheduler scheduler,
@NonNull CompletableSource fallback)
Returns a
Completable that runs this Completable and switches to the other CompletableSource
in case this Completable doesn't complete within the given time while "waiting" on
the specified Scheduler . |
static @NonNull Completable |
timer(long delay,
@NonNull TimeUnit unit)
Returns a
Completable instance that fires its onComplete event after the given delay elapsed. |
static @NonNull Completable |
timer(long delay,
@NonNull TimeUnit unit,
@NonNull Scheduler scheduler)
Returns a
Completable instance that fires its onComplete event after the given delay elapsed
by using the supplied Scheduler . |
<R> R |
to(@NonNull CompletableConverter<? extends R> converter)
Calls the specified
CompletableConverter function during assembly time and returns its resulting value. |
<T> @NonNull CompletionStage<T> |
toCompletionStage(T defaultItem)
Signals the given default item when the upstream completes or signals the upstream error via
a
CompletionStage . |
<T> @NonNull Flowable<T> |
toFlowable()
Returns a
Flowable which when subscribed to subscribes to this Completable and
relays the terminal events to the downstream Subscriber . |
@NonNull Future<Void> |
toFuture()
|
<T> @NonNull Maybe<T> |
toMaybe()
Converts this
Completable into a Maybe . |
<T> @NonNull Observable<T> |
toObservable()
Returns an
Observable which when subscribed to subscribes to this Completable and
relays the terminal events to the downstream Observer . |
<T> @NonNull Single<T> |
toSingle(@NonNull Supplier<? extends T> completionValueSupplier)
|
<T> @NonNull Single<T> |
toSingleDefault(T completionValue)
Converts this
Completable into a Single which when this Completable completes normally,
emits the given value through onSuccess . |
static @NonNull Completable |
unsafeCreate(@NonNull CompletableSource onSubscribe)
Constructs a
Completable instance by wrapping the given source callback
without any safeguards; you should manage the lifecycle and response
to downstream disposal. |
@NonNull Completable |
unsubscribeOn(@NonNull Scheduler scheduler)
Returns a
Completable which makes sure when an observer disposes the subscription, the
dispose() method is called on the specified Scheduler . |
static <R> @NonNull Completable |
using(@NonNull Supplier<R> resourceSupplier,
@NonNull Function<? super R,? extends CompletableSource> sourceSupplier,
@NonNull Consumer<? super R> resourceCleanup)
Returns a
Completable instance which manages a resource along
with a custom CompletableSource instance while the subscription is active. |
static <R> @NonNull Completable |
using(@NonNull Supplier<R> resourceSupplier,
@NonNull Function<? super R,? extends CompletableSource> sourceSupplier,
@NonNull Consumer<? super R> resourceCleanup,
boolean eager)
Returns a
Completable instance which manages a resource along
with a custom CompletableSource instance while the subscription is active and performs eager or lazy
resource disposition. |
static @NonNull Completable |
wrap(@NonNull CompletableSource source)
|
@CheckReturnValue @NonNull @SchedulerSupport(value="none") @SafeVarargs public static @NonNull Completable ambArray(@NonNull CompletableSource... sources)
Completable
which terminates as soon as one of the source Completable
s
terminates (normally or with an error) and disposes all other Completable
s.
ambArray
does not operate by default on a particular Scheduler
.sources
- the array of source Completable
s. A subscription to each source will
occur in the same order as in this array.Completable
instanceNullPointerException
- if sources
is null
@CheckReturnValue @NonNull @SchedulerSupport(value="none") public static @NonNull Completable amb(@NonNull Iterable<? extends CompletableSource> sources)
Completable
which terminates as soon as one of the source Completable
s in the Iterable
sequence
terminates (normally or with an error) and disposes all other Completable
s.
amb
does not operate by default on a particular Scheduler
.sources
- the Iterable
of source Completable
s. A subscription to each source will
occur in the same order as in this Iterable
.Completable
instanceNullPointerException
- if sources
is null
@CheckReturnValue @NonNull @SchedulerSupport(value="none") public static @NonNull Completable complete()
Completable
instance that completes immediately when subscribed to.
complete
does not operate by default on a particular Scheduler
.Completable
instance@CheckReturnValue @NonNull @SchedulerSupport(value="none") @SafeVarargs public static @NonNull Completable concatArray(@NonNull CompletableSource... sources)
Completable
which completes only when all sources complete, one after another.
concatArray
does not operate by default on a particular Scheduler
.sources
- the sources to concatenateCompletable
instanceNullPointerException
- if sources
is null
@CheckReturnValue @NonNull @SchedulerSupport(value="none") @SafeVarargs public static @NonNull Completable concatArrayDelayError(@NonNull CompletableSource... sources)
Completable
which completes only when all sources complete, one after another.
concatArrayDelayError
does not operate by default on a particular Scheduler
.sources
- the sources to concatenateCompletable
instanceNullPointerException
- if sources
is null
@CheckReturnValue @NonNull @SchedulerSupport(value="none") public static @NonNull Completable concat(@NonNull Iterable<? extends CompletableSource> sources)
Completable
which completes only when all sources complete, one after another.
concat
does not operate by default on a particular Scheduler
.sources
- the sources to concatenateCompletable
instanceNullPointerException
- if sources
is null
@CheckReturnValue @SchedulerSupport(value="none") @BackpressureSupport(value=FULL) @NonNull public static @NonNull Completable concat(@NonNull Publisher<? extends CompletableSource> sources)
Completable
which completes only when all sources complete, one after another.
sources
- the sources to concatenateCompletable
instanceNullPointerException
- if sources
is null
@CheckReturnValue @NonNull @SchedulerSupport(value="none") @BackpressureSupport(value=FULL) public static @NonNull Completable concat(@NonNull Publisher<? extends CompletableSource> sources, int prefetch)
Completable
which completes only when all sources complete, one after another.
sources
- the sources to concatenateprefetch
- the number of sources to prefetch from the sourcesCompletable
instanceNullPointerException
- if sources
is null
IllegalArgumentException
- if prefetch
is non-positive@CheckReturnValue @NonNull @SchedulerSupport(value="none") public static @NonNull Completable concatDelayError(@NonNull Iterable<? extends CompletableSource> sources)
Completable
which completes only when all sources complete, one after another.
concatDelayError
does not operate by default on a particular Scheduler
.sources
- the sources to concatenateCompletable
instanceNullPointerException
- if sources
is null
@CheckReturnValue @SchedulerSupport(value="none") @BackpressureSupport(value=FULL) @NonNull public static @NonNull Completable concatDelayError(@NonNull Publisher<? extends CompletableSource> sources)
Completable
which completes only when all sources complete, one after another.
sources
- the sources to concatenateCompletable
instanceNullPointerException
- if sources
is null
@CheckReturnValue @NonNull @SchedulerSupport(value="none") @BackpressureSupport(value=FULL) public static @NonNull Completable concatDelayError(@NonNull Publisher<? extends CompletableSource> sources, int prefetch)
Completable
which completes only when all sources complete, one after another.
sources
- the sources to concatenateprefetch
- the number of sources to prefetch from the sourcesCompletable
instanceNullPointerException
- if sources
is null
IllegalArgumentException
- if prefetch
is non-positive@CheckReturnValue @NonNull @SchedulerSupport(value="none") public static @NonNull Completable create(@NonNull CompletableOnSubscribe source)
Completable
) that bridges the reactive world with the callback-style world.
Example:
Completable.create(emitter -> {
Callback listener = new Callback() {
@Override
public void onEvent(Event e) {
emitter.onComplete();
}
@Override
public void onFailure(Exception e) {
emitter.onError(e);
}
};
AutoCloseable c = api.someMethod(listener);
emitter.setCancellable(c::close);
});
Whenever a CompletableObserver
subscribes to the returned Completable
, the provided
CompletableOnSubscribe
callback is invoked with a fresh instance of a CompletableEmitter
that will interact only with that specific CompletableObserver
. If this CompletableObserver
disposes the flow (making CompletableEmitter.isDisposed()
return true
),
other observers subscribed to the same returned Completable
are not affected.
create
does not operate by default on a particular Scheduler
.source
- the emitter that is called when a CompletableObserver
subscribes to the returned Completable
Completable
instanceNullPointerException
- if source
is null
CompletableOnSubscribe
,
Cancellable
@CheckReturnValue @NonNull @SchedulerSupport(value="none") public static @NonNull Single<Boolean> sequenceEqual(@NonNull CompletableSource source1, @NonNull CompletableSource source2)
CompletableSource
s and emits true
via a Single
if both complete.
sequenceEqual
does not operate by default on a particular Scheduler
.source1
- the first CompletableSource
instancesource2
- the second CompletableSource
instanceSingle
instanceNullPointerException
- if source1
or source2
is null
@CheckReturnValue @NonNull @SchedulerSupport(value="none") public static @NonNull Completable unsafeCreate(@NonNull CompletableSource onSubscribe)
Completable
instance by wrapping the given source callback
without any safeguards; you should manage the lifecycle and response
to downstream disposal.
unsafeCreate
does not operate by default on a particular Scheduler
.onSubscribe
- the callback which will receive the CompletableObserver
instances
when the Completable
is subscribed to.Completable
instanceNullPointerException
- if onSubscribe
is null
IllegalArgumentException
- if source
is a Completable
@CheckReturnValue @NonNull @SchedulerSupport(value="none") public static @NonNull Completable defer(@NonNull Supplier<? extends CompletableSource> supplier)
Completable
instance returned by a supplier.
defer
does not operate by default on a particular Scheduler
.supplier
- the supplier that returns the Completable
that will be subscribed to.Completable
instanceNullPointerException
- if supplier
is null
@CheckReturnValue @NonNull @SchedulerSupport(value="none") public static @NonNull Completable error(@NonNull Supplier<? extends Throwable> supplier)
Completable
which calls the given error supplier for each subscriber
and emits its returned Throwable
.
If the errorSupplier
returns null
, the downstream CompletableObserver
s will receive a
NullPointerException
.
error
does not operate by default on a particular Scheduler
.supplier
- the error supplier, not null
Completable
instanceNullPointerException
- if supplier
is null
@CheckReturnValue @NonNull @SchedulerSupport(value="none") public static @NonNull Completable error(@NonNull Throwable throwable)
Completable
instance that emits the given Throwable
exception to subscribers.
error
does not operate by default on a particular Scheduler
.throwable
- the Throwable
instance to emit, not null
Completable
instanceNullPointerException
- if throwable
is null
@CheckReturnValue @NonNull @SchedulerSupport(value="none") public static @NonNull Completable fromAction(@NonNull Action action)
Completable
instance that runs the given Action
for each CompletableObserver
and
emits either an exception or simply completes.
fromAction
does not operate by default on a particular Scheduler
.Action
throws an exception, the respective Throwable
is
delivered to the downstream via CompletableObserver.onError(Throwable)
,
except when the downstream has disposed this Completable
source.
In this latter case, the Throwable
is delivered to the global error handler via
RxJavaPlugins.onError(Throwable)
as an UndeliverableException
.
action
- the Action
to run for each subscribing CompletableObserver
Completable
instanceNullPointerException
- if action
is null
@CheckReturnValue @NonNull @SchedulerSupport(value="none") public static @NonNull Completable fromCallable(@NonNull Callable<?> callable)
Completable
which when subscribed, executes the Callable
function, ignores its
normal result and emits onError
or onComplete
only.
fromCallable
does not operate by default on a particular Scheduler
.Callable
throws an exception, the respective Throwable
is
delivered to the downstream via CompletableObserver.onError(Throwable)
,
except when the downstream has disposed this Completable
source.
In this latter case, the Throwable
is delivered to the global error handler via
RxJavaPlugins.onError(Throwable)
as an UndeliverableException
.
callable
- the Callable
instance to execute for each subscribing CompletableObserver
Completable
instanceNullPointerException
- if callable
is null
defer(Supplier)
,
fromSupplier(Supplier)
@CheckReturnValue @NonNull @SchedulerSupport(value="none") public static @NonNull Completable fromFuture(@NonNull Future<?> future)
Completable
instance that reacts to the termination of the given Future
in a blocking fashion.
Note that disposing the Completable
won't cancel the Future
.
Use doOnDispose(Action)
and call Future.cancel(boolean)
in the
Action
.
fromFuture
does not operate by default on a particular Scheduler
.future
- the Future
to react toCompletable
instanceNullPointerException
- if future
is null
fromCompletionStage(CompletionStage)
@CheckReturnValue @NonNull @SchedulerSupport(value="none") public static <T> @NonNull Completable fromMaybe(@NonNull MaybeSource<T> maybe)
Completable
instance that when subscribed to, subscribes to the MaybeSource
instance and
emits an onComplete
event if the maybe emits onSuccess
/onComplete
or forwards any
onError
events.
fromMaybe
does not operate by default on a particular Scheduler
.History: 2.1.17 - beta
T
- the value type of the MaybeSource
elementmaybe
- the MaybeSource
instance to subscribe to, not null
Completable
instanceNullPointerException
- if maybe
is null
@CheckReturnValue @NonNull @SchedulerSupport(value="none") public static @NonNull Completable fromRunnable(@NonNull Runnable run)
Completable
instance that runs the given Runnable
for each CompletableObserver
and
emits either its unchecked exception or simply completes.
If the code to be wrapped needs to throw a checked or more broader Throwable
exception, that
exception has to be converted to an unchecked exception by the wrapped code itself. Alternatively,
use the fromAction(Action)
method which allows the wrapped code to throw any Throwable
exception and will signal it to observers as-is.
fromRunnable
does not operate by default on a particular Scheduler
.Runnable
throws an exception, the respective Throwable
is
delivered to the downstream via CompletableObserver.onError(Throwable)
,
except when the downstream has disposed this Completable
source.
In this latter case, the Throwable
is delivered to the global error handler via
RxJavaPlugins.onError(Throwable)
as an UndeliverableException
.
run
- the Runnable
to run for each CompletableObserver
Completable
instanceNullPointerException
- if run
is null
fromAction(Action)
@CheckReturnValue @NonNull @SchedulerSupport(value="none") public static <T> @NonNull Completable fromObservable(@NonNull ObservableSource<T> observable)
Completable
instance that subscribes to the given ObservableSource
, ignores all values and
emits only the terminal event.
fromObservable
does not operate by default on a particular Scheduler
.T
- the type of the ObservableSource
observable
- the ObservableSource
instance to subscribe to, not null
Completable
instanceNullPointerException
- if observable
is null
@CheckReturnValue @NonNull @BackpressureSupport(value=UNBOUNDED_IN) @SchedulerSupport(value="none") public static <T> @NonNull Completable fromPublisher(@NonNull Publisher<T> publisher)
Completable
instance that subscribes to the given Publisher
, ignores all values and
emits only the terminal event.
The Publisher
must follow the
Reactive-Streams specification.
Violating the specification may result in undefined behavior.
If possible, use create(CompletableOnSubscribe)
to create a
source-like Completable
instead.
Note that even though Publisher
appears to be a functional interface, it
is not recommended to implement it through a lambda as the specification requires
state management that is not achievable with a stateless lambda.
Completable
honors the backpressure of the downstream consumer
and expects the other Publisher
to honor it as well.fromPublisher
does not operate by default on a particular Scheduler
.T
- the type of the Publisher
publisher
- the Publisher
instance to subscribe to, not null
Completable
instanceNullPointerException
- if publisher
is null
create(CompletableOnSubscribe)
@CheckReturnValue @NonNull @SchedulerSupport(value="none") public static <T> @NonNull Completable fromSingle(@NonNull SingleSource<T> single)
Completable
instance that when subscribed to, subscribes to the SingleSource
instance and
emits a completion event if the single emits onSuccess
or forwards any onError
events.
fromSingle
does not operate by default on a particular Scheduler
.T
- the value type of the SingleSource
single
- the SingleSource
instance to subscribe to, not null
Completable
instanceNullPointerException
- if single
is null
@CheckReturnValue @NonNull @SchedulerSupport(value="none") public static @NonNull Completable fromSupplier(@NonNull Supplier<?> supplier)
Completable
which when subscribed, executes the Supplier
function, ignores its
normal result and emits onError
or onComplete
only.
fromSupplier
does not operate by default on a particular Scheduler
.Supplier
throws an exception, the respective Throwable
is
delivered to the downstream via CompletableObserver.onError(Throwable)
,
except when the downstream has disposed this Completable
source.
In this latter case, the Throwable
is delivered to the global error handler via
RxJavaPlugins.onError(Throwable)
as an UndeliverableException
.
supplier
- the Supplier
instance to execute for each CompletableObserver
Completable
instanceNullPointerException
- if supplier
is null
defer(Supplier)
,
fromCallable(Callable)
@CheckReturnValue @NonNull @SchedulerSupport(value="none") @SafeVarargs public static @NonNull Completable mergeArray(@NonNull CompletableSource... sources)
Completable
instance that subscribes to all sources at once and
completes only when all source CompletableSource
s complete or one of them emits an error.
mergeArray
does not operate by default on a particular Scheduler
.CompletableSource
s signal a Throwable
via onError
, the resulting
Completable
terminates with that Throwable
and all other source CompletableSource
s are disposed.
If more than one CompletableSource
signals an error, the resulting Completable
may terminate with the
first one's error or, depending on the concurrency of the sources, may terminate with a
CompositeException
containing two or more of the various error signals.
Throwable
s that didn't make into the composite will be sent (individually) to the global error handler via
RxJavaPlugins.onError(Throwable)
method as UndeliverableException
errors. Similarly, Throwable
s
signaled by source(s) after the returned Completable
has been disposed or terminated with a
(composite) error will be sent to the same global error handler.
Use mergeArrayDelayError(CompletableSource...)
to merge sources and terminate only when all source CompletableSource
s
have completed or failed with an error.
sources
- the array of CompletableSource
s.Completable
instanceNullPointerException
- if sources
is null
mergeArrayDelayError(CompletableSource...)
@CheckReturnValue @NonNull @SchedulerSupport(value="none") public static @NonNull Completable merge(@NonNull Iterable<? extends CompletableSource> sources)
Completable
instance that subscribes to all sources at once and
completes only when all source CompletableSource
s complete or one of them emits an error.
merge
does not operate by default on a particular Scheduler
.CompletableSource
s signal a Throwable
via onError
, the resulting
Completable
terminates with that Throwable
and all other source CompletableSource
s are disposed.
If more than one CompletableSource
signals an error, the resulting Completable
may terminate with the
first one's error or, depending on the concurrency of the sources, may terminate with a
CompositeException
containing two or more of the various error signals.
Throwable
s that didn't make into the composite will be sent (individually) to the global error handler via
RxJavaPlugins.onError(Throwable)
method as UndeliverableException
errors. Similarly, Throwable
s
signaled by source(s) after the returned Completable
has been disposed or terminated with a
(composite) error will be sent to the same global error handler.
Use mergeDelayError(Iterable)
to merge sources and terminate only when all source CompletableSource
s
have completed or failed with an error.
sources
- the Iterable
sequence of CompletableSource
s.Completable
instanceNullPointerException
- if sources
is null
mergeDelayError(Iterable)
@CheckReturnValue @SchedulerSupport(value="none") @BackpressureSupport(value=UNBOUNDED_IN) @NonNull public static @NonNull Completable merge(@NonNull Publisher<? extends CompletableSource> sources)
Completable
instance that subscribes to all sources at once and
completes only when all source CompletableSource
s complete or one of them emits an error.
Publisher
in an unbounded manner
(requesting Long.MAX_VALUE
upfront).merge
does not operate by default on a particular Scheduler
.CompletableSource
s signal a Throwable
via onError
, the resulting
Completable
terminates with that Throwable
and all other source CompletableSource
s are disposed.
If more than one CompletableSource
signals an error, the resulting Completable
may terminate with the
first one's error or, depending on the concurrency of the sources, may terminate with a
CompositeException
containing two or more of the various error signals.
Throwable
s that didn't make into the composite will be sent (individually) to the global error handler via
RxJavaPlugins.onError(Throwable)
method as UndeliverableException
errors. Similarly, Throwable
s
signaled by source(s) after the returned Completable
has been disposed or terminated with a
(composite) error will be sent to the same global error handler.
Use mergeDelayError(Publisher)
to merge sources and terminate only when all source CompletableSource
s
have completed or failed with an error.
sources
- the Publisher
sequence of CompletableSource
s.Completable
instanceNullPointerException
- if sources
is null
mergeDelayError(Publisher)
@CheckReturnValue @SchedulerSupport(value="none") @BackpressureSupport(value=FULL) @NonNull public static @NonNull Completable merge(@NonNull Publisher<? extends CompletableSource> sources, int maxConcurrency)
Completable
instance that keeps subscriptions to a limited number of sources at once and
completes only when all source CompletableSource
s complete or one of them emits an error.
Publisher
in a bounded manner,
requesting maxConcurrency
items first, then keeps requesting as
many more as the inner CompletableSource
s terminate.merge
does not operate by default on a particular Scheduler
.CompletableSource
s signal a Throwable
via onError
, the resulting
Completable
terminates with that Throwable
and all other source CompletableSource
s are disposed.
If more than one CompletableSource
signals an error, the resulting Completable
may terminate with the
first one's error or, depending on the concurrency of the sources, may terminate with a
CompositeException
containing two or more of the various error signals.
Throwable
s that didn't make into the composite will be sent (individually) to the global error handler via
RxJavaPlugins.onError(Throwable)
method as UndeliverableException
errors. Similarly, Throwable
s
signaled by source(s) after the returned Completable
has been disposed or terminated with a
(composite) error will be sent to the same global error handler.
Use mergeDelayError(Publisher, int)
to merge sources and terminate only when all source CompletableSource
s
have completed or failed with an error.
sources
- the Publisher
sequence of CompletableSource
s.maxConcurrency
- the maximum number of concurrent subscriptionsCompletable
instanceNullPointerException
- if sources
is null
IllegalArgumentException
- if maxConcurrency
is less than 1mergeDelayError(Publisher, int)
@CheckReturnValue @NonNull @SchedulerSupport(value="none") @SafeVarargs public static @NonNull Completable mergeArrayDelayError(@NonNull CompletableSource... sources)
Completable
that subscribes to all CompletableSource
s in the source array and delays
any error emitted by any of the inner CompletableSource
s until all of
them terminate in a way or another.
mergeArrayDelayError
does not operate by default on a particular Scheduler
.sources
- the array of CompletableSource
sCompletable
instanceNullPointerException
- if sources
is null
@CheckReturnValue @NonNull @SchedulerSupport(value="none") public static @NonNull Completable mergeDelayError(@NonNull Iterable<? extends CompletableSource> sources)
Completable
that subscribes to all CompletableSource
s in the source sequence and delays
any error emitted by any of the inner CompletableSource
s until all of
them terminate in a way or another.
mergeDelayError
does not operate by default on a particular Scheduler
.sources
- the sequence of CompletableSource
sCompletable
instanceNullPointerException
- if sources
is null
@CheckReturnValue @SchedulerSupport(value="none") @BackpressureSupport(value=UNBOUNDED_IN) @NonNull public static @NonNull Completable mergeDelayError(@NonNull Publisher<? extends CompletableSource> sources)
Completable
that subscribes to all CompletableSource
s in the source sequence and delays
any error emitted by either the sources Publisher
or any of the inner CompletableSource
s until all of
them terminate in a way or another.
Publisher
in an unbounded manner
(requesting Long.MAX_VALUE
from it).mergeDelayError
does not operate by default on a particular Scheduler
.sources
- the sequence of CompletableSource
sCompletable
instanceNullPointerException
- if sources
is null
@CheckReturnValue @SchedulerSupport(value="none") @BackpressureSupport(value=FULL) @NonNull public static @NonNull Completable mergeDelayError(@NonNull Publisher<? extends CompletableSource> sources, int maxConcurrency)
Completable
that subscribes to a limited number of inner CompletableSource
s at once in
the source sequence and delays any error emitted by either the sources
Publisher
or any of the inner CompletableSource
s until all of
them terminate in a way or another.
maxConcurrency
items from the Publisher
upfront and keeps requesting as many more as many inner CompletableSource
s terminate.mergeDelayError
does not operate by default on a particular Scheduler
.sources
- the sequence of CompletableSource
smaxConcurrency
- the maximum number of concurrent subscriptions to have
at a time to the inner CompletableSource
sCompletable
instanceNullPointerException
- if sources
is null
IllegalArgumentException
- if maxConcurrency
is non-positive@CheckReturnValue @SchedulerSupport(value="none") @NonNull public static @NonNull Completable never()
Completable
that never calls onError
or onComplete
.
never
does not operate by default on a particular Scheduler
.onError
or onComplete
@CheckReturnValue @SchedulerSupport(value="io.reactivex:computation") @NonNull public static @NonNull Completable timer(long delay, @NonNull TimeUnit unit)
Completable
instance that fires its onComplete
event after the given delay elapsed.
timer
does operate by default on the computation
Scheduler
.delay
- the delay timeunit
- the delay unitCompletable
instanceNullPointerException
- if unit
is null
@CheckReturnValue @NonNull @SchedulerSupport(value="custom") public static @NonNull Completable timer(long delay, @NonNull TimeUnit unit, @NonNull Scheduler scheduler)
Completable
instance that fires its onComplete
event after the given delay elapsed
by using the supplied Scheduler
.
timer
operates on the Scheduler
you specify.delay
- the delay timeunit
- the delay unitscheduler
- the Scheduler
where to emit the onComplete
eventCompletable
instanceNullPointerException
- if unit
or scheduler
is null
@CheckReturnValue @NonNull @SchedulerSupport(value="none") @BackpressureSupport(value=UNBOUNDED_IN) public static @NonNull Completable switchOnNext(@NonNull Publisher<? extends CompletableSource> sources)
CompletableSource
s emitted by the source Publisher
whenever
a new CompletableSource
is emitted, disposing the previously running CompletableSource
,
exposing the setup as a Completable
sequence.
sources
Publisher
is consumed in an unbounded manner (requesting Long.MAX_VALUE
).switchOnNext
does not operate by default on a particular Scheduler
.sources
Publisher
or the currently running CompletableSource
, disposing the rest. Late errors are
forwarded to the global error handler via RxJavaPlugins.onError(Throwable)
.sources
- the Publisher
sequence of inner CompletableSource
s to switch betweenCompletable
instanceNullPointerException
- if sources
is null
switchOnNextDelayError(Publisher)
,
ReactiveX operators documentation: Switch@CheckReturnValue @NonNull @SchedulerSupport(value="none") @BackpressureSupport(value=UNBOUNDED_IN) public static @NonNull Completable switchOnNextDelayError(@NonNull Publisher<? extends CompletableSource> sources)
CompletableSource
s emitted by the source Publisher
whenever
a new CompletableSource
is emitted, disposing the previously running CompletableSource
,
exposing the setup as a Completable
sequence and delaying all errors from
all of them until all terminate.
sources
Publisher
is consumed in an unbounded manner (requesting Long.MAX_VALUE
).switchOnNextDelayError
does not operate by default on a particular Scheduler
.Completable
collects all errors emitted by either the sources
Publisher
or any inner CompletableSource
and emits them as a CompositeException
when all sources terminate. If only one source ever failed, its error is emitted as-is at the end.sources
- the Publisher
sequence of inner CompletableSource
s to switch betweenCompletable
instanceNullPointerException
- if sources
is null
switchOnNext(Publisher)
,
ReactiveX operators documentation: Switch@CheckReturnValue @SchedulerSupport(value="none") @NonNull public static <R> @NonNull Completable using(@NonNull Supplier<R> resourceSupplier, @NonNull Function<? super R,? extends CompletableSource> sourceSupplier, @NonNull Consumer<? super R> resourceCleanup)
Completable
instance which manages a resource along
with a custom CompletableSource
instance while the subscription is active.
This overload disposes eagerly before the terminal event is emitted.
using
does not operate by default on a particular Scheduler
.R
- the resource typeresourceSupplier
- the Supplier
that returns a resource to be managed.sourceSupplier
- the Function
that given a resource returns a CompletableSource
instance that will be subscribed toresourceCleanup
- the Consumer
that disposes the resource created by the resource supplierCompletable
instanceNullPointerException
- if resourceSupplier
, sourceSupplier
or resourceCleanup
is null
@CheckReturnValue @NonNull @SchedulerSupport(value="none") public static <R> @NonNull Completable using(@NonNull Supplier<R> resourceSupplier, @NonNull Function<? super R,? extends CompletableSource> sourceSupplier, @NonNull Consumer<? super R> resourceCleanup, boolean eager)
Completable
instance which manages a resource along
with a custom CompletableSource
instance while the subscription is active and performs eager or lazy
resource disposition.
If this overload performs a lazy disposal after the terminal event is emitted.
The exceptions thrown at this time will be delivered to the global RxJavaPlugins.onError(Throwable)
handler only.
using
does not operate by default on a particular Scheduler
.R
- the resource typeresourceSupplier
- the Supplier
that returns a resource to be managedsourceSupplier
- the Function
that given a resource returns a non-null
CompletableSource
instance that will be subscribed toresourceCleanup
- the Consumer
that disposes the resource created by the resource suppliereager
- If true
then resource disposal will happen either on a dispose()
call before the upstream is disposed
or just before the emission of a terminal event (onComplete
or onError
).
If false
the resource disposal will happen either on a dispose()
call after the upstream is disposed
or just after the emission of a terminal event (onComplete
or onError
).Completable
instanceNullPointerException
- if resourceSupplier
, sourceSupplier
or resourceCleanup
is null
@CheckReturnValue @NonNull @SchedulerSupport(value="none") public static @NonNull Completable wrap(@NonNull CompletableSource source)
CompletableSource
into a Completable
if not already Completable
.
wrap
does not operate by default on a particular Scheduler
.source
- the source to wrapCompletable
instanceNullPointerException
- if source
is null
@CheckReturnValue @NonNull @SchedulerSupport(value="none") public final @NonNull Completable ambWith(@NonNull CompletableSource other)
Completable
that emits the a terminated event of either this Completable
or the other CompletableSource
, whichever fires first.
ambWith
does not operate by default on a particular Scheduler
.other
- the other CompletableSource
, not null
. A subscription to this provided source will occur after subscribing
to the current source.Completable
instanceNullPointerException
- if other
is null
@CheckReturnValue @NonNull @SchedulerSupport(value="none") public final <T> @NonNull Observable<T> andThen(@NonNull ObservableSource<T> next)
Observable
which will subscribe to this Completable
and once that is completed then
will subscribe to the next
ObservableSource
. An error event from this Completable
will be
propagated to the downstream observer and will result in skipping the subscription to the
next ObservableSource
.
andThen
does not operate by default on a particular Scheduler
.T
- the value type of the next ObservableSource
next
- the ObservableSource
to subscribe after this Completable
is completed, not null
Observable
that composes this Completable
and the next ObservableSource
NullPointerException
- if next
is null
@CheckReturnValue @NonNull @BackpressureSupport(value=FULL) @SchedulerSupport(value="none") public final <T> @NonNull Flowable<T> andThen(@NonNull Publisher<T> next)
Flowable
which will subscribe to this Completable
and once that is completed then
will subscribe to the next
Publisher
. An error event from this Completable
will be
propagated to the downstream subscriber and will result in skipping the subscription to the next
Publisher
.
Flowable
honors the backpressure of the downstream consumer
and expects the other Publisher
to honor it as well.andThen
does not operate by default on a particular Scheduler
.T
- the value type of the next Publisher
next
- the Publisher
to subscribe after this Completable
is completed, not null
Flowable
that composes this Completable
and the next Publisher
NullPointerException
- if next
is null
@CheckReturnValue @NonNull @SchedulerSupport(value="none") public final <T> @NonNull Single<T> andThen(@NonNull SingleSource<T> next)
Single
which will subscribe to this Completable
and once that is completed then
will subscribe to the next
SingleSource
. An error event from this Completable
will be
propagated to the downstream observer and will result in skipping the subscription to the next
SingleSource
.
andThen
does not operate by default on a particular Scheduler
.T
- the value type of the next SingleSource
next
- the SingleSource
to subscribe after this Completable
is completed, not null
Single
that composes this Completable
and the next SingleSource
NullPointerException
- if next
is null
@CheckReturnValue @NonNull @SchedulerSupport(value="none") public final <T> @NonNull Maybe<T> andThen(@NonNull MaybeSource<T> next)
Maybe
which will subscribe to this Completable
and once that is completed then
will subscribe to the next
MaybeSource
. An error event from this Completable
will be
propagated to the downstream observer and will result in skipping the subscription to the next
MaybeSource
.
andThen
does not operate by default on a particular Scheduler
.T
- the value type of the next MaybeSource
next
- the MaybeSource
to subscribe after this Completable
is completed, not null
Maybe
that composes this Completable
and the next MaybeSource
NullPointerException
- if next
is null
@CheckReturnValue @SchedulerSupport(value="none") @NonNull public final @NonNull Completable andThen(@NonNull CompletableSource next)
Completable
that first runs this Completable
and then the other CompletableSource
. An error event from this Completable
will be
propagated to the downstream observer and will result in skipping the subscription to the next
CompletableSource
.
This is an alias for concatWith(CompletableSource)
.
andThen
does not operate by default on a particular Scheduler
.next
- the other CompletableSource
, not null
Completable
instanceNullPointerException
- if next
is null
@SchedulerSupport(value="none") public final void blockingAwait()
Completable
instance in a blocking manner and
rethrows any exception emitted.
blockingAwait
does not operate by default on a particular Scheduler
.Exception
into RuntimeException
and throws that. Otherwise, RuntimeException
s and
Error
s are rethrown as they are.RuntimeException
- wrapping an InterruptedException
if the current thread is interrupted@CheckReturnValue @SchedulerSupport(value="none") public final boolean blockingAwait(long timeout, @NonNull TimeUnit unit)
Completable
instance in a blocking manner
with a specific timeout and rethrows any exception emitted within the timeout window.
blockingAwait
does not operate by default on a particular Scheduler
.Exception
into RuntimeException
and throws that. Otherwise, RuntimeException
s and
Error
s are rethrown as they are.timeout
- the timeout valueunit
- the timeout unittrue
if the this Completable
instance completed normally within the time limit,
false
if the timeout elapsed before this Completable
terminated.RuntimeException
- wrapping an InterruptedException
if the current thread is interruptedNullPointerException
- if unit
is null
@SchedulerSupport(value="none") public final void blockingSubscribe()
Completable
and blocks the current thread until it terminates.
blockingSubscribe
does not operate by default on a particular Scheduler
.Completable
signals an error,
the Throwable
is routed to the global error handler via RxJavaPlugins.onError(Throwable)
.
If the current thread is interrupted, an InterruptedException
is routed to the same global error handler.
blockingSubscribe(Action)
,
blockingSubscribe(Action, Consumer)
@SchedulerSupport(value="none") public final void blockingSubscribe(@NonNull Action onComplete)
Completable
and calls given onComplete
callback on the current thread
when it completes normally.
blockingSubscribe
does not operate by default on a particular Scheduler
.Completable
signals an error or onComplete
throws,
the respective Throwable
is routed to the global error handler via RxJavaPlugins.onError(Throwable)
.
If the current thread is interrupted, an InterruptedException
is routed to the same global error handler.
onComplete
- the Action
to call if the current Completable
completes normallyNullPointerException
- if onComplete
is null
blockingSubscribe(Action, Consumer)
@SchedulerSupport(value="none") public final void blockingSubscribe(@NonNull Action onComplete, @NonNull Consumer<? super Throwable> onError)
Completable
and calls the appropriate callback on the current thread
when it terminates.
blockingSubscribe
does not operate by default on a particular Scheduler
.onComplete
or onError
throw, the Throwable
is routed to the
global error handler via RxJavaPlugins.onError(Throwable)
.
If the current thread is interrupted, the onError
consumer is called with an InterruptedException
.
onComplete
- the Action
to call if the current Completable
completes normallyonError
- the Consumer
to call if the current Completable
signals an errorNullPointerException
- if onComplete
or onError
is null
@SchedulerSupport(value="none") public final void blockingSubscribe(@NonNull CompletableObserver observer)
Completable
and calls the appropriate CompletableObserver
method on the current thread.
blockingSubscribe
does not operate by default on a particular Scheduler
.onError
signal is delivered to the CompletableObserver.onError(Throwable)
method.
If any of the CompletableObserver
's methods throw, the RuntimeException
is propagated to the caller of this method.
If the current thread is interrupted, an InterruptedException
is delivered to observer.onError
.
observer
- the CompletableObserver
to call methods on the current threadNullPointerException
- if observer
is null
@CheckReturnValue @SchedulerSupport(value="none") @NonNull public final @NonNull Completable cache()
Completable
only once, when the first CompletableObserver
subscribes to the result Completable
, caches its terminal event
and relays/replays it to observers.
Note that this operator doesn't allow disposing the connection of the upstream source.
cache
does not operate by default on a particular Scheduler
.History: 2.0.4 - experimental
Completable
instance@CheckReturnValue @SchedulerSupport(value="none") @NonNull public final @NonNull Completable compose(@NonNull CompletableTransformer transformer)
CompletableSource
wrapped with wrap(CompletableSource)
.
compose
does not operate by default on a particular Scheduler
.transformer
- the transformer function, not null
Completable
instanceNullPointerException
- if transformer
is null
@CheckReturnValue @NonNull @SchedulerSupport(value="none") public final @NonNull Completable concatWith(@NonNull CompletableSource other)
Completable
with another CompletableSource
.
An error event from this Completable
will be
propagated to the downstream observer and will result in skipping the subscription to the next
CompletableSource
.
concatWith
does not operate by default on a particular Scheduler
.other
- the other CompletableSource
, not null
Completable
which subscribes to this and then the other CompletableSource
NullPointerException
- if other
is null
andThen(CompletableSource)
,
andThen(MaybeSource)
,
andThen(ObservableSource)
,
andThen(SingleSource)
,
andThen(Publisher)
@CheckReturnValue @SchedulerSupport(value="io.reactivex:computation") @NonNull public final @NonNull Completable delay(long time, @NonNull TimeUnit unit)
Completable
which delays the emission of the completion event by the given time.
delay
does operate by default on the computation
Scheduler
.time
- the delay timeunit
- the delay unitCompletable
instanceNullPointerException
- if unit
is null
@CheckReturnValue @SchedulerSupport(value="custom") @NonNull public final @NonNull Completable delay(long time, @NonNull TimeUnit unit, @NonNull Scheduler scheduler)
Completable
which delays the emission of the completion event by the given time while
running on the specified Scheduler
.
delay
operates on the Scheduler
you specify.time
- the delay timeunit
- the delay unitscheduler
- the Scheduler
to run the delayed completion onCompletable
instanceNullPointerException
- if unit
or scheduler
is null
@CheckReturnValue @NonNull @SchedulerSupport(value="custom") public final @NonNull Completable delay(long time, @NonNull TimeUnit unit, @NonNull Scheduler scheduler, boolean delayError)
Completable
which delays the emission of the completion event, and optionally the error as well, by the given time while
running on the specified Scheduler
.
delay
operates on the Scheduler
you specify.time
- the delay timeunit
- the delay unitscheduler
- the Scheduler
to run the delayed completion ondelayError
- delay the error emission as well?Completable
instanceNullPointerException
- if unit
or scheduler
is null
@CheckReturnValue @SchedulerSupport(value="io.reactivex:computation") @NonNull public final @NonNull Completable delaySubscription(long time, @NonNull TimeUnit unit)
Completable
that delays the subscription to the upstream by a given amount of time.
delaySubscription
operates by default on the computation
Scheduler
.History: 2.2.3 - experimental
time
- the time to delay the subscriptionunit
- the time unit of delay
Completable
instanceNullPointerException
- if unit
is null
@CheckReturnValue @SchedulerSupport(value="custom") @NonNull public final @NonNull Completable delaySubscription(long time, @NonNull TimeUnit unit, @NonNull Scheduler scheduler)
Completable
that delays the subscription to the upstream by a given amount of time,
both waiting and subscribing on a given Scheduler
.
Scheduler
this operator will use.History: 2.2.3 - experimental
time
- the time to delay the subscriptionunit
- the time unit of delay
scheduler
- the Scheduler
on which the waiting and subscription will happenCompletable
instanceNullPointerException
- if unit
or scheduler
is null
@CheckReturnValue @SchedulerSupport(value="none") @NonNull public final @NonNull Completable doOnComplete(@NonNull Action onComplete)
Completable
which calls the given onComplete
Action
if this Completable
completes.
doOnComplete
does not operate by default on a particular Scheduler
.onComplete
- the Action
to call when this emits an onComplete
eventCompletable
instanceNullPointerException
- if onComplete
is null
doFinally(Action)
@CheckReturnValue @SchedulerSupport(value="none") @NonNull public final @NonNull Completable doOnDispose(@NonNull Action onDispose)
Action
if a CompletableObserver
subscribed to the current
Completable
disposes the common Disposable
it received via onSubscribe
.
doOnDispose
does not operate by default on a particular Scheduler
.onDispose
- the Action
to call when the downstream observer disposes the subscriptionCompletable
instanceNullPointerException
- if onDispose
is null
@CheckReturnValue @SchedulerSupport(value="none") @NonNull public final @NonNull Completable doOnError(@NonNull Consumer<? super Throwable> onError)
Completable
which calls the given onError
Consumer
if this Completable
emits an error.
doOnError
does not operate by default on a particular Scheduler
.onError
- the error Consumer
receiving the upstream Throwable
if the upstream signals it via onError
Completable
instanceNullPointerException
- if onError
is null
doFinally(Action)
@CheckReturnValue @NonNull @SchedulerSupport(value="none") public final @NonNull Completable doOnEvent(@NonNull Consumer<? super Throwable> onEvent)
Completable
which calls the given onEvent
Consumer
with the Throwable
for an onError
or null
for an onComplete
signal from this Completable
before delivering the signal to the downstream.
doOnEvent
does not operate by default on a particular Scheduler
.onEvent
- the event Consumer
that receives null
for upstream
completion or a Throwable
if the upstream signaled an errorCompletable
instanceNullPointerException
- if onEvent
is null
@CheckReturnValue @SchedulerSupport(value="none") @NonNull public final @NonNull Completable doOnLifecycle(@NonNull Consumer<? super Disposable> onSubscribe, @NonNull Action onDispose)
onXXX
method (shared between all CompletableObserver
s) for the lifecycle events of
the sequence (subscription, disposal).
doOnLifecycle
does not operate by default on a particular Scheduler
.onSubscribe
- a Consumer
called with the Disposable
sent via CompletableObserver.onSubscribe(Disposable)
onDispose
- called when the downstream disposes the Disposable
via dispose()
Completable
instanceNullPointerException
- if onSubscribe
or onDispose
is null
@CheckReturnValue @SchedulerSupport(value="none") @NonNull public final @NonNull Completable doOnSubscribe(@NonNull Consumer<? super Disposable> onSubscribe)
Completable
instance that calls the given onSubscribe
callback with the disposable
that the downstream CompletableObserver
s receive upon subscription.
doOnSubscribe
does not operate by default on a particular Scheduler
.onSubscribe
- the Consumer
called when a downstream CompletableObserver
subscribesCompletable
instanceNullPointerException
- if onSubscribe
is null
@CheckReturnValue @SchedulerSupport(value="none") @NonNull public final @NonNull Completable doOnTerminate(@NonNull Action onTerminate)
Completable
instance that calls the given onTerminate
Action
just before this Completable
completes normally or with an exception.
doOnTerminate
does not operate by default on a particular Scheduler
.onTerminate
- the Action
to call just before this Completable
terminatesCompletable
instanceNullPointerException
- if onTerminate
is null
doFinally(Action)
@CheckReturnValue @SchedulerSupport(value="none") @NonNull public final @NonNull Completable doAfterTerminate(@NonNull Action onAfterTerminate)
Completable
instance that calls the given onAfterTerminate
Action
after this Completable
completes normally or with an exception.
doAfterTerminate
does not operate by default on a particular Scheduler
.onAfterTerminate
- the Action
to call after this Completable
terminatesCompletable
instanceNullPointerException
- if onAfterTerminate
is null
doFinally(Action)
@CheckReturnValue @NonNull @SchedulerSupport(value="none") public final @NonNull Completable doFinally(@NonNull Action onFinally)
Action
after this Completable
signals onError
or onComplete
or gets disposed by
the downstream.
In case of a race between a terminal event and a dispose call, the provided onFinally
action
is executed once per subscription.
Note that the onFinally
action is shared between subscriptions and as such
should be thread-safe.
doFinally
does not operate by default on a particular Scheduler
.History: 2.0.1 - experimental
onFinally
- the Action
called when this Completable
terminates or gets disposedCompletable
instanceNullPointerException
- if onFinally
is null
@CheckReturnValue @NonNull @SchedulerSupport(value="none") public final @NonNull Completable lift(@NonNull CompletableOperator onLift)
Completable
which, when subscribed to, invokes the apply(CompletableObserver)
method
of the provided CompletableOperator
for each individual downstream Completable
and allows the
insertion of a custom operator by accessing the downstream's CompletableObserver
during this subscription phase
and providing a new CompletableObserver
, containing the custom operator's intended business logic, that will be
used in the subscription process going further upstream.
Generally, such a new CompletableObserver
will wrap the downstream's CompletableObserver
and forwards the
onError
and onComplete
events from the upstream directly or according to the
emission pattern the custom operator's business logic requires. In addition, such operator can intercept the
flow control calls of dispose
and isDisposed
that would have traveled upstream and perform
additional actions depending on the same business logic requirements.
Example:
// Step 1: Create the consumer type that will be returned by the CompletableOperator.apply():
public final class CustomCompletableObserver implements CompletableObserver, Disposable {
// The downstream's CompletableObserver that will receive the onXXX events
final CompletableObserver downstream;
// The connection to the upstream source that will call this class' onXXX methods
Disposable upstream;
// The constructor takes the downstream subscriber and usually any other parameters
public CustomCompletableObserver(CompletableObserver downstream) {
this.downstream = downstream;
}
// In the subscription phase, the upstream sends a Disposable to this class
// and subsequently this class has to send a Disposable to the downstream.
// Note that relaying the upstream's Disposable directly is not allowed in RxJava
@Override
public void onSubscribe(Disposable d) {
if (upstream != null) {
d.dispose();
} else {
upstream = d;
downstream.onSubscribe(this);
}
}
// Some operators may handle the upstream's error while others
// could just forward it to the downstream.
@Override
public void onError(Throwable throwable) {
downstream.onError(throwable);
}
// When the upstream completes, usually the downstream should complete as well.
// In completable, this could also mean doing some side-effects
@Override
public void onComplete() {
System.out.println("Sequence completed");
downstream.onComplete();
}
// Some operators may use their own resources which should be cleaned up if
// the downstream disposes the flow before it completed. Operators without
// resources can simply forward the dispose to the upstream.
// In some cases, a disposed flag may be set by this method so that other parts
// of this class may detect the dispose and stop sending events
// to the downstream.
@Override
public void dispose() {
upstream.dispose();
}
// Some operators may simply forward the call to the upstream while others
// can return the disposed flag set in dispose().
@Override
public boolean isDisposed() {
return upstream.isDisposed();
}
}
// Step 2: Create a class that implements the CompletableOperator interface and
// returns the custom consumer type from above in its apply() method.
// Such class may define additional parameters to be submitted to
// the custom consumer type.
final class CustomCompletableOperator implements CompletableOperator {
@Override
public CompletableObserver apply(CompletableObserver upstream) {
return new CustomCompletableObserver(upstream);
}
}
// Step 3: Apply the custom operator via lift() in a flow by creating an instance of it
// or reusing an existing one.
Completable.complete()
.lift(new CustomCompletableOperator())
.test()
.assertResult();
Creating custom operators can be complicated and it is recommended one consults the RxJava wiki: Writing operators page about the tools, requirements, rules, considerations and pitfalls of implementing them.
Note that implementing custom operators via this lift()
method adds slightly more overhead by requiring
an additional allocation and indirection per assembled flows. Instead, extending the abstract Completable
class and creating a CompletableTransformer
with it is recommended.
Note also that it is not possible to stop the subscription phase in lift()
as the apply()
method
requires a non-null
CompletableObserver
instance to be returned, which is then unconditionally subscribed to
the current Completable
. For example, if the operator decided there is no reason to subscribe to the
upstream source because of some optimization possibility or a failure to prepare the operator, it still has to
return a CompletableObserver
that should immediately dispose the upstream's Disposable
in its
onSubscribe
method. Again, using a CompletableTransformer
and extending the Completable
is
a better option as subscribeActual(io.reactivex.rxjava3.core.CompletableObserver)
can decide to not subscribe to its upstream after all.
lift
does not operate by default on a particular Scheduler
, however, the
CompletableOperator
may use a Scheduler
to support its own asynchronous behavior.onLift
- the CompletableOperator
that receives the downstream's CompletableObserver
and should return
a CompletableObserver
with custom behavior to be used as the consumer for the current
Completable
.Completable
instanceNullPointerException
- if onLift
is null
compose(CompletableTransformer)
@CheckReturnValue @SchedulerSupport(value="none") @NonNull public final <T> @NonNull Single<Notification<T>> materialize()
Completable
into a Notification
of the same kind
and emits it as a single success value to downstream.
materialize
does not operate by default on a particular Scheduler
.History: 2.2.4 - experimental
T
- the intended target element type of the Notification
Single
instanceSingle.dematerialize(Function)
@CheckReturnValue @NonNull @SchedulerSupport(value="none") public final @NonNull Completable mergeWith(@NonNull CompletableSource other)
Completable
which subscribes to this and the other CompletableSource
and completes
when both of them complete or one emits an error.
mergeWith
does not operate by default on a particular Scheduler
.other
- the other CompletableSource
instanceCompletable
instanceNullPointerException
- if other
is null
@CheckReturnValue @NonNull @SchedulerSupport(value="custom") public final @NonNull Completable observeOn(@NonNull Scheduler scheduler)
Completable
which emits the terminal events from the thread of the specified Scheduler
.
observeOn
operates on a Scheduler
you specify.scheduler
- the Scheduler
to emit terminal events onCompletable
instanceNullPointerException
- if scheduler
is null
@CheckReturnValue @SchedulerSupport(value="none") @NonNull public final @NonNull Completable onErrorComplete()
Completable
instance that if this Completable
emits an error, it will emit an onComplete
and swallow the upstream Throwable
.
onErrorComplete
does not operate by default on a particular Scheduler
.Completable
instance@CheckReturnValue @NonNull @SchedulerSupport(value="none") public final @NonNull Completable onErrorComplete(@NonNull Predicate<? super Throwable> predicate)
Completable
instance that if this Completable
emits an error and the Predicate
returns
true
, it will emit an onComplete
and swallow the Throwable
.
onErrorComplete
does not operate by default on a particular Scheduler
.predicate
- the Predicate
to call when a Throwable
is emitted which should return true
if the Throwable
should be swallowed and replaced with an onComplete
.Completable
instanceNullPointerException
- if predicate
is null
@CheckReturnValue @NonNull @SchedulerSupport(value="none") public final @NonNull Completable onErrorResumeNext(@NonNull Function<? super Throwable,? extends CompletableSource> fallbackSupplier)
Completable
instance that when encounters an error from this Completable
, calls the
specified mapper
Function
that returns a CompletableSource
instance for it and resumes the
execution with it.
onErrorResumeNext
does not operate by default on a particular Scheduler
.fallbackSupplier
- the mapper
Function
that takes the error and should return a CompletableSource
as
continuation.Completable
instanceNullPointerException
- if fallbackSupplier
is null
@CheckReturnValue @NonNull @SchedulerSupport(value="none") public final @NonNull Completable onErrorResumeWith(@NonNull CompletableSource fallback)
CompletableSource
when the current Completable
fails instead of
signaling the error via onError
.
You can use this to prevent errors from propagating or to supply fallback data should errors be encountered.
onErrorResumeWith
does not operate by default on a particular Scheduler
.fallback
- the next CompletableSource
that will take over if the current Completable
encounters
an errorCompletable
instanceNullPointerException
- if fallback
is null
@CheckReturnValue @NonNull @SchedulerSupport(value="none") public final <T> @NonNull Maybe<T> onErrorReturn(@NonNull Function<? super Throwable,? extends T> itemSupplier)
Throwable
error signaled by the current
Completable
instead of signaling the error via onError
.
You can use this to prevent errors from propagating or to supply fallback data should errors be encountered.
onErrorReturn
does not operate by default on a particular Scheduler
.T
- the item type to return on erroritemSupplier
- a function that returns a single value that will be emitted as success value
the current Completable
signals an onError
eventMaybe
instanceNullPointerException
- if itemSupplier
is null
@CheckReturnValue @NonNull @SchedulerSupport(value="none") public final <T> @NonNull Maybe<T> onErrorReturnItem(@NonNull T item)
Completable
fails instead of signaling the error via onError
.
You can use this to prevent errors from propagating or to supply fallback data should errors be encountered.
onErrorReturnItem
does not operate by default on a particular Scheduler
.T
- the item type to return on erroritem
- the value that is emitted as onSuccess
in case the current Completable
signals an onError
Maybe
instanceNullPointerException
- if item
is null
@CheckReturnValue @SchedulerSupport(value="none") @NonNull public final @NonNull Completable onTerminateDetach()
CompletableObserver
if
the sequence is terminated or downstream calls dispose()
.
onTerminateDetach
does not operate by default on a particular Scheduler
.History: 2.1.5 - experimental
Completable
instance@CheckReturnValue @SchedulerSupport(value="none") @NonNull public final @NonNull Completable repeat()
Completable
that repeatedly subscribes to this Completable
until disposed.
repeat
does not operate by default on a particular Scheduler
.Completable
instance@CheckReturnValue @SchedulerSupport(value="none") @NonNull public final @NonNull Completable repeat(long times)
Completable
that subscribes repeatedly at most the given number of times to this Completable
.
repeat
does not operate by default on a particular Scheduler
.times
- the number of times the re-subscription should happenCompletable
instanceIllegalArgumentException
- if times
is negative@CheckReturnValue @SchedulerSupport(value="none") @NonNull public final @NonNull Completable repeatUntil(@NonNull BooleanSupplier stop)
Completable
that repeatedly subscribes to this Completable
so long as the given
stop BooleanSupplier
returns false
.
repeatUntil
does not operate by default on a particular Scheduler
.stop
- the BooleanSupplier
that should return true
to stop resubscribing.Completable
instanceNullPointerException
- if stop
is null
@CheckReturnValue @SchedulerSupport(value="none") @NonNull public final @NonNull Completable repeatWhen(@NonNull Function<? super Flowable<Object>,? extends Publisher<?>> handler)
Completable
instance that repeats when the Publisher
returned by the handler Function
emits an item or completes when this Publisher
emits an onComplete
event.
repeatWhen
does not operate by default on a particular Scheduler
.handler
- the Function
that transforms the stream of values indicating the completion of
this Completable
and returns a Publisher
that emits items for repeating or completes to indicate the
repetition should stopCompletable
instanceNullPointerException
- if handler
is null
@CheckReturnValue @SchedulerSupport(value="none") @NonNull public final @NonNull Completable retry()
Completable
that retries this Completable
as long as it emits an onError
event.
retry
does not operate by default on a particular Scheduler
.Completable
instance@CheckReturnValue @SchedulerSupport(value="none") @NonNull public final @NonNull Completable retry(@NonNull BiPredicate<? super Integer,? super Throwable> predicate)
Completable
that retries this Completable
in case of an error as long as the predicate
returns true
.
retry
does not operate by default on a particular Scheduler
.predicate
- the Predicate
called when this Completable
emits an error with the repeat count and the latest Throwable
and should return true
to retry.Completable
instanceNullPointerException
- if predicate
is null
@CheckReturnValue @SchedulerSupport(value="none") @NonNull public final @NonNull Completable retry(long times)
Completable
that when this Completable
emits an error, retries at most the given
number of times before giving up and emitting the last error.
retry
does not operate by default on a particular Scheduler
.times
- the number of times to resubscribe if the current Completable
failsCompletable
instanceIllegalArgumentException
- if times
is negative@CheckReturnValue @SchedulerSupport(value="none") @NonNull public final @NonNull Completable retry(long times, @NonNull Predicate<? super Throwable> predicate)
Completable
that when this Completable
emits an error, retries at most times
or until the predicate returns false
, whichever happens first and emitting the last error.
retry
does not operate by default on a particular Scheduler
.History: 2.1.8 - experimental
times
- the number of times to resubscribe if the current Completable
failspredicate
- the Predicate
that is called with the latest Throwable
and should return
true
to indicate the returned Completable
should resubscribe to this Completable
.Completable
instanceNullPointerException
- if predicate
is null
IllegalArgumentException
- if times
is negative@CheckReturnValue @SchedulerSupport(value="none") @NonNull public final @NonNull Completable retry(@NonNull Predicate<? super Throwable> predicate)
Completable
that when this Completable
emits an error, calls the given predicate with
the latest Throwable
to decide whether to resubscribe to the upstream or not.
retry
does not operate by default on a particular Scheduler
.predicate
- the Predicate
that is called with the latest Throwable
and should return
true
to indicate the returned Completable
should resubscribe to this Completable
.Completable
instanceNullPointerException
- if predicate
is null
@CheckReturnValue @NonNull @SchedulerSupport(value="none") public final @NonNull Completable retryUntil(@NonNull BooleanSupplier stop)
true
.
retryUntil
does not operate by default on a particular Scheduler
.stop
- the function that should return true
to stop retryingCompletable
instanceNullPointerException
- if stop
is null
@CheckReturnValue @SchedulerSupport(value="none") @NonNull public final @NonNull Completable retryWhen(@NonNull Function<? super Flowable<Throwable>,? extends Publisher<?>> handler)
Completable
which given a Publisher
and when this Completable
emits an error, delivers
that error through a Flowable
and the Publisher
should signal a value indicating a retry in response
or a terminal event indicating a termination.
Note that the inner Publisher
returned by the handler function should signal
either onNext
, onError
or onComplete
in response to the received
Throwable
to indicate the operator should retry or terminate. If the upstream to
the operator is asynchronous, signaling onNext
followed by onComplete
immediately may
result in the sequence to be completed immediately. Similarly, if this inner
Publisher
signals onError
or onComplete
while the upstream is
active, the sequence is terminated with the same signal immediately.
The following example demonstrates how to retry an asynchronous source with a delay:
Completable.timer(1, TimeUnit.SECONDS)
.doOnSubscribe(s -> System.out.println("subscribing"))
.doOnComplete(() -> { throw new RuntimeException(); })
.retryWhen(errors -> {
AtomicInteger counter = new AtomicInteger();
return errors
.takeWhile(e -> counter.getAndIncrement() != 3)
.flatMap(e -> {
System.out.println("delay retry by " + counter.get() + " second(s)");
return Flowable.timer(counter.get(), TimeUnit.SECONDS);
});
})
.blockingAwait();
retryWhen
does not operate by default on a particular Scheduler
.handler
- the Function
that receives a Flowable
delivering Throwable
s and should return a Publisher
that
emits items to indicate retries or emits terminal events to indicate termination.Completable
instanceNullPointerException
- if handler
is null
@SchedulerSupport(value="none") public final void safeSubscribe(@NonNull CompletableObserver observer)
CompletableObserver
, catches any RuntimeException
s thrown by its
CompletableObserver.onSubscribe(Disposable)
, CompletableObserver.onError(Throwable)
or CompletableObserver.onComplete()
methods and routes those to the global
error handler via RxJavaPlugins.onError(Throwable)
.
By default, the Completable
protocol forbids the onXXX
methods to throw, but some
CompletableObserver
implementation may do it anyway, causing undefined behavior in the
upstream. This method and the underlying safe wrapper ensures such misbehaving consumers don't
disrupt the protocol.
safeSubscribe
does not operate by default on a particular Scheduler
.observer
- the potentially misbehaving CompletableObserver
NullPointerException
- if observer
is null
subscribe(Action, Consumer)
@CheckReturnValue @NonNull @SchedulerSupport(value="none") public final @NonNull Completable startWith(@NonNull CompletableSource other)
Completable
which first runs the other CompletableSource
then the current Completable
if the other completed normally.
startWith
does not operate by default on a particular Scheduler
.other
- the other CompletableSource
to run firstCompletable
instanceNullPointerException
- if other
is null
@CheckReturnValue @NonNull @SchedulerSupport(value="none") @BackpressureSupport(value=FULL) public final <T> @NonNull Flowable<T> startWith(@NonNull SingleSource<T> other)
Flowable
which first runs the other SingleSource
then the current Completable
if the other succeeded normally.
Flowable
honors the backpressure of the downstream consumer.startWith
does not operate by default on a particular Scheduler
.T
- the element type of the other
SingleSource
.other
- the other SingleSource
to run firstFlowable
instanceNullPointerException
- if other
is null
@CheckReturnValue @NonNull @SchedulerSupport(value="none") @BackpressureSupport(value=FULL) public final <T> @NonNull Flowable<T> startWith(@NonNull MaybeSource<T> other)
Flowable
which first runs the other MaybeSource
then the current Completable
if the other succeeded or completed normally.
Flowable
honors the backpressure of the downstream consumer.startWith
does not operate by default on a particular Scheduler
.T
- the element type of the other
MaybeSource
.other
- the other MaybeSource
to run firstFlowable
instanceNullPointerException
- if other
is null
@CheckReturnValue @NonNull @SchedulerSupport(value="none") public final <T> @NonNull Observable<T> startWith(@NonNull ObservableSource<T> other)
Observable
which first delivers the events
of the other ObservableSource
then runs the current Completable
.
startWith
does not operate by default on a particular Scheduler
.T
- the value typeother
- the other ObservableSource
to run firstObservable
instanceNullPointerException
- if other
is null
@CheckReturnValue @NonNull @BackpressureSupport(value=FULL) @SchedulerSupport(value="none") public final <T> @NonNull Flowable<T> startWith(@NonNull Publisher<T> other)
Flowable
which first delivers the events
of the other Publisher
then runs the current Completable
.
Flowable
honors the backpressure of the downstream consumer
and expects the other Publisher
to honor it as well.startWith
does not operate by default on a particular Scheduler
.T
- the value typeother
- the other Publisher
to run firstFlowable
instanceNullPointerException
- if other
is null
@CheckReturnValue @SchedulerSupport(value="none") @NonNull public final @NonNull Completable hide()
Completable
and its Disposable
.
Allows preventing certain identity-based optimizations (fusion).
hide
does not operate by default on a particular Scheduler
.History: 2.0.5 - experimental
Completable
instance@SchedulerSupport(value="none") @NonNull public final @NonNull Disposable subscribe()
Completable
and returns a Disposable
which can be used to dispose
the subscription.
subscribe
does not operate by default on a particular Scheduler
.Disposable
that can be used for disposing the subscription at any timesubscribe(Action, Consumer, DisposableContainer)
@SchedulerSupport(value="none") public final void subscribe(@NonNull CompletableObserver observer)
CompletableSource
CompletableObserver
to this CompletableSource
instance.subscribe
in interface CompletableSource
observer
- the CompletableObserver
, not null
protected abstract void subscribeActual(@NonNull CompletableObserver observer)
CompletableObserver
s and
perform the business logic in your operator.
There is no need to call any of the plugin hooks on the current Completable
instance or
the CompletableObserver
; all hooks and basic safeguards have been
applied by subscribe(CompletableObserver)
before this method gets called.
observer
- the CompletableObserver
instance, never null
@CheckReturnValue @SchedulerSupport(value="none") @NonNull public final <E extends CompletableObserver> E subscribeWith(E observer)
CompletableObserver
(subclass) to this Completable
and returns the given
CompletableObserver
as is.
Usage example:
Completable source = Completable.complete().delay(1, TimeUnit.SECONDS);
CompositeDisposable composite = new CompositeDisposable();
DisposableCompletableObserver ds = new DisposableCompletableObserver() {
// ...
};
composite.add(source.subscribeWith(ds));
subscribeWith
does not operate by default on a particular Scheduler
.E
- the type of the CompletableObserver
to use and returnobserver
- the CompletableObserver
(subclass) to use and return, not null
observer
NullPointerException
- if observer
is null
@CheckReturnValue @NonNull @SchedulerSupport(value="none") public final @NonNull Disposable subscribe(@NonNull Action onComplete, @NonNull Consumer<? super Throwable> onError)
Completable
and calls back either the onError
or onComplete
functions.
subscribe
does not operate by default on a particular Scheduler
.onComplete
- the Action
that is called if the Completable
completes normallyonError
- the Consumer
that is called if this Completable
emits an errorDisposable
that can be used for disposing the subscription at any timeNullPointerException
- if onComplete
or onError
is null
subscribe(Action, Consumer, DisposableContainer)
@SchedulerSupport(value="none") @NonNull public final @NonNull Disposable subscribe(@NonNull Action onComplete, @NonNull Consumer<? super Throwable> onError, @NonNull DisposableContainer container)
Disposable
CompletableObserver
,
adds it to the given DisposableContainer
and ensures, that if the upstream
terminates or this particular Disposable
is disposed, the CompletableObserver
is removed
from the given composite.
The CompletableObserver
will be removed after the callback for the terminal event has been invoked.
subscribe
does not operate by default on a particular Scheduler
.onError
- the callback for an upstream erroronComplete
- the callback for an upstream completioncontainer
- the DisposableContainer
(such as CompositeDisposable
) to add and remove the
created Disposable
CompletableObserver
Disposable
that allows disposing the particular subscription.NullPointerException
- if onComplete
, onError
or container
is null
@CheckReturnValue @NonNull @SchedulerSupport(value="none") public final @NonNull Disposable subscribe(@NonNull Action onComplete)
Completable
and calls the given Action
when this Completable
completes normally.
If the Completable
emits an error, it is wrapped into an
OnErrorNotImplementedException
and routed to the global RxJavaPlugins.onError(Throwable)
handler.
subscribe
does not operate by default on a particular Scheduler
.onComplete
- the Action
called when this Completable
completes normallyDisposable
that can be used for disposing the subscription at any timeNullPointerException
- if onComplete
is null
subscribe(Action, Consumer, DisposableContainer)
@CheckReturnValue @NonNull @SchedulerSupport(value="custom") public final @NonNull Completable subscribeOn(@NonNull Scheduler scheduler)
Completable
which subscribes the downstream subscriber on the specified scheduler, making
sure the subscription side-effects happen on that specific thread of the Scheduler
.
subscribeOn
operates on a Scheduler
you specify.scheduler
- the Scheduler
to subscribe onCompletable
instanceNullPointerException
- if scheduler
is null
@CheckReturnValue @NonNull @SchedulerSupport(value="none") public final @NonNull Completable takeUntil(@NonNull CompletableSource other)
Completable
terminates (wins the termination race) while disposing the connection to the losing source.
takeUntil
does not operate by default on a particular Scheduler
.RxJavaPlugins.onError(Throwable)
.History: 2.1.17 - experimental
other
- the other completable source to observe for the terminal signalsCompletable
instanceNullPointerException
- if other
is null
@CheckReturnValue @SchedulerSupport(value="io.reactivex:computation") @NonNull public final @NonNull Completable timeout(long timeout, @NonNull TimeUnit unit)
Completabl
e that runs this Completable
and emits a TimeoutException
in case
this Completable
doesn't complete within the given time.
timeout
signals the TimeoutException
on the computation
Scheduler
.timeout
- the timeout valueunit
- the unit of timeout
Completable
instanceNullPointerException
- if unit
is null
@CheckReturnValue @NonNull @SchedulerSupport(value="io.reactivex:computation") public final @NonNull Completable timeout(long timeout, @NonNull TimeUnit unit, @NonNull CompletableSource fallback)
Completable
that runs this Completable
and switches to the other CompletableSource
in case this Completable
doesn't complete within the given time.
timeout
subscribes to the other CompletableSource
on
the computation
Scheduler
.timeout
- the timeout valueunit
- the unit of timeout
fallback
- the other CompletableSource
instance to switch to in case of a timeoutCompletable
instanceNullPointerException
- if unit
or fallback
is null
@CheckReturnValue @SchedulerSupport(value="custom") @NonNull public final @NonNull Completable timeout(long timeout, @NonNull TimeUnit unit, @NonNull Scheduler scheduler)
Completable
that runs this Completable
and emits a TimeoutException
in case
this Completable
doesn't complete within the given time while "waiting" on the specified
Scheduler
.
timeout
signals the TimeoutException
on the Scheduler
you specify.timeout
- the timeout valueunit
- the unit of timeout
scheduler
- the Scheduler
to use to wait for completion and signal TimeoutException
Completable
instanceNullPointerException
- if unit
or scheduler
is null
@CheckReturnValue @NonNull @SchedulerSupport(value="custom") public final @NonNull Completable timeout(long timeout, @NonNull TimeUnit unit, @NonNull Scheduler scheduler, @NonNull CompletableSource fallback)
Completable
that runs this Completable
and switches to the other CompletableSource
in case this Completable
doesn't complete within the given time while "waiting" on
the specified Scheduler
.
timeout
subscribes to the other CompletableSource
on
the Scheduler
you specify.timeout
- the timeout valueunit
- the unit of timeout
scheduler
- the Scheduler
to use to wait for completionfallback
- the other Completable
instance to switch to in case of a timeoutCompletable
instanceNullPointerException
- if unit
, scheduler
or fallback
is null
@CheckReturnValue @SchedulerSupport(value="none") public final <R> R to(@NonNull CompletableConverter<? extends R> converter)
CompletableConverter
function during assembly time and returns its resulting value.
This allows fluent conversion to any other type.
to
does not operate by default on a particular Scheduler
.History: 2.1.7 - experimental
R
- the resulting object typeconverter
- the CompletableConverter
that receives the current Completable
instance and returns a value to be the result of to()
NullPointerException
- if converter
is null
@CheckReturnValue @BackpressureSupport(value=FULL) @SchedulerSupport(value="none") @NonNull public final <T> @NonNull Flowable<T> toFlowable()
Flowable
which when subscribed to subscribes to this Completable
and
relays the terminal events to the downstream Subscriber
.
Flowable
honors the backpressure of the downstream consumer.toFlowable
does not operate by default on a particular Scheduler
.T
- the value typeFlowable
instance@CheckReturnValue @SchedulerSupport(value="none") @NonNull public final @NonNull Future<Void> toFuture()
Future
representing the termination of the current Completable
via a null
value.
Cancelling the Future
will cancel the subscription to the current Completable
.
toFuture
does not operate by default on a particular Scheduler
.Future
instance@CheckReturnValue @SchedulerSupport(value="none") @NonNull public final <T> @NonNull Maybe<T> toMaybe()
Completable
into a Maybe
.
toMaybe
does not operate by default on a particular Scheduler
.T
- the value typeMaybe
instance@CheckReturnValue @SchedulerSupport(value="none") @NonNull public final <T> @NonNull Observable<T> toObservable()
Observable
which when subscribed to subscribes to this Completable
and
relays the terminal events to the downstream Observer
.
toObservable
does not operate by default on a particular Scheduler
.T
- the value typeObservable
created@CheckReturnValue @NonNull @SchedulerSupport(value="none") public final <T> @NonNull Single<T> toSingle(@NonNull Supplier<? extends T> completionValueSupplier)
Completable
into a Single
which when this Completable
completes normally,
calls the given Supplier
and emits its returned value through onSuccess
.
toSingle
does not operate by default on a particular Scheduler
.T
- the value typecompletionValueSupplier
- the value supplier called when this Completable
completes normallySingle
instanceNullPointerException
- if completionValueSupplier
is null
@CheckReturnValue @NonNull @SchedulerSupport(value="none") public final <T> @NonNull Single<T> toSingleDefault(T completionValue)
Completable
into a Single
which when this Completable
completes normally,
emits the given value through onSuccess
.
toSingleDefault
does not operate by default on a particular Scheduler
.T
- the value typecompletionValue
- the value to emit when this Completable
completes normallySingle
instanceNullPointerException
- if completionValue
is null
@CheckReturnValue @NonNull @SchedulerSupport(value="custom") public final @NonNull Completable unsubscribeOn(@NonNull Scheduler scheduler)
Completable
which makes sure when an observer disposes the subscription, the
dispose()
method is called on the specified Scheduler
.
unsubscribeOn
calls dispose()
of the upstream on the Scheduler
you specify.scheduler
- the target Scheduler
where to execute the disposingCompletable
instanceNullPointerException
- if scheduler
is null
@CheckReturnValue @SchedulerSupport(value="none") @NonNull public final @NonNull TestObserver<Void> test()
TestObserver
and subscribes
it to this Completable
.
test
does not operate by default on a particular Scheduler
.TestObserver
instance@CheckReturnValue @SchedulerSupport(value="none") @NonNull public final @NonNull TestObserver<Void> test(boolean dispose)
TestObserver
optionally in cancelled state, then subscribes it to this Completable
.dispose
- if true
, the TestObserver
will be cancelled before subscribing to this
Completable
.
test
does not operate by default on a particular Scheduler
.TestObserver
instance@CheckReturnValue @SchedulerSupport(value="none") @NonNull public static @NonNull Completable fromCompletionStage(@NonNull CompletionStage<?> stage)
CompletionStage
terminates.
Note that the operator takes an already instantiated, running or terminated CompletionStage
.
If the CompletionStage
is to be created per consumer upon subscription, use defer(Supplier)
around fromCompletionStage
:
Maybe.defer(() -> Completable.fromCompletionStage(createCompletionStage()));
Canceling the flow can't cancel the execution of the CompletionStage
because CompletionStage
itself doesn't support cancellation. Instead, the operator detaches from the CompletionStage
.
fromCompletionStage
does not operate by default on a particular Scheduler
.stage
- the CompletionStage
to convert to a Completable
and
signal onComplete
or onError
when the CompletionStage
terminates normally or with a failureCompletable
instanceNullPointerException
- if stage
is null
@CheckReturnValue @SchedulerSupport(value="none") @NonNull public final <T> @NonNull CompletionStage<T> toCompletionStage(T defaultItem)
CompletionStage
.
The upstream can be canceled by converting the resulting CompletionStage
into
CompletableFuture
via CompletionStage.toCompletableFuture()
and
calling CompletableFuture.cancel(boolean)
on it.
The upstream will be also cancelled if the resulting CompletionStage
is converted to and
completed manually by CompletableFuture.complete(Object)
or CompletableFuture.completeExceptionally(Throwable)
.
CompletionStage
s don't have a notion of emptiness and allow null
s, therefore, one can either use
a defaultItem
of null
or turn the flow into a sequence of Optional
s and default to Optional.empty()
:
CompletionStage<Optional<T>> stage = source.map(Optional::of).toCompletionStage(Optional.empty());
toCompletionStage
does not operate by default on a particular Scheduler
.T
- the type of the default item to signal upon completiondefaultItem
- the item to signal upon completionCompletionStage
instance