Debian Codegraph @

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