Debian Codegraph @

src/main/java/io/reactivex/rxjava3/core/Completable.java

raw
1 /*
2 * Copyright (c) 2016-present, RxJava Contributors.
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in
5 * compliance with the License. You may obtain a copy of the License at
6 *
7 * http://www.apache.org/licenses/LICENSE-2.0
8 *
9 * Unless required by applicable law or agreed to in writing, software distributed under the License is
10 * distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See
11 * the License for the specific language governing permissions and limitations under the License.
12 */
13
14 package io.reactivex.rxjava3.core;
15
16 import java.util.*;
17 import java.util.concurrent.*;
18
19 import org.reactivestreams.*;
20
21 import io.reactivex.rxjava3.annotations.*;
22 import io.reactivex.rxjava3.disposables.*;
23 import io.reactivex.rxjava3.exceptions.*;
24 import io.reactivex.rxjava3.functions.*;
25 import io.reactivex.rxjava3.internal.functions.*;
26 import io.reactivex.rxjava3.internal.fuseable.*;
27 import io.reactivex.rxjava3.internal.jdk8.*;
28 import io.reactivex.rxjava3.internal.observers.*;
29 import io.reactivex.rxjava3.internal.operators.completable.*;
30 import io.reactivex.rxjava3.internal.operators.maybe.*;
31 import io.reactivex.rxjava3.internal.operators.mixed.*;
32 import io.reactivex.rxjava3.internal.operators.single.SingleDelayWithCompletable;
33 import io.reactivex.rxjava3.observers.TestObserver;
34 import io.reactivex.rxjava3.plugins.RxJavaPlugins;
35 import io.reactivex.rxjava3.schedulers.Schedulers;
36
37 /**
38 * The {@code Completable} class represents a deferred computation without any value but
39 * only indication for completion or exception.
40 * <p>
41 * {@code Completable} behaves similarly to {@link Observable} except that it can only emit either
42 * a completion or error signal (there is no {@code onNext} or {@code onSuccess} as with the other
43 * reactive types).
44 * <p>
45 * The {@code Completable} class implements the {@link CompletableSource} base interface and the default consumer
46 * type it interacts with is the {@link CompletableObserver} via the {@link #subscribe(CompletableObserver)} method.
47 * The {@code Completable} operates with the following sequential protocol:
48 * <pre><code>
49 * onSubscribe (onError | onComplete)?
50 * </code></pre>
51 * <p>
52 * Note that as with the {@code Observable} protocol, {@code onError} and {@code onComplete} are mutually exclusive events.
53 * <p>
54 * Like {@code Observable}, a running {@code Completable} can be stopped through the {@link Disposable} instance
55 * provided to consumers through {@link CompletableObserver#onSubscribe}.
56 * <p>
57 * Like an {@code Observable}, a {@code Completable} is lazy, can be either "hot" or "cold", synchronous or
58 * asynchronous. {@code Completable} instances returned by the methods of this class are <em>cold</em>
59 * and there is a standard <em>hot</em> implementation in the form of a subject:
60 * {@link io.reactivex.rxjava3.subjects.CompletableSubject CompletableSubject}.
61 * <p>
62 * The documentation for this class makes use of marble diagrams. The following legend explains these diagrams:
63 * <p>
64 * <img width="640" height="577" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Completable.png" alt="">
65 * <p>
66 * See {@link Flowable} or {@code Observable} for the
67 * implementation of the Reactive Pattern for a stream or vector of values.
68 * <p>
69 * Example:
70 * <pre><code>
71 * Disposable d = Completable.complete()
72 * .delay(10, TimeUnit.SECONDS, Schedulers.io())
73 * .subscribeWith(new DisposableCompletableObserver() {
74 * &#64;Override
75 * public void onStart() {
76 * System.out.println("Started");
77 * }
78 *
79 * &#64;Override
80 * public void onError(Throwable error) {
81 * error.printStackTrace();
82 * }
83 *
84 * &#64;Override
85 * public void onComplete() {
86 * System.out.println("Done!");
87 * }
88 * });
89 *
90 * Thread.sleep(5000);
91 *
92 * d.dispose();
93 * </code></pre>
94 * <p>
95 * Note that by design, subscriptions via {@link #subscribe(CompletableObserver)} can't be disposed
96 * from the outside (hence the
97 * {@code void} return of the {@link #subscribe(CompletableObserver)} method) and it is the
98 * responsibility of the implementor of the {@code CompletableObserver} to allow this to happen.
99 * RxJava supports such usage with the standard
100 * {@link io.reactivex.rxjava3.observers.DisposableCompletableObserver DisposableCompletableObserver} instance.
101 * For convenience, the {@link #subscribeWith(CompletableObserver)} method is provided as well to
102 * allow working with a {@code CompletableObserver} (or subclass) instance to be applied with in
103 * a fluent manner (such as in the example above).
104 *
105 * @see io.reactivex.rxjava3.observers.DisposableCompletableObserver
106 */
107 public abstract class Completable implements CompletableSource {
108 /**
109 * Returns a {@code Completable} which terminates as soon as one of the source {@code Completable}s
110 * terminates (normally or with an error) and disposes all other {@code Completable}s.
111 * <p>
112 * <img width="640" height="518" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Completable.ambArray.png" alt="">
113 * <dl>
114 * <dt><b>Scheduler:</b></dt>
115 * <dd>{@code ambArray} does not operate by default on a particular {@link Scheduler}.</dd>
116 * </dl>
117 * @param sources the array of source {@code Completable}s. A subscription to each source will
118 * occur in the same order as in this array.
119 * @return the new {@code Completable} instance
120 * @throws NullPointerException if {@code sources} is {@code null}
121 */
122 @CheckReturnValue
123 @NonNull
124 @SchedulerSupport(SchedulerSupport.NONE)
125 @SafeVarargs
126 public static Completable ambArray(@NonNull CompletableSource... sources) {
127 Objects.requireNonNull(sources, "sources is null");
128 if (sources.length == 0) {
129 return complete();
130 }
131 if (sources.length == 1) {
132 return wrap(sources[0]);
133 }
134
135 return RxJavaPlugins.onAssembly(new CompletableAmb(sources, null));
136 }
137
138 /**
139 * Returns a {@code Completable} which terminates as soon as one of the source {@code Completable}s in the {@link Iterable} sequence
140 * terminates (normally or with an error) and disposes all other {@code Completable}s.
141 * <p>
142 * <img width="640" height="518" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Completable.amb.png" alt="">
143 * <dl>
144 * <dt><b>Scheduler:</b></dt>
145 * <dd>{@code amb} does not operate by default on a particular {@link Scheduler}.</dd>
146 * </dl>
147 * @param sources the {@code Iterable} of source {@code Completable}s. A subscription to each source will
148 * occur in the same order as in this {@code Iterable}.
149 * @return the new {@code Completable} instance
150 * @throws NullPointerException if {@code sources} is {@code null}
151 */
152 @CheckReturnValue
153 @NonNull
154 @SchedulerSupport(SchedulerSupport.NONE)
155 public static Completable amb(@NonNull Iterable<@NonNull ? extends CompletableSource> sources) {
156 Objects.requireNonNull(sources, "sources is null");
157
158 return RxJavaPlugins.onAssembly(new CompletableAmb(null, sources));
159 }
160
161 /**
162 * Returns a {@code Completable} instance that completes immediately when subscribed to.
163 * <p>
164 * <img width="640" height="472" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Completable.complete.png" alt="">
165 * <dl>
166 * <dt><b>Scheduler:</b></dt>
167 * <dd>{@code complete} does not operate by default on a particular {@link Scheduler}.</dd>
168 * </dl>
169 * @return the shared {@code Completable} instance
170 */
171 @CheckReturnValue
172 @NonNull
173 @SchedulerSupport(SchedulerSupport.NONE)
174 public static Completable complete() {
175 return RxJavaPlugins.onAssembly(CompletableEmpty.INSTANCE);
176 }
177
178 /**
179 * Returns a {@code Completable} which completes only when all sources complete, one after another.
180 * <p>
181 * <img width="640" height="284" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Completable.concatArray.png" alt="">
182 * <dl>
183 * <dt><b>Scheduler:</b></dt>
184 * <dd>{@code concatArray} does not operate by default on a particular {@link Scheduler}.</dd>
185 * </dl>
186 * @param sources the sources to concatenate
187 * @return the new {@code Completable} instance
188 * @throws NullPointerException if {@code sources} is {@code null}
189 */
190 @CheckReturnValue
191 @NonNull
192 @SchedulerSupport(SchedulerSupport.NONE)
193 @SafeVarargs
194 public static Completable concatArray(@NonNull CompletableSource... sources) {
195 Objects.requireNonNull(sources, "sources is null");
196 if (sources.length == 0) {
197 return complete();
198 } else
199 if (sources.length == 1) {
200 return wrap(sources[0]);
201 }
202 return RxJavaPlugins.onAssembly(new CompletableConcatArray(sources));
203 }
204
205 /**
206 * Returns a {@code Completable} which completes only when all sources complete, one after another.
207 * <p>
208 * <img width="640" height="324" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Completable.concatArrayDelayError.png" alt="">
209 * <dl>
210 * <dt><b>Scheduler:</b></dt>
211 * <dd>{@code concatArrayDelayError} does not operate by default on a particular {@link Scheduler}.</dd>
212 * </dl>
213 * @param sources the sources to concatenate
214 * @return the new {@code Completable} instance
215 * @throws NullPointerException if {@code sources} is {@code null}
216 * @since 3.0.0
217 */
218 @CheckReturnValue
219 @NonNull
220 @SchedulerSupport(SchedulerSupport.NONE)
221 @SafeVarargs
222 public static Completable concatArrayDelayError(@NonNull CompletableSource... sources) {
223 return Flowable.fromArray(sources).concatMapCompletableDelayError(Functions.identity(), true, 2);
224 }
225
226 /**
227 * Returns a {@code Completable} which completes only when all sources complete, one after another.
228 * <p>
229 * <img width="640" height="303" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Completable.concat.png" alt="">
230 * <dl>
231 * <dt><b>Scheduler:</b></dt>
232 * <dd>{@code concat} does not operate by default on a particular {@link Scheduler}.</dd>
233 * </dl>
234 * @param sources the sources to concatenate
235 * @return the new {@code Completable} instance
236 * @throws NullPointerException if {@code sources} is {@code null}
237 */
238 @CheckReturnValue
239 @NonNull
240 @SchedulerSupport(SchedulerSupport.NONE)
241 public static Completable concat(@NonNull Iterable<@NonNull ? extends CompletableSource> sources) {
242 Objects.requireNonNull(sources, "sources is null");
243
244 return RxJavaPlugins.onAssembly(new CompletableConcatIterable(sources));
245 }
246
247 /**
248 * Returns a {@code Completable} which completes only when all sources complete, one after another.
249 * <p>
250 * <img width="640" height="238" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Completable.concat.p.png" alt="">
251 * <dl>
252 * <dt><b>Backpressure:</b></dt>
253 * <dd>The returned {@code Completable} honors the backpressure of the downstream consumer
254 * and expects the other {@link Publisher} to honor it as well.</dd>
255 * <dt><b>Scheduler:</b></dt>
256 * <dd>{@code concat} does not operate by default on a particular {@link Scheduler}.</dd>
257 * </dl>
258 * @param sources the sources to concatenate
259 * @return the new {@code Completable} instance
260 * @throws NullPointerException if {@code sources} is {@code null}
261 */
262 @CheckReturnValue
263 @SchedulerSupport(SchedulerSupport.NONE)
264 @BackpressureSupport(BackpressureKind.FULL)
265 @NonNull
266 public static Completable concat(@NonNull Publisher<@NonNull ? extends CompletableSource> sources) {
267 return concat(sources, 2);
268 }
269
270 /**
271 * Returns a {@code Completable} which completes only when all sources complete, one after another.
272 * <p>
273 * <img width="640" height="238" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Completable.concat.pn.png" alt="">
274 * <dl>
275 * <dt><b>Backpressure:</b></dt>
276 * <dd>The returned {@code Completable} honors the backpressure of the downstream consumer
277 * and expects the other {@link Publisher} to honor it as well.</dd>
278 * <dt><b>Scheduler:</b></dt>
279 * <dd>{@code concat} does not operate by default on a particular {@link Scheduler}.</dd>
280 * </dl>
281 * @param sources the sources to concatenate
282 * @param prefetch the number of sources to prefetch from the sources
283 * @return the new {@code Completable} instance
284 * @throws NullPointerException if {@code sources} is {@code null}
285 * @throws IllegalArgumentException if {@code prefetch} is non-positive
286 */
287 @CheckReturnValue
288 @NonNull
289 @SchedulerSupport(SchedulerSupport.NONE)
290 @BackpressureSupport(BackpressureKind.FULL)
291 public static Completable concat(@NonNull Publisher<@NonNull ? extends CompletableSource> sources, int prefetch) {
292 Objects.requireNonNull(sources, "sources is null");
293 ObjectHelper.verifyPositive(prefetch, "prefetch");
294 return RxJavaPlugins.onAssembly(new CompletableConcat(sources, prefetch));
295 }
296
297 /**
298 * Returns a {@code Completable} which completes only when all sources complete, one after another.
299 * <p>
300 * <img width="640" height="361" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Completable.concatDelayError.i.png" alt="">
301 * <dl>
302 * <dt><b>Scheduler:</b></dt>
303 * <dd>{@code concatDelayError} does not operate by default on a particular {@link Scheduler}.</dd>
304 * </dl>
305 * @param sources the sources to concatenate
306 * @return the new {@code Completable} instance
307 * @throws NullPointerException if {@code sources} is {@code null}
308 * @since 3.0.0
309 */
310 @CheckReturnValue
311 @NonNull
312 @SchedulerSupport(SchedulerSupport.NONE)
313 public static Completable concatDelayError(@NonNull Iterable<@NonNull ? extends CompletableSource> sources) {
314 return Flowable.fromIterable(sources).concatMapCompletableDelayError(Functions.identity());
315 }
316
317 /**
318 * Returns a {@code Completable} which completes only when all sources complete, one after another.
319 * <p>
320 * <img width="640" height="396" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Completable.concatDelayError.p.png" alt="">
321 * <dl>
322 * <dt><b>Backpressure:</b></dt>
323 * <dd>The returned {@code Completable} honors the backpressure of the downstream consumer
324 * and expects the other {@link Publisher} to honor it as well.</dd>
325 * <dt><b>Scheduler:</b></dt>
326 * <dd>{@code concatDelayError} does not operate by default on a particular {@link Scheduler}.</dd>
327 * </dl>
328 * @param sources the sources to concatenate
329 * @return the new {@code Completable} instance
330 * @throws NullPointerException if {@code sources} is {@code null}
331 * @since 3.0.0
332 */
333 @CheckReturnValue
334 @SchedulerSupport(SchedulerSupport.NONE)
335 @BackpressureSupport(BackpressureKind.FULL)
336 @NonNull
337 public static Completable concatDelayError(@NonNull Publisher<@NonNull ? extends CompletableSource> sources) {
338 return concatDelayError(sources, 2);
339 }
340
341 /**
342 * Returns a {@code Completable} which completes only when all sources complete, one after another.
343 * <p>
344 * <img width="640" height="359" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Completable.concatDelayError.pn.png" alt="">
345 * <dl>
346 * <dt><b>Backpressure:</b></dt>
347 * <dd>The returned {@code Completable} honors the backpressure of the downstream consumer
348 * and expects the other {@link Publisher} to honor it as well.</dd>
349 * <dt><b>Scheduler:</b></dt>
350 * <dd>{@code concatDelayError} does not operate by default on a particular {@link Scheduler}.</dd>
351 * </dl>
352 * @param sources the sources to concatenate
353 * @param prefetch the number of sources to prefetch from the sources
354 * @return the new {@code Completable} instance
355 * @throws NullPointerException if {@code sources} is {@code null}
356 * @throws IllegalArgumentException if {@code prefetch} is non-positive
357 * @since 3.0.0
358 */
359 @CheckReturnValue
360 @NonNull
361 @SchedulerSupport(SchedulerSupport.NONE)
362 @BackpressureSupport(BackpressureKind.FULL)
363 public static Completable concatDelayError(@NonNull Publisher<@NonNull ? extends CompletableSource> sources, int prefetch) {
364 return Flowable.fromPublisher(sources).concatMapCompletableDelayError(Functions.identity(), true, prefetch);
365 }
366
367 /**
368 * Provides an API (via a cold {@code Completable}) that bridges the reactive world with the callback-style world.
369 * <p>
370 * <img width="640" height="442" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Completable.create.png" alt="">
371 * <p>
372 * Example:
373 * <pre><code>
374 * Completable.create(emitter -&gt; {
375 * Callback listener = new Callback() {
376 * &#64;Override
377 * public void onEvent(Event e) {
378 * emitter.onComplete();
379 * }
380 *
381 * &#64;Override
382 * public void onFailure(Exception e) {
383 * emitter.onError(e);
384 * }
385 * };
386 *
387 * AutoCloseable c = api.someMethod(listener);
388 *
389 * emitter.setCancellable(c::close);
390 *
391 * });
392 * </code></pre>
393 * <p>
394 * Whenever a {@link CompletableObserver} subscribes to the returned {@code Completable}, the provided
395 * {@link CompletableOnSubscribe} callback is invoked with a fresh instance of a {@link CompletableEmitter}
396 * that will interact only with that specific {@code CompletableObserver}. If this {@code CompletableObserver}
397 * disposes the flow (making {@link CompletableEmitter#isDisposed} return {@code true}),
398 * other observers subscribed to the same returned {@code Completable} are not affected.
399 * <dl>
400 * <dt><b>Scheduler:</b></dt>
401 * <dd>{@code create} does not operate by default on a particular {@link Scheduler}.</dd>
402 * </dl>
403 * @param source the emitter that is called when a {@code CompletableObserver} subscribes to the returned {@code Completable}
404 * @return the new {@code Completable} instance
405 * @throws NullPointerException if {@code source} is {@code null}
406 * @see CompletableOnSubscribe
407 * @see Cancellable
408 */
409 @CheckReturnValue
410 @NonNull
411 @SchedulerSupport(SchedulerSupport.NONE)
412 public static Completable create(@NonNull CompletableOnSubscribe source) {
413 Objects.requireNonNull(source, "source is null");
414 return RxJavaPlugins.onAssembly(new CompletableCreate(source));
415 }
416
417 /**
418 * Compares two {@link CompletableSource}s and emits {@code true} via a {@link Single} if both complete.
419 * <p>
420 * <img width="640" height="187" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Completable.sequenceEqual.png" alt="">
421 * <dl>
422 * <dt><b>Scheduler:</b></dt>
423 * <dd>{@code sequenceEqual} does not operate by default on a particular {@link Scheduler}.</dd>
424 * </dl>
425 * @param source1 the first {@code CompletableSource} instance
426 * @param source2 the second {@code CompletableSource} instance
427 * @return the new {@code Single} instance
428 * @throws NullPointerException if {@code source1} or {@code source2} is {@code null}
429 * @since 3.0.0
430 */
431 @CheckReturnValue
432 @NonNull
433 @SchedulerSupport(SchedulerSupport.NONE)
434 public static Single<Boolean> sequenceEqual(@NonNull CompletableSource source1, @NonNull CompletableSource source2) { // NOPMD
435 Objects.requireNonNull(source1, "source1 is null");
436 Objects.requireNonNull(source2, "source2 is null");
437 return mergeArrayDelayError(source1, source2).andThen(Single.just(true));
438 }
439
440 /**
441 * Constructs a {@code Completable} instance by wrapping the given source callback
442 * <strong>without any safeguards; you should manage the lifecycle and response
443 * to downstream disposal</strong>.
444 * <p>
445 * <img width="640" height="260" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Completable.unsafeCreate.png" alt="">
446 * <dl>
447 * <dt><b>Scheduler:</b></dt>
448 * <dd>{@code unsafeCreate} does not operate by default on a particular {@link Scheduler}.</dd>
449 * </dl>
450 * @param onSubscribe the callback which will receive the {@link CompletableObserver} instances
451 * when the {@code Completable} is subscribed to.
452 * @return the new {@code Completable} instance
453 * @throws NullPointerException if {@code onSubscribe} is {@code null}
454 * @throws IllegalArgumentException if {@code source} is a {@code Completable}
455 */
456 @CheckReturnValue
457 @NonNull
458 @SchedulerSupport(SchedulerSupport.NONE)
459 public static Completable unsafeCreate(@NonNull CompletableSource onSubscribe) {
460 Objects.requireNonNull(onSubscribe, "onSubscribe is null");
461 if (onSubscribe instanceof Completable) {
462 throw new IllegalArgumentException("Use of unsafeCreate(Completable)!");
463 }
464 return RxJavaPlugins.onAssembly(new CompletableFromUnsafeSource(onSubscribe));
465 }
466
467 /**
468 * Defers the subscription to a {@code Completable} instance returned by a supplier.
469 * <p>
470 * <img width="640" height="298" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Completable.defer.png" alt="">
471 * <dl>
472 * <dt><b>Scheduler:</b></dt>
473 * <dd>{@code defer} does not operate by default on a particular {@link Scheduler}.</dd>
474 * </dl>
475 * @param supplier the supplier that returns the {@code Completable} that will be subscribed to.
476 * @return the new {@code Completable} instance
477 * @throws NullPointerException if {@code supplier} is {@code null}
478 */
479 @CheckReturnValue
480 @NonNull
481 @SchedulerSupport(SchedulerSupport.NONE)
482 public static Completable defer(@NonNull Supplier<? extends @NonNull CompletableSource> supplier) {
483 Objects.requireNonNull(supplier, "supplier is null");
484 return RxJavaPlugins.onAssembly(new CompletableDefer(supplier));
485 }
486
487 /**
488 * Creates a {@code Completable} which calls the given error supplier for each subscriber
489 * and emits its returned {@link Throwable}.
490 * <p>
491 * <img width="640" height="462" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Completable.error.f.png" alt="">
492 * <p>
493 * If the {@code errorSupplier} returns {@code null}, the downstream {@link CompletableObserver}s will receive a
494 * {@link NullPointerException}.
495 * <dl>
496 * <dt><b>Scheduler:</b></dt>
497 * <dd>{@code error} does not operate by default on a particular {@link Scheduler}.</dd>
498 * </dl>
499 * @param supplier the error supplier, not {@code null}
500 * @return the new {@code Completable} instance
501 * @throws NullPointerException if {@code supplier} is {@code null}
502 */
503 @CheckReturnValue
504 @NonNull
505 @SchedulerSupport(SchedulerSupport.NONE)
506 public static Completable error(@NonNull Supplier<? extends @NonNull Throwable> supplier) {
507 Objects.requireNonNull(supplier, "supplier is null");
508 return RxJavaPlugins.onAssembly(new CompletableErrorSupplier(supplier));
509 }
510
511 /**
512 * Creates a {@code Completable} instance that emits the given {@link Throwable} exception to subscribers.
513 * <p>
514 * <img width="640" height="462" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Completable.error.png" alt="">
515 * <dl>
516 * <dt><b>Scheduler:</b></dt>
517 * <dd>{@code error} does not operate by default on a particular {@link Scheduler}.</dd>
518 * </dl>
519 * @param throwable the {@code Throwable} instance to emit, not {@code null}
520 * @return the new {@code Completable} instance
521 * @throws NullPointerException if {@code throwable} is {@code null}
522 */
523 @CheckReturnValue
524 @NonNull
525 @SchedulerSupport(SchedulerSupport.NONE)
526 public static Completable error(@NonNull Throwable throwable) {
527 Objects.requireNonNull(throwable, "throwable is null");
528 return RxJavaPlugins.onAssembly(new CompletableError(throwable));
529 }
530
531 /**
532 * Returns a {@code Completable} instance that runs the given {@link Action} for each {@link CompletableObserver} and
533 * emits either an exception or simply completes.
534 * <p>
535 * <img width="640" height="297" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Completable.fromAction.png" alt="">
536 * <dl>
537 * <dt><b>Scheduler:</b></dt>
538 * <dd>{@code fromAction} does not operate by default on a particular {@link Scheduler}.</dd>
539 * <dt><b>Error handling:</b></dt>
540 * <dd> If the {@code Action} throws an exception, the respective {@link Throwable} is
541 * delivered to the downstream via {@link CompletableObserver#onError(Throwable)},
542 * except when the downstream has disposed this {@code Completable} source.
543 * In this latter case, the {@code Throwable} is delivered to the global error handler via
544 * {@link RxJavaPlugins#onError(Throwable)} as an {@link io.reactivex.rxjava3.exceptions.UndeliverableException UndeliverableException}.
545 * </dd>
546 * </dl>
547 * @param action the {@code Action} to run for each subscribing {@code CompletableObserver}
548 * @return the new {@code Completable} instance
549 * @throws NullPointerException if {@code action} is {@code null}
550 */
551 @CheckReturnValue
552 @NonNull
553 @SchedulerSupport(SchedulerSupport.NONE)
554 public static Completable fromAction(@NonNull Action action) {
555 Objects.requireNonNull(action, "action is null");
556 return RxJavaPlugins.onAssembly(new CompletableFromAction(action));
557 }
558
559 /**
560 * Returns a {@code Completable} which when subscribed, executes the {@link Callable} function, ignores its
561 * normal result and emits {@code onError} or {@code onComplete} only.
562 * <p>
563 * <img width="640" height="286" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Completable.fromCallable.png" alt="">
564 * <dl>
565 * <dt><b>Scheduler:</b></dt>
566 * <dd>{@code fromCallable} does not operate by default on a particular {@link Scheduler}.</dd>
567 * <dt><b>Error handling:</b></dt>
568 * <dd> If the {@code Callable} throws an exception, the respective {@link Throwable} is
569 * delivered to the downstream via {@link CompletableObserver#onError(Throwable)},
570 * except when the downstream has disposed this {@code Completable} source.
571 * In this latter case, the {@code Throwable} is delivered to the global error handler via
572 * {@link RxJavaPlugins#onError(Throwable)} as an {@link io.reactivex.rxjava3.exceptions.UndeliverableException UndeliverableException}.
573 * </dd>
574 * </dl>
575 * @param callable the {@code Callable} instance to execute for each subscribing {@link CompletableObserver}
576 * @return the new {@code Completable} instance
577 * @throws NullPointerException if {@code callable} is {@code null}
578 * @see #defer(Supplier)
579 * @see #fromSupplier(Supplier)
580 */
581 @CheckReturnValue
582 @NonNull
583 @SchedulerSupport(SchedulerSupport.NONE)
584 public static Completable fromCallable(@NonNull Callable<?> callable) {
585 Objects.requireNonNull(callable, "callable is null");
586 return RxJavaPlugins.onAssembly(new CompletableFromCallable(callable));
587 }
588
589 /**
590 * Returns a {@code Completable} instance that reacts to the termination of the given {@link Future} in a blocking fashion.
591 * <p>
592 * <img width="640" height="628" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Completable.fromFuture.png" alt="">
593 * <p>
594 * Note that disposing the {@code Completable} won't cancel the {@code Future}.
595 * Use {@link #doOnDispose(Action)} and call {@link Future#cancel(boolean)} in the
596 * {@link Action}.
597 * <dl>
598 * <dt><b>Scheduler:</b></dt>
599 * <dd>{@code fromFuture} does not operate by default on a particular {@link Scheduler}.</dd>
600 * </dl>
601 * @param future the {@code Future} to react to
602 * @return the new {@code Completable} instance
603 * @throws NullPointerException if {@code future} is {@code null}
604 */
605 @CheckReturnValue
606 @NonNull
607 @SchedulerSupport(SchedulerSupport.NONE)
608 public static Completable fromFuture(@NonNull Future<?> future) {
609 Objects.requireNonNull(future, "future is null");
610 return fromAction(Functions.futureAction(future));
611 }
612
613 /**
614 * Returns a {@code Completable} instance that when subscribed to, subscribes to the {@link MaybeSource} instance and
615 * emits an {@code onComplete} event if the maybe emits {@code onSuccess}/{@code onComplete} or forwards any
616 * {@code onError} events.
617 * <p>
618 * <img width="640" height="235" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Completable.fromMaybe.png" alt="">
619 * <dl>
620 * <dt><b>Scheduler:</b></dt>
621 * <dd>{@code fromMaybe} does not operate by default on a particular {@link Scheduler}.</dd>
622 * </dl>
623 * <p>History: 2.1.17 - beta
624 * @param <T> the value type of the {@code MaybeSource} element
625 * @param maybe the {@code MaybeSource} instance to subscribe to, not {@code null}
626 * @return the new {@code Completable} instance
627 * @throws NullPointerException if {@code maybe} is {@code null}
628 * @since 2.2
629 */
630 @CheckReturnValue
631 @NonNull
632 @SchedulerSupport(SchedulerSupport.NONE)
633 public static <@NonNull T> Completable fromMaybe(@NonNull MaybeSource<T> maybe) {
634 Objects.requireNonNull(maybe, "maybe is null");
635 return RxJavaPlugins.onAssembly(new MaybeIgnoreElementCompletable<>(maybe));
636 }
637
638 /**
639 * Returns a {@code Completable} instance that runs the given {@link Runnable} for each {@link CompletableObserver} and
640 * emits either its unchecked exception or simply completes.
641 * <p>
642 * <img width="640" height="297" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Completable.fromRunnable.png" alt="">
643 * <p>
644 * If the code to be wrapped needs to throw a checked or more broader {@link Throwable} exception, that
645 * exception has to be converted to an unchecked exception by the wrapped code itself. Alternatively,
646 * use the {@link #fromAction(Action)} method which allows the wrapped code to throw any {@code Throwable}
647 * exception and will signal it to observers as-is.
648 * <dl>
649 * <dt><b>Scheduler:</b></dt>
650 * <dd>{@code fromRunnable} does not operate by default on a particular {@link Scheduler}.</dd>
651 * <dt><b>Error handling:</b></dt>
652 * <dd> If the {@code Runnable} throws an exception, the respective {@code Throwable} is
653 * delivered to the downstream via {@link CompletableObserver#onError(Throwable)},
654 * except when the downstream has disposed this {@code Completable} source.
655 * In this latter case, the {@code Throwable} is delivered to the global error handler via
656 * {@link RxJavaPlugins#onError(Throwable)} as an {@link io.reactivex.rxjava3.exceptions.UndeliverableException UndeliverableException}.
657 * </dd>
658 * </dl>
659 * @param run the {@code Runnable} to run for each {@code CompletableObserver}
660 * @return the new {@code Completable} instance
661 * @throws NullPointerException if {@code run} is {@code null}
662 * @see #fromAction(Action)
663 */
664 @CheckReturnValue
665 @NonNull
666 @SchedulerSupport(SchedulerSupport.NONE)
667 public static Completable fromRunnable(@NonNull Runnable run) {
668 Objects.requireNonNull(run, "run is null");
669 return RxJavaPlugins.onAssembly(new CompletableFromRunnable(run));
670 }
671
672 /**
673 * Returns a {@code Completable} instance that subscribes to the given {@link ObservableSource}, ignores all values and
674 * emits only the terminal event.
675 * <p>
676 * <img width="640" height="414" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Completable.fromObservable.png" alt="">
677 * <dl>
678 * <dt><b>Scheduler:</b></dt>
679 * <dd>{@code fromObservable} does not operate by default on a particular {@link Scheduler}.</dd>
680 * </dl>
681 * @param <T> the type of the {@code ObservableSource}
682 * @param observable the {@code ObservableSource} instance to subscribe to, not {@code null}
683 * @return the new {@code Completable} instance
684 * @throws NullPointerException if {@code observable} is {@code null}
685 */
686 @CheckReturnValue
687 @NonNull
688 @SchedulerSupport(SchedulerSupport.NONE)
689 public static <@NonNull T> Completable fromObservable(@NonNull ObservableSource<T> observable) {
690 Objects.requireNonNull(observable, "observable is null");
691 return RxJavaPlugins.onAssembly(new CompletableFromObservable<>(observable));
692 }
693
694 /**
695 * Returns a {@code Completable} instance that subscribes to the given {@link Publisher}, ignores all values and
696 * emits only the terminal event.
697 * <p>
698 * <img width="640" height="422" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Completable.fromPublisher.png" alt="">
699 * <p>
700 * The {@code Publisher} must follow the
701 * <a href="https://github.com/reactive-streams/reactive-streams-jvm#reactive-streams">Reactive-Streams specification</a>.
702 * Violating the specification may result in undefined behavior.
703 * <p>
704 * If possible, use {@link #create(CompletableOnSubscribe)} to create a
705 * source-like {@code Completable} instead.
706 * <p>
707 * Note that even though {@code Publisher} appears to be a functional interface, it
708 * is not recommended to implement it through a lambda as the specification requires
709 * state management that is not achievable with a stateless lambda.
710 * <dl>
711 * <dt><b>Backpressure:</b></dt>
712 * <dd>The returned {@code Completable} honors the backpressure of the downstream consumer
713 * and expects the other {@code Publisher} to honor it as well.</dd>
714 * <dt><b>Scheduler:</b></dt>
715 * <dd>{@code fromPublisher} does not operate by default on a particular {@link Scheduler}.</dd>
716 * </dl>
717 * @param <T> the type of the {@code Publisher}
718 * @param publisher the {@code Publisher} instance to subscribe to, not {@code null}
719 * @return the new {@code Completable} instance
720 * @throws NullPointerException if {@code publisher} is {@code null}
721 * @see #create(CompletableOnSubscribe)
722 */
723 @CheckReturnValue
724 @NonNull
725 @BackpressureSupport(BackpressureKind.UNBOUNDED_IN)
726 @SchedulerSupport(SchedulerSupport.NONE)
727 public static <@NonNull T> Completable fromPublisher(@NonNull Publisher<T> publisher) {
728 Objects.requireNonNull(publisher, "publisher is null");
729 return RxJavaPlugins.onAssembly(new CompletableFromPublisher<>(publisher));
730 }
731
732 /**
733 * Returns a {@code Completable} instance that when subscribed to, subscribes to the {@link SingleSource} instance and
734 * emits a completion event if the single emits {@code onSuccess} or forwards any {@code onError} events.
735 * <p>
736 * <img width="640" height="356" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Completable.fromSingle.png" alt="">
737 * <dl>
738 * <dt><b>Scheduler:</b></dt>
739 * <dd>{@code fromSingle} does not operate by default on a particular {@link Scheduler}.</dd>
740 * </dl>
741 * @param <T> the value type of the {@code SingleSource}
742 * @param single the {@code SingleSource} instance to subscribe to, not {@code null}
743 * @return the new {@code Completable} instance
744 * @throws NullPointerException if {@code single} is {@code null}
745 */
746 @CheckReturnValue
747 @NonNull
748 @SchedulerSupport(SchedulerSupport.NONE)
749 public static <@NonNull T> Completable fromSingle(@NonNull SingleSource<T> single) {
750 Objects.requireNonNull(single, "single is null");
751 return RxJavaPlugins.onAssembly(new CompletableFromSingle<>(single));
752 }
753
754 /**
755 * Returns a {@code Completable} which when subscribed, executes the {@link Supplier} function, ignores its
756 * normal result and emits {@code onError} or {@code onComplete} only.
757 * <p>
758 * <img width="640" height="286" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Completable.fromSupplier.png" alt="">
759 * <dl>
760 * <dt><b>Scheduler:</b></dt>
761 * <dd>{@code fromSupplier} does not operate by default on a particular {@link Scheduler}.</dd>
762 * <dt><b>Error handling:</b></dt>
763 * <dd> If the {@code Supplier} throws an exception, the respective {@link Throwable} is
764 * delivered to the downstream via {@link CompletableObserver#onError(Throwable)},
765 * except when the downstream has disposed this {@code Completable} source.
766 * In this latter case, the {@code Throwable} is delivered to the global error handler via
767 * {@link RxJavaPlugins#onError(Throwable)} as an {@link io.reactivex.rxjava3.exceptions.UndeliverableException UndeliverableException}.
768 * </dd>
769 * </dl>
770 * @param supplier the {@code Supplier} instance to execute for each {@link CompletableObserver}
771 * @return the new {@code Completable} instance
772 * @throws NullPointerException if {@code supplier} is {@code null}
773 * @see #defer(Supplier)
774 * @see #fromCallable(Callable)
775 * @since 3.0.0
776 */
777 @CheckReturnValue
778 @NonNull
779 @SchedulerSupport(SchedulerSupport.NONE)
780 public static Completable fromSupplier(@NonNull Supplier<?> supplier) {
781 Objects.requireNonNull(supplier, "supplier is null");
782 return RxJavaPlugins.onAssembly(new CompletableFromSupplier(supplier));
783 }
784
785 /**
786 * Returns a {@code Completable} instance that subscribes to all sources at once and
787 * completes only when all source {@link CompletableSource}s complete or one of them emits an error.
788 * <p>
789 * <img width="640" height="270" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Completable.mergeArray.png" alt="">
790 * <dl>
791 * <dt><b>Scheduler:</b></dt>
792 * <dd>{@code mergeArray} does not operate by default on a particular {@link Scheduler}.</dd>
793 * <dt><b>Error handling:</b></dt>
794 * <dd>If any of the source {@code CompletableSource}s signal a {@link Throwable} via {@code onError}, the resulting
795 * {@code Completable} terminates with that {@code Throwable} and all other source {@code CompletableSource}s are disposed.
796 * If more than one {@code CompletableSource} signals an error, the resulting {@code Completable} may terminate with the
797 * first one's error or, depending on the concurrency of the sources, may terminate with a
798 * {@link CompositeException} containing two or more of the various error signals.
799 * {@code Throwable}s that didn't make into the composite will be sent (individually) to the global error handler via
800 * {@link RxJavaPlugins#onError(Throwable)} method as {@link UndeliverableException} errors. Similarly, {@code Throwable}s
801 * signaled by source(s) after the returned {@code Completable} has been disposed or terminated with a
802 * (composite) error will be sent to the same global error handler.
803 * Use {@link #mergeArrayDelayError(CompletableSource...)} to merge sources and terminate only when all source {@code CompletableSource}s
804 * have completed or failed with an error.
805 * </dd>
806 * </dl>
807 * @param sources the array of {@code CompletableSource}s.
808 * @return the new {@code Completable} instance
809 * @throws NullPointerException if {@code sources} is {@code null}
810 * @see #mergeArrayDelayError(CompletableSource...)
811 */
812 @CheckReturnValue
813 @NonNull
814 @SchedulerSupport(SchedulerSupport.NONE)
815 @SafeVarargs
816 public static Completable mergeArray(@NonNull CompletableSource... sources) {
817 Objects.requireNonNull(sources, "sources is null");
818 if (sources.length == 0) {
819 return complete();
820 } else
821 if (sources.length == 1) {
822 return wrap(sources[0]);
823 }
824 return RxJavaPlugins.onAssembly(new CompletableMergeArray(sources));
825 }
826
827 /**
828 * Returns a {@code Completable} instance that subscribes to all sources at once and
829 * completes only when all source {@link CompletableSource}s complete or one of them emits an error.
830 * <p>
831 * <img width="640" height="311" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Completable.merge.png" alt="">
832 * <dl>
833 * <dt><b>Scheduler:</b></dt>
834 * <dd>{@code merge} does not operate by default on a particular {@link Scheduler}.</dd>
835 * <dt><b>Error handling:</b></dt>
836 * <dd>If any of the source {@code CompletableSource}s signal a {@link Throwable} via {@code onError}, the resulting
837 * {@code Completable} terminates with that {@code Throwable} and all other source {@code CompletableSource}s are disposed.
838 * If more than one {@code CompletableSource} signals an error, the resulting {@code Completable} may terminate with the
839 * first one's error or, depending on the concurrency of the sources, may terminate with a
840 * {@link CompositeException} containing two or more of the various error signals.
841 * {@code Throwable}s that didn't make into the composite will be sent (individually) to the global error handler via
842 * {@link RxJavaPlugins#onError(Throwable)} method as {@link UndeliverableException} errors. Similarly, {@code Throwable}s
843 * signaled by source(s) after the returned {@code Completable} has been disposed or terminated with a
844 * (composite) error will be sent to the same global error handler.
845 * Use {@link #mergeDelayError(Iterable)} to merge sources and terminate only when all source {@code CompletableSource}s
846 * have completed or failed with an error.
847 * </dd>
848 * </dl>
849 * @param sources the {@link Iterable} sequence of {@code CompletableSource}s.
850 * @return the new {@code Completable} instance
851 * @throws NullPointerException if {@code sources} is {@code null}
852 * @see #mergeDelayError(Iterable)
853 */
854 @CheckReturnValue
855 @NonNull
856 @SchedulerSupport(SchedulerSupport.NONE)
857 public static Completable merge(@NonNull Iterable<@NonNull ? extends CompletableSource> sources) {
858 Objects.requireNonNull(sources, "sources is null");
859 return RxJavaPlugins.onAssembly(new CompletableMergeIterable(sources));
860 }
861
862 /**
863 * Returns a {@code Completable} instance that subscribes to all sources at once and
864 * completes only when all source {@link CompletableSource}s complete or one of them emits an error.
865 * <p>
866 * <img width="640" height="336" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Completable.merge.p.png" alt="">
867 * <dl>
868 * <dt><b>Backpressure:</b></dt>
869 * <dd>The operator consumes the given {@link Publisher} in an unbounded manner
870 * (requesting {@link Long#MAX_VALUE} upfront).</dd>
871 * <dt><b>Scheduler:</b></dt>
872 * <dd>{@code merge} does not operate by default on a particular {@link Scheduler}.</dd>
873 * <dt><b>Error handling:</b></dt>
874 * <dd>If any of the source {@code CompletableSource}s signal a {@link Throwable} via {@code onError}, the resulting
875 * {@code Completable} terminates with that {@code Throwable} and all other source {@code CompletableSource}s are disposed.
876 * If more than one {@code CompletableSource} signals an error, the resulting {@code Completable} may terminate with the
877 * first one's error or, depending on the concurrency of the sources, may terminate with a
878 * {@link CompositeException} containing two or more of the various error signals.
879 * {@code Throwable}s that didn't make into the composite will be sent (individually) to the global error handler via
880 * {@link RxJavaPlugins#onError(Throwable)} method as {@link UndeliverableException} errors. Similarly, {@code Throwable}s
881 * signaled by source(s) after the returned {@code Completable} has been disposed or terminated with a
882 * (composite) error will be sent to the same global error handler.
883 * Use {@link #mergeDelayError(Publisher)} to merge sources and terminate only when all source {@code CompletableSource}s
884 * have completed or failed with an error.
885 * </dd>
886 * </dl>
887 * @param sources the {@code Publisher} sequence of {@code CompletableSource}s.
888 * @return the new {@code Completable} instance
889 * @throws NullPointerException if {@code sources} is {@code null}
890 * @see #mergeDelayError(Publisher)
891 */
892 @CheckReturnValue
893 @SchedulerSupport(SchedulerSupport.NONE)
894 @BackpressureSupport(BackpressureKind.UNBOUNDED_IN)
895 @NonNull
896 public static Completable merge(@NonNull Publisher<@NonNull ? extends CompletableSource> sources) {
897 return merge0(sources, Integer.MAX_VALUE, false);
898 }
899
900 /**
901 * Returns a {@code Completable} instance that keeps subscriptions to a limited number of sources at once and
902 * completes only when all source {@link CompletableSource}s complete or one of them emits an error.
903 * <p>
904 * <img width="640" height="269" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Completable.merge.pn.png" alt="">
905 * <dl>
906 * <dt><b>Backpressure:</b></dt>
907 * <dd>The operator consumes the given {@link Publisher} in a bounded manner,
908 * requesting {@code maxConcurrency} items first, then keeps requesting as
909 * many more as the inner {@code CompletableSource}s terminate.</dd>
910 * <dt><b>Scheduler:</b></dt>
911 * <dd>{@code merge} does not operate by default on a particular {@link Scheduler}.</dd>
912 * <dt><b>Error handling:</b></dt>
913 * <dd>If any of the source {@code CompletableSource}s signal a {@link Throwable} via {@code onError}, the resulting
914 * {@code Completable} terminates with that {@code Throwable} and all other source {@code CompletableSource}s are disposed.
915 * If more than one {@code CompletableSource} signals an error, the resulting {@code Completable} may terminate with the
916 * first one's error or, depending on the concurrency of the sources, may terminate with a
917 * {@link CompositeException} containing two or more of the various error signals.
918 * {@code Throwable}s that didn't make into the composite will be sent (individually) to the global error handler via
919 * {@link RxJavaPlugins#onError(Throwable)} method as {@link UndeliverableException} errors. Similarly, {@code Throwable}s
920 * signaled by source(s) after the returned {@code Completable} has been disposed or terminated with a
921 * (composite) error will be sent to the same global error handler.
922 * Use {@link #mergeDelayError(Publisher, int)} to merge sources and terminate only when all source {@code CompletableSource}s
923 * have completed or failed with an error.
924 * </dd>
925 * </dl>
926 * @param sources the {@code Publisher} sequence of {@code CompletableSource}s.
927 * @param maxConcurrency the maximum number of concurrent subscriptions
928 * @return the new {@code Completable} instance
929 * @throws NullPointerException if {@code sources} is {@code null}
930 * @throws IllegalArgumentException if {@code maxConcurrency} is less than 1
931 * @see #mergeDelayError(Publisher, int)
932 */
933 @CheckReturnValue
934 @SchedulerSupport(SchedulerSupport.NONE)
935 @BackpressureSupport(BackpressureKind.FULL)
936 @NonNull
937 public static Completable merge(@NonNull Publisher<@NonNull ? extends CompletableSource> sources, int maxConcurrency) {
938 return merge0(sources, maxConcurrency, false);
939 }
940
941 /**
942 * Returns a {@code Completable} instance that keeps subscriptions to a limited number of {@link CompletableSource}s at once and
943 * completes only when all source {@code CompletableSource}s terminate in one way or another, combining any exceptions
944 * signaled by either the source {@link Publisher} or the inner {@code CompletableSource} instances.
945 * <dl>
946 * <dt><b>Backpressure:</b></dt>
947 * <dd>The operator consumes the given {@code Publisher} in a bounded manner,
948 * requesting {@code maxConcurrency} items first, then keeps requesting as
949 * many more as the inner {@code CompletableSource}s terminate.</dd>
950 * <dt><b>Scheduler:</b></dt>
951 * <dd>{@code merge0} does not operate by default on a particular {@link Scheduler}.</dd>
952 * </dl>
953 * @param sources the {@code Publisher} sequence of {@code CompletableSource}s.
954 * @param maxConcurrency the maximum number of concurrent subscriptions
955 * @param delayErrors delay all errors from the main source and from the inner {@code CompletableSource}s?
956 * @return the new {@code Completable} instance
957 * @throws NullPointerException if {@code sources} is {@code null}
958 * @throws IllegalArgumentException if {@code maxConcurrency} is less than 1
959 */
960 @CheckReturnValue
961 @NonNull
962 @SchedulerSupport(SchedulerSupport.NONE)
963 @BackpressureSupport(BackpressureKind.FULL)
964 private static Completable merge0(@NonNull Publisher<@NonNull ? extends CompletableSource> sources, int maxConcurrency, boolean delayErrors) {
965 Objects.requireNonNull(sources, "sources is null");
966 ObjectHelper.verifyPositive(maxConcurrency, "maxConcurrency");
967 return RxJavaPlugins.onAssembly(new CompletableMerge(sources, maxConcurrency, delayErrors));
968 }
969
970 /**
971 * Returns a {@code Completable} that subscribes to all {@link CompletableSource}s in the source array and delays
972 * any error emitted by any of the inner {@code CompletableSource}s until all of
973 * them terminate in a way or another.
974 * <p>
975 * <img width="640" height="430" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Completable.mergeArrayDelayError.png" alt="">
976 * <dl>
977 * <dt><b>Scheduler:</b></dt>
978 * <dd>{@code mergeArrayDelayError} does not operate by default on a particular {@link Scheduler}.</dd>
979 * </dl>
980 * @param sources the array of {@code CompletableSource}s
981 * @return the new {@code Completable} instance
982 * @throws NullPointerException if {@code sources} is {@code null}
983 */
984 @CheckReturnValue
985 @NonNull
986 @SchedulerSupport(SchedulerSupport.NONE)
987 @SafeVarargs
988 public static Completable mergeArrayDelayError(@NonNull CompletableSource... sources) {
989 Objects.requireNonNull(sources, "sources is null");
990 return RxJavaPlugins.onAssembly(new CompletableMergeArrayDelayError(sources));
991 }
992
993 /**
994 * Returns a {@code Completable} that subscribes to all {@link CompletableSource}s in the source sequence and delays
995 * any error emitted by any of the inner {@code CompletableSource}s until all of
996 * them terminate in a way or another.
997 * <p>
998 * <img width="640" height="476" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Completable.mergeDelayError.png" alt="">
999 * <dl>
1000 * <dt><b>Scheduler:</b></dt>
1001 * <dd>{@code mergeDelayError} does not operate by default on a particular {@link Scheduler}.</dd>
1002 * </dl>
1003 * @param sources the sequence of {@code CompletableSource}s
1004 * @return the new {@code Completable} instance
1005 * @throws NullPointerException if {@code sources} is {@code null}
1006 */
1007 @CheckReturnValue
1008 @NonNull
1009 @SchedulerSupport(SchedulerSupport.NONE)
1010 public static Completable mergeDelayError(@NonNull Iterable<@NonNull ? extends CompletableSource> sources) {
1011 Objects.requireNonNull(sources, "sources is null");
1012 return RxJavaPlugins.onAssembly(new CompletableMergeDelayErrorIterable(sources));
1013 }
1014
1015 /**
1016 * Returns a {@code Completable} that subscribes to all {@link CompletableSource}s in the source sequence and delays
1017 * any error emitted by either the sources {@link Publisher} or any of the inner {@code CompletableSource}s until all of
1018 * them terminate in a way or another.
1019 * <p>
1020 * <img width="640" height="466" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Completable.mergeDelayError.p.png" alt="">
1021 * <dl>
1022 * <dt><b>Backpressure:</b></dt>
1023 * <dd>The operator consumes the {@code Publisher} in an unbounded manner
1024 * (requesting {@link Long#MAX_VALUE} from it).</dd>
1025 * <dt><b>Scheduler:</b></dt>
1026 * <dd>{@code mergeDelayError} does not operate by default on a particular {@link Scheduler}.</dd>
1027 * </dl>
1028 * @param sources the sequence of {@code CompletableSource}s
1029 * @return the new {@code Completable} instance
1030 * @throws NullPointerException if {@code sources} is {@code null}
1031 */
1032 @CheckReturnValue
1033 @SchedulerSupport(SchedulerSupport.NONE)
1034 @BackpressureSupport(BackpressureKind.UNBOUNDED_IN)
1035 @NonNull
1036 public static Completable mergeDelayError(@NonNull Publisher<@NonNull ? extends CompletableSource> sources) {
1037 return merge0(sources, Integer.MAX_VALUE, true);
1038 }
1039
1040 /**
1041 * Returns a {@code Completable} that subscribes to a limited number of inner {@link CompletableSource}s at once in
1042 * the source sequence and delays any error emitted by either the sources
1043 * {@link Publisher} or any of the inner {@code CompletableSource}s until all of
1044 * them terminate in a way or another.
1045 * <p>
1046 * <img width="640" height="440" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Completable.mergeDelayError.pn.png" alt="">
1047 * <dl>
1048 * <dt><b>Backpressure:</b></dt>
1049 * <dd>The operator requests {@code maxConcurrency} items from the {@code Publisher}
1050 * upfront and keeps requesting as many more as many inner {@code CompletableSource}s terminate.</dd>
1051 * <dt><b>Scheduler:</b></dt>
1052 * <dd>{@code mergeDelayError} does not operate by default on a particular {@link Scheduler}.</dd>
1053 * </dl>
1054 * @param sources the sequence of {@code CompletableSource}s
1055 * @param maxConcurrency the maximum number of concurrent subscriptions to have
1056 * at a time to the inner {@code CompletableSource}s
1057 * @return the new {@code Completable} instance
1058 * @throws NullPointerException if {@code sources} is {@code null}
1059 * @throws IllegalArgumentException if {@code maxConcurrency} is non-positive
1060 */
1061 @CheckReturnValue
1062 @SchedulerSupport(SchedulerSupport.NONE)
1063 @BackpressureSupport(BackpressureKind.FULL)
1064 @NonNull
1065 public static Completable mergeDelayError(@NonNull Publisher<@NonNull ? extends CompletableSource> sources, int maxConcurrency) {
1066 return merge0(sources, maxConcurrency, true);
1067 }
1068
1069 /**
1070 * Returns a {@code Completable} that never calls {@code onError} or {@code onComplete}.
1071 * <p>
1072 * <img width="640" height="512" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Completable.never.png" alt="">
1073 * <dl>
1074 * <dt><b>Scheduler:</b></dt>
1075 * <dd>{@code never} does not operate by default on a particular {@link Scheduler}.</dd>
1076 * </dl>
1077 * @return the singleton instance that never calls {@code onError} or {@code onComplete}
1078 */
1079 @CheckReturnValue
1080 @SchedulerSupport(SchedulerSupport.NONE)
1081 @NonNull
1082 public static Completable never() {
1083 return RxJavaPlugins.onAssembly(CompletableNever.INSTANCE);
1084 }
1085
1086 /**
1087 * Returns a {@code Completable} instance that fires its {@code onComplete} event after the given delay elapsed.
1088 * <p>
1089 * <img width="640" height="413" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Completable.timer.png" alt="">
1090 * <dl>
1091 * <dt><b>Scheduler:</b></dt>
1092 * <dd>{@code timer} does operate by default on the {@code computation} {@link Scheduler}.</dd>
1093 * </dl>
1094 * @param delay the delay time
1095 * @param unit the delay unit
1096 * @return the new {@code Completable} instance
1097 * @throws NullPointerException if {@code unit} is {@code null}
1098 */
1099 @CheckReturnValue
1100 @SchedulerSupport(SchedulerSupport.COMPUTATION)
1101 @NonNull
1102 public static Completable timer(long delay, @NonNull TimeUnit unit) {
1103 return timer(delay, unit, Schedulers.computation());
1104 }
1105
1106 /**
1107 * Returns a {@code Completable} instance that fires its {@code onComplete} event after the given delay elapsed
1108 * by using the supplied {@link Scheduler}.
1109 * <p>
1110 * <img width="640" height="413" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Completable.timer.s.png" alt="">
1111 * <dl>
1112 * <dt><b>Scheduler:</b></dt>
1113 * <dd>{@code timer} operates on the {@code Scheduler} you specify.</dd>
1114 * </dl>
1115 * @param delay the delay time
1116 * @param unit the delay unit
1117 * @param scheduler the {@code Scheduler} where to emit the {@code onComplete} event
1118 * @return the new {@code Completable} instance
1119 * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null}
1120 */
1121 @CheckReturnValue
1122 @NonNull
1123 @SchedulerSupport(SchedulerSupport.CUSTOM)
1124 public static Completable timer(long delay, @NonNull TimeUnit unit, @NonNull Scheduler scheduler) {
1125 Objects.requireNonNull(unit, "unit is null");
1126 Objects.requireNonNull(scheduler, "scheduler is null");
1127 return RxJavaPlugins.onAssembly(new CompletableTimer(delay, unit, scheduler));
1128 }
1129
1130 /**
1131 * Creates a {@link NullPointerException} instance and sets the given {@link Throwable} as its initial cause.
1132 * @param ex the {@code Throwable} instance to use as cause, not {@code null} (not verified)
1133 * @return the new {@code NullPointerException}
1134 */
1135 private static NullPointerException toNpe(Throwable ex) {
1136 NullPointerException npe = new NullPointerException("Actually not, but can't pass out an exception otherwise...");
1137 npe.initCause(ex);
1138 return npe;
1139 }
1140
1141 /**
1142 * Switches between {@link CompletableSource}s emitted by the source {@link Publisher} whenever
1143 * a new {@code CompletableSource} is emitted, disposing the previously running {@code CompletableSource},
1144 * exposing the setup as a {@code Completable} sequence.
1145 * <p>
1146 * <img width="640" height="518" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Completable.switchOnNext.png" alt="">
1147 * <dl>
1148 * <dt><b>Backpressure:</b></dt>
1149 * <dd>The {@code sources} {@code Publisher} is consumed in an unbounded manner (requesting {@link Long#MAX_VALUE}).</dd>
1150 * <dt><b>Scheduler:</b></dt>
1151 * <dd>{@code switchOnNext} does not operate by default on a particular {@link Scheduler}.</dd>
1152 * <dt><b>Error handling:</b></dt>
1153 * <dd>The returned sequence fails with the first error signaled by the {@code sources} {@code Publisher}
1154 * or the currently running {@code CompletableSource}, disposing the rest. Late errors are
1155 * forwarded to the global error handler via {@link RxJavaPlugins#onError(Throwable)}.</dd>
1156 * </dl>
1157 * @param sources the {@code Publisher} sequence of inner {@code CompletableSource}s to switch between
1158 * @return the new {@code Completable} instance
1159 * @throws NullPointerException if {@code sources} is {@code null}
1160 * @since 3.0.0
1161 * @see #switchOnNextDelayError(Publisher)
1162 * @see <a href="http://reactivex.io/documentation/operators/switch.html">ReactiveX operators documentation: Switch</a>
1163 */
1164 @CheckReturnValue
1165 @NonNull
1166 @SchedulerSupport(SchedulerSupport.NONE)
1167 @BackpressureSupport(BackpressureKind.UNBOUNDED_IN)
1168 public static Completable switchOnNext(@NonNull Publisher<@NonNull ? extends CompletableSource> sources) {
1169 Objects.requireNonNull(sources, "sources is null");
1170 return RxJavaPlugins.onAssembly(new FlowableSwitchMapCompletablePublisher<>(sources, Functions.identity(), false));
1171 }
1172
1173 /**
1174 * Switches between {@link CompletableSource}s emitted by the source {@link Publisher} whenever
1175 * a new {@code CompletableSource} is emitted, disposing the previously running {@code CompletableSource},
1176 * exposing the setup as a {@code Completable} sequence and delaying all errors from
1177 * all of them until all terminate.
1178 * <p>
1179 * <img width="640" height="415" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Completable.switchOnNextDelayError.png" alt="">
1180 * <dl>
1181 * <dt><b>Backpressure:</b></dt>
1182 * <dd>The {@code sources} {@code Publisher} is consumed in an unbounded manner (requesting {@link Long#MAX_VALUE}).</dd>
1183 * <dt><b>Scheduler:</b></dt>
1184 * <dd>{@code switchOnNextDelayError} does not operate by default on a particular {@link Scheduler}.</dd>
1185 * <dt><b>Error handling:</b></dt>
1186 * <dd>The returned {@code Completable} collects all errors emitted by either the {@code sources}
1187 * {@code Publisher} or any inner {@code CompletableSource} and emits them as a {@link CompositeException}
1188 * when all sources terminate. If only one source ever failed, its error is emitted as-is at the end.</dd>
1189 * </dl>
1190 * @param sources the {@code Publisher} sequence of inner {@code CompletableSource}s to switch between
1191 * @return the new {@code Completable} instance
1192 * @throws NullPointerException if {@code sources} is {@code null}
1193 * @since 3.0.0
1194 * @see #switchOnNext(Publisher)
1195 * @see <a href="http://reactivex.io/documentation/operators/switch.html">ReactiveX operators documentation: Switch</a>
1196 */
1197 @CheckReturnValue
1198 @NonNull
1199 @SchedulerSupport(SchedulerSupport.NONE)
1200 @BackpressureSupport(BackpressureKind.UNBOUNDED_IN)
1201 public static Completable switchOnNextDelayError(@NonNull Publisher<@NonNull ? extends CompletableSource> sources) {
1202 Objects.requireNonNull(sources, "sources is null");
1203 return RxJavaPlugins.onAssembly(new FlowableSwitchMapCompletablePublisher<>(sources, Functions.identity(), true));
1204 }
1205
1206 /**
1207 * Returns a {@code Completable} instance which manages a resource along
1208 * with a custom {@link CompletableSource} instance while the subscription is active.
1209 * <p>
1210 * <img width="640" height="389" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Completable.using.png" alt="">
1211 * <p>
1212 * This overload disposes eagerly before the terminal event is emitted.
1213 * <dl>
1214 * <dt><b>Scheduler:</b></dt>
1215 * <dd>{@code using} does not operate by default on a particular {@link Scheduler}.</dd>
1216 * </dl>
1217 * @param <R> the resource type
1218 * @param resourceSupplier the {@link Supplier} that returns a resource to be managed.
1219 * @param sourceSupplier the {@link Function} that given a resource returns a {@code CompletableSource} instance that will be subscribed to
1220 * @param resourceCleanup the {@link Consumer} that disposes the resource created by the resource supplier
1221 * @return the new {@code Completable} instance
1222 * @throws NullPointerException if {@code resourceSupplier}, {@code sourceSupplier}
1223 * or {@code resourceCleanup} is {@code null}
1224 */
1225 @CheckReturnValue
1226 @SchedulerSupport(SchedulerSupport.NONE)
1227 @NonNull
1228 public static <@NonNull R> Completable using(@NonNull Supplier<R> resourceSupplier,
1229 @NonNull Function<? super R, ? extends CompletableSource> sourceSupplier,
1230 @NonNull Consumer<? super R> resourceCleanup) {
1231 return using(resourceSupplier, sourceSupplier, resourceCleanup, true);
1232 }
1233
1234 /**
1235 * Returns a {@code Completable} instance which manages a resource along
1236 * with a custom {@link CompletableSource} instance while the subscription is active and performs eager or lazy
1237 * resource disposition.
1238 * <p>
1239 * <img width="640" height="332" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Completable.using.b.png" alt="">
1240 * <p>
1241 * If this overload performs a lazy disposal after the terminal event is emitted.
1242 * The exceptions thrown at this time will be delivered to the global {@link RxJavaPlugins#onError(Throwable)} handler only.
1243 * <dl>
1244 * <dt><b>Scheduler:</b></dt>
1245 * <dd>{@code using} does not operate by default on a particular {@link Scheduler}.</dd>
1246 * </dl>
1247 * @param <R> the resource type
1248 * @param resourceSupplier the {@link Supplier} that returns a resource to be managed
1249 * @param sourceSupplier the {@link Function} that given a resource returns a non-{@code null}
1250 * {@code CompletableSource} instance that will be subscribed to
1251 * @param resourceCleanup the {@link Consumer} that disposes the resource created by the resource supplier
1252 * @param eager
1253 * If {@code true} then resource disposal will happen either on a {@code dispose()} call before the upstream is disposed
1254 * or just before the emission of a terminal event ({@code onComplete} or {@code onError}).
1255 * If {@code false} the resource disposal will happen either on a {@code dispose()} call after the upstream is disposed
1256 * or just after the emission of a terminal event ({@code onComplete} or {@code onError}).
1257 * @return the new {@code Completable} instance
1258 * @throws NullPointerException if {@code resourceSupplier}, {@code sourceSupplier}
1259 * or {@code resourceCleanup} is {@code null}
1260 */
1261 @CheckReturnValue
1262 @NonNull
1263 @SchedulerSupport(SchedulerSupport.NONE)
1264 public static <@NonNull R> Completable using(
1265 @NonNull Supplier<R> resourceSupplier,
1266 @NonNull Function<? super R, ? extends CompletableSource> sourceSupplier,
1267 @NonNull Consumer<? super R> resourceCleanup,
1268 boolean eager) {
1269 Objects.requireNonNull(resourceSupplier, "resourceSupplier is null");
1270 Objects.requireNonNull(sourceSupplier, "sourceSupplier is null");
1271 Objects.requireNonNull(resourceCleanup, "resourceCleanup is null");
1272
1273 return RxJavaPlugins.onAssembly(new CompletableUsing<>(resourceSupplier, sourceSupplier, resourceCleanup, eager));
1274 }
1275
1276 /**
1277 * Wraps the given {@link CompletableSource} into a {@code Completable}
1278 * if not already {@code Completable}.
1279 * <p>
1280 * <img width="640" height="354" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Completable.wrap.png" alt="">
1281 * <dl>
1282 * <dt><b>Scheduler:</b></dt>
1283 * <dd>{@code wrap} does not operate by default on a particular {@link Scheduler}.</dd>
1284 * </dl>
1285 * @param source the source to wrap
1286 * @return the new wrapped or cast {@code Completable} instance
1287 * @throws NullPointerException if {@code source} is {@code null}
1288 */
1289 @CheckReturnValue
1290 @NonNull
1291 @SchedulerSupport(SchedulerSupport.NONE)
1292 public static Completable wrap(@NonNull CompletableSource source) {
1293 Objects.requireNonNull(source, "source is null");
1294 if (source instanceof Completable) {
1295 return RxJavaPlugins.onAssembly((Completable)source);
1296 }
1297 return RxJavaPlugins.onAssembly(new CompletableFromUnsafeSource(source));
1298 }
1299
1300 /**
1301 * Returns a {@code Completable} that emits the a terminated event of either this {@code Completable}
1302 * or the other {@link CompletableSource}, whichever fires first.
1303 * <p>
1304 * <img width="640" height="485" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Completable.ambWith.png" alt="">
1305 * <dl>
1306 * <dt><b>Scheduler:</b></dt>
1307 * <dd>{@code ambWith} does not operate by default on a particular {@link Scheduler}.</dd>
1308 * </dl>
1309 * @param other the other {@code CompletableSource}, not {@code null}. A subscription to this provided source will occur after subscribing
1310 * to the current source.
1311 * @return the new {@code Completable} instance
1312 * @throws NullPointerException if {@code other} is {@code null}
1313 */
1314 @CheckReturnValue
1315 @NonNull
1316 @SchedulerSupport(SchedulerSupport.NONE)
1317 public final Completable ambWith(@NonNull CompletableSource other) {
1318 Objects.requireNonNull(other, "other is null");
1319 return ambArray(this, other);
1320 }
1321
1322 /**
1323 * Returns an {@link Observable} which will subscribe to this {@code Completable} and once that is completed then
1324 * will subscribe to the {@code next} {@link ObservableSource}. An error event from this {@code Completable} will be
1325 * propagated to the downstream observer and will result in skipping the subscription to the
1326 * next {@code ObservableSource}.
1327 * <p>
1328 * <img width="640" height="278" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Completable.andThen.o.png" alt="">
1329 * <dl>
1330 * <dt><b>Scheduler:</b></dt>
1331 * <dd>{@code andThen} does not operate by default on a particular {@link Scheduler}.</dd>
1332 * </dl>
1333 * @param <T> the value type of the next {@code ObservableSource}
1334 * @param next the {@code ObservableSource} to subscribe after this {@code Completable} is completed, not {@code null}
1335 * @return the new {@code Observable} that composes this {@code Completable} and the next {@code ObservableSource}
1336 * @throws NullPointerException if {@code next} is {@code null}
1337 */
1338 @CheckReturnValue
1339 @NonNull
1340 @SchedulerSupport(SchedulerSupport.NONE)
1341 public final <@NonNull T> Observable<T> andThen(@NonNull ObservableSource<T> next) {
1342 Objects.requireNonNull(next, "next is null");
1343 return RxJavaPlugins.onAssembly(new CompletableAndThenObservable<>(this, next));
1344 }
1345
1346 /**
1347 * Returns a {@link Flowable} which will subscribe to this {@code Completable} and once that is completed then
1348 * will subscribe to the {@code next} {@link Publisher}. An error event from this {@code Completable} will be
1349 * propagated to the downstream subscriber and will result in skipping the subscription to the next
1350 * {@code Publisher}.
1351 * <p>
1352 * <img width="640" height="249" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Completable.andThen.p.png" alt="">
1353 * <dl>
1354 * <dt><b>Backpressure:</b></dt>
1355 * <dd>The returned {@code Flowable} honors the backpressure of the downstream consumer
1356 * and expects the other {@code Publisher} to honor it as well.</dd>
1357 * <dt><b>Scheduler:</b></dt>
1358 * <dd>{@code andThen} does not operate by default on a particular {@link Scheduler}.</dd>
1359 * </dl>
1360 * @param <T> the value type of the next {@code Publisher}
1361 * @param next the {@code Publisher} to subscribe after this {@code Completable} is completed, not {@code null}
1362 * @return the new {@code Flowable} that composes this {@code Completable} and the next {@code Publisher}
1363 * @throws NullPointerException if {@code next} is {@code null}
1364 */
1365 @CheckReturnValue
1366 @NonNull
1367 @BackpressureSupport(BackpressureKind.FULL)
1368 @SchedulerSupport(SchedulerSupport.NONE)
1369 public final <@NonNull T> Flowable<T> andThen(@NonNull Publisher<T> next) {
1370 Objects.requireNonNull(next, "next is null");
1371 return RxJavaPlugins.onAssembly(new CompletableAndThenPublisher<>(this, next));
1372 }
1373
1374 /**
1375 * Returns a {@link Single} which will subscribe to this {@code Completable} and once that is completed then
1376 * will subscribe to the {@code next} {@link SingleSource}. An error event from this {@code Completable} will be
1377 * propagated to the downstream observer and will result in skipping the subscription to the next
1378 * {@code SingleSource}.
1379 * <p>
1380 * <img width="640" height="437" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Completable.andThen.s.png" alt="">
1381 * <dl>
1382 * <dt><b>Scheduler:</b></dt>
1383 * <dd>{@code andThen} does not operate by default on a particular {@link Scheduler}.</dd>
1384 * </dl>
1385 *
1386 * @param <T> the value type of the next {@code SingleSource}
1387 * @param next the {@code SingleSource} to subscribe after this {@code Completable} is completed, not {@code null}
1388 * @return the new {@code Single} that composes this {@code Completable} and the next {@code SingleSource}
1389 * @throws NullPointerException if {@code next} is {@code null}
1390 */
1391 @CheckReturnValue
1392 @NonNull
1393 @SchedulerSupport(SchedulerSupport.NONE)
1394 public final <@NonNull T> Single<T> andThen(@NonNull SingleSource<T> next) {
1395 Objects.requireNonNull(next, "next is null");
1396 return RxJavaPlugins.onAssembly(new SingleDelayWithCompletable<>(next, this));
1397 }
1398
1399 /**
1400 * Returns a {@link Maybe} which will subscribe to this {@code Completable} and once that is completed then
1401 * will subscribe to the {@code next} {@link MaybeSource}. An error event from this {@code Completable} will be
1402 * propagated to the downstream observer and will result in skipping the subscription to the next
1403 * {@code MaybeSource}.
1404 * <p>
1405 * <img width="640" height="281" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Completable.andThen.m.png" alt="">
1406 * <dl>
1407 * <dt><b>Scheduler:</b></dt>
1408 * <dd>{@code andThen} does not operate by default on a particular {@link Scheduler}.</dd>
1409 * </dl>
1410 *
1411 * @param <T> the value type of the next {@code MaybeSource}
1412 * @param next the {@code MaybeSource} to subscribe after this {@code Completable} is completed, not {@code null}
1413 * @return the new {@code Maybe} that composes this {@code Completable} and the next {@code MaybeSource}
1414 * @throws NullPointerException if {@code next} is {@code null}
1415 */
1416 @CheckReturnValue
1417 @NonNull
1418 @SchedulerSupport(SchedulerSupport.NONE)
1419 public final <@NonNull T> Maybe<T> andThen(@NonNull MaybeSource<T> next) {
1420 Objects.requireNonNull(next, "next is null");
1421 return RxJavaPlugins.onAssembly(new MaybeDelayWithCompletable<>(next, this));
1422 }
1423
1424 /**
1425 * Returns a {@code Completable} that first runs this {@code Completable}
1426 * and then the other {@link CompletableSource}. An error event from this {@code Completable} will be
1427 * propagated to the downstream observer and will result in skipping the subscription to the next
1428 * {@code CompletableSource}.
1429 * <p>
1430 * <img width="640" height="437" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Completable.andThen.c.png" alt="">
1431 * <p>
1432 * This is an alias for {@link #concatWith(CompletableSource)}.
1433 * <dl>
1434 * <dt><b>Scheduler:</b></dt>
1435 * <dd>{@code andThen} does not operate by default on a particular {@link Scheduler}.</dd>
1436 * </dl>
1437 * @param next the other {@code CompletableSource}, not {@code null}
1438 * @return the new {@code Completable} instance
1439 * @throws NullPointerException if {@code next} is {@code null}
1440 */
1441 @CheckReturnValue
1442 @SchedulerSupport(SchedulerSupport.NONE)
1443 @NonNull
1444 public final Completable andThen(@NonNull CompletableSource next) {
1445 Objects.requireNonNull(next, "next is null");
1446 return RxJavaPlugins.onAssembly(new CompletableAndThenCompletable(this, next));
1447 }
1448
1449 /**
1450 * Subscribes to and awaits the termination of this {@code Completable} instance in a blocking manner and
1451 * rethrows any exception emitted.
1452 * <p>
1453 * <img width="640" height="433" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Completable.blockingAwait.png" alt="">
1454 * <dl>
1455 * <dt><b>Scheduler:</b></dt>
1456 * <dd>{@code blockingAwait} does not operate by default on a particular {@link Scheduler}.</dd>
1457 * <dt><b>Error handling:</b></dt>
1458 * <dd>If the source signals an error, the operator wraps a checked {@link Exception}
1459 * into {@link RuntimeException} and throws that. Otherwise, {@code RuntimeException}s and
1460 * {@link Error}s are rethrown as they are.</dd>
1461 * </dl>
1462 * @throws RuntimeException wrapping an {@link InterruptedException} if the current thread is interrupted
1463 */
1464 @SchedulerSupport(SchedulerSupport.NONE)
1465 public final void blockingAwait() {
1466 BlockingMultiObserver<Void> observer = new BlockingMultiObserver<>();
1467 subscribe(observer);
1468 observer.blockingGet();
1469 }
1470
1471 /**
1472 * Subscribes to and awaits the termination of this {@code Completable} instance in a blocking manner
1473 * with a specific timeout and rethrows any exception emitted within the timeout window.
1474 * <p>
1475 * <img width="640" height="348" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Completable.blockingAwait.t.png" alt="">
1476 * <dl>
1477 * <dt><b>Scheduler:</b></dt>
1478 * <dd>{@code blockingAwait} does not operate by default on a particular {@link Scheduler}.</dd>
1479 * <dt><b>Error handling:</b></dt>
1480 * <dd>If the source signals an error, the operator wraps a checked {@link Exception}
1481 * into {@link RuntimeException} and throws that. Otherwise, {@code RuntimeException}s and
1482 * {@link Error}s are rethrown as they are.</dd>
1483 * </dl>
1484 * @param timeout the timeout value
1485 * @param unit the timeout unit
1486 * @return {@code true} if the this {@code Completable} instance completed normally within the time limit,
1487 * {@code false} if the timeout elapsed before this {@code Completable} terminated.
1488 * @throws RuntimeException wrapping an {@link InterruptedException} if the current thread is interrupted
1489 * @throws NullPointerException if {@code unit} is {@code null}
1490 */
1491 @CheckReturnValue
1492 @SchedulerSupport(SchedulerSupport.NONE)
1493 public final boolean blockingAwait(long timeout, @NonNull TimeUnit unit) {
1494 Objects.requireNonNull(unit, "unit is null");
1495 BlockingMultiObserver<Void> observer = new BlockingMultiObserver<>();
1496 subscribe(observer);
1497 return observer.blockingAwait(timeout, unit);
1498 }
1499
1500 /**
1501 * Subscribes to the current {@code Completable} and <em>blocks the current thread</em> until it terminates.
1502 * <p>
1503 * <img width="640" height="346" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Completable.blockingSubscribe.png" alt="">
1504 * <dl>
1505 * <dt><b>Scheduler:</b></dt>
1506 * <dd>{@code blockingSubscribe} does not operate by default on a particular {@link Scheduler}.</dd>
1507 * <dt><b>Error handling:</b></dt>
1508 * <dd>If the current {@code Completable} signals an error,
1509 * the {@link Throwable} is routed to the global error handler via {@link RxJavaPlugins#onError(Throwable)}.
1510 * If the current thread is interrupted, an {@link InterruptedException} is routed to the same global error handler.
1511 * </dd>
1512 * </dl>
1513 * @since 3.0.0
1514 * @see #blockingSubscribe(Action)
1515 * @see #blockingSubscribe(Action, Consumer)
1516 */
1517 @SchedulerSupport(SchedulerSupport.NONE)
1518 public final void blockingSubscribe() {
1519 blockingSubscribe(Functions.EMPTY_ACTION, Functions.ERROR_CONSUMER);
1520 }
1521
1522 /**
1523 * Subscribes to the current {@code Completable} and calls given {@code onComplete} callback on the <em>current thread</em>
1524 * when it completes normally.
1525 * <p>
1526 * <img width="640" height="351" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Completable.blockingSubscribe.a.png" alt="">
1527 * <dl>
1528 * <dt><b>Scheduler:</b></dt>
1529 * <dd>{@code blockingSubscribe} does not operate by default on a particular {@link Scheduler}.</dd>
1530 * <dt><b>Error handling:</b></dt>
1531 * <dd>If either the current {@code Completable} signals an error or {@code onComplete} throws,
1532 * the respective {@link Throwable} is routed to the global error handler via {@link RxJavaPlugins#onError(Throwable)}.
1533 * If the current thread is interrupted, an {@link InterruptedException} is routed to the same global error handler.
1534 * </dd>
1535 * </dl>
1536 * @param onComplete the {@link Action} to call if the current {@code Completable} completes normally
1537 * @throws NullPointerException if {@code onComplete} is {@code null}
1538 * @since 3.0.0
1539 * @see #blockingSubscribe(Action, Consumer)
1540 */
1541 @SchedulerSupport(SchedulerSupport.NONE)
1542 public final void blockingSubscribe(@NonNull Action onComplete) {
1543 blockingSubscribe(onComplete, Functions.ERROR_CONSUMER);
1544 }
1545
1546 /**
1547 * Subscribes to the current {@code Completable} and calls the appropriate callback on the <em>current thread</em>
1548 * when it terminates.
1549 * <p>
1550 * <img width="640" height="352" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Completable.blockingSubscribe.ac.png" alt="">
1551 * <dl>
1552 * <dt><b>Scheduler:</b></dt>
1553 * <dd>{@code blockingSubscribe} does not operate by default on a particular {@link Scheduler}.</dd>
1554 * <dt><b>Error handling:</b></dt>
1555 * <dd>If either {@code onComplete} or {@code onError} throw, the {@link Throwable} is routed to the
1556 * global error handler via {@link RxJavaPlugins#onError(Throwable)}.
1557 * If the current thread is interrupted, the {@code onError} consumer is called with an {@link InterruptedException}.
1558 * </dd>
1559 * </dl>
1560 * @param onComplete the {@link Action} to call if the current {@code Completable} completes normally
1561 * @param onError the {@link Consumer} to call if the current {@code Completable} signals an error
1562 * @throws NullPointerException if {@code onComplete} or {@code onError} is {@code null}
1563 * @since 3.0.0
1564 */
1565 @SchedulerSupport(SchedulerSupport.NONE)
1566 public final void blockingSubscribe(@NonNull Action onComplete, @NonNull Consumer<? super Throwable> onError) {
1567 Objects.requireNonNull(onComplete, "onComplete is null");
1568 Objects.requireNonNull(onError, "onError is null");
1569 BlockingMultiObserver<Void> observer = new BlockingMultiObserver<>();
1570 subscribe(observer);
1571 observer.blockingConsume(Functions.emptyConsumer(), onError, onComplete);
1572 }
1573
1574 /**
1575 * Subscribes to the current {@code Completable} and calls the appropriate {@link CompletableObserver} method on the <em>current thread</em>.
1576 * <p>
1577 * <img width="640" height="468" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Completable.blockingSubscribe.o.png" alt="">
1578 * <dl>
1579 * <dt><b>Scheduler:</b></dt>
1580 * <dd>{@code blockingSubscribe} does not operate by default on a particular {@link Scheduler}.</dd>
1581 * <dt><b>Error handling:</b></dt>
1582 * <dd>An {@code onError} signal is delivered to the {@link CompletableObserver#onError(Throwable)} method.
1583 * If any of the {@code CompletableObserver}'s methods throw, the {@link RuntimeException} is propagated to the caller of this method.
1584 * If the current thread is interrupted, an {@link InterruptedException} is delivered to {@code observer.onError}.
1585 * </dd>
1586 * </dl>
1587 * @param observer the {@code CompletableObserver} to call methods on the current thread
1588 * @throws NullPointerException if {@code observer} is {@code null}
1589 * @since 3.0.0
1590 */
1591 @SchedulerSupport(SchedulerSupport.NONE)
1592 public final void blockingSubscribe(@NonNull CompletableObserver observer) {
1593 Objects.requireNonNull(observer, "observer is null");
1594 BlockingDisposableMultiObserver<Void> blockingObserver = new BlockingDisposableMultiObserver<>();
1595 observer.onSubscribe(blockingObserver);
1596 subscribe(blockingObserver);
1597 blockingObserver.blockingConsume(observer);
1598 }
1599
1600 /**
1601 * Subscribes to this {@code Completable} only once, when the first {@link CompletableObserver}
1602 * subscribes to the result {@code Completable}, caches its terminal event
1603 * and relays/replays it to observers.
1604 * <p>
1605 * <img width="640" height="375" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Completable.cache.png" alt="">
1606 * <p>
1607 * Note that this operator doesn't allow disposing the connection
1608 * of the upstream source.
1609 * <dl>
1610 * <dt><b>Scheduler:</b></dt>
1611 * <dd>{@code cache} does not operate by default on a particular {@link Scheduler}.</dd>
1612 * </dl>
1613 * <p>History: 2.0.4 - experimental
1614 * @return the new {@code Completable} instance
1615 * @since 2.1
1616 */
1617 @CheckReturnValue
1618 @SchedulerSupport(SchedulerSupport.NONE)
1619 @NonNull
1620 public final Completable cache() {
1621 return RxJavaPlugins.onAssembly(new CompletableCache(this));
1622 }
1623
1624 /**
1625 * Calls the given transformer function with this instance and returns the function's resulting
1626 * {@link CompletableSource} wrapped with {@link #wrap(CompletableSource)}.
1627 * <p>
1628 * <img width="640" height="625" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Completable.compose.png" alt="">
1629 * <dl>
1630 * <dt><b>Scheduler:</b></dt>
1631 * <dd>{@code compose} does not operate by default on a particular {@link Scheduler}.</dd>
1632 * </dl>
1633 * @param transformer the transformer function, not {@code null}
1634 * @return the new {@code Completable} instance
1635 * @throws NullPointerException if {@code transformer} is {@code null}
1636 */
1637 @CheckReturnValue
1638 @SchedulerSupport(SchedulerSupport.NONE)
1639 @NonNull
1640 public final Completable compose(@NonNull CompletableTransformer transformer) {
1641 return wrap(Objects.requireNonNull(transformer, "transformer is null").apply(this));
1642 }
1643
1644 /**
1645 * Concatenates this {@code Completable} with another {@link CompletableSource}.
1646 * An error event from this {@code Completable} will be
1647 * propagated to the downstream observer and will result in skipping the subscription to the next
1648 * {@code CompletableSource}.
1649 * <p>
1650 * <img width="640" height="317" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Completable.concatWith.png" alt="">
1651 * <dl>
1652 * <dt><b>Scheduler:</b></dt>
1653 * <dd>{@code concatWith} does not operate by default on a particular {@link Scheduler}.</dd>
1654 * </dl>
1655 * @param other the other {@code CompletableSource}, not {@code null}
1656 * @return the new {@code Completable} which subscribes to this and then the other {@code CompletableSource}
1657 * @throws NullPointerException if {@code other} is {@code null}
1658 * @see #andThen(CompletableSource)
1659 * @see #andThen(MaybeSource)
1660 * @see #andThen(ObservableSource)
1661 * @see #andThen(SingleSource)
1662 * @see #andThen(Publisher)
1663 */
1664 @CheckReturnValue
1665 @NonNull
1666 @SchedulerSupport(SchedulerSupport.NONE)
1667 public final Completable concatWith(@NonNull CompletableSource other) {
1668 Objects.requireNonNull(other, "other is null");
1669 return RxJavaPlugins.onAssembly(new CompletableAndThenCompletable(this, other));
1670 }
1671
1672 /**
1673 * Returns a {@code Completable} which delays the emission of the completion event by the given time.
1674 * <p>
1675 * <img width="640" height="344" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Completable.delay.png" alt="">
1676 * <dl>
1677 * <dt><b>Scheduler:</b></dt>
1678 * <dd>{@code delay} does operate by default on the {@code computation} {@link Scheduler}.</dd>
1679 * </dl>
1680 * @param time the delay time
1681 * @param unit the delay unit
1682 * @return the new {@code Completable} instance
1683 * @throws NullPointerException if {@code unit} is {@code null}
1684 */
1685 @CheckReturnValue
1686 @SchedulerSupport(SchedulerSupport.COMPUTATION)
1687 @NonNull
1688 public final Completable delay(long time, @NonNull TimeUnit unit) {
1689 return delay(time, unit, Schedulers.computation(), false);
1690 }
1691
1692 /**
1693 * Returns a {@code Completable} which delays the emission of the completion event by the given time while
1694 * running on the specified {@link Scheduler}.
1695 * <p>
1696 * <img width="640" height="313" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Completable.delay.s.png" alt="">
1697 * <dl>
1698 * <dt><b>Scheduler:</b></dt>
1699 * <dd>{@code delay} operates on the {@code Scheduler} you specify.</dd>
1700 * </dl>
1701 * @param time the delay time
1702 * @param unit the delay unit
1703 * @param scheduler the {@code Scheduler} to run the delayed completion on
1704 * @return the new {@code Completable} instance
1705 * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null}
1706 */
1707 @CheckReturnValue
1708 @SchedulerSupport(SchedulerSupport.CUSTOM)
1709 @NonNull
1710 public final Completable delay(long time, @NonNull TimeUnit unit, @NonNull Scheduler scheduler) {
1711 return delay(time, unit, scheduler, false);
1712 }
1713
1714 /**
1715 * Returns a {@code Completable} which delays the emission of the completion event, and optionally the error as well, by the given time while
1716 * running on the specified {@link Scheduler}.
1717 * <p>
1718 * <img width="640" height="253" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Completable.delay.sb.png" alt="">
1719 * <dl>
1720 * <dt><b>Scheduler:</b></dt>
1721 * <dd>{@code delay} operates on the {@code Scheduler} you specify.</dd>
1722 * </dl>
1723 * @param time the delay time
1724 * @param unit the delay unit
1725 * @param scheduler the {@code Scheduler} to run the delayed completion on
1726 * @param delayError delay the error emission as well?
1727 * @return the new {@code Completable} instance
1728 * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null}
1729 */
1730 @CheckReturnValue
1731 @NonNull
1732 @SchedulerSupport(SchedulerSupport.CUSTOM)
1733 public final Completable delay(long time, @NonNull TimeUnit unit, @NonNull Scheduler scheduler, boolean delayError) {
1734 Objects.requireNonNull(unit, "unit is null");
1735 Objects.requireNonNull(scheduler, "scheduler is null");
1736 return RxJavaPlugins.onAssembly(new CompletableDelay(this, time, unit, scheduler, delayError));
1737 }
1738
1739 /**
1740 * Returns a {@code Completable} that delays the subscription to the upstream by a given amount of time.
1741 * <p>
1742 * <img width="640" height="475" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Completable.delaySubscription.t.png" alt="">
1743 * <dl>
1744 * <dt><b>Scheduler:</b></dt>
1745 * <dd>This version of {@code delaySubscription} operates by default on the {@code computation} {@link Scheduler}.</dd>
1746 * </dl>
1747 * <p>History: 2.2.3 - experimental
1748 *
1749 * @param time the time to delay the subscription
1750 * @param unit the time unit of {@code delay}
1751 * @return the new {@code Completable} instance
1752 * @throws NullPointerException if {@code unit} is {@code null}
1753 * @since 3.0.0
1754 * @see <a href="http://reactivex.io/documentation/operators/delay.html">ReactiveX operators documentation: Delay</a>
1755 */
1756 @CheckReturnValue
1757 @SchedulerSupport(SchedulerSupport.COMPUTATION)
1758 @NonNull
1759 public final Completable delaySubscription(long time, @NonNull TimeUnit unit) {
1760 return delaySubscription(time, unit, Schedulers.computation());
1761 }
1762
1763 /**
1764 * Returns a {@code Completable} that delays the subscription to the upstream by a given amount of time,
1765 * both waiting and subscribing on a given {@link Scheduler}.
1766 * <p>
1767 * <img width="640" height="420" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Completable.delaySubscription.ts.png" alt="">
1768 * <dl>
1769 * <dt><b>Scheduler:</b></dt>
1770 * <dd>You specify which {@code Scheduler} this operator will use.</dd>
1771 * </dl>
1772 * <p>History: 2.2.3 - experimental
1773 * @param time the time to delay the subscription
1774 * @param unit the time unit of {@code delay}
1775 * @param scheduler the {@code Scheduler} on which the waiting and subscription will happen
1776 * @return the new {@code Completable} instance
1777 * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null}
1778 * @since 3.0.0
1779 * @see <a href="http://reactivex.io/documentation/operators/delay.html">ReactiveX operators documentation: Delay</a>
1780 */
1781 @CheckReturnValue
1782 @SchedulerSupport(SchedulerSupport.CUSTOM)
1783 @NonNull
1784 public final Completable delaySubscription(long time, @NonNull TimeUnit unit, @NonNull Scheduler scheduler) {
1785 return Completable.timer(time, unit, scheduler).andThen(this);
1786 }
1787
1788 /**
1789 * Returns a {@code Completable} which calls the given {@code onComplete} {@link Action} if this {@code Completable} completes.
1790 * <p>
1791 * <img width="640" height="304" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Completable.doOnComplete.png" alt="">
1792 * <dl>
1793 * <dt><b>Scheduler:</b></dt>
1794 * <dd>{@code doOnComplete} does not operate by default on a particular {@link Scheduler}.</dd>
1795 * </dl>
1796 * @param onComplete the {@code Action} to call when this emits an {@code onComplete} event
1797 * @return the new {@code Completable} instance
1798 * @throws NullPointerException if {@code onComplete} is {@code null}
1799 * @see #doFinally(Action)
1800 */
1801 @CheckReturnValue
1802 @SchedulerSupport(SchedulerSupport.NONE)
1803 @NonNull
1804 public final Completable doOnComplete(@NonNull Action onComplete) {
1805 return doOnLifecycle(Functions.emptyConsumer(), Functions.emptyConsumer(),
1806 onComplete, Functions.EMPTY_ACTION,
1807 Functions.EMPTY_ACTION, Functions.EMPTY_ACTION);
1808 }
1809
1810 /**
1811 * Calls the shared {@link Action} if a {@link CompletableObserver} subscribed to the current
1812 * {@code Completable} disposes the common {@link Disposable} it received via {@code onSubscribe}.
1813 * <p>
1814 * <img width="640" height="589" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Completable.doOnDispose.png" alt="">
1815 * <dl>
1816 * <dt><b>Scheduler:</b></dt>
1817 * <dd>{@code doOnDispose} does not operate by default on a particular {@link Scheduler}.</dd>
1818 * </dl>
1819 * @param onDispose the {@code Action} to call when the downstream observer disposes the subscription
1820 * @return the new {@code Completable} instance
1821 * @throws NullPointerException if {@code onDispose} is {@code null}
1822 */
1823 @CheckReturnValue
1824 @SchedulerSupport(SchedulerSupport.NONE)
1825 @NonNull
1826 public final Completable doOnDispose(@NonNull Action onDispose) {
1827 return doOnLifecycle(Functions.emptyConsumer(), Functions.emptyConsumer(),
1828 Functions.EMPTY_ACTION, Functions.EMPTY_ACTION,
1829 Functions.EMPTY_ACTION, onDispose);
1830 }
1831
1832 /**
1833 * Returns a {@code Completable} which calls the given {@code onError} {@link Consumer} if this {@code Completable} emits an error.
1834 * <p>
1835 * <img width="640" height="304" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Completable.doOnError.png" alt="">
1836 * <dl>
1837 * <dt><b>Scheduler:</b></dt>
1838 * <dd>{@code doOnError} does not operate by default on a particular {@link Scheduler}.</dd>
1839 * </dl>
1840 * @param onError the error {@code Consumer} receiving the upstream {@link Throwable} if the upstream signals it via {@code onError}
1841 * @return the new {@code Completable} instance
1842 * @throws NullPointerException if {@code onError} is {@code null}
1843 * @see #doFinally(Action)
1844 */
1845 @CheckReturnValue
1846 @SchedulerSupport(SchedulerSupport.NONE)
1847 @NonNull
1848 public final Completable doOnError(@NonNull Consumer<? super Throwable> onError) {
1849 return doOnLifecycle(Functions.emptyConsumer(), onError,
1850 Functions.EMPTY_ACTION, Functions.EMPTY_ACTION,
1851 Functions.EMPTY_ACTION, Functions.EMPTY_ACTION);
1852 }
1853
1854 /**
1855 * Returns a {@code Completable} which calls the given {@code onEvent} {@link Consumer} with the {@link Throwable} for an {@code onError}
1856 * or {@code null} for an {@code onComplete} signal from this {@code Completable} before delivering the signal to the downstream.
1857 * <p>
1858 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Completable.doOnEvent.png" alt="">
1859 * <dl>
1860 * <dt><b>Scheduler:</b></dt>
1861 * <dd>{@code doOnEvent} does not operate by default on a particular {@link Scheduler}.</dd>
1862 * </dl>
1863 * @param onEvent the event {@code Consumer} that receives {@code null} for upstream
1864 * completion or a {@code Throwable} if the upstream signaled an error
1865 * @return the new {@code Completable} instance
1866 * @throws NullPointerException if {@code onEvent} is {@code null}
1867 */
1868 @CheckReturnValue
1869 @NonNull
1870 @SchedulerSupport(SchedulerSupport.NONE)
1871 public final Completable doOnEvent(@NonNull Consumer<@Nullable ? super Throwable> onEvent) {
1872 Objects.requireNonNull(onEvent, "onEvent is null");
1873 return RxJavaPlugins.onAssembly(new CompletableDoOnEvent(this, onEvent));
1874 }
1875
1876 /**
1877 * Calls the appropriate {@code onXXX} method (shared between all {@link CompletableObserver}s) for the lifecycle events of
1878 * the sequence (subscription, disposal).
1879 * <p>
1880 * <img width="640" height="257" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Completable.doOnLifecycle.png" alt="">
1881 * <dl>
1882 * <dt><b>Scheduler:</b></dt>
1883 * <dd>{@code doOnLifecycle} does not operate by default on a particular {@link Scheduler}.</dd>
1884 * </dl>
1885 *
1886 * @param onSubscribe
1887 * a {@link Consumer} called with the {@link Disposable} sent via {@link CompletableObserver#onSubscribe(Disposable)}
1888 * @param onDispose
1889 * called when the downstream disposes the {@code Disposable} via {@code dispose()}
1890 * @return the new {@code Completable} instance
1891 * @throws NullPointerException if {@code onSubscribe} or {@code onDispose} is {@code null}
1892 * @see <a href="http://reactivex.io/documentation/operators/do.html">ReactiveX operators documentation: Do</a>
1893 * @since 3.0.0
1894 */
1895 @CheckReturnValue
1896 @SchedulerSupport(SchedulerSupport.NONE)
1897 @NonNull
1898 public final Completable doOnLifecycle(@NonNull Consumer<? super Disposable> onSubscribe, @NonNull Action onDispose) {
1899 return doOnLifecycle(onSubscribe, Functions.emptyConsumer(),
1900 Functions.EMPTY_ACTION, Functions.EMPTY_ACTION,
1901 Functions.EMPTY_ACTION, onDispose);
1902 }
1903
1904 /**
1905 * Returns a {@code Completable} instance that calls the various callbacks upon the specific
1906 * lifecycle events.
1907 * <dl>
1908 * <dt><b>Scheduler:</b></dt>
1909 * <dd>{@code doOnLifecycle} does not operate by default on a particular {@link Scheduler}.</dd>
1910 * </dl>
1911 * @param onSubscribe the {@link Consumer} called when a {@link CompletableObserver} subscribes.
1912 * @param onError the {@code Consumer} called when this emits an {@code onError} event
1913 * @param onComplete the {@link Action} called just before when the current {@code Completable} completes normally
1914 * @param onTerminate the {@code Action} called just before this {@code Completable} terminates
1915 * @param onAfterTerminate the {@code Action} called after this {@code Completable} completes normally
1916 * @param onDispose the {@code Action} called when the downstream disposes the subscription
1917 * @return the new {@code Completable} instance
1918 * @throws NullPointerException if {@code onSubscribe}, {@code onError}, {@code onComplete}
1919 * {@code onTerminate}, {@code onAfterTerminate} or {@code onDispose} is {@code null}
1920 */
1921 @CheckReturnValue
1922 @NonNull
1923 @SchedulerSupport(SchedulerSupport.NONE)
1924 private Completable doOnLifecycle(
1925 final Consumer<? super Disposable> onSubscribe,
1926 final Consumer<? super Throwable> onError,
1927 final Action onComplete,
1928 final Action onTerminate,
1929 final Action onAfterTerminate,
1930 final Action onDispose) {
1931 Objects.requireNonNull(onSubscribe, "onSubscribe is null");
1932 Objects.requireNonNull(onError, "onError is null");
1933 Objects.requireNonNull(onComplete, "onComplete is null");
1934 Objects.requireNonNull(onTerminate, "onTerminate is null");
1935 Objects.requireNonNull(onAfterTerminate, "onAfterTerminate is null");
1936 Objects.requireNonNull(onDispose, "onDispose is null");
1937 return RxJavaPlugins.onAssembly(new CompletablePeek(this, onSubscribe, onError, onComplete, onTerminate, onAfterTerminate, onDispose));
1938 }
1939
1940 /**
1941 * Returns a {@code Completable} instance that calls the given {@code onSubscribe} callback with the disposable
1942 * that the downstream {@link CompletableObserver}s receive upon subscription.
1943 * <p>
1944 * <img width="640" height="304" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Completable.doOnSubscribe.png" alt="">
1945 * <dl>
1946 * <dt><b>Scheduler:</b></dt>
1947 * <dd>{@code doOnSubscribe} does not operate by default on a particular {@link Scheduler}.</dd>
1948 * </dl>
1949 * @param onSubscribe the {@link Consumer} called when a downstream {@code CompletableObserver} subscribes
1950 * @return the new {@code Completable} instance
1951 * @throws NullPointerException if {@code onSubscribe} is {@code null}
1952 */
1953 @CheckReturnValue
1954 @SchedulerSupport(SchedulerSupport.NONE)
1955 @NonNull
1956 public final Completable doOnSubscribe(@NonNull Consumer<? super Disposable> onSubscribe) {
1957 return doOnLifecycle(onSubscribe, Functions.emptyConsumer(),
1958 Functions.EMPTY_ACTION, Functions.EMPTY_ACTION,
1959 Functions.EMPTY_ACTION, Functions.EMPTY_ACTION);
1960 }
1961
1962 /**
1963 * Returns a {@code Completable} instance that calls the given {@code onTerminate} {@link Action} just before this {@code Completable}
1964 * completes normally or with an exception.
1965 * <p>
1966 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Completable.doOnTerminate.png" alt="">
1967 * <dl>
1968 * <dt><b>Scheduler:</b></dt>
1969 * <dd>{@code doOnTerminate} does not operate by default on a particular {@link Scheduler}.</dd>
1970 * </dl>
1971 * @param onTerminate the {@code Action} to call just before this {@code Completable} terminates
1972 * @return the new {@code Completable} instance
1973 * @throws NullPointerException if {@code onTerminate} is {@code null}
1974 * @see #doFinally(Action)
1975 */
1976 @CheckReturnValue
1977 @SchedulerSupport(SchedulerSupport.NONE)
1978 @NonNull
1979 public final Completable doOnTerminate(@NonNull Action onTerminate) {
1980 return doOnLifecycle(Functions.emptyConsumer(), Functions.emptyConsumer(),
1981 Functions.EMPTY_ACTION, onTerminate,
1982 Functions.EMPTY_ACTION, Functions.EMPTY_ACTION);
1983 }
1984
1985 /**
1986 * Returns a {@code Completable} instance that calls the given {@code onAfterTerminate} {@link Action} after this {@code Completable}
1987 * completes normally or with an exception.
1988 * <p>
1989 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Completable.doAfterTerminate.png" alt="">
1990 * <dl>
1991 * <dt><b>Scheduler:</b></dt>
1992 * <dd>{@code doAfterTerminate} does not operate by default on a particular {@link Scheduler}.</dd>
1993 * </dl>
1994 * @param onAfterTerminate the {@code Action} to call after this {@code Completable} terminates
1995 * @return the new {@code Completable} instance
1996 * @throws NullPointerException if {@code onAfterTerminate} is {@code null}
1997 * @see #doFinally(Action)
1998 */
1999 @CheckReturnValue
2000 @SchedulerSupport(SchedulerSupport.NONE)
2001 @NonNull
2002 public final Completable doAfterTerminate(@NonNull Action onAfterTerminate) {
2003 return doOnLifecycle(
2004 Functions.emptyConsumer(),
2005 Functions.emptyConsumer(),
2006 Functions.EMPTY_ACTION,
2007 Functions.EMPTY_ACTION,
2008 onAfterTerminate,
2009 Functions.EMPTY_ACTION);
2010 }
2011 /**
2012 * Calls the specified {@link Action} after this {@code Completable} signals {@code onError} or {@code onComplete} or gets disposed by
2013 * the downstream.
2014 * <p>
2015 * <img width="640" height="331" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Completable.doFinally.png" alt="">
2016 * <p>
2017 * In case of a race between a terminal event and a dispose call, the provided {@code onFinally} action
2018 * is executed once per subscription.
2019 * <p>
2020 * Note that the {@code onFinally} action is shared between subscriptions and as such
2021 * should be thread-safe.
2022 * <dl>
2023 * <dt><b>Scheduler:</b></dt>
2024 * <dd>{@code doFinally} does not operate by default on a particular {@link Scheduler}.</dd>
2025 * </dl>
2026 * <p>History: 2.0.1 - experimental
2027 * @param onFinally the {@code Action} called when this {@code Completable} terminates or gets disposed
2028 * @return the new {@code Completable} instance
2029 * @throws NullPointerException if {@code onFinally} is {@code null}
2030 * @since 2.1
2031 */
2032 @CheckReturnValue
2033 @NonNull
2034 @SchedulerSupport(SchedulerSupport.NONE)
2035 public final Completable doFinally(@NonNull Action onFinally) {
2036 Objects.requireNonNull(onFinally, "onFinally is null");
2037 return RxJavaPlugins.onAssembly(new CompletableDoFinally(this, onFinally));
2038 }
2039
2040 /**
2041 * <strong>This method requires advanced knowledge about building operators, please consider
2042 * other standard composition methods first;</strong>
2043 * Returns a {@code Completable} which, when subscribed to, invokes the {@link CompletableOperator#apply(CompletableObserver) apply(CompletableObserver)} method
2044 * of the provided {@link CompletableOperator} for each individual downstream {@link Completable} and allows the
2045 * insertion of a custom operator by accessing the downstream's {@link CompletableObserver} during this subscription phase
2046 * and providing a new {@code CompletableObserver}, containing the custom operator's intended business logic, that will be
2047 * used in the subscription process going further upstream.
2048 * <p>
2049 * <img width="640" height="313" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Completable.lift.png" alt="">
2050 * <p>
2051 * Generally, such a new {@code CompletableObserver} will wrap the downstream's {@code CompletableObserver} and forwards the
2052 * {@code onError} and {@code onComplete} events from the upstream directly or according to the
2053 * emission pattern the custom operator's business logic requires. In addition, such operator can intercept the
2054 * flow control calls of {@code dispose} and {@code isDisposed} that would have traveled upstream and perform
2055 * additional actions depending on the same business logic requirements.
2056 * <p>
2057 * Example:
2058 * <pre><code>
2059 * // Step 1: Create the consumer type that will be returned by the CompletableOperator.apply():
2060 *
2061 * public final class CustomCompletableObserver implements CompletableObserver, Disposable {
2062 *
2063 * // The downstream's CompletableObserver that will receive the onXXX events
2064 * final CompletableObserver downstream;
2065 *
2066 * // The connection to the upstream source that will call this class' onXXX methods
2067 * Disposable upstream;
2068 *
2069 * // The constructor takes the downstream subscriber and usually any other parameters
2070 * public CustomCompletableObserver(CompletableObserver downstream) {
2071 * this.downstream = downstream;
2072 * }
2073 *
2074 * // In the subscription phase, the upstream sends a Disposable to this class
2075 * // and subsequently this class has to send a Disposable to the downstream.
2076 * // Note that relaying the upstream's Disposable directly is not allowed in RxJava
2077 * &#64;Override
2078 * public void onSubscribe(Disposable d) {
2079 * if (upstream != null) {
2080 * d.dispose();
2081 * } else {
2082 * upstream = d;
2083 * downstream.onSubscribe(this);
2084 * }
2085 * }
2086 *
2087 * // Some operators may handle the upstream's error while others
2088 * // could just forward it to the downstream.
2089 * &#64;Override
2090 * public void onError(Throwable throwable) {
2091 * downstream.onError(throwable);
2092 * }
2093 *
2094 * // When the upstream completes, usually the downstream should complete as well.
2095 * // In completable, this could also mean doing some side-effects
2096 * &#64;Override
2097 * public void onComplete() {
2098 * System.out.println("Sequence completed");
2099 * downstream.onComplete();
2100 * }
2101 *
2102 * // Some operators may use their own resources which should be cleaned up if
2103 * // the downstream disposes the flow before it completed. Operators without
2104 * // resources can simply forward the dispose to the upstream.
2105 * // In some cases, a disposed flag may be set by this method so that other parts
2106 * // of this class may detect the dispose and stop sending events
2107 * // to the downstream.
2108 * &#64;Override
2109 * public void dispose() {
2110 * upstream.dispose();
2111 * }
2112 *
2113 * // Some operators may simply forward the call to the upstream while others
2114 * // can return the disposed flag set in dispose().
2115 * &#64;Override
2116 * public boolean isDisposed() {
2117 * return upstream.isDisposed();
2118 * }
2119 * }
2120 *
2121 * // Step 2: Create a class that implements the CompletableOperator interface and
2122 * // returns the custom consumer type from above in its apply() method.
2123 * // Such class may define additional parameters to be submitted to
2124 * // the custom consumer type.
2125 *
2126 * final class CustomCompletableOperator implements CompletableOperator {
2127 * &#64;Override
2128 * public CompletableObserver apply(CompletableObserver upstream) {
2129 * return new CustomCompletableObserver(upstream);
2130 * }
2131 * }
2132 *
2133 * // Step 3: Apply the custom operator via lift() in a flow by creating an instance of it
2134 * // or reusing an existing one.
2135 *
2136 * Completable.complete()
2137 * .lift(new CustomCompletableOperator())
2138 * .test()
2139 * .assertResult();
2140 * </code></pre>
2141 * <p>
2142 * Creating custom operators can be complicated and it is recommended one consults the
2143 * <a href="https://github.com/ReactiveX/RxJava/wiki/Writing-operators-for-2.0">RxJava wiki: Writing operators</a> page about
2144 * the tools, requirements, rules, considerations and pitfalls of implementing them.
2145 * <p>
2146 * Note that implementing custom operators via this {@code lift()} method adds slightly more overhead by requiring
2147 * an additional allocation and indirection per assembled flows. Instead, extending the abstract {@code Completable}
2148 * class and creating a {@link CompletableTransformer} with it is recommended.
2149 * <p>
2150 * Note also that it is not possible to stop the subscription phase in {@code lift()} as the {@code apply()} method
2151 * requires a non-{@code null} {@code CompletableObserver} instance to be returned, which is then unconditionally subscribed to
2152 * the current {@code Completable}. For example, if the operator decided there is no reason to subscribe to the
2153 * upstream source because of some optimization possibility or a failure to prepare the operator, it still has to
2154 * return a {@code CompletableObserver} that should immediately dispose the upstream's {@link Disposable} in its
2155 * {@code onSubscribe} method. Again, using a {@code CompletableTransformer} and extending the {@code Completable} is
2156 * a better option as {@link #subscribeActual} can decide to not subscribe to its upstream after all.
2157 * <dl>
2158 * <dt><b>Scheduler:</b></dt>
2159 * <dd>{@code lift} does not operate by default on a particular {@link Scheduler}, however, the
2160 * {@code CompletableOperator} may use a {@code Scheduler} to support its own asynchronous behavior.</dd>
2161 * </dl>
2162 *
2163 * @param onLift the {@code CompletableOperator} that receives the downstream's {@code CompletableObserver} and should return
2164 * a {@code CompletableObserver} with custom behavior to be used as the consumer for the current
2165 * {@code Completable}.
2166 * @return the new {@code Completable} instance
2167 * @throws NullPointerException if {@code onLift} is {@code null}
2168 * @see <a href="https://github.com/ReactiveX/RxJava/wiki/Writing-operators-for-2.0">RxJava wiki: Writing operators</a>
2169 * @see #compose(CompletableTransformer)
2170 */
2171 @CheckReturnValue
2172 @NonNull
2173 @SchedulerSupport(SchedulerSupport.NONE)
2174 public final Completable lift(@NonNull CompletableOperator onLift) {
2175 Objects.requireNonNull(onLift, "onLift is null");
2176 return RxJavaPlugins.onAssembly(new CompletableLift(this, onLift));
2177 }
2178
2179 /**
2180 * Maps the signal types of this {@code Completable} into a {@link Notification} of the same kind
2181 * and emits it as a single success value to downstream.
2182 * <p>
2183 * <img width="640" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/materialize.v3.png" alt="">
2184 * <dl>
2185 * <dt><b>Scheduler:</b></dt>
2186 * <dd>{@code materialize} does not operate by default on a particular {@link Scheduler}.</dd>
2187 * </dl>
2188 * <p>History: 2.2.4 - experimental
2189 * @param <T> the intended target element type of the {@code Notification}
2190 * @return the new {@link Single} instance
2191 * @since 3.0.0
2192 * @see Single#dematerialize(Function)
2193 */
2194 @CheckReturnValue
2195 @SchedulerSupport(SchedulerSupport.NONE)
2196 @NonNull
2197 public final <@NonNull T> Single<Notification<T>> materialize() {
2198 return RxJavaPlugins.onAssembly(new CompletableMaterialize<>(this));
2199 }
2200
2201 /**
2202 * Returns a {@code Completable} which subscribes to this and the other {@link CompletableSource} and completes
2203 * when both of them complete or one emits an error.
2204 * <p>
2205 * <img width="640" height="442" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Completable.mergeWith.png" alt="">
2206 * <dl>
2207 * <dt><b>Scheduler:</b></dt>
2208 * <dd>{@code mergeWith} does not operate by default on a particular {@link Scheduler}.</dd>
2209 * </dl>
2210 * @param other the other {@code CompletableSource} instance
2211 * @return the new {@code Completable} instance
2212 * @throws NullPointerException if {@code other} is {@code null}
2213 */
2214 @CheckReturnValue
2215 @NonNull
2216 @SchedulerSupport(SchedulerSupport.NONE)
2217 public final Completable mergeWith(@NonNull CompletableSource other) {
2218 Objects.requireNonNull(other, "other is null");
2219 return mergeArray(this, other);
2220 }
2221
2222 /**
2223 * Returns a {@code Completable} which emits the terminal events from the thread of the specified {@link Scheduler}.
2224 * <p>
2225 * <img width="640" height="523" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Completable.observeOn.png" alt="">
2226 * <dl>
2227 * <dt><b>Scheduler:</b></dt>
2228 * <dd>{@code observeOn} operates on a {@code Scheduler} you specify.</dd>
2229 * </dl>
2230 * @param scheduler the {@code Scheduler} to emit terminal events on
2231 * @return the new {@code Completable} instance
2232 * @throws NullPointerException if {@code scheduler} is {@code null}
2233 */
2234 @CheckReturnValue
2235 @NonNull
2236 @SchedulerSupport(SchedulerSupport.CUSTOM)
2237 public final Completable observeOn(@NonNull Scheduler scheduler) {
2238 Objects.requireNonNull(scheduler, "scheduler is null");
2239 return RxJavaPlugins.onAssembly(new CompletableObserveOn(this, scheduler));
2240 }
2241
2242 /**
2243 * Returns a {@code Completable} instance that if this {@code Completable} emits an error, it will emit an {@code onComplete}
2244 * and swallow the upstream {@link Throwable}.
2245 * <p>
2246 * <img width="640" height="585" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Completable.onErrorComplete.png" alt="">
2247 * <dl>
2248 * <dt><b>Scheduler:</b></dt>
2249 * <dd>{@code onErrorComplete} does not operate by default on a particular {@link Scheduler}.</dd>
2250 * </dl>
2251 * @return the new {@code Completable} instance
2252 */
2253 @CheckReturnValue
2254 @SchedulerSupport(SchedulerSupport.NONE)
2255 @NonNull
2256 public final Completable onErrorComplete() {
2257 return onErrorComplete(Functions.alwaysTrue());
2258 }
2259
2260 /**
2261 * Returns a {@code Completable} instance that if this {@code Completable} emits an error and the {@link Predicate} returns
2262 * {@code true}, it will emit an {@code onComplete} and swallow the {@link Throwable}.
2263 * <p>
2264 * <img width="640" height="283" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Completable.onErrorComplete.f.png" alt="">
2265 * <dl>
2266 * <dt><b>Scheduler:</b></dt>
2267 * <dd>{@code onErrorComplete} does not operate by default on a particular {@link Scheduler}.</dd>
2268 * </dl>
2269 * @param predicate the {@code Predicate} to call when a {@code Throwable} is emitted which should return {@code true}
2270 * if the {@code Throwable} should be swallowed and replaced with an {@code onComplete}.
2271 * @return the new {@code Completable} instance
2272 * @throws NullPointerException if {@code predicate} is {@code null}
2273 */
2274 @CheckReturnValue
2275 @NonNull
2276 @SchedulerSupport(SchedulerSupport.NONE)
2277 public final Completable onErrorComplete(@NonNull Predicate<? super Throwable> predicate) {
2278 Objects.requireNonNull(predicate, "predicate is null");
2279
2280 return RxJavaPlugins.onAssembly(new CompletableOnErrorComplete(this, predicate));
2281 }
2282
2283 /**
2284 * Returns a {@code Completable} instance that when encounters an error from this {@code Completable}, calls the
2285 * specified {@code mapper} {@link Function} that returns a {@link CompletableSource} instance for it and resumes the
2286 * execution with it.
2287 * <p>
2288 * <img width="640" height="426" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Completable.onErrorResumeNext.png" alt="">
2289 * <dl>
2290 * <dt><b>Scheduler:</b></dt>
2291 * <dd>{@code onErrorResumeNext} does not operate by default on a particular {@link Scheduler}.</dd>
2292 * </dl>
2293 * @param fallbackSupplier the {@code mapper} {@code Function} that takes the error and should return a {@code CompletableSource} as
2294 * continuation.
2295 * @return the new {@code Completable} instance
2296 * @throws NullPointerException if {@code fallbackSupplier} is {@code null}
2297 */
2298 @CheckReturnValue
2299 @NonNull
2300 @SchedulerSupport(SchedulerSupport.NONE)
2301 public final Completable onErrorResumeNext(@NonNull Function<? super Throwable, ? extends CompletableSource> fallbackSupplier) {
2302 Objects.requireNonNull(fallbackSupplier, "fallbackSupplier is null");
2303 return RxJavaPlugins.onAssembly(new CompletableResumeNext(this, fallbackSupplier));
2304 }
2305 /**
2306 * Resumes the flow with the given {@link CompletableSource} when the current {@code Completable} fails instead of
2307 * signaling the error via {@code onError}.
2308 * <p>
2309 * <img width="640" height="409" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Completable.onErrorResumeWith.png" alt="">
2310 * <p>
2311 * You can use this to prevent errors from propagating or to supply fallback data should errors be
2312 * encountered.
2313 * <dl>
2314 * <dt><b>Scheduler:</b></dt>
2315 * <dd>{@code onErrorResumeWith} does not operate by default on a particular {@link Scheduler}.</dd>
2316 * </dl>
2317 *
2318 * @param fallback
2319 * the next {@code CompletableSource} that will take over if the current {@code Completable} encounters
2320 * an error
2321 * @return the new {@code Completable} instance
2322 * @throws NullPointerException if {@code fallback} is {@code null}
2323 * @see <a href="http://reactivex.io/documentation/operators/catch.html">ReactiveX operators documentation: Catch</a>
2324 * @since 3.0.0
2325 */
2326 @CheckReturnValue
2327 @NonNull
2328 @SchedulerSupport(SchedulerSupport.NONE)
2329 public final Completable onErrorResumeWith(@NonNull CompletableSource fallback) {
2330 Objects.requireNonNull(fallback, "fallback is null");
2331 return onErrorResumeNext(Functions.justFunction(fallback));
2332 }
2333
2334 /**
2335 * Ends the flow with a success item returned by a function for the {@link Throwable} error signaled by the current
2336 * {@code Completable} instead of signaling the error via {@code onError}.
2337 * <p>
2338 * <img width="640" height="567" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Completable.onErrorReturn.png" alt="">
2339 * <p>
2340 * You can use this to prevent errors from propagating or to supply fallback data should errors be
2341 * encountered.
2342 * <dl>
2343 * <dt><b>Scheduler:</b></dt>
2344 * <dd>{@code onErrorReturn} does not operate by default on a particular {@link Scheduler}.</dd>
2345 * </dl>
2346 *
2347 * @param <T> the item type to return on error
2348 * @param itemSupplier
2349 * a function that returns a single value that will be emitted as success value
2350 * the current {@code Completable} signals an {@code onError} event
2351 * @return the new {@link Maybe} instance
2352 * @throws NullPointerException if {@code itemSupplier} is {@code null}
2353 * @see <a href="http://reactivex.io/documentation/operators/catch.html">ReactiveX operators documentation: Catch</a>
2354 * @since 3.0.0
2355 */
2356 @CheckReturnValue
2357 @NonNull
2358 @SchedulerSupport(SchedulerSupport.NONE)
2359 public final <@NonNull T> Maybe<T> onErrorReturn(@NonNull Function<? super Throwable, ? extends T> itemSupplier) {
2360 Objects.requireNonNull(itemSupplier, "itemSupplier is null");
2361 return RxJavaPlugins.onAssembly(new CompletableOnErrorReturn<>(this, itemSupplier));
2362 }
2363
2364 /**
2365 * Ends the flow with the given success item when the current {@code Completable}
2366 * fails instead of signaling the error via {@code onError}.
2367 * <p>
2368 * <img width="640" height="567" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Completable.onErrorReturnItem.png" alt="">
2369 * <p>
2370 * You can use this to prevent errors from propagating or to supply fallback data should errors be
2371 * encountered.
2372 * <dl>
2373 * <dt><b>Scheduler:</b></dt>
2374 * <dd>{@code onErrorReturnItem} does not operate by default on a particular {@link Scheduler}.</dd>
2375 * </dl>
2376 *
2377 * @param <T> the item type to return on error
2378 * @param item
2379 * the value that is emitted as {@code onSuccess} in case the current {@code Completable} signals an {@code onError}
2380 * @return the new {@link Maybe} instance
2381 * @throws NullPointerException if {@code item} is {@code null}
2382 * @see <a href="http://reactivex.io/documentation/operators/catch.html">ReactiveX operators documentation: Catch</a>
2383 */
2384 @CheckReturnValue
2385 @NonNull
2386 @SchedulerSupport(SchedulerSupport.NONE)
2387 public final <@NonNull T> Maybe<T> onErrorReturnItem(@NonNull T item) {
2388 Objects.requireNonNull(item, "item is null");
2389 return onErrorReturn(Functions.justFunction(item));
2390 }
2391
2392 /**
2393 * Nulls out references to the upstream producer and downstream {@link CompletableObserver} if
2394 * the sequence is terminated or downstream calls {@code dispose()}.
2395 * <p>
2396 * <img width="640" height="326" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Completable.onTerminateDetach.png" alt="">
2397 * <dl>
2398 * <dt><b>Scheduler:</b></dt>
2399 * <dd>{@code onTerminateDetach} does not operate by default on a particular {@link Scheduler}.</dd>
2400 * </dl>
2401 * <p>History: 2.1.5 - experimental
2402 * @return the new {@code Completable} instance
2403 * @since 2.2
2404 */
2405 @CheckReturnValue
2406 @SchedulerSupport(SchedulerSupport.NONE)
2407 @NonNull
2408 public final Completable onTerminateDetach() {
2409 return RxJavaPlugins.onAssembly(new CompletableDetach(this));
2410 }
2411
2412 /**
2413 * Returns a {@code Completable} that repeatedly subscribes to this {@code Completable} until disposed.
2414 * <p>
2415 * <img width="640" height="373" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Completable.repeat.png" alt="">
2416 * <dl>
2417 * <dt><b>Scheduler:</b></dt>
2418 * <dd>{@code repeat} does not operate by default on a particular {@link Scheduler}.</dd>
2419 * </dl>
2420 * @return the new {@code Completable} instance
2421 */
2422 @CheckReturnValue
2423 @SchedulerSupport(SchedulerSupport.NONE)
2424 @NonNull
2425 public final Completable repeat() {
2426 return fromPublisher(toFlowable().repeat());
2427 }
2428
2429 /**
2430 * Returns a {@code Completable} that subscribes repeatedly at most the given number of times to this {@code Completable}.
2431 * <p>
2432 * <img width="640" height="408" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Completable.repeat.n.png" alt="">
2433 * <dl>
2434 * <dt><b>Scheduler:</b></dt>
2435 * <dd>{@code repeat} does not operate by default on a particular {@link Scheduler}.</dd>
2436 * </dl>
2437 * @param times the number of times the re-subscription should happen
2438 * @return the new {@code Completable} instance
2439 * @throws IllegalArgumentException if {@code times} is negative
2440 */
2441 @CheckReturnValue
2442 @SchedulerSupport(SchedulerSupport.NONE)
2443 @NonNull
2444 public final Completable repeat(long times) {
2445 return fromPublisher(toFlowable().repeat(times));
2446 }
2447
2448 /**
2449 * Returns a {@code Completable} that repeatedly subscribes to this {@code Completable} so long as the given
2450 * stop {@link BooleanSupplier} returns {@code false}.
2451 * <p>
2452 * <img width="640" height="381" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Completable.repeatUntil.png" alt="">
2453 * <dl>
2454 * <dt><b>Scheduler:</b></dt>
2455 * <dd>{@code repeatUntil} does not operate by default on a particular {@link Scheduler}.</dd>
2456 * </dl>
2457 * @param stop the {@code BooleanSupplier} that should return {@code true} to stop resubscribing.
2458 * @return the new {@code Completable} instance
2459 * @throws NullPointerException if {@code stop} is {@code null}
2460 */
2461 @CheckReturnValue
2462 @SchedulerSupport(SchedulerSupport.NONE)
2463 @NonNull
2464 public final Completable repeatUntil(@NonNull BooleanSupplier stop) {
2465 return fromPublisher(toFlowable().repeatUntil(stop));
2466 }
2467
2468 /**
2469 * Returns a {@code Completable} instance that repeats when the {@link Publisher} returned by the handler {@link Function}
2470 * emits an item or completes when this {@code Publisher} emits an {@code onComplete} event.
2471 * <p>
2472 * <img width="640" height="586" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Completable.repeatWhen.png" alt="">
2473 * <dl>
2474 * <dt><b>Scheduler:</b></dt>
2475 * <dd>{@code repeatWhen} does not operate by default on a particular {@link Scheduler}.</dd>
2476 * </dl>
2477 * @param handler the {@code Function} that transforms the stream of values indicating the completion of
2478 * this {@code Completable} and returns a {@code Publisher} that emits items for repeating or completes to indicate the
2479 * repetition should stop
2480 * @return the new {@code Completable} instance
2481 * @throws NullPointerException if {@code handler} is {@code null}
2482 */
2483 @CheckReturnValue
2484 @SchedulerSupport(SchedulerSupport.NONE)
2485 @NonNull
2486 public final Completable repeatWhen(@NonNull Function<? super Flowable<Object>, @NonNull ? extends Publisher<@NonNull ?>> handler) {
2487 return fromPublisher(toFlowable().repeatWhen(handler));
2488 }
2489
2490 /**
2491 * Returns a {@code Completable} that retries this {@code Completable} as long as it emits an {@code onError} event.
2492 * <p>
2493 * <img width="640" height="368" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Completable.retry.png" alt="">
2494 * <dl>
2495 * <dt><b>Scheduler:</b></dt>
2496 * <dd>{@code retry} does not operate by default on a particular {@link Scheduler}.</dd>
2497 * </dl>
2498 * @return the new {@code Completable} instance
2499 */
2500 @CheckReturnValue
2501 @SchedulerSupport(SchedulerSupport.NONE)
2502 @NonNull
2503 public final Completable retry() {
2504 return fromPublisher(toFlowable().retry());
2505 }
2506
2507 /**
2508 * Returns a {@code Completable} that retries this {@code Completable} in case of an error as long as the {@code predicate}
2509 * returns {@code true}.
2510 * <p>
2511 * <img width="640" height="325" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Completable.retry.ff.png" alt="">
2512 * <dl>
2513 * <dt><b>Scheduler:</b></dt>
2514 * <dd>{@code retry} does not operate by default on a particular {@link Scheduler}.</dd>
2515 * </dl>
2516 * @param predicate the {@link Predicate} called when this {@code Completable} emits an error with the repeat count and the latest {@link Throwable}
2517 * and should return {@code true} to retry.
2518 * @return the new {@code Completable} instance
2519 * @throws NullPointerException if {@code predicate} is {@code null}
2520 */
2521 @CheckReturnValue
2522 @SchedulerSupport(SchedulerSupport.NONE)
2523 @NonNull
2524 public final Completable retry(@NonNull BiPredicate<? super Integer, ? super Throwable> predicate) {
2525 return fromPublisher(toFlowable().retry(predicate));
2526 }
2527
2528 /**
2529 * Returns a {@code Completable} that when this {@code Completable} emits an error, retries at most the given
2530 * number of times before giving up and emitting the last error.
2531 * <p>
2532 * <img width="640" height="451" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Completable.retry.n.png" alt="">
2533 * <dl>
2534 * <dt><b>Scheduler:</b></dt>
2535 * <dd>{@code retry} does not operate by default on a particular {@link Scheduler}.</dd>
2536 * </dl>
2537 * @param times the number of times to resubscribe if the current {@code Completable} fails
2538 * @return the new {@code Completable} instance
2539 * @throws IllegalArgumentException if {@code times} is negative
2540 */
2541 @CheckReturnValue
2542 @SchedulerSupport(SchedulerSupport.NONE)
2543 @NonNull
2544 public final Completable retry(long times) {
2545 return fromPublisher(toFlowable().retry(times));
2546 }
2547
2548 /**
2549 * Returns a {@code Completable} that when this {@code Completable} emits an error, retries at most times
2550 * or until the predicate returns {@code false}, whichever happens first and emitting the last error.
2551 * <p>
2552 * <img width="640" height="361" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Completable.retry.nf.png" alt="">
2553 * <dl>
2554 * <dt><b>Scheduler:</b></dt>
2555 * <dd>{@code retry} does not operate by default on a particular {@link Scheduler}.</dd>
2556 * </dl>
2557 * <p>History: 2.1.8 - experimental
2558 * @param times the number of times to resubscribe if the current {@code Completable} fails
2559 * @param predicate the {@link Predicate} that is called with the latest {@link Throwable} and should return
2560 * {@code true} to indicate the returned {@code Completable} should resubscribe to this {@code Completable}.
2561 * @return the new {@code Completable} instance
2562 * @throws NullPointerException if {@code predicate} is {@code null}
2563 * @throws IllegalArgumentException if {@code times} is negative
2564 * @since 2.2
2565 */
2566 @CheckReturnValue
2567 @SchedulerSupport(SchedulerSupport.NONE)
2568 @NonNull
2569 public final Completable retry(long times, @NonNull Predicate<? super Throwable> predicate) {
2570 return fromPublisher(toFlowable().retry(times, predicate));
2571 }
2572
2573 /**
2574 * Returns a {@code Completable} that when this {@code Completable} emits an error, calls the given predicate with
2575 * the latest {@link Throwable} to decide whether to resubscribe to the upstream or not.
2576 * <p>
2577 * <img width="640" height="336" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Completable.retry.f.png" alt="">
2578 * <dl>
2579 * <dt><b>Scheduler:</b></dt>
2580 * <dd>{@code retry} does not operate by default on a particular {@link Scheduler}.</dd>
2581 * </dl>
2582 * @param predicate the {@link Predicate} that is called with the latest {@code Throwable} and should return
2583 * {@code true} to indicate the returned {@code Completable} should resubscribe to this {@code Completable}.
2584 * @return the new {@code Completable} instance
2585 * @throws NullPointerException if {@code predicate} is {@code null}
2586 */
2587 @CheckReturnValue
2588 @SchedulerSupport(SchedulerSupport.NONE)
2589 @NonNull
2590 public final Completable retry(@NonNull Predicate<? super Throwable> predicate) {
2591 return fromPublisher(toFlowable().retry(predicate));
2592 }
2593
2594 /**
2595 * Retries until the given stop function returns {@code true}.
2596 * <p>
2597 * <img width="640" height="354" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Completable.retryUntil.png" alt="">
2598 * <dl>
2599 * <dt><b>Scheduler:</b></dt>
2600 * <dd>{@code retryUntil} does not operate by default on a particular {@link Scheduler}.</dd>
2601 * </dl>
2602 * @param stop the function that should return {@code true} to stop retrying
2603 * @return the new {@code Completable} instance
2604 * @throws NullPointerException if {@code stop} is {@code null}
2605 * @since 3.0.0
2606 */
2607 @CheckReturnValue
2608 @NonNull
2609 @SchedulerSupport(SchedulerSupport.NONE)
2610 public final Completable retryUntil(@NonNull BooleanSupplier stop) {
2611 Objects.requireNonNull(stop, "stop is null");
2612 return retry(Long.MAX_VALUE, Functions.predicateReverseFor(stop));
2613 }
2614
2615 /**
2616 * Returns a {@code Completable} which given a {@link Publisher} and when this {@code Completable} emits an error, delivers
2617 * that error through a {@link Flowable} and the {@code Publisher} should signal a value indicating a retry in response
2618 * or a terminal event indicating a termination.
2619 * <p>
2620 * <img width="640" height="586" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Completable.retryWhen.png" alt="">
2621 * <p>
2622 * Note that the inner {@code Publisher} returned by the handler function should signal
2623 * either {@code onNext}, {@code onError} or {@code onComplete} in response to the received
2624 * {@link Throwable} to indicate the operator should retry or terminate. If the upstream to
2625 * the operator is asynchronous, signaling {@code onNext} followed by {@code onComplete} immediately may
2626 * result in the sequence to be completed immediately. Similarly, if this inner
2627 * {@code Publisher} signals {@code onError} or {@code onComplete} while the upstream is
2628 * active, the sequence is terminated with the same signal immediately.
2629 * <p>
2630 * The following example demonstrates how to retry an asynchronous source with a delay:
2631 * <pre><code>
2632 * Completable.timer(1, TimeUnit.SECONDS)
2633 * .doOnSubscribe(s -&gt; System.out.println("subscribing"))
2634 * .doOnComplete(() -&gt; { throw new RuntimeException(); })
2635 * .retryWhen(errors -&gt; {
2636 * AtomicInteger counter = new AtomicInteger();
2637 * return errors
2638 * .takeWhile(e -&gt; counter.getAndIncrement() != 3)
2639 * .flatMap(e -&gt; {
2640 * System.out.println("delay retry by " + counter.get() + " second(s)");
2641 * return Flowable.timer(counter.get(), TimeUnit.SECONDS);
2642 * });
2643 * })
2644 * .blockingAwait();
2645 * </code></pre>
2646 * <dl>
2647 * <dt><b>Scheduler:</b></dt>
2648 * <dd>{@code retryWhen} does not operate by default on a particular {@link Scheduler}.</dd>
2649 * </dl>
2650 * @param handler the {@link Function} that receives a {@code Flowable} delivering {@code Throwable}s and should return a {@code Publisher} that
2651 * emits items to indicate retries or emits terminal events to indicate termination.
2652 * @return the new {@code Completable} instance
2653 * @throws NullPointerException if {@code handler} is {@code null}
2654 */
2655 @CheckReturnValue
2656 @SchedulerSupport(SchedulerSupport.NONE)
2657 @NonNull
2658 public final Completable retryWhen(@NonNull Function<? super Flowable<Throwable>, @NonNull ? extends Publisher<@NonNull ?>> handler) {
2659 return fromPublisher(toFlowable().retryWhen(handler));
2660 }
2661
2662 /**
2663 * Wraps the given {@link CompletableObserver}, catches any {@link RuntimeException}s thrown by its
2664 * {@link CompletableObserver#onSubscribe(Disposable)}, {@link CompletableObserver#onError(Throwable)}
2665 * or {@link CompletableObserver#onComplete()} methods and routes those to the global
2666 * error handler via {@link RxJavaPlugins#onError(Throwable)}.
2667 * <p>
2668 * By default, the {@code Completable} protocol forbids the {@code onXXX} methods to throw, but some
2669 * {@code CompletableObserver} implementation may do it anyway, causing undefined behavior in the
2670 * upstream. This method and the underlying safe wrapper ensures such misbehaving consumers don't
2671 * disrupt the protocol.
2672 * <dl>
2673 * <dt><b>Scheduler:</b></dt>
2674 * <dd>{@code safeSubscribe} does not operate by default on a particular {@link Scheduler}.</dd>
2675 * </dl>
2676 * @param observer the potentially misbehaving {@code CompletableObserver}
2677 * @throws NullPointerException if {@code observer} is {@code null}
2678 * @see #subscribe(Action, Consumer)
2679 * @since 3.0.0
2680 */
2681 @SchedulerSupport(SchedulerSupport.NONE)
2682 public final void safeSubscribe(@NonNull CompletableObserver observer) {
2683 Objects.requireNonNull(observer, "observer is null");
2684 subscribe(new SafeCompletableObserver(observer));
2685 }
2686
2687 /**
2688 * Returns a {@code Completable} which first runs the other {@link CompletableSource}
2689 * then the current {@code Completable} if the other completed normally.
2690 * <p>
2691 * <img width="640" height="437" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Completable.startWith.c.png" alt="">
2692 * <dl>
2693 * <dt><b>Scheduler:</b></dt>
2694 * <dd>{@code startWith} does not operate by default on a particular {@link Scheduler}.</dd>
2695 * </dl>
2696 * @param other the other {@code CompletableSource} to run first
2697 * @return the new {@code Completable} instance
2698 * @throws NullPointerException if {@code other} is {@code null}
2699 */
2700 @CheckReturnValue
2701 @NonNull
2702 @SchedulerSupport(SchedulerSupport.NONE)
2703 public final Completable startWith(@NonNull CompletableSource other) {
2704 Objects.requireNonNull(other, "other is null");
2705 return concatArray(other, this);
2706 }
2707
2708 /**
2709 * Returns a {@link Flowable} which first runs the other {@link SingleSource}
2710 * then the current {@code Completable} if the other succeeded normally.
2711 * <p>
2712 * <img width="640" height="388" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Completable.startWith.s.png" alt="">
2713 * <dl>
2714 * <dt><b>Backpressure:</b></dt>
2715 * <dd>The returned {@code Flowable} honors the backpressure of the downstream consumer.</dd>
2716 * <dt><b>Scheduler:</b></dt>
2717 * <dd>{@code startWith} does not operate by default on a particular {@link Scheduler}.</dd>
2718 * </dl>
2719 * @param <T> the element type of the {@code other} {@code SingleSource}.
2720 * @param other the other {@code SingleSource} to run first
2721 * @return the new {@code Flowable} instance
2722 * @throws NullPointerException if {@code other} is {@code null}
2723 * @since 3.0.0
2724 */
2725 @CheckReturnValue
2726 @NonNull
2727 @SchedulerSupport(SchedulerSupport.NONE)
2728 @BackpressureSupport(BackpressureKind.FULL)
2729 public final <@NonNull T> Flowable<T> startWith(@NonNull SingleSource<T> other) {
2730 Objects.requireNonNull(other, "other is null");
2731 return Flowable.concat(Single.wrap(other).toFlowable(), toFlowable());
2732 }
2733
2734 /**
2735 * Returns a {@link Flowable} which first runs the other {@link MaybeSource}
2736 * then the current {@code Completable} if the other succeeded or completed normally.
2737 * <p>
2738 * <img width="640" height="266" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Completable.startWith.m.png" alt="">
2739 * <dl>
2740 * <dt><b>Backpressure:</b></dt>
2741 * <dd>The returned {@code Flowable} honors the backpressure of the downstream consumer.</dd>
2742 * <dt><b>Scheduler:</b></dt>
2743 * <dd>{@code startWith} does not operate by default on a particular {@link Scheduler}.</dd>
2744 * </dl>
2745 * @param <T> the element type of the {@code other} {@code MaybeSource}.
2746 * @param other the other {@code MaybeSource} to run first
2747 * @return the new {@code Flowable} instance
2748 * @throws NullPointerException if {@code other} is {@code null}
2749 * @since 3.0.0
2750 */
2751 @CheckReturnValue
2752 @NonNull
2753 @SchedulerSupport(SchedulerSupport.NONE)
2754 @BackpressureSupport(BackpressureKind.FULL)
2755 public final <@NonNull T> Flowable<T> startWith(@NonNull MaybeSource<T> other) {
2756 Objects.requireNonNull(other, "other is null");
2757 return Flowable.concat(Maybe.wrap(other).toFlowable(), toFlowable());
2758 }
2759
2760 /**
2761 * Returns an {@link Observable} which first delivers the events
2762 * of the other {@link ObservableSource} then runs the current {@code Completable}.
2763 * <p>
2764 * <img width="640" height="289" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Completable.startWith.o.png" alt="">
2765 * <dl>
2766 * <dt><b>Scheduler:</b></dt>
2767 * <dd>{@code startWith} does not operate by default on a particular {@link Scheduler}.</dd>
2768 * </dl>
2769 * @param <T> the value type
2770 * @param other the other {@code ObservableSource} to run first
2771 * @return the new {@code Observable} instance
2772 * @throws NullPointerException if {@code other} is {@code null}
2773 */
2774 @CheckReturnValue
2775 @NonNull
2776 @SchedulerSupport(SchedulerSupport.NONE)
2777 public final <@NonNull T> Observable<T> startWith(@NonNull ObservableSource<T> other) {
2778 Objects.requireNonNull(other, "other is null");
2779 return Observable.wrap(other).concatWith(this.toObservable());
2780 }
2781
2782 /**
2783 * Returns a {@link Flowable} which first delivers the events
2784 * of the other {@link Publisher} then runs the current {@code Completable}.
2785 * <p>
2786 * <img width="640" height="250" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Completable.startWith.p.png" alt="">
2787 * <dl>
2788 * <dt><b>Backpressure:</b></dt>
2789 * <dd>The returned {@code Flowable} honors the backpressure of the downstream consumer
2790 * and expects the other {@code Publisher} to honor it as well.</dd>
2791 * <dt><b>Scheduler:</b></dt>
2792 * <dd>{@code startWith} does not operate by default on a particular {@link Scheduler}.</dd>
2793 * </dl>
2794 * @param <T> the value type
2795 * @param other the other {@code Publisher} to run first
2796 * @return the new {@code Flowable} instance
2797 * @throws NullPointerException if {@code other} is {@code null}
2798 */
2799 @CheckReturnValue
2800 @NonNull
2801 @BackpressureSupport(BackpressureKind.FULL)
2802 @SchedulerSupport(SchedulerSupport.NONE)
2803 public final <@NonNull T> Flowable<T> startWith(@NonNull Publisher<T> other) {
2804 Objects.requireNonNull(other, "other is null");
2805 return this.<T>toFlowable().startWith(other);
2806 }
2807
2808 /**
2809 * Hides the identity of this {@code Completable} and its {@link Disposable}.
2810 * <p>
2811 * <img width="640" height="432" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Completable.hide.png" alt="">
2812 * <p>
2813 * Allows preventing certain identity-based optimizations (fusion).
2814 * <dl>
2815 * <dt><b>Scheduler:</b></dt>
2816 * <dd>{@code hide} does not operate by default on a particular {@link Scheduler}.</dd>
2817 * </dl>
2818 * <p>History: 2.0.5 - experimental
2819 * @return the new {@code Completable} instance
2820 * @since 2.1
2821 */
2822 @CheckReturnValue
2823 @SchedulerSupport(SchedulerSupport.NONE)
2824 @NonNull
2825 public final Completable hide() {
2826 return RxJavaPlugins.onAssembly(new CompletableHide(this));
2827 }
2828
2829 /**
2830 * Subscribes to this {@code Completable} and returns a {@link Disposable} which can be used to dispose
2831 * the subscription.
2832 * <p>
2833 * <img width="640" height="352" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Completable.subscribe.png" alt="">
2834 * <dl>
2835 * <dt><b>Scheduler:</b></dt>
2836 * <dd>{@code subscribe} does not operate by default on a particular {@link Scheduler}.</dd>
2837 * </dl>
2838 * @return the new {@code Disposable} that can be used for disposing the subscription at any time
2839 * @see #subscribe(Action, Consumer, DisposableContainer)
2840 */
2841 @SchedulerSupport(SchedulerSupport.NONE)
2842 @NonNull
2843 public final Disposable subscribe() {
2844 EmptyCompletableObserver observer = new EmptyCompletableObserver();
2845 subscribe(observer);
2846 return observer;
2847 }
2848
2849 @SchedulerSupport(SchedulerSupport.NONE)
2850 @Override
2851 public final void subscribe(@NonNull CompletableObserver observer) {
2852 Objects.requireNonNull(observer, "observer is null");
2853 try {
2854
2855 observer = RxJavaPlugins.onSubscribe(this, observer);
2856
2857 Objects.requireNonNull(observer, "The RxJavaPlugins.onSubscribe hook returned a null CompletableObserver. Please check the handler provided to RxJavaPlugins.setOnCompletableSubscribe for invalid null returns. Further reading: https://github.com/ReactiveX/RxJava/wiki/Plugins");
2858
2859 subscribeActual(observer);
2860 } catch (NullPointerException ex) { // NOPMD
2861 throw ex;
2862 } catch (Throwable ex) {
2863 Exceptions.throwIfFatal(ex);
2864 RxJavaPlugins.onError(ex);
2865 throw toNpe(ex);
2866 }
2867 }
2868
2869 /**
2870 * Implement this method to handle the incoming {@link CompletableObserver}s and
2871 * perform the business logic in your operator.
2872 * <p>There is no need to call any of the plugin hooks on the current {@code Completable} instance or
2873 * the {@code CompletableObserver}; all hooks and basic safeguards have been
2874 * applied by {@link #subscribe(CompletableObserver)} before this method gets called.
2875 * @param observer the {@code CompletableObserver} instance, never {@code null}
2876 */
2877 protected abstract void subscribeActual(@NonNull CompletableObserver observer);
2878
2879 /**
2880 * Subscribes a given {@link CompletableObserver} (subclass) to this {@code Completable} and returns the given
2881 * {@code CompletableObserver} as is.
2882 * <p>
2883 * <img width="640" height="349" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Completable.subscribeWith.png" alt="">
2884 * <p>Usage example:
2885 * <pre><code>
2886 * Completable source = Completable.complete().delay(1, TimeUnit.SECONDS);
2887 * CompositeDisposable composite = new CompositeDisposable();
2888 *
2889 * DisposableCompletableObserver ds = new DisposableCompletableObserver() {
2890 * // ...
2891 * };
2892 *
2893 * composite.add(source.subscribeWith(ds));
2894 * </code></pre>
2895 * <dl>
2896 * <dt><b>Scheduler:</b></dt>
2897 * <dd>{@code subscribeWith} does not operate by default on a particular {@link Scheduler}.</dd>
2898 * </dl>
2899 * @param <E> the type of the {@code CompletableObserver} to use and return
2900 * @param observer the {@code CompletableObserver} (subclass) to use and return, not {@code null}
2901 * @return the input {@code observer}
2902 * @throws NullPointerException if {@code observer} is {@code null}
2903 * @since 2.0
2904 */
2905 @CheckReturnValue
2906 @SchedulerSupport(SchedulerSupport.NONE)
2907 @NonNull
2908 public final <@NonNull E extends CompletableObserver> E subscribeWith(E observer) {
2909 subscribe(observer);
2910 return observer;
2911 }
2912
2913 /**
2914 * Subscribes to this {@code Completable} and calls back either the {@code onError} or {@code onComplete} functions.
2915 * <p>
2916 * <img width="640" height="352" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Completable.subscribe.ff.png" alt="">
2917 * <dl>
2918 * <dt><b>Scheduler:</b></dt>
2919 * <dd>{@code subscribe} does not operate by default on a particular {@link Scheduler}.</dd>
2920 * </dl>
2921 * @param onComplete the {@link Action} that is called if the {@code Completable} completes normally
2922 * @param onError the {@link Consumer} that is called if this {@code Completable} emits an error
2923 * @return the new {@link Disposable} that can be used for disposing the subscription at any time
2924 * @throws NullPointerException if {@code onComplete} or {@code onError} is {@code null}
2925 * @see #subscribe(Action, Consumer, DisposableContainer)
2926 */
2927 @CheckReturnValue
2928 @NonNull
2929 @SchedulerSupport(SchedulerSupport.NONE)
2930 public final Disposable subscribe(@NonNull Action onComplete, @NonNull Consumer<? super Throwable> onError) {
2931 Objects.requireNonNull(onError, "onError is null");
2932 Objects.requireNonNull(onComplete, "onComplete is null");
2933
2934 CallbackCompletableObserver observer = new CallbackCompletableObserver(onError, onComplete);
2935 subscribe(observer);
2936 return observer;
2937 }
2938
2939 /**
2940 * Wraps the given onXXX callbacks into a {@link Disposable} {@link CompletableObserver},
2941 * adds it to the given {@link DisposableContainer} and ensures, that if the upstream
2942 * terminates or this particular {@code Disposable} is disposed, the {@code CompletableObserver} is removed
2943 * from the given composite.
2944 * <p>
2945 * The {@code CompletableObserver} will be removed after the callback for the terminal event has been invoked.
2946 * <dl>
2947 * <dt><b>Scheduler:</b></dt>
2948 * <dd>{@code subscribe} does not operate by default on a particular {@link Scheduler}.</dd>
2949 * </dl>
2950 * @param onError the callback for an upstream error
2951 * @param onComplete the callback for an upstream completion
2952 * @param container the {@code DisposableContainer} (such as {@link CompositeDisposable}) to add and remove the
2953 * created {@code Disposable} {@code CompletableObserver}
2954 * @return the {@code Disposable} that allows disposing the particular subscription.
2955 * @throws NullPointerException
2956 * if {@code onComplete}, {@code onError}
2957 * or {@code container} is {@code null}
2958 * @since 3.1.0
2959 */
2960 @SchedulerSupport(SchedulerSupport.NONE)
2961 @NonNull
2962 public final Disposable subscribe(
2963 @NonNull Action onComplete,
2964 @NonNull Consumer<? super Throwable> onError,
2965 @NonNull DisposableContainer container) {
2966 Objects.requireNonNull(onComplete, "onComplete is null");
2967 Objects.requireNonNull(onError, "onError is null");
2968 Objects.requireNonNull(container, "container is null");
2969
2970 DisposableAutoReleaseMultiObserver<Void> observer = new DisposableAutoReleaseMultiObserver<>(
2971 container, Functions.emptyConsumer(), onError, onComplete);
2972 container.add(observer);
2973 subscribe(observer);
2974 return observer;
2975 }
2976
2977 /**
2978 * Subscribes to this {@code Completable} and calls the given {@link Action} when this {@code Completable}
2979 * completes normally.
2980 * <p>
2981 * <img width="640" height="352" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Completable.subscribe.f.png" alt="">
2982 * <p>
2983 * If the {@code Completable} emits an error, it is wrapped into an
2984 * {@link OnErrorNotImplementedException}
2985 * and routed to the global {@link RxJavaPlugins#onError(Throwable)} handler.
2986 * <dl>
2987 * <dt><b>Scheduler:</b></dt>
2988 * <dd>{@code subscribe} does not operate by default on a particular {@link Scheduler}.</dd>
2989 * </dl>
2990 * @param onComplete the {@code Action} called when this {@code Completable} completes normally
2991 * @return the new {@link Disposable} that can be used for disposing the subscription at any time
2992 * @throws NullPointerException if {@code onComplete} is {@code null}
2993 * @see #subscribe(Action, Consumer, DisposableContainer)
2994 */
2995 @CheckReturnValue
2996 @NonNull
2997 @SchedulerSupport(SchedulerSupport.NONE)
2998 public final Disposable subscribe(@NonNull Action onComplete) {
2999 return subscribe(onComplete, Functions.ON_ERROR_MISSING);
3000 }
3001
3002 /**
3003 * Returns a {@code Completable} which subscribes the downstream subscriber on the specified scheduler, making
3004 * sure the subscription side-effects happen on that specific thread of the {@link Scheduler}.
3005 * <p>
3006 * <img width="640" height="686" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Completable.subscribeOn.png" alt="">
3007 * <dl>
3008 * <dt><b>Scheduler:</b></dt>
3009 * <dd>{@code subscribeOn} operates on a {@code Scheduler} you specify.</dd>
3010 * </dl>
3011 * @param scheduler the {@code Scheduler} to subscribe on
3012 * @return the new {@code Completable} instance
3013 * @throws NullPointerException if {@code scheduler} is {@code null}
3014 */
3015 @CheckReturnValue
3016 @NonNull
3017 @SchedulerSupport(SchedulerSupport.CUSTOM)
3018 public final Completable subscribeOn(@NonNull Scheduler scheduler) {
3019 Objects.requireNonNull(scheduler, "scheduler is null");
3020
3021 return RxJavaPlugins.onAssembly(new CompletableSubscribeOn(this, scheduler));
3022 }
3023
3024 /**
3025 * Terminates the downstream if this or the other {@code Completable}
3026 * terminates (wins the termination race) while disposing the connection to the losing source.
3027 * <p>
3028 * <img width="640" height="468" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Completable.takeuntil.c.png" alt="">
3029 * <dl>
3030 * <dt><b>Scheduler:</b></dt>
3031 * <dd>{@code takeUntil} does not operate by default on a particular {@link Scheduler}.</dd>
3032 * <dt><b>Error handling:</b></dt>
3033 * <dd>If both this and the other sources signal an error, only one of the errors
3034 * is signaled to the downstream and the other error is signaled to the global
3035 * error handler via {@link RxJavaPlugins#onError(Throwable)}.</dd>
3036 * </dl>
3037 * <p>History: 2.1.17 - experimental
3038 * @param other the other completable source to observe for the terminal signals
3039 * @return the new {@code Completable} instance
3040 * @throws NullPointerException if {@code other} is {@code null}
3041 * @since 2.2
3042 */
3043 @CheckReturnValue
3044 @NonNull
3045 @SchedulerSupport(SchedulerSupport.NONE)
3046 public final Completable takeUntil(@NonNull CompletableSource other) {
3047 Objects.requireNonNull(other, "other is null");
3048
3049 return RxJavaPlugins.onAssembly(new CompletableTakeUntilCompletable(this, other));
3050 }
3051
3052 /**
3053 * Returns a {@code Completabl}e that runs this {@code Completable} and emits a {@link TimeoutException} in case
3054 * this {@code Completable} doesn't complete within the given time.
3055 * <p>
3056 * <img width="640" height="348" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Completable.timeout.png" alt="">
3057 * <dl>
3058 * <dt><b>Scheduler:</b></dt>
3059 * <dd>{@code timeout} signals the {@code TimeoutException} on the {@code computation} {@link Scheduler}.</dd>
3060 * </dl>
3061 * @param timeout the timeout value
3062 * @param unit the unit of {@code timeout}
3063 * @return the new {@code Completable} instance
3064 * @throws NullPointerException if {@code unit} is {@code null}
3065 */
3066 @CheckReturnValue
3067 @SchedulerSupport(SchedulerSupport.COMPUTATION)
3068 @NonNull
3069 public final Completable timeout(long timeout, @NonNull TimeUnit unit) {
3070 return timeout0(timeout, unit, Schedulers.computation(), null);
3071 }
3072
3073 /**
3074 * Returns a {@code Completable} that runs this {@code Completable} and switches to the other {@link CompletableSource}
3075 * in case this {@code Completable} doesn't complete within the given time.
3076 * <p>
3077 * <img width="640" height="308" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Completable.timeout.c.png" alt="">
3078 * <dl>
3079 * <dt><b>Scheduler:</b></dt>
3080 * <dd>{@code timeout} subscribes to the other {@code CompletableSource} on
3081 * the {@code computation} {@link Scheduler}.</dd>
3082 * </dl>
3083 * @param timeout the timeout value
3084 * @param unit the unit of {@code timeout}
3085 * @param fallback the other {@code CompletableSource} instance to switch to in case of a timeout
3086 * @return the new {@code Completable} instance
3087 * @throws NullPointerException if {@code unit} or {@code fallback} is {@code null}
3088 */
3089 @CheckReturnValue
3090 @NonNull
3091 @SchedulerSupport(SchedulerSupport.COMPUTATION)
3092 public final Completable timeout(long timeout, @NonNull TimeUnit unit, @NonNull CompletableSource fallback) {
3093 Objects.requireNonNull(fallback, "fallback is null");
3094 return timeout0(timeout, unit, Schedulers.computation(), fallback);
3095 }
3096
3097 /**
3098 * Returns a {@code Completable} that runs this {@code Completable} and emits a {@link TimeoutException} in case
3099 * this {@code Completable} doesn't complete within the given time while "waiting" on the specified
3100 * {@link Scheduler}.
3101 * <p>
3102 * <img width="640" height="348" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Completable.timeout.s.png" alt="">
3103 * <dl>
3104 * <dt><b>Scheduler:</b></dt>
3105 * <dd>{@code timeout} signals the {@code TimeoutException} on the {@code Scheduler} you specify.</dd>
3106 * </dl>
3107 * @param timeout the timeout value
3108 * @param unit the unit of {@code timeout}
3109 * @param scheduler the {@code Scheduler} to use to wait for completion and signal {@code TimeoutException}
3110 * @return the new {@code Completable} instance
3111 * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null}
3112 */
3113 @CheckReturnValue
3114 @SchedulerSupport(SchedulerSupport.CUSTOM)
3115 @NonNull
3116 public final Completable timeout(long timeout, @NonNull TimeUnit unit, @NonNull Scheduler scheduler) {
3117 return timeout0(timeout, unit, scheduler, null);
3118 }
3119
3120 /**
3121 * Returns a {@code Completable} that runs this {@code Completable} and switches to the other {@link CompletableSource}
3122 * in case this {@code Completable} doesn't complete within the given time while "waiting" on
3123 * the specified {@link Scheduler}.
3124 * <p>
3125 * <img width="640" height="308" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Completable.timeout.sc.png" alt="">
3126 * <dl>
3127 * <dt><b>Scheduler:</b></dt>
3128 * <dd>{@code timeout} subscribes to the other {@code CompletableSource} on
3129 * the {@code Scheduler} you specify.</dd>
3130 * </dl>
3131 * @param timeout the timeout value
3132 * @param unit the unit of {@code timeout}
3133 * @param scheduler the {@code Scheduler} to use to wait for completion
3134 * @param fallback the other {@code Completable} instance to switch to in case of a timeout
3135 * @return the new {@code Completable} instance
3136 * @throws NullPointerException if {@code unit}, {@code scheduler} or {@code fallback} is {@code null}
3137 */
3138 @CheckReturnValue
3139 @NonNull
3140 @SchedulerSupport(SchedulerSupport.CUSTOM)
3141 public final Completable timeout(long timeout, @NonNull TimeUnit unit, @NonNull Scheduler scheduler, @NonNull CompletableSource fallback) {
3142 Objects.requireNonNull(fallback, "fallback is null");
3143 return timeout0(timeout, unit, scheduler, fallback);
3144 }
3145
3146 /**
3147 * Returns a {@code Completable} that runs this {@code Completable} and optionally switches to the other {@link CompletableSource}
3148 * in case this {@code Completable} doesn't complete within the given time while "waiting" on
3149 * the specified {@link Scheduler}.
3150 * <dl>
3151 * <dt><b>Scheduler:</b></dt>
3152 * <dd>You specify the {@code Scheduler} this operator runs on.</dd>
3153 * </dl>
3154 * @param timeout the timeout value
3155 * @param unit the unit of {@code timeout}
3156 * @param scheduler the {@code Scheduler} to use to wait for completion
3157 * @param fallback the other {@code Completable} instance to switch to in case of a timeout,
3158 * if {@code null} a {@link TimeoutException} is emitted instead
3159 * @return the new {@code Completable} instance
3160 * @throws NullPointerException if {@code unit}, {@code scheduler} or {@code fallback} is {@code null}
3161 */
3162 @CheckReturnValue
3163 @NonNull
3164 @SchedulerSupport(SchedulerSupport.CUSTOM)
3165 private Completable timeout0(long timeout, TimeUnit unit, Scheduler scheduler, CompletableSource fallback) {
3166 Objects.requireNonNull(unit, "unit is null");
3167 Objects.requireNonNull(scheduler, "scheduler is null");
3168 return RxJavaPlugins.onAssembly(new CompletableTimeout(this, timeout, unit, scheduler, fallback));
3169 }
3170
3171 /**
3172 * Calls the specified {@link CompletableConverter} function during assembly time and returns its resulting value.
3173 * <p>
3174 * <img width="640" height="751" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Completable.to.png" alt="">
3175 * <p>
3176 * This allows fluent conversion to any other type.
3177 * <dl>
3178 * <dt><b>Scheduler:</b></dt>
3179 * <dd>{@code to} does not operate by default on a particular {@link Scheduler}.</dd>
3180 * </dl>
3181 * <p>History: 2.1.7 - experimental
3182 * @param <R> the resulting object type
3183 * @param converter the {@code CompletableConverter} that receives the current {@code Completable} instance and returns a value to be the result of {@code to()}
3184 * @return the converted value
3185 * @throws NullPointerException if {@code converter} is {@code null}
3186 * @since 2.2
3187 */
3188 @CheckReturnValue
3189 @SchedulerSupport(SchedulerSupport.NONE)
3190 public final <R> R to(@NonNull CompletableConverter<? extends R> converter) {
3191 return Objects.requireNonNull(converter, "converter is null").apply(this);
3192 }
3193
3194 /**
3195 * Returns a {@link Flowable} which when subscribed to subscribes to this {@code Completable} and
3196 * relays the terminal events to the downstream {@link Subscriber}.
3197 * <p>
3198 * <img width="640" height="585" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Completable.toFlowable.png" alt="">
3199 * <dl>
3200 * <dt><b>Backpressure:</b></dt>
3201 * <dd>The returned {@code Flowable} honors the backpressure of the downstream consumer.</dd>
3202 * <dt><b>Scheduler:</b></dt>
3203 * <dd>{@code toFlowable} does not operate by default on a particular {@link Scheduler}.</dd>
3204 * </dl>
3205 * @param <T> the value type
3206 * @return the new {@code Flowable} instance
3207 */
3208 @CheckReturnValue
3209 @SuppressWarnings("unchecked")
3210 @BackpressureSupport(BackpressureKind.FULL)
3211 @SchedulerSupport(SchedulerSupport.NONE)
3212 @NonNull
3213 public final <@NonNull T> Flowable<T> toFlowable() {
3214 if (this instanceof FuseToFlowable) {
3215 return ((FuseToFlowable<T>)this).fuseToFlowable();
3216 }
3217 return RxJavaPlugins.onAssembly(new CompletableToFlowable<>(this));
3218 }
3219 /**
3220 * Returns a {@link Future} representing the termination of the current {@code Completable}
3221 * via a {@code null} value.
3222 * <p>
3223 * <img width="640" height="433" src="https://github.com/ReactiveX/RxJava/wiki/images/rx-operators/Completable.toFuture.png" alt="">
3224 * <p>
3225 * Cancelling the {@code Future} will cancel the subscription to the current {@code Completable}.
3226 * <dl>
3227 * <dt><b>Scheduler:</b></dt>
3228 * <dd>{@code toFuture} does not operate by default on a particular {@link Scheduler}.</dd>
3229 * </dl>
3230 *
3231 * @return the new {@code Future} instance
3232 * @see <a href="http://reactivex.io/documentation/operators/to.html">ReactiveX documentation: To</a>
3233 * @since 3.0.0
3234 */
3235 @CheckReturnValue
3236 @SchedulerSupport(SchedulerSupport.NONE)
3237 @NonNull
3238 public final Future<Void> toFuture() {
3239 return subscribeWith(new FutureMultiObserver<>());
3240 }
3241
3242 /**
3243 * Converts this {@code Completable} into a {@link Maybe}.
3244 * <p>
3245 * <img width="640" height="585" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Completable.toMaybe.png" alt="">
3246 * <dl>
3247 * <dt><b>Scheduler:</b></dt>
3248 * <dd>{@code toMaybe} does not operate by default on a particular {@link Scheduler}.</dd>
3249 * </dl>
3250 *
3251 * @param <T> the value type
3252 * @return the new {@code Maybe} instance
3253 */
3254 @CheckReturnValue
3255 @SuppressWarnings("unchecked")
3256 @SchedulerSupport(SchedulerSupport.NONE)
3257 @NonNull
3258 public final <@NonNull T> Maybe<T> toMaybe() {
3259 if (this instanceof FuseToMaybe) {
3260 return ((FuseToMaybe<T>)this).fuseToMaybe();
3261 }
3262 return RxJavaPlugins.onAssembly(new MaybeFromCompletable<>(this));
3263 }
3264
3265 /**
3266 * Returns an {@link Observable} which when subscribed to subscribes to this {@code Completable} and
3267 * relays the terminal events to the downstream {@link Observer}.
3268 * <p>
3269 * <img width="640" height="293" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Completable.toObservable.png" alt="">
3270 * <dl>
3271 * <dt><b>Scheduler:</b></dt>
3272 * <dd>{@code toObservable} does not operate by default on a particular {@link Scheduler}.</dd>
3273 * </dl>
3274 * @param <T> the value type
3275 * @return the new {@code Observable} created
3276 */
3277 @CheckReturnValue
3278 @SuppressWarnings("unchecked")
3279 @SchedulerSupport(SchedulerSupport.NONE)
3280 @NonNull
3281 public final <@NonNull T> Observable<T> toObservable() {
3282 if (this instanceof FuseToObservable) {
3283 return ((FuseToObservable<T>)this).fuseToObservable();
3284 }
3285 return RxJavaPlugins.onAssembly(new CompletableToObservable<>(this));
3286 }
3287
3288 /**
3289 * Converts this {@code Completable} into a {@link Single} which when this {@code Completable} completes normally,
3290 * calls the given {@link Supplier} and emits its returned value through {@code onSuccess}.
3291 * <p>
3292 * <img width="640" height="583" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Completable.toSingle.png" alt="">
3293 * <dl>
3294 * <dt><b>Scheduler:</b></dt>
3295 * <dd>{@code toSingle} does not operate by default on a particular {@link Scheduler}.</dd>
3296 * </dl>
3297 * @param <T> the value type
3298 * @param completionValueSupplier the value supplier called when this {@code Completable} completes normally
3299 * @return the new {@code Single} instance
3300 * @throws NullPointerException if {@code completionValueSupplier} is {@code null}
3301 */
3302 @CheckReturnValue
3303 @NonNull
3304 @SchedulerSupport(SchedulerSupport.NONE)
3305 public final <@NonNull T> Single<T> toSingle(@NonNull Supplier<? extends T> completionValueSupplier) {
3306 Objects.requireNonNull(completionValueSupplier, "completionValueSupplier is null");
3307 return RxJavaPlugins.onAssembly(new CompletableToSingle<>(this, completionValueSupplier, null));
3308 }
3309
3310 /**
3311 * Converts this {@code Completable} into a {@link Single} which when this {@code Completable} completes normally,
3312 * emits the given value through {@code onSuccess}.
3313 * <p>
3314 * <img width="640" height="583" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Completable.toSingleDefault.png" alt="">
3315 * <dl>
3316 * <dt><b>Scheduler:</b></dt>
3317 * <dd>{@code toSingleDefault} does not operate by default on a particular {@link Scheduler}.</dd>
3318 * </dl>
3319 * @param <T> the value type
3320 * @param completionValue the value to emit when this {@code Completable} completes normally
3321 * @return the new {@code Single} instance
3322 * @throws NullPointerException if {@code completionValue} is {@code null}
3323 */
3324 @CheckReturnValue
3325 @NonNull
3326 @SchedulerSupport(SchedulerSupport.NONE)
3327 public final <@NonNull T> Single<T> toSingleDefault(T completionValue) {
3328 Objects.requireNonNull(completionValue, "completionValue is null");
3329 return RxJavaPlugins.onAssembly(new CompletableToSingle<>(this, null, completionValue));
3330 }
3331
3332 /**
3333 * Returns a {@code Completable} which makes sure when an observer disposes the subscription, the
3334 * {@code dispose()} method is called on the specified {@link Scheduler}.
3335 * <p>
3336 * <img width="640" height="716" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Completable.unsubscribeOn.png" alt="">
3337 * <dl>
3338 * <dt><b>Scheduler:</b></dt>
3339 * <dd>{@code unsubscribeOn} calls {@code dispose()} of the upstream on the {@code Scheduler} you specify.</dd>
3340 * </dl>
3341 * @param scheduler the target {@code Scheduler} where to execute the disposing
3342 * @return the new {@code Completable} instance
3343 * @throws NullPointerException if {@code scheduler} is {@code null}
3344 */
3345 @CheckReturnValue
3346 @NonNull
3347 @SchedulerSupport(SchedulerSupport.CUSTOM)
3348 public final Completable unsubscribeOn(@NonNull Scheduler scheduler) {
3349 Objects.requireNonNull(scheduler, "scheduler is null");
3350 return RxJavaPlugins.onAssembly(new CompletableDisposeOn(this, scheduler));
3351 }
3352 // -------------------------------------------------------------------------
3353 // Fluent test support, super handy and reduces test preparation boilerplate
3354 // -------------------------------------------------------------------------
3355
3356 /**
3357 * Creates a {@link TestObserver} and subscribes
3358 * it to this {@code Completable}.
3359 * <p>
3360 * <img width="640" height="458" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Completable.test.png" alt="">
3361 * <dl>
3362 * <dt><b>Scheduler:</b></dt>
3363 * <dd>{@code test} does not operate by default on a particular {@link Scheduler}.</dd>
3364 * </dl>
3365 * @return the new {@code TestObserver} instance
3366 * @since 2.0
3367 */
3368 @CheckReturnValue
3369 @SchedulerSupport(SchedulerSupport.NONE)
3370 @NonNull
3371 public final TestObserver<Void> test() {
3372 TestObserver<Void> to = new TestObserver<>();
3373 subscribe(to);
3374 return to;
3375 }
3376
3377 /**
3378 * Creates a {@link TestObserver} optionally in cancelled state, then subscribes it to this {@code Completable}.
3379 * @param dispose if {@code true}, the {@code TestObserver} will be cancelled before subscribing to this
3380 * {@code Completable}.
3381 * <p>
3382 * <img width="640" height="499" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Completable.test.b.png" alt="">
3383 * <dl>
3384 * <dt><b>Scheduler:</b></dt>
3385 * <dd>{@code test} does not operate by default on a particular {@link Scheduler}.</dd>
3386 * </dl>
3387 * @return the new {@code TestObserver} instance
3388 * @since 2.0
3389 */
3390 @CheckReturnValue
3391 @SchedulerSupport(SchedulerSupport.NONE)
3392 @NonNull
3393 public final TestObserver<Void> test(boolean dispose) {
3394 TestObserver<Void> to = new TestObserver<>();
3395
3396 if (dispose) {
3397 to.dispose();
3398 }
3399 subscribe(to);
3400 return to;
3401 }
3402
3403 // -------------------------------------------------------------------------
3404 // JDK 8 Support
3405 // -------------------------------------------------------------------------
3406
3407 /**
3408 * Signals completion (or error) when the {@link CompletionStage} terminates.
3409 * <p>
3410 * <img width="640" height="262" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/fromCompletionStage.c.png" alt="">
3411 * <p>
3412 * Note that the operator takes an already instantiated, running or terminated {@code CompletionStage}.
3413 * If the optional is to be created per consumer upon subscription, use {@link #defer(Supplier)}
3414 * around {@code fromCompletionStage}:
3415 * <pre><code>
3416 * Maybe.defer(() -&gt; Completable.fromCompletionStage(createCompletionStage()));
3417 * </code></pre>
3418 * <p>
3419 * Canceling the flow can't cancel the execution of the {@code CompletionStage} because {@code CompletionStage}
3420 * itself doesn't support cancellation. Instead, the operator detaches from the {@code CompletionStage}.
3421 * <dl>
3422 * <dt><b>Scheduler:</b></dt>
3423 * <dd>{@code fromCompletionStage} does not operate by default on a particular {@link Scheduler}.</dd>
3424 * </dl>
3425 * @param stage the {@code CompletionStage} to convert to a {@code Completable} and
3426 * signal {@code onComplete} or {@code onError} when the {@code CompletionStage} terminates normally or with a failure
3427 * @return the new {@code Completable} instance
3428 * @throws NullPointerException if {@code stage} is {@code null}
3429 * @since 3.0.0
3430 */
3431 @CheckReturnValue
3432 @SchedulerSupport(SchedulerSupport.NONE)
3433 @NonNull
3434 public static Completable fromCompletionStage(@NonNull CompletionStage<?> stage) {
3435 Objects.requireNonNull(stage, "stage is null");
3436 return RxJavaPlugins.onAssembly(new CompletableFromCompletionStage<>(stage));
3437 }
3438
3439 /**
3440 * Signals the given default item when the upstream completes or signals the upstream error via
3441 * a {@link CompletionStage}.
3442 * <p>
3443 * <img width="640" height="323" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/toCompletionStage.c.png" alt="">
3444 * <p>
3445 * The upstream can be canceled by converting the resulting {@code CompletionStage} into
3446 * {@link CompletableFuture} via {@link CompletionStage#toCompletableFuture()} and
3447 * calling {@link CompletableFuture#cancel(boolean)} on it.
3448 * The upstream will be also cancelled if the resulting {@code CompletionStage} is converted to and
3449 * completed manually by {@link CompletableFuture#complete(Object)} or {@link CompletableFuture#completeExceptionally(Throwable)}.
3450 * <p>
3451 * {@code CompletionStage}s don't have a notion of emptiness and allow {@code null}s, therefore, one can either use
3452 * a {@code defaultItem} of {@code null} or turn the flow into a sequence of {@link Optional}s and default to {@link Optional#empty()}:
3453 * <pre><code>
3454 * CompletionStage&lt;Optional&lt;T&gt;&gt; stage = source.map(Optional::of).toCompletionStage(Optional.empty());
3455 * </code></pre>
3456 * <dl>
3457 * <dt><b>Scheduler:</b></dt>
3458 * <dd>{@code toCompletionStage} does not operate by default on a particular {@link Scheduler}.</dd>
3459 * </dl>
3460 * @param <T> the type of the default item to signal upon completion
3461 * @param defaultItem the item to signal upon completion
3462 * @return the new {@code CompletionStage} instance
3463 * @since 3.0.0
3464 */
3465 @CheckReturnValue
3466 @SchedulerSupport(SchedulerSupport.NONE)
3467 @NonNull
3468 public final <@Nullable T> CompletionStage<T> toCompletionStage(T defaultItem) {
3469 return subscribeWith(new CompletionStageConsumer<>(true, defaultItem));
3470 }
3471 }