0
# Completable API
1

2
Completable is RxJava's reactive type for operations that only signal completion or error without emitting items. It's ideal for actions like save operations, cleanup tasks, or any fire-and-forget operations where you only care about success or failure.
3

4
## Capabilities
5

6
### Completable Creation
7

8
Factory methods for creating Completable instances.
9

10
```java { .api }
11
/**
12
 * Creates a Completable that completes immediately
13
 * @return Completable that signals completion
14
 */
15
public static Completable complete();
16

17
/**
18
 * Creates a Completable from a Runnable, executed lazily
19
 * @param run the Runnable to execute
20
 * @return Completable that executes the Runnable and completes
21
 */
22
public static Completable fromRunnable(Runnable run);
23

24
/**
25
 * Creates a Completable from an Action, executed lazily
26
 * @param action the Action to execute
27
 * @return Completable that executes the Action and completes
28
 */
29
public static Completable fromAction(Action action);
30

31
/**
32
 * Creates a Completable using a custom emitter function
33
 * @param source the CompletableOnSubscribe function
34
 * @return Completable created from the custom emitter
35
 */
36
public static Completable create(CompletableOnSubscribe source);
37

38
/**
39
 * Creates a Completable that only calls onError
40
 * @param error the error to emit
41
 * @return Completable that emits the error
42
 */
43
public static Completable error(Throwable error);
44

45
/**
46
 * Creates a Completable that defers creation until subscription
47
 * @param completableSupplier supplier of Completable to defer
48
 * @return Completable that defers to supplied Completable
49
 */
50
public static Completable defer(Supplier<? extends CompletableSource> completableSupplier);
51

52
/**
53
 * Creates a Completable that never completes or errors
54
 * @return Completable that never signals anything
55
 */
56
public static Completable never();
57

58
/**
59
 * Creates a Completable that completes after a delay
60
 * @param delay the delay duration
61
 * @param unit the time unit
62
 * @return Completable that completes after the delay
63
 */
64
public static Completable timer(long delay, TimeUnit unit);
65

66
/**
67
 * Creates a Completable from a Future, ignoring the result
68
 * @param future the Future to convert
69
 * @return Completable that completes when Future completes
70
 */
71
public static Completable fromFuture(Future<?> future);
72
```
73

74
### Chaining and Continuation
75

76
Chain Completables and continue with other reactive types.
77

78
```java { .api }
79
/**
80
 * Continue with another Completable after this one completes
81
 * @param next Completable to execute after this one
82
 * @return Completable that executes both in sequence
83
 */
84
public final Completable andThen(CompletableSource next);
85

86
/**
87
 * Continue with a Single after this Completable completes
88
 * @param next Single to execute after this completes
89
 * @return Single that executes after this Completable
90
 */
91
public final <T> Single<T> andThen(SingleSource<T> next);
92

93
/**
94
 * Continue with an Observable after this Completable completes
95
 * @param next Observable to execute after this completes
96
 * @return Observable that executes after this Completable
97
 */
98
public final <T> Observable<T> andThen(ObservableSource<T> next);
99

100
/**
101
 * Continue with a Flowable after this Completable completes
102
 * @param next Flowable to execute after this completes
103
 * @return Flowable that executes after this Completable
104
 */
105
public final <T> Flowable<T> andThen(Publisher<T> next);
106

107
/**
108
 * Continue with a Maybe after this Completable completes
109
 * @param next Maybe to execute after this completes
110
 * @return Maybe that executes after this Completable
111
 */
112
public final <T> Maybe<T> andThen(MaybeSource<T> next);
113
```
114

115
### Combination Operators
116

117
Combine multiple Completable sources.
118

119
```java { .api }
120
/**
121
 * Merge multiple Completables (complete when all complete)
122
 * @param sources array of Completable sources
123
 * @return Completable that completes when all sources complete
124
 */
125
public static Completable merge(CompletableSource... sources);
126

127
/**
128
 * Merge multiple Completables from an Iterable
129
 * @param sources Iterable of Completable sources
130
 * @return Completable that completes when all sources complete
131
 */
132
public static Completable merge(Iterable<? extends CompletableSource> sources);
133

134
/**
135
 * Concatenate multiple Completables in sequence
136
 * @param sources array of Completable sources
137
 * @return Completable that executes all sources in order
138
 */
139
public static Completable concat(CompletableSource... sources);
140

141
/**
142
 * Merge this Completable with another
143
 * @param other Completable to merge with this one
144
 * @return Completable that completes when both complete
145
 */
146
public final Completable mergeWith(CompletableSource other);
147

148
/**
149
 * Race multiple Completables (complete with the first one)
150
 * @param sources array of Completable sources
151
 * @return Completable that completes with the first source
152
 */
153
public static Completable amb(CompletableSource... sources);
154

155
/**
156
 * Race this Completable with another
157
 * @param other Completable to race with this one
158
 * @return Completable that completes with the first one
159
 */
160
public final Completable ambWith(CompletableSource other);
161
```
162

