Debian Codegraph @

src/main/java/io/reactivex/rxjava3/observers/ResourceCompletableObserver.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.observers;
15
16 import java.util.Objects;
17 import java.util.concurrent.atomic.AtomicReference;
18
19 import io.reactivex.rxjava3.annotations.NonNull;
20 import io.reactivex.rxjava3.core.CompletableObserver;
21 import io.reactivex.rxjava3.disposables.Disposable;
22 import io.reactivex.rxjava3.internal.disposables.*;
23 import io.reactivex.rxjava3.internal.util.EndConsumerHelper;
24
25 /**
26 * An abstract {@link CompletableObserver} that allows asynchronous cancellation of its subscription and associated resources.
27 *
28 * <p>All pre-implemented final methods are thread-safe.
29 *
30 * <p>Override the protected {@link #onStart()} to perform initialization when this
31 * {@code ResourceCompletableObserver} is subscribed to a source.
32 *
33 * <p>Use the public {@link #dispose()} method to dispose the sequence externally and release
34 * all resources.
35 *
36 * <p>To release the associated resources, one has to call {@link #dispose()}
37 * in {@code onError()} and {@code onComplete()} explicitly.
38 *
39 * <p>Use {@link #add(Disposable)} to associate resources (as {@link io.reactivex.rxjava3.disposables.Disposable Disposable}s)
40 * with this {@code ResourceCompletableObserver} that will be cleaned up when {@link #dispose()} is called.
41 * Removing previously associated resources is not possible but one can create a
42 * {@link io.reactivex.rxjava3.disposables.CompositeDisposable CompositeDisposable}, associate it with this
43 * {@code ResourceCompletableObserver} and then add/remove resources to/from the {@code CompositeDisposable}
44 * freely.
45 *
46 * <p>Like all other consumers, {@code ResourceCompletableObserver} can be subscribed only once.
47 * Any subsequent attempt to subscribe it to a new source will yield an
48 * {@link IllegalStateException} with message {@code "It is not allowed to subscribe with a(n) <class name> multiple times."}.
49 *
50 * <p>Implementation of {@link #onStart()}, {@link #onError(Throwable)}
51 * and {@link #onComplete()} are not allowed to throw any unchecked exceptions.
52 *
53 * <p>Example<pre><code>
54 * Disposable d =
55 * Completable.complete().delay(1, TimeUnit.SECONDS)
56 * .subscribeWith(new ResourceCompletableObserver() {
57 * &#64;Override public void onStart() {
58 * add(Schedulers.single()
59 * .scheduleDirect(() -&gt; System.out.println("Time!"),
60 * 2, TimeUnit.SECONDS));
61 * }
62 * &#64;Override public void onError(Throwable t) {
63 * t.printStackTrace();
64 * dispose();
65 * }
66 * &#64;Override public void onComplete() {
67 * System.out.println("Done!");
68 * dispose();
69 * }
70 * });
71 * // ...
72 * d.dispose();
73 * </code></pre>
74 */
75 public abstract class ResourceCompletableObserver implements CompletableObserver, Disposable {
76 /** The active subscription. */
77 private final AtomicReference<Disposable> upstream = new AtomicReference<>();
78
79 /** The resource composite, can never be null. */
80 private final ListCompositeDisposable resources = new ListCompositeDisposable();
81
82 /**
83 * Adds a resource to this {@code ResourceCompletableObserver}.
84 *
85 * @param resource the resource to add
86 *
87 * @throws NullPointerException if resource is {@code null}
88 */
89 public final void add(@NonNull Disposable resource) {
90 Objects.requireNonNull(resource, "resource is null");
91 resources.add(resource);
92 }
93
94 @Override
95 public final void onSubscribe(@NonNull Disposable d) {
96 if (EndConsumerHelper.setOnce(this.upstream, d, getClass())) {
97 onStart();
98 }
99 }
100
101 /**
102 * Called once the upstream sets a {@link Disposable} on this {@code ResourceCompletableObserver}.
103 *
104 * <p>You can perform initialization at this moment. The default
105 * implementation does nothing.
106 */
107 protected void onStart() {
108 }
109
110 /**
111 * Cancels the main disposable (if any) and disposes the resources associated with
112 * this {@code ResourceCompletableObserver} (if any).
113 *
114 * <p>This method can be called before the upstream calls {@link #onSubscribe(Disposable)} at which
115 * case the main {@link Disposable} will be immediately disposed.
116 */
117 @Override
118 public final void dispose() {
119 if (DisposableHelper.dispose(upstream)) {
120 resources.dispose();
121 }
122 }
123
124 /**
125 * Returns true if this {@code ResourceCompletableObserver} has been disposed/cancelled.
126 * @return true if this {@code ResourceCompletableObserver} has been disposed/cancelled
127 */
128 @Override
129 public final boolean isDisposed() {
130 return DisposableHelper.isDisposed(upstream.get());
131 }
132 }