Debian Codegraph @

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