Debian Codegraph @

src/main/java/io/reactivex/rxjava3/flowables/ConnectableFlowable.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.flowables;
15
16 import java.util.Objects;
17 import java.util.concurrent.TimeUnit;
18
19 import org.reactivestreams.*;
20
21 import io.reactivex.rxjava3.annotations.*;
22 import io.reactivex.rxjava3.core.*;
23 import io.reactivex.rxjava3.disposables.Disposable;
24 import io.reactivex.rxjava3.functions.Consumer;
25 import io.reactivex.rxjava3.internal.functions.*;
26 import io.reactivex.rxjava3.internal.operators.flowable.*;
27 import io.reactivex.rxjava3.internal.util.ConnectConsumer;
28 import io.reactivex.rxjava3.plugins.RxJavaPlugins;
29 import io.reactivex.rxjava3.schedulers.Schedulers;
30
31 /**
32 * A {@code ConnectableFlowable} resembles an ordinary {@link Flowable}, except that it does not begin
33 * emitting items when it is subscribed to, but only when its {@link #connect} method is called. In this way you
34 * can wait for all intended {@link Subscriber}s to {@link Flowable#subscribe} to the {@code Flowable}
35 * before the {@code Flowable} begins emitting items.
36 * <p>
37 * <img width="640" height="510" src="https://github.com/ReactiveX/RxJava/wiki/images/rx-operators/publishConnect.v3.png" alt="">
38 * <p>
39 * When the upstream terminates, the {@code ConnectableFlowable} remains in this terminated state and,
40 * depending on the actual underlying implementation, relays cached events to late {@code Subscriber}s.
41 * In order to reuse and restart this {@code ConnectableFlowable}, the {@link #reset()} method has to be called.
42 * When called, this {@code ConnectableFlowable} will appear as fresh, unconnected source to new {@code Subscriber}s.
43 * Disposing the connection will reset the {@code ConnectableFlowable} to its fresh state and there is no need to call
44 * {@code reset()} in this case.
45 * <p>
46 * Note that although {@link #connect()} and {@link #reset()} are safe to call from multiple threads, it is recommended
47 * a dedicated thread or business logic manages the connection or resetting of a {@code ConnectableFlowable} so that
48 * there is no unwanted signal loss due to early {@code connect()} or {@code reset()} calls while {@code Subscriber}s are
49 * still being subscribed to to this {@code ConnectableFlowable} to receive signals from the get go.
50 * <p>
51 * @see <a href="https://github.com/ReactiveX/RxJava/wiki/Connectable-Observable-Operators">RxJava Wiki: Connectable Observable Operators</a>
52 * @param <T>
53 * the type of items emitted by the {@code ConnectableFlowable}
54 * @since 2.0.0
55 */
56 public abstract class ConnectableFlowable<T> extends Flowable<T> {
57
58 /**
59 * Instructs the {@code ConnectableFlowable} to begin emitting the items from its underlying
60 * {@link Flowable} to its {@link Subscriber}s.
61 * <dl>
62 * <dt><b>Scheduler:</b></dt>
63 * <dd>The behavior is determined by the implementor of this abstract class.</dd>
64 * </dl>
65 *
66 * @param connection
67 * the action that receives the connection subscription before the subscription to source happens
68 * allowing the caller to synchronously disconnect a synchronous source
69 * @throws NullPointerException if {@code connection} is {@code null}
70 * @see <a href="http://reactivex.io/documentation/operators/connect.html">ReactiveX documentation: Connect</a>
71 */
72 @SchedulerSupport(SchedulerSupport.NONE)
73 public abstract void connect(@NonNull Consumer<? super Disposable> connection);
74
75 /**
76 * Resets this {@code ConnectableFlowable} into its fresh state if it has terminated.
77 * <p>
78 * Calling this method on a fresh or active {@code ConnectableFlowable} has no effect.
79 * <dl>
80 * <dt><b>Scheduler:</b></dt>
81 * <dd>The behavior is determined by the implementor of this abstract class.</dd>
82 * </dl>
83 * @since 3.0.0
84 */
85 @SchedulerSupport(SchedulerSupport.NONE)
86 public abstract void reset();
87
88 /**
89 * Instructs the {@code ConnectableFlowable} to begin emitting the items from its underlying
90 * {@link Flowable} to its {@link Subscriber}s.
91 * <p>
92 * To disconnect from a synchronous source, use the {@link #connect(io.reactivex.rxjava3.functions.Consumer)} method.
93 * <dl>
94 * <dt><b>Scheduler:</b></dt>
95 * <dd>The behavior is determined by the implementor of this abstract class.</dd>
96 * </dl>
97 *
98 * @return the subscription representing the connection
99 * @see <a href="http://reactivex.io/documentation/operators/connect.html">ReactiveX documentation: Connect</a>
100 */
101 @NonNull
102 @SchedulerSupport(SchedulerSupport.NONE)
103 public final Disposable connect() {
104 ConnectConsumer cc = new ConnectConsumer();
105 connect(cc);
106 return cc.disposable;
107 }
108
109 /**
110 * Returns a {@link Flowable} that stays connected to this {@code ConnectableFlowable} as long as there
111 * is at least one subscription to this {@code ConnectableFlowable}.
112 * <dl>
113 * <dt><b>Backpressure:</b></dt>
114 * <dd>The operator itself doesn't interfere with backpressure which is determined by the upstream
115 * {@code ConnectableFlowable}'s backpressure behavior.</dd>
116 * <dt><b>Scheduler:</b></dt>
117 * <dd>This {@code refCount} overload does not operate on any particular {@link Scheduler}.</dd>
118 * </dl>
119 * @return the new {@code Flowable} instance
120 * @see <a href="http://reactivex.io/documentation/operators/refcount.html">ReactiveX documentation: RefCount</a>
121 * @see #refCount(int)
122 * @see #refCount(long, TimeUnit)
123 * @see #refCount(int, long, TimeUnit)
124 */
125 @NonNull
126 @CheckReturnValue
127 @SchedulerSupport(SchedulerSupport.NONE)
128 @BackpressureSupport(BackpressureKind.PASS_THROUGH)
129 public Flowable<T> refCount() {
130 return RxJavaPlugins.onAssembly(new FlowableRefCount<>(this));
131 }
132
133 /**
134 * Connects to the upstream {@code ConnectableFlowable} if the number of subscribed
135 * subscriber reaches the specified count and disconnect if all subscribers have unsubscribed.
136 * <dl>
137 * <dt><b>Backpressure:</b></dt>
138 * <dd>The operator itself doesn't interfere with backpressure which is determined by the upstream
139 * {@code ConnectableFlowable}'s backpressure behavior.</dd>
140 * <dt><b>Scheduler:</b></dt>
141 * <dd>This {@code refCount} overload does not operate on any particular {@link Scheduler}.</dd>
142 * </dl>
143 * <p>History: 2.1.14 - experimental
144 * @param subscriberCount the number of subscribers required to connect to the upstream
145 * @return the new {@link Flowable} instance
146 * @throws IllegalArgumentException if {@code subscriberCount} is non-positive
147 * @since 2.2
148 */
149 @CheckReturnValue
150 @SchedulerSupport(SchedulerSupport.NONE)
151 @BackpressureSupport(BackpressureKind.PASS_THROUGH)
152 @NonNull
153 public final Flowable<T> refCount(int subscriberCount) {
154 return refCount(subscriberCount, 0, TimeUnit.NANOSECONDS, Schedulers.trampoline());
155 }
156
157 /**
158 * Connects to the upstream {@code ConnectableFlowable} if the number of subscribed
159 * subscriber reaches 1 and disconnect after the specified
160 * timeout if all subscribers have unsubscribed.
161 * <dl>
162 * <dt><b>Backpressure:</b></dt>
163 * <dd>The operator itself doesn't interfere with backpressure which is determined by the upstream
164 * {@code ConnectableFlowable}'s backpressure behavior.</dd>
165 * <dt><b>Scheduler:</b></dt>
166 * <dd>This {@code refCount} overload operates on the {@code computation} {@link Scheduler}.</dd>
167 * </dl>
168 * <p>History: 2.1.14 - experimental
169 * @param timeout the time to wait before disconnecting after all subscribers unsubscribed
170 * @param unit the time unit of the timeout
171 * @return the new {@link Flowable} instance
172 * @throws NullPointerException if {@code unit} is {@code null}
173 * @see #refCount(long, TimeUnit, Scheduler)
174 * @since 2.2
175 */
176 @CheckReturnValue
177 @SchedulerSupport(SchedulerSupport.COMPUTATION)
178 @BackpressureSupport(BackpressureKind.PASS_THROUGH)
179 @NonNull
180 public final Flowable<T> refCount(long timeout, @NonNull TimeUnit unit) {
181 return refCount(1, timeout, unit, Schedulers.computation());
182 }
183
184 /**
185 * Connects to the upstream {@code ConnectableFlowable} if the number of subscribed
186 * subscriber reaches 1 and disconnect after the specified
187 * timeout if all subscribers have unsubscribed.
188 * <dl>
189 * <dt><b>Backpressure:</b></dt>
190 * <dd>The operator itself doesn't interfere with backpressure which is determined by the upstream
191 * {@code ConnectableFlowable}'s backpressure behavior.</dd>
192 * <dt><b>Scheduler:</b></dt>
193 * <dd>This {@code refCount} overload operates on the specified {@link Scheduler}.</dd>
194 * </dl>
195 * <p>History: 2.1.14 - experimental
196 * @param timeout the time to wait before disconnecting after all subscribers unsubscribed
197 * @param unit the time unit of the timeout
198 * @param scheduler the target scheduler to wait on before disconnecting
199 * @return the new {@link Flowable} instance
200 * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null}
201 * @since 2.2
202 */
203 @CheckReturnValue
204 @SchedulerSupport(SchedulerSupport.CUSTOM)
205 @BackpressureSupport(BackpressureKind.PASS_THROUGH)
206 @NonNull
207 public final Flowable<T> refCount(long timeout, @NonNull TimeUnit unit, @NonNull Scheduler scheduler) {
208 return refCount(1, timeout, unit, scheduler);
209 }
210
211 /**
212 * Connects to the upstream {@code ConnectableFlowable} if the number of subscribed
213 * subscriber reaches the specified count and disconnect after the specified
214 * timeout if all subscribers have unsubscribed.
215 * <dl>
216 * <dt><b>Backpressure:</b></dt>
217 * <dd>The operator itself doesn't interfere with backpressure which is determined by the upstream
218 * {@code ConnectableFlowable}'s backpressure behavior.</dd>
219 * <dt><b>Scheduler:</b></dt>
220 * <dd>This {@code refCount} overload operates on the {@code computation} {@link Scheduler}.</dd>
221 * </dl>
222 * <p>History: 2.1.14 - experimental
223 * @param subscriberCount the number of subscribers required to connect to the upstream
224 * @param timeout the time to wait before disconnecting after all subscribers unsubscribed
225 * @param unit the time unit of the timeout
226 * @return the new {@link Flowable} instance
227 * @throws NullPointerException if {@code unit} is {@code null}
228 * @throws IllegalArgumentException if {@code subscriberCount} is non-positive
229 * @see #refCount(int, long, TimeUnit, Scheduler)
230 * @since 2.2
231 */
232 @CheckReturnValue
233 @SchedulerSupport(SchedulerSupport.COMPUTATION)
234 @BackpressureSupport(BackpressureKind.PASS_THROUGH)
235 @NonNull
236 public final Flowable<T> refCount(int subscriberCount, long timeout, @NonNull TimeUnit unit) {
237 return refCount(subscriberCount, timeout, unit, Schedulers.computation());
238 }
239
240 /**
241 * Connects to the upstream {@code ConnectableFlowable} if the number of subscribed
242 * subscriber reaches the specified count and disconnect after the specified
243 * timeout if all subscribers have unsubscribed.
244 * <dl>
245 * <dt><b>Backpressure:</b></dt>
246 * <dd>The operator itself doesn't interfere with backpressure which is determined by the upstream
247 * {@code ConnectableFlowable}'s backpressure behavior.</dd>
248 * <dt><b>Scheduler:</b></dt>
249 * <dd>This {@code refCount} overload operates on the specified {@link Scheduler}.</dd>
250 * </dl>
251 * <p>History: 2.1.14 - experimental
252 * @param subscriberCount the number of subscribers required to connect to the upstream
253 * @param timeout the time to wait before disconnecting after all subscribers unsubscribed
254 * @param unit the time unit of the timeout
255 * @param scheduler the target scheduler to wait on before disconnecting
256 * @return the new {@link Flowable} instance
257 * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null}
258 * @throws IllegalArgumentException if {@code subscriberCount} is non-positive
259 * @since 2.2
260 */
261 @CheckReturnValue
262 @SchedulerSupport(SchedulerSupport.CUSTOM)
263 @BackpressureSupport(BackpressureKind.PASS_THROUGH)
264 @NonNull
265 public final Flowable<T> refCount(int subscriberCount, long timeout, @NonNull TimeUnit unit, @NonNull Scheduler scheduler) {
266 ObjectHelper.verifyPositive(subscriberCount, "subscriberCount");
267 Objects.requireNonNull(unit, "unit is null");
268 Objects.requireNonNull(scheduler, "scheduler is null");
269 return RxJavaPlugins.onAssembly(new FlowableRefCount<>(this, subscriberCount, timeout, unit, scheduler));
270 }
271
272 /**
273 * Returns a {@link Flowable} that automatically connects (at most once) to this {@code ConnectableFlowable}
274 * when the first {@link Subscriber} subscribes.
275 * <p>
276 * <img width="640" height="392" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/autoConnect.f.png" alt="">
277 * <p>
278 * The connection happens after the first subscription and happens at most once
279 * during the lifetime of the returned {@code Flowable}. If this {@code ConnectableFlowable}
280 * terminates, the connection is never renewed, no matter how {@code Subscriber}s come
281 * and go. Use {@link #refCount()} to renew a connection or dispose an active
282 * connection when all {@code Subscriber}s have cancelled their {@link Subscription}s.
283 * <p>
284 * This overload does not allow disconnecting the connection established via
285 * {@link #connect(Consumer)}. Use the {@link #autoConnect(int, Consumer)} overload
286 * to gain access to the {@link Disposable} representing the only connection.
287 * <dl>
288 * <dt><b>Backpressure:</b></dt>
289 * <dd>The operator itself doesn't interfere with backpressure which is determined by
290 * the upstream {@code ConnectableFlowable}'s behavior.</dd>
291 * <dt><b>Scheduler:</b></dt>
292 * <dd>{@code autoConnect} does not operate by default on a particular {@link Scheduler}.</dd>
293 * </dl>
294 *
295 * @return a new {@code Flowable} instance that automatically connects to this {@code ConnectableFlowable}
296 * when the first {@code Subscriber} subscribes
297 * @see #refCount()
298 * @see #autoConnect(int, Consumer)
299 */
300 @NonNull
301 @CheckReturnValue
302 @BackpressureSupport(BackpressureKind.PASS_THROUGH)
303 @SchedulerSupport(SchedulerSupport.NONE)
304 public Flowable<T> autoConnect() {
305 return autoConnect(1);
306 }
307 /**
308 * Returns a {@link Flowable} that automatically connects (at most once) to this {@code ConnectableFlowable}
309 * when the specified number of {@link Subscriber}s subscribe to it.
310 * <p>
311 * <img width="640" height="392" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/autoConnect.f.png" alt="">
312 * <p>
313 * The connection happens after the given number of subscriptions and happens at most once
314 * during the lifetime of the returned {@code Flowable}. If this {@code ConnectableFlowable}
315 * terminates, the connection is never renewed, no matter how {@code Subscriber}s come
316 * and go. Use {@link #refCount()} to renew a connection or dispose an active
317 * connection when all {@code Subscriber}s have cancelled their {@link Subscription}s.
318 * <p>
319 * This overload does not allow disconnecting the connection established via
320 * {@link #connect(Consumer)}. Use the {@link #autoConnect(int, Consumer)} overload
321 * to gain access to the {@link Disposable} representing the only connection.
322 * <dl>
323 * <dt><b>Backpressure:</b></dt>
324 * <dd>The operator itself doesn't interfere with backpressure which is determined by
325 * the upstream {@code ConnectableFlowable}'s behavior.</dd>
326 * <dt><b>Scheduler:</b></dt>
327 * <dd>{@code autoConnect} does not operate by default on a particular {@link Scheduler}.</dd>
328 * </dl>
329 *
330 * @param numberOfSubscribers the number of subscribers to await before calling connect
331 * on the {@code ConnectableFlowable}. A non-positive value indicates
332 * an immediate connection.
333 * @return a new {@code Flowable} instance that automatically connects to this {@code ConnectableFlowable}
334 * when the specified number of {@code Subscriber}s subscribe to it
335 */
336 @NonNull
337 @CheckReturnValue
338 @BackpressureSupport(BackpressureKind.PASS_THROUGH)
339 @SchedulerSupport(SchedulerSupport.NONE)
340 public Flowable<T> autoConnect(int numberOfSubscribers) {
341 return autoConnect(numberOfSubscribers, Functions.emptyConsumer());
342 }
343
344 /**
345 * Returns a {@link Flowable} that automatically connects (at most once) to this {@code ConnectableFlowable}
346 * when the specified number of {@link Subscriber}s subscribe to it and calls the
347 * specified callback with the {@link Disposable} associated with the established connection.
348 * <p>
349 * <img width="640" height="392" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/autoConnect.f.png" alt="">
350 * <p>
351 * The connection happens after the given number of subscriptions and happens at most once
352 * during the lifetime of the returned {@code Flowable}. If this {@code ConnectableFlowable}
353 * terminates, the connection is never renewed, no matter how {@code Subscriber}s come
354 * and go. Use {@link #refCount()} to renew a connection or dispose an active
355 * connection when all {@code Subscriber}s have cancelled their {@link Subscription}s.
356 * <dl>
357 * <dt><b>Backpressure:</b></dt>
358 * <dd>The operator itself doesn't interfere with backpressure which is determined by
359 * the upstream {@code ConnectableFlowable}'s behavior.</dd>
360 * <dt><b>Scheduler:</b></dt>
361 * <dd>{@code autoConnect} does not operate by default on a particular {@link Scheduler}.</dd>
362 * </dl>
363 *
364 * @param numberOfSubscribers the number of subscribers to await before calling connect
365 * on the {@code ConnectableFlowable}. A non-positive value indicates
366 * an immediate connection.
367 * @param connection the callback {@link Consumer} that will receive the {@code Disposable} representing the
368 * established connection
369 * @return a new {@code Flowable} instance that automatically connects to this {@code ConnectableFlowable}
370 * when the specified number of {@code Subscriber}s subscribe to it and calls the
371 * specified callback with the {@code Disposable} associated with the established connection
372 * @throws NullPointerException if {@code connection} is {@code null}
373 */
374 @NonNull
375 @CheckReturnValue
376 @BackpressureSupport(BackpressureKind.PASS_THROUGH)
377 @SchedulerSupport(SchedulerSupport.NONE)
378 public Flowable<T> autoConnect(int numberOfSubscribers, @NonNull Consumer<? super Disposable> connection) {
379 Objects.requireNonNull(connection, "connection is null");
380 if (numberOfSubscribers <= 0) {
381 this.connect(connection);
382 return RxJavaPlugins.onAssembly(this);
383 }
384 return RxJavaPlugins.onAssembly(new FlowableAutoConnect<>(this, numberOfSubscribers, connection));
385 }
386 }