163
### Subscription and Scheduling
164

165
Control subscription behavior and execution context.
166

167
```java { .api }
168
/**
169
 * Subscribe with a simple onComplete callback
170
 * @param onComplete action called when completed
171
 * @return Disposable for managing the subscription
172
 */
173
public final Disposable subscribe(Action onComplete);
174

175
/**
176
 * Subscribe with onComplete and onError callbacks
177
 * @param onComplete action called when completed
178
 * @param onError action called on error
179
 * @return Disposable for managing the subscription
180
 */
181
public final Disposable subscribe(Action onComplete, Consumer<? super Throwable> onError);
182

183
/**
184
 * Subscribe with full CompletableObserver interface
185
 * @param observer the CompletableObserver to receive signals
186
 */
187
public final void subscribe(CompletableObserver observer);
188

189
/**
190
 * Subscribe and block until completion
191
 */
192
public final void blockingAwait();
193

194
/**
195
 * Subscribe and block until completion with timeout
196
 * @param timeout the timeout duration
197
 * @param unit the time unit
198
 * @return true if completed within timeout, false if timeout occurred
199
 */
200
public final boolean blockingAwait(long timeout, TimeUnit unit);
201

202
/**
203
 * Specify the Scheduler for subscription operations
204
 * @param scheduler the Scheduler to use for subscriptions
205
 * @return Completable operating on the specified scheduler
206
 */
207
public final Completable subscribeOn(Scheduler scheduler);
208

209
/**
210
 * Specify the Scheduler for observation operations
211
 * @param scheduler the Scheduler to use for observations
212
 * @return Completable observing on the specified scheduler
213
 */
214
public final Completable observeOn(Scheduler scheduler);
215

216
/**
217
 * Add a delay before completing
218
 * @param delay the delay duration
219
 * @param unit the time unit
220
 * @return Completable that completes after the delay
221
 */
222
public final Completable delay(long delay, TimeUnit unit);
223
```
224

225
### Error Handling
226

227
Handle errors in the Completable stream.
228

229
```java { .api }
230
/**
231
 * Resume with another Completable when an error occurs
232
 * @param resumeSource Completable to switch to on error
233
 * @return Completable that switches to resumeSource on error
234
 */
235
public final Completable onErrorResumeNext(CompletableSource resumeSource);
236

237
/**
238
 * Complete normally instead of error when an error occurs
239
 * @return Completable that completes on any error
240
 */
241
public final Completable onErrorComplete();
242

243
/**
244
 * Complete normally for specific errors using a predicate
245
 * @param predicate function to test if error should be converted to completion
246
 * @return Completable that completes for matching errors
247
 */
248
public final Completable onErrorComplete(Predicate<? super Throwable> predicate);
249

250
/**
251
 * Retry the subscription when an error occurs
252
 * @param times maximum number of retry attempts
253
 * @return Completable that retries up to the specified times
254
 */
255
public final Completable retry(long times);
256

257
/**
258
 * Perform side-effect action when an error occurs
259
 * @param onError action to perform on error
260
 * @return Completable that performs the action on error
261
 */
262
public final Completable doOnError(Consumer<? super Throwable> onError);
263
```
264

265
### Side Effects
266

267
Perform side-effect actions without modifying the stream.
268

269
```java { .api }
270
/**
271
 * Perform an action when Completable completes
272
 * @param onComplete action to perform on completion
273
 * @return Completable that performs the action on completion
274
 */
275
public final Completable doOnComplete(Action onComplete);
276

277
/**
278
 * Perform an action when subscription occurs
279
 * @param onSubscribe action to perform on subscription
280
 * @return Completable that performs the action on subscription
281
 */
282
public final Completable doOnSubscribe(Consumer<? super Disposable> onSubscribe);
283

284
/**
285
 * Perform an action when disposal occurs
286
 * @param onDispose action to perform on disposal
287
 * @return Completable that performs the action on disposal
288
 */
289
public final Completable doOnDispose(Action onDispose);
290

291
/**
292
 * Perform an action on any terminal event (complete or error)
293
 * @param onTerminate action to perform on terminal event
294
 * @return Completable that performs the action on terminal events
295
 */
296
public final Completable doOnTerminate(Action onTerminate);
297

298
/**
299
 * Perform an action after any terminal event (complete or error)
300
 * @param onAfterTerminate action to perform after terminal event
301
 * @return Completable that performs the action after terminal events
302
 */
303
public final Completable doAfterTerminate(Action onAfterTerminate);
304

305
/**
306
 * Perform an action on any event (success, error, disposal)
307
 * @param onFinally action to perform on any final event
308
 * @return Completable that performs the action on final events
309
 */
310
public final Completable doFinally(Action onFinally);
311
```
312

313
### Type Conversions
314

315
Convert to other reactive types.
316

317
```java { .api }
318
/**
319
 * Convert to Observable (completes empty or errors)
320
 * @return Observable that completes empty or errors
321
 */
322
public final <T> Observable<T> toObservable();
323

324
/**
325
 * Convert to Flowable (completes empty or errors)
326
 * @return Flowable that completes empty or errors
327
 */
328
public final <T> Flowable<T> toFlowable();
329

330
/**
331
 * Convert to Single with provided value on completion
332
 * @param completionValue value to emit on successful completion
333
 * @return Single that emits the value on completion
334
 */
335
public final <T> Single<T> toSingle(Supplier<? extends T> completionValue);
336

337
/**
338
 * Convert to Maybe (completes empty or errors)
339
 * @return Maybe that completes empty or errors
340
 */
341
public final <T> Maybe<T> toMaybe();
342
```
343

344
## Types
345

346
```java { .api }
347
/**
348
 * Interface for creating custom Completable sources
349
 */
350
public interface CompletableOnSubscribe {
351
    void subscribe(CompletableEmitter emitter) throws Throwable;
352
}
353

354
/**
355
 * Emitter interface for custom Completable creation
356
 */
357
public interface CompletableEmitter {
358
    void onComplete();
359
    void onError(Throwable error);
360
    boolean isDisposed();
361
}
362

363
/**
364
 * Observer interface for Completable
365
 */
366
public interface CompletableObserver {
367
    void onSubscribe(Disposable d);
368
    void onComplete();
369
    void onError(Throwable e);
370
}
371

372
/**
373
 * Base interface for Completable sources
374
 */
375
public interface CompletableSource {
376
    void subscribe(CompletableObserver observer);
377
}
378
```
379

380
**Usage Examples:**
381

382
```java
383
import io.reactivex.rxjava3.core.Completable;
384
import io.reactivex.rxjava3.schedulers.Schedulers;
385
import java.util.concurrent.TimeUnit;
386

387
// Basic Completable operations
388
Completable.fromRunnable(() -> System.out.println("Task executed"))
389
    .subscribe(
390
        () -> System.out.println("Completed"),
391
        error -> System.err.println("Error: " + error)
392
    );
393

394
// Chaining operations
395
Completable.fromAction(() -> System.out.println("First task"))
396
    .andThen(Completable.fromAction(() -> System.out.println("Second task")))
397
    .andThen(Completable.fromAction(() -> System.out.println("Third task")))
398
    .subscribe(() -> System.out.println("All tasks completed"));
399

400
// Async execution with scheduling
401
Completable.fromCallable(() -> {
402
        Thread.sleep(1000);
403
        System.out.println("Background task completed");
404
        return null;
405
    })
406
    .subscribeOn(Schedulers.io())
407
    .observeOn(Schedulers.single())
408
    .subscribe(() -> System.out.println("Notified on main thread"));
409

410
// Error handling
411
Completable.fromAction(() -> {
412
        if (Math.random() > 0.5) {
413
            throw new RuntimeException("Random failure");
414
        }
415
        System.out.println("Task succeeded");
416
    })
417
    .onErrorComplete()  // Convert errors to completion
418
    .subscribe(() -> System.out.println("Always completes"));
419

420
// Combining multiple Completables
421
Completable task1 = Completable.fromAction(() -> System.out.println("Task 1"));
422
Completable task2 = Completable.fromAction(() -> System.out.println("Task 2"));
423
Completable task3 = Completable.fromAction(() -> System.out.println("Task 3"));
424

425
// Run all in parallel
426
Completable.merge(task1, task2, task3)
427
    .subscribe(() -> System.out.println("All parallel tasks completed"));
428

429
// Run in sequence
430
Completable.concat(task1, task2, task3)
431
    .subscribe(() -> System.out.println("All sequential tasks completed"));
432

433
// Timeout and retry
434
Completable.fromAction(() -> {
435
        Thread.sleep(2000);  // Simulate slow operation
436
        System.out.println("Slow task completed");
437
    })
438
    .timeout(1, TimeUnit.SECONDS)
439
    .retry(2)
440
    .onErrorComplete()
441
    .subscribe(() -> System.out.println("Task handled"));
442

443
// Continue with other reactive types
444
Completable.complete()
445
    .andThen(Single.just("Result after completion"))
446
    .subscribe(System.out::println);
447
```