Debian Codegraph @

src/main/java/io/reactivex/rxjava3/core/Flowable.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.core;
15
16 import java.util.*;
17 import java.util.concurrent.*;
18 import java.util.stream.*;
19
20 import org.reactivestreams.*;
21
22 import io.reactivex.rxjava3.annotations.*;
23 import io.reactivex.rxjava3.disposables.*;
24 import io.reactivex.rxjava3.exceptions.*;
25 import io.reactivex.rxjava3.flowables.*;
26 import io.reactivex.rxjava3.functions.*;
27 import io.reactivex.rxjava3.internal.functions.*;
28 import io.reactivex.rxjava3.internal.jdk8.*;
29 import io.reactivex.rxjava3.internal.operators.flowable.*;
30 import io.reactivex.rxjava3.internal.operators.maybe.MaybeToFlowable;
31 import io.reactivex.rxjava3.internal.operators.mixed.*;
32 import io.reactivex.rxjava3.internal.operators.observable.ObservableFromPublisher;
33 import io.reactivex.rxjava3.internal.operators.single.SingleToFlowable;
34 import io.reactivex.rxjava3.internal.schedulers.ImmediateThinScheduler;
35 import io.reactivex.rxjava3.internal.subscribers.*;
36 import io.reactivex.rxjava3.internal.util.*;
37 import io.reactivex.rxjava3.operators.ScalarSupplier;
38 import io.reactivex.rxjava3.parallel.ParallelFlowable;
39 import io.reactivex.rxjava3.plugins.RxJavaPlugins;
40 import io.reactivex.rxjava3.schedulers.*;
41 import io.reactivex.rxjava3.subscribers.*;
42
43 /**
44 * The {@code Flowable} class that implements the <a href="https://github.com/reactive-streams/reactive-streams-jvm">Reactive Streams</a> {@link Publisher}
45 * Pattern and offers factory methods, intermediate operators and the ability to consume reactive dataflows.
46 * <p>
47 * <em>Reactive Streams</em> operates with {@code Publisher}s which {@code Flowable} extends. Many operators
48 * therefore accept general {@code Publisher}s directly and allow direct interoperation with other
49 * <em>Reactive Streams</em> implementations.
50 * <p>
51 * The {@code Flowable} hosts the default buffer size of 128 elements for operators, accessible via {@link #bufferSize()},
52 * that can be overridden globally via the system parameter {@code rx3.buffer-size}. Most operators, however, have
53 * overloads that allow setting their internal buffer size explicitly.
54 * <p>
55 * The documentation for this class makes use of marble diagrams. The following legend explains these diagrams:
56 * <p>
57 * <img width="640" height="317" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/legend.v3.png" alt="">
58 * <p>
59 * The {@code Flowable} follows the protocol
60 * <pre><code>
61 * onSubscribe onNext* (onError | onComplete)?
62 * </code></pre>
63 * where the stream can be disposed through the {@link Subscription} instance provided to consumers through
64 * {@link Subscriber#onSubscribe(Subscription)}.
65 * Unlike the {@code Observable.subscribe()} of version 1.x, {@link #subscribe(Subscriber)} does not allow external cancellation
66 * of a subscription and the {@link Subscriber} instance is expected to expose such capability if needed.
67 * <p>
68 * {@code Flowable}s support backpressure and require {@code Subscriber}s to signal demand via {@link Subscription#request(long)}.
69 * <p>
70 * Example:
71 * <pre><code>
72 * Disposable d = Flowable.just("Hello world!")
73 * .delay(1, TimeUnit.SECONDS)
74 * .subscribeWith(new DisposableSubscriber&lt;String&gt;() {
75 * &#64;Override public void onStart() {
76 * System.out.println("Start!");
77 * request(1);
78 * }
79 * &#64;Override public void onNext(String t) {
80 * System.out.println(t);
81 * request(1);
82 * }
83 * &#64;Override public void onError(Throwable t) {
84 * t.printStackTrace();
85 * }
86 * &#64;Override public void onComplete() {
87 * System.out.println("Done!");
88 * }
89 * });
90 *
91 * Thread.sleep(500);
92 * // the sequence can now be cancelled via dispose()
93 * d.dispose();
94 * </code></pre>
95 * <p>
96 * The <em>Reactive Streams</em> specification is relatively strict when defining interactions between {@code Publisher}s and {@code Subscriber}s, so much so
97 * that there is a significant performance penalty due certain timing requirements and the need to prepare for invalid
98 * request amounts via {@link Subscription#request(long)}.
99 * Therefore, RxJava has introduced the {@link FlowableSubscriber} interface that indicates the consumer can be driven with relaxed rules.
100 * All RxJava operators are implemented with these relaxed rules in mind.
101 * If the subscribing {@code Subscriber} does not implement this interface, for example, due to it being from another <em>Reactive Streams</em> compliant
102 * library, the {@code Flowable} will automatically apply a compliance wrapper around it.
103 * <p>
104 * {@code Flowable} is an abstract class, but it is not advised to implement sources and custom operators by extending the class directly due
105 * to the large amounts of <a href="https://github.com/reactive-streams/reactive-streams-jvm#specification">Reactive Streams</a>
106 * rules to be followed to the letter. See <a href="https://github.com/ReactiveX/RxJava/wiki/Writing-operators-for-2.0">the wiki</a> for
107 * some guidance if such custom implementations are necessary.
108 * <p>
109 * The recommended way of creating custom {@code Flowable}s is by using the {@link #create(FlowableOnSubscribe, BackpressureStrategy)} factory method:
110 * <pre><code>
111 * Flowable&lt;String&gt; source = Flowable.create(new FlowableOnSubscribe&lt;String&gt;() {
112 * &#64;Override
113 * public void subscribe(FlowableEmitter&lt;String&gt; emitter) throws Exception {
114 *
115 * // signal an item
116 * emitter.onNext("Hello");
117 *
118 * // could be some blocking operation
119 * Thread.sleep(1000);
120 *
121 * // the consumer might have cancelled the flow
122 * if (emitter.isCancelled()) {
123 * return;
124 * }
125 *
126 * emitter.onNext("World");
127 *
128 * Thread.sleep(1000);
129 *
130 * // the end-of-sequence has to be signaled, otherwise the
131 * // consumers may never finish
132 * emitter.onComplete();
133 * }
134 * }, BackpressureStrategy.BUFFER);
135 *
136 * System.out.println("Subscribe!");
137 *
138 * source.subscribe(System.out::println);
139 *
140 * System.out.println("Done!");
141 * </code></pre>
142 * <p>
143 * RxJava reactive sources, such as {@code Flowable}, are generally synchronous and sequential in nature. In the ReactiveX design, the location (thread)
144 * where operators run is <i>orthogonal</i> to when the operators can work with data. This means that asynchrony and parallelism
145 * has to be explicitly expressed via operators such as {@link #subscribeOn(Scheduler)}, {@link #observeOn(Scheduler)} and {@link #parallel()}. In general,
146 * operators featuring a {@link Scheduler} parameter are introducing this type of asynchrony into the flow.
147 * <p>
148 * For more information see the <a href="http://reactivex.io/documentation/Publisher.html">ReactiveX documentation</a>.
149 *
150 * @param <T>
151 * the type of the items emitted by the {@code Flowable}
152 * @see Observable
153 * @see ParallelFlowable
154 * @see io.reactivex.rxjava3.subscribers.DisposableSubscriber
155 */
156 public abstract class Flowable<@NonNull T> implements Publisher<T> {
157 /** The default buffer size. */
158 static final int BUFFER_SIZE;
159 static {
160 BUFFER_SIZE = Math.max(1, Integer.getInteger("rx3.buffer-size", 128));
161 }
162
163 /**
164 * Mirrors the one {@link Publisher} in an {@link Iterable} of several {@code Publisher}s that first either emits an item or sends
165 * a termination notification.
166 * <p>
167 * <img width="640" height="417" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Flowable.amb.png" alt="">
168 * <p>
169 * When one of the {@code Publisher}s signal an item or terminates first, all subscriptions to the other
170 * {@code Publisher}s are canceled.
171 * <dl>
172 * <dt><b>Backpressure:</b></dt>
173 * <dd>The operator itself doesn't interfere with backpressure which is determined by the winning
174 * {@code Publisher}'s backpressure behavior.</dd>
175 * <dt><b>Scheduler:</b></dt>
176 * <dd>{@code amb} does not operate by default on a particular {@link Scheduler}.</dd>
177 * <dt><b>Error handling:</b></dt>
178 * <dd>
179 * If any of the losing {@code Publisher}s signals an error, the error is routed to the global
180 * error handler via {@link RxJavaPlugins#onError(Throwable)}.
181 * </dd>
182 * </dl>
183 *
184 * @param <T> the common element type
185 * @param sources
186 * an {@code Iterable} of {@code Publisher}s sources competing to react first. A subscription to each {@code Publisher} will
187 * occur in the same order as in this {@code Iterable}.
188 * @return the new {@code Flowable} instance
189 * @throws NullPointerException if {@code sources} is {@code null}
190 * @see <a href="http://reactivex.io/documentation/operators/amb.html">ReactiveX operators documentation: Amb</a>
191 */
192 @CheckReturnValue
193 @NonNull
194 @BackpressureSupport(BackpressureKind.PASS_THROUGH)
195 @SchedulerSupport(SchedulerSupport.NONE)
196 public static <@NonNull T> Flowable<T> amb(@NonNull Iterable<@NonNull ? extends Publisher<? extends T>> sources) {
197 Objects.requireNonNull(sources, "sources is null");
198 return RxJavaPlugins.onAssembly(new FlowableAmb<>(null, sources));
199 }
200
201 /**
202 * Mirrors the one {@link Publisher} in an array of several {@code Publisher}s that first either emits an item or sends
203 * a termination notification.
204 * <p>
205 * <img width="640" height="417" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Flowable.ambArray.png" alt="">
206 * <p>
207 * When one of the {@code Publisher}s signal an item or terminates first, all subscriptions to the other
208 * {@code Publisher}s are canceled.
209 * <dl>
210 * <dt><b>Backpressure:</b></dt>
211 * <dd>The operator itself doesn't interfere with backpressure which is determined by the winning
212 * {@code Publisher}'s backpressure behavior.</dd>
213 * <dt><b>Scheduler:</b></dt>
214 * <dd>{@code ambArray} does not operate by default on a particular {@link Scheduler}.</dd>
215 * <dt><b>Error handling:</b></dt>
216 * <dd>
217 * If any of the losing {@code Publisher}s signals an error, the error is routed to the global
218 * error handler via {@link RxJavaPlugins#onError(Throwable)}.
219 * </dd>
220 * </dl>
221 *
222 * @param <T> the common element type
223 * @param sources
224 * an array of {@code Publisher} sources competing to react first. A subscription to each {@code Publisher} will
225 * occur in the same order as in this array.
226 * @return the new {@code Flowable} instance
227 * @throws NullPointerException if {@code sources} is {@code null}
228 * @see <a href="http://reactivex.io/documentation/operators/amb.html">ReactiveX operators documentation: Amb</a>
229 */
230 @CheckReturnValue
231 @NonNull
232 @BackpressureSupport(BackpressureKind.PASS_THROUGH)
233 @SchedulerSupport(SchedulerSupport.NONE)
234 @SafeVarargs
235 public static <@NonNull T> Flowable<T> ambArray(@NonNull Publisher<? extends T>... sources) {
236 Objects.requireNonNull(sources, "sources is null");
237 int len = sources.length;
238 if (len == 0) {
239 return empty();
240 } else
241 if (len == 1) {
242 return fromPublisher(sources[0]);
243 }
244 return RxJavaPlugins.onAssembly(new FlowableAmb<>(sources, null));
245 }
246
247 /**
248 * Returns the default internal buffer size used by most async operators.
249 * <p>The value can be overridden via system parameter {@code rx3.buffer-size}
250 * <em>before</em> the {@code Flowable} class is loaded.
251 * @return the default internal buffer size.
252 */
253 @CheckReturnValue
254 public static int bufferSize() {
255 return BUFFER_SIZE;
256 }
257
258 /**
259 * Combines a collection of source {@link Publisher}s by emitting an item that aggregates the latest values of each of
260 * the source {@code Publisher}s each time an item is received from any of the source {@code Publisher}s, where this
261 * aggregation is defined by a specified function.
262 * <p>
263 * Note on method signature: since Java doesn't allow creating a generic array with {@code new T[]}, the
264 * implementation of this operator has to create an {@code Object[]} instead. Unfortunately, a
265 * {@code Function<Integer[], R>} passed to the method would trigger a {@link ClassCastException}.
266 * <p>
267 * If any of the sources never produces an item but only terminates (normally or with an error), the
268 * resulting sequence terminates immediately (normally or with all the errors accumulated until that point).
269 * If that input source is also synchronous, other sources after it will not be subscribed to.
270 * <p>
271 * If the provided array of source {@code Publisher}s is empty, the resulting sequence completes immediately without emitting
272 * any items and without any calls to the combiner function.
273 *
274 * <dl>
275 * <dt><b>Backpressure:</b></dt>
276 * <dd>The returned {@code Publisher} honors backpressure from downstream. The source {@code Publisher}s
277 * are requested in a bounded manner, however, their backpressure is not enforced (the operator won't signal
278 * {@link MissingBackpressureException}) and may lead to {@link OutOfMemoryError} due to internal buffer bloat.</dd>
279 * <dt><b>Scheduler:</b></dt>
280 * <dd>{@code combineLatestArray} does not operate by default on a particular {@link Scheduler}.</dd>
281 * </dl>
282 *
283 * @param <T>
284 * the common base type of source values
285 * @param <R>
286 * the result type
287 * @param sources
288 * the collection of source {@code Publisher}s
289 * @param combiner
290 * the aggregation function used to combine the items emitted by the source {@code Publisher}s
291 * @return the new {@code Flowable} instance
292 * @throws NullPointerException if {@code sources} or {@code combiner} is {@code null}
293 * @see <a href="http://reactivex.io/documentation/operators/combinelatest.html">ReactiveX operators documentation: CombineLatest</a>
294 */
295 @SchedulerSupport(SchedulerSupport.NONE)
296 @CheckReturnValue
297 @BackpressureSupport(BackpressureKind.FULL)
298 @NonNull
299 public static <@NonNull T, @NonNull R> Flowable<R> combineLatestArray(@NonNull Publisher<? extends T>[] sources, @NonNull Function<? super Object[], ? extends R> combiner) {
300 return combineLatestArray(sources, combiner, bufferSize());
301 }
302
303 /**
304 * Combines a collection of source {@link Publisher}s by emitting an item that aggregates the latest values of each of
305 * the source {@code Publisher}s each time an item is received from any of the source {@code Publisher}s, where this
306 * aggregation is defined by a specified function.
307 * <p>
308 * Note on method signature: since Java doesn't allow creating a generic array with {@code new T[]}, the
309 * implementation of this operator has to create an {@code Object[]} instead. Unfortunately, a
310 * {@code Function<Integer[], R>} passed to the method would trigger a {@link ClassCastException}.
311 * <p>
312 * If any of the sources never produces an item but only terminates (normally or with an error), the
313 * resulting sequence terminates immediately (normally or with all the errors accumulated until that point).
314 * If that input source is also synchronous, other sources after it will not be subscribed to.
315 * <p>
316 * If the provided array of source {@code Publisher}s is empty, the resulting sequence completes immediately without emitting
317 * any items and without any calls to the combiner function.
318 *
319 * <dl>
320 * <dt><b>Backpressure:</b></dt>
321 * <dd>The returned {@code Publisher} honors backpressure from downstream. The source {@code Publisher}s
322 * are requested in a bounded manner, however, their backpressure is not enforced (the operator won't signal
323 * {@link MissingBackpressureException}) and may lead to {@link OutOfMemoryError} due to internal buffer bloat.</dd>
324 * <dt><b>Scheduler:</b></dt>
325 * <dd>{@code combineLatestArray} does not operate by default on a particular {@link Scheduler}.</dd>
326 * </dl>
327 *
328 * @param <T>
329 * the common base type of source values
330 * @param <R>
331 * the result type
332 * @param sources
333 * the collection of source {@code Publisher}s
334 * @param combiner
335 * the aggregation function used to combine the items emitted by the source {@code Publisher}s
336 * @param bufferSize
337 * the internal buffer size and prefetch amount applied to every source {@code Flowable}
338 * @return the new {@code Flowable} instance
339 * @throws NullPointerException if {@code sources} or {@code combiner} is {@code null}
340 * @throws IllegalArgumentException if {@code bufferSize} is non-positive
341 * @see <a href="http://reactivex.io/documentation/operators/combinelatest.html">ReactiveX operators documentation: CombineLatest</a>
342 */
343 @SchedulerSupport(SchedulerSupport.NONE)
344 @CheckReturnValue
345 @NonNull
346 @BackpressureSupport(BackpressureKind.FULL)
347 public static <@NonNull T, @NonNull R> Flowable<R> combineLatestArray(@NonNull Publisher<? extends T>[] sources, @NonNull Function<? super Object[], ? extends R> combiner, int bufferSize) {
348 Objects.requireNonNull(sources, "sources is null");
349 if (sources.length == 0) {
350 return empty();
351 }
352 Objects.requireNonNull(combiner, "combiner is null");
353 ObjectHelper.verifyPositive(bufferSize, "bufferSize");
354 return RxJavaPlugins.onAssembly(new FlowableCombineLatest<>(sources, combiner, bufferSize, false));
355 }
356
357 /**
358 * Combines a collection of source {@link Publisher}s by emitting an item that aggregates the latest values of each of
359 * the source {@code Publisher}s each time an item is received from any of the source {@code Publisher}s, where this
360 * aggregation is defined by a specified function.
361 * <p>
362 * Note on method signature: since Java doesn't allow creating a generic array with {@code new T[]}, the
363 * implementation of this operator has to create an {@code Object[]} instead. Unfortunately, a
364 * {@code Function<Integer[], R>} passed to the method would trigger a {@link ClassCastException}.
365 * <p>
366 * If any of the sources never produces an item but only terminates (normally or with an error), the
367 * resulting sequence terminates immediately (normally or with all the errors accumulated until that point).
368 * If that input source is also synchronous, other sources after it will not be subscribed to.
369 * <p>
370 * If the provided iterable of source {@code Publisher}s is empty, the resulting sequence completes immediately without emitting
371 * any items and without any calls to the combiner function.
372 *
373 * <dl>
374 * <dt><b>Backpressure:</b></dt>
375 * <dd>The returned {@code Publisher} honors backpressure from downstream. The source {@code Publisher}s
376 * are requested in a bounded manner, however, their backpressure is not enforced (the operator won't signal
377 * {@link MissingBackpressureException}) and may lead to {@link OutOfMemoryError} due to internal buffer bloat.</dd>
378 * <dt><b>Scheduler:</b></dt>
379 * <dd>{@code combineLatest} does not operate by default on a particular {@link Scheduler}.</dd>
380 * </dl>
381 *
382 * @param <T>
383 * the common base type of source values
384 * @param <R>
385 * the result type
386 * @param sources
387 * the collection of source {@code Publisher}s
388 * @param combiner
389 * the aggregation function used to combine the items emitted by the source {@code Publisher}s
390 * @return the new {@code Flowable} instance
391 * @throws NullPointerException if {@code sources} or {@code combiner} is {@code null}
392 * @see <a href="http://reactivex.io/documentation/operators/combinelatest.html">ReactiveX operators documentation: CombineLatest</a>
393 */
394 @SchedulerSupport(SchedulerSupport.NONE)
395 @CheckReturnValue
396 @BackpressureSupport(BackpressureKind.FULL)
397 @NonNull
398 public static <@NonNull T, @NonNull R> Flowable<R> combineLatest(@NonNull Iterable<@NonNull ? extends Publisher<? extends T>> sources,
399 @NonNull Function<? super Object[], ? extends R> combiner) {
400 return combineLatest(sources, combiner, bufferSize());
401 }
402
403 /**
404 * Combines a collection of source {@link Publisher}s by emitting an item that aggregates the latest values of each of
405 * the source {@code Publisher}s each time an item is received from any of the source {@code Publisher}s, where this
406 * aggregation is defined by a specified function.
407 * <p>
408 * Note on method signature: since Java doesn't allow creating a generic array with {@code new T[]}, the
409 * implementation of this operator has to create an {@code Object[]} instead. Unfortunately, a
410 * {@code Function<Integer[], R>} passed to the method would trigger a {@link ClassCastException}.
411 * <p>
412 * If any of the sources never produces an item but only terminates (normally or with an error), the
413 * resulting sequence terminates immediately (normally or with all the errors accumulated until that point).
414 * If that input source is also synchronous, other sources after it will not be subscribed to.
415 * <p>
416 * If the provided iterable of source {@code Publisher}s is empty, the resulting sequence completes immediately without emitting any items and
417 * without any calls to the combiner function.
418 *
419 * <dl>
420 * <dt><b>Backpressure:</b></dt>
421 * <dd>The returned {@code Publisher} honors backpressure from downstream. The source {@code Publisher}s
422 * are requested in a bounded manner, however, their backpressure is not enforced (the operator won't signal
423 * {@link MissingBackpressureException}) and may lead to {@link OutOfMemoryError} due to internal buffer bloat.</dd>
424 * <dt><b>Scheduler:</b></dt>
425 * <dd>{@code combineLatest} does not operate by default on a particular {@link Scheduler}.</dd>
426 * </dl>
427 *
428 * @param <T>
429 * the common base type of source values
430 * @param <R>
431 * the result type
432 * @param sources
433 * the collection of source {@code Publisher}s
434 * @param combiner
435 * the aggregation function used to combine the items emitted by the source {@code Publisher}s
436 * @param bufferSize
437 * the internal buffer size and prefetch amount applied to every source {@code Flowable}
438 * @return the new {@code Flowable} instance
439 * @throws NullPointerException if {@code sources} or {@code combiner} is {@code null}
440 * @throws IllegalArgumentException if {@code bufferSize} is non-positive
441 * @see <a href="http://reactivex.io/documentation/operators/combinelatest.html">ReactiveX operators documentation: CombineLatest</a>
442 */
443 @SchedulerSupport(SchedulerSupport.NONE)
444 @CheckReturnValue
445 @NonNull
446 @BackpressureSupport(BackpressureKind.FULL)
447 public static <@NonNull T, @NonNull R> Flowable<R> combineLatest(@NonNull Iterable<@NonNull ? extends Publisher<? extends T>> sources,
448 @NonNull Function<? super Object[], ? extends R> combiner, int bufferSize) {
449 Objects.requireNonNull(sources, "sources is null");
450 Objects.requireNonNull(combiner, "combiner is null");
451 ObjectHelper.verifyPositive(bufferSize, "bufferSize");
452 return RxJavaPlugins.onAssembly(new FlowableCombineLatest<>(sources, combiner, bufferSize, false));
453 }
454
455 /**
456 * Combines a collection of source {@link Publisher}s by emitting an item that aggregates the latest values of each of
457 * the source {@code Publisher}s each time an item is received from any of the source {@code Publisher}s, where this
458 * aggregation is defined by a specified function.
459 * <p>
460 * Note on method signature: since Java doesn't allow creating a generic array with {@code new T[]}, the
461 * implementation of this operator has to create an {@code Object[]} instead. Unfortunately, a
462 * {@code Function<Integer[], R>} passed to the method would trigger a {@link ClassCastException}.
463 * <p>
464 * If any of the sources never produces an item but only terminates (normally or with an error), the
465 * resulting sequence terminates immediately (normally or with all the errors accumulated until that point).
466 * If that input source is also synchronous, other sources after it will not be subscribed to.
467 * <p>
468 * If the provided array of source {@code Publisher}s is empty, the resulting sequence completes immediately without emitting
469 * any items and without any calls to the combiner function.
470 *
471 * <dl>
472 * <dt><b>Backpressure:</b></dt>
473 * <dd>The returned {@code Publisher} honors backpressure from downstream. The source {@code Publisher}s
474 * are requested in a bounded manner, however, their backpressure is not enforced (the operator won't signal
475 * {@link MissingBackpressureException}) and may lead to {@link OutOfMemoryError} due to internal buffer bloat.</dd>
476 * <dt><b>Scheduler:</b></dt>
477 * <dd>{@code combineLatestArrayDelayError} does not operate by default on a particular {@link Scheduler}.</dd>
478 * </dl>
479 *
480 * @param <T>
481 * the common base type of source values
482 * @param <R>
483 * the result type
484 * @param sources
485 * the collection of source {@code Publisher}s
486 * @param combiner
487 * the aggregation function used to combine the items emitted by the source {@code Publisher}s
488 * @return the new {@code Flowable} instance
489 * @throws NullPointerException if {@code sources} or {@code combiner} is {@code null}
490 * @see <a href="http://reactivex.io/documentation/operators/combinelatest.html">ReactiveX operators documentation: CombineLatest</a>
491 */
492 @SchedulerSupport(SchedulerSupport.NONE)
493 @CheckReturnValue
494 @BackpressureSupport(BackpressureKind.FULL)
495 @NonNull
496 public static <@NonNull T, @NonNull R> Flowable<R> combineLatestArrayDelayError(@NonNull Publisher<? extends T>[] sources,
497 @NonNull Function<? super Object[], ? extends R> combiner) {
498 return combineLatestArrayDelayError(sources, combiner, bufferSize());
499 }
500
501 /**
502 * Combines a collection of source {@link Publisher}s by emitting an item that aggregates the latest values of each of
503 * the source {@code Publisher}s each time an item is received from any of the source {@code Publisher}s, where this
504 * aggregation is defined by a specified function and delays any error from the sources until
505 * all source {@code Publisher}s terminate.
506 * <p>
507 * Note on method signature: since Java doesn't allow creating a generic array with {@code new T[]}, the
508 * implementation of this operator has to create an {@code Object[]} instead. Unfortunately, a
509 * {@code Function<Integer[], R>} passed to the method would trigger a {@link ClassCastException}.
510 * <p>
511 * If any of the sources never produces an item but only terminates (normally or with an error), the
512 * resulting sequence terminates immediately (normally or with all the errors accumulated until that point).
513 * If that input source is also synchronous, other sources after it will not be subscribed to.
514 * <p>
515 * If the provided array of source {@code Publisher}s is empty, the resulting sequence completes immediately without emitting
516 * any items and without any calls to the combiner function.
517 *
518 * <dl>
519 * <dt><b>Backpressure:</b></dt>
520 * <dd>The returned {@code Publisher} honors backpressure from downstream. The source {@code Publisher}s
521 * are requested in a bounded manner, however, their backpressure is not enforced (the operator won't signal
522 * {@link MissingBackpressureException}) and may lead to {@link OutOfMemoryError} due to internal buffer bloat.</dd>
523 * <dt><b>Scheduler:</b></dt>
524 * <dd>{@code combineLatestArrayDelayError} does not operate by default on a particular {@link Scheduler}.</dd>
525 * </dl>
526 *
527 * @param <T>
528 * the common base type of source values
529 * @param <R>
530 * the result type
531 * @param sources
532 * the collection of source {@code Publisher}s
533 * @param combiner
534 * the aggregation function used to combine the items emitted by the source {@code Publisher}s
535 * @param bufferSize
536 * the internal buffer size and prefetch amount applied to every source {@code Flowable}
537 * @return the new {@code Flowable} instance
538 * @throws NullPointerException if {@code sources} or {@code combiner} is {@code null}
539 * @throws IllegalArgumentException if {@code bufferSize} is non-positive
540 * @see <a href="http://reactivex.io/documentation/operators/combinelatest.html">ReactiveX operators documentation: CombineLatest</a>
541 */
542 @SchedulerSupport(SchedulerSupport.NONE)
543 @CheckReturnValue
544 @NonNull
545 @BackpressureSupport(BackpressureKind.FULL)
546 public static <@NonNull T, @NonNull R> Flowable<R> combineLatestArrayDelayError(@NonNull Publisher<? extends T>[] sources,
547 @NonNull Function<? super Object[], ? extends R> combiner, int bufferSize) {
548 Objects.requireNonNull(sources, "sources is null");
549 Objects.requireNonNull(combiner, "combiner is null");
550 ObjectHelper.verifyPositive(bufferSize, "bufferSize");
551 if (sources.length == 0) {
552 return empty();
553 }
554 return RxJavaPlugins.onAssembly(new FlowableCombineLatest<>(sources, combiner, bufferSize, true));
555 }
556
557 /**
558 * Combines a collection of source {@link Publisher}s by emitting an item that aggregates the latest values of each of
559 * the source {@code Publisher}s each time an item is received from any of the source {@code Publisher}s, where this
560 * aggregation is defined by a specified function and delays any error from the sources until
561 * all source {@code Publisher}s terminate.
562 * <p>
563 * Note on method signature: since Java doesn't allow creating a generic array with {@code new T[]}, the
564 * implementation of this operator has to create an {@code Object[]} instead. Unfortunately, a
565 * {@code Function<Integer[], R>} passed to the method would trigger a {@link ClassCastException}.
566 * <p>
567 * If any of the sources never produces an item but only terminates (normally or with an error), the
568 * resulting sequence terminates immediately (normally or with all the errors accumulated until that point).
569 * If that input source is also synchronous, other sources after it will not be subscribed to.
570 * <p>
571 * If the provided iterable of source {@code Publisher}s is empty, the resulting sequence completes immediately without emitting
572 * any items and without any calls to the combiner function.
573 *
574 * <dl>
575 * <dt><b>Backpressure:</b></dt>
576 * <dd>The returned {@code Publisher} honors backpressure from downstream. The source {@code Publisher}s
577 * are requested in a bounded manner, however, their backpressure is not enforced (the operator won't signal
578 * {@link MissingBackpressureException}) and may lead to {@link OutOfMemoryError} due to internal buffer bloat.</dd>
579 * <dt><b>Scheduler:</b></dt>
580 * <dd>{@code combineLatestDelayError} does not operate by default on a particular {@link Scheduler}.</dd>
581 * </dl>
582 *
583 * @param <T>
584 * the common base type of source values
585 * @param <R>
586 * the result type
587 * @param sources
588 * the collection of source {@code Publisher}s
589 * @param combiner
590 * the aggregation function used to combine the items emitted by the source {@code Publisher}s
591 * @return the new {@code Flowable} instance
592 * @throws NullPointerException if {@code sources} or {@code combiner} is {@code null}
593 * @see <a href="http://reactivex.io/documentation/operators/combinelatest.html">ReactiveX operators documentation: CombineLatest</a>
594 */
595 @SchedulerSupport(SchedulerSupport.NONE)
596 @CheckReturnValue
597 @BackpressureSupport(BackpressureKind.FULL)
598 @NonNull
599 public static <@NonNull T, @NonNull R> Flowable<R> combineLatestDelayError(@NonNull Iterable<@NonNull ? extends Publisher<? extends T>> sources,
600 @NonNull Function<? super Object[], ? extends R> combiner) {
601 return combineLatestDelayError(sources, combiner, bufferSize());
602 }
603
604 /**
605 * Combines a collection of source {@link Publisher}s by emitting an item that aggregates the latest values of each of
606 * the source {@code Publisher}s each time an item is received from any of the source {@code Publisher}s, where this
607 * aggregation is defined by a specified function and delays any error from the sources until
608 * all source {@code Publisher}s terminate.
609 * <p>
610 * Note on method signature: since Java doesn't allow creating a generic array with {@code new T[]}, the
611 * implementation of this operator has to create an {@code Object[]} instead. Unfortunately, a
612 * {@code Function<Integer[], R>} passed to the method would trigger a {@link ClassCastException}.
613 * <p>
614 * If any of the sources never produces an item but only terminates (normally or with an error), the
615 * resulting sequence terminates immediately (normally or with all the errors accumulated until that point).
616 * If that input source is also synchronous, other sources after it will not be subscribed to.
617 * <p>
618 * If the provided iterable of source {@code Publisher}s is empty, the resulting sequence completes immediately without emitting
619 * any items and without any calls to the combiner function.
620 *
621 * <dl>
622 * <dt><b>Backpressure:</b></dt>
623 * <dd>The returned {@code Publisher} honors backpressure from downstream. The source {@code Publisher}s
624 * are requested in a bounded manner, however, their backpressure is not enforced (the operator won't signal
625 * {@link MissingBackpressureException}) and may lead to {@link OutOfMemoryError} due to internal buffer bloat.</dd>
626 * <dt><b>Scheduler:</b></dt>
627 * <dd>{@code combineLatestDelayError} does not operate by default on a particular {@link Scheduler}.</dd>
628 * </dl>
629 *
630 * @param <T>
631 * the common base type of source values
632 * @param <R>
633 * the result type
634 * @param sources
635 * the collection of source {@code Publisher}s
636 * @param combiner
637 * the aggregation function used to combine the items emitted by the source {@code Publisher}s
638 * @param bufferSize
639 * the internal buffer size and prefetch amount applied to every source {@code Flowable}
640 * @return the new {@code Flowable} instance
641 * @throws NullPointerException if {@code sources} or {@code combiner} is {@code null}
642 * @throws IllegalArgumentException if {@code bufferSize} is non-positive
643 * @see <a href="http://reactivex.io/documentation/operators/combinelatest.html">ReactiveX operators documentation: CombineLatest</a>
644 */
645 @SchedulerSupport(SchedulerSupport.NONE)
646 @CheckReturnValue
647 @BackpressureSupport(BackpressureKind.FULL)
648 @NonNull
649 public static <@NonNull T, @NonNull R> Flowable<R> combineLatestDelayError(@NonNull Iterable<@NonNull ? extends Publisher<? extends T>> sources,
650 @NonNull Function<? super Object[], ? extends R> combiner, int bufferSize) {
651 Objects.requireNonNull(sources, "sources is null");
652 Objects.requireNonNull(combiner, "combiner is null");
653 ObjectHelper.verifyPositive(bufferSize, "bufferSize");
654 return RxJavaPlugins.onAssembly(new FlowableCombineLatest<>(sources, combiner, bufferSize, true));
655 }
656
657 /**
658 * Combines two source {@link Publisher}s by emitting an item that aggregates the latest values of each of the
659 * source {@code Publisher}s each time an item is received from either of the source {@code Publisher}s, where this
660 * aggregation is defined by a specified function.
661 * <p>
662 * If any of the sources never produces an item but only terminates (normally or with an error), the
663 * resulting sequence terminates immediately (normally or with all the errors accumulated until that point).
664 * If that input source is also synchronous, other sources after it will not be subscribed to.
665 * <p>
666 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/combineLatest.v3.png" alt="">
667 * <dl>
668 * <dt><b>Backpressure:</b></dt>
669 * <dd>The returned {@code Publisher} honors backpressure from downstream. The source {@code Publisher}s
670 * are requested in a bounded manner, however, their backpressure is not enforced (the operator won't signal
671 * {@link MissingBackpressureException}) and may lead to {@link OutOfMemoryError} due to internal buffer bloat.</dd>
672 * <dt><b>Scheduler:</b></dt>
673 * <dd>{@code combineLatest} does not operate by default on a particular {@link Scheduler}.</dd>
674 * </dl>
675 *
676 * @param <T1> the element type of the first source
677 * @param <T2> the element type of the second source
678 * @param <R> the combined output type
679 * @param source1
680 * the first source {@code Publisher}
681 * @param source2
682 * the second source {@code Publisher}
683 * @param combiner
684 * the aggregation function used to combine the items emitted by the source {@code Publisher}s
685 * @return the new {@code Flowable} instance
686 * @throws NullPointerException if {@code source1}, {@code source2} or {@code combiner} is {@code null}
687 * @see <a href="http://reactivex.io/documentation/operators/combinelatest.html">ReactiveX operators documentation: CombineLatest</a>
688 */
689 @SuppressWarnings("unchecked")
690 @CheckReturnValue
691 @BackpressureSupport(BackpressureKind.FULL)
692 @SchedulerSupport(SchedulerSupport.NONE)
693 @NonNull
694 public static <@NonNull T1, @NonNull T2, @NonNull R> Flowable<R> combineLatest(
695 @NonNull Publisher<? extends T1> source1, @NonNull Publisher<? extends T2> source2,
696 @NonNull BiFunction<? super T1, ? super T2, ? extends R> combiner) {
697 Objects.requireNonNull(source1, "source1 is null");
698 Objects.requireNonNull(source2, "source2 is null");
699 Objects.requireNonNull(combiner, "combiner is null");
700 return combineLatestArray(new Publisher[] { source1, source2 }, Functions.toFunction(combiner), bufferSize());
701 }
702
703 /**
704 * Combines three source {@link Publisher}s by emitting an item that aggregates the latest values of each of the
705 * source {@code Publisher}s each time an item is received from any of the source {@code Publisher}s, where this
706 * aggregation is defined by a specified function.
707 * <p>
708 * If any of the sources never produces an item but only terminates (normally or with an error), the
709 * resulting sequence terminates immediately (normally or with all the errors accumulated until that point).
710 * If that input source is also synchronous, other sources after it will not be subscribed to.
711 * <p>
712 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/combineLatest.v3.png" alt="">
713 * <dl>
714 * <dt><b>Backpressure:</b></dt>
715 * <dd>The returned {@code Publisher} honors backpressure from downstream. The source {@code Publisher}s
716 * are requested in a bounded manner, however, their backpressure is not enforced (the operator won't signal
717 * {@link MissingBackpressureException}) and may lead to {@link OutOfMemoryError} due to internal buffer bloat.</dd>
718 * <dt><b>Scheduler:</b></dt>
719 * <dd>{@code combineLatest} does not operate by default on a particular {@link Scheduler}.</dd>
720 * </dl>
721 *
722 * @param <T1> the element type of the first source
723 * @param <T2> the element type of the second source
724 * @param <T3> the element type of the third source
725 * @param <R> the combined output type
726 * @param source1
727 * the first source {@code Publisher}
728 * @param source2
729 * the second source {@code Publisher}
730 * @param source3
731 * the third source {@code Publisher}
732 * @param combiner
733 * the aggregation function used to combine the items emitted by the source {@code Publisher}s
734 * @return the new {@code Flowable} instance
735 * @throws NullPointerException if {@code source1}, {@code source2}, {@code source3} or {@code combiner} is {@code null}
736 * @see <a href="http://reactivex.io/documentation/operators/combinelatest.html">ReactiveX operators documentation: CombineLatest</a>
737 */
738 @SuppressWarnings("unchecked")
739 @CheckReturnValue
740 @NonNull
741 @BackpressureSupport(BackpressureKind.FULL)
742 @SchedulerSupport(SchedulerSupport.NONE)
743 public static <@NonNull T1, @NonNull T2, @NonNull T3, @NonNull R> Flowable<R> combineLatest(
744 @NonNull Publisher<? extends T1> source1, @NonNull Publisher<? extends T2> source2,
745 @NonNull Publisher<? extends T3> source3,
746 @NonNull Function3<? super T1, ? super T2, ? super T3, ? extends R> combiner) {
747 Objects.requireNonNull(source1, "source1 is null");
748 Objects.requireNonNull(source2, "source2 is null");
749 Objects.requireNonNull(source3, "source3 is null");
750 Objects.requireNonNull(combiner, "combiner is null");
751 return combineLatestArray(new Publisher[] { source1, source2, source3 }, Functions.toFunction(combiner), bufferSize());
752 }
753
754 /**
755 * Combines four source {@link Publisher}s by emitting an item that aggregates the latest values of each of the
756 * source {@code Publisher}s each time an item is received from any of the source {@code Publisher}s, where this
757 * aggregation is defined by a specified function.
758 * <p>
759 * If any of the sources never produces an item but only terminates (normally or with an error), the
760 * resulting sequence terminates immediately (normally or with all the errors accumulated until that point).
761 * If that input source is also synchronous, other sources after it will not be subscribed to.
762 * <p>
763 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/combineLatest.v3.png" alt="">
764 * <dl>
765 * <dt><b>Backpressure:</b></dt>
766 * <dd>The returned {@code Publisher} honors backpressure from downstream. The source {@code Publisher}s
767 * are requested in a bounded manner, however, their backpressure is not enforced (the operator won't signal
768 * {@link MissingBackpressureException}) and may lead to {@link OutOfMemoryError} due to internal buffer bloat.</dd>
769 * <dt><b>Scheduler:</b></dt>
770 * <dd>{@code combineLatest} does not operate by default on a particular {@link Scheduler}.</dd>
771 * </dl>
772 *
773 * @param <T1> the element type of the first source
774 * @param <T2> the element type of the second source
775 * @param <T3> the element type of the third source
776 * @param <T4> the element type of the fourth source
777 * @param <R> the combined output type
778 * @param source1
779 * the first source {@code Publisher}
780 * @param source2
781 * the second source {@code Publisher}
782 * @param source3
783 * the third source {@code Publisher}
784 * @param source4
785 * the fourth source {@code Publisher}
786 * @param combiner
787 * the aggregation function used to combine the items emitted by the source {@code Publisher}s
788 * @return the new {@code Flowable} instance
789 * @throws NullPointerException if {@code source1}, {@code source2}, {@code source3},
790 * {@code source4} or {@code combiner} is {@code null}
791 * @see <a href="http://reactivex.io/documentation/operators/combinelatest.html">ReactiveX operators documentation: CombineLatest</a>
792 */
793 @SuppressWarnings("unchecked")
794 @CheckReturnValue
795 @NonNull
796 @BackpressureSupport(BackpressureKind.FULL)
797 @SchedulerSupport(SchedulerSupport.NONE)
798 public static <@NonNull T1, @NonNull T2, @NonNull T3, @NonNull T4, @NonNull R> Flowable<R> combineLatest(
799 @NonNull Publisher<? extends T1> source1, @NonNull Publisher<? extends T2> source2,
800 @NonNull Publisher<? extends T3> source3, @NonNull Publisher<? extends T4> source4,
801 @NonNull Function4<? super T1, ? super T2, ? super T3, ? super T4, ? extends R> combiner) {
802 Objects.requireNonNull(source1, "source1 is null");
803 Objects.requireNonNull(source2, "source2 is null");
804 Objects.requireNonNull(source3, "source3 is null");
805 Objects.requireNonNull(source4, "source4 is null");
806 Objects.requireNonNull(combiner, "combiner is null");
807 return combineLatestArray(new Publisher[] { source1, source2, source3, source4 }, Functions.toFunction(combiner), bufferSize());
808 }
809
810 /**
811 * Combines five source {@link Publisher}s by emitting an item that aggregates the latest values of each of the
812 * source {@code Publisher}s each time an item is received from any of the source {@code Publisher}s, where this
813 * aggregation is defined by a specified function.
814 * <p>
815 * If any of the sources never produces an item but only terminates (normally or with an error), the
816 * resulting sequence terminates immediately (normally or with all the errors accumulated until that point).
817 * If that input source is also synchronous, other sources after it will not be subscribed to.
818 * <p>
819 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/combineLatest.v3.png" alt="">
820 * <dl>
821 * <dt><b>Backpressure:</b></dt>
822 * <dd>The returned {@code Publisher} honors backpressure from downstream. The source {@code Publisher}s
823 * are requested in a bounded manner, however, their backpressure is not enforced (the operator won't signal
824 * {@link MissingBackpressureException}) and may lead to {@link OutOfMemoryError} due to internal buffer bloat.</dd>
825 * <dt><b>Scheduler:</b></dt>
826 * <dd>{@code combineLatest} does not operate by default on a particular {@link Scheduler}.</dd>
827 * </dl>
828 *
829 * @param <T1> the element type of the first source
830 * @param <T2> the element type of the second source
831 * @param <T3> the element type of the third source
832 * @param <T4> the element type of the fourth source
833 * @param <T5> the element type of the fifth source
834 * @param <R> the combined output type
835 * @param source1
836 * the first source {@code Publisher}
837 * @param source2
838 * the second source {@code Publisher}
839 * @param source3
840 * the third source {@code Publisher}
841 * @param source4
842 * the fourth source {@code Publisher}
843 * @param source5
844 * the fifth source {@code Publisher}
845 * @param combiner
846 * the aggregation function used to combine the items emitted by the source {@code Publisher}s
847 * @return the new {@code Flowable} instance
848 * @throws NullPointerException if {@code source1}, {@code source2}, {@code source3},
849 * {@code source4}, {@code source5} or {@code combiner} is {@code null}
850 * @see <a href="http://reactivex.io/documentation/operators/combinelatest.html">ReactiveX operators documentation: CombineLatest</a>
851 */
852 @SuppressWarnings("unchecked")
853 @CheckReturnValue
854 @NonNull
855 @BackpressureSupport(BackpressureKind.FULL)
856 @SchedulerSupport(SchedulerSupport.NONE)
857 public static <@NonNull T1, @NonNull T2, @NonNull T3, @NonNull T4, @NonNull T5, @NonNull R> Flowable<R> combineLatest(
858 @NonNull Publisher<? extends T1> source1, @NonNull Publisher<? extends T2> source2,
859 @NonNull Publisher<? extends T3> source3, @NonNull Publisher<? extends T4> source4,
860 @NonNull Publisher<? extends T5> source5,
861 @NonNull Function5<? super T1, ? super T2, ? super T3, ? super T4, ? super T5, ? extends R> combiner) {
862 Objects.requireNonNull(source1, "source1 is null");
863 Objects.requireNonNull(source2, "source2 is null");
864 Objects.requireNonNull(source3, "source3 is null");
865 Objects.requireNonNull(source4, "source4 is null");
866 Objects.requireNonNull(source5, "source5 is null");
867 Objects.requireNonNull(combiner, "combiner is null");
868 return combineLatestArray(new Publisher[] { source1, source2, source3, source4, source5 }, Functions.toFunction(combiner), bufferSize());
869 }
870
871 /**
872 * Combines six source {@link Publisher}s by emitting an item that aggregates the latest values of each of the
873 * source {@code Publisher}s each time an item is received from any of the source {@code Publisher}s, where this
874 * aggregation is defined by a specified function.
875 * <p>
876 * If any of the sources never produces an item but only terminates (normally or with an error), the
877 * resulting sequence terminates immediately (normally or with all the errors accumulated until that point).
878 * If that input source is also synchronous, other sources after it will not be subscribed to.
879 * <p>
880 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/combineLatest.v3.png" alt="">
881 * <dl>
882 * <dt><b>Backpressure:</b></dt>
883 * <dd>The returned {@code Publisher} honors backpressure from downstream. The source {@code Publisher}s
884 * are requested in a bounded manner, however, their backpressure is not enforced (the operator won't signal
885 * {@link MissingBackpressureException}) and may lead to {@link OutOfMemoryError} due to internal buffer bloat.</dd>
886 * <dt><b>Scheduler:</b></dt>
887 * <dd>{@code combineLatest} does not operate by default on a particular {@link Scheduler}.</dd>
888 * </dl>
889 *
890 * @param <T1> the element type of the first source
891 * @param <T2> the element type of the second source
892 * @param <T3> the element type of the third source
893 * @param <T4> the element type of the fourth source
894 * @param <T5> the element type of the fifth source
895 * @param <T6> the element type of the sixth source
896 * @param <R> the combined output type
897 * @param source1
898 * the first source {@code Publisher}
899 * @param source2
900 * the second source {@code Publisher}
901 * @param source3
902 * the third source {@code Publisher}
903 * @param source4
904 * the fourth source {@code Publisher}
905 * @param source5
906 * the fifth source {@code Publisher}
907 * @param source6
908 * the sixth source {@code Publisher}
909 * @param combiner
910 * the aggregation function used to combine the items emitted by the source {@code Publisher}s
911 * @return the new {@code Flowable} instance
912 * @throws NullPointerException if {@code source1}, {@code source2}, {@code source3},
913 * {@code source4}, {@code source5}, {@code source6} or {@code combiner} is {@code null}
914 * @see <a href="http://reactivex.io/documentation/operators/combinelatest.html">ReactiveX operators documentation: CombineLatest</a>
915 */
916 @SuppressWarnings("unchecked")
917 @CheckReturnValue
918 @NonNull
919 @BackpressureSupport(BackpressureKind.FULL)
920 @SchedulerSupport(SchedulerSupport.NONE)
921 public static <@NonNull T1, @NonNull T2, @NonNull T3, @NonNull T4, @NonNull T5, @NonNull T6, @NonNull R> Flowable<R> combineLatest(
922 @NonNull Publisher<? extends T1> source1, @NonNull Publisher<? extends T2> source2,
923 @NonNull Publisher<? extends T3> source3, @NonNull Publisher<? extends T4> source4,
924 @NonNull Publisher<? extends T5> source5, @NonNull Publisher<? extends T6> source6,
925 @NonNull Function6<? super T1, ? super T2, ? super T3, ? super T4, ? super T5, ? super T6, ? extends R> combiner) {
926 Objects.requireNonNull(source1, "source1 is null");
927 Objects.requireNonNull(source2, "source2 is null");
928 Objects.requireNonNull(source3, "source3 is null");
929 Objects.requireNonNull(source4, "source4 is null");
930 Objects.requireNonNull(source5, "source5 is null");
931 Objects.requireNonNull(source6, "source6 is null");
932 Objects.requireNonNull(combiner, "combiner is null");
933 return combineLatestArray(new Publisher[] { source1, source2, source3, source4, source5, source6 }, Functions.toFunction(combiner), bufferSize());
934 }
935
936 /**
937 * Combines seven source {@link Publisher}s by emitting an item that aggregates the latest values of each of the
938 * source {@code Publisher}s each time an item is received from any of the source {@code Publisher}s, where this
939 * aggregation is defined by a specified function.
940 * <p>
941 * If any of the sources never produces an item but only terminates (normally or with an error), the
942 * resulting sequence terminates immediately (normally or with all the errors accumulated until that point).
943 * If that input source is also synchronous, other sources after it will not be subscribed to.
944 * <p>
945 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/combineLatest.v3.png" alt="">
946 * <dl>
947 * <dt><b>Backpressure:</b></dt>
948 * <dd>The returned {@code Publisher} honors backpressure from downstream. The source {@code Publisher}s
949 * are requested in a bounded manner, however, their backpressure is not enforced (the operator won't signal
950 * {@link MissingBackpressureException}) and may lead to {@link OutOfMemoryError} due to internal buffer bloat.</dd>
951 * <dt><b>Scheduler:</b></dt>
952 * <dd>{@code combineLatest} does not operate by default on a particular {@link Scheduler}.</dd>
953 * </dl>
954 *
955 * @param <T1> the element type of the first source
956 * @param <T2> the element type of the second source
957 * @param <T3> the element type of the third source
958 * @param <T4> the element type of the fourth source
959 * @param <T5> the element type of the fifth source
960 * @param <T6> the element type of the sixth source
961 * @param <T7> the element type of the seventh source
962 * @param <R> the combined output type
963 * @param source1
964 * the first source {@code Publisher}
965 * @param source2
966 * the second source {@code Publisher}
967 * @param source3
968 * the third source {@code Publisher}
969 * @param source4
970 * the fourth source {@code Publisher}
971 * @param source5
972 * the fifth source {@code Publisher}
973 * @param source6
974 * the sixth source {@code Publisher}
975 * @param source7
976 * the seventh source {@code Publisher}
977 * @param combiner
978 * the aggregation function used to combine the items emitted by the source {@code Publisher}s
979 * @return the new {@code Flowable} instance
980 * @throws NullPointerException if {@code source1}, {@code source2}, {@code source3},
981 * {@code source4}, {@code source5}, {@code source6},
982 * {@code source7} or {@code combiner} is {@code null}
983 * @see <a href="http://reactivex.io/documentation/operators/combinelatest.html">ReactiveX operators documentation: CombineLatest</a>
984 */
985 @SuppressWarnings("unchecked")
986 @CheckReturnValue
987 @NonNull
988 @BackpressureSupport(BackpressureKind.FULL)
989 @SchedulerSupport(SchedulerSupport.NONE)
990 public static <@NonNull T1, @NonNull T2, @NonNull T3, @NonNull T4, @NonNull T5, @NonNull T6, @NonNull T7, @NonNull R> Flowable<R> combineLatest(
991 @NonNull Publisher<? extends T1> source1, @NonNull Publisher<? extends T2> source2,
992 @NonNull Publisher<? extends T3> source3, @NonNull Publisher<? extends T4> source4,
993 @NonNull Publisher<? extends T5> source5, @NonNull Publisher<? extends T6> source6,
994 @NonNull Publisher<? extends T7> source7,
995 @NonNull Function7<? super T1, ? super T2, ? super T3, ? super T4, ? super T5, ? super T6, ? super T7, ? extends R> combiner) {
996 Objects.requireNonNull(source1, "source1 is null");
997 Objects.requireNonNull(source2, "source2 is null");
998 Objects.requireNonNull(source3, "source3 is null");
999 Objects.requireNonNull(source4, "source4 is null");
1000 Objects.requireNonNull(source5, "source5 is null");
1001 Objects.requireNonNull(source6, "source6 is null");
1002 Objects.requireNonNull(source7, "source7 is null");
1003 Objects.requireNonNull(combiner, "combiner is null");
1004 return combineLatestArray(new Publisher[] { source1, source2, source3, source4, source5, source6, source7 }, Functions.toFunction(combiner), bufferSize());
1005 }
1006
1007 /**
1008 * Combines eight source {@link Publisher}s by emitting an item that aggregates the latest values of each of the
1009 * source {@code Publisher}s each time an item is received from any of the source {@code Publisher}s, where this
1010 * aggregation is defined by a specified function.
1011 * <p>
1012 * If any of the sources never produces an item but only terminates (normally or with an error), the
1013 * resulting sequence terminates immediately (normally or with all the errors accumulated until that point).
1014 * If that input source is also synchronous, other sources after it will not be subscribed to.
1015 * <p>
1016 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/combineLatest.v3.png" alt="">
1017 * <dl>
1018 * <dt><b>Backpressure:</b></dt>
1019 * <dd>The returned {@code Publisher} honors backpressure from downstream. The source {@code Publisher}s
1020 * are requested in a bounded manner, however, their backpressure is not enforced (the operator won't signal
1021 * {@link MissingBackpressureException}) and may lead to {@link OutOfMemoryError} due to internal buffer bloat.</dd>
1022 * <dt><b>Scheduler:</b></dt>
1023 * <dd>{@code combineLatest} does not operate by default on a particular {@link Scheduler}.</dd>
1024 * </dl>
1025 *
1026 * @param <T1> the element type of the first source
1027 * @param <T2> the element type of the second source
1028 * @param <T3> the element type of the third source
1029 * @param <T4> the element type of the fourth source
1030 * @param <T5> the element type of the fifth source
1031 * @param <T6> the element type of the sixth source
1032 * @param <T7> the element type of the seventh source
1033 * @param <T8> the element type of the eighth source
1034 * @param <R> the combined output type
1035 * @param source1
1036 * the first source {@code Publisher}
1037 * @param source2
1038 * the second source {@code Publisher}
1039 * @param source3
1040 * the third source {@code Publisher}
1041 * @param source4
1042 * the fourth source {@code Publisher}
1043 * @param source5
1044 * the fifth source {@code Publisher}
1045 * @param source6
1046 * the sixth source {@code Publisher}
1047 * @param source7
1048 * the seventh source {@code Publisher}
1049 * @param source8
1050 * the eighth source {@code Publisher}
1051 * @param combiner
1052 * the aggregation function used to combine the items emitted by the source {@code Publisher}s
1053 * @return the new {@code Flowable} instance
1054 * @throws NullPointerException if {@code source1}, {@code source2}, {@code source3},
1055 * {@code source4}, {@code source5}, {@code source6},
1056 * {@code source7}, {@code source8} or {@code combiner} is {@code null}
1057 * @see <a href="http://reactivex.io/documentation/operators/combinelatest.html">ReactiveX operators documentation: CombineLatest</a>
1058 */
1059 @SuppressWarnings("unchecked")
1060 @CheckReturnValue
1061 @NonNull
1062 @BackpressureSupport(BackpressureKind.FULL)
1063 @SchedulerSupport(SchedulerSupport.NONE)
1064 public static <@NonNull T1, @NonNull T2, @NonNull T3, @NonNull T4, @NonNull T5, @NonNull T6, @NonNull T7, @NonNull T8, @NonNull R> Flowable<R> combineLatest(
1065 @NonNull Publisher<? extends T1> source1, @NonNull Publisher<? extends T2> source2,
1066 @NonNull Publisher<? extends T3> source3, @NonNull Publisher<? extends T4> source4,
1067 @NonNull Publisher<? extends T5> source5, @NonNull Publisher<? extends T6> source6,
1068 @NonNull Publisher<? extends T7> source7, @NonNull Publisher<? extends T8> source8,
1069 @NonNull Function8<? super T1, ? super T2, ? super T3, ? super T4, ? super T5, ? super T6, ? super T7, ? super T8, ? extends R> combiner) {
1070 Objects.requireNonNull(source1, "source1 is null");
1071 Objects.requireNonNull(source2, "source2 is null");
1072 Objects.requireNonNull(source3, "source3 is null");
1073 Objects.requireNonNull(source4, "source4 is null");
1074 Objects.requireNonNull(source5, "source5 is null");
1075 Objects.requireNonNull(source6, "source6 is null");
1076 Objects.requireNonNull(source7, "source7 is null");
1077 Objects.requireNonNull(source8, "source8 is null");
1078 Objects.requireNonNull(combiner, "combiner is null");
1079 return combineLatestArray(new Publisher[] { source1, source2, source3, source4, source5, source6, source7, source8 }, Functions.toFunction(combiner), bufferSize());
1080 }
1081
1082 /**
1083 * Combines nine source {@link Publisher}s by emitting an item that aggregates the latest values of each of the
1084 * source {@code Publisher}s each time an item is received from any of the source {@code Publisher}s, where this
1085 * aggregation is defined by a specified function.
1086 * <p>
1087 * If any of the sources never produces an item but only terminates (normally or with an error), the
1088 * resulting sequence terminates immediately (normally or with all the errors accumulated until that point).
1089 * If that input source is also synchronous, other sources after it will not be subscribed to.
1090 * <p>
1091 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/combineLatest.v3.png" alt="">
1092 * <dl>
1093 * <dt><b>Backpressure:</b></dt>
1094 * <dd>The returned {@code Publisher} honors backpressure from downstream. The source {@code Publisher}s
1095 * are requested in a bounded manner, however, their backpressure is not enforced (the operator won't signal
1096 * {@link MissingBackpressureException}) and may lead to {@link OutOfMemoryError} due to internal buffer bloat.</dd>
1097 * <dt><b>Scheduler:</b></dt>
1098 * <dd>{@code combineLatest} does not operate by default on a particular {@link Scheduler}.</dd>
1099 * </dl>
1100 *
1101 * @param <T1> the element type of the first source
1102 * @param <T2> the element type of the second source
1103 * @param <T3> the element type of the third source
1104 * @param <T4> the element type of the fourth source
1105 * @param <T5> the element type of the fifth source
1106 * @param <T6> the element type of the sixth source
1107 * @param <T7> the element type of the seventh source
1108 * @param <T8> the element type of the eighth source
1109 * @param <T9> the element type of the ninth source
1110 * @param <R> the combined output type
1111 * @param source1
1112 * the first source {@code Publisher}
1113 * @param source2
1114 * the second source {@code Publisher}
1115 * @param source3
1116 * the third source {@code Publisher}
1117 * @param source4
1118 * the fourth source {@code Publisher}
1119 * @param source5
1120 * the fifth source {@code Publisher}
1121 * @param source6
1122 * the sixth source {@code Publisher}
1123 * @param source7
1124 * the seventh source {@code Publisher}
1125 * @param source8
1126 * the eighth source {@code Publisher}
1127 * @param source9
1128 * the ninth source {@code Publisher}
1129 * @param combiner
1130 * the aggregation function used to combine the items emitted by the source {@code Publisher}s
1131 * @return the new {@code Flowable} instance
1132 * @throws NullPointerException if {@code source1}, {@code source2}, {@code source3},
1133 * {@code source4}, {@code source5}, {@code source6},
1134 * {@code source7}, {@code source8}, {@code source9}
1135 * or {@code combiner} is {@code null}
1136 * @see <a href="http://reactivex.io/documentation/operators/combinelatest.html">ReactiveX operators documentation: CombineLatest</a>
1137 */
1138 @SuppressWarnings("unchecked")
1139 @CheckReturnValue
1140 @NonNull
1141 @BackpressureSupport(BackpressureKind.FULL)
1142 @SchedulerSupport(SchedulerSupport.NONE)
1143 public static <@NonNull T1, @NonNull T2, @NonNull T3, @NonNull T4, @NonNull T5, @NonNull T6, @NonNull T7, @NonNull T8, @NonNull T9, @NonNull R> Flowable<R> combineLatest(
1144 @NonNull Publisher<? extends T1> source1, @NonNull Publisher<? extends T2> source2,
1145 @NonNull Publisher<? extends T3> source3, @NonNull Publisher<? extends T4> source4,
1146 @NonNull Publisher<? extends T5> source5, @NonNull Publisher<? extends T6> source6,
1147 @NonNull Publisher<? extends T7> source7, @NonNull Publisher<? extends T8> source8,
1148 @NonNull Publisher<? extends T9> source9,
1149 @NonNull Function9<? super T1, ? super T2, ? super T3, ? super T4, ? super T5, ? super T6, ? super T7, ? super T8, ? super T9, ? extends R> combiner) {
1150 Objects.requireNonNull(source1, "source1 is null");
1151 Objects.requireNonNull(source2, "source2 is null");
1152 Objects.requireNonNull(source3, "source3 is null");
1153 Objects.requireNonNull(source4, "source4 is null");
1154 Objects.requireNonNull(source5, "source5 is null");
1155 Objects.requireNonNull(source6, "source6 is null");
1156 Objects.requireNonNull(source7, "source7 is null");
1157 Objects.requireNonNull(source8, "source8 is null");
1158 Objects.requireNonNull(source9, "source9 is null");
1159 Objects.requireNonNull(combiner, "combiner is null");
1160 return combineLatestArray(new Publisher[] { source1, source2, source3, source4, source5, source6, source7, source8, source9 }, Functions.toFunction(combiner), bufferSize());
1161 }
1162
1163 /**
1164 * Concatenates elements of each {@link Publisher} provided via an {@link Iterable} sequence into a single sequence
1165 * of elements without interleaving them.
1166 * <p>
1167 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/concat.v3.png" alt="">
1168 * <dl>
1169 * <dt><b>Backpressure:</b></dt>
1170 * <dd>The operator honors backpressure from downstream. The {@code Publisher}
1171 * sources are expected to honor backpressure as well.
1172 * If any of the source {@code Publisher}s violate this, it <em>may</em> throw an
1173 * {@link IllegalStateException} when that {@code Publisher} completes.</dd>
1174 * <dt><b>Scheduler:</b></dt>
1175 * <dd>{@code concat} does not operate by default on a particular {@link Scheduler}.</dd>
1176 * </dl>
1177 * @param <T> the common value type of the sources
1178 * @param sources the {@code Iterable} sequence of {@code Publisher}s
1179 * @return the new {@code Flowable} instance
1180 * @throws NullPointerException if {@code sources} is {@code null}
1181 */
1182 @SuppressWarnings({ "unchecked", "rawtypes" })
1183 @CheckReturnValue
1184 @NonNull
1185 @BackpressureSupport(BackpressureKind.FULL)
1186 @SchedulerSupport(SchedulerSupport.NONE)
1187 public static <@NonNull T> Flowable<T> concat(@NonNull Iterable<@NonNull ? extends Publisher<? extends T>> sources) {
1188 Objects.requireNonNull(sources, "sources is null");
1189 // unlike general sources, fromIterable can only throw on a boundary because it is consumed only there
1190 return fromIterable(sources).concatMapDelayError((Function)Functions.identity(), false, 2);
1191 }
1192
1193 /**
1194 * Returns a {@code Flowable} that emits the items emitted by each of the {@link Publisher}s emitted by the source
1195 * {@code Publisher}, one after the other, without interleaving them.
1196 * <p>
1197 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/concat.v3.png" alt="">
1198 * <dl>
1199 * <dt><b>Backpressure:</b></dt>
1200 * <dd>The operator honors backpressure from downstream. Both the outer and inner {@code Publisher}
1201 * sources are expected to honor backpressure as well. If the outer violates this, a
1202 * {@link MissingBackpressureException} is signaled. If any of the inner {@code Publisher}s violates
1203 * this, it <em>may</em> throw an {@link IllegalStateException} when an inner {@code Publisher} completes.</dd>
1204 * <dt><b>Scheduler:</b></dt>
1205 * <dd>{@code concat} does not operate by default on a particular {@link Scheduler}.</dd>
1206 * </dl>
1207 *
1208 * @param <T> the common element base type
1209 * @param sources
1210 * a {@code Publisher} that emits {@code Publisher}s
1211 * @return the new {@code Flowable} instance
1212 * @throws NullPointerException if {@code sources} is {@code null}
1213 * @see <a href="http://reactivex.io/documentation/operators/concat.html">ReactiveX operators documentation: Concat</a>
1214 */
1215 @CheckReturnValue
1216 @BackpressureSupport(BackpressureKind.FULL)
1217 @SchedulerSupport(SchedulerSupport.NONE)
1218 @NonNull
1219 public static <@NonNull T> Flowable<T> concat(@NonNull Publisher<@NonNull ? extends Publisher<? extends T>> sources) {
1220 return concat(sources, bufferSize());
1221 }
1222
1223 /**
1224 * Returns a {@code Flowable} that emits the items emitted by each of the {@link Publisher}s emitted by the source
1225 * {@code Publisher}, one after the other, without interleaving them.
1226 * <p>
1227 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/concat.v3.png" alt="">
1228 * <dl>
1229 * <dt><b>Backpressure:</b></dt>
1230 * <dd>The operator honors backpressure from downstream. Both the outer and inner {@code Publisher}
1231 * sources are expected to honor backpressure as well. If the outer violates this, a
1232 * {@link MissingBackpressureException} is signaled. If any of the inner {@code Publisher}s violates
1233 * this, it <em>may</em> throw an {@link IllegalStateException} when an inner {@code Publisher} completes.</dd>
1234 * <dt><b>Scheduler:</b></dt>
1235 * <dd>{@code concat} does not operate by default on a particular {@link Scheduler}.</dd>
1236 * </dl>
1237 *
1238 * @param <T> the common element base type
1239 * @param sources
1240 * a {@code Publisher} that emits {@code Publisher}s
1241 * @param prefetch
1242 * the number of {@code Publisher}s to prefetch from the sources sequence.
1243 * @return the new {@code Flowable} instance
1244 * @throws NullPointerException if {@code sources} is {@code null}
1245 * @throws IllegalArgumentException if {@code prefetch} is non-positive
1246 * @see <a href="http://reactivex.io/documentation/operators/concat.html">ReactiveX operators documentation: Concat</a>
1247 */
1248 @SuppressWarnings({ "unchecked", "rawtypes" })
1249 @CheckReturnValue
1250 @BackpressureSupport(BackpressureKind.FULL)
1251 @SchedulerSupport(SchedulerSupport.NONE)
1252 @NonNull
1253 public static <@NonNull T> Flowable<T> concat(@NonNull Publisher<@NonNull ? extends Publisher<? extends T>> sources, int prefetch) {
1254 return fromPublisher(sources).concatMap((Function)Functions.identity(), prefetch);
1255 }
1256
1257 /**
1258 * Returns a {@code Flowable} that emits the items emitted by two {@link Publisher}s, one after the other, without
1259 * interleaving them.
1260 * <p>
1261 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/concat.v3.png" alt="">
1262 * <dl>
1263 * <dt><b>Backpressure:</b></dt>
1264 * <dd>The operator honors backpressure from downstream. The {@code Publisher}
1265 * sources are expected to honor backpressure as well.
1266 * If any of the source {@code Publisher}s violate this, it <em>may</em> throw an
1267 * {@link IllegalStateException} when that source {@code Publisher} completes.</dd>
1268 * <dt><b>Scheduler:</b></dt>
1269 * <dd>{@code concat} does not operate by default on a particular {@link Scheduler}.</dd>
1270 * </dl>
1271 *
1272 * @param <T> the common element base type
1273 * @param source1
1274 * a {@code Publisher} to be concatenated
1275 * @param source2
1276 * a {@code Publisher} to be concatenated
1277 * @return the new {@code Flowable} instance
1278 * @throws NullPointerException if {@code source1} or {@code source2} is {@code null}
1279 * @see <a href="http://reactivex.io/documentation/operators/concat.html">ReactiveX operators documentation: Concat</a>
1280 */
1281 @CheckReturnValue
1282 @NonNull
1283 @BackpressureSupport(BackpressureKind.FULL)
1284 @SchedulerSupport(SchedulerSupport.NONE)
1285 public static <@NonNull T> Flowable<T> concat(@NonNull Publisher<? extends T> source1, @NonNull Publisher<? extends T> source2) {
1286 Objects.requireNonNull(source1, "source1 is null");
1287 Objects.requireNonNull(source2, "source2 is null");
1288 return concatArray(source1, source2);
1289 }
1290
1291 /**
1292 * Returns a {@code Flowable} that emits the items emitted by three {@link Publisher}s, one after the other, without
1293 * interleaving them.
1294 * <p>
1295 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/concat.v3.png" alt="">
1296 * <dl>
1297 * <dt><b>Backpressure:</b></dt>
1298 * <dd>The operator honors backpressure from downstream. The {@code Publisher}
1299 * sources are expected to honor backpressure as well.
1300 * If any of the source {@code Publisher}s violate this, it <em>may</em> throw an
1301 * {@link IllegalStateException} when that source {@code Publisher} completes.</dd>
1302 * <dt><b>Scheduler:</b></dt>
1303 * <dd>{@code concat} does not operate by default on a particular {@link Scheduler}.</dd>
1304 * </dl>
1305 *
1306 * @param <T> the common element base type
1307 * @param source1
1308 * a {@code Publisher} to be concatenated
1309 * @param source2
1310 * a {@code Publisher} to be concatenated
1311 * @param source3
1312 * a {@code Publisher} to be concatenated
1313 * @return the new {@code Flowable} instance
1314 * @throws NullPointerException if {@code source1}, {@code source2} or {@code source3} is {@code null}
1315 * @see <a href="http://reactivex.io/documentation/operators/concat.html">ReactiveX operators documentation: Concat</a>
1316 */
1317 @CheckReturnValue
1318 @NonNull
1319 @BackpressureSupport(BackpressureKind.FULL)
1320 @SchedulerSupport(SchedulerSupport.NONE)
1321 public static <@NonNull T> Flowable<T> concat(
1322 @NonNull Publisher<? extends T> source1, @NonNull Publisher<? extends T> source2,
1323 @NonNull Publisher<? extends T> source3) {
1324 Objects.requireNonNull(source1, "source1 is null");
1325 Objects.requireNonNull(source2, "source2 is null");
1326 Objects.requireNonNull(source3, "source3 is null");
1327 return concatArray(source1, source2, source3);
1328 }
1329
1330 /**
1331 * Returns a {@code Flowable} that emits the items emitted by four {@link Publisher}s, one after the other, without
1332 * interleaving them.
1333 * <p>
1334 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/concat.v3.png" alt="">
1335 * <dl>
1336 * <dt><b>Backpressure:</b></dt>
1337 * <dd>The operator honors backpressure from downstream. The {@code Publisher}
1338 * sources are expected to honor backpressure as well.
1339 * If any of the source {@code Publisher}s violate this, it <em>may</em> throw an
1340 * {@link IllegalStateException} when that source {@code Publisher} completes.</dd>
1341 * <dt><b>Scheduler:</b></dt>
1342 * <dd>{@code concat} does not operate by default on a particular {@link Scheduler}.</dd>
1343 * </dl>
1344 *
1345 * @param <T> the common element base type
1346 * @param source1
1347 * a {@code Publisher} to be concatenated
1348 * @param source2
1349 * a {@code Publisher} to be concatenated
1350 * @param source3
1351 * a {@code Publisher} to be concatenated
1352 * @param source4
1353 * a {@code Publisher} to be concatenated
1354 * @return the new {@code Flowable} instance
1355 * @throws NullPointerException if {@code source1}, {@code source2}, {@code source3} or {@code source4} is {@code null}
1356 * @see <a href="http://reactivex.io/documentation/operators/concat.html">ReactiveX operators documentation: Concat</a>
1357 */
1358 @CheckReturnValue
1359 @NonNull
1360 @BackpressureSupport(BackpressureKind.FULL)
1361 @SchedulerSupport(SchedulerSupport.NONE)
1362 public static <@NonNull T> Flowable<T> concat(
1363 @NonNull Publisher<? extends T> source1, @NonNull Publisher<? extends T> source2,
1364 @NonNull Publisher<? extends T> source3, @NonNull Publisher<? extends T> source4) {
1365 Objects.requireNonNull(source1, "source1 is null");
1366 Objects.requireNonNull(source2, "source2 is null");
1367 Objects.requireNonNull(source3, "source3 is null");
1368 Objects.requireNonNull(source4, "source4 is null");
1369 return concatArray(source1, source2, source3, source4);
1370 }
1371
1372 /**
1373 * Concatenates a variable number of {@link Publisher} sources.
1374 * <p>
1375 * Note: named this way because of overload conflict with {@code concat(Publisher<Publisher<T>>}).
1376 * <p>
1377 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/concat.v3.png" alt="">
1378 * <dl>
1379 * <dt><b>Backpressure:</b></dt>
1380 * <dd>The operator honors backpressure from downstream. The {@code Publisher}
1381 * sources are expected to honor backpressure as well.
1382 * If any of the source {@code Publisher}s violate this, it <em>may</em> throw an
1383 * {@link IllegalStateException} when that source {@code Publisher} completes.</dd>
1384 * <dt><b>Scheduler:</b></dt>
1385 * <dd>{@code concatArray} does not operate by default on a particular {@link Scheduler}.</dd>
1386 * </dl>
1387 * @param sources the array of source {@code Publisher}s
1388 * @param <T> the common base value type
1389 * @return the new {@code Flowable} instance
1390 * @throws NullPointerException if {@code sources} is {@code null}
1391 */
1392 @CheckReturnValue
1393 @BackpressureSupport(BackpressureKind.FULL)
1394 @SchedulerSupport(SchedulerSupport.NONE)
1395 @SafeVarargs
1396 @NonNull
1397 public static <@NonNull T> Flowable<T> concatArray(@NonNull Publisher<? extends T>... sources) {
1398 Objects.requireNonNull(sources, "sources is null");
1399 if (sources.length == 0) {
1400 return empty();
1401 } else
1402 if (sources.length == 1) {
1403 return fromPublisher(sources[0]);
1404 }
1405 return RxJavaPlugins.onAssembly(new FlowableConcatArray<>(sources, false));
1406 }
1407
1408 /**
1409 * Concatenates a variable number of {@link Publisher} sources and delays errors from any of them
1410 * till all terminate.
1411 * <p>
1412 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/concat.v3.png" alt="">
1413 * <dl>
1414 * <dt><b>Backpressure:</b></dt>
1415 * <dd>The operator honors backpressure from downstream. The {@code Publisher}
1416 * sources are expected to honor backpressure as well.
1417 * If any of the source {@code Publisher}s violate this, it <em>may</em> throw an
1418 * {@link IllegalStateException} when that source {@code Publisher} completes.</dd>
1419 * <dt><b>Scheduler:</b></dt>
1420 * <dd>{@code concatArrayDelayError} does not operate by default on a particular {@link Scheduler}.</dd>
1421 * </dl>
1422 * @param sources the array of source {@code Publisher}s
1423 * @param <T> the common base value type
1424 * @return the new {@code Flowable} instance
1425 * @throws NullPointerException if {@code sources} is {@code null}
1426 */
1427 @CheckReturnValue
1428 @BackpressureSupport(BackpressureKind.FULL)
1429 @SchedulerSupport(SchedulerSupport.NONE)
1430 @SafeVarargs
1431 @NonNull
1432 public static <@NonNull T> Flowable<T> concatArrayDelayError(@NonNull Publisher<? extends T>... sources) {
1433 Objects.requireNonNull(sources, "sources is null");
1434 if (sources.length == 0) {
1435 return empty();
1436 } else
1437 if (sources.length == 1) {
1438 return fromPublisher(sources[0]);
1439 }
1440 return RxJavaPlugins.onAssembly(new FlowableConcatArray<>(sources, true));
1441 }
1442
1443 /**
1444 * Concatenates an array of {@link Publisher}s eagerly into a single stream of values.
1445 * <p>
1446 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Flowable.concatArrayEager.png" alt="">
1447 * <p>
1448 * Eager concatenation means that once a subscriber subscribes, this operator subscribes to all of the
1449 * source {@code Publisher}s. The operator buffers the values emitted by these {@code Publisher}s and then drains them
1450 * in order, each one after the previous one completes.
1451 * <dl>
1452 * <dt><b>Backpressure:</b></dt>
1453 * <dd>The operator honors backpressure from downstream. The {@code Publisher}
1454 * sources are expected to honor backpressure as well.
1455 * If any of the source {@code Publisher}s violate this, the operator will signal a
1456 * {@link MissingBackpressureException}.</dd>
1457 * <dt><b>Scheduler:</b></dt>
1458 * <dd>This method does not operate by default on a particular {@link Scheduler}.</dd>
1459 * </dl>
1460 * @param <T> the value type
1461 * @param sources an array of {@code Publisher}s that need to be eagerly concatenated
1462 * @return the new {@code Flowable} instance with the specified concatenation behavior
1463 * @throws NullPointerException if {@code sources} is {@code null}
1464 * @since 2.0
1465 */
1466 @CheckReturnValue
1467 @BackpressureSupport(BackpressureKind.FULL)
1468 @SchedulerSupport(SchedulerSupport.NONE)
1469 @SafeVarargs
1470 @NonNull
1471 public static <@NonNull T> Flowable<T> concatArrayEager(@NonNull Publisher<? extends T>... sources) {
1472 return concatArrayEager(bufferSize(), bufferSize(), sources);
1473 }
1474
1475 /**
1476 * Concatenates an array of {@link Publisher}s eagerly into a single stream of values.
1477 * <p>
1478 * <img width="640" height="406" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Flowable.concatArrayEager.nn.png" alt="">
1479 * <p>
1480 * Eager concatenation means that once a subscriber subscribes, this operator subscribes to all of the
1481 * source {@code Publisher}s. The operator buffers the values emitted by these {@code Publisher}s and then drains them
1482 * in order, each one after the previous one completes.
1483 * <dl>
1484 * <dt><b>Backpressure:</b></dt>
1485 * <dd>The operator honors backpressure from downstream. The {@code Publisher}
1486 * sources are expected to honor backpressure as well.
1487 * If any of the source {@code Publisher}s violate this, the operator will signal a
1488 * {@link MissingBackpressureException}.</dd>
1489 * <dt><b>Scheduler:</b></dt>
1490 * <dd>This method does not operate by default on a particular {@link Scheduler}.</dd>
1491 * </dl>
1492 * @param <T> the value type
1493 * @param sources an array of {@code Publisher}s that need to be eagerly concatenated
1494 * @param maxConcurrency the maximum number of concurrent subscriptions at a time, {@link Integer#MAX_VALUE}
1495 * is interpreted as an indication to subscribe to all sources at once
1496 * @param prefetch the number of elements to prefetch from each {@code Publisher} source
1497 * @return the new {@code Flowable} instance with the specified concatenation behavior
1498 * @throws NullPointerException if {@code sources} is {@code null}
1499 * @throws IllegalArgumentException if {@code maxConcurrency} or {@code prefetch} is non-positive
1500 * @since 2.0
1501 */
1502 @CheckReturnValue
1503 @NonNull
1504 @BackpressureSupport(BackpressureKind.FULL)
1505 @SchedulerSupport(SchedulerSupport.NONE)
1506 @SuppressWarnings({ "rawtypes", "unchecked" })
1507 @SafeVarargs
1508 public static <@NonNull T> Flowable<T> concatArrayEager(int maxConcurrency, int prefetch, @NonNull Publisher<? extends T>... sources) {
1509 Objects.requireNonNull(sources, "sources is null");
1510 ObjectHelper.verifyPositive(maxConcurrency, "maxConcurrency");
1511 ObjectHelper.verifyPositive(prefetch, "prefetch");
1512 return RxJavaPlugins.onAssembly(new FlowableConcatMapEager(new FlowableFromArray(sources), Functions.identity(), maxConcurrency, prefetch, ErrorMode.IMMEDIATE));
1513 }
1514
1515 /**
1516 * Concatenates an array of {@link Publisher}s eagerly into a single stream of values
1517 * and delaying any errors until all sources terminate.
1518 * <p>
1519 * <img width="640" height="358" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Flowable.concatArrayEagerDelayError.png" alt="">
1520 * <p>
1521 * Eager concatenation means that once a subscriber subscribes, this operator subscribes to all of the
1522 * source {@code Publisher}s. The operator buffers the values emitted by these {@code Publisher}s
1523 * and then drains them in order, each one after the previous one completes.
1524 * <dl>
1525 * <dt><b>Backpressure:</b></dt>
1526 * <dd>The operator honors backpressure from downstream. The {@code Publisher}
1527 * sources are expected to honor backpressure as well.
1528 * If any of the source {@code Publisher}s violate this, the operator will signal a
1529 * {@link MissingBackpressureException}.</dd>
1530 * <dt><b>Scheduler:</b></dt>
1531 * <dd>This method does not operate by default on a particular {@link Scheduler}.</dd>
1532 * </dl>
1533 * @param <T> the value type
1534 * @param sources an array of {@code Publisher}s that need to be eagerly concatenated
1535 * @return the new {@code Flowable} instance with the specified concatenation behavior
1536 * @throws NullPointerException if {@code sources} is {@code null}
1537 * @since 2.2.1 - experimental
1538 */
1539 @CheckReturnValue
1540 @SchedulerSupport(SchedulerSupport.NONE)
1541 @BackpressureSupport(BackpressureKind.FULL)
1542 @SafeVarargs
1543 @NonNull
1544 public static <@NonNull T> Flowable<T> concatArrayEagerDelayError(@NonNull Publisher<? extends T>... sources) {
1545 return concatArrayEagerDelayError(bufferSize(), bufferSize(), sources);
1546 }
1547
1548 /**
1549 * Concatenates an array of {@link Publisher}s eagerly into a single stream of values
1550 * and delaying any errors until all sources terminate.
1551 * <p>
1552 * <img width="640" height="359" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Flowable.concatArrayEagerDelayError.nn.png" alt="">
1553 * <p>
1554 * Eager concatenation means that once a subscriber subscribes, this operator subscribes to all of the
1555 * source {@code Publisher}s. The operator buffers the values emitted by these {@code Publisher}s
1556 * and then drains them in order, each one after the previous one completes.
1557 * <dl>
1558 * <dt><b>Backpressure:</b></dt>
1559 * <dd>The operator honors backpressure from downstream. The {@code Publisher}
1560 * sources are expected to honor backpressure as well.
1561 * If any of the source {@code Publisher}s violate this, the operator will signal a
1562 * {@link MissingBackpressureException}.</dd>
1563 * <dt><b>Scheduler:</b></dt>
1564 * <dd>This method does not operate by default on a particular {@link Scheduler}.</dd>
1565 * </dl>
1566 * @param <T> the value type
1567 * @param sources an array of {@code Publisher}s that need to be eagerly concatenated
1568 * @param maxConcurrency the maximum number of concurrent subscriptions at a time, {@link Integer#MAX_VALUE}
1569 * is interpreted as indication to subscribe to all sources at once
1570 * @param prefetch the number of elements to prefetch from each {@code Publisher} source
1571 * @return the new {@code Flowable} instance with the specified concatenation behavior
1572 * @throws NullPointerException if {@code sources} is {@code null}
1573 * @throws IllegalArgumentException if {@code maxConcurrency} or {@code prefetch} is non-positive
1574 * @since 2.2.1 - experimental
1575 */
1576 @SuppressWarnings({ "rawtypes", "unchecked" })
1577 @CheckReturnValue
1578 @SchedulerSupport(SchedulerSupport.NONE)
1579 @BackpressureSupport(BackpressureKind.FULL)
1580 @SafeVarargs
1581 @NonNull
1582 public static <@NonNull T> Flowable<T> concatArrayEagerDelayError(int maxConcurrency, int prefetch, @NonNull Publisher<? extends T>... sources) {
1583 return fromArray(sources).concatMapEagerDelayError((Function)Functions.identity(), true, maxConcurrency, prefetch);
1584 }
1585
1586 /**
1587 * Concatenates the {@link Iterable} sequence of {@link Publisher}s into a single sequence by subscribing to each {@code Publisher},
1588 * one after the other, one at a time and delays any errors till the all inner {@code Publisher}s terminate.
1589 *
1590 * <dl>
1591 * <dt><b>Backpressure:</b></dt>
1592 * <dd>The operator honors backpressure from downstream. Both the outer and inner {@code Publisher}
1593 * sources are expected to honor backpressure as well. If the outer violates this, a
1594 * {@link MissingBackpressureException} is signaled. If any of the inner {@code Publisher}s violates
1595 * this, it <em>may</em> throw an {@link IllegalStateException} when an inner {@code Publisher} completes.</dd>
1596 * <dt><b>Scheduler:</b></dt>
1597 * <dd>{@code concatDelayError} does not operate by default on a particular {@link Scheduler}.</dd>
1598 * </dl>
1599 *
1600 * @param <T> the common element base type
1601 * @param sources the {@code Iterable} sequence of {@code Publisher}s
1602 * @return the new {@code Flowable} with the concatenating behavior
1603 * @throws NullPointerException if {@code sources} is {@code null}
1604 */
1605 @SuppressWarnings({ "unchecked", "rawtypes" })
1606 @CheckReturnValue
1607 @NonNull
1608 @BackpressureSupport(BackpressureKind.FULL)
1609 @SchedulerSupport(SchedulerSupport.NONE)
1610 public static <@NonNull T> Flowable<T> concatDelayError(@NonNull Iterable<@NonNull ? extends Publisher<? extends T>> sources) {
1611 Objects.requireNonNull(sources, "sources is null");
1612 return fromIterable(sources).concatMapDelayError((Function)Functions.identity());
1613 }
1614
1615 /**
1616 * Concatenates the {@link Publisher} sequence of {@code Publisher}s into a single sequence by subscribing to each inner {@code Publisher},
1617 * one after the other, one at a time and delays any errors till the all inner and the outer {@code Publisher}s terminate.
1618 *
1619 * <dl>
1620 * <dt><b>Backpressure:</b></dt>
1621 * <dd>{@code concatDelayError} fully supports backpressure.</dd>
1622 * <dt><b>Scheduler:</b></dt>
1623 * <dd>{@code concatDelayError} does not operate by default on a particular {@link Scheduler}.</dd>
1624 * </dl>
1625 *
1626 * @param <T> the common element base type
1627 * @param sources the {@code Publisher} sequence of {@code Publisher}s
1628 * @return the new {@code Flowable} with the concatenating behavior
1629 * @throws NullPointerException if {@code sources} is {@code null}
1630 */
1631 @CheckReturnValue
1632 @BackpressureSupport(BackpressureKind.FULL)
1633 @SchedulerSupport(SchedulerSupport.NONE)
1634 @NonNull
1635 public static <@NonNull T> Flowable<T> concatDelayError(@NonNull Publisher<@NonNull ? extends Publisher<? extends T>> sources) {
1636 return concatDelayError(sources, bufferSize(), true);
1637 }
1638
1639 /**
1640 * Concatenates the {@link Publisher} sequence of {@code Publisher}s into a single sequence by subscribing to each inner {@code Publisher},
1641 * one after the other, one at a time and delays any errors till the all inner and the outer {@code Publisher}s terminate.
1642 *
1643 * <dl>
1644 * <dt><b>Backpressure:</b></dt>
1645 * <dd>{@code concatDelayError} fully supports backpressure.</dd>
1646 * <dt><b>Scheduler:</b></dt>
1647 * <dd>{@code concatDelayError} does not operate by default on a particular {@link Scheduler}.</dd>
1648 * </dl>
1649 *
1650 * @param <T> the common element base type
1651 * @param sources the {@code Publisher} sequence of {@code Publisher}s
1652 * @param prefetch the number of elements to prefetch from the outer {@code Publisher}
1653 * @param tillTheEnd if {@code true}, exceptions from the outer and all inner {@code Publisher}s are delayed to the end
1654 * if {@code false}, exception from the outer {@code Publisher} is delayed till the current inner {@code Publisher} terminates
1655 * @return the new {@code Flowable} with the concatenating behavior
1656 * @throws NullPointerException if {@code sources} is {@code null}
1657 * @throws IllegalArgumentException if {@code prefetch} is {@code null}
1658 */
1659 @SuppressWarnings({ "unchecked", "rawtypes" })
1660 @CheckReturnValue
1661 @BackpressureSupport(BackpressureKind.FULL)
1662 @SchedulerSupport(SchedulerSupport.NONE)
1663 @NonNull
1664 public static <@NonNull T> Flowable<T> concatDelayError(@NonNull Publisher<@NonNull ? extends Publisher<? extends T>> sources, int prefetch, boolean tillTheEnd) {
1665 return fromPublisher(sources).concatMapDelayError((Function)Functions.identity(), tillTheEnd, prefetch);
1666 }
1667
1668 /**
1669 * Concatenates a sequence of {@link Publisher}s eagerly into a single stream of values.
1670 * <p>
1671 * <img width="640" height="422" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Flowable.concatEager.i.png" alt="">
1672 * <p>
1673 * Eager concatenation means that once a subscriber subscribes, this operator subscribes to all of the
1674 * source {@code Publisher}s. The operator buffers the values emitted by these {@code Publisher}s and then drains them
1675 * in order, each one after the previous one completes.
1676 * <dl>
1677 * <dt><b>Backpressure:</b></dt>
1678 * <dd>Backpressure is honored towards the downstream and the inner {@code Publisher}s are
1679 * expected to support backpressure. Violating this assumption, the operator will
1680 * signal {@link MissingBackpressureException}.</dd>
1681 * <dt><b>Scheduler:</b></dt>
1682 * <dd>This method does not operate by default on a particular {@link Scheduler}.</dd>
1683 * </dl>
1684 * @param <T> the value type
1685 * @param sources a sequence of {@code Publisher}s that need to be eagerly concatenated
1686 * @return the new {@code Flowable} instance with the specified concatenation behavior
1687 * @throws NullPointerException if {@code sources} is {@code null}
1688 * @since 2.0
1689 */
1690 @CheckReturnValue
1691 @BackpressureSupport(BackpressureKind.FULL)
1692 @SchedulerSupport(SchedulerSupport.NONE)
1693 @NonNull
1694 public static <@NonNull T> Flowable<T> concatEager(@NonNull Iterable<@NonNull ? extends Publisher<? extends T>> sources) {
1695 return concatEager(sources, bufferSize(), bufferSize());
1696 }
1697
1698 /**
1699 * Concatenates a sequence of {@link Publisher}s eagerly into a single stream of values and
1700 * runs a limited number of inner sequences at once.
1701 * <p>
1702 * <img width="640" height="375" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Flowable.concatEager.in.png" alt="">
1703 * <p>
1704 * Eager concatenation means that once a subscriber subscribes, this operator subscribes to all of the
1705 * source {@code Publisher}s. The operator buffers the values emitted by these {@code Publisher}s and then drains them
1706 * in order, each one after the previous one completes.
1707 * <dl>
1708 * <dt><b>Backpressure:</b></dt>
1709 * <dd>Backpressure is honored towards the downstream and both the outer and inner {@code Publisher}s are
1710 * expected to support backpressure. Violating this assumption, the operator will
1711 * signal {@link MissingBackpressureException}.</dd>
1712 * <dt><b>Scheduler:</b></dt>
1713 * <dd>This method does not operate by default on a particular {@link Scheduler}.</dd>
1714 * </dl>
1715 * @param <T> the value type
1716 * @param sources a sequence of {@code Publisher}s that need to be eagerly concatenated
1717 * @param maxConcurrency the maximum number of concurrently running inner {@code Publisher}s; {@link Integer#MAX_VALUE}
1718 * is interpreted as all inner {@code Publisher}s can be active at the same time
1719 * @param prefetch the number of elements to prefetch from each inner {@code Publisher} source
1720 * @return the new {@code Flowable} instance with the specified concatenation behavior
1721 * @throws NullPointerException if {@code sources} is {@code null}
1722 * @throws IllegalArgumentException if {@code maxConcurrency} or {@code prefetch} is non-positive
1723 * @since 2.0
1724 */
1725 @CheckReturnValue
1726 @NonNull
1727 @BackpressureSupport(BackpressureKind.FULL)
1728 @SchedulerSupport(SchedulerSupport.NONE)
1729 @SuppressWarnings({ "rawtypes", "unchecked" })
1730 public static <@NonNull T> Flowable<T> concatEager(@NonNull Iterable<@NonNull ? extends Publisher<? extends T>> sources, int maxConcurrency, int prefetch) {
1731 Objects.requireNonNull(sources, "sources is null");
1732 ObjectHelper.verifyPositive(maxConcurrency, "maxConcurrency");
1733 ObjectHelper.verifyPositive(prefetch, "prefetch");
1734 return RxJavaPlugins.onAssembly(new FlowableConcatMapEager(new FlowableFromIterable(sources), Functions.identity(), maxConcurrency, prefetch, ErrorMode.BOUNDARY));
1735 }
1736
1737 /**
1738 * Concatenates a {@link Publisher} sequence of {@code Publisher}s eagerly into a single stream of values.
1739 * <p>
1740 * <img width="640" height="490" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Flowable.concatEager.p.png" alt="">
1741 * <p>
1742 * Eager concatenation means that once a subscriber subscribes, this operator subscribes to all of the
1743 * emitted source {@code Publisher}s as they are observed. The operator buffers the values emitted by these
1744 * {@code Publisher}s and then drains them in order, each one after the previous one completes.
1745 * <dl>
1746 * <dt><b>Backpressure:</b></dt>
1747 * <dd>Backpressure is honored towards the downstream and both the outer and inner {@code Publisher}s are
1748 * expected to support backpressure. Violating this assumption, the operator will
1749 * signal {@link MissingBackpressureException}.</dd>
1750 * <dt><b>Scheduler:</b></dt>
1751 * <dd>This method does not operate by default on a particular {@link Scheduler}.</dd>
1752 * </dl>
1753 * @param <T> the value type
1754 * @param sources a sequence of {@code Publisher}s that need to be eagerly concatenated
1755 * @return the new {@code Flowable} instance with the specified concatenation behavior
1756 * @throws NullPointerException if {@code sources} is {@code null}
1757 * @since 2.0
1758 */
1759 @CheckReturnValue
1760 @BackpressureSupport(BackpressureKind.FULL)
1761 @SchedulerSupport(SchedulerSupport.NONE)
1762 @NonNull
1763 public static <@NonNull T> Flowable<T> concatEager(@NonNull Publisher<@NonNull ? extends Publisher<? extends T>> sources) {
1764 return concatEager(sources, bufferSize(), bufferSize());
1765 }
1766
1767 /**
1768 * Concatenates a {@link Publisher} sequence of {@code Publisher}s eagerly into a single stream of values and
1769 * runs a limited number of inner sequences at once.
1770 * <p>
1771 * <img width="640" height="421" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Flowable.concatEager.pn.png" alt="">
1772 * <p>
1773 * Eager concatenation means that once a subscriber subscribes, this operator subscribes to all of the
1774 * emitted source {@code Publisher}s as they are observed. The operator buffers the values emitted by these
1775 * {@code Publisher}s and then drains them in order, each one after the previous one completes.
1776 * <dl>
1777 * <dt><b>Backpressure:</b></dt>
1778 * <dd>Backpressure is honored towards the downstream and both the outer and inner {@code Publisher}s are
1779 * expected to support backpressure. Violating this assumption, the operator will
1780 * signal {@link MissingBackpressureException}.</dd>
1781 * <dt><b>Scheduler:</b></dt>
1782 * <dd>This method does not operate by default on a particular {@link Scheduler}.</dd>
1783 * </dl>
1784 * @param <T> the value type
1785 * @param sources a sequence of {@code Publisher}s that need to be eagerly concatenated
1786 * @param maxConcurrency the maximum number of concurrently running inner {@code Publisher}s; {@link Integer#MAX_VALUE}
1787 * is interpreted as all inner {@code Publisher}s can be active at the same time
1788 * @param prefetch the number of elements to prefetch from each inner {@code Publisher} source
1789 * @return the new {@code Flowable} instance with the specified concatenation behavior
1790 * @throws NullPointerException if {@code sources} is {@code null}
1791 * @throws IllegalArgumentException if {@code maxConcurrency} or {@code prefetch} is non-positive
1792 * @since 2.0
1793 */
1794 @CheckReturnValue
1795 @NonNull
1796 @BackpressureSupport(BackpressureKind.FULL)
1797 @SchedulerSupport(SchedulerSupport.NONE)
1798 @SuppressWarnings({ "rawtypes", "unchecked" })
1799 public static <@NonNull T> Flowable<T> concatEager(@NonNull Publisher<@NonNull ? extends Publisher<? extends T>> sources, int maxConcurrency, int prefetch) {
1800 Objects.requireNonNull(sources, "sources is null");
1801 ObjectHelper.verifyPositive(maxConcurrency, "maxConcurrency");
1802 ObjectHelper.verifyPositive(prefetch, "prefetch");
1803 return RxJavaPlugins.onAssembly(new FlowableConcatMapEagerPublisher(sources, Functions.identity(), maxConcurrency, prefetch, ErrorMode.IMMEDIATE));
1804 }
1805
1806 /**
1807 * Concatenates a sequence of {@link Publisher}s eagerly into a single stream of values,
1808 * delaying errors until all the inner sequences terminate.
1809 * <p>
1810 * <img width="640" height="428" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Flowable.concatEagerDelayError.i.png" alt="">
1811 * <p>
1812 * Eager concatenation means that once a subscriber subscribes, this operator subscribes to all of the
1813 * source {@code Publisher}s. The operator buffers the values emitted by these {@code Publisher}s and then drains them
1814 * in order, each one after the previous one completes.
1815 * <dl>
1816 * <dt><b>Backpressure:</b></dt>
1817 * <dd>Backpressure is honored towards the downstream and the inner {@code Publisher}s are
1818 * expected to support backpressure. Violating this assumption, the operator will
1819 * signal {@link MissingBackpressureException}.</dd>
1820 * <dt><b>Scheduler:</b></dt>
1821 * <dd>This method does not operate by default on a particular {@link Scheduler}.</dd>
1822 * </dl>
1823 * @param <T> the value type
1824 * @param sources a sequence of {@code Publisher}s that need to be eagerly concatenated
1825 * @return the new {@code Flowable} instance with the specified concatenation behavior
1826 * @throws NullPointerException if {@code sources} is {@code null}
1827 * @since 3.0.0
1828 */
1829 @CheckReturnValue
1830 @BackpressureSupport(BackpressureKind.FULL)
1831 @SchedulerSupport(SchedulerSupport.NONE)
1832 @NonNull
1833 public static <@NonNull T> Flowable<T> concatEagerDelayError(@NonNull Iterable<@NonNull ? extends Publisher<? extends T>> sources) {
1834 return concatEagerDelayError(sources, bufferSize(), bufferSize());
1835 }
1836
1837 /**
1838 * Concatenates a sequence of {@link Publisher}s eagerly into a single stream of values,
1839 * delaying errors until all the inner sequences terminate and runs a limited number
1840 * of inner sequences at once.
1841 * <p>
1842 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Flowable.concatEagerDelayError.in.png" alt="">
1843 * <p>
1844 * Eager concatenation means that once a subscriber subscribes, this operator subscribes to all of the
1845 * source {@code Publisher}s. The operator buffers the values emitted by these {@code Publisher}s and then drains them
1846 * in order, each one after the previous one completes.
1847 * <dl>
1848 * <dt><b>Backpressure:</b></dt>
1849 * <dd>Backpressure is honored towards the downstream and both the outer and inner {@code Publisher}s are
1850 * expected to support backpressure. Violating this assumption, the operator will
1851 * signal {@link MissingBackpressureException}.</dd>
1852 * <dt><b>Scheduler:</b></dt>
1853 * <dd>This method does not operate by default on a particular {@link Scheduler}.</dd>
1854 * </dl>
1855 * @param <T> the value type
1856 * @param sources a sequence of {@code Publisher}s that need to be eagerly concatenated
1857 * @param maxConcurrency the maximum number of concurrently running inner {@code Publisher}s; {@link Integer#MAX_VALUE}
1858 * is interpreted as all inner {@code Publisher}s can be active at the same time
1859 * @param prefetch the number of elements to prefetch from each inner {@code Publisher} source
1860 * @return the new {@code Flowable} instance with the specified concatenation behavior
1861 * @throws NullPointerException if {@code sources} is {@code null}
1862 * @throws IllegalArgumentException if {@code maxConcurrency} or {@code prefetch} is non-positive
1863 * @since 3.0.0
1864 */
1865 @CheckReturnValue
1866 @NonNull
1867 @BackpressureSupport(BackpressureKind.FULL)
1868 @SchedulerSupport(SchedulerSupport.NONE)
1869 @SuppressWarnings({ "rawtypes", "unchecked" })
1870 public static <@NonNull T> Flowable<T> concatEagerDelayError(@NonNull Iterable<@NonNull ? extends Publisher<? extends T>> sources, int maxConcurrency, int prefetch) {
1871 Objects.requireNonNull(sources, "sources is null");
1872 ObjectHelper.verifyPositive(maxConcurrency, "maxConcurrency");
1873 ObjectHelper.verifyPositive(prefetch, "prefetch");
1874 return RxJavaPlugins.onAssembly(new FlowableConcatMapEager(new FlowableFromIterable(sources), Functions.identity(), maxConcurrency, prefetch, ErrorMode.END));
1875 }
1876
1877 /**
1878 * Concatenates a {@link Publisher} sequence of {@code Publisher}s eagerly into a single stream of values,
1879 * delaying errors until all the inner and the outer sequences terminate.
1880 * <p>
1881 * <img width="640" height="496" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Flowable.concatEagerDelayError.p.png" alt="">
1882 * <p>
1883 * Eager concatenation means that once a subscriber subscribes, this operator subscribes to all of the
1884 * emitted source {@code Publisher}s as they are observed. The operator buffers the values emitted by these
1885 * {@code Publisher}s and then drains them in order, each one after the previous one completes.
1886 * <dl>
1887 * <dt><b>Backpressure:</b></dt>
1888 * <dd>Backpressure is honored towards the downstream and both the outer and inner {@code Publisher}s are
1889 * expected to support backpressure. Violating this assumption, the operator will
1890 * signal {@link MissingBackpressureException}.</dd>
1891 * <dt><b>Scheduler:</b></dt>
1892 * <dd>This method does not operate by default on a particular {@link Scheduler}.</dd>
1893 * </dl>
1894 * @param <T> the value type
1895 * @param sources a sequence of {@code Publisher}s that need to be eagerly concatenated
1896 * @return the new {@code Flowable} instance with the specified concatenation behavior
1897 * @throws NullPointerException if {@code sources} is {@code null}
1898 * @since 3.0.0
1899 */
1900 @CheckReturnValue
1901 @BackpressureSupport(BackpressureKind.FULL)
1902 @SchedulerSupport(SchedulerSupport.NONE)
1903 @NonNull
1904 public static <@NonNull T> Flowable<T> concatEagerDelayError(@NonNull Publisher<@NonNull ? extends Publisher<? extends T>> sources) {
1905 return concatEagerDelayError(sources, bufferSize(), bufferSize());
1906 }
1907
1908 /**
1909 * Concatenates a {@link Publisher} sequence of {@code Publisher}s eagerly into a single stream of values,
1910 * delaying errors until all the inner and outer sequences terminate and runs a limited number of inner
1911 * sequences at once.
1912 * <p>
1913 * <img width="640" height="421" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Flowable.concatEagerDelayError.pn.png" alt="">
1914 * <p>
1915 * Eager concatenation means that once a subscriber subscribes, this operator subscribes to all of the
1916 * emitted source {@code Publisher}s as they are observed. The operator buffers the values emitted by these
1917 * {@code Publisher}s and then drains them in order, each one after the previous one completes.
1918 * <dl>
1919 * <dt><b>Backpressure:</b></dt>
1920 * <dd>Backpressure is honored towards the downstream and both the outer and inner {@code Publisher}s are
1921 * expected to support backpressure. Violating this assumption, the operator will
1922 * signal {@link MissingBackpressureException}.</dd>
1923 * <dt><b>Scheduler:</b></dt>
1924 * <dd>This method does not operate by default on a particular {@link Scheduler}.</dd>
1925 * </dl>
1926 * @param <T> the value type
1927 * @param sources a sequence of {@code Publisher}s that need to be eagerly concatenated
1928 * @param maxConcurrency the maximum number of concurrently running inner {@code Publisher}s; {@link Integer#MAX_VALUE}
1929 * is interpreted as all inner {@code Publisher}s can be active at the same time
1930 * @param prefetch the number of elements to prefetch from each inner {@code Publisher} source
1931 * @return the new {@code Flowable} instance with the specified concatenation behavior
1932 * @throws NullPointerException if {@code sources} is {@code null}
1933 * @throws IllegalArgumentException if {@code maxConcurrency} or {@code prefetch} is non-positive
1934 * @since 3.0.0
1935 */
1936 @CheckReturnValue
1937 @NonNull
1938 @BackpressureSupport(BackpressureKind.FULL)
1939 @SchedulerSupport(SchedulerSupport.NONE)
1940 @SuppressWarnings({ "rawtypes", "unchecked" })
1941 public static <@NonNull T> Flowable<T> concatEagerDelayError(@NonNull Publisher<@NonNull ? extends Publisher<? extends T>> sources, int maxConcurrency, int prefetch) {
1942 Objects.requireNonNull(sources, "sources is null");
1943 ObjectHelper.verifyPositive(maxConcurrency, "maxConcurrency");
1944 ObjectHelper.verifyPositive(prefetch, "prefetch");
1945 return RxJavaPlugins.onAssembly(new FlowableConcatMapEagerPublisher(sources, Functions.identity(), maxConcurrency, prefetch, ErrorMode.END));
1946 }
1947
1948 /**
1949 * Provides an API (via a cold {@code Flowable}) that bridges the reactive world with the callback-style,
1950 * generally non-backpressured world.
1951 * <p>
1952 * Example:
1953 * <pre><code>
1954 * Flowable.&lt;Event&gt;create(emitter -&gt; {
1955 * Callback listener = new Callback() {
1956 * &#64;Override
1957 * public void onEvent(Event e) {
1958 * emitter.onNext(e);
1959 * if (e.isLast()) {
1960 * emitter.onComplete();
1961 * }
1962 * }
1963 *
1964 * &#64;Override
1965 * public void onFailure(Exception e) {
1966 * emitter.onError(e);
1967 * }
1968 * };
1969 *
1970 * AutoCloseable c = api.someMethod(listener);
1971 *
1972 * emitter.setCancellable(c::close);
1973 *
1974 * }, BackpressureStrategy.BUFFER);
1975 * </code></pre>
1976 * <p>
1977 * Whenever a {@link Subscriber} subscribes to the returned {@code Flowable}, the provided
1978 * {@link FlowableOnSubscribe} callback is invoked with a fresh instance of a {@link FlowableEmitter}
1979 * that will interact only with that specific {@code Subscriber}. If this {@code Subscriber}
1980 * cancels the flow (making {@link FlowableEmitter#isCancelled} return {@code true}),
1981 * other observers subscribed to the same returned {@code Flowable} are not affected.
1982 * <p>
1983 * You should call the {@link FlowableEmitter#onNext(Object)}, {@link FlowableEmitter#onError(Throwable)}
1984 * and {@link FlowableEmitter#onComplete()} methods in a serialized fashion. The
1985 * rest of its methods are thread-safe.
1986 * <dl>
1987 * <dt><b>Backpressure:</b></dt>
1988 * <dd>The backpressure behavior is determined by the {@code mode} parameter.</dd>
1989 * <dt><b>Scheduler:</b></dt>
1990 * <dd>{@code create} does not operate by default on a particular {@link Scheduler}.</dd>
1991 * </dl>
1992 *
1993 * @param <T> the element type
1994 * @param source the emitter that is called when a {@code Subscriber} subscribes to the returned {@code Flowable}
1995 * @param mode the backpressure mode to apply if the downstream {@code Subscriber} doesn't request (fast) enough
1996 * @return the new {@code Flowable} instance
1997 * @throws NullPointerException if {@code source} or {@code mode} is {@code null}
1998 * @see FlowableOnSubscribe
1999 * @see BackpressureStrategy
2000 * @see Cancellable
2001 */
2002 @CheckReturnValue
2003 @NonNull
2004 @BackpressureSupport(BackpressureKind.SPECIAL)
2005 @SchedulerSupport(SchedulerSupport.NONE)
2006 public static <@NonNull T> Flowable<T> create(@NonNull FlowableOnSubscribe<T> source, @NonNull BackpressureStrategy mode) {
2007 Objects.requireNonNull(source, "source is null");
2008 Objects.requireNonNull(mode, "mode is null");
2009 return RxJavaPlugins.onAssembly(new FlowableCreate<>(source, mode));
2010 }
2011
2012 /**
2013 * Returns a {@code Flowable} that calls a {@link Publisher} factory to create a {@code Publisher} for each new {@link Subscriber}
2014 * that subscribes. That is, for each subscriber, the actual {@code Publisher} that subscriber observes is
2015 * determined by the factory function.
2016 * <p>
2017 * <img width="640" height="340" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/defer.v3.png" alt="">
2018 * <p>
2019 * The defer {@code Subscriber} allows you to defer or delay emitting items from a {@code Publisher} until such time as a
2020 * {@code Subscriber} subscribes to the {@code Publisher}. This allows a {@code Subscriber} to easily obtain updates or a
2021 * refreshed version of the sequence.
2022 * <dl>
2023 * <dt><b>Backpressure:</b></dt>
2024 * <dd>The operator itself doesn't interfere with backpressure which is determined by the {@code Publisher}
2025 * returned by the {@code supplier}.</dd>
2026 * <dt><b>Scheduler:</b></dt>
2027 * <dd>{@code defer} does not operate by default on a particular {@link Scheduler}.</dd>
2028 * </dl>
2029 *
2030 * @param supplier
2031 * the {@code Publisher} factory function to invoke for each {@code Subscriber} that subscribes to the
2032 * resulting {@code Flowable}
2033 * @param <T>
2034 * the type of the items emitted by the {@code Publisher}
2035 * @return the new {@code Flowable} instance
2036 * @throws NullPointerException if {@code supplier} is {@code null}
2037 * @see <a href="http://reactivex.io/documentation/operators/defer.html">ReactiveX operators documentation: Defer</a>
2038 */
2039 @CheckReturnValue
2040 @NonNull
2041 @BackpressureSupport(BackpressureKind.PASS_THROUGH)
2042 @SchedulerSupport(SchedulerSupport.NONE)
2043 public static <@NonNull T> Flowable<T> defer(@NonNull Supplier<? extends @NonNull Publisher<? extends T>> supplier) {
2044 Objects.requireNonNull(supplier, "supplier is null");
2045 return RxJavaPlugins.onAssembly(new FlowableDefer<>(supplier));
2046 }
2047
2048 /**
2049 * Returns a {@code Flowable} that emits no items to the {@link Subscriber} and immediately invokes its
2050 * {@link Subscriber#onComplete onComplete} method.
2051 * <p>
2052 * <img width="640" height="190" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/empty.v3.png" alt="">
2053 * <dl>
2054 * <dt><b>Backpressure:</b></dt>
2055 * <dd>This source doesn't produce any elements and effectively ignores downstream backpressure.</dd>
2056 * <dt><b>Scheduler:</b></dt>
2057 * <dd>{@code empty} does not operate by default on a particular {@link Scheduler}.</dd>
2058 * </dl>
2059 *
2060 * @param <T>
2061 * the type of the items (ostensibly) emitted by the {@link Publisher}
2062 * @return the shared {@code Flowable} instance
2063 * @see <a href="http://reactivex.io/documentation/operators/empty-never-throw.html">ReactiveX operators documentation: Empty</a>
2064 */
2065 @CheckReturnValue
2066 @BackpressureSupport(BackpressureKind.PASS_THROUGH)
2067 @SchedulerSupport(SchedulerSupport.NONE)
2068 @SuppressWarnings("unchecked")
2069 @NonNull
2070 public static <@NonNull T> Flowable<T> empty() {
2071 return RxJavaPlugins.onAssembly((Flowable<T>) FlowableEmpty.INSTANCE);
2072 }
2073
2074 /**
2075 * Returns a {@code Flowable} that invokes a {@link Subscriber}'s {@link Subscriber#onError onError} method when the
2076 * {@code Subscriber} subscribes to it.
2077 * <p>
2078 * <img width="640" height="190" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/error.v3.png" alt="">
2079 * <dl>
2080 * <dt><b>Backpressure:</b></dt>
2081 * <dd>This source doesn't produce any elements and effectively ignores downstream backpressure.</dd>
2082 * <dt><b>Scheduler:</b></dt>
2083 * <dd>{@code error} does not operate by default on a particular {@link Scheduler}.</dd>
2084 * </dl>
2085 *
2086 * @param supplier
2087 * a {@link Supplier} factory to return a {@link Throwable} for each individual {@code Subscriber}
2088 * @param <T>
2089 * the type of the items (ostensibly) emitted by the resulting {@code Flowable}
2090 * @return the new {@code Flowable} instance
2091 * @throws NullPointerException if {@code supplier} is {@code null}
2092 * @see <a href="http://reactivex.io/documentation/operators/empty-never-throw.html">ReactiveX operators documentation: Throw</a>
2093 */
2094 @CheckReturnValue
2095 @NonNull
2096 @BackpressureSupport(BackpressureKind.PASS_THROUGH)
2097 @SchedulerSupport(SchedulerSupport.NONE)
2098 public static <@NonNull T> Flowable<T> error(@NonNull Supplier<? extends @NonNull Throwable> supplier) {
2099 Objects.requireNonNull(supplier, "supplier is null");
2100 return RxJavaPlugins.onAssembly(new FlowableError<>(supplier));
2101 }
2102
2103 /**
2104 * Returns a {@code Flowable} that invokes a {@link Subscriber}'s {@link Subscriber#onError onError} method when the
2105 * {@code Subscriber} subscribes to it.
2106 * <p>
2107 * <img width="640" height="190" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/error.v3.png" alt="">
2108 * <dl>
2109 * <dt><b>Backpressure:</b></dt>
2110 * <dd>This source doesn't produce any elements and effectively ignores downstream backpressure.</dd>
2111 * <dt><b>Scheduler:</b></dt>
2112 * <dd>{@code error} does not operate by default on a particular {@link Scheduler}.</dd>
2113 * </dl>
2114 *
2115 * @param throwable
2116 * the particular {@link Throwable} to pass to {@link Subscriber#onError onError}
2117 * @param <T>
2118 * the type of the items (ostensibly) emitted by the resulting {@code Flowable}
2119 * @return the new {@code Flowable} instance
2120 * @throws NullPointerException if {@code throwable} is {@code null}
2121 * @see <a href="http://reactivex.io/documentation/operators/empty-never-throw.html">ReactiveX operators documentation: Throw</a>
2122 */
2123 @CheckReturnValue
2124 @NonNull
2125 @BackpressureSupport(BackpressureKind.PASS_THROUGH)
2126 @SchedulerSupport(SchedulerSupport.NONE)
2127 public static <@NonNull T> Flowable<T> error(@NonNull Throwable throwable) {
2128 Objects.requireNonNull(throwable, "throwable is null");
2129 return error(Functions.justSupplier(throwable));
2130 }
2131
2132 /**
2133 * Returns a {@code Flowable} instance that runs the given {@link Action} for each {@link Subscriber} and
2134 * emits either its exception or simply completes.
2135 * <p>
2136 * <img width="640" height="285" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Flowable.fromAction.png" alt="">
2137 * <dl>
2138 * <dt><b>Backpressure:</b></dt>
2139 * <dd>This source doesn't produce any elements and effectively ignores downstream backpressure.</dd>
2140 * <dt><b>Scheduler:</b></dt>
2141 * <dd>{@code fromAction} does not operate by default on a particular {@link Scheduler}.</dd>
2142 * <dt><b>Error handling:</b></dt>
2143 * <dd> If the {@code Action} throws an exception, the respective {@link Throwable} is
2144 * delivered to the downstream via {@link Subscriber#onError(Throwable)},
2145 * except when the downstream has canceled the resulting {@code Flowable} source.
2146 * In this latter case, the {@code Throwable} is delivered to the global error handler via
2147 * {@link RxJavaPlugins#onError(Throwable)} as an {@link io.reactivex.rxjava3.exceptions.UndeliverableException UndeliverableException}.
2148 * </dd>
2149 * </dl>
2150 * @param <T> the target type
2151 * @param action the {@code Action} to run for each {@code Subscriber}
2152 * @return the new {@code Flowable} instance
2153 * @throws NullPointerException if {@code action} is {@code null}
2154 * @since 3.0.0
2155 */
2156 @CheckReturnValue
2157 @NonNull
2158 @SchedulerSupport(SchedulerSupport.NONE)
2159 @BackpressureSupport(BackpressureKind.PASS_THROUGH)
2160 public static <@NonNull T> Flowable<T> fromAction(@NonNull Action action) {
2161 Objects.requireNonNull(action, "action is null");
2162 return RxJavaPlugins.onAssembly(new FlowableFromAction<>(action));
2163 }
2164
2165 /**
2166 * Converts an array into a {@link Publisher} that emits the items in the array.
2167 * <p>
2168 * <img width="640" height="315" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/from.v3.png" alt="">
2169 * <dl>
2170 * <dt><b>Backpressure:</b></dt>
2171 * <dd>The operator honors backpressure from downstream and iterates the given {@code array}
2172 * on demand (i.e., when requested).</dd>
2173 * <dt><b>Scheduler:</b></dt>
2174 * <dd>{@code fromArray} does not operate by default on a particular {@link Scheduler}.</dd>
2175 * </dl>
2176 *
2177 * @param items
2178 * the array of elements
2179 * @param <T>
2180 * the type of items in the array and the type of items to be emitted by the resulting {@code Flowable}
2181 * @return the new {@code Flowable} instance
2182 * @throws NullPointerException if {@code items} is {@code null}
2183 * @see <a href="http://reactivex.io/documentation/operators/from.html">ReactiveX operators documentation: From</a>
2184 */
2185 @CheckReturnValue
2186 @NonNull
2187 @BackpressureSupport(BackpressureKind.FULL)
2188 @SchedulerSupport(SchedulerSupport.NONE)
2189 @SafeVarargs
2190 public static <@NonNull T> Flowable<T> fromArray(@NonNull T... items) {
2191 Objects.requireNonNull(items, "items is null");
2192 if (items.length == 0) {
2193 return empty();
2194 }
2195 if (items.length == 1) {
2196 return just(items[0]);
2197 }
2198 return RxJavaPlugins.onAssembly(new FlowableFromArray<>(items));
2199 }
2200
2201 /**
2202 * Returns a {@code Flowable} that, when a {@link Subscriber} subscribes to it, invokes a function you specify and then
2203 * emits the value returned from that function.
2204 * <p>
2205 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/fromCallable.v3.png" alt="">
2206 * <p>
2207 * This allows you to defer the execution of the function you specify until a {@code Subscriber} subscribes to the
2208 * {@link Publisher}. That is to say, it makes the function "lazy."
2209 * <dl>
2210 * <dt><b>Backpressure:</b></dt>
2211 * <dd>The operator honors backpressure from downstream.</dd>
2212 * <dt><b>Scheduler:</b></dt>
2213 * <dd>{@code fromCallable} does not operate by default on a particular {@link Scheduler}.</dd>
2214 * <dt><b>Error handling:</b></dt>
2215 * <dd> If the {@link Callable} throws an exception, the respective {@link Throwable} is
2216 * delivered to the downstream via {@link Subscriber#onError(Throwable)},
2217 * except when the downstream has canceled this {@code Flowable} source.
2218 * In this latter case, the {@code Throwable} is delivered to the global error handler via
2219 * {@link RxJavaPlugins#onError(Throwable)} as an {@link io.reactivex.rxjava3.exceptions.UndeliverableException UndeliverableException}.
2220 * </dd>
2221 * </dl>
2222 *
2223 * @param callable
2224 * a function, the execution of which should be deferred; {@code fromCallable} will invoke this
2225 * function only when a {@code Subscriber} subscribes to the {@code Publisher} that {@code fromCallable} returns
2226 * @param <T>
2227 * the type of the item emitted by the {@code Publisher}
2228 * @return the new {@code Flowable} instance
2229 * @throws NullPointerException if {@code callable} is {@code null}
2230 * @see #defer(Supplier)
2231 * @see #fromSupplier(Supplier)
2232 * @since 2.0
2233 */
2234 @CheckReturnValue
2235 @NonNull
2236 @BackpressureSupport(BackpressureKind.FULL)
2237 @SchedulerSupport(SchedulerSupport.NONE)
2238 public static <@NonNull T> Flowable<T> fromCallable(@NonNull Callable<? extends T> callable) {
2239 Objects.requireNonNull(callable, "callable is null");
2240 return RxJavaPlugins.onAssembly(new FlowableFromCallable<>(callable));
2241 }
2242
2243 /**
2244 * Wraps a {@link CompletableSource} into a {@code Flowable}.
2245 * <p>
2246 * <img width="640" height="278" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Flowable.fromCompletable.png" alt="">
2247 * <dl>
2248 * <dt><b>Backpressure:</b></dt>
2249 * <dd>This source doesn't produce any elements and effectively ignores downstream backpressure.</dd>
2250 * <dt><b>Scheduler:</b></dt>
2251 * <dd>{@code fromCompletable} does not operate by default on a particular {@link Scheduler}.</dd>
2252 * </dl>
2253 * @param <T> the target type
2254 * @param completableSource the {@code CompletableSource} to convert from
2255 * @return the new {@code Flowable} instance
2256 * @throws NullPointerException if {@code completableSource} is {@code null}
2257 */
2258 @CheckReturnValue
2259 @NonNull
2260 @SchedulerSupport(SchedulerSupport.NONE)
2261 @BackpressureSupport(BackpressureKind.PASS_THROUGH)
2262 public static <@NonNull T> Flowable<T> fromCompletable(@NonNull CompletableSource completableSource) {
2263 Objects.requireNonNull(completableSource, "completableSource is null");
2264 return RxJavaPlugins.onAssembly(new FlowableFromCompletable<>(completableSource));
2265 }
2266
2267 /**
2268 * Converts a {@link Future} into a {@link Publisher}.
2269 * <p>
2270 * <img width="640" height="315" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/from.Future.v3.png" alt="">
2271 * <p>
2272 * The operator calls {@link Future#get()}, which is a blocking method, on the subscription thread.
2273 * It is recommended applying {@link #subscribeOn(Scheduler)} to move this blocking wait to a
2274 * background thread, and if the {@link Scheduler} supports it, interrupt the wait when the flow
2275 * is disposed.
2276 * <p>
2277 * Also note that this operator will consume a {@link CompletionStage}-based {@code Future} subclass (such as
2278 * {@link CompletableFuture}) in a blocking manner as well. Use the {@link #fromCompletionStage(CompletionStage)}
2279 * operator to convert and consume such sources in a non-blocking fashion instead.
2280 * <p>
2281 * Unlike 1.x, canceling the {@code Flowable} won't cancel the future. If necessary, one can use composition to achieve the
2282 * cancellation effect: {@code futurePublisher.doOnCancel(() -> future.cancel(true));}.
2283 * <dl>
2284 * <dt><b>Backpressure:</b></dt>
2285 * <dd>The operator honors backpressure from downstream.</dd>
2286 * <dt><b>Scheduler:</b></dt>
2287 * <dd>{@code fromFuture} does not operate by default on a particular {@code Scheduler}.</dd>
2288 * </dl>
2289 *
2290 * @param future
2291 * the source {@code Future}
2292 * @param <T>
2293 * the type of object that the {@code Future} returns, and also the type of item to be emitted by
2294 * the resulting {@code Flowable}
2295 * @return the new {@code Flowable} instance
2296 * @throws NullPointerException if {@code future} is {@code null}
2297 * @see <a href="http://reactivex.io/documentation/operators/from.html">ReactiveX operators documentation: From</a>
2298 * @see #fromCompletionStage(CompletionStage)
2299 */
2300 @CheckReturnValue
2301 @NonNull
2302 @BackpressureSupport(BackpressureKind.FULL)
2303 @SchedulerSupport(SchedulerSupport.NONE)
2304 public static <@NonNull T> Flowable<T> fromFuture(@NonNull Future<? extends T> future) {
2305 Objects.requireNonNull(future, "future is null");
2306 return RxJavaPlugins.onAssembly(new FlowableFromFuture<>(future, 0L, null));
2307 }
2308
2309 /**
2310 * Converts a {@link Future} into a {@link Publisher}, with a timeout on the {@code Future}.
2311 * <p>
2312 * <img width="640" height="315" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/from.Future.v3.png" alt="">
2313 * <p>
2314 * The operator calls {@link Future#get(long, TimeUnit)}, which is a blocking method, on the subscription thread.
2315 * It is recommended applying {@link #subscribeOn(Scheduler)} to move this blocking wait to a
2316 * background thread, and if the {@link Scheduler} supports it, interrupt the wait when the flow
2317 * is disposed.
2318 * <p>
2319 * Unlike 1.x, canceling the {@code Flowable} won't cancel the future. If necessary, one can use composition to achieve the
2320 * cancellation effect: {@code futurePublisher.doOnCancel(() -> future.cancel(true));}.
2321 * <p>
2322 * Also note that this operator will consume a {@link CompletionStage}-based {@code Future} subclass (such as
2323 * {@link CompletableFuture}) in a blocking manner as well. Use the {@link #fromCompletionStage(CompletionStage)}
2324 * operator to convert and consume such sources in a non-blocking fashion instead.
2325 * <dl>
2326 * <dt><b>Backpressure:</b></dt>
2327 * <dd>The operator honors backpressure from downstream.</dd>
2328 * <dt><b>Scheduler:</b></dt>
2329 * <dd>{@code fromFuture} does not operate by default on a particular {@code Scheduler}.</dd>
2330 * </dl>
2331 *
2332 * @param future
2333 * the source {@code Future}
2334 * @param timeout
2335 * the maximum time to wait before calling {@code get}
2336 * @param unit
2337 * the {@link TimeUnit} of the {@code timeout} argument
2338 * @param <T>
2339 * the type of object that the {@code Future} returns, and also the type of item to be emitted by
2340 * the resulting {@code Flowable}
2341 * @return the new {@code Flowable} instance
2342 * @throws NullPointerException if {@code future} or {@code unit} is {@code null}
2343 * @see <a href="http://reactivex.io/documentation/operators/from.html">ReactiveX operators documentation: From</a>
2344 * @see #fromCompletionStage(CompletionStage)
2345 */
2346 @CheckReturnValue
2347 @NonNull
2348 @BackpressureSupport(BackpressureKind.FULL)
2349 @SchedulerSupport(SchedulerSupport.NONE)
2350 public static <@NonNull T> Flowable<T> fromFuture(@NonNull Future<? extends T> future, long timeout, @NonNull TimeUnit unit) {
2351 Objects.requireNonNull(future, "future is null");
2352 Objects.requireNonNull(unit, "unit is null");
2353 return RxJavaPlugins.onAssembly(new FlowableFromFuture<>(future, timeout, unit));
2354 }
2355
2356 /**
2357 * Converts an {@link Iterable} sequence into a {@link Publisher} that emits the items in the sequence.
2358 * <p>
2359 * <img width="640" height="315" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/from.v3.png" alt="">
2360 * <dl>
2361 * <dt><b>Backpressure:</b></dt>
2362 * <dd>The operator honors backpressure from downstream and iterates the given {@code iterable}
2363 * on demand (i.e., when requested).</dd>
2364 * <dt><b>Scheduler:</b></dt>
2365 * <dd>{@code fromIterable} does not operate by default on a particular {@link Scheduler}.</dd>
2366 * </dl>
2367 *
2368 * @param source
2369 * the source {@code Iterable} sequence
2370 * @param <T>
2371 * the type of items in the {@code Iterable} sequence and the type of items to be emitted by the
2372 * resulting {@code Flowable}
2373 * @return the new {@code Flowable} instance
2374 * @throws NullPointerException if {@code source} is {@code null}
2375 * @see <a href="http://reactivex.io/documentation/operators/from.html">ReactiveX operators documentation: From</a>
2376 * @see #fromStream(Stream)
2377 */
2378 @CheckReturnValue
2379 @NonNull
2380 @BackpressureSupport(BackpressureKind.FULL)
2381 @SchedulerSupport(SchedulerSupport.NONE)
2382 public static <@NonNull T> Flowable<T> fromIterable(@NonNull Iterable<? extends T> source) {
2383 Objects.requireNonNull(source, "source is null");
2384 return RxJavaPlugins.onAssembly(new FlowableFromIterable<>(source));
2385 }
2386
2387 /**
2388 * Returns a {@code Flowable} instance that when subscribed to, subscribes to the {@link MaybeSource} instance and
2389 * emits {@code onSuccess} as a single item or forwards any {@code onComplete} or
2390 * {@code onError} signal.
2391 * <p>
2392 * <img width="640" height="226" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Flowable.fromMaybe.png" alt="">
2393 * <dl>
2394 * <dt><b>Backpressure:</b></dt>
2395 * <dd>The operator honors backpressure from downstream.</dd>
2396 * <dt><b>Scheduler:</b></dt>
2397 * <dd>{@code fromMaybe} does not operate by default on a particular {@link Scheduler}.</dd>
2398 * </dl>
2399 * @param <T> the value type of the {@code MaybeSource} element
2400 * @param maybe the {@code MaybeSource} instance to subscribe to, not {@code null}
2401 * @return the new {@code Flowable} instance
2402 * @throws NullPointerException if {@code maybe} is {@code null}
2403 * @since 3.0.0
2404 */
2405 @CheckReturnValue
2406 @NonNull
2407 @SchedulerSupport(SchedulerSupport.NONE)
2408 @BackpressureSupport(BackpressureKind.FULL)
2409 public static <@NonNull T> Flowable<T> fromMaybe(@NonNull MaybeSource<T> maybe) {
2410 Objects.requireNonNull(maybe, "maybe is null");
2411 return RxJavaPlugins.onAssembly(new MaybeToFlowable<>(maybe));
2412 }
2413
2414 /**
2415 * Converts the given {@link ObservableSource} into a {@code Flowable} by applying the specified backpressure strategy.
2416 * <p>
2417 * Marble diagrams for the various backpressure strategies are as follows:
2418 * <ul>
2419 * <li>{@link BackpressureStrategy#BUFFER}
2420 * <p>
2421 * <img width="640" height="264" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Flowable.fromObservable.buffer.png" alt="">
2422 * </li>
2423 * <li>{@link BackpressureStrategy#DROP}
2424 * <p>
2425 * <img width="640" height="374" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Flowable.fromObservable.drop.png" alt="">
2426 * </li>
2427 * <li>{@link BackpressureStrategy#LATEST}
2428 * <p>
2429 * <img width="640" height="284" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Flowable.fromObservable.latest.png" alt="">
2430 * </li>
2431 * <li>{@link BackpressureStrategy#ERROR}
2432 * <p>
2433 * <img width="640" height="365" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Flowable.fromObservable.error.png" alt="">
2434 * </li>
2435 * <li>{@link BackpressureStrategy#MISSING}
2436 * <p>
2437 * <img width="640" height="397" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Flowable.fromObservable.missing.png" alt="">
2438 * </li>
2439 * </ul>
2440 * <dl>
2441 * <dt><b>Backpressure:</b></dt>
2442 * <dd>The operator applies the chosen backpressure strategy of {@link BackpressureStrategy} enum.</dd>
2443 * <dt><b>Scheduler:</b></dt>
2444 * <dd>{@code fromObservable} does not operate by default on a particular {@link Scheduler}.</dd>
2445 * </dl>
2446 *
2447 * @param <T> the element type of the source and resulting sequence
2448 * @param source the {@code ObservableSource} to convert
2449 * @param strategy the backpressure strategy to apply
2450 * @return the new {@code Flowable} instance
2451 * @throws NullPointerException if {@code source} or {@code strategy} is {@code null}
2452 */
2453 @BackpressureSupport(BackpressureKind.SPECIAL)
2454 @CheckReturnValue
2455 @SchedulerSupport(SchedulerSupport.NONE)
2456 @NonNull
2457 public static <@NonNull T> Flowable<T> fromObservable(@NonNull ObservableSource<T> source, @NonNull BackpressureStrategy strategy) {
2458 Objects.requireNonNull(source, "source is null");
2459 Objects.requireNonNull(strategy, "strategy is null");
2460 Flowable<T> f = new FlowableFromObservable<>(source);
2461 switch (strategy) {
2462 case DROP:
2463 return f.onBackpressureDrop();
2464 case LATEST:
2465 return f.onBackpressureLatest();
2466 case MISSING:
2467 return f;
2468 case ERROR:
2469 return RxJavaPlugins.onAssembly(new FlowableOnBackpressureError<>(f));
2470 default:
2471 return f.onBackpressureBuffer();
2472 }
2473 }
2474
2475 /**
2476 * Converts an arbitrary <em>Reactive Streams</em> {@link Publisher} into a {@code Flowable} if not already a
2477 * {@code Flowable}.
2478 * <p>
2479 * The {@code Publisher} must follow the
2480 * <a href="https://github.com/reactive-streams/reactive-streams-jvm#reactive-streams">Reactive-Streams specification</a>.
2481 * Violating the specification may result in undefined behavior.
2482 * <p>
2483 * If possible, use {@link #create(FlowableOnSubscribe, BackpressureStrategy)} to create a
2484 * source-like {@code Flowable} instead.
2485 * <p>
2486 * Note that even though {@code Publisher} appears to be a functional interface, it
2487 * is not recommended to implement it through a lambda as the specification requires
2488 * state management that is not achievable with a stateless lambda.
2489 * <dl>
2490 * <dt><b>Backpressure:</b></dt>
2491 * <dd>The operator is a pass-through for backpressure and its behavior is determined by the
2492 * backpressure behavior of the wrapped publisher.</dd>
2493 * <dt><b>Scheduler:</b></dt>
2494 * <dd>{@code fromPublisher} does not operate by default on a particular {@link Scheduler}.</dd>
2495 * </dl>
2496 * @param <T> the value type of the flow
2497 * @param publisher the {@code Publisher} to convert
2498 * @return the new {@code Flowable} instance
2499 * @throws NullPointerException if {@code publisher} is {@code null}
2500 * @see #create(FlowableOnSubscribe, BackpressureStrategy)
2501 */
2502 @CheckReturnValue
2503 @NonNull
2504 @BackpressureSupport(BackpressureKind.PASS_THROUGH)
2505 @SchedulerSupport(SchedulerSupport.NONE)
2506 @SuppressWarnings("unchecked")
2507 public static <@NonNull T> Flowable<T> fromPublisher(@NonNull Publisher<? extends T> publisher) {
2508 if (publisher instanceof Flowable) {
2509 return RxJavaPlugins.onAssembly((Flowable<T>)publisher);
2510 }
2511 Objects.requireNonNull(publisher, "publisher is null");
2512
2513 return RxJavaPlugins.onAssembly(new FlowableFromPublisher<>(publisher));
2514 }
2515
2516 /**
2517 * Returns a {@code Flowable} instance that runs the given {@link Runnable} for each {@link Subscriber} and
2518 * emits either its unchecked exception or simply completes.
2519 * <p>
2520 * <img width="640" height="286" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Flowable.fromRunnable.png" alt="">
2521 * <p>
2522 * If the code to be wrapped needs to throw a checked or more broader {@link Throwable} exception, that
2523 * exception has to be converted to an unchecked exception by the wrapped code itself. Alternatively,
2524 * use the {@link #fromAction(Action)} method which allows the wrapped code to throw any {@code Throwable}
2525 * exception and will signal it to observers as-is.
2526 * <dl>
2527 * <dt><b>Backpressure:</b></dt>
2528 * <dd>This source doesn't produce any elements and effectively ignores downstream backpressure.</dd>
2529 * <dt><b>Scheduler:</b></dt>
2530 * <dd>{@code fromRunnable} does not operate by default on a particular {@link Scheduler}.</dd>
2531 * <dt><b>Error handling:</b></dt>
2532 * <dd> If the {@code Runnable} throws an exception, the respective {@code Throwable} is
2533 * delivered to the downstream via {@link Subscriber#onError(Throwable)},
2534 * except when the downstream has canceled the resulting {@code Flowable} source.
2535 * In this latter case, the {@code Throwable} is delivered to the global error handler via
2536 * {@link RxJavaPlugins#onError(Throwable)} as an {@link io.reactivex.rxjava3.exceptions.UndeliverableException UndeliverableException}.
2537 * </dd>
2538 * </dl>
2539 * @param <T> the target type
2540 * @param run the {@code Runnable} to run for each {@code Subscriber}
2541 * @return the new {@code Flowable} instance
2542 * @throws NullPointerException if {@code run} is {@code null}
2543 * @since 3.0.0
2544 * @see #fromAction(Action)
2545 */
2546 @CheckReturnValue
2547 @NonNull
2548 @SchedulerSupport(SchedulerSupport.NONE)
2549 @BackpressureSupport(BackpressureKind.PASS_THROUGH)
2550 public static <@NonNull T> Flowable<T> fromRunnable(@NonNull Runnable run) {
2551 Objects.requireNonNull(run, "run is null");
2552 return RxJavaPlugins.onAssembly(new FlowableFromRunnable<>(run));
2553 }
2554
2555 /**
2556 * Returns a {@code Flowable} instance that when subscribed to, subscribes to the {@link SingleSource} instance and
2557 * emits {@code onSuccess} as a single item or forwards the {@code onError} signal.
2558 * <p>
2559 * <img width="640" height="341" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Flowable.fromSingle.png" alt="">
2560 * <dl>
2561 * <dt><b>Backpressure:</b></dt>
2562 * <dd>The operator honors backpressure from downstream.</dd>
2563 * <dt><b>Scheduler:</b></dt>
2564 * <dd>{@code fromSingle} does not operate by default on a particular {@link Scheduler}.</dd>
2565 * </dl>
2566 * @param <T> the value type of the {@code SingleSource} element
2567 * @param source the {@code SingleSource} instance to subscribe to, not {@code null}
2568 * @return the new {@code Flowable} instance
2569 * @throws NullPointerException if {@code source} is {@code null}
2570 * @since 3.0.0
2571 */
2572 @CheckReturnValue
2573 @NonNull
2574 @SchedulerSupport(SchedulerSupport.NONE)
2575 @BackpressureSupport(BackpressureKind.FULL)
2576 public static <@NonNull T> Flowable<T> fromSingle(@NonNull SingleSource<T> source) {
2577 Objects.requireNonNull(source, "source is null");
2578 return RxJavaPlugins.onAssembly(new SingleToFlowable<>(source));
2579 }
2580
2581 /**
2582 * Returns a {@code Flowable} that, when a {@link Subscriber} subscribes to it, invokes a supplier function you specify and then
2583 * emits the value returned from that function.
2584 * <p>
2585 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Flowable.fromSupplier.v3.png" alt="">
2586 * <p>
2587 * This allows you to defer the execution of the function you specify until a {@code Subscriber} subscribes to the
2588 * {@link Publisher}. That is to say, it makes the function "lazy."
2589 * <dl>
2590 * <dt><b>Backpressure:</b></dt>
2591 * <dd>The operator honors backpressure from downstream.</dd>
2592 * <dt><b>Scheduler:</b></dt>
2593 * <dd>{@code fromSupplier} does not operate by default on a particular {@link Scheduler}.</dd>
2594 * <dt><b>Error handling:</b></dt>
2595 * <dd> If the {@link Supplier} throws an exception, the respective {@link Throwable} is
2596 * delivered to the downstream via {@link Subscriber#onError(Throwable)},
2597 * except when the downstream has canceled this {@code Flowable} source.
2598 * In this latter case, the {@code Throwable} is delivered to the global error handler via
2599 * {@link RxJavaPlugins#onError(Throwable)} as an {@link io.reactivex.rxjava3.exceptions.UndeliverableException UndeliverableException}.
2600 * </dd>
2601 * </dl>
2602 *
2603 * @param supplier
2604 * a function, the execution of which should be deferred; {@code fromSupplier} will invoke this
2605 * function only when a {@code Subscriber} subscribes to the {@code Publisher} that {@code fromSupplier} returns
2606 * @param <T>
2607 * the type of the item emitted by the {@code Publisher}
2608 * @return the new {@code Flowable} instance
2609 * @throws NullPointerException if {@code supplier} is {@code null}
2610 * @see #defer(Supplier)
2611 * @see #fromCallable(Callable)
2612 * @since 3.0.0
2613 */
2614 @CheckReturnValue
2615 @NonNull
2616 @BackpressureSupport(BackpressureKind.FULL)
2617 @SchedulerSupport(SchedulerSupport.NONE)
2618 public static <@NonNull T> Flowable<T> fromSupplier(@NonNull Supplier<? extends T> supplier) {
2619 Objects.requireNonNull(supplier, "supplier is null");
2620 return RxJavaPlugins.onAssembly(new FlowableFromSupplier<>(supplier));
2621 }
2622
2623 /**
2624 * Returns a cold, synchronous, stateless and backpressure-aware generator of values.
2625 * <p>
2626 * Note that the {@link Emitter#onNext}, {@link Emitter#onError} and
2627 * {@link Emitter#onComplete} methods provided to the function via the {@link Emitter} instance should be called synchronously,
2628 * never concurrently and only while the function body is executing. Calling them from multiple threads
2629 * or outside the function call is not supported and leads to an undefined behavior.
2630 * <dl>
2631 * <dt><b>Backpressure:</b></dt>
2632 * <dd>The operator honors downstream backpressure.</dd>
2633 * <dt><b>Scheduler:</b></dt>
2634 * <dd>{@code generate} does not operate by default on a particular {@link Scheduler}.</dd>
2635 * </dl>
2636 *
2637 * @param <T> the generated value type
2638 * @param generator the {@link Consumer} called whenever a particular downstream {@link Subscriber} has
2639 * requested a value. The callback then should call {@code onNext}, {@code onError} or
2640 * {@code onComplete} to signal a value or a terminal event. Signaling multiple {@code onNext}
2641 * in a call will make the operator signal {@link IllegalStateException}.
2642 * @return the new {@code Flowable} instance
2643 * @throws NullPointerException if {@code generator} is {@code null}
2644 */
2645 @CheckReturnValue
2646 @NonNull
2647 @BackpressureSupport(BackpressureKind.FULL)
2648 @SchedulerSupport(SchedulerSupport.NONE)
2649 public static <@NonNull T> Flowable<T> generate(@NonNull Consumer<@NonNull Emitter<T>> generator) {
2650 Objects.requireNonNull(generator, "generator is null");
2651 return generate(Functions.nullSupplier(),
2652 FlowableInternalHelper.simpleGenerator(generator),
2653 Functions.emptyConsumer());
2654 }
2655
2656 /**
2657 * Returns a cold, synchronous, stateful and backpressure-aware generator of values.
2658 * <p>
2659 * Note that the {@link Emitter#onNext}, {@link Emitter#onError} and
2660 * {@link Emitter#onComplete} methods provided to the function via the {@link Emitter} instance should be called synchronously,
2661 * never concurrently and only while the function body is executing. Calling them from multiple threads
2662 * or outside the function call is not supported and leads to an undefined behavior.
2663 * <dl>
2664 * <dt><b>Backpressure:</b></dt>
2665 * <dd>The operator honors downstream backpressure.</dd>
2666 * <dt><b>Scheduler:</b></dt>
2667 * <dd>{@code generate} does not operate by default on a particular {@link Scheduler}.</dd>
2668 * </dl>
2669 *
2670 * @param <S> the type of the per-{@link Subscriber} state
2671 * @param <T> the generated value type
2672 * @param initialState the {@link Supplier} to generate the initial state for each {@code Subscriber}
2673 * @param generator the {@link Consumer} called with the current state whenever a particular downstream {@code Subscriber} has
2674 * requested a value. The callback then should call {@code onNext}, {@code onError} or
2675 * {@code onComplete} to signal a value or a terminal event. Signaling multiple {@code onNext}
2676 * in a call will make the operator signal {@link IllegalStateException}.
2677 * @return the new {@code Flowable} instance
2678 * @throws NullPointerException if {@code initialState} or {@code generator} is {@code null}
2679 */
2680 @CheckReturnValue
2681 @NonNull
2682 @BackpressureSupport(BackpressureKind.FULL)
2683 @SchedulerSupport(SchedulerSupport.NONE)
2684 public static <@NonNull T, @NonNull S> Flowable<T> generate(@NonNull Supplier<S> initialState, @NonNull BiConsumer<S, Emitter<T>> generator) {
2685 Objects.requireNonNull(generator, "generator is null");
2686 return generate(initialState, FlowableInternalHelper.simpleBiGenerator(generator),
2687 Functions.emptyConsumer());
2688 }
2689
2690 /**
2691 * Returns a cold, synchronous, stateful and backpressure-aware generator of values.
2692 * <p>
2693 * Note that the {@link Emitter#onNext}, {@link Emitter#onError} and
2694 * {@link Emitter#onComplete} methods provided to the function via the {@link Emitter} instance should be called synchronously,
2695 * never concurrently and only while the function body is executing. Calling them from multiple threads
2696 * or outside the function call is not supported and leads to an undefined behavior.
2697 * <dl>
2698 * <dt><b>Backpressure:</b></dt>
2699 * <dd>The operator honors downstream backpressure.</dd>
2700 * <dt><b>Scheduler:</b></dt>
2701 * <dd>{@code generate} does not operate by default on a particular {@link Scheduler}.</dd>
2702 * </dl>
2703 *
2704 * @param <S> the type of the per-{@link Subscriber} state
2705 * @param <T> the generated value type
2706 * @param initialState the {@link Supplier} to generate the initial state for each {@code Subscriber}
2707 * @param generator the {@link Consumer} called with the current state whenever a particular downstream {@code Subscriber} has
2708 * requested a value. The callback then should call {@code onNext}, {@code onError} or
2709 * {@code onComplete} to signal a value or a terminal event. Signaling multiple {@code onNext}
2710 * in a call will make the operator signal {@link IllegalStateException}.
2711 * @param disposeState the {@code Consumer} that is called with the current state when the generator
2712 * terminates the sequence or it gets canceled
2713 * @return the new {@code Flowable} instance
2714 * @throws NullPointerException if {@code initialState}, {@code generator} or {@code disposeState} is {@code null}
2715 */
2716 @CheckReturnValue
2717 @NonNull
2718 @BackpressureSupport(BackpressureKind.FULL)
2719 @SchedulerSupport(SchedulerSupport.NONE)
2720 public static <@NonNull T, @NonNull S> Flowable<T> generate(@NonNull Supplier<S> initialState, @NonNull BiConsumer<S, Emitter<T>> generator,
2721 @NonNull Consumer<? super S> disposeState) {
2722 Objects.requireNonNull(generator, "generator is null");
2723 return generate(initialState, FlowableInternalHelper.simpleBiGenerator(generator), disposeState);
2724 }
2725
2726 /**
2727 * Returns a cold, synchronous, stateful and backpressure-aware generator of values.
2728 * <p>
2729 * Note that the {@link Emitter#onNext}, {@link Emitter#onError} and
2730 * {@link Emitter#onComplete} methods provided to the function via the {@link Emitter} instance should be called synchronously,
2731 * never concurrently and only while the function body is executing. Calling them from multiple threads
2732 * or outside the function call is not supported and leads to an undefined behavior.
2733 * <dl>
2734 * <dt><b>Backpressure:</b></dt>
2735 * <dd>The operator honors downstream backpressure.</dd>
2736 * <dt><b>Scheduler:</b></dt>
2737 * <dd>{@code generate} does not operate by default on a particular {@link Scheduler}.</dd>
2738 * </dl>
2739 *
2740 * @param <S> the type of the per-{@link Subscriber} state
2741 * @param <T> the generated value type
2742 * @param initialState the {@link Supplier} to generate the initial state for each {@code Subscriber}
2743 * @param generator the {@link Function} called with the current state whenever a particular downstream {@code Subscriber} has
2744 * requested a value. The callback then should call {@code onNext}, {@code onError} or
2745 * {@code onComplete} to signal a value or a terminal event and should return a (new) state for
2746 * the next invocation. Signaling multiple {@code onNext}
2747 * in a call will make the operator signal {@link IllegalStateException}.
2748 * @return the new {@code Flowable} instance
2749 * @throws NullPointerException if {@code initialState} or {@code generator} is {@code null}
2750 */
2751 @CheckReturnValue
2752 @BackpressureSupport(BackpressureKind.FULL)
2753 @SchedulerSupport(SchedulerSupport.NONE)
2754 @NonNull
2755 public static <@NonNull T, @NonNull S> Flowable<T> generate(@NonNull Supplier<S> initialState, @NonNull BiFunction<S, @NonNull Emitter<T>, S> generator) {
2756 return generate(initialState, generator, Functions.emptyConsumer());
2757 }
2758
2759 /**
2760 * Returns a cold, synchronous, stateful and backpressure-aware generator of values.
2761 * <p>
2762 * Note that the {@link Emitter#onNext}, {@link Emitter#onError} and
2763 * {@link Emitter#onComplete} methods provided to the function via the {@link Emitter} instance should be called synchronously,
2764 * never concurrently and only while the function body is executing. Calling them from multiple threads
2765 * or outside the function call is not supported and leads to an undefined behavior.
2766 * <dl>
2767 * <dt><b>Backpressure:</b></dt>
2768 * <dd>The operator honors downstream backpressure.</dd>
2769 * <dt><b>Scheduler:</b></dt>
2770 * <dd>{@code generate} does not operate by default on a particular {@link Scheduler}.</dd>
2771 * </dl>
2772 *
2773 * @param <S> the type of the per-{@link Subscriber} state
2774 * @param <T> the generated value type
2775 * @param initialState the {@link Supplier} to generate the initial state for each {@code Subscriber}
2776 * @param generator the {@link Function} called with the current state whenever a particular downstream {@code Subscriber} has
2777 * requested a value. The callback then should call {@code onNext}, {@code onError} or
2778 * {@code onComplete} to signal a value or a terminal event and should return a (new) state for
2779 * the next invocation. Signaling multiple {@code onNext}
2780 * in a call will make the operator signal {@link IllegalStateException}.
2781 * @param disposeState the {@link Consumer} that is called with the current state when the generator
2782 * terminates the sequence or it gets canceled
2783 * @return the new {@code Flowable} instance
2784 * @throws NullPointerException if {@code initialState}, {@code generator} or {@code disposeState} is {@code null}
2785 */
2786 @CheckReturnValue
2787 @NonNull
2788 @BackpressureSupport(BackpressureKind.FULL)
2789 @SchedulerSupport(SchedulerSupport.NONE)
2790 public static <@NonNull T, @NonNull S> Flowable<T> generate(@NonNull Supplier<S> initialState, @NonNull BiFunction<S, @NonNull Emitter<T>, S> generator, @NonNull Consumer<? super S> disposeState) {
2791 Objects.requireNonNull(initialState, "initialState is null");
2792 Objects.requireNonNull(generator, "generator is null");
2793 Objects.requireNonNull(disposeState, "disposeState is null");
2794 return RxJavaPlugins.onAssembly(new FlowableGenerate<>(initialState, generator, disposeState));
2795 }
2796
2797 /**
2798 * Returns a {@code Flowable} that emits a {@code 0L} after the {@code initialDelay} and ever-increasing numbers
2799 * after each {@code period} of time thereafter.
2800 * <p>
2801 * <img width="640" height="200" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/timer.p.v3.png" alt="">
2802 * <dl>
2803 * <dt><b>Backpressure:</b></dt>
2804 * <dd>The operator generates values based on time and ignores downstream backpressure which
2805 * may lead to {@link MissingBackpressureException} at some point in the chain.
2806 * Downstream consumers should consider applying one of the {@code onBackpressureXXX} operators as well.</dd>
2807 * <dt><b>Scheduler:</b></dt>
2808 * <dd>{@code interval} operates by default on the {@code computation} {@link Scheduler}.</dd>
2809 * </dl>
2810 *
2811 * @param initialDelay
2812 * the initial delay time to wait before emitting the first value of 0L
2813 * @param period
2814 * the period of time between emissions of the subsequent numbers
2815 * @param unit
2816 * the time unit for both {@code initialDelay} and {@code period}
2817 * @return the new {@code Flowable} instance
2818 * @throws NullPointerException if {@code unit} is {@code null}
2819 * @see <a href="http://reactivex.io/documentation/operators/interval.html">ReactiveX operators documentation: Interval</a>
2820 * @since 1.0.12
2821 */
2822 @CheckReturnValue
2823 @BackpressureSupport(BackpressureKind.ERROR)
2824 @SchedulerSupport(SchedulerSupport.COMPUTATION)
2825 @NonNull
2826 public static Flowable<Long> interval(long initialDelay, long period, @NonNull TimeUnit unit) {
2827 return interval(initialDelay, period, unit, Schedulers.computation());
2828 }
2829
2830 /**
2831 * Returns a {@code Flowable} that emits a {@code 0L} after the {@code initialDelay} and ever-increasing numbers
2832 * after each {@code period} of time thereafter, on a specified {@link Scheduler}.
2833 * <p>
2834 * <img width="640" height="200" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/timer.ps.v3.png" alt="">
2835 * <dl>
2836 * <dt><b>Backpressure:</b></dt>
2837 * <dd>The operator generates values based on time and ignores downstream backpressure which
2838 * may lead to {@link MissingBackpressureException} at some point in the chain.
2839 * Downstream consumers should consider applying one of the {@code onBackpressureXXX} operators as well.</dd>
2840 * <dt><b>Scheduler:</b></dt>
2841 * <dd>You specify which {@code Scheduler} this operator will use.</dd>
2842 * </dl>
2843 *
2844 * @param initialDelay
2845 * the initial delay time to wait before emitting the first value of 0L
2846 * @param period
2847 * the period of time between emissions of the subsequent numbers
2848 * @param unit
2849 * the time unit for both {@code initialDelay} and {@code period}
2850 * @param scheduler
2851 * the {@code Scheduler} on which the waiting happens and items are emitted
2852 * @return the new {@code Flowable} instance
2853 * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null}
2854 * @see <a href="http://reactivex.io/documentation/operators/interval.html">ReactiveX operators documentation: Interval</a>
2855 * @since 1.0.12
2856 */
2857 @CheckReturnValue
2858 @NonNull
2859 @BackpressureSupport(BackpressureKind.ERROR)
2860 @SchedulerSupport(SchedulerSupport.CUSTOM)
2861 public static Flowable<Long> interval(long initialDelay, long period, @NonNull TimeUnit unit, @NonNull Scheduler scheduler) {
2862 Objects.requireNonNull(unit, "unit is null");
2863 Objects.requireNonNull(scheduler, "scheduler is null");
2864 return RxJavaPlugins.onAssembly(new FlowableInterval(Math.max(0L, initialDelay), Math.max(0L, period), unit, scheduler));
2865 }
2866
2867 /**
2868 * Returns a {@code Flowable} that emits a sequential number every specified interval of time.
2869 * <p>
2870 * <img width="640" height="195" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/interval.v3.png" alt="">
2871 * <dl>
2872 * <dt><b>Backpressure:</b></dt>
2873 * <dd>The operator signals a {@link MissingBackpressureException} if the downstream
2874 * is not ready to receive the next value.</dd>
2875 * <dt><b>Scheduler:</b></dt>
2876 * <dd>{@code interval} operates by default on the {@code computation} {@link Scheduler}.</dd>
2877 * </dl>
2878 *
2879 * @param period
2880 * the period size in time units (see below)
2881 * @param unit
2882 * time units to use for the interval size
2883 * @return the new {@code Flowable} instance
2884 * @throws NullPointerException if {@code unit} is {@code null}
2885 * @see <a href="http://reactivex.io/documentation/operators/interval.html">ReactiveX operators documentation: Interval</a>
2886 */
2887 @CheckReturnValue
2888 @BackpressureSupport(BackpressureKind.ERROR)
2889 @SchedulerSupport(SchedulerSupport.COMPUTATION)
2890 @NonNull
2891 public static Flowable<Long> interval(long period, @NonNull TimeUnit unit) {
2892 return interval(period, period, unit, Schedulers.computation());
2893 }
2894
2895 /**
2896 * Returns a {@code Flowable} that emits a sequential number every specified interval of time, on a
2897 * specified {@link Scheduler}.
2898 * <p>
2899 * <img width="640" height="200" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/interval.s.v3.png" alt="">
2900 * <dl>
2901 * <dt><b>Backpressure:</b></dt>
2902 * <dd>The operator generates values based on time and ignores downstream backpressure which
2903 * may lead to {@link MissingBackpressureException} at some point in the chain.
2904 * Downstream consumers should consider applying one of the {@code onBackpressureXXX} operators as well.</dd>
2905 * <dt><b>Scheduler:</b></dt>
2906 * <dd>You specify which {@code Scheduler} this operator will use.</dd>
2907 * </dl>
2908 *
2909 * @param period
2910 * the period size in time units (see below)
2911 * @param unit
2912 * time units to use for the interval size
2913 * @param scheduler
2914 * the {@code Scheduler} to use for scheduling the items
2915 * @return the new {@code Flowable} instance
2916 * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null}
2917 * @see <a href="http://reactivex.io/documentation/operators/interval.html">ReactiveX operators documentation: Interval</a>
2918 */
2919 @CheckReturnValue
2920 @BackpressureSupport(BackpressureKind.ERROR)
2921 @SchedulerSupport(SchedulerSupport.CUSTOM)
2922 @NonNull
2923 public static Flowable<Long> interval(long period, @NonNull TimeUnit unit, @NonNull Scheduler scheduler) {
2924 return interval(period, period, unit, scheduler);
2925 }
2926
2927 /**
2928 * Signals a range of long values, the first after some initial delay and the rest periodically after.
2929 * <p>
2930 * The sequence completes immediately after the last value {@code (start + count - 1)} has been reached.
2931 * <dl>
2932 * <dt><b>Backpressure:</b></dt>
2933 * <dd>The operator signals a {@link MissingBackpressureException} if the downstream can't keep up.</dd>
2934 * <dt><b>Scheduler:</b></dt>
2935 * <dd>{@code intervalRange} by default operates on the {@link Schedulers#computation() computation} {@link Scheduler}.</dd>
2936 * </dl>
2937 * @param start that start value of the range
2938 * @param count the number of values to emit in total, if zero, the operator emits an {@code onComplete} after the initial delay.
2939 * @param initialDelay the initial delay before signaling the first value (the start)
2940 * @param period the period between subsequent values
2941 * @param unit the unit of measure of the {@code initialDelay} and {@code period} amounts
2942 * @return the new {@code Flowable} instance
2943 * @throws NullPointerException if {@code unit} is {@code null}
2944 * @throws IllegalArgumentException
2945 * if {@code count} is less than zero, or if {@code start} + {@code count} &minus; 1 exceeds
2946 * {@link Long#MAX_VALUE}
2947 * @see #range(int, int)
2948 */
2949 @CheckReturnValue
2950 @NonNull
2951 @BackpressureSupport(BackpressureKind.ERROR)
2952 @SchedulerSupport(SchedulerSupport.COMPUTATION)
2953 public static Flowable<Long> intervalRange(long start, long count, long initialDelay, long period, @NonNull TimeUnit unit) {
2954 return intervalRange(start, count, initialDelay, period, unit, Schedulers.computation());
2955 }
2956
2957 /**
2958 * Signals a range of long values, the first after some initial delay and the rest periodically after.
2959 * <p>
2960 * The sequence completes immediately after the last value (start + count - 1) has been reached.
2961 * <dl>
2962 * <dt><b>Backpressure:</b></dt>
2963 * <dd>The operator signals a {@link MissingBackpressureException} if the downstream can't keep up.</dd>
2964 * <dt><b>Scheduler:</b></dt>
2965 * <dd>you provide the {@link Scheduler}.</dd>
2966 * </dl>
2967 * @param start that start value of the range
2968 * @param count the number of values to emit in total, if zero, the operator emits an {@code onComplete} after the initial delay.
2969 * @param initialDelay the initial delay before signaling the first value (the start)
2970 * @param period the period between subsequent values
2971 * @param unit the unit of measure of the {@code initialDelay} and {@code period} amounts
2972 * @param scheduler the target {@code Scheduler} where the values and terminal signals will be emitted
2973 * @return the new {@code Flowable} instance
2974 * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null}
2975 * @throws IllegalArgumentException
2976 * if {@code count} is less than zero, or if {@code start} + {@code count} &minus; 1 exceeds
2977 * {@link Long#MAX_VALUE}
2978 */
2979 @CheckReturnValue
2980 @NonNull
2981 @BackpressureSupport(BackpressureKind.ERROR)
2982 @SchedulerSupport(SchedulerSupport.CUSTOM)
2983 public static Flowable<Long> intervalRange(long start, long count, long initialDelay, long period, @NonNull TimeUnit unit, @NonNull Scheduler scheduler) {
2984 if (count < 0L) {
2985 throw new IllegalArgumentException("count >= 0 required but it was " + count);
2986 }
2987 if (count == 0L) {
2988 return Flowable.<Long>empty().delay(initialDelay, unit, scheduler);
2989 }
2990
2991 long end = start + (count - 1);
2992 if (start > 0 && end < 0) {
2993 throw new IllegalArgumentException("Overflow! start + count is bigger than Long.MAX_VALUE");
2994 }
2995 Objects.requireNonNull(unit, "unit is null");
2996 Objects.requireNonNull(scheduler, "scheduler is null");
2997
2998 return RxJavaPlugins.onAssembly(new FlowableIntervalRange(start, end, Math.max(0L, initialDelay), Math.max(0L, period), unit, scheduler));
2999 }
3000
3001 /**
3002 * Returns a {@code Flowable} that signals the given (constant reference) item and then completes.
3003 * <p>
3004 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/just.v3.png" alt="">
3005 * <p>
3006 * Note that the item is taken and re-emitted as is and not computed by any means by {@code just}. Use {@link #fromCallable(Callable)}
3007 * to generate a single item on demand (when {@link Subscriber}s subscribe to it).
3008 * <p>
3009 * See the multi-parameter overloads of {@code just} to emit more than one (constant reference) items one after the other.
3010 * Use {@link #fromArray(Object...)} to emit an arbitrary number of items that are known upfront.
3011 * <p>
3012 * To emit the items of an {@link Iterable} sequence (such as a {@link java.util.List}), use {@link #fromIterable(Iterable)}.
3013 * <dl>
3014 * <dt><b>Backpressure:</b></dt>
3015 * <dd>The operator honors backpressure from downstream.</dd>
3016 * <dt><b>Scheduler:</b></dt>
3017 * <dd>{@code just} does not operate by default on a particular {@link Scheduler}.</dd>
3018 * </dl>
3019 *
3020 * @param item
3021 * the item to emit
3022 * @param <T>
3023 * the type of that item
3024 * @return the new {@code Flowable} instance
3025 * @throws NullPointerException if {@code item} is {@code null}
3026 * @see <a href="http://reactivex.io/documentation/operators/just.html">ReactiveX operators documentation: Just</a>
3027 * @see #just(Object, Object)
3028 * @see #fromCallable(Callable)
3029 * @see #fromArray(Object...)
3030 * @see #fromIterable(Iterable)
3031 */
3032 @CheckReturnValue
3033 @NonNull
3034 @BackpressureSupport(BackpressureKind.FULL)
3035 @SchedulerSupport(SchedulerSupport.NONE)
3036 public static <@NonNull T> Flowable<T> just(T item) {
3037 Objects.requireNonNull(item, "item is null");
3038 return RxJavaPlugins.onAssembly(new FlowableJust<>(item));
3039 }
3040
3041 /**
3042 * Converts two items into a {@link Publisher} that emits those items.
3043 * <p>
3044 * <img width="640" height="315" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/just.m.v3.png" alt="">
3045 * <dl>
3046 * <dt><b>Backpressure:</b></dt>
3047 * <dd>The operator honors backpressure from downstream and signals each value on-demand (i.e., when requested).</dd>
3048 * <dt><b>Scheduler:</b></dt>
3049 * <dd>{@code just} does not operate by default on a particular {@link Scheduler}.</dd>
3050 * </dl>
3051 *
3052 * @param item1
3053 * first item
3054 * @param item2
3055 * second item
3056 * @param <T>
3057 * the type of these items
3058 * @return the new {@code Flowable} instance
3059 * @throws NullPointerException if {@code item1} or {@code item2} is {@code null}
3060 * @see <a href="http://reactivex.io/documentation/operators/just.html">ReactiveX operators documentation: Just</a>
3061 */
3062 @CheckReturnValue
3063 @NonNull
3064 @BackpressureSupport(BackpressureKind.FULL)
3065 @SchedulerSupport(SchedulerSupport.NONE)
3066 public static <@NonNull T> Flowable<T> just(T item1, T item2) {
3067 Objects.requireNonNull(item1, "item1 is null");
3068 Objects.requireNonNull(item2, "item2 is null");
3069
3070 return fromArray(item1, item2);
3071 }
3072
3073 /**
3074 * Converts three items into a {@link Publisher} that emits those items.
3075 * <p>
3076 * <img width="640" height="315" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/just.m.v3.png" alt="">
3077 * <dl>
3078 * <dt><b>Backpressure:</b></dt>
3079 * <dd>The operator honors backpressure from downstream and signals each value on-demand (i.e., when requested).</dd>
3080 * <dt><b>Scheduler:</b></dt>
3081 * <dd>{@code just} does not operate by default on a particular {@link Scheduler}.</dd>
3082 * </dl>
3083 *
3084 * @param item1
3085 * first item
3086 * @param item2
3087 * second item
3088 * @param item3
3089 * third item
3090 * @param <T>
3091 * the type of these items
3092 * @return the new {@code Flowable} instance
3093 * @throws NullPointerException if {@code item1}, {@code item2} or {@code item3} is {@code null}
3094 * @see <a href="http://reactivex.io/documentation/operators/just.html">ReactiveX operators documentation: Just</a>
3095 */
3096 @CheckReturnValue
3097 @NonNull
3098 @BackpressureSupport(BackpressureKind.FULL)
3099 @SchedulerSupport(SchedulerSupport.NONE)
3100 public static <@NonNull T> Flowable<T> just(T item1, T item2, T item3) {
3101 Objects.requireNonNull(item1, "item1 is null");
3102 Objects.requireNonNull(item2, "item2 is null");
3103 Objects.requireNonNull(item3, "item3 is null");
3104
3105 return fromArray(item1, item2, item3);
3106 }
3107
3108 /**
3109 * Converts four items into a {@link Publisher} that emits those items.
3110 * <p>
3111 * <img width="640" height="315" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/just.m.v3.png" alt="">
3112 * <dl>
3113 * <dt><b>Backpressure:</b></dt>
3114 * <dd>The operator honors backpressure from downstream and signals each value on-demand (i.e., when requested).</dd>
3115 * <dt><b>Scheduler:</b></dt>
3116 * <dd>{@code just} does not operate by default on a particular {@link Scheduler}.</dd>
3117 * </dl>
3118 *
3119 * @param item1
3120 * first item
3121 * @param item2
3122 * second item
3123 * @param item3
3124 * third item
3125 * @param item4
3126 * fourth item
3127 * @param <T>
3128 * the type of these items
3129 * @return the new {@code Flowable} instance
3130 * @throws NullPointerException if {@code item1}, {@code item2}, {@code item3},
3131 * or {@code item4} is {@code null}
3132 * @see <a href="http://reactivex.io/documentation/operators/just.html">ReactiveX operators documentation: Just</a>
3133 */
3134 @CheckReturnValue
3135 @NonNull
3136 @BackpressureSupport(BackpressureKind.FULL)
3137 @SchedulerSupport(SchedulerSupport.NONE)
3138 public static <@NonNull T> Flowable<T> just(T item1, T item2, T item3, T item4) {
3139 Objects.requireNonNull(item1, "item1 is null");
3140 Objects.requireNonNull(item2, "item2 is null");
3141 Objects.requireNonNull(item3, "item3 is null");
3142 Objects.requireNonNull(item4, "item4 is null");
3143
3144 return fromArray(item1, item2, item3, item4);
3145 }
3146
3147 /**
3148 * Converts five items into a {@link Publisher} that emits those items.
3149 * <p>
3150 * <img width="640" height="315" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/just.m.v3.png" alt="">
3151 * <dl>
3152 * <dt><b>Backpressure:</b></dt>
3153 * <dd>The operator honors backpressure from downstream and signals each value on-demand (i.e., when requested).</dd>
3154 * <dt><b>Scheduler:</b></dt>
3155 * <dd>{@code just} does not operate by default on a particular {@link Scheduler}.</dd>
3156 * </dl>
3157 *
3158 * @param item1
3159 * first item
3160 * @param item2
3161 * second item
3162 * @param item3
3163 * third item
3164 * @param item4
3165 * fourth item
3166 * @param item5
3167 * fifth item
3168 * @param <T>
3169 * the type of these items
3170 * @return the new {@code Flowable} instance
3171 * @throws NullPointerException if {@code item1}, {@code item2}, {@code item3},
3172 * {@code item4} or {@code item5} is {@code null}
3173 * @see <a href="http://reactivex.io/documentation/operators/just.html">ReactiveX operators documentation: Just</a>
3174 */
3175 @CheckReturnValue
3176 @NonNull
3177 @BackpressureSupport(BackpressureKind.FULL)
3178 @SchedulerSupport(SchedulerSupport.NONE)
3179 public static <@NonNull T> Flowable<T> just(T item1, T item2, T item3, T item4, T item5) {
3180 Objects.requireNonNull(item1, "item1 is null");
3181 Objects.requireNonNull(item2, "item2 is null");
3182 Objects.requireNonNull(item3, "item3 is null");
3183 Objects.requireNonNull(item4, "item4 is null");
3184 Objects.requireNonNull(item5, "item5 is null");
3185
3186 return fromArray(item1, item2, item3, item4, item5);
3187 }
3188
3189 /**
3190 * Converts six items into a {@link Publisher} that emits those items.
3191 * <p>
3192 * <img width="640" height="315" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/just.m.v3.png" alt="">
3193 * <dl>
3194 * <dt><b>Backpressure:</b></dt>
3195 * <dd>The operator honors backpressure from downstream and signals each value on-demand (i.e., when requested).</dd>
3196 * <dt><b>Scheduler:</b></dt>
3197 * <dd>{@code just} does not operate by default on a particular {@link Scheduler}.</dd>
3198 * </dl>
3199 *
3200 * @param item1
3201 * first item
3202 * @param item2
3203 * second item
3204 * @param item3
3205 * third item
3206 * @param item4
3207 * fourth item
3208 * @param item5
3209 * fifth item
3210 * @param item6
3211 * sixth item
3212 * @param <T>
3213 * the type of these items
3214 * @return the new {@code Flowable} instance
3215 * @throws NullPointerException if {@code item1}, {@code item2}, {@code item3},
3216 * {@code item4}, {@code item5} or {@code item6} is {@code null}
3217 * @see <a href="http://reactivex.io/documentation/operators/just.html">ReactiveX operators documentation: Just</a>
3218 */
3219 @CheckReturnValue
3220 @NonNull
3221 @BackpressureSupport(BackpressureKind.FULL)
3222 @SchedulerSupport(SchedulerSupport.NONE)
3223 public static <@NonNull T> Flowable<T> just(T item1, T item2, T item3, T item4, T item5, T item6) {
3224 Objects.requireNonNull(item1, "item1 is null");
3225 Objects.requireNonNull(item2, "item2 is null");
3226 Objects.requireNonNull(item3, "item3 is null");
3227 Objects.requireNonNull(item4, "item4 is null");
3228 Objects.requireNonNull(item5, "item5 is null");
3229 Objects.requireNonNull(item6, "item6 is null");
3230
3231 return fromArray(item1, item2, item3, item4, item5, item6);
3232 }
3233
3234 /**
3235 * Converts seven items into a {@link Publisher} that emits those items.
3236 * <p>
3237 * <img width="640" height="315" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/just.m.v3.png" alt="">
3238 * <dl>
3239 * <dt><b>Backpressure:</b></dt>
3240 * <dd>The operator honors backpressure from downstream and signals each value on-demand (i.e., when requested).</dd>
3241 * <dt><b>Scheduler:</b></dt>
3242 * <dd>{@code just} does not operate by default on a particular {@link Scheduler}.</dd>
3243 * </dl>
3244 *
3245 * @param item1
3246 * first item
3247 * @param item2
3248 * second item
3249 * @param item3
3250 * third item
3251 * @param item4
3252 * fourth item
3253 * @param item5
3254 * fifth item
3255 * @param item6
3256 * sixth item
3257 * @param item7
3258 * seventh item
3259 * @param <T>
3260 * the type of these items
3261 * @return the new {@code Flowable} instance
3262 * @throws NullPointerException if {@code item1}, {@code item2}, {@code item3},
3263 * {@code item4}, {@code item5}, {@code item6}
3264 * or {@code item7} is {@code null}
3265 * @see <a href="http://reactivex.io/documentation/operators/just.html">ReactiveX operators documentation: Just</a>
3266 */
3267 @CheckReturnValue
3268 @NonNull
3269 @BackpressureSupport(BackpressureKind.FULL)
3270 @SchedulerSupport(SchedulerSupport.NONE)
3271 public static <@NonNull T> Flowable<T> just(T item1, T item2, T item3, T item4, T item5, T item6, T item7) {
3272 Objects.requireNonNull(item1, "item1 is null");
3273 Objects.requireNonNull(item2, "item2 is null");
3274 Objects.requireNonNull(item3, "item3 is null");
3275 Objects.requireNonNull(item4, "item4 is null");
3276 Objects.requireNonNull(item5, "item5 is null");
3277 Objects.requireNonNull(item6, "item6 is null");
3278 Objects.requireNonNull(item7, "item7 is null");
3279
3280 return fromArray(item1, item2, item3, item4, item5, item6, item7);
3281 }
3282
3283 /**
3284 * Converts eight items into a {@link Publisher} that emits those items.
3285 * <p>
3286 * <img width="640" height="315" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/just.m.v3.png" alt="">
3287 * <dl>
3288 * <dt><b>Backpressure:</b></dt>
3289 * <dd>The operator honors backpressure from downstream and signals each value on-demand (i.e., when requested).</dd>
3290 * <dt><b>Scheduler:</b></dt>
3291 * <dd>{@code just} does not operate by default on a particular {@link Scheduler}.</dd>
3292 * </dl>
3293 *
3294 * @param item1
3295 * first item
3296 * @param item2
3297 * second item
3298 * @param item3
3299 * third item
3300 * @param item4
3301 * fourth item
3302 * @param item5
3303 * fifth item
3304 * @param item6
3305 * sixth item
3306 * @param item7
3307 * seventh item
3308 * @param item8
3309 * eighth item
3310 * @param <T>
3311 * the type of these items
3312 * @return the new {@code Flowable} instance
3313 * @throws NullPointerException if {@code item1}, {@code item2}, {@code item3},
3314 * {@code item4}, {@code item5}, {@code item6},
3315 * {@code item7} or {@code item8} is {@code null}
3316 * @see <a href="http://reactivex.io/documentation/operators/just.html">ReactiveX operators documentation: Just</a>
3317 */
3318 @CheckReturnValue
3319 @NonNull
3320 @BackpressureSupport(BackpressureKind.FULL)
3321 @SchedulerSupport(SchedulerSupport.NONE)
3322 public static <@NonNull T> Flowable<T> just(T item1, T item2, T item3, T item4, T item5, T item6, T item7, T item8) {
3323 Objects.requireNonNull(item1, "item1 is null");
3324 Objects.requireNonNull(item2, "item2 is null");
3325 Objects.requireNonNull(item3, "item3 is null");
3326 Objects.requireNonNull(item4, "item4 is null");
3327 Objects.requireNonNull(item5, "item5 is null");
3328 Objects.requireNonNull(item6, "item6 is null");
3329 Objects.requireNonNull(item7, "item7 is null");
3330 Objects.requireNonNull(item8, "item8 is null");
3331
3332 return fromArray(item1, item2, item3, item4, item5, item6, item7, item8);
3333 }
3334
3335 /**
3336 * Converts nine items into a {@link Publisher} that emits those items.
3337 * <p>
3338 * <img width="640" height="315" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/just.m.v3.png" alt="">
3339 * <dl>
3340 * <dt><b>Backpressure:</b></dt>
3341 * <dd>The operator honors backpressure from downstream and signals each value on-demand (i.e., when requested).</dd>
3342 * <dt><b>Scheduler:</b></dt>
3343 * <dd>{@code just} does not operate by default on a particular {@link Scheduler}.</dd>
3344 * </dl>
3345 *
3346 * @param item1
3347 * first item
3348 * @param item2
3349 * second item
3350 * @param item3
3351 * third item
3352 * @param item4
3353 * fourth item
3354 * @param item5
3355 * fifth item
3356 * @param item6
3357 * sixth item
3358 * @param item7
3359 * seventh item
3360 * @param item8
3361 * eighth item
3362 * @param item9
3363 * ninth item
3364 * @param <T>
3365 * the type of these items
3366 * @return the new {@code Flowable} instance
3367 * @throws NullPointerException if {@code item1}, {@code item2}, {@code item3},
3368 * {@code item4}, {@code item5}, {@code item6},
3369 * {@code item7}, {@code item8} or {@code item9} is {@code null}
3370 * @see <a href="http://reactivex.io/documentation/operators/just.html">ReactiveX operators documentation: Just</a>
3371 */
3372 @CheckReturnValue
3373 @NonNull
3374 @BackpressureSupport(BackpressureKind.FULL)
3375 @SchedulerSupport(SchedulerSupport.NONE)
3376 public static <@NonNull T> Flowable<T> just(T item1, T item2, T item3, T item4, T item5, T item6, T item7, T item8, T item9) {
3377 Objects.requireNonNull(item1, "item1 is null");
3378 Objects.requireNonNull(item2, "item2 is null");
3379 Objects.requireNonNull(item3, "item3 is null");
3380 Objects.requireNonNull(item4, "item4 is null");
3381 Objects.requireNonNull(item5, "item5 is null");
3382 Objects.requireNonNull(item6, "item6 is null");
3383 Objects.requireNonNull(item7, "item7 is null");
3384 Objects.requireNonNull(item8, "item8 is null");
3385 Objects.requireNonNull(item9, "item9 is null");
3386
3387 return fromArray(item1, item2, item3, item4, item5, item6, item7, item8, item9);
3388 }
3389
3390 /**
3391 * Converts ten items into a {@link Publisher} that emits those items.
3392 * <p>
3393 * <img width="640" height="315" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/just.m.v3.png" alt="">
3394 * <dl>
3395 * <dt><b>Backpressure:</b></dt>
3396 * <dd>The operator honors backpressure from downstream and signals each value on-demand (i.e., when requested).</dd>
3397 * <dt><b>Scheduler:</b></dt>
3398 * <dd>{@code just} does not operate by default on a particular {@link Scheduler}.</dd>
3399 * </dl>
3400 *
3401 * @param item1
3402 * first item
3403 * @param item2
3404 * second item
3405 * @param item3
3406 * third item
3407 * @param item4
3408 * fourth item
3409 * @param item5
3410 * fifth item
3411 * @param item6
3412 * sixth item
3413 * @param item7
3414 * seventh item
3415 * @param item8
3416 * eighth item
3417 * @param item9
3418 * ninth item
3419 * @param item10
3420 * tenth item
3421 * @param <T>
3422 * the type of these items
3423 * @return the new {@code Flowable} instance
3424 * @throws NullPointerException if {@code item1}, {@code item2}, {@code item3},
3425 * {@code item4}, {@code item5}, {@code item6},
3426 * {@code item7}, {@code item8}, {@code item9},
3427 * or {@code item10} is {@code null}
3428 * @see <a href="http://reactivex.io/documentation/operators/just.html">ReactiveX operators documentation: Just</a>
3429 */
3430 @CheckReturnValue
3431 @NonNull
3432 @BackpressureSupport(BackpressureKind.FULL)
3433 @SchedulerSupport(SchedulerSupport.NONE)
3434 public static <@NonNull T> Flowable<T> just(T item1, T item2, T item3, T item4, T item5, T item6, T item7, T item8, T item9, T item10) {
3435 Objects.requireNonNull(item1, "item1 is null");
3436 Objects.requireNonNull(item2, "item2 is null");
3437 Objects.requireNonNull(item3, "item3 is null");
3438 Objects.requireNonNull(item4, "item4 is null");
3439 Objects.requireNonNull(item5, "item5 is null");
3440 Objects.requireNonNull(item6, "item6 is null");
3441 Objects.requireNonNull(item7, "item7 is null");
3442 Objects.requireNonNull(item8, "item8 is null");
3443 Objects.requireNonNull(item9, "item9 is null");
3444 Objects.requireNonNull(item10, "item10 is null");
3445
3446 return fromArray(item1, item2, item3, item4, item5, item6, item7, item8, item9, item10);
3447 }
3448
3449 /**
3450 * Flattens an {@link Iterable} of {@link Publisher}s into one {@code Publisher}, without any transformation, while limiting the
3451 * number of concurrent subscriptions to these {@code Publisher}s.
3452 * <p>
3453 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/merge.v3.png" alt="">
3454 * <p>
3455 * You can combine the items emitted by multiple {@code Publisher}s so that they appear as a single {@code Publisher}, by
3456 * using the {@code merge} method.
3457 * <dl>
3458 * <dt><b>Backpressure:</b></dt>
3459 * <dd>The operator honors backpressure from downstream. The source {@code Publisher}s are expected to honor
3460 * backpressure; if violated, the operator <em>may</em> signal {@link MissingBackpressureException}.</dd>
3461 * <dt><b>Scheduler:</b></dt>
3462 * <dd>{@code merge} does not operate by default on a particular {@link Scheduler}.</dd>
3463 * <dt><b>Error handling:</b></dt>
3464 * <dd>If any of the source {@code Publisher}s signal a {@link Throwable} via {@code onError}, the resulting
3465 * {@code Flowable} terminates with that {@code Throwable} and all other source {@code Publisher}s are canceled.
3466 * If more than one {@code Publisher} signals an error, the resulting {@code Flowable} may terminate with the
3467 * first one's error or, depending on the concurrency of the sources, may terminate with a
3468 * {@link CompositeException} containing two or more of the various error signals.
3469 * {@code Throwable}s that didn't make into the composite will be sent (individually) to the global error handler via
3470 * {@link RxJavaPlugins#onError(Throwable)} method as {@link UndeliverableException} errors. Similarly, {@code Throwable}s
3471 * signaled by source(s) after the returned {@code Flowable} has been canceled or terminated with a
3472 * (composite) error will be sent to the same global error handler.
3473 * Use {@link #mergeDelayError(Iterable, int, int)} to merge sources and terminate only when all source {@code Publisher}s
3474 * have completed or failed with an error.
3475 * </dd>
3476 * </dl>
3477 *
3478 * @param <T> the common element base type
3479 * @param sources
3480 * the {@code Iterable} of {@code Publisher}s
3481 * @param maxConcurrency
3482 * the maximum number of {@code Publisher}s that may be subscribed to concurrently
3483 * @param bufferSize
3484 * the number of items to prefetch from each inner {@code Publisher}
3485 * @return the new {@code Flowable} instance
3486 * @throws NullPointerException if {@code sources} is {@code null}
3487 * @throws IllegalArgumentException
3488 * if {@code maxConcurrency} or {@code bufferSize} is non-positive
3489 * @see <a href="http://reactivex.io/documentation/operators/merge.html">ReactiveX operators documentation: Merge</a>
3490 * @see #mergeDelayError(Iterable, int, int)
3491 */
3492 @SuppressWarnings({ "unchecked", "rawtypes" })
3493 @CheckReturnValue
3494 @BackpressureSupport(BackpressureKind.FULL)
3495 @SchedulerSupport(SchedulerSupport.NONE)
3496 @NonNull
3497 public static <@NonNull T> Flowable<T> merge(@NonNull Iterable<@NonNull ? extends Publisher<? extends T>> sources, int maxConcurrency, int bufferSize) {
3498 return fromIterable(sources).flatMap((Function)Functions.identity(), false, maxConcurrency, bufferSize);
3499 }
3500
3501 /**
3502 * Flattens an array of {@link Publisher}s into one {@code Publisher}, without any transformation, while limiting the
3503 * number of concurrent subscriptions to these {@code Publisher}s.
3504 * <p>
3505 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/merge.v3.png" alt="">
3506 * <p>
3507 * You can combine the items emitted by multiple {@code Publisher}s so that they appear as a single {@code Publisher}, by
3508 * using the {@code merge} method.
3509 * <dl>
3510 * <dt><b>Backpressure:</b></dt>
3511 * <dd>The operator honors backpressure from downstream. The source {@code Publisher}s are expected to honor
3512 * backpressure; if violated, the operator <em>may</em> signal {@link MissingBackpressureException}.</dd>
3513 * <dt><b>Scheduler:</b></dt>
3514 * <dd>{@code mergeArray} does not operate by default on a particular {@link Scheduler}.</dd>
3515 * <dt><b>Error handling:</b></dt>
3516 * <dd>If any of the source {@code Publisher}s signal a {@link Throwable} via {@code onError}, the resulting
3517 * {@code Flowable} terminates with that {@code Throwable} and all other source {@code Publisher}s are canceled.
3518 * If more than one {@code Publisher} signals an error, the resulting {@code Flowable} may terminate with the
3519 * first one's error or, depending on the concurrency of the sources, may terminate with a
3520 * {@link CompositeException} containing two or more of the various error signals.
3521 * {@code Throwable}s that didn't make into the composite will be sent (individually) to the global error handler via
3522 * {@link RxJavaPlugins#onError(Throwable)} method as {@link UndeliverableException} errors. Similarly, {@code Throwable}s
3523 * signaled by source(s) after the returned {@code Flowable} has been canceled or terminated with a
3524 * (composite) error will be sent to the same global error handler.
3525 * Use {@link #mergeArrayDelayError(int, int, Publisher[])} to merge sources and terminate only when all source {@code Publisher}s
3526 * have completed or failed with an error.
3527 * </dd>
3528 * </dl>
3529 *
3530 * @param <T> the common element base type
3531 * @param sources
3532 * the array of {@code Publisher}s
3533 * @param maxConcurrency
3534 * the maximum number of {@code Publisher}s that may be subscribed to concurrently
3535 * @param bufferSize
3536 * the number of items to prefetch from each inner {@code Publisher}
3537 * @return the new {@code Flowable} instance
3538 * @throws NullPointerException if {@code sources} is {@code null}
3539 * @throws IllegalArgumentException
3540 * if {@code maxConcurrency} or {@code bufferSize} is non-positive
3541 * @see <a href="http://reactivex.io/documentation/operators/merge.html">ReactiveX operators documentation: Merge</a>
3542 * @see #mergeArrayDelayError(int, int, Publisher...)
3543 */
3544 @SuppressWarnings({ "unchecked", "rawtypes" })
3545 @CheckReturnValue
3546 @BackpressureSupport(BackpressureKind.FULL)
3547 @SchedulerSupport(SchedulerSupport.NONE)
3548 @SafeVarargs
3549 @NonNull
3550 public static <@NonNull T> Flowable<T> mergeArray(int maxConcurrency, int bufferSize, @NonNull Publisher<? extends T>... sources) {
3551 return fromArray(sources).flatMap((Function)Functions.identity(), false, maxConcurrency, bufferSize);
3552 }
3553
3554 /**
3555 * Flattens an {@link Iterable} of {@link Publisher}s into one {@code Publisher}, without any transformation.
3556 * <p>
3557 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/merge.v3.png" alt="">
3558 * <p>
3559 * You can combine the items emitted by multiple {@code Publisher}s so that they appear as a single {@code Publisher}, by
3560 * using the {@code merge} method.
3561 * <dl>
3562 * <dt><b>Backpressure:</b></dt>
3563 * <dd>The operator honors backpressure from downstream. The source {@code Publisher}s are expected to honor
3564 * backpressure; if violated, the operator <em>may</em> signal {@link MissingBackpressureException}.</dd>
3565 * <dt><b>Scheduler:</b></dt>
3566 * <dd>{@code merge} does not operate by default on a particular {@link Scheduler}.</dd>
3567 * <dt><b>Error handling:</b></dt>
3568 * <dd>If any of the source {@code Publisher}s signal a {@link Throwable} via {@code onError}, the resulting
3569 * {@code Flowable} terminates with that {@code Throwable} and all other source {@code Publisher}s are canceled.
3570 * If more than one {@code Publisher} signals an error, the resulting {@code Flowable} may terminate with the
3571 * first one's error or, depending on the concurrency of the sources, may terminate with a
3572 * {@link CompositeException} containing two or more of the various error signals.
3573 * {@code Throwable}s that didn't make into the composite will be sent (individually) to the global error handler via
3574 * {@link RxJavaPlugins#onError(Throwable)} method as {@link UndeliverableException} errors. Similarly, {@code Throwable}s
3575 * signaled by source(s) after the returned {@code Flowable} has been canceled or terminated with a
3576 * (composite) error will be sent to the same global error handler.
3577 * Use {@link #mergeDelayError(Iterable)} to merge sources and terminate only when all source {@code Publisher}s
3578 * have completed or failed with an error.
3579 * </dd>
3580 * </dl>
3581 *
3582 * @param <T> the common element base type
3583 * @param sources
3584 * the {@code Iterable} of {@code Publisher}s
3585 * @return the new {@code Flowable} instance
3586 * @throws NullPointerException if {@code sources} is {@code null}
3587 * @see <a href="http://reactivex.io/documentation/operators/merge.html">ReactiveX operators documentation: Merge</a>
3588 * @see #mergeDelayError(Iterable)
3589 */
3590 @SuppressWarnings({ "unchecked", "rawtypes" })
3591 @CheckReturnValue
3592 @BackpressureSupport(BackpressureKind.FULL)
3593 @SchedulerSupport(SchedulerSupport.NONE)
3594 @NonNull
3595 public static <@NonNull T> Flowable<T> merge(@NonNull Iterable<@NonNull ? extends Publisher<? extends T>> sources) {
3596 return fromIterable(sources).flatMap((Function)Functions.identity());
3597 }
3598
3599 /**
3600 * Flattens an {@link Iterable} of {@link Publisher}s into one {@code Publisher}, without any transformation, while limiting the
3601 * number of concurrent subscriptions to these {@code Publisher}s.
3602 * <p>
3603 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/merge.v3.png" alt="">
3604 * <p>
3605 * You can combine the items emitted by multiple {@code Publisher}s so that they appear as a single {@code Publisher}, by
3606 * using the {@code merge} method.
3607 * <dl>
3608 * <dt><b>Backpressure:</b></dt>
3609 * <dd>The operator honors backpressure from downstream. The source {@code Publisher}s are expected to honor
3610 * backpressure; if violated, the operator <em>may</em> signal {@link MissingBackpressureException}.</dd>
3611 * <dt><b>Scheduler:</b></dt>
3612 * <dd>{@code merge} does not operate by default on a particular {@link Scheduler}.</dd>
3613 * <dt><b>Error handling:</b></dt>
3614 * <dd>If any of the source {@code Publisher}s signal a {@link Throwable} via {@code onError}, the resulting
3615 * {@code Flowable} terminates with that {@code Throwable} and all other source {@code Publisher}s are canceled.
3616 * If more than one {@code Publisher} signals an error, the resulting {@code Flowable} may terminate with the
3617 * first one's error or, depending on the concurrency of the sources, may terminate with a
3618 * {@link CompositeException} containing two or more of the various error signals.
3619 * {@code Throwable}s that didn't make into the composite will be sent (individually) to the global error handler via
3620 * {@link RxJavaPlugins#onError(Throwable)} method as {@link UndeliverableException} errors. Similarly, {@code Throwable}s
3621 * signaled by source(s) after the returned {@code Flowable} has been canceled or terminated with a
3622 * (composite) error will be sent to the same global error handler.
3623 * Use {@link #mergeDelayError(Iterable, int)} to merge sources and terminate only when all source {@code Publisher}s
3624 * have completed or failed with an error.
3625 * </dd>
3626 * </dl>
3627 *
3628 * @param <T> the common element base type
3629 * @param sources
3630 * the {@code Iterable} of {@code Publisher}s
3631 * @param maxConcurrency
3632 * the maximum number of {@code Publisher}s that may be subscribed to concurrently
3633 * @return the new {@code Flowable} instance
3634 * @throws NullPointerException if {@code sources} is {@code null}
3635 * @throws IllegalArgumentException
3636 * if {@code maxConcurrency} is less than or equal to 0
3637 * @see <a href="http://reactivex.io/documentation/operators/merge.html">ReactiveX operators documentation: Merge</a>
3638 * @see #mergeDelayError(Iterable, int)
3639 */
3640 @SuppressWarnings({ "unchecked", "rawtypes" })
3641 @CheckReturnValue
3642 @BackpressureSupport(BackpressureKind.FULL)
3643 @SchedulerSupport(SchedulerSupport.NONE)
3644 @NonNull
3645 public static <@NonNull T> Flowable<T> merge(@NonNull Iterable<@NonNull ? extends Publisher<? extends T>> sources, int maxConcurrency) {
3646 return fromIterable(sources).flatMap((Function)Functions.identity(), maxConcurrency);
3647 }
3648
3649 /**
3650 * Flattens a {@link Publisher} that emits {@code Publisher}s into a single {@code Publisher} that emits the items emitted by
3651 * thos {@code Publisher}s , without any transformation.
3652 * <p>
3653 * <img width="640" height="370" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/merge.oo.v3.png" alt="">
3654 * <p>
3655 * You can combine the items emitted by multiple {@code Publisher}s so that they appear as a single {@code Publisher}, by
3656 * using the {@code merge} method.
3657 * <dl>
3658 * <dt><b>Backpressure:</b></dt>
3659 * <dd>The operator honors backpressure from downstream. The outer {@code Publisher} is consumed
3660 * in unbounded mode (i.e., no backpressure is applied to it). The inner {@code Publisher}s are expected to honor
3661 * backpressure; if violated, the operator <em>may</em> signal {@link MissingBackpressureException}.</dd>
3662 * <dt><b>Scheduler:</b></dt>
3663 * <dd>{@code merge} does not operate by default on a particular {@link Scheduler}.</dd>
3664 * <dt><b>Error handling:</b></dt>
3665 * <dd>If any of the source {@code Publisher}s signal a {@link Throwable} via {@code onError}, the resulting
3666 * {@code Flowable} terminates with that {@code Throwable} and all other source {@code Publisher}s are canceled.
3667 * If more than one {@code Publisher} signals an error, the resulting {@code Flowable} may terminate with the
3668 * first one's error or, depending on the concurrency of the sources, may terminate with a
3669 * {@link CompositeException} containing two or more of the various error signals.
3670 * {@code Throwable}s that didn't make into the composite will be sent (individually) to the global error handler via
3671 * {@link RxJavaPlugins#onError(Throwable)} method as {@link UndeliverableException} errors. Similarly, {@code Throwable}s
3672 * signaled by source(s) after the returned {@code Flowable} has been canceled or terminated with a
3673 * (composite) error will be sent to the same global error handler.
3674 * Use {@link #mergeDelayError(Publisher)} to merge sources and terminate only when all source {@code Publisher}s
3675 * have completed or failed with an error.
3676 * </dd>
3677 * </dl>
3678 *
3679 * @param <T> the common element base type
3680 * @param sources
3681 * a {@code Publisher} that emits {@code Publisher}s
3682 * @return the new {@code Flowable} instance
3683 * @throws NullPointerException if {@code sources} is {@code null}
3684 * @see <a href="http://reactivex.io/documentation/operators/merge.html">ReactiveX operators documentation: Merge</a>
3685 * @see #mergeDelayError(Publisher)
3686 */
3687 @CheckReturnValue
3688 @BackpressureSupport(BackpressureKind.FULL)
3689 @SchedulerSupport(SchedulerSupport.NONE)
3690 @NonNull
3691 public static <@NonNull T> Flowable<T> merge(@NonNull Publisher<@NonNull ? extends Publisher<? extends T>> sources) {
3692 return merge(sources, bufferSize());
3693 }
3694
3695 /**
3696 * Flattens a {@link Publisher} that emits {@code Publisher}s into a single {@code Publisher} that emits the items emitted by
3697 * those {@code Publisher}s, without any transformation, while limiting the maximum number of concurrent
3698 * subscriptions to these {@code Publisher}s.
3699 * <p>
3700 * <img width="640" height="370" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/merge.oo.v3.png" alt="">
3701 * <p>
3702 * You can combine the items emitted by multiple {@code Publisher}s so that they appear as a single {@code Publisher}, by
3703 * using the {@code merge} method.
3704 * <dl>
3705 * <dt><b>Backpressure:</b></dt>
3706 * <dd>The operator honors backpressure from downstream. Both the outer and inner {@code Publisher}s are expected to honor
3707 * backpressure; if violated, the operator <em>may</em> signal {@link MissingBackpressureException}.</dd>
3708 * <dt><b>Scheduler:</b></dt>
3709 * <dd>{@code merge} does not operate by default on a particular {@link Scheduler}.</dd>
3710 * <dt><b>Error handling:</b></dt>
3711 * <dd>If any of the source {@code Publisher}s signal a {@link Throwable} via {@code onError}, the resulting
3712 * {@code Flowable} terminates with that {@code Throwable} and all other source {@code Publisher}s are canceled.
3713 * If more than one {@code Publisher} signals an error, the resulting {@code Flowable} may terminate with the
3714 * first one's error or, depending on the concurrency of the sources, may terminate with a
3715 * {@link CompositeException} containing two or more of the various error signals.
3716 * {@code Throwable}s that didn't make into the composite will be sent (individually) to the global error handler via
3717 * {@link RxJavaPlugins#onError(Throwable)} method as {@link UndeliverableException} errors. Similarly, {@code Throwable}s
3718 * signaled by source(s) after the returned {@code Flowable} has been canceled or terminated with a
3719 * (composite) error will be sent to the same global error handler.
3720 * Use {@link #mergeDelayError(Publisher, int)} to merge sources and terminate only when all source {@code Publisher}s
3721 * have completed or failed with an error.
3722 * </dd>
3723 * </dl>
3724 *
3725 * @param <T> the common element base type
3726 * @param sources
3727 * a {@code Publisher} that emits {@code Publisher}s
3728 * @param maxConcurrency
3729 * the maximum number of {@code Publisher}s that may be subscribed to concurrently
3730 * @return the new {@code Flowable} instance
3731 * @throws NullPointerException if {@code sources} is {@code null}
3732 * @throws IllegalArgumentException
3733 * if {@code maxConcurrency} is less than or equal to 0
3734 * @see <a href="http://reactivex.io/documentation/operators/merge.html">ReactiveX operators documentation: Merge</a>
3735 * @see #mergeDelayError(Publisher, int)
3736 * @since 1.1.0
3737 */
3738 @SuppressWarnings({ "unchecked", "rawtypes" })
3739 @CheckReturnValue
3740 @BackpressureSupport(BackpressureKind.FULL)
3741 @SchedulerSupport(SchedulerSupport.NONE)
3742 @NonNull
3743 public static <@NonNull T> Flowable<T> merge(@NonNull Publisher<@NonNull ? extends Publisher<? extends T>> sources, int maxConcurrency) {
3744 return fromPublisher(sources).flatMap((Function)Functions.identity(), maxConcurrency);
3745 }
3746
3747 /**
3748 * Flattens an array of {@link Publisher}s into one {@code Publisher}, without any transformation.
3749 * <p>
3750 * <img width="640" height="370" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/merge.io.v3.png" alt="">
3751 * <p>
3752 * You can combine items emitted by multiple {@code Publisher}s so that they appear as a single {@code Publisher}, by
3753 * using the {@code merge} method.
3754 * <dl>
3755 * <dt><b>Backpressure:</b></dt>
3756 * <dd>The operator honors backpressure from downstream. The source {@code Publisher}s are expected to honor
3757 * backpressure; if violated, the operator <em>may</em> signal {@link MissingBackpressureException}.</dd>
3758 * <dt><b>Scheduler:</b></dt>
3759 * <dd>{@code mergeArray} does not operate by default on a particular {@link Scheduler}.</dd>
3760 * <dt><b>Error handling:</b></dt>
3761 * <dd>If any of the source {@code Publisher}s signal a {@link Throwable} via {@code onError}, the resulting
3762 * {@code Flowable} terminates with that {@code Throwable} and all other source {@code Publisher}s are canceled.
3763 * If more than one {@code Publisher} signals an error, the resulting {@code Flowable} may terminate with the
3764 * first one's error or, depending on the concurrency of the sources, may terminate with a
3765 * {@link CompositeException} containing two or more of the various error signals.
3766 * {@code Throwable}s that didn't make into the composite will be sent (individually) to the global error handler via
3767 * {@link RxJavaPlugins#onError(Throwable)} method as {@link UndeliverableException} errors. Similarly, {@code Throwable}s
3768 * signaled by source(s) after the returned {@code Flowable} has been canceled or terminated with a
3769 * (composite) error will be sent to the same global error handler.
3770 * Use {@link #mergeArrayDelayError(Publisher...)} to merge sources and terminate only when all source {@code Publisher}s
3771 * have completed or failed with an error.
3772 * </dd>
3773 * </dl>
3774 *
3775 * @param <T> the common element base type
3776 * @param sources
3777 * the array of {@code Publisher}s
3778 * @return the new {@code Flowable} instance
3779 * @throws NullPointerException if {@code sources} is {@code null}
3780 * @see <a href="http://reactivex.io/documentation/operators/merge.html">ReactiveX operators documentation: Merge</a>
3781 * @see #mergeArrayDelayError(Publisher...)
3782 */
3783 @SuppressWarnings({ "unchecked", "rawtypes" })
3784 @CheckReturnValue
3785 @BackpressureSupport(BackpressureKind.FULL)
3786 @SchedulerSupport(SchedulerSupport.NONE)
3787 @SafeVarargs
3788 @NonNull
3789 public static <@NonNull T> Flowable<T> mergeArray(@NonNull Publisher<? extends T>... sources) {
3790 return fromArray(sources).flatMap((Function)Functions.identity(), sources.length);
3791 }
3792
3793 /**
3794 * Flattens two {@link Publisher}s into a single {@code Publisher}, without any transformation.
3795 * <p>
3796 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/merge.v3.png" alt="">
3797 * <p>
3798 * You can combine items emitted by multiple {@code Publisher}s so that they appear as a single {@code Publisher}, by
3799 * using the {@code merge} method.
3800 * <dl>
3801 * <dt><b>Backpressure:</b></dt>
3802 * <dd>The operator honors backpressure from downstream. The source {@code Publisher}s are expected to honor
3803 * backpressure; if violated, the operator <em>may</em> signal {@link MissingBackpressureException}.</dd>
3804 * <dt><b>Scheduler:</b></dt>
3805 * <dd>{@code merge} does not operate by default on a particular {@link Scheduler}.</dd>
3806 * <dt><b>Error handling:</b></dt>
3807 * <dd>If any of the source {@code Publisher}s signal a {@link Throwable} via {@code onError}, the resulting
3808 * {@code Flowable} terminates with that {@code Throwable} and all other source {@code Publisher}s are canceled.
3809 * If more than one {@code Publisher} signals an error, the resulting {@code Flowable} may terminate with the
3810 * first one's error or, depending on the concurrency of the sources, may terminate with a
3811 * {@link CompositeException} containing two or more of the various error signals.
3812 * {@code Throwable}s that didn't make into the composite will be sent (individually) to the global error handler via
3813 * {@link RxJavaPlugins#onError(Throwable)} method as {@link UndeliverableException} errors. Similarly, {@code Throwable}s
3814 * signaled by source(s) after the returned {@code Flowable} has been canceled or terminated with a
3815 * (composite) error will be sent to the same global error handler.
3816 * Use {@link #mergeDelayError(Publisher, Publisher)} to merge sources and terminate only when all source {@code Publisher}s
3817 * have completed or failed with an error.
3818 * </dd>
3819 * </dl>
3820 *
3821 * @param <T> the common element base type
3822 * @param source1
3823 * a {@code Publisher} to be merged
3824 * @param source2
3825 * a {@code Publisher} to be merged
3826 * @return the new {@code Flowable} instance
3827 * @throws NullPointerException if {@code source1} or {@code source2} is {@code null}
3828 * @see <a href="http://reactivex.io/documentation/operators/merge.html">ReactiveX operators documentation: Merge</a>
3829 * @see #mergeDelayError(Publisher, Publisher)
3830 */
3831 @SuppressWarnings({ "unchecked", "rawtypes" })
3832 @CheckReturnValue
3833 @NonNull
3834 @BackpressureSupport(BackpressureKind.FULL)
3835 @SchedulerSupport(SchedulerSupport.NONE)
3836 public static <@NonNull T> Flowable<T> merge(@NonNull Publisher<? extends T> source1, @NonNull Publisher<? extends T> source2) {
3837 Objects.requireNonNull(source1, "source1 is null");
3838 Objects.requireNonNull(source2, "source2 is null");
3839 return fromArray(source1, source2).flatMap((Function)Functions.identity(), false, 2);
3840 }
3841
3842 /**
3843 * Flattens three {@link Publisher}s into a single {@code Publisher}, without any transformation.
3844 * <p>
3845 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/merge.v3.png" alt="">
3846 * <p>
3847 * You can combine items emitted by multiple {@code Publisher}s so that they appear as a single {@code Publisher}, by
3848 * using the {@code merge} method.
3849 * <dl>
3850 * <dt><b>Backpressure:</b></dt>
3851 * <dd>The operator honors backpressure from downstream. The source {@code Publisher}s are expected to honor
3852 * backpressure; if violated, the operator <em>may</em> signal {@link MissingBackpressureException}.</dd>
3853 * <dt><b>Scheduler:</b></dt>
3854 * <dd>{@code merge} does not operate by default on a particular {@link Scheduler}.</dd>
3855 * <dt><b>Error handling:</b></dt>
3856 * <dd>If any of the source {@code Publisher}s signal a {@link Throwable} via {@code onError}, the resulting
3857 * {@code Flowable} terminates with that {@code Throwable} and all other source {@code Publisher}s are canceled.
3858 * If more than one {@code Publisher} signals an error, the resulting {@code Flowable} may terminate with the
3859 * first one's error or, depending on the concurrency of the sources, may terminate with a
3860 * {@link CompositeException} containing two or more of the various error signals.
3861 * {@code Throwable}s that didn't make into the composite will be sent (individually) to the global error handler via
3862 * {@link RxJavaPlugins#onError(Throwable)} method as {@link UndeliverableException} errors. Similarly, {@code Throwable}s
3863 * signaled by source(s) after the returned {@code Flowable} has been canceled or terminated with a
3864 * (composite) error will be sent to the same global error handler.
3865 * Use {@link #mergeDelayError(Publisher, Publisher, Publisher)} to merge sources and terminate only when all source {@code Publisher}s
3866 * have completed or failed with an error.
3867 * </dd>
3868 * </dl>
3869 *
3870 * @param <T> the common element base type
3871 * @param source1
3872 * a {@code Publisher} to be merged
3873 * @param source2
3874 * a {@code Publisher} to be merged
3875 * @param source3
3876 * a {@code Publisher} to be merged
3877 * @return the new {@code Flowable} instance
3878 * @throws NullPointerException if {@code source1}, {@code source2} or {@code source3} is {@code null}
3879 * @see <a href="http://reactivex.io/documentation/operators/merge.html">ReactiveX operators documentation: Merge</a>
3880 * @see #mergeDelayError(Publisher, Publisher, Publisher)
3881 */
3882 @SuppressWarnings({ "unchecked", "rawtypes" })
3883 @CheckReturnValue
3884 @NonNull
3885 @BackpressureSupport(BackpressureKind.FULL)
3886 @SchedulerSupport(SchedulerSupport.NONE)
3887 public static <@NonNull T> Flowable<T> merge(@NonNull Publisher<? extends T> source1, @NonNull Publisher<? extends T> source2, @NonNull Publisher<? extends T> source3) {
3888 Objects.requireNonNull(source1, "source1 is null");
3889 Objects.requireNonNull(source2, "source2 is null");
3890 Objects.requireNonNull(source3, "source3 is null");
3891 return fromArray(source1, source2, source3).flatMap((Function)Functions.identity(), false, 3);
3892 }
3893
3894 /**
3895 * Flattens four {@link Publisher}s into a single {@code Publisher}, without any transformation.
3896 * <p>
3897 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/merge.v3.png" alt="">
3898 * <p>
3899 * You can combine items emitted by multiple {@code Publisher}s so that they appear as a single {@code Publisher}, by
3900 * using the {@code merge} method.
3901 * <dl>
3902 * <dt><b>Backpressure:</b></dt>
3903 * <dd>The operator honors backpressure from downstream. The source {@code Publisher}s are expected to honor
3904 * backpressure; if violated, the operator <em>may</em> signal {@link MissingBackpressureException}.</dd>
3905 * <dt><b>Scheduler:</b></dt>
3906 * <dd>{@code merge} does not operate by default on a particular {@link Scheduler}.</dd>
3907 * <dt><b>Error handling:</b></dt>
3908 * <dd>If any of the source {@code Publisher}s signal a {@link Throwable} via {@code onError}, the resulting
3909 * {@code Flowable} terminates with that {@code Throwable} and all other source {@code Publisher}s are canceled.
3910 * If more than one {@code Publisher} signals an error, the resulting {@code Flowable} may terminate with the
3911 * first one's error or, depending on the concurrency of the sources, may terminate with a
3912 * {@link CompositeException} containing two or more of the various error signals.
3913 * {@code Throwable}s that didn't make into the composite will be sent (individually) to the global error handler via
3914 * {@link RxJavaPlugins#onError(Throwable)} method as {@link UndeliverableException} errors. Similarly, {@code Throwable}s
3915 * signaled by source(s) after the returned {@code Flowable} has been canceled or terminated with a
3916 * (composite) error will be sent to the same global error handler.
3917 * Use {@link #mergeDelayError(Publisher, Publisher, Publisher, Publisher)} to merge sources and terminate only when all source {@code Publisher}s
3918 * have completed or failed with an error.
3919 * </dd>
3920 * </dl>
3921 *
3922 * @param <T> the common element base type
3923 * @param source1
3924 * a {@code Publisher} to be merged
3925 * @param source2
3926 * a {@code Publisher} to be merged
3927 * @param source3
3928 * a {@code Publisher} to be merged
3929 * @param source4
3930 * a {@code Publisher} to be merged
3931 * @return the new {@code Flowable} instance
3932 * @throws NullPointerException if {@code source1}, {@code source2}, {@code source3} or {@code source4} is {@code null}
3933 * @see <a href="http://reactivex.io/documentation/operators/merge.html">ReactiveX operators documentation: Merge</a>
3934 * @see #mergeDelayError(Publisher, Publisher, Publisher, Publisher)
3935 */
3936 @SuppressWarnings({ "unchecked", "rawtypes" })
3937 @CheckReturnValue
3938 @NonNull
3939 @BackpressureSupport(BackpressureKind.FULL)
3940 @SchedulerSupport(SchedulerSupport.NONE)
3941 public static <@NonNull T> Flowable<T> merge(
3942 @NonNull Publisher<? extends T> source1, @NonNull Publisher<? extends T> source2,
3943 @NonNull Publisher<? extends T> source3, @NonNull Publisher<? extends T> source4) {
3944 Objects.requireNonNull(source1, "source1 is null");
3945 Objects.requireNonNull(source2, "source2 is null");
3946 Objects.requireNonNull(source3, "source3 is null");
3947 Objects.requireNonNull(source4, "source4 is null");
3948 return fromArray(source1, source2, source3, source4).flatMap((Function)Functions.identity(), false, 4);
3949 }
3950
3951 /**
3952 * Flattens an {@link Iterable} of {@link Publisher}s into one {@code Publisher}, in a way that allows a {@link Subscriber} to receive all
3953 * successfully emitted items from each of the source {@code Publisher}s without being interrupted by an error
3954 * notification from one of them.
3955 * <p>
3956 * This behaves like {@link #merge(Publisher)} except that if any of the merged {@code Publisher}s notify of an
3957 * error via {@link Subscriber#onError onError}, {@code mergeDelayError} will refrain from propagating that
3958 * error notification until all of the merged {@code Publisher}s have finished emitting items.
3959 * <p>
3960 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/mergeDelayError.v3.png" alt="">
3961 * <p>
3962 * Even if multiple merged {@code Publisher}s send {@code onError} notifications, {@code mergeDelayError} will only
3963 * invoke the {@code onError} method of its {@code Subscriber}s once.
3964 * <dl>
3965 * <dt><b>Backpressure:</b></dt>
3966 * <dd>The operator honors backpressure from downstream. All inner {@code Publisher}s are expected to honor
3967 * backpressure; if violated, the operator <em>may</em> signal {@link MissingBackpressureException}.</dd>
3968 * <dt><b>Scheduler:</b></dt>
3969 * <dd>{@code mergeDelayError} does not operate by default on a particular {@link Scheduler}.</dd>
3970 * </dl>
3971 *
3972 * @param <T> the common element base type
3973 * @param sources
3974 * the {@code Iterable} of {@code Publisher}s
3975 * @return the new {@code Flowable} instance
3976 * @throws NullPointerException if {@code sources} is {@code null}
3977 * @see <a href="http://reactivex.io/documentation/operators/merge.html">ReactiveX operators documentation: Merge</a>
3978 */
3979 @SuppressWarnings({ "unchecked", "rawtypes" })
3980 @CheckReturnValue
3981 @BackpressureSupport(BackpressureKind.FULL)
3982 @SchedulerSupport(SchedulerSupport.NONE)
3983 @NonNull
3984 public static <@NonNull T> Flowable<T> mergeDelayError(@NonNull Iterable<@NonNull ? extends Publisher<? extends T>> sources) {
3985 return fromIterable(sources).flatMap((Function)Functions.identity(), true);
3986 }
3987
3988 /**
3989 * Flattens an {@link Iterable} of {@link Publisher}s into one {@code Publisher}, in a way that allows a {@link Subscriber} to receive all
3990 * successfully emitted items from each of the source {@code Publisher}s without being interrupted by an error
3991 * notification from one of them, while limiting the number of concurrent subscriptions to these {@code Publisher}s.
3992 * <p>
3993 * This behaves like {@link #merge(Publisher)} except that if any of the merged {@code Publisher}s notify of an
3994 * error via {@link Subscriber#onError onError}, {@code mergeDelayError} will refrain from propagating that
3995 * error notification until all of the merged {@code Publisher}s have finished emitting items.
3996 * <p>
3997 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/mergeDelayError.v3.png" alt="">
3998 * <p>
3999 * Even if multiple merged {@code Publisher}s send {@code onError} notifications, {@code mergeDelayError} will only
4000 * invoke the {@code onError} method of its {@code Subscriber}s once.
4001 * <dl>
4002 * <dt><b>Backpressure:</b></dt>
4003 * <dd>The operator honors backpressure from downstream. All inner {@code Publisher}s are expected to honor
4004 * backpressure; if violated, the operator <em>may</em> signal {@link MissingBackpressureException}.</dd>
4005 * <dt><b>Scheduler:</b></dt>
4006 * <dd>{@code mergeDelayError} does not operate by default on a particular {@link Scheduler}.</dd>
4007 * </dl>
4008 *
4009 * @param <T> the common element base type
4010 * @param sources
4011 * the {@code Iterable} of {@code Publisher}s
4012 * @param maxConcurrency
4013 * the maximum number of {@code Publisher}s that may be subscribed to concurrently
4014 * @param bufferSize
4015 * the number of items to prefetch from each inner {@code Publisher}
4016 * @return the new {@code Flowable} instance
4017 * @throws NullPointerException if {@code sources} is {@code null}
4018 * @throws IllegalArgumentException if {@code maxConcurrency} or {@code bufferSize} is non-positive
4019 * @see <a href="http://reactivex.io/documentation/operators/merge.html">ReactiveX operators documentation: Merge</a>
4020 */
4021 @SuppressWarnings({ "unchecked", "rawtypes" })
4022 @CheckReturnValue
4023 @BackpressureSupport(BackpressureKind.FULL)
4024 @SchedulerSupport(SchedulerSupport.NONE)
4025 @NonNull
4026 public static <@NonNull T> Flowable<T> mergeDelayError(@NonNull Iterable<@NonNull ? extends Publisher<? extends T>> sources, int maxConcurrency, int bufferSize) {
4027 return fromIterable(sources).flatMap((Function)Functions.identity(), true, maxConcurrency, bufferSize);
4028 }
4029
4030 /**
4031 * Flattens an array of {@link Publisher}s into one {@code Publisher}, in a way that allows a {@link Subscriber} to receive all
4032 * successfully emitted items from each of the source {@code Publisher}s without being interrupted by an error
4033 * notification from one of them, while limiting the number of concurrent subscriptions to these {@code Publisher}s.
4034 * <p>
4035 * This behaves like {@link #merge(Publisher)} except that if any of the merged {@code Publisher}s notify of an
4036 * error via {@link Subscriber#onError onError}, {@code mergeDelayError} will refrain from propagating that
4037 * error notification until all of the merged {@code Publisher}s have finished emitting items.
4038 * <p>
4039 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/mergeDelayError.v3.png" alt="">
4040 * <p>
4041 * Even if multiple merged {@code Publisher}s send {@code onError} notifications, {@code mergeDelayError} will only
4042 * invoke the {@code onError} method of its {@code Subscriber}s once.
4043 * <dl>
4044 * <dt><b>Backpressure:</b></dt>
4045 * <dd>The operator honors backpressure from downstream. All source {@code Publisher}s are expected to honor
4046 * backpressure; if violated, the operator <em>may</em> signal {@link MissingBackpressureException}.</dd>
4047 * <dt><b>Scheduler:</b></dt>
4048 * <dd>{@code mergeArrayDelayError} does not operate by default on a particular {@link Scheduler}.</dd>
4049 * </dl>
4050 *
4051 * @param <T> the common element base type
4052 * @param sources
4053 * the array of {@code Publisher}s
4054 * @param maxConcurrency
4055 * the maximum number of {@code Publisher}s that may be subscribed to concurrently
4056 * @param bufferSize
4057 * the number of items to prefetch from each inner {@code Publisher}
4058 * @return the new {@code Flowable} instance
4059 * @throws NullPointerException if {@code sources} is {@code null}
4060 * @throws IllegalArgumentException if {@code maxConcurrency} or {@code bufferSize} is non-positive
4061 * @see <a href="http://reactivex.io/documentation/operators/merge.html">ReactiveX operators documentation: Merge</a>
4062 */
4063 @SuppressWarnings({ "unchecked", "rawtypes" })
4064 @CheckReturnValue
4065 @BackpressureSupport(BackpressureKind.FULL)
4066 @SchedulerSupport(SchedulerSupport.NONE)
4067 @SafeVarargs
4068 @NonNull
4069 public static <@NonNull T> Flowable<T> mergeArrayDelayError(int maxConcurrency, int bufferSize, @NonNull Publisher<? extends T>... sources) {
4070 return fromArray(sources).flatMap((Function)Functions.identity(), true, maxConcurrency, bufferSize);
4071 }
4072
4073 /**
4074 * Flattens an {@link Iterable} of {@link Publisher}s into one {@code Publisher}, in a way that allows a {@link Subscriber} to receive all
4075 * successfully emitted items from each of the source {@code Publisher}s without being interrupted by an error
4076 * notification from one of them, while limiting the number of concurrent subscriptions to these {@code Publisher}s.
4077 * <p>
4078 * This behaves like {@link #merge(Publisher)} except that if any of the merged {@code Publisher}s notify of an
4079 * error via {@link Subscriber#onError onError}, {@code mergeDelayError} will refrain from propagating that
4080 * error notification until all of the merged {@code Publisher}s have finished emitting items.
4081 * <p>
4082 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/mergeDelayError.v3.png" alt="">
4083 * <p>
4084 * Even if multiple merged {@code Publisher}s send {@code onError} notifications, {@code mergeDelayError} will only
4085 * invoke the {@code onError} method of its {@code Subscriber}s once.
4086 * <dl>
4087 * <dt><b>Backpressure:</b></dt>
4088 * <dd>The operator honors backpressure from downstream. All inner {@code Publisher}s are expected to honor
4089 * backpressure; if violated, the operator <em>may</em> signal {@link MissingBackpressureException}.</dd>
4090 * <dt><b>Scheduler:</b></dt>
4091 * <dd>{@code mergeDelayError} does not operate by default on a particular {@link Scheduler}.</dd>
4092 * </dl>
4093 *
4094 * @param <T> the common element base type
4095 * @param sources
4096 * the {@code Iterable} of {@code Publisher}s
4097 * @param maxConcurrency
4098 * the maximum number of {@code Publisher}s that may be subscribed to concurrently
4099 * @return the new {@code Flowable} instance
4100 * @throws NullPointerException if {@code sources} is {@code null}
4101 * @throws IllegalArgumentException if {@code maxConcurrency} is non-positive
4102 * @see <a href="http://reactivex.io/documentation/operators/merge.html">ReactiveX operators documentation: Merge</a>
4103 */
4104 @SuppressWarnings({ "unchecked", "rawtypes" })
4105 @CheckReturnValue
4106 @BackpressureSupport(BackpressureKind.FULL)
4107 @SchedulerSupport(SchedulerSupport.NONE)
4108 @NonNull
4109 public static <@NonNull T> Flowable<T> mergeDelayError(@NonNull Iterable<@NonNull ? extends Publisher<? extends T>> sources, int maxConcurrency) {
4110 return fromIterable(sources).flatMap((Function)Functions.identity(), true, maxConcurrency);
4111 }
4112
4113 /**
4114 * Flattens a {@link Publisher} that emits {@code Publisher}s into one {@code Publisher}, in a way that allows a {@link Subscriber} to
4115 * receive all successfully emitted items from all of the source {@code Publisher}s without being interrupted by
4116 * an error notification from one of them.
4117 * <p>
4118 * This behaves like {@link #merge(Publisher)} except that if any of the merged {@code Publisher}s notify of an
4119 * error via {@link Subscriber#onError onError}, {@code mergeDelayError} will refrain from propagating that
4120 * error notification until all of the merged {@code Publisher}s have finished emitting items.
4121 * <p>
4122 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/mergeDelayError.v3.png" alt="">
4123 * <p>
4124 * Even if multiple merged {@code Publisher}s send {@code onError} notifications, {@code mergeDelayError} will only
4125 * invoke the {@code onError} method of its {@code Subscriber}s once.
4126 * <dl>
4127 * <dt><b>Backpressure:</b></dt>
4128 * <dd>The operator honors backpressure from downstream. The outer {@code Publisher} is consumed
4129 * in unbounded mode (i.e., no backpressure is applied to it). The inner {@code Publisher}s are expected to honor
4130 * backpressure; if violated, the operator <em>may</em> signal {@link MissingBackpressureException}.</dd>
4131 * <dt><b>Scheduler:</b></dt>
4132 * <dd>{@code mergeDelayError} does not operate by default on a particular {@link Scheduler}.</dd>
4133 * </dl>
4134 *
4135 * @param <T> the common element base type
4136 * @param sources
4137 * a {@code Publisher} that emits {@code Publisher}s
4138 * @return the new {@code Flowable} instance
4139 * @throws NullPointerException if {@code sources} is {@code null}
4140 * @see <a href="http://reactivex.io/documentation/operators/merge.html">ReactiveX operators documentation: Merge</a>
4141 */
4142 @CheckReturnValue
4143 @BackpressureSupport(BackpressureKind.FULL)
4144 @SchedulerSupport(SchedulerSupport.NONE)
4145 @NonNull
4146 public static <@NonNull T> Flowable<T> mergeDelayError(@NonNull Publisher<@NonNull ? extends Publisher<? extends T>> sources) {
4147 return mergeDelayError(sources, bufferSize());
4148 }
4149
4150 /**
4151 * Flattens a {@link Publisher} that emits {@code Publisher}s into one {@code Publisher}, in a way that allows a {@link Subscriber} to
4152 * receive all successfully emitted items from all of the source {@code Publisher}s without being interrupted by
4153 * an error notification from one of them, while limiting the
4154 * number of concurrent subscriptions to these {@code Publisher}s.
4155 * <p>
4156 * This behaves like {@link #merge(Publisher)} except that if any of the merged {@code Publisher}s notify of an
4157 * error via {@link Subscriber#onError onError}, {@code mergeDelayError} will refrain from propagating that
4158 * error notification until all of the merged {@code Publisher}s have finished emitting items.
4159 * <p>
4160 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/mergeDelayError.v3.png" alt="">
4161 * <p>
4162 * Even if multiple merged {@code Publisher}s send {@code onError} notifications, {@code mergeDelayError} will only
4163 * invoke the {@code onError} method of its {@code Subscriber}s once.
4164 * <dl>
4165 * <dt><b>Backpressure:</b></dt>
4166 * <dd>The operator honors backpressure from downstream. Both the outer and inner {@code Publisher}s are expected to honor
4167 * backpressure; if violated, the operator <em>may</em> signal {@link MissingBackpressureException}.</dd>
4168 * <dt><b>Scheduler:</b></dt>
4169 * <dd>{@code mergeDelayError} does not operate by default on a particular {@link Scheduler}.</dd>
4170 * </dl>
4171 *
4172 * @param <T> the common element base type
4173 * @param sources
4174 * a {@code Publisher} that emits {@code Publisher}s
4175 * @param maxConcurrency
4176 * the maximum number of {@code Publisher}s that may be subscribed to concurrently
4177 * @return the new {@code Flowable} instance
4178 * @throws NullPointerException if {@code sources} is {@code null}
4179 * @throws IllegalArgumentException if {@code maxConcurrency} is non-positive
4180 * @see <a href="http://reactivex.io/documentation/operators/merge.html">ReactiveX operators documentation: Merge</a>
4181 * @since 2.0
4182 */
4183 @SuppressWarnings({ "unchecked", "rawtypes" })
4184 @CheckReturnValue
4185 @BackpressureSupport(BackpressureKind.FULL)
4186 @SchedulerSupport(SchedulerSupport.NONE)
4187 @NonNull
4188 public static <@NonNull T> Flowable<T> mergeDelayError(@NonNull Publisher<@NonNull ? extends Publisher<? extends T>> sources, int maxConcurrency) {
4189 return fromPublisher(sources).flatMap((Function)Functions.identity(), true, maxConcurrency);
4190 }
4191
4192 /**
4193 * Flattens an array of {@link Publisher}s into one {@code Flowable}, in a way that allows a {@link Subscriber} to receive all
4194 * successfully emitted items from each of the source {@code Publisher}s without being interrupted by an error
4195 * notification from one of them.
4196 * <p>
4197 * This behaves like {@link #merge(Publisher)} except that if any of the merged {@code Publisher}s notify of an
4198 * error via {@link Subscriber#onError onError}, {@code mergeDelayError} will refrain from propagating that
4199 * error notification until all of the merged {@code Publisher}s have finished emitting items.
4200 * <p>
4201 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/mergeDelayError.v3.png" alt="">
4202 * <p>
4203 * Even if multiple merged {@code Publisher}s send {@code onError} notifications, {@code mergeDelayError} will only
4204 * invoke the {@code onError} method of its {@code Subscriber}s once.
4205 * <dl>
4206 * <dt><b>Backpressure:</b></dt>
4207 * <dd>The operator honors backpressure from downstream. Both the outer and inner {@code Publisher}s are expected to honor
4208 * backpressure; if violated, the operator <em>may</em> signal {@link MissingBackpressureException}.</dd>
4209 * <dt><b>Scheduler:</b></dt>
4210 * <dd>{@code mergeArrayDelayError} does not operate by default on a particular {@link Scheduler}.</dd>
4211 * </dl>
4212 *
4213 * @param <T> the common element base type
4214 * @param sources
4215 * the array of {@code Publisher}s
4216 * @return the new {@code Flowable} instance
4217 * @throws NullPointerException if {@code sources} is {@code null}
4218 * @see <a href="http://reactivex.io/documentation/operators/merge.html">ReactiveX operators documentation: Merge</a>
4219 */
4220 @SuppressWarnings({ "unchecked", "rawtypes" })
4221 @CheckReturnValue
4222 @BackpressureSupport(BackpressureKind.FULL)
4223 @SchedulerSupport(SchedulerSupport.NONE)
4224 @SafeVarargs
4225 @NonNull
4226 public static <@NonNull T> Flowable<T> mergeArrayDelayError(@NonNull Publisher<? extends T>... sources) {
4227 return fromArray(sources).flatMap((Function)Functions.identity(), true, sources.length);
4228 }
4229
4230 /**
4231 * Flattens two {@link Publisher}s into one {@code Publisher}, in a way that allows a {@link Subscriber} to receive all
4232 * successfully emitted items from each of the source {@code Publisher}s without being interrupted by an error
4233 * notification from one of them.
4234 * <p>
4235 * This behaves like {@link #merge(Publisher, Publisher)} except that if any of the merged {@code Publisher}s
4236 * notify of an error via {@link Subscriber#onError onError}, {@code mergeDelayError} will refrain from
4237 * propagating that error notification until all of the merged {@code Publisher}s have finished emitting items.
4238 * <p>
4239 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/mergeDelayError.v3.png" alt="">
4240 * <p>
4241 * Even if both merged {@code Publisher}s send {@code onError} notifications, {@code mergeDelayError} will only
4242 * invoke the {@code onError} method of its {@code Subscriber}s once.
4243 * <dl>
4244 * <dt><b>Backpressure:</b></dt>
4245 * <dd>The operator honors backpressure from downstream. The source {@code Publisher}s are expected to honor
4246 * backpressure; if violated, the operator <em>may</em> signal {@link MissingBackpressureException}.</dd>
4247 * <dt><b>Scheduler:</b></dt>
4248 * <dd>{@code mergeDelayError} does not operate by default on a particular {@link Scheduler}.</dd>
4249 * </dl>
4250 *
4251 * @param <T> the common element base type
4252 * @param source1
4253 * a {@code Publisher} to be merged
4254 * @param source2
4255 * a {@code Publisher} to be merged
4256 * @return the new {@code Flowable} instance
4257 * @throws NullPointerException if {@code source1} or {@code source2} is {@code null}
4258 * @see <a href="http://reactivex.io/documentation/operators/merge.html">ReactiveX operators documentation: Merge</a>
4259 */
4260 @SuppressWarnings({ "unchecked", "rawtypes" })
4261 @CheckReturnValue
4262 @NonNull
4263 @BackpressureSupport(BackpressureKind.FULL)
4264 @SchedulerSupport(SchedulerSupport.NONE)
4265 public static <@NonNull T> Flowable<T> mergeDelayError(@NonNull Publisher<? extends T> source1, @NonNull Publisher<? extends T> source2) {
4266 Objects.requireNonNull(source1, "source1 is null");
4267 Objects.requireNonNull(source2, "source2 is null");
4268 return fromArray(source1, source2).flatMap((Function)Functions.identity(), true, 2);
4269 }
4270
4271 /**
4272 * Flattens three {@link Publisher}s into one {@code Publisher}, in a way that allows a {@link Subscriber} to receive all
4273 * successfully emitted items from all of the source {@code Publisher}s without being interrupted by an error
4274 * notification from one of them.
4275 * <p>
4276 * This behaves like {@link #merge(Publisher, Publisher, Publisher)} except that if any of the merged
4277 * {@code Publisher}s notify of an error via {@link Subscriber#onError onError}, {@code mergeDelayError} will refrain
4278 * from propagating that error notification until all of the merged {@code Publisher}s have finished emitting
4279 * items.
4280 * <p>
4281 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/mergeDelayError.v3.png" alt="">
4282 * <p>
4283 * Even if multiple merged {@code Publisher}s send {@code onError} notifications, {@code mergeDelayError} will only
4284 * invoke the {@code onError} method of its {@code Subscriber}s once.
4285 * <dl>
4286 * <dt><b>Backpressure:</b></dt>
4287 * <dd>The operator honors backpressure from downstream. The source {@code Publisher}s are expected to honor
4288 * backpressure; if violated, the operator <em>may</em> signal {@link MissingBackpressureException}.</dd>
4289 * <dt><b>Scheduler:</b></dt>
4290 * <dd>{@code mergeDelayError} does not operate by default on a particular {@link Scheduler}.</dd>
4291 * </dl>
4292 *
4293 * @param <T> the common element base type
4294 * @param source1
4295 * a {@code Publisher} to be merged
4296 * @param source2
4297 * a {@code Publisher} to be merged
4298 * @param source3
4299 * a {@code Publisher} to be merged
4300 * @return the new {@code Flowable} instance
4301 * @throws NullPointerException if {@code source1}, {@code source2} or {@code source3} is {@code null}
4302 * @see <a href="http://reactivex.io/documentation/operators/merge.html">ReactiveX operators documentation: Merge</a>
4303 */
4304 @SuppressWarnings({ "unchecked", "rawtypes" })
4305 @CheckReturnValue
4306 @NonNull
4307 @BackpressureSupport(BackpressureKind.FULL)
4308 @SchedulerSupport(SchedulerSupport.NONE)
4309 public static <@NonNull T> Flowable<T> mergeDelayError(@NonNull Publisher<? extends T> source1, @NonNull Publisher<? extends T> source2, @NonNull Publisher<? extends T> source3) {
4310 Objects.requireNonNull(source1, "source1 is null");
4311 Objects.requireNonNull(source2, "source2 is null");
4312 Objects.requireNonNull(source3, "source3 is null");
4313 return fromArray(source1, source2, source3).flatMap((Function)Functions.identity(), true, 3);
4314 }
4315
4316 /**
4317 * Flattens four {@link Publisher}s into one {@code Publisher}, in a way that allows a {@link Subscriber} to receive all
4318 * successfully emitted items from all of the source {@code Publisher}s without being interrupted by an error
4319 * notification from one of them.
4320 * <p>
4321 * This behaves like {@link #merge(Publisher, Publisher, Publisher, Publisher)} except that if any of
4322 * the merged {@code Publisher}s notify of an error via {@link Subscriber#onError onError}, {@code mergeDelayError}
4323 * will refrain from propagating that error notification until all of the merged {@code Publisher}s have finished
4324 * emitting items.
4325 * <p>
4326 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/mergeDelayError.v3.png" alt="">
4327 * <p>
4328 * Even if multiple merged {@code Publisher}s send {@code onError} notifications, {@code mergeDelayError} will only
4329 * invoke the {@code onError} method of its {@code Subscriber}s once.
4330 * <dl>
4331 * <dt><b>Backpressure:</b></dt>
4332 * <dd>The operator honors backpressure from downstream. The source {@code Publisher}s are expected to honor
4333 * backpressure; if violated, the operator <em>may</em> signal {@link MissingBackpressureException}.</dd>
4334 * <dt><b>Scheduler:</b></dt>
4335 * <dd>{@code mergeDelayError} does not operate by default on a particular {@link Scheduler}.</dd>
4336 * </dl>
4337 *
4338 * @param <T> the common element base type
4339 * @param source1
4340 * a {@code Publisher} to be merged
4341 * @param source2
4342 * a {@code Publisher} to be merged
4343 * @param source3
4344 * a {@code Publisher} to be merged
4345 * @param source4
4346 * a {@code Publisher} to be merged
4347 * @return the new {@code Flowable} instance
4348 * @throws NullPointerException if {@code source1}, {@code source2}, {@code source3} or {@code source4} is {@code null}
4349 * @see <a href="http://reactivex.io/documentation/operators/merge.html">ReactiveX operators documentation: Merge</a>
4350 */
4351 @SuppressWarnings({ "unchecked", "rawtypes" })
4352 @CheckReturnValue
4353 @NonNull
4354 @BackpressureSupport(BackpressureKind.FULL)
4355 @SchedulerSupport(SchedulerSupport.NONE)
4356 public static <@NonNull T> Flowable<T> mergeDelayError(
4357 @NonNull Publisher<? extends T> source1, @NonNull Publisher<? extends T> source2,
4358 @NonNull Publisher<? extends T> source3, @NonNull Publisher<? extends T> source4) {
4359 Objects.requireNonNull(source1, "source1 is null");
4360 Objects.requireNonNull(source2, "source2 is null");
4361 Objects.requireNonNull(source3, "source3 is null");
4362 Objects.requireNonNull(source4, "source4 is null");
4363 return fromArray(source1, source2, source3, source4).flatMap((Function)Functions.identity(), true, 4);
4364 }
4365
4366 /**
4367 * Returns a {@code Flowable} that never sends any items or notifications to a {@link Subscriber}.
4368 * <p>
4369 * <img width="640" height="185" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/never.v3.png" alt="">
4370 * <p>
4371 * This {@link Publisher} is useful primarily for testing purposes.
4372 * <dl>
4373 * <dt><b>Backpressure:</b></dt>
4374 * <dd>This source doesn't produce any elements and effectively ignores downstream backpressure.</dd>
4375 * <dt><b>Scheduler:</b></dt>
4376 * <dd>{@code never} does not operate by default on a particular {@link Scheduler}.</dd>
4377 * </dl>
4378 *
4379 * @param <T>
4380 * the type of items (not) emitted by the {@code Publisher}
4381 * @return the shared {@code Flowable} instance
4382 * @see <a href="http://reactivex.io/documentation/operators/empty-never-throw.html">ReactiveX operators documentation: Never</a>
4383 */
4384 @CheckReturnValue
4385 @BackpressureSupport(BackpressureKind.PASS_THROUGH)
4386 @SchedulerSupport(SchedulerSupport.NONE)
4387 @SuppressWarnings("unchecked")
4388 @NonNull
4389 public static <@NonNull T> Flowable<T> never() {
4390 return RxJavaPlugins.onAssembly((Flowable<T>) FlowableNever.INSTANCE);
4391 }
4392
4393 /**
4394 * Returns a {@code Flowable} that emits a sequence of {@link Integer}s within a specified range.
4395 * <p>
4396 * <img width="640" height="195" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/range.v3.png" alt="">
4397 * <dl>
4398 * <dt><b>Backpressure:</b></dt>
4399 * <dd>The operator honors backpressure from downstream and signals values on-demand (i.e., when requested).</dd>
4400 * <dt><b>Scheduler:</b></dt>
4401 * <dd>{@code range} does not operate by default on a particular {@link Scheduler}.</dd>
4402 * </dl>
4403 *
4404 * @param start
4405 * the value of the first {@code Integer} in the sequence
4406 * @param count
4407 * the number of sequential {@code Integer}s to generate
4408 * @return the new {@code Flowable} instance
4409 * @throws IllegalArgumentException
4410 * if {@code count} is less than zero, or if {@code start} + {@code count} &minus; 1 exceeds
4411 * {@link Integer#MAX_VALUE}
4412 * @see <a href="http://reactivex.io/documentation/operators/range.html">ReactiveX operators documentation: Range</a>
4413 * @see #rangeLong(long, long)
4414 * @see #intervalRange(long, long, long, long, TimeUnit)
4415 */
4416 @CheckReturnValue
4417 @BackpressureSupport(BackpressureKind.FULL)
4418 @SchedulerSupport(SchedulerSupport.NONE)
4419 @NonNull
4420 public static Flowable<Integer> range(int start, int count) {
4421 if (count < 0) {
4422 throw new IllegalArgumentException("count >= 0 required but it was " + count);
4423 } else
4424 if (count == 0) {
4425 return empty();
4426 } else
4427 if (count == 1) {
4428 return just(start);
4429 } else
4430 if ((long)start + (count - 1) > Integer.MAX_VALUE) {
4431 throw new IllegalArgumentException("Integer overflow");
4432 }
4433 return RxJavaPlugins.onAssembly(new FlowableRange(start, count));
4434 }
4435
4436 /**
4437 * Returns a {@code Flowable} that emits a sequence of {@link Long}s within a specified range.
4438 * <p>
4439 * <img width="640" height="195" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/range.v3.png" alt="">
4440 * <dl>
4441 * <dt><b>Backpressure:</b></dt>
4442 * <dd>The operator honors backpressure from downstream and signals values on-demand (i.e., when requested).</dd>
4443 * <dt><b>Scheduler:</b></dt>
4444 * <dd>{@code rangeLong} does not operate by default on a particular {@link Scheduler}.</dd>
4445 * </dl>
4446 *
4447 * @param start
4448 * the value of the first {@code Long} in the sequence
4449 * @param count
4450 * the number of sequential {@code Long}s to generate
4451 * @return the new {@code Flowable} instance
4452 * @throws IllegalArgumentException
4453 * if {@code count} is less than zero, or if {@code start} + {@code count} &minus; 1 exceeds
4454 * {@link Long#MAX_VALUE}
4455 * @see <a href="http://reactivex.io/documentation/operators/range.html">ReactiveX operators documentation: Range</a>
4456 */
4457 @CheckReturnValue
4458 @BackpressureSupport(BackpressureKind.FULL)
4459 @SchedulerSupport(SchedulerSupport.NONE)
4460 @NonNull
4461 public static Flowable<Long> rangeLong(long start, long count) {
4462 if (count < 0) {
4463 throw new IllegalArgumentException("count >= 0 required but it was " + count);
4464 }
4465
4466 if (count == 0) {
4467 return empty();
4468 }
4469
4470 if (count == 1) {
4471 return just(start);
4472 }
4473
4474 long end = start + (count - 1);
4475 if (start > 0 && end < 0) {
4476 throw new IllegalArgumentException("Overflow! start + count is bigger than Long.MAX_VALUE");
4477 }
4478
4479 return RxJavaPlugins.onAssembly(new FlowableRangeLong(start, count));
4480 }
4481
4482 /**
4483 * Returns a {@link Single} that emits a {@link Boolean} value that indicates whether two {@link Publisher} sequences are the
4484 * same by comparing the items emitted by each {@code Publisher} pairwise.
4485 * <p>
4486 * <img width="640" height="385" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/sequenceEqual.v3.png" alt="">
4487 * <dl>
4488 * <dt><b>Backpressure:</b></dt>
4489 * <dd>This operator honors downstream backpressure and expects both of its sources
4490 * to honor backpressure as well. If violated, the operator will emit a {@link MissingBackpressureException}.</dd>
4491 * <dt><b>Scheduler:</b></dt>
4492 * <dd>{@code sequenceEqual} does not operate by default on a particular {@link Scheduler}.</dd>
4493 * </dl>
4494 *
4495 * @param source1
4496 * the first {@code Publisher} to compare
4497 * @param source2
4498 * the second {@code Publisher} to compare
4499 * @param <T>
4500 * the type of items emitted by each {@code Publisher}
4501 * @return the new {@code Single} instance
4502 * @throws NullPointerException if {@code source1} or {@code source2} is {@code null}
4503 * @see <a href="http://reactivex.io/documentation/operators/sequenceequal.html">ReactiveX operators documentation: SequenceEqual</a>
4504 */
4505 @CheckReturnValue
4506 @BackpressureSupport(BackpressureKind.FULL)
4507 @SchedulerSupport(SchedulerSupport.NONE)
4508 @NonNull
4509 public static <@NonNull T> Single<Boolean> sequenceEqual(@NonNull Publisher<? extends T> source1, @NonNull Publisher<? extends T> source2) {
4510 return sequenceEqual(source1, source2, ObjectHelper.equalsPredicate(), bufferSize());
4511 }
4512
4513 /**
4514 * Returns a {@link Single} that emits a {@link Boolean} value that indicates whether two {@link Publisher} sequences are the
4515 * same by comparing the items emitted by each {@code Publisher} pairwise based on the results of a specified
4516 * equality function.
4517 * <p>
4518 * <img width="640" height="385" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/sequenceEqual.v3.png" alt="">
4519 * <dl>
4520 * <dt><b>Backpressure:</b></dt>
4521 * <dd>The operator honors backpressure from downstream. The source {@code Publisher}s are expected to honor
4522 * backpressure; if violated, the operator signals a {@link MissingBackpressureException}.</dd>
4523 * <dt><b>Scheduler:</b></dt>
4524 * <dd>{@code sequenceEqual} does not operate by default on a particular {@link Scheduler}.</dd>
4525 * </dl>
4526 *
4527 * @param source1
4528 * the first {@code Publisher} to compare
4529 * @param source2
4530 * the second {@code Publisher} to compare
4531 * @param isEqual
4532 * a function used to compare items emitted by each {@code Publisher}
4533 * @param <T>
4534 * the type of items emitted by each {@code Publisher}
4535 * @return the new {@code Single} instance
4536 * @throws NullPointerException if {@code source1}, {@code source2} or {@code isEqual} is {@code null}
4537 * @see <a href="http://reactivex.io/documentation/operators/sequenceequal.html">ReactiveX operators documentation: SequenceEqual</a>
4538 */
4539 @CheckReturnValue
4540 @BackpressureSupport(BackpressureKind.FULL)
4541 @SchedulerSupport(SchedulerSupport.NONE)
4542 @NonNull
4543 public static <@NonNull T> Single<Boolean> sequenceEqual(@NonNull Publisher<? extends T> source1, @NonNull Publisher<? extends T> source2,
4544 @NonNull BiPredicate<? super T, ? super T> isEqual) {
4545 return sequenceEqual(source1, source2, isEqual, bufferSize());
4546 }
4547
4548 /**
4549 * Returns a {@link Single} that emits a {@link Boolean} value that indicates whether two {@link Publisher} sequences are the
4550 * same by comparing the items emitted by each {@code Publisher} pairwise based on the results of a specified
4551 * equality function.
4552 * <p>
4553 * <img width="640" height="385" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/sequenceEqual.v3.png" alt="">
4554 * <dl>
4555 * <dt><b>Backpressure:</b></dt>
4556 * <dd>The operator honors backpressure from downstream. The source {@code Publisher}s are expected to honor
4557 * backpressure; if violated, the operator signals a {@link MissingBackpressureException}.</dd>
4558 * <dt><b>Scheduler:</b></dt>
4559 * <dd>{@code sequenceEqual} does not operate by default on a particular {@link Scheduler}.</dd>
4560 * </dl>
4561 *
4562 * @param source1
4563 * the first {@code Publisher} to compare
4564 * @param source2
4565 * the second {@code Publisher} to compare
4566 * @param isEqual
4567 * a function used to compare items emitted by each {@code Publisher}
4568 * @param bufferSize
4569 * the number of items to prefetch from the first and second source {@code Publisher}
4570 * @param <T>
4571 * the type of items emitted by each {@code Publisher}
4572 * @return the new {@code Single} instance
4573 * @throws NullPointerException if {@code source1}, {@code source2} or {@code isEqual} is {@code null}
4574 * @throws IllegalArgumentException if {@code bufferSize} is non-positive
4575 * @see <a href="http://reactivex.io/documentation/operators/sequenceequal.html">ReactiveX operators documentation: SequenceEqual</a>
4576 */
4577 @CheckReturnValue
4578 @NonNull
4579 @BackpressureSupport(BackpressureKind.FULL)
4580 @SchedulerSupport(SchedulerSupport.NONE)
4581 public static <@NonNull T> Single<Boolean> sequenceEqual(@NonNull Publisher<? extends T> source1, @NonNull Publisher<? extends T> source2,
4582 @NonNull BiPredicate<? super T, ? super T> isEqual, int bufferSize) {
4583 Objects.requireNonNull(source1, "source1 is null");
4584 Objects.requireNonNull(source2, "source2 is null");
4585 Objects.requireNonNull(isEqual, "isEqual is null");
4586 ObjectHelper.verifyPositive(bufferSize, "bufferSize");
4587 return RxJavaPlugins.onAssembly(new FlowableSequenceEqualSingle<>(source1, source2, isEqual, bufferSize));
4588 }
4589
4590 /**
4591 * Returns a {@link Single} that emits a {@link Boolean} value that indicates whether two {@link Publisher} sequences are the
4592 * same by comparing the items emitted by each {@code Publisher} pairwise.
4593 * <p>
4594 * <img width="640" height="385" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/sequenceEqual.v3.png" alt="">
4595 * <dl>
4596 * <dt><b>Backpressure:</b></dt>
4597 * <dd>This operator honors downstream backpressure and expects both of its sources
4598 * to honor backpressure as well. If violated, the operator will emit a {@link MissingBackpressureException}.</dd>
4599 * <dt><b>Scheduler:</b></dt>
4600 * <dd>{@code sequenceEqual} does not operate by default on a particular {@link Scheduler}.</dd>
4601 * </dl>
4602 *
4603 * @param source1
4604 * the first {@code Publisher} to compare
4605 * @param source2
4606 * the second {@code Publisher} to compare
4607 * @param bufferSize
4608 * the number of items to prefetch from the first and second source {@code Publisher}
4609 * @param <T>
4610 * the type of items emitted by each {@code Publisher}
4611 * @return the new {@code Single} instance
4612 * @throws NullPointerException if {@code source1} or {@code source2} is {@code null}
4613 * @throws IllegalArgumentException if {@code bufferSize} is non-positive
4614 * @see <a href="http://reactivex.io/documentation/operators/sequenceequal.html">ReactiveX operators documentation: SequenceEqual</a>
4615 */
4616 @CheckReturnValue
4617 @BackpressureSupport(BackpressureKind.FULL)
4618 @SchedulerSupport(SchedulerSupport.NONE)
4619 @NonNull
4620 public static <@NonNull T> Single<Boolean> sequenceEqual(@NonNull Publisher<? extends T> source1, @NonNull Publisher<? extends T> source2, int bufferSize) {
4621 return sequenceEqual(source1, source2, ObjectHelper.equalsPredicate(), bufferSize);
4622 }
4623
4624 /**
4625 * Converts a {@link Publisher} that emits {@code Publisher}s into a {@code Publisher} that emits the items emitted by the
4626 * most recently emitted of those {@code Publisher}s.
4627 * <p>
4628 * <img width="640" height="370" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/switchDo.v3.png" alt="">
4629 * <p>
4630 * {@code switchOnNext} subscribes to a {@code Publisher} that emits {@code Publisher}s. Each time it observes one of
4631 * these emitted {@code Publisher}s, the {@code Publisher} returned by {@code switchOnNext} begins emitting the items
4632 * emitted by that {@code Publisher}. When a new {@code Publisher} is emitted, {@code switchOnNext} stops emitting items
4633 * from the earlier-emitted {@code Publisher} and begins emitting items from the new one.
4634 * <p>
4635 * The resulting {@code Flowable} completes if both the outer {@code Publisher} and the last inner {@code Publisher}, if any, complete.
4636 * If the outer {@code Publisher} signals an {@code onError}, the inner {@code Publisher} is canceled and the error delivered in-sequence.
4637 * <dl>
4638 * <dt><b>Backpressure:</b></dt>
4639 * <dd>The operator honors backpressure from downstream. The outer {@code Publisher} is consumed in an
4640 * unbounded manner (i.e., without backpressure) and the inner {@code Publisher}s are expected to honor
4641 * backpressure but it is not enforced; the operator won't signal a {@link MissingBackpressureException}
4642 * but the violation <em>may</em> lead to {@link OutOfMemoryError} due to internal buffer bloat.</dd>
4643 * <dt><b>Scheduler:</b></dt>
4644 * <dd>{@code switchOnNext} does not operate by default on a particular {@link Scheduler}.</dd>
4645 * </dl>
4646 *
4647 * @param <T> the item type
4648 * @param sources
4649 * the source {@code Publisher} that emits {@code Publisher}s
4650 * @param bufferSize
4651 * the number of items to prefetch from the inner {@code Publisher}s
4652 * @return the new {@code Flowable} instance
4653 * @throws NullPointerException if {@code sources} is {@code null}
4654 * @throws IllegalArgumentException if {@code bufferSize} is non-positive
4655 * @see <a href="http://reactivex.io/documentation/operators/switch.html">ReactiveX operators documentation: Switch</a>
4656 */
4657 @SuppressWarnings({ "unchecked", "rawtypes" })
4658 @CheckReturnValue
4659 @BackpressureSupport(BackpressureKind.FULL)
4660 @SchedulerSupport(SchedulerSupport.NONE)
4661 @NonNull
4662 public static <@NonNull T> Flowable<T> switchOnNext(@NonNull Publisher<? extends Publisher<? extends T>> sources, int bufferSize) {
4663 return fromPublisher(sources).switchMap((Function)Functions.identity(), bufferSize);
4664 }
4665
4666 /**
4667 * Converts a {@link Publisher} that emits {@code Publisher}s into a {@code Publisher} that emits the items emitted by the
4668 * most recently emitted of those {@code Publisher}s.
4669 * <p>
4670 * <img width="640" height="370" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/switchDo.v3.png" alt="">
4671 * <p>
4672 * {@code switchOnNext} subscribes to a {@code Publisher} that emits {@code Publisher}s. Each time it observes one of
4673 * these emitted {@code Publisher}s, the {@code Publisher} returned by {@code switchOnNext} begins emitting the items
4674 * emitted by that {@code Publisher}. When a new {@code Publisher} is emitted, {@code switchOnNext} stops emitting items
4675 * from the earlier-emitted {@code Publisher} and begins emitting items from the new one.
4676 * <p>
4677 * The resulting {@code Flowable} completes if both the outer {@code Publisher} and the last inner {@code Publisher}, if any, complete.
4678 * If the outer {@code Publisher} signals an {@code onError}, the inner {@code Publisher} is canceled and the error delivered in-sequence.
4679 * <dl>
4680 * <dt><b>Backpressure:</b></dt>
4681 * <dd>The operator honors backpressure from downstream. The outer {@code Publisher} is consumed in an
4682 * unbounded manner (i.e., without backpressure) and the inner {@code Publisher}s are expected to honor
4683 * backpressure but it is not enforced; the operator won't signal a {@link MissingBackpressureException}
4684 * but the violation <em>may</em> lead to {@link OutOfMemoryError} due to internal buffer bloat.</dd>
4685 * <dt><b>Scheduler:</b></dt>
4686 * <dd>{@code switchOnNext} does not operate by default on a particular {@link Scheduler}.</dd>
4687 * </dl>
4688 *
4689 * @param <T> the item type
4690 * @param sources
4691 * the source {@code Publisher} that emits {@code Publisher}s
4692 * @return the new {@code Flowable} instance
4693 * @throws NullPointerException if {@code sources} is {@code null}
4694 * @see <a href="http://reactivex.io/documentation/operators/switch.html">ReactiveX operators documentation: Switch</a>
4695 */
4696 @SuppressWarnings({ "unchecked", "rawtypes" })
4697 @CheckReturnValue
4698 @BackpressureSupport(BackpressureKind.FULL)
4699 @SchedulerSupport(SchedulerSupport.NONE)
4700 @NonNull
4701 public static <@NonNull T> Flowable<T> switchOnNext(@NonNull Publisher<@NonNull ? extends Publisher<? extends T>> sources) {
4702 return fromPublisher(sources).switchMap((Function)Functions.identity());
4703 }
4704
4705 /**
4706 * Converts a {@link Publisher} that emits {@code Publisher}s into a {@code Publisher} that emits the items emitted by the
4707 * most recently emitted of those {@code Publisher}s and delays any exception until all {@code Publisher}s terminate.
4708 * <p>
4709 * <img width="640" height="370" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/switchDo.v3.png" alt="">
4710 * <p>
4711 * {@code switchOnNext} subscribes to a {@code Publisher} that emits {@code Publisher}s. Each time it observes one of
4712 * these emitted {@code Publisher}s, the {@code Publisher} returned by {@code switchOnNext} begins emitting the items
4713 * emitted by that {@code Publisher}. When a new {@code Publisher} is emitted, {@code switchOnNext} stops emitting items
4714 * from the earlier-emitted {@code Publisher} and begins emitting items from the new one.
4715 * <p>
4716 * The resulting {@code Flowable} completes if both the main {@code Publisher} and the last inner {@code Publisher}, if any, complete.
4717 * If the main {@code Publisher} signals an {@code onError}, the termination of the last inner {@code Publisher} will emit that error as is
4718 * or wrapped into a {@link CompositeException} along with the other possible errors the former inner {@code Publisher}s signaled.
4719 * <dl>
4720 * <dt><b>Backpressure:</b></dt>
4721 * <dd>The operator honors backpressure from downstream. The outer {@code Publisher} is consumed in an
4722 * unbounded manner (i.e., without backpressure) and the inner {@code Publisher}s are expected to honor
4723 * backpressure but it is not enforced; the operator won't signal a {@link MissingBackpressureException}
4724 * but the violation <em>may</em> lead to {@link OutOfMemoryError} due to internal buffer bloat.</dd>
4725 * <dt><b>Scheduler:</b></dt>
4726 * <dd>{@code switchOnNextDelayError} does not operate by default on a particular {@link Scheduler}.</dd>
4727 * </dl>
4728 *
4729 * @param <T> the item type
4730 * @param sources
4731 * the source {@code Publisher} that emits {@code Publisher}s
4732 * @return the new {@code Flowable} instance
4733 * @throws NullPointerException if {@code sources} is {@code null}
4734 * @see <a href="http://reactivex.io/documentation/operators/switch.html">ReactiveX operators documentation: Switch</a>
4735 * @since 2.0
4736 */
4737 @CheckReturnValue
4738 @BackpressureSupport(BackpressureKind.FULL)
4739 @SchedulerSupport(SchedulerSupport.NONE)
4740 @NonNull
4741 public static <@NonNull T> Flowable<T> switchOnNextDelayError(@NonNull Publisher<@NonNull ? extends Publisher<? extends T>> sources) {
4742 return switchOnNextDelayError(sources, bufferSize());
4743 }
4744
4745 /**
4746 * Converts a {@link Publisher} that emits {@code Publisher}s into a {@code Publisher} that emits the items emitted by the
4747 * most recently emitted of those {@code Publisher}s and delays any exception until all {@code Publisher}s terminate.
4748 * <p>
4749 * <img width="640" height="370" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/switchDo.v3.png" alt="">
4750 * <p>
4751 * {@code switchOnNext} subscribes to a {@code Publisher} that emits {@code Publisher}s. Each time it observes one of
4752 * these emitted {@code Publisher}s, the {@code Publisher} returned by {@code switchOnNext} begins emitting the items
4753 * emitted by that {@code Publisher}. When a new {@code Publisher} is emitted, {@code switchOnNext} stops emitting items
4754 * from the earlier-emitted {@code Publisher} and begins emitting items from the new one.
4755 * <p>
4756 * The resulting {@code Flowable} completes if both the main {@code Publisher} and the last inner {@code Publisher}, if any, complete.
4757 * If the main {@code Publisher} signals an {@code onError}, the termination of the last inner {@code Publisher} will emit that error as is
4758 * or wrapped into a {@link CompositeException} along with the other possible errors the former inner {@code Publisher}s signaled.
4759 * <dl>
4760 * <dt><b>Backpressure:</b></dt>
4761 * <dd>The operator honors backpressure from downstream. The outer {@code Publisher} is consumed in an
4762 * unbounded manner (i.e., without backpressure) and the inner {@code Publisher}s are expected to honor
4763 * backpressure but it is not enforced; the operator won't signal a {@link MissingBackpressureException}
4764 * but the violation <em>may</em> lead to {@link OutOfMemoryError} due to internal buffer bloat.</dd>
4765 * <dt><b>Scheduler:</b></dt>
4766 * <dd>{@code switchOnNextDelayError} does not operate by default on a particular {@link Scheduler}.</dd>
4767 * </dl>
4768 *
4769 * @param <T> the item type
4770 * @param sources
4771 * the source {@code Publisher} that emits {@code Publisher}s
4772 * @param prefetch
4773 * the number of items to prefetch from the inner {@code Publisher}s
4774 * @return the new {@code Flowable} instance
4775 * @throws NullPointerException if {@code sources} is {@code null}
4776 * @throws IllegalArgumentException if {@code prefetch} is non-positive
4777 * @see <a href="http://reactivex.io/documentation/operators/switch.html">ReactiveX operators documentation: Switch</a>
4778 * @since 2.0
4779 */
4780 @CheckReturnValue
4781 @BackpressureSupport(BackpressureKind.FULL)
4782 @SchedulerSupport(SchedulerSupport.NONE)
4783 @NonNull
4784 public static <@NonNull T> Flowable<T> switchOnNextDelayError(@NonNull Publisher<@NonNull ? extends Publisher<? extends T>> sources, int prefetch) {
4785 return fromPublisher(sources).switchMapDelayError(Functions.<Publisher<? extends T>>identity(), prefetch);
4786 }
4787
4788 /**
4789 * Returns a {@code Flowable} that emits {@code 0L} after a specified delay, and then completes.
4790 * <p>
4791 * <img width="640" height="200" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/timer.v3.png" alt="">
4792 * <dl>
4793 * <dt><b>Backpressure:</b></dt>
4794 * <dd>This operator does not support backpressure as it uses time. If the downstream needs a slower rate
4795 * it should slow the timer or use something like {@link #onBackpressureDrop}.</dd>
4796 * <dt><b>Scheduler:</b></dt>
4797 * <dd>{@code timer} operates by default on the {@code computation} {@link Scheduler}.</dd>
4798 * </dl>
4799 *
4800 * @param delay
4801 * the initial delay before emitting a single {@code 0L}
4802 * @param unit
4803 * time units to use for {@code delay}
4804 * @return the new {@code Flowable} instance
4805 * @throws NullPointerException if {@code unit} is {@code null}
4806 * @see <a href="http://reactivex.io/documentation/operators/timer.html">ReactiveX operators documentation: Timer</a>
4807 */
4808 @CheckReturnValue
4809 @BackpressureSupport(BackpressureKind.ERROR)
4810 @SchedulerSupport(SchedulerSupport.COMPUTATION)
4811 @NonNull
4812 public static Flowable<Long> timer(long delay, @NonNull TimeUnit unit) {
4813 return timer(delay, unit, Schedulers.computation());
4814 }
4815
4816 /**
4817 * Returns a {@code Flowable} that emits {@code 0L} after a specified delay, on a specified {@link Scheduler}, and then
4818 * completes.
4819 * <p>
4820 * <img width="640" height="200" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/timer.s.v3.png" alt="">
4821 * <dl>
4822 * <dt><b>Backpressure:</b></dt>
4823 * <dd>This operator does not support backpressure as it uses time. If the downstream needs a slower rate
4824 * it should slow the timer or use something like {@link #onBackpressureDrop}.</dd>
4825 * <dt><b>Scheduler:</b></dt>
4826 * <dd>You specify which {@code Scheduler} this operator will use.</dd>
4827 * </dl>
4828 *
4829 * @param delay
4830 * the initial delay before emitting a single 0L
4831 * @param unit
4832 * time units to use for {@code delay}
4833 * @param scheduler
4834 * the {@code Scheduler} to use for scheduling the item
4835 * @return the new {@code Flowable} instance
4836 * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null}
4837 * @see <a href="http://reactivex.io/documentation/operators/timer.html">ReactiveX operators documentation: Timer</a>
4838 */
4839 @CheckReturnValue
4840 @NonNull
4841 @BackpressureSupport(BackpressureKind.ERROR)
4842 @SchedulerSupport(SchedulerSupport.CUSTOM)
4843 public static Flowable<Long> timer(long delay, @NonNull TimeUnit unit, @NonNull Scheduler scheduler) {
4844 Objects.requireNonNull(unit, "unit is null");
4845 Objects.requireNonNull(scheduler, "scheduler is null");
4846
4847 return RxJavaPlugins.onAssembly(new FlowableTimer(Math.max(0L, delay), unit, scheduler));
4848 }
4849
4850 /**
4851 * Create a {@code Flowable} by wrapping a {@link Publisher} <em>which has to be implemented according
4852 * to the <b>Reactive Streams</b> specification by handling backpressure and
4853 * cancellation correctly; no safeguards are provided by the {@code Flowable} itself</em>.
4854 * <dl>
4855 * <dt><b>Backpressure:</b></dt>
4856 * <dd>This operator is a pass-through for backpressure and the behavior is determined by the
4857 * provided {@code Publisher} implementation.</dd>
4858 * <dt><b>Scheduler:</b></dt>
4859 * <dd>{@code unsafeCreate} by default doesn't operate on any particular {@link Scheduler}.</dd>
4860 * </dl>
4861 * @param <T> the value type emitted
4862 * @param onSubscribe the {@code Publisher} instance to wrap
4863 * @return the new {@code Flowable} instance
4864 * @throws NullPointerException if {@code onSubscribe} is {@code null}
4865 * @throws IllegalArgumentException if {@code onSubscribe} is a subclass of {@code Flowable}; such
4866 * instances don't need conversion and is possibly a port remnant from 1.x or one should use {@link #hide()}
4867 * instead.
4868 */
4869 @CheckReturnValue
4870 @NonNull
4871 @BackpressureSupport(BackpressureKind.NONE)
4872 @SchedulerSupport(SchedulerSupport.NONE)
4873 public static <@NonNull T> Flowable<T> unsafeCreate(@NonNull Publisher<T> onSubscribe) {
4874 Objects.requireNonNull(onSubscribe, "onSubscribe is null");
4875 if (onSubscribe instanceof Flowable) {
4876 throw new IllegalArgumentException("unsafeCreate(Flowable) should be upgraded");
4877 }
4878 return RxJavaPlugins.onAssembly(new FlowableFromPublisher<>(onSubscribe));
4879 }
4880
4881 /**
4882 * Constructs a {@code Flowable} that creates a dependent resource object, a {@link Publisher} with
4883 * that resource and calls the provided {@code resourceDisposer} function if this inner source terminates or the
4884 * downstream cancels the flow.
4885 * <p>
4886 * <img width="640" height="400" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/using.v3.png" alt="">
4887 * <dl>
4888 * <dt><b>Backpressure:</b></dt>
4889 * <dd>The operator is a pass-through for backpressure and otherwise depends on the
4890 * backpressure support of the {@code Publisher} returned by the {@code resourceFactory}.</dd>
4891 * <dt><b>Scheduler:</b></dt>
4892 * <dd>{@code using} does not operate by default on a particular {@link Scheduler}.</dd>
4893 * </dl>
4894 *
4895 * @param <T> the element type of the generated {@code Publisher}
4896 * @param <D> the type of the resource associated with the output sequence
4897 * @param resourceSupplier
4898 * the factory function to create a resource object that depends on the {@code Publisher}
4899 * @param sourceSupplier
4900 * the factory function to create a {@code Publisher}
4901 * @param resourceCleanup
4902 * the function that will dispose of the resource
4903 * @return the new {@code Flowable} instance
4904 * @throws NullPointerException if {@code resourceSupplier}, {@code sourceSupplier} or {@code resourceCleanup} is {@code null}
4905 * @see <a href="http://reactivex.io/documentation/operators/using.html">ReactiveX operators documentation: Using</a>
4906 */
4907 @CheckReturnValue
4908 @BackpressureSupport(BackpressureKind.PASS_THROUGH)
4909 @SchedulerSupport(SchedulerSupport.NONE)
4910 @NonNull
4911 public static <@NonNull T, @NonNull D> Flowable<T> using(
4912 @NonNull Supplier<? extends D> resourceSupplier,
4913 @NonNull Function<? super D, @NonNull ? extends Publisher<? extends T>> sourceSupplier,
4914 @NonNull Consumer<? super D> resourceCleanup) {
4915 return using(resourceSupplier, sourceSupplier, resourceCleanup, true);
4916 }
4917
4918 /**
4919 * Constructs a {@code Flowable} that creates a dependent resource object, a {@link Publisher} with
4920 * that resource and calls the provided {@code resourceDisposer} function if this inner source terminates or the
4921 * downstream disposes the flow; doing it before these end-states have been reached if {@code eager == true}, after otherwise.
4922 * <p>
4923 * <img width="640" height="400" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/using.v3.png" alt="">
4924 * <dl>
4925 * <dt><b>Backpressure:</b></dt>
4926 * <dd>The operator is a pass-through for backpressure and otherwise depends on the
4927 * backpressure support of the {@code Publisher} returned by the {@code resourceFactory}.</dd>
4928 * <dt><b>Scheduler:</b></dt>
4929 * <dd>{@code using} does not operate by default on a particular {@link Scheduler}.</dd>
4930 * </dl>
4931 *
4932 * @param <T> the element type of the generated {@code Publisher}
4933 * @param <D> the type of the resource associated with the output sequence
4934 * @param resourceSupplier
4935 * the factory function to create a resource object that depends on the {@code Publisher}
4936 * @param sourceSupplier
4937 * the factory function to create a {@code Publisher}
4938 * @param resourceCleanup
4939 * the function that will dispose of the resource
4940 * @param eager
4941 * If {@code true}, the resource disposal will happen either on a {@code cancel()} call before the upstream is disposed
4942 * or just before the emission of a terminal event ({@code onComplete} or {@code onError}).
4943 * If {@code false} the resource disposal will happen either on a {@code cancel()} call after the upstream is disposed
4944 * or just after the emission of a terminal event ({@code onComplete} or {@code onError}).
4945 * @return the new {@code Flowable} instance
4946 * @throws NullPointerException if {@code resourceSupplier}, {@code sourceSupplier} or {@code resourceCleanup} is {@code null}
4947 * @see <a href="http://reactivex.io/documentation/operators/using.html">ReactiveX operators documentation: Using</a>
4948 * @since 2.0
4949 */
4950 @CheckReturnValue
4951 @NonNull
4952 @BackpressureSupport(BackpressureKind.PASS_THROUGH)
4953 @SchedulerSupport(SchedulerSupport.NONE)
4954 public static <@NonNull T, @NonNull D> Flowable<T> using(
4955 @NonNull Supplier<? extends D> resourceSupplier,
4956 @NonNull Function<? super D, @NonNull ? extends Publisher<? extends T>> sourceSupplier,
4957 @NonNull Consumer<? super D> resourceCleanup,
4958 boolean eager) {
4959 Objects.requireNonNull(resourceSupplier, "resourceSupplier is null");
4960 Objects.requireNonNull(sourceSupplier, "sourceSupplier is null");
4961 Objects.requireNonNull(resourceCleanup, "resourceCleanup is null");
4962 return RxJavaPlugins.onAssembly(new FlowableUsing<T, D>(resourceSupplier, sourceSupplier, resourceCleanup, eager));
4963 }
4964
4965 /**
4966 * Returns a {@code Flowable} that emits the results of a specified combiner function applied to combinations of
4967 * items emitted, in sequence, by an {@link Iterable} of other {@link Publisher}s.
4968 * <p>
4969 * {@code zip} applies this function in strict sequence, so the first item emitted by the new {@code Publisher}
4970 * will be the result of the function applied to the first item emitted by each of the source {@code Publisher}s;
4971 * the second item emitted by the new {@code Publisher} will be the result of the function applied to the second
4972 * item emitted by each of those {@code Publisher}s; and so forth.
4973 * <p>
4974 * The resulting {@code Flowable} returned from {@code zip} will invoke {@code onNext} as many times as
4975 * the number of {@code onNext} invocations of the source {@code Publisher} that emits the fewest items.
4976 * <p>
4977 * The operator subscribes to its sources in the order they are specified and completes eagerly if
4978 * one of the sources is shorter than the rest while canceling the other sources. Therefore, it
4979 * is possible those other sources will never be able to run to completion (and thus not calling
4980 * {@code doOnComplete()}). This can also happen if the sources are exactly the same length; if
4981 * source A completes and B has been consumed and is about to complete, the operator detects A won't
4982 * be sending further values and it will cancel B immediately. For example:
4983 * <pre><code>zip(Arrays.asList(range(1, 5).doOnComplete(action1), range(6, 5).doOnComplete(action2)), (a) -&gt; a)</code></pre>
4984 * {@code action1} will be called but {@code action2} won't.
4985 * <br>To work around this termination property,
4986 * use {@link #doOnCancel(Action)} as well or use {@code using()} to do cleanup in case of completion
4987 * or cancellation.
4988 * <p>
4989 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/zip.v3.png" alt="">
4990 * <dl>
4991 * <dt><b>Backpressure:</b></dt>
4992 * <dd>The operator expects backpressure from the sources and honors backpressure from the downstream.
4993 * (I.e., zipping with {@link #interval(long, TimeUnit)} may result in {@link MissingBackpressureException}, use
4994 * one of the {@code onBackpressureX} to handle similar, backpressure-ignoring sources.</dd>
4995 * <dt><b>Scheduler:</b></dt>
4996 * <dd>{@code zip} does not operate by default on a particular {@link Scheduler}.</dd>
4997 * </dl>
4998 *
4999 * @param <T> the common value type
5000 * @param <R> the zipped result type
5001 * @param sources
5002 * an {@code Iterable} of source {@code Publisher}s
5003 * @param zipper
5004 * a function that, when applied to an item emitted by each of the source {@code Publisher}s, results in
5005 * an item that will be emitted by the resulting {@code Flowable}
5006 * @return the new {@code Flowable} instance
5007 * @throws NullPointerException if {@code sources} or {@code zipper} is {@code null}
5008 * @see <a href="http://reactivex.io/documentation/operators/zip.html">ReactiveX operators documentation: Zip</a>
5009 */
5010 @CheckReturnValue
5011 @NonNull
5012 @BackpressureSupport(BackpressureKind.FULL)
5013 @SchedulerSupport(SchedulerSupport.NONE)
5014 public static <@NonNull T, @NonNull R> Flowable<R> zip(@NonNull Iterable<@NonNull ? extends Publisher<? extends T>> sources, @NonNull Function<? super Object[], ? extends R> zipper) {
5015 Objects.requireNonNull(zipper, "zipper is null");
5016 Objects.requireNonNull(sources, "sources is null");
5017 return RxJavaPlugins.onAssembly(new FlowableZip<>(null, sources, zipper, bufferSize(), false));
5018 }
5019
5020 /**
5021 * Returns a {@code Flowable} that emits the results of a specified combiner function applied to combinations of
5022 * items emitted, in sequence, by an {@link Iterable} of other {@link Publisher}s.
5023 * <p>
5024 * {@code zip} applies this function in strict sequence, so the first item emitted by the new {@code Publisher}
5025 * will be the result of the function applied to the first item emitted by each of the source {@code Publisher}s;
5026 * the second item emitted by the new {@code Publisher} will be the result of the function applied to the second
5027 * item emitted by each of those {@code Publisher}s; and so forth.
5028 * <p>
5029 * The resulting {@code Floawble} returned from {@code zip} will invoke {@code onNext} as many times as
5030 * the number of {@code onNext} invocations of the source {@code Publisher} that emits the fewest items.
5031 * <p>
5032 * The operator subscribes to its sources in the order they are specified and completes eagerly if
5033 * one of the sources is shorter than the rest while canceling the other sources. Therefore, it
5034 * is possible those other sources will never be able to run to completion (and thus not calling
5035 * {@code doOnComplete()}). This can also happen if the sources are exactly the same length; if
5036 * source A completes and B has been consumed and is about to complete, the operator detects A won't
5037 * be sending further values and it will cancel B immediately. For example:
5038 * <pre><code>zip(Arrays.asList(range(1, 5).doOnComplete(action1), range(6, 5).doOnComplete(action2)), (a) -&gt; a)</code></pre>
5039 * {@code action1} will be called but {@code action2} won't.
5040 * <br>To work around this termination property,
5041 * use {@link #doOnCancel(Action)} as well or use {@code using()} to do cleanup in case of completion
5042 * or cancellation.
5043 * <p>
5044 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/zip.v3.png" alt="">
5045 * <dl>
5046 * <dt><b>Backpressure:</b></dt>
5047 * <dd>The operator expects backpressure from the sources and honors backpressure from the downstream.
5048 * (I.e., zipping with {@link #interval(long, TimeUnit)} may result in {@link MissingBackpressureException}, use
5049 * one of the {@code onBackpressureX} to handle similar, backpressure-ignoring sources.</dd>
5050 * <dt><b>Scheduler:</b></dt>
5051 * <dd>{@code zip} does not operate by default on a particular {@link Scheduler}.</dd>
5052 * </dl>
5053 *
5054 *
5055 * @param sources
5056 * an {@code Iterable} of source {@code Publisher}s
5057 * @param zipper
5058 * a function that, when applied to an item emitted by each of the source {@code Publisher}s, results in
5059 * an item that will be emitted by the resulting {@code Flowable}
5060 * @param delayError
5061 * delay errors signaled by any of the source {@code Publisher} until all {@code Publisher}s terminate
5062 * @param bufferSize
5063 * the number of elements to prefetch from each source {@code Publisher}
5064 * @param <T> the common source value type
5065 * @param <R> the zipped result type
5066 * @return the new {@code Flowable} instance
5067 * @throws NullPointerException if {@code sources} or {@code zipper} is {@code null}
5068 * @throws IllegalArgumentException if {@code bufferSize} is non-positive
5069 * @see <a href="http://reactivex.io/documentation/operators/zip.html">ReactiveX operators documentation: Zip</a>
5070 */
5071 @CheckReturnValue
5072 @NonNull
5073 @BackpressureSupport(BackpressureKind.FULL)
5074 @SchedulerSupport(SchedulerSupport.NONE)
5075 public static <@NonNull T, @NonNull R> Flowable<R> zip(@NonNull Iterable<@NonNull ? extends Publisher<? extends T>> sources,
5076 @NonNull Function<? super Object[], ? extends R> zipper, boolean delayError,
5077 int bufferSize) {
5078 Objects.requireNonNull(zipper, "zipper is null");
5079 Objects.requireNonNull(sources, "sources is null");
5080 ObjectHelper.verifyPositive(bufferSize, "bufferSize");
5081 return RxJavaPlugins.onAssembly(new FlowableZip<>(null, sources, zipper, bufferSize, delayError));
5082 }
5083
5084 /**
5085 * Returns a {@code Flowable} that emits the results of a specified combiner function applied to combinations of
5086 * two items emitted, in sequence, by two other {@link Publisher}s.
5087 * <p>
5088 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/zip.v3.png" alt="">
5089 * <p>
5090 * {@code zip} applies this function in strict sequence, so the first item emitted by the new {@code Publisher}
5091 * will be the result of the function applied to the first item emitted by {@code o1} and the first item
5092 * emitted by {@code o2}; the second item emitted by the new {@code Publisher} will be the result of the function
5093 * applied to the second item emitted by {@code o1} and the second item emitted by {@code o2}; and so forth.
5094 * <p>
5095 * The resulting {@code Flowable} returned from {@code zip} will invoke {@link Subscriber#onNext onNext}
5096 * as many times as the number of {@code onNext} invocations of the source {@code Publisher} that emits the fewest
5097 * items.
5098 * <p>
5099 * The operator subscribes to its sources in the order they are specified and completes eagerly if
5100 * one of the sources is shorter than the rest while canceling the other sources. Therefore, it
5101 * is possible those other sources will never be able to run to completion (and thus not calling
5102 * {@code doOnComplete()}). This can also happen if the sources are exactly the same length; if
5103 * source A completes and B has been consumed and is about to complete, the operator detects A won't
5104 * be sending further values and it will cancel B immediately. For example:
5105 * <pre><code>zip(range(1, 5).doOnComplete(action1), range(6, 5).doOnComplete(action2), (a, b) -&gt; a + b)</code></pre>
5106 * {@code action1} will be called but {@code action2} won't.
5107 * <br>To work around this termination property,
5108 * use {@link #doOnCancel(Action)} as well or use {@code using()} to do cleanup in case of completion
5109 * or cancellation.
5110 * <dl>
5111 * <dt><b>Backpressure:</b></dt>
5112 * <dd>The operator expects backpressure from the sources and honors backpressure from the downstream.
5113 * (I.e., zipping with {@link #interval(long, TimeUnit)} may result in {@link MissingBackpressureException}, use
5114 * one of the {@code onBackpressureX} to handle similar, backpressure-ignoring sources.</dd>
5115 * <dt><b>Scheduler:</b></dt>
5116 * <dd>{@code zip} does not operate by default on a particular {@link Scheduler}.</dd>
5117 * </dl>
5118 *
5119 * @param <T1> the value type of the first source
5120 * @param <T2> the value type of the second source
5121 * @param <R> the zipped result type
5122 * @param source1
5123 * the first source {@code Publisher}
5124 * @param source2
5125 * a second source {@code Publisher}
5126 * @param zipper
5127 * a function that, when applied to an item emitted by each of the source {@code Publisher}s, results
5128 * in an item that will be emitted by the resulting {@code Flowable}
5129 * @return the new {@code Flowable} instance
5130 * @throws NullPointerException if {@code source1}, {@code source2} or {@code zipper} is {@code null}
5131 * @see <a href="http://reactivex.io/documentation/operators/zip.html">ReactiveX operators documentation: Zip</a>
5132 */
5133 @CheckReturnValue
5134 @NonNull
5135 @BackpressureSupport(BackpressureKind.FULL)
5136 @SchedulerSupport(SchedulerSupport.NONE)
5137 public static <@NonNull T1, @NonNull T2, @NonNull R> Flowable<R> zip(
5138 @NonNull Publisher<? extends T1> source1, @NonNull Publisher<? extends T2> source2,
5139 @NonNull BiFunction<? super T1, ? super T2, ? extends R> zipper) {
5140 Objects.requireNonNull(source1, "source1 is null");
5141 Objects.requireNonNull(source2, "source2 is null");
5142 Objects.requireNonNull(zipper, "zipper is null");
5143 return zipArray(Functions.toFunction(zipper), false, bufferSize(), source1, source2);
5144 }
5145
5146 /**
5147 * Returns a {@code Flowable} that emits the results of a specified combiner function applied to combinations of
5148 * two items emitted, in sequence, by two other {@link Publisher}s.
5149 * <p>
5150 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/zip.v3.png" alt="">
5151 * <p>
5152 * {@code zip} applies this function in strict sequence, so the first item emitted by the new {@code Publisher}
5153 * will be the result of the function applied to the first item emitted by {@code o1} and the first item
5154 * emitted by {@code o2}; the second item emitted by the new {@code Publisher} will be the result of the function
5155 * applied to the second item emitted by {@code o1} and the second item emitted by {@code o2}; and so forth.
5156 * <p>
5157 * The resulting {@code Flowable} returned from {@code zip} will invoke {@link Subscriber#onNext onNext}
5158 * as many times as the number of {@code onNext} invocations of the source {@code Publisher} that emits the fewest
5159 * items.
5160 * <p>
5161 * The operator subscribes to its sources in the order they are specified and completes eagerly if
5162 * one of the sources is shorter than the rest while canceling the other sources. Therefore, it
5163 * is possible those other sources will never be able to run to completion (and thus not calling
5164 * {@code doOnComplete()}). This can also happen if the sources are exactly the same length; if
5165 * source A completes and B has been consumed and is about to complete, the operator detects A won't
5166 * be sending further values and it will cancel B immediately. For example:
5167 * <pre><code>zip(range(1, 5).doOnComplete(action1), range(6, 5).doOnComplete(action2), (a, b) -&gt; a + b)</code></pre>
5168 * {@code action1} will be called but {@code action2} won't.
5169 * <br>To work around this termination property,
5170 * use {@link #doOnCancel(Action)} as well or use {@code using()} to do cleanup in case of completion
5171 * or cancellation.
5172 * <dl>
5173 * <dt><b>Backpressure:</b></dt>
5174 * <dd>The operator expects backpressure from the sources and honors backpressure from the downstream.
5175 * (I.e., zipping with {@link #interval(long, TimeUnit)} may result in {@link MissingBackpressureException}, use
5176 * one of the {@code onBackpressureX} to handle similar, backpressure-ignoring sources.</dd>
5177 * <dt><b>Scheduler:</b></dt>
5178 * <dd>{@code zip} does not operate by default on a particular {@link Scheduler}.</dd>
5179 * </dl>
5180 *
5181 * @param <T1> the value type of the first source
5182 * @param <T2> the value type of the second source
5183 * @param <R> the zipped result type
5184 * @param source1
5185 * the first source {@code Publisher}
5186 * @param source2
5187 * a second source {@code Publisher}
5188 * @param zipper
5189 * a function that, when applied to an item emitted by each of the source {@code Publisher}s, results
5190 * in an item that will be emitted by the resulting {@code Flowable}
5191 * @param delayError delay errors from any of the source {@code Publisher}s till the other terminates
5192 * @return the new {@code Flowable} instance
5193 * @throws NullPointerException if {@code source1}, {@code source2} or {@code zipper} is {@code null}
5194 * @see <a href="http://reactivex.io/documentation/operators/zip.html">ReactiveX operators documentation: Zip</a>
5195 */
5196 @CheckReturnValue
5197 @NonNull
5198 @BackpressureSupport(BackpressureKind.FULL)
5199 @SchedulerSupport(SchedulerSupport.NONE)
5200 public static <@NonNull T1, @NonNull T2, @NonNull R> Flowable<R> zip(
5201 @NonNull Publisher<? extends T1> source1, @NonNull Publisher<? extends T2> source2,
5202 @NonNull BiFunction<? super T1, ? super T2, ? extends R> zipper, boolean delayError) {
5203 Objects.requireNonNull(source1, "source1 is null");
5204 Objects.requireNonNull(source2, "source2 is null");
5205 Objects.requireNonNull(zipper, "zipper is null");
5206 return zipArray(Functions.toFunction(zipper), delayError, bufferSize(), source1, source2);
5207 }
5208
5209 /**
5210 * Returns a {@code Flowable} that emits the results of a specified combiner function applied to combinations of
5211 * two items emitted, in sequence, by two other {@link Publisher}s.
5212 * <p>
5213 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/zip.v3.png" alt="">
5214 * <p>
5215 * {@code zip} applies this function in strict sequence, so the first item emitted by the new {@code Publisher}
5216 * will be the result of the function applied to the first item emitted by {@code o1} and the first item
5217 * emitted by {@code o2}; the second item emitted by the new {@code Publisher} will be the result of the function
5218 * applied to the second item emitted by {@code o1} and the second item emitted by {@code o2}; and so forth.
5219 * <p>
5220 * The resulting {@code Flowable} returned from {@code zip} will invoke {@link Subscriber#onNext onNext}
5221 * as many times as the number of {@code onNext} invocations of the source {@code Publisher} that emits the fewest
5222 * items.
5223 * <p>
5224 * The operator subscribes to its sources in the order they are specified and completes eagerly if
5225 * one of the sources is shorter than the rest while canceling the other sources. Therefore, it
5226 * is possible those other sources will never be able to run to completion (and thus not calling
5227 * {@code doOnComplete()}). This can also happen if the sources are exactly the same length; if
5228 * source A completes and B has been consumed and is about to complete, the operator detects A won't
5229 * be sending further values and it will cancel B immediately. For example:
5230 * <pre><code>zip(range(1, 5).doOnComplete(action1), range(6, 5).doOnComplete(action2), (a, b) -&gt; a + b)</code></pre>
5231 * {@code action1} will be called but {@code action2} won't.
5232 * <br>To work around this termination property,
5233 * use {@link #doOnCancel(Action)} as well or use {@code using()} to do cleanup in case of completion
5234 * or cancellation.
5235 * <dl>
5236 * <dt><b>Backpressure:</b></dt>
5237 * <dd>The operator expects backpressure from the sources and honors backpressure from the downstream.
5238 * (I.e., zipping with {@link #interval(long, TimeUnit)} may result in {@link MissingBackpressureException}, use
5239 * one of the {@code onBackpressureX} to handle similar, backpressure-ignoring sources.</dd>
5240 * <dt><b>Scheduler:</b></dt>
5241 * <dd>{@code zip} does not operate by default on a particular {@link Scheduler}.</dd>
5242 * </dl>
5243 *
5244 * @param <T1> the value type of the first source
5245 * @param <T2> the value type of the second source
5246 * @param <R> the zipped result type
5247 * @param source1
5248 * the first source {@code Publisher}
5249 * @param source2
5250 * a second source {@code Publisher}
5251 * @param zipper
5252 * a function that, when applied to an item emitted by each of the source {@code Publisher}s, results
5253 * in an item that will be emitted by the resulting {@code Flowable}
5254 * @param delayError delay errors from any of the source {@code Publisher}s till the other terminates
5255 * @param bufferSize the number of elements to prefetch from each source {@code Publisher}
5256 * @return the new {@code Flowable} instance
5257 * @throws NullPointerException if {@code source1}, {@code source2} or {@code zipper} is {@code null}
5258 * @throws IllegalArgumentException if {@code bufferSize} is non-positive
5259 * @see <a href="http://reactivex.io/documentation/operators/zip.html">ReactiveX operators documentation: Zip</a>
5260 */
5261 @CheckReturnValue
5262 @NonNull
5263 @BackpressureSupport(BackpressureKind.FULL)
5264 @SchedulerSupport(SchedulerSupport.NONE)
5265 public static <@NonNull T1, @NonNull T2, @NonNull R> Flowable<R> zip(
5266 @NonNull Publisher<? extends T1> source1, @NonNull Publisher<? extends T2> source2,
5267 @NonNull BiFunction<? super T1, ? super T2, ? extends R> zipper, boolean delayError, int bufferSize) {
5268 Objects.requireNonNull(source1, "source1 is null");
5269 Objects.requireNonNull(source2, "source2 is null");
5270 Objects.requireNonNull(zipper, "zipper is null");
5271 return zipArray(Functions.toFunction(zipper), delayError, bufferSize, source1, source2);
5272 }
5273
5274 /**
5275 * Returns a {@code Flowable} that emits the results of a specified combiner function applied to combinations of
5276 * three items emitted, in sequence, by three other {@link Publisher}s.
5277 * <p>
5278 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/zip.v3.png" alt="">
5279 * <p>
5280 * {@code zip} applies this function in strict sequence, so the first item emitted by the new {@code Publisher}
5281 * will be the result of the function applied to the first item emitted by {@code o1}, the first item
5282 * emitted by {@code o2}, and the first item emitted by {@code o3}; the second item emitted by the new
5283 * {@code Publisher} will be the result of the function applied to the second item emitted by {@code o1}, the
5284 * second item emitted by {@code o2}, and the second item emitted by {@code o3}; and so forth.
5285 * <p>
5286 * The resulting {@code Flowable} returned from {@code zip} will invoke {@link Subscriber#onNext onNext}
5287 * as many times as the number of {@code onNext} invocations of the source {@code Publisher} that emits the fewest
5288 * items.
5289 * <p>
5290 * The operator subscribes to its sources in the order they are specified and completes eagerly if
5291 * one of the sources is shorter than the rest while canceling the other sources. Therefore, it
5292 * is possible those other sources will never be able to run to completion (and thus not calling
5293 * {@code doOnComplete()}). This can also happen if the sources are exactly the same length; if
5294 * source A completes and B has been consumed and is about to complete, the operator detects A won't
5295 * be sending further values and it will cancel B immediately. For example:
5296 * <pre><code>zip(range(1, 5).doOnComplete(action1), range(6, 5).doOnComplete(action2), ..., (a, b, c) -&gt; a + b)</code></pre>
5297 * {@code action1} will be called but {@code action2} won't.
5298 * <br>To work around this termination property,
5299 * use {@link #doOnCancel(Action)} as well or use {@code using()} to do cleanup in case of completion
5300 * or cancellation.
5301 * <dl>
5302 * <dt><b>Backpressure:</b></dt>
5303 * <dd>The operator expects backpressure from the sources and honors backpressure from the downstream.
5304 * (I.e., zipping with {@link #interval(long, TimeUnit)} may result in {@link MissingBackpressureException}, use
5305 * one of the {@code onBackpressureX} to handle similar, backpressure-ignoring sources.</dd>
5306 * <dt><b>Scheduler:</b></dt>
5307 * <dd>{@code zip} does not operate by default on a particular {@link Scheduler}.</dd>
5308 * </dl>
5309 *
5310 * @param <T1> the value type of the first source
5311 * @param <T2> the value type of the second source
5312 * @param <T3> the value type of the third source
5313 * @param <R> the zipped result type
5314 * @param source1
5315 * the first source {@code Publisher}
5316 * @param source2
5317 * a second source {@code Publisher}
5318 * @param source3
5319 * a third source {@code Publisher}
5320 * @param zipper
5321 * a function that, when applied to an item emitted by each of the source {@code Publisher}s, results in
5322 * an item that will be emitted by the resulting {@code Flowable}
5323 * @return the new {@code Flowable} instance
5324 * @throws NullPointerException if {@code source1}, {@code source2}, {@code source3} or {@code zipper} is {@code null}
5325 * @see <a href="http://reactivex.io/documentation/operators/zip.html">ReactiveX operators documentation: Zip</a>
5326 */
5327 @CheckReturnValue
5328 @NonNull
5329 @BackpressureSupport(BackpressureKind.FULL)
5330 @SchedulerSupport(SchedulerSupport.NONE)
5331 public static <@NonNull T1, @NonNull T2, @NonNull T3, @NonNull R> Flowable<R> zip(
5332 @NonNull Publisher<? extends T1> source1, @NonNull Publisher<? extends T2> source2, @NonNull Publisher<? extends T3> source3,
5333 @NonNull Function3<? super T1, ? super T2, ? super T3, ? extends R> zipper) {
5334 Objects.requireNonNull(source1, "source1 is null");
5335 Objects.requireNonNull(source2, "source2 is null");
5336 Objects.requireNonNull(source3, "source3 is null");
5337 Objects.requireNonNull(zipper, "zipper is null");
5338 return zipArray(Functions.toFunction(zipper), false, bufferSize(), source1, source2, source3);
5339 }
5340
5341 /**
5342 * Returns a {@code Flowable} that emits the results of a specified combiner function applied to combinations of
5343 * four items emitted, in sequence, by four other {@link Publisher}s.
5344 * <p>
5345 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/zip.v3.png" alt="">
5346 * <p>
5347 * {@code zip} applies this function in strict sequence, so the first item emitted by the new {@code Publisher}
5348 * will be the result of the function applied to the first item emitted by {@code o1}, the first item
5349 * emitted by {@code o2}, the first item emitted by {@code o3}, and the first item emitted by {@code 04};
5350 * the second item emitted by the new {@code Publisher} will be the result of the function applied to the second
5351 * item emitted by each of those {@code Publisher}s; and so forth.
5352 * <p>
5353 * The resulting {@code Flowable} returned from {@code zip} will invoke {@link Subscriber#onNext onNext}
5354 * as many times as the number of {@code onNext} invocations of the source {@code Publisher} that emits the fewest
5355 * items.
5356 * <p>
5357 * The operator subscribes to its sources in the order they are specified and completes eagerly if
5358 * one of the sources is shorter than the rest while canceling the other sources. Therefore, it
5359 * is possible those other sources will never be able to run to completion (and thus not calling
5360 * {@code doOnComplete()}). This can also happen if the sources are exactly the same length; if
5361 * source A completes and B has been consumed and is about to complete, the operator detects A won't
5362 * be sending further values and it will cancel B immediately. For example:
5363 * <pre><code>zip(range(1, 5).doOnComplete(action1), range(6, 5).doOnComplete(action2), ..., (a, b, c, d) -&gt; a + b)</code></pre>
5364 * {@code action1} will be called but {@code action2} won't.
5365 * <br>To work around this termination property,
5366 * use {@link #doOnCancel(Action)} as well or use {@code using()} to do cleanup in case of completion
5367 * or cancellation.
5368 * <dl>
5369 * <dt><b>Backpressure:</b></dt>
5370 * <dd>The operator expects backpressure from the sources and honors backpressure from the downstream.
5371 * (I.e., zipping with {@link #interval(long, TimeUnit)} may result in {@link MissingBackpressureException}, use
5372 * one of the {@code onBackpressureX} to handle similar, backpressure-ignoring sources.</dd>
5373 * <dt><b>Scheduler:</b></dt>
5374 * <dd>{@code zip} does not operate by default on a particular {@link Scheduler}.</dd>
5375 * </dl>
5376 *
5377 * @param <T1> the value type of the first source
5378 * @param <T2> the value type of the second source
5379 * @param <T3> the value type of the third source
5380 * @param <T4> the value type of the fourth source
5381 * @param <R> the zipped result type
5382 * @param source1
5383 * the first source {@code Publisher}
5384 * @param source2
5385 * a second source {@code Publisher}
5386 * @param source3
5387 * a third source {@code Publisher}
5388 * @param source4
5389 * a fourth source {@code Publisher}
5390 * @param zipper
5391 * a function that, when applied to an item emitted by each of the source {@code Publisher}s, results in
5392 * an item that will be emitted by the resulting {@code Flowable}
5393 * @return the new {@code Flowable} instance
5394 * @throws NullPointerException if {@code source1}, {@code source2}, {@code source3},
5395 * {@code source4} or {@code zipper} is {@code null}
5396 * @see <a href="http://reactivex.io/documentation/operators/zip.html">ReactiveX operators documentation: Zip</a>
5397 */
5398 @CheckReturnValue
5399 @NonNull
5400 @BackpressureSupport(BackpressureKind.FULL)
5401 @SchedulerSupport(SchedulerSupport.NONE)
5402 public static <@NonNull T1, @NonNull T2, @NonNull T3, @NonNull T4, @NonNull R> Flowable<R> zip(
5403 @NonNull Publisher<? extends T1> source1, @NonNull Publisher<? extends T2> source2, @NonNull Publisher<? extends T3> source3,
5404 @NonNull Publisher<? extends T4> source4,
5405 @NonNull Function4<? super T1, ? super T2, ? super T3, ? super T4, ? extends R> zipper) {
5406 Objects.requireNonNull(source1, "source1 is null");
5407 Objects.requireNonNull(source2, "source2 is null");
5408 Objects.requireNonNull(source3, "source3 is null");
5409 Objects.requireNonNull(source4, "source4 is null");
5410 Objects.requireNonNull(zipper, "zipper is null");
5411 return zipArray(Functions.toFunction(zipper), false, bufferSize(), source1, source2, source3, source4);
5412 }
5413
5414 /**
5415 * Returns a {@code Flowable} that emits the results of a specified combiner function applied to combinations of
5416 * five items emitted, in sequence, by five other {@link Publisher}s.
5417 * <p>
5418 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/zip.v3.png" alt="">
5419 * <p>
5420 * {@code zip} applies this function in strict sequence, so the first item emitted by the new {@code Publisher}
5421 * will be the result of the function applied to the first item emitted by {@code o1}, the first item
5422 * emitted by {@code o2}, the first item emitted by {@code o3}, the first item emitted by {@code o4}, and
5423 * the first item emitted by {@code o5}; the second item emitted by the new {@code Publisher} will be the result of
5424 * the function applied to the second item emitted by each of those {@code Publisher}s; and so forth.
5425 * <p>
5426 * The resulting {@code Flowable} returned from {@code zip} will invoke {@link Subscriber#onNext onNext}
5427 * as many times as the number of {@code onNext} invocations of the source {@code Publisher} that emits the fewest
5428 * items.
5429 * <p>
5430 * The operator subscribes to its sources in the order they are specified and completes eagerly if
5431 * one of the sources is shorter than the rest while canceling the other sources. Therefore, it
5432 * is possible those other sources will never be able to run to completion (and thus not calling
5433 * {@code doOnComplete()}). This can also happen if the sources are exactly the same length; if
5434 * source A completes and B has been consumed and is about to complete, the operator detects A won't
5435 * be sending further values and it will cancel B immediately. For example:
5436 * <pre><code>zip(range(1, 5).doOnComplete(action1), range(6, 5).doOnComplete(action2), ..., (a, b, c, d, e) -&gt; a + b)</code></pre>
5437 * {@code action1} will be called but {@code action2} won't.
5438 * <br>To work around this termination property,
5439 * use {@link #doOnCancel(Action)} as well or use {@code using()} to do cleanup in case of completion
5440 * or cancellation.
5441 * <dl>
5442 * <dt><b>Backpressure:</b></dt>
5443 * <dd>The operator expects backpressure from the sources and honors backpressure from the downstream.
5444 * (I.e., zipping with {@link #interval(long, TimeUnit)} may result in {@link MissingBackpressureException}, use
5445 * one of the {@code onBackpressureX} to handle similar, backpressure-ignoring sources.</dd>
5446 * <dt><b>Scheduler:</b></dt>
5447 * <dd>{@code zip} does not operate by default on a particular {@link Scheduler}.</dd>
5448 * </dl>
5449 *
5450 * @param <T1> the value type of the first source
5451 * @param <T2> the value type of the second source
5452 * @param <T3> the value type of the third source
5453 * @param <T4> the value type of the fourth source
5454 * @param <T5> the value type of the fifth source
5455 * @param <R> the zipped result type
5456 * @param source1
5457 * the first source {@code Publisher}
5458 * @param source2
5459 * a second source {@code Publisher}
5460 * @param source3
5461 * a third source {@code Publisher}
5462 * @param source4
5463 * a fourth source {@code Publisher}
5464 * @param source5
5465 * a fifth source {@code Publisher}
5466 * @param zipper
5467 * a function that, when applied to an item emitted by each of the source {@code Publisher}s, results in
5468 * an item that will be emitted by the resulting {@code Flowable}
5469 * @return the new {@code Flowable} instance
5470 * @throws NullPointerException if {@code source1}, {@code source2}, {@code source3},
5471 * {@code source4}, {@code source5} or {@code zipper} is {@code null}
5472 * @see <a href="http://reactivex.io/documentation/operators/zip.html">ReactiveX operators documentation: Zip</a>
5473 */
5474 @CheckReturnValue
5475 @NonNull
5476 @BackpressureSupport(BackpressureKind.FULL)
5477 @SchedulerSupport(SchedulerSupport.NONE)
5478 public static <@NonNull T1, @NonNull T2, @NonNull T3, @NonNull T4, @NonNull T5, @NonNull R> Flowable<R> zip(
5479 @NonNull Publisher<? extends T1> source1, @NonNull Publisher<? extends T2> source2, @NonNull Publisher<? extends T3> source3,
5480 @NonNull Publisher<? extends T4> source4, @NonNull Publisher<? extends T5> source5,
5481 @NonNull Function5<? super T1, ? super T2, ? super T3, ? super T4, ? super T5, ? extends R> zipper) {
5482 Objects.requireNonNull(source1, "source1 is null");
5483 Objects.requireNonNull(source2, "source2 is null");
5484 Objects.requireNonNull(source3, "source3 is null");
5485 Objects.requireNonNull(source4, "source4 is null");
5486 Objects.requireNonNull(source5, "source5 is null");
5487 Objects.requireNonNull(zipper, "zipper is null");
5488 return zipArray(Functions.toFunction(zipper), false, bufferSize(), source1, source2, source3, source4, source5);
5489 }
5490
5491 /**
5492 * Returns a {@code Flowable} that emits the results of a specified combiner function applied to combinations of
5493 * six items emitted, in sequence, by six other {@link Publisher}s.
5494 * <p>
5495 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/zip.v3.png" alt="">
5496 * <p>
5497 * {@code zip} applies this function in strict sequence, so the first item emitted by the new {@code Publisher}
5498 * will be the result of the function applied to the first item emitted by each source {@code Publisher}, the
5499 * second item emitted by the new {@code Publisher} will be the result of the function applied to the second item
5500 * emitted by each of those {@code Publisher}s, and so forth.
5501 * <p>
5502 * The resulting {@code Flowable} returned from {@code zip} will invoke {@link Subscriber#onNext onNext}
5503 * as many times as the number of {@code onNext} invocations of the source {@code Publisher} that emits the fewest
5504 * items.
5505 * <p>
5506 * The operator subscribes to its sources in the order they are specified and completes eagerly if
5507 * one of the sources is shorter than the rest while canceling the other sources. Therefore, it
5508 * is possible those other sources will never be able to run to completion (and thus not calling
5509 * {@code doOnComplete()}). This can also happen if the sources are exactly the same length; if
5510 * source A completes and B has been consumed and is about to complete, the operator detects A won't
5511 * be sending further values and it will cancel B immediately. For example:
5512 * <pre><code>zip(range(1, 5).doOnComplete(action1), range(6, 5).doOnComplete(action2), ..., (a, b, c, d, e, f) -&gt; a + b)</code></pre>
5513 * {@code action1} will be called but {@code action2} won't.
5514 * <br>To work around this termination property,
5515 * use {@link #doOnCancel(Action)} as well or use {@code using()} to do cleanup in case of completion
5516 * or cancellation.
5517 * <dl>
5518 * <dt><b>Backpressure:</b></dt>
5519 * <dd>The operator expects backpressure from the sources and honors backpressure from the downstream.
5520 * (I.e., zipping with {@link #interval(long, TimeUnit)} may result in {@link MissingBackpressureException}, use
5521 * one of the {@code onBackpressureX} to handle similar, backpressure-ignoring sources.</dd>
5522 * <dt><b>Scheduler:</b></dt>
5523 * <dd>{@code zip} does not operate by default on a particular {@link Scheduler}.</dd>
5524 * </dl>
5525 *
5526 * @param <T1> the value type of the first source
5527 * @param <T2> the value type of the second source
5528 * @param <T3> the value type of the third source
5529 * @param <T4> the value type of the fourth source
5530 * @param <T5> the value type of the fifth source
5531 * @param <T6> the value type of the sixth source
5532 * @param <R> the zipped result type
5533 * @param source1
5534 * the first source {@code Publisher}
5535 * @param source2
5536 * a second source {@code Publisher}
5537 * @param source3
5538 * a third source {@code Publisher}
5539 * @param source4
5540 * a fourth source {@code Publisher}
5541 * @param source5
5542 * a fifth source {@code Publisher}
5543 * @param source6
5544 * a sixth source {@code Publisher}
5545 * @param zipper
5546 * a function that, when applied to an item emitted by each of the source {@code Publisher}s, results in
5547 * an item that will be emitted by the resulting {@code Flowable}
5548 * @return the new {@code Flowable} instance
5549 * @throws NullPointerException if {@code source1}, {@code source2}, {@code source3},
5550 * {@code source4}, {@code source5}, {@code source6}
5551 * or {@code zipper} is {@code null}
5552 * @see <a href="http://reactivex.io/documentation/operators/zip.html">ReactiveX operators documentation: Zip</a>
5553 */
5554 @CheckReturnValue
5555 @NonNull
5556 @BackpressureSupport(BackpressureKind.FULL)
5557 @SchedulerSupport(SchedulerSupport.NONE)
5558 public static <@NonNull T1, @NonNull T2, @NonNull T3, @NonNull T4, @NonNull T5, @NonNull T6, @NonNull R> Flowable<R> zip(
5559 @NonNull Publisher<? extends T1> source1, @NonNull Publisher<? extends T2> source2, @NonNull Publisher<? extends T3> source3,
5560 @NonNull Publisher<? extends T4> source4, @NonNull Publisher<? extends T5> source5, @NonNull Publisher<? extends T6> source6,
5561 @NonNull Function6<? super T1, ? super T2, ? super T3, ? super T4, ? super T5, ? super T6, ? extends R> zipper) {
5562 Objects.requireNonNull(source1, "source1 is null");
5563 Objects.requireNonNull(source2, "source2 is null");
5564 Objects.requireNonNull(source3, "source3 is null");
5565 Objects.requireNonNull(source4, "source4 is null");
5566 Objects.requireNonNull(source5, "source5 is null");
5567 Objects.requireNonNull(source6, "source6 is null");
5568 Objects.requireNonNull(zipper, "zipper is null");
5569 return zipArray(Functions.toFunction(zipper), false, bufferSize(), source1, source2, source3, source4, source5, source6);
5570 }
5571
5572 /**
5573 * Returns a {@code Flowable} that emits the results of a specified combiner function applied to combinations of
5574 * seven items emitted, in sequence, by seven other {@link Publisher}s.
5575 * <p>
5576 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/zip.v3.png" alt="">
5577 * <p>
5578 * {@code zip} applies this function in strict sequence, so the first item emitted by the new {@code Publisher}
5579 * will be the result of the function applied to the first item emitted by each source {@code Publisher}, the
5580 * second item emitted by the new {@code Publisher} will be the result of the function applied to the second item
5581 * emitted by each of those {@code Publisher}s, and so forth.
5582 * <p>
5583 * The resulting {@code Flowable} returned from {@code zip} will invoke {@link Subscriber#onNext onNext}
5584 * as many times as the number of {@code onNext} invocations of the source {@code Publisher} that emits the fewest
5585 * items.
5586 * <p>
5587 * The operator subscribes to its sources in the order they are specified and completes eagerly if
5588 * one of the sources is shorter than the rest while canceling the other sources. Therefore, it
5589 * is possible those other sources will never be able to run to completion (and thus not calling
5590 * {@code doOnComplete()}). This can also happen if the sources are exactly the same length; if
5591 * source A completes and B has been consumed and is about to complete, the operator detects A won't
5592 * be sending further values and it will cancel B immediately. For example:
5593 * <pre><code>zip(range(1, 5).doOnComplete(action1), range(6, 5).doOnComplete(action2), ..., (a, b, c, d, e, f, g) -&gt; a + b)</code></pre>
5594 * {@code action1} will be called but {@code action2} won't.
5595 * <br>To work around this termination property,
5596 * use {@link #doOnCancel(Action)} as well or use {@code using()} to do cleanup in case of completion
5597 * or cancellation.
5598 * <dl>
5599 * <dt><b>Backpressure:</b></dt>
5600 * <dd>The operator expects backpressure from the sources and honors backpressure from the downstream.
5601 * (I.e., zipping with {@link #interval(long, TimeUnit)} may result in {@link MissingBackpressureException}, use
5602 * one of the {@code onBackpressureX} to handle similar, backpressure-ignoring sources.</dd>
5603 * <dt><b>Scheduler:</b></dt>
5604 * <dd>{@code zip} does not operate by default on a particular {@link Scheduler}.</dd>
5605 * </dl>
5606 *
5607 * @param <T1> the value type of the first source
5608 * @param <T2> the value type of the second source
5609 * @param <T3> the value type of the third source
5610 * @param <T4> the value type of the fourth source
5611 * @param <T5> the value type of the fifth source
5612 * @param <T6> the value type of the sixth source
5613 * @param <T7> the value type of the seventh source
5614 * @param <R> the zipped result type
5615 * @param source1
5616 * the first source {@code Publisher}
5617 * @param source2
5618 * a second source {@code Publisher}
5619 * @param source3
5620 * a third source {@code Publisher}
5621 * @param source4
5622 * a fourth source {@code Publisher}
5623 * @param source5
5624 * a fifth source {@code Publisher}
5625 * @param source6
5626 * a sixth source {@code Publisher}
5627 * @param source7
5628 * a seventh source {@code Publisher}
5629 * @param zipper
5630 * a function that, when applied to an item emitted by each of the source {@code Publisher}s, results in
5631 * an item that will be emitted by the resulting {@code Flowable}
5632 * @return the new {@code Flowable} instance
5633 * @throws NullPointerException if {@code source1}, {@code source2}, {@code source3},
5634 * {@code source4}, {@code source5}, {@code source6},
5635 * {@code source7} or {@code zipper} is {@code null}
5636 * @see <a href="http://reactivex.io/documentation/operators/zip.html">ReactiveX operators documentation: Zip</a>
5637 */
5638 @CheckReturnValue
5639 @NonNull
5640 @BackpressureSupport(BackpressureKind.FULL)
5641 @SchedulerSupport(SchedulerSupport.NONE)
5642 public static <@NonNull T1, @NonNull T2, @NonNull T3, @NonNull T4, @NonNull T5, @NonNull T6, @NonNull T7, @NonNull R> Flowable<R> zip(
5643 @NonNull Publisher<? extends T1> source1, @NonNull Publisher<? extends T2> source2, @NonNull Publisher<? extends T3> source3,
5644 @NonNull Publisher<? extends T4> source4, @NonNull Publisher<? extends T5> source5, @NonNull Publisher<? extends T6> source6,
5645 @NonNull Publisher<? extends T7> source7,
5646 @NonNull Function7<? super T1, ? super T2, ? super T3, ? super T4, ? super T5, ? super T6, ? super T7, ? extends R> zipper) {
5647 Objects.requireNonNull(source1, "source1 is null");
5648 Objects.requireNonNull(source2, "source2 is null");
5649 Objects.requireNonNull(source3, "source3 is null");
5650 Objects.requireNonNull(source4, "source4 is null");
5651 Objects.requireNonNull(source5, "source5 is null");
5652 Objects.requireNonNull(source6, "source6 is null");
5653 Objects.requireNonNull(source7, "source7 is null");
5654 Objects.requireNonNull(zipper, "zipper is null");
5655 return zipArray(Functions.toFunction(zipper), false, bufferSize(), source1, source2, source3, source4, source5, source6, source7);
5656 }
5657
5658 /**
5659 * Returns a {@code Flowable} that emits the results of a specified combiner function applied to combinations of
5660 * eight items emitted, in sequence, by eight other {@link Publisher}s.
5661 * <p>
5662 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/zip.v3.png" alt="">
5663 * <p>
5664 * {@code zip} applies this function in strict sequence, so the first item emitted by the new {@code Publisher}
5665 * will be the result of the function applied to the first item emitted by each source {@code Publisher}, the
5666 * second item emitted by the new {@code Publisher} will be the result of the function applied to the second item
5667 * emitted by each of those {@code Publisher}s, and so forth.
5668 * <p>
5669 * The resulting {@code Flowable} returned from {@code zip} will invoke {@link Subscriber#onNext onNext}
5670 * as many times as the number of {@code onNext} invocations of the source {@code Publisher} that emits the fewest
5671 * items.
5672 * <p>
5673 * The operator subscribes to its sources in the order they are specified and completes eagerly if
5674 * one of the sources is shorter than the rest while canceling the other sources. Therefore, it
5675 * is possible those other sources will never be able to run to completion (and thus not calling
5676 * {@code doOnComplete()}). This can also happen if the sources are exactly the same length; if
5677 * source A completes and B has been consumed and is about to complete, the operator detects A won't
5678 * be sending further values and it will cancel B immediately. For example:
5679 * <pre><code>zip(range(1, 5).doOnComplete(action1), range(6, 5).doOnComplete(action2), ..., (a, b, c, d, e, f, g, h) -&gt; a + b)</code></pre>
5680 * {@code action1} will be called but {@code action2} won't.
5681 * <br>To work around this termination property,
5682 * use {@link #doOnCancel(Action)} as well or use {@code using()} to do cleanup in case of completion
5683 * or cancellation.
5684 * <dl>
5685 * <dt><b>Backpressure:</b></dt>
5686 * <dd>The operator expects backpressure from the sources and honors backpressure from the downstream.
5687 * (I.e., zipping with {@link #interval(long, TimeUnit)} may result in {@link MissingBackpressureException}, use
5688 * one of the {@code onBackpressureX} to handle similar, backpressure-ignoring sources.</dd>
5689 * <dt><b>Scheduler:</b></dt>
5690 * <dd>{@code zip} does not operate by default on a particular {@link Scheduler}.</dd>
5691 * </dl>
5692 *
5693 * @param <T1> the value type of the first source
5694 * @param <T2> the value type of the second source
5695 * @param <T3> the value type of the third source
5696 * @param <T4> the value type of the fourth source
5697 * @param <T5> the value type of the fifth source
5698 * @param <T6> the value type of the sixth source
5699 * @param <T7> the value type of the seventh source
5700 * @param <T8> the value type of the eighth source
5701 * @param <R> the zipped result type
5702 * @param source1
5703 * the first source {@code Publisher}
5704 * @param source2
5705 * a second source {@code Publisher}
5706 * @param source3
5707 * a third source {@code Publisher}
5708 * @param source4
5709 * a fourth source {@code Publisher}
5710 * @param source5
5711 * a fifth source {@code Publisher}
5712 * @param source6
5713 * a sixth source {@code Publisher}
5714 * @param source7
5715 * a seventh source {@code Publisher}
5716 * @param source8
5717 * an eighth source {@code Publisher}
5718 * @param zipper
5719 * a function that, when applied to an item emitted by each of the source {@code Publisher}s, results in
5720 * an item that will be emitted by the resulting {@code Flowable}
5721 * @return the new {@code Flowable} instance
5722 * @throws NullPointerException if {@code source1}, {@code source2}, {@code source3},
5723 * {@code source4}, {@code source5}, {@code source6},
5724 * {@code source7}, {@code source8} or {@code zipper} is {@code null}
5725 * @see <a href="http://reactivex.io/documentation/operators/zip.html">ReactiveX operators documentation: Zip</a>
5726 */
5727 @CheckReturnValue
5728 @NonNull
5729 @BackpressureSupport(BackpressureKind.FULL)
5730 @SchedulerSupport(SchedulerSupport.NONE)
5731 public static <@NonNull T1, @NonNull T2, @NonNull T3, @NonNull T4, @NonNull T5, @NonNull T6, @NonNull T7, @NonNull T8, @NonNull R> Flowable<R> zip(
5732 @NonNull Publisher<? extends T1> source1, @NonNull Publisher<? extends T2> source2, @NonNull Publisher<? extends T3> source3,
5733 @NonNull Publisher<? extends T4> source4, @NonNull Publisher<? extends T5> source5, @NonNull Publisher<? extends T6> source6,
5734 @NonNull Publisher<? extends T7> source7, @NonNull Publisher<? extends T8> source8,
5735 @NonNull Function8<? super T1, ? super T2, ? super T3, ? super T4, ? super T5, ? super T6, ? super T7, ? super T8, ? extends R> zipper) {
5736 Objects.requireNonNull(source1, "source1 is null");
5737 Objects.requireNonNull(source2, "source2 is null");
5738 Objects.requireNonNull(source3, "source3 is null");
5739 Objects.requireNonNull(source4, "source4 is null");
5740 Objects.requireNonNull(source5, "source5 is null");
5741 Objects.requireNonNull(source6, "source6 is null");
5742 Objects.requireNonNull(source7, "source7 is null");
5743 Objects.requireNonNull(source8, "source8 is null");
5744 Objects.requireNonNull(zipper, "zipper is null");
5745 return zipArray(Functions.toFunction(zipper), false, bufferSize(), source1, source2, source3, source4, source5, source6, source7, source8);
5746 }
5747
5748 /**
5749 * Returns a {@code Flowable} that emits the results of a specified combiner function applied to combinations of
5750 * nine items emitted, in sequence, by nine other {@link Publisher}s.
5751 * <p>
5752 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/zip.v3.png" alt="">
5753 * <p>
5754 * {@code zip} applies this function in strict sequence, so the first item emitted by the new {@code Publisher}
5755 * will be the result of the function applied to the first item emitted by each source {@code Publisher}, the
5756 * second item emitted by the new {@code Publisher} will be the result of the function applied to the second item
5757 * emitted by each of those {@code Publisher}s, and so forth.
5758 * <p>
5759 * The resulting {@code Flowable} returned from {@code zip} will invoke {@link Subscriber#onNext onNext}
5760 * as many times as the number of {@code onNext} invocations of the source {@code Publisher} that emits the fewest
5761 * items.
5762 * <p>
5763 * The operator subscribes to its sources in the order they are specified and completes eagerly if
5764 * one of the sources is shorter than the rest while canceling the other sources. Therefore, it
5765 * is possible those other sources will never be able to run to completion (and thus not calling
5766 * {@code doOnComplete()}). This can also happen if the sources are exactly the same length; if
5767 * source A completes and B has been consumed and is about to complete, the operator detects A won't
5768 * be sending further values and it will cancel B immediately. For example:
5769 * <pre><code>zip(range(1, 5).doOnComplete(action1), range(6, 5).doOnComplete(action2), ..., (a, b, c, d, e, f, g, h, i) -&gt; a + b)</code></pre>
5770 * {@code action1} will be called but {@code action2} won't.
5771 * <br>To work around this termination property,
5772 * use {@link #doOnCancel(Action)} as well or use {@code using()} to do cleanup in case of completion
5773 * or cancellation.
5774 * <dl>
5775 * <dt><b>Backpressure:</b></dt>
5776 * <dd>The operator expects backpressure from the sources and honors backpressure from the downstream.
5777 * (I.e., zipping with {@link #interval(long, TimeUnit)} may result in {@link MissingBackpressureException}, use
5778 * one of the {@code onBackpressureX} to handle similar, backpressure-ignoring sources.</dd>
5779 * <dt><b>Scheduler:</b></dt>
5780 * <dd>{@code zip} does not operate by default on a particular {@link Scheduler}.</dd>
5781 * </dl>
5782 *
5783 * @param <T1> the value type of the first source
5784 * @param <T2> the value type of the second source
5785 * @param <T3> the value type of the third source
5786 * @param <T4> the value type of the fourth source
5787 * @param <T5> the value type of the fifth source
5788 * @param <T6> the value type of the sixth source
5789 * @param <T7> the value type of the seventh source
5790 * @param <T8> the value type of the eighth source
5791 * @param <T9> the value type of the ninth source
5792 * @param <R> the zipped result type
5793 * @param source1
5794 * the first source {@code Publisher}
5795 * @param source2
5796 * a second source {@code Publisher}
5797 * @param source3
5798 * a third source {@code Publisher}
5799 * @param source4
5800 * a fourth source {@code Publisher}
5801 * @param source5
5802 * a fifth source {@code Publisher}
5803 * @param source6
5804 * a sixth source {@code Publisher}
5805 * @param source7
5806 * a seventh source {@code Publisher}
5807 * @param source8
5808 * an eighth source {@code Publisher}
5809 * @param source9
5810 * a ninth source {@code Publisher}
5811 * @param zipper
5812 * a function that, when applied to an item emitted by each of the source {@code Publisher}s, results in
5813 * an item that will be emitted by the resulting {@code Flowable}
5814 * @return the new {@code Flowable} instance
5815 * @throws NullPointerException if {@code source1}, {@code source2}, {@code source3},
5816 * {@code source4}, {@code source5}, {@code source6},
5817 * {@code source7}, {@code source8}, {@code source9}
5818 * or {@code zipper} is {@code null}
5819 * @see <a href="http://reactivex.io/documentation/operators/zip.html">ReactiveX operators documentation: Zip</a>
5820 */
5821 @CheckReturnValue
5822 @NonNull
5823 @BackpressureSupport(BackpressureKind.FULL)
5824 @SchedulerSupport(SchedulerSupport.NONE)
5825 public static <@NonNull T1, @NonNull T2, @NonNull T3, @NonNull T4, @NonNull T5, @NonNull T6, @NonNull T7, @NonNull T8, @NonNull T9, @NonNull R> Flowable<R> zip(
5826 @NonNull Publisher<? extends T1> source1, @NonNull Publisher<? extends T2> source2, @NonNull Publisher<? extends T3> source3,
5827 @NonNull Publisher<? extends T4> source4, @NonNull Publisher<? extends T5> source5, @NonNull Publisher<? extends T6> source6,
5828 @NonNull Publisher<? extends T7> source7, @NonNull Publisher<? extends T8> source8, @NonNull Publisher<? extends T9> source9,
5829 @NonNull Function9<? super T1, ? super T2, ? super T3, ? super T4, ? super T5, ? super T6, ? super T7, ? super T8, ? super T9, ? extends R> zipper) {
5830
5831 Objects.requireNonNull(source1, "source1 is null");
5832 Objects.requireNonNull(source2, "source2 is null");
5833 Objects.requireNonNull(source3, "source3 is null");
5834 Objects.requireNonNull(source4, "source4 is null");
5835 Objects.requireNonNull(source5, "source5 is null");
5836 Objects.requireNonNull(source6, "source6 is null");
5837 Objects.requireNonNull(source7, "source7 is null");
5838 Objects.requireNonNull(source8, "source8 is null");
5839 Objects.requireNonNull(source9, "source9 is null");
5840 Objects.requireNonNull(zipper, "zipper is null");
5841 return zipArray(Functions.toFunction(zipper), false, bufferSize(), source1, source2, source3, source4, source5, source6, source7, source8, source9);
5842 }
5843
5844 /**
5845 * Returns a {@code Flowable} that emits the results of a specified combiner function applied to combinations of
5846 * items emitted, in sequence, by an array of other {@link Publisher}s.
5847 * <p>
5848 * {@code zip} applies this function in strict sequence, so the first item emitted by the new {@code Publisher}
5849 * will be the result of the function applied to the first item emitted by each of the source {@code Publisher}s;
5850 * the second item emitted by the new {@code Publisher} will be the result of the function applied to the second
5851 * item emitted by each of those {@code Publisher}s; and so forth.
5852 * <p>
5853 * The resulting {@code Flowable} returned from {@code zip} will invoke {@code onNext} as many times as
5854 * the number of {@code onNext} invocations of the source {@code Publisher} that emits the fewest items.
5855 * <p>
5856 * The operator subscribes to its sources in the order they are specified and completes eagerly if
5857 * one of the sources is shorter than the rest while canceling the other sources. Therefore, it
5858 * is possible those other sources will never be able to run to completion (and thus not calling
5859 * {@code doOnComplete()}). This can also happen if the sources are exactly the same length; if
5860 * source A completes and B has been consumed and is about to complete, the operator detects A won't
5861 * be sending further values and it will cancel B immediately. For example:
5862 * <pre><code>zip(new Publisher[]{range(1, 5).doOnComplete(action1), range(6, 5).doOnComplete(action2)}, (a) -&gt;
5863 * a)</code></pre>
5864 * {@code action1} will be called but {@code action2} won't.
5865 * <br>To work around this termination property,
5866 * use {@link #doOnCancel(Action)} as well or use {@code using()} to do cleanup in case of completion
5867 * or cancellation.
5868 * <p>
5869 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/zip.v3.png" alt="">
5870 * <dl>
5871 * <dt><b>Backpressure:</b></dt>
5872 * <dd>The operator expects backpressure from the sources and honors backpressure from the downstream.
5873 * (I.e., zipping with {@link #interval(long, TimeUnit)} may result in {@link MissingBackpressureException}, use
5874 * one of the {@code onBackpressureX} to handle similar, backpressure-ignoring sources.</dd>
5875 * <dt><b>Scheduler:</b></dt>
5876 * <dd>{@code zipArray} does not operate by default on a particular {@link Scheduler}.</dd>
5877 * </dl>
5878 *
5879 * @param <T> the common element type
5880 * @param <R> the result type
5881 * @param sources
5882 * an array of source {@code Publisher}s
5883 * @param zipper
5884 * a function that, when applied to an item emitted by each of the source {@code Publisher}s, results in
5885 * an item that will be emitted by the resulting {@code Flowable}
5886 * @param delayError
5887 * delay errors signaled by any of the source {@code Publisher} until all {@code Publisher}s terminate
5888 * @param bufferSize
5889 * the number of elements to prefetch from each source {@code Publisher}
5890 * @return the new {@code Flowable} instance
5891 * @throws NullPointerException if {@code sources} or {@code zipper} is {@code null}
5892 * @throws IllegalArgumentException if {@code bufferSize} is non-positive
5893 * @see <a href="http://reactivex.io/documentation/operators/zip.html">ReactiveX operators documentation: Zip</a>
5894 */
5895 @CheckReturnValue
5896 @NonNull
5897 @BackpressureSupport(BackpressureKind.FULL)
5898 @SchedulerSupport(SchedulerSupport.NONE)
5899 @SafeVarargs
5900 public static <@NonNull T, @NonNull R> Flowable<R> zipArray(@NonNull Function<? super Object[], ? extends R> zipper,
5901 boolean delayError, int bufferSize, @NonNull Publisher<? extends T>... sources) {
5902 Objects.requireNonNull(sources, "sources is null");
5903 if (sources.length == 0) {
5904 return empty();
5905 }
5906 Objects.requireNonNull(zipper, "zipper is null");
5907 ObjectHelper.verifyPositive(bufferSize, "bufferSize");
5908 return RxJavaPlugins.onAssembly(new FlowableZip<>(sources, null, zipper, bufferSize, delayError));
5909 }
5910
5911 // ***************************************************************************************************
5912 // Instance operators
5913 // ***************************************************************************************************
5914
5915 /**
5916 * Returns a {@link Single} that emits a {@link Boolean} that indicates whether all of the items emitted by the current
5917 * {@code Flowable} satisfy a condition.
5918 * <p>
5919 * <img width="640" height="315" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/all.v3.png" alt="">
5920 * <dl>
5921 * <dt><b>Backpressure:</b></dt>
5922 * <dd>The operator honors backpressure from downstream and consumes the current {@code Flowable} in an unbounded
5923 * manner (i.e., without applying backpressure).</dd>
5924 * <dt><b>Scheduler:</b></dt>
5925 * <dd>{@code all} does not operate by default on a particular {@link Scheduler}.</dd>
5926 * </dl>
5927 *
5928 * @param predicate
5929 * a function that evaluates an item and returns a {@code Boolean}
5930 * @return the new {@code Single} instance
5931 * @throws NullPointerException if {@code predicate} is {@code null}
5932 * @see <a href="http://reactivex.io/documentation/operators/all.html">ReactiveX operators documentation: All</a>
5933 */
5934 @CheckReturnValue
5935 @NonNull
5936 @BackpressureSupport(BackpressureKind.UNBOUNDED_IN)
5937 @SchedulerSupport(SchedulerSupport.NONE)
5938 public final Single<Boolean> all(@NonNull Predicate<? super T> predicate) {
5939 Objects.requireNonNull(predicate, "predicate is null");
5940 return RxJavaPlugins.onAssembly(new FlowableAllSingle<>(this, predicate));
5941 }
5942
5943 /**
5944 * Mirrors the {@link Publisher} (current or provided) that first either emits an item or sends a termination
5945 * notification.
5946 * <p>
5947 * <img width="640" height="376" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Flowable.ambWith.png" alt="">
5948 * <p>
5949 * When the current {@code Flowable} signals an item or terminates first, the subscription to the other
5950 * {@code Publisher} is canceled. If the other {@code Publisher} signals an item or terminates first,
5951 * the subscription to the current {@code Flowable} is canceled.
5952 * <dl>
5953 * <dt><b>Backpressure:</b></dt>
5954 * <dd>The operator itself doesn't interfere with backpressure which is determined by the winning
5955 * {@code Publisher}'s backpressure behavior.</dd>
5956 * <dt><b>Scheduler:</b></dt>
5957 * <dd>{@code ambWith} does not operate by default on a particular {@link Scheduler}.</dd>
5958 * <dt><b>Error handling:</b></dt>
5959 * <dd>
5960 * If the losing {@code Publisher} signals an error, the error is routed to the global
5961 * error handler via {@link RxJavaPlugins#onError(Throwable)}.
5962 * </dd>
5963 * </dl>
5964 *
5965 * @param other
5966 * a {@code Publisher} competing to react first. A subscription to this provided {@code Publisher} will occur after subscribing
5967 * to the current {@code Flowable}.
5968 * @return the new {@code Flowable} instance
5969 * @throws NullPointerException if {@code other} is {@code null}
5970 * @see <a href="http://reactivex.io/documentation/operators/amb.html">ReactiveX operators documentation: Amb</a>
5971 */
5972 @CheckReturnValue
5973 @NonNull
5974 @BackpressureSupport(BackpressureKind.FULL)
5975 @SchedulerSupport(SchedulerSupport.NONE)
5976 public final Flowable<T> ambWith(@NonNull Publisher<? extends T> other) {
5977 Objects.requireNonNull(other, "other is null");
5978 return ambArray(this, other);
5979 }
5980
5981 /**
5982 * Returns a {@link Single} that emits {@code true} if any item emitted by the current {@code Flowable} satisfies a
5983 * specified condition, otherwise {@code false}. <em>Note:</em> this always emits {@code false} if the
5984 * current {@code Flowable} is empty.
5985 * <p>
5986 * <img width="640" height="320" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/exists.v3.png" alt="">
5987 * <p>
5988 * In Rx.Net this is the {@code any} operator but we renamed it in RxJava to better match Java naming
5989 * idioms.
5990 * <dl>
5991 * <dt><b>Backpressure:</b></dt>
5992 * <dd>The operator honors backpressure from downstream and consumes the current {@code Flowable} in an unbounded manner
5993 * (i.e., no backpressure applied to it).</dd>
5994 * <dt><b>Scheduler:</b></dt>
5995 * <dd>{@code any} does not operate by default on a particular {@link Scheduler}.</dd>
5996 * </dl>
5997 *
5998 * @param predicate
5999 * the condition to test items emitted by the current {@code Flowable}
6000 * @return the new {@code Single} instance
6001 * @throws NullPointerException if {@code predicate} is {@code null}
6002 * @see <a href="http://reactivex.io/documentation/operators/contains.html">ReactiveX operators documentation: Contains</a>
6003 */
6004 @CheckReturnValue
6005 @NonNull
6006 @BackpressureSupport(BackpressureKind.UNBOUNDED_IN)
6007 @SchedulerSupport(SchedulerSupport.NONE)
6008 public final Single<Boolean> any(@NonNull Predicate<? super T> predicate) {
6009 Objects.requireNonNull(predicate, "predicate is null");
6010 return RxJavaPlugins.onAssembly(new FlowableAnySingle<>(this, predicate));
6011 }
6012
6013 /**
6014 * Returns the first item emitted by this {@code Flowable}, or throws
6015 * {@link NoSuchElementException} if it emits no items.
6016 * <dl>
6017 * <dt><b>Backpressure:</b></dt>
6018 * <dd>The operator consumes the current {@code Flowable} in an unbounded manner
6019 * (i.e., no backpressure applied to it).</dd>
6020 * <dt><b>Scheduler:</b></dt>
6021 * <dd>{@code blockingFirst} does not operate by default on a particular {@link Scheduler}.</dd>
6022 * <dt><b>Error handling:</b></dt>
6023 * <dd>If the source signals an error, the operator wraps a checked {@link Exception}
6024 * into {@link RuntimeException} and throws that. Otherwise, {@code RuntimeException}s and
6025 * {@link Error}s are rethrown as they are.</dd>
6026 * </dl>
6027 *
6028 * @return the new {@code Flowable} instance
6029 * @throws NoSuchElementException
6030 * if this {@code Flowable} emits no items
6031 * @see <a href="http://reactivex.io/documentation/operators/first.html">ReactiveX documentation: First</a>
6032 */
6033 @CheckReturnValue
6034 @BackpressureSupport(BackpressureKind.UNBOUNDED_IN)
6035 @SchedulerSupport(SchedulerSupport.NONE)
6036 @NonNull
6037 public final T blockingFirst() {
6038 BlockingFirstSubscriber<T> s = new BlockingFirstSubscriber<>();
6039 subscribe(s);
6040 T v = s.blockingGet();
6041 if (v != null) {
6042 return v;
6043 }
6044 throw new NoSuchElementException();
6045 }
6046
6047 /**
6048 * Returns the first item emitted by this {@code Flowable}, or a default value if it emits no
6049 * items.
6050 * <dl>
6051 * <dt><b>Backpressure:</b></dt>
6052 * <dd>The operator consumes the current {@code Flowable} in an unbounded manner
6053 * (i.e., no backpressure applied to it).</dd>
6054 * <dt><b>Scheduler:</b></dt>
6055 * <dd>{@code blockingFirst} does not operate by default on a particular {@link Scheduler}.</dd>
6056 * <dt><b>Error handling:</b></dt>
6057 * <dd>If the source signals an error, the operator wraps a checked {@link Exception}
6058 * into {@link RuntimeException} and throws that. Otherwise, {@code RuntimeException}s and
6059 * {@link Error}s are rethrown as they are.</dd>
6060 * </dl>
6061 *
6062 * @param defaultItem
6063 * a default value to return if this {@code Flowable} emits no items
6064 * @return the new {@code Flowable} instance
6065 * @throws NullPointerException if {@code defaultItem} is {@code null}
6066 * @see <a href="http://reactivex.io/documentation/operators/first.html">ReactiveX documentation: First</a>
6067 */
6068 @CheckReturnValue
6069 @BackpressureSupport(BackpressureKind.UNBOUNDED_IN)
6070 @SchedulerSupport(SchedulerSupport.NONE)
6071 @NonNull
6072 public final T blockingFirst(@NonNull T defaultItem) {
6073 Objects.requireNonNull(defaultItem, "defaultItem is null");
6074 BlockingFirstSubscriber<T> s = new BlockingFirstSubscriber<>();
6075 subscribe(s);
6076 T v = s.blockingGet();
6077 return v != null ? v : defaultItem;
6078 }
6079
6080 /**
6081 * Consumes the current {@code Flowable} in a blocking fashion and invokes the given
6082 * {@link Consumer} with each upstream item on the <em>current thread</em> until the
6083 * upstream terminates.
6084 * <p>
6085 * <img width="640" height="330" src="https://github.com/ReactiveX/RxJava/wiki/images/rx-operators/B.forEach.v3.png" alt="">
6086 * <p>
6087 * <em>Note:</em> the method will only return if the upstream terminates or the current
6088 * thread is interrupted.
6089 * <p>
6090 * This method executes the {@code Consumer} on the current thread while
6091 * {@link #subscribe(Consumer)} executes the consumer on the original caller thread of the
6092 * sequence.
6093 * <dl>
6094 * <dt><b>Backpressure:</b></dt>
6095 * <dd>The operator requests {@link Flowable#bufferSize()} upfront, then 75% of this
6096 * amount when 75% is received.</dd>
6097 * <dt><b>Scheduler:</b></dt>
6098 * <dd>{@code blockingForEach} does not operate by default on a particular {@link Scheduler}.</dd>
6099 * <dt><b>Error handling:</b></dt>
6100 * <dd>If the source signals an error, the operator wraps a checked {@link Exception}
6101 * into {@link RuntimeException} and throws that. Otherwise, {@code RuntimeException}s and
6102 * {@link Error}s are rethrown as they are.</dd>
6103 * </dl>
6104 *
6105 * @param onNext
6106 * the {@code Consumer} to invoke for each item emitted by the {@code Flowable}
6107 * @throws NullPointerException if {@code onNext} is {@code null}
6108 * @throws RuntimeException
6109 * if an error occurs; {@code Error}s and {@code RuntimeException}s are rethrown
6110 * as they are, checked {@code Exception}s are wrapped into {@code RuntimeException}s
6111 * @see <a href="http://reactivex.io/documentation/operators/subscribe.html">ReactiveX documentation: Subscribe</a>
6112 * @see #subscribe(Consumer)
6113 * @see #blockingForEach(Consumer, int)
6114 */
6115 @BackpressureSupport(BackpressureKind.FULL)
6116 @SchedulerSupport(SchedulerSupport.NONE)
6117 public final void blockingForEach(@NonNull Consumer<? super T> onNext) {
6118 blockingForEach(onNext, bufferSize());
6119 }
6120
6121 /**
6122 * Consumes the current {@code Flowable} in a blocking fashion and invokes the given
6123 * {@link Consumer} with each upstream item on the <em>current thread</em> until the
6124 * upstream terminates.
6125 * <p>
6126 * <img width="640" height="330" src="https://github.com/ReactiveX/RxJava/wiki/images/rx-operators/B.forEach.v3.png" alt="">
6127 * <p>
6128 * <em>Note:</em> the method will only return if the upstream terminates or the current
6129 * thread is interrupted.
6130 * <p>
6131 * This method executes the {@code Consumer} on the current thread while
6132 * {@link #subscribe(Consumer)} executes the consumer on the original caller thread of the
6133 * sequence.
6134 * <dl>
6135 * <dt><b>Backpressure:</b></dt>
6136 * <dd>The operator requests the given {@code prefetch} amount upfront, then 75% of this
6137 * amount when 75% is received.</dd>
6138 * <dt><b>Scheduler:</b></dt>
6139 * <dd>{@code blockingForEach} does not operate by default on a particular {@link Scheduler}.</dd>
6140 * <dt><b>Error handling:</b></dt>
6141 * <dd>If the source signals an error, the operator wraps a checked {@link Exception}
6142 * into {@link RuntimeException} and throws that. Otherwise, {@code RuntimeException}s and
6143 * {@link Error}s are rethrown as they are.</dd>
6144 * </dl>
6145 *
6146 * @param onNext
6147 * the {@code Consumer} to invoke for each item emitted by the {@code Flowable}
6148 * @param bufferSize
6149 * the number of items to prefetch upfront, then 75% of it after 75% received
6150 * @throws NullPointerException if {@code onNext} is {@code null}
6151 * @throws IllegalArgumentException if {@code bufferSize} is non-positive
6152 * @throws RuntimeException
6153 * if an error occurs; {@code Error}s and {@code RuntimeException}s are rethrown
6154 * as they are, checked {@code Exception}s are wrapped into {@code RuntimeException}s
6155 * @see <a href="http://reactivex.io/documentation/operators/subscribe.html">ReactiveX documentation: Subscribe</a>
6156 * @see #subscribe(Consumer)
6157 */
6158 @BackpressureSupport(BackpressureKind.FULL)
6159 @SchedulerSupport(SchedulerSupport.NONE)
6160 public final void blockingForEach(@NonNull Consumer<? super T> onNext, int bufferSize) {
6161 Objects.requireNonNull(onNext, "onNext is null");
6162 Iterator<T> it = blockingIterable(bufferSize).iterator();
6163 while (it.hasNext()) {
6164 try {
6165 onNext.accept(it.next());
6166 } catch (Throwable e) {
6167 Exceptions.throwIfFatal(e);
6168 ((Disposable)it).dispose();
6169 throw ExceptionHelper.wrapOrThrow(e);
6170 }
6171 }
6172 }
6173
6174 /**
6175 * Converts this {@code Flowable} into an {@link Iterable}.
6176 * <p>
6177 * <img width="640" height="315" src="https://github.com/ReactiveX/RxJava/wiki/images/rx-operators/B.toIterable.v3.png" alt="">
6178 * <dl>
6179 * <dt><b>Backpressure:</b></dt>
6180 * <dd>The operator expects the upstream to honor backpressure otherwise the returned
6181 * {@code Iterable}'s iterator will throw a {@link MissingBackpressureException}.</dd>
6182 * <dt><b>Scheduler:</b></dt>
6183 * <dd>{@code blockingIterable} does not operate by default on a particular {@link Scheduler}.</dd>
6184 * </dl>
6185 *
6186 * @return the new {@code Iterable} instance
6187 * @see <a href="http://reactivex.io/documentation/operators/to.html">ReactiveX documentation: To</a>
6188 */
6189 @CheckReturnValue
6190 @BackpressureSupport(BackpressureKind.FULL)
6191 @SchedulerSupport(SchedulerSupport.NONE)
6192 @NonNull
6193 public final Iterable<T> blockingIterable() {
6194 return blockingIterable(bufferSize());
6195 }
6196
6197 /**
6198 * Converts this {@code Flowable} into an {@link Iterable}.
6199 * <p>
6200 * <img width="640" height="315" src="https://github.com/ReactiveX/RxJava/wiki/images/rx-operators/B.toIterable.v3.png" alt="">
6201 * <dl>
6202 * <dt><b>Backpressure:</b></dt>
6203 * <dd>The operator expects the upstream to honor backpressure otherwise the returned
6204 * {@code Iterable}'s iterator will throw a {@link MissingBackpressureException}.
6205 * </dd>
6206 * <dt><b>Scheduler:</b></dt>
6207 * <dd>{@code blockingIterable} does not operate by default on a particular {@link Scheduler}.</dd>
6208 * </dl>
6209 *
6210 * @param bufferSize the number of items to prefetch from the current {@code Flowable}
6211 * @return the new {@code Iterable} instance
6212 * @throws IllegalArgumentException if {@code bufferSize} is non-positive
6213 * @see <a href="http://reactivex.io/documentation/operators/to.html">ReactiveX documentation: To</a>
6214 */
6215 @CheckReturnValue
6216 @BackpressureSupport(BackpressureKind.FULL)
6217 @SchedulerSupport(SchedulerSupport.NONE)
6218 @NonNull
6219 public final Iterable<T> blockingIterable(int bufferSize) {
6220 ObjectHelper.verifyPositive(bufferSize, "bufferSize");
6221 return new BlockingFlowableIterable<>(this, bufferSize);
6222 }
6223
6224 /**
6225 * Returns the last item emitted by this {@code Flowable}, or throws
6226 * {@link NoSuchElementException} if this {@code Flowable} emits no items.
6227 * <p>
6228 * <img width="640" height="315" src="https://github.com/ReactiveX/RxJava/wiki/images/rx-operators/B.last.v3.png" alt="">
6229 * <dl>
6230 * <dt><b>Backpressure:</b></dt>
6231 * <dd>The operator consumes the current {@code Flowable} in an unbounded manner
6232 * (i.e., no backpressure applied to it).</dd>
6233 * <dt><b>Scheduler:</b></dt>
6234 * <dd>{@code blockingLast} does not operate by default on a particular {@link Scheduler}.</dd>
6235 * <dt><b>Error handling:</b></dt>
6236 * <dd>If the source signals an error, the operator wraps a checked {@link Exception}
6237 * into {@link RuntimeException} and throws that. Otherwise, {@code RuntimeException}s and
6238 * {@link Error}s are rethrown as they are.</dd>
6239 * </dl>
6240 *
6241 * @return the new {@code Flowable} instance
6242 * @throws NoSuchElementException
6243 * if this {@code Flowable} emits no items
6244 * @see <a href="http://reactivex.io/documentation/operators/last.html">ReactiveX documentation: Last</a>
6245 */
6246 @CheckReturnValue
6247 @BackpressureSupport(BackpressureKind.UNBOUNDED_IN)
6248 @SchedulerSupport(SchedulerSupport.NONE)
6249 @NonNull
6250 public final T blockingLast() {
6251 BlockingLastSubscriber<T> s = new BlockingLastSubscriber<>();
6252 subscribe(s);
6253 T v = s.blockingGet();
6254 if (v != null) {
6255 return v;
6256 }
6257 throw new NoSuchElementException();
6258 }
6259
6260 /**
6261 * Returns the last item emitted by this {@code Flowable}, or a default value if it emits no
6262 * items.
6263 * <p>
6264 * <img width="640" height="310" src="https://github.com/ReactiveX/RxJava/wiki/images/rx-operators/B.lastOrDefault.v3.png" alt="">
6265 * <dl>
6266 * <dt><b>Backpressure:</b></dt>
6267 * <dd>The operator consumes the current {@code Flowable} in an unbounded manner
6268 * (i.e., no backpressure applied to it).</dd>
6269 * <dt><b>Scheduler:</b></dt>
6270 * <dd>{@code blockingLast} does not operate by default on a particular {@link Scheduler}.</dd>
6271 * <dt><b>Error handling:</b></dt>
6272 * <dd>If the source signals an error, the operator wraps a checked {@link Exception}
6273 * into {@link RuntimeException} and throws that. Otherwise, {@code RuntimeException}s and
6274 * {@link Error}s are rethrown as they are.</dd>
6275 * </dl>
6276 *
6277 * @param defaultItem
6278 * a default value to return if this {@code Flowable} emits no items
6279 * @return the new {@code Flowable} instance
6280 * @throws NullPointerException if {@code defaultItem} is {@code null}
6281 * @see <a href="http://reactivex.io/documentation/operators/last.html">ReactiveX documentation: Last</a>
6282 */
6283 @CheckReturnValue
6284 @BackpressureSupport(BackpressureKind.UNBOUNDED_IN)
6285 @SchedulerSupport(SchedulerSupport.NONE)
6286 @NonNull
6287 public final T blockingLast(@NonNull T defaultItem) {
6288 Objects.requireNonNull(defaultItem, "defaultItem is null");
6289 BlockingLastSubscriber<T> s = new BlockingLastSubscriber<>();
6290 subscribe(s);
6291 T v = s.blockingGet();
6292 return v != null ? v : defaultItem;
6293 }
6294
6295 /**
6296 * Returns an {@link Iterable} that returns the latest item emitted by this {@code Flowable},
6297 * waiting if necessary for one to become available.
6298 * <p>
6299 * If this {@code Flowable} produces items faster than {@code Iterator.next} takes them,
6300 * {@code onNext} events might be skipped, but {@code onError} or {@code onComplete} events are not.
6301 * <p>
6302 * Note also that an {@code onNext} directly followed by {@code onComplete} might hide the {@code onNext}
6303 * event.
6304 * <dl>
6305 * <dt><b>Backpressure:</b></dt>
6306 * <dd>The operator consumes the current {@code Flowable} in an unbounded manner
6307 * (i.e., no backpressure applied to it).</dd>
6308 * <dt><b>Scheduler:</b></dt>
6309 * <dd>{@code blockingLatest} does not operate by default on a particular {@link Scheduler}.</dd>
6310 * </dl>
6311 *
6312 * @return the new {@code Iterable} instance
6313 * @see <a href="http://reactivex.io/documentation/operators/first.html">ReactiveX documentation: First</a>
6314 */
6315 @CheckReturnValue
6316 @BackpressureSupport(BackpressureKind.UNBOUNDED_IN)
6317 @SchedulerSupport(SchedulerSupport.NONE)
6318 @NonNull
6319 public final Iterable<T> blockingLatest() {
6320 return new BlockingFlowableLatest<>(this);
6321 }
6322
6323 /**
6324 * Returns an {@link Iterable} that always returns the item most recently emitted by this
6325 * {@code Flowable}.
6326 * <p>
6327 * <img width="640" height="490" src="https://github.com/ReactiveX/RxJava/wiki/images/rx-operators/B.mostRecent.v3.png" alt="">
6328 * <dl>
6329 * <dt><b>Backpressure:</b></dt>
6330 * <dd>The operator consumes the current {@code Flowable} in an unbounded manner
6331 * (i.e., no backpressure applied to it).</dd>
6332 * <dt><b>Scheduler:</b></dt>
6333 * <dd>{@code blockingMostRecent} does not operate by default on a particular {@link Scheduler}.</dd>
6334 * </dl>
6335 *
6336 * @param initialItem
6337 * the initial item that the {@code Iterable} sequence will yield if this
6338 * {@code Flowable} has not yet emitted an item
6339 * @return the new {@code Iterable} instance
6340 * @throws NullPointerException if {@code initialItem} is {@code null}
6341 * @see <a href="http://reactivex.io/documentation/operators/first.html">ReactiveX documentation: First</a>
6342 */
6343 @CheckReturnValue
6344 @BackpressureSupport(BackpressureKind.UNBOUNDED_IN)
6345 @SchedulerSupport(SchedulerSupport.NONE)
6346 @NonNull
6347 public final Iterable<T> blockingMostRecent(@NonNull T initialItem) {
6348 Objects.requireNonNull(initialItem, "initialItem is null");
6349 return new BlockingFlowableMostRecent<>(this, initialItem);
6350 }
6351
6352 /**
6353 * Returns an {@link Iterable} that blocks until this {@code Flowable} emits another item, then
6354 * returns that item.
6355 * <p>
6356 * <img width="640" height="490" src="https://github.com/ReactiveX/RxJava/wiki/images/rx-operators/B.next.v3.png" alt="">
6357 * <dl>
6358 * <dt><b>Backpressure:</b></dt>
6359 * <dd>The operator consumes the current {@code Flowable} in an unbounded manner
6360 * (i.e., no backpressure applied to it).</dd>
6361 * <dt><b>Scheduler:</b></dt>
6362 * <dd>{@code blockingNext} does not operate by default on a particular {@link Scheduler}.</dd>
6363 * </dl>
6364 *
6365 * @return the new {@code Iterable} instance
6366 * @see <a href="http://reactivex.io/documentation/operators/takelast.html">ReactiveX documentation: TakeLast</a>
6367 */
6368 @CheckReturnValue
6369 @BackpressureSupport(BackpressureKind.UNBOUNDED_IN)
6370 @SchedulerSupport(SchedulerSupport.NONE)
6371 @NonNull
6372 public final Iterable<T> blockingNext() {
6373 return new BlockingFlowableNext<>(this);
6374 }
6375
6376 /**
6377 * If this {@code Flowable} completes after emitting a single item, return that item, otherwise
6378 * throw a {@link NoSuchElementException}.
6379 * <p>
6380 * <img width="640" height="315" src="https://github.com/ReactiveX/RxJava/wiki/images/rx-operators/B.single.v3.png" alt="">
6381 * <dl>
6382 * <dt><b>Backpressure:</b></dt>
6383 * <dd>The operator consumes the current {@code Flowable} in an unbounded manner
6384 * (i.e., no backpressure applied to it).</dd>
6385 * <dt><b>Scheduler:</b></dt>
6386 * <dd>{@code blockingSingle} does not operate by default on a particular {@link Scheduler}.</dd>
6387 * <dt><b>Error handling:</b></dt>
6388 * <dd>If the source signals an error, the operator wraps a checked {@link Exception}
6389 * into {@link RuntimeException} and throws that. Otherwise, {@code RuntimeException}s and
6390 * {@link Error}s are rethrown as they are.</dd>
6391 * </dl>
6392 *
6393 * @return the new {@code Flowable} instance
6394 * @see <a href="http://reactivex.io/documentation/operators/first.html">ReactiveX documentation: First</a>
6395 */
6396 @CheckReturnValue
6397 @BackpressureSupport(BackpressureKind.UNBOUNDED_IN)
6398 @SchedulerSupport(SchedulerSupport.NONE)
6399 @NonNull
6400 public final T blockingSingle() {
6401 return singleOrError().blockingGet();
6402 }
6403
6404 /**
6405 * If this {@code Flowable} completes after emitting a single item, return that item; if it emits
6406 * more than one item, throw an {@link IllegalArgumentException}; if it emits no items, return a default
6407 * value.
6408 * <p>
6409 * <img width="640" height="315" src="https://github.com/ReactiveX/RxJava/wiki/images/rx-operators/B.singleOrDefault.v3.png" alt="">
6410 * <dl>
6411 * <dt><b>Backpressure:</b></dt>
6412 * <dd>The operator consumes the current {@code Flowable} in an unbounded manner
6413 * (i.e., no backpressure applied to it).</dd>
6414 * <dt><b>Scheduler:</b></dt>
6415 * <dd>{@code blockingSingle} does not operate by default on a particular {@link Scheduler}.</dd>
6416 * <dt><b>Error handling:</b></dt>
6417 * <dd>If the source signals an error, the operator wraps a checked {@link Exception}
6418 * into {@link RuntimeException} and throws that. Otherwise, {@code RuntimeException}s and
6419 * {@link Error}s are rethrown as they are.</dd>
6420 * </dl>
6421 *
6422 * @param defaultItem
6423 * a default value to return if this {@code Flowable} emits no items
6424 * @return the new {@code Flowable} instance
6425 * @throws NullPointerException if {@code defaultItem} is {@code null}
6426 * @see <a href="http://reactivex.io/documentation/operators/first.html">ReactiveX documentation: First</a>
6427 */
6428 @CheckReturnValue
6429 @BackpressureSupport(BackpressureKind.UNBOUNDED_IN)
6430 @SchedulerSupport(SchedulerSupport.NONE)
6431 @NonNull
6432 public final T blockingSingle(@NonNull T defaultItem) {
6433 return single(defaultItem).blockingGet();
6434 }
6435
6436 /**
6437 * Returns a {@link Future} representing the only value emitted by this {@code Flowable}.
6438 * <p>
6439 * <img width="640" height="311" src="https://github.com/ReactiveX/RxJava/wiki/images/rx-operators/Flowable.toFuture.png" alt="">
6440 * <p>
6441 * If the {@code Flowable} emits more than one item, {@link java.util.concurrent.Future} will receive an
6442 * {@link java.lang.IndexOutOfBoundsException}. If the {@code Flowable} is empty, {@link java.util.concurrent.Future}
6443 * will receive a {@link java.util.NoSuchElementException}. The {@code Flowable} source has to terminate in order
6444 * for the returned {@code Future} to terminate as well.
6445 * <p>
6446 * If the {@code Flowable} may emit more than one item, use {@code Flowable.toList().toFuture()}.
6447 * <dl>
6448 * <dt><b>Backpressure:</b></dt>
6449 * <dd>The operator consumes the current {@code Flowable} in an unbounded manner
6450 * (i.e., no backpressure applied to it).</dd>
6451 * <dt><b>Scheduler:</b></dt>
6452 * <dd>{@code toFuture} does not operate by default on a particular {@link Scheduler}.</dd>
6453 * </dl>
6454 *
6455 * @return the new {@code Future} instance
6456 * @see <a href="http://reactivex.io/documentation/operators/to.html">ReactiveX documentation: To</a>
6457 */
6458 @CheckReturnValue
6459 @BackpressureSupport(BackpressureKind.UNBOUNDED_IN)
6460 @SchedulerSupport(SchedulerSupport.NONE)
6461 @NonNull
6462 public final Future<T> toFuture() {
6463 return subscribeWith(new FutureSubscriber<>());
6464 }
6465
6466 /**
6467 * Runs the current {@code Flowable} to a terminal event, ignoring any values and rethrowing any exception.
6468 * <p>
6469 * Note that calling this method will block the caller thread until the upstream terminates
6470 * normally or with an error. Therefore, calling this method from special threads such as the
6471 * Android Main Thread or the Swing Event Dispatch Thread is not recommended.
6472 * <dl>
6473 * <dt><b>Backpressure:</b></dt>
6474 * <dd>The operator consumes the current {@code Flowable} in an unbounded manner
6475 * (i.e., no backpressure applied to it).</dd>
6476 * <dt><b>Scheduler:</b></dt>
6477 * <dd>{@code blockingSubscribe} does not operate by default on a particular {@link Scheduler}.</dd>
6478 * </dl>
6479 * @since 2.0
6480 * @see #blockingSubscribe(Consumer)
6481 * @see #blockingSubscribe(Consumer, Consumer)
6482 * @see #blockingSubscribe(Consumer, Consumer, Action)
6483 */
6484 @BackpressureSupport(BackpressureKind.UNBOUNDED_IN)
6485 @SchedulerSupport(SchedulerSupport.NONE)
6486 public final void blockingSubscribe() {
6487 FlowableBlockingSubscribe.subscribe(this);
6488 }
6489
6490 /**
6491 * Subscribes to the source and calls the given callbacks <strong>on the current thread</strong>.
6492 * <p>
6493 * If the {@code Flowable} emits an error, it is wrapped into an
6494 * {@link io.reactivex.rxjava3.exceptions.OnErrorNotImplementedException OnErrorNotImplementedException}
6495 * and routed to the {@link RxJavaPlugins#onError(Throwable)} handler.
6496 * Using the overloads {@link #blockingSubscribe(Consumer, Consumer)}
6497 * or {@link #blockingSubscribe(Consumer, Consumer, Action)} instead is recommended.
6498 * <p>
6499 * Note that calling this method will block the caller thread until the upstream terminates
6500 * normally or with an error. Therefore, calling this method from special threads such as the
6501 * Android Main Thread or the Swing Event Dispatch Thread is not recommended.
6502 * <dl>
6503 * <dt><b>Backpressure:</b></dt>
6504 * <dd>The operator consumes the current {@code Flowable} in an unbounded manner
6505 * (i.e., no backpressure applied to it).</dd>
6506 * <dt><b>Scheduler:</b></dt>
6507 * <dd>{@code blockingSubscribe} does not operate by default on a particular {@link Scheduler}.</dd>
6508 * </dl>
6509 * @param onNext the callback action for each source value
6510 * @throws NullPointerException if {@code onNext} is {@code null}
6511 * @since 2.0
6512 * @see #blockingSubscribe(Consumer, Consumer)
6513 * @see #blockingSubscribe(Consumer, Consumer, Action)
6514 */
6515 @BackpressureSupport(BackpressureKind.UNBOUNDED_IN)
6516 @SchedulerSupport(SchedulerSupport.NONE)
6517 public final void blockingSubscribe(@NonNull Consumer<? super T> onNext) {
6518 FlowableBlockingSubscribe.subscribe(this, onNext, Functions.ON_ERROR_MISSING, Functions.EMPTY_ACTION);
6519 }
6520
6521 /**
6522 * Subscribes to the source and calls the given callbacks <strong>on the current thread</strong>.
6523 * <p>
6524 * If the {@code Flowable} emits an error, it is wrapped into an
6525 * {@link io.reactivex.rxjava3.exceptions.OnErrorNotImplementedException OnErrorNotImplementedException}
6526 * and routed to the {@link RxJavaPlugins#onError(Throwable)} handler.
6527 * Using the overloads {@link #blockingSubscribe(Consumer, Consumer)}
6528 * or {@link #blockingSubscribe(Consumer, Consumer, Action)} instead is recommended.
6529 * <p>
6530 * Note that calling this method will block the caller thread until the upstream terminates
6531 * normally or with an error. Therefore, calling this method from special threads such as the
6532 * Android Main Thread or the Swing Event Dispatch Thread is not recommended.
6533 * <dl>
6534 * <dt><b>Backpressure:</b></dt>
6535 * <dd>The operator consumes the current {@code Flowable} in an bounded manner (up to bufferSize
6536 * outstanding request amount for items).</dd>
6537 * <dt><b>Scheduler:</b></dt>
6538 * <dd>{@code blockingSubscribe} does not operate by default on a particular {@link Scheduler}.</dd>
6539 * </dl>
6540 * <p>History: 2.1.15 - experimental
6541 * @param onNext the callback action for each source value
6542 * @param bufferSize the size of the buffer
6543 * @throws NullPointerException if {@code onNext} is {@code null}
6544 * @throws IllegalArgumentException if {@code bufferSize} is non-positive
6545 * @see #blockingSubscribe(Consumer, Consumer)
6546 * @see #blockingSubscribe(Consumer, Consumer, Action)
6547 * @since 2.2
6548 */
6549 @BackpressureSupport(BackpressureKind.FULL)
6550 @SchedulerSupport(SchedulerSupport.NONE)
6551 public final void blockingSubscribe(@NonNull Consumer<? super T> onNext, int bufferSize) {
6552 FlowableBlockingSubscribe.subscribe(this, onNext, Functions.ON_ERROR_MISSING, Functions.EMPTY_ACTION, bufferSize);
6553 }
6554
6555 /**
6556 * Subscribes to the source and calls the given callbacks <strong>on the current thread</strong>.
6557 * <p>
6558 * Note that calling this method will block the caller thread until the upstream terminates
6559 * normally or with an error. Therefore, calling this method from special threads such as the
6560 * Android Main Thread or the Swing Event Dispatch Thread is not recommended.
6561 * <dl>
6562 * <dt><b>Backpressure:</b></dt>
6563 * <dd>The operator consumes the current {@code Flowable} in an unbounded manner
6564 * (i.e., no backpressure applied to it).</dd>
6565 * <dt><b>Scheduler:</b></dt>
6566 * <dd>{@code blockingSubscribe} does not operate by default on a particular {@link Scheduler}.</dd>
6567 * </dl>
6568 * @param onNext the callback action for each source value
6569 * @param onError the callback action for an error event
6570 * @throws NullPointerException if {@code onNext} or {@code onError} is {@code null}
6571 * @since 2.0
6572 * @see #blockingSubscribe(Consumer, Consumer, Action)
6573 */
6574 @BackpressureSupport(BackpressureKind.UNBOUNDED_IN)
6575 @SchedulerSupport(SchedulerSupport.NONE)
6576 public final void blockingSubscribe(@NonNull Consumer<? super T> onNext, @NonNull Consumer<? super Throwable> onError) {
6577 FlowableBlockingSubscribe.subscribe(this, onNext, onError, Functions.EMPTY_ACTION);
6578 }
6579
6580 /**
6581 * Subscribes to the source and calls the given callbacks <strong>on the current thread</strong>.
6582 * <p>
6583 * Note that calling this method will block the caller thread until the upstream terminates
6584 * normally or with an error. Therefore, calling this method from special threads such as the
6585 * Android Main Thread or the Swing Event Dispatch Thread is not recommended.
6586 * <dl>
6587 * <dt><b>Backpressure:</b></dt>
6588 * <dd>The operator consumes the current {@code Flowable} in an bounded manner (up to bufferSize
6589 * outstanding request amount for items).</dd>
6590 * <dt><b>Scheduler:</b></dt>
6591 * <dd>{@code blockingSubscribe} does not operate by default on a particular {@link Scheduler}.</dd>
6592 * </dl>
6593 * <p>History: 2.1.15 - experimental
6594 * @param onNext the callback action for each source value
6595 * @param onError the callback action for an error event
6596 * @param bufferSize the size of the buffer
6597 * @throws NullPointerException if {@code onNext} or {@code onError} is {@code null}
6598 * @throws IllegalArgumentException if {@code bufferSize} is non-positive
6599 * @since 2.2
6600 * @see #blockingSubscribe(Consumer, Consumer, Action)
6601 */
6602 @BackpressureSupport(BackpressureKind.FULL)
6603 @SchedulerSupport(SchedulerSupport.NONE)
6604 public final void blockingSubscribe(@NonNull Consumer<? super T> onNext, @NonNull Consumer<? super Throwable> onError,
6605 int bufferSize) {
6606 FlowableBlockingSubscribe.subscribe(this, onNext, onError, Functions.EMPTY_ACTION, bufferSize);
6607 }
6608
6609 /**
6610 * Subscribes to the source and calls the given callbacks <strong>on the current thread</strong>.
6611 * <p>
6612 * Note that calling this method will block the caller thread until the upstream terminates
6613 * normally or with an error. Therefore, calling this method from special threads such as the
6614 * Android Main Thread or the Swing Event Dispatch Thread is not recommended.
6615 * <dl>
6616 * <dt><b>Backpressure:</b></dt>
6617 * <dd>The operator consumes the current {@code Flowable} in an unbounded manner
6618 * (i.e., no backpressure applied to it).</dd>
6619 * <dt><b>Scheduler:</b></dt>
6620 * <dd>{@code blockingSubscribe} does not operate by default on a particular {@link Scheduler}.</dd>
6621 * </dl>
6622 * @param onNext the callback action for each source value
6623 * @param onError the callback action for an error event
6624 * @param onComplete the callback action for the completion event.
6625 * @throws NullPointerException if {@code onNext}, {@code onError} or {@code onComplete} is {@code null}
6626 * @since 2.0
6627 */
6628 @BackpressureSupport(BackpressureKind.UNBOUNDED_IN)
6629 @SchedulerSupport(SchedulerSupport.NONE)
6630 public final void blockingSubscribe(@NonNull Consumer<? super T> onNext, @NonNull Consumer<? super Throwable> onError, @NonNull Action onComplete) {
6631 FlowableBlockingSubscribe.subscribe(this, onNext, onError, onComplete);
6632 }
6633
6634 /**
6635 * Subscribes to the source and calls the given callbacks <strong>on the current thread</strong>.
6636 * <p>
6637 * Note that calling this method will block the caller thread until the upstream terminates
6638 * normally or with an error. Therefore, calling this method from special threads such as the
6639 * Android Main Thread or the Swing Event Dispatch Thread is not recommended.
6640 * <dl>
6641 * <dt><b>Backpressure:</b></dt>
6642 * <dd>The operator consumes the current {@code Flowable} in an bounded manner (up to bufferSize
6643 * outstanding request amount for items).</dd>
6644 * <dt><b>Scheduler:</b></dt>
6645 * <dd>{@code blockingSubscribe} does not operate by default on a particular {@link Scheduler}.</dd>
6646 * </dl>
6647 * <p>History: 2.1.15 - experimental
6648 * @param onNext the callback action for each source value
6649 * @param onError the callback action for an error event
6650 * @param onComplete the callback action for the completion event.
6651 * @param bufferSize the size of the buffer
6652 * @throws NullPointerException if {@code onNext}, {@code onError} or {@code onComplete} is {@code null}
6653 * @throws IllegalArgumentException if {@code bufferSize} is non-positive
6654 * @since 2.2
6655 */
6656 @BackpressureSupport(BackpressureKind.FULL)
6657 @SchedulerSupport(SchedulerSupport.NONE)
6658 public final void blockingSubscribe(@NonNull Consumer<? super T> onNext, @NonNull Consumer<? super Throwable> onError, @NonNull Action onComplete,
6659 int bufferSize) {
6660 FlowableBlockingSubscribe.subscribe(this, onNext, onError, onComplete, bufferSize);
6661 }
6662
6663 /**
6664 * Subscribes to the source and calls the {@link Subscriber} methods <strong>on the current thread</strong>.
6665 * <p>
6666 * Note that calling this method will block the caller thread until the upstream terminates
6667 * normally, with an error or the {@code Subscriber} cancels the {@link Subscription} it receives via
6668 * {@link Subscriber#onSubscribe(Subscription)}.
6669 * Therefore, calling this method from special threads such as the
6670 * Android Main Thread or the Swing Event Dispatch Thread is not recommended.
6671 * <dl>
6672 * <dt><b>Backpressure:</b></dt>
6673 * <dd>The supplied {@code Subscriber} determines how backpressure is applied.</dd>
6674 * <dt><b>Scheduler:</b></dt>
6675 * <dd>{@code blockingSubscribe} does not operate by default on a particular {@link Scheduler}.</dd>
6676 * </dl>
6677 * The cancellation and backpressure is composed through.
6678 * @param subscriber the subscriber to forward events and calls to in the current thread
6679 * @throws NullPointerException if {@code subscriber} is {@code null}
6680 * @since 2.0
6681 */
6682 @BackpressureSupport(BackpressureKind.SPECIAL)
6683 @SchedulerSupport(SchedulerSupport.NONE)
6684 public final void blockingSubscribe(@NonNull Subscriber<? super T> subscriber) {
6685 Objects.requireNonNull(subscriber, "subscriber is null");
6686 FlowableBlockingSubscribe.subscribe(this, subscriber);
6687 }
6688
6689 /**
6690 * Returns a {@code Flowable} that emits buffers of items it collects from the current {@code Flowable}. The resulting
6691 * {@code Flowable} emits connected, non-overlapping buffers, each containing {@code count} items. When the current
6692 * {@code Flowable} completes, the resulting {@code Flowable} emits the current buffer and propagates the notification from the
6693 * current {@code Flowable}. Note that if the current {@code Flowable} issues an {@code onError} notification the event is passed on
6694 * immediately without first emitting the buffer it is in the process of assembling.
6695 * <p>
6696 * <img width="640" height="320" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/buffer3.v3.png" alt="">
6697 * <dl>
6698 * <dt><b>Backpressure:</b></dt>
6699 * <dd>The operator honors backpressure from downstream and expects the current {@code Flowable} to honor it as
6700 * well, although not enforced; violation <em>may</em> lead to {@link MissingBackpressureException} somewhere
6701 * downstream.</dd>
6702 * <dt><b>Scheduler:</b></dt>
6703 * <dd>This version of {@code buffer} does not operate by default on a particular {@link Scheduler}.</dd>
6704 * </dl>
6705 *
6706 * @param count
6707 * the maximum number of items in each buffer before it should be emitted
6708 * @return the new {@code Flowable} instance
6709 * @throws IllegalArgumentException if {@code count} is non-positive
6710 * @see <a href="http://reactivex.io/documentation/operators/buffer.html">ReactiveX operators documentation: Buffer</a>
6711 */
6712 @CheckReturnValue
6713 @BackpressureSupport(BackpressureKind.FULL)
6714 @SchedulerSupport(SchedulerSupport.NONE)
6715 @NonNull
6716 public final Flowable<List<T>> buffer(int count) {
6717 return buffer(count, count);
6718 }
6719
6720 /**
6721 * Returns a {@code Flowable} that emits buffers of items it collects from the current {@code Flowable}. The resulting
6722 * {@code Flowable} emits buffers every {@code skip} items, each containing {@code count} items. When the current
6723 * {@code Flowable} completes, the resulting {@code Flowable} emits the current buffer and propagates the notification from the
6724 * current {@code Flowable}. Note that if the current {@code Flowable} issues an {@code onError} notification the event is passed on
6725 * immediately without first emitting the buffer it is in the process of assembling.
6726 * <p>
6727 * <img width="640" height="320" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/buffer4.v3.png" alt="">
6728 * <dl>
6729 * <dt><b>Backpressure:</b></dt>
6730 * <dd>The operator honors backpressure from downstream and expects the current {@code Flowable} to honor it as
6731 * well, although not enforced; violation <em>may</em> lead to {@link MissingBackpressureException} somewhere
6732 * downstream.</dd>
6733 * <dt><b>Scheduler:</b></dt>
6734 * <dd>This version of {@code buffer} does not operate by default on a particular {@link Scheduler}.</dd>
6735 * </dl>
6736 *
6737 * @param count
6738 * the maximum size of each buffer before it should be emitted
6739 * @param skip
6740 * how many items emitted by the current {@code Flowable} should be skipped before starting a new
6741 * buffer. Note that when {@code skip} and {@code count} are equal, this is the same operation as
6742 * {@link #buffer(int)}.
6743 * @return the new {@code Flowable} instance
6744 * @throws IllegalArgumentException if {@code count} or {@code skip} is non-positive
6745 * @see <a href="http://reactivex.io/documentation/operators/buffer.html">ReactiveX operators documentation: Buffer</a>
6746 */
6747 @CheckReturnValue
6748 @BackpressureSupport(BackpressureKind.FULL)
6749 @SchedulerSupport(SchedulerSupport.NONE)
6750 @NonNull
6751 public final Flowable<List<T>> buffer(int count, int skip) {
6752 return buffer(count, skip, ArrayListSupplier.asSupplier());
6753 }
6754
6755 /**
6756 * Returns a {@code Flowable} that emits buffers of items it collects from the current {@code Flowable}. The resulting
6757 * {@code Flowable} emits buffers every {@code skip} items, each containing {@code count} items. When the current
6758 * {@code Flowable} completes, the resulting {@code Flowable} emits the current buffer and propagates the notification from the
6759 * current {@code Flowable}. Note that if the current {@code Flowable} issues an {@code onError} notification the event is passed on
6760 * immediately without first emitting the buffer it is in the process of assembling.
6761 * <p>
6762 * <img width="640" height="320" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/buffer4.v3.png" alt="">
6763 * <dl>
6764 * <dt><b>Backpressure:</b></dt>
6765 * <dd>The operator honors backpressure from downstream and expects the current {@code Flowable} to honor it as
6766 * well, although not enforced; violation <em>may</em> lead to {@link MissingBackpressureException} somewhere
6767 * downstream.</dd>
6768 * <dt><b>Scheduler:</b></dt>
6769 * <dd>This version of {@code buffer} does not operate by default on a particular {@link Scheduler}.</dd>
6770 * </dl>
6771 *
6772 * @param <U> the collection subclass type to buffer into
6773 * @param count
6774 * the maximum size of each buffer before it should be emitted
6775 * @param skip
6776 * how many items emitted by the current {@code Flowable} should be skipped before starting a new
6777 * buffer. Note that when {@code skip} and {@code count} are equal, this is the same operation as
6778 * {@link #buffer(int)}.
6779 * @param bufferSupplier
6780 * a factory function that returns an instance of the collection subclass to be used and returned
6781 * as the buffer
6782 * @return the new {@code Flowable} instance
6783 * @throws NullPointerException if {@code bufferSupplier} is {@code null}
6784 * @throws IllegalArgumentException if {@code count} or {@code skip} is non-positive
6785 * @see <a href="http://reactivex.io/documentation/operators/buffer.html">ReactiveX operators documentation: Buffer</a>
6786 */
6787 @CheckReturnValue
6788 @NonNull
6789 @BackpressureSupport(BackpressureKind.FULL)
6790 @SchedulerSupport(SchedulerSupport.NONE)
6791 public final <@NonNull U extends Collection<? super T>> Flowable<U> buffer(int count, int skip, @NonNull Supplier<U> bufferSupplier) {
6792 ObjectHelper.verifyPositive(count, "count");
6793 ObjectHelper.verifyPositive(skip, "skip");
6794 Objects.requireNonNull(bufferSupplier, "bufferSupplier is null");
6795 return RxJavaPlugins.onAssembly(new FlowableBuffer<>(this, count, skip, bufferSupplier));
6796 }
6797
6798 /**
6799 * Returns a {@code Flowable} that emits buffers of items it collects from the current {@code Flowable}. The resulting
6800 * {@code Flowable} emits connected, non-overlapping buffers, each containing {@code count} items. When the current
6801 * {@code Flowable} completes, the resulting {@code Flowable} emits the current buffer and propagates the notification from the
6802 * current {@code Flowable}. Note that if the current {@code Flowable} issues an {@code onError} notification the event is passed on
6803 * immediately without first emitting the buffer it is in the process of assembling.
6804 * <p>
6805 * <img width="640" height="320" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/buffer3.v3.png" alt="">
6806 * <dl>
6807 * <dt><b>Backpressure:</b></dt>
6808 * <dd>The operator honors backpressure from downstream and expects the current {@code Flowable} to honor it as
6809 * well, although not enforced; violation <em>may</em> lead to {@link MissingBackpressureException} somewhere
6810 * downstream.</dd>
6811 * <dt><b>Scheduler:</b></dt>
6812 * <dd>This version of {@code buffer} does not operate by default on a particular {@link Scheduler}.</dd>
6813 * </dl>
6814 *
6815 * @param <U> the collection subclass type to buffer into
6816 * @param count
6817 * the maximum number of items in each buffer before it should be emitted
6818 * @param bufferSupplier
6819 * a factory function that returns an instance of the collection subclass to be used and returned
6820 * as the buffer
6821 * @return the new {@code Flowable} instance
6822 * @throws NullPointerException if {@code bufferSupplier} is {@code null}
6823 * @throws IllegalArgumentException if {@code count} is non-positive
6824 * @see <a href="http://reactivex.io/documentation/operators/buffer.html">ReactiveX operators documentation: Buffer</a>
6825 */
6826 @CheckReturnValue
6827 @BackpressureSupport(BackpressureKind.FULL)
6828 @SchedulerSupport(SchedulerSupport.NONE)
6829 @NonNull
6830 public final <@NonNull U extends Collection<? super T>> Flowable<U> buffer(int count, @NonNull Supplier<U> bufferSupplier) {
6831 return buffer(count, count, bufferSupplier);
6832 }
6833
6834 /**
6835 * Returns a {@code Flowable} that emits buffers of items it collects from the current {@code Flowable}. The resulting
6836 * {@code Flowable} starts a new buffer periodically, as determined by the {@code timeskip} argument. It emits
6837 * each buffer after a fixed timespan, specified by the {@code timespan} argument. When the current
6838 * {@code Flowable} completes, the resulting {@code Flowable} emits the current buffer and propagates the notification from the
6839 * current {@code Flowable}. Note that if the current {@code Flowable} issues an {@code onError} notification the event is passed on
6840 * immediately without first emitting the buffer it is in the process of assembling.
6841 * <p>
6842 * <img width="640" height="320" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/buffer7.v3.png" alt="">
6843 * <dl>
6844 * <dt><b>Backpressure:</b></dt>
6845 * <dd>This operator does not support backpressure as it uses time. It requests {@link Long#MAX_VALUE}
6846 * upstream and does not obey downstream requests.</dd>
6847 * <dt><b>Scheduler:</b></dt>
6848 * <dd>This version of {@code buffer} operates by default on the {@code computation} {@link Scheduler}.</dd>
6849 * </dl>
6850 *
6851 * @param timespan
6852 * the period of time each buffer collects items before it is emitted
6853 * @param timeskip
6854 * the period of time after which a new buffer will be created
6855 * @param unit
6856 * the unit of time that applies to the {@code timespan} and {@code timeskip} arguments
6857 * @return the new {@code Flowable} instance
6858 * @throws NullPointerException if {@code unit} is {@code null}
6859 * @see <a href="http://reactivex.io/documentation/operators/buffer.html">ReactiveX operators documentation: Buffer</a>
6860 */
6861 @CheckReturnValue
6862 @BackpressureSupport(BackpressureKind.ERROR)
6863 @SchedulerSupport(SchedulerSupport.COMPUTATION)
6864 @NonNull
6865 public final Flowable<List<T>> buffer(long timespan, long timeskip, @NonNull TimeUnit unit) {
6866 return buffer(timespan, timeskip, unit, Schedulers.computation(), ArrayListSupplier.asSupplier());
6867 }
6868
6869 /**
6870 * Returns a {@code Flowable} that emits buffers of items it collects from the current {@code Flowable}. The resulting
6871 * {@code Flowable} starts a new buffer periodically, as determined by the {@code timeskip} argument, and on the
6872 * specified {@code scheduler}. It emits each buffer after a fixed timespan, specified by the
6873 * {@code timespan} argument. When the current {@code Flowable} completes, the resulting {@code Flowable} emits the current buffer
6874 * and propagates the notification from the current {@code Flowable}. Note that if the current {@code Flowable} issues an {@code onError}
6875 * notification the event is passed on immediately without first emitting the buffer it is in the process of
6876 * assembling.
6877 * <p>
6878 * <img width="640" height="320" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/buffer7.s.v3.png" alt="">
6879 * <dl>
6880 * <dt><b>Backpressure:</b></dt>
6881 * <dd>This operator does not support backpressure as it uses time. It requests {@link Long#MAX_VALUE}
6882 * upstream and does not obey downstream requests.</dd>
6883 * <dt><b>Scheduler:</b></dt>
6884 * <dd>You specify which {@link Scheduler} this operator will use.</dd>
6885 * </dl>
6886 *
6887 * @param timespan
6888 * the period of time each buffer collects items before it is emitted
6889 * @param timeskip
6890 * the period of time after which a new buffer will be created
6891 * @param unit
6892 * the unit of time that applies to the {@code timespan} and {@code timeskip} arguments
6893 * @param scheduler
6894 * the {@code Scheduler} to use when determining the end and start of a buffer
6895 * @return the new {@code Flowable} instance
6896 * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null}
6897 * @see <a href="http://reactivex.io/documentation/operators/buffer.html">ReactiveX operators documentation: Buffer</a>
6898 */
6899 @CheckReturnValue
6900 @BackpressureSupport(BackpressureKind.ERROR)
6901 @SchedulerSupport(SchedulerSupport.CUSTOM)
6902 @NonNull
6903 public final Flowable<List<T>> buffer(long timespan, long timeskip, @NonNull TimeUnit unit, @NonNull Scheduler scheduler) {
6904 return buffer(timespan, timeskip, unit, scheduler, ArrayListSupplier.asSupplier());
6905 }
6906
6907 /**
6908 * Returns a {@code Flowable} that emits buffers of items it collects from the current {@code Flowable}. The resulting
6909 * {@code Flowable} starts a new buffer periodically, as determined by the {@code timeskip} argument, and on the
6910 * specified {@code scheduler}. It emits each buffer after a fixed timespan, specified by the
6911 * {@code timespan} argument. When the current {@code Flowable} completes, the resulting {@code Flowable} emits the current buffer
6912 * and propagates the notification from the current {@code Flowable}. Note that if the current {@code Flowable} issues an {@code onError}
6913 * notification the event is passed on immediately without first emitting the buffer it is in the process of
6914 * assembling.
6915 * <p>
6916 * <img width="640" height="320" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/buffer7.s.v3.png" alt="">
6917 * <dl>
6918 * <dt><b>Backpressure:</b></dt>
6919 * <dd>This operator does not support backpressure as it uses time. It requests {@link Long#MAX_VALUE}
6920 * upstream and does not obey downstream requests.</dd>
6921 * <dt><b>Scheduler:</b></dt>
6922 * <dd>You specify which {@link Scheduler} this operator will use.</dd>
6923 * </dl>
6924 *
6925 * @param <U> the collection subclass type to buffer into
6926 * @param timespan
6927 * the period of time each buffer collects items before it is emitted
6928 * @param timeskip
6929 * the period of time after which a new buffer will be created
6930 * @param unit
6931 * the unit of time that applies to the {@code timespan} and {@code timeskip} arguments
6932 * @param scheduler
6933 * the {@code Scheduler} to use when determining the end and start of a buffer
6934 * @param bufferSupplier
6935 * a factory function that returns an instance of the collection subclass to be used and returned
6936 * as the buffer
6937 * @return the new {@code Flowable} instance
6938 * @throws NullPointerException if {@code unit}, {@code scheduler} or {@code bufferSupplier} is {@code null}
6939 * @see <a href="http://reactivex.io/documentation/operators/buffer.html">ReactiveX operators documentation: Buffer</a>
6940 */
6941 @CheckReturnValue
6942 @NonNull
6943 @BackpressureSupport(BackpressureKind.ERROR)
6944 @SchedulerSupport(SchedulerSupport.CUSTOM)
6945 public final <@NonNull U extends Collection<? super T>> Flowable<U> buffer(long timespan, long timeskip, @NonNull TimeUnit unit,
6946 @NonNull Scheduler scheduler, @NonNull Supplier<U> bufferSupplier) {
6947 Objects.requireNonNull(unit, "unit is null");
6948 Objects.requireNonNull(scheduler, "scheduler is null");
6949 Objects.requireNonNull(bufferSupplier, "bufferSupplier is null");
6950 return RxJavaPlugins.onAssembly(new FlowableBufferTimed<>(this, timespan, timeskip, unit, scheduler, bufferSupplier, Integer.MAX_VALUE, false));
6951 }
6952
6953 /**
6954 * Returns a {@code Flowable} that emits buffers of items it collects from the current {@code Flowable}. The resulting
6955 * {@code Flowable} emits connected, non-overlapping buffers, each of a fixed duration specified by the
6956 * {@code timespan} argument. When the current {@code Flowable} completes, the resulting {@code Flowable} emits the current buffer
6957 * and propagates the notification from the current {@code Flowable}. Note that if the current {@code Flowable} issues an {@code onError}
6958 * notification the event is passed on immediately without first emitting the buffer it is in the process of
6959 * assembling.
6960 * <p>
6961 * <img width="640" height="320" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/buffer5.v3.png" alt="">
6962 * <dl>
6963 * <dt><b>Backpressure:</b></dt>
6964 * <dd>This operator does not support backpressure as it uses time. It requests {@link Long#MAX_VALUE}
6965 * upstream and does not obey downstream requests.</dd>
6966 * <dt><b>Scheduler:</b></dt>
6967 * <dd>This version of {@code buffer} operates by default on the {@code computation} {@link Scheduler}.</dd>
6968 * </dl>
6969 *
6970 * @param timespan
6971 * the period of time each buffer collects items before it is emitted and replaced with a new
6972 * buffer
6973 * @param unit
6974 * the unit of time that applies to the {@code timespan} argument
6975 * @return the new {@code Flowable} instance
6976 * @throws NullPointerException if {@code unit} is {@code null}
6977 * @see <a href="http://reactivex.io/documentation/operators/buffer.html">ReactiveX operators documentation: Buffer</a>
6978 */
6979 @CheckReturnValue
6980 @BackpressureSupport(BackpressureKind.ERROR)
6981 @SchedulerSupport(SchedulerSupport.COMPUTATION)
6982 @NonNull
6983 public final Flowable<List<T>> buffer(long timespan, @NonNull TimeUnit unit) {
6984 return buffer(timespan, unit, Schedulers.computation(), Integer.MAX_VALUE);
6985 }
6986
6987 /**
6988 * Returns a {@code Flowable} that emits buffers of items it collects from the current {@code Flowable}. The resulting
6989 * {@code Flowable} emits connected, non-overlapping buffers, each of a fixed duration specified by the
6990 * {@code timespan} argument or a maximum size specified by the {@code count} argument (whichever is reached
6991 * first). When the current {@code Flowable} completes, the resulting {@code Flowable} emits the current buffer and propagates the
6992 * notification from the current {@code Flowable}. Note that if the current {@code Flowable} issues an {@code onError} notification the event
6993 * is passed on immediately without first emitting the buffer it is in the process of assembling.
6994 * <p>
6995 * <img width="640" height="320" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/buffer6.v3.png" alt="">
6996 * <dl>
6997 * <dt><b>Backpressure:</b></dt>
6998 * <dd>This operator does not support backpressure as it uses time. It requests {@link Long#MAX_VALUE}
6999 * upstream and does not obey downstream requests.</dd>
7000 * <dt><b>Scheduler:</b></dt>
7001 * <dd>This version of {@code buffer} operates by default on the {@code computation} {@link Scheduler}.</dd>
7002 * </dl>
7003 *
7004 * @param timespan
7005 * the period of time each buffer collects items before it is emitted and replaced with a new
7006 * buffer
7007 * @param unit
7008 * the unit of time which applies to the {@code timespan} argument
7009 * @param count
7010 * the maximum size of each buffer before it is emitted
7011 * @return the new {@code Flowable} instance
7012 * @throws NullPointerException if {@code unit} is {@code null}
7013 * @throws IllegalArgumentException if {@code count} is non-positive
7014 * @see <a href="http://reactivex.io/documentation/operators/buffer.html">ReactiveX operators documentation: Buffer</a>
7015 */
7016 @CheckReturnValue
7017 @BackpressureSupport(BackpressureKind.ERROR)
7018 @SchedulerSupport(SchedulerSupport.COMPUTATION)
7019 @NonNull
7020 public final Flowable<List<T>> buffer(long timespan, @NonNull TimeUnit unit, int count) {
7021 return buffer(timespan, unit, Schedulers.computation(), count);
7022 }
7023
7024 /**
7025 * Returns a {@code Flowable} that emits buffers of items it collects from the current {@code Flowable}. The resulting
7026 * {@code Flowable} emits connected, non-overlapping buffers, each of a fixed duration specified by the
7027 * {@code timespan} argument as measured on the specified {@code scheduler}, or a maximum size specified by
7028 * the {@code count} argument (whichever is reached first). When the current {@code Flowable} completes, the resulting
7029 * {@code Flowable} emits the current buffer and propagates the notification from the current {@code Flowable}. Note that if the
7030 * current {@code Flowable} issues an {@code onError} notification the event is passed on immediately without first emitting the
7031 * buffer it is in the process of assembling.
7032 * <p>
7033 * <img width="640" height="320" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/buffer6.s.v3.png" alt="">
7034 * <dl>
7035 * <dt><b>Backpressure:</b></dt>
7036 * <dd>This operator does not support backpressure as it uses time. It requests {@link Long#MAX_VALUE}
7037 * upstream and does not obey downstream requests.</dd>
7038 * <dt><b>Scheduler:</b></dt>
7039 * <dd>You specify which {@link Scheduler} this operator will use.</dd>
7040 * </dl>
7041 *
7042 * @param timespan
7043 * the period of time each buffer collects items before it is emitted and replaced with a new
7044 * buffer
7045 * @param unit
7046 * the unit of time which applies to the {@code timespan} argument
7047 * @param scheduler
7048 * the {@code Scheduler} to use when determining the end and start of a buffer
7049 * @param count
7050 * the maximum size of each buffer before it is emitted
7051 * @return the new {@code Flowable} instance
7052 * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null}
7053 * @throws IllegalArgumentException if {@code count} is non-positive
7054 * @see <a href="http://reactivex.io/documentation/operators/buffer.html">ReactiveX operators documentation: Buffer</a>
7055 */
7056 @CheckReturnValue
7057 @BackpressureSupport(BackpressureKind.ERROR)
7058 @SchedulerSupport(SchedulerSupport.CUSTOM)
7059 @NonNull
7060 public final Flowable<List<T>> buffer(long timespan, @NonNull TimeUnit unit, @NonNull Scheduler scheduler, int count) {
7061 return buffer(timespan, unit, scheduler, count, ArrayListSupplier.asSupplier(), false);
7062 }
7063
7064 /**
7065 * Returns a {@code Flowable} that emits buffers of items it collects from the current {@code Flowable}. The resulting
7066 * {@code Flowable} emits connected, non-overlapping buffers, each of a fixed duration specified by the
7067 * {@code timespan} argument as measured on the specified {@code scheduler}, or a maximum size specified by
7068 * the {@code count} argument (whichever is reached first). When the current {@code Flowable} completes, the resulting
7069 * {@code Flowable} emits the current buffer and propagates the notification from the current {@code Flowable}. Note that if the
7070 * current {@code Flowable} issues an {@code onError} notification the event is passed on immediately without first emitting the
7071 * buffer it is in the process of assembling.
7072 * <p>
7073 * <img width="640" height="320" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/buffer6.s.v3.png" alt="">
7074 * <dl>
7075 * <dt><b>Backpressure:</b></dt>
7076 * <dd>This operator does not support backpressure as it uses time. It requests {@link Long#MAX_VALUE}
7077 * upstream and does not obey downstream requests.</dd>
7078 * <dt><b>Scheduler:</b></dt>
7079 * <dd>You specify which {@link Scheduler} this operator will use.</dd>
7080 * </dl>
7081 *
7082 * @param <U> the collection subclass type to buffer into
7083 * @param timespan
7084 * the period of time each buffer collects items before it is emitted and replaced with a new
7085 * buffer
7086 * @param unit
7087 * the unit of time which applies to the {@code timespan} argument
7088 * @param scheduler
7089 * the {@code Scheduler} to use when determining the end and start of a buffer
7090 * @param count
7091 * the maximum size of each buffer before it is emitted
7092 * @param bufferSupplier
7093 * a factory function that returns an instance of the collection subclass to be used and returned
7094 * as the buffer
7095 * @param restartTimerOnMaxSize if {@code true}, the time window is restarted when the max capacity of the current buffer
7096 * is reached
7097 * @return the new {@code Flowable} instance
7098 * @throws NullPointerException if {@code unit}, {@code scheduler} or {@code bufferSupplier} is {@code null}
7099 * @throws IllegalArgumentException if {@code count} is non-positive
7100 * @see <a href="http://reactivex.io/documentation/operators/buffer.html">ReactiveX operators documentation: Buffer</a>
7101 */
7102 @CheckReturnValue
7103 @BackpressureSupport(BackpressureKind.ERROR)
7104 @SchedulerSupport(SchedulerSupport.CUSTOM)
7105 @NonNull
7106 public final <@NonNull U extends Collection<? super T>> Flowable<U> buffer(
7107 long timespan, @NonNull TimeUnit unit,
7108 @NonNull Scheduler scheduler, int count,
7109 @NonNull Supplier<U> bufferSupplier,
7110 boolean restartTimerOnMaxSize) {
7111 Objects.requireNonNull(unit, "unit is null");
7112 Objects.requireNonNull(scheduler, "scheduler is null");
7113 Objects.requireNonNull(bufferSupplier, "bufferSupplier is null");
7114 ObjectHelper.verifyPositive(count, "count");
7115 return RxJavaPlugins.onAssembly(new FlowableBufferTimed<>(this, timespan, timespan, unit, scheduler, bufferSupplier, count, restartTimerOnMaxSize));
7116 }
7117
7118 /**
7119 * Returns a {@code Flowable} that emits buffers of items it collects from the current {@code Flowable}. The resulting
7120 * {@code Flowable} emits connected, non-overlapping buffers, each of a fixed duration specified by the
7121 * {@code timespan} argument and on the specified {@code scheduler}. When the current {@code Flowable} completes, the
7122 * resulting {@code Flowable} emits the current buffer and propagates the notification from the current {@code Flowable}. Note that
7123 * if the current {@code Flowable} issues an {@code onError} notification the event is passed on immediately without first emitting
7124 * the buffer it is in the process of assembling.
7125 * <p>
7126 * <img width="640" height="320" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/buffer5.s.v3.png" alt="">
7127 * <dl>
7128 * <dt><b>Backpressure:</b></dt>
7129 * <dd>This operator does not support backpressure as it uses time. It requests {@link Long#MAX_VALUE}
7130 * upstream and does not obey downstream requests.</dd>
7131 * <dt><b>Scheduler:</b></dt>
7132 * <dd>You specify which {@link Scheduler} this operator will use.</dd>
7133 * </dl>
7134 *
7135 * @param timespan
7136 * the period of time each buffer collects items before it is emitted and replaced with a new
7137 * buffer
7138 * @param unit
7139 * the unit of time which applies to the {@code timespan} argument
7140 * @param scheduler
7141 * the {@code Scheduler} to use when determining the end and start of a buffer
7142 * @return the new {@code Flowable} instance
7143 * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null}
7144 * @see <a href="http://reactivex.io/documentation/operators/buffer.html">ReactiveX operators documentation: Buffer</a>
7145 */
7146 @CheckReturnValue
7147 @BackpressureSupport(BackpressureKind.ERROR)
7148 @SchedulerSupport(SchedulerSupport.CUSTOM)
7149 @NonNull
7150 public final Flowable<List<T>> buffer(long timespan, @NonNull TimeUnit unit, @NonNull Scheduler scheduler) {
7151 return buffer(timespan, unit, scheduler, Integer.MAX_VALUE, ArrayListSupplier.asSupplier(), false);
7152 }
7153
7154 /**
7155 * Returns a {@code Flowable} that emits buffers of items it collects from the current {@code Flowable}. The resulting
7156 * {@code Flowable} emits buffers that it creates when the specified {@code openingIndicator} {@link Publisher} emits an
7157 * item, and closes when the {@code Publisher} returned from {@code closingIndicator} emits an item. If any of the current
7158 * {@code PFlowable}, {@code openingIndicator} or {@code closingIndicator} issues an {@code onError} notification the event is passed
7159 * on immediately without first emitting the buffer it is in the process of assembling.
7160 * <p>
7161 * <img width="640" height="470" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/buffer2.v3.png" alt="">
7162 * <dl>
7163 * <dt><b>Backpressure:</b></dt>
7164 * <dd>This operator does not support backpressure as it is instead controlled by the given {@code Publisher}s and
7165 * buffers data. It requests {@link Long#MAX_VALUE} upstream and does not obey downstream requests.</dd>
7166 * <dt><b>Scheduler:</b></dt>
7167 * <dd>This version of {@code buffer} does not operate by default on a particular {@link Scheduler}.</dd>
7168 * </dl>
7169 *
7170 * @param <TOpening> the element type of the buffer-opening {@code Publisher}
7171 * @param <TClosing> the element type of the individual buffer-closing {@code Publisher}s
7172 * @param openingIndicator
7173 * the {@code Publisher} that, when it emits an item, causes a new buffer to be created
7174 * @param closingIndicator
7175 * the {@link Function} that is used to produce a {@code Publisher} for every buffer created. When this
7176 * {@code Publisher} emits an item, the associated buffer is emitted.
7177 * @return the new {@code Flowable} instance
7178 * @throws NullPointerException if {@code openingIndicator} or {@code closingIndicator} is {@code null}
7179 * @see <a href="http://reactivex.io/documentation/operators/buffer.html">ReactiveX operators documentation: Buffer</a>
7180 */
7181 @CheckReturnValue
7182 @BackpressureSupport(BackpressureKind.ERROR)
7183 @SchedulerSupport(SchedulerSupport.NONE)
7184 @NonNull
7185 public final <@NonNull TOpening, @NonNull TClosing> Flowable<List<T>> buffer(
7186 @NonNull Publisher<? extends TOpening> openingIndicator,
7187 @NonNull Function<? super TOpening, @NonNull ? extends Publisher<? extends TClosing>> closingIndicator) {
7188 return buffer(openingIndicator, closingIndicator, ArrayListSupplier.asSupplier());
7189 }
7190
7191 /**
7192 * Returns a {@code Flowable} that emits buffers of items it collects from the current {@code Flowable}. The resulting
7193 * {@code Flowable} emits buffers that it creates when the specified {@code openingIndicator} {@link Publisher} emits an
7194 * item, and closes when the {@code Publisher} returned from {@code closingIndicator} emits an item. If any of the current
7195 * {@code Flowable}, {@code openingIndicator} or {@code closingIndicator} issues an {@code onError} notification the event is passed
7196 * on immediately without first emitting the buffer it is in the process of assembling.
7197 * <p>
7198 * <img width="640" height="470" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/buffer2.v3.png" alt="">
7199 * <dl>
7200 * <dt><b>Backpressure:</b></dt>
7201 * <dd>This operator does not support backpressure as it is instead controlled by the given {@code Publisher}s and
7202 * buffers data. It requests {@link Long#MAX_VALUE} upstream and does not obey downstream requests.</dd>
7203 * <dt><b>Scheduler:</b></dt>
7204 * <dd>This version of {@code buffer} does not operate by default on a particular {@link Scheduler}.</dd>
7205 * </dl>
7206 *
7207 * @param <U> the collection subclass type to buffer into
7208 * @param <TOpening> the element type of the buffer-opening {@code Publisher}
7209 * @param <TClosing> the element type of the individual buffer-closing {@code Publisher}s
7210 * @param openingIndicator
7211 * the {@code Publisher} that, when it emits an item, causes a new buffer to be created
7212 * @param closingIndicator
7213 * the {@link Function} that is used to produce a {@code Publisher} for every buffer created. When this
7214 * {@code Publisher} emits an item, the associated buffer is emitted.
7215 * @param bufferSupplier
7216 * a factory function that returns an instance of the collection subclass to be used and returned
7217 * as the buffer
7218 * @return the new {@code Flowable} instance
7219 * @throws NullPointerException if {@code openingIndicator}, {@code closingIndicator} or {@code bufferSupplier} is {@code null}
7220 * @see <a href="http://reactivex.io/documentation/operators/buffer.html">ReactiveX operators documentation: Buffer</a>
7221 */
7222 @CheckReturnValue
7223 @BackpressureSupport(BackpressureKind.ERROR)
7224 @SchedulerSupport(SchedulerSupport.NONE)
7225 @NonNull
7226 public final <@NonNull TOpening, @NonNull TClosing, @NonNull U extends Collection<? super T>> Flowable<U> buffer(
7227 @NonNull Publisher<? extends TOpening> openingIndicator,
7228 @NonNull Function<? super TOpening, @NonNull ? extends Publisher<? extends TClosing>> closingIndicator,
7229 @NonNull Supplier<U> bufferSupplier) {
7230 Objects.requireNonNull(openingIndicator, "openingIndicator is null");
7231 Objects.requireNonNull(closingIndicator, "closingIndicator is null");
7232 Objects.requireNonNull(bufferSupplier, "bufferSupplier is null");
7233 return RxJavaPlugins.onAssembly(new FlowableBufferBoundary<T, U, TOpening, TClosing>(this, openingIndicator, closingIndicator, bufferSupplier));
7234 }
7235
7236 /**
7237 * Returns a {@code Flowable} that emits non-overlapping buffered items from the current {@code Flowable} each time the
7238 * specified boundary {@link Publisher} emits an item.
7239 * <p>
7240 * <img width="640" height="395" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/buffer8.v3.png" alt="">
7241 * <p>
7242 * Completion of either the source or the boundary {@code Publisher} causes the returned {@code Publisher} to emit the
7243 * latest buffer and complete. If either the current {@code Flowable} or the boundary {@code Publisher} issues an {@code onError} notification
7244 * the event is passed on immediately without first emitting the buffer it is in the process of assembling.
7245 * <dl>
7246 * <dt><b>Backpressure:</b></dt>
7247 * <dd>This operator does not support backpressure as it is instead controlled by the {@code Publisher}
7248 * {@code boundary} and buffers data. It requests {@link Long#MAX_VALUE} upstream and does not obey
7249 * downstream requests.</dd>
7250 * <dt><b>Scheduler:</b></dt>
7251 * <dd>This version of {@code buffer} does not operate by default on a particular {@link Scheduler}.</dd>
7252 * </dl>
7253 *
7254 * @param <B>
7255 * the boundary value type (ignored)
7256 * @param boundaryIndicator
7257 * the boundary {@code Publisher}
7258 * @return the new {@code Flowable} instance
7259 * @throws NullPointerException if {@code boundaryIndicator} is {@code null}
7260 * @see #buffer(Publisher, int)
7261 * @see <a href="http://reactivex.io/documentation/operators/buffer.html">ReactiveX operators documentation: Buffer</a>
7262 */
7263 @CheckReturnValue
7264 @BackpressureSupport(BackpressureKind.ERROR)
7265 @SchedulerSupport(SchedulerSupport.NONE)
7266 @NonNull
7267 public final <@NonNull B> Flowable<List<T>> buffer(@NonNull Publisher<B> boundaryIndicator) {
7268 return buffer(boundaryIndicator, ArrayListSupplier.asSupplier());
7269 }
7270
7271 /**
7272 * Returns a {@code Flowable} that emits non-overlapping buffered items from the current {@code Flowable} each time the
7273 * specified boundary {@link Publisher} emits an item.
7274 * <p>
7275 * <img width="640" height="395" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/buffer8.v3.png" alt="">
7276 * <p>
7277 * Completion of either the source or the boundary {@code Publisher} causes the returned {@code Publisher} to emit the
7278 * latest buffer and complete. If either the current {@code Flowable} or the boundary {@code Publisher} issues an {@code onError} notification
7279 * the event is passed on immediately without first emitting the buffer it is in the process of assembling.
7280 * <dl>
7281 * <dt><b>Backpressure:</b></dt>
7282 * <dd>This operator does not support backpressure as it is instead controlled by the {@code Publisher}
7283 * {@code boundary} and buffers data. It requests {@link Long#MAX_VALUE} upstream and does not obey
7284 * downstream requests.</dd>
7285 * <dt><b>Scheduler:</b></dt>
7286 * <dd>This version of {@code buffer} does not operate by default on a particular {@link Scheduler}.</dd>
7287 * </dl>
7288 *
7289 * @param <B>
7290 * the boundary value type (ignored)
7291 * @param boundaryIndicator
7292 * the boundary {@code Publisher}
7293 * @param initialCapacity
7294 * the initial capacity of each buffer chunk
7295 * @return the new {@code Flowable} instance
7296 * @throws NullPointerException if {@code boundaryIndicator} is {@code null}
7297 * @throws IllegalArgumentException if {@code initialCapacity} is non-positive
7298 * @see <a href="http://reactivex.io/documentation/operators/buffer.html">ReactiveX operators documentation: Buffer</a>
7299 * @see #buffer(Publisher)
7300 */
7301 @CheckReturnValue
7302 @BackpressureSupport(BackpressureKind.ERROR)
7303 @SchedulerSupport(SchedulerSupport.NONE)
7304 @NonNull
7305 public final <@NonNull B> Flowable<List<T>> buffer(@NonNull Publisher<B> boundaryIndicator, int initialCapacity) {
7306 ObjectHelper.verifyPositive(initialCapacity, "initialCapacity");
7307 return buffer(boundaryIndicator, Functions.createArrayList(initialCapacity));
7308 }
7309
7310 /**
7311 * Returns a {@code Flowable} that emits non-overlapping buffered items from the current {@code Flowable} each time the
7312 * specified boundary {@link Publisher} emits an item.
7313 * <p>
7314 * <img width="640" height="395" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/buffer8.v3.png" alt="">
7315 * <p>
7316 * Completion of either the source or the boundary {@code Publisher} causes the returned {@code Publisher} to emit the
7317 * latest buffer and complete. If either the current {@code Flowable} or the boundary {@code Publisher} issues an {@code onError} notification
7318 * the event is passed on immediately without first emitting the buffer it is in the process of assembling.
7319 * <dl>
7320 * <dt><b>Backpressure:</b></dt>
7321 * <dd>This operator does not support backpressure as it is instead controlled by the {@code Publisher}
7322 * {@code boundary} and buffers data. It requests {@link Long#MAX_VALUE} upstream and does not obey
7323 * downstream requests.</dd>
7324 * <dt><b>Scheduler:</b></dt>
7325 * <dd>This version of {@code buffer} does not operate by default on a particular {@link Scheduler}.</dd>
7326 * </dl>
7327 *
7328 * @param <U> the collection subclass type to buffer into
7329 * @param <B>
7330 * the boundary value type (ignored)
7331 * @param boundaryIndicator
7332 * the boundary {@code Publisher}
7333 * @param bufferSupplier
7334 * a factory function that returns an instance of the collection subclass to be used and returned
7335 * as the buffer
7336 * @return the new {@code Flowable} instance
7337 * @throws NullPointerException if {@code boundaryIndicator} or {@code bufferSupplier} is {@code null}
7338 * @see #buffer(Publisher, int)
7339 * @see <a href="http://reactivex.io/documentation/operators/buffer.html">ReactiveX operators documentation: Buffer</a>
7340 */
7341 @CheckReturnValue
7342 @BackpressureSupport(BackpressureKind.ERROR)
7343 @SchedulerSupport(SchedulerSupport.NONE)
7344 @NonNull
7345 public final <@NonNull B, @NonNull U extends Collection<? super T>> Flowable<U> buffer(@NonNull Publisher<B> boundaryIndicator, @NonNull Supplier<U> bufferSupplier) {
7346 Objects.requireNonNull(boundaryIndicator, "boundaryIndicator is null");
7347 Objects.requireNonNull(bufferSupplier, "bufferSupplier is null");
7348 return RxJavaPlugins.onAssembly(new FlowableBufferExactBoundary<>(this, boundaryIndicator, bufferSupplier));
7349 }
7350
7351 /**
7352 * Returns a {@code Flowable} that subscribes to this {@link Publisher} lazily, caches all of its events
7353 * and replays them, in the same order as received, to all the downstream subscribers.
7354 * <p>
7355 * <img width="640" height="410" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/cache.v3.png" alt="">
7356 * <p>
7357 * This is useful when you want a {@code Publisher} to cache responses and you can't control the
7358 * subscribe/cancel behavior of all the {@link Subscriber}s.
7359 * <p>
7360 * The operator subscribes only when the first downstream subscriber subscribes and maintains
7361 * a single subscription towards this {@code Publisher}. In contrast, the operator family of {@link #replay()}
7362 * that return a {@link ConnectableFlowable} require an explicit call to {@link ConnectableFlowable#connect()}.
7363 * <p>
7364 * <em>Note:</em> You sacrifice the ability to cancel the origin when you use the {@code cache}
7365 * operator so be careful not to use this operator on {@code Publisher}s that emit an infinite or very large number
7366 * of items that will use up memory.
7367 * A possible workaround is to apply {@link #takeUntil(Publisher)} with a predicate or
7368 * another source before (and perhaps after) the application of {@code cache()}.
7369 * <pre><code>
7370 * AtomicBoolean shouldStop = new AtomicBoolean();
7371 *
7372 * source.takeUntil(v -&gt; shouldStop.get())
7373 * .cache()
7374 * .takeUntil(v -&gt; shouldStop.get())
7375 * .subscribe(...);
7376 * </code></pre>
7377 * Since the operator doesn't allow clearing the cached values either, the possible workaround is
7378 * to forget all references to it via {@link #onTerminateDetach()} applied along with the previous
7379 * workaround:
7380 * <pre><code>
7381 * AtomicBoolean shouldStop = new AtomicBoolean();
7382 *
7383 * source.takeUntil(v -&gt; shouldStop.get())
7384 * .onTerminateDetach()
7385 * .cache()
7386 * .takeUntil(v -&gt; shouldStop.get())
7387 * .onTerminateDetach()
7388 * .subscribe(...);
7389 * </code></pre>
7390 * <dl>
7391 * <dt><b>Backpressure:</b></dt>
7392 * <dd>The operator consumes this {@code Publisher} in an unbounded fashion but respects the backpressure
7393 * of each downstream {@code Subscriber} individually.</dd>
7394 * <dt><b>Scheduler:</b></dt>
7395 * <dd>{@code cache} does not operate by default on a particular {@link Scheduler}.</dd>
7396 * </dl>
7397 *
7398 * @return the new {@code Flowable} instance
7399 * @see <a href="http://reactivex.io/documentation/operators/replay.html">ReactiveX operators documentation: Replay</a>
7400 * @see #takeUntil(Predicate)
7401 * @see #takeUntil(Publisher)
7402 */
7403 @CheckReturnValue
7404 @BackpressureSupport(BackpressureKind.FULL)
7405 @SchedulerSupport(SchedulerSupport.NONE)
7406 @NonNull
7407 public final Flowable<T> cache() {
7408 return cacheWithInitialCapacity(16);
7409 }
7410
7411 /**
7412 * Returns a {@code Flowable} that subscribes to this {@link Publisher} lazily, caches all of its events
7413 * and replays them, in the same order as received, to all the downstream subscribers.
7414 * <p>
7415 * <img width="640" height="410" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/cache.v3.png" alt="">
7416 * <p>
7417 * This is useful when you want a {@code Publisher} to cache responses and you can't control the
7418 * subscribe/cancel behavior of all the {@link Subscriber}s.
7419 * <p>
7420 * The operator subscribes only when the first downstream subscriber subscribes and maintains
7421 * a single subscription towards this {@code Publisher}. In contrast, the operator family of {@link #replay()}
7422 * that return a {@link ConnectableFlowable} require an explicit call to {@link ConnectableFlowable#connect()}.
7423 * <p>
7424 * <em>Note:</em> You sacrifice the ability to cancel the origin when you use the {@code cache}
7425 * operator so be careful not to use this operator on {@code Publisher}s that emit an infinite or very large number
7426 * of items that will use up memory.
7427 * A possible workaround is to apply {@link #takeUntil(Publisher)} with a predicate or
7428 * another source before (and perhaps after) the application of {@code cacheWithInitialCapacity()}.
7429 * <pre><code>
7430 * AtomicBoolean shouldStop = new AtomicBoolean();
7431 *
7432 * source.takeUntil(v -&gt; shouldStop.get())
7433 * .cache()
7434 * .takeUntil(v -&gt; shouldStop.get())
7435 * .subscribe(...);
7436 * </code></pre>
7437 * Since the operator doesn't allow clearing the cached values either, the possible workaround is
7438 * to forget all references to it via {@link #onTerminateDetach()} applied along with the previous
7439 * workaround:
7440 * <pre><code>
7441 * AtomicBoolean shouldStop = new AtomicBoolean();
7442 *
7443 * source.takeUntil(v -&gt; shouldStop.get())
7444 * .onTerminateDetach()
7445 * .cache()
7446 * .takeUntil(v -&gt; shouldStop.get())
7447 * .onTerminateDetach()
7448 * .subscribe(...);
7449 * </code></pre>
7450 * <dl>
7451 * <dt><b>Backpressure:</b></dt>
7452 * <dd>The operator consumes this {@code Publisher} in an unbounded fashion but respects the backpressure
7453 * of each downstream {@code Subscriber} individually.</dd>
7454 * <dt><b>Scheduler:</b></dt>
7455 * <dd>{@code cacheWithInitialCapacity} does not operate by default on a particular {@link Scheduler}.</dd>
7456 * </dl>
7457 * <p>
7458 * <em>Note:</em> The capacity hint is not an upper bound on cache size. For that, consider
7459 * {@link #replay(int)} in combination with {@link ConnectableFlowable#autoConnect()} or similar.
7460 *
7461 * @param initialCapacity hint for number of items to cache (for optimizing underlying data structure)
7462 * @return the new {@code Flowable} instance
7463 * @throws IllegalArgumentException if {@code initialCapacity} is non-positive
7464 * @see <a href="http://reactivex.io/documentation/operators/replay.html">ReactiveX operators documentation: Replay</a>
7465 * @see #takeUntil(Predicate)
7466 * @see #takeUntil(Publisher)
7467 */
7468 @CheckReturnValue
7469 @BackpressureSupport(BackpressureKind.FULL)
7470 @SchedulerSupport(SchedulerSupport.NONE)
7471 @NonNull
7472 public final Flowable<T> cacheWithInitialCapacity(int initialCapacity) {
7473 ObjectHelper.verifyPositive(initialCapacity, "initialCapacity");
7474 return RxJavaPlugins.onAssembly(new FlowableCache<>(this, initialCapacity));
7475 }
7476
7477 /**
7478 * Returns a {@code Flowable} that emits the items emitted by the current {@code Flowable}, converted to the specified
7479 * type.
7480 * <p>
7481 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/cast.v3.png" alt="">
7482 * <dl>
7483 * <dt><b>Backpressure:</b></dt>
7484 * <dd>The operator doesn't interfere with backpressure which is determined by the current {@code Flowable}'s
7485 * backpressure behavior.</dd>
7486 * <dt><b>Scheduler:</b></dt>
7487 * <dd>{@code cast} does not operate by default on a particular {@link Scheduler}.</dd>
7488 * </dl>
7489 *
7490 * @param <U> the output value type cast to
7491 * @param clazz
7492 * the target class type that {@code cast} will cast the items emitted by the current {@code Flowable}
7493 * into before emitting them from the resulting {@code Flowable}
7494 * @return the new {@code Flowable} instance
7495 * @throws NullPointerException if {@code clazz} is {@code null}
7496 * @see <a href="http://reactivex.io/documentation/operators/map.html">ReactiveX operators documentation: Map</a>
7497 */
7498 @CheckReturnValue
7499 @NonNull
7500 @BackpressureSupport(BackpressureKind.PASS_THROUGH)
7501 @SchedulerSupport(SchedulerSupport.NONE)
7502 public final <@NonNull U> Flowable<U> cast(@NonNull Class<U> clazz) {
7503 Objects.requireNonNull(clazz, "clazz is null");
7504 return map(Functions.castFunction(clazz));
7505 }
7506
7507 /**
7508 * Collects items emitted by the finite source {@link Publisher} into a single mutable data structure and returns
7509 * a {@link Single} that emits this structure.
7510 * <p>
7511 * <img width="640" height="330" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/collect.v3.png" alt="">
7512 * <p>
7513 * This is a simplified version of {@code reduce} that does not need to return the state on each pass.
7514 * <p>
7515 * Note that this operator requires the upstream to signal {@code onComplete} for the accumulator object to
7516 * be emitted. Sources that are infinite and never complete will never emit anything through this
7517 * operator and an infinite source may lead to a fatal {@link OutOfMemoryError}.
7518 * <dl>
7519 * <dt><b>Backpressure:</b></dt>
7520 * <dd>This operator does not support backpressure because by intent it will receive all values and reduce
7521 * them to a single {@code onNext}.</dd>
7522 * <dt><b>Scheduler:</b></dt>
7523 * <dd>{@code collect} does not operate by default on a particular {@link Scheduler}.</dd>
7524 * </dl>
7525 *
7526 * @param <U> the accumulator and output type
7527 * @param initialItemSupplier
7528 * the mutable data structure that will collect the items
7529 * @param collector
7530 * a function that accepts the {@code state} and an emitted item, and modifies {@code state}
7531 * accordingly
7532 * @return the new {@code Single} instance
7533 * @throws NullPointerException if {@code initialItemSupplier} or {@code collector} is {@code null}
7534 * @see <a href="http://reactivex.io/documentation/operators/reduce.html">ReactiveX operators documentation: Reduce</a>
7535 * @see #collect(Collector)
7536 */
7537 @CheckReturnValue
7538 @NonNull
7539 @BackpressureSupport(BackpressureKind.UNBOUNDED_IN)
7540 @SchedulerSupport(SchedulerSupport.NONE)
7541 public final <@NonNull U> Single<U> collect(@NonNull Supplier<? extends U> initialItemSupplier, @NonNull BiConsumer<? super U, ? super T> collector) {
7542 Objects.requireNonNull(initialItemSupplier, "initialItemSupplier is null");
7543 Objects.requireNonNull(collector, "collector is null");
7544 return RxJavaPlugins.onAssembly(new FlowableCollectSingle<>(this, initialItemSupplier, collector));
7545 }
7546
7547 /**
7548 * Collects items emitted by the finite source {@link Publisher} into a single mutable data structure and returns
7549 * a {@link Single} that emits this structure.
7550 * <p>
7551 * <img width="640" height="330" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/collect.v3.png" alt="">
7552 * <p>
7553 * This is a simplified version of {@code reduce} that does not need to return the state on each pass.
7554 * <p>
7555 * Note that this operator requires the upstream to signal {@code onComplete} for the accumulator object to
7556 * be emitted. Sources that are infinite and never complete will never emit anything through this
7557 * operator and an infinite source may lead to a fatal {@link OutOfMemoryError}.
7558 * <dl>
7559 * <dt><b>Backpressure:</b></dt>
7560 * <dd>This operator does not support backpressure because by intent it will receive all values and reduce
7561 * them to a single {@code onNext}.</dd>
7562 * <dt><b>Scheduler:</b></dt>
7563 * <dd>{@code collectInto} does not operate by default on a particular {@link Scheduler}.</dd>
7564 * </dl>
7565 *
7566 * @param <U> the accumulator and output type
7567 * @param initialItem
7568 * the mutable data structure that will collect the items
7569 * @param collector
7570 * a function that accepts the {@code state} and an emitted item, and modifies {@code state}
7571 * accordingly
7572 * @return the new {@code Single} instance
7573 * @throws NullPointerException if {@code initialItem} or {@code collector} is {@code null}
7574 * @see <a href="http://reactivex.io/documentation/operators/reduce.html">ReactiveX operators documentation: Reduce</a>
7575 */
7576 @CheckReturnValue
7577 @NonNull
7578 @BackpressureSupport(BackpressureKind.UNBOUNDED_IN)
7579 @SchedulerSupport(SchedulerSupport.NONE)
7580 public final <@NonNull U> Single<U> collectInto(U initialItem, @NonNull BiConsumer<? super U, ? super T> collector) {
7581 Objects.requireNonNull(initialItem, "initialItem is null");
7582 return collect(Functions.justSupplier(initialItem), collector);
7583 }
7584
7585 /**
7586 * Transform the current {@code Flowable} by applying a particular {@link FlowableTransformer} function to it.
7587 * <p>
7588 * This method operates on the {@code Flowable} itself whereas {@link #lift} operates on the {@code Flowable}'s
7589 * {@link Subscriber}s.
7590 * <p>
7591 * If the operator you are creating is designed to act on the individual items emitted by a current
7592 * {@code Flowable}, use {@link #lift}. If your operator is designed to transform the current {@code Flowable} as a whole
7593 * (for instance, by applying a particular set of existing RxJava operators to it) use {@code compose}.
7594 * <dl>
7595 * <dt><b>Backpressure:</b></dt>
7596 * <dd>The operator itself doesn't interfere with the backpressure behavior which only depends
7597 * on what kind of {@link Publisher} the {@code FlowableTransformer} returns.</dd>
7598 * <dt><b>Scheduler:</b></dt>
7599 * <dd>{@code compose} does not operate by default on a particular {@link Scheduler}.</dd>
7600 * </dl>
7601 *
7602 * @param <R> the value type of the output {@code Publisher}
7603 * @param composer implements the function that transforms the current {@code Flowable}
7604 * @return the new composed {@code Flowable} instance
7605 * @throws NullPointerException if {@code composer} is {@code null}
7606 * @see <a href="https://github.com/ReactiveX/RxJava/wiki/Implementing-Your-Own-Operators">RxJava wiki: Implementing Your Own Operators</a>
7607 */
7608 @SuppressWarnings("unchecked")
7609 @CheckReturnValue
7610 @BackpressureSupport(BackpressureKind.PASS_THROUGH)
7611 @SchedulerSupport(SchedulerSupport.NONE)
7612 @NonNull
7613 public final <@NonNull R> Flowable<R> compose(@NonNull FlowableTransformer<? super T, ? extends R> composer) {
7614 return fromPublisher(((FlowableTransformer<T, R>) Objects.requireNonNull(composer, "composer is null")).apply(this));
7615 }
7616
7617 /**
7618 * Returns a new {@code Flowable} that emits items resulting from applying a function that you supply to each item
7619 * emitted by the current {@code Flowable}, where that function returns a {@link Publisher}, and then emitting the items
7620 * that result from concatenating those returned {@code Publisher}s.
7621 * <p>
7622 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/concatMap.v3.png" alt="">
7623 * <p>
7624 * Note that there is no guarantee where the given {@code mapper} function will be executed; it could be on the subscribing thread,
7625 * on the upstream thread signaling the new item to be mapped or on the thread where the inner source terminates. To ensure
7626 * the {@code mapper} function is confined to a known thread, use the {@link #concatMap(Function, int, Scheduler)} overload.
7627 * <dl>
7628 * <dt><b>Backpressure:</b></dt>
7629 * <dd>The operator honors backpressure from downstream. Both this and the inner {@code Publisher}s are
7630 * expected to honor backpressure as well. If the current {@code Flowable} violates the rule, the operator will
7631 * signal a {@link MissingBackpressureException}. If any of the inner {@code Publisher}s doesn't honor
7632 * backpressure, that <em>may</em> throw an {@link IllegalStateException} when that
7633 * {@code Publisher} completes.</dd>
7634 * <dt><b>Scheduler:</b></dt>
7635 * <dd>{@code concatMap} does not operate by default on a particular {@link Scheduler}.</dd>
7636 * </dl>
7637 *
7638 * @param <R> the type of the inner {@code Publisher} sources and thus the output type
7639 * @param mapper
7640 * a function that, when applied to an item emitted by the current {@code Flowable}, returns a
7641 * {@code Publisher}
7642 * @return the new {@code Flowable} instance
7643 * @throws NullPointerException if {@code mapper} is {@code null}
7644 * @see <a href="http://reactivex.io/documentation/operators/flatmap.html">ReactiveX operators documentation: FlatMap</a>
7645 */
7646 @CheckReturnValue
7647 @BackpressureSupport(BackpressureKind.FULL)
7648 @SchedulerSupport(SchedulerSupport.NONE)
7649 @NonNull
7650 public final <@NonNull R> Flowable<R> concatMap(@NonNull Function<? super T, @NonNull ? extends Publisher<? extends R>> mapper) {
7651 return concatMap(mapper, 2);
7652 }
7653
7654 /**
7655 * Returns a new {@code Flowable} that emits items resulting from applying a function that you supply to each item
7656 * emitted by the current {@code Flowable}, where that function returns a {@link Publisher}, and then emitting the items
7657 * that result from concatenating those returned {@code Publisher}s.
7658 * <p>
7659 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/concatMap.v3.png" alt="">
7660 * <p>
7661 * Note that there is no guarantee where the given {@code mapper} function will be executed; it could be on the subscribing thread,
7662 * on the upstream thread signaling the new item to be mapped or on the thread where the inner source terminates. To ensure
7663 * the {@code mapper} function is confined to a known thread, use the {@link #concatMap(Function, int, Scheduler)} overload.
7664 * <dl>
7665 * <dt><b>Backpressure:</b></dt>
7666 * <dd>The operator honors backpressure from downstream. Both this and the inner {@code Publisher}s are
7667 * expected to honor backpressure as well. If the current {@code Flowable} violates the rule, the operator will
7668 * signal a {@link MissingBackpressureException}. If any of the inner {@code Publisher}s doesn't honor
7669 * backpressure, that <em>may</em> throw an {@link IllegalStateException} when that
7670 * {@code Publisher} completes.</dd>
7671 * <dt><b>Scheduler:</b></dt>
7672 * <dd>{@code concatMap} does not operate by default on a particular {@link Scheduler}.</dd>
7673 * </dl>
7674 *
7675 * @param <R> the type of the inner {@code Publisher} sources and thus the output type
7676 * @param mapper
7677 * a function that, when applied to an item emitted by the current {@code Flowable}, returns a
7678 * {@code Publisher}
7679 * @param prefetch
7680 * the number of elements to prefetch from the current {@code Flowable}
7681 * @return the new {@code Flowable} instance
7682 * @throws NullPointerException if {@code mapper} is {@code null}
7683 * @throws IllegalArgumentException if {@code prefetch} is non-positive
7684 * @see <a href="http://reactivex.io/documentation/operators/flatmap.html">ReactiveX operators documentation: FlatMap</a>
7685 * @see #concatMap(Function, int, Scheduler)
7686 */
7687 @CheckReturnValue
7688 @NonNull
7689 @BackpressureSupport(BackpressureKind.FULL)
7690 @SchedulerSupport(SchedulerSupport.NONE)
7691 public final <@NonNull R> Flowable<R> concatMap(@NonNull Function<? super T, @NonNull ? extends Publisher<? extends R>> mapper, int prefetch) {
7692 Objects.requireNonNull(mapper, "mapper is null");
7693 ObjectHelper.verifyPositive(prefetch, "prefetch");
7694 if (this instanceof ScalarSupplier) {
7695 @SuppressWarnings("unchecked")
7696 T v = ((ScalarSupplier<T>)this).get();
7697 if (v == null) {
7698 return empty();
7699 }
7700 return FlowableScalarXMap.scalarXMap(v, mapper);
7701 }
7702 return RxJavaPlugins.onAssembly(new FlowableConcatMap<>(this, mapper, prefetch, ErrorMode.IMMEDIATE));
7703 }
7704
7705 /**
7706 * Returns a new {@code Flowable} that emits items resulting from applying a function (on a designated scheduler)
7707 * that you supply to each item emitted by the current {@code Flowable}, where that function returns a {@link Publisher}, and then emitting the items
7708 * that result from concatenating those returned {@code Publisher}s.
7709 * <p>
7710 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/concatMap.v3.png" alt="">
7711 * <p>
7712 * The difference between {@link #concatMap(Function, int)} and this operator is that this operator guarantees the {@code mapper}
7713 * function is executed on the specified scheduler.
7714 * <dl>
7715 * <dt><b>Backpressure:</b></dt>
7716 * <dd>The operator honors backpressure from downstream. Both this and the inner {@code Publisher}s are
7717 * expected to honor backpressure as well. If the current {@code Flowable} violates the rule, the operator will
7718 * signal a {@link MissingBackpressureException}. If any of the inner {@code Publisher}s doesn't honor
7719 * backpressure, that <em>may</em> throw an {@link IllegalStateException} when that
7720 * {@code Publisher} completes.</dd>
7721 * <dt><b>Scheduler:</b></dt>
7722 * <dd>{@code concatMap} executes the given {@code mapper} function on the provided {@link Scheduler}.</dd>
7723 * </dl>
7724 *
7725 * @param <R> the type of the inner {@code Publisher} sources and thus the output type
7726 * @param mapper
7727 * a function that, when applied to an item emitted by the current {@code Flowable}, returns a
7728 * {@code Publisher}
7729 * @param prefetch
7730 * the number of elements to prefetch from the current {@code Flowable}
7731 * @param scheduler
7732 * the scheduler where the {@code mapper} function will be executed
7733 * @return the new {@code Flowable} instance
7734 * @throws NullPointerException if {@code mapper} or {@code scheduler} is {@code null}
7735 * @throws IllegalArgumentException if {@code prefetch} is non-positive
7736 * @see <a href="http://reactivex.io/documentation/operators/flatmap.html">ReactiveX operators documentation: FlatMap</a>
7737 * @since 3.0.0
7738 * @see #concatMap(Function, int)
7739 * @see #concatMapDelayError(Function, boolean, int, Scheduler)
7740 */
7741 @CheckReturnValue
7742 @NonNull
7743 @BackpressureSupport(BackpressureKind.FULL)
7744 @SchedulerSupport(SchedulerSupport.CUSTOM)
7745 public final <@NonNull R> Flowable<R> concatMap(@NonNull Function<? super T, @NonNull ? extends Publisher<? extends R>> mapper, int prefetch, @NonNull Scheduler scheduler) {
7746 Objects.requireNonNull(mapper, "mapper is null");
7747 ObjectHelper.verifyPositive(prefetch, "prefetch");
7748 Objects.requireNonNull(scheduler, "scheduler is null");
7749 return RxJavaPlugins.onAssembly(new FlowableConcatMapScheduler<>(this, mapper, prefetch, ErrorMode.IMMEDIATE, scheduler));
7750 }
7751
7752 /**
7753 * Maps the upstream items into {@link CompletableSource}s and subscribes to them one after the
7754 * other completes.
7755 * <p>
7756 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/concatMap.v3.png" alt="">
7757 * <dl>
7758 * <dt><b>Backpressure:</b></dt>
7759 * <dd>The operator expects the upstream to support backpressure. If this {@code Flowable} violates the rule, the operator will
7760 * signal a {@link MissingBackpressureException}.</dd>
7761 * <dt><b>Scheduler:</b></dt>
7762 * <dd>{@code concatMapCompletable} does not operate by default on a particular {@link Scheduler}.</dd>
7763 * </dl>
7764 * <p>History: 2.1.11 - experimental
7765 * @param mapper the function called with the upstream item and should return
7766 * a {@code CompletableSource} to become the next source to
7767 * be subscribed to
7768 * @return the new {@link Completable} instance
7769 * @throws NullPointerException if {@code mapper} is {@code null}
7770 * @see #concatMapCompletableDelayError(Function)
7771 * @since 2.2
7772 */
7773 @CheckReturnValue
7774 @SchedulerSupport(SchedulerSupport.NONE)
7775 @BackpressureSupport(BackpressureKind.FULL)
7776 @NonNull
7777 public final Completable concatMapCompletable(@NonNull Function<? super T, ? extends CompletableSource> mapper) {
7778 return concatMapCompletable(mapper, 2);
7779 }
7780
7781 /**
7782 * Maps the upstream items into {@link CompletableSource}s and subscribes to them one after the
7783 * other completes.
7784 * <p>
7785 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/concatMap.v3.png" alt="">
7786 * <dl>
7787 * <dt><b>Backpressure:</b></dt>
7788 * <dd>The operator expects the upstream to support backpressure. If this {@code Flowable} violates the rule, the operator will
7789 * signal a {@link MissingBackpressureException}.</dd>
7790 * <dt><b>Scheduler:</b></dt>
7791 * <dd>{@code concatMapCompletable} does not operate by default on a particular {@link Scheduler}.</dd>
7792 * </dl>
7793 * <p>History: 2.1.11 - experimental
7794 * @param mapper the function called with the upstream item and should return
7795 * a {@code CompletableSource} to become the next source to
7796 * be subscribed to
7797 * @param prefetch The number of upstream items to prefetch so that fresh items are
7798 * ready to be mapped when a previous {@code CompletableSource} terminates.
7799 * The operator replenishes after half of the prefetch amount has been consumed
7800 * and turned into {@code CompletableSource}s.
7801 * @return the new {@link Completable} instance
7802 * @throws NullPointerException if {@code mapper} is {@code null}
7803 * @throws IllegalArgumentException if {@code prefetch} is non-positive
7804 * @see #concatMapCompletableDelayError(Function, boolean, int)
7805 * @since 2.2
7806 */
7807 @CheckReturnValue
7808 @NonNull
7809 @SchedulerSupport(SchedulerSupport.NONE)
7810 @BackpressureSupport(BackpressureKind.FULL)
7811 public final Completable concatMapCompletable(@NonNull Function<? super T, ? extends CompletableSource> mapper, int prefetch) {
7812 Objects.requireNonNull(mapper, "mapper is null");
7813 ObjectHelper.verifyPositive(prefetch, "prefetch");
7814 return RxJavaPlugins.onAssembly(new FlowableConcatMapCompletable<>(this, mapper, ErrorMode.IMMEDIATE, prefetch));
7815 }
7816
7817 /**
7818 * Maps the upstream items into {@link CompletableSource}s and subscribes to them one after the
7819 * other terminates, delaying all errors till both this {@code Flowable} and all
7820 * inner {@code CompletableSource}s terminate.
7821 * <p>
7822 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/concatMap.v3.png" alt="">
7823 * <dl>
7824 * <dt><b>Backpressure:</b></dt>
7825 * <dd>The operator expects the upstream to support backpressure. If this {@code Flowable} violates the rule, the operator will
7826 * signal a {@link MissingBackpressureException}.</dd>
7827 * <dt><b>Scheduler:</b></dt>
7828 * <dd>{@code concatMapCompletableDelayError} does not operate by default on a particular {@link Scheduler}.</dd>
7829 * </dl>
7830 * <p>History: 2.1.11 - experimental
7831 * @param mapper the function called with the upstream item and should return
7832 * a {@code CompletableSource} to become the next source to
7833 * be subscribed to
7834 * @return the new {@link Completable} instance
7835 * @throws NullPointerException if {@code mapper} is {@code null}
7836 * @see #concatMapCompletable(Function, int)
7837 * @since 2.2
7838 */
7839 @CheckReturnValue
7840 @SchedulerSupport(SchedulerSupport.NONE)
7841 @BackpressureSupport(BackpressureKind.FULL)
7842 @NonNull
7843 public final Completable concatMapCompletableDelayError(@NonNull Function<? super T, ? extends CompletableSource> mapper) {
7844 return concatMapCompletableDelayError(mapper, true, 2);
7845 }
7846
7847 /**
7848 * Maps the upstream items into {@link CompletableSource}s and subscribes to them one after the
7849 * other terminates, optionally delaying all errors till both this {@code Flowable} and all
7850 * inner {@code CompletableSource}s terminate.
7851 * <p>
7852 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/concatMap.v3.png" alt="">
7853 * <dl>
7854 * <dt><b>Backpressure:</b></dt>
7855 * <dd>The operator expects the upstream to support backpressure. If this {@code Flowable} violates the rule, the operator will
7856 * signal a {@link MissingBackpressureException}.</dd>
7857 * <dt><b>Scheduler:</b></dt>
7858 * <dd>{@code concatMapCompletableDelayError} does not operate by default on a particular {@link Scheduler}.</dd>
7859 * </dl>
7860 * <p>History: 2.1.11 - experimental
7861 * @param mapper the function called with the upstream item and should return
7862 * a {@code CompletableSource} to become the next source to
7863 * be subscribed to
7864 * @param tillTheEnd If {@code true}, errors from this {@code Flowable} or any of the
7865 * inner {@code CompletableSource}s are delayed until all
7866 * of them terminate. If {@code false}, an error from this
7867 * {@code Flowable} is delayed until the current inner
7868 * {@code CompletableSource} terminates and only then is
7869 * it emitted to the downstream.
7870 * @return the new {@link Completable} instance
7871 * @throws NullPointerException if {@code mapper} is {@code null}
7872 * @see #concatMapCompletable(Function)
7873 * @since 2.2
7874 */
7875 @CheckReturnValue
7876 @SchedulerSupport(SchedulerSupport.NONE)
7877 @BackpressureSupport(BackpressureKind.FULL)
7878 @NonNull
7879 public final Completable concatMapCompletableDelayError(@NonNull Function<? super T, ? extends CompletableSource> mapper, boolean tillTheEnd) {
7880 return concatMapCompletableDelayError(mapper, tillTheEnd, 2);
7881 }
7882
7883 /**
7884 * Maps the upstream items into {@link CompletableSource}s and subscribes to them one after the
7885 * other terminates, optionally delaying all errors till both this {@code Flowable} and all
7886 * inner {@code CompletableSource}s terminate.
7887 * <p>
7888 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/concatMap.v3.png" alt="">
7889 * <dl>
7890 * <dt><b>Backpressure:</b></dt>
7891 * <dd>The operator expects the upstream to support backpressure. If this {@code Flowable} violates the rule, the operator will
7892 * signal a {@link MissingBackpressureException}.</dd>
7893 * <dt><b>Scheduler:</b></dt>
7894 * <dd>{@code concatMapCompletableDelayError} does not operate by default on a particular {@link Scheduler}.</dd>
7895 * </dl>
7896 * <p>History: 2.1.11 - experimental
7897 * @param mapper the function called with the upstream item and should return
7898 * a {@code CompletableSource} to become the next source to
7899 * be subscribed to
7900 * @param tillTheEnd If {@code true}, errors from this {@code Flowable} or any of the
7901 * inner {@code CompletableSource}s are delayed until all
7902 * of them terminate. If {@code false}, an error from this
7903 * {@code Flowable} is delayed until the current inner
7904 * {@code CompletableSource} terminates and only then is
7905 * it emitted to the downstream.
7906 * @param prefetch The number of upstream items to prefetch so that fresh items are
7907 * ready to be mapped when a previous {@code CompletableSource} terminates.
7908 * The operator replenishes after half of the prefetch amount has been consumed
7909 * and turned into {@code CompletableSource}s.
7910 * @return the new {@link Completable} instance
7911 * @throws NullPointerException if {@code mapper} is {@code null}
7912 * @throws IllegalArgumentException if {@code prefetch} is non-positive
7913 * @see #concatMapCompletable(Function, int)
7914 * @since 2.2
7915 */
7916 @CheckReturnValue
7917 @NonNull
7918 @SchedulerSupport(SchedulerSupport.NONE)
7919 @BackpressureSupport(BackpressureKind.FULL)
7920 public final Completable concatMapCompletableDelayError(@NonNull Function<? super T, ? extends CompletableSource> mapper, boolean tillTheEnd, int prefetch) {
7921 Objects.requireNonNull(mapper, "mapper is null");
7922 ObjectHelper.verifyPositive(prefetch, "prefetch");
7923 return RxJavaPlugins.onAssembly(new FlowableConcatMapCompletable<>(this, mapper, tillTheEnd ? ErrorMode.END : ErrorMode.BOUNDARY, prefetch));
7924 }
7925
7926 /**
7927 * Maps each of the items into a {@link Publisher}, subscribes to them one after the other,
7928 * one at a time and emits their values in order
7929 * while delaying any error from either this or any of the inner {@code Publisher}s
7930 * till all of them terminate.
7931 * <p>
7932 * Note that there is no guarantee where the given {@code mapper} function will be executed; it could be on the subscribing thread,
7933 * on the upstream thread signaling the new item to be mapped or on the thread where the inner source terminates. To ensure
7934 * the {@code mapper} function is confined to a known thread, use the {@link #concatMapDelayError(Function, boolean, int, Scheduler)} overload.
7935 * <dl>
7936 * <dt><b>Backpressure:</b></dt>
7937 * <dd>The operator honors backpressure from downstream. Both this and the inner {@code Publisher}s are
7938 * expected to honor backpressure as well. If the current {@code Flowable} violates the rule, the operator will
7939 * signal a {@link MissingBackpressureException}. If any of the inner {@code Publisher}s doesn't honor
7940 * backpressure, that <em>may</em> throw an {@link IllegalStateException} when that
7941 * {@code Publisher} completes.</dd>
7942 * <dt><b>Scheduler:</b></dt>
7943 * <dd>{@code concatMapDelayError} does not operate by default on a particular {@link Scheduler}.</dd>
7944 * </dl>
7945 *
7946 * @param <R> the result value type
7947 * @param mapper the function that maps the items of this {@code Publisher} into the inner {@code Publisher}s.
7948 * @return the new {@code Flowable} instance with the concatenation behavior
7949 * @throws NullPointerException if {@code mapper} is {@code null}
7950 * @see #concatMapDelayError(Function, boolean, int, Scheduler)
7951 */
7952 @CheckReturnValue
7953 @BackpressureSupport(BackpressureKind.FULL)
7954 @SchedulerSupport(SchedulerSupport.NONE)
7955 @NonNull
7956 public final <@NonNull R> Flowable<R> concatMapDelayError(@NonNull Function<? super T, @NonNull ? extends Publisher<? extends R>> mapper) {
7957 return concatMapDelayError(mapper, true, 2);
7958 }
7959
7960 /**
7961 * Maps each of the items into a {@link Publisher}, subscribes to them one after the other,
7962 * one at a time and emits their values in order
7963 * while delaying any error from either this or any of the inner {@code Publisher}s
7964 * till all of them terminate.
7965 * <p>
7966 * Note that there is no guarantee where the given {@code mapper} function will be executed; it could be on the subscribing thread,
7967 * on the upstream thread signaling the new item to be mapped or on the thread where the inner source terminates. To ensure
7968 * the {@code mapper} function is confined to a known thread, use the {@link #concatMapDelayError(Function, boolean, int, Scheduler)} overload.
7969 *
7970 * <dl>
7971 * <dt><b>Backpressure:</b></dt>
7972 * <dd>The operator honors backpressure from downstream. Both this and the inner {@code Publisher}s are
7973 * expected to honor backpressure as well. If the current {@code Flowable} violates the rule, the operator will
7974 * signal a {@link MissingBackpressureException}. If any of the inner {@code Publisher}s doesn't honor
7975 * backpressure, that <em>may</em> throw an {@link IllegalStateException} when that
7976 * {@code Publisher} completes.</dd>
7977 * <dt><b>Scheduler:</b></dt>
7978 * <dd>{@code concatMapDelayError} does not operate by default on a particular {@link Scheduler}.</dd>
7979 * </dl>
7980 *
7981 * @param <R> the result value type
7982 * @param mapper the function that maps the items of this {@code Publisher} into the inner {@code Publisher}s.
7983 * @param tillTheEnd
7984 * if {@code true}, all errors from the outer and inner {@code Publisher} sources are delayed until the end,
7985 * if {@code false}, an error from the main source is signaled when the current inner {@code Publisher} source terminates
7986 * @param prefetch
7987 * the number of elements to prefetch from the current {@code Flowable}
7988 * @return the new {@code Flowable} instance with the concatenation behavior
7989 * @throws NullPointerException if {@code mapper} is {@code null}
7990 * @throws IllegalArgumentException if {@code prefetch} is non-positive
7991 * @see #concatMapDelayError(Function, boolean, int, Scheduler)
7992 */
7993 @CheckReturnValue
7994 @NonNull
7995 @BackpressureSupport(BackpressureKind.FULL)
7996 @SchedulerSupport(SchedulerSupport.NONE)
7997 public final <@NonNull R> Flowable<R> concatMapDelayError(@NonNull Function<? super T, @NonNull ? extends Publisher<? extends R>> mapper,
7998 boolean tillTheEnd, int prefetch) {
7999 Objects.requireNonNull(mapper, "mapper is null");
8000 ObjectHelper.verifyPositive(prefetch, "prefetch");
8001 if (this instanceof ScalarSupplier) {
8002 @SuppressWarnings("unchecked")
8003 T v = ((ScalarSupplier<T>)this).get();
8004 if (v == null) {
8005 return empty();
8006 }
8007 return FlowableScalarXMap.scalarXMap(v, mapper);
8008 }
8009 return RxJavaPlugins.onAssembly(new FlowableConcatMap<>(this, mapper, prefetch, tillTheEnd ? ErrorMode.END : ErrorMode.BOUNDARY));
8010 }
8011
8012 /**
8013 * Maps each of the upstream items into a {@link Publisher}, subscribes to them one after the other,
8014 * one at a time and emits their values in order
8015 * while executing the mapper function on the designated scheduler, delaying any error from either this or any of the
8016 * inner {@code Publisher}s till all of them terminate.
8017 * <p>
8018 * The difference between {@link #concatMapDelayError(Function, boolean, int)} and this operator is that this operator guarantees the {@code mapper}
8019 * function is executed on the specified scheduler.
8020 *
8021 * <dl>
8022 * <dt><b>Backpressure:</b></dt>
8023 * <dd>The operator honors backpressure from downstream. Both this and the inner {@code Publisher}s are
8024 * expected to honor backpressure as well. If the current {@code Flowable} violates the rule, the operator will
8025 * signal a {@link MissingBackpressureException}. If any of the inner {@code Publisher}s doesn't honor
8026 * backpressure, that <em>may</em> throw an {@link IllegalStateException} when that
8027 * {@code Publisher} completes.</dd>
8028 * <dt><b>Scheduler:</b></dt>
8029 * <dd>{@code concatMapDelayError} executes the given {@code mapper} function on the provided {@link Scheduler}.</dd>
8030 * </dl>
8031 *
8032 * @param <R> the result value type
8033 * @param mapper the function that maps the items of this {@code Publisher} into the inner {@code Publisher}s.
8034 * @param tillTheEnd
8035 * if {@code true}, all errors from the outer and inner {@code Publisher} sources are delayed until the end,
8036 * if {@code false}, an error from the main source is signaled when the current inner {@code Publisher} source terminates
8037 * @param prefetch
8038 * the number of elements to prefetch from the current {@code Flowable}
8039 * @param scheduler
8040 * the scheduler where the {@code mapper} function will be executed
8041 * @return the new {@code Flowable} instance with the concatenation behavior
8042 * @throws NullPointerException if {@code mapper} or {@code scheduler} is {@code null}
8043 * @throws IllegalArgumentException if {@code prefetch} is non-positive
8044 * @see #concatMapDelayError(Function, boolean, int)
8045 * @since 3.0.0
8046 */
8047 @CheckReturnValue
8048 @NonNull
8049 @BackpressureSupport(BackpressureKind.FULL)
8050 @SchedulerSupport(SchedulerSupport.CUSTOM)
8051 public final <@NonNull R> Flowable<R> concatMapDelayError(@NonNull Function<? super T, @NonNull ? extends Publisher<? extends R>> mapper,
8052 boolean tillTheEnd, int prefetch, @NonNull Scheduler scheduler) {
8053 Objects.requireNonNull(mapper, "mapper is null");
8054 ObjectHelper.verifyPositive(prefetch, "prefetch");
8055 Objects.requireNonNull(scheduler, "scheduler is null");
8056 return RxJavaPlugins.onAssembly(new FlowableConcatMapScheduler<>(this, mapper, prefetch, tillTheEnd ? ErrorMode.END : ErrorMode.BOUNDARY, scheduler));
8057 }
8058
8059 /**
8060 * Maps a sequence of values into {@link Publisher}s and concatenates these {@code Publisher}s eagerly into a single
8061 * {@code Publisher}.
8062 * <p>
8063 * Eager concatenation means that once a subscriber subscribes, this operator subscribes to all of the
8064 * inner {@code Publisher}s. The operator buffers the values emitted by these {@code Publisher}s and then drains them in
8065 * order, each one after the previous one completes.
8066 * <dl>
8067 * <dt><b>Backpressure:</b></dt>
8068 * <dd>Backpressure is honored towards the downstream, however, due to the eagerness requirement, sources
8069 * are subscribed to in unbounded mode and their values are queued up in an unbounded buffer.</dd>
8070 * <dt><b>Scheduler:</b></dt>
8071 * <dd>This method does not operate by default on a particular {@link Scheduler}.</dd>
8072 * </dl>
8073 * @param <R> the value type
8074 * @param mapper the function that maps a sequence of values into a sequence of {@code Publisher}s that will be
8075 * eagerly concatenated
8076 * @return the new {@code Flowable} instance with the specified concatenation behavior
8077 * @throws NullPointerException if {@code mapper} is {@code null}
8078 * @since 2.0
8079 */
8080 @CheckReturnValue
8081 @BackpressureSupport(BackpressureKind.FULL)
8082 @SchedulerSupport(SchedulerSupport.NONE)
8083 @NonNull
8084 public final <@NonNull R> Flowable<R> concatMapEager(@NonNull Function<? super T, @NonNull ? extends Publisher<? extends R>> mapper) {
8085 return concatMapEager(mapper, bufferSize(), bufferSize());
8086 }
8087
8088 /**
8089 * Maps a sequence of values into {@link Publisher}s and concatenates these {@code Publisher}s eagerly into a single
8090 * {@code Publisher}.
8091 * <p>
8092 * Eager concatenation means that once a subscriber subscribes, this operator subscribes to all of the
8093 * inner {@code Publisher}s. The operator buffers the values emitted by these {@code Publisher}s and then drains them in
8094 * order, each one after the previous one completes.
8095 * <dl>
8096 * <dt><b>Backpressure:</b></dt>
8097 * <dd>Backpressure is honored towards the downstream, however, due to the eagerness requirement, sources
8098 * are subscribed to in unbounded mode and their values are queued up in an unbounded buffer.</dd>
8099 * <dt><b>Scheduler:</b></dt>
8100 * <dd>This method does not operate by default on a particular {@link Scheduler}.</dd>
8101 * </dl>
8102 * @param <R> the value type
8103 * @param mapper the function that maps a sequence of values into a sequence of {@code Publisher}s that will be
8104 * eagerly concatenated
8105 * @param maxConcurrency the maximum number of concurrent subscribed {@code Publisher}s
8106 * @param prefetch hints about the number of expected values from each inner {@code Publisher}, must be positive
8107 * @return the new {@code Flowable} instance with the specified concatenation behavior
8108 * @throws NullPointerException if {@code mapper} is {@code null}
8109 * @throws IllegalArgumentException if {@code maxConcurrency} or {@code prefetch} is non-positive
8110 * @since 2.0
8111 */
8112 @CheckReturnValue
8113 @NonNull
8114 @BackpressureSupport(BackpressureKind.FULL)
8115 @SchedulerSupport(SchedulerSupport.NONE)
8116 public final <@NonNull R> Flowable<R> concatMapEager(@NonNull Function<? super T, @NonNull ? extends Publisher<? extends R>> mapper,
8117 int maxConcurrency, int prefetch) {
8118 Objects.requireNonNull(mapper, "mapper is null");
8119 ObjectHelper.verifyPositive(maxConcurrency, "maxConcurrency");
8120 ObjectHelper.verifyPositive(prefetch, "prefetch");
8121 return RxJavaPlugins.onAssembly(new FlowableConcatMapEager<>(this, mapper, maxConcurrency, prefetch, ErrorMode.IMMEDIATE));
8122 }
8123
8124 /**
8125 * Maps a sequence of values into {@link Publisher}s and concatenates these {@code Publisher}s eagerly into a single
8126 * {@code Publisher}.
8127 * <p>
8128 * Eager concatenation means that once a subscriber subscribes, this operator subscribes to all of the
8129 * inner {@code Publisher}s. The operator buffers the values emitted by these {@code Publisher}s and then drains them in
8130 * order, each one after the previous one completes.
8131 * <dl>
8132 * <dt><b>Backpressure:</b></dt>
8133 * <dd>Backpressure is honored towards the downstream, however, due to the eagerness requirement, sources
8134 * are subscribed to in unbounded mode and their values are queued up in an unbounded buffer.</dd>
8135 * <dt><b>Scheduler:</b></dt>
8136 * <dd>This method does not operate by default on a particular {@link Scheduler}.</dd>
8137 * </dl>
8138 * @param <R> the value type
8139 * @param mapper the function that maps a sequence of values into a sequence of {@code Publisher}s that will be
8140 * eagerly concatenated
8141 * @param tillTheEnd
8142 * if {@code true}, all errors from the outer and inner {@code Publisher} sources are delayed until the end,
8143 * if {@code false}, an error from the main source is signaled when the current inner {@code Publisher} source terminates
8144 * @return the new {@code Flowable} instance with the specified concatenation behavior
8145 * @throws NullPointerException if {@code mapper} is {@code null}
8146 * @since 2.0
8147 */
8148 @CheckReturnValue
8149 @BackpressureSupport(BackpressureKind.FULL)
8150 @SchedulerSupport(SchedulerSupport.NONE)
8151 @NonNull
8152 public final <@NonNull R> Flowable<R> concatMapEagerDelayError(@NonNull Function<? super T, @NonNull ? extends Publisher<? extends R>> mapper,
8153 boolean tillTheEnd) {
8154 return concatMapEagerDelayError(mapper, tillTheEnd, bufferSize(), bufferSize());
8155 }
8156
8157 /**
8158 * Maps a sequence of values into {@link Publisher}s and concatenates these {@code Publisher}s eagerly into a single
8159 * {@code Flowable} sequence.
8160 * <p>
8161 * Eager concatenation means that once a subscriber subscribes, this operator subscribes to all of the
8162 * inner {@code Publisher}s. The operator buffers the values emitted by these {@code Publisher}s and then drains them in
8163 * order, each one after the previous one completes.
8164 * <dl>
8165 * <dt><b>Backpressure:</b></dt>
8166 * <dd>Backpressure is honored towards the downstream, however, due to the eagerness requirement, sources
8167 * are subscribed to in unbounded mode and their values are queued up in an unbounded buffer.</dd>
8168 * <dt><b>Scheduler:</b></dt>
8169 * <dd>This method does not operate by default on a particular {@link Scheduler}.</dd>
8170 * </dl>
8171 * @param <R> the value type
8172 * @param mapper the function that maps a sequence of values into a sequence of {@code Publisher}s that will be
8173 * eagerly concatenated
8174 * @param tillTheEnd
8175 * if {@code true}, exceptions from the current {@code Flowable} and all the inner {@code Publisher}s are delayed until
8176 * all of them terminate, if {@code false}, exception from the current {@code Flowable} is delayed until the
8177 * currently running {@code Publisher} terminates
8178 * @param maxConcurrency the maximum number of concurrent subscribed {@code Publisher}s
8179 * @param prefetch
8180 * the number of elements to prefetch from each source {@code Publisher}
8181 * @return the new {@code Flowable} instance with the specified concatenation behavior
8182 * @throws NullPointerException if {@code mapper} is {@code null}
8183 * @throws IllegalArgumentException if {@code maxConcurrency} or {@code prefetch} is non-positive
8184 * @since 2.0
8185 */
8186 @CheckReturnValue
8187 @NonNull
8188 @BackpressureSupport(BackpressureKind.FULL)
8189 @SchedulerSupport(SchedulerSupport.NONE)
8190 public final <@NonNull R> Flowable<R> concatMapEagerDelayError(@NonNull Function<? super T, @NonNull ? extends Publisher<? extends R>> mapper,
8191 boolean tillTheEnd, int maxConcurrency, int prefetch) {
8192 Objects.requireNonNull(mapper, "mapper is null");
8193 ObjectHelper.verifyPositive(maxConcurrency, "maxConcurrency");
8194 ObjectHelper.verifyPositive(prefetch, "prefetch");
8195 return RxJavaPlugins.onAssembly(new FlowableConcatMapEager<>(this, mapper, maxConcurrency, prefetch, tillTheEnd ? ErrorMode.END : ErrorMode.BOUNDARY));
8196 }
8197
8198 /**
8199 * Returns a {@code Flowable} that concatenate each item emitted by the current {@code Flowable} with the values in an
8200 * {@link Iterable} corresponding to that item that is generated by a selector.
8201 *
8202 * <dl>
8203 * <dt><b>Backpressure:</b></dt>
8204 * <dd>The operator honors backpressure from downstream. The current {@code Flowable}s is
8205 * expected to honor backpressure as well. If the current {@code Flowable} violates the rule, the operator will
8206 * signal a {@link MissingBackpressureException}.</dd>
8207 * <dt><b>Scheduler:</b></dt>
8208 * <dd>{@code concatMapIterable} does not operate by default on a particular {@link Scheduler}.</dd>
8209 * </dl>
8210 *
8211 * @param <U>
8212 * the type of item emitted by the resulting {@code Flowable}
8213 * @param mapper
8214 * a function that returns an {@code Iterable} sequence of values for when given an item emitted by the
8215 * current {@code Flowable}
8216 * @return the new {@code Flowable} instance
8217 * @throws NullPointerException if {@code mapper} is {@code null}
8218 * @see <a href="http://reactivex.io/documentation/operators/flatmap.html">ReactiveX operators documentation: FlatMap</a>
8219 */
8220 @CheckReturnValue
8221 @BackpressureSupport(BackpressureKind.FULL)
8222 @SchedulerSupport(SchedulerSupport.NONE)
8223 @NonNull
8224 public final <@NonNull U> Flowable<U> concatMapIterable(@NonNull Function<? super T, @NonNull ? extends Iterable<? extends U>> mapper) {
8225 return concatMapIterable(mapper, 2);
8226 }
8227
8228 /**
8229 * Returns a {@code Flowable} that concatenate each item emitted by the current {@code Flowable} with the values in an
8230 * {@link Iterable} corresponding to that item that is generated by a selector.
8231 *
8232 * <dl>
8233 * <dt><b>Backpressure:</b></dt>
8234 * <dd>The operator honors backpressure from downstream. The current {@code Flowable} is
8235 * expected to honor backpressure as well. If the current {@code Flowable} violates the rule, the operator will
8236 * signal a {@link MissingBackpressureException}.</dd>
8237 * <dt><b>Scheduler:</b></dt>
8238 * <dd>{@code concatMapIterable} does not operate by default on a particular {@link Scheduler}.</dd>
8239 * </dl>
8240 *
8241 * @param <U>
8242 * the type of item emitted by the resulting {@code Flowable}
8243 * @param mapper
8244 * a function that returns an {@code Iterable} sequence of values for when given an item emitted by the
8245 * current {@code Flowable}
8246 * @param prefetch
8247 * the number of elements to prefetch from the current {@code Flowable}
8248 * @return the new {@code Flowable} instance
8249 * @throws NullPointerException if {@code mapper} is {@code null}
8250 * @throws IllegalArgumentException if {@code prefetch} is non-positive
8251 * @see <a href="http://reactivex.io/documentation/operators/flatmap.html">ReactiveX operators documentation: FlatMap</a>
8252 */
8253 @CheckReturnValue
8254 @NonNull
8255 @BackpressureSupport(BackpressureKind.FULL)
8256 @SchedulerSupport(SchedulerSupport.NONE)
8257 public final <@NonNull U> Flowable<U> concatMapIterable(@NonNull Function<? super T, @NonNull ? extends Iterable<? extends U>> mapper, int prefetch) {
8258 Objects.requireNonNull(mapper, "mapper is null");
8259 ObjectHelper.verifyPositive(prefetch, "prefetch");
8260 return RxJavaPlugins.onAssembly(new FlowableFlattenIterable<>(this, mapper, prefetch));
8261 }
8262
8263 /**
8264 * Maps the upstream items into {@link MaybeSource}s and subscribes to them one after the
8265 * other succeeds or completes, emits their success value if available or terminates immediately if
8266 * either this {@code Flowable} or the current inner {@code MaybeSource} fail.
8267 * <p>
8268 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/concatMap.v3.png" alt="">
8269 * <dl>
8270 * <dt><b>Backpressure:</b></dt>
8271 * <dd>The operator expects the upstream to support backpressure and honors
8272 * the backpressure from downstream. If this {@code Flowable} violates the rule, the operator will
8273 * signal a {@link MissingBackpressureException}.</dd>
8274 * <dt><b>Scheduler:</b></dt>
8275 * <dd>{@code concatMapMaybe} does not operate by default on a particular {@link Scheduler}.</dd>
8276 * </dl>
8277 * <p>History: 2.1.11 - experimental
8278 * @param <R> the result type of the inner {@code MaybeSource}s
8279 * @param mapper the function called with the upstream item and should return
8280 * a {@code MaybeSource} to become the next source to
8281 * be subscribed to
8282 * @return the new {@code Flowable} instance
8283 * @throws NullPointerException if {@code mapper} is {@code null}
8284 * @see #concatMapMaybeDelayError(Function)
8285 * @see #concatMapMaybe(Function, int)
8286 * @since 2.2
8287 */
8288 @CheckReturnValue
8289 @BackpressureSupport(BackpressureKind.FULL)
8290 @SchedulerSupport(SchedulerSupport.NONE)
8291 @NonNull
8292 public final <@NonNull R> Flowable<R> concatMapMaybe(@NonNull Function<? super T, ? extends MaybeSource<? extends R>> mapper) {
8293 return concatMapMaybe(mapper, 2);
8294 }
8295
8296 /**
8297 * Maps the upstream items into {@link MaybeSource}s and subscribes to them one after the
8298 * other succeeds or completes, emits their success value if available or terminates immediately if
8299 * either this {@code Flowable} or the current inner {@code MaybeSource} fail.
8300 * <p>
8301 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/concatMap.v3.png" alt="">
8302 * <dl>
8303 * <dt><b>Backpressure:</b></dt>
8304 * <dd>The operator expects the upstream to support backpressure and honors
8305 * the backpressure from downstream. If this {@code Flowable} violates the rule, the operator will
8306 * signal a {@link MissingBackpressureException}.</dd>
8307 * <dt><b>Scheduler:</b></dt>
8308 * <dd>{@code concatMapMaybe} does not operate by default on a particular {@link Scheduler}.</dd>
8309 * </dl>
8310 * <p>History: 2.1.11 - experimental
8311 * @param <R> the result type of the inner {@code MaybeSource}s
8312 * @param mapper the function called with the upstream item and should return
8313 * a {@code MaybeSource} to become the next source to
8314 * be subscribed to
8315 * @param prefetch The number of upstream items to prefetch so that fresh items are
8316 * ready to be mapped when a previous {@code MaybeSource} terminates.
8317 * The operator replenishes after half of the prefetch amount has been consumed
8318 * and turned into {@code MaybeSource}s.
8319 * @return the new {@code Flowable} instance
8320 * @throws NullPointerException if {@code mapper} is {@code null}
8321 * @throws IllegalArgumentException if {@code prefetch} is non-positive
8322 * @see #concatMapMaybe(Function)
8323 * @see #concatMapMaybeDelayError(Function, boolean, int)
8324 * @since 2.2
8325 */
8326 @CheckReturnValue
8327 @NonNull
8328 @BackpressureSupport(BackpressureKind.FULL)
8329 @SchedulerSupport(SchedulerSupport.NONE)
8330 public final <@NonNull R> Flowable<R> concatMapMaybe(@NonNull Function<? super T, ? extends MaybeSource<? extends R>> mapper, int prefetch) {
8331 Objects.requireNonNull(mapper, "mapper is null");
8332 ObjectHelper.verifyPositive(prefetch, "prefetch");
8333 return RxJavaPlugins.onAssembly(new FlowableConcatMapMaybe<>(this, mapper, ErrorMode.IMMEDIATE, prefetch));
8334 }
8335
8336 /**
8337 * Maps the upstream items into {@link MaybeSource}s and subscribes to them one after the
8338 * other terminates, emits their success value if available and delaying all errors
8339 * till both this {@code Flowable} and all inner {@code MaybeSource}s terminate.
8340 * <p>
8341 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/concatMap.v3.png" alt="">
8342 * <dl>
8343 * <dt><b>Backpressure:</b></dt>
8344 * <dd>The operator expects the upstream to support backpressure and honors
8345 * the backpressure from downstream. If this {@code Flowable} violates the rule, the operator will
8346 * signal a {@link MissingBackpressureException}.</dd>
8347 * <dt><b>Scheduler:</b></dt>
8348 * <dd>{@code concatMapMaybeDelayError} does not operate by default on a particular {@link Scheduler}.</dd>
8349 * </dl>
8350 * <p>History: 2.1.11 - experimental
8351 * @param <R> the result type of the inner {@code MaybeSource}s
8352 * @param mapper the function called with the upstream item and should return
8353 * a {@code MaybeSource} to become the next source to
8354 * be subscribed to
8355 * @return the new {@code Flowable} instance
8356 * @throws NullPointerException if {@code mapper} is {@code null}
8357 * @see #concatMapMaybe(Function)
8358 * @see #concatMapMaybeDelayError(Function, boolean)
8359 * @since 2.2
8360 */
8361 @CheckReturnValue
8362 @BackpressureSupport(BackpressureKind.FULL)
8363 @SchedulerSupport(SchedulerSupport.NONE)
8364 @NonNull
8365 public final <@NonNull R> Flowable<R> concatMapMaybeDelayError(@NonNull Function<? super T, ? extends MaybeSource<? extends R>> mapper) {
8366 return concatMapMaybeDelayError(mapper, true, 2);
8367 }
8368
8369 /**
8370 * Maps the upstream items into {@link MaybeSource}s and subscribes to them one after the
8371 * other terminates, emits their success value if available and optionally delaying all errors
8372 * till both this {@code Flowable} and all inner {@code MaybeSource}s terminate.
8373 * <p>
8374 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/concatMap.v3.png" alt="">
8375 * <dl>
8376 * <dt><b>Backpressure:</b></dt>
8377 * <dd>The operator expects the upstream to support backpressure and honors
8378 * the backpressure from downstream. If this {@code Flowable} violates the rule, the operator will
8379 * signal a {@link MissingBackpressureException}.</dd>
8380 * <dt><b>Scheduler:</b></dt>
8381 * <dd>{@code concatMapMaybeDelayError} does not operate by default on a particular {@link Scheduler}.</dd>
8382 * </dl>
8383 * <p>History: 2.1.11 - experimental
8384 * @param <R> the result type of the inner {@code MaybeSource}s
8385 * @param mapper the function called with the upstream item and should return
8386 * a {@code MaybeSource} to become the next source to
8387 * be subscribed to
8388 * @param tillTheEnd If {@code true}, errors from this {@code Flowable} or any of the
8389 * inner {@code MaybeSource}s are delayed until all
8390 * of them terminate. If {@code false}, an error from this
8391 * {@code Flowable} is delayed until the current inner
8392 * {@code MaybeSource} terminates and only then is
8393 * it emitted to the downstream.
8394 * @return the new {@code Flowable} instance
8395 * @throws NullPointerException if {@code mapper} is {@code null}
8396 * @see #concatMapMaybe(Function, int)
8397 * @see #concatMapMaybeDelayError(Function, boolean, int)
8398 * @since 2.2
8399 */
8400 @CheckReturnValue
8401 @BackpressureSupport(BackpressureKind.FULL)
8402 @SchedulerSupport(SchedulerSupport.NONE)
8403 @NonNull
8404 public final <@NonNull R> Flowable<R> concatMapMaybeDelayError(@NonNull Function<? super T, ? extends MaybeSource<? extends R>> mapper, boolean tillTheEnd) {
8405 return concatMapMaybeDelayError(mapper, tillTheEnd, 2);
8406 }
8407
8408 /**
8409 * Maps the upstream items into {@link MaybeSource}s and subscribes to them one after the
8410 * other terminates, emits their success value if available and optionally delaying all errors
8411 * till both this {@code Flowable} and all inner {@code MaybeSource}s terminate.
8412 * <p>
8413 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/concatMap.v3.png" alt="">
8414 * <dl>
8415 * <dt><b>Backpressure:</b></dt>
8416 * <dd>The operator expects the upstream to support backpressure and honors
8417 * the backpressure from downstream. If this {@code Flowable} violates the rule, the operator will
8418 * signal a {@link MissingBackpressureException}.</dd>
8419 * <dt><b>Scheduler:</b></dt>
8420 * <dd>{@code concatMapMaybeDelayError} does not operate by default on a particular {@link Scheduler}.</dd>
8421 * </dl>
8422 * <p>History: 2.1.11 - experimental
8423 * @param <R> the result type of the inner {@code MaybeSource}s
8424 * @param mapper the function called with the upstream item and should return
8425 * a {@code MaybeSource} to become the next source to
8426 * be subscribed to
8427 * @param tillTheEnd If {@code true}, errors from this {@code Flowable} or any of the
8428 * inner {@code MaybeSource}s are delayed until all
8429 * of them terminate. If {@code false}, an error from this
8430 * {@code Flowable} is delayed until the current inner
8431 * {@code MaybeSource} terminates and only then is
8432 * it emitted to the downstream.
8433 * @param prefetch The number of upstream items to prefetch so that fresh items are
8434 * ready to be mapped when a previous {@code MaybeSource} terminates.
8435 * The operator replenishes after half of the prefetch amount has been consumed
8436 * and turned into {@code MaybeSource}s.
8437 * @return the new {@code Flowable} instance
8438 * @throws NullPointerException if {@code mapper} is {@code null}
8439 * @throws IllegalArgumentException if {@code prefetch} is non-positive
8440 * @see #concatMapMaybe(Function, int)
8441 * @since 2.2
8442 */
8443 @CheckReturnValue
8444 @NonNull
8445 @BackpressureSupport(BackpressureKind.FULL)
8446 @SchedulerSupport(SchedulerSupport.NONE)
8447 public final <@NonNull R> Flowable<R> concatMapMaybeDelayError(@NonNull Function<? super T, ? extends MaybeSource<? extends R>> mapper, boolean tillTheEnd, int prefetch) {
8448 Objects.requireNonNull(mapper, "mapper is null");
8449 ObjectHelper.verifyPositive(prefetch, "prefetch");
8450 return RxJavaPlugins.onAssembly(new FlowableConcatMapMaybe<>(this, mapper, tillTheEnd ? ErrorMode.END : ErrorMode.BOUNDARY, prefetch));
8451 }
8452
8453 /**
8454 * Maps the upstream items into {@link SingleSource}s and subscribes to them one after the
8455 * other succeeds, emits their success values or terminates immediately if
8456 * either this {@code Flowable} or the current inner {@code SingleSource} fail.
8457 * <p>
8458 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/concatMap.v3.png" alt="">
8459 * <dl>
8460 * <dt><b>Backpressure:</b></dt>
8461 * <dd>The operator expects the upstream to support backpressure and honors
8462 * the backpressure from downstream. If this {@code Flowable} violates the rule, the operator will
8463 * signal a {@link MissingBackpressureException}.</dd>
8464 * <dt><b>Scheduler:</b></dt>
8465 * <dd>{@code concatMapSingle} does not operate by default on a particular {@link Scheduler}.</dd>
8466 * </dl>
8467 * <p>History: 2.1.11 - experimental
8468 * @param <R> the result type of the inner {@code SingleSource}s
8469 * @param mapper the function called with the upstream item and should return
8470 * a {@code SingleSource} to become the next source to
8471 * be subscribed to
8472 * @return the new {@code Flowable} instance
8473 * @throws NullPointerException if {@code mapper} is {@code null}
8474 * @see #concatMapSingleDelayError(Function)
8475 * @see #concatMapSingle(Function, int)
8476 * @since 2.2
8477 */
8478 @CheckReturnValue
8479 @BackpressureSupport(BackpressureKind.FULL)
8480 @SchedulerSupport(SchedulerSupport.NONE)
8481 @NonNull
8482 public final <@NonNull R> Flowable<R> concatMapSingle(@NonNull Function<? super T, ? extends SingleSource<? extends R>> mapper) {
8483 return concatMapSingle(mapper, 2);
8484 }
8485
8486 /**
8487 * Maps the upstream items into {@link SingleSource}s and subscribes to them one after the
8488 * other succeeds, emits their success values or terminates immediately if
8489 * either this {@code Flowable} or the current inner {@code SingleSource} fail.
8490 * <p>
8491 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/concatMap.v3.png" alt="">
8492 * <dl>
8493 * <dt><b>Backpressure:</b></dt>
8494 * <dd>The operator expects the upstream to support backpressure and honors
8495 * the backpressure from downstream. If this {@code Flowable} violates the rule, the operator will
8496 * signal a {@link MissingBackpressureException}.</dd>
8497 * <dt><b>Scheduler:</b></dt>
8498 * <dd>{@code concatMapSingle} does not operate by default on a particular {@link Scheduler}.</dd>
8499 * </dl>
8500 * <p>History: 2.1.11 - experimental
8501 * @param <R> the result type of the inner {@code SingleSource}s
8502 * @param mapper the function called with the upstream item and should return
8503 * a {@code SingleSource} to become the next source to
8504 * be subscribed to
8505 * @param prefetch The number of upstream items to prefetch so that fresh items are
8506 * ready to be mapped when a previous {@code SingleSource} terminates.
8507 * The operator replenishes after half of the prefetch amount has been consumed
8508 * and turned into {@code SingleSource}s.
8509 * @return the new {@code Flowable} instance
8510 * @throws NullPointerException if {@code mapper} is {@code null}
8511 * @throws IllegalArgumentException if {@code prefetch} is non-positive
8512 * @see #concatMapSingle(Function)
8513 * @see #concatMapSingleDelayError(Function, boolean, int)
8514 * @since 2.2
8515 */
8516 @CheckReturnValue
8517 @NonNull
8518 @BackpressureSupport(BackpressureKind.FULL)
8519 @SchedulerSupport(SchedulerSupport.NONE)
8520 public final <@NonNull R> Flowable<R> concatMapSingle(@NonNull Function<? super T, ? extends SingleSource<? extends R>> mapper, int prefetch) {
8521 Objects.requireNonNull(mapper, "mapper is null");
8522 ObjectHelper.verifyPositive(prefetch, "prefetch");
8523 return RxJavaPlugins.onAssembly(new FlowableConcatMapSingle<>(this, mapper, ErrorMode.IMMEDIATE, prefetch));
8524 }
8525
8526 /**
8527 * Maps the upstream items into {@link SingleSource}s and subscribes to them one after the
8528 * other succeeds or fails, emits their success values and delays all errors
8529 * till both this {@code Flowable} and all inner {@code SingleSource}s terminate.
8530 * <p>
8531 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/concatMap.v3.png" alt="">
8532 * <dl>
8533 * <dt><b>Backpressure:</b></dt>
8534 * <dd>The operator expects the upstream to support backpressure and honors
8535 * the backpressure from downstream. If this {@code Flowable} violates the rule, the operator will
8536 * signal a {@link MissingBackpressureException}.</dd>
8537 * <dt><b>Scheduler:</b></dt>
8538 * <dd>{@code concatMapSingleDelayError} does not operate by default on a particular {@link Scheduler}.</dd>
8539 * </dl>
8540 * <p>History: 2.1.11 - experimental
8541 * @param <R> the result type of the inner {@code SingleSource}s
8542 * @param mapper the function called with the upstream item and should return
8543 * a {@code SingleSource} to become the next source to
8544 * be subscribed to
8545 * @return the new {@code Flowable} instance
8546 * @throws NullPointerException if {@code mapper} is {@code null}
8547 * @see #concatMapSingle(Function)
8548 * @see #concatMapSingleDelayError(Function, boolean)
8549 * @since 2.2
8550 */
8551 @CheckReturnValue
8552 @BackpressureSupport(BackpressureKind.FULL)
8553 @SchedulerSupport(SchedulerSupport.NONE)
8554 @NonNull
8555 public final <@NonNull R> Flowable<R> concatMapSingleDelayError(@NonNull Function<? super T, ? extends SingleSource<? extends R>> mapper) {
8556 return concatMapSingleDelayError(mapper, true, 2);
8557 }
8558
8559 /**
8560 * Maps the upstream items into {@link SingleSource}s and subscribes to them one after the
8561 * other succeeds or fails, emits their success values and optionally delays all errors
8562 * till both this {@code Flowable} and all inner {@code SingleSource}s terminate.
8563 * <p>
8564 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/concatMap.v3.png" alt="">
8565 * <dl>
8566 * <dt><b>Backpressure:</b></dt>
8567 * <dd>The operator expects the upstream to support backpressure and honors
8568 * the backpressure from downstream. If this {@code Flowable} violates the rule, the operator will
8569 * signal a {@link MissingBackpressureException}.</dd>
8570 * <dt><b>Scheduler:</b></dt>
8571 * <dd>{@code concatMapSingleDelayError} does not operate by default on a particular {@link Scheduler}.</dd>
8572 * </dl>
8573 * <p>History: 2.1.11 - experimental
8574 * @param <R> the result type of the inner {@code SingleSource}s
8575 * @param mapper the function called with the upstream item and should return
8576 * a {@code SingleSource} to become the next source to
8577 * be subscribed to
8578 * @param tillTheEnd If {@code true}, errors from this {@code Flowable} or any of the
8579 * inner {@code SingleSource}s are delayed until all
8580 * of them terminate. If {@code false}, an error from this
8581 * {@code Flowable} is delayed until the current inner
8582 * {@code SingleSource} terminates and only then is
8583 * it emitted to the downstream.
8584 * @return the new {@code Flowable} instance
8585 * @throws NullPointerException if {@code mapper} is {@code null}
8586 * @see #concatMapSingle(Function, int)
8587 * @see #concatMapSingleDelayError(Function, boolean, int)
8588 * @since 2.2
8589 */
8590 @CheckReturnValue
8591 @BackpressureSupport(BackpressureKind.FULL)
8592 @SchedulerSupport(SchedulerSupport.NONE)
8593 @NonNull
8594 public final <@NonNull R> Flowable<R> concatMapSingleDelayError(@NonNull Function<? super T, ? extends SingleSource<? extends R>> mapper, boolean tillTheEnd) {
8595 return concatMapSingleDelayError(mapper, tillTheEnd, 2);
8596 }
8597
8598 /**
8599 * Maps the upstream items into {@link SingleSource}s and subscribes to them one after the
8600 * other succeeds or fails, emits their success values and optionally delays errors
8601 * till both this {@code Flowable} and all inner {@code SingleSource}s terminate.
8602 * <p>
8603 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/concatMap.v3.png" alt="">
8604 * <dl>
8605 * <dt><b>Backpressure:</b></dt>
8606 * <dd>The operator expects the upstream to support backpressure and honors
8607 * the backpressure from downstream. If this {@code Flowable} violates the rule, the operator will
8608 * signal a {@link MissingBackpressureException}.</dd>
8609 * <dt><b>Scheduler:</b></dt>
8610 * <dd>{@code concatMapSingleDelayError} does not operate by default on a particular {@link Scheduler}.</dd>
8611 * </dl>
8612 * <p>History: 2.1.11 - experimental
8613 * @param <R> the result type of the inner {@code SingleSource}s
8614 * @param mapper the function called with the upstream item and should return
8615 * a {@code SingleSource} to become the next source to
8616 * be subscribed to
8617 * @param tillTheEnd If {@code true}, errors from this {@code Flowable} or any of the
8618 * inner {@code SingleSource}s are delayed until all
8619 * of them terminate. If {@code false}, an error from this
8620 * {@code Flowable} is delayed until the current inner
8621 * {@code SingleSource} terminates and only then is
8622 * it emitted to the downstream.
8623 * @param prefetch The number of upstream items to prefetch so that fresh items are
8624 * ready to be mapped when a previous {@code SingleSource} terminates.
8625 * The operator replenishes after half of the prefetch amount has been consumed
8626 * and turned into {@code SingleSource}s.
8627 * @return the new {@code Flowable} instance
8628 * @throws NullPointerException if {@code mapper} is {@code null}
8629 * @throws IllegalArgumentException if {@code prefetch} is non-positive
8630 * @see #concatMapSingle(Function, int)
8631 * @since 2.2
8632 */
8633 @CheckReturnValue
8634 @NonNull
8635 @BackpressureSupport(BackpressureKind.FULL)
8636 @SchedulerSupport(SchedulerSupport.NONE)
8637 public final <@NonNull R> Flowable<R> concatMapSingleDelayError(@NonNull Function<? super T, ? extends SingleSource<? extends R>> mapper, boolean tillTheEnd, int prefetch) {
8638 Objects.requireNonNull(mapper, "mapper is null");
8639 ObjectHelper.verifyPositive(prefetch, "prefetch");
8640 return RxJavaPlugins.onAssembly(new FlowableConcatMapSingle<>(this, mapper, tillTheEnd ? ErrorMode.END : ErrorMode.BOUNDARY, prefetch));
8641 }
8642
8643 /**
8644 * Returns a {@code Flowable} that emits the items emitted from the current {@code Flowable}, then the next, one after
8645 * the other, without interleaving them.
8646 * <p>
8647 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/concat.v3.png" alt="">
8648 * <dl>
8649 * <dt><b>Backpressure:</b></dt>
8650 * <dd>The operator honors backpressure from downstream. Both this and the {@code other} {@link Publisher}s
8651 * are expected to honor backpressure as well. If any of then violates this rule, it <em>may</em> throw an
8652 * {@link IllegalStateException} when the current {@code Flowable} completes.</dd>
8653 * <dt><b>Scheduler:</b></dt>
8654 * <dd>{@code concatWith} does not operate by default on a particular {@link Scheduler}.</dd>
8655 * </dl>
8656 *
8657 * @param other
8658 * a {@code Publisher} to be concatenated after the current
8659 * @return the new {@code Flowable} instance
8660 * @throws NullPointerException if {@code other} is {@code null}
8661 * @see <a href="http://reactivex.io/documentation/operators/concat.html">ReactiveX operators documentation: Concat</a>
8662 */
8663 @CheckReturnValue
8664 @NonNull
8665 @BackpressureSupport(BackpressureKind.FULL)
8666 @SchedulerSupport(SchedulerSupport.NONE)
8667 public final Flowable<T> concatWith(@NonNull Publisher<? extends T> other) {
8668 Objects.requireNonNull(other, "other is null");
8669 return concat(this, other);
8670 }
8671
8672 /**
8673 * Returns a {@code Flowable} that emits the items from this {@code Flowable} followed by the success item or error event
8674 * of the other {@link SingleSource}.
8675 * <p>
8676 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/concat.v3.png" alt="">
8677 * <dl>
8678 * <dt><b>Backpressure:</b></dt>
8679 * <dd>The operator supports backpressure and makes sure the success item of the other {@code SingleSource}
8680 * is only emitted when there is a demand for it.</dd>
8681 * <dt><b>Scheduler:</b></dt>
8682 * <dd>{@code concatWith} does not operate by default on a particular {@link Scheduler}.</dd>
8683 * </dl>
8684 * <p>History: 2.1.10 - experimental
8685 * @param other the {@code SingleSource} whose signal should be emitted after this {@code Flowable} completes normally.
8686 * @return the new {@code Flowable} instance
8687 * @throws NullPointerException if {@code other} is {@code null}
8688 * @since 2.2
8689 */
8690 @CheckReturnValue
8691 @BackpressureSupport(BackpressureKind.FULL)
8692 @SchedulerSupport(SchedulerSupport.NONE)
8693 @NonNull
8694 public final Flowable<T> concatWith(@NonNull SingleSource<? extends T> other) {
8695 Objects.requireNonNull(other, "other is null");
8696 return RxJavaPlugins.onAssembly(new FlowableConcatWithSingle<>(this, other));
8697 }
8698
8699 /**
8700 * Returns a {@code Flowable} that emits the items from this {@code Flowable} followed by the success item or terminal events
8701 * of the other {@link MaybeSource}.
8702 * <p>
8703 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/concat.v3.png" alt="">
8704 * <dl>
8705 * <dt><b>Backpressure:</b></dt>
8706 * <dd>The operator supports backpressure and makes sure the success item of the other {@code MaybeSource}
8707 * is only emitted when there is a demand for it.</dd>
8708 * <dt><b>Scheduler:</b></dt>
8709 * <dd>{@code concatWith} does not operate by default on a particular {@link Scheduler}.</dd>
8710 * </dl>
8711 * <p>History: 2.1.10 - experimental
8712 * @param other the {@code MaybeSource} whose signal should be emitted after this {@code Flowable} completes normally.
8713 * @return the new {@code Flowable} instance
8714 * @throws NullPointerException if {@code other} is {@code null}
8715 * @since 2.2
8716 */
8717 @CheckReturnValue
8718 @BackpressureSupport(BackpressureKind.FULL)
8719 @SchedulerSupport(SchedulerSupport.NONE)
8720 @NonNull
8721 public final Flowable<T> concatWith(@NonNull MaybeSource<? extends T> other) {
8722 Objects.requireNonNull(other, "other is null");
8723 return RxJavaPlugins.onAssembly(new FlowableConcatWithMaybe<>(this, other));
8724 }
8725
8726 /**
8727 * Returns a {@code Flowable} that emits items from this {@code Flowable} and when it completes normally, the
8728 * other {@link CompletableSource} is subscribed to and the returned {@code Flowable} emits its terminal events.
8729 * <p>
8730 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/concat.v3.png" alt="">
8731 * <dl>
8732 * <dt><b>Backpressure:</b></dt>
8733 * <dd>The operator does not interfere with backpressure between the current {@code Flowable} and the
8734 * downstream consumer (i.e., acts as pass-through). When the operator switches to the
8735 * {@link Completable}, backpressure is no longer present because {@code Completable} doesn't
8736 * have items to apply backpressure to.</dd>
8737 * <dt><b>Scheduler:</b></dt>
8738 * <dd>{@code concatWith} does not operate by default on a particular {@link Scheduler}.</dd>
8739 * </dl>
8740 * <p>History: 2.1.10 - experimental
8741 * @param other the {@code CompletableSource} to subscribe to once the current {@code Flowable} completes normally
8742 * @return the new {@code Flowable} instance
8743 * @throws NullPointerException if {@code other} is {@code null}
8744 * @since 2.2
8745 */
8746 @CheckReturnValue
8747 @BackpressureSupport(BackpressureKind.PASS_THROUGH)
8748 @SchedulerSupport(SchedulerSupport.NONE)
8749 @NonNull
8750 public final Flowable<T> concatWith(@NonNull CompletableSource other) {
8751 Objects.requireNonNull(other, "other is null");
8752 return RxJavaPlugins.onAssembly(new FlowableConcatWithCompletable<>(this, other));
8753 }
8754
8755 /**
8756 * Returns a {@link Single} that emits a {@link Boolean} that indicates whether the current {@code Flowable} emitted a
8757 * specified item.
8758 * <p>
8759 * <img width="640" height="320" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/contains.v3.png" alt="">
8760 * <dl>
8761 * <dt><b>Backpressure:</b></dt>
8762 * <dd>The operator honors backpressure from downstream and consumes the current {@code Flowable} in an
8763 * unbounded manner (i.e., without applying backpressure).</dd>
8764 * <dt><b>Scheduler:</b></dt>
8765 * <dd>{@code contains} does not operate by default on a particular {@link Scheduler}.</dd>
8766 * </dl>
8767 *
8768 * @param item
8769 * the item to search for in the emissions from the current {@code Flowable}
8770 * @return the new {@code Single} instance
8771 * @throws NullPointerException if {@code item} is {@code null}
8772 * @see <a href="http://reactivex.io/documentation/operators/contains.html">ReactiveX operators documentation: Contains</a>
8773 */
8774 @CheckReturnValue
8775 @NonNull
8776 @BackpressureSupport(BackpressureKind.UNBOUNDED_IN)
8777 @SchedulerSupport(SchedulerSupport.NONE)
8778 public final Single<Boolean> contains(@NonNull Object item) {
8779 Objects.requireNonNull(item, "item is null");
8780 return any(Functions.equalsWith(item));
8781 }
8782
8783 /**
8784 * Returns a {@link Single} that counts the total number of items emitted by the current {@code Flowable} and emits
8785 * this count as a 64-bit {@link Long}.
8786 * <p>
8787 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/longCount.v3.png" alt="">
8788 * <dl>
8789 * <dt><b>Backpressure:</b></dt>
8790 * <dd>The operator honors backpressure from downstream and consumes the current {@code Flowable} in an
8791 * unbounded manner (i.e., without applying backpressure).</dd>
8792 * <dt><b>Scheduler:</b></dt>
8793 * <dd>{@code count} does not operate by default on a particular {@link Scheduler}.</dd>
8794 * </dl>
8795 *
8796 * @return the new {@code Single} instance
8797 * @see <a href="http://reactivex.io/documentation/operators/count.html">ReactiveX operators documentation: Count</a>
8798 */
8799 @CheckReturnValue
8800 @BackpressureSupport(BackpressureKind.UNBOUNDED_IN)
8801 @SchedulerSupport(SchedulerSupport.NONE)
8802 @NonNull
8803 public final Single<Long> count() {
8804 return RxJavaPlugins.onAssembly(new FlowableCountSingle<>(this));
8805 }
8806
8807 /**
8808 * Returns a {@code Flowable} that mirrors the current {@code Flowable}, except that it drops items emitted by the
8809 * current {@code Flowable} that are followed by another item within a computed debounce duration.
8810 * <p>
8811 * <img width="640" height="425" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/debounce.f.v3.png" alt="">
8812 * <p>
8813 * The delivery of the item happens on the thread of the first {@code onNext} or {@code onComplete}
8814 * signal of the generated {@link Publisher} sequence,
8815 * which if takes too long, a newer item may arrive from the upstream, causing the
8816 * generated sequence to get cancelled, which may also interrupt any downstream blocking operation
8817 * (yielding an {@code InterruptedException}). It is recommended processing items
8818 * that may take long time to be moved to another thread via {@link #observeOn} applied after
8819 * {@code debounce} itself.
8820 * <dl>
8821 * <dt><b>Backpressure:</b></dt>
8822 * <dd>This operator does not support backpressure as it uses the {@code debounceSelector} to mark
8823 * boundaries.</dd>
8824 * <dt><b>Scheduler:</b></dt>
8825 * <dd>This version of {@code debounce} does not operate by default on a particular {@link Scheduler}.</dd>
8826 * </dl>
8827 *
8828 * @param <U>
8829 * the debounce value type (ignored)
8830 * @param debounceIndicator
8831 * function to retrieve a sequence that indicates the throttle duration for each item
8832 * @return the new {@code Flowable} instance
8833 * @throws NullPointerException if {@code debounceIndicator} is {@code null}
8834 * @see <a href="http://reactivex.io/documentation/operators/debounce.html">ReactiveX operators documentation: Debounce</a>
8835 * @see <a href="https://github.com/ReactiveX/RxJava/wiki/Backpressure">RxJava wiki: Backpressure</a>
8836 */
8837 @CheckReturnValue
8838 @NonNull
8839 @BackpressureSupport(BackpressureKind.ERROR)
8840 @SchedulerSupport(SchedulerSupport.NONE)
8841 public final <@NonNull U> Flowable<T> debounce(@NonNull Function<? super T, @NonNull ? extends Publisher<U>> debounceIndicator) {
8842 Objects.requireNonNull(debounceIndicator, "debounceIndicator is null");
8843 return RxJavaPlugins.onAssembly(new FlowableDebounce<>(this, debounceIndicator));
8844 }
8845
8846 /**
8847 * Returns a {@code Flowable} that mirrors the current {@code Flowable}, except that it drops items emitted by the
8848 * current {@code Flowable} that are followed by newer items before a timeout value expires. The timer resets on
8849 * each emission.
8850 * <p>
8851 * <em>Note:</em> If items keep being emitted by the current {@code Flowable} faster than the timeout then no items
8852 * will be emitted by the resulting {@code Flowable}.
8853 * <p>
8854 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/debounce.v3.png" alt="">
8855 * <p>
8856 * Delivery of the item after the grace period happens on the {@code computation} {@link Scheduler}'s
8857 * {@code Worker} which if takes too long, a newer item may arrive from the upstream, causing the
8858 * {@code Worker}'s task to get disposed, which may also interrupt any downstream blocking operation
8859 * (yielding an {@code InterruptedException}). It is recommended processing items
8860 * that may take long time to be moved to another thread via {@link #observeOn} applied after
8861 * {@code debounce} itself.
8862 * <dl>
8863 * <dt><b>Backpressure:</b></dt>
8864 * <dd>This operator does not support backpressure as it uses time to control data flow.</dd>
8865 * <dt><b>Scheduler:</b></dt>
8866 * <dd>{@code debounce} operates by default on the {@code computation} {@code Scheduler}.</dd>
8867 * </dl>
8868 *
8869 * @param timeout
8870 * the length of the window of time that must pass after the emission of an item from the current
8871 * {@code Flowable} in which it emits no items in order for the item to be emitted by the
8872 * resulting {@code Flowable}
8873 * @param unit
8874 * the unit of time for the specified {@code timeout}
8875 * @return the new {@code Flowable} instance
8876 * @throws NullPointerException if {@code unit} is {@code null}
8877 * @see <a href="http://reactivex.io/documentation/operators/debounce.html">ReactiveX operators documentation: Debounce</a>
8878 * @see <a href="https://github.com/ReactiveX/RxJava/wiki/Backpressure">RxJava wiki: Backpressure</a>
8879 * @see #throttleWithTimeout(long, TimeUnit)
8880 */
8881 @CheckReturnValue
8882 @BackpressureSupport(BackpressureKind.ERROR)
8883 @SchedulerSupport(SchedulerSupport.COMPUTATION)
8884 @NonNull
8885 public final Flowable<T> debounce(long timeout, @NonNull TimeUnit unit) {
8886 return debounce(timeout, unit, Schedulers.computation());
8887 }
8888
8889 /**
8890 * Returns a {@code Flowable} that mirrors the current {@code Flowable}, except that it drops items emitted by the
8891 * current {@code Flowable} that are followed by newer items before a timeout value expires on a specified
8892 * {@link Scheduler}. The timer resets on each emission.
8893 * <p>
8894 * <em>Note:</em> If items keep being emitted by the current {@code Flowable} faster than the timeout then no items
8895 * will be emitted by the resulting {@code Flowable}.
8896 * <p>
8897 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/debounce.s.v3.png" alt="">
8898 * <p>
8899 * Delivery of the item after the grace period happens on the given {@code Scheduler}'s
8900 * {@code Worker} which if takes too long, a newer item may arrive from the upstream, causing the
8901 * {@code Worker}'s task to get disposed, which may also interrupt any downstream blocking operation
8902 * (yielding an {@code InterruptedException}). It is recommended processing items
8903 * that may take long time to be moved to another thread via {@link #observeOn} applied after
8904 * {@code debounce} itself.
8905 * <dl>
8906 * <dt><b>Backpressure:</b></dt>
8907 * <dd>This operator does not support backpressure as it uses time to control data flow.</dd>
8908 * <dt><b>Scheduler:</b></dt>
8909 * <dd>You specify which {@code Scheduler} this operator will use.</dd>
8910 * </dl>
8911 *
8912 * @param timeout
8913 * the time each item has to be "the most recent" of those emitted by the current {@code Flowable} to
8914 * ensure that it's not dropped
8915 * @param unit
8916 * the unit of time for the specified {@code timeout}
8917 * @param scheduler
8918 * the {@code Scheduler} to use internally to manage the timers that handle the timeout for each
8919 * item
8920 * @return the new {@code Flowable} instance
8921 * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null}
8922 * @see <a href="http://reactivex.io/documentation/operators/debounce.html">ReactiveX operators documentation: Debounce</a>
8923 * @see <a href="https://github.com/ReactiveX/RxJava/wiki/Backpressure">RxJava wiki: Backpressure</a>
8924 * @see #throttleWithTimeout(long, TimeUnit, Scheduler)
8925 */
8926 @CheckReturnValue
8927 @NonNull
8928 @BackpressureSupport(BackpressureKind.ERROR)
8929 @SchedulerSupport(SchedulerSupport.CUSTOM)
8930 public final Flowable<T> debounce(long timeout, @NonNull TimeUnit unit, @NonNull Scheduler scheduler) {
8931 Objects.requireNonNull(unit, "unit is null");
8932 Objects.requireNonNull(scheduler, "scheduler is null");
8933 return RxJavaPlugins.onAssembly(new FlowableDebounceTimed<>(this, timeout, unit, scheduler));
8934 }
8935
8936 /**
8937 * Returns a {@code Flowable} that emits the items emitted by the current {@code Flowable} or a specified default item
8938 * if the current {@code Flowable} is empty.
8939 * <p>
8940 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/defaultIfEmpty.v3.png" alt="">
8941 * <dl>
8942 * <dt><b>Backpressure:</b></dt>
8943 * <dd>If the current {@code Flowable} is empty, this operator is guaranteed to honor backpressure from downstream.
8944 * If the current {@code Flowable} is non-empty, it is expected to honor backpressure as well; if the rule is violated,
8945 * a {@link MissingBackpressureException} <em>may</em> get signaled somewhere downstream.
8946 * </dd>
8947 * <dt><b>Scheduler:</b></dt>
8948 * <dd>{@code defaultIfEmpty} does not operate by default on a particular {@link Scheduler}.</dd>
8949 * </dl>
8950 *
8951 * @param defaultItem
8952 * the item to emit if the current {@code Flowable} emits no items
8953 * @return the new {@code Flowable} instance
8954 * @throws NullPointerException if {@code defaultItem} is {@code null}
8955 * @see <a href="http://reactivex.io/documentation/operators/defaultifempty.html">ReactiveX operators documentation: DefaultIfEmpty</a>
8956 */
8957 @CheckReturnValue
8958 @NonNull
8959 @BackpressureSupport(BackpressureKind.FULL)
8960 @SchedulerSupport(SchedulerSupport.NONE)
8961 public final Flowable<T> defaultIfEmpty(@NonNull T defaultItem) {
8962 Objects.requireNonNull(defaultItem, "defaultItem is null");
8963 return switchIfEmpty(just(defaultItem));
8964 }
8965
8966 /**
8967 * Returns a {@code Flowable} that delays the emissions of the current {@code Flowable} via another {@link Publisher} on a
8968 * per-item basis.
8969 * <p>
8970 * <img width="640" height="450" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/delay.o.v3.png" alt="">
8971 * <p>
8972 * <em>Note:</em> the resulting {@code Flowable} will immediately propagate any {@code onError} notification
8973 * from the current {@code Flowable}.
8974 * <dl>
8975 * <dt><b>Backpressure:</b></dt>
8976 * <dd>The operator doesn't interfere with the backpressure behavior which is determined by the current {@code Flowable}.
8977 * All of the other {@code Publisher}s supplied by the function are consumed
8978 * in an unbounded manner (i.e., no backpressure applied to them).</dd>
8979 * <dt><b>Scheduler:</b></dt>
8980 * <dd>This version of {@code delay} does not operate by default on a particular {@link Scheduler}.</dd>
8981 * </dl>
8982 *
8983 * @param <U>
8984 * the item delay value type (ignored)
8985 * @param itemDelayIndicator
8986 * a function that returns a {@code Publisher} for each item emitted by the current {@code Flowable}, which is
8987 * then used to delay the emission of that item by the resulting {@code Flowable} until the {@code Publisher}
8988 * returned from {@code itemDelay} emits an item
8989 * @return the new {@code Flowable} instance
8990 * @throws NullPointerException if {@code itemDelayIndicator} is {@code null}
8991 * @see <a href="http://reactivex.io/documentation/operators/delay.html">ReactiveX operators documentation: Delay</a>
8992 */
8993 @CheckReturnValue
8994 @NonNull
8995 @BackpressureSupport(BackpressureKind.FULL)
8996 @SchedulerSupport(SchedulerSupport.NONE)
8997 public final <@NonNull U> Flowable<T> delay(@NonNull Function<? super T, @NonNull ? extends Publisher<U>> itemDelayIndicator) {
8998 Objects.requireNonNull(itemDelayIndicator, "itemDelayIndicator is null");
8999 return flatMap(FlowableInternalHelper.itemDelay(itemDelayIndicator));
9000 }
9001
9002 /**
9003 * Returns a {@code Flowable} that emits the items emitted by the current {@code Flowable} shifted forward in time by a
9004 * specified delay. The {@code onError} notification from the current {@code Flowable} is not delayed.
9005 * <p>
9006 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/delay.v3.png" alt="">
9007 * <dl>
9008 * <dt><b>Backpressure:</b></dt>
9009 * <dd>The operator doesn't interfere with the backpressure behavior which is determined by the current {@code Flowable}.</dd>
9010 * <dt><b>Scheduler:</b></dt>
9011 * <dd>This version of {@code delay} operates by default on the {@code computation} {@link Scheduler}.</dd>
9012 * </dl>
9013 *
9014 * @param time
9015 * the delay to shift the source by
9016 * @param unit
9017 * the {@link TimeUnit} in which {@code period} is defined
9018 * @return the new {@code Flowable} instance
9019 * @throws NullPointerException if {@code unit} is {@code null}
9020 * @see <a href="http://reactivex.io/documentation/operators/delay.html">ReactiveX operators documentation: Delay</a>
9021 */
9022 @CheckReturnValue
9023 @BackpressureSupport(BackpressureKind.FULL)
9024 @SchedulerSupport(SchedulerSupport.COMPUTATION)
9025 @NonNull
9026 public final Flowable<T> delay(long time, @NonNull TimeUnit unit) {
9027 return delay(time, unit, Schedulers.computation(), false);
9028 }
9029
9030 /**
9031 * Returns a {@code Flowable} that emits the items emitted by the current {@code Flowable} shifted forward in time by a
9032 * specified delay. If {@code delayError} is {@code true}, error notifications will also be delayed.
9033 * <p>
9034 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/delay.v3.png" alt="">
9035 * <dl>
9036 * <dt><b>Backpressure:</b></dt>
9037 * <dd>The operator doesn't interfere with the backpressure behavior which is determined by the current {@code Flowable}.</dd>
9038 * <dt><b>Scheduler:</b></dt>
9039 * <dd>This version of {@code delay} operates by default on the {@code computation} {@link Scheduler}.</dd>
9040 * </dl>
9041 *
9042 * @param time
9043 * the delay to shift the source by
9044 * @param unit
9045 * the {@link TimeUnit} in which {@code period} is defined
9046 * @param delayError
9047 * if {@code true}, the upstream exception is signaled with the given delay, after all preceding normal elements,
9048 * if {@code false}, the upstream exception is signaled immediately
9049 * @return the new {@code Flowable} instance
9050 * @throws NullPointerException if {@code unit} is {@code null}
9051 * @see <a href="http://reactivex.io/documentation/operators/delay.html">ReactiveX operators documentation: Delay</a>
9052 */
9053 @CheckReturnValue
9054 @BackpressureSupport(BackpressureKind.FULL)
9055 @SchedulerSupport(SchedulerSupport.COMPUTATION)
9056 @NonNull
9057 public final Flowable<T> delay(long time, @NonNull TimeUnit unit, boolean delayError) {
9058 return delay(time, unit, Schedulers.computation(), delayError);
9059 }
9060
9061 /**
9062 * Returns a {@code Flowable} that emits the items emitted by the current {@code Flowable} shifted forward in time by a
9063 * specified delay. The {@code onError} notification from the current {@code Flowable} is not delayed.
9064 * <p>
9065 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/delay.s.v3.png" alt="">
9066 * <dl>
9067 * <dt><b>Backpressure:</b></dt>
9068 * <dd>The operator doesn't interfere with the backpressure behavior which is determined by the current {@code Flowable}.</dd>
9069 * <dt><b>Scheduler:</b></dt>
9070 * <dd>You specify which {@link Scheduler} this operator will use.</dd>
9071 * </dl>
9072 *
9073 * @param time
9074 * the delay to shift the source by
9075 * @param unit
9076 * the time unit of {@code delay}
9077 * @param scheduler
9078 * the {@code Scheduler} to use for delaying
9079 * @return the new {@code Flowable} instance
9080 * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null}
9081 * @see <a href="http://reactivex.io/documentation/operators/delay.html">ReactiveX operators documentation: Delay</a>
9082 */
9083 @CheckReturnValue
9084 @BackpressureSupport(BackpressureKind.FULL)
9085 @SchedulerSupport(SchedulerSupport.CUSTOM)
9086 @NonNull
9087 public final Flowable<T> delay(long time, @NonNull TimeUnit unit, @NonNull Scheduler scheduler) {
9088 return delay(time, unit, scheduler, false);
9089 }
9090
9091 /**
9092 * Returns a {@code Flowable} that emits the items emitted by the current {@code Flowable} shifted forward in time by a
9093 * specified delay. If {@code delayError} is {@code true}, error notifications will also be delayed.
9094 * <p>
9095 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/delay.s.v3.png" alt="">
9096 * <dl>
9097 * <dt><b>Backpressure:</b></dt>
9098 * <dd>The operator doesn't interfere with the backpressure behavior which is determined by the current {@code Flowable}.</dd>
9099 * <dt><b>Scheduler:</b></dt>
9100 * <dd>You specify which {@link Scheduler} this operator will use.</dd>
9101 * </dl>
9102 *
9103 * @param time
9104 * the delay to shift the source by
9105 * @param unit
9106 * the time unit of {@code delay}
9107 * @param scheduler
9108 * the {@code Scheduler} to use for delaying
9109 * @param delayError
9110 * if {@code true}, the upstream exception is signaled with the given delay, after all preceding normal elements,
9111 * if {@code false}, the upstream exception is signaled immediately
9112 * @return the new {@code Flowable} instance
9113 * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null}
9114 * @see <a href="http://reactivex.io/documentation/operators/delay.html">ReactiveX operators documentation: Delay</a>
9115 */
9116 @CheckReturnValue
9117 @NonNull
9118 @BackpressureSupport(BackpressureKind.FULL)
9119 @SchedulerSupport(SchedulerSupport.CUSTOM)
9120 public final Flowable<T> delay(long time, @NonNull TimeUnit unit, @NonNull Scheduler scheduler, boolean delayError) {
9121 Objects.requireNonNull(unit, "unit is null");
9122 Objects.requireNonNull(scheduler, "scheduler is null");
9123
9124 return RxJavaPlugins.onAssembly(new FlowableDelay<>(this, Math.max(0L, time), unit, scheduler, delayError));
9125 }
9126
9127 /**
9128 * Returns a {@code Flowable} that delays the subscription to and emissions from the current {@code Flowable} via another
9129 * {@link Publisher} on a per-item basis.
9130 * <p>
9131 * <img width="640" height="450" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/delay.oo.v3.png" alt="">
9132 * <p>
9133 * <em>Note:</em> the resulting {@code Flowable} will immediately propagate any {@code onError} notification
9134 * from the current {@code Flowable}.
9135 * <dl>
9136 * <dt><b>Backpressure:</b></dt>
9137 * <dd>The operator doesn't interfere with the backpressure behavior which is determined by the current {@code Flowable}.
9138 * All of the other {@code Publisher}s supplied by the functions are consumed
9139 * in an unbounded manner (i.e., no backpressure applied to them).</dd>
9140 * <dt><b>Scheduler:</b></dt>
9141 * <dd>This version of {@code delay} does not operate by default on a particular {@link Scheduler}.</dd>
9142 * </dl>
9143 *
9144 * @param <U>
9145 * the subscription delay value type (ignored)
9146 * @param <V>
9147 * the item delay value type (ignored)
9148 * @param subscriptionIndicator
9149 * a function that returns a {@code Publisher} that triggers the subscription to the current {@code Flowable}
9150 * once it emits any item
9151 * @param itemDelayIndicator
9152 * a function that returns a {@code Publisher} for each item emitted by the current {@code Flowable}, which is
9153 * then used to delay the emission of that item by the resulting {@code Flowable} until the {@code Publisher}
9154 * returned from {@code itemDelay} emits an item
9155 * @return the new {@code Flowable} instance
9156 * @throws NullPointerException if {@code subscriptionIndicator} and {@code itemDelayIndicator} is {@code null}
9157 * @see <a href="http://reactivex.io/documentation/operators/delay.html">ReactiveX operators documentation: Delay</a>
9158 */
9159 @CheckReturnValue
9160 @BackpressureSupport(BackpressureKind.FULL)
9161 @SchedulerSupport(SchedulerSupport.NONE)
9162 @NonNull
9163 public final <@NonNull U, @NonNull V> Flowable<T> delay(@NonNull Publisher<U> subscriptionIndicator,
9164 @NonNull Function<? super T, @NonNull ? extends Publisher<V>> itemDelayIndicator) {
9165 return delaySubscription(subscriptionIndicator).delay(itemDelayIndicator);
9166 }
9167
9168 /**
9169 * Returns a {@code Flowable} that delays the subscription to this {@link Publisher}
9170 * until the other {@code Publisher} emits an element or completes normally.
9171 * <dl>
9172 * <dt><b>Backpressure:</b></dt>
9173 * <dd>The operator forwards the backpressure requests to this {@code Publisher} once
9174 * the subscription happens and requests {@link Long#MAX_VALUE} from the other {@code Publisher}</dd>
9175 * <dt><b>Scheduler:</b></dt>
9176 * <dd>This method does not operate by default on a particular {@link Scheduler}.</dd>
9177 * </dl>
9178 *
9179 * @param <U> the value type of the other {@code Publisher}, irrelevant
9180 * @param subscriptionIndicator the other {@code Publisher} that should trigger the subscription
9181 * to this {@code Publisher}.
9182 * @return the new {@code Flowable} instance
9183 * @throws NullPointerException if {@code subscriptionIndicator} is {@code null}
9184 * @since 2.0
9185 */
9186 @CheckReturnValue
9187 @NonNull
9188 @BackpressureSupport(BackpressureKind.FULL)
9189 @SchedulerSupport(SchedulerSupport.NONE)
9190 public final <@NonNull U> Flowable<T> delaySubscription(@NonNull Publisher<U> subscriptionIndicator) {
9191 Objects.requireNonNull(subscriptionIndicator, "subscriptionIndicator is null");
9192 return RxJavaPlugins.onAssembly(new FlowableDelaySubscriptionOther<>(this, subscriptionIndicator));
9193 }
9194
9195 /**
9196 * Returns a {@code Flowable} that delays the subscription to the current {@code Flowable} by a given amount of time.
9197 * <p>
9198 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/delaySubscription.v3.png" alt="">
9199 * <dl>
9200 * <dt><b>Backpressure:</b></dt>
9201 * <dd>The operator doesn't interfere with the backpressure behavior which is determined by the current {@code Flowable}.</dd>
9202 * <dt><b>Scheduler:</b></dt>
9203 * <dd>This version of {@code delaySubscription} operates by default on the {@code computation} {@link Scheduler}.</dd>
9204 * </dl>
9205 *
9206 * @param time
9207 * the time to delay the subscription
9208 * @param unit
9209 * the time unit of {@code delay}
9210 * @return the new {@code Flowable} instance
9211 * @throws NullPointerException if {@code unit} is {@code null}
9212 * @see <a href="http://reactivex.io/documentation/operators/delay.html">ReactiveX operators documentation: Delay</a>
9213 */
9214 @CheckReturnValue
9215 @BackpressureSupport(BackpressureKind.FULL)
9216 @SchedulerSupport(SchedulerSupport.COMPUTATION)
9217 @NonNull
9218 public final Flowable<T> delaySubscription(long time, @NonNull TimeUnit unit) {
9219 return delaySubscription(time, unit, Schedulers.computation());
9220 }
9221
9222 /**
9223 * Returns a {@code Flowable} that delays the subscription to the current {@code Flowable} by a given amount of time,
9224 * both waiting and subscribing on a given {@link Scheduler}.
9225 * <p>
9226 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/delaySubscription.s.v3.png" alt="">
9227 * <dl>
9228 * <dt><b>Backpressure:</b></dt>
9229 * <dd>The operator doesn't interfere with the backpressure behavior which is determined by the current {@code Flowable}.</dd>
9230 * <dt><b>Scheduler:</b></dt>
9231 * <dd>You specify which {@code Scheduler} this operator will use.</dd>
9232 * </dl>
9233 *
9234 * @param time
9235 * the time to delay the subscription
9236 * @param unit
9237 * the time unit of {@code delay}
9238 * @param scheduler
9239 * the {@code Scheduler} on which the waiting and subscription will happen
9240 * @return the new {@code Flowable} instance
9241 * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null}
9242 * @see <a href="http://reactivex.io/documentation/operators/delay.html">ReactiveX operators documentation: Delay</a>
9243 */
9244 @CheckReturnValue
9245 @BackpressureSupport(BackpressureKind.FULL)
9246 @SchedulerSupport(SchedulerSupport.CUSTOM)
9247 @NonNull
9248 public final Flowable<T> delaySubscription(long time, @NonNull TimeUnit unit, @NonNull Scheduler scheduler) {
9249 return delaySubscription(timer(time, unit, scheduler));
9250 }
9251
9252 /**
9253 * Returns a {@code Flowable} that reverses the effect of {@link #materialize materialize} by transforming the
9254 * {@link Notification} objects extracted from the source items via a selector function
9255 * into their respective {@link Subscriber} signal types.
9256 * <p>
9257 * <img width="640" height="335" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/dematerialize.v3.png" alt="">
9258 * <p>
9259 * The intended use of the {@code selector} function is to perform a
9260 * type-safe identity mapping (see example) on a source that is already of type
9261 * {@code Notification<T>}. The Java language doesn't allow
9262 * limiting instance methods to a certain generic argument shape, therefore,
9263 * a function is used to ensure the conversion remains type safe.
9264 * <p>
9265 * When the upstream signals an {@link Notification#createOnError(Throwable) onError} or
9266 * {@link Notification#createOnComplete() onComplete} item, the
9267 * returned {@code Flowable} cancels of the flow and terminates with that type of terminal event:
9268 * <pre><code>
9269 * Flowable.just(createOnNext(1), createOnComplete(), createOnNext(2))
9270 * .doOnCancel(() -&gt; System.out.println("Canceled!"));
9271 * .dematerialize(notification -&gt; notification)
9272 * .test()
9273 * .assertResult(1);
9274 * </code></pre>
9275 * If the upstream signals {@code onError} or {@code onComplete} directly, the flow is terminated
9276 * with the same event.
9277 * <pre><code>
9278 * Flowable.just(createOnNext(1), createOnNext(2))
9279 * .dematerialize(notification -&gt; notification)
9280 * .test()
9281 * .assertResult(1, 2);
9282 * </code></pre>
9283 * If this behavior is not desired, the completion can be suppressed by applying {@link #concatWith(Publisher)}
9284 * with a {@link #never()} source.
9285 * <dl>
9286 * <dt><b>Backpressure:</b></dt>
9287 * <dd>The operator doesn't interfere with backpressure which is determined by the current {@code Flowable}'s
9288 * backpressure behavior.</dd>
9289 * <dt><b>Scheduler:</b></dt>
9290 * <dd>{@code dematerialize} does not operate by default on a particular {@link Scheduler}.</dd>
9291 * </dl>
9292 * <p>History: 2.2.4 - experimental
9293 *
9294 * @param <R> the output value type
9295 * @param selector function that returns the upstream item and should return a {@code Notification} to signal
9296 * the corresponding {@code Subscriber} event to the downstream.
9297 * @return the new {@code Flowable} instance
9298 * @throws NullPointerException if {@code selector} is {@code null}
9299 * @see <a href="http://reactivex.io/documentation/operators/materialize-dematerialize.html">ReactiveX operators documentation: Dematerialize</a>
9300 * @since 3.0.0
9301 */
9302 @CheckReturnValue
9303 @NonNull
9304 @SchedulerSupport(SchedulerSupport.NONE)
9305 @BackpressureSupport(BackpressureKind.PASS_THROUGH)
9306 public final <@NonNull R> Flowable<R> dematerialize(@NonNull Function<@NonNull ? super T, @NonNull Notification<R>> selector) {
9307 Objects.requireNonNull(selector, "selector is null");
9308 return RxJavaPlugins.onAssembly(new FlowableDematerialize<>(this, selector));
9309 }
9310
9311 /**
9312 * Returns a {@code Flowable} that emits all items emitted by the current {@code Flowable} that are distinct
9313 * based on {@link Object#equals(Object)} comparison.
9314 * <p>
9315 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/distinct.v3.png" alt="">
9316 * <p>
9317 * It is recommended the elements' class {@code T} in the flow overrides the default {@code Object.equals()} and {@link Object#hashCode()} to provide
9318 * a meaningful comparison between items as the default Java implementation only considers reference equivalence.
9319 * <p>
9320 * By default, {@code distinct()} uses an internal {@link java.util.HashSet} per {@link Subscriber} to remember
9321 * previously seen items and uses {@link java.util.Set#add(Object)} returning {@code false} as the
9322 * indicator for duplicates.
9323 * <p>
9324 * Note that this internal {@link HashSet} may grow unbounded as items won't be removed from it by
9325 * the operator. Therefore, using very long or infinite upstream (with very distinct elements) may lead
9326 * to {@link OutOfMemoryError}.
9327 * <p>
9328 * Customizing the retention policy can happen only by providing a custom {@link java.util.Collection} implementation
9329 * to the {@link #distinct(Function, Supplier)} overload.
9330 * <dl>
9331 * <dt><b>Backpressure:</b></dt>
9332 * <dd>The operator doesn't interfere with backpressure which is determined by the current {@code Flowable}'s
9333 * backpressure behavior.</dd>
9334 * <dt><b>Scheduler:</b></dt>
9335 * <dd>{@code distinct} does not operate by default on a particular {@link Scheduler}.</dd>
9336 * </dl>
9337 *
9338 * @return the new {@code Flowable} instance
9339 * @see <a href="http://reactivex.io/documentation/operators/distinct.html">ReactiveX operators documentation: Distinct</a>
9340 * @see #distinct(Function)
9341 * @see #distinct(Function, Supplier)
9342 */
9343 @SuppressWarnings({ "rawtypes", "unchecked" })
9344 @CheckReturnValue
9345 @BackpressureSupport(BackpressureKind.FULL)
9346 @SchedulerSupport(SchedulerSupport.NONE)
9347 @NonNull
9348 public final Flowable<T> distinct() {
9349 return distinct((Function)Functions.identity(), Functions.<T>createHashSet());
9350 }
9351
9352 /**
9353 * Returns a {@code Flowable} that emits all items emitted by the current {@code Flowable} that are distinct according
9354 * to a key selector function and based on {@link Object#equals(Object)} comparison of the objects
9355 * returned by the key selector function.
9356 * <p>
9357 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/distinct.key.v3.png" alt="">
9358 * <p>
9359 * It is recommended the keys' class {@code K} overrides the default {@code Object.equals()} and {@link Object#hashCode()} to provide
9360 * a meaningful comparison between the key objects as the default Java implementation only considers reference equivalence.
9361 * <p>
9362 * By default, {@code distinct()} uses an internal {@link java.util.HashSet} per {@link Subscriber} to remember
9363 * previously seen keys and uses {@link java.util.Set#add(Object)} returning {@code false} as the
9364 * indicator for duplicates.
9365 * <p>
9366 * Note that this internal {@link HashSet} may grow unbounded as keys won't be removed from it by
9367 * the operator. Therefore, using very long or infinite upstream (with very distinct keys) may lead
9368 * to {@link OutOfMemoryError}.
9369 * <p>
9370 * Customizing the retention policy can happen only by providing a custom {@link java.util.Collection} implementation
9371 * to the {@link #distinct(Function, Supplier)} overload.
9372 * <dl>
9373 * <dt><b>Backpressure:</b></dt>
9374 * <dd>The operator doesn't interfere with backpressure which is determined by the current {@code Flowable}'s
9375 * backpressure behavior.</dd>
9376 * <dt><b>Scheduler:</b></dt>
9377 * <dd>{@code distinct} does not operate by default on a particular {@link Scheduler}.</dd>
9378 * </dl>
9379 *
9380 * @param <K> the key type
9381 * @param keySelector
9382 * a function that projects an emitted item to a key value that is used to decide whether an item
9383 * is distinct from another one or not
9384 * @return the new {@code Flowable} instance
9385 * @throws NullPointerException if {@code keySelector} is {@code null}
9386 * @see <a href="http://reactivex.io/documentation/operators/distinct.html">ReactiveX operators documentation: Distinct</a>
9387 * @see #distinct(Function, Supplier)
9388 */
9389 @CheckReturnValue
9390 @BackpressureSupport(BackpressureKind.FULL)
9391 @SchedulerSupport(SchedulerSupport.NONE)
9392 @NonNull
9393 public final <@NonNull K> Flowable<T> distinct(@NonNull Function<? super T, K> keySelector) {
9394 return distinct(keySelector, Functions.createHashSet());
9395 }
9396
9397 /**
9398 * Returns a {@code Flowable} that emits all items emitted by the current {@code Flowable} that are distinct according
9399 * to a key selector function and based on {@link Object#equals(Object)} comparison of the objects
9400 * returned by the key selector function.
9401 * <p>
9402 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/distinct.key.v3.png" alt="">
9403 * <p>
9404 * It is recommended the keys' class {@code K} overrides the default {@code Object.equals()} and {@link Object#hashCode()} to provide
9405 * a meaningful comparison between the key objects as the default Java implementation only considers reference equivalence.
9406 * <dl>
9407 * <dt><b>Backpressure:</b></dt>
9408 * <dd>The operator doesn't interfere with backpressure which is determined by the current {@code Flowable}'s
9409 * backpressure behavior.</dd>
9410 * <dt><b>Scheduler:</b></dt>
9411 * <dd>{@code distinct} does not operate by default on a particular {@link Scheduler}.</dd>
9412 * </dl>
9413 *
9414 * @param <K> the key type
9415 * @param keySelector
9416 * a function that projects an emitted item to a key value that is used to decide whether an item
9417 * is distinct from another one or not
9418 * @param collectionSupplier
9419 * function called for each individual {@link Subscriber} to return a {@link Collection} subtype for holding the extracted
9420 * keys and whose add() method's return indicates uniqueness.
9421 * @return the new {@code Flowable} instance
9422 * @throws NullPointerException if {@code keySelector} or {@code collectionSupplier} is {@code null}
9423 * @see <a href="http://reactivex.io/documentation/operators/distinct.html">ReactiveX operators documentation: Distinct</a>
9424 */
9425 @CheckReturnValue
9426 @BackpressureSupport(BackpressureKind.FULL)
9427 @SchedulerSupport(SchedulerSupport.NONE)
9428 @NonNull
9429 public final <@NonNull K> Flowable<T> distinct(@NonNull Function<? super T, K> keySelector,
9430 @NonNull Supplier<? extends Collection<? super K>> collectionSupplier) {
9431 Objects.requireNonNull(keySelector, "keySelector is null");
9432 Objects.requireNonNull(collectionSupplier, "collectionSupplier is null");
9433 return RxJavaPlugins.onAssembly(new FlowableDistinct<>(this, keySelector, collectionSupplier));
9434 }
9435
9436 /**
9437 * Returns a {@code Flowable} that emits all items emitted by the current {@code Flowable} that are distinct from their
9438 * immediate predecessors based on {@link Object#equals(Object)} comparison.
9439 * <p>
9440 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/distinctUntilChanged.v3.png" alt="">
9441 * <p>
9442 * It is recommended the elements' class {@code T} in the flow overrides the default {@code Object.equals()} to provide
9443 * a meaningful comparison between items as the default Java implementation only considers reference equivalence.
9444 * Alternatively, use the {@link #distinctUntilChanged(BiPredicate)} overload and provide a comparison function
9445 * in case the class {@code T} can't be overridden with custom {@code equals()} or the comparison itself
9446 * should happen on different terms or properties of the class {@code T}.
9447 * <p>
9448 * Note that the operator always retains the latest item from upstream regardless of the comparison result
9449 * and uses it in the next comparison with the next upstream item.
9450 * <p>
9451 * Note that if element type {@code T} in the flow is mutable, the comparison of the previous and current
9452 * item may yield unexpected results if the items are mutated externally. Common cases are mutable
9453 * {@link CharSequence}s or {@link List}s where the objects will actually have the same
9454 * references when they are modified and {@code distinctUntilChanged} will evaluate subsequent items as same.
9455 * To avoid such situation, it is recommended that mutable data is converted to an immutable one,
9456 * for example using {@code map(CharSequence::toString)} or {@code map(list -> Collections.unmodifiableList(new ArrayList<>(list)))}.
9457 * <dl>
9458 * <dt><b>Backpressure:</b></dt>
9459 * <dd>The operator doesn't interfere with backpressure which is determined by the current {@code Flowable}'s
9460 * backpressure behavior.</dd>
9461 * <dt><b>Scheduler:</b></dt>
9462 * <dd>{@code distinctUntilChanged} does not operate by default on a particular {@link Scheduler}.</dd>
9463 * </dl>
9464 *
9465 * @return the new {@code Flowable} instance
9466 * @see <a href="http://reactivex.io/documentation/operators/distinct.html">ReactiveX operators documentation: Distinct</a>
9467 * @see #distinctUntilChanged(BiPredicate)
9468 */
9469 @CheckReturnValue
9470 @BackpressureSupport(BackpressureKind.FULL)
9471 @SchedulerSupport(SchedulerSupport.NONE)
9472 @NonNull
9473 public final Flowable<T> distinctUntilChanged() {
9474 return distinctUntilChanged(Functions.identity());
9475 }
9476
9477 /**
9478 * Returns a {@code Flowable} that emits all items emitted by the current {@code Flowable} that are distinct from their
9479 * immediate predecessors, according to a key selector function and based on {@link Object#equals(Object)} comparison
9480 * of those objects returned by the key selector function.
9481 * <p>
9482 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/distinctUntilChanged.key.v3.png" alt="">
9483 * <p>
9484 * It is recommended the keys' class {@code K} overrides the default {@code Object.equals()} to provide
9485 * a meaningful comparison between the key objects as the default Java implementation only considers reference equivalence.
9486 * Alternatively, use the {@link #distinctUntilChanged(BiPredicate)} overload and provide a comparison function
9487 * in case the class {@code K} can't be overridden with custom {@code equals()} or the comparison itself
9488 * should happen on different terms or properties of the item class {@code T} (for which the keys can be
9489 * derived via a similar selector).
9490 * <p>
9491 * Note that the operator always retains the latest key from upstream regardless of the comparison result
9492 * and uses it in the next comparison with the next key derived from the next upstream item.
9493 * <p>
9494 * Note that if element type {@code T} in the flow is mutable, the comparison of the previous and current
9495 * item may yield unexpected results if the items are mutated externally. Common cases are mutable
9496 * {@link CharSequence}s or {@link List}s where the objects will actually have the same
9497 * references when they are modified and {@code distinctUntilChanged} will evaluate subsequent items as same.
9498 * To avoid such situation, it is recommended that mutable data is converted to an immutable one,
9499 * for example using {@code map(CharSequence::toString)} or {@code map(list -> Collections.unmodifiableList(new ArrayList<>(list)))}.
9500 * <dl>
9501 * <dt><b>Backpressure:</b></dt>
9502 * <dd>The operator doesn't interfere with backpressure which is determined by the current {@code Flowable}'s
9503 * backpressure behavior.</dd>
9504 * <dt><b>Scheduler:</b></dt>
9505 * <dd>{@code distinctUntilChanged} does not operate by default on a particular {@link Scheduler}.</dd>
9506 * </dl>
9507 *
9508 * @param <K> the key type
9509 * @param keySelector
9510 * a function that projects an emitted item to a key value that is used to decide whether an item
9511 * is distinct from another one or not
9512 * @return the new {@code Flowable} instance
9513 * @throws NullPointerException if {@code keySelector} is {@code null}
9514 * @see <a href="http://reactivex.io/documentation/operators/distinct.html">ReactiveX operators documentation: Distinct</a>
9515 */
9516 @CheckReturnValue
9517 @BackpressureSupport(BackpressureKind.FULL)
9518 @SchedulerSupport(SchedulerSupport.NONE)
9519 @NonNull
9520 public final <@NonNull K> Flowable<T> distinctUntilChanged(@NonNull Function<? super T, K> keySelector) {
9521 Objects.requireNonNull(keySelector, "keySelector is null");
9522 return RxJavaPlugins.onAssembly(new FlowableDistinctUntilChanged<>(this, keySelector, ObjectHelper.equalsPredicate()));
9523 }
9524
9525 /**
9526 * Returns a {@code Flowable} that emits all items emitted by the current {@code Flowable} that are distinct from their
9527 * immediate predecessors when compared with each other via the provided comparator function.
9528 * <p>
9529 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/distinctUntilChanged.v3.png" alt="">
9530 * <p>
9531 * Note that the operator always retains the latest item from upstream regardless of the comparison result
9532 * and uses it in the next comparison with the next upstream item.
9533 * <p>
9534 * Note that if element type {@code T} in the flow is mutable, the comparison of the previous and current
9535 * item may yield unexpected results if the items are mutated externally. Common cases are mutable
9536 * {@link CharSequence}s or {@link List}s where the objects will actually have the same
9537 * references when they are modified and {@code distinctUntilChanged} will evaluate subsequent items as same.
9538 * To avoid such situation, it is recommended that mutable data is converted to an immutable one,
9539 * for example using {@code map(CharSequence::toString)} or {@code map(list -> Collections.unmodifiableList(new ArrayList<>(list)))}.
9540 * <dl>
9541 * <dt><b>Backpressure:</b></dt>
9542 * <dd>The operator doesn't interfere with backpressure which is determined by the current {@code Flowable}'s
9543 * backpressure behavior.</dd>
9544 * <dt><b>Scheduler:</b></dt>
9545 * <dd>{@code distinctUntilChanged} does not operate by default on a particular {@link Scheduler}.</dd>
9546 * </dl>
9547 *
9548 * @param comparer the function that receives the previous item and the current item and is
9549 * expected to return {@code true} if the two are equal, thus skipping the current value.
9550 * @return the new {@code Flowable} instance
9551 * @throws NullPointerException if {@code comparer} is {@code null}
9552 * @see <a href="http://reactivex.io/documentation/operators/distinct.html">ReactiveX operators documentation: Distinct</a>
9553 * @since 2.0
9554 */
9555 @CheckReturnValue
9556 @BackpressureSupport(BackpressureKind.FULL)
9557 @SchedulerSupport(SchedulerSupport.NONE)
9558 @NonNull
9559 public final Flowable<T> distinctUntilChanged(@NonNull BiPredicate<? super T, ? super T> comparer) {
9560 Objects.requireNonNull(comparer, "comparer is null");
9561 return RxJavaPlugins.onAssembly(new FlowableDistinctUntilChanged<>(this, Functions.identity(), comparer));
9562 }
9563
9564 /**
9565 * Calls the specified action after this {@code Flowable} signals {@code onError} or {@code onComplete} or gets canceled by
9566 * the downstream.
9567 * <p>In case of a race between a terminal event and a cancellation, the provided {@code onFinally} action
9568 * is executed once per subscription.
9569 * <p>Note that the {@code onFinally} action is shared between subscriptions and as such
9570 * should be thread-safe.
9571 * <dl>
9572 * <dt><b>Backpressure:</b></dt>
9573 * <dd>The operator doesn't interfere with backpressure which is determined by the current {@code Flowable}'s backpressure
9574 * behavior.</dd>
9575 * <dt><b>Scheduler:</b></dt>
9576 * <dd>{@code doFinally} does not operate by default on a particular {@link Scheduler}.</dd>
9577 * <dt><b>Operator-fusion:</b></dt>
9578 * <dd>This operator supports normal and conditional {@link Subscriber}s as well as boundary-limited
9579 * synchronous or asynchronous queue-fusion.</dd>
9580 * </dl>
9581 * <p>History: 2.0.1 - experimental
9582 * @param onFinally the action called when this {@code Flowable} terminates or gets canceled
9583 * @throws NullPointerException if {@code onFinally} is {@code null}
9584 * @return the new {@code Flowable} instance
9585 * @since 2.1
9586 */
9587 @CheckReturnValue
9588 @BackpressureSupport(BackpressureKind.PASS_THROUGH)
9589 @SchedulerSupport(SchedulerSupport.NONE)
9590 @NonNull
9591 public final Flowable<T> doFinally(@NonNull Action onFinally) {
9592 Objects.requireNonNull(onFinally, "onFinally is null");
9593 return RxJavaPlugins.onAssembly(new FlowableDoFinally<>(this, onFinally));
9594 }
9595
9596 /**
9597 * Calls the specified consumer with the current item after this item has been emitted to the downstream.
9598 * <p>Note that the {@code onAfterNext} action is shared between subscriptions and as such
9599 * should be thread-safe.
9600 * <dl>
9601 * <dt><b>Backpressure:</b></dt>
9602 * <dd>The operator doesn't interfere with backpressure which is determined by the current {@code Flowable}'s backpressure
9603 * behavior.</dd>
9604 * <dt><b>Scheduler:</b></dt>
9605 * <dd>{@code doAfterNext} does not operate by default on a particular {@link Scheduler}.</dd>
9606 * <dt><b>Operator-fusion:</b></dt>
9607 * <dd>This operator supports normal and conditional {@link Subscriber}s as well as boundary-limited
9608 * synchronous or asynchronous queue-fusion.</dd>
9609 * </dl>
9610 * <p>History: 2.0.1 - experimental
9611 * @param onAfterNext the {@link Consumer} that will be called after emitting an item from upstream to the downstream
9612 * @throws NullPointerException if {@code onAfterNext} is {@code null}
9613 * @return the new {@code Flowable} instance
9614 * @since 2.1
9615 */
9616 @CheckReturnValue
9617 @BackpressureSupport(BackpressureKind.PASS_THROUGH)
9618 @SchedulerSupport(SchedulerSupport.NONE)
9619 @NonNull
9620 public final Flowable<T> doAfterNext(@NonNull Consumer<? super T> onAfterNext) {
9621 Objects.requireNonNull(onAfterNext, "onAfterNext is null");
9622 return RxJavaPlugins.onAssembly(new FlowableDoAfterNext<>(this, onAfterNext));
9623 }
9624
9625 /**
9626 * Registers an {@link Action} to be called when this {@link Publisher} invokes either
9627 * {@link Subscriber#onComplete onComplete} or {@link Subscriber#onError onError}.
9628 * <p>
9629 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/finallyDo.v3.png" alt="">
9630 * <dl>
9631 * <dt><b>Backpressure:</b></dt>
9632 * <dd>The operator doesn't interfere with backpressure which is determined by the current {@code Flowable}'s backpressure
9633 * behavior.</dd>
9634 * <dt><b>Scheduler:</b></dt>
9635 * <dd>{@code doAfterTerminate} does not operate by default on a particular {@link Scheduler}.</dd>
9636 * </dl>
9637 *
9638 * @param onAfterTerminate
9639 * an {@code Action} to be invoked when the current {@code Flowable} finishes
9640 * @return the new {@code Flowable} instance
9641 * @throws NullPointerException if {@code onAfterTerminate} is {@code null}
9642 * @see <a href="http://reactivex.io/documentation/operators/do.html">ReactiveX operators documentation: Do</a>
9643 * @see #doOnTerminate(Action)
9644 */
9645 @CheckReturnValue
9646 @BackpressureSupport(BackpressureKind.PASS_THROUGH)
9647 @SchedulerSupport(SchedulerSupport.NONE)
9648 @NonNull
9649 public final Flowable<T> doAfterTerminate(@NonNull Action onAfterTerminate) {
9650 return doOnEach(Functions.emptyConsumer(), Functions.emptyConsumer(),
9651 Functions.EMPTY_ACTION, onAfterTerminate);
9652 }
9653
9654 /**
9655 * Calls the cancel {@link Action} if the downstream cancels the sequence.
9656 * <p>
9657 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/doOnUnsubscribe.v3.png" alt="">
9658 * <p>
9659 * The action is shared between subscriptions and thus may be called concurrently from multiple
9660 * threads; the action must be thread-safe.
9661 * <p>
9662 * If the action throws a runtime exception, that exception is rethrown by the {@code onCancel()} call,
9663 * sometimes as a {@link CompositeException} if there were multiple exceptions along the way.
9664 * <dl>
9665 * <dt><b>Backpressure:</b></dt>
9666 * <dd>{@code doOnCancel} does not interact with backpressure requests or value delivery; backpressure
9667 * behavior is preserved between its upstream and its downstream.</dd>
9668 * <dt><b>Scheduler:</b></dt>
9669 * <dd>{@code doOnCancel} does not operate by default on a particular {@link Scheduler}.</dd>
9670 * </dl>
9671 *
9672 * @param onCancel
9673 * the action that gets called when the current {@code Flowable}'s {@link Subscription} is canceled
9674 * @return the new {@code Flowable} instance
9675 * @throws NullPointerException if {@code onCancel} is {@code null}
9676 * @see <a href="http://reactivex.io/documentation/operators/do.html">ReactiveX operators documentation: Do</a>
9677 */
9678 @CheckReturnValue
9679 @BackpressureSupport(BackpressureKind.PASS_THROUGH)
9680 @SchedulerSupport(SchedulerSupport.NONE)
9681 @NonNull
9682 public final Flowable<T> doOnCancel(@NonNull Action onCancel) {
9683 return doOnLifecycle(Functions.emptyConsumer(), Functions.EMPTY_LONG_CONSUMER, onCancel);
9684 }
9685
9686 /**
9687 * Invokes an {@link Action} just before the current {@code Flowable} calls {@code onComplete}.
9688 * <p>
9689 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/doOnComplete.v3.png" alt="">
9690 * <dl>
9691 * <dt><b>Backpressure:</b></dt>
9692 * <dd>The operator doesn't interfere with backpressure which is determined by the current {@code Flowable}'s
9693 * backpressure behavior.</dd>
9694 * <dt><b>Scheduler:</b></dt>
9695 * <dd>{@code doOnComplete} does not operate by default on a particular {@link Scheduler}.</dd>
9696 * </dl>
9697 *
9698 * @param onComplete
9699 * the action to invoke when the current {@code Flowable} calls {@code onComplete}
9700 * @return the new {@code Flowable} instance
9701 * @throws NullPointerException if {@code onComplete} is {@code null}
9702 * @see <a href="http://reactivex.io/documentation/operators/do.html">ReactiveX operators documentation: Do</a>
9703 */
9704 @CheckReturnValue
9705 @BackpressureSupport(BackpressureKind.PASS_THROUGH)
9706 @SchedulerSupport(SchedulerSupport.NONE)
9707 @NonNull
9708 public final Flowable<T> doOnComplete(@NonNull Action onComplete) {
9709 return doOnEach(Functions.emptyConsumer(), Functions.emptyConsumer(),
9710 onComplete, Functions.EMPTY_ACTION);
9711 }
9712
9713 /**
9714 * Calls the appropriate onXXX consumer (shared between all subscribers) whenever a signal with the same type
9715 * passes through, before forwarding them to downstream.
9716 * <p>
9717 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/doOnEach.v3.png" alt="">
9718 * <dl>
9719 * <dt><b>Backpressure:</b></dt>
9720 * <dd>The operator doesn't interfere with backpressure which is determined by the current {@code Flowable}'s
9721 * backpressure behavior.</dd>
9722 * <dt><b>Scheduler:</b></dt>
9723 * <dd>{@code doOnEach} does not operate by default on a particular {@link Scheduler}.</dd>
9724 * </dl>
9725 *
9726 * @param onNext the {@link Consumer} to invoke when the current {@code Flowable} calls {@code onNext}
9727 * @param onError the {@code Consumer} to invoke when the current {@code Flowable} calls {@code onError}
9728 * @param onComplete the {@link Action} to invoke when the current {@code Flowable} calls {@code onComplete}
9729 * @param onAfterTerminate the {@code Action} to invoke when the current {@code Flowable} calls {@code onAfterTerminate}
9730 * @return the new {@code Flowable} instance
9731 * @throws NullPointerException if {@code onNext}, {@code onError}, {@code onComplete} or {@code onAfterTerminate} is {@code null}
9732 * @see <a href="http://reactivex.io/documentation/operators/do.html">ReactiveX operators documentation: Do</a>
9733 */
9734 @CheckReturnValue
9735 @NonNull
9736 @BackpressureSupport(BackpressureKind.PASS_THROUGH)
9737 @SchedulerSupport(SchedulerSupport.NONE)
9738 private Flowable<T> doOnEach(@NonNull Consumer<? super T> onNext, @NonNull Consumer<? super Throwable> onError,
9739 Action onComplete, Action onAfterTerminate) {
9740 Objects.requireNonNull(onNext, "onNext is null");
9741 Objects.requireNonNull(onError, "onError is null");
9742 Objects.requireNonNull(onComplete, "onComplete is null");
9743 Objects.requireNonNull(onAfterTerminate, "onAfterTerminate is null");
9744 return RxJavaPlugins.onAssembly(new FlowableDoOnEach<>(this, onNext, onError, onComplete, onAfterTerminate));
9745 }
9746
9747 /**
9748 * Invokes a {@link Consumer} with a {@link Notification} instances matching the signals emitted by the current {@code Flowable}
9749 * before they are forwarded to the downstream.
9750 * <p>
9751 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/doOnEach.v3.png" alt="">
9752 * <dl>
9753 * <dt><b>Backpressure:</b></dt>
9754 * <dd>The operator doesn't interfere with backpressure which is determined by the current {@code Flowable}'s
9755 * backpressure behavior.</dd>
9756 * <dt><b>Scheduler:</b></dt>
9757 * <dd>{@code doOnEach} does not operate by default on a particular {@link Scheduler}.</dd>
9758 * </dl>
9759 *
9760 * @param onNotification
9761 * the action to invoke for each item emitted by the current {@code Flowable}
9762 * @return the new {@code Flowable} instance
9763 * @throws NullPointerException if {@code onNotification} is {@code null}
9764 * @see <a href="http://reactivex.io/documentation/operators/do.html">ReactiveX operators documentation: Do</a>
9765 */
9766 @CheckReturnValue
9767 @NonNull
9768 @BackpressureSupport(BackpressureKind.PASS_THROUGH)
9769 @SchedulerSupport(SchedulerSupport.NONE)
9770 public final Flowable<T> doOnEach(@NonNull Consumer<@NonNull ? super Notification<T>> onNotification) {
9771 Objects.requireNonNull(onNotification, "onNotification is null");
9772 return doOnEach(
9773 Functions.notificationOnNext(onNotification),
9774 Functions.notificationOnError(onNotification),
9775 Functions.notificationOnComplete(onNotification),
9776 Functions.EMPTY_ACTION
9777 );
9778 }
9779
9780 /**
9781 * Calls the appropriate methods of the given {@link Subscriber} when the current {@code Flowable} signals events before forwarding it
9782 * to the downstream.
9783 * <p>
9784 * In case the {@code onError} of the supplied {@code Subscriber} throws, the downstream will receive a composite
9785 * exception containing the original exception and the exception thrown by {@code onError}. If either the
9786 * {@code onNext} or the {@code onComplete} method of the supplied {@code Subscriber} throws, the downstream will be
9787 * terminated and will receive this thrown exception.
9788 * <p>
9789 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/doOnEach.o.v3.png" alt="">
9790 * <dl>
9791 * <dt><b>Backpressure:</b></dt>
9792 * <dd>The operator doesn't interfere with backpressure which is determined by the current {@code Flowable}'s
9793 * backpressure behavior.</dd>
9794 * <dt><b>Scheduler:</b></dt>
9795 * <dd>{@code doOnEach} does not operate by default on a particular {@link Scheduler}.</dd>
9796 * </dl>
9797 *
9798 * @param subscriber
9799 * the {@code Subscriber} to be notified about {@code onNext}, {@code onError} and {@code onComplete} events on its
9800 * respective methods before the actual downstream {@code Subscriber} gets notified.
9801 * @return the new {@code Flowable} instance
9802 * @throws NullPointerException if {@code subscriber} is {@code null}
9803 * @see <a href="http://reactivex.io/documentation/operators/do.html">ReactiveX operators documentation: Do</a>
9804 */
9805 @CheckReturnValue
9806 @NonNull
9807 @BackpressureSupport(BackpressureKind.PASS_THROUGH)
9808 @SchedulerSupport(SchedulerSupport.NONE)
9809 public final Flowable<T> doOnEach(@NonNull Subscriber<? super T> subscriber) {
9810 Objects.requireNonNull(subscriber, "subscriber is null");
9811 return doOnEach(
9812 FlowableInternalHelper.subscriberOnNext(subscriber),
9813 FlowableInternalHelper.subscriberOnError(subscriber),
9814 FlowableInternalHelper.subscriberOnComplete(subscriber),
9815 Functions.EMPTY_ACTION);
9816 }
9817
9818 /**
9819 * Calls the given {@link Consumer} with the error {@link Throwable} if the current {@code Flowable} failed before forwarding it to
9820 * the downstream.
9821 * <p>
9822 * In case the {@code onError} action throws, the downstream will receive a composite exception containing
9823 * the original exception and the exception thrown by {@code onError}.
9824 * <p>
9825 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/doOnError.v3.png" alt="">
9826 * <dl>
9827 * <dt><b>Backpressure:</b></dt>
9828 * <dd>The operator doesn't interfere with backpressure which is determined by the current {@code Flowable}'s
9829 * backpressure behavior.</dd>
9830 * <dt><b>Scheduler:</b></dt>
9831 * <dd>{@code doOnError} does not operate by default on a particular {@link Scheduler}.</dd>
9832 * </dl>
9833 *
9834 * @param onError
9835 * the action to invoke if the current {@code Flowable} calls {@code onError}
9836 * @return the new {@code Flowable} instance
9837 * @throws NullPointerException if {@code onError} is {@code null}
9838 * @see <a href="http://reactivex.io/documentation/operators/do.html">ReactiveX operators documentation: Do</a>
9839 */
9840 @CheckReturnValue
9841 @BackpressureSupport(BackpressureKind.PASS_THROUGH)
9842 @SchedulerSupport(SchedulerSupport.NONE)
9843 @NonNull
9844 public final Flowable<T> doOnError(@NonNull Consumer<? super Throwable> onError) {
9845 return doOnEach(Functions.emptyConsumer(), onError,
9846 Functions.EMPTY_ACTION, Functions.EMPTY_ACTION);
9847 }
9848
9849 /**
9850 * Calls the appropriate {@code onXXX} method (shared between all {@link Subscriber}s) for the lifecycle events of
9851 * the sequence (subscription, cancellation, requesting).
9852 * <p>
9853 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/doOnNext.v3.png" alt="">
9854 * <dl>
9855 * <dt><b>Backpressure:</b></dt>
9856 * <dd>The operator doesn't interfere with backpressure which is determined by the current {@code Flowable}'s
9857 * backpressure behavior.</dd>
9858 * <dt><b>Scheduler:</b></dt>
9859 * <dd>{@code doOnLifecycle} does not operate by default on a particular {@link Scheduler}.</dd>
9860 * </dl>
9861 *
9862 * @param onSubscribe
9863 * a {@link Consumer} called with the {@link Subscription} sent via {@link Subscriber#onSubscribe(Subscription)}
9864 * @param onRequest
9865 * a {@link LongConsumer} called with the request amount sent via {@link Subscription#request(long)}
9866 * @param onCancel
9867 * called when the downstream cancels the {@code Subscription} via {@link Subscription#cancel()}
9868 * @return the new {@code Flowable} instance
9869 * @throws NullPointerException if {@code onSubscribe}, {@code onRequest} or {@code onCancel} is {@code null}
9870 * @see <a href="http://reactivex.io/documentation/operators/do.html">ReactiveX operators documentation: Do</a>
9871 */
9872 @CheckReturnValue
9873 @NonNull
9874 @BackpressureSupport(BackpressureKind.PASS_THROUGH)
9875 @SchedulerSupport(SchedulerSupport.NONE)
9876 public final Flowable<T> doOnLifecycle(@NonNull Consumer<? super Subscription> onSubscribe,
9877 @NonNull LongConsumer onRequest, @NonNull Action onCancel) {
9878 Objects.requireNonNull(onSubscribe, "onSubscribe is null");
9879 Objects.requireNonNull(onRequest, "onRequest is null");
9880 Objects.requireNonNull(onCancel, "onCancel is null");
9881 return RxJavaPlugins.onAssembly(new FlowableDoOnLifecycle<>(this, onSubscribe, onRequest, onCancel));
9882 }
9883
9884 /**
9885 * Calls the given {@link Consumer} with the value emitted by the current {@code Flowable} before forwarding it to the downstream.
9886 * <p>
9887 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/doOnNext.v3.png" alt="">
9888 * <dl>
9889 * <dt><b>Backpressure:</b></dt>
9890 * <dd>The operator doesn't interfere with backpressure which is determined by the current {@code Flowable}'s
9891 * backpressure behavior.</dd>
9892 * <dt><b>Scheduler:</b></dt>
9893 * <dd>{@code doOnNext} does not operate by default on a particular {@link Scheduler}.</dd>
9894 * </dl>
9895 *
9896 * @param onNext
9897 * the action to invoke when the current {@code Flowable} calls {@code onNext}
9898 * @return the new {@code Flowable} instance
9899 * @throws NullPointerException if {@code onNext} is {@code null}
9900 * @see <a href="http://reactivex.io/documentation/operators/do.html">ReactiveX operators documentation: Do</a>
9901 * @see #doAfterNext(Consumer)
9902 */
9903 @CheckReturnValue
9904 @BackpressureSupport(BackpressureKind.PASS_THROUGH)
9905 @SchedulerSupport(SchedulerSupport.NONE)
9906 @NonNull
9907 public final Flowable<T> doOnNext(@NonNull Consumer<? super T> onNext) {
9908 return doOnEach(onNext, Functions.emptyConsumer(),
9909 Functions.EMPTY_ACTION, Functions.EMPTY_ACTION);
9910 }
9911
9912 /**
9913 * Calls the given {@link LongConsumer} with the request amount from the downstream before forwarding it
9914 * to the current {@code Flowable}.
9915 * <p>
9916 * <b>Note:</b> This operator is for tracing the internal behavior of back-pressure request
9917 * patterns and generally intended for debugging use.
9918 * <dl>
9919 * <dt><b>Backpressure:</b></dt>
9920 * <dd>The operator doesn't interfere with backpressure which is determined by the current {@code Flowable}'s
9921 * backpressure behavior.</dd>
9922 * <dt><b>Scheduler:</b></dt>
9923 * <dd>{@code doOnRequest} does not operate by default on a particular {@link Scheduler}.</dd>
9924 * </dl>
9925 *
9926 * @param onRequest
9927 * the action that gets called when a {@link Subscriber} requests items from the current
9928 * {@code Flowable}
9929 * @return the new {@code Flowable} instance
9930 * @throws NullPointerException if {@code onRequest} is {@code null}
9931 * @see <a href="http://reactivex.io/documentation/operators/do.html">ReactiveX operators
9932 * documentation: Do</a>
9933 * @since 2.0
9934 */
9935 @CheckReturnValue
9936 @BackpressureSupport(BackpressureKind.PASS_THROUGH)
9937 @SchedulerSupport(SchedulerSupport.NONE)
9938 @NonNull
9939 public final Flowable<T> doOnRequest(@NonNull LongConsumer onRequest) {
9940 return doOnLifecycle(Functions.emptyConsumer(), onRequest, Functions.EMPTY_ACTION);
9941 }
9942
9943 /**
9944 * Calls the given {@link Consumer} with the {@link Subscription} provided by the current {@code Flowable} upon
9945 * subscription from the downstream before forwarding it to the subscriber's
9946 * {@link Subscriber#onSubscribe(Subscription) onSubscribe} method.
9947 * <p>
9948 * <img width="640" height="390" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/doOnSubscribe.v3.png" alt="">
9949 * <dl>
9950 * <dt><b>Backpressure:</b></dt>
9951 * <dd>The operator doesn't interfere with backpressure which is determined by the current {@code Flowable}'s
9952 * backpressure behavior.</dd>
9953 * <dt><b>Scheduler:</b></dt>
9954 * <dd>{@code doOnSubscribe} does not operate by default on a particular {@link Scheduler}.</dd>
9955 * </dl>
9956 *
9957 * @param onSubscribe
9958 * the {@code Consumer} that gets called when a {@link Subscriber} subscribes to the current {@code Flowable}
9959 * @return the new {@code Flowable} instance
9960 * @throws NullPointerException if {@code onSubscribe} is {@code null}
9961 * @see <a href="http://reactivex.io/documentation/operators/do.html">ReactiveX operators documentation: Do</a>
9962 */
9963 @CheckReturnValue
9964 @BackpressureSupport(BackpressureKind.PASS_THROUGH)
9965 @SchedulerSupport(SchedulerSupport.NONE)
9966 @NonNull
9967 public final Flowable<T> doOnSubscribe(@NonNull Consumer<? super Subscription> onSubscribe) {
9968 return doOnLifecycle(onSubscribe, Functions.EMPTY_LONG_CONSUMER, Functions.EMPTY_ACTION);
9969 }
9970
9971 /**
9972 * Calls the given {@link Action} when the current {@code Flowable} completes normally or with an error before those signals
9973 * are forwarded to the downstream.
9974 * <p>
9975 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/doOnTerminate.v3.png" alt="">
9976 * <p>
9977 * This differs from {@code doAfterTerminate} in that this happens <em>before</em> the {@code onComplete} or
9978 * {@code onError} notification.
9979 * <dl>
9980 * <dt><b>Backpressure:</b></dt>
9981 * <dd>The operator doesn't interfere with backpressure which is determined by the current {@code Flowable}'s
9982 * backpressure behavior.</dd>
9983 * <dt><b>Scheduler:</b></dt>
9984 * <dd>{@code doOnTerminate} does not operate by default on a particular {@link Scheduler}.</dd>
9985 * </dl>
9986 *
9987 * @param onTerminate
9988 * the action to invoke when the current {@code Flowable} calls {@code onComplete} or {@code onError}
9989 * @return the new {@code Flowable} instance
9990 * @throws NullPointerException if {@code onTerminate} is {@code null}
9991 * @see <a href="http://reactivex.io/documentation/operators/do.html">ReactiveX operators documentation: Do</a>
9992 * @see #doAfterTerminate(Action)
9993 */
9994 @CheckReturnValue
9995 @BackpressureSupport(BackpressureKind.PASS_THROUGH)
9996 @SchedulerSupport(SchedulerSupport.NONE)
9997 @NonNull
9998 public final Flowable<T> doOnTerminate(@NonNull Action onTerminate) {
9999 return doOnEach(Functions.emptyConsumer(), Functions.actionConsumer(onTerminate),
10000 onTerminate, Functions.EMPTY_ACTION);
10001 }
10002
10003 /**
10004 * Returns a {@link Maybe} that emits the single item at a specified index in a sequence of emissions from
10005 * this {@code Flowable} or completes if this {@code Flowable} sequence has fewer elements than index.
10006 * <p>
10007 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/elementAt.v3.png" alt="">
10008 * <dl>
10009 * <dt><b>Backpressure:</b></dt>
10010 * <dd>The operator honors backpressure from downstream and consumes the current {@code Flowable} in a bounded manner.</dd>
10011 * <dt><b>Scheduler:</b></dt>
10012 * <dd>{@code elementAt} does not operate by default on a particular {@link Scheduler}.</dd>
10013 * </dl>
10014 *
10015 * @param index
10016 * the zero-based index of the item to retrieve
10017 * @return the new {@code Maybe} instance
10018 * @throws IndexOutOfBoundsException if {@code index} is negative
10019 * @see <a href="http://reactivex.io/documentation/operators/elementat.html">ReactiveX operators documentation: ElementAt</a>
10020 */
10021 @CheckReturnValue
10022 @BackpressureSupport(BackpressureKind.FULL)
10023 @SchedulerSupport(SchedulerSupport.NONE)
10024 @NonNull
10025 public final Maybe<T> elementAt(long index) {
10026 if (index < 0) {
10027 throw new IndexOutOfBoundsException("index >= 0 required but it was " + index);
10028 }
10029 return RxJavaPlugins.onAssembly(new FlowableElementAtMaybe<>(this, index));
10030 }
10031
10032 /**
10033 * Returns a {@link Single} that emits the item found at a specified index in a sequence of emissions from
10034 * this {@code Flowable}, or a default item if that index is out of range.
10035 * <p>
10036 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/elementAtOrDefault.v3.png" alt="">
10037 * <dl>
10038 * <dt><b>Backpressure:</b></dt>
10039 * <dd>The operator honors backpressure from downstream and consumes the current {@code Flowable} in a bounded manner.</dd>
10040 * <dt><b>Scheduler:</b></dt>
10041 * <dd>{@code elementAt} does not operate by default on a particular {@link Scheduler}.</dd>
10042 * </dl>
10043 *
10044 * @param index
10045 * the zero-based index of the item to retrieve
10046 * @param defaultItem
10047 * the default item
10048 * @return the new {@code Single} instance
10049 * @throws NullPointerException if {@code defaultItem} is {@code null}
10050 * @throws IndexOutOfBoundsException
10051 * if {@code index} is negative
10052 * @see <a href="http://reactivex.io/documentation/operators/elementat.html">ReactiveX operators documentation: ElementAt</a>
10053 */
10054 @CheckReturnValue
10055 @NonNull
10056 @BackpressureSupport(BackpressureKind.FULL)
10057 @SchedulerSupport(SchedulerSupport.NONE)
10058 public final Single<T> elementAt(long index, @NonNull T defaultItem) {
10059 if (index < 0) {
10060 throw new IndexOutOfBoundsException("index >= 0 required but it was " + index);
10061 }
10062 Objects.requireNonNull(defaultItem, "defaultItem is null");
10063 return RxJavaPlugins.onAssembly(new FlowableElementAtSingle<>(this, index, defaultItem));
10064 }
10065
10066 /**
10067 * Returns a {@link Single} that emits the item found at a specified index in a sequence of emissions from
10068 * this {@code Flowable} or signals a {@link NoSuchElementException} if this {@code Flowable} has fewer elements than index.
10069 * <p>
10070 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/elementAtOrDefault.v3.png" alt="">
10071 * <dl>
10072 * <dt><b>Backpressure:</b></dt>
10073 * <dd>The operator honors backpressure from downstream and consumes the current {@code Flowable} in a bounded manner.</dd>
10074 * <dt><b>Scheduler:</b></dt>
10075 * <dd>{@code elementAtOrError} does not operate by default on a particular {@link Scheduler}.</dd>
10076 * </dl>
10077 *
10078 * @param index
10079 * the zero-based index of the item to retrieve
10080 * @return the new {@code Single} instance
10081 * @throws IndexOutOfBoundsException
10082 * if {@code index} is less than 0
10083 * @see <a href="http://reactivex.io/documentation/operators/elementat.html">ReactiveX operators documentation: ElementAt</a>
10084 */
10085 @CheckReturnValue
10086 @BackpressureSupport(BackpressureKind.FULL)
10087 @SchedulerSupport(SchedulerSupport.NONE)
10088 @NonNull
10089 public final Single<T> elementAtOrError(long index) {
10090 if (index < 0) {
10091 throw new IndexOutOfBoundsException("index >= 0 required but it was " + index);
10092 }
10093 return RxJavaPlugins.onAssembly(new FlowableElementAtSingle<>(this, index, null));
10094 }
10095
10096 /**
10097 * Filters items emitted by the current {@code Flowable} by only emitting those that satisfy a specified predicate.
10098 * <p>
10099 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/filter.v3.png" alt="">
10100 * <dl>
10101 * <dt><b>Backpressure:</b></dt>
10102 * <dd>The operator doesn't interfere with backpressure which is determined by the current {@code Flowable}'s backpressure
10103 * behavior.</dd>
10104 * <dt><b>Scheduler:</b></dt>
10105 * <dd>{@code filter} does not operate by default on a particular {@link Scheduler}.</dd>
10106 * </dl>
10107 *
10108 * @param predicate
10109 * a function that evaluates each item emitted by the current {@code Flowable}, returning {@code true}
10110 * if it passes the filter
10111 * @return the new {@code Flowable} instance
10112 * @throws NullPointerException if {@code predicate} is {@code null}
10113 * @see <a href="http://reactivex.io/documentation/operators/filter.html">ReactiveX operators documentation: Filter</a>
10114 */
10115 @CheckReturnValue
10116 @NonNull
10117 @BackpressureSupport(BackpressureKind.PASS_THROUGH)
10118 @SchedulerSupport(SchedulerSupport.NONE)
10119 public final Flowable<T> filter(@NonNull Predicate<? super T> predicate) {
10120 Objects.requireNonNull(predicate, "predicate is null");
10121 return RxJavaPlugins.onAssembly(new FlowableFilter<>(this, predicate));
10122 }
10123
10124 /**
10125 * Returns a {@link Maybe} that emits only the very first item emitted by this {@code Flowable} or
10126 * completes if this {@code Flowable} is empty.
10127 * <p>
10128 * <img width="640" height="286" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/firstElement.m.png" alt="">
10129 * <dl>
10130 * <dt><b>Backpressure:</b></dt>
10131 * <dd>The operator honors backpressure from downstream and consumes the current {@code Flowable} in a bounded manner.</dd>
10132 * <dt><b>Scheduler:</b></dt>
10133 * <dd>{@code firstElement} does not operate by default on a particular {@link Scheduler}.</dd>
10134 * </dl>
10135 *
10136 * @return the new {@code Maybe} instance
10137 * @see <a href="http://reactivex.io/documentation/operators/first.html">ReactiveX operators documentation: First</a>
10138 */
10139 @CheckReturnValue
10140 @BackpressureSupport(BackpressureKind.FULL)
10141 @SchedulerSupport(SchedulerSupport.NONE)
10142 @NonNull
10143 public final Maybe<T> firstElement() {
10144 return elementAt(0);
10145 }
10146
10147 /**
10148 * Returns a {@link Single} that emits only the very first item emitted by this {@code Flowable}, or a default
10149 * item if this {@code Flowable} completes without emitting anything.
10150 * <p>
10151 * <img width="640" height="298" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Flowable.first.s.png" alt="">
10152 * <dl>
10153 * <dt><b>Backpressure:</b></dt>
10154 * <dd>The operator honors backpressure from downstream and consumes the current {@code Flowable} in a bounded manner.</dd>
10155 * <dt><b>Scheduler:</b></dt>
10156 * <dd>{@code first} does not operate by default on a particular {@link Scheduler}.</dd>
10157 * </dl>
10158 *
10159 * @param defaultItem
10160 * the default item to emit if the current {@code Flowable} doesn't emit anything
10161 * @return the new {@code Single} instance
10162 * @throws NullPointerException if {@code defaultItem} is {@code null}
10163 * @see <a href="http://reactivex.io/documentation/operators/first.html">ReactiveX operators documentation: First</a>
10164 */
10165 @CheckReturnValue
10166 @BackpressureSupport(BackpressureKind.FULL)
10167 @SchedulerSupport(SchedulerSupport.NONE)
10168 @NonNull
10169 public final Single<T> first(@NonNull T defaultItem) {
10170 return elementAt(0, defaultItem);
10171 }
10172
10173 /**
10174 * Returns a {@link Single} that emits only the very first item emitted by this {@code Flowable} or
10175 * signals a {@link NoSuchElementException} if this {@code Flowable} is empty.
10176 * <p>
10177 * <img width="640" height="237" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/firstOrError.png" alt="">
10178 * <dl>
10179 * <dt><b>Backpressure:</b></dt>
10180 * <dd>The operator honors backpressure from downstream and consumes the current {@code Flowable} in a bounded manner.</dd>
10181 * <dt><b>Scheduler:</b></dt>
10182 * <dd>{@code firstOrError} does not operate by default on a particular {@link Scheduler}.</dd>
10183 * </dl>
10184 *
10185 * @return the new {@code Single} instance
10186 * @see <a href="http://reactivex.io/documentation/operators/first.html">ReactiveX operators documentation: First</a>
10187 */
10188 @CheckReturnValue
10189 @BackpressureSupport(BackpressureKind.FULL) // take may trigger UNBOUNDED_IN
10190 @SchedulerSupport(SchedulerSupport.NONE)
10191 @NonNull
10192 public final Single<T> firstOrError() {
10193 return elementAtOrError(0);
10194 }
10195
10196 /**
10197 * Returns a {@code Flowable} that emits items based on applying a function that you supply to each item emitted
10198 * by the current {@code Flowable}, where that function returns a {@link Publisher}, and then merging those resulting
10199 * {@code Publisher}s and emitting the results of this merger.
10200 * <p>
10201 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/flatMap.v3.png" alt="">
10202 * <dl>
10203 * <dt><b>Backpressure:</b></dt>
10204 * <dd>The operator honors backpressure from downstream. The upstream {@code Flowable} is consumed
10205 * in a bounded manner (up to {@link #bufferSize()} outstanding request amount for items).
10206 * The inner {@code Publisher}s are expected to honor backpressure; if violated,
10207 * the operator <em>may</em> signal {@link MissingBackpressureException}.</dd>
10208 * <dt><b>Scheduler:</b></dt>
10209 * <dd>{@code flatMap} does not operate by default on a particular {@link Scheduler}.</dd>
10210 * </dl>
10211 *
10212 * @param <R> the value type of the inner {@code Publisher}s and the output type
10213 * @param mapper
10214 * a function that, when applied to an item emitted by the current {@code Flowable}, returns a
10215 * {@code Publisher}
10216 * @return the new {@code Flowable} instance
10217 * @throws NullPointerException if {@code mapper} is {@code null}
10218 * @see <a href="http://reactivex.io/documentation/operators/flatmap.html">ReactiveX operators documentation: FlatMap</a>
10219 */
10220 @CheckReturnValue
10221 @BackpressureSupport(BackpressureKind.FULL)
10222 @SchedulerSupport(SchedulerSupport.NONE)
10223 @NonNull
10224 public final <@NonNull R> Flowable<R> flatMap(@NonNull Function<? super T, @NonNull ? extends Publisher<? extends R>> mapper) {
10225 return flatMap(mapper, false, bufferSize(), bufferSize());
10226 }
10227
10228 /**
10229 * Returns a {@code Flowable} that emits items based on applying a function that you supply to each item emitted
10230 * by the current {@code Flowable}, where that function returns a {@link Publisher}, and then merging those resulting
10231 * {@code Publisher}s and emitting the results of this merger.
10232 * <p>
10233 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/flatMap.v3.png" alt="">
10234 * <dl>
10235 * <dt><b>Backpressure:</b></dt>
10236 * <dd>The operator honors backpressure from downstream. The upstream {@code Flowable} is consumed
10237 * in a bounded manner (up to {@link #bufferSize()} outstanding request amount for items).
10238 * The inner {@code Publisher}s are expected to honor backpressure; if violated,
10239 * the operator <em>may</em> signal {@link MissingBackpressureException}.</dd>
10240 * <dt><b>Scheduler:</b></dt>
10241 * <dd>{@code flatMap} does not operate by default on a particular {@link Scheduler}.</dd>
10242 * </dl>
10243 *
10244 * @param <R> the value type of the inner {@code Publisher}s and the output type
10245 * @param mapper
10246 * a function that, when applied to an item emitted by the current {@code Flowable}, returns a
10247 * {@code Publisher}
10248 * @param delayErrors
10249 * if {@code true}, exceptions from the current {@code Flowable} and all inner {@code Publisher}s are delayed until all of them terminate
10250 * if {@code false}, the first one signaling an exception will terminate the whole sequence immediately
10251 * @return the new {@code Flowable} instance
10252 * @throws NullPointerException if {@code mapper} is {@code null}
10253 * @see <a href="http://reactivex.io/documentation/operators/flatmap.html">ReactiveX operators documentation: FlatMap</a>
10254 */
10255 @CheckReturnValue
10256 @BackpressureSupport(BackpressureKind.FULL)
10257 @SchedulerSupport(SchedulerSupport.NONE)
10258 @NonNull
10259 public final <@NonNull R> Flowable<R> flatMap(@NonNull Function<? super T, @NonNull ? extends Publisher<? extends R>> mapper, boolean delayErrors) {
10260 return flatMap(mapper, delayErrors, bufferSize(), bufferSize());
10261 }
10262
10263 /**
10264 * Returns a {@code Flowable} that emits items based on applying a function that you supply to each item emitted
10265 * by the current {@code Flowable}, where that function returns a {@link Publisher}, and then merging those resulting
10266 * {@code Publisher}s and emitting the results of this merger, while limiting the maximum number of concurrent
10267 * subscriptions to these {@code Publisher}s.
10268 * <!-- <p> -->
10269 * <!-- <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/flatMap.v3.png" alt=""> -->
10270 * <dl>
10271 * <dt><b>Backpressure:</b></dt>
10272 * <dd>The operator honors backpressure from downstream. The upstream {@code Flowable} is consumed
10273 * in a bounded manner (up to {@code maxConcurrency} outstanding request amount for items).
10274 * The inner {@code Publisher}s are expected to honor backpressure; if violated,
10275 * the operator <em>may</em> signal {@link MissingBackpressureException}.</dd>
10276 * <dt><b>Scheduler:</b></dt>
10277 * <dd>{@code flatMap} does not operate by default on a particular {@link Scheduler}.</dd>
10278 * </dl>
10279 *
10280 * @param <R> the value type of the inner {@code Publisher}s and the output type
10281 * @param mapper
10282 * a function that, when applied to an item emitted by the current {@code Flowable}, returns a
10283 * {@code Publisher}
10284 * @param maxConcurrency
10285 * the maximum number of {@code Publisher}s that may be subscribed to concurrently
10286 * @return the new {@code Flowable} instance
10287 * @throws NullPointerException if {@code mapper} is {@code null}
10288 * @throws IllegalArgumentException if {@code maxConcurrency} is non-positive
10289 * @see <a href="http://reactivex.io/documentation/operators/flatmap.html">ReactiveX operators documentation: FlatMap</a>
10290 * @since 2.0
10291 */
10292 @CheckReturnValue
10293 @BackpressureSupport(BackpressureKind.FULL)
10294 @SchedulerSupport(SchedulerSupport.NONE)
10295 @NonNull
10296 public final <@NonNull R> Flowable<R> flatMap(@NonNull Function<? super T, @NonNull ? extends Publisher<? extends R>> mapper, int maxConcurrency) {
10297 return flatMap(mapper, false, maxConcurrency, bufferSize());
10298 }
10299
10300 /**
10301 * Returns a {@code Flowable} that emits items based on applying a function that you supply to each item emitted
10302 * by the current {@code Flowable}, where that function returns a {@link Publisher}, and then merging those resulting
10303 * {@code Publisher}s and emitting the results of this merger, while limiting the maximum number of concurrent
10304 * subscriptions to these {@code Publisher}s.
10305 * <!-- <p> -->
10306 * <!-- <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/flatMap.v3.png" alt=""> -->
10307 * <dl>
10308 * <dt><b>Backpressure:</b></dt>
10309 * <dd>The operator honors backpressure from downstream. The upstream {@code Flowable} is consumed
10310 * in a bounded manner (up to {@code maxConcurrency} outstanding request amount for items).
10311 * The inner {@code Publisher}s are expected to honor backpressure; if violated,
10312 * the operator <em>may</em> signal {@link MissingBackpressureException}.</dd>
10313 * <dt><b>Scheduler:</b></dt>
10314 * <dd>{@code flatMap} does not operate by default on a particular {@link Scheduler}.</dd>
10315 * </dl>
10316 *
10317 * @param <R> the value type of the inner {@code Publisher}s and the output type
10318 * @param mapper
10319 * a function that, when applied to an item emitted by the current {@code Flowable}, returns a
10320 * {@code Publisher}
10321 * @param maxConcurrency
10322 * the maximum number of {@code Publisher}s that may be subscribed to concurrently
10323 * @param delayErrors
10324 * if {@code true}, exceptions from the current {@code Flowable} and all inner {@code Publisher}s are delayed until all of them terminate
10325 * if {@code false}, the first one signaling an exception will terminate the whole sequence immediately
10326 * @return the new {@code Flowable} instance
10327 * @throws NullPointerException if {@code mapper} is {@code null}
10328 * @throws IllegalArgumentException if {@code maxConcurrency} is non-positive
10329 * @see <a href="http://reactivex.io/documentation/operators/flatmap.html">ReactiveX operators documentation: FlatMap</a>
10330 * @since 2.0
10331 */
10332 @CheckReturnValue
10333 @BackpressureSupport(BackpressureKind.FULL)
10334 @SchedulerSupport(SchedulerSupport.NONE)
10335 @NonNull
10336 public final <@NonNull R> Flowable<R> flatMap(@NonNull Function<? super T, @NonNull ? extends Publisher<? extends R>> mapper, boolean delayErrors, int maxConcurrency) {
10337 return flatMap(mapper, delayErrors, maxConcurrency, bufferSize());
10338 }
10339
10340 /**
10341 * Returns a {@code Flowable} that emits items based on applying a function that you supply to each item emitted
10342 * by the current {@code Flowable}, where that function returns a {@link Publisher}, and then merging those resulting
10343 * {@code Publisher}s and emitting the results of this merger, while limiting the maximum number of concurrent
10344 * subscriptions to these {@code Publisher}s.
10345 * <!-- <p> -->
10346 * <!-- <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/flatMap.v3.png" alt=""> -->
10347 * <dl>
10348 * <dt><b>Backpressure:</b></dt>
10349 * <dd>The operator honors backpressure from downstream. The upstream {@code Flowable} is consumed
10350 * in a bounded manner (up to {@code maxConcurrency} outstanding request amount for items).
10351 * The inner {@code Publisher}s are expected to honor backpressure; if violated,
10352 * the operator <em>may</em> signal {@link MissingBackpressureException}.</dd>
10353 * <dt><b>Scheduler:</b></dt>
10354 * <dd>{@code flatMap} does not operate by default on a particular {@link Scheduler}.</dd>
10355 * </dl>
10356 *
10357 * @param <R> the value type of the inner {@code Publisher}s and the output type
10358 * @param mapper
10359 * a function that, when applied to an item emitted by the current {@code Flowable}, returns a
10360 * {@code Publisher}
10361 * @param maxConcurrency
10362 * the maximum number of {@code Publisher}s that may be subscribed to concurrently
10363 * @param delayErrors
10364 * if {@code true}, exceptions from the current {@code Flowable} and all inner {@code Publisher}s are delayed until all of them terminate
10365 * if {@code false}, the first one signaling an exception will terminate the whole sequence immediately
10366 * @param bufferSize
10367 * the number of elements to prefetch from each inner {@code Publisher}
10368 * @return the new {@code Flowable} instance
10369 * @throws NullPointerException if {@code mapper} is {@code null}
10370 * @throws IllegalArgumentException if {@code maxConcurrency} or {@code bufferSize} is non-positive
10371 * @see <a href="http://reactivex.io/documentation/operators/flatmap.html">ReactiveX operators documentation: FlatMap</a>
10372 * @since 2.0
10373 */
10374 @CheckReturnValue
10375 @NonNull
10376 @BackpressureSupport(BackpressureKind.FULL)
10377 @SchedulerSupport(SchedulerSupport.NONE)
10378 public final <@NonNull R> Flowable<R> flatMap(@NonNull Function<? super T, @NonNull ? extends Publisher<? extends R>> mapper,
10379 boolean delayErrors, int maxConcurrency, int bufferSize) {
10380 Objects.requireNonNull(mapper, "mapper is null");
10381 ObjectHelper.verifyPositive(maxConcurrency, "maxConcurrency");
10382 ObjectHelper.verifyPositive(bufferSize, "bufferSize");
10383 if (this instanceof ScalarSupplier) {
10384 @SuppressWarnings("unchecked")
10385 T v = ((ScalarSupplier<T>)this).get();
10386 if (v == null) {
10387 return empty();
10388 }
10389 return FlowableScalarXMap.scalarXMap(v, mapper);
10390 }
10391 return RxJavaPlugins.onAssembly(new FlowableFlatMap<>(this, mapper, delayErrors, maxConcurrency, bufferSize));
10392 }
10393
10394 /**
10395 * Returns a {@code Flowable} that applies a function to each item emitted or notification raised by the current
10396 * {@code Flowable} and then flattens the {@link Publisher}s returned from these functions and emits the resulting items.
10397 * <p>
10398 * <img width="640" height="410" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/mergeMap.nce.v3.png" alt="">
10399 * <dl>
10400 * <dt><b>Backpressure:</b></dt>
10401 * <dd>The operator honors backpressure from downstream. The upstream {@code Flowable} is consumed
10402 * in a bounded manner (up to {@link #bufferSize()} outstanding request amount for items).
10403 * The inner {@code Publisher}s are expected to honor backpressure; if violated,
10404 * the operator <em>may</em> signal {@link MissingBackpressureException}.</dd>
10405 * <dt><b>Scheduler:</b></dt>
10406 * <dd>{@code flatMap} does not operate by default on a particular {@link Scheduler}.</dd>
10407 * </dl>
10408 *
10409 * @param <R>
10410 * the result type
10411 * @param onNextMapper
10412 * a function that returns a {@code Publisher} to merge for each item emitted by the current {@code Flowable}
10413 * @param onErrorMapper
10414 * a function that returns a {@code Publisher} to merge for an {@code onError} notification from the current
10415 * {@code Flowable}
10416 * @param onCompleteSupplier
10417 * a function that returns a {@code Publisher} to merge for an {@code onComplete} notification from the current
10418 * {@code Flowable}
10419 * @return the new {@code Flowable} instance
10420 * @throws NullPointerException if {@code onNextMapper}, {@code onErrorMapper} or {@code onCompleteSupplier} is {@code null}
10421 * @see <a href="http://reactivex.io/documentation/operators/flatmap.html">ReactiveX operators documentation: FlatMap</a>
10422 */
10423 @CheckReturnValue
10424 @NonNull
10425 @BackpressureSupport(BackpressureKind.FULL)
10426 @SchedulerSupport(SchedulerSupport.NONE)
10427 public final <@NonNull R> Flowable<R> flatMap(
10428 @NonNull Function<? super T, @NonNull ? extends Publisher<? extends R>> onNextMapper,
10429 @NonNull Function<? super Throwable, @NonNull ? extends Publisher<? extends R>> onErrorMapper,
10430 @NonNull Supplier<? extends Publisher<? extends R>> onCompleteSupplier) {
10431 Objects.requireNonNull(onNextMapper, "onNextMapper is null");
10432 Objects.requireNonNull(onErrorMapper, "onErrorMapper is null");
10433 Objects.requireNonNull(onCompleteSupplier, "onCompleteSupplier is null");
10434 return merge(new FlowableMapNotification<>(this, onNextMapper, onErrorMapper, onCompleteSupplier));
10435 }
10436
10437 /**
10438 * Returns a {@code Flowable} that applies a function to each item emitted or notification raised by the current
10439 * {@code Flowable} and then flattens the {@link Publisher}s returned from these functions and emits the resulting items,
10440 * while limiting the maximum number of concurrent subscriptions to these {@code Publisher}s.
10441 * <!-- <p> -->
10442 * <!-- <img width="640" height="410" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/mergeMap.nce.v3.png" alt=""> -->
10443 * <dl>
10444 * <dt><b>Backpressure:</b></dt>
10445 * <dd>The operator honors backpressure from downstream. The upstream {@code Flowable} is consumed
10446 * in a bounded manner (up to {@code maxConcurrency} outstanding request amount for items).
10447 * The inner {@code Publisher}s are expected to honor backpressure; if violated,
10448 * the operator <em>may</em> signal {@link MissingBackpressureException}.</dd>
10449 * <dt><b>Scheduler:</b></dt>
10450 * <dd>{@code flatMap} does not operate by default on a particular {@link Scheduler}.</dd>
10451 * </dl>
10452 *
10453 * @param <R>
10454 * the result type
10455 * @param onNextMapper
10456 * a function that returns a {@code Publisher} to merge for each item emitted by the current {@code Flowable}
10457 * @param onErrorMapper
10458 * a function that returns a {@code Publisher} to merge for an {@code onError} notification from the current
10459 * {@code Flowable}
10460 * @param onCompleteSupplier
10461 * a function that returns a {@code Publisher} to merge for an {@code onComplete} notification from the current
10462 * {@code Flowable}
10463 * @param maxConcurrency
10464 * the maximum number of {@code Publisher}s that may be subscribed to concurrently
10465 * @return the new {@code Flowable} instance
10466 * @throws NullPointerException if {@code onNextMapper}, {@code onErrorMapper} or {@code onCompleteSupplier} is {@code null}
10467 * @throws IllegalArgumentException if {@code maxConcurrency} is non-positive
10468 * @see <a href="http://reactivex.io/documentation/operators/flatmap.html">ReactiveX operators documentation: FlatMap</a>
10469 * @since 2.0
10470 */
10471 @CheckReturnValue
10472 @NonNull
10473 @BackpressureSupport(BackpressureKind.FULL)
10474 @SchedulerSupport(SchedulerSupport.NONE)
10475 public final <@NonNull R> Flowable<R> flatMap(
10476 @NonNull Function<? super T, @NonNull ? extends Publisher<? extends R>> onNextMapper,
10477 @NonNull Function<Throwable, @NonNull ? extends Publisher<? extends R>> onErrorMapper,
10478 @NonNull Supplier<? extends Publisher<? extends R>> onCompleteSupplier,
10479 int maxConcurrency) {
10480 Objects.requireNonNull(onNextMapper, "onNextMapper is null");
10481 Objects.requireNonNull(onErrorMapper, "onErrorMapper is null");
10482 Objects.requireNonNull(onCompleteSupplier, "onCompleteSupplier is null");
10483 return merge(new FlowableMapNotification<>(
10484 this, onNextMapper, onErrorMapper, onCompleteSupplier), maxConcurrency);
10485 }
10486
10487 /**
10488 * Returns a {@code Flowable} that emits the results of a specified function to the pair of values emitted by the
10489 * current {@code Flowable} and a specified collection {@link Publisher}.
10490 * <p>
10491 * <img width="640" height="390" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/mergeMap.r.v3.png" alt="">
10492 * <dl>
10493 * <dt><b>Backpressure:</b></dt>
10494 * <dd>The operator honors backpressure from downstream. The upstream {@code Flowable} is consumed
10495 * in a bounded manner (up to {@code maxConcurrency} outstanding request amount for items).
10496 * The inner {@code Publisher}s are expected to honor backpressure; if violated,
10497 * the operator <em>may</em> signal {@link MissingBackpressureException}.</dd>
10498 * <dt><b>Scheduler:</b></dt>
10499 * <dd>{@code flatMap} does not operate by default on a particular {@link Scheduler}.</dd>
10500 * </dl>
10501 *
10502 * @param <U>
10503 * the type of items emitted by the inner {@code Publisher}s
10504 * @param <R>
10505 * the type of items emitted by the combiner function
10506 * @param mapper
10507 * a function that returns a {@code Publisher} for each item emitted by the current {@code Flowable}
10508 * @param combiner
10509 * a function that combines one item emitted by each of the source and collection {@code Publisher}s and
10510 * returns an item to be emitted by the resulting {@code Flowable}
10511 * @return the new {@code Flowable} instance
10512 * @throws NullPointerException if {@code mapper} or {@code combiner} is {@code null}
10513 * @see <a href="http://reactivex.io/documentation/operators/flatmap.html">ReactiveX operators documentation: FlatMap</a>
10514 */
10515 @CheckReturnValue
10516 @BackpressureSupport(BackpressureKind.FULL)
10517 @SchedulerSupport(SchedulerSupport.NONE)
10518 @NonNull
10519 public final <@NonNull U, @NonNull R> Flowable<R> flatMap(@NonNull Function<? super T, @NonNull ? extends Publisher<? extends U>> mapper,
10520 @NonNull BiFunction<? super T, ? super U, ? extends R> combiner) {
10521 return flatMap(mapper, combiner, false, bufferSize(), bufferSize());
10522 }
10523
10524 /**
10525 * Returns a {@code Flowable} that emits the results of a specified function to the pair of values emitted by the
10526 * current {@code Flowable} and a specified inner {@link Publisher}.
10527 * <p>
10528 * <img width="640" height="390" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/mergeMap.r.v3.png" alt="">
10529 * <dl>
10530 * <dt><b>Backpressure:</b></dt>
10531 * <dd>The operator honors backpressure from downstream. The upstream {@code Flowable} is consumed
10532 * in a bounded manner (up to {@link #bufferSize()} outstanding request amount for items).
10533 * The inner {@code Publisher}s are expected to honor backpressure; if violated,
10534 * the operator <em>may</em> signal {@link MissingBackpressureException}.</dd>
10535 * <dt><b>Scheduler:</b></dt>
10536 * <dd>{@code flatMap} does not operate by default on a particular {@link Scheduler}.</dd>
10537 * </dl>
10538 *
10539 * @param <U>
10540 * the type of items emitted by the inner {@code Publisher}s
10541 * @param <R>
10542 * the type of items emitted by the combiner functions
10543 * @param mapper
10544 * a function that returns a {@code Publisher} for each item emitted by the current {@code Flowable}
10545 * @param combiner
10546 * a function that combines one item emitted by each of the source and collection {@code Publisher}s and
10547 * returns an item to be emitted by the resulting {@code Flowable}
10548 * @param delayErrors
10549 * if {@code true}, exceptions from the current {@code Flowable} and all inner {@code Publisher}s are delayed until all of them terminate
10550 * if {@code false}, the first one signaling an exception will terminate the whole sequence immediately
10551 * @return the new {@code Flowable} instance
10552 * @throws NullPointerException if {@code mapper} or {@code combiner} is {@code null}
10553 * @see <a href="http://reactivex.io/documentation/operators/flatmap.html">ReactiveX operators documentation: FlatMap</a>
10554 */
10555 @CheckReturnValue
10556 @BackpressureSupport(BackpressureKind.FULL)
10557 @SchedulerSupport(SchedulerSupport.NONE)
10558 @NonNull
10559 public final <@NonNull U, @NonNull R> Flowable<R> flatMap(@NonNull Function<? super T, @NonNull ? extends Publisher<? extends U>> mapper,
10560 @NonNull BiFunction<? super T, ? super U, ? extends R> combiner, boolean delayErrors) {
10561 return flatMap(mapper, combiner, delayErrors, bufferSize(), bufferSize());
10562 }
10563
10564 /**
10565 * Returns a {@code Flowable} that emits the results of a specified function to the pair of values emitted by the
10566 * current {@code Flowable} and a specified collection {@link Publisher}, while limiting the maximum number of concurrent
10567 * subscriptions to these {@code Publisher}s.
10568 * <!-- <p> -->
10569 * <!-- <img width="640" height="390" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/mergeMap.r.v3.png" alt=""> -->
10570 * <dl>
10571 * <dt><b>Backpressure:</b></dt>
10572 * <dd>The operator honors backpressure from downstream. The upstream {@code Flowable} is consumed
10573 * in a bounded manner (up to {@code maxConcurrency} outstanding request amount for items).
10574 * The inner {@code Publisher}s are expected to honor backpressure; if violated,
10575 * the operator <em>may</em> signal {@link MissingBackpressureException}.</dd>
10576 * <dt><b>Scheduler:</b></dt>
10577 * <dd>{@code flatMap} does not operate by default on a particular {@link Scheduler}.</dd>
10578 * </dl>
10579 *
10580 * @param <U>
10581 * the type of items emitted by the inner {@code Publisher}s
10582 * @param <R>
10583 * the type of items emitted by the combiner function
10584 * @param mapper
10585 * a function that returns a {@code Publisher} for each item emitted by the current {@code Flowable}
10586 * @param combiner
10587 * a function that combines one item emitted by each of the source and collection {@code Publisher}s and
10588 * returns an item to be emitted by the resulting {@code Flowable}
10589 * @param maxConcurrency
10590 * the maximum number of {@code Publisher}s that may be subscribed to concurrently
10591 * @param delayErrors
10592 * if {@code true}, exceptions from the current {@code Flowable} and all inner {@code Publisher}s are delayed until all of them terminate
10593 * if {@code false}, the first one signaling an exception will terminate the whole sequence immediately
10594 * @return the new {@code Flowable} instance
10595 * @throws NullPointerException if {@code mapper} or {@code combiner} is {@code null}
10596 * @throws IllegalArgumentException if {@code maxConcurrency} is non-positive
10597 * @see <a href="http://reactivex.io/documentation/operators/flatmap.html">ReactiveX operators documentation: FlatMap</a>
10598 * @since 2.0
10599 */
10600 @CheckReturnValue
10601 @BackpressureSupport(BackpressureKind.FULL)
10602 @SchedulerSupport(SchedulerSupport.NONE)
10603 @NonNull
10604 public final <@NonNull U, @NonNull R> Flowable<R> flatMap(@NonNull Function<? super T, @NonNull ? extends Publisher<? extends U>> mapper,
10605 @NonNull BiFunction<? super T, ? super U, ? extends R> combiner, boolean delayErrors, int maxConcurrency) {
10606 return flatMap(mapper, combiner, delayErrors, maxConcurrency, bufferSize());
10607 }
10608
10609 /**
10610 * Returns a {@code Flowable} that emits the results of a specified function to the pair of values emitted by the
10611 * current {@code Flowable} and a specified collection {@link Publisher}, while limiting the maximum number of concurrent
10612 * subscriptions to these {@code Publisher}s.
10613 * <!-- <p> -->
10614 * <!-- <img width="640" height="390" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/mergeMap.r.v3.png" alt=""> -->
10615 * <dl>
10616 * <dt><b>Backpressure:</b></dt>
10617 * <dd>The operator honors backpressure from downstream. The upstream {@code Flowable} is consumed
10618 * in a bounded manner (up to {@code maxConcurrency} outstanding request amount for items).
10619 * The inner {@code Publisher}s are expected to honor backpressure; if violated,
10620 * the operator <em>may</em> signal {@link MissingBackpressureException}.</dd>
10621 * <dt><b>Scheduler:</b></dt>
10622 * <dd>{@code flatMap} does not operate by default on a particular {@link Scheduler}.</dd>
10623 * </dl>
10624 *
10625 * @param <U>
10626 * the type of items emitted by the inner {@code Publisher}s
10627 * @param <R>
10628 * the type of items emitted by the combiner function
10629 * @param mapper
10630 * a function that returns a {@code Publisher} for each item emitted by the current {@code Flowable}
10631 * @param combiner
10632 * a function that combines one item emitted by each of the source and collection {@code Publisher}s and
10633 * returns an item to be emitted by the resulting {@code Flowable}
10634 * @param maxConcurrency
10635 * the maximum number of {@code Publisher}s that may be subscribed to concurrently
10636 * @param delayErrors
10637 * if {@code true}, exceptions from the current {@code Flowable} and all inner {@code Publisher}s are delayed until all of them terminate
10638 * if {@code false}, the first one signaling an exception will terminate the whole sequence immediately
10639 * @param bufferSize
10640 * the number of elements to prefetch from the inner {@code Publisher}s.
10641 * @return the new {@code Flowable} instance
10642 * @throws NullPointerException if {@code mapper} or {@code combiner} is {@code null}
10643 * @throws IllegalArgumentException if {@code maxConcurrency} or {@code bufferSize} is non-positive
10644 * @see <a href="http://reactivex.io/documentation/operators/flatmap.html">ReactiveX operators documentation: FlatMap</a>
10645 * @since 2.0
10646 */
10647 @CheckReturnValue
10648 @NonNull
10649 @BackpressureSupport(BackpressureKind.FULL)
10650 @SchedulerSupport(SchedulerSupport.NONE)
10651 public final <@NonNull U, @NonNull R> Flowable<R> flatMap(@NonNull Function<? super T, @NonNull ? extends Publisher<? extends U>> mapper,
10652 @NonNull BiFunction<? super T, ? super U, ? extends R> combiner, boolean delayErrors, int maxConcurrency, int bufferSize) {
10653 Objects.requireNonNull(mapper, "mapper is null");
10654 Objects.requireNonNull(combiner, "combiner is null");
10655 ObjectHelper.verifyPositive(maxConcurrency, "maxConcurrency");
10656 ObjectHelper.verifyPositive(bufferSize, "bufferSize");
10657 return flatMap(FlowableInternalHelper.flatMapWithCombiner(mapper, combiner), delayErrors, maxConcurrency, bufferSize);
10658 }
10659
10660 /**
10661 * Returns a {@code Flowable} that emits the results of a specified function to the pair of values emitted by the
10662 * current {@code Flowable} and a specified collection {@link Publisher}, while limiting the maximum number of concurrent
10663 * subscriptions to these {@code Publisher}s.
10664 * <!-- <p> -->
10665 * <!-- <img width="640" height="390" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/mergeMap.r.v3.png" alt=""> -->
10666 * <dl>
10667 * <dt><b>Backpressure:</b></dt>
10668 * <dd>The operator honors backpressure from downstream. The upstream {@code Flowable} is consumed
10669 * in a bounded manner (up to {@link #bufferSize()} outstanding request amount for items).
10670 * The inner {@code Publisher}s are expected to honor backpressure; if violated,
10671 * the operator <em>may</em> signal {@link MissingBackpressureException}.</dd>
10672 * <dt><b>Scheduler:</b></dt>
10673 * <dd>{@code flatMap} does not operate by default on a particular {@link Scheduler}.</dd>
10674 * </dl>
10675 *
10676 * @param <U>
10677 * the type of items emitted by the inner {@code Publisher}s
10678 * @param <R>
10679 * the type of items emitted by the combiner function
10680 * @param mapper
10681 * a function that returns a {@code Publisher} for each item emitted by the current {@code Flowable}
10682 * @param combiner
10683 * a function that combines one item emitted by each of the source and collection {@code Publisher}s and
10684 * returns an item to be emitted by the resulting {@code Flowable}
10685 * @param maxConcurrency
10686 * the maximum number of {@code Publisher}s that may be subscribed to concurrently
10687 * @return the new {@code Flowable} instance
10688 * @throws NullPointerException if {@code mapper} or {@code combiner} is {@code null}
10689 * @throws IllegalArgumentException if {@code maxConcurrency} is non-positive
10690 * @see <a href="http://reactivex.io/documentation/operators/flatmap.html">ReactiveX operators documentation: FlatMap</a>
10691 * @since 2.0
10692 */
10693 @CheckReturnValue
10694 @BackpressureSupport(BackpressureKind.FULL)
10695 @SchedulerSupport(SchedulerSupport.NONE)
10696 @NonNull
10697 public final <@NonNull U, @NonNull R> Flowable<R> flatMap(@NonNull Function<? super T, @NonNull ? extends Publisher<? extends U>> mapper,
10698 @NonNull BiFunction<? super T, ? super U, ? extends R> combiner, int maxConcurrency) {
10699 return flatMap(mapper, combiner, false, maxConcurrency, bufferSize());
10700 }
10701
10702 /**
10703 * Maps each element of the upstream {@code Flowable} into {@link CompletableSource}s, subscribes to them and
10704 * waits until the upstream and all {@code CompletableSource}s complete.
10705 * <dl>
10706 * <dt><b>Backpressure:</b></dt>
10707 * <dd>The operator consumes the upstream in an unbounded manner.</dd>
10708 * <dt><b>Scheduler:</b></dt>
10709 * <dd>{@code flatMapCompletable} does not operate by default on a particular {@link Scheduler}.</dd>
10710 * </dl>
10711 * @param mapper the function that received each source value and transforms them into {@code CompletableSource}s.
10712 * @return the new {@link Completable} instance
10713 * @throws NullPointerException if {@code mapper} is {@code null}
10714 */
10715 @CheckReturnValue
10716 @BackpressureSupport(BackpressureKind.UNBOUNDED_IN)
10717 @SchedulerSupport(SchedulerSupport.NONE)
10718 @NonNull
10719 public final Completable flatMapCompletable(@NonNull Function<? super T, ? extends CompletableSource> mapper) {
10720 return flatMapCompletable(mapper, false, Integer.MAX_VALUE);
10721 }
10722
10723 /**
10724 * Maps each element of the upstream {@code Flowable} into {@link CompletableSource}s, subscribes to them and
10725 * waits until the upstream and all {@code CompletableSource}s complete, optionally delaying all errors.
10726 * <dl>
10727 * <dt><b>Backpressure:</b></dt>
10728 * <dd>If {@code maxConcurrency == }{@link Integer#MAX_VALUE} the operator consumes the upstream in an unbounded manner.
10729 * Otherwise, the operator expects the upstream to honor backpressure. If the upstream doesn't support backpressure
10730 * the operator behaves as if {@code maxConcurrency == }{@link Integer#MAX_VALUE} was used.</dd>
10731 * <dt><b>Scheduler:</b></dt>
10732 * <dd>{@code flatMapCompletable} does not operate by default on a particular {@link Scheduler}.</dd>
10733 * </dl>
10734 * @param mapper the function that received each source value and transforms them into {@code CompletableSource}s.
10735 * @param delayErrors if {@code true}, errors from the upstream and inner {@code CompletableSource}s are delayed until each of them
10736 * terminates.
10737 * @param maxConcurrency the maximum number of active subscriptions to the {@code CompletableSource}s.
10738 * @return the new {@link Completable} instance
10739 * @throws NullPointerException if {@code mapper} is {@code null}
10740 * @throws IllegalArgumentException if {@code maxConcurrency} is non-positive
10741 */
10742 @CheckReturnValue
10743 @NonNull
10744 @BackpressureSupport(BackpressureKind.UNBOUNDED_IN)
10745 @SchedulerSupport(SchedulerSupport.NONE)
10746 public final Completable flatMapCompletable(@NonNull Function<? super T, ? extends CompletableSource> mapper, boolean delayErrors, int maxConcurrency) {
10747 Objects.requireNonNull(mapper, "mapper is null");
10748 ObjectHelper.verifyPositive(maxConcurrency, "maxConcurrency");
10749 return RxJavaPlugins.onAssembly(new FlowableFlatMapCompletableCompletable<>(this, mapper, delayErrors, maxConcurrency));
10750 }
10751
10752 /**
10753 * Merges {@link Iterable}s generated by a mapper {@link Function} for each individual item emitted by
10754 * the current {@code Flowable} into a single {@code Flowable} sequence.
10755 * <p>
10756 * <img width="640" height="342" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/flatMapIterable.f.png" alt="">
10757 * <dl>
10758 * <dt><b>Backpressure:</b></dt>
10759 * <dd>The operator honors backpressure from downstream. The current {@code Flowable}s is
10760 * expected to honor backpressure as well. If the current {@code Flowable} violates the rule, the operator will
10761 * signal a {@link MissingBackpressureException}.</dd>
10762 * <dt><b>Scheduler:</b></dt>
10763 * <dd>{@code flatMapIterable} does not operate by default on a particular {@link Scheduler}.</dd>
10764 * </dl>
10765 *
10766 * @param <U>
10767 * the output type and the element type of the {@code Iterable}s
10768 * @param mapper
10769 * a function that returns an {@code Iterable} sequence of values for when given an item emitted by the
10770 * current {@code Flowable}
10771 * @return the new {@code Flowable} instance
10772 * @throws NullPointerException if {@code mapper} is {@code null}
10773 * @see <a href="http://reactivex.io/documentation/operators/flatmap.html">ReactiveX operators documentation: FlatMap</a>
10774 */
10775 @CheckReturnValue
10776 @BackpressureSupport(BackpressureKind.FULL)
10777 @SchedulerSupport(SchedulerSupport.NONE)
10778 @NonNull
10779 public final <@NonNull U> Flowable<U> flatMapIterable(@NonNull Function<? super T, @NonNull ? extends Iterable<? extends U>> mapper) {
10780 return flatMapIterable(mapper, bufferSize());
10781 }
10782
10783 /**
10784 * Merges {@link Iterable}s generated by a mapper {@link Function} for each individual item emitted by
10785 * the current {@code Flowable} into a single {@code Flowable} sequence.
10786 * <p>
10787 * <img width="640" height="342" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/flatMapIterable.f.png" alt="">
10788 * <dl>
10789 * <dt><b>Backpressure:</b></dt>
10790 * <dd>The operator honors backpressure from downstream. The current {@code Flowable}s is
10791 * expected to honor backpressure as well. If the current {@code Flowable} violates the rule, the operator will
10792 * signal a {@link MissingBackpressureException}.</dd>
10793 * <dt><b>Scheduler:</b></dt>
10794 * <dd>{@code flatMapIterable} does not operate by default on a particular {@link Scheduler}.</dd>
10795 * </dl>
10796 *
10797 * @param <U>
10798 * the type of item emitted by the resulting {@code Iterable}
10799 * @param mapper
10800 * a function that returns an {@code Iterable} sequence of values for when given an item emitted by the
10801 * current {@code Flowable}
10802 * @param bufferSize
10803 * the number of elements to prefetch from the current {@code Flowable}
10804 * @return the new {@code Flowable} instance
10805 * @throws NullPointerException if {@code mapper} is {@code null}
10806 * @throws IllegalArgumentException if {@code bufferSize} is non-positive
10807 * @see <a href="http://reactivex.io/documentation/operators/flatmap.html">ReactiveX operators documentation: FlatMap</a>
10808 */
10809 @CheckReturnValue
10810 @NonNull
10811 @BackpressureSupport(BackpressureKind.FULL)
10812 @SchedulerSupport(SchedulerSupport.NONE)
10813 public final <@NonNull U> Flowable<U> flatMapIterable(@NonNull Function<? super T, @NonNull ? extends Iterable<? extends U>> mapper, int bufferSize) {
10814 Objects.requireNonNull(mapper, "mapper is null");
10815 ObjectHelper.verifyPositive(bufferSize, "bufferSize");
10816 return RxJavaPlugins.onAssembly(new FlowableFlattenIterable<>(this, mapper, bufferSize));
10817 }
10818
10819 /**
10820 * Merges {@link Iterable}s generated by a mapper {@link Function} for each individual item emitted by
10821 * the current {@code Flowable} into a single {@code Flowable} sequence where the resulting items will
10822 * be the combination of the original item and each inner item of the respective {@code Iterable} as returned
10823 * by the {@code resultSelector} {@link BiFunction}.
10824 * <p>
10825 * <img width="640" height="410" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/flatMapIterable.f.r.png" alt="">
10826 * <dl>
10827 * <dt><b>Backpressure:</b></dt>
10828 * <dd>The operator honors backpressure from downstream and the current {@code Flowable}s is
10829 * consumed in a bounded manner (requesting {@link #bufferSize()} items upfront, then 75% of it after 75% received).</dd>
10830 * <dt><b>Scheduler:</b></dt>
10831 * <dd>{@code flatMapIterable} does not operate by default on a particular {@link Scheduler}.</dd>
10832 * </dl>
10833 *
10834 * @param <U>
10835 * the element type of the {@code Iterable}s
10836 * @param <V>
10837 * the output type as determined by the {@code resultSelector} function
10838 * @param mapper
10839 * a function that returns an {@code Iterable} sequence of values for each item emitted by the current
10840 * {@code Flowable}
10841 * @param combiner
10842 * a function that returns an item based on the item emitted by the current {@code Flowable} and the
10843 * {@code Iterable} returned for that item by the {@code collectionSelector}
10844 * @return the new {@code Flowable} instance
10845 * @throws NullPointerException if {@code mapper} or {@code combiner} is {@code null}
10846 * @see <a href="http://reactivex.io/documentation/operators/flatmap.html">ReactiveX operators documentation: FlatMap</a>
10847 */
10848 @CheckReturnValue
10849 @NonNull
10850 @BackpressureSupport(BackpressureKind.FULL)
10851 @SchedulerSupport(SchedulerSupport.NONE)
10852 public final <@NonNull U, @NonNull V> Flowable<V> flatMapIterable(@NonNull Function<? super T, @NonNull ? extends Iterable<? extends U>> mapper,
10853 @NonNull BiFunction<? super T, ? super U, ? extends V> combiner) {
10854 Objects.requireNonNull(mapper, "mapper is null");
10855 Objects.requireNonNull(combiner, "combiner is null");
10856 return flatMap(FlowableInternalHelper.flatMapIntoIterable(mapper), combiner, false, bufferSize(), bufferSize());
10857 }
10858
10859 /**
10860 * Merges {@link Iterable}s generated by a mapper {@link Function} for each individual item emitted by
10861 * the current {@code Flowable} into a single {@code Flowable} sequence where the resulting items will
10862 * be the combination of the original item and each inner item of the respective {@code Iterable} as returned
10863 * by the {@code resultSelector} {@link BiFunction}.
10864 * <p>
10865 * <img width="640" height="410" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/flatMapIterable.f.r.png" alt="">
10866 * <dl>
10867 * <dt><b>Backpressure:</b></dt>
10868 * <dd>The operator honors backpressure from downstream. The current {@code Flowable}s is
10869 * expected to honor backpressure as well. If the current {@code Flowable} violates the rule, the operator will
10870 * signal a {@link MissingBackpressureException}.</dd>
10871 * <dt><b>Scheduler:</b></dt>
10872 * <dd>{@code flatMapIterable} does not operate by default on a particular {@link Scheduler}.</dd>
10873 * </dl>
10874 *
10875 * @param <U>
10876 * the element type of the inner {@code Iterable} sequences
10877 * @param <V>
10878 * the type of item emitted by the resulting {@code Flowable}
10879 * @param mapper
10880 * a function that returns an {@code Iterable} sequence of values for when given an item emitted by the
10881 * current {@code Flowable}
10882 * @param combiner
10883 * a function that returns an item based on the item emitted by the current {@code Flowable} and the
10884 * {@code Iterable} returned for that item by the {@code collectionSelector}
10885 * @param prefetch
10886 * the number of elements to prefetch from the current {@code Flowable}
10887 * @return the new {@code Flowable} instance
10888 * @throws NullPointerException if {@code mapper} or {@code combiner} is {@code null}
10889 * @throws IllegalArgumentException if {@code prefetch} is non-positive
10890 * @see <a href="http://reactivex.io/documentation/operators/flatmap.html">ReactiveX operators documentation: FlatMap</a>
10891 * @since 2.0
10892 */
10893 @CheckReturnValue
10894 @NonNull
10895 @BackpressureSupport(BackpressureKind.FULL)
10896 @SchedulerSupport(SchedulerSupport.NONE)
10897 public final <@NonNull U, @NonNull V> Flowable<V> flatMapIterable(@NonNull Function<? super T, @NonNull ? extends Iterable<? extends U>> mapper,
10898 @NonNull BiFunction<? super T, ? super U, ? extends V> combiner, int prefetch) {
10899 Objects.requireNonNull(mapper, "mapper is null");
10900 Objects.requireNonNull(combiner, "combiner is null");
10901 return flatMap(FlowableInternalHelper.flatMapIntoIterable(mapper), combiner, false, bufferSize(), prefetch);
10902 }
10903
10904 /**
10905 * Maps each element of the upstream {@code Flowable} into {@link MaybeSource}s, subscribes to all of them
10906 * and merges their {@code onSuccess} values, in no particular order, into a single {@code Flowable} sequence.
10907 * <dl>
10908 * <dt><b>Backpressure:</b></dt>
10909 * <dd>The operator consumes the upstream in an unbounded manner.</dd>
10910 * <dt><b>Scheduler:</b></dt>
10911 * <dd>{@code flatMapMaybe} does not operate by default on a particular {@link Scheduler}.</dd>
10912 * </dl>
10913 * @param <R> the result value type
10914 * @param mapper the function that received each source value and transforms them into {@code MaybeSource}s.
10915 * @return the new {@code Flowable} instance
10916 * @throws NullPointerException if {@code mapper} is {@code null}
10917 */
10918 @CheckReturnValue
10919 @BackpressureSupport(BackpressureKind.UNBOUNDED_IN)
10920 @SchedulerSupport(SchedulerSupport.NONE)
10921 @NonNull
10922 public final <@NonNull R> Flowable<R> flatMapMaybe(@NonNull Function<? super T, ? extends MaybeSource<? extends R>> mapper) {
10923 return flatMapMaybe(mapper, false, Integer.MAX_VALUE);
10924 }
10925
10926 /**
10927 * Maps each element of the upstream {@code Flowable} into {@link MaybeSource}s, subscribes to at most
10928 * {@code maxConcurrency} {@code MaybeSource}s at a time and merges their {@code onSuccess} values,
10929 * in no particular order, into a single {@code Flowable} sequence, optionally delaying all errors.
10930 * <dl>
10931 * <dt><b>Backpressure:</b></dt>
10932 * <dd>If {@code maxConcurrency == }{@link Integer#MAX_VALUE} the operator consumes the upstream in an unbounded manner.
10933 * Otherwise, the operator expects the upstream to honor backpressure. If the upstream doesn't support backpressure
10934 * the operator behaves as if {@code maxConcurrency == }{@link Integer#MAX_VALUE} was used.</dd>
10935 * <dt><b>Scheduler:</b></dt>
10936 * <dd>{@code flatMapMaybe} does not operate by default on a particular {@link Scheduler}.</dd>
10937 * </dl>
10938 * @param <R> the result value type
10939 * @param mapper the function that received each source value and transforms them into {@code MaybeSource}s.
10940 * @param delayErrors if {@code true}, errors from the upstream and inner {@code MaybeSource}s are delayed until each of them
10941 * terminates.
10942 * @param maxConcurrency the maximum number of active subscriptions to the {@code MaybeSource}s.
10943 * @return the new {@code Flowable} instance
10944 * @throws NullPointerException if {@code mapper} is {@code null}
10945 * @throws IllegalArgumentException if {@code maxConcurrency} is non-positive
10946 */
10947 @CheckReturnValue
10948 @NonNull
10949 @BackpressureSupport(BackpressureKind.UNBOUNDED_IN)
10950 @SchedulerSupport(SchedulerSupport.NONE)
10951 public final <@NonNull R> Flowable<R> flatMapMaybe(@NonNull Function<? super T, ? extends MaybeSource<? extends R>> mapper, boolean delayErrors, int maxConcurrency) {
10952 Objects.requireNonNull(mapper, "mapper is null");
10953 ObjectHelper.verifyPositive(maxConcurrency, "maxConcurrency");
10954 return RxJavaPlugins.onAssembly(new FlowableFlatMapMaybe<>(this, mapper, delayErrors, maxConcurrency));
10955 }
10956
10957 /**
10958 * Maps each element of the upstream {@code Flowable} into {@link SingleSource}s, subscribes to all of them
10959 * and merges their {@code onSuccess} values, in no particular order, into a single {@code Flowable} sequence.
10960 * <dl>
10961 * <dt><b>Backpressure:</b></dt>
10962 * <dd>The operator consumes the upstream in an unbounded manner.</dd>
10963 * <dt><b>Scheduler:</b></dt>
10964 * <dd>{@code flatMapSingle} does not operate by default on a particular {@link Scheduler}.</dd>
10965 * </dl>
10966 * @param <R> the result value type
10967 * @param mapper the function that received each source value and transforms them into {@code SingleSource}s.
10968 * @return the new {@code Flowable} instance
10969 * @throws NullPointerException if {@code mapper} is {@code null}
10970 */
10971 @CheckReturnValue
10972 @BackpressureSupport(BackpressureKind.UNBOUNDED_IN)
10973 @SchedulerSupport(SchedulerSupport.NONE)
10974 @NonNull
10975 public final <@NonNull R> Flowable<R> flatMapSingle(@NonNull Function<? super T, ? extends SingleSource<? extends R>> mapper) {
10976 return flatMapSingle(mapper, false, Integer.MAX_VALUE);
10977 }
10978
10979 /**
10980 * Maps each element of the upstream {@code Flowable} into {@link SingleSource}s, subscribes to at most
10981 * {@code maxConcurrency} {@code SingleSource}s at a time and merges their {@code onSuccess} values,
10982 * in no particular order, into a single {@code Flowable} sequence, optionally delaying all errors.
10983 * <dl>
10984 * <dt><b>Backpressure:</b></dt>
10985 * <dd>If {@code maxConcurrency == }{@link Integer#MAX_VALUE} the operator consumes the upstream in an unbounded manner.
10986 * Otherwise, the operator expects the upstream to honor backpressure. If the upstream doesn't support backpressure
10987 * the operator behaves as if {@code maxConcurrency == }{@link Integer#MAX_VALUE} was used.</dd>
10988 * <dt><b>Scheduler:</b></dt>
10989 * <dd>{@code flatMapSingle} does not operate by default on a particular {@link Scheduler}.</dd>
10990 * </dl>
10991 * @param <R> the result value type
10992 * @param mapper the function that received each source value and transforms them into {@code SingleSource}s.
10993 * @param delayErrors if {@code true}, errors from the upstream and inner {@code SingleSources} are delayed until each of them
10994 * terminates.
10995 * @param maxConcurrency the maximum number of active subscriptions to the {@code SingleSource}s.
10996 * @return the new {@code Flowable} instance
10997 * @throws NullPointerException if {@code mapper} is {@code null}
10998 * @throws IllegalArgumentException if {@code maxConcurrency} is non-positive
10999 */
11000 @CheckReturnValue
11001 @NonNull
11002 @BackpressureSupport(BackpressureKind.UNBOUNDED_IN)
11003 @SchedulerSupport(SchedulerSupport.NONE)
11004 public final <@NonNull R> Flowable<R> flatMapSingle(@NonNull Function<? super T, ? extends SingleSource<? extends R>> mapper, boolean delayErrors, int maxConcurrency) {
11005 Objects.requireNonNull(mapper, "mapper is null");
11006 ObjectHelper.verifyPositive(maxConcurrency, "maxConcurrency");
11007 return RxJavaPlugins.onAssembly(new FlowableFlatMapSingle<>(this, mapper, delayErrors, maxConcurrency));
11008 }
11009
11010 /**
11011 * Subscribes to the current {@code Flowable} and receives notifications for each element.
11012 * <p>
11013 * Alias to {@link #subscribe(Consumer)}
11014 * <dl>
11015 * <dt><b>Backpressure:</b></dt>
11016 * <dd>The operator consumes the current {@code Flowable} in an unbounded manner (i.e., no
11017 * backpressure is applied to it).</dd>
11018 * <dt><b>Scheduler:</b></dt>
11019 * <dd>{@code forEach} does not operate by default on a particular {@link Scheduler}.</dd>
11020 * </dl>
11021 *
11022 * @param onNext
11023 * {@link Consumer} to execute for each item.
11024 * @return
11025 * a {@link Disposable} that allows canceling an asynchronous sequence
11026 * @throws NullPointerException
11027 * if {@code onNext} is {@code null}
11028 * @see <a href="http://reactivex.io/documentation/operators/subscribe.html">ReactiveX operators documentation: Subscribe</a>
11029 */
11030 @CheckReturnValue
11031 @BackpressureSupport(BackpressureKind.NONE)
11032 @SchedulerSupport(SchedulerSupport.NONE)
11033 @NonNull
11034 public final Disposable forEach(@NonNull Consumer<? super T> onNext) {
11035 return subscribe(onNext);
11036 }
11037
11038 /**
11039 * Subscribes to the current {@code Flowable} and receives notifications for each element until the
11040 * {@code onNext} Predicate returns {@code false}.
11041 * <p>
11042 * If the {@code Flowable} emits an error, it is wrapped into an
11043 * {@link io.reactivex.rxjava3.exceptions.OnErrorNotImplementedException OnErrorNotImplementedException}
11044 * and routed to the {@link RxJavaPlugins#onError(Throwable)} handler.
11045 * <dl>
11046 * <dt><b>Backpressure:</b></dt>
11047 * <dd>The operator consumes the current {@code Flowable} in an unbounded manner (i.e., no
11048 * backpressure is applied to it).</dd>
11049 * <dt><b>Scheduler:</b></dt>
11050 * <dd>{@code forEachWhile} does not operate by default on a particular {@link Scheduler}.</dd>
11051 * </dl>
11052 *
11053 * @param onNext
11054 * {@link Predicate} to execute for each item.
11055 * @return
11056 * a {@link Disposable} that allows canceling an asynchronous sequence
11057 * @throws NullPointerException
11058 * if {@code onNext} is {@code null}
11059 * @see <a href="http://reactivex.io/documentation/operators/subscribe.html">ReactiveX operators documentation: Subscribe</a>
11060 */
11061 @CheckReturnValue
11062 @BackpressureSupport(BackpressureKind.NONE)
11063 @SchedulerSupport(SchedulerSupport.NONE)
11064 @NonNull
11065 public final Disposable forEachWhile(@NonNull Predicate<? super T> onNext) {
11066 return forEachWhile(onNext, Functions.ON_ERROR_MISSING, Functions.EMPTY_ACTION);
11067 }
11068
11069 /**
11070 * Subscribes to the current {@code Flowable} and receives notifications for each element and error events until the
11071 * {@code onNext} Predicate returns {@code false}.
11072 * <dl>
11073 * <dt><b>Backpressure:</b></dt>
11074 * <dd>The operator consumes the current {@code Flowable} in an unbounded manner (i.e., no
11075 * backpressure is applied to it).</dd>
11076 * <dt><b>Scheduler:</b></dt>
11077 * <dd>{@code forEachWhile} does not operate by default on a particular {@link Scheduler}.</dd>
11078 * </dl>
11079 *
11080 * @param onNext
11081 * {@link Predicate} to execute for each item.
11082 * @param onError
11083 * {@link Consumer} to execute when an error is emitted.
11084 * @return
11085 * a {@link Disposable} that allows canceling an asynchronous sequence
11086 * @throws NullPointerException
11087 * if {@code onNext} or {@code onError} is {@code null}
11088 * @see <a href="http://reactivex.io/documentation/operators/subscribe.html">ReactiveX operators documentation: Subscribe</a>
11089 */
11090 @CheckReturnValue
11091 @BackpressureSupport(BackpressureKind.NONE)
11092 @SchedulerSupport(SchedulerSupport.NONE)
11093 @NonNull
11094 public final Disposable forEachWhile(@NonNull Predicate<? super T> onNext, @NonNull Consumer<? super Throwable> onError) {
11095 return forEachWhile(onNext, onError, Functions.EMPTY_ACTION);
11096 }
11097
11098 /**
11099 * Subscribes to the current {@code Flowable} and receives notifications for each element and the terminal events until the
11100 * {@code onNext} Predicate returns {@code false}.
11101 * <dl>
11102 * <dt><b>Backpressure:</b></dt>
11103 * <dd>The operator consumes the current {@code Flowable} in an unbounded manner (i.e., no
11104 * backpressure is applied to it).</dd>
11105 * <dt><b>Scheduler:</b></dt>
11106 * <dd>{@code forEachWhile} does not operate by default on a particular {@link Scheduler}.</dd>
11107 * </dl>
11108 *
11109 * @param onNext
11110 * {@link Predicate} to execute for each item.
11111 * @param onError
11112 * {@link Consumer} to execute when an error is emitted.
11113 * @param onComplete
11114 * {@link Action} to execute when completion is signaled.
11115 * @return
11116 * a {@link Disposable} that allows canceling an asynchronous sequence
11117 * @throws NullPointerException
11118 * if {@code onNext}, {@code onError} or {@code onComplete} is {@code null}
11119 * @see <a href="http://reactivex.io/documentation/operators/subscribe.html">ReactiveX operators documentation: Subscribe</a>
11120 */
11121 @CheckReturnValue
11122 @NonNull
11123 @BackpressureSupport(BackpressureKind.NONE)
11124 @SchedulerSupport(SchedulerSupport.NONE)
11125 public final Disposable forEachWhile(@NonNull Predicate<? super T> onNext, @NonNull Consumer<? super Throwable> onError,
11126 @NonNull Action onComplete) {
11127 Objects.requireNonNull(onNext, "onNext is null");
11128 Objects.requireNonNull(onError, "onError is null");
11129 Objects.requireNonNull(onComplete, "onComplete is null");
11130
11131 ForEachWhileSubscriber<T> s = new ForEachWhileSubscriber<>(onNext, onError, onComplete);
11132 subscribe(s);
11133 return s;
11134 }
11135
11136 /**
11137 * Groups the items emitted by the current {@code Flowable} according to a specified criterion, and emits these
11138 * grouped items as {@link GroupedFlowable}s. The emitted {@code GroupedFlowable} allows only a single
11139 * {@link Subscriber} during its lifetime and if this {@code Subscriber} cancels before the
11140 * source terminates, the next emission by the source having the same key will trigger a new
11141 * {@code GroupedFlowable} emission.
11142 * <p>
11143 * <img width="640" height="360" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/groupBy.v3.png" alt="">
11144 * <p>
11145 * <em>Note:</em> A {@code GroupedFlowable} will cache the items it is to emit until such time as it
11146 * is subscribed to. For this reason, in order to avoid memory leaks, you should not simply ignore those
11147 * {@code GroupedFlowable}s that do not concern you. Instead, you can signal to them that they may
11148 * discard their buffers by applying an operator like {@link #ignoreElements} to them.
11149 * <p>
11150 * Note that the {@code GroupedFlowable}s should be subscribed to as soon as possible, otherwise,
11151 * the unconsumed groups may starve other groups due to the internal backpressure
11152 * coordination of the {@code groupBy} operator. Such hangs can be usually avoided by using
11153 * {@link #flatMap(Function, int)} or {@link #concatMapEager(Function, int, int)} and overriding the default maximum concurrency
11154 * value to be greater or equal to the expected number of groups, possibly using
11155 * {@link Integer#MAX_VALUE} if the number of expected groups is unknown.
11156 * <p>
11157 * Note also that ignoring groups or subscribing later (i.e., on another thread) will result in
11158 * so-called group abandonment where a group will only contain one element and the group will be
11159 * re-created over and over as new upstream items trigger a new group. The behavior is
11160 * a trade-off between no-dataloss, upstream cancellation and excessive group creation.
11161 *
11162 * <dl>
11163 * <dt><b>Backpressure:</b></dt>
11164 * <dd>The consumer of the returned {@code Flowable} has to be ready to receive new {@code GroupedFlowable}s or else
11165 * this operator will signal {@link MissingBackpressureException}. To avoid this exception, make
11166 * sure a combining operator (such as {@code flatMap}) has adequate amount of buffering/prefetch configured.
11167 * The inner {@code GroupedFlowable}s honor backpressure but due to the single-source multiple consumer
11168 * nature of this operator, each group must be consumed so the whole operator can make progress and not hang.</dd>
11169 * <dt><b>Scheduler:</b></dt>
11170 * <dd>{@code groupBy} does not operate by default on a particular {@link Scheduler}.</dd>
11171 * <dt><b>Error handling:</b></dt>
11172 * <dd>If the upstream signals or the callback(s) throw an exception, the returned {@code Flowable} and
11173 * all active inner {@code GroupedFlowable}s will signal the same exception.</dd>
11174 * </dl>
11175 *
11176 * @param keySelector
11177 * a function that extracts the key for each item
11178 * @param <K>
11179 * the key type
11180 * @return the new {@code Flowable} instance
11181 * @throws NullPointerException if {@code keySelector} is {@code null}
11182 * @see <a href="http://reactivex.io/documentation/operators/groupby.html">ReactiveX operators documentation: GroupBy</a>
11183 * @see #groupBy(Function, boolean)
11184 * @see #groupBy(Function, Function)
11185 */
11186 @CheckReturnValue
11187 @BackpressureSupport(BackpressureKind.ERROR)
11188 @SchedulerSupport(SchedulerSupport.NONE)
11189 @NonNull
11190 public final <@NonNull K> Flowable<GroupedFlowable<K, T>> groupBy(@NonNull Function<? super T, ? extends K> keySelector) {
11191 return groupBy(keySelector, Functions.identity(), false, bufferSize());
11192 }
11193
11194 /**
11195 * Groups the items emitted by the current {@code Flowable} according to a specified criterion, and emits these
11196 * grouped items as {@link GroupedFlowable}s. The emitted {@code GroupedFlowable} allows only a single
11197 * {@link Subscriber} during its lifetime and if this {@code Subscriber} cancels before the
11198 * source terminates, the next emission by the source having the same key will trigger a new
11199 * {@code GroupedFlowable} emission.
11200 * <p>
11201 * <img width="640" height="360" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/groupBy.v3.png" alt="">
11202 * <p>
11203 * <em>Note:</em> A {@code GroupedFlowable} will cache the items it is to emit until such time as it
11204 * is subscribed to. For this reason, in order to avoid memory leaks, you should not simply ignore those
11205 * {@code GroupedFlowable}s that do not concern you. Instead, you can signal to them that they may
11206 * discard their buffers by applying an operator like {@link #ignoreElements} to them.
11207 * <p>
11208 * Note that the {@code GroupedFlowable}s should be subscribed to as soon as possible, otherwise,
11209 * the unconsumed groups may starve other groups due to the internal backpressure
11210 * coordination of the {@code groupBy} operator. Such hangs can be usually avoided by using
11211 * {@link #flatMap(Function, int)} or {@link #concatMapEager(Function, int, int)} and overriding the default maximum concurrency
11212 * value to be greater or equal to the expected number of groups, possibly using
11213 * {@link Integer#MAX_VALUE} if the number of expected groups is unknown.
11214 * <p>
11215 * Note also that ignoring groups or subscribing later (i.e., on another thread) will result in
11216 * so-called group abandonment where a group will only contain one element and the group will be
11217 * re-created over and over as new upstream items trigger a new group. The behavior is
11218 * a trade-off between no-dataloss, upstream cancellation and excessive group creation.
11219 *
11220 * <dl>
11221 * <dt><b>Backpressure:</b></dt>
11222 * <dd>The consumer of the returned {@code Flowable} has to be ready to receive new {@code GroupedFlowable}s or else
11223 * this operator will signal {@link MissingBackpressureException}. To avoid this exception, make
11224 * sure a combining operator (such as {@code flatMap}) has adequate amount of buffering/prefetch configured.
11225 * The inner {@code GroupedFlowable}s honor backpressure but due to the single-source multiple consumer
11226 * nature of this operator, each group must be consumed so the whole operator can make progress and not hang.</dd>
11227 * <dt><b>Scheduler:</b></dt>
11228 * <dd>{@code groupBy} does not operate by default on a particular {@link Scheduler}.</dd>
11229 * <dt><b>Error handling:</b></dt>
11230 * <dd>If the upstream signals or the callback(s) throw an exception, the returned {@code Flowable} and
11231 * all active inner {@code GroupedFlowable}s will signal the same exception.</dd>
11232 * </dl>
11233 *
11234 * @param keySelector
11235 * a function that extracts the key for each item
11236 * @param <K>
11237 * the key type
11238 * @param delayError
11239 * if {@code true}, the exception from the current {@code Flowable} is delayed in each group until that specific group emitted
11240 * the normal values; if {@code false}, the exception bypasses values in the groups and is reported immediately.
11241 * @return the new {@code Flowable} instance
11242 * @throws NullPointerException if {@code keySelector} is {@code null}
11243 * @see <a href="http://reactivex.io/documentation/operators/groupby.html">ReactiveX operators documentation: GroupBy</a>
11244 */
11245 @CheckReturnValue
11246 @BackpressureSupport(BackpressureKind.ERROR)
11247 @SchedulerSupport(SchedulerSupport.NONE)
11248 @NonNull
11249 public final <@NonNull K> Flowable<GroupedFlowable<K, T>> groupBy(@NonNull Function<? super T, ? extends K> keySelector, boolean delayError) {
11250 return groupBy(keySelector, Functions.identity(), delayError, bufferSize());
11251 }
11252
11253 /**
11254 * Groups the items emitted by the current {@code Flowable} according to a specified criterion, and emits these
11255 * grouped items as {@link GroupedFlowable}s. The emitted {@code GroupedFlowable} allows only a single
11256 * {@link Subscriber} during its lifetime and if this {@code Subscriber} cancels before the
11257 * source terminates, the next emission by the source having the same key will trigger a new
11258 * {@code GroupedFlowable} emission.
11259 * <p>
11260 * <img width="640" height="360" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/groupBy.v3.png" alt="">
11261 * <p>
11262 * <em>Note:</em> A {@code GroupedFlowable} will cache the items it is to emit until such time as it
11263 * is subscribed to. For this reason, in order to avoid memory leaks, you should not simply ignore those
11264 * {@code GroupedFlowable}s that do not concern you. Instead, you can signal to them that they may
11265 * discard their buffers by applying an operator like {@link #ignoreElements} to them.
11266 * <p>
11267 * Note that the {@code GroupedFlowable}s should be subscribed to as soon as possible, otherwise,
11268 * the unconsumed groups may starve other groups due to the internal backpressure
11269 * coordination of the {@code groupBy} operator. Such hangs can be usually avoided by using
11270 * {@link #flatMap(Function, int)} or {@link #concatMapEager(Function, int, int)} and overriding the default maximum concurrency
11271 * value to be greater or equal to the expected number of groups, possibly using
11272 * {@link Integer#MAX_VALUE} if the number of expected groups is unknown.
11273 * <p>
11274 * Note also that ignoring groups or subscribing later (i.e., on another thread) will result in
11275 * so-called group abandonment where a group will only contain one element and the group will be
11276 * re-created over and over as new upstream items trigger a new group. The behavior is
11277 * a trade-off between no-dataloss, upstream cancellation and excessive group creation.
11278 *
11279 * <dl>
11280 * <dt><b>Backpressure:</b></dt>
11281 * <dd>The consumer of the returned {@code Flowable} has to be ready to receive new {@code GroupedFlowable}s or else
11282 * this operator will signal {@link MissingBackpressureException}. To avoid this exception, make
11283 * sure a combining operator (such as {@code flatMap}) has adequate amount of buffering/prefetch configured.
11284 * The inner {@code GroupedFlowable}s honor backpressure but due to the single-source multiple consumer
11285 * nature of this operator, each group must be consumed so the whole operator can make progress and not hang.</dd>
11286 * <dt><b>Scheduler:</b></dt>
11287 * <dd>{@code groupBy} does not operate by default on a particular {@link Scheduler}.</dd>
11288 * <dt><b>Error handling:</b></dt>
11289 * <dd>If the upstream signals or the callback(s) throw an exception, the returned {@code Flowable} and
11290 * all active inner {@code GroupedFlowable}s will signal the same exception.</dd>
11291 * </dl>
11292 *
11293 * @param keySelector
11294 * a function that extracts the key for each item
11295 * @param valueSelector
11296 * a function that extracts the return element for each item
11297 * @param <K>
11298 * the key type
11299 * @param <V>
11300 * the element type
11301 * @return the new {@code Flowable} instance
11302 * @throws NullPointerException if {@code keySelector} or {@code valueSelector} is {@code null}
11303 * @see <a href="http://reactivex.io/documentation/operators/groupby.html">ReactiveX operators documentation: GroupBy</a>
11304 * @see #groupBy(Function, Function, boolean)
11305 * @see #groupBy(Function, Function, boolean, int)
11306 * @see #groupBy(Function, Function, boolean, int, Function)
11307 */
11308 @CheckReturnValue
11309 @BackpressureSupport(BackpressureKind.ERROR)
11310 @SchedulerSupport(SchedulerSupport.NONE)
11311 @NonNull
11312 public final <@NonNull K, @NonNull V> Flowable<GroupedFlowable<K, V>> groupBy(@NonNull Function<? super T, ? extends K> keySelector,
11313 @NonNull Function<? super T, ? extends V> valueSelector) {
11314 return groupBy(keySelector, valueSelector, false, bufferSize());
11315 }
11316
11317 /**
11318 * Groups the items emitted by the current {@code Flowable} according to a specified criterion, and emits these
11319 * grouped items as {@link GroupedFlowable}s. The emitted {@code GroupedFlowable} allows only a single
11320 * {@link Subscriber} during its lifetime and if this {@code Subscriber} cancels before the
11321 * source terminates, the next emission by the source having the same key will trigger a new
11322 * {@code GroupedFlowable} emission.
11323 * <p>
11324 * <img width="640" height="360" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/groupBy.v3.png" alt="">
11325 * <p>
11326 * <em>Note:</em> A {@code GroupedFlowable} will cache the items it is to emit until such time as it
11327 * is subscribed to. For this reason, in order to avoid memory leaks, you should not simply ignore those
11328 * {@code GroupedFlowable}s that do not concern you. Instead, you can signal to them that they may
11329 * discard their buffers by applying an operator like {@link #ignoreElements} to them.
11330 * <p>
11331 * Note that the {@code GroupedFlowable}s should be subscribed to as soon as possible, otherwise,
11332 * the unconsumed groups may starve other groups due to the internal backpressure
11333 * coordination of the {@code groupBy} operator. Such hangs can be usually avoided by using
11334 * {@link #flatMap(Function, int)} or {@link #concatMapEager(Function, int, int)} and overriding the default maximum concurrency
11335 * value to be greater or equal to the expected number of groups, possibly using
11336 * {@link Integer#MAX_VALUE} if the number of expected groups is unknown.
11337 * <p>
11338 * Note also that ignoring groups or subscribing later (i.e., on another thread) will result in
11339 * so-called group abandonment where a group will only contain one element and the group will be
11340 * re-created over and over as new upstream items trigger a new group. The behavior is
11341 * a trade-off between no-dataloss, upstream cancellation and excessive group creation.
11342 *
11343 * <dl>
11344 * <dt><b>Backpressure:</b></dt>
11345 * <dd>The consumer of the returned {@code Flowable} has to be ready to receive new {@code GroupedFlowable}s or else
11346 * this operator will signal {@link MissingBackpressureException}. To avoid this exception, make
11347 * sure a combining operator (such as {@code flatMap}) has adequate amount of buffering/prefetch configured.
11348 * The inner {@code GroupedFlowable}s honor backpressure but due to the single-source multiple consumer
11349 * nature of this operator, each group must be consumed so the whole operator can make progress and not hang.</dd>
11350 * <dt><b>Scheduler:</b></dt>
11351 * <dd>{@code groupBy} does not operate by default on a particular {@link Scheduler}.</dd>
11352 * <dt><b>Error handling:</b></dt>
11353 * <dd>If the upstream signals or the callback(s) throw an exception, the returned {@code Flowable} and
11354 * all active inner {@code GroupedFlowable}s will signal the same exception.</dd>
11355 * </dl>
11356 *
11357 * @param keySelector
11358 * a function that extracts the key for each item
11359 * @param valueSelector
11360 * a function that extracts the return element for each item
11361 * @param <K>
11362 * the key type
11363 * @param <V>
11364 * the element type
11365 * @param delayError
11366 * if {@code true}, the exception from the current {@code Flowable} is delayed in each group until that specific group emitted
11367 * the normal values; if {@code false}, the exception bypasses values in the groups and is reported immediately.
11368 * @return the new {@code Flowable} instance
11369 * @throws NullPointerException if {@code keySelector} or {@code valueSelector} is {@code null}
11370 * @see <a href="http://reactivex.io/documentation/operators/groupby.html">ReactiveX operators documentation: GroupBy</a>
11371 * @see #groupBy(Function, Function, boolean, int)
11372 */
11373 @CheckReturnValue
11374 @BackpressureSupport(BackpressureKind.ERROR)
11375 @SchedulerSupport(SchedulerSupport.NONE)
11376 @NonNull
11377 public final <@NonNull K, @NonNull V> Flowable<GroupedFlowable<K, V>> groupBy(@NonNull Function<? super T, ? extends K> keySelector,
11378 @NonNull Function<? super T, ? extends V> valueSelector, boolean delayError) {
11379 return groupBy(keySelector, valueSelector, delayError, bufferSize());
11380 }
11381
11382 /**
11383 * Groups the items emitted by the current {@code Flowable} according to a specified criterion, and emits these
11384 * grouped items as {@link GroupedFlowable}s. The emitted {@code GroupedFlowable} allows only a single
11385 * {@link Subscriber} during its lifetime and if this {@code Subscriber} cancels before the
11386 * source terminates, the next emission by the source having the same key will trigger a new
11387 * {@code GroupedFlowable} emission.
11388 * <p>
11389 * <img width="640" height="360" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/groupBy.v3.png" alt="">
11390 * <p>
11391 * <em>Note:</em> A {@code GroupedFlowable} will cache the items it is to emit until such time as it
11392 * is subscribed to. For this reason, in order to avoid memory leaks, you should not simply ignore those
11393 * {@code GroupedFlowable}s that do not concern you. Instead, you can signal to them that they may
11394 * discard their buffers by applying an operator like {@link #ignoreElements} to them.
11395 * <p>
11396 * Note that the {@code GroupedFlowable}s should be subscribed to as soon as possible, otherwise,
11397 * the unconsumed groups may starve other groups due to the internal backpressure
11398 * coordination of the {@code groupBy} operator. Such hangs can be usually avoided by using
11399 * {@link #flatMap(Function, int)} or {@link #concatMapEager(Function, int, int)} and overriding the default maximum concurrency
11400 * value to be greater or equal to the expected number of groups, possibly using
11401 * {@link Integer#MAX_VALUE} if the number of expected groups is unknown.
11402 * <p>
11403 * Note also that ignoring groups or subscribing later (i.e., on another thread) will result in
11404 * so-called group abandonment where a group will only contain one element and the group will be
11405 * re-created over and over as new upstream items trigger a new group. The behavior is
11406 * a trade-off between no-dataloss, upstream cancellation and excessive group creation.
11407 *
11408 * <dl>
11409 * <dt><b>Backpressure:</b></dt>
11410 * <dd>The consumer of the returned {@code Flowable} has to be ready to receive new {@code GroupedFlowable}s or else
11411 * this operator will signal {@link MissingBackpressureException}. To avoid this exception, make
11412 * sure a combining operator (such as {@code flatMap}) has adequate amount of buffering/prefetch configured.
11413 * The inner {@code GroupedFlowable}s honor backpressure but due to the single-source multiple consumer
11414 * nature of this operator, each group must be consumed so the whole operator can make progress and not hang.</dd>
11415 * <dt><b>Scheduler:</b></dt>
11416 * <dd>{@code groupBy} does not operate by default on a particular {@link Scheduler}.</dd>
11417 * <dt><b>Error handling:</b></dt>
11418 * <dd>If the upstream signals or the callback(s) throw an exception, the returned {@code Flowable} and
11419 * all active inner {@code GroupedFlowable}s will signal the same exception.</dd>
11420 * </dl>
11421 *
11422 * @param keySelector
11423 * a function that extracts the key for each item
11424 * @param valueSelector
11425 * a function that extracts the return element for each item
11426 * @param delayError
11427 * if {@code true}, the exception from the current {@code Flowable} is delayed in each group until that specific group emitted
11428 * the normal values; if {@code false}, the exception bypasses values in the groups and is reported immediately.
11429 * @param bufferSize
11430 * the hint for how many {@code GroupedFlowable}s and element in each {@code GroupedFlowable} should be buffered
11431 * @param <K>
11432 * the key type
11433 * @param <V>
11434 * the element type
11435 * @return the new {@code Flowable} instance
11436 * @throws NullPointerException if {@code keySelector} or {@code valueSelector} is {@code null}
11437 * @throws IllegalArgumentException if {@code bufferSize} is non-positive
11438 * @see <a href="http://reactivex.io/documentation/operators/groupby.html">ReactiveX operators documentation: GroupBy</a>
11439 */
11440 @CheckReturnValue
11441 @NonNull
11442 @BackpressureSupport(BackpressureKind.SPECIAL)
11443 @SchedulerSupport(SchedulerSupport.NONE)
11444 public final <@NonNull K, @NonNull V> Flowable<GroupedFlowable<K, V>> groupBy(@NonNull Function<? super T, ? extends K> keySelector,
11445 @NonNull Function<? super T, ? extends V> valueSelector,
11446 boolean delayError, int bufferSize) {
11447 Objects.requireNonNull(keySelector, "keySelector is null");
11448 Objects.requireNonNull(valueSelector, "valueSelector is null");
11449 ObjectHelper.verifyPositive(bufferSize, "bufferSize");
11450
11451 return RxJavaPlugins.onAssembly(new FlowableGroupBy<>(this, keySelector, valueSelector, bufferSize, delayError, null));
11452 }
11453
11454 /**
11455 * Groups the items emitted by the current {@code Flowable} according to a specified criterion, and emits these
11456 * grouped items as {@link GroupedFlowable}s. The emitted {@code GroupedFlowable} allows only a single
11457 * {@link Subscriber} during its lifetime and if this {@code Subscriber} cancels before the
11458 * source terminates, the next emission by the source having the same key will trigger a new
11459 * {@code GroupedFlowable} emission. The {@code evictingMapFactory} is used to create a map that will
11460 * be used to hold the {@code GroupedFlowable}s by key. The evicting map created by this factory must
11461 * notify the provided {@code Consumer<Object>} with the entry value (not the key!) when an entry in this
11462 * map has been evicted. The next source emission will bring about the completion of the evicted
11463 * {@code GroupedFlowable}s and the arrival of an item with the same key as a completed {@code GroupedFlowable}
11464 * will prompt the creation and emission of a new {@code GroupedFlowable} with that key.
11465 *
11466 * <p>A use case for specifying an {@code evictingMapFactory} is where the source is infinite and fast and
11467 * over time the number of keys grows enough to be a concern in terms of the memory footprint of the
11468 * internal hash map containing the {@code GroupedFlowable}s.
11469 *
11470 * <p>The map created by an {@code evictingMapFactory} must be thread-safe.
11471 *
11472 * <p>An example of an {@code evictingMapFactory} using <a href="https://google.github.io/guava/releases/24.0-jre/api/docs/com/google/common/cache/CacheBuilder.html">CacheBuilder</a> from the Guava library is below:
11473 *
11474 * <pre><code>
11475 * Function&lt;Consumer&lt;Object&gt;, Map&lt;Integer, Object&gt;&gt; evictingMapFactory =
11476 * notify -&gt;
11477 * CacheBuilder
11478 * .newBuilder()
11479 * .maximumSize(3)
11480 * .removalListener(entry -&gt; {
11481 * try {
11482 * // emit the value not the key!
11483 * notify.accept(entry.getValue());
11484 * } catch (Exception e) {
11485 * throw new RuntimeException(e);
11486 * }
11487 * })
11488 * .&lt;Integer, Object&gt; build()
11489 * .asMap();
11490 *
11491 * // Emit 1000 items but ensure that the
11492 * // internal map never has more than 3 items in it
11493 * Flowable
11494 * .range(1, 1000)
11495 * // note that number of keys is 10
11496 * .groupBy(x -&gt; x % 10, x -&gt; x, true, 16, evictingMapFactory)
11497 * .flatMap(g -&gt; g)
11498 * .forEach(System.out::println);
11499 * </code></pre>
11500 *
11501 * <p>
11502 * <img width="640" height="360" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/groupBy.v3.png" alt="">
11503 * <p>
11504 * <em>Note:</em> A {@code GroupedFlowable} will cache the items it is to emit until such time as it
11505 * is subscribed to. For this reason, in order to avoid memory leaks, you should not simply ignore those
11506 * {@code GroupedFlowable}s that do not concern you. Instead, you can signal to them that they may
11507 * discard their buffers by applying an operator like {@link #ignoreElements} to them.
11508 * <p>
11509 * Note that the {@code GroupedFlowable}s should be subscribed to as soon as possible, otherwise,
11510 * the unconsumed groups may starve other groups due to the internal backpressure
11511 * coordination of the {@code groupBy} operator. Such hangs can be usually avoided by using
11512 * {@link #flatMap(Function, int)} or {@link #concatMapEager(Function, int, int)} and overriding the default maximum concurrency
11513 * value to be greater or equal to the expected number of groups, possibly using
11514 * {@link Integer#MAX_VALUE} if the number of expected groups is unknown.
11515 * <p>
11516 * Note also that ignoring groups or subscribing later (i.e., on another thread) will result in
11517 * so-called group abandonment where a group will only contain one element and the group will be
11518 * re-created over and over as new upstream items trigger a new group. The behavior is
11519 * a trade-off between no-dataloss, upstream cancellation and excessive group creation.
11520 *
11521 * <dl>
11522 * <dt><b>Backpressure:</b></dt>
11523 * <dd>The consumer of the returned {@code Flowable} has to be ready to receive new {@code GroupedFlowable}s or else
11524 * this operator will signal {@link MissingBackpressureException}. To avoid this exception, make
11525 * sure a combining operator (such as {@code flatMap}) has adequate amount of buffering/prefetch configured.
11526 * The inner {@code GroupedFlowable}s honor backpressure but due to the single-source multiple consumer
11527 * nature of this operator, each group must be consumed so the whole operator can make progress and not hang.</dd>
11528 * <dt><b>Scheduler:</b></dt>
11529 * <dd>{@code groupBy} does not operate by default on a particular {@link Scheduler}.</dd>
11530 * <dt><b>Error handling:</b></dt>
11531 * <dd>If the upstream signals or the callback(s) throw an exception, the returned {@code Flowable} and
11532 * all active inner {@code GroupedFlowable}s will signal the same exception.</dd>
11533 * </dl>
11534 * <p>History: 2.1.10 - beta
11535 * @param keySelector
11536 * a function that extracts the key for each item
11537 * @param valueSelector
11538 * a function that extracts the return element for each item
11539 * @param delayError
11540 * if {@code true}, the exception from the current {@code Flowable} is delayed in each group until that specific group emitted
11541 * the normal values; if {@code false}, the exception bypasses values in the groups and is reported immediately.
11542 * @param bufferSize
11543 * the hint for how many {@code GroupedFlowable}s and element in each {@code GroupedFlowable} should be buffered
11544 * @param evictingMapFactory
11545 * The factory used to create a map that will be used by the implementation to hold the
11546 * {@code GroupedFlowable}s. The evicting map created by this factory must
11547 * notify the provided {@code Consumer<Object>} with the entry value (not the key!) when
11548 * an entry in this map has been evicted. The next source emission will bring about the
11549 * completion of the evicted {@code GroupedFlowable}s. See example above.
11550 * @param <K>
11551 * the key type
11552 * @param <V>
11553 * the element type
11554 * @return the new {@code Flowable} instance
11555 * @throws NullPointerException if {@code keySelector}, {@code valueSelector} or {@code evictingMapFactory} is {@code null}
11556 * @throws IllegalArgumentException if {@code bufferSize} is non-positive
11557 * @see <a href="http://reactivex.io/documentation/operators/groupby.html">ReactiveX operators documentation: GroupBy</a>
11558 *
11559 * @since 2.2
11560 */
11561 @CheckReturnValue
11562 @NonNull
11563 @BackpressureSupport(BackpressureKind.SPECIAL)
11564 @SchedulerSupport(SchedulerSupport.NONE)
11565 public final <@NonNull K, @NonNull V> Flowable<GroupedFlowable<K, V>> groupBy(@NonNull Function<? super T, ? extends K> keySelector,
11566 @NonNull Function<? super T, ? extends V> valueSelector,
11567 boolean delayError, int bufferSize,
11568 @NonNull Function<? super Consumer<Object>, ? extends Map<K, Object>> evictingMapFactory) {
11569 Objects.requireNonNull(keySelector, "keySelector is null");
11570 Objects.requireNonNull(valueSelector, "valueSelector is null");
11571 ObjectHelper.verifyPositive(bufferSize, "bufferSize");
11572 Objects.requireNonNull(evictingMapFactory, "evictingMapFactory is null");
11573
11574 return RxJavaPlugins.onAssembly(new FlowableGroupBy<>(this, keySelector, valueSelector, bufferSize, delayError, evictingMapFactory));
11575 }
11576
11577 /**
11578 * Returns a {@code Flowable} that correlates two {@link Publisher}s when they overlap in time and groups the results.
11579 * <p>
11580 * There are no guarantees in what order the items get combined when multiple
11581 * items from one or both source {@code Publisher}s overlap.
11582 * <p>
11583 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/groupJoin.v3.png" alt="">
11584 * <dl>
11585 * <dt><b>Backpressure:</b></dt>
11586 * <dd>The operator doesn't support backpressure and consumes all participating {@code Publisher}s in
11587 * an unbounded mode (i.e., not applying any backpressure to them).</dd>
11588 * <dt><b>Scheduler:</b></dt>
11589 * <dd>{@code groupJoin} does not operate by default on a particular {@link Scheduler}.</dd>
11590 * </dl>
11591 *
11592 * @param <TRight> the value type of the right {@code Publisher} source
11593 * @param <TLeftEnd> the element type of the left duration {@code Publisher}s
11594 * @param <TRightEnd> the element type of the right duration {@code Publisher}s
11595 * @param <R> the result type
11596 * @param other
11597 * the other {@code Publisher} to correlate items from the current {@code Flowable} with
11598 * @param leftEnd
11599 * a function that returns a {@code Publisher} whose emissions indicate the duration of the values of
11600 * the current {@code Flowable}
11601 * @param rightEnd
11602 * a function that returns a {@code Publisher} whose emissions indicate the duration of the values of
11603 * the {@code right} {@code Publisher}
11604 * @param resultSelector
11605 * a function that takes an item emitted by each {@code Publisher} and returns the value to be emitted
11606 * by the resulting {@code Flowable}
11607 * @return the new {@code Flowable} instance
11608 * @throws NullPointerException if {@code other}, {@code leftEnd}, {@code rightEnd} or {@code resultSelector} is {@code null}
11609 * @see <a href="http://reactivex.io/documentation/operators/join.html">ReactiveX operators documentation: Join</a>
11610 */
11611 @CheckReturnValue
11612 @NonNull
11613 @BackpressureSupport(BackpressureKind.ERROR)
11614 @SchedulerSupport(SchedulerSupport.NONE)
11615 public final <@NonNull TRight, @NonNull TLeftEnd, @NonNull TRightEnd, @NonNull R> Flowable<R> groupJoin(
11616 @NonNull Publisher<? extends TRight> other,
11617 @NonNull Function<? super T, @NonNull ? extends Publisher<TLeftEnd>> leftEnd,
11618 @NonNull Function<? super TRight, @NonNull ? extends Publisher<TRightEnd>> rightEnd,
11619 @NonNull BiFunction<? super T, ? super Flowable<TRight>, ? extends R> resultSelector) {
11620 Objects.requireNonNull(other, "other is null");
11621 Objects.requireNonNull(leftEnd, "leftEnd is null");
11622 Objects.requireNonNull(rightEnd, "rightEnd is null");
11623 Objects.requireNonNull(resultSelector, "resultSelector is null");
11624 return RxJavaPlugins.onAssembly(new FlowableGroupJoin<>(
11625 this, other, leftEnd, rightEnd, resultSelector));
11626 }
11627
11628 /**
11629 * Hides the identity of this {@code Flowable} and its {@link Subscription}.
11630 * <p>Allows hiding extra features such as {@link Processor}'s
11631 * {@link Subscriber} methods or preventing certain identity-based
11632 * optimizations (fusion).
11633 * <dl>
11634 * <dt><b>Backpressure:</b></dt>
11635 * <dd>The operator is a pass-through for backpressure, the behavior is determined by the upstream's
11636 * backpressure behavior.</dd>
11637 * <dt><b>Scheduler:</b></dt>
11638 * <dd>{@code hide} does not operate by default on a particular {@link Scheduler}.</dd>
11639 * </dl>
11640 * @return the new {@code Flowable} instance
11641 *
11642 * @since 2.0
11643 */
11644 @CheckReturnValue
11645 @BackpressureSupport(BackpressureKind.PASS_THROUGH)
11646 @SchedulerSupport(SchedulerSupport.NONE)
11647 @NonNull
11648 public final Flowable<T> hide() {
11649 return RxJavaPlugins.onAssembly(new FlowableHide<>(this));
11650 }
11651
11652 /**
11653 * Ignores all items emitted by the current {@code Flowable} and only calls {@code onComplete} or {@code onError}.
11654 * <p>
11655 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/ignoreElements.v3.png" alt="">
11656 * <dl>
11657 * <dt><b>Backpressure:</b></dt>
11658 * <dd>This operator ignores backpressure as it doesn't emit any elements and consumes the current {@code Flowable}
11659 * in an unbounded manner (i.e., no backpressure is applied to it).</dd>
11660 * <dt><b>Scheduler:</b></dt>
11661 * <dd>{@code ignoreElements} does not operate by default on a particular {@link Scheduler}.</dd>
11662 * </dl>
11663 *
11664 * @return the new {@link Completable} instance
11665 * @see <a href="http://reactivex.io/documentation/operators/ignoreelements.html">ReactiveX operators documentation: IgnoreElements</a>
11666 */
11667 @CheckReturnValue
11668 @BackpressureSupport(BackpressureKind.UNBOUNDED_IN)
11669 @SchedulerSupport(SchedulerSupport.NONE)
11670 @NonNull
11671 public final Completable ignoreElements() {
11672 return RxJavaPlugins.onAssembly(new FlowableIgnoreElementsCompletable<>(this));
11673 }
11674
11675 /**
11676 * Returns a {@link Single} that emits {@code true} if the current {@code Flowable} is empty, otherwise {@code false}.
11677 * <p>
11678 * In Rx.Net this is negated as the {@code any} {@link Subscriber} but we renamed this in RxJava to better match Java
11679 * naming idioms.
11680 * <p>
11681 * <img width="640" height="320" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/isEmpty.v3.png" alt="">
11682 * <dl>
11683 * <dt><b>Backpressure:</b></dt>
11684 * <dd>The operator honors backpressure from downstream and consumes the current {@code Flowable} in an
11685 * unbounded manner (i.e., without applying backpressure).</dd>
11686 * <dt><b>Scheduler:</b></dt>
11687 * <dd>{@code isEmpty} does not operate by default on a particular {@link Scheduler}.</dd>
11688 * </dl>
11689 *
11690 * @return the new {@code Single} instance
11691 * @see <a href="http://reactivex.io/documentation/operators/contains.html">ReactiveX operators documentation: Contains</a>
11692 */
11693 @CheckReturnValue
11694 @BackpressureSupport(BackpressureKind.UNBOUNDED_IN)
11695 @SchedulerSupport(SchedulerSupport.NONE)
11696 @NonNull
11697 public final Single<Boolean> isEmpty() {
11698 return all(Functions.alwaysFalse());
11699 }
11700
11701 /**
11702 * Correlates the items emitted by two {@link Publisher}s based on overlapping durations.
11703 * <p>
11704 * There are no guarantees in what order the items get combined when multiple
11705 * items from one or both source {@code Publisher}s overlap.
11706 * <p>
11707 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/join_.v3.png" alt="">
11708 * <dl>
11709 * <dt><b>Backpressure:</b></dt>
11710 * <dd>The operator doesn't support backpressure and consumes all participating {@code Publisher}s in
11711 * an unbounded mode (i.e., not applying any backpressure to them).</dd>
11712 * <dt><b>Scheduler:</b></dt>
11713 * <dd>{@code join} does not operate by default on a particular {@link Scheduler}.</dd>
11714 * </dl>
11715 *
11716 * @param <TRight> the value type of the right {@code Publisher} source
11717 * @param <TLeftEnd> the element type of the left duration {@code Publisher}s
11718 * @param <TRightEnd> the element type of the right duration {@code Publisher}s
11719 * @param <R> the result type
11720 * @param other
11721 * the second {@code Publisher} to join items from
11722 * @param leftEnd
11723 * a function to select a duration for each item emitted by the current {@code Flowable}, used to
11724 * determine overlap
11725 * @param rightEnd
11726 * a function to select a duration for each item emitted by the {@code right} {@code Publisher}, used to
11727 * determine overlap
11728 * @param resultSelector
11729 * a function that computes an item to be emitted by the resulting {@code Flowable} for any two
11730 * overlapping items emitted by the two {@code Publisher}s
11731 * @return the new {@code Flowable} instance
11732 * @throws NullPointerException if {@code other}, {@code leftEnd}, {@code rightEnd} or {@code resultSelector} is {@code null}
11733 * @see <a href="http://reactivex.io/documentation/operators/join.html">ReactiveX operators documentation: Join</a>
11734 */
11735 @CheckReturnValue
11736 @NonNull
11737 @BackpressureSupport(BackpressureKind.ERROR)
11738 @SchedulerSupport(SchedulerSupport.NONE)
11739 public final <@NonNull TRight, @NonNull TLeftEnd, @NonNull TRightEnd, @NonNull R> Flowable<R> join(
11740 @NonNull Publisher<? extends TRight> other,
11741 @NonNull Function<? super T, @NonNull ? extends Publisher<TLeftEnd>> leftEnd,
11742 @NonNull Function<? super TRight, @NonNull ? extends Publisher<TRightEnd>> rightEnd,
11743 @NonNull BiFunction<? super T, ? super TRight, ? extends R> resultSelector) {
11744 Objects.requireNonNull(other, "other is null");
11745 Objects.requireNonNull(leftEnd, "leftEnd is null");
11746 Objects.requireNonNull(rightEnd, "rightEnd is null");
11747 Objects.requireNonNull(resultSelector, "resultSelector is null");
11748 return RxJavaPlugins.onAssembly(new FlowableJoin<T, TRight, TLeftEnd, TRightEnd, R>(
11749 this, other, leftEnd, rightEnd, resultSelector));
11750 }
11751
11752 /**
11753 * Returns a {@link Maybe} that emits the last item emitted by this {@code Flowable} or completes if
11754 * this {@code Flowable} is empty.
11755 * <p>
11756 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/last.v3.png" alt="">
11757 * <dl>
11758 * <dt><b>Backpressure:</b></dt>
11759 * <dd>The operator honors backpressure from downstream and consumes the current {@code Flowable} in an
11760 * unbounded manner (i.e., without applying backpressure).</dd>
11761 * <dt><b>Scheduler:</b></dt>
11762 * <dd>{@code lastElement} does not operate by default on a particular {@link Scheduler}.</dd>
11763 * </dl>
11764 *
11765 * @return the new {@code Maybe} instance
11766 * @see <a href="http://reactivex.io/documentation/operators/last.html">ReactiveX operators documentation: Last</a>
11767 */
11768 @CheckReturnValue
11769 @BackpressureSupport(BackpressureKind.UNBOUNDED_IN)
11770 @SchedulerSupport(SchedulerSupport.NONE)
11771 @NonNull
11772 public final Maybe<T> lastElement() {
11773 return RxJavaPlugins.onAssembly(new FlowableLastMaybe<>(this));
11774 }
11775
11776 /**
11777 * Returns a {@link Single} that emits only the last item emitted by this {@code Flowable}, or a default item
11778 * if this {@code Flowable} completes without emitting any items.
11779 * <p>
11780 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/lastOrDefault.v3.png" alt="">
11781 * <dl>
11782 * <dt><b>Backpressure:</b></dt>
11783 * <dd>The operator honors backpressure from downstream and consumes the current {@code Flowable} in an
11784 * unbounded manner (i.e., without applying backpressure).</dd>
11785 * <dt><b>Scheduler:</b></dt>
11786 * <dd>{@code last} does not operate by default on a particular {@link Scheduler}.</dd>
11787 * </dl>
11788 *
11789 * @param defaultItem
11790 * the default item to emit if the current {@code Flowable} is empty
11791 * @return the new {@code Single} instance
11792 * @throws NullPointerException if {@code defaultItem} is {@code null}
11793 * @see <a href="http://reactivex.io/documentation/operators/last.html">ReactiveX operators documentation: Last</a>
11794 */
11795 @CheckReturnValue
11796 @NonNull
11797 @BackpressureSupport(BackpressureKind.UNBOUNDED_IN)
11798 @SchedulerSupport(SchedulerSupport.NONE)
11799 public final Single<T> last(@NonNull T defaultItem) {
11800 Objects.requireNonNull(defaultItem, "defaultItem is null");
11801 return RxJavaPlugins.onAssembly(new FlowableLastSingle<>(this, defaultItem));
11802 }
11803
11804 /**
11805 * Returns a {@link Single} that emits only the last item emitted by this {@code Flowable} or signals
11806 * a {@link NoSuchElementException} if this {@code Flowable} is empty.
11807 * <p>
11808 * <img width="640" height="236" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/lastOrError.png" alt="">
11809 * <dl>
11810 * <dt><b>Backpressure:</b></dt>
11811 * <dd>The operator honors backpressure from downstream and consumes the current {@code Flowable} in an
11812 * unbounded manner (i.e., without applying backpressure).</dd>
11813 * <dt><b>Scheduler:</b></dt>
11814 * <dd>{@code lastOrError} does not operate by default on a particular {@link Scheduler}.</dd>
11815 * </dl>
11816 *
11817 * @return the new {@code Single} instance
11818 * @see <a href="http://reactivex.io/documentation/operators/last.html">ReactiveX operators documentation: Last</a>
11819 */
11820 @CheckReturnValue
11821 @BackpressureSupport(BackpressureKind.UNBOUNDED_IN)
11822 @SchedulerSupport(SchedulerSupport.NONE)
11823 @NonNull
11824 public final Single<T> lastOrError() {
11825 return RxJavaPlugins.onAssembly(new FlowableLastSingle<>(this, null));
11826 }
11827
11828 /**
11829 * <strong>This method requires advanced knowledge about building operators, please consider
11830 * other standard composition methods first;</strong>
11831 * Returns a {@code Flowable} which, when subscribed to, invokes the {@link FlowableOperator#apply(Subscriber) apply(Subscriber)} method
11832 * of the provided {@link FlowableOperator} for each individual downstream {@link Subscriber} and allows the
11833 * insertion of a custom operator by accessing the downstream's {@code Subscriber} during this subscription phase
11834 * and providing a new {@code Subscriber}, containing the custom operator's intended business logic, that will be
11835 * used in the subscription process going further upstream.
11836 * <p>
11837 * Generally, such a new {@code Subscriber} will wrap the downstream's {@code Subscriber} and forwards the
11838 * {@code onNext}, {@code onError} and {@code onComplete} events from the upstream directly or according to the
11839 * emission pattern the custom operator's business logic requires. In addition, such operator can intercept the
11840 * flow control calls of {@code cancel} and {@code request} that would have traveled upstream and perform
11841 * additional actions depending on the same business logic requirements.
11842 * <p>
11843 * Example:
11844 * <pre><code>
11845 * // Step 1: Create the consumer type that will be returned by the FlowableOperator.apply():
11846 *
11847 * public final class CustomSubscriber&lt;T&gt; implements FlowableSubscriber&lt;T&gt;, Subscription {
11848 *
11849 * // The downstream's Subscriber that will receive the onXXX events
11850 * final Subscriber&lt;? super String&gt; downstream;
11851 *
11852 * // The connection to the upstream source that will call this class' onXXX methods
11853 * Subscription upstream;
11854 *
11855 * // The constructor takes the downstream subscriber and usually any other parameters
11856 * public CustomSubscriber(Subscriber&lt;? super String&gt; downstream) {
11857 * this.downstream = downstream;
11858 * }
11859 *
11860 * // In the subscription phase, the upstream sends a Subscription to this class
11861 * // and subsequently this class has to send a Subscription to the downstream.
11862 * // Note that relaying the upstream's Subscription instance directly is not allowed in RxJava
11863 * &#64;Override
11864 * public void onSubscribe(Subscription s) {
11865 * if (upstream != null) {
11866 * s.cancel();
11867 * } else {
11868 * upstream = s;
11869 * downstream.onSubscribe(this);
11870 * }
11871 * }
11872 *
11873 * // The upstream calls this with the next item and the implementation's
11874 * // responsibility is to emit an item to the downstream based on the intended
11875 * // business logic, or if it can't do so for the particular item,
11876 * // request more from the upstream
11877 * &#64;Override
11878 * public void onNext(T item) {
11879 * String str = item.toString();
11880 * if (str.length() &lt; 2) {
11881 * downstream.onNext(str);
11882 * } else {
11883 * upstream.request(1);
11884 * }
11885 * }
11886 *
11887 * // Some operators may handle the upstream's error while others
11888 * // could just forward it to the downstream.
11889 * &#64;Override
11890 * public void onError(Throwable throwable) {
11891 * downstream.onError(throwable);
11892 * }
11893 *
11894 * // When the upstream completes, usually the downstream should complete as well.
11895 * &#64;Override
11896 * public void onComplete() {
11897 * downstream.onComplete();
11898 * }
11899 *
11900 * // Some operators have to intercept the downstream's request calls to trigger
11901 * // the emission of queued items while others can simply forward the request
11902 * // amount as is.
11903 * &#64;Override
11904 * public void request(long n) {
11905 * upstream.request(n);
11906 * }
11907 *
11908 * // Some operators may use their own resources which should be cleaned up if
11909 * // the downstream cancels the flow before it completed. Operators without
11910 * // resources can simply forward the cancellation to the upstream.
11911 * // In some cases, a canceled flag may be set by this method so that other parts
11912 * // of this class may detect the cancellation and stop sending events
11913 * // to the downstream.
11914 * &#64;Override
11915 * public void cancel() {
11916 * upstream.cancel();
11917 * }
11918 * }
11919 *
11920 * // Step 2: Create a class that implements the FlowableOperator interface and
11921 * // returns the custom consumer type from above in its apply() method.
11922 * // Such class may define additional parameters to be submitted to
11923 * // the custom consumer type.
11924 *
11925 * final class CustomOperator&lt;T&gt; implements FlowableOperator&lt;String&gt; {
11926 * &#64;Override
11927 * public Subscriber&lt;? super String&gt; apply(Subscriber&lt;? super T&gt; upstream) {
11928 * return new CustomSubscriber&lt;T&gt;(upstream);
11929 * }
11930 * }
11931 *
11932 * // Step 3: Apply the custom operator via lift() in a flow by creating an instance of it
11933 * // or reusing an existing one.
11934 *
11935 * Flowable.range(5, 10)
11936 * .lift(new CustomOperator&lt;Integer&gt;())
11937 * .test()
11938 * .assertResult("5", "6", "7", "8", "9");
11939 * </code></pre>
11940 * <p>
11941 * Creating custom operators can be complicated and it is recommended one consults the
11942 * <a href="https://github.com/ReactiveX/RxJava/wiki/Writing-operators-for-2.0">RxJava wiki: Writing operators</a> page about
11943 * the tools, requirements, rules, considerations and pitfalls of implementing them.
11944 * <p>
11945 * Note that implementing custom operators via this {@code lift()} method adds slightly more overhead by requiring
11946 * an additional allocation and indirection per assembled flows. Instead, extending the abstract {@code Flowable}
11947 * class and creating a {@link FlowableTransformer} with it is recommended.
11948 * <p>
11949 * Note also that it is not possible to stop the subscription phase in {@code lift()} as the {@code apply()} method
11950 * requires a non-{@code null} {@code Subscriber} instance to be returned, which is then unconditionally subscribed to
11951 * the upstream {@code Flowable}. For example, if the operator decided there is no reason to subscribe to the
11952 * upstream source because of some optimization possibility or a failure to prepare the operator, it still has to
11953 * return a {@code Subscriber} that should immediately cancel the upstream's {@link Subscription} in its
11954 * {@code onSubscribe} method. Again, using a {@code FlowableTransformer} and extending the {@code Flowable} is
11955 * a better option as {@link #subscribeActual} can decide to not subscribe to its upstream after all.
11956 * <dl>
11957 * <dt><b>Backpressure:</b></dt>
11958 * <dd>The {@code Subscriber} instance returned by the {@code FlowableOperator} is responsible to be
11959 * backpressure-aware or document the fact that the consumer of the returned {@link Publisher} has to apply one of
11960 * the {@code onBackpressureXXX} operators.</dd>
11961 * <dt><b>Scheduler:</b></dt>
11962 * <dd>{@code lift} does not operate by default on a particular {@link Scheduler}, however, the
11963 * {@code FlowableOperator} may use a {@code Scheduler} to support its own asynchronous behavior.</dd>
11964 * </dl>
11965 *
11966 * @param <R> the output value type
11967 * @param lifter the {@code FlowableOperator} that receives the downstream's {@code Subscriber} and should return
11968 * a {@code Subscriber} with custom behavior to be used as the consumer for the current
11969 * {@code Flowable}.
11970 * @return the new {@code Flowable} instance
11971 * @throws NullPointerException if {@code lifter} is {@code null}
11972 * @see <a href="https://github.com/ReactiveX/RxJava/wiki/Writing-operators-for-2.0">RxJava wiki: Writing operators</a>
11973 * @see #compose(FlowableTransformer)
11974 */
11975 @CheckReturnValue
11976 @NonNull
11977 @BackpressureSupport(BackpressureKind.SPECIAL)
11978 @SchedulerSupport(SchedulerSupport.NONE)
11979 public final <@NonNull R> Flowable<R> lift(@NonNull FlowableOperator<? extends R, ? super T> lifter) {
11980 Objects.requireNonNull(lifter, "lifter is null");
11981 return RxJavaPlugins.onAssembly(new FlowableLift<>(this, lifter));
11982 }
11983
11984 /**
11985 * Returns a {@code Flowable} that applies a specified function to each item emitted by the current {@code Flowable} and
11986 * emits the results of these function applications.
11987 * <p>
11988 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/map.v3.png" alt="">
11989 * <dl>
11990 * <dt><b>Backpressure:</b></dt>
11991 * <dd>The operator doesn't interfere with backpressure which is determined by the current {@code Flowable}'s backpressure
11992 * behavior.</dd>
11993 * <dt><b>Scheduler:</b></dt>
11994 * <dd>{@code map} does not operate by default on a particular {@link Scheduler}.</dd>
11995 * </dl>
11996 *
11997 * @param <R> the output type
11998 * @param mapper
11999 * a function to apply to each item emitted by the current {@code Flowable}
12000 * @return the new {@code Flowable} instance
12001 * @throws NullPointerException if {@code mapper} is {@code null}
12002 * @see <a href="http://reactivex.io/documentation/operators/map.html">ReactiveX operators documentation: Map</a>
12003 * @see #mapOptional(Function)
12004 */
12005 @CheckReturnValue
12006 @NonNull
12007 @BackpressureSupport(BackpressureKind.PASS_THROUGH)
12008 @SchedulerSupport(SchedulerSupport.NONE)
12009 public final <@NonNull R> Flowable<R> map(@NonNull Function<? super T, ? extends R> mapper) {
12010 Objects.requireNonNull(mapper, "mapper is null");
12011 return RxJavaPlugins.onAssembly(new FlowableMap<>(this, mapper));
12012 }
12013
12014 /**
12015 * Returns a {@code Flowable} that represents all of the emissions <em>and</em> notifications from the current
12016 * {@code Flowable} into emissions marked with their original types within {@link Notification} objects.
12017 * <p>
12018 * <img width="640" height="315" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/materialize.v3.png" alt="">
12019 * <dl>
12020 * <dt><b>Backpressure:</b></dt>
12021 * <dd>The operator honors backpressure from downstream and expects it from the current {@code Flowable}.
12022 * If this expectation is violated, the operator <em>may</em> throw an {@link IllegalStateException}.</dd>
12023 * <dt><b>Scheduler:</b></dt>
12024 * <dd>{@code materialize} does not operate by default on a particular {@link Scheduler}.</dd>
12025 * </dl>
12026 *
12027 * @return the new {@code Flowable} instance
12028 * @see <a href="http://reactivex.io/documentation/operators/materialize-dematerialize.html">ReactiveX operators documentation: Materialize</a>
12029 * @see #dematerialize(Function)
12030 */
12031 @CheckReturnValue
12032 @BackpressureSupport(BackpressureKind.FULL)
12033 @SchedulerSupport(SchedulerSupport.NONE)
12034 @NonNull
12035 public final Flowable<Notification<T>> materialize() {
12036 return RxJavaPlugins.onAssembly(new FlowableMaterialize<>(this));
12037 }
12038
12039 /**
12040 * Flattens this and another {@link Publisher} into a single {@code Publisher}, without any transformation.
12041 * <p>
12042 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/merge.v3.png" alt="">
12043 * <p>
12044 * You can combine items emitted by multiple {@code Publisher}s so that they appear as a single {@code Publisher}, by
12045 * using the {@code mergeWith} method.
12046 * <dl>
12047 * <dt><b>Backpressure:</b></dt>
12048 * <dd>The operator honors backpressure from downstream. This and the other {@code Publisher}s are expected to honor
12049 * backpressure; if violated, the operator <em>may</em> signal {@link MissingBackpressureException}.</dd>
12050 * <dt><b>Scheduler:</b></dt>
12051 * <dd>{@code mergeWith} does not operate by default on a particular {@link Scheduler}.</dd>
12052 * </dl>
12053 *
12054 * @param other
12055 * a {@code Publisher} to be merged
12056 * @return the new {@code Flowable} instance
12057 * @throws NullPointerException if {@code other} is {@code null}
12058 * @see <a href="http://reactivex.io/documentation/operators/merge.html">ReactiveX operators documentation: Merge</a>
12059 */
12060 @CheckReturnValue
12061 @NonNull
12062 @BackpressureSupport(BackpressureKind.FULL)
12063 @SchedulerSupport(SchedulerSupport.NONE)
12064 public final Flowable<T> mergeWith(@NonNull Publisher<? extends T> other) {
12065 Objects.requireNonNull(other, "other is null");
12066 return merge(this, other);
12067 }
12068
12069 /**
12070 * Merges the sequence of items of this {@code Flowable} with the success value of the other {@link SingleSource}.
12071 * <p>
12072 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/merge.v3.png" alt="">
12073 * <p>
12074 * The success value of the other {@code SingleSource} can get interleaved at any point of this
12075 * {@code Flowable} sequence.
12076 * <dl>
12077 * <dt><b>Backpressure:</b></dt>
12078 * <dd>The operator honors backpressure from downstream and ensures the success item from the
12079 * {@code SingleSource} is emitted only when there is a downstream demand.</dd>
12080 * <dt><b>Scheduler:</b></dt>
12081 * <dd>{@code mergeWith} does not operate by default on a particular {@link Scheduler}.</dd>
12082 * </dl>
12083 * <p>History: 2.1.10 - experimental
12084 * @param other the {@code SingleSource} whose success value to merge with
12085 * @return the new {@code Flowable} instance
12086 * @throws NullPointerException if {@code other} is {@code null}
12087 * @since 2.2
12088 */
12089 @CheckReturnValue
12090 @NonNull
12091 @BackpressureSupport(BackpressureKind.FULL)
12092 @SchedulerSupport(SchedulerSupport.NONE)
12093 public final Flowable<T> mergeWith(@NonNull SingleSource<? extends T> other) {
12094 Objects.requireNonNull(other, "other is null");
12095 return RxJavaPlugins.onAssembly(new FlowableMergeWithSingle<>(this, other));
12096 }
12097
12098 /**
12099 * Merges the sequence of items of this {@code Flowable} with the success value of the other {@link MaybeSource}
12100 * or waits for both to complete normally if the {@code MaybeSource} is empty.
12101 * <p>
12102 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/merge.v3.png" alt="">
12103 * <p>
12104 * The success value of the other {@code MaybeSource} can get interleaved at any point of this
12105 * {@code Flowable} sequence.
12106 * <dl>
12107 * <dt><b>Backpressure:</b></dt>
12108 * <dd>The operator honors backpressure from downstream and ensures the success item from the
12109 * {@code MaybeSource} is emitted only when there is a downstream demand.</dd>
12110 * <dt><b>Scheduler:</b></dt>
12111 * <dd>{@code mergeWith} does not operate by default on a particular {@link Scheduler}.</dd>
12112 * </dl>
12113 * <p>History: 2.1.10 - experimental
12114 * @param other the {@code MaybeSource} which provides a success value to merge with or completes
12115 * @return the new {@code Flowable} instance
12116 * @throws NullPointerException if {@code other} is {@code null}
12117 * @since 2.2
12118 */
12119 @CheckReturnValue
12120 @NonNull
12121 @BackpressureSupport(BackpressureKind.FULL)
12122 @SchedulerSupport(SchedulerSupport.NONE)
12123 public final Flowable<T> mergeWith(@NonNull MaybeSource<? extends T> other) {
12124 Objects.requireNonNull(other, "other is null");
12125 return RxJavaPlugins.onAssembly(new FlowableMergeWithMaybe<>(this, other));
12126 }
12127
12128 /**
12129 * Relays the items of this {@code Flowable} and completes only when the other {@link CompletableSource} completes
12130 * as well.
12131 * <p>
12132 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/merge.v3.png" alt="">
12133 * <dl>
12134 * <dt><b>Backpressure:</b></dt>
12135 * <dd>The operator doesn't interfere with backpressure which is determined by the current {@code Flowable}'s backpressure
12136 * behavior.</dd>
12137 * <dt><b>Scheduler:</b></dt>
12138 * <dd>{@code mergeWith} does not operate by default on a particular {@link Scheduler}.</dd>
12139 * </dl>
12140 * <p>History: 2.1.10 - experimental
12141 * @param other the {@code CompletableSource} to await for completion
12142 * @return the new {@code Flowable} instance
12143 * @throws NullPointerException if {@code other} is {@code null}
12144 * @since 2.2
12145 */
12146 @CheckReturnValue
12147 @NonNull
12148 @BackpressureSupport(BackpressureKind.PASS_THROUGH)
12149 @SchedulerSupport(SchedulerSupport.NONE)
12150 public final Flowable<T> mergeWith(@NonNull CompletableSource other) {
12151 Objects.requireNonNull(other, "other is null");
12152 return RxJavaPlugins.onAssembly(new FlowableMergeWithCompletable<>(this, other));
12153 }
12154
12155 /**
12156 * Signals the items and terminal signals of the current {@code Flowable} on the specified {@link Scheduler},
12157 * asynchronously with a bounded buffer of {@link #bufferSize()} slots.
12158 *
12159 * <p>Note that {@code onError} notifications will cut ahead of {@code onNext} notifications on the emission thread if {@code Scheduler} is truly
12160 * asynchronous. If strict event ordering is required, consider using the {@link #observeOn(Scheduler, boolean)} overload.
12161 * <p>
12162 * <img width="640" height="308" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/observeOn.v3.png" alt="">
12163 * <p>
12164 * This operator keeps emitting as many signals as it can on the given {@code Scheduler}'s Worker thread,
12165 * which may result in a longer than expected occupation of this thread. In other terms,
12166 * it does not allow per-signal fairness in case the worker runs on a shared underlying thread.
12167 * If such fairness and signal/work interleaving is preferred, use the delay operator with zero time instead.
12168 * <dl>
12169 * <dt><b>Backpressure:</b></dt>
12170 * <dd>This operator honors backpressure from downstream and expects it from the current {@code Flowable}. Violating this
12171 * expectation will lead to {@link MissingBackpressureException}. This is the most common operator where the exception
12172 * pops up; look for sources up the chain that don't support backpressure,
12173 * such as {@link #interval(long, TimeUnit)}, {@link #timer(long, TimeUnit)},
12174 * {@link io.reactivex.rxjava3.processors.PublishProcessor PublishProcessor} or
12175 * {@link io.reactivex.rxjava3.processors.BehaviorProcessor BehaviorProcessor} and apply any
12176 * of the {@code onBackpressureXXX} operators <strong>before</strong> applying {@code observeOn} itself.
12177 * Note also that request amounts are not preserved between the immediate downstream and the
12178 * immediate upstream. The operator always requests the default {@link #bufferSize()} amount first, then after
12179 * every 75% of that amount delivered, another 75% of this default value. If preserving the request amounts
12180 * is to be preferred over potential excess scheduler infrastructure use, consider applying
12181 * {@link #delay(long, TimeUnit, Scheduler)} with zero time instead.
12182 * </dd>
12183 * <dt><b>Scheduler:</b></dt>
12184 * <dd>You specify which {@code Scheduler} this operator will use.</dd>
12185 * </dl>
12186 *
12187 * @param scheduler
12188 * the {@code Scheduler} to notify {@link Subscriber}s on
12189 * @return the new {@code Flowable} instance
12190 * @throws NullPointerException if {@code scheduler} is {@code null}
12191 * @see <a href="http://reactivex.io/documentation/operators/observeon.html">ReactiveX operators documentation: ObserveOn</a>
12192 * @see <a href="http://www.grahamlea.com/2014/07/rxjava-threading-examples/">RxJava Threading Examples</a>
12193 * @see #subscribeOn
12194 * @see #observeOn(Scheduler, boolean)
12195 * @see #observeOn(Scheduler, boolean, int)
12196 * @see #delay(long, TimeUnit, Scheduler)
12197 */
12198 @CheckReturnValue
12199 @BackpressureSupport(BackpressureKind.FULL)
12200 @SchedulerSupport(SchedulerSupport.CUSTOM)
12201 @NonNull
12202 public final Flowable<T> observeOn(@NonNull Scheduler scheduler) {
12203 return observeOn(scheduler, false, bufferSize());
12204 }
12205
12206 /**
12207 * Signals the items and terminal signals of the current {@code Flowable} on the specified {@link Scheduler},
12208 * asynchronously with a bounded buffer and optionally delays {@code onError} notifications.
12209 * <p>
12210 * <img width="640" height="308" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/observeOn.v3.png" alt="">
12211 * <p>
12212 * This operator keeps emitting as many signals as it can on the given {@code Scheduler}'s Worker thread,
12213 * which may result in a longer than expected occupation of this thread. In other terms,
12214 * it does not allow per-signal fairness in case the worker runs on a shared underlying thread.
12215 * If such fairness and signal/work interleaving is preferred, use the delay operator with zero time instead.
12216 * <dl>
12217 * <dt><b>Backpressure:</b></dt>
12218 * <dd>This operator honors backpressure from downstream and expects it from the current {@code Flowable}. Violating this
12219 * expectation will lead to {@link MissingBackpressureException}. This is the most common operator where the exception
12220 * pops up; look for sources up the chain that don't support backpressure,
12221 * such as {@link #interval(long, TimeUnit)}, {@link #timer(long, TimeUnit)},
12222 * {@link io.reactivex.rxjava3.processors.PublishProcessor PublishProcessor} or
12223 * {@link io.reactivex.rxjava3.processors.BehaviorProcessor BehaviorProcessor} and apply any
12224 * of the {@code onBackpressureXXX} operators <strong>before</strong> applying {@code observeOn} itself.
12225 * Note also that request amounts are not preserved between the immediate downstream and the
12226 * immediate upstream. The operator always requests the default {@link #bufferSize()} amount first, then after
12227 * every 75% of that amount delivered, another 75% of this default value. If preserving the request amounts
12228 * is to be preferred over potential excess scheduler infrastructure use, consider applying
12229 * {@link #delay(long, TimeUnit, Scheduler, boolean)} with zero time instead.
12230 * </dd>
12231 * <dt><b>Scheduler:</b></dt>
12232 * <dd>You specify which {@code Scheduler} this operator will use.</dd>
12233 * </dl>
12234 *
12235 * @param scheduler
12236 * the {@code Scheduler} to notify {@link Subscriber}s on
12237 * @param delayError
12238 * indicates if the {@code onError} notification may not cut ahead of {@code onNext} notification on the other side of the
12239 * scheduling boundary. If {@code true}, a sequence ending in {@code onError} will be replayed in the same order as was received
12240 * from upstream
12241 * @return the new {@code Flowable} instance
12242 * @throws NullPointerException if {@code scheduler} is {@code null}
12243 * @see <a href="http://reactivex.io/documentation/operators/observeon.html">ReactiveX operators documentation: ObserveOn</a>
12244 * @see <a href="http://www.grahamlea.com/2014/07/rxjava-threading-examples/">RxJava Threading Examples</a>
12245 * @see #subscribeOn
12246 * @see #observeOn(Scheduler)
12247 * @see #observeOn(Scheduler, boolean, int)
12248 * @see #delay(long, TimeUnit, Scheduler, boolean)
12249 */
12250 @CheckReturnValue
12251 @BackpressureSupport(BackpressureKind.FULL)
12252 @SchedulerSupport(SchedulerSupport.CUSTOM)
12253 @NonNull
12254 public final Flowable<T> observeOn(@NonNull Scheduler scheduler, boolean delayError) {
12255 return observeOn(scheduler, delayError, bufferSize());
12256 }
12257
12258 /**
12259 * Signals the items and terminal signals of the current {@code Flowable} on the specified {@link Scheduler},
12260 * asynchronously with a bounded buffer of configurable size and optionally delays {@code onError} notifications.
12261 * <p>
12262 * <img width="640" height="308" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/observeOn.v3.png" alt="">
12263 * <p>
12264 * This operator keeps emitting as many signals as it can on the given {@code Scheduler}'s Worker thread,
12265 * which may result in a longer than expected occupation of this thread. In other terms,
12266 * it does not allow per-signal fairness in case the worker runs on a shared underlying thread.
12267 * If such fairness and signal/work interleaving is preferred, use the delay operator with zero time instead.
12268 * <dl>
12269 * <dt><b>Backpressure:</b></dt>
12270 * <dd>This operator honors backpressure from downstream and expects it from the current {@code Flowable}. Violating this
12271 * expectation will lead to {@link MissingBackpressureException}. This is the most common operator where the exception
12272 * pops up; look for sources up the chain that don't support backpressure,
12273 * such as {@link #interval(long, TimeUnit)}, {@link #timer(long, TimeUnit)},
12274 * {@link io.reactivex.rxjava3.processors.PublishProcessor PublishProcessor} or
12275 * {@link io.reactivex.rxjava3.processors.BehaviorProcessor BehaviorProcessor} and apply any
12276 * of the {@code onBackpressureXXX} operators <strong>before</strong> applying {@code observeOn} itself.
12277 * Note also that request amounts are not preserved between the immediate downstream and the
12278 * immediate upstream. The operator always requests the specified {@code bufferSize} amount first, then after
12279 * every 75% of that amount delivered, another 75% of this specified value. If preserving the request amounts
12280 * is to be preferred over potential excess scheduler infrastructure use, consider applying
12281 * {@link #delay(long, TimeUnit, Scheduler, boolean)} with zero time instead.
12282 * </dd>
12283 * <dt><b>Scheduler:</b></dt>
12284 * <dd>You specify which {@code Scheduler} this operator will use.</dd>
12285 * </dl>
12286 *
12287 * @param scheduler
12288 * the {@code Scheduler} to notify {@link Subscriber}s on
12289 * @param delayError
12290 * indicates if the {@code onError} notification may not cut ahead of {@code onNext} notification on the other side of the
12291 * scheduling boundary. If {@code true}, a sequence ending in {@code onError} will be replayed in the same order as was received
12292 * from upstream
12293 * @param bufferSize the size of the buffer.
12294 * @return the new {@code Flowable} instance
12295 * @throws NullPointerException if {@code scheduler} is {@code null}
12296 * @throws IllegalArgumentException if {@code bufferSize} is non-positive
12297 * @see <a href="http://reactivex.io/documentation/operators/observeon.html">ReactiveX operators documentation: ObserveOn</a>
12298 * @see <a href="http://www.grahamlea.com/2014/07/rxjava-threading-examples/">RxJava Threading Examples</a>
12299 * @see #subscribeOn
12300 * @see #observeOn(Scheduler)
12301 * @see #observeOn(Scheduler, boolean)
12302 * @see #delay(long, TimeUnit, Scheduler, boolean)
12303 */
12304 @CheckReturnValue
12305 @NonNull
12306 @BackpressureSupport(BackpressureKind.FULL)
12307 @SchedulerSupport(SchedulerSupport.CUSTOM)
12308 public final Flowable<T> observeOn(@NonNull Scheduler scheduler, boolean delayError, int bufferSize) {
12309 Objects.requireNonNull(scheduler, "scheduler is null");
12310 ObjectHelper.verifyPositive(bufferSize, "bufferSize");
12311 return RxJavaPlugins.onAssembly(new FlowableObserveOn<>(this, scheduler, delayError, bufferSize));
12312 }
12313
12314 /**
12315 * Filters the items emitted by the current {@code Flowable}, only emitting those of the specified type.
12316 * <p>
12317 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/ofClass.v3.png" alt="">
12318 * <dl>
12319 * <dt><b>Backpressure:</b></dt>
12320 * <dd>The operator doesn't interfere with backpressure which is determined by the current {@code Flowable}'s backpressure
12321 * behavior.</dd>
12322 * <dt><b>Scheduler:</b></dt>
12323 * <dd>{@code ofType} does not operate by default on a particular {@link Scheduler}.</dd>
12324 * </dl>
12325 *
12326 * @param <U> the output type
12327 * @param clazz
12328 * the class type to filter the items emitted by the current {@code Flowable}
12329 * @return the new {@code Flowable} instance
12330 * @throws NullPointerException if {@code clazz} is {@code null}
12331 * @see <a href="http://reactivex.io/documentation/operators/filter.html">ReactiveX operators documentation: Filter</a>
12332 */
12333 @CheckReturnValue
12334 @NonNull
12335 @BackpressureSupport(BackpressureKind.PASS_THROUGH)
12336 @SchedulerSupport(SchedulerSupport.NONE)
12337 public final <@NonNull U> Flowable<U> ofType(@NonNull Class<U> clazz) {
12338 Objects.requireNonNull(clazz, "clazz is null");
12339 return filter(Functions.isInstanceOf(clazz)).cast(clazz);
12340 }
12341
12342 /**
12343 * Buffers an unlimited number of items from the current {@code Flowable} and allows it to emit as fast it can while allowing the
12344 * downstream to consume the items at its own place.
12345 * <p>
12346 * <img width="640" height="300" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/bp.obp.buffer.v3.png" alt="">
12347 * <p>
12348 * An error from the current {@code Flowable} will cut ahead of any unconsumed item. Use {@link #onBackpressureBuffer(boolean)}
12349 * to have the operator keep the original signal order.
12350 * <dl>
12351 * <dt><b>Backpressure:</b></dt>
12352 * <dd>The operator honors backpressure from downstream and consumes the current {@code Flowable} in an unbounded
12353 * manner (i.e., not applying backpressure to it).</dd>
12354 * <dt><b>Scheduler:</b></dt>
12355 * <dd>{@code onBackpressureBuffer} does not operate by default on a particular {@link Scheduler}.</dd>
12356 * </dl>
12357 *
12358 * @return the new {@code Flowable} instance
12359 * @see <a href="http://reactivex.io/documentation/operators/backpressure.html">ReactiveX operators documentation: backpressure operators</a>
12360 * @see #onBackpressureBuffer(boolean)
12361 */
12362 @CheckReturnValue
12363 @BackpressureSupport(BackpressureKind.UNBOUNDED_IN)
12364 @SchedulerSupport(SchedulerSupport.NONE)
12365 @NonNull
12366 public final Flowable<T> onBackpressureBuffer() {
12367 return onBackpressureBuffer(bufferSize(), false, true);
12368 }
12369
12370 /**
12371 * Buffers an unlimited number of items from the current {@code Flowable} and allows it to emit as fast it can while allowing the
12372 * downstream to consume the items at its own place, optionally delaying an error until all buffered items have been consumed.
12373 * <p>
12374 * <img width="640" height="300" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/bp.obp.buffer.v3.png" alt="">
12375 * <dl>
12376 * <dt><b>Backpressure:</b></dt>
12377 * <dd>The operator honors backpressure from downstream and consumes the current {@code Flowable} in an unbounded
12378 * manner (i.e., not applying backpressure to it).</dd>
12379 * <dt><b>Scheduler:</b></dt>
12380 * <dd>{@code onBackpressureBuffer} does not operate by default on a particular {@link Scheduler}.</dd>
12381 * </dl>
12382 * @param delayError
12383 * if {@code true}, an exception from the current {@code Flowable} is delayed until all buffered elements have been
12384 * consumed by the downstream; if {@code false}, an exception is immediately signaled to the downstream, skipping
12385 * any buffered element
12386 * @return the new {@code Flowable} instance
12387 * @see <a href="http://reactivex.io/documentation/operators/backpressure.html">ReactiveX operators documentation: backpressure operators</a>
12388 */
12389 @CheckReturnValue
12390 @BackpressureSupport(BackpressureKind.UNBOUNDED_IN)
12391 @SchedulerSupport(SchedulerSupport.NONE)
12392 @NonNull
12393 public final Flowable<T> onBackpressureBuffer(boolean delayError) {
12394 return onBackpressureBuffer(bufferSize(), delayError, true);
12395 }
12396
12397 /**
12398 * Buffers an limited number of items from the current {@code Flowable} and allows it to emit as fast it can while allowing the
12399 * downstream to consume the items at its own place, however, the resulting {@code Flowable} will signal a
12400 * {@link MissingBackpressureException} via {@code onError} as soon as the buffer's capacity is exceeded, dropping all undelivered
12401 * items, and canceling the flow.
12402 * <p>
12403 * <img width="640" height="300" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/bp.obp.buffer.v3.png" alt="">
12404 * <p>
12405 * An error from the current {@code Flowable} will cut ahead of any unconsumed item. Use {@link #onBackpressureBuffer(int, boolean)}
12406 * to have the operator keep the original signal order.
12407 * <dl>
12408 * <dt><b>Backpressure:</b></dt>
12409 * <dd>The operator honors backpressure from downstream and consumes the current {@code Flowable} in an unbounded
12410 * manner (i.e., not applying backpressure to it).</dd>
12411 * <dt><b>Scheduler:</b></dt>
12412 * <dd>{@code onBackpressureBuffer} does not operate by default on a particular {@link Scheduler}.</dd>
12413 * </dl>
12414 *
12415 * @param capacity number of slots available in the buffer.
12416 * @return the new {@code Flowable} instance
12417 * @throws IllegalArgumentException if {@code capacity} is non-positive
12418 * @see <a href="http://reactivex.io/documentation/operators/backpressure.html">ReactiveX operators documentation: backpressure operators</a>
12419 * @since 1.1.0
12420 * @see #onBackpressureBuffer(long, Action, BackpressureOverflowStrategy)
12421 */
12422 @CheckReturnValue
12423 @BackpressureSupport(BackpressureKind.ERROR)
12424 @SchedulerSupport(SchedulerSupport.NONE)
12425 @NonNull
12426 public final Flowable<T> onBackpressureBuffer(int capacity) {
12427 return onBackpressureBuffer(capacity, false, false);
12428 }
12429
12430 /**
12431 * Buffers an limited number of items from the current {@code Flowable} and allows it to emit as fast it can while allowing the
12432 * downstream to consume the items at its own place, however, the resulting {@code Flowable} will signal a
12433 * {@link MissingBackpressureException} via {@code onError} as soon as the buffer's capacity is exceeded, dropping all undelivered
12434 * items, and canceling the flow.
12435 * <p>
12436 * <img width="640" height="300" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/bp.obp.buffer.v3.png" alt="">
12437 * <dl>
12438 * <dt><b>Backpressure:</b></dt>
12439 * <dd>The operator honors backpressure from downstream and consumes the current {@code Flowable} in an unbounded
12440 * manner (i.e., not applying backpressure to it).</dd>
12441 * <dt><b>Scheduler:</b></dt>
12442 * <dd>{@code onBackpressureBuffer} does not operate by default on a particular {@link Scheduler}.</dd>
12443 * </dl>
12444 *
12445 * @param capacity number of slots available in the buffer.
12446 * @param delayError
12447 * if {@code true}, an exception from the current {@code Flowable} is delayed until all buffered elements have been
12448 * consumed by the downstream; if {@code false}, an exception is immediately signaled to the downstream, skipping
12449 * any buffered element
12450 * @return the new {@code Flowable} instance
12451 * @throws IllegalArgumentException if {@code capacity} is non-positive
12452 * @see <a href="http://reactivex.io/documentation/operators/backpressure.html">ReactiveX operators documentation: backpressure operators</a>
12453 * @since 1.1.0
12454 */
12455 @CheckReturnValue
12456 @BackpressureSupport(BackpressureKind.ERROR)
12457 @SchedulerSupport(SchedulerSupport.NONE)
12458 @NonNull
12459 public final Flowable<T> onBackpressureBuffer(int capacity, boolean delayError) {
12460 return onBackpressureBuffer(capacity, delayError, false);
12461 }
12462
12463 /**
12464 * Buffers an optionally unlimited number of items from the current {@code Flowable} and allows it to emit as fast it can while allowing the
12465 * downstream to consume the items at its own place.
12466 * If {@code unbounded} is {@code true}, the resulting {@code Flowable} will signal a
12467 * {@link MissingBackpressureException} via {@code onError} as soon as the buffer's capacity is exceeded, dropping all undelivered
12468 * items, and canceling the flow.
12469 * <p>
12470 * <img width="640" height="300" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/bp.obp.buffer.v3.png" alt="">
12471 * <dl>
12472 * <dt><b>Backpressure:</b></dt>
12473 * <dd>The operator honors backpressure from downstream and consumes the current {@code Flowable} in an unbounded
12474 * manner (i.e., not applying backpressure to it).</dd>
12475 * <dt><b>Scheduler:</b></dt>
12476 * <dd>{@code onBackpressureBuffer} does not operate by default on a particular {@link Scheduler}.</dd>
12477 * </dl>
12478 *
12479 * @param capacity number of slots available in the buffer.
12480 * @param delayError
12481 * if {@code true}, an exception from the current {@code Flowable} is delayed until all buffered elements have been
12482 * consumed by the downstream; if {@code false}, an exception is immediately signaled to the downstream, skipping
12483 * any buffered element
12484 * @param unbounded
12485 * if {@code true}, the capacity value is interpreted as the internal "island" size of the unbounded buffer
12486 * @return the new {@code Flowable} instance
12487 * @throws IllegalArgumentException if {@code capacity} is non-positive
12488 * @see <a href="http://reactivex.io/documentation/operators/backpressure.html">ReactiveX operators documentation: backpressure operators</a>
12489 * @since 1.1.0
12490 */
12491 @CheckReturnValue
12492 @BackpressureSupport(BackpressureKind.SPECIAL)
12493 @SchedulerSupport(SchedulerSupport.NONE)
12494 @NonNull
12495 public final Flowable<T> onBackpressureBuffer(int capacity, boolean delayError, boolean unbounded) {
12496 ObjectHelper.verifyPositive(capacity, "capacity");
12497 return RxJavaPlugins.onAssembly(new FlowableOnBackpressureBuffer<>(this, capacity, unbounded, delayError, Functions.EMPTY_ACTION));
12498 }
12499
12500 /**
12501 * Buffers an optionally unlimited number of items from the current {@code Flowable} and allows it to emit as fast it can while allowing the
12502 * downstream to consume the items at its own place.
12503 * If {@code unbounded} is {@code true}, the resulting {@code Flowable} will signal a
12504 * {@link MissingBackpressureException} via {@code onError} as soon as the buffer's capacity is exceeded, dropping all undelivered
12505 * items, canceling the flow and calling the {@code onOverflow} action.
12506 * <p>
12507 * <img width="640" height="300" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/bp.obp.buffer.v3.png" alt="">
12508 * <dl>
12509 * <dt><b>Backpressure:</b></dt>
12510 * <dd>The operator honors backpressure from downstream and consumes the current {@code Flowable} in an unbounded
12511 * manner (i.e., not applying backpressure to it).</dd>
12512 * <dt><b>Scheduler:</b></dt>
12513 * <dd>{@code onBackpressureBuffer} does not operate by default on a particular {@link Scheduler}.</dd>
12514 * </dl>
12515 *
12516 * @param capacity number of slots available in the buffer.
12517 * @param delayError
12518 * if {@code true}, an exception from the current {@code Flowable} is delayed until all buffered elements have been
12519 * consumed by the downstream; if {@code false}, an exception is immediately signaled to the downstream, skipping
12520 * any buffered element
12521 * @param unbounded
12522 * if {@code true}, the capacity value is interpreted as the internal "island" size of the unbounded buffer
12523 * @param onOverflow action to execute if an item needs to be buffered, but there are no available slots.
12524 * @return the new {@code Flowable} instance
12525 * @throws NullPointerException if {@code onOverflow} is {@code null}
12526 * @throws IllegalArgumentException if {@code capacity} is non-positive
12527 * @see <a href="http://reactivex.io/documentation/operators/backpressure.html">ReactiveX operators documentation: backpressure operators</a>
12528 * @since 1.1.0
12529 */
12530 @CheckReturnValue
12531 @NonNull
12532 @BackpressureSupport(BackpressureKind.SPECIAL)
12533 @SchedulerSupport(SchedulerSupport.NONE)
12534 public final Flowable<T> onBackpressureBuffer(int capacity, boolean delayError, boolean unbounded,
12535 @NonNull Action onOverflow) {
12536 Objects.requireNonNull(onOverflow, "onOverflow is null");
12537 ObjectHelper.verifyPositive(capacity, "capacity");
12538 return RxJavaPlugins.onAssembly(new FlowableOnBackpressureBuffer<>(this, capacity, unbounded, delayError, onOverflow));
12539 }
12540
12541 /**
12542 * Buffers an limited number of items from the current {@code Flowable} and allows it to emit as fast it can while allowing the
12543 * downstream to consume the items at its own place, however, the resulting {@code Flowable} will signal a
12544 * {@link MissingBackpressureException} via {@code onError} as soon as the buffer's capacity is exceeded, dropping all undelivered
12545 * items, canceling the flow and calling the {@code onOverflow} action.
12546 * <p>
12547 * <img width="640" height="300" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/bp.obp.buffer.v3.png" alt="">
12548 * <dl>
12549 * <dt><b>Backpressure:</b></dt>
12550 * <dd>The operator honors backpressure from downstream and consumes the current {@code Flowable} in an unbounded
12551 * manner (i.e., not applying backpressure to it).</dd>
12552 * <dt><b>Scheduler:</b></dt>
12553 * <dd>{@code onBackpressureBuffer} does not operate by default on a particular {@link Scheduler}.</dd>
12554 * </dl>
12555 *
12556 * @param capacity number of slots available in the buffer.
12557 * @param onOverflow action to execute if an item needs to be buffered, but there are no available slots. Null is allowed.
12558 * @return the new {@code Flowable} instance
12559 * @throws NullPointerException if {@code onOverflow} is {@code null}
12560 * @throws IllegalArgumentException if {@code capacity} is non-positive
12561 * @see <a href="http://reactivex.io/documentation/operators/backpressure.html">ReactiveX operators documentation: backpressure operators</a>
12562 * @since 1.1.0
12563 */
12564 @CheckReturnValue
12565 @BackpressureSupport(BackpressureKind.ERROR)
12566 @SchedulerSupport(SchedulerSupport.NONE)
12567 @NonNull
12568 public final Flowable<T> onBackpressureBuffer(int capacity, @NonNull Action onOverflow) {
12569 return onBackpressureBuffer(capacity, false, false, onOverflow);
12570 }
12571
12572 /**
12573 * Buffers an optionally unlimited number of items from the current {@code Flowable} and allows it to emit as fast it can while allowing the
12574 * downstream to consume the items at its own place.
12575 * The resulting {@code Flowable} will behave as determined by {@code overflowStrategy} if the buffer capacity is exceeded:
12576 * <ul>
12577 * <li>{@link BackpressureOverflowStrategy#ERROR} (default) will call {@code onError} dropping all undelivered items,
12578 * canceling the source, and notifying the producer with {@code onOverflow}. </li>
12579 * <li>{@link BackpressureOverflowStrategy#DROP_LATEST} will drop any new items emitted by the producer while
12580 * the buffer is full, without generating any {@code onError}. Each drop will, however, invoke {@code onOverflow}
12581 * to signal the overflow to the producer.</li>
12582 * <li>{@link BackpressureOverflowStrategy#DROP_OLDEST} will drop the oldest items in the buffer in order to make
12583 * room for newly emitted ones. Overflow will not generate an {@code onError}, but each drop will invoke
12584 * {@code onOverflow} to signal the overflow to the producer.</li>
12585 * </ul>
12586 *
12587 * <p>
12588 * <img width="640" height="300" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/bp.obp.buffer.v3.png" alt="">
12589 * <dl>
12590 * <dt><b>Backpressure:</b></dt>
12591 * <dd>The operator honors backpressure from downstream and consumes the current {@code Flowable} in an unbounded
12592 * manner (i.e., not applying backpressure to it).</dd>
12593 * <dt><b>Scheduler:</b></dt>
12594 * <dd>{@code onBackpressureBuffer} does not operate by default on a particular {@link Scheduler}.</dd>
12595 * </dl>
12596 *
12597 * @param capacity number of slots available in the buffer.
12598 * @param onOverflow action to execute if an item needs to be buffered, but there are no available slots, {@code null} is allowed.
12599 * @param overflowStrategy how should the resulting {@code Flowable} react to buffer overflows, {@code null} is not allowed.
12600 * @return the new {@code Flowable} instance
12601 * @throws NullPointerException if {@code onOverflow} or {@code overflowStrategy} is {@code null}
12602 * @throws IllegalArgumentException if {@code capacity} is non-positive
12603 * @see <a href="http://reactivex.io/documentation/operators/backpressure.html">ReactiveX operators documentation: backpressure operators</a>
12604 * @since 2.0
12605 */
12606 @CheckReturnValue
12607 @NonNull
12608 @BackpressureSupport(BackpressureKind.SPECIAL)
12609 @SchedulerSupport(SchedulerSupport.NONE)
12610 public final Flowable<T> onBackpressureBuffer(long capacity, @Nullable Action onOverflow, @NonNull BackpressureOverflowStrategy overflowStrategy) {
12611 Objects.requireNonNull(overflowStrategy, "overflowStrategy is null");
12612 ObjectHelper.verifyPositive(capacity, "capacity");
12613 return RxJavaPlugins.onAssembly(new FlowableOnBackpressureBufferStrategy<>(this, capacity, onOverflow, overflowStrategy));
12614 }
12615
12616 /**
12617 * Drops items from the current {@code Flowable} if the downstream is not ready to receive new items (indicated
12618 * by a lack of {@link Subscription#request(long)} calls from it).
12619 * <p>
12620 * <img width="640" height="245" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/bp.obp.drop.v3.png" alt="">
12621 * <p>
12622 * If the downstream request count hits 0 then the resulting {@code Flowable} will refrain from calling {@code onNext} until
12623 * the {@link Subscriber} invokes {@code request(n)} again to increase the request count.
12624 * <dl>
12625 * <dt><b>Backpressure:</b></dt>
12626 * <dd>The operator honors backpressure from downstream and consumes the current {@code Flowable} in an unbounded
12627 * manner (i.e., not applying backpressure to it).</dd>
12628 * <dt><b>Scheduler:</b></dt>
12629 * <dd>{@code onBackpressureDrop} does not operate by default on a particular {@link Scheduler}.</dd>
12630 * </dl>
12631 *
12632 * @return the new {@code Flowable} instance
12633 * @see <a href="http://reactivex.io/documentation/operators/backpressure.html">ReactiveX operators documentation: backpressure operators</a>
12634 */
12635 @CheckReturnValue
12636 @BackpressureSupport(BackpressureKind.UNBOUNDED_IN)
12637 @SchedulerSupport(SchedulerSupport.NONE)
12638 @NonNull
12639 public final Flowable<T> onBackpressureDrop() {
12640 return RxJavaPlugins.onAssembly(new FlowableOnBackpressureDrop<>(this));
12641 }
12642
12643 /**
12644 * Drops items from the current {@code Flowable} if the downstream is not ready to receive new items (indicated
12645 * by a lack of {@link Subscription#request(long)} calls from it) and calls the given {@link Consumer} with such
12646 * dropped items.
12647 * <p>
12648 * <img width="640" height="245" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/bp.obp.drop.v3.png" alt="">
12649 * <p>
12650 * If the downstream request count hits 0 then the resulting {@code Flowable} will refrain from calling {@code onNext} until
12651 * the {@link Subscriber} invokes {@code request(n)} again to increase the request count.
12652 * <dl>
12653 * <dt><b>Backpressure:</b></dt>
12654 * <dd>The operator honors backpressure from downstream and consumes the current {@code Flowable} in an unbounded
12655 * manner (i.e., not applying backpressure to it).</dd>
12656 * <dt><b>Scheduler:</b></dt>
12657 * <dd>{@code onBackpressureDrop} does not operate by default on a particular {@link Scheduler}.</dd>
12658 * </dl>
12659 *
12660 * @param onDrop the action to invoke for each item dropped, should be fast and should never block.
12661 * @return the new {@code Flowable} instance
12662 * @throws NullPointerException if {@code onDrop} is {@code null}
12663 * @see <a href="http://reactivex.io/documentation/operators/backpressure.html">ReactiveX operators documentation: backpressure operators</a>
12664 * @since 1.1.0
12665 */
12666 @CheckReturnValue
12667 @NonNull
12668 @BackpressureSupport(BackpressureKind.UNBOUNDED_IN)
12669 @SchedulerSupport(SchedulerSupport.NONE)
12670 public final Flowable<T> onBackpressureDrop(@NonNull Consumer<? super T> onDrop) {
12671 Objects.requireNonNull(onDrop, "onDrop is null");
12672 return RxJavaPlugins.onAssembly(new FlowableOnBackpressureDrop<>(this, onDrop));
12673 }
12674
12675 /**
12676 * Drops all but the latest item emitted by the current {@code Flowable} if the downstream is not ready to receive
12677 * new items (indicated by a lack of {@link Subscription#request(long)} calls from it) and emits this latest
12678 * item when the downstream becomes ready.
12679 * <p>
12680 * <img width="640" height="245" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/bp.obp.latest.v3.png" alt="">
12681 * <p>
12682 * Its behavior is logically equivalent to {@code blockingLatest()} with the exception that
12683 * the downstream is not blocking while requesting more values.
12684 * <p>
12685 * Note that if the current {@code Flowable} does support backpressure, this operator ignores that capability
12686 * and doesn't propagate any backpressure requests from downstream.
12687 * <p>
12688 * Note that due to the nature of how backpressure requests are propagated through subscribeOn/observeOn,
12689 * requesting more than 1 from downstream doesn't guarantee a continuous delivery of {@code onNext} events.
12690 * <dl>
12691 * <dt><b>Backpressure:</b></dt>
12692 * <dd>The operator honors backpressure from downstream and consumes the current {@code Flowable} in an unbounded
12693 * manner (i.e., not applying backpressure to it).</dd>
12694 * <dt><b>Scheduler:</b></dt>
12695 * <dd>{@code onBackpressureLatest} does not operate by default on a particular {@link Scheduler}.</dd>
12696 * </dl>
12697 *
12698 * @return the new {@code Flowable} instance
12699 * @since 1.1.0
12700 */
12701 @CheckReturnValue
12702 @BackpressureSupport(BackpressureKind.UNBOUNDED_IN)
12703 @SchedulerSupport(SchedulerSupport.NONE)
12704 @NonNull
12705 public final Flowable<T> onBackpressureLatest() {
12706 return RxJavaPlugins.onAssembly(new FlowableOnBackpressureLatest<>(this));
12707 }
12708
12709 /**
12710 * Reduces a sequence of two not emitted values via a function into a single value if the downstream is not ready to receive
12711 * new items (indicated by a lack of {@link Subscription#request(long)} calls from it) and emits this latest
12712 * item when the downstream becomes ready.
12713 * <p>
12714 * <img width="640" height="354" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Flowable.onBackpressureReduce.png" alt="">
12715 * <p>
12716 * Note that if the current {@code Flowable} does support backpressure, this operator ignores that capability
12717 * and doesn't propagate any backpressure requests from downstream.
12718 * <p>
12719 * Note that due to the nature of how backpressure requests are propagated through subscribeOn/observeOn,
12720 * requesting more than 1 from downstream doesn't guarantee a continuous delivery of {@code onNext} events.
12721 * <dl>
12722 * <dt><b>Backpressure:</b></dt>
12723 * <dd>The operator honors backpressure from downstream and consumes the current {@code Flowable} in an unbounded
12724 * manner (i.e., not applying backpressure to it).</dd>
12725 * <dt><b>Scheduler:</b></dt>
12726 * <dd>{@code onBackpressureReduce} does not operate by default on a particular {@link Scheduler}.</dd>
12727 * </dl>
12728 * <p>History: 3.0.9 - experimental
12729 * @param reducer the bi-function to call when there is more than one non-emitted value to downstream,
12730 * the first argument of the bi-function is previous item and the second one is currently
12731 * emitting from upstream
12732 * @return the new {@code Flowable} instance
12733 * @throws NullPointerException if {@code reducer} is {@code null}
12734 * @since 3.1.0
12735 * @see #onBackpressureReduce(Supplier, BiFunction)
12736 */
12737 @CheckReturnValue
12738 @BackpressureSupport(BackpressureKind.UNBOUNDED_IN)
12739 @SchedulerSupport(SchedulerSupport.NONE)
12740 @NonNull
12741 public final Flowable<T> onBackpressureReduce(@NonNull BiFunction<T, T, T> reducer) {
12742 Objects.requireNonNull(reducer, "reducer is null");
12743 return RxJavaPlugins.onAssembly(new FlowableOnBackpressureReduce<>(this, reducer));
12744 }
12745
12746 /**
12747 * Reduces upstream values into an aggregate value, provided by a supplier and combined via a reducer function,
12748 * while the downstream is not ready to receive items, then emits this aggregate value when the downstream becomes ready.
12749 * <p>
12750 * <img width="640" height="315" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Flowable.onBackpressureReduce.ff.png" alt="">
12751 * <p>
12752 * Note that even if the downstream is ready to receive an item, the upstream item will always be aggregated into the output type,
12753 * calling both the supplier and the reducer to produce the output value.
12754 * <p>
12755 * Note that if the current {@code Flowable} does support backpressure, this operator ignores that capability
12756 * and doesn't propagate any backpressure requests from downstream.
12757 * <p>
12758 * Note that due to the nature of how backpressure requests are propagated through subscribeOn/observeOn,
12759 * requesting more than 1 from downstream doesn't guarantee a continuous delivery of {@code onNext} events.
12760 * <dl>
12761 * <dt><b>Backpressure:</b></dt>
12762 * <dd>The operator honors backpressure from downstream and consumes the current {@code Flowable} in an unbounded
12763 * manner (i.e., not applying backpressure to it).</dd>
12764 * <dt><b>Scheduler:</b></dt>
12765 * <dd>{@code onBackpressureReduce} does not operate by default on a particular {@link Scheduler}.</dd>
12766 * </dl>
12767 * <p>History: 3.0.9 - experimental
12768 * @param <R> the aggregate type emitted when the downstream requests more items
12769 * @param supplier the factory to call to create new item of type R to pass it as the first argument to {@code reducer}.
12770 * It is called when previous returned value by {@code reducer} already sent to
12771 * downstream or the very first update from upstream received.
12772 * @param reducer the bi-function to call to reduce excessive updates which downstream is not ready to receive.
12773 * The first argument of type R is the object returned by {@code supplier} or result of previous
12774 * {@code reducer} invocation. The second argument of type T is the current update from upstream.
12775 * @return the new {@code Flowable} instance
12776 * @throws NullPointerException if {@code supplier} or {@code reducer} is {@code null}
12777 * @see #onBackpressureReduce(BiFunction)
12778 * @since 3.1.0
12779 */
12780 @CheckReturnValue
12781 @BackpressureSupport(BackpressureKind.UNBOUNDED_IN)
12782 @SchedulerSupport(SchedulerSupport.NONE)
12783 @NonNull
12784 public final <@NonNull R> Flowable<R> onBackpressureReduce(@NonNull Supplier<R> supplier, @NonNull BiFunction<R, ? super T, R> reducer) {
12785 Objects.requireNonNull(supplier, "supplier is null");
12786 Objects.requireNonNull(reducer, "reducer is null");
12787 return RxJavaPlugins.onAssembly(new FlowableOnBackpressureReduceWith<>(this, supplier, reducer));
12788 }
12789
12790 /**
12791 * Returns a {@code Flowable} instance that if the current {@code Flowable} emits an error, it will emit an {@code onComplete}
12792 * and swallow the throwable.
12793 * <p>
12794 * <img width="640" height="372" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Flowable.onErrorComplete.png" alt="">
12795 * <dl>
12796 * <dt><b>Backpressure:</b></dt>
12797 * <dd>The operator doesn't interfere with backpressure which is determined by the current {@code Flowable}'s backpressure
12798 * behavior.</dd>
12799 * <dt><b>Scheduler:</b></dt>
12800 * <dd>{@code onErrorComplete} does not operate by default on a particular {@link Scheduler}.</dd>
12801 * </dl>
12802 * @return the new {@code Flowable} instance
12803 * @since 3.0.0
12804 */
12805 @CheckReturnValue
12806 @SchedulerSupport(SchedulerSupport.NONE)
12807 @BackpressureSupport(BackpressureKind.PASS_THROUGH)
12808 @NonNull
12809 public final Flowable<T> onErrorComplete() {
12810 return onErrorComplete(Functions.alwaysTrue());
12811 }
12812
12813 /**
12814 * Returns a {@code Flowable} instance that if the current {@code Flowable} emits an error and the predicate returns
12815 * {@code true}, it will emit an {@code onComplete} and swallow the throwable.
12816 * <p>
12817 * <img width="640" height="201" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Flowable.onErrorComplete.f.png" alt="">
12818 * <dl>
12819 * <dt><b>Backpressure:</b></dt>
12820 * <dd>The operator doesn't interfere with backpressure which is determined by the current {@code Flowable}'s backpressure
12821 * behavior.</dd>
12822 * <dt><b>Scheduler:</b></dt>
12823 * <dd>{@code onErrorComplete} does not operate by default on a particular {@link Scheduler}.</dd>
12824 * </dl>
12825 * @param predicate the predicate to call when an {@link Throwable} is emitted which should return {@code true}
12826 * if the {@code Throwable} should be swallowed and replaced with an {@code onComplete}.
12827 * @return the new {@code Flowable} instance
12828 * @throws NullPointerException if {@code predicate} is {@code null}
12829 * @since 3.0.0
12830 */
12831 @CheckReturnValue
12832 @BackpressureSupport(BackpressureKind.PASS_THROUGH)
12833 @SchedulerSupport(SchedulerSupport.NONE)
12834 @NonNull
12835 public final Flowable<T> onErrorComplete(@NonNull Predicate<? super Throwable> predicate) {
12836 Objects.requireNonNull(predicate, "predicate is null");
12837
12838 return RxJavaPlugins.onAssembly(new FlowableOnErrorComplete<>(this, predicate));
12839 }
12840
12841 /**
12842 * Resumes the flow with a {@link Publisher} returned for the failure {@link Throwable} of the current {@code Flowable} by a
12843 * function instead of signaling the error via {@code onError}.
12844 * <p>
12845 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/onErrorResumeNext.v3.png" alt="">
12846 * <p>
12847 * By default, when a {@code Publisher} encounters an error that prevents it from emitting the expected item to
12848 * its {@link Subscriber}, the {@code Publisher} invokes its {@code Subscriber}'s {@code onError} method, and then quits
12849 * without invoking any more of its {@code Subscriber}'s methods. The {@code onErrorResumeNext} method changes this
12850 * behavior. If you pass a function that returns a {@code Publisher} ({@code resumeFunction}) to
12851 * {@code onErrorResumeNext}, if the original {@code Publisher} encounters an error, instead of invoking its
12852 * {@code Subscriber}'s {@code onError} method, it will instead relinquish control to the {@code Publisher} returned from
12853 * {@code resumeFunction}, which will invoke the {@code Subscriber}'s {@link Subscriber#onNext onNext} method if it is
12854 * able to do so. In such a case, because no {@code Publisher} necessarily invokes {@code onError}, the {@code Subscriber}
12855 * may never know that an error happened.
12856 * <p>
12857 * You can use this to prevent errors from propagating or to supply fallback data should errors be
12858 * encountered.
12859 * <dl>
12860 * <dt><b>Backpressure:</b></dt>
12861 * <dd>The operator honors backpressure from downstream. This and the resuming {@code Publisher}s
12862 * are expected to honor backpressure as well.
12863 * If any of them violate this expectation, the operator <em>may</em> throw an
12864 * {@link IllegalStateException} when the current {@code Flowable} completes or
12865 * a {@link MissingBackpressureException} is signaled somewhere downstream.</dd>
12866 * <dt><b>Scheduler:</b></dt>
12867 * <dd>{@code onErrorResumeNext} does not operate by default on a particular {@link Scheduler}.</dd>
12868 * </dl>
12869 *
12870 * @param fallbackSupplier
12871 * a function that returns a {@code Publisher} that will take over if the current {@code Flowable} encounters
12872 * an error
12873 * @return the new {@code Flowable} instance
12874 * @throws NullPointerException if {@code fallbackSupplier} is {@code null}
12875 * @see <a href="http://reactivex.io/documentation/operators/catch.html">ReactiveX operators documentation: Catch</a>
12876 */
12877 @CheckReturnValue
12878 @NonNull
12879 @BackpressureSupport(BackpressureKind.FULL)
12880 @SchedulerSupport(SchedulerSupport.NONE)
12881 public final Flowable<T> onErrorResumeNext(@NonNull Function<? super Throwable, @NonNull ? extends Publisher<? extends T>> fallbackSupplier) {
12882 Objects.requireNonNull(fallbackSupplier, "fallbackSupplier is null");
12883 return RxJavaPlugins.onAssembly(new FlowableOnErrorNext<>(this, fallbackSupplier));
12884 }
12885
12886 /**
12887 * Resumes the flow with the given {@link Publisher} when the current {@code Flowable} fails instead of
12888 * signaling the error via {@code onError}.
12889 * <p>
12890 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/onErrorResumeWith.v3.png" alt="">
12891 * <p>
12892 * By default, when a {@code Publisher} encounters an error that prevents it from emitting the expected item to
12893 * its {@link Subscriber}, the {@code Publisher} invokes its {@code Subscriber}'s {@code onError} method, and then quits
12894 * without invoking any more of its {@code Subscriber}'s methods. The {@code onErrorResumeWith} method changes this
12895 * behavior. If you pass another {@code Publisher} ({@code resumeSequence}) to a {@code Publisher}'s
12896 * {@code onErrorResumeWith} method, if the original {@code Publisher} encounters an error, instead of invoking its
12897 * {@code Subscriber}'s {@code onError} method, it will instead relinquish control to {@code resumeSequence} which
12898 * will invoke the {@code Subscriber}'s {@link Subscriber#onNext onNext} method if it is able to do so. In such a case,
12899 * because no {@code Publisher} necessarily invokes {@code onError}, the {@code Subscriber} may never know that an error
12900 * happened.
12901 * <p>
12902 * You can use this to prevent errors from propagating or to supply fallback data should errors be
12903 * encountered.
12904 * <dl>
12905 * <dt><b>Backpressure:</b></dt>
12906 * <dd>The operator honors backpressure from downstream. This and the resuming {@code Publisher}s
12907 * are expected to honor backpressure as well.
12908 * If any of them violate this expectation, the operator <em>may</em> throw an
12909 * {@link IllegalStateException} when the current {@code Flowable} completes or
12910 * {@link MissingBackpressureException} is signaled somewhere downstream.</dd>
12911 * <dt><b>Scheduler:</b></dt>
12912 * <dd>{@code onErrorResumeWith} does not operate by default on a particular {@link Scheduler}.</dd>
12913 * </dl>
12914 *
12915 * @param fallback
12916 * the next {@code Publisher} source that will take over if the current {@code Flowable} encounters
12917 * an error
12918 * @return the new {@code Flowable} instance
12919 * @throws NullPointerException if {@code fallback} is {@code null}
12920 * @see <a href="http://reactivex.io/documentation/operators/catch.html">ReactiveX operators documentation: Catch</a>
12921 */
12922 @CheckReturnValue
12923 @NonNull
12924 @BackpressureSupport(BackpressureKind.FULL)
12925 @SchedulerSupport(SchedulerSupport.NONE)
12926 public final Flowable<T> onErrorResumeWith(@NonNull Publisher<? extends T> fallback) {
12927 Objects.requireNonNull(fallback, "fallback is null");
12928 return onErrorResumeNext(Functions.justFunction(fallback));
12929 }
12930
12931 /**
12932 * Ends the flow with a last item returned by a function for the {@link Throwable} error signaled by the current
12933 * {@code Flowable} instead of signaling the error via {@code onError}.
12934 * <p>
12935 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/onErrorReturn.v3.png" alt="">
12936 * <p>
12937 * By default, when a {@link Publisher} encounters an error that prevents it from emitting the expected item to
12938 * its {@link Subscriber}, the {@code Publisher} invokes its {@code Subscriber}'s {@code onError} method, and then quits
12939 * without invoking any more of its {@code Subscriber}'s methods. The {@code onErrorReturn} method changes this
12940 * behavior. If you pass a function ({@code resumeFunction}) to a {@code Publisher}'s {@code onErrorReturn}
12941 * method, if the original {@code Publisher} encounters an error, instead of invoking its {@code Subscriber}'s
12942 * {@code onError} method, it will instead emit the return value of {@code resumeFunction}.
12943 * <p>
12944 * You can use this to prevent errors from propagating or to supply fallback data should errors be
12945 * encountered.
12946 * <dl>
12947 * <dt><b>Backpressure:</b></dt>
12948 * <dd>The operator honors backpressure from downstream. The current {@code Flowable} is expected to honor
12949 * backpressure as well. If it this expectation is violated, the operator <em>may</em> throw
12950 * {@link IllegalStateException} when the current {@code Flowable} completes or
12951 * {@link MissingBackpressureException} is signaled somewhere downstream.</dd>
12952 * <dt><b>Scheduler:</b></dt>
12953 * <dd>{@code onErrorReturn} does not operate by default on a particular {@link Scheduler}.</dd>
12954 * </dl>
12955 *
12956 * @param itemSupplier
12957 * a function that returns a single value that will be emitted along with a regular {@code onComplete} in case
12958 * the current {@code Flowable} signals an {@code onError} event
12959 * @return the new {@code Flowable} instance
12960 * @throws NullPointerException if {@code itemSupplier} is {@code null}
12961 * @see <a href="http://reactivex.io/documentation/operators/catch.html">ReactiveX operators documentation: Catch</a>
12962 */
12963 @CheckReturnValue
12964 @NonNull
12965 @BackpressureSupport(BackpressureKind.FULL)
12966 @SchedulerSupport(SchedulerSupport.NONE)
12967 public final Flowable<T> onErrorReturn(@NonNull Function<? super Throwable, ? extends T> itemSupplier) {
12968 Objects.requireNonNull(itemSupplier, "itemSupplier is null");
12969 return RxJavaPlugins.onAssembly(new FlowableOnErrorReturn<>(this, itemSupplier));
12970 }
12971
12972 /**
12973 * Ends the flow with the given last item when the current {@code Flowable} fails instead of signaling the error via {@code onError}.
12974 * <p>
12975 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/onErrorReturn.v3.png" alt="">
12976 * <p>
12977 * By default, when a {@link Publisher} encounters an error that prevents it from emitting the expected item to
12978 * its {@link Subscriber}, the {@code Publisher} invokes its {@code Subscriber}'s {@code onError} method, and then quits
12979 * without invoking any more of its {@code Subscriber}'s methods. The {@code onErrorReturn} method changes this
12980 * behavior. If you pass a function ({@code resumeFunction}) to a {@code Publisher}'s {@code onErrorReturn}
12981 * method, if the original {@code Publisher} encounters an error, instead of invoking its {@code Subscriber}'s
12982 * {@code onError} method, it will instead emit the return value of {@code resumeFunction}.
12983 * <p>
12984 * You can use this to prevent errors from propagating or to supply fallback data should errors be
12985 * encountered.
12986 * <dl>
12987 * <dt><b>Backpressure:</b></dt>
12988 * <dd>The operator honors backpressure from downstream. The current {@code Flowable} is expected to honor
12989 * backpressure as well. If it this expectation is violated, the operator <em>may</em> throw
12990 * {@link IllegalStateException} when the current {@code Flowable} completes or
12991 * {@link MissingBackpressureException} is signaled somewhere downstream.</dd>
12992 * <dt><b>Scheduler:</b></dt>
12993 * <dd>{@code onErrorReturnItem} does not operate by default on a particular {@link Scheduler}.</dd>
12994 * </dl>
12995 *
12996 * @param item
12997 * the value that is emitted along with a regular {@code onComplete} in case the current
12998 * {@code Flowable} signals an exception
12999 * @return the new {@code Flowable} instance
13000 * @throws NullPointerException if {@code item} is {@code null}
13001 * @see <a href="http://reactivex.io/documentation/operators/catch.html">ReactiveX operators documentation: Catch</a>
13002 */
13003 @CheckReturnValue
13004 @NonNull
13005 @BackpressureSupport(BackpressureKind.FULL)
13006 @SchedulerSupport(SchedulerSupport.NONE)
13007 public final Flowable<T> onErrorReturnItem(@NonNull T item) {
13008 Objects.requireNonNull(item, "item is null");
13009 return onErrorReturn(Functions.justFunction(item));
13010 }
13011
13012 /**
13013 * Nulls out references to the upstream producer and downstream {@link Subscriber} if
13014 * the sequence is terminated or downstream cancels.
13015 * <dl>
13016 * <dt><b>Backpressure:</b></dt>
13017 * <dd>The operator doesn't interfere with backpressure which is determined by the current {@code Flowable}'s backpressure
13018 * behavior.</dd>
13019 * <dt><b>Scheduler:</b></dt>
13020 * <dd>{@code onTerminateDetach} does not operate by default on a particular {@link Scheduler}.</dd>
13021 * </dl>
13022 * @return the new {@code Flowable} instance
13023 * the sequence is terminated or downstream cancels
13024 * @since 2.0
13025 */
13026 @CheckReturnValue
13027 @BackpressureSupport(BackpressureKind.PASS_THROUGH)
13028 @SchedulerSupport(SchedulerSupport.NONE)
13029 @NonNull
13030 public final Flowable<T> onTerminateDetach() {
13031 return RxJavaPlugins.onAssembly(new FlowableDetach<>(this));
13032 }
13033
13034 /**
13035 * Parallelizes the flow by creating multiple 'rails' (equal to the number of CPUs)
13036 * and dispatches the upstream items to them in a round-robin fashion.
13037 * <p>
13038 * Note that the rails don't execute in parallel on their own and one needs to
13039 * apply {@link ParallelFlowable#runOn(Scheduler)} to specify the {@link Scheduler} where
13040 * each rail will execute.
13041 * <p>
13042 * To merge the parallel 'rails' back into a single sequence, use {@link ParallelFlowable#sequential()}.
13043 * <p>
13044 * <img width="640" height="547" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/flowable.parallel.png" alt="">
13045 * <dl>
13046 * <dt><b>Backpressure:</b></dt>
13047 * <dd>The operator requires the upstream to honor backpressure and each 'rail' honors backpressure
13048 * as well.</dd>
13049 * <dt><b>Scheduler:</b></dt>
13050 * <dd>{@code parallel} does not operate by default on a particular {@code Scheduler}.</dd>
13051 * </dl>
13052 * <p>History: 2.0.5 - experimental; 2.1 - beta
13053 * @return the new {@link ParallelFlowable} instance
13054 * @since 2.2
13055 */
13056 @BackpressureSupport(BackpressureKind.FULL)
13057 @SchedulerSupport(SchedulerSupport.NONE)
13058 @CheckReturnValue
13059 @NonNull
13060 public final ParallelFlowable<T> parallel() {
13061 return ParallelFlowable.from(this);
13062 }
13063
13064 /**
13065 * Parallelizes the flow by creating the specified number of 'rails'
13066 * and dispatches the upstream items to them in a round-robin fashion.
13067 * <p>
13068 * Note that the rails don't execute in parallel on their own and one needs to
13069 * apply {@link ParallelFlowable#runOn(Scheduler)} to specify the {@link Scheduler} where
13070 * each rail will execute.
13071 * <p>
13072 * To merge the parallel 'rails' back into a single sequence, use {@link ParallelFlowable#sequential()}.
13073 * <p>
13074 * <img width="640" height="547" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/flowable.parallel.png" alt="">
13075 * <dl>
13076 * <dt><b>Backpressure:</b></dt>
13077 * <dd>The operator requires the upstream to honor backpressure and each 'rail' honors backpressure
13078 * as well.</dd>
13079 * <dt><b>Scheduler:</b></dt>
13080 * <dd>{@code parallel} does not operate by default on a particular {@code Scheduler}.</dd>
13081 * </dl>
13082 * <p>History: 2.0.5 - experimental; 2.1 - beta
13083 * @param parallelism the number of 'rails' to use
13084 * @return the new {@link ParallelFlowable} instance
13085 * @throws IllegalArgumentException if {@code parallelism} is non-positive
13086 * @since 2.2
13087 */
13088 @BackpressureSupport(BackpressureKind.FULL)
13089 @SchedulerSupport(SchedulerSupport.NONE)
13090 @CheckReturnValue
13091 @NonNull
13092 public final ParallelFlowable<T> parallel(int parallelism) {
13093 return ParallelFlowable.from(this, parallelism);
13094 }
13095
13096 /**
13097 * Parallelizes the flow by creating the specified number of 'rails'
13098 * and dispatches the upstream items to them in a round-robin fashion and
13099 * uses the defined per-'rail' prefetch amount.
13100 * <p>
13101 * Note that the rails don't execute in parallel on their own and one needs to
13102 * apply {@link ParallelFlowable#runOn(Scheduler)} to specify the {@link Scheduler} where
13103 * each rail will execute.
13104 * <p>
13105 * To merge the parallel 'rails' back into a single sequence, use {@link ParallelFlowable#sequential()}.
13106 * <p>
13107 * <img width="640" height="547" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/flowable.parallel.png" alt="">
13108 * <dl>
13109 * <dt><b>Backpressure:</b></dt>
13110 * <dd>The operator requires the upstream to honor backpressure and each 'rail' honors backpressure
13111 * as well.</dd>
13112 * <dt><b>Scheduler:</b></dt>
13113 * <dd>{@code parallel} does not operate by default on a particular {@code Scheduler}.</dd>
13114 * </dl>
13115 * <p>History: 2.0.5 - experimental; 2.1 - beta
13116 * @param parallelism the number of 'rails' to use
13117 * @param prefetch the number of items each 'rail' should prefetch
13118 * @return the new {@link ParallelFlowable} instance
13119 * @throws IllegalArgumentException if {@code parallelism} or {@code prefetch} is non-positive
13120 * @since 2.2
13121 */
13122 @BackpressureSupport(BackpressureKind.FULL)
13123 @SchedulerSupport(SchedulerSupport.NONE)
13124 @CheckReturnValue
13125 @NonNull
13126 public final ParallelFlowable<T> parallel(int parallelism, int prefetch) {
13127 return ParallelFlowable.from(this, parallelism, prefetch);
13128 }
13129
13130 /**
13131 * Returns a {@link ConnectableFlowable}, which is a variety of {@link Publisher} that waits until its
13132 * {@link ConnectableFlowable#connect connect} method is called before it begins emitting items to those
13133 * {@link Subscriber}s that have subscribed to it.
13134 * <p>
13135 * <img width="640" height="510" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/publishConnect.v3.png" alt="">
13136 * <dl>
13137 * <dt><b>Backpressure:</b></dt>
13138 * <dd>The returned {@code ConnectableFlowable} honors backpressure for each of its {@code Subscriber}s
13139 * and expects the current {@code Flowable} to honor backpressure as well. If this expectation is violated,
13140 * the operator will signal a {@link MissingBackpressureException} to its {@code Subscriber}s and disconnect.</dd>
13141 * <dt><b>Scheduler:</b></dt>
13142 * <dd>{@code publish} does not operate by default on a particular {@link Scheduler}.</dd>
13143 * </dl>
13144 *
13145 * @return the new {@code ConnectableFlowable} instance
13146 * @see <a href="http://reactivex.io/documentation/operators/publish.html">ReactiveX operators documentation: Publish</a>
13147 */
13148 @CheckReturnValue
13149 @BackpressureSupport(BackpressureKind.FULL)
13150 @SchedulerSupport(SchedulerSupport.NONE)
13151 @NonNull
13152 public final ConnectableFlowable<T> publish() {
13153 return publish(bufferSize());
13154 }
13155
13156 /**
13157 * Returns a {@code Flowable} that emits the results of invoking a specified selector on items emitted by a
13158 * {@link ConnectableFlowable} that shares a single subscription to the underlying sequence.
13159 * <p>
13160 * <img width="640" height="510" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/publishConnect.f.v3.png" alt="">
13161 * <dl>
13162 * <dt><b>Backpressure:</b></dt>
13163 * <dd>The operator expects the current {@code Flowable} to honor backpressure and if this expectation is
13164 * violated, the operator will signal a {@link MissingBackpressureException} through the {@code Flowable}
13165 * provided to the function. Since the {@link Publisher} returned by the {@code selector} may be
13166 * independent of the provided {@code Flowable} to the function, the output's backpressure behavior
13167 * is determined by this returned {@code Publisher}.</dd>
13168 * <dt><b>Scheduler:</b></dt>
13169 * <dd>{@code publish} does not operate by default on a particular {@link Scheduler}.</dd>
13170 * </dl>
13171 *
13172 * @param <R>
13173 * the type of items emitted by the resulting {@code Flowable}
13174 * @param selector
13175 * a function that can use the multicasted source sequence as many times as needed, without
13176 * causing multiple subscriptions to the source sequence. {@link Subscriber}s to the given source will
13177 * receive all notifications of the source from the time of the subscription forward.
13178 * @return the new {@code Flowable} instance
13179 * @throws NullPointerException if {@code selector} is {@code null}
13180 * @see <a href="http://reactivex.io/documentation/operators/publish.html">ReactiveX operators documentation: Publish</a>
13181 */
13182 @CheckReturnValue
13183 @BackpressureSupport(BackpressureKind.FULL)
13184 @SchedulerSupport(SchedulerSupport.NONE)
13185 @NonNull
13186 public final <@NonNull R> Flowable<R> publish(@NonNull Function<? super Flowable<T>, @NonNull ? extends Publisher<R>> selector) {
13187 return publish(selector, bufferSize());
13188 }
13189
13190 /**
13191 * Returns a {@code Flowable} that emits the results of invoking a specified selector on items emitted by a
13192 * {@link ConnectableFlowable} that shares a single subscription to the underlying sequence.
13193 * <p>
13194 * <img width="640" height="510" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/publishConnect.f.v3.png" alt="">
13195 * <dl>
13196 * <dt><b>Backpressure:</b></dt>
13197 * <dd>The operator expects the current {@code Flowable} to honor backpressure and if this expectation is
13198 * violated, the operator will signal a {@link MissingBackpressureException} through the {@code Flowable}
13199 * provided to the function. Since the {@link Publisher} returned by the {@code selector} may be
13200 * independent of the provided {@code Flowable} to the function, the output's backpressure behavior
13201 * is determined by this returned {@code Publisher}.</dd>
13202 * <dt><b>Scheduler:</b></dt>
13203 * <dd>{@code publish} does not operate by default on a particular {@link Scheduler}.</dd>
13204 * </dl>
13205 *
13206 * @param <R>
13207 * the type of items emitted by the resulting {@code Flowable}
13208 * @param selector
13209 * a function that can use the multicasted source sequence as many times as needed, without
13210 * causing multiple subscriptions to the source sequence. {@link Subscriber}s to the given source will
13211 * receive all notifications of the source from the time of the subscription forward.
13212 * @param prefetch
13213 * the number of elements to prefetch from the current {@code Flowable}
13214 * @return the new {@code Flowable} instance
13215 * @throws NullPointerException if {@code selector} is {@code null}
13216 * @throws IllegalArgumentException if {@code prefetch} is non-positive
13217 * @see <a href="http://reactivex.io/documentation/operators/publish.html">ReactiveX operators documentation: Publish</a>
13218 */
13219 @CheckReturnValue
13220 @NonNull
13221 @BackpressureSupport(BackpressureKind.FULL)
13222 @SchedulerSupport(SchedulerSupport.NONE)
13223 public final <@NonNull R> Flowable<R> publish(@NonNull Function<? super Flowable<T>, @NonNull ? extends Publisher<? extends R>> selector, int prefetch) {
13224 Objects.requireNonNull(selector, "selector is null");
13225 ObjectHelper.verifyPositive(prefetch, "prefetch");
13226 return RxJavaPlugins.onAssembly(new FlowablePublishMulticast<>(this, selector, prefetch, false));
13227 }
13228
13229 /**
13230 * Returns a {@link ConnectableFlowable}, which is a variety of {@link Publisher} that waits until its
13231 * {@link ConnectableFlowable#connect connect} method is called before it begins emitting items to those
13232 * {@link Subscriber}s that have subscribed to it.
13233 * <p>
13234 * <img width="640" height="510" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/publishConnect.v3.png" alt="">
13235 * <dl>
13236 * <dt><b>Backpressure:</b></dt>
13237 * <dd>The returned {@code ConnectableFlowable} honors backpressure for each of its {@code Subscriber}s
13238 * and expects the current {@code Flowable} to honor backpressure as well. If this expectation is violated,
13239 * the operator will signal a {@link MissingBackpressureException} to its {@code Subscriber}s and disconnect.</dd>
13240 * <dt><b>Scheduler:</b></dt>
13241 * <dd>{@code publish} does not operate by default on a particular {@link Scheduler}.</dd>
13242 * </dl>
13243 *
13244 * @param bufferSize
13245 * the number of elements to prefetch from the current {@code Flowable}
13246 * @return the new {@code ConnectableFlowable} instance
13247 * @throws IllegalArgumentException if {@code bufferSize} is non-positive
13248 * @see <a href="http://reactivex.io/documentation/operators/publish.html">ReactiveX operators documentation: Publish</a>
13249 */
13250 @CheckReturnValue
13251 @BackpressureSupport(BackpressureKind.FULL)
13252 @SchedulerSupport(SchedulerSupport.NONE)
13253 @NonNull
13254 public final ConnectableFlowable<T> publish(int bufferSize) {
13255 ObjectHelper.verifyPositive(bufferSize, "bufferSize");
13256 return RxJavaPlugins.onAssembly(new FlowablePublish<>(this, bufferSize));
13257 }
13258
13259 /**
13260 * Requests {@code n} initially from the upstream and then 75% of {@code n} subsequently
13261 * after 75% of {@code n} values have been emitted to the downstream.
13262 *
13263 * <p>This operator allows preventing the downstream to trigger unbounded mode via {@code request(}{@link Long#MAX_VALUE}{@code )}
13264 * or compensate for the per-item overhead of small and frequent requests.
13265 *
13266 * <dl>
13267 * <dt><b>Backpressure:</b></dt>
13268 * <dd>The operator expects backpressure from upstream and honors backpressure from downstream.</dd>
13269 * <dt><b>Scheduler:</b></dt>
13270 * <dd>{@code rebatchRequests} does not operate by default on a particular {@link Scheduler}.</dd>
13271 * </dl>
13272 *
13273 * @param n the initial request amount, further request will happen after 75% of this value
13274 * @return the new {@code Flowable} instance
13275 * @throws IllegalArgumentException if {@code n} is non-positive
13276 * @since 2.0
13277 */
13278 @CheckReturnValue
13279 @BackpressureSupport(BackpressureKind.FULL)
13280 @SchedulerSupport(SchedulerSupport.NONE)
13281 @NonNull
13282 public final Flowable<T> rebatchRequests(int n) {
13283 return observeOn(ImmediateThinScheduler.INSTANCE, true, n);
13284 }
13285
13286 /**
13287 * Returns a {@link Maybe} that applies a specified accumulator function to the first item emitted by the current
13288 * {@code Flowable}, then feeds the result of that function along with the second item emitted by the current
13289 * {@code Flowable} into the same function, and so on until all items have been emitted by the current and finite {@code Flowable},
13290 * and emits the final result from the final call to your function as its sole item.
13291 * <p>
13292 * <img width="640" height="320" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/reduce.v3.png" alt="">
13293 * <p>
13294 * This technique, which is called "reduce" here, is sometimes called "aggregate," "fold," "accumulate,"
13295 * "compress," or "inject" in other programming contexts. Groovy, for instance, has an {@code inject} method
13296 * that does a similar operation on lists.
13297 * <p>
13298 * Note that this operator requires the upstream to signal {@code onComplete} for the accumulator object to
13299 * be emitted. Sources that are infinite and never complete will never emit anything through this
13300 * operator and an infinite source may lead to a fatal {@link OutOfMemoryError}.
13301 * <dl>
13302 * <dt><b>Backpressure:</b></dt>
13303 * <dd>The operator honors backpressure of its downstream consumer and consumes the
13304 * upstream source in unbounded mode.</dd>
13305 * <dt><b>Scheduler:</b></dt>
13306 * <dd>{@code reduce} does not operate by default on a particular {@link Scheduler}.</dd>
13307 * </dl>
13308 *
13309 * @param reducer
13310 * an accumulator function to be invoked on each item emitted by the current {@code Flowable}, whose
13311 * result will be used in the next accumulator call
13312 * @return the new {@code Maybe} instance
13313 * @throws NullPointerException if {@code reducer} is {@code null}
13314 * @see <a href="http://reactivex.io/documentation/operators/reduce.html">ReactiveX operators documentation: Reduce</a>
13315 * @see <a href="http://en.wikipedia.org/wiki/Fold_(higher-order_function)">Wikipedia: Fold (higher-order function)</a>
13316 */
13317 @CheckReturnValue
13318 @NonNull
13319 @BackpressureSupport(BackpressureKind.UNBOUNDED_IN)
13320 @SchedulerSupport(SchedulerSupport.NONE)
13321 public final Maybe<T> reduce(@NonNull BiFunction<T, T, T> reducer) {
13322 Objects.requireNonNull(reducer, "reducer is null");
13323 return RxJavaPlugins.onAssembly(new FlowableReduceMaybe<>(this, reducer));
13324 }
13325
13326 /**
13327 * Returns a {@link Single} that applies a specified accumulator function to the first item emitted by the current
13328 * {@code Flowable} and a specified seed value, then feeds the result of that function along with the second item
13329 * emitted by the current {@code Flowable} into the same function, and so on until all items have been emitted by the
13330 * current and finite {@code Flowable}, emitting the final result from the final call to your function as its sole item.
13331 * <p>
13332 * <img width="640" height="325" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/reduceSeed.v3.png" alt="">
13333 * <p>
13334 * This technique, which is called "reduce" here, is sometimes called "aggregate," "fold," "accumulate,"
13335 * "compress," or "inject" in other programming contexts. Groovy, for instance, has an {@code inject} method
13336 * that does a similar operation on lists.
13337 * <p>
13338 * Note that the {@code seed} is shared among all subscribers to the resulting {@code Flowable}
13339 * and may cause problems if it is mutable. To make sure each subscriber gets its own value, defer
13340 * the application of this operator via {@link #defer(Supplier)}:
13341 * <pre><code>
13342 * Flowable&lt;T&gt; source = ...
13343 * Single.defer(() -&gt; source.reduce(new ArrayList&lt;&gt;(), (list, item) -&gt; list.add(item)));
13344 *
13345 * // alternatively, by using compose to stay fluent
13346 *
13347 * source.compose(o -&gt;
13348 * Flowable.defer(() -&gt; o.reduce(new ArrayList&lt;&gt;(), (list, item) -&gt; list.add(item)).toFlowable())
13349 * ).firstOrError();
13350 *
13351 * // or, by using reduceWith instead of reduce
13352 *
13353 * source.reduceWith(() -&gt; new ArrayList&lt;&gt;(), (list, item) -&gt; list.add(item)));
13354 * </code></pre>
13355 * <p>
13356 * Note that this operator requires the upstream to signal {@code onComplete} for the accumulator object to
13357 * be emitted. Sources that are infinite and never complete will never emit anything through this
13358 * operator and an infinite source may lead to a fatal {@link OutOfMemoryError}.
13359 * <dl>
13360 * <dt><b>Backpressure:</b></dt>
13361 * <dd>The operator honors backpressure of its downstream consumer and consumes the
13362 * upstream source in unbounded mode.</dd>
13363 * <dt><b>Scheduler:</b></dt>
13364 * <dd>{@code reduce} does not operate by default on a particular {@link Scheduler}.</dd>
13365 * </dl>
13366 *
13367 * @param <R> the accumulator and output value type
13368 * @param seed
13369 * the initial (seed) accumulator value
13370 * @param reducer
13371 * an accumulator function to be invoked on each item emitted by the current {@code Flowable}, the
13372 * result of which will be used in the next accumulator call
13373 * @return the new {@code Single} instance
13374 * @throws NullPointerException if {@code seed} or {@code reducer} is {@code null}
13375 * @see <a href="http://reactivex.io/documentation/operators/reduce.html">ReactiveX operators documentation: Reduce</a>
13376 * @see <a href="http://en.wikipedia.org/wiki/Fold_(higher-order_function)">Wikipedia: Fold (higher-order function)</a>
13377 * @see #reduceWith(Supplier, BiFunction)
13378 */
13379 @CheckReturnValue
13380 @NonNull
13381 @BackpressureSupport(BackpressureKind.UNBOUNDED_IN)
13382 @SchedulerSupport(SchedulerSupport.NONE)
13383 public final <@NonNull R> Single<R> reduce(R seed, @NonNull BiFunction<R, ? super T, R> reducer) {
13384 Objects.requireNonNull(seed, "seed is null");
13385 Objects.requireNonNull(reducer, "reducer is null");
13386 return RxJavaPlugins.onAssembly(new FlowableReduceSeedSingle<>(this, seed, reducer));
13387 }
13388
13389 /**
13390 * Returns a {@link Single} that applies a specified accumulator function to the first item emitted by the current
13391 * {@code Flowable} and a seed value derived from calling a specified {@code seedSupplier}, then feeds the result
13392 * of that function along with the second item emitted by the current {@code Flowable} into the same function, and so on until
13393 * all items have been emitted by the current and finite {@code Flowable}, emitting the final result from the final call to your
13394 * function as its sole item.
13395 * <p>
13396 * <img width="640" height="325" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/reduceSeed.v3.png" alt="">
13397 * <p>
13398 * This technique, which is called "reduce" here, is sometimes called "aggregate", "fold", "accumulate",
13399 * "compress", or "inject" in other programming contexts. Groovy, for instance, has an {@code inject} method
13400 * that does a similar operation on lists.
13401 * <p>
13402 * Note that this operator requires the upstream to signal {@code onComplete} for the accumulator object to
13403 * be emitted. Sources that are infinite and never complete will never emit anything through this
13404 * operator and an infinite source may lead to a fatal {@link OutOfMemoryError}.
13405 * <dl>
13406 * <dt><b>Backpressure:</b></dt>
13407 * <dd>The operator honors backpressure of its downstream consumer and consumes the
13408 * upstream source in unbounded mode.</dd>
13409 * <dt><b>Scheduler:</b></dt>
13410 * <dd>{@code reduceWith} does not operate by default on a particular {@link Scheduler}.</dd>
13411 * </dl>
13412 *
13413 * @param <R> the accumulator and output value type
13414 * @param seedSupplier
13415 * the {@link Supplier} that provides the initial (seed) accumulator value for each individual {@link Subscriber}
13416 * @param reducer
13417 * an accumulator function to be invoked on each item emitted by the current {@code Flowable}, the
13418 * result of which will be used in the next accumulator call
13419 * @return the new {@code Single} instance
13420 * @throws NullPointerException if {@code seedSupplier} or {@code reducer} is {@code null}
13421 * @see <a href="http://reactivex.io/documentation/operators/reduce.html">ReactiveX operators documentation: Reduce</a>
13422 * @see <a href="http://en.wikipedia.org/wiki/Fold_(higher-order_function)">Wikipedia: Fold (higher-order function)</a>
13423 */
13424 @CheckReturnValue
13425 @NonNull
13426 @BackpressureSupport(BackpressureKind.UNBOUNDED_IN)
13427 @SchedulerSupport(SchedulerSupport.NONE)
13428 public final <@NonNull R> Single<R> reduceWith(@NonNull Supplier<R> seedSupplier, @NonNull BiFunction<R, ? super T, R> reducer) {
13429 Objects.requireNonNull(seedSupplier, "seedSupplier is null");
13430 Objects.requireNonNull(reducer, "reducer is null");
13431 return RxJavaPlugins.onAssembly(new FlowableReduceWithSingle<>(this, seedSupplier, reducer));
13432 }
13433
13434 /**
13435 * Returns a {@code Flowable} that repeats the sequence of items emitted by the current {@code Flowable} indefinitely.
13436 * <p>
13437 * <img width="640" height="309" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/repeat.o.v3.png" alt="">
13438 * <dl>
13439 * <dt><b>Backpressure:</b></dt>
13440 * <dd>The operator honors downstream backpressure and expects the current {@code Flowable} to honor backpressure as well.
13441 * If this expectation is violated, the operator <em>may</em> throw an {@link IllegalStateException}.</dd>
13442 * <dt><b>Scheduler:</b></dt>
13443 * <dd>{@code repeat} does not operate by default on a particular {@link Scheduler}.</dd>
13444 * </dl>
13445 *
13446 * @return the new {@code Flowable} instance
13447 * @see <a href="http://reactivex.io/documentation/operators/repeat.html">ReactiveX operators documentation: Repeat</a>
13448 */
13449 @CheckReturnValue
13450 @BackpressureSupport(BackpressureKind.FULL)
13451 @SchedulerSupport(SchedulerSupport.NONE)
13452 @NonNull
13453 public final Flowable<T> repeat() {
13454 return repeat(Long.MAX_VALUE);
13455 }
13456
13457 /**
13458 * Returns a {@code Flowable} that repeats the sequence of items emitted by the current {@code Flowable} at most
13459 * {@code count} times.
13460 * <p>
13461 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/repeat.on.v3.png" alt="">
13462 * <dl>
13463 * <dt><b>Backpressure:</b></dt>
13464 * <dd>The operator honors downstream backpressure and expects the current {@code Flowable} to honor backpressure as well.
13465 * If this expectation is violated, the operator <em>may</em> throw an {@link IllegalStateException}.</dd>
13466 * <dt><b>Scheduler:</b></dt>
13467 * <dd>{@code repeat} does not operate by default on a particular {@link Scheduler}.</dd>
13468 * </dl>
13469 *
13470 * @param times
13471 * the number of times the current {@code Flowable} items are repeated, a count of 0 will yield an empty
13472 * sequence
13473 * @return the new {@code Flowable} instance
13474 * @throws IllegalArgumentException
13475 * if {@code times} is less than zero
13476 * @see <a href="http://reactivex.io/documentation/operators/repeat.html">ReactiveX operators documentation: Repeat</a>
13477 */
13478 @CheckReturnValue
13479 @BackpressureSupport(BackpressureKind.FULL)
13480 @SchedulerSupport(SchedulerSupport.NONE)
13481 @NonNull
13482 public final Flowable<T> repeat(long times) {
13483 if (times < 0) {
13484 throw new IllegalArgumentException("times >= 0 required but it was " + times);
13485 }
13486 if (times == 0) {
13487 return empty();
13488 }
13489 return RxJavaPlugins.onAssembly(new FlowableRepeat<>(this, times));
13490 }
13491
13492 /**
13493 * Returns a {@code Flowable} that repeats the sequence of items emitted by the current {@code Flowable} until
13494 * the provided stop function returns {@code true}.
13495 * <p>
13496 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/repeat.on.v3.png" alt="">
13497 * <dl>
13498 * <dt><b>Backpressure:</b></dt>
13499 * <dd>The operator honors downstream backpressure and expects the current {@code Flowable} to honor backpressure as well.
13500 * If this expectation is violated, the operator <em>may</em> throw an {@link IllegalStateException}.</dd>
13501 * <dt><b>Scheduler:</b></dt>
13502 * <dd>{@code repeatUntil} does not operate by default on a particular {@link Scheduler}.</dd>
13503 * </dl>
13504 *
13505 * @param stop
13506 * a boolean supplier that is called when the current {@code Flowable} completes and unless it returns
13507 * {@code false}, the current {@code Flowable} is resubscribed
13508 * @return the new {@code Flowable} instance
13509 * @throws NullPointerException
13510 * if {@code stop} is {@code null}
13511 * @see <a href="http://reactivex.io/documentation/operators/repeat.html">ReactiveX operators documentation: Repeat</a>
13512 */
13513 @CheckReturnValue
13514 @NonNull
13515 @BackpressureSupport(BackpressureKind.FULL)
13516 @SchedulerSupport(SchedulerSupport.NONE)
13517 public final Flowable<T> repeatUntil(@NonNull BooleanSupplier stop) {
13518 Objects.requireNonNull(stop, "stop is null");
13519 return RxJavaPlugins.onAssembly(new FlowableRepeatUntil<>(this, stop));
13520 }
13521
13522 /**
13523 * Returns a {@code Flowable} that emits the same values as the current {@code Flowable} with the exception of an
13524 * {@code onComplete}. An {@code onComplete} notification from the source will result in the emission of
13525 * a {@code void} item to the {@code Flowable} provided as an argument to the {@code notificationHandler}
13526 * function. If that {@link Publisher} calls {@code onComplete} or {@code onError} then {@code repeatWhen} will
13527 * call {@code onComplete} or {@code onError} on the child subscription. Otherwise, this {@code Publisher} will
13528 * resubscribe to the current {@code Flowable}.
13529 * <p>
13530 * <img width="640" height="430" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/repeatWhen.f.v3.png" alt="">
13531 * <dl>
13532 * <dt><b>Backpressure:</b></dt>
13533 * <dd>The operator honors downstream backpressure and expects the current {@code Flowable} to honor backpressure as well.
13534 * If this expectation is violated, the operator <em>may</em> throw an {@link IllegalStateException}.</dd>
13535 * <dt><b>Scheduler:</b></dt>
13536 * <dd>{@code repeatWhen} does not operate by default on a particular {@link Scheduler}.</dd>
13537 * </dl>
13538 *
13539 * @param handler
13540 * receives a {@code Publisher} of notifications with which a user can complete or error, aborting the repeat.
13541 * @return the new {@code Flowable} instance
13542 * @throws NullPointerException if {@code handler} is {@code null}
13543 * @see <a href="http://reactivex.io/documentation/operators/repeat.html">ReactiveX operators documentation: Repeat</a>
13544 */
13545 @CheckReturnValue
13546 @NonNull
13547 @BackpressureSupport(BackpressureKind.FULL)
13548 @SchedulerSupport(SchedulerSupport.NONE)
13549 public final Flowable<T> repeatWhen(@NonNull Function<? super Flowable<Object>, @NonNull ? extends Publisher<@NonNull ?>> handler) {
13550 Objects.requireNonNull(handler, "handler is null");
13551 return RxJavaPlugins.onAssembly(new FlowableRepeatWhen<>(this, handler));
13552 }
13553
13554 /**
13555 * Returns a {@link ConnectableFlowable} that shares a single subscription to the underlying {@link Publisher}
13556 * that will replay all of its items and notifications to any future {@link Subscriber}. A connectable
13557 * {@code Flowable} resembles an ordinary {@code Flowable}, except that it does not begin emitting items when it is
13558 * subscribed to, but only when its {@code connect} method is called.
13559 * <p>
13560 * <img width="640" height="515" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/replay.v3.png" alt="">
13561 * <dl>
13562 * <dt><b>Backpressure:</b></dt>
13563 * <dd>This operator supports backpressure. Note that the upstream requests are determined by the child
13564 * {@code Subscriber} which requests the largest amount: i.e., two child {@code Subscriber}s with requests of 10 and 100 will
13565 * request 100 elements from the current {@code Flowable} sequence.</dd>
13566 * <dt><b>Scheduler:</b></dt>
13567 * <dd>This version of {@code replay} does not operate by default on a particular {@link Scheduler}.</dd>
13568 * </dl>
13569 *
13570 * @return the new {@code ConnectableFlowable} instance
13571 * @see <a href="http://reactivex.io/documentation/operators/replay.html">ReactiveX operators documentation: Replay</a>
13572 */
13573 @CheckReturnValue
13574 @BackpressureSupport(BackpressureKind.FULL)
13575 @SchedulerSupport(SchedulerSupport.NONE)
13576 @NonNull
13577 public final ConnectableFlowable<T> replay() {
13578 return FlowableReplay.createFrom(this);
13579 }
13580
13581 /**
13582 * Returns a {@code Flowable} that emits items that are the results of invoking a specified selector on the items
13583 * emitted by a {@link ConnectableFlowable} that shares a single subscription to the current {@code Flowable}.
13584 * <p>
13585 * <img width="640" height="450" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/replay.f.v3.png" alt="">
13586 * <dl>
13587 * <dt><b>Backpressure:</b></dt>
13588 * <dd>This operator supports backpressure. Note that the upstream requests are determined by the child
13589 * {@link Subscriber} which requests the largest amount: i.e., two child {@code Subscriber}s with requests of 10 and 100 will
13590 * request 100 elements from the current {@code Flowable} sequence.</dd>
13591 * <dt><b>Scheduler:</b></dt>
13592 * <dd>This version of {@code replay} does not operate by default on a particular {@link Scheduler}.</dd>
13593 * </dl>
13594 *
13595 * @param <R>
13596 * the type of items emitted by the resulting {@code Flowable}
13597 * @param selector
13598 * the selector function, which can use the multicasted sequence as many times as needed, without
13599 * causing multiple subscriptions to the current {@code Flowable}
13600 * @return the new {@code Flowable} instance
13601 * @throws NullPointerException if {@code selector} is {@code null}
13602 * @see <a href="http://reactivex.io/documentation/operators/replay.html">ReactiveX operators documentation: Replay</a>
13603 */
13604 @CheckReturnValue
13605 @NonNull
13606 @BackpressureSupport(BackpressureKind.FULL)
13607 @SchedulerSupport(SchedulerSupport.NONE)
13608 public final <@NonNull R> Flowable<R> replay(@NonNull Function<? super Flowable<T>, @NonNull ? extends Publisher<R>> selector) {
13609 Objects.requireNonNull(selector, "selector is null");
13610 return FlowableReplay.multicastSelector(FlowableInternalHelper.replaySupplier(this), selector);
13611 }
13612
13613 /**
13614 * Returns a {@code Flowable} that emits items that are the results of invoking a specified selector on items
13615 * emitted by a {@link ConnectableFlowable} that shares a single subscription to the current {@code Flowable},
13616 * replaying {@code bufferSize} notifications.
13617 * <p>
13618 * Note that due to concurrency requirements, {@code replay(bufferSize)} may hold strong references to more than
13619 * {@code bufferSize} source emissions.
13620 * <p>
13621 * <img width="640" height="440" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/replay.fn.v3.png" alt="">
13622 * <dl>
13623 * <dt><b>Backpressure:</b></dt>
13624 * <dd>This operator supports backpressure. Note that the upstream requests are determined by the child
13625 * {@link Subscriber} which requests the largest amount: i.e., two child {@code Subscriber}s with requests of 10 and 100 will
13626 * request 100 elements from the current {@code Flowable} sequence.</dd>
13627 * <dt><b>Scheduler:</b></dt>
13628 * <dd>This version of {@code replay} does not operate by default on a particular {@link Scheduler}.</dd>
13629 * </dl>
13630 *
13631 * @param <R>
13632 * the type of items emitted by the resulting {@code Flowable}
13633 * @param selector
13634 * the selector function, which can use the multicasted sequence as many times as needed, without
13635 * causing multiple subscriptions to the current {@code Flowable}
13636 * @param bufferSize
13637 * the buffer size that limits the number of items the operator can replay
13638 * @return the new {@code Flowable} instance
13639 * @throws NullPointerException if {@code selector} is {@code null}
13640 * @throws IllegalArgumentException if {@code bufferSize} is non-positive
13641 * @see <a href="http://reactivex.io/documentation/operators/replay.html">ReactiveX operators documentation: Replay</a>
13642 * @see #replay(Function, int, boolean)
13643 */
13644 @CheckReturnValue
13645 @NonNull
13646 @BackpressureSupport(BackpressureKind.FULL)
13647 @SchedulerSupport(SchedulerSupport.NONE)
13648 public final <@NonNull R> Flowable<R> replay(@NonNull Function<? super Flowable<T>, @NonNull ? extends Publisher<R>> selector, int bufferSize) {
13649 Objects.requireNonNull(selector, "selector is null");
13650 ObjectHelper.verifyPositive(bufferSize, "bufferSize");
13651 return FlowableReplay.multicastSelector(FlowableInternalHelper.replaySupplier(this, bufferSize, false), selector);
13652 }
13653
13654 /**
13655 * Returns a {@code Flowable} that emits items that are the results of invoking a specified selector on items
13656 * emitted by a {@link ConnectableFlowable} that shares a single subscription to the current {@code Flowable},
13657 * replaying {@code bufferSize} notifications.
13658 * <p>
13659 * Note that due to concurrency requirements, {@code replay(bufferSize)} may hold strong references to more than
13660 * {@code bufferSize} source emissions.
13661 * <p>
13662 * <img width="640" height="440" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/replay.fn.v3.png" alt="">
13663 * <dl>
13664 * <dt><b>Backpressure:</b></dt>
13665 * <dd>This operator supports backpressure. Note that the upstream requests are determined by the child
13666 * {@link Subscriber} which requests the largest amount: i.e., two child {@code Subscriber}s with requests of 10 and 100 will
13667 * request 100 elements from the current {@code Flowable} sequence.</dd>
13668 * <dt><b>Scheduler:</b></dt>
13669 * <dd>This version of {@code replay} does not operate by default on a particular {@link Scheduler}.</dd>
13670 * </dl>
13671 *
13672 * @param <R>
13673 * the type of items emitted by the resulting {@code Flowable}
13674 * @param selector
13675 * the selector function, which can use the multicasted sequence as many times as needed, without
13676 * causing multiple subscriptions to the current {@code Flowable}
13677 * @param bufferSize
13678 * the buffer size that limits the number of items the operator can replay
13679 * @param eagerTruncate
13680 * if {@code true}, whenever the internal buffer is truncated to the given bufferSize, the
13681 * oldest item will be guaranteed dereferenced, thus avoiding unexpected retention
13682 * @return the new {@code Flowable} instance
13683 * @throws NullPointerException if {@code selector} is {@code null}
13684 * @throws IllegalArgumentException if {@code bufferSize} is non-positive
13685 * @see <a href="http://reactivex.io/documentation/operators/replay.html">ReactiveX operators documentation: Replay</a>
13686 */
13687 @CheckReturnValue
13688 @NonNull
13689 @BackpressureSupport(BackpressureKind.FULL)
13690 @SchedulerSupport(SchedulerSupport.NONE)
13691 public final <@NonNull R> Flowable<R> replay(@NonNull Function<? super Flowable<T>, @NonNull ? extends Publisher<R>> selector, int bufferSize, boolean eagerTruncate) {
13692 Objects.requireNonNull(selector, "selector is null");
13693 ObjectHelper.verifyPositive(bufferSize, "bufferSize");
13694 return FlowableReplay.multicastSelector(FlowableInternalHelper.replaySupplier(this, bufferSize, eagerTruncate), selector);
13695 }
13696
13697 /**
13698 * Returns a {@code Flowable} that emits items that are the results of invoking a specified selector on items
13699 * emitted by a {@link ConnectableFlowable} that shares a single subscription to the current {@code Flowable},
13700 * replaying no more than {@code bufferSize} items that were emitted within a specified time window.
13701 * <p>
13702 * Note that due to concurrency requirements, {@code replay(bufferSize)} may hold strong references to more than
13703 * {@code bufferSize} source emissions.
13704 * <p>
13705 * <img width="640" height="445" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/replay.fnt.v3.png" alt="">
13706 * <dl>
13707 * <dt><b>Backpressure:</b></dt>
13708 * <dd>This operator supports backpressure. Note that the upstream requests are determined by the child
13709 * {@link Subscriber} which requests the largest amount: i.e., two child {@code Subscriber}s with requests of 10 and 100 will
13710 * request 100 elements from the current {@code Flowable} sequence.</dd>
13711 * <dt><b>Scheduler:</b></dt>
13712 * <dd>This version of {@code replay} operates by default on the {@code computation} {@link Scheduler}.</dd>
13713 * </dl>
13714 *
13715 * @param <R>
13716 * the type of items emitted by the resulting {@code Flowable}
13717 * @param selector
13718 * a selector function, which can use the multicasted sequence as many times as needed, without
13719 * causing multiple subscriptions to the current {@code Flowable}
13720 * @param bufferSize
13721 * the buffer size that limits the number of items the operator can replay
13722 * @param time
13723 * the duration of the window in which the replayed items must have been emitted
13724 * @param unit
13725 * the time unit of {@code time}
13726 * @return the new {@code Flowable} instance
13727 * @throws NullPointerException if {@code selector} or {@code unit} is {@code null}
13728 * @throws IllegalArgumentException if {@code bufferSize} is non-positive
13729 * @see <a href="http://reactivex.io/documentation/operators/replay.html">ReactiveX operators documentation: Replay</a>
13730 */
13731 @CheckReturnValue
13732 @BackpressureSupport(BackpressureKind.FULL)
13733 @SchedulerSupport(SchedulerSupport.COMPUTATION)
13734 @NonNull
13735 public final <@NonNull R> Flowable<R> replay(@NonNull Function<? super Flowable<T>, @NonNull ? extends Publisher<R>> selector, int bufferSize, long time, @NonNull TimeUnit unit) {
13736 return replay(selector, bufferSize, time, unit, Schedulers.computation());
13737 }
13738
13739 /**
13740 * Returns a {@code Flowable} that emits items that are the results of invoking a specified selector on items
13741 * emitted by a {@link ConnectableFlowable} that shares a single subscription to the current {@code Flowable},
13742 * replaying no more than {@code bufferSize} items that were emitted within a specified time window.
13743 * <p>
13744 * Note that due to concurrency requirements, {@code replay(bufferSize)} may hold strong references to more than
13745 * {@code bufferSize} source emissions.
13746 * <p>
13747 * <img width="640" height="445" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/replay.fnts.v3.png" alt="">
13748 * <dl>
13749 * <dt><b>Backpressure:</b></dt>
13750 * <dd>This operator supports backpressure. Note that the upstream requests are determined by the child
13751 * {@link Subscriber} which requests the largest amount: i.e., two child {@code Subscriber}s with requests of 10 and 100 will
13752 * request 100 elements from the current {@code Flowable} sequence.</dd>
13753 * <dt><b>Scheduler:</b></dt>
13754 * <dd>You specify which {@link Scheduler} this operator will use.</dd>
13755 * </dl>
13756 *
13757 * @param <R>
13758 * the type of items emitted by the resulting {@code Flowable}
13759 * @param selector
13760 * a selector function, which can use the multicasted sequence as many times as needed, without
13761 * causing multiple subscriptions to the current {@code Flowable}
13762 * @param bufferSize
13763 * the buffer size that limits the number of items the operator can replay
13764 * @param time
13765 * the duration of the window in which the replayed items must have been emitted
13766 * @param unit
13767 * the time unit of {@code time}
13768 * @param scheduler
13769 * the {@code Scheduler} that is the time source for the window
13770 * @return the new {@code Flowable} instance
13771 * @throws NullPointerException if {@code selector}, {@code unit} or {@code scheduler} is {@code null}
13772 * @throws IllegalArgumentException
13773 * if {@code bufferSize} is non-positive
13774 * @see <a href="http://reactivex.io/documentation/operators/replay.html">ReactiveX operators documentation: Replay</a>
13775 * @see #replay(Function, int, long, TimeUnit, Scheduler, boolean)
13776 */
13777 @CheckReturnValue
13778 @NonNull
13779 @BackpressureSupport(BackpressureKind.FULL)
13780 @SchedulerSupport(SchedulerSupport.CUSTOM)
13781 public final <@NonNull R> Flowable<R> replay(@NonNull Function<? super Flowable<T>, @NonNull ? extends Publisher<R>> selector, int bufferSize, long time, @NonNull TimeUnit unit, @NonNull Scheduler scheduler) {
13782 Objects.requireNonNull(selector, "selector is null");
13783 Objects.requireNonNull(unit, "unit is null");
13784 ObjectHelper.verifyPositive(bufferSize, "bufferSize");
13785 Objects.requireNonNull(scheduler, "scheduler is null");
13786 return FlowableReplay.multicastSelector(
13787 FlowableInternalHelper.replaySupplier(this, bufferSize, time, unit, scheduler, false), selector);
13788 }
13789
13790 /**
13791 * Returns a {@code Flowable} that emits items that are the results of invoking a specified selector on items
13792 * emitted by a {@link ConnectableFlowable} that shares a single subscription to the current {@code Flowable},
13793 * replaying no more than {@code bufferSize} items that were emitted within a specified time window.
13794 * <p>
13795 * Note that due to concurrency requirements, {@code replay(bufferSize)} may hold strong references to more than
13796 * {@code bufferSize} source emissions.
13797 * <p>
13798 * <img width="640" height="445" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/replay.fnts.v3.png" alt="">
13799 * <dl>
13800 * <dt><b>Backpressure:</b></dt>
13801 * <dd>This operator supports backpressure. Note that the upstream requests are determined by the child
13802 * {@link Subscriber} which requests the largest amount: i.e., two child {@code Subscriber}s with requests of 10 and 100 will
13803 * request 100 elements from the current {@code Flowable} sequence.</dd>
13804 * <dt><b>Scheduler:</b></dt>
13805 * <dd>You specify which {@link Scheduler} this operator will use.</dd>
13806 * </dl>
13807 *
13808 * @param <R>
13809 * the type of items emitted by the resulting {@code Flowable}
13810 * @param selector
13811 * a selector function, which can use the multicasted sequence as many times as needed, without
13812 * causing multiple subscriptions to the current {@code Flowable}
13813 * @param bufferSize
13814 * the buffer size that limits the number of items the operator can replay
13815 * @param time
13816 * the duration of the window in which the replayed items must have been emitted
13817 * @param unit
13818 * the time unit of {@code time}
13819 * @param scheduler
13820 * the {@code Scheduler} that is the time source for the window
13821 * @param eagerTruncate
13822 * if {@code true}, whenever the internal buffer is truncated to the given bufferSize/age, the
13823 * oldest item will be guaranteed dereferenced, thus avoiding unexpected retention
13824 * @return the new {@code Flowable} instance
13825 * @throws NullPointerException if {@code selector}, {@code unit} or {@code scheduler} is {@code null}
13826 * @throws IllegalArgumentException
13827 * if {@code bufferSize} is less than zero
13828 * @see <a href="http://reactivex.io/documentation/operators/replay.html">ReactiveX operators documentation: Replay</a>
13829 */
13830 @CheckReturnValue
13831 @NonNull
13832 @BackpressureSupport(BackpressureKind.FULL)
13833 @SchedulerSupport(SchedulerSupport.CUSTOM)
13834 public final <@NonNull R> Flowable<R> replay(@NonNull Function<? super Flowable<T>, @NonNull ? extends Publisher<R>> selector, int bufferSize, long time, @NonNull TimeUnit unit, @NonNull Scheduler scheduler, boolean eagerTruncate) {
13835 Objects.requireNonNull(selector, "selector is null");
13836 Objects.requireNonNull(unit, "unit is null");
13837 ObjectHelper.verifyPositive(bufferSize, "bufferSize");
13838 Objects.requireNonNull(scheduler, "scheduler is null");
13839 return FlowableReplay.multicastSelector(
13840 FlowableInternalHelper.replaySupplier(this, bufferSize, time, unit, scheduler, eagerTruncate), selector);
13841 }
13842
13843 /**
13844 * Returns a {@code Flowable} that emits items that are the results of invoking a specified selector on items
13845 * emitted by a {@link ConnectableFlowable} that shares a single subscription to the current {@code Flowable},
13846 * replaying all items that were emitted within a specified time window.
13847 * <p>
13848 * <img width="640" height="435" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/replay.ft.v3.png" alt="">
13849 * <dl>
13850 * <dt><b>Backpressure:</b></dt>
13851 * <dd>This operator supports backpressure. Note that the upstream requests are determined by the child
13852 * {@link Subscriber} which requests the largest amount: i.e., two child {@code Subscriber}s with requests of 10 and 100 will
13853 * request 100 elements from the current {@code Flowable} sequence.</dd>
13854 * <dt><b>Scheduler:</b></dt>
13855 * <dd>This version of {@code replay} operates by default on the {@code computation} {@link Scheduler}.</dd>
13856 * </dl>
13857 *
13858 * @param <R>
13859 * the type of items emitted by the resulting {@code Flowable}
13860 * @param selector
13861 * a selector function, which can use the multicasted sequence as many times as needed, without
13862 * causing multiple subscriptions to the current {@code Flowable}
13863 * @param time
13864 * the duration of the window in which the replayed items must have been emitted
13865 * @param unit
13866 * the time unit of {@code time}
13867 * @return the new {@code Flowable} instance
13868 * @throws NullPointerException if {@code selector} or {@code unit} is {@code null}
13869 * @see <a href="http://reactivex.io/documentation/operators/replay.html">ReactiveX operators documentation: Replay</a>
13870 */
13871 @CheckReturnValue
13872 @BackpressureSupport(BackpressureKind.FULL)
13873 @SchedulerSupport(SchedulerSupport.COMPUTATION)
13874 @NonNull
13875 public final <@NonNull R> Flowable<R> replay(@NonNull Function<? super Flowable<T>, @NonNull ? extends Publisher<R>> selector, long time, @NonNull TimeUnit unit) {
13876 return replay(selector, time, unit, Schedulers.computation());
13877 }
13878
13879 /**
13880 * Returns a {@code Flowable} that emits items that are the results of invoking a specified selector on items
13881 * emitted by a {@link ConnectableFlowable} that shares a single subscription to the current {@code Flowable},
13882 * replaying all items that were emitted within a specified time window.
13883 * <p>
13884 * <img width="640" height="440" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/replay.fts.v3.png" alt="">
13885 * <dl>
13886 * <dt><b>Backpressure:</b></dt>
13887 * <dd>This operator supports backpressure. Note that the upstream requests are determined by the child
13888 * {@link Subscriber} which requests the largest amount: i.e., two child {@code Subscriber}s with requests of 10 and 100 will
13889 * request 100 elements from the current {@code Flowable} sequence.</dd>
13890 * <dt><b>Scheduler:</b></dt>
13891 * <dd>You specify which {@link Scheduler} this operator will use.</dd>
13892 * </dl>
13893 *
13894 * @param <R>
13895 * the type of items emitted by the resulting {@code Flowable}
13896 * @param selector
13897 * a selector function, which can use the multicasted sequence as many times as needed, without
13898 * causing multiple subscriptions to the current {@code Flowable}
13899 * @param time
13900 * the duration of the window in which the replayed items must have been emitted
13901 * @param unit
13902 * the time unit of {@code time}
13903 * @param scheduler
13904 * the scheduler that is the time source for the window
13905 * @return the new {@code Flowable} instance
13906 * @throws NullPointerException if {@code selector}, {@code unit} or {@code scheduler} is {@code null}
13907 * @see <a href="http://reactivex.io/documentation/operators/replay.html">ReactiveX operators documentation: Replay</a>
13908 * @see #replay(Function, long, TimeUnit, Scheduler, boolean)
13909 */
13910 @CheckReturnValue
13911 @NonNull
13912 @BackpressureSupport(BackpressureKind.FULL)
13913 @SchedulerSupport(SchedulerSupport.CUSTOM)
13914 public final <@NonNull R> Flowable<R> replay(@NonNull Function<? super Flowable<T>, @NonNull ? extends Publisher<R>> selector, long time, @NonNull TimeUnit unit, @NonNull Scheduler scheduler) {
13915 Objects.requireNonNull(selector, "selector is null");
13916 Objects.requireNonNull(unit, "unit is null");
13917 Objects.requireNonNull(scheduler, "scheduler is null");
13918 return FlowableReplay.multicastSelector(FlowableInternalHelper.replaySupplier(this, time, unit, scheduler, false), selector);
13919 }
13920
13921 /**
13922 * Returns a {@code Flowable} that emits items that are the results of invoking a specified selector on items
13923 * emitted by a {@link ConnectableFlowable} that shares a single subscription to the current {@code Flowable},
13924 * replaying all items that were emitted within a specified time window.
13925 * <p>
13926 * <img width="640" height="440" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/replay.fts.v3.png" alt="">
13927 * <dl>
13928 * <dt><b>Backpressure:</b></dt>
13929 * <dd>This operator supports backpressure. Note that the upstream requests are determined by the child
13930 * {@link Subscriber} which requests the largest amount: i.e., two child {@code Subscriber}s with requests of 10 and 100 will
13931 * request 100 elements from the current {@code Flowable} sequence.</dd>
13932 * <dt><b>Scheduler:</b></dt>
13933 * <dd>You specify which {@link Scheduler} this operator will use.</dd>
13934 * </dl>
13935 *
13936 * @param <R>
13937 * the type of items emitted by the resulting {@code Flowable}
13938 * @param selector
13939 * a selector function, which can use the multicasted sequence as many times as needed, without
13940 * causing multiple subscriptions to the current {@code Flowable}
13941 * @param time
13942 * the duration of the window in which the replayed items must have been emitted
13943 * @param unit
13944 * the time unit of {@code time}
13945 * @param scheduler
13946 * the scheduler that is the time source for the window
13947 * @param eagerTruncate
13948 * if {@code true}, whenever the internal buffer is truncated to the given age, the
13949 * oldest item will be guaranteed dereferenced, thus avoiding unexpected retention
13950 * @return the new {@code Flowable} instance
13951 * @throws NullPointerException if {@code selector}, {@code unit} or {@code scheduler} is {@code null}
13952 * @see <a href="http://reactivex.io/documentation/operators/replay.html">ReactiveX operators documentation: Replay</a>
13953 */
13954 @CheckReturnValue
13955 @NonNull
13956 @BackpressureSupport(BackpressureKind.FULL)
13957 @SchedulerSupport(SchedulerSupport.CUSTOM)
13958 public final <@NonNull R> Flowable<R> replay(@NonNull Function<? super Flowable<T>, @NonNull ? extends Publisher<R>> selector, long time, @NonNull TimeUnit unit, @NonNull Scheduler scheduler, boolean eagerTruncate) {
13959 Objects.requireNonNull(selector, "selector is null");
13960 Objects.requireNonNull(unit, "unit is null");
13961 Objects.requireNonNull(scheduler, "scheduler is null");
13962 return FlowableReplay.multicastSelector(FlowableInternalHelper.replaySupplier(this, time, unit, scheduler, eagerTruncate), selector);
13963 }
13964
13965 /**
13966 * Returns a {@link ConnectableFlowable} that shares a single subscription to the current {@code Flowable} and
13967 * replays at most {@code bufferSize} items to late {@link Subscriber}s. A Connectable {@code Flowable} resembles
13968 * an ordinary {@code Flowable}, except that it does not begin emitting items when it is subscribed to, but only
13969 * when its {@code connect} method is called.
13970 * <p>
13971 * Note that due to concurrency requirements, {@code replay(bufferSize)} may hold strong references to more than
13972 * {@code bufferSize} source emissions.
13973 * To ensure no beyond-bufferSize items are referenced,
13974 * use the {@link #replay(int, boolean)} overload with {@code eagerTruncate = true}.
13975 * <p>
13976 * <img width="640" height="515" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/replay.n.v3.png" alt="">
13977 * <dl>
13978 * <dt><b>Backpressure:</b></dt>
13979 * <dd>This operator supports backpressure. Note that the upstream requests are determined by the child
13980 * {@code Subscriber} which requests the largest amount: i.e., two child {@code Subscriber}s with requests of 10 and 100 will
13981 * request 100 elements from the current {@code Flowable} sequence.</dd>
13982 * <dt><b>Scheduler:</b></dt>
13983 * <dd>This version of {@code replay} does not operate by default on a particular {@link Scheduler}.</dd>
13984 * </dl>
13985 *
13986 * @param bufferSize
13987 * the buffer size that limits the number of items that can be replayed
13988 * @return the new {@code ConnectableFlowable} instance
13989 * @throws IllegalArgumentException if {@code bufferSize} is non-positive
13990 * @see <a href="http://reactivex.io/documentation/operators/replay.html">ReactiveX operators documentation: Replay</a>
13991 * @see #replay(int, boolean)
13992 */
13993 @CheckReturnValue
13994 @BackpressureSupport(BackpressureKind.FULL)
13995 @SchedulerSupport(SchedulerSupport.NONE)
13996 @NonNull
13997 public final ConnectableFlowable<T> replay(int bufferSize) {
13998 ObjectHelper.verifyPositive(bufferSize, "bufferSize");
13999 return FlowableReplay.create(this, bufferSize, false);
14000 }
14001 /**
14002 * Returns a {@link ConnectableFlowable} that shares a single subscription to the current {@code Flowable} and
14003 * replays at most {@code bufferSize} items to late {@link Subscriber}s. A connectable {@code Flowable} resembles
14004 * an ordinary {@code Flowable}, except that it does not begin emitting items when it is subscribed to, but only
14005 * when its {@code connect} method is called.
14006 * <p>
14007 * <img width="640" height="515" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/replay.n.v3.png" alt="">
14008 * <p>
14009 * Note that due to concurrency requirements, {@code replay(bufferSize)} may hold strong references to more than
14010 * {@code bufferSize} source emissions.
14011 * To ensure no beyond-bufferSize items are referenced, set {@code eagerTruncate = true}.
14012 * <dl>
14013 * <dt><b>Backpressure:</b></dt>
14014 * <dd>This operator supports backpressure. Note that the upstream requests are determined by the child
14015 * {@code Subscriber} which requests the largest amount: i.e., two child {@code Subscriber}s with requests of 10 and 100 will
14016 * request 100 elements from the current {@code Flowable} sequence.</dd>
14017 * <dt><b>Scheduler:</b></dt>
14018 * <dd>This version of {@code replay} does not operate by default on a particular {@link Scheduler}.</dd>
14019 * </dl>
14020 *
14021 * @param bufferSize
14022 * the buffer size that limits the number of items that can be replayed
14023 * @param eagerTruncate
14024 * if {@code true}, whenever the internal buffer is truncated to the given bufferSize, the
14025 * oldest item will be guaranteed dereferenced, thus avoiding unexpected retention
14026 * @return the new {@code ConnectableFlowable} instance
14027 * @throws IllegalArgumentException if {@code bufferSize} is non-positive
14028 * @see <a href="http://reactivex.io/documentation/operators/replay.html">ReactiveX operators documentation: Replay</a>
14029 * @since 3.0.0
14030 */
14031 @CheckReturnValue
14032 @BackpressureSupport(BackpressureKind.FULL)
14033 @SchedulerSupport(SchedulerSupport.NONE)
14034 @NonNull
14035 public final ConnectableFlowable<T> replay(int bufferSize, boolean eagerTruncate) {
14036 ObjectHelper.verifyPositive(bufferSize, "bufferSize");
14037 return FlowableReplay.create(this, bufferSize, eagerTruncate);
14038 }
14039
14040 /**
14041 * Returns a {@link ConnectableFlowable} that shares a single subscription to the current {@code Flowable} and
14042 * replays at most {@code bufferSize} items that were emitted during a specified time window. A connectable
14043 * {@code Flowable} resembles an ordinary {@code Flowable}, except that it does not begin emitting items when it is
14044 * subscribed to, but only when its {@code connect} method is called.
14045 * <p>
14046 * <img width="640" height="515" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/replay.nt.v3.png" alt="">
14047 * <p>
14048 * Note that due to concurrency requirements, {@code replay(bufferSize)} may hold strong references to more than
14049 * {@code bufferSize} source emissions.
14050 * To ensure no out-of-date or beyond-bufferSize items are referenced,
14051 * use the {@link #replay(int, long, TimeUnit, Scheduler, boolean)} overload with {@code eagerTruncate = true}.
14052 * <dl>
14053 * <dt><b>Backpressure:</b></dt>
14054 * <dd>This operator supports backpressure. Note that the upstream requests are determined by the child
14055 * {@link Subscriber} which requests the largest amount: i.e., two child {@code Subscriber}s with requests of 10 and 100 will
14056 * request 100 elements from the current {@code Flowable} sequence.</dd>
14057 * <dt><b>Scheduler:</b></dt>
14058 * <dd>This version of {@code replay} operates by default on the {@code computation} {@link Scheduler}.</dd>
14059 * </dl>
14060 *
14061 * @param bufferSize
14062 * the buffer size that limits the number of items that can be replayed
14063 * @param time
14064 * the duration of the window in which the replayed items must have been emitted
14065 * @param unit
14066 * the time unit of {@code time}
14067 * @return the new {@code ConnectableFlowable} instance
14068 * @throws NullPointerException if {@code unit} is {@code null}
14069 * @throws IllegalArgumentException if {@code bufferSize} is non-positive
14070 * @see <a href="http://reactivex.io/documentation/operators/replay.html">ReactiveX operators documentation: Replay</a>
14071 * @see #replay(int, long, TimeUnit, Scheduler, boolean)
14072 */
14073 @CheckReturnValue
14074 @BackpressureSupport(BackpressureKind.FULL)
14075 @SchedulerSupport(SchedulerSupport.COMPUTATION)
14076 @NonNull
14077 public final ConnectableFlowable<T> replay(int bufferSize, long time, @NonNull TimeUnit unit) {
14078 return replay(bufferSize, time, unit, Schedulers.computation());
14079 }
14080
14081 /**
14082 * Returns a {@link ConnectableFlowable} that shares a single subscription to the current {@code Flowable} and
14083 * replays a maximum of {@code bufferSize} items that are emitted within a specified time window to late {@link Subscriber}s. A
14084 * connectable {@code Flowable} resembles an ordinary {@code Flowable}, except that it does not begin emitting items
14085 * when it is subscribed to, but only when its {@code connect} method is called.
14086 * <p>
14087 * <img width="640" height="515" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/replay.nts.v3.png" alt="">
14088 * <p>
14089 * Note that due to concurrency requirements, {@code replay(bufferSize)} may hold strong references to more than
14090 * {@code bufferSize} source emissions.
14091 * To ensure no out-of-date or beyond-bufferSize items are referenced,
14092 * use the {@link #replay(int, long, TimeUnit, Scheduler, boolean)} overload with {@code eagerTruncate = true}.
14093 * <dl>
14094 * <dt><b>Backpressure:</b></dt>
14095 * <dd>This operator supports backpressure. Note that the upstream requests are determined by the child
14096 * {@code Subscriber} which requests the largest amount: i.e., two child {@code Subscriber}s with requests of 10 and 100 will
14097 * request 100 elements from the current {@code Flowable} sequence.</dd>
14098 * <dt><b>Scheduler:</b></dt>
14099 * <dd>You specify which {@link Scheduler} this operator will use.</dd>
14100 * </dl>
14101 *
14102 * @param bufferSize
14103 * the buffer size that limits the number of items that can be replayed
14104 * @param time
14105 * the duration of the window in which the replayed items must have been emitted
14106 * @param unit
14107 * the time unit of {@code time}
14108 * @param scheduler
14109 * the scheduler that is used as a time source for the window
14110 * @return the new {@code ConnectableFlowable} instance
14111 * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null}
14112 * @throws IllegalArgumentException if {@code bufferSize} is non-positive
14113 * @see <a href="http://reactivex.io/documentation/operators/replay.html">ReactiveX operators documentation: Replay</a>
14114 * @see #replay(int, long, TimeUnit, Scheduler, boolean)
14115 */
14116 @CheckReturnValue
14117 @BackpressureSupport(BackpressureKind.FULL)
14118 @SchedulerSupport(SchedulerSupport.CUSTOM)
14119 @NonNull
14120 public final ConnectableFlowable<T> replay(int bufferSize, long time, @NonNull TimeUnit unit, @NonNull Scheduler scheduler) {
14121 Objects.requireNonNull(unit, "unit is null");
14122 Objects.requireNonNull(scheduler, "scheduler is null");
14123 ObjectHelper.verifyPositive(bufferSize, "bufferSize");
14124 return FlowableReplay.create(this, time, unit, scheduler, bufferSize, false);
14125 }
14126
14127 /**
14128 * Returns a {@link ConnectableFlowable} that shares a single subscription to the current {@code Flowable} and
14129 * replays a maximum of {@code bufferSize} items that are emitted within a specified time window to late {@link Subscriber}s. A
14130 * connectable {@code Flowable} resembles an ordinary {@code Flowable}, except that it does not begin emitting items
14131 * when it is subscribed to, but only when its {@code connect} method is called.
14132 * <p>
14133 * Note that due to concurrency requirements, {@code replay(bufferSize)} may hold strong references to more than
14134 * {@code bufferSize} source emissions. To ensure no out-of-date or beyond-bufferSize items
14135 * are referenced, set {@code eagerTruncate = true}.
14136 * <p>
14137 * <img width="640" height="515" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/replay.nts.v3.png" alt="">
14138 * <dl>
14139 * <dt><b>Backpressure:</b></dt>
14140 * <dd>This operator supports backpressure. Note that the upstream requests are determined by the child
14141 * {@code Subscriber} which requests the largest amount: i.e., two child {@code Subscriber}s with requests of 10 and 100 will
14142 * request 100 elements from the current {@code Flowable} sequence.</dd>
14143 * <dt><b>Scheduler:</b></dt>
14144 * <dd>You specify which {@link Scheduler} this operator will use.</dd>
14145 * </dl>
14146 *
14147 * @param bufferSize
14148 * the buffer size that limits the number of items that can be replayed
14149 * @param time
14150 * the duration of the window in which the replayed items must have been emitted
14151 * @param unit
14152 * the time unit of {@code time}
14153 * @param scheduler
14154 * the scheduler that is used as a time source for the window
14155 * @param eagerTruncate
14156 * if {@code true}, whenever the internal buffer is truncated to the given bufferSize/age, the
14157 * oldest item will be guaranteed dereferenced, thus avoiding unexpected retention
14158 * @return the new {@code ConnectableFlowable} instance
14159 * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null}
14160 * @throws IllegalArgumentException if {@code bufferSize} is non-positive
14161 * @see <a href="http://reactivex.io/documentation/operators/replay.html">ReactiveX operators documentation: Replay</a>
14162 * @since 3.0.0
14163 */
14164 @CheckReturnValue
14165 @BackpressureSupport(BackpressureKind.FULL)
14166 @SchedulerSupport(SchedulerSupport.CUSTOM)
14167 @NonNull
14168 public final ConnectableFlowable<T> replay(int bufferSize, long time, @NonNull TimeUnit unit, @NonNull Scheduler scheduler, boolean eagerTruncate) {
14169 Objects.requireNonNull(unit, "unit is null");
14170 Objects.requireNonNull(scheduler, "scheduler is null");
14171 ObjectHelper.verifyPositive(bufferSize, "bufferSize");
14172 return FlowableReplay.create(this, time, unit, scheduler, bufferSize, eagerTruncate);
14173 }
14174
14175 /**
14176 * Returns a {@link ConnectableFlowable} that shares a single subscription to the current {@code Flowable} and
14177 * replays all items emitted by it within a specified time window to late {@link Subscriber}s. A connectable {@code Flowable}
14178 * resembles an ordinary {@code Flowable}, except that it does not begin emitting items when it is subscribed to,
14179 * but only when its {@code connect} method is called.
14180 * <p>
14181 * <img width="640" height="515" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/replay.t.v3.png" alt="">
14182 * <p>
14183 * Note that the internal buffer may retain strong references to the oldest item. To ensure no out-of-date items
14184 * are referenced, use the {@link #replay(long, TimeUnit, Scheduler, boolean)} overload with {@code eagerTruncate = true}.
14185 * <dl>
14186 * <dt><b>Backpressure:</b></dt>
14187 * <dd>This operator supports backpressure. Note that the upstream requests are determined by the child
14188 * {@code Subscriber} which requests the largest amount: i.e., two child {@code Subscriber}s with requests of 10 and 100 will
14189 * request 100 elements from the current {@code Flowable} sequence.</dd>
14190 * <dt><b>Scheduler:</b></dt>
14191 * <dd>This version of {@code replay} operates by default on the {@code computation} {@link Scheduler}.</dd>
14192 * </dl>
14193 *
14194 * @param time
14195 * the duration of the window in which the replayed items must have been emitted
14196 * @param unit
14197 * the time unit of {@code time}
14198 * @return the new {@code ConnectableFlowable} instance
14199 * @throws NullPointerException if {@code unit} is {@code null}
14200 * @see <a href="http://reactivex.io/documentation/operators/replay.html">ReactiveX operators documentation: Replay</a>
14201 */
14202 @CheckReturnValue
14203 @BackpressureSupport(BackpressureKind.FULL)
14204 @SchedulerSupport(SchedulerSupport.COMPUTATION)
14205 @NonNull
14206 public final ConnectableFlowable<T> replay(long time, @NonNull TimeUnit unit) {
14207 return replay(time, unit, Schedulers.computation());
14208 }
14209
14210 /**
14211 * Returns a {@link ConnectableFlowable} that shares a single subscription to the current {@code Flowable} and
14212 * replays all items emitted by it within a specified time window to late {@link Subscriber}s. A connectable {@code Flowable}
14213 * resembles an ordinary {@code Flowable}, except that it does not begin emitting items when it is subscribed to,
14214 * but only when its {@code connect} method is called.
14215 * <p>
14216 * <img width="640" height="515" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/replay.ts.v3.png" alt="">
14217 * <p>
14218 * Note that the internal buffer may retain strong references to the oldest item. To ensure no out-of-date items
14219 * are referenced, use the {@link #replay(long, TimeUnit, Scheduler, boolean)} overload with {@code eagerTruncate = true}.
14220 * <dl>
14221 * <dt><b>Backpressure:</b></dt>
14222 * <dd>This operator supports backpressure. Note that the upstream requests are determined by the child
14223 * {@code Subscriber} which requests the largest amount: i.e., two child {@code Subscriber}s with requests of 10 and 100 will
14224 * request 100 elements from the current {@code Flowable} sequence.</dd>
14225 * <dt><b>Scheduler:</b></dt>
14226 * <dd>You specify which {@link Scheduler} this operator will use.</dd>
14227 * </dl>
14228 *
14229 * @param time
14230 * the duration of the window in which the replayed items must have been emitted
14231 * @param unit
14232 * the time unit of {@code time}
14233 * @param scheduler
14234 * the {@code Scheduler} that is the time source for the window
14235 * @return the new {@code ConnectableFlowable} instance
14236 * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null}
14237 * @see <a href="http://reactivex.io/documentation/operators/replay.html">ReactiveX operators documentation: Replay</a>
14238 * @see #replay(long, TimeUnit, Scheduler, boolean)
14239 */
14240 @CheckReturnValue
14241 @BackpressureSupport(BackpressureKind.FULL)
14242 @SchedulerSupport(SchedulerSupport.CUSTOM)
14243 @NonNull
14244 public final ConnectableFlowable<T> replay(long time, @NonNull TimeUnit unit, @NonNull Scheduler scheduler) {
14245 Objects.requireNonNull(unit, "unit is null");
14246 Objects.requireNonNull(scheduler, "scheduler is null");
14247 return FlowableReplay.create(this, time, unit, scheduler, false);
14248 }
14249
14250 /**
14251 * Returns a {@link ConnectableFlowable} that shares a single subscription to the current {@code Flowable} and
14252 * replays all items emitted by it within a specified time window to late {@link Subscriber}s. A connectable {@code Flowable}
14253 * resembles an ordinary {@code Flowable}, except that it does not begin emitting items when it is subscribed to,
14254 * but only when its {@code connect} method is called.
14255 * <p>
14256 * <img width="640" height="515" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/replay.ts.v3.png" alt="">
14257 * <p>
14258 * Note that the internal buffer may retain strong references to the oldest item. To ensure no out-of-date items
14259 * are referenced, set {@code eagerTruncate = true}.
14260 * <dl>
14261 * <dt><b>Backpressure:</b></dt>
14262 * <dd>This operator supports backpressure. Note that the upstream requests are determined by the child
14263 * {@code Subscriber} which requests the largest amount: i.e., two child {@code Subscriber}s with requests of 10 and 100 will
14264 * request 100 elements from the current {@code Flowable} sequence.</dd>
14265 * <dt><b>Scheduler:</b></dt>
14266 * <dd>You specify which {@link Scheduler} this operator will use.</dd>
14267 * </dl>
14268 *
14269 * @param time
14270 * the duration of the window in which the replayed items must have been emitted
14271 * @param unit
14272 * the time unit of {@code time}
14273 * @param scheduler
14274 * the {@code Scheduler} that is the time source for the window
14275 * @param eagerTruncate
14276 * if {@code true}, whenever the internal buffer is truncated to the given bufferSize/age, the
14277 * oldest item will be guaranteed dereferenced, thus avoiding unexpected retention
14278 * @return the new {@code ConnectableFlowable} instance
14279 * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null}
14280 * @see <a href="http://reactivex.io/documentation/operators/replay.html">ReactiveX operators documentation: Replay</a>
14281 */
14282 @CheckReturnValue
14283 @BackpressureSupport(BackpressureKind.FULL)
14284 @SchedulerSupport(SchedulerSupport.CUSTOM)
14285 @NonNull
14286 public final ConnectableFlowable<T> replay(long time, @NonNull TimeUnit unit, @NonNull Scheduler scheduler, boolean eagerTruncate) {
14287 Objects.requireNonNull(unit, "unit is null");
14288 Objects.requireNonNull(scheduler, "scheduler is null");
14289 return FlowableReplay.create(this, time, unit, scheduler, eagerTruncate);
14290 }
14291
14292 /**
14293 * Returns a {@code Flowable} that mirrors the current {@code Flowable}, resubscribing to it if it calls {@code onError}
14294 * (infinite retry count).
14295 * <p>
14296 * <img width="640" height="315" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/retry.v3.png" alt="">
14297 * <p>
14298 * If the current {@code Flowable} calls {@link Subscriber#onError}, this method will resubscribe to the current
14299 * {@code Flowable} rather than propagating the {@code onError} call.
14300 * <p>
14301 * Any and all items emitted by the current {@code Flowable} will be emitted by the resulting {@code Flowable}, even
14302 * those emitted during failed subscriptions. For example, if the current {@code Flowable} fails at first but emits
14303 * {@code [1, 2]} then succeeds the second time and emits {@code [1, 2, 3, 4, 5]} then the complete sequence
14304 * of emissions and notifications would be {@code [1, 2, 1, 2, 3, 4, 5, onComplete]}.
14305 * <dl>
14306 * <dt><b>Backpressure:</b></dt>
14307 * <dd>The operator honors downstream backpressure and expects the current {@code Flowable} to honor backpressure as well.
14308 * If this expectation is violated, the operator <em>may</em> throw an {@link IllegalStateException}.</dd>
14309 * <dt><b>Scheduler:</b></dt>
14310 * <dd>{@code retry} does not operate by default on a particular {@link Scheduler}.</dd>
14311 * </dl>
14312 *
14313 * @return the new {@code Flowable} instance
14314 * @see <a href="http://reactivex.io/documentation/operators/retry.html">ReactiveX operators documentation: Retry</a>
14315 */
14316 @CheckReturnValue
14317 @BackpressureSupport(BackpressureKind.FULL)
14318 @SchedulerSupport(SchedulerSupport.NONE)
14319 @NonNull
14320 public final Flowable<T> retry() {
14321 return retry(Long.MAX_VALUE, Functions.alwaysTrue());
14322 }
14323
14324 /**
14325 * Returns a {@code Flowable} that mirrors the current {@code Flowable}, resubscribing to it if it calls {@code onError}
14326 * and the predicate returns {@code true} for that specific exception and retry count.
14327 * <p>
14328 * <img width="640" height="315" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/retry.v3.png" alt="">
14329 * <dl>
14330 * <dt><b>Backpressure:</b></dt>
14331 * <dd>The operator honors downstream backpressure and expects the current {@code Flowable} to honor backpressure as well.
14332 * If this expectation is violated, the operator <em>may</em> throw an {@link IllegalStateException}.</dd>
14333 * <dt><b>Scheduler:</b></dt>
14334 * <dd>{@code retry} does not operate by default on a particular {@link Scheduler}.</dd>
14335 * </dl>
14336 *
14337 * @param predicate
14338 * the predicate that determines if a resubscription may happen in case of a specific exception
14339 * and retry count
14340 * @return the new {@code Flowable} instance
14341 * @throws NullPointerException if {@code predicate} is {@code null}
14342 * @see #retry()
14343 * @see <a href="http://reactivex.io/documentation/operators/retry.html">ReactiveX operators documentation: Retry</a>
14344 */
14345 @CheckReturnValue
14346 @NonNull
14347 @BackpressureSupport(BackpressureKind.FULL)
14348 @SchedulerSupport(SchedulerSupport.NONE)
14349 public final Flowable<T> retry(@NonNull BiPredicate<@NonNull ? super Integer, @NonNull ? super Throwable> predicate) {
14350 Objects.requireNonNull(predicate, "predicate is null");
14351
14352 return RxJavaPlugins.onAssembly(new FlowableRetryBiPredicate<>(this, predicate));
14353 }
14354
14355 /**
14356 * Returns a {@code Flowable} that mirrors the current {@code Flowable}, resubscribing to it if it calls {@code onError}
14357 * up to a specified number of retries.
14358 * <p>
14359 * <img width="640" height="315" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/retry.v3.png" alt="">
14360 * <p>
14361 * If the current {@code Flowable} calls {@link Subscriber#onError}, this method will resubscribe to the current
14362 * {@code Flowable} for a maximum of {@code count} resubscriptions rather than propagating the
14363 * {@code onError} call.
14364 * <p>
14365 * Any and all items emitted by the current {@code Flowable} will be emitted by the resulting {@code Flowable}, even
14366 * those emitted during failed subscriptions. For example, if the current {@code Flowable} fails at first but emits
14367 * {@code [1, 2]} then succeeds the second time and emits {@code [1, 2, 3, 4, 5]} then the complete sequence
14368 * of emissions and notifications would be {@code [1, 2, 1, 2, 3, 4, 5, onComplete]}.
14369 * <dl>
14370 * <dt><b>Backpressure:</b></dt>
14371 * <dd>The operator honors downstream backpressure and expects the current {@code Flowable} to honor backpressure as well.
14372 * If this expectation is violated, the operator <em>may</em> throw an {@link IllegalStateException}.</dd>
14373 * <dt><b>Scheduler:</b></dt>
14374 * <dd>{@code retry} does not operate by default on a particular {@link Scheduler}.</dd>
14375 * </dl>
14376 *
14377 * @param times
14378 * the number of times to resubscribe if the current {@code Flowable} fails
14379 * @return the new {@code Flowable} instance
14380 * @throws IllegalArgumentException if {@code times} is negative
14381 * @see <a href="http://reactivex.io/documentation/operators/retry.html">ReactiveX operators documentation: Retry</a>
14382 */
14383 @CheckReturnValue
14384 @BackpressureSupport(BackpressureKind.FULL)
14385 @SchedulerSupport(SchedulerSupport.NONE)
14386 @NonNull
14387 public final Flowable<T> retry(long times) {
14388 return retry(times, Functions.alwaysTrue());
14389 }
14390
14391 /**
14392 * Retries at most times or until the predicate returns {@code false}, whichever happens first.
14393 *
14394 * <dl>
14395 * <dt><b>Backpressure:</b></dt>
14396 * <dd>The operator honors downstream backpressure and expects the current {@code Flowable} to honor backpressure as well.
14397 * If this expectation is violated, the operator <em>may</em> throw an {@link IllegalStateException}.</dd>
14398 * <dt><b>Scheduler:</b></dt>
14399 * <dd>{@code retry} does not operate by default on a particular {@link Scheduler}.</dd>
14400 * </dl>
14401 * @param times the number of times to resubscribe if the current {@code Flowable} fails
14402 * @param predicate the predicate called with the failure {@link Throwable} and should return {@code true} to trigger a retry.
14403 * @throws NullPointerException if {@code predicate} is {@code null}
14404 * @throws IllegalArgumentException if {@code times} is negative
14405 * @return the new {@code Flowable} instance
14406 */
14407 @CheckReturnValue
14408 @NonNull
14409 @BackpressureSupport(BackpressureKind.FULL)
14410 @SchedulerSupport(SchedulerSupport.NONE)
14411 public final Flowable<T> retry(long times, @NonNull Predicate<@NonNull ? super Throwable> predicate) {
14412 if (times < 0) {
14413 throw new IllegalArgumentException("times >= 0 required but it was " + times);
14414 }
14415 Objects.requireNonNull(predicate, "predicate is null");
14416
14417 return RxJavaPlugins.onAssembly(new FlowableRetryPredicate<>(this, times, predicate));
14418 }
14419
14420 /**
14421 * Retries the current {@code Flowable} if the predicate returns {@code true}.
14422 * <dl>
14423 * <dt><b>Backpressure:</b></dt>
14424 * <dd>The operator honors downstream backpressure and expects the current {@code Flowable} to honor backpressure as well.
14425 * If this expectation is violated, the operator <em>may</em> throw an {@link IllegalStateException}.</dd>
14426 * <dt><b>Scheduler:</b></dt>
14427 * <dd>{@code retry} does not operate by default on a particular {@link Scheduler}.</dd>
14428 * </dl>
14429 *
14430 * @param predicate the predicate that receives the failure {@link Throwable} and should return {@code true} to trigger a retry.
14431 * @return the new {@code Flowable} instance
14432 * @throws NullPointerException if {@code predicate} is {@code null}
14433 */
14434 @CheckReturnValue
14435 @BackpressureSupport(BackpressureKind.FULL)
14436 @SchedulerSupport(SchedulerSupport.NONE)
14437 @NonNull
14438 public final Flowable<T> retry(@NonNull Predicate<@NonNull ? super Throwable> predicate) {
14439 return retry(Long.MAX_VALUE, predicate);
14440 }
14441
14442 /**
14443 * Retries until the given stop function returns {@code true}.
14444 * <dl>
14445 * <dt><b>Backpressure:</b></dt>
14446 * <dd>The operator honors downstream backpressure and expects the current {@code Flowable} to honor backpressure as well.
14447 * If this expectation is violated, the operator <em>may</em> throw an {@link IllegalStateException}.</dd>
14448 * <dt><b>Scheduler:</b></dt>
14449 * <dd>{@code retryUntil} does not operate by default on a particular {@link Scheduler}.</dd>
14450 * </dl>
14451 * @param stop the function that should return {@code true} to stop retrying
14452 * @return the new {@code Flowable} instance
14453 * @throws NullPointerException if {@code stop} is {@code null}
14454 */
14455 @CheckReturnValue
14456 @NonNull
14457 @BackpressureSupport(BackpressureKind.FULL)
14458 @SchedulerSupport(SchedulerSupport.NONE)
14459 public final Flowable<T> retryUntil(@NonNull BooleanSupplier stop) {
14460 Objects.requireNonNull(stop, "stop is null");
14461 return retry(Long.MAX_VALUE, Functions.predicateReverseFor(stop));
14462 }
14463
14464 /**
14465 * Returns a {@code Flowable} that emits the same values as the current {@code Flowable} with the exception of an
14466 * {@code onError}. An {@code onError} notification from the source will result in the emission of a
14467 * {@link Throwable} item to the {@code Flowable} provided as an argument to the {@code notificationHandler}
14468 * function. If that {@link Publisher} calls {@code onComplete} or {@code onError} then {@code retry} will call
14469 * {@code onComplete} or {@code onError} on the child subscription. Otherwise, this {@code Publisher} will
14470 * resubscribe to the current {@code Flowable}.
14471 * <p>
14472 * <img width="640" height="430" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/retryWhen.f.v3.png" alt="">
14473 * <p>
14474 * Example:
14475 *
14476 * This retries 3 times, each time incrementing the number of seconds it waits.
14477 *
14478 * <pre><code>
14479 * Flowable.create((FlowableEmitter&lt;? super String&gt; s) -&gt; {
14480 * System.out.println("subscribing");
14481 * s.onError(new RuntimeException("always fails"));
14482 * }, BackpressureStrategy.BUFFER).retryWhen(attempts -&gt; {
14483 * return attempts.zipWith(Flowable.range(1, 3), (n, i) -&gt; i).flatMap(i -&gt; {
14484 * System.out.println("delay retry by " + i + " second(s)");
14485 * return Flowable.timer(i, TimeUnit.SECONDS);
14486 * });
14487 * }).blockingForEach(System.out::println);
14488 * </code></pre>
14489 *
14490 * Output is:
14491 *
14492 * <pre> {@code
14493 * subscribing
14494 * delay retry by 1 second(s)
14495 * subscribing
14496 * delay retry by 2 second(s)
14497 * subscribing
14498 * delay retry by 3 second(s)
14499 * subscribing
14500 * } </pre>
14501 * <p>
14502 * Note that the inner {@code Publisher} returned by the handler function should signal
14503 * either {@code onNext}, {@code onError} or {@code onComplete} in response to the received
14504 * {@code Throwable} to indicate the operator should retry or terminate. If the upstream to
14505 * the operator is asynchronous, signaling {@code onNext} followed by {@code onComplete} immediately may
14506 * result in the sequence to be completed immediately. Similarly, if this inner
14507 * {@code Publisher} signals {@code onError} or {@code onComplete} while the upstream is
14508 * active, the sequence is terminated with the same signal immediately.
14509 * <p>
14510 * The following example demonstrates how to retry an asynchronous source with a delay:
14511 * <pre><code>
14512 * Flowable.timer(1, TimeUnit.SECONDS)
14513 * .doOnSubscribe(s -&gt; System.out.println("subscribing"))
14514 * .map(v -&gt; { throw new RuntimeException(); })
14515 * .retryWhen(errors -&gt; {
14516 * AtomicInteger counter = new AtomicInteger();
14517 * return errors
14518 * .takeWhile(e -&gt; counter.getAndIncrement() != 3)
14519 * .flatMap(e -&gt; {
14520 * System.out.println("delay retry by " + counter.get() + " second(s)");
14521 * return Flowable.timer(counter.get(), TimeUnit.SECONDS);
14522 * });
14523 * })
14524 * .blockingSubscribe(System.out::println, System.out::println);
14525 * </code></pre>
14526 * <dl>
14527 * <dt><b>Backpressure:</b></dt>
14528 * <dd>The operator honors downstream backpressure and expects both the source
14529 * and inner {@code Publisher}s to honor backpressure as well.
14530 * If this expectation is violated, the operator <em>may</em> throw an {@link IllegalStateException}.</dd>
14531 * <dt><b>Scheduler:</b></dt>
14532 * <dd>{@code retryWhen} does not operate by default on a particular {@link Scheduler}.</dd>
14533 * </dl>
14534 *
14535 * @param handler
14536 * receives a {@code Publisher} of notifications with which a user can complete or error, aborting the
14537 * retry
14538 * @return the new {@code Flowable} instance
14539 * @throws NullPointerException if {@code handler} is {@code null}
14540 * @see <a href="http://reactivex.io/documentation/operators/retry.html">ReactiveX operators documentation: Retry</a>
14541 */
14542 @CheckReturnValue
14543 @NonNull
14544 @BackpressureSupport(BackpressureKind.FULL)
14545 @SchedulerSupport(SchedulerSupport.NONE)
14546 public final Flowable<T> retryWhen(
14547 @NonNull Function<? super Flowable<Throwable>, @NonNull ? extends Publisher<@NonNull ?>> handler) {
14548 Objects.requireNonNull(handler, "handler is null");
14549
14550 return RxJavaPlugins.onAssembly(new FlowableRetryWhen<>(this, handler));
14551 }
14552
14553 /**
14554 * Subscribes to the current {@code Flowable} and wraps the given {@link Subscriber} into a {@link SafeSubscriber}
14555 * (if not already a {@code SafeSubscriber}) that
14556 * deals with exceptions thrown by a misbehaving {@code Subscriber} (that doesn't follow the
14557 * <em>Reactive Streams</em> specification).
14558 * <dl>
14559 * <dt><b>Backpressure:</b></dt>
14560 * <dd>This operator leaves the reactive world and the backpressure behavior depends on the {@code Subscriber}'s behavior.</dd>
14561 * <dt><b>Scheduler:</b></dt>
14562 * <dd>{@code safeSubscribe} does not operate by default on a particular {@link Scheduler}.</dd>
14563 * </dl>
14564 * @param subscriber the incoming {@code Subscriber} instance
14565 * @throws NullPointerException if {@code subscriber} is {@code null}
14566 */
14567 @BackpressureSupport(BackpressureKind.PASS_THROUGH)
14568 @SchedulerSupport(SchedulerSupport.NONE)
14569 public final void safeSubscribe(@NonNull Subscriber<? super T> subscriber) {
14570 Objects.requireNonNull(subscriber, "subscriber is null");
14571 if (subscriber instanceof SafeSubscriber) {
14572 subscribe((SafeSubscriber<? super T>)subscriber);
14573 } else {
14574 subscribe(new SafeSubscriber<>(subscriber));
14575 }
14576 }
14577
14578 /**
14579 * Returns a {@code Flowable} that emits the most recently emitted item (if any) emitted by the current {@code Flowable}
14580 * within periodic time intervals.
14581 * <p>
14582 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/sample.v3.png" alt="">
14583 * <dl>
14584 * <dt><b>Backpressure:</b></dt>
14585 * <dd>This operator does not support backpressure as it uses time to control data flow.</dd>
14586 * <dt><b>Scheduler:</b></dt>
14587 * <dd>{@code sample} operates by default on the {@code computation} {@link Scheduler}.</dd>
14588 * </dl>
14589 *
14590 * @param period
14591 * the sampling rate
14592 * @param unit
14593 * the {@link TimeUnit} in which {@code period} is defined
14594 * @return the new {@code Flowable} instance
14595 * @throws NullPointerException if {@code unit} is {@code null}
14596 * @see <a href="http://reactivex.io/documentation/operators/sample.html">ReactiveX operators documentation: Sample</a>
14597 * @see <a href="https://github.com/ReactiveX/RxJava/wiki/Backpressure">RxJava wiki: Backpressure</a>
14598 * @see #throttleLast(long, TimeUnit)
14599 */
14600 @CheckReturnValue
14601 @BackpressureSupport(BackpressureKind.ERROR)
14602 @SchedulerSupport(SchedulerSupport.COMPUTATION)
14603 @NonNull
14604 public final Flowable<T> sample(long period, @NonNull TimeUnit unit) {
14605 return sample(period, unit, Schedulers.computation());
14606 }
14607
14608 /**
14609 * Returns a {@code Flowable} that emits the most recently emitted item (if any) emitted by the current {@code Flowable}
14610 * within periodic time intervals and optionally emit the very last upstream item when the upstream completes.
14611 * <p>
14612 * <img width="640" height="277" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/sample.emitlast.png" alt="">
14613 * <dl>
14614 * <dt><b>Backpressure:</b></dt>
14615 * <dd>This operator does not support backpressure as it uses time to control data flow.</dd>
14616 * <dt><b>Scheduler:</b></dt>
14617 * <dd>{@code sample} operates by default on the {@code computation} {@link Scheduler}.</dd>
14618 * </dl>
14619 *
14620 * <p>History: 2.0.5 - experimental
14621 * @param period
14622 * the sampling rate
14623 * @param unit
14624 * the {@link TimeUnit} in which {@code period} is defined
14625 * @param emitLast
14626 * if {@code true}, and the upstream completes while there is still an unsampled item available,
14627 * that item is emitted to downstream before completion
14628 * if {@code false}, an unsampled last item is ignored.
14629 * @return the new {@code Flowable} instance
14630 * @throws NullPointerException if {@code unit} is {@code null}
14631 * @see <a href="http://reactivex.io/documentation/operators/sample.html">ReactiveX operators documentation: Sample</a>
14632 * @see <a href="https://github.com/ReactiveX/RxJava/wiki/Backpressure">RxJava wiki: Backpressure</a>
14633 * @see #throttleLast(long, TimeUnit)
14634 * @since 2.1
14635 */
14636 @CheckReturnValue
14637 @BackpressureSupport(BackpressureKind.ERROR)
14638 @SchedulerSupport(SchedulerSupport.COMPUTATION)
14639 @NonNull
14640 public final Flowable<T> sample(long period, @NonNull TimeUnit unit, boolean emitLast) {
14641 return sample(period, unit, Schedulers.computation(), emitLast);
14642 }
14643
14644 /**
14645 * Returns a {@code Flowable} that emits the most recently emitted item (if any) emitted by the current {@code Flowable}
14646 * within periodic time intervals, where the intervals are defined on a particular {@link Scheduler}.
14647 * <p>
14648 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/sample.s.v3.png" alt="">
14649 * <dl>
14650 * <dt><b>Backpressure:</b></dt>
14651 * <dd>This operator does not support backpressure as it uses time to control data flow.</dd>
14652 * <dt><b>Scheduler:</b></dt>
14653 * <dd>You specify which {@code Scheduler} this operator will use.</dd>
14654 * </dl>
14655 *
14656 * @param period
14657 * the sampling rate
14658 * @param unit
14659 * the {@link TimeUnit} in which {@code period} is defined
14660 * @param scheduler
14661 * the {@code Scheduler} to use when sampling
14662 * @return the new {@code Flowable} instance
14663 * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null}
14664 * @see <a href="http://reactivex.io/documentation/operators/sample.html">ReactiveX operators documentation: Sample</a>
14665 * @see <a href="https://github.com/ReactiveX/RxJava/wiki/Backpressure">RxJava wiki: Backpressure</a>
14666 * @see #throttleLast(long, TimeUnit, Scheduler)
14667 */
14668 @CheckReturnValue
14669 @NonNull
14670 @BackpressureSupport(BackpressureKind.ERROR)
14671 @SchedulerSupport(SchedulerSupport.CUSTOM)
14672 public final Flowable<T> sample(long period, @NonNull TimeUnit unit, @NonNull Scheduler scheduler) {
14673 Objects.requireNonNull(unit, "unit is null");
14674 Objects.requireNonNull(scheduler, "scheduler is null");
14675 return RxJavaPlugins.onAssembly(new FlowableSampleTimed<>(this, period, unit, scheduler, false));
14676 }
14677
14678 /**
14679 * Returns a {@code Flowable} that emits the most recently emitted item (if any) emitted by the current {@code Flowable}
14680 * within periodic time intervals, where the intervals are defined on a particular {@link Scheduler}
14681 * and optionally emit the very last upstream item when the upstream completes.
14682 * <p>
14683 * <img width="640" height="277" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/sample.s.emitlast.png" alt="">
14684 * <dl>
14685 * <dt><b>Backpressure:</b></dt>
14686 * <dd>This operator does not support backpressure as it uses time to control data flow.</dd>
14687 * <dt><b>Scheduler:</b></dt>
14688 * <dd>You specify which {@code Scheduler} this operator will use.</dd>
14689 * </dl>
14690 *
14691 * <p>History: 2.0.5 - experimental
14692 * @param period
14693 * the sampling rate
14694 * @param unit
14695 * the {@link TimeUnit} in which {@code period} is defined
14696 * @param scheduler
14697 * the {@code Scheduler} to use when sampling
14698 * @param emitLast
14699 * if {@code true} and the upstream completes while there is still an unsampled item available,
14700 * that item is emitted to downstream before completion
14701 * if {@code false}, an unsampled last item is ignored.
14702 * @return the new {@code Flowable} instance
14703 * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null}
14704 * @see <a href="http://reactivex.io/documentation/operators/sample.html">ReactiveX operators documentation: Sample</a>
14705 * @see <a href="https://github.com/ReactiveX/RxJava/wiki/Backpressure">RxJava wiki: Backpressure</a>
14706 * @see #throttleLast(long, TimeUnit, Scheduler)
14707 * @since 2.1
14708 */
14709 @CheckReturnValue
14710 @NonNull
14711 @BackpressureSupport(BackpressureKind.ERROR)
14712 @SchedulerSupport(SchedulerSupport.CUSTOM)
14713 public final Flowable<T> sample(long period, @NonNull TimeUnit unit, @NonNull Scheduler scheduler, boolean emitLast) {
14714 Objects.requireNonNull(unit, "unit is null");
14715 Objects.requireNonNull(scheduler, "scheduler is null");
14716 return RxJavaPlugins.onAssembly(new FlowableSampleTimed<>(this, period, unit, scheduler, emitLast));
14717 }
14718
14719 /**
14720 * Returns a {@code Flowable} that, when the specified {@code sampler} {@link Publisher} emits an item or completes,
14721 * emits the most recently emitted item (if any) emitted by the current {@code Flowable} since the previous
14722 * emission from the {@code sampler} {@code Publisher}.
14723 * <p>
14724 * <img width="640" height="290" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/sample.o.nolast.png" alt="">
14725 * <dl>
14726 * <dt><b>Backpressure:</b></dt>
14727 * <dd>This operator does not support backpressure as it uses the emissions of the {@code sampler}
14728 * {@code Publisher} to control data flow.</dd>
14729 * <dt><b>Scheduler:</b></dt>
14730 * <dd>This version of {@code sample} does not operate by default on a particular {@link Scheduler}.</dd>
14731 * </dl>
14732 *
14733 * @param <U> the element type of the sampler {@code Publisher}
14734 * @param sampler
14735 * the {@code Publisher} to use for sampling the current {@code Flowable}
14736 * @return the new {@code Flowable} instance
14737 * @throws NullPointerException if {@code sampler} is {@code null}
14738 * @see <a href="http://reactivex.io/documentation/operators/sample.html">ReactiveX operators documentation: Sample</a>
14739 * @see <a href="https://github.com/ReactiveX/RxJava/wiki/Backpressure">RxJava wiki: Backpressure</a>
14740 */
14741 @CheckReturnValue
14742 @NonNull
14743 @BackpressureSupport(BackpressureKind.ERROR)
14744 @SchedulerSupport(SchedulerSupport.NONE)
14745 public final <@NonNull U> Flowable<T> sample(@NonNull Publisher<U> sampler) {
14746 Objects.requireNonNull(sampler, "sampler is null");
14747 return RxJavaPlugins.onAssembly(new FlowableSamplePublisher<>(this, sampler, false));
14748 }
14749
14750 /**
14751 * Returns a {@code Flowable} that, when the specified {@code sampler} {@link Publisher} emits an item or completes,
14752 * emits the most recently emitted item (if any) emitted by the current {@code Flowable} since the previous
14753 * emission from the {@code sampler} {@code Publisher}
14754 * and optionally emit the very last upstream item when the upstream or other {@code Publisher} complete.
14755 * <p>
14756 * <img width="640" height="290" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/sample.o.emitlast.png" alt="">
14757 * <dl>
14758 * <dt><b>Backpressure:</b></dt>
14759 * <dd>This operator does not support backpressure as it uses the emissions of the {@code sampler}
14760 * {@code Publisher} to control data flow.</dd>
14761 * <dt><b>Scheduler:</b></dt>
14762 * <dd>This version of {@code sample} does not operate by default on a particular {@link Scheduler}.</dd>
14763 * </dl>
14764 *
14765 * <p>History: 2.0.5 - experimental
14766 * @param <U> the element type of the sampler {@code Publisher}
14767 * @param sampler
14768 * the {@code Publisher} to use for sampling the current {@code Flowable}
14769 * @param emitLast
14770 * if {@code true} and the upstream completes while there is still an unsampled item available,
14771 * that item is emitted to downstream before completion
14772 * if {@code false}, an unsampled last item is ignored.
14773 * @return the new {@code Flowable} instance
14774 * @throws NullPointerException if {@code sampler} is {@code null}
14775 * @see <a href="http://reactivex.io/documentation/operators/sample.html">ReactiveX operators documentation: Sample</a>
14776 * @see <a href="https://github.com/ReactiveX/RxJava/wiki/Backpressure">RxJava wiki: Backpressure</a>
14777 * @since 2.1
14778 */
14779 @CheckReturnValue
14780 @NonNull
14781 @BackpressureSupport(BackpressureKind.ERROR)
14782 @SchedulerSupport(SchedulerSupport.NONE)
14783 public final <@NonNull U> Flowable<T> sample(@NonNull Publisher<U> sampler, boolean emitLast) {
14784 Objects.requireNonNull(sampler, "sampler is null");
14785 return RxJavaPlugins.onAssembly(new FlowableSamplePublisher<>(this, sampler, emitLast));
14786 }
14787
14788 /**
14789 * Returns a {@code Flowable} that emits the first value emitted by the current {@code Flowable}, then emits one value
14790 * for each subsequent value emitted by the current {@code Flowable}. Each emission after the first is the result of
14791 * applying the specified accumulator function to the previous emission and the corresponding value from the current {@code Flowable}.
14792 * <p>
14793 * <img width="640" height="320" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/scan.v3.png" alt="">
14794 * <p>
14795 * This sort of function is sometimes called an accumulator.
14796 * <dl>
14797 * <dt><b>Backpressure:</b></dt>
14798 * <dd>The operator honors downstream backpressure and expects the current {@code Flowable} to honor backpressure as well.
14799 * Violating this expectation, a {@link MissingBackpressureException} <em>may</em> get signaled somewhere downstream.</dd>
14800 * <dt><b>Scheduler:</b></dt>
14801 * <dd>{@code scan} does not operate by default on a particular {@link Scheduler}.</dd>
14802 * </dl>
14803 *
14804 * @param accumulator
14805 * an accumulator function to be invoked on each item emitted by the current {@code Flowable}, whose
14806 * result will be emitted to {@link Subscriber}s via {@link Subscriber#onNext onNext} and used in the
14807 * next accumulator call
14808 * @return the new {@code Flowable} instance
14809 * @throws NullPointerException if {@code accumulator} is {@code null}
14810 * @see <a href="http://reactivex.io/documentation/operators/scan.html">ReactiveX operators documentation: Scan</a>
14811 */
14812 @CheckReturnValue
14813 @NonNull
14814 @BackpressureSupport(BackpressureKind.FULL)
14815 @SchedulerSupport(SchedulerSupport.NONE)
14816 public final Flowable<T> scan(@NonNull BiFunction<T, T, T> accumulator) {
14817 Objects.requireNonNull(accumulator, "accumulator is null");
14818 return RxJavaPlugins.onAssembly(new FlowableScan<>(this, accumulator));
14819 }
14820
14821 /**
14822 * Returns a {@code Flowable} that emits the provided initial (seed) value, then emits one value for each value emitted
14823 * by the current {@code Flowable}. Each emission after the first is the result of applying the specified accumulator
14824 * function to the previous emission and the corresponding value from the current {@code Flowable}.
14825 * <p>
14826 * <img width="640" height="320" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/scanSeed.v3.png" alt="">
14827 * <p>
14828 * This sort of function is sometimes called an accumulator.
14829 * <p>
14830 * Note that the {@code Flowable} that results from this method will emit {@code initialValue} as its first
14831 * emitted item.
14832 * <p>
14833 * Note that the {@code initialValue} is shared among all subscribers to the resulting {@code Flowable}
14834 * and may cause problems if it is mutable. To make sure each subscriber gets its own value, defer
14835 * the application of this operator via {@link #defer(Supplier)}:
14836 * <pre><code>
14837 * Publisher&lt;T&gt; source = ...
14838 * Flowable.defer(() -&gt; source.scan(new ArrayList&lt;&gt;(), (list, item) -&gt; list.add(item)));
14839 *
14840 * // alternatively, by using compose to stay fluent
14841 *
14842 * source.compose(o -&gt;
14843 * Flowable.defer(() -&gt; o.scan(new ArrayList&lt;&gt;(), (list, item) -&gt; list.add(item)))
14844 * );
14845 * </code></pre>
14846 * <dl>
14847 * <dt><b>Backpressure:</b></dt>
14848 * <dd>The operator honors downstream backpressure and expects the current {@code Flowable} to honor backpressure as well.
14849 * Violating this expectation, a {@link MissingBackpressureException} <em>may</em> get signaled somewhere downstream.
14850 * The downstream request pattern is not preserved across this operator.
14851 * The upstream is requested {@link #bufferSize()} - 1 upfront and 75% of {@link #bufferSize()} thereafter.</dd>
14852 * <dt><b>Scheduler:</b></dt>
14853 * <dd>{@code scan} does not operate by default on a particular {@link Scheduler}.</dd>
14854 * </dl>
14855 *
14856 * @param <R> the initial, accumulator and result type
14857 * @param initialValue
14858 * the initial (seed) accumulator item
14859 * @param accumulator
14860 * an accumulator function to be invoked on each item emitted by the current {@code Flowable}, whose
14861 * result will be emitted to {@link Subscriber}s via {@link Subscriber#onNext onNext} and used in the
14862 * next accumulator call
14863 * @return the new {@code Flowable} instance
14864 * @throws NullPointerException if {@code initialValue} or {@code accumulator} is {@code null}
14865 * @see <a href="http://reactivex.io/documentation/operators/scan.html">ReactiveX operators documentation: Scan</a>
14866 */
14867 @CheckReturnValue
14868 @NonNull
14869 @BackpressureSupport(BackpressureKind.FULL)
14870 @SchedulerSupport(SchedulerSupport.NONE)
14871 public final <@NonNull R> Flowable<R> scan(R initialValue, @NonNull BiFunction<R, ? super T, R> accumulator) {
14872 Objects.requireNonNull(initialValue, "initialValue is null");
14873 return scanWith(Functions.justSupplier(initialValue), accumulator);
14874 }
14875
14876 /**
14877 * Returns a {@code Flowable} that emits the provided initial (seed) value, then emits one value for each value emitted
14878 * by the current {@code Flowable}. Each emission after the first is the result of applying the specified accumulator
14879 * function to the previous emission and the corresponding value from the current {@code Flowable}.
14880 * <p>
14881 * <img width="640" height="320" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/scanSeed.v3.png" alt="">
14882 * <p>
14883 * This sort of function is sometimes called an accumulator.
14884 * <p>
14885 * Note that the {@code Flowable} that results from this method will emit the value returned by
14886 * the {@code seedSupplier} as its first item.
14887 * <dl>
14888 * <dt><b>Backpressure:</b></dt>
14889 * <dd>The operator honors downstream backpressure and expects the current {@code Flowable} to honor backpressure as well.
14890 * Violating this expectation, a {@link MissingBackpressureException} <em>may</em> get signaled somewhere downstream.
14891 * The downstream request pattern is not preserved across this operator.
14892 * The upstream is requested {@link #bufferSize()} - 1 upfront and 75% of {@link #bufferSize()} thereafter.</dd>
14893 * <dt><b>Scheduler:</b></dt>
14894 * <dd>{@code scanWith} does not operate by default on a particular {@link Scheduler}.</dd>
14895 * </dl>
14896 *
14897 * @param <R> the initial, accumulator and result type
14898 * @param seedSupplier
14899 * a {@link Supplier} that returns the initial (seed) accumulator item for each individual {@link Subscriber}
14900 * @param accumulator
14901 * an accumulator function to be invoked on each item emitted by the current {@code Flowable}, whose
14902 * result will be emitted to {@code Subscriber}s via {@link Subscriber#onNext onNext} and used in the
14903 * next accumulator call
14904 * @return the new {@code Flowable} instance
14905 * @throws NullPointerException if {@code seedSupplier} or {@code accumulator} is {@code null}
14906 * @see <a href="http://reactivex.io/documentation/operators/scan.html">ReactiveX operators documentation: Scan</a>
14907 */
14908 @CheckReturnValue
14909 @NonNull
14910 @BackpressureSupport(BackpressureKind.FULL)
14911 @SchedulerSupport(SchedulerSupport.NONE)
14912 public final <@NonNull R> Flowable<R> scanWith(@NonNull Supplier<R> seedSupplier, @NonNull BiFunction<R, ? super T, R> accumulator) {
14913 Objects.requireNonNull(seedSupplier, "seedSupplier is null");
14914 Objects.requireNonNull(accumulator, "accumulator is null");
14915 return RxJavaPlugins.onAssembly(new FlowableScanSeed<>(this, seedSupplier, accumulator));
14916 }
14917
14918 /**
14919 * Forces the current {@code Flowable}'s emissions and notifications to be serialized and for it to obey
14920 * <a href="http://reactivex.io/documentation/contract.html">the {@code Publisher} contract</a> in other ways.
14921 * <p>
14922 * It is possible for a {@link Publisher} to invoke its {@link Subscriber}s' methods asynchronously, perhaps from
14923 * different threads. This could make such a {@code Publisher} poorly-behaved, in that it might try to invoke
14924 * {@code onComplete} or {@code onError} before one of its {@code onNext} invocations, or it might call
14925 * {@code onNext} from two different threads concurrently. You can force such a {@code Publisher} to be
14926 * well-behaved and sequential by applying the {@code serialize} method to it.
14927 * <p>
14928 * <img width="640" height="400" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/synchronize.v3.png" alt="">
14929 * <dl>
14930 * <dt><b>Backpressure:</b></dt>
14931 * <dd>The operator doesn't interfere with backpressure which is determined by the current {@code Flowable}'s backpressure
14932 * behavior.</dd>
14933 * <dt><b>Scheduler:</b></dt>
14934 * <dd>{@code serialize} does not operate by default on a particular {@link Scheduler}.</dd>
14935 * </dl>
14936 *
14937 * @return the new {@code Flowable} instance
14938 * @see <a href="http://reactivex.io/documentation/operators/serialize.html">ReactiveX operators documentation: Serialize</a>
14939 */
14940 @CheckReturnValue
14941 @BackpressureSupport(BackpressureKind.PASS_THROUGH)
14942 @SchedulerSupport(SchedulerSupport.NONE)
14943 @NonNull
14944 public final Flowable<T> serialize() {
14945 return RxJavaPlugins.onAssembly(new FlowableSerialized<>(this));
14946 }
14947
14948 /**
14949 * Returns a new {@code Flowable} that multicasts (and shares a single subscription to) the current {@code Flowable}. As long as
14950 * there is at least one {@link Subscriber}, the current {@code Flowable} will be subscribed and emitting data.
14951 * When all subscribers have canceled it will cancel the current {@code Flowable}.
14952 * <p>
14953 * This is an alias for {@link #publish()}.{@link ConnectableFlowable#refCount() refCount()}.
14954 * <p>
14955 * <img width="640" height="510" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/publishRefCount.v3.png" alt="">
14956 * <dl>
14957 * <dt><b>Backpressure:</b></dt>
14958 * <dd>The operator honors backpressure and expects the current {@code Flowable} to honor backpressure as well.
14959 * If this expectation is violated, the operator will signal a {@link MissingBackpressureException} to
14960 * its {@code Subscriber}s.</dd>
14961 * <dt><b>Scheduler:</b></dt>
14962 * <dd>{@code share} does not operate by default on a particular {@link Scheduler}.</dd>
14963 * </dl>
14964 *
14965 * @return the new {@code Flowable} instance
14966 * @see <a href="http://reactivex.io/documentation/operators/refcount.html">ReactiveX operators documentation: RefCount</a>
14967 */
14968 @CheckReturnValue
14969 @BackpressureSupport(BackpressureKind.FULL)
14970 @SchedulerSupport(SchedulerSupport.NONE)
14971 @NonNull
14972 public final Flowable<T> share() {
14973 return publish().refCount();
14974 }
14975
14976 /**
14977 * Returns a {@link Maybe} that completes if this {@code Flowable} is empty, signals one item if this {@code Flowable}
14978 * signals exactly one item or signals an {@link IllegalArgumentException} if this {@code Flowable} signals
14979 * more than one item.
14980 * <p>
14981 * <img width="640" height="315" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/single.v3.png" alt="">
14982 * <dl>
14983 * <dt><b>Backpressure:</b></dt>
14984 * <dd>The operator honors backpressure from downstream and consumes the current {@code Flowable} in an
14985 * unbounded manner (i.e., without applying backpressure).</dd>
14986 * <dt><b>Scheduler:</b></dt>
14987 * <dd>{@code singleElement} does not operate by default on a particular {@link Scheduler}.</dd>
14988 * </dl>
14989 *
14990 * @return the new {@code Maybe} instance
14991 * @see <a href="http://reactivex.io/documentation/operators/first.html">ReactiveX operators documentation: First</a>
14992 */
14993 @CheckReturnValue
14994 @BackpressureSupport(BackpressureKind.UNBOUNDED_IN)
14995 @SchedulerSupport(SchedulerSupport.NONE)
14996 @NonNull
14997 public final Maybe<T> singleElement() {
14998 return RxJavaPlugins.onAssembly(new FlowableSingleMaybe<>(this));
14999 }
15000
15001 /**
15002 * Returns a {@link Single} that emits the single item emitted by the current {@code Flowable} if it
15003 * emits only a single item, or a default item if the current {@code Flowable} emits no items. If the current
15004 * {@code Flowable} emits more than one item, an {@link IllegalArgumentException} is signaled instead.
15005 * <p>
15006 * <img width="640" height="315" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/singleOrDefault.v3.png" alt="">
15007 * <dl>
15008 * <dt><b>Backpressure:</b></dt>
15009 * <dd>The operator honors backpressure from downstream and consumes the current {@code Flowable} in an
15010 * unbounded manner (i.e., without applying backpressure).</dd>
15011 * <dt><b>Scheduler:</b></dt>
15012 * <dd>{@code single} does not operate by default on a particular {@link Scheduler}.</dd>
15013 * </dl>
15014 *
15015 * @param defaultItem
15016 * a default value to emit if the current {@code Flowable} emits no item
15017 * @return the new {@code Single} instance
15018 * @throws NullPointerException if {@code defaultItem} is {@code null}
15019 * @see <a href="http://reactivex.io/documentation/operators/first.html">ReactiveX operators documentation: First</a>
15020 */
15021 @CheckReturnValue
15022 @NonNull
15023 @BackpressureSupport(BackpressureKind.UNBOUNDED_IN)
15024 @SchedulerSupport(SchedulerSupport.NONE)
15025 public final Single<T> single(@NonNull T defaultItem) {
15026 Objects.requireNonNull(defaultItem, "defaultItem is null");
15027 return RxJavaPlugins.onAssembly(new FlowableSingleSingle<>(this, defaultItem));
15028 }
15029
15030 /**
15031 * Returns a {@link Single} that emits the single item emitted by this {@code Flowable}, if this {@code Flowable}
15032 * emits only a single item, otherwise
15033 * if this {@code Flowable} completes without emitting any items a {@link NoSuchElementException} will be signaled and
15034 * if this {@code Flowable} emits more than one item, an {@link IllegalArgumentException} will be signaled.
15035 * <p>
15036 * <img width="640" height="206" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/singleOrError.png" alt="">
15037 * <dl>
15038 * <dt><b>Backpressure:</b></dt>
15039 * <dd>The operator honors backpressure from downstream and consumes the current {@code Flowable} in an
15040 * unbounded manner (i.e., without applying backpressure).</dd>
15041 * <dt><b>Scheduler:</b></dt>
15042 * <dd>{@code singleOrError} does not operate by default on a particular {@link Scheduler}.</dd>
15043 * </dl>
15044 *
15045 * @return the new {@code Single} instance
15046 * @see <a href="http://reactivex.io/documentation/operators/first.html">ReactiveX operators documentation: First</a>
15047 */
15048 @CheckReturnValue
15049 @BackpressureSupport(BackpressureKind.UNBOUNDED_IN)
15050 @SchedulerSupport(SchedulerSupport.NONE)
15051 @NonNull
15052 public final Single<T> singleOrError() {
15053 return RxJavaPlugins.onAssembly(new FlowableSingleSingle<>(this, null));
15054 }
15055
15056 /**
15057 * Returns a {@code Flowable} that skips the first {@code count} items emitted by the current {@code Flowable} and emits
15058 * the remainder.
15059 * <p>
15060 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/skip.v3.png" alt="">
15061 * <dl>
15062 * <dt><b>Backpressure:</b></dt>
15063 * <dd>The operator doesn't interfere with backpressure which is determined by the current {@code Flowable}'s backpressure
15064 * behavior.</dd>
15065 * <dt><b>Scheduler:</b></dt>
15066 * <dd>This version of {@code skip} does not operate by default on a particular {@link Scheduler}.</dd>
15067 * </dl>
15068 *
15069 * @param count
15070 * the number of items to skip
15071 * @return the new {@code Flowable} instance
15072 * @throws IllegalArgumentException if {@code count} is negative
15073 * @see <a href="http://reactivex.io/documentation/operators/skip.html">ReactiveX operators documentation: Skip</a>
15074 */
15075 @CheckReturnValue
15076 @BackpressureSupport(BackpressureKind.FULL)
15077 @SchedulerSupport(SchedulerSupport.NONE)
15078 @NonNull
15079 public final Flowable<T> skip(long count) {
15080 if (count < 0) {
15081 throw new IllegalArgumentException("count >= 0 expected but it was " + count);
15082 }
15083 if (count == 0) {
15084 return RxJavaPlugins.onAssembly(this);
15085 }
15086 return RxJavaPlugins.onAssembly(new FlowableSkip<>(this, count));
15087 }
15088
15089 /**
15090 * Returns a {@code Flowable} that skips values emitted by the current {@code Flowable} before a specified time window
15091 * elapses.
15092 * <p>
15093 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/skip.t.v3.png" alt="">
15094 * <dl>
15095 * <dt><b>Backpressure:</b></dt>
15096 * <dd>The operator doesn't support backpressure as it uses time to skip an arbitrary number of elements and
15097 * thus has to consume the current {@code Flowable} in an unbounded manner (i.e., no backpressure applied to it).</dd>
15098 * <dt><b>Scheduler:</b></dt>
15099 * <dd>{@code skip} does not operate on any particular scheduler but uses the current time
15100 * from the {@code computation} {@link Scheduler}.</dd>
15101 * </dl>
15102 *
15103 * @param time
15104 * the length of the time window to skip
15105 * @param unit
15106 * the time unit of {@code time}
15107 * @return the new {@code Flowable} instance
15108 * @throws NullPointerException if {@code unit} is {@code null}
15109 * @see <a href="http://reactivex.io/documentation/operators/skip.html">ReactiveX operators documentation: Skip</a>
15110 */
15111 @CheckReturnValue
15112 @BackpressureSupport(BackpressureKind.FULL)
15113 @SchedulerSupport(SchedulerSupport.NONE)
15114 @NonNull
15115 public final Flowable<T> skip(long time, @NonNull TimeUnit unit) {
15116 return skipUntil(timer(time, unit));
15117 }
15118
15119 /**
15120 * Returns a {@code Flowable} that skips values emitted by the current {@code Flowable} before a specified time window
15121 * on a specified {@link Scheduler} elapses.
15122 * <p>
15123 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/skip.ts.v3.png" alt="">
15124 * <dl>
15125 * <dt><b>Backpressure:</b></dt>
15126 * <dd>The operator doesn't support backpressure as it uses time to skip an arbitrary number of elements and
15127 * thus has to consume the current {@code Flowable} in an unbounded manner (i.e., no backpressure applied to it).</dd>
15128 * <dt><b>Scheduler:</b></dt>
15129 * <dd>You specify which {@code Scheduler} this operator will use for the timed skipping</dd>
15130 * </dl>
15131 *
15132 * @param time
15133 * the length of the time window to skip
15134 * @param unit
15135 * the time unit of {@code time}
15136 * @param scheduler
15137 * the {@code Scheduler} on which the timed wait happens
15138 * @return the new {@code Flowable} instance
15139 * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null}
15140 * @see <a href="http://reactivex.io/documentation/operators/skip.html">ReactiveX operators documentation: Skip</a>
15141 */
15142 @CheckReturnValue
15143 @BackpressureSupport(BackpressureKind.FULL)
15144 @SchedulerSupport(SchedulerSupport.CUSTOM)
15145 @NonNull
15146 public final Flowable<T> skip(long time, @NonNull TimeUnit unit, @NonNull Scheduler scheduler) {
15147 return skipUntil(timer(time, unit, scheduler));
15148 }
15149
15150 /**
15151 * Returns a {@code Flowable} that drops a specified number of items from the end of the sequence emitted by the
15152 * current {@code Flowable}.
15153 * <p>
15154 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/skipLast.v3.png" alt="">
15155 * <p>
15156 * This {@link Subscriber} accumulates a queue long enough to store the first {@code count} items. As more items are
15157 * received, items are taken from the front of the queue and emitted by the resulting {@code Flowable}. This causes
15158 * such items to be delayed.
15159 * <dl>
15160 * <dt><b>Backpressure:</b></dt>
15161 * <dd>The operator doesn't interfere with backpressure which is determined by the current {@code Flowable}'s backpressure
15162 * behavior.</dd>
15163 * <dt><b>Scheduler:</b></dt>
15164 * <dd>This version of {@code skipLast} does not operate by default on a particular {@link Scheduler}.</dd>
15165 * </dl>
15166 *
15167 * @param count
15168 * number of items to drop from the end of the source sequence
15169 * @return the new {@code Flowable} instance
15170 * @throws IllegalArgumentException
15171 * if {@code count} is less than zero
15172 * @see <a href="http://reactivex.io/documentation/operators/skiplast.html">ReactiveX operators documentation: SkipLast</a>
15173 */
15174 @CheckReturnValue
15175 @BackpressureSupport(BackpressureKind.FULL)
15176 @SchedulerSupport(SchedulerSupport.NONE)
15177 @NonNull
15178 public final Flowable<T> skipLast(int count) {
15179 if (count < 0) {
15180 throw new IllegalArgumentException("count >= 0 required but it was " + count);
15181 }
15182 if (count == 0) {
15183 return RxJavaPlugins.onAssembly(this);
15184 }
15185 return RxJavaPlugins.onAssembly(new FlowableSkipLast<>(this, count));
15186 }
15187
15188 /**
15189 * Returns a {@code Flowable} that drops items emitted by the current {@code Flowable} during a specified time window
15190 * before the source completes.
15191 * <p>
15192 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/skipLast.t.v3.png" alt="">
15193 * <p>
15194 * Note: this action will cache the latest items arriving in the specified time window.
15195 * <dl>
15196 * <dt><b>Backpressure:</b></dt>
15197 * <dd>The operator doesn't support backpressure as it uses time to skip an arbitrary number of elements and
15198 * thus has to consume the current {@code Flowable} in an unbounded manner (i.e., no backpressure applied to it).</dd>
15199 * <dt><b>Scheduler:</b></dt>
15200 * <dd>{@code skipLast} does not operate on any particular scheduler but uses the current time
15201 * from the {@code computation} {@link Scheduler}.</dd>
15202 * </dl>
15203 *
15204 * @param time
15205 * the length of the time window
15206 * @param unit
15207 * the time unit of {@code time}
15208 * @return the new {@code Flowable} instance
15209 * @throws NullPointerException if {@code unit} is {@code null}
15210 * @see <a href="http://reactivex.io/documentation/operators/skiplast.html">ReactiveX operators documentation: SkipLast</a>
15211 */
15212 @CheckReturnValue
15213 @BackpressureSupport(BackpressureKind.UNBOUNDED_IN)
15214 @SchedulerSupport(SchedulerSupport.NONE)
15215 @NonNull
15216 public final Flowable<T> skipLast(long time, @NonNull TimeUnit unit) {
15217 return skipLast(time, unit, Schedulers.computation(), false, bufferSize());
15218 }
15219
15220 /**
15221 * Returns a {@code Flowable} that drops items emitted by the current {@code Flowable} during a specified time window
15222 * before the source completes.
15223 * <p>
15224 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/skipLast.t.v3.png" alt="">
15225 * <p>
15226 * Note: this action will cache the latest items arriving in the specified time window.
15227 * <dl>
15228 * <dt><b>Backpressure:</b></dt>
15229 * <dd>The operator doesn't support backpressure as it uses time to skip an arbitrary number of elements and
15230 * thus has to consume the current {@code Flowable} in an unbounded manner (i.e., no backpressure applied to it).</dd>
15231 * <dt><b>Scheduler:</b></dt>
15232 * <dd>{@code skipLast} does not operate on any particular scheduler but uses the current time
15233 * from the {@code computation} {@link Scheduler}.</dd>
15234 * </dl>
15235 *
15236 * @param time
15237 * the length of the time window
15238 * @param unit
15239 * the time unit of {@code time}
15240 * @param delayError
15241 * if {@code true}, an exception signaled by the current {@code Flowable} is delayed until the regular elements are consumed
15242 * by the downstream; if {@code false}, an exception is immediately signaled and all regular elements dropped
15243 * @return the new {@code Flowable} instance
15244 * @throws NullPointerException if {@code unit} is {@code null}
15245 * @see <a href="http://reactivex.io/documentation/operators/skiplast.html">ReactiveX operators documentation: SkipLast</a>
15246 */
15247 @CheckReturnValue
15248 @BackpressureSupport(BackpressureKind.UNBOUNDED_IN)
15249 @SchedulerSupport(SchedulerSupport.NONE)
15250 @NonNull
15251 public final Flowable<T> skipLast(long time, @NonNull TimeUnit unit, boolean delayError) {
15252 return skipLast(time, unit, Schedulers.computation(), delayError, bufferSize());
15253 }
15254
15255 /**
15256 * Returns a {@code Flowable} that drops items emitted by the current {@code Flowable} during a specified time window
15257 * (defined on a specified scheduler) before the source completes.
15258 * <p>
15259 * <img width="640" height="340" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/skipLast.ts.v3.png" alt="">
15260 * <p>
15261 * Note: this action will cache the latest items arriving in the specified time window.
15262 * <dl>
15263 * <dt><b>Backpressure:</b></dt>
15264 * <dd>The operator doesn't support backpressure as it uses time to skip an arbitrary number of elements and
15265 * thus has to consume the current {@code Flowable} in an unbounded manner (i.e., no backpressure applied to it).</dd>
15266 * <dt><b>Scheduler:</b></dt>
15267 * <dd>You specify which {@link Scheduler} this operator will use for tracking the current time</dd>
15268 * </dl>
15269 *
15270 * @param time
15271 * the length of the time window
15272 * @param unit
15273 * the time unit of {@code time}
15274 * @param scheduler
15275 * the scheduler used as the time source
15276 * @return the new {@code Flowable} instance
15277 * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null}
15278 * @see <a href="http://reactivex.io/documentation/operators/skiplast.html">ReactiveX operators documentation: SkipLast</a>
15279 */
15280 @CheckReturnValue
15281 @BackpressureSupport(BackpressureKind.UNBOUNDED_IN)
15282 @SchedulerSupport(SchedulerSupport.CUSTOM)
15283 @NonNull
15284 public final Flowable<T> skipLast(long time, @NonNull TimeUnit unit, @NonNull Scheduler scheduler) {
15285 return skipLast(time, unit, scheduler, false, bufferSize());
15286 }
15287
15288 /**
15289 * Returns a {@code Flowable} that drops items emitted by the current {@code Flowable} during a specified time window
15290 * (defined on a specified scheduler) before the source completes.
15291 * <p>
15292 * <img width="640" height="340" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/skipLast.ts.v3.png" alt="">
15293 * <p>
15294 * Note: this action will cache the latest items arriving in the specified time window.
15295 * <dl>
15296 * <dt><b>Backpressure:</b></dt>
15297 * <dd>The operator doesn't support backpressure as it uses time to skip an arbitrary number of elements and
15298 * thus has to consume the current {@code Flowable} in an unbounded manner (i.e., no backpressure applied to it).</dd>
15299 * <dt><b>Scheduler:</b></dt>
15300 * <dd>You specify which {@link Scheduler} this operator will use to track the current time</dd>
15301 * </dl>
15302 *
15303 * @param time
15304 * the length of the time window
15305 * @param unit
15306 * the time unit of {@code time}
15307 * @param scheduler
15308 * the scheduler used as the time source
15309 * @param delayError
15310 * if {@code true}, an exception signaled by the current {@code Flowable} is delayed until the regular elements are consumed
15311 * by the downstream; if {@code false}, an exception is immediately signaled and all regular elements dropped
15312 * @return the new {@code Flowable} instance
15313 * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null}
15314 * @see <a href="http://reactivex.io/documentation/operators/skiplast.html">ReactiveX operators documentation: SkipLast</a>
15315 */
15316 @CheckReturnValue
15317 @BackpressureSupport(BackpressureKind.UNBOUNDED_IN)
15318 @SchedulerSupport(SchedulerSupport.CUSTOM)
15319 @NonNull
15320 public final Flowable<T> skipLast(long time, @NonNull TimeUnit unit, @NonNull Scheduler scheduler, boolean delayError) {
15321 return skipLast(time, unit, scheduler, delayError, bufferSize());
15322 }
15323
15324 /**
15325 * Returns a {@code Flowable} that drops items emitted by the current {@code Flowable} during a specified time window
15326 * (defined on a specified scheduler) before the source completes.
15327 * <p>
15328 * <img width="640" height="340" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/skipLast.ts.v3.png" alt="">
15329 * <p>
15330 * Note: this action will cache the latest items arriving in the specified time window.
15331 * <dl>
15332 * <dt><b>Backpressure:</b></dt>
15333 * <dd>The operator doesn't support backpressure as it uses time to skip an arbitrary number of elements and
15334 * thus has to consume the current {@code Flowable} in an unbounded manner (i.e., no backpressure applied to it).</dd>
15335 * <dt><b>Scheduler:</b></dt>
15336 * <dd>You specify which {@link Scheduler} this operator will use.</dd>
15337 * </dl>
15338 *
15339 * @param time
15340 * the length of the time window
15341 * @param unit
15342 * the time unit of {@code time}
15343 * @param scheduler
15344 * the scheduler used as the time source
15345 * @param delayError
15346 * if {@code true}, an exception signaled by the current {@code Flowable} is delayed until the regular elements are consumed
15347 * by the downstream; if {@code false}, an exception is immediately signaled and all regular elements dropped
15348 * @param bufferSize
15349 * the hint about how many elements to expect to be skipped
15350 * @return the new {@code Flowable} instance
15351 * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null}
15352 * @throws IllegalArgumentException if {@code bufferSize} is non-positive
15353 * @see <a href="http://reactivex.io/documentation/operators/skiplast.html">ReactiveX operators documentation: SkipLast</a>
15354 */
15355 @CheckReturnValue
15356 @NonNull
15357 @BackpressureSupport(BackpressureKind.UNBOUNDED_IN)
15358 @SchedulerSupport(SchedulerSupport.CUSTOM)
15359 public final Flowable<T> skipLast(long time, @NonNull TimeUnit unit, @NonNull Scheduler scheduler, boolean delayError, int bufferSize) {
15360 Objects.requireNonNull(unit, "unit is null");
15361 Objects.requireNonNull(scheduler, "scheduler is null");
15362 ObjectHelper.verifyPositive(bufferSize, "bufferSize");
15363 // the internal buffer holds pairs of (timestamp, value) so double the default buffer size
15364 int s = bufferSize << 1;
15365 return RxJavaPlugins.onAssembly(new FlowableSkipLastTimed<>(this, time, unit, scheduler, s, delayError));
15366 }
15367
15368 /**
15369 * Returns a {@code Flowable} that skips items emitted by the current {@code Flowable} until a second {@link Publisher} emits
15370 * an item.
15371 * <p>
15372 * <img width="640" height="375" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/skipUntil.v3.png" alt="">
15373 * <dl>
15374 * <dt><b>Backpressure:</b></dt>
15375 * <dd>The operator doesn't interfere with backpressure which is determined by the current {@code Flowable}'s backpressure
15376 * behavior.</dd>
15377 * <dt><b>Scheduler:</b></dt>
15378 * <dd>{@code skipUntil} does not operate by default on a particular {@link Scheduler}.</dd>
15379 * </dl>
15380 *
15381 * @param <U> the element type of the other {@code Publisher}
15382 * @param other
15383 * the second {@code Publisher} that has to emit an item before the current {@code Flowable}'s elements begin
15384 * to be mirrored by the resulting {@code Flowable}
15385 * @return the new {@code Flowable} instance
15386 * @throws NullPointerException if {@code other} is {@code null}
15387 * @see <a href="http://reactivex.io/documentation/operators/skipuntil.html">ReactiveX operators documentation: SkipUntil</a>
15388 */
15389 @CheckReturnValue
15390 @NonNull
15391 @BackpressureSupport(BackpressureKind.FULL)
15392 @SchedulerSupport(SchedulerSupport.NONE)
15393 public final <@NonNull U> Flowable<T> skipUntil(@NonNull Publisher<U> other) {
15394 Objects.requireNonNull(other, "other is null");
15395 return RxJavaPlugins.onAssembly(new FlowableSkipUntil<>(this, other));
15396 }
15397
15398 /**
15399 * Returns a {@code Flowable} that skips all items emitted by the current {@code Flowable} as long as a specified
15400 * condition holds {@code true}, but emits all further source items as soon as the condition becomes {@code false}.
15401 * <p>
15402 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/skipWhile.v3.png" alt="">
15403 * <dl>
15404 * <dt><b>Backpressure:</b></dt>
15405 * <dd>The operator doesn't interfere with backpressure which is determined by the current {@code Flowable}'s backpressure
15406 * behavior.</dd>
15407 * <dt><b>Scheduler:</b></dt>
15408 * <dd>{@code skipWhile} does not operate by default on a particular {@link Scheduler}.</dd>
15409 * </dl>
15410 *
15411 * @param predicate
15412 * a function to test each item emitted from the current {@code Flowable}
15413 * @return the new {@code Flowable} instance
15414 * @throws NullPointerException if {@code predicate} is {@code null}
15415 * @see <a href="http://reactivex.io/documentation/operators/skipwhile.html">ReactiveX operators documentation: SkipWhile</a>
15416 */
15417 @CheckReturnValue
15418 @NonNull
15419 @BackpressureSupport(BackpressureKind.FULL)
15420 @SchedulerSupport(SchedulerSupport.NONE)
15421 public final Flowable<T> skipWhile(@NonNull Predicate<? super T> predicate) {
15422 Objects.requireNonNull(predicate, "predicate is null");
15423 return RxJavaPlugins.onAssembly(new FlowableSkipWhile<>(this, predicate));
15424 }
15425 /**
15426 * Returns a {@code Flowable} that emits the events emitted by source {@link Publisher}, in a
15427 * sorted order. Each item emitted by the {@code Publisher} must implement {@link Comparable} with respect to all
15428 * other items in the sequence.
15429 *
15430 * <p>If any item emitted by this {@code Flowable} does not implement {@code Comparable} with respect to
15431 * all other items emitted by this {@code Flowable}, no items will be emitted and the
15432 * sequence is terminated with a {@link ClassCastException}.
15433 * <p>Note that calling {@code sorted} with long, non-terminating or infinite sources
15434 * might cause {@link OutOfMemoryError}
15435 *
15436 * <dl>
15437 * <dt><b>Backpressure:</b></dt>
15438 * <dd>The operator honors backpressure from downstream and consumes the current {@code Flowable} in an
15439 * unbounded manner (i.e., without applying backpressure to it).</dd>
15440 * <dt><b>Scheduler:</b></dt>
15441 * <dd>{@code sorted} does not operate by default on a particular {@link Scheduler}.</dd>
15442 * </dl>
15443 *
15444 * @return the new {@code Flowable} instance
15445 */
15446 @CheckReturnValue
15447 @BackpressureSupport(BackpressureKind.FULL)
15448 @SchedulerSupport(SchedulerSupport.NONE)
15449 @NonNull
15450 public final Flowable<T> sorted() {
15451 return toList().toFlowable().map(Functions.listSorter(Functions.naturalComparator())).flatMapIterable(Functions.identity());
15452 }
15453
15454 /**
15455 * Returns a {@code Flowable} that emits the events emitted by source {@link Publisher}, in a
15456 * sorted order based on a specified comparison function.
15457 *
15458 * <p>Note that calling {@code sorted} with long, non-terminating or infinite sources
15459 * might cause {@link OutOfMemoryError}
15460 *
15461 * <dl>
15462 * <dt><b>Backpressure:</b></dt>
15463 * <dd>The operator honors backpressure from downstream and consumes the current {@code Flowable} in an
15464 * unbounded manner (i.e., without applying backpressure to it).</dd>
15465 * <dt><b>Scheduler:</b></dt>
15466 * <dd>{@code sorted} does not operate by default on a particular {@link Scheduler}.</dd>
15467 * </dl>
15468 *
15469 * @param comparator
15470 * a function that compares two items emitted by the current {@code Flowable} and returns an {@link Integer}
15471 * that indicates their sort order
15472 * @throws NullPointerException if {@code comparator} is {@code null}
15473 * @return the new {@code Flowable} instance
15474 */
15475 @CheckReturnValue
15476 @NonNull
15477 @BackpressureSupport(BackpressureKind.FULL)
15478 @SchedulerSupport(SchedulerSupport.NONE)
15479 public final Flowable<T> sorted(@NonNull Comparator<@NonNull ? super T> comparator) {
15480 Objects.requireNonNull(comparator, "comparator is null");
15481 return toList().toFlowable().map(Functions.listSorter(comparator)).flatMapIterable(Functions.identity());
15482 }
15483
15484 /**
15485 * Returns a {@code Flowable} that emits the items in a specified {@link Iterable} before it begins to emit items
15486 * emitted by the current {@code Flowable}.
15487 * <p>
15488 * <img width="640" height="315" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/startWith.v3.png" alt="">
15489 * <dl>
15490 * <dt><b>Backpressure:</b></dt>
15491 * <dd>The operator honors backpressure from downstream. The Current {@code Flowable}
15492 * is expected to honor backpressure as well. If it violates this rule, it <em>may</em> throw an
15493 * {@link IllegalStateException} when the current {@code Flowable} completes.</dd>
15494 * <dt><b>Scheduler:</b></dt>
15495 * <dd>{@code startWithIterable} does not operate by default on a particular {@link Scheduler}.</dd>
15496 * </dl>
15497 *
15498 * @param items
15499 * an {@code Iterable} that contains the items you want the resulting {@code Flowable} to emit first
15500 * @return the new {@code Flowable} instance
15501 * @throws NullPointerException if {@code items} is {@code null}
15502 * @see <a href="http://reactivex.io/documentation/operators/startwith.html">ReactiveX operators documentation: StartWith</a>
15503 * @see #startWithArray(Object...)
15504 * @see #startWithItem(Object)
15505 * @since 3.0.0
15506 */
15507 @CheckReturnValue
15508 @BackpressureSupport(BackpressureKind.FULL)
15509 @SchedulerSupport(SchedulerSupport.NONE)
15510 @NonNull
15511 public final Flowable<T> startWithIterable(@NonNull Iterable<? extends T> items) {
15512 return concatArray(fromIterable(items), this);
15513 }
15514
15515 /**
15516 * Returns a {@code Flowable} which first runs the other {@link CompletableSource}
15517 * then the current {@code Flowable} if the other completed normally.
15518 * <p>
15519 * <img width="640" height="268" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Flowable.startWith.c.png" alt="">
15520 * <dl>
15521 * <dt><b>Backpressure:</b></dt>
15522 * <dd>The returned {@code Flowable} honors the backpressure of the downstream consumer.</dd>
15523 * <dt><b>Scheduler:</b></dt>
15524 * <dd>{@code startWith} does not operate by default on a particular {@link Scheduler}.</dd>
15525 * </dl>
15526 * @param other the other {@code CompletableSource} to run first
15527 * @return the new {@code Flowable} instance
15528 * @throws NullPointerException if {@code other} is {@code null}
15529 * @since 3.0.0
15530 */
15531 @CheckReturnValue
15532 @NonNull
15533 @SchedulerSupport(SchedulerSupport.NONE)
15534 @BackpressureSupport(BackpressureKind.FULL)
15535 public final Flowable<T> startWith(@NonNull CompletableSource other) {
15536 Objects.requireNonNull(other, "other is null");
15537 return Flowable.concat(Completable.wrap(other).<T>toFlowable(), this);
15538 }
15539
15540 /**
15541 * Returns a {@code Flowable} which first runs the other {@link SingleSource}
15542 * then the current {@code Flowable} if the other succeeded normally.
15543 * <p>
15544 * <img width="640" height="248" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Flowable.startWith.s.png" alt="">
15545 * <dl>
15546 * <dt><b>Backpressure:</b></dt>
15547 * <dd>The returned {@code Flowable} honors the backpressure of the downstream consumer.</dd>
15548 * <dt><b>Scheduler:</b></dt>
15549 * <dd>{@code startWith} does not operate by default on a particular {@link Scheduler}.</dd>
15550 * </dl>
15551 * @param other the other {@code SingleSource} to run first
15552 * @return the new {@code Flowable} instance
15553 * @throws NullPointerException if {@code other} is {@code null}
15554 * @since 3.0.0
15555 */
15556 @CheckReturnValue
15557 @NonNull
15558 @SchedulerSupport(SchedulerSupport.NONE)
15559 @BackpressureSupport(BackpressureKind.FULL)
15560 public final Flowable<T> startWith(@NonNull SingleSource<T> other) {
15561 Objects.requireNonNull(other, "other is null");
15562 return Flowable.concat(Single.wrap(other).toFlowable(), this);
15563 }
15564
15565 /**
15566 * Returns a {@code Flowable} which first runs the other {@link MaybeSource}
15567 * then the current {@code Flowable} if the other succeeded or completed normally.
15568 * <p>
15569 * <img width="640" height="168" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Flowable.startWith.m.png" alt="">
15570 * <dl>
15571 * <dt><b>Backpressure:</b></dt>
15572 * <dd>The returned {@code Flowable} honors the backpressure of the downstream consumer.</dd>
15573 * <dt><b>Scheduler:</b></dt>
15574 * <dd>{@code startWith} does not operate by default on a particular {@link Scheduler}.</dd>
15575 * </dl>
15576 * @param other the other {@code MaybeSource} to run first
15577 * @return the new {@code Flowable} instance
15578 * @throws NullPointerException if {@code other} is {@code null}
15579 * @since 3.0.0
15580 */
15581 @CheckReturnValue
15582 @NonNull
15583 @SchedulerSupport(SchedulerSupport.NONE)
15584 @BackpressureSupport(BackpressureKind.FULL)
15585 public final Flowable<T> startWith(@NonNull MaybeSource<T> other) {
15586 Objects.requireNonNull(other, "other is null");
15587 return Flowable.concat(Maybe.wrap(other).toFlowable(), this);
15588 }
15589
15590 /**
15591 * Returns a {@code Flowable} that emits the items in a specified {@link Publisher} before it begins to emit
15592 * items emitted by the current {@code Flowable}.
15593 * <p>
15594 * <img width="640" height="315" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/startWith.o.v3.png" alt="">
15595 * <dl>
15596 * <dt><b>Backpressure:</b></dt>
15597 * <dd>The operator honors backpressure from downstream. Both this and the {@code other} {@code Publisher}s
15598 * are expected to honor backpressure as well. If any of then violates this rule, it <em>may</em> throw an
15599 * {@link IllegalStateException} when the current {@code Flowable} completes.</dd>
15600 * <dt><b>Scheduler:</b></dt>
15601 * <dd>{@code startWith} does not operate by default on a particular {@link Scheduler}.</dd>
15602 * </dl>
15603 *
15604 * @param other
15605 * a {@code Publisher} that contains the items you want the modified {@code Publisher} to emit first
15606 * @return the new {@code Flowable} instance
15607 * @throws NullPointerException if {@code other} is {@code null}
15608 * @see <a href="http://reactivex.io/documentation/operators/startwith.html">ReactiveX operators documentation: StartWith</a>
15609 */
15610 @CheckReturnValue
15611 @NonNull
15612 @BackpressureSupport(BackpressureKind.FULL)
15613 @SchedulerSupport(SchedulerSupport.NONE)
15614 public final Flowable<T> startWith(@NonNull Publisher<? extends T> other) {
15615 Objects.requireNonNull(other, "other is null");
15616 return concatArray(other, this);
15617 }
15618
15619 /**
15620 * Returns a {@code Flowable} that emits a specified item before it begins to emit items emitted by the current
15621 * {@code Flowable}.
15622 * <p>
15623 * <img width="640" height="315" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/startWith.v3.png" alt="">
15624 * <dl>
15625 * <dt><b>Backpressure:</b></dt>
15626 * <dd>The operator honors backpressure from downstream. The current {@code Flowable}
15627 * is expected to honor backpressure as well. If it violates this rule, it <em>may</em> throw an
15628 * {@link IllegalStateException} when the current {@code Flowable} completes.</dd>
15629 * <dt><b>Scheduler:</b></dt>
15630 * <dd>{@code startWithItem} does not operate by default on a particular {@link Scheduler}.</dd>
15631 * </dl>
15632 *
15633 * @param item
15634 * the item to emit first
15635 * @return the new {@code Flowable} instance
15636 * @throws NullPointerException if {@code item} is {@code null}
15637 * @see <a href="http://reactivex.io/documentation/operators/startwith.html">ReactiveX operators documentation: StartWith</a>
15638 * @see #startWithArray(Object...)
15639 * @see #startWithIterable(Iterable)
15640 * @since 3.0.0
15641 */
15642 @CheckReturnValue
15643 @NonNull
15644 @BackpressureSupport(BackpressureKind.FULL)
15645 @SchedulerSupport(SchedulerSupport.NONE)
15646 public final Flowable<T> startWithItem(@NonNull T item) {
15647 Objects.requireNonNull(item, "item is null");
15648 return concatArray(just(item), this);
15649 }
15650
15651 /**
15652 * Returns a {@code Flowable} that emits the specified items before it begins to emit items emitted by the current
15653 * {@code Flowable}.
15654 * <p>
15655 * <img width="640" height="315" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/startWith.v3.png" alt="">
15656 * <dl>
15657 * <dt><b>Backpressure:</b></dt>
15658 * <dd>The operator honors backpressure from downstream. The current {@code Flowable}
15659 * is expected to honor backpressure as well. If it violates this rule, it <em>may</em> throw an
15660 * {@link IllegalStateException} when the current {@code Flowable} completes.</dd>
15661 * <dt><b>Scheduler:</b></dt>
15662 * <dd>{@code startWithArray} does not operate by default on a particular {@link Scheduler}.</dd>
15663 * </dl>
15664 *
15665 * @param items
15666 * the array of values to emit first
15667 * @return the new {@code Flowable} instance
15668 * @throws NullPointerException if {@code items} is {@code null}
15669 * @see <a href="http://reactivex.io/documentation/operators/startwith.html">ReactiveX operators documentation: StartWith</a>
15670 * @see #startWithItem(Object)
15671 * @see #startWithIterable(Iterable)
15672 */
15673 @CheckReturnValue
15674 @BackpressureSupport(BackpressureKind.FULL)
15675 @SchedulerSupport(SchedulerSupport.NONE)
15676 @SafeVarargs
15677 @NonNull
15678 public final Flowable<T> startWithArray(@NonNull T... items) {
15679 Flowable<T> fromArray = fromArray(items);
15680 if (fromArray == empty()) {
15681 return RxJavaPlugins.onAssembly(this);
15682 }
15683 return concatArray(fromArray, this);
15684 }
15685
15686 /**
15687 * Subscribes to the current {@code Flowable} and ignores {@code onNext} and {@code onComplete} emissions.
15688 * <p>
15689 * If the {@code Flowable} emits an error, it is wrapped into an
15690 * {@link io.reactivex.rxjava3.exceptions.OnErrorNotImplementedException OnErrorNotImplementedException}
15691 * and routed to the {@link RxJavaPlugins#onError(Throwable)} handler.
15692 * <dl>
15693 * <dt><b>Backpressure:</b></dt>
15694 * <dd>The operator consumes the current {@code Flowable} in an unbounded manner (i.e., no
15695 * backpressure is applied to it).</dd>
15696 * <dt><b>Scheduler:</b></dt>
15697 * <dd>{@code subscribe} does not operate by default on a particular {@link Scheduler}.</dd>
15698 * </dl>
15699 *
15700 * @return the new {@link Disposable} instance that allows cancelling the flow
15701 * @see <a href="http://reactivex.io/documentation/operators/subscribe.html">ReactiveX operators documentation: Subscribe</a>
15702 * @see #subscribe(Consumer, Consumer, Action, DisposableContainer)
15703 */
15704 @BackpressureSupport(BackpressureKind.UNBOUNDED_IN)
15705 @SchedulerSupport(SchedulerSupport.NONE)
15706 @NonNull
15707 public final Disposable subscribe() {
15708 return subscribe(Functions.emptyConsumer(), Functions.ON_ERROR_MISSING, Functions.EMPTY_ACTION);
15709 }
15710
15711 /**
15712 * Subscribes to the current {@code Flowable} and provides a callback to handle the items it emits.
15713 * <p>
15714 * If the {@code Flowable} emits an error, it is wrapped into an
15715 * {@link io.reactivex.rxjava3.exceptions.OnErrorNotImplementedException OnErrorNotImplementedException}
15716 * and routed to the {@link RxJavaPlugins#onError(Throwable)} handler.
15717 * <dl>
15718 * <dt><b>Backpressure:</b></dt>
15719 * <dd>The operator consumes the current {@code Flowable} in an unbounded manner (i.e., no
15720 * backpressure is applied to it).</dd>
15721 * <dt><b>Scheduler:</b></dt>
15722 * <dd>{@code subscribe} does not operate by default on a particular {@link Scheduler}.</dd>
15723 * </dl>
15724 *
15725 * @param onNext
15726 * the {@code Consumer<T>} you have designed to accept emissions from the current {@code Flowable}
15727 * @return the new {@link Disposable} instance that allows cancelling the flow
15728 * @throws NullPointerException
15729 * if {@code onNext} is {@code null}
15730 * @see <a href="http://reactivex.io/documentation/operators/subscribe.html">ReactiveX operators documentation: Subscribe</a>
15731 * @see #subscribe(Consumer, Consumer, Action, DisposableContainer)
15732 */
15733 @CheckReturnValue
15734 @BackpressureSupport(BackpressureKind.UNBOUNDED_IN)
15735 @SchedulerSupport(SchedulerSupport.NONE)
15736 @NonNull
15737 public final Disposable subscribe(@NonNull Consumer<? super T> onNext) {
15738 return subscribe(onNext, Functions.ON_ERROR_MISSING, Functions.EMPTY_ACTION);
15739 }
15740
15741 /**
15742 * Subscribes to the current {@code Flowable} and provides callbacks to handle the items it emits and any error
15743 * notification it issues.
15744 * <dl>
15745 * <dt><b>Backpressure:</b></dt>
15746 * <dd>The operator consumes the current {@code Flowable} in an unbounded manner (i.e., no
15747 * backpressure is applied to it).</dd>
15748 * <dt><b>Scheduler:</b></dt>
15749 * <dd>{@code subscribe} does not operate by default on a particular {@link Scheduler}.</dd>
15750 * </dl>
15751 *
15752 * @param onNext
15753 * the {@code Consumer<T>} you have designed to accept emissions from the current {@code Flowable}
15754 * @param onError
15755 * the {@code Consumer<Throwable>} you have designed to accept any error notification from the
15756 * current {@code Flowable}
15757 * @return the new {@link Disposable} instance that allows cancelling the flow
15758 * @throws NullPointerException
15759 * if {@code onNext} or {@code onError} is {@code null}
15760 * @see <a href="http://reactivex.io/documentation/operators/subscribe.html">ReactiveX operators documentation: Subscribe</a>
15761 * @see #subscribe(Consumer, Consumer, Action, DisposableContainer)
15762 */
15763 @CheckReturnValue
15764 @BackpressureSupport(BackpressureKind.UNBOUNDED_IN)
15765 @SchedulerSupport(SchedulerSupport.NONE)
15766 @NonNull
15767 public final Disposable subscribe(@NonNull Consumer<? super T> onNext, @NonNull Consumer<? super Throwable> onError) {
15768 return subscribe(onNext, onError, Functions.EMPTY_ACTION);
15769 }
15770
15771 /**
15772 * Subscribes to the current {@code Flowable} and provides callbacks to handle the items it emits and any error or
15773 * completion notification it issues.
15774 * <dl>
15775 * <dt><b>Backpressure:</b></dt>
15776 * <dd>The operator consumes the current {@code Flowable} in an unbounded manner (i.e., no
15777 * backpressure is applied to it).</dd>
15778 * <dt><b>Scheduler:</b></dt>
15779 * <dd>{@code subscribe} does not operate by default on a particular {@link Scheduler}.</dd>
15780 * </dl>
15781 *
15782 * @param onNext
15783 * the {@code Consumer<T>} you have designed to accept emissions from the current {@code Flowable}
15784 * @param onError
15785 * the {@code Consumer<Throwable>} you have designed to accept any error notification from the
15786 * current {@code Flowable}
15787 * @param onComplete
15788 * the {@link Action} you have designed to accept a completion notification from the
15789 * the current {@code Flowable}
15790 * @return the new {@link Disposable} instance that allows cancelling the flow
15791 * @throws NullPointerException
15792 * if {@code onNext}, {@code onError} or {@code onComplete} is {@code null}
15793 * @see <a href="http://reactivex.io/documentation/operators/subscribe.html">ReactiveX operators documentation: Subscribe</a>
15794 * @see #subscribe(Consumer, Consumer, Action, DisposableContainer)
15795 */
15796 @CheckReturnValue
15797 @BackpressureSupport(BackpressureKind.UNBOUNDED_IN)
15798 @SchedulerSupport(SchedulerSupport.NONE)
15799 @NonNull
15800 public final Disposable subscribe(@NonNull Consumer<? super T> onNext, @NonNull Consumer<? super Throwable> onError,
15801 @NonNull Action onComplete) {
15802 Objects.requireNonNull(onNext, "onNext is null");
15803 Objects.requireNonNull(onError, "onError is null");
15804 Objects.requireNonNull(onComplete, "onComplete is null");
15805
15806 LambdaSubscriber<T> ls = new LambdaSubscriber<>(onNext, onError, onComplete, FlowableInternalHelper.RequestMax.INSTANCE);
15807
15808 subscribe(ls);
15809
15810 return ls;
15811 }
15812
15813 /**
15814 * Wraps the given onXXX callbacks into a {@link Disposable} {@link Subscriber},
15815 * adds it to the given {@link DisposableContainer} and ensures, that if the upstream
15816 * terminates or this particular {@code Disposable} is disposed, the {@code Subscriber} is removed
15817 * from the given container.
15818 * <p>
15819 * The {@coded Subscriber} will be removed after the callback for the terminal event has been invoked.
15820 * <dl>
15821 * <dt><b>Backpressure:</b></dt>
15822 * <dd>The operator consumes the current {@code Flowable} in an unbounded manner (i.e., no
15823 * backpressure is applied to it).</dd>
15824 * <dt><b>Scheduler:</b></dt>
15825 * <dd>{@code subscribe} does not operate by default on a particular {@link Scheduler}.</dd>
15826 * </dl>
15827 * @param onNext the callback for upstream items
15828 * @param onError the callback for an upstream error if any
15829 * @param onComplete the callback for the upstream completion if any
15830 * @param container the {@code DisposableContainer} (such as {@link CompositeDisposable}) to add and remove the
15831 * created {@code Disposable} {@code Subscriber}
15832 * @return the {@code Disposable} that allows disposing the particular subscription.
15833 * @throws NullPointerException
15834 * if {@code onNext}, {@code onError},
15835 * {@code onComplete} or {@code container} is {@code null}
15836 * @since 3.1.0
15837 */
15838 @BackpressureSupport(BackpressureKind.SPECIAL)
15839 @SchedulerSupport(SchedulerSupport.NONE)
15840 @NonNull
15841 public final Disposable subscribe(
15842 @NonNull Consumer<? super T> onNext,
15843 @NonNull Consumer<? super Throwable> onError,
15844 @NonNull Action onComplete,
15845 @NonNull DisposableContainer container) {
15846 Objects.requireNonNull(onNext, "onNext is null");
15847 Objects.requireNonNull(onError, "onError is null");
15848 Objects.requireNonNull(onComplete, "onComplete is null");
15849 Objects.requireNonNull(container, "container is null");
15850
15851 DisposableAutoReleaseSubscriber<T> subscriber = new DisposableAutoReleaseSubscriber<>(
15852 container, onNext, onError, onComplete);
15853 container.add(subscriber);
15854 subscribe(subscriber);
15855 return subscriber;
15856 }
15857
15858 @BackpressureSupport(BackpressureKind.SPECIAL)
15859 @SchedulerSupport(SchedulerSupport.NONE)
15860 @Override
15861 public final void subscribe(@NonNull Subscriber<? super T> subscriber) {
15862 if (subscriber instanceof FlowableSubscriber) {
15863 subscribe((FlowableSubscriber<? super T>)subscriber);
15864 } else {
15865 Objects.requireNonNull(subscriber, "subscriber is null");
15866 subscribe(new StrictSubscriber<>(subscriber));
15867 }
15868 }
15869
15870 /**
15871 * Establish a connection between this {@code Flowable} and the given {@link FlowableSubscriber} and
15872 * start streaming events based on the demand of the {@code FlowableSubscriber}.
15873 * <p>
15874 * This is a "factory method" and can be called multiple times, each time starting a new {@link Subscription}.
15875 * <p>
15876 * Each {@code Subscription} will work for only a single {@code FlowableSubscriber}.
15877 * <p>
15878 * If the same {@code FlowableSubscriber} instance is subscribed to multiple {@code Flowable}s and/or the
15879 * same {@code Flowable} multiple times, it must ensure the serialization over its {@code onXXX}
15880 * methods manually.
15881 * <p>
15882 * If the {@code Flowable} rejects the subscription attempt or otherwise fails it will signal
15883 * the error via {@link FlowableSubscriber#onError(Throwable)}.
15884 * <p>
15885 * This subscribe method relaxes the following <em>Reactive Streams</em> rules:
15886 * <ul>
15887 * <li>§1.3: {@code onNext} should not be called concurrently until {@code onSubscribe} returns.
15888 * <b>{@link FlowableSubscriber#onSubscribe(Subscription)} should make sure a sync or async call triggered by request() is safe.</b></li>
15889 * <li>§2.3: {@code onError} or {@code onComplete} must not call cancel.
15890 * <b>Calling request() or cancel() is NOP at this point.</b></li>
15891 * <li>§2.12: {@code onSubscribe} must be called at most once on the same instance.
15892 * <b>{@code FlowableSubscriber} reuse is not checked and if happens, it is the responsibility of
15893 * the {@code FlowableSubscriber} to ensure proper serialization of its onXXX methods.</b></li>
15894 * <li>§3.9: negative requests should emit an {@code onError(IllegalArgumentException)}.
15895 * <b>Non-positive requests signal via {@link RxJavaPlugins#onError(Throwable)} and the stream is not affected.</b></li>
15896 * </ul>
15897 * <dl>
15898 * <dt><b>Backpressure:</b></dt>
15899 * <dd>The backpressure behavior/expectation is determined by the supplied {@code FlowableSubscriber}.</dd>
15900 * <dt><b>Scheduler:</b></dt>
15901 * <dd>{@code subscribe} does not operate by default on a particular {@link Scheduler}.</dd>
15902 * </dl>
15903 * <p>History: 2.0.7 - experimental; 2.1 - beta
15904 * @param subscriber the {@code FlowableSubscriber} that will consume signals from this {@code Flowable}
15905 * @throws NullPointerException if {@code subscriber} is {@code null}
15906 * @since 2.2
15907 */
15908 @BackpressureSupport(BackpressureKind.SPECIAL)
15909 @SchedulerSupport(SchedulerSupport.NONE)
15910 public final void subscribe(@NonNull FlowableSubscriber<? super T> subscriber) {
15911 Objects.requireNonNull(subscriber, "subscriber is null");
15912 try {
15913 Subscriber<? super T> flowableSubscriber = RxJavaPlugins.onSubscribe(this, subscriber);
15914
15915 Objects.requireNonNull(flowableSubscriber, "The RxJavaPlugins.onSubscribe hook returned a null FlowableSubscriber. Please check the handler provided to RxJavaPlugins.setOnFlowableSubscribe for invalid null returns. Further reading: https://github.com/ReactiveX/RxJava/wiki/Plugins");
15916
15917 subscribeActual(flowableSubscriber);
15918 } catch (NullPointerException e) { // NOPMD
15919 throw e;
15920 } catch (Throwable e) {
15921 Exceptions.throwIfFatal(e);
15922 // can't call onError because no way to know if a Subscription has been set or not
15923 // can't call onSubscribe because the call might have set a Subscription already
15924 RxJavaPlugins.onError(e);
15925
15926 NullPointerException npe = new NullPointerException("Actually not, but can't throw other exceptions due to RS");
15927 npe.initCause(e);
15928 throw npe;
15929 }
15930 }
15931
15932 /**
15933 * Operator implementations (both source and intermediate) should implement this method that
15934 * performs the necessary business logic and handles the incoming {@link Subscriber}s.
15935 * <p>There is no need to call any of the plugin hooks on the current {@code Flowable} instance or
15936 * the {@code Subscriber}; all hooks and basic safeguards have been
15937 * applied by {@link #subscribe(Subscriber)} before this method gets called.
15938 * @param subscriber the incoming {@code Subscriber}, never {@code null}
15939 */
15940 protected abstract void subscribeActual(@NonNull Subscriber<? super T> subscriber);
15941
15942 /**
15943 * Subscribes a given {@link Subscriber} (subclass) to this {@code Flowable} and returns the given
15944 * {@code Subscriber} as is.
15945 * <p>Usage example:
15946 * <pre><code>
15947 * Flowable&lt;Integer&gt; source = Flowable.range(1, 10);
15948 * CompositeDisposable composite = new CompositeDisposable();
15949 *
15950 * ResourceSubscriber&lt;Integer&gt; rs = new ResourceSubscriber&lt;&gt;() {
15951 * // ...
15952 * };
15953 *
15954 * composite.add(source.subscribeWith(rs));
15955 * </code></pre>
15956 *
15957 * <dl>
15958 * <dt><b>Backpressure:</b></dt>
15959 * <dd>The backpressure behavior/expectation is determined by the supplied {@code Subscriber}.</dd>
15960 * <dt><b>Scheduler:</b></dt>
15961 * <dd>{@code subscribeWith} does not operate by default on a particular {@link Scheduler}.</dd>
15962 * </dl>
15963 * @param <E> the type of the {@code Subscriber} to use and return
15964 * @param subscriber the {@code Subscriber} (subclass) to use and return, not {@code null}
15965 * @return the input {@code subscriber}
15966 * @throws NullPointerException if {@code subscriber} is {@code null}
15967 * @since 2.0
15968 */
15969 @CheckReturnValue
15970 @BackpressureSupport(BackpressureKind.SPECIAL)
15971 @SchedulerSupport(SchedulerSupport.NONE)
15972 @NonNull
15973 public final <@NonNull E extends Subscriber<? super T>> E subscribeWith(E subscriber) {
15974 subscribe(subscriber);
15975 return subscriber;
15976 }
15977
15978 /**
15979 * Asynchronously subscribes {@link Subscriber}s to the current {@code Flowable} on the specified {@link Scheduler}.
15980 * <p>
15981 * If there is a {@link #create(FlowableOnSubscribe, BackpressureStrategy)} type source up in the
15982 * chain, it is recommended to use {@code subscribeOn(scheduler, false)} instead
15983 * to avoid same-pool deadlock because requests may pile up behind an eager/blocking emitter.
15984 * <p>
15985 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/subscribeOn.v3.png" alt="">
15986 * <dl>
15987 * <dt><b>Backpressure:</b></dt>
15988 * <dd>The operator doesn't interfere with backpressure which is determined by the current {@code Flowable}'s backpressure
15989 * behavior.</dd>
15990 * <dt><b>Scheduler:</b></dt>
15991 * <dd>You specify which {@code Scheduler} this operator will use.</dd>
15992 * </dl>
15993 *
15994 * @param scheduler
15995 * the {@code Scheduler} to perform subscription actions on
15996 * @return the new {@code Flowable} instance
15997 * @throws NullPointerException if {@code scheduler} is {@code null}
15998 * @see <a href="http://reactivex.io/documentation/operators/subscribeon.html">ReactiveX operators documentation: SubscribeOn</a>
15999 * @see <a href="http://www.grahamlea.com/2014/07/rxjava-threading-examples/">RxJava Threading Examples</a>
16000 * @see #observeOn
16001 * @see #subscribeOn(Scheduler, boolean)
16002 */
16003 @CheckReturnValue
16004 @NonNull
16005 @BackpressureSupport(BackpressureKind.PASS_THROUGH)
16006 @SchedulerSupport(SchedulerSupport.CUSTOM)
16007 public final Flowable<T> subscribeOn(@NonNull Scheduler scheduler) {
16008 Objects.requireNonNull(scheduler, "scheduler is null");
16009 return subscribeOn(scheduler, !(this instanceof FlowableCreate));
16010 }
16011
16012 /**
16013 * Asynchronously subscribes {@link Subscriber}s to the current {@code Flowable} on the specified {@link Scheduler}
16014 * optionally reroutes requests from other threads to the same {@code Scheduler} thread.
16015 * <p>
16016 * If there is a {@link #create(FlowableOnSubscribe, BackpressureStrategy)} type source up in the
16017 * chain, it is recommended to have {@code requestOn} {@code false} to avoid same-pool deadlock
16018 * because requests may pile up behind an eager/blocking emitter.
16019 * <p>
16020 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/subscribeOn.v3.png" alt="">
16021 * <dl>
16022 * <dt><b>Backpressure:</b></dt>
16023 * <dd>The operator doesn't interfere with backpressure which is determined by the current {@code Flowable}'s backpressure
16024 * behavior.</dd>
16025 * <dt><b>Scheduler:</b></dt>
16026 * <dd>You specify which {@code Scheduler} this operator will use.</dd>
16027 * </dl>
16028 * <p>History: 2.1.1 - experimental
16029 * @param scheduler
16030 * the {@code Scheduler} to perform subscription actions on
16031 * @param requestOn if {@code true}, requests are rerouted to the given {@code Scheduler} as well (strong pipelining)
16032 * if {@code false}, requests coming from any thread are simply forwarded to
16033 * the upstream on the same thread (weak pipelining)
16034 * @return the new {@code Flowable} instance
16035 * @throws NullPointerException if {@code scheduler} is {@code null}
16036 * @see <a href="http://reactivex.io/documentation/operators/subscribeon.html">ReactiveX operators documentation: SubscribeOn</a>
16037 * @see <a href="http://www.grahamlea.com/2014/07/rxjava-threading-examples/">RxJava Threading Examples</a>
16038 * @see #observeOn
16039 * @since 2.2
16040 */
16041 @CheckReturnValue
16042 @NonNull
16043 @BackpressureSupport(BackpressureKind.PASS_THROUGH)
16044 @SchedulerSupport(SchedulerSupport.CUSTOM)
16045 public final Flowable<T> subscribeOn(@NonNull Scheduler scheduler, boolean requestOn) {
16046 Objects.requireNonNull(scheduler, "scheduler is null");
16047 return RxJavaPlugins.onAssembly(new FlowableSubscribeOn<>(this, scheduler, requestOn));
16048 }
16049
16050 /**
16051 * Returns a {@code Flowable} that emits the items emitted by the current {@code Flowable} or the items of an alternate
16052 * {@link Publisher} if the current {@code Flowable} is empty.
16053 * <p>
16054 * <img width="640" height="256" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/switchifempty.png" alt="">
16055 * <dl>
16056 * <dt><b>Backpressure:</b></dt>
16057 * <dd>If the current {@code Flowable} is empty, the alternate {@code Publisher} is expected to honor backpressure.
16058 * If the current {@code Flowable} is non-empty, it is expected to honor backpressure as instead.
16059 * In either case, if violated, a {@link MissingBackpressureException} <em>may</em> get
16060 * signaled somewhere downstream.
16061 * </dd>
16062 * <dt><b>Scheduler:</b></dt>
16063 * <dd>{@code switchIfEmpty} does not operate by default on a particular {@link Scheduler}.</dd>
16064 * </dl>
16065 *
16066 * @param other
16067 * the alternate {@code Publisher} to subscribe to if the source does not emit any items
16068 * @return the new {@code Flowable} instance
16069 * @throws NullPointerException if {@code other} is {@code null}
16070 * @since 1.1.0
16071 */
16072 @CheckReturnValue
16073 @NonNull
16074 @BackpressureSupport(BackpressureKind.FULL)
16075 @SchedulerSupport(SchedulerSupport.NONE)
16076 public final Flowable<T> switchIfEmpty(@NonNull Publisher<? extends T> other) {
16077 Objects.requireNonNull(other, "other is null");
16078 return RxJavaPlugins.onAssembly(new FlowableSwitchIfEmpty<>(this, other));
16079 }
16080
16081 /**
16082 * Returns a new {@code Flowable} by applying a function that you supply to each item emitted by the current
16083 * {@code Flowable} that returns a {@link Publisher}, and then emitting the items emitted by the most recently emitted
16084 * of these {@code Publisher}s.
16085 * <p>
16086 * The resulting {@code Flowable} completes if both the current {@code Flowable} and the last inner {@code Publisher}, if any, complete.
16087 * If the current {@code Flowable} signals an {@code onError}, the inner {@code Publisher} is canceled and the error delivered in-sequence.
16088 * <p>
16089 * <img width="640" height="350" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/switchMap.v3.png" alt="">
16090 * <dl>
16091 * <dt><b>Backpressure:</b></dt>
16092 * <dd>The operator honors backpressure from downstream. The outer {@code Publisher} is consumed in an
16093 * unbounded manner (i.e., without backpressure) and the inner {@code Publisher}s are expected to honor
16094 * backpressure but it is not enforced; the operator won't signal a {@link MissingBackpressureException}
16095 * but the violation <em>may</em> lead to {@link OutOfMemoryError} due to internal buffer bloat.</dd>
16096 * <dt><b>Scheduler:</b></dt>
16097 * <dd>{@code switchMap} does not operate by default on a particular {@link Scheduler}.</dd>
16098 * </dl>
16099 *
16100 * @param <R> the element type of the inner {@code Publisher}s and the output
16101 * @param mapper
16102 * a function that, when applied to an item emitted by the current {@code Flowable}, returns a
16103 * {@code Publisher}
16104 * @return the new {@code Flowable} instance
16105 * @throws NullPointerException if {@code mapper} is {@code null}
16106 * @see <a href="http://reactivex.io/documentation/operators/flatmap.html">ReactiveX operators documentation: FlatMap</a>
16107 * @see #switchMapDelayError(Function)
16108 */
16109 @CheckReturnValue
16110 @BackpressureSupport(BackpressureKind.FULL)
16111 @SchedulerSupport(SchedulerSupport.NONE)
16112 @NonNull
16113 public final <@NonNull R> Flowable<R> switchMap(@NonNull Function<? super T, @NonNull ? extends Publisher<? extends R>> mapper) {
16114 return switchMap(mapper, bufferSize());
16115 }
16116
16117 /**
16118 * Returns a new {@code Flowable} by applying a function that you supply to each item emitted by the current
16119 * {@code Flowable} that returns a {@link Publisher}, and then emitting the items emitted by the most recently emitted
16120 * of these {@code Publisher}s.
16121 * <p>
16122 * The resulting {@code Flowable} completes if both the current {@code Flowable} and the last inner {@code Publisher}, if any, complete.
16123 * If the current {@code Flowable} signals an {@code onError}, the inner {@code Publisher} is canceled and the error delivered in-sequence.
16124 * <p>
16125 * <img width="640" height="350" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/switchMap.v3.png" alt="">
16126 * <dl>
16127 * <dt><b>Backpressure:</b></dt>
16128 * <dd>The operator honors backpressure from downstream. The outer {@code Publisher} is consumed in an
16129 * unbounded manner (i.e., without backpressure) and the inner {@code Publisher}s are expected to honor
16130 * backpressure but it is not enforced; the operator won't signal a {@link MissingBackpressureException}
16131 * but the violation <em>may</em> lead to {@link OutOfMemoryError} due to internal buffer bloat.</dd>
16132 * <dt><b>Scheduler:</b></dt>
16133 * <dd>{@code switchMap} does not operate by default on a particular {@link Scheduler}.</dd>
16134 * </dl>
16135 *
16136 * @param <R> the element type of the inner {@code Publisher}s and the output
16137 * @param mapper
16138 * a function that, when applied to an item emitted by the current {@code Flowable}, returns a
16139 * {@code Publisher}
16140 * @param bufferSize
16141 * the number of elements to prefetch from the current active inner {@code Publisher}
16142 * @return the new {@code Flowable} instance
16143 * @throws NullPointerException if {@code mapper} is {@code null}
16144 * @throws IllegalArgumentException if {@code bufferSize} is non-positive
16145 * @see <a href="http://reactivex.io/documentation/operators/flatmap.html">ReactiveX operators documentation: FlatMap</a>
16146 * @see #switchMapDelayError(Function, int)
16147 */
16148 @CheckReturnValue
16149 @BackpressureSupport(BackpressureKind.FULL)
16150 @SchedulerSupport(SchedulerSupport.NONE)
16151 @NonNull
16152 public final <@NonNull R> Flowable<R> switchMap(@NonNull Function<? super T, @NonNull ? extends Publisher<? extends R>> mapper, int bufferSize) {
16153 return switchMap0(mapper, bufferSize, false);
16154 }
16155
16156 /**
16157 * Maps the upstream values into {@link CompletableSource}s, subscribes to the newer one while
16158 * disposing the subscription to the previous {@code CompletableSource}, thus keeping at most one
16159 * active {@code CompletableSource} running.
16160 * <p>
16161 * <img width="640" height="522" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/switchMapCompletable.f.png" alt="">
16162 * <p>
16163 * Since a {@code CompletableSource} doesn't produce any items, the resulting reactive type of
16164 * this operator is a {@link Completable} that can only indicate successful completion or
16165 * a failure in any of the inner {@code CompletableSource}s or the failure of the current
16166 * {@code Flowable}.
16167 * <dl>
16168 * <dt><b>Backpressure:</b></dt>
16169 * <dd>The operator consumes the current {@code Flowable} in an unbounded manner and otherwise
16170 * does not have backpressure in its return type because no items are ever produced.</dd>
16171 * <dt><b>Scheduler:</b></dt>
16172 * <dd>{@code switchMapCompletable} does not operate by default on a particular {@link Scheduler}.</dd>
16173 * <dt><b>Error handling:</b></dt>
16174 * <dd>If either this {@code Flowable} or the active {@code CompletableSource} signals an {@code onError},
16175 * the resulting {@code Completable} is terminated immediately with that {@link Throwable}.
16176 * Use the {@link #switchMapCompletableDelayError(Function)} to delay such inner failures until
16177 * every inner {@code CompletableSource}s and the main {@code Flowable} terminates in some fashion.
16178 * If they fail concurrently, the operator may combine the {@code Throwable}s into a
16179 * {@link io.reactivex.rxjava3.exceptions.CompositeException CompositeException}
16180 * and signal it to the downstream instead. If any inactivated (switched out) {@code CompletableSource}
16181 * signals an {@code onError} late, the {@code Throwable}s will be signaled to the global error handler via
16182 * {@link RxJavaPlugins#onError(Throwable)} method as {@link UndeliverableException} errors.
16183 * </dd>
16184 * </dl>
16185 * <p>History: 2.1.11 - experimental
16186 * @param mapper the function called with each upstream item and should return a
16187 * {@code CompletableSource} to be subscribed to and awaited for
16188 * (non blockingly) for its terminal event
16189 * @return the new {@code Completable} instance
16190 * @throws NullPointerException if {@code mapper} is {@code null}
16191 * @see #switchMapCompletableDelayError(Function)
16192 * @since 2.2
16193 */
16194 @CheckReturnValue
16195 @NonNull
16196 @BackpressureSupport(BackpressureKind.UNBOUNDED_IN)
16197 @SchedulerSupport(SchedulerSupport.NONE)
16198 public final Completable switchMapCompletable(@NonNull Function<? super T, ? extends CompletableSource> mapper) {
16199 Objects.requireNonNull(mapper, "mapper is null");
16200 return RxJavaPlugins.onAssembly(new FlowableSwitchMapCompletable<>(this, mapper, false));
16201 }
16202
16203 /**
16204 * Maps the upstream values into {@link CompletableSource}s, subscribes to the newer one while
16205 * disposing the subscription to the previous {@code CompletableSource}, thus keeping at most one
16206 * active {@code CompletableSource} running and delaying any main or inner errors until all
16207 * of them terminate.
16208 * <p>
16209 * <img width="640" height="453" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/switchMapCompletableDelayError.f.png" alt="">
16210 * <p>
16211 * Since a {@code CompletableSource} doesn't produce any items, the resulting reactive type of
16212 * this operator is a {@link Completable} that can only indicate successful completion or
16213 * a failure in any of the inner {@code CompletableSource}s or the failure of the current
16214 * {@code Flowable}.
16215 * <dl>
16216 * <dt><b>Backpressure:</b></dt>
16217 * <dd>The operator consumes the current {@code Flowable} in an unbounded manner and otherwise
16218 * does not have backpressure in its return type because no items are ever produced.</dd>
16219 * <dt><b>Scheduler:</b></dt>
16220 * <dd>{@code switchMapCompletableDelayError} does not operate by default on a particular {@link Scheduler}.</dd>
16221 * <dt><b>Error handling:</b></dt>
16222 * <dd>The errors of this {@code Flowable} and all the {@code CompletableSource}s, who had the chance
16223 * to run to their completion, are delayed until
16224 * all of them terminate in some fashion. At this point, if there was only one failure, the respective
16225 * {@link Throwable} is emitted to the downstream. If there was more than one failure, the
16226 * operator combines all {@code Throwable}s into a {@link io.reactivex.rxjava3.exceptions.CompositeException CompositeException}
16227 * and signals that to the downstream.
16228 * If any inactivated (switched out) {@code CompletableSource}
16229 * signals an {@code onError} late, the {@code Throwable}s will be signaled to the global error handler via
16230 * {@link RxJavaPlugins#onError(Throwable)} method as {@link UndeliverableException} errors.
16231 * </dd>
16232 * </dl>
16233 * <p>History: 2.1.11 - experimental
16234 * @param mapper the function called with each upstream item and should return a
16235 * {@code CompletableSource} to be subscribed to and awaited for
16236 * (non blockingly) for its terminal event
16237 * @return the new {@code Completable} instance
16238 * @throws NullPointerException if {@code mapper} is {@code null}
16239 * @see #switchMapCompletable(Function)
16240 * @since 2.2
16241 */
16242 @CheckReturnValue
16243 @NonNull
16244 @BackpressureSupport(BackpressureKind.UNBOUNDED_IN)
16245 @SchedulerSupport(SchedulerSupport.NONE)
16246 public final Completable switchMapCompletableDelayError(@NonNull Function<? super T, ? extends CompletableSource> mapper) {
16247 Objects.requireNonNull(mapper, "mapper is null");
16248 return RxJavaPlugins.onAssembly(new FlowableSwitchMapCompletable<>(this, mapper, true));
16249 }
16250
16251 /**
16252 * Returns a new {@code Flowable} by applying a function that you supply to each item emitted by the current
16253 * {@code Flowable} that returns a {@link Publisher}, and then emitting the items emitted by the most recently emitted
16254 * of these {@code Publisher}s and delays any error until all {@code Publisher}s terminate.
16255 * <p>
16256 * The resulting {@code Flowable} completes if both the current {@code Flowable} and the last inner {@code Publisher}, if any, complete.
16257 * If the current {@code Flowable} signals an {@code onError}, the termination of the last inner {@code Publisher} will emit that error as is
16258 * or wrapped into a {@link CompositeException} along with the other possible errors the former inner {@code Publisher}s signaled.
16259 * <p>
16260 * <img width="640" height="350" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/switchMap.v3.png" alt="">
16261 * <dl>
16262 * <dt><b>Backpressure:</b></dt>
16263 * <dd>The operator honors backpressure from downstream. The outer {@code Publisher} is consumed in an
16264 * unbounded manner (i.e., without backpressure) and the inner {@code Publisher}s are expected to honor
16265 * backpressure but it is not enforced; the operator won't signal a {@link MissingBackpressureException}
16266 * but the violation <em>may</em> lead to {@link OutOfMemoryError} due to internal buffer bloat.</dd>
16267 * <dt><b>Scheduler:</b></dt>
16268 * <dd>{@code switchMapDelayError} does not operate by default on a particular {@link Scheduler}.</dd>
16269 * </dl>
16270 *
16271 * @param <R> the element type of the inner {@code Publisher}s and the output
16272 * @param mapper
16273 * a function that, when applied to an item emitted by the current {@code Flowable}, returns a
16274 * {@code Publisher}
16275 * @return the new {@code Flowable} instance
16276 * @throws NullPointerException if {@code mapper} is {@code null}
16277 * @see <a href="http://reactivex.io/documentation/operators/flatmap.html">ReactiveX operators documentation: FlatMap</a>
16278 * @see #switchMap(Function)
16279 * @since 2.0
16280 */
16281 @CheckReturnValue
16282 @BackpressureSupport(BackpressureKind.SPECIAL)
16283 @SchedulerSupport(SchedulerSupport.NONE)
16284 @NonNull
16285 public final <@NonNull R> Flowable<R> switchMapDelayError(@NonNull Function<? super T, @NonNull ? extends Publisher<? extends R>> mapper) {
16286 return switchMapDelayError(mapper, bufferSize());
16287 }
16288
16289 /**
16290 * Returns a new {@code Flowable} by applying a function that you supply to each item emitted by the current
16291 * {@code Flowable} that returns a {@link Publisher}, and then emitting the items emitted by the most recently emitted
16292 * of these {@code Publisher}s and delays any error until all {@code Publisher}s terminate.
16293 * <p>
16294 * The resulting {@code Flowable} completes if both the current {@code Flowable} and the last inner {@code Publisher}, if any, complete.
16295 * If the current {@code Flowable} signals an {@code onError}, the termination of the last inner {@code Publisher} will emit that error as is
16296 * or wrapped into a {@link CompositeException} along with the other possible errors the former inner {@code Publisher}s signaled.
16297 * <p>
16298 * <img width="640" height="350" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/switchMap.v3.png" alt="">
16299 * <dl>
16300 * <dt><b>Backpressure:</b></dt>
16301 * <dd>The operator honors backpressure from downstream. The outer {@code Publisher} is consumed in an
16302 * unbounded manner (i.e., without backpressure) and the inner {@code Publisher}s are expected to honor
16303 * backpressure but it is not enforced; the operator won't signal a {@link MissingBackpressureException}
16304 * but the violation <em>may</em> lead to {@link OutOfMemoryError} due to internal buffer bloat.</dd>
16305 * <dt><b>Scheduler:</b></dt>
16306 * <dd>{@code switchMapDelayError} does not operate by default on a particular {@link Scheduler}.</dd>
16307 * </dl>
16308 *
16309 * @param <R> the element type of the inner {@code Publisher}s and the output
16310 * @param mapper
16311 * a function that, when applied to an item emitted by the current {@code Flowable}, returns a
16312 * {@code Publisher}
16313 * @param bufferSize
16314 * the number of elements to prefetch from the current active inner {@code Publisher}
16315 * @return the new {@code Flowable} instance
16316 * @throws NullPointerException if {@code mapper} is {@code null}
16317 * @throws IllegalArgumentException if {@code bufferSize} is non-positive
16318 * @see <a href="http://reactivex.io/documentation/operators/flatmap.html">ReactiveX operators documentation: FlatMap</a>
16319 * @see #switchMap(Function, int)
16320 * @since 2.0
16321 */
16322 @CheckReturnValue
16323 @BackpressureSupport(BackpressureKind.SPECIAL)
16324 @SchedulerSupport(SchedulerSupport.NONE)
16325 @NonNull
16326 public final <@NonNull R> Flowable<R> switchMapDelayError(@NonNull Function<? super T, @NonNull ? extends Publisher<? extends R>> mapper, int bufferSize) {
16327 return switchMap0(mapper, bufferSize, true);
16328 }
16329
16330 <R> Flowable<R> switchMap0(Function<? super T, @NonNull ? extends Publisher<? extends R>> mapper, int bufferSize, boolean delayError) {
16331 Objects.requireNonNull(mapper, "mapper is null");
16332 ObjectHelper.verifyPositive(bufferSize, "bufferSize");
16333 if (this instanceof ScalarSupplier) {
16334 @SuppressWarnings("unchecked")
16335 T v = ((ScalarSupplier<T>)this).get();
16336 if (v == null) {
16337 return empty();
16338 }
16339 return FlowableScalarXMap.scalarXMap(v, mapper);
16340 }
16341 return RxJavaPlugins.onAssembly(new FlowableSwitchMap<>(this, mapper, bufferSize, delayError));
16342 }
16343
16344 /**
16345 * Maps the upstream items into {@link MaybeSource}s and switches (subscribes) to the newer ones
16346 * while disposing the older ones (and ignoring their signals) and emits the latest success value of the current one if
16347 * available while failing immediately if this {@code Flowable} or any of the
16348 * active inner {@code MaybeSource}s fail.
16349 * <p>
16350 * <img width="640" height="350" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/switchMap.v3.png" alt="">
16351 * <dl>
16352 * <dt><b>Backpressure:</b></dt>
16353 * <dd>The operator honors backpressure from downstream. The main {@code Flowable} is consumed in an
16354 * unbounded manner (i.e., without backpressure).</dd>
16355 * <dt><b>Scheduler:</b></dt>
16356 * <dd>{@code switchMapMaybe} does not operate by default on a particular {@link Scheduler}.</dd>
16357 * <dt><b>Error handling:</b></dt>
16358 * <dd>This operator terminates with an {@code onError} if this {@code Flowable} or any of
16359 * the inner {@code MaybeSource}s fail while they are active. When this happens concurrently, their
16360 * individual {@link Throwable} errors may get combined and emitted as a single
16361 * {@link CompositeException}. Otherwise, a late
16362 * (i.e., inactive or switched out) {@code onError} from this {@code Flowable} or from any of
16363 * the inner {@code MaybeSource}s will be forwarded to the global error handler via
16364 * {@link io.reactivex.rxjava3.plugins.RxJavaPlugins#onError(Throwable)} as
16365 * {@link io.reactivex.rxjava3.exceptions.UndeliverableException UndeliverableException}</dd>
16366 * </dl>
16367 * <p>History: 2.1.11 - experimental
16368 * @param <R> the output value type
16369 * @param mapper the function called with the current upstream event and should
16370 * return a {@code MaybeSource} to replace the current active inner source
16371 * and get subscribed to.
16372 * @return the new {@code Flowable} instance
16373 * @throws NullPointerException if {@code mapper} is {@code null}
16374 * @see #switchMapMaybeDelayError(Function)
16375 * @since 2.2
16376 */
16377 @CheckReturnValue
16378 @NonNull
16379 @BackpressureSupport(BackpressureKind.UNBOUNDED_IN)
16380 @SchedulerSupport(SchedulerSupport.NONE)
16381 public final <@NonNull R> Flowable<R> switchMapMaybe(@NonNull Function<? super T, ? extends MaybeSource<? extends R>> mapper) {
16382 Objects.requireNonNull(mapper, "mapper is null");
16383 return RxJavaPlugins.onAssembly(new FlowableSwitchMapMaybe<>(this, mapper, false));
16384 }
16385
16386 /**
16387 * Maps the upstream items into {@link MaybeSource}s and switches (subscribes) to the newer ones
16388 * while disposing the older ones (and ignoring their signals) and emits the latest success value of the current one if
16389 * available, delaying errors from this {@code Flowable} or the inner {@code MaybeSource}s until all terminate.
16390 * <p>
16391 * <img width="640" height="350" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/switchMap.v3.png" alt="">
16392 * <dl>
16393 * <dt><b>Backpressure:</b></dt>
16394 * <dd>The operator honors backpressure from downstream. The main {@code Flowable} is consumed in an
16395 * unbounded manner (i.e., without backpressure).</dd>
16396 * <dt><b>Scheduler:</b></dt>
16397 * <dd>{@code switchMapMaybeDelayError} does not operate by default on a particular {@link Scheduler}.</dd>
16398 * </dl>
16399 * <p>History: 2.1.11 - experimental
16400 * @param <R> the output value type
16401 * @param mapper the function called with the current upstream event and should
16402 * return a {@code MaybeSource} to replace the current active inner source
16403 * and get subscribed to.
16404 * @return the new {@code Flowable} instance
16405 * @throws NullPointerException if {@code mapper} is {@code null}
16406 * @see #switchMapMaybe(Function)
16407 * @since 2.2
16408 */
16409 @CheckReturnValue
16410 @NonNull
16411 @BackpressureSupport(BackpressureKind.UNBOUNDED_IN)
16412 @SchedulerSupport(SchedulerSupport.NONE)
16413 public final <@NonNull R> Flowable<R> switchMapMaybeDelayError(@NonNull Function<? super T, ? extends MaybeSource<? extends R>> mapper) {
16414 Objects.requireNonNull(mapper, "mapper is null");
16415 return RxJavaPlugins.onAssembly(new FlowableSwitchMapMaybe<>(this, mapper, true));
16416 }
16417
16418 /**
16419 * Maps the upstream items into {@link SingleSource}s and switches (subscribes) to the newer ones
16420 * while disposing the older ones (and ignoring their signals) and emits the latest success value of the current one
16421 * while failing immediately if this {@code Flowable} or any of the
16422 * active inner {@code SingleSource}s fail.
16423 * <p>
16424 * <img width="640" height="350" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/switchMap.v3.png" alt="">
16425 * <dl>
16426 * <dt><b>Backpressure:</b></dt>
16427 * <dd>The operator honors backpressure from downstream. The main {@code Flowable} is consumed in an
16428 * unbounded manner (i.e., without backpressure).</dd>
16429 * <dt><b>Scheduler:</b></dt>
16430 * <dd>{@code switchMapSingle} does not operate by default on a particular {@link Scheduler}.</dd>
16431 * <dt><b>Error handling:</b></dt>
16432 * <dd>This operator terminates with an {@code onError} if this {@code Flowable} or any of
16433 * the inner {@code SingleSource}s fail while they are active. When this happens concurrently, their
16434 * individual {@link Throwable} errors may get combined and emitted as a single
16435 * {@link CompositeException}. Otherwise, a late
16436 * (i.e., inactive or switched out) {@code onError} from this {@code Flowable} or from any of
16437 * the inner {@code SingleSource}s will be forwarded to the global error handler via
16438 * {@link io.reactivex.rxjava3.plugins.RxJavaPlugins#onError(Throwable)} as
16439 * {@link io.reactivex.rxjava3.exceptions.UndeliverableException UndeliverableException}</dd>
16440 * </dl>
16441 * <p>History: 2.1.11 - experimental
16442 * @param <R> the output value type
16443 * @param mapper the function called with the current upstream event and should
16444 * return a {@code SingleSource} to replace the current active inner source
16445 * and get subscribed to.
16446 * @return the new {@code Flowable} instance
16447 * @throws NullPointerException if {@code mapper} is {@code null}
16448 * @see #switchMapSingleDelayError(Function)
16449 * @since 2.2
16450 */
16451 @CheckReturnValue
16452 @NonNull
16453 @BackpressureSupport(BackpressureKind.UNBOUNDED_IN)
16454 @SchedulerSupport(SchedulerSupport.NONE)
16455 public final <@NonNull R> Flowable<R> switchMapSingle(@NonNull Function<? super T, ? extends SingleSource<? extends R>> mapper) {
16456 Objects.requireNonNull(mapper, "mapper is null");
16457 return RxJavaPlugins.onAssembly(new FlowableSwitchMapSingle<>(this, mapper, false));
16458 }
16459
16460 /**
16461 * Maps the upstream items into {@link SingleSource}s and switches (subscribes) to the newer ones
16462 * while disposing the older ones (and ignoring their signals) and emits the latest success value of the current one,
16463 * delaying errors from this {@code Flowable} or the inner {@code SingleSource}s until all terminate.
16464 * <p>
16465 * <img width="640" height="350" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/switchMap.v3.png" alt="">
16466 * <dl>
16467 * <dt><b>Backpressure:</b></dt>
16468 * <dd>The operator honors backpressure from downstream. The main {@code Flowable} is consumed in an
16469 * unbounded manner (i.e., without backpressure).</dd>
16470 * <dt><b>Scheduler:</b></dt>
16471 * <dd>{@code switchMapSingleDelayError} does not operate by default on a particular {@link Scheduler}.</dd>
16472 * </dl>
16473 * <p>History: 2.1.11 - experimental
16474 * @param <R> the output value type
16475 * @param mapper the function called with the current upstream event and should
16476 * return a {@code SingleSource} to replace the current active inner source
16477 * and get subscribed to.
16478 * @return the new {@code Flowable} instance
16479 * @throws NullPointerException if {@code mapper} is {@code null}
16480 * @see #switchMapSingle(Function)
16481 * @since 2.2
16482 */
16483 @CheckReturnValue
16484 @NonNull
16485 @BackpressureSupport(BackpressureKind.UNBOUNDED_IN)
16486 @SchedulerSupport(SchedulerSupport.NONE)
16487 public final <@NonNull R> Flowable<R> switchMapSingleDelayError(@NonNull Function<? super T, ? extends SingleSource<? extends R>> mapper) {
16488 Objects.requireNonNull(mapper, "mapper is null");
16489 return RxJavaPlugins.onAssembly(new FlowableSwitchMapSingle<>(this, mapper, true));
16490 }
16491
16492 /**
16493 * Returns a {@code Flowable} that emits only the first {@code count} items emitted by the current {@code Flowable}.
16494 * If the source emits fewer than {@code count} items then all of its items are emitted.
16495 * <p>
16496 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/take.v3.png" alt="">
16497 * <p>
16498 * This method returns a {@code Flowable} that will invoke a subscribing {@link Subscriber}'s
16499 * {@link Subscriber#onNext onNext} function a maximum of {@code count} times before invoking
16500 * {@link Subscriber#onComplete onComplete}.
16501 * <p>
16502 * Limits both the number of upstream items (after which the sequence completes)
16503 * and the total downstream request amount requested from the upstream to
16504 * possibly prevent the creation of excess items by the upstream.
16505 * <p>
16506 * The operator requests at most the given {@code count} of items from upstream even
16507 * if the downstream requests more than that. For example, given a {@code take(5)},
16508 * if the downstream requests 1, a request of 1 is submitted to the upstream
16509 * and the operator remembers that only 4 items can be requested now on. A request
16510 * of 5 at this point will request 4 from the upstream and any subsequent requests will
16511 * be ignored.
16512 * <p>
16513 * Note that requests are negotiated on an operator boundary and {@code take}'s amount
16514 * may not be preserved further upstream. For example,
16515 * {@code source.observeOn(Schedulers.computation()).take(5)} will still request the
16516 * default (128) elements from the given {@code source}.
16517 * <dl>
16518 * <dt><b>Backpressure:</b></dt>
16519 * <dd>The current {@code Flowable} is consumed in a bounded manner.</dd>
16520 * <dt><b>Scheduler:</b></dt>
16521 * <dd>This version of {@code take} does not operate by default on a particular {@link Scheduler}.</dd>
16522 * </dl>
16523 *
16524 * @param count
16525 * the maximum number of items and the total request amount, non-negative.
16526 * Zero will immediately cancel the upstream on subscription and complete
16527 * the downstream.
16528 * @return the new {@code Flowable} instance
16529 * @throws IllegalArgumentException if {@code count} is negative
16530 * @see <a href="http://reactivex.io/documentation/operators/take.html">ReactiveX operators documentation: Take</a>
16531 */
16532 @CheckReturnValue
16533 @BackpressureSupport(BackpressureKind.FULL)
16534 @SchedulerSupport(SchedulerSupport.NONE)
16535 @NonNull
16536 public final Flowable<T> take(long count) {
16537 if (count < 0) {
16538 throw new IllegalArgumentException("count >= 0 required but it was " + count);
16539 }
16540 return RxJavaPlugins.onAssembly(new FlowableTake<>(this, count));
16541 }
16542
16543 /**
16544 * Returns a {@code Flowable} that emits those items emitted by source {@link Publisher} before a specified time runs
16545 * out.
16546 * <p>
16547 * If time runs out before the {@code Flowable} completes normally, the {@code onComplete} event will be
16548 * signaled on the default {@code computation} {@link Scheduler}.
16549 * <p>
16550 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/take.t.v3.png" alt="">
16551 * <dl>
16552 * <dt><b>Backpressure:</b></dt>
16553 * <dd>The operator doesn't interfere with backpressure which is determined by the current {@code Flowable}'s backpressure
16554 * behavior.</dd>
16555 * <dt><b>Scheduler:</b></dt>
16556 * <dd>This version of {@code take} operates by default on the {@code computation} {@code Scheduler}.</dd>
16557 * </dl>
16558 *
16559 * @param time
16560 * the length of the time window
16561 * @param unit
16562 * the time unit of {@code time}
16563 * @return the new {@code Flowable} instance
16564 * @throws NullPointerException if {@code unit} is {@code null}
16565 * @see <a href="http://reactivex.io/documentation/operators/take.html">ReactiveX operators documentation: Take</a>
16566 */
16567 @CheckReturnValue
16568 @BackpressureSupport(BackpressureKind.PASS_THROUGH)
16569 @SchedulerSupport(SchedulerSupport.COMPUTATION)
16570 @NonNull
16571 public final Flowable<T> take(long time, @NonNull TimeUnit unit) {
16572 return takeUntil(timer(time, unit));
16573 }
16574
16575 /**
16576 * Returns a {@code Flowable} that emits those items emitted by source {@link Publisher} before a specified time (on a
16577 * specified {@link Scheduler}) runs out.
16578 * <p>
16579 * If time runs out before the {@code Flowable} completes normally, the {@code onComplete} event will be
16580 * signaled on the provided {@code Scheduler}.
16581 * <p>
16582 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/take.ts.v3.png" alt="">
16583 * <dl>
16584 * <dt><b>Backpressure:</b></dt>
16585 * <dd>The operator doesn't interfere with backpressure which is determined by the current {@code Flowable}'s backpressure
16586 * behavior.</dd>
16587 * <dt><b>Scheduler:</b></dt>
16588 * <dd>You specify which {@code Scheduler} this operator will use.</dd>
16589 * </dl>
16590 *
16591 * @param time
16592 * the length of the time window
16593 * @param unit
16594 * the time unit of {@code time}
16595 * @param scheduler
16596 * the {@code Scheduler} used for time source
16597 * @return the new {@code Flowable} instance
16598 * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null}
16599 * @see <a href="http://reactivex.io/documentation/operators/take.html">ReactiveX operators documentation: Take</a>
16600 */
16601 @CheckReturnValue
16602 @BackpressureSupport(BackpressureKind.PASS_THROUGH)
16603 @SchedulerSupport(SchedulerSupport.CUSTOM)
16604 @NonNull
16605 public final Flowable<T> take(long time, @NonNull TimeUnit unit, @NonNull Scheduler scheduler) {
16606 return takeUntil(timer(time, unit, scheduler));
16607 }
16608
16609 /**
16610 * Returns a {@code Flowable} that emits at most the last {@code count} items emitted by the current {@code Flowable}. If the source emits fewer than
16611 * {@code count} items then all of its items are emitted.
16612 * <p>
16613 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/takeLast.n.v3.png" alt="">
16614 * <dl>
16615 * <dt><b>Backpressure:</b></dt>
16616 * <dd>The operator honors backpressure from downstream if the {@code count} is non-zero; ignores
16617 * backpressure if the {@code count} is zero as it doesn't signal any values.</dd>
16618 * <dt><b>Scheduler:</b></dt>
16619 * <dd>This version of {@code takeLast} does not operate by default on a particular {@link Scheduler}.</dd>
16620 * </dl>
16621 *
16622 * @param count
16623 * the maximum number of items to emit from the end of the sequence of items emitted by the current
16624 * {@code Flowable}
16625 * @return the new {@code Flowable} instance
16626 * @throws IllegalArgumentException
16627 * if {@code count} is negative
16628 * @see <a href="http://reactivex.io/documentation/operators/takelast.html">ReactiveX operators documentation: TakeLast</a>
16629 */
16630 @CheckReturnValue
16631 @BackpressureSupport(BackpressureKind.FULL)
16632 @SchedulerSupport(SchedulerSupport.NONE)
16633 @NonNull
16634 public final Flowable<T> takeLast(int count) {
16635 if (count < 0) {
16636 throw new IllegalArgumentException("count >= 0 required but it was " + count);
16637 } else
16638 if (count == 0) {
16639 return RxJavaPlugins.onAssembly(new FlowableIgnoreElements<>(this));
16640 } else
16641 if (count == 1) {
16642 return RxJavaPlugins.onAssembly(new FlowableTakeLastOne<>(this));
16643 }
16644 return RxJavaPlugins.onAssembly(new FlowableTakeLast<>(this, count));
16645 }
16646
16647 /**
16648 * Returns a {@code Flowable} that emits at most a specified number of items from the current {@code Flowable} that were
16649 * emitted in a specified window of time before the current {@code Flowable} completed.
16650 * <p>
16651 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/takeLast.tn.v3.png" alt="">
16652 * <dl>
16653 * <dt><b>Backpressure:</b></dt>
16654 * <dd>The operator honors backpressure from downstream and consumes the current {@code Flowable} in an
16655 * unbounded manner (i.e., no backpressure is applied to it).</dd>
16656 * <dt><b>Scheduler:</b></dt>
16657 * <dd>{@code takeLast} does not operate on any particular scheduler but uses the current time
16658 * from the {@code computation} {@link Scheduler}.</dd>
16659 * </dl>
16660 *
16661 * @param count
16662 * the maximum number of items to emit
16663 * @param time
16664 * the length of the time window
16665 * @param unit
16666 * the time unit of {@code time}
16667 * @return the new {@code Flowable} instance
16668 * @throws NullPointerException if {@code unit} is {@code null}
16669 * @throws IllegalArgumentException if {@code count} is negative
16670 * @see <a href="http://reactivex.io/documentation/operators/takelast.html">ReactiveX operators documentation: TakeLast</a>
16671 */
16672 @CheckReturnValue
16673 @BackpressureSupport(BackpressureKind.FULL)
16674 @SchedulerSupport(SchedulerSupport.NONE)
16675 @NonNull
16676 public final Flowable<T> takeLast(long count, long time, @NonNull TimeUnit unit) {
16677 return takeLast(count, time, unit, Schedulers.computation(), false, bufferSize());
16678 }
16679
16680 /**
16681 * Returns a {@code Flowable} that emits at most a specified number of items from the current {@code Flowable} that were
16682 * emitted in a specified window of time before the current {@code Flowable} completed, where the timing information is
16683 * provided by a given {@link Scheduler}.
16684 * <p>
16685 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/takeLast.tns.v3.png" alt="">
16686 * <dl>
16687 * <dt><b>Backpressure:</b></dt>
16688 * <dd>The operator honors backpressure from downstream and consumes the current {@code Flowable} in an
16689 * unbounded manner (i.e., no backpressure is applied to it).</dd>
16690 * <dt><b>Scheduler:</b></dt>
16691 * <dd>You specify which {@code Scheduler} this operator will use for tracking the current time</dd>
16692 * </dl>
16693 *
16694 * @param count
16695 * the maximum number of items to emit
16696 * @param time
16697 * the length of the time window
16698 * @param unit
16699 * the time unit of {@code time}
16700 * @param scheduler
16701 * the {@code Scheduler} that provides the timestamps for the observed items
16702 * @return the new {@code Flowable} instance
16703 * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null}
16704 * @throws IllegalArgumentException
16705 * if {@code count} is less than zero
16706 * @see <a href="http://reactivex.io/documentation/operators/takelast.html">ReactiveX operators documentation: TakeLast</a>
16707 */
16708 @CheckReturnValue
16709 @BackpressureSupport(BackpressureKind.FULL)
16710 @SchedulerSupport(SchedulerSupport.CUSTOM)
16711 @NonNull
16712 public final Flowable<T> takeLast(long count, long time, @NonNull TimeUnit unit, @NonNull Scheduler scheduler) {
16713 return takeLast(count, time, unit, scheduler, false, bufferSize());
16714 }
16715
16716 /**
16717 * Returns a {@code Flowable} that emits at most a specified number of items from the current {@code Flowable} that were
16718 * emitted in a specified window of time before the current {@code Flowable} completed, where the timing information is
16719 * provided by a given {@link Scheduler}.
16720 * <p>
16721 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/takeLast.tns.v3.png" alt="">
16722 * <dl>
16723 * <dt><b>Backpressure:</b></dt>
16724 * <dd>The operator honors backpressure from downstream and consumes the current {@code Flowable} in an
16725 * unbounded manner (i.e., no backpressure is applied to it).</dd>
16726 * <dt><b>Scheduler:</b></dt>
16727 * <dd>You specify which {@code Scheduler} this operator will use for tracking the current time</dd>
16728 * </dl>
16729 *
16730 * @param count
16731 * the maximum number of items to emit
16732 * @param time
16733 * the length of the time window
16734 * @param unit
16735 * the time unit of {@code time}
16736 * @param scheduler
16737 * the {@code Scheduler} that provides the timestamps for the observed items
16738 * @param delayError
16739 * if {@code true}, an exception signaled by the current {@code Flowable} is delayed until the regular elements are consumed
16740 * by the downstream; if {@code false}, an exception is immediately signaled and all regular elements dropped
16741 * @param bufferSize
16742 * the hint about how many elements to expect to be last
16743 * @return the new {@code Flowable} instance
16744 * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null}
16745 * @throws IllegalArgumentException
16746 * if {@code count} is negative or {@code bufferSize} is non-positive
16747 * @see <a href="http://reactivex.io/documentation/operators/takelast.html">ReactiveX operators documentation: TakeLast</a>
16748 */
16749 @CheckReturnValue
16750 @NonNull
16751 @BackpressureSupport(BackpressureKind.FULL)
16752 @SchedulerSupport(SchedulerSupport.CUSTOM)
16753 public final Flowable<T> takeLast(long count, long time, @NonNull TimeUnit unit, @NonNull Scheduler scheduler, boolean delayError, int bufferSize) {
16754 Objects.requireNonNull(unit, "unit is null");
16755 Objects.requireNonNull(scheduler, "scheduler is null");
16756 ObjectHelper.verifyPositive(bufferSize, "bufferSize");
16757 if (count < 0) {
16758 throw new IllegalArgumentException("count >= 0 required but it was " + count);
16759 }
16760 return RxJavaPlugins.onAssembly(new FlowableTakeLastTimed<>(this, count, time, unit, scheduler, bufferSize, delayError));
16761 }
16762
16763 /**
16764 * Returns a {@code Flowable} that emits the items from the current {@code Flowable} that were emitted in a specified
16765 * window of time before the current {@code Flowable} completed.
16766 * <p>
16767 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/takeLast.t.v3.png" alt="">
16768 * <dl>
16769 * <dt><b>Backpressure:</b></dt>
16770 * <dd>The operator honors backpressure from downstream and consumes the current {@code Flowable} in an
16771 * unbounded manner (i.e., no backpressure is applied to it) but note that this <em>may</em>
16772 * lead to {@link OutOfMemoryError} due to internal buffer bloat.
16773 * Consider using {@link #takeLast(long, long, TimeUnit)} in this case.</dd>
16774 * <dt><b>Scheduler:</b></dt>
16775 * <dd>This version of {@code takeLast} operates by default on the {@code computation} {@link Scheduler}.</dd>
16776 * </dl>
16777 *
16778 * @param time
16779 * the length of the time window
16780 * @param unit
16781 * the time unit of {@code time}
16782 * @return the new {@code Flowable} instance
16783 * @throws NullPointerException if {@code unit} is {@code null}
16784 * @see <a href="http://reactivex.io/documentation/operators/takelast.html">ReactiveX operators documentation: TakeLast</a>
16785 */
16786 @CheckReturnValue
16787 @BackpressureSupport(BackpressureKind.FULL)
16788 @SchedulerSupport(SchedulerSupport.COMPUTATION)
16789 @NonNull
16790 public final Flowable<T> takeLast(long time, @NonNull TimeUnit unit) {
16791 return takeLast(time, unit, Schedulers.computation(), false, bufferSize());
16792 }
16793
16794 /**
16795 * Returns a {@code Flowable} that emits the items from the current {@code Flowable} that were emitted in a specified
16796 * window of time before the current {@code Flowable} completed.
16797 * <p>
16798 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/takeLast.t.v3.png" alt="">
16799 * <dl>
16800 * <dt><b>Backpressure:</b></dt>
16801 * <dd>The operator honors backpressure from downstream and consumes the current {@code Flowable} in an
16802 * unbounded manner (i.e., no backpressure is applied to it) but note that this <em>may</em>
16803 * lead to {@link OutOfMemoryError} due to internal buffer bloat.
16804 * Consider using {@link #takeLast(long, long, TimeUnit)} in this case.</dd>
16805 * <dt><b>Scheduler:</b></dt>
16806 * <dd>This version of {@code takeLast} operates by default on the {@code computation} {@link Scheduler}.</dd>
16807 * </dl>
16808 *
16809 * @param time
16810 * the length of the time window
16811 * @param unit
16812 * the time unit of {@code time}
16813 * @param delayError
16814 * if {@code true}, an exception signaled by the current {@code Flowable} is delayed until the regular elements are consumed
16815 * by the downstream; if {@code false}, an exception is immediately signaled and all regular elements dropped
16816 * @return the new {@code Flowable} instance
16817 * @throws NullPointerException if {@code unit} is {@code null}
16818 * @see <a href="http://reactivex.io/documentation/operators/takelast.html">ReactiveX operators documentation: TakeLast</a>
16819 */
16820 @CheckReturnValue
16821 @BackpressureSupport(BackpressureKind.FULL)
16822 @SchedulerSupport(SchedulerSupport.COMPUTATION)
16823 @NonNull
16824 public final Flowable<T> takeLast(long time, @NonNull TimeUnit unit, boolean delayError) {
16825 return takeLast(time, unit, Schedulers.computation(), delayError, bufferSize());
16826 }
16827
16828 /**
16829 * Returns a {@code Flowable} that emits the items from the current {@code Flowable} that were emitted in a specified
16830 * window of time before the current {@code Flowable} completed, where the timing information is provided by a specified
16831 * {@link Scheduler}.
16832 * <p>
16833 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/takeLast.ts.v3.png" alt="">
16834 * <dl>
16835 * <dt><b>Backpressure:</b></dt>
16836 * <dd>The operator honors backpressure from downstream and consumes the current {@code Flowable} in an
16837 * unbounded manner (i.e., no backpressure is applied to it) but note that this <em>may</em>
16838 * lead to {@link OutOfMemoryError} due to internal buffer bloat.
16839 * Consider using {@link #takeLast(long, long, TimeUnit, Scheduler)} in this case.</dd>
16840 * <dt><b>Scheduler:</b></dt>
16841 * <dd>You specify which {@code Scheduler} this operator will use.</dd>
16842 * </dl>
16843 *
16844 * @param time
16845 * the length of the time window
16846 * @param unit
16847 * the time unit of {@code time}
16848 * @param scheduler
16849 * the {@code Scheduler} that provides the timestamps for the observed items
16850 * @return the new {@code Flowable} instance
16851 * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null}
16852 * @see <a href="http://reactivex.io/documentation/operators/takelast.html">ReactiveX operators documentation: TakeLast</a>
16853 */
16854 @CheckReturnValue
16855 @BackpressureSupport(BackpressureKind.FULL)
16856 @SchedulerSupport(SchedulerSupport.CUSTOM)
16857 @NonNull
16858 public final Flowable<T> takeLast(long time, @NonNull TimeUnit unit, @NonNull Scheduler scheduler) {
16859 return takeLast(time, unit, scheduler, false, bufferSize());
16860 }
16861
16862 /**
16863 * Returns a {@code Flowable} that emits the items from the current {@code Flowable} that were emitted in a specified
16864 * window of time before the current {@code Flowable} completed, where the timing information is provided by a specified
16865 * {@link Scheduler}.
16866 * <p>
16867 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/takeLast.ts.v3.png" alt="">
16868 * <dl>
16869 * <dt><b>Backpressure:</b></dt>
16870 * <dd>The operator honors backpressure from downstream and consumes the current {@code Flowable} in an
16871 * unbounded manner (i.e., no backpressure is applied to it) but note that this <em>may</em>
16872 * lead to {@link OutOfMemoryError} due to internal buffer bloat.
16873 * Consider using {@link #takeLast(long, long, TimeUnit, Scheduler)} in this case.</dd>
16874 * <dt><b>Scheduler:</b></dt>
16875 * <dd>You specify which {@code Scheduler} this operator will use.</dd>
16876 * </dl>
16877 *
16878 * @param time
16879 * the length of the time window
16880 * @param unit
16881 * the time unit of {@code time}
16882 * @param scheduler
16883 * the {@code Scheduler} that provides the timestamps for the observed items
16884 * @param delayError
16885 * if {@code true}, an exception signaled by the current {@code Flowable} is delayed until the regular elements are consumed
16886 * by the downstream; if {@code false}, an exception is immediately signaled and all regular elements dropped
16887 * @return the new {@code Flowable} instance
16888 * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null}
16889 * @see <a href="http://reactivex.io/documentation/operators/takelast.html">ReactiveX operators documentation: TakeLast</a>
16890 */
16891 @CheckReturnValue
16892 @BackpressureSupport(BackpressureKind.FULL)
16893 @SchedulerSupport(SchedulerSupport.CUSTOM)
16894 @NonNull
16895 public final Flowable<T> takeLast(long time, @NonNull TimeUnit unit, @NonNull Scheduler scheduler, boolean delayError) {
16896 return takeLast(time, unit, scheduler, delayError, bufferSize());
16897 }
16898
16899 /**
16900 * Returns a {@code Flowable} that emits the items from the current {@code Flowable} that were emitted in a specified
16901 * window of time before the current {@code Flowable} completed, where the timing information is provided by a specified
16902 * {@link Scheduler}.
16903 * <p>
16904 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/takeLast.ts.v3.png" alt="">
16905 * <dl>
16906 * <dt><b>Backpressure:</b></dt>
16907 * <dd>The operator honors backpressure from downstream and consumes the current {@code Flowable} in an
16908 * unbounded manner (i.e., no backpressure is applied to it) but note that this <em>may</em>
16909 * lead to {@link OutOfMemoryError} due to internal buffer bloat.
16910 * Consider using {@link #takeLast(long, long, TimeUnit, Scheduler)} in this case.</dd>
16911 * <dt><b>Scheduler:</b></dt>
16912 * <dd>You specify which {@code Scheduler} this operator will use.</dd>
16913 * </dl>
16914 *
16915 * @param time
16916 * the length of the time window
16917 * @param unit
16918 * the time unit of {@code time}
16919 * @param scheduler
16920 * the {@code Scheduler} that provides the timestamps for the observed items
16921 * @param delayError
16922 * if {@code true}, an exception signaled by the current {@code Flowable} is delayed until the regular elements are consumed
16923 * by the downstream; if {@code false}, an exception is immediately signaled and all regular elements dropped
16924 * @param bufferSize
16925 * the hint about how many elements to expect to be last
16926 * @return the new {@code Flowable} instance
16927 * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null}
16928 * @throws IllegalArgumentException if {@code bufferSize} is non-positive
16929 * @see <a href="http://reactivex.io/documentation/operators/takelast.html">ReactiveX operators documentation: TakeLast</a>
16930 */
16931 @CheckReturnValue
16932 @BackpressureSupport(BackpressureKind.FULL)
16933 @SchedulerSupport(SchedulerSupport.CUSTOM)
16934 @NonNull
16935 public final Flowable<T> takeLast(long time, @NonNull TimeUnit unit, @NonNull Scheduler scheduler, boolean delayError, int bufferSize) {
16936 return takeLast(Long.MAX_VALUE, time, unit, scheduler, delayError, bufferSize);
16937 }
16938
16939 /**
16940 * Returns a {@code Flowable} that emits items emitted by the current {@code Flowable}, checks the specified predicate
16941 * for each item, and then completes when the condition is satisfied.
16942 * <p>
16943 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/takeUntil.p.v3.png" alt="">
16944 * <p>
16945 * The difference between this operator and {@link #takeWhile(Predicate)} is that here, the condition is
16946 * evaluated <em>after</em> the item is emitted.
16947 *
16948 * <dl>
16949 * <dt><b>Backpressure:</b></dt>
16950 * <dd>The operator is a pass-through for backpressure; the backpressure behavior is determined by the upstream
16951 * source and the downstream consumer.</dd>
16952 * <dt><b>Scheduler:</b></dt>
16953 * <dd>{@code takeUntil} does not operate by default on a particular {@link Scheduler}.</dd>
16954 * </dl>
16955 *
16956 * @param stopPredicate
16957 * a function that evaluates an item emitted by the current {@code Flowable} and returns a {@link Boolean}
16958 * @return the new {@code Flowable} instance
16959 * @throws NullPointerException if {@code stopPredicate} is {@code null}
16960 * @see <a href="http://reactivex.io/documentation/operators/takeuntil.html">ReactiveX operators documentation: TakeUntil</a>
16961 * @see Flowable#takeWhile(Predicate)
16962 * @since 1.1.0
16963 */
16964 @CheckReturnValue
16965 @NonNull
16966 @BackpressureSupport(BackpressureKind.PASS_THROUGH)
16967 @SchedulerSupport(SchedulerSupport.NONE)
16968 public final Flowable<T> takeUntil(@NonNull Predicate<? super T> stopPredicate) {
16969 Objects.requireNonNull(stopPredicate, "stopPredicate is null");
16970 return RxJavaPlugins.onAssembly(new FlowableTakeUntilPredicate<>(this, stopPredicate));
16971 }
16972
16973 /**
16974 * Returns a {@code Flowable} that emits the items emitted by the current {@code Flowable} until a second {@link Publisher}
16975 * emits an item or completes.
16976 * <p>
16977 * <img width="640" height="188" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Flowable.takeUntil.p.png" alt="">
16978 * <dl>
16979 * <dt><b>Backpressure:</b></dt>
16980 * <dd>The operator doesn't interfere with backpressure which is determined by the current {@code Flowable}'s backpressure
16981 * behavior.</dd>
16982 * <dt><b>Scheduler:</b></dt>
16983 * <dd>{@code takeUntil} does not operate by default on a particular {@link Scheduler}.</dd>
16984 * </dl>
16985 *
16986 * @param other
16987 * the {@code Publisher} whose first emitted item or completion will cause {@code takeUntil} to stop emitting items
16988 * from the current {@code Flowable}
16989 * @param <U>
16990 * the type of items emitted by {@code other}
16991 * @return the new {@code Flowable} instance
16992 * @throws NullPointerException if {@code other} is {@code null}
16993 * @see <a href="http://reactivex.io/documentation/operators/takeuntil.html">ReactiveX operators documentation: TakeUntil</a>
16994 */
16995 @CheckReturnValue
16996 @NonNull
16997 @BackpressureSupport(BackpressureKind.PASS_THROUGH)
16998 @SchedulerSupport(SchedulerSupport.NONE)
16999 public final <@NonNull U> Flowable<T> takeUntil(@NonNull Publisher<U> other) {
17000 Objects.requireNonNull(other, "other is null");
17001 return RxJavaPlugins.onAssembly(new FlowableTakeUntil<>(this, other));
17002 }
17003
17004 /**
17005 * Returns a {@code Flowable} that emits items emitted by the current {@code Flowable} so long as each item satisfied a
17006 * specified condition, and then completes as soon as this condition is not satisfied.
17007 * <p>
17008 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/takeWhile.v3.png" alt="">
17009 * <dl>
17010 * <dt><b>Backpressure:</b></dt>
17011 * <dd>The operator doesn't interfere with backpressure which is determined by the current {@code Flowable}'s backpressure
17012 * behavior.</dd>
17013 * <dt><b>Scheduler:</b></dt>
17014 * <dd>{@code takeWhile} does not operate by default on a particular {@link Scheduler}.</dd>
17015 * </dl>
17016 *
17017 * @param predicate
17018 * a function that evaluates an item emitted by the current {@code Flowable} and returns a {@link Boolean}
17019 * @return the new {@code Flowable} instance
17020 * @throws NullPointerException if {@code predicate} is {@code null}
17021 * @see <a href="http://reactivex.io/documentation/operators/takewhile.html">ReactiveX operators documentation: TakeWhile</a>
17022 * @see Flowable#takeUntil(Predicate)
17023 */
17024 @CheckReturnValue
17025 @NonNull
17026 @BackpressureSupport(BackpressureKind.PASS_THROUGH)
17027 @SchedulerSupport(SchedulerSupport.NONE)
17028 public final Flowable<T> takeWhile(@NonNull Predicate<? super T> predicate) {
17029 Objects.requireNonNull(predicate, "predicate is null");
17030 return RxJavaPlugins.onAssembly(new FlowableTakeWhile<>(this, predicate));
17031 }
17032
17033 /**
17034 * Returns a {@code Flowable} that emits only the first item emitted by the current {@code Flowable} during sequential
17035 * time windows of a specified duration.
17036 * <p>
17037 * This differs from {@link #throttleLast} in that this only tracks the passage of time whereas
17038 * {@link #throttleLast} ticks at scheduled intervals.
17039 * <p>
17040 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/throttleFirst.v3.png" alt="">
17041 * <dl>
17042 * <dt><b>Backpressure:</b></dt>
17043 * <dd>This operator does not support backpressure as it uses time to control data flow.</dd>
17044 * <dt><b>Scheduler:</b></dt>
17045 * <dd>{@code throttleFirst} operates by default on the {@code computation} {@link Scheduler}.</dd>
17046 * </dl>
17047 *
17048 * @param windowDuration
17049 * time to wait before emitting another item after emitting the last item
17050 * @param unit
17051 * the unit of time of {@code windowDuration}
17052 * @return the new {@code Flowable} instance
17053 * @throws NullPointerException if {@code unit} is {@code null}
17054 * @see <a href="http://reactivex.io/documentation/operators/sample.html">ReactiveX operators documentation: Sample</a>
17055 * @see <a href="https://github.com/ReactiveX/RxJava/wiki/Backpressure">RxJava wiki: Backpressure</a>
17056 */
17057 @CheckReturnValue
17058 @BackpressureSupport(BackpressureKind.ERROR)
17059 @SchedulerSupport(SchedulerSupport.COMPUTATION)
17060 @NonNull
17061 public final Flowable<T> throttleFirst(long windowDuration, @NonNull TimeUnit unit) {
17062 return throttleFirst(windowDuration, unit, Schedulers.computation());
17063 }
17064
17065 /**
17066 * Returns a {@code Flowable} that emits only the first item emitted by the current {@code Flowable} during sequential
17067 * time windows of a specified duration, where the windows are managed by a specified {@link Scheduler}.
17068 * <p>
17069 * This differs from {@link #throttleLast} in that this only tracks the passage of time whereas
17070 * {@link #throttleLast} ticks at scheduled intervals.
17071 * <p>
17072 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/throttleFirst.s.v3.png" alt="">
17073 * <dl>
17074 * <dt><b>Backpressure:</b></dt>
17075 * <dd>This operator does not support backpressure as it uses time to control data flow.</dd>
17076 * <dt><b>Scheduler:</b></dt>
17077 * <dd>You specify which {@code Scheduler} this operator will use.</dd>
17078 * </dl>
17079 *
17080 * @param skipDuration
17081 * time to wait before emitting another item after emitting the last item
17082 * @param unit
17083 * the unit of time of {@code skipDuration}
17084 * @param scheduler
17085 * the {@code Scheduler} to use internally to manage the timers that handle timeout for each
17086 * event
17087 * @return the new {@code Flowable} instance
17088 * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null}
17089 * @see <a href="http://reactivex.io/documentation/operators/sample.html">ReactiveX operators documentation: Sample</a>
17090 * @see <a href="https://github.com/ReactiveX/RxJava/wiki/Backpressure">RxJava wiki: Backpressure</a>
17091 */
17092 @CheckReturnValue
17093 @NonNull
17094 @BackpressureSupport(BackpressureKind.ERROR)
17095 @SchedulerSupport(SchedulerSupport.CUSTOM)
17096 public final Flowable<T> throttleFirst(long skipDuration, @NonNull TimeUnit unit, @NonNull Scheduler scheduler) {
17097 Objects.requireNonNull(unit, "unit is null");
17098 Objects.requireNonNull(scheduler, "scheduler is null");
17099 return RxJavaPlugins.onAssembly(new FlowableThrottleFirstTimed<>(this, skipDuration, unit, scheduler));
17100 }
17101
17102 /**
17103 * Returns a {@code Flowable} that emits only the last item emitted by the current {@code Flowable} during sequential
17104 * time windows of a specified duration.
17105 * <p>
17106 * This differs from {@link #throttleFirst} in that this ticks along at a scheduled interval whereas
17107 * {@link #throttleFirst} does not tick, it just tracks the passage of time.
17108 * <p>
17109 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/throttleLast.v3.png" alt="">
17110 * <dl>
17111 * <dt><b>Backpressure:</b></dt>
17112 * <dd>This operator does not support backpressure as it uses time to control data flow.</dd>
17113 * <dt><b>Scheduler:</b></dt>
17114 * <dd>{@code throttleLast} operates by default on the {@code computation} {@link Scheduler}.</dd>
17115 * </dl>
17116 *
17117 * @param intervalDuration
17118 * duration of windows within which the last item emitted by the current {@code Flowable} will be
17119 * emitted
17120 * @param unit
17121 * the unit of time of {@code intervalDuration}
17122 * @return the new {@code Flowable} instance
17123 * @throws NullPointerException if {@code unit} is {@code null}
17124 * @see <a href="http://reactivex.io/documentation/operators/sample.html">ReactiveX operators documentation: Sample</a>
17125 * @see <a href="https://github.com/ReactiveX/RxJava/wiki/Backpressure">RxJava wiki: Backpressure</a>
17126 * @see #sample(long, TimeUnit)
17127 */
17128 @CheckReturnValue
17129 @BackpressureSupport(BackpressureKind.ERROR)
17130 @SchedulerSupport(SchedulerSupport.COMPUTATION)
17131 @NonNull
17132 public final Flowable<T> throttleLast(long intervalDuration, @NonNull TimeUnit unit) {
17133 return sample(intervalDuration, unit);
17134 }
17135
17136 /**
17137 * Returns a {@code Flowable} that emits only the last item emitted by the current {@code Flowable} during sequential
17138 * time windows of a specified duration, where the duration is governed by a specified {@link Scheduler}.
17139 * <p>
17140 * This differs from {@link #throttleFirst(long, TimeUnit, Scheduler)} in that this ticks along at a scheduled interval whereas
17141 * {@code throttleFirst} does not tick, it just tracks the passage of time.
17142 * <p>
17143 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/throttleLast.s.v3.png" alt="">
17144 * <dl>
17145 * <dt><b>Backpressure:</b></dt>
17146 * <dd>This operator does not support backpressure as it uses time to control data flow.</dd>
17147 * <dt><b>Scheduler:</b></dt>
17148 * <dd>You specify which {@code Scheduler} this operator will use.</dd>
17149 * </dl>
17150 *
17151 * @param intervalDuration
17152 * duration of windows within which the last item emitted by the current {@code Flowable} will be
17153 * emitted
17154 * @param unit
17155 * the unit of time of {@code intervalDuration}
17156 * @param scheduler
17157 * the {@code Scheduler} to use internally to manage the timers that handle timeout for each
17158 * event
17159 * @return the new {@code Flowable} instance
17160 * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null}
17161 * @see <a href="http://reactivex.io/documentation/operators/sample.html">ReactiveX operators documentation: Sample</a>
17162 * @see <a href="https://github.com/ReactiveX/RxJava/wiki/Backpressure">RxJava wiki: Backpressure</a>
17163 * @see #sample(long, TimeUnit, Scheduler)
17164 */
17165 @CheckReturnValue
17166 @BackpressureSupport(BackpressureKind.ERROR)
17167 @SchedulerSupport(SchedulerSupport.CUSTOM)
17168 @NonNull
17169 public final Flowable<T> throttleLast(long intervalDuration, @NonNull TimeUnit unit, @NonNull Scheduler scheduler) {
17170 return sample(intervalDuration, unit, scheduler);
17171 }
17172
17173 /**
17174 * Throttles items from the upstream {@code Flowable} by first emitting the next
17175 * item from upstream, then periodically emitting the latest item (if any) when
17176 * the specified timeout elapses between them.
17177 * <p>
17178 * <img width="640" height="326" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/throttleLatest.png" alt="">
17179 * <p>
17180 * Unlike the option with {@link #throttleLatest(long, TimeUnit, boolean)}, the very last item being held back
17181 * (if any) is not emitted when the upstream completes.
17182 * <p>
17183 * If no items were emitted from the upstream during this timeout phase, the next
17184 * upstream item is emitted immediately and the timeout window starts from then.
17185 * <dl>
17186 * <dt><b>Backpressure:</b></dt>
17187 * <dd>This operator does not support backpressure as it uses time to control data flow.
17188 * If the downstream is not ready to receive items, a
17189 * {@link io.reactivex.rxjava3.exceptions.MissingBackpressureException MissingBackpressureException}
17190 * will be signaled.</dd>
17191 * <dt><b>Scheduler:</b></dt>
17192 * <dd>{@code throttleLatest} operates by default on the {@code computation} {@link Scheduler}.</dd>
17193 * </dl>
17194 * <p>History: 2.1.14 - experimental
17195 * @param timeout the time to wait after an item emission towards the downstream
17196 * before trying to emit the latest item from upstream again
17197 * @param unit the time unit
17198 * @return the new {@code Flowable} instance
17199 * @throws NullPointerException if {@code unit} is {@code null}
17200 * @since 2.2
17201 * @see #throttleLatest(long, TimeUnit, boolean)
17202 * @see #throttleLatest(long, TimeUnit, Scheduler)
17203 */
17204 @CheckReturnValue
17205 @BackpressureSupport(BackpressureKind.ERROR)
17206 @SchedulerSupport(SchedulerSupport.COMPUTATION)
17207 @NonNull
17208 public final Flowable<T> throttleLatest(long timeout, @NonNull TimeUnit unit) {
17209 return throttleLatest(timeout, unit, Schedulers.computation(), false);
17210 }
17211
17212 /**
17213 * Throttles items from the upstream {@code Flowable} by first emitting the next
17214 * item from upstream, then periodically emitting the latest item (if any) when
17215 * the specified timeout elapses between them.
17216 * <p>
17217 * <img width="640" height="326" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/throttleLatest.e.png" alt="">
17218 * <p>
17219 * If no items were emitted from the upstream during this timeout phase, the next
17220 * upstream item is emitted immediately and the timeout window starts from then.
17221 * <dl>
17222 * <dt><b>Backpressure:</b></dt>
17223 * <dd>This operator does not support backpressure as it uses time to control data flow.
17224 * If the downstream is not ready to receive items, a
17225 * {@link io.reactivex.rxjava3.exceptions.MissingBackpressureException MissingBackpressureException}
17226 * will be signaled.</dd>
17227 * <dt><b>Scheduler:</b></dt>
17228 * <dd>{@code throttleLatest} operates by default on the {@code computation} {@link Scheduler}.</dd>
17229 * </dl>
17230 * <p>History: 2.1.14 - experimental
17231 * @param timeout the time to wait after an item emission towards the downstream
17232 * before trying to emit the latest item from upstream again
17233 * @param unit the time unit
17234 * @param emitLast If {@code true}, the very last item from the upstream will be emitted
17235 * immediately when the upstream completes, regardless if there is
17236 * a timeout window active or not. If {@code false}, the very last
17237 * upstream item is ignored and the flow terminates.
17238 * @return the new {@code Flowable} instance
17239 * @throws NullPointerException if {@code unit} is {@code null}
17240 * @see #throttleLatest(long, TimeUnit, Scheduler, boolean)
17241 * @since 2.2
17242 */
17243 @CheckReturnValue
17244 @BackpressureSupport(BackpressureKind.ERROR)
17245 @SchedulerSupport(SchedulerSupport.COMPUTATION)
17246 @NonNull
17247 public final Flowable<T> throttleLatest(long timeout, @NonNull TimeUnit unit, boolean emitLast) {
17248 return throttleLatest(timeout, unit, Schedulers.computation(), emitLast);
17249 }
17250
17251 /**
17252 * Throttles items from the upstream {@code Flowable} by first emitting the next
17253 * item from upstream, then periodically emitting the latest item (if any) when
17254 * the specified timeout elapses between them.
17255 * <p>
17256 * <img width="640" height="326" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/throttleLatest.s.png" alt="">
17257 * <p>
17258 * Unlike the option with {@link #throttleLatest(long, TimeUnit, Scheduler, boolean)}, the very last item being held back
17259 * (if any) is not emitted when the upstream completes.
17260 * <p>
17261 * If no items were emitted from the upstream during this timeout phase, the next
17262 * upstream item is emitted immediately and the timeout window starts from then.
17263 * <dl>
17264 * <dt><b>Backpressure:</b></dt>
17265 * <dd>This operator does not support backpressure as it uses time to control data flow.
17266 * If the downstream is not ready to receive items, a
17267 * {@link io.reactivex.rxjava3.exceptions.MissingBackpressureException MissingBackpressureException}
17268 * will be signaled.</dd>
17269 * <dt><b>Scheduler:</b></dt>
17270 * <dd>You specify which {@link Scheduler} this operator will use.</dd>
17271 * </dl>
17272 * <p>History: 2.1.14 - experimental
17273 * @param timeout the time to wait after an item emission towards the downstream
17274 * before trying to emit the latest item from upstream again
17275 * @param unit the time unit
17276 * @param scheduler the {@code Scheduler} where the timed wait and latest item
17277 * emission will be performed
17278 * @return the new {@code Flowable} instance
17279 * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null}
17280 * @see #throttleLatest(long, TimeUnit, Scheduler, boolean)
17281 * @since 2.2
17282 */
17283 @CheckReturnValue
17284 @BackpressureSupport(BackpressureKind.ERROR)
17285 @SchedulerSupport(SchedulerSupport.CUSTOM)
17286 @NonNull
17287 public final Flowable<T> throttleLatest(long timeout, @NonNull TimeUnit unit, @NonNull Scheduler scheduler) {
17288 return throttleLatest(timeout, unit, scheduler, false);
17289 }
17290
17291 /**
17292 * Throttles items from the upstream {@code Flowable} by first emitting the next
17293 * item from upstream, then periodically emitting the latest item (if any) when
17294 * the specified timeout elapses between them.
17295 * <p>
17296 * <img width="640" height="326" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/throttleLatest.se.png" alt="">
17297 * <p>
17298 * If no items were emitted from the upstream during this timeout phase, the next
17299 * upstream item is emitted immediately and the timeout window starts from then.
17300 * <dl>
17301 * <dt><b>Backpressure:</b></dt>
17302 * <dd>This operator does not support backpressure as it uses time to control data flow.
17303 * If the downstream is not ready to receive items, a
17304 * {@link io.reactivex.rxjava3.exceptions.MissingBackpressureException MissingBackpressureException}
17305 * will be signaled.</dd>
17306 * <dt><b>Scheduler:</b></dt>
17307 * <dd>You specify which {@link Scheduler} this operator will use.</dd>
17308 * </dl>
17309 * <p>History: 2.1.14 - experimental
17310 * @param timeout the time to wait after an item emission towards the downstream
17311 * before trying to emit the latest item from upstream again
17312 * @param unit the time unit
17313 * @param scheduler the {@code Scheduler} where the timed wait and latest item
17314 * emission will be performed
17315 * @param emitLast If {@code true}, the very last item from the upstream will be emitted
17316 * immediately when the upstream completes, regardless if there is
17317 * a timeout window active or not. If {@code false}, the very last
17318 * upstream item is ignored and the flow terminates.
17319 * @return the new {@code Flowable} instance
17320 * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null}
17321 * @since 2.2
17322 */
17323 @CheckReturnValue
17324 @NonNull
17325 @BackpressureSupport(BackpressureKind.ERROR)
17326 @SchedulerSupport(SchedulerSupport.CUSTOM)
17327 public final Flowable<T> throttleLatest(long timeout, @NonNull TimeUnit unit, @NonNull Scheduler scheduler, boolean emitLast) {
17328 Objects.requireNonNull(unit, "unit is null");
17329 Objects.requireNonNull(scheduler, "scheduler is null");
17330 return RxJavaPlugins.onAssembly(new FlowableThrottleLatest<>(this, timeout, unit, scheduler, emitLast));
17331 }
17332
17333 /**
17334 * Returns a {@code Flowable} that mirrors the current {@code Flowable}, except that it drops items emitted by the
17335 * current {@code Flowable} that are followed by newer items before a timeout value expires. The timer resets on
17336 * each emission (alias to {@link #debounce(long, TimeUnit)}).
17337 * <p>
17338 * <em>Note:</em> If items keep being emitted by the current {@code Flowable} faster than the timeout then no items
17339 * will be emitted by the resulting {@code Flowable}.
17340 * <p>
17341 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/throttleWithTimeout.v3.png" alt="">
17342 * <dl>
17343 * <dt><b>Backpressure:</b></dt>
17344 * <dd>This operator does not support backpressure as it uses time to control data flow.</dd>
17345 * <dt><b>Scheduler:</b></dt>
17346 * <dd>{@code throttleWithTimeout} operates by default on the {@code computation} {@link Scheduler}.</dd>
17347 * </dl>
17348 *
17349 * @param timeout
17350 * the length of the window of time that must pass after the emission of an item from the current
17351 * {@code Flowable} in which it emits no items in order for the item to be emitted by the
17352 * resulting {@code Flowable}
17353 * @param unit
17354 * the unit of time for the specified {@code timeout}
17355 * @return the new {@code Flowable} instance
17356 * @throws NullPointerException if {@code unit} is {@code null}
17357 * @see <a href="http://reactivex.io/documentation/operators/debounce.html">ReactiveX operators documentation: Debounce</a>
17358 * @see <a href="https://github.com/ReactiveX/RxJava/wiki/Backpressure">RxJava wiki: Backpressure</a>
17359 * @see #debounce(long, TimeUnit)
17360 */
17361 @CheckReturnValue
17362 @BackpressureSupport(BackpressureKind.ERROR)
17363 @SchedulerSupport(SchedulerSupport.COMPUTATION)
17364 @NonNull
17365 public final Flowable<T> throttleWithTimeout(long timeout, @NonNull TimeUnit unit) {
17366 return debounce(timeout, unit);
17367 }
17368
17369 /**
17370 * Returns a {@code Flowable} that mirrors the current {@code Flowable}, except that it drops items emitted by the
17371 * current {@code Flowable} that are followed by newer items before a timeout value expires on a specified
17372 * {@link Scheduler}. The timer resets on each emission (alias to {@link #debounce(long, TimeUnit, Scheduler)}).
17373 * <p>
17374 * <em>Note:</em> If items keep being emitted by the current {@code Flowable} faster than the timeout then no items
17375 * will be emitted by the resulting {@code Flowable}.
17376 * <p>
17377 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/throttleWithTimeout.s.v3.png" alt="">
17378 * <dl>
17379 * <dt><b>Backpressure:</b></dt>
17380 * <dd>This operator does not support backpressure as it uses time to control data flow.</dd>
17381 * <dt><b>Scheduler:</b></dt>
17382 * <dd>You specify which {@code Scheduler} this operator will use.</dd>
17383 * </dl>
17384 *
17385 * @param timeout
17386 * the length of the window of time that must pass after the emission of an item from the current
17387 * {@code Flowable} in which it emits no items in order for the item to be emitted by the
17388 * resulting {@code Flowable}
17389 * @param unit
17390 * the unit of time for the specified {@code timeout}
17391 * @param scheduler
17392 * the {@code Scheduler} to use internally to manage the timers that handle the timeout for each
17393 * item
17394 * @return the new {@code Flowable} instance
17395 * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null}
17396 * @see <a href="http://reactivex.io/documentation/operators/debounce.html">ReactiveX operators documentation: Debounce</a>
17397 * @see <a href="https://github.com/ReactiveX/RxJava/wiki/Backpressure">RxJava wiki: Backpressure</a>
17398 * @see #debounce(long, TimeUnit, Scheduler)
17399 */
17400 @CheckReturnValue
17401 @BackpressureSupport(BackpressureKind.ERROR)
17402 @SchedulerSupport(SchedulerSupport.CUSTOM)
17403 @NonNull
17404 public final Flowable<T> throttleWithTimeout(long timeout, @NonNull TimeUnit unit, @NonNull Scheduler scheduler) {
17405 return debounce(timeout, unit, scheduler);
17406 }
17407
17408 /**
17409 * Returns a {@code Flowable} that emits records of the time interval between consecutive items emitted by the
17410 * current {@code Flowable}.
17411 * <p>
17412 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/timeInterval.v3.png" alt="">
17413 * <dl>
17414 * <dt><b>Backpressure:</b></dt>
17415 * <dd>The operator doesn't interfere with backpressure which is determined by the current {@code Flowable}'s backpressure
17416 * behavior.</dd>
17417 * <dt><b>Scheduler:</b></dt>
17418 * <dd>{@code timeInterval} does not operate on any particular scheduler but uses the current time
17419 * from the {@code computation} {@link Scheduler}.</dd>
17420 * </dl>
17421 *
17422 * @return the new {@code Flowable} instance
17423 * @see <a href="http://reactivex.io/documentation/operators/timeinterval.html">ReactiveX operators documentation: TimeInterval</a>
17424 */
17425 @CheckReturnValue
17426 @BackpressureSupport(BackpressureKind.PASS_THROUGH)
17427 @SchedulerSupport(SchedulerSupport.NONE)
17428 @NonNull
17429 public final Flowable<Timed<T>> timeInterval() {
17430 return timeInterval(TimeUnit.MILLISECONDS, Schedulers.computation());
17431 }
17432
17433 /**
17434 * Returns a {@code Flowable} that emits records of the time interval between consecutive items emitted by the
17435 * current {@code Flowable}, where this interval is computed on a specified {@link Scheduler}.
17436 * <p>
17437 * <img width="640" height="315" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/timeInterval.s.v3.png" alt="">
17438 * <dl>
17439 * <dt><b>Backpressure:</b></dt>
17440 * <dd>The operator doesn't interfere with backpressure which is determined by the current {@code Flowable}'s backpressure
17441 * behavior.</dd>
17442 * <dt><b>Scheduler:</b></dt>
17443 * <dd>{@code timeInterval} does not operate on any particular scheduler but uses the current time
17444 * from the specified {@code Scheduler}.</dd>
17445 * </dl>
17446 *
17447 * @param scheduler
17448 * the {@code Scheduler} used to compute time intervals
17449 * @return the new {@code Flowable} instance
17450 * @throws NullPointerException if {@code scheduler} is {@code null}
17451 * @see <a href="http://reactivex.io/documentation/operators/timeinterval.html">ReactiveX operators documentation: TimeInterval</a>
17452 */
17453 @CheckReturnValue
17454 @BackpressureSupport(BackpressureKind.PASS_THROUGH)
17455 @SchedulerSupport(SchedulerSupport.NONE) // Supplied scheduler is only used for creating timestamps.
17456 @NonNull
17457 public final Flowable<Timed<T>> timeInterval(@NonNull Scheduler scheduler) {
17458 return timeInterval(TimeUnit.MILLISECONDS, scheduler);
17459 }
17460
17461 /**
17462 * Returns a {@code Flowable} that emits records of the time interval between consecutive items emitted by the
17463 * current {@code Flowable}.
17464 * <p>
17465 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/timeInterval.v3.png" alt="">
17466 * <dl>
17467 * <dt><b>Backpressure:</b></dt>
17468 * <dd>The operator doesn't interfere with backpressure which is determined by the current {@code Flowable}'s backpressure
17469 * behavior.</dd>
17470 * <dt><b>Scheduler:</b></dt>
17471 * <dd>{@code timeInterval} does not operate on any particular scheduler but uses the current time
17472 * from the {@code computation} {@link Scheduler}.</dd>
17473 * </dl>
17474 *
17475 * @param unit the time unit for the current time
17476 * @return the new {@code Flowable} instance
17477 * @throws NullPointerException if {@code unit} is {@code null}
17478 * @see <a href="http://reactivex.io/documentation/operators/timeinterval.html">ReactiveX operators documentation: TimeInterval</a>
17479 */
17480 @CheckReturnValue
17481 @BackpressureSupport(BackpressureKind.PASS_THROUGH)
17482 @SchedulerSupport(SchedulerSupport.NONE)
17483 @NonNull
17484 public final Flowable<Timed<T>> timeInterval(@NonNull TimeUnit unit) {
17485 return timeInterval(unit, Schedulers.computation());
17486 }
17487
17488 /**
17489 * Returns a {@code Flowable} that emits records of the time interval between consecutive items emitted by the
17490 * current {@code Flowable}, where this interval is computed on a specified {@link Scheduler}.
17491 * <p>
17492 * <img width="640" height="315" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/timeInterval.s.v3.png" alt="">
17493 * <dl>
17494 * <dt><b>Backpressure:</b></dt>
17495 * <dd>The operator doesn't interfere with backpressure which is determined by the current {@code Flowable}'s backpressure
17496 * behavior.</dd>
17497 * <dt><b>Scheduler:</b></dt>
17498 * <dd>{@code timeInterval} does not operate on any particular scheduler but uses the current time
17499 * from the specified {@code Scheduler}.</dd>
17500 * </dl>
17501 *
17502 * @param unit the time unit for the current time
17503 * @param scheduler
17504 * the {@code Scheduler} used to compute time intervals
17505 * @return the new {@code Flowable} instance
17506 * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null}
17507 * @see <a href="http://reactivex.io/documentation/operators/timeinterval.html">ReactiveX operators documentation: TimeInterval</a>
17508 */
17509 @CheckReturnValue
17510 @BackpressureSupport(BackpressureKind.PASS_THROUGH)
17511 @SchedulerSupport(SchedulerSupport.NONE) // Supplied scheduler is only used for creating timestamps.
17512 @NonNull
17513 public final Flowable<Timed<T>> timeInterval(@NonNull TimeUnit unit, @NonNull Scheduler scheduler) {
17514 Objects.requireNonNull(unit, "unit is null");
17515 Objects.requireNonNull(scheduler, "scheduler is null");
17516 return RxJavaPlugins.onAssembly(new FlowableTimeInterval<>(this, unit, scheduler));
17517 }
17518
17519 /**
17520 * Returns a {@code Flowable} that mirrors the current {@code Flowable}, but notifies {@link Subscriber}s of a
17521 * {@link TimeoutException} if an item emitted by the current {@code Flowable} doesn't arrive within a window of
17522 * time after the emission of the previous item, where that period of time is measured by a {@link Publisher} that
17523 * is a function of the previous item.
17524 * <p>
17525 * <img width="640" height="400" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/timeout3.v3.png" alt="">
17526 * <p>
17527 * Note: The arrival of the first source item is never timed out.
17528 * <dl>
17529 * <dt><b>Backpressure:</b></dt>
17530 * <dd>The operator honors backpressure from downstream. The {@code Publisher}
17531 * sources are expected to honor backpressure as well.
17532 * If any of the current {@code Flowable}s violate this, it <em>may</em> throw an
17533 * {@link IllegalStateException} when the current {@code Flowable} completes.</dd>
17534 * <dt><b>Scheduler:</b></dt>
17535 * <dd>This version of {@code timeout} operates by default on the {@code immediate} {@link Scheduler}.</dd>
17536 * </dl>
17537 *
17538 * @param <V>
17539 * the timeout value type (ignored)
17540 * @param itemTimeoutIndicator
17541 * a function that returns a {@code Publisher} for each item emitted by the current
17542 * {@code Flowable} and that determines the timeout window for the subsequent item
17543 * @return the new {@code Flowable} instance
17544 * @throws NullPointerException if {@code itemTimeoutIndicator} is {@code null}
17545 * @see <a href="http://reactivex.io/documentation/operators/timeout.html">ReactiveX operators documentation: Timeout</a>
17546 */
17547 @CheckReturnValue
17548 @BackpressureSupport(BackpressureKind.PASS_THROUGH)
17549 @SchedulerSupport(SchedulerSupport.NONE)
17550 @NonNull
17551 public final <@NonNull V> Flowable<T> timeout(@NonNull Function<? super T, @NonNull ? extends Publisher<V>> itemTimeoutIndicator) {
17552 return timeout0(null, itemTimeoutIndicator, null);
17553 }
17554
17555 /**
17556 * Returns a {@code Flowable} that mirrors the current {@code Flowable}, but that switches to a fallback {@link Publisher} if
17557 * an item emitted by the current {@code Flowable} doesn't arrive within a window of time after the emission of the
17558 * previous item, where that period of time is measured by a {@code Publisher} that is a function of the previous
17559 * item.
17560 * <p>
17561 * <img width="640" height="400" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/timeout4.v3.png" alt="">
17562 * <p>
17563 * Note: The arrival of the first source item is never timed out.
17564 * <dl>
17565 * <dt><b>Backpressure:</b></dt>
17566 * <dd>The operator honors backpressure from downstream. The {@code Publisher}
17567 * sources are expected to honor backpressure as well.
17568 * If any of the current {@code Flowable}s violate this, it <em>may</em> throw an
17569 * {@link IllegalStateException} when the current {@code Flowable} completes.</dd>
17570 * <dt><b>Scheduler:</b></dt>
17571 * <dd>This version of {@code timeout} operates by default on the {@code immediate} {@link Scheduler}.</dd>
17572 * </dl>
17573 *
17574 * @param <V>
17575 * the timeout value type (ignored)
17576 * @param itemTimeoutIndicator
17577 * a function that returns a {@code Publisher}, for each item emitted by the current {@code Flowable}, that
17578 * determines the timeout window for the subsequent item
17579 * @param fallback
17580 * the fallback {@code Publisher} to switch to if the current {@code Flowable} times out
17581 * @return the new {@code Flowable} instance
17582 * @throws NullPointerException if {@code itemTimeoutIndicator} or {@code fallback} is {@code null}
17583 * @see <a href="http://reactivex.io/documentation/operators/timeout.html">ReactiveX operators documentation: Timeout</a>
17584 */
17585 @CheckReturnValue
17586 @NonNull
17587 @BackpressureSupport(BackpressureKind.FULL)
17588 @SchedulerSupport(SchedulerSupport.NONE)
17589 public final <@NonNull V> Flowable<T> timeout(@NonNull Function<? super T, @NonNull ? extends Publisher<V>> itemTimeoutIndicator, @NonNull Publisher<? extends T> fallback) {
17590 Objects.requireNonNull(fallback, "fallback is null");
17591 return timeout0(null, itemTimeoutIndicator, fallback);
17592 }
17593
17594 /**
17595 * Returns a {@code Flowable} that mirrors the current {@code Flowable} but applies a timeout policy for each emitted
17596 * item. If the next item isn't emitted within the specified timeout duration starting from its predecessor,
17597 * the resulting {@code Flowable} terminates and notifies {@link Subscriber}s of a {@link TimeoutException}.
17598 * <p>
17599 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/timeout.1.v3.png" alt="">
17600 * <dl>
17601 * <dt><b>Backpressure:</b></dt>
17602 * <dd>The operator doesn't interfere with backpressure which is determined by the current {@code Flowable}'s backpressure
17603 * behavior.</dd>
17604 * <dt><b>Scheduler:</b></dt>
17605 * <dd>This version of {@code timeout} operates by default on the {@code computation} {@link Scheduler}.</dd>
17606 * </dl>
17607 *
17608 * @param timeout
17609 * maximum duration between emitted items before a timeout occurs
17610 * @param unit
17611 * the unit of time that applies to the {@code timeout} argument.
17612 * @return the new {@code Flowable} instance
17613 * @throws NullPointerException if {@code unit} is {@code null}
17614 * @see <a href="http://reactivex.io/documentation/operators/timeout.html">ReactiveX operators documentation: Timeout</a>
17615 */
17616 @CheckReturnValue
17617 @BackpressureSupport(BackpressureKind.PASS_THROUGH)
17618 @SchedulerSupport(SchedulerSupport.COMPUTATION)
17619 @NonNull
17620 public final Flowable<T> timeout(long timeout, @NonNull TimeUnit unit) {
17621 return timeout0(timeout, unit, null, Schedulers.computation());
17622 }
17623
17624 /**
17625 * Returns a {@code Flowable} that mirrors the current {@code Flowable} but applies a timeout policy for each emitted
17626 * item. If the next item isn't emitted within the specified timeout duration starting from its predecessor,
17627 * the current {@code Flowable} is disposed and the resulting {@code Flowable} begins instead to mirror a fallback {@link Publisher}.
17628 * <p>
17629 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/timeout.2.v3.png" alt="">
17630 * <dl>
17631 * <dt><b>Backpressure:</b></dt>
17632 * <dd>The operator honors backpressure from downstream. The {@code Publisher}
17633 * sources are expected to honor backpressure as well.
17634 * If any of the current {@code Flowable}s violate this, it <em>may</em> throw an
17635 * {@link IllegalStateException} when the current {@code Flowable} completes.</dd>
17636 * <dt><b>Scheduler:</b></dt>
17637 * <dd>This version of {@code timeout} operates by default on the {@code computation} {@link Scheduler}.</dd>
17638 * </dl>
17639 *
17640 * @param timeout
17641 * maximum duration between items before a timeout occurs
17642 * @param unit
17643 * the unit of time that applies to the {@code timeout} argument
17644 * @param fallback
17645 * the fallback {@code Publisher} to use in case of a timeout
17646 * @return the new {@code Flowable} instance
17647 * @throws NullPointerException if {@code unit} or {@code fallback} is {@code null}
17648 * @see <a href="http://reactivex.io/documentation/operators/timeout.html">ReactiveX operators documentation: Timeout</a>
17649 */
17650 @CheckReturnValue
17651 @NonNull
17652 @BackpressureSupport(BackpressureKind.FULL)
17653 @SchedulerSupport(SchedulerSupport.COMPUTATION)
17654 public final Flowable<T> timeout(long timeout, @NonNull TimeUnit unit, @NonNull Publisher<? extends T> fallback) {
17655 Objects.requireNonNull(fallback, "fallback is null");
17656 return timeout0(timeout, unit, fallback, Schedulers.computation());
17657 }
17658
17659 /**
17660 * Returns a {@code Flowable} that mirrors the current {@code Flowable} but applies a timeout policy for each emitted
17661 * item using a specified {@link Scheduler}. If the next item isn't emitted within the specified timeout duration
17662 * starting from its predecessor, the current {@code Flowable} is disposed and the resulting {@code Flowable} begins
17663 * instead to mirror a fallback {@link Publisher}.
17664 * <p>
17665 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/timeout.2s.v3.png" alt="">
17666 * <dl>
17667 * <dt><b>Backpressure:</b></dt>
17668 * <dd>The operator honors backpressure from downstream. The {@code Publisher}
17669 * sources are expected to honor backpressure as well.
17670 * If any of the current {@code Flowable}s violate this, it <em>may</em> throw an
17671 * {@link IllegalStateException} when the current {@code Flowable} completes.</dd>
17672 * <dt><b>Scheduler:</b></dt>
17673 * <dd>You specify which {@code Scheduler} this operator will use.</dd>
17674 * </dl>
17675 *
17676 * @param timeout
17677 * maximum duration between items before a timeout occurs
17678 * @param unit
17679 * the unit of time that applies to the {@code timeout} argument
17680 * @param scheduler
17681 * the {@code Scheduler} to run the timeout timers on
17682 * @param fallback
17683 * the {@code Publisher} to use as the fallback in case of a timeout
17684 * @return the new {@code Flowable} instance
17685 * @throws NullPointerException if {@code unit}, {@code scheduler} or {@code fallback} is {@code null}
17686 * @see <a href="http://reactivex.io/documentation/operators/timeout.html">ReactiveX operators documentation: Timeout</a>
17687 */
17688 @CheckReturnValue
17689 @NonNull
17690 @BackpressureSupport(BackpressureKind.FULL)
17691 @SchedulerSupport(SchedulerSupport.CUSTOM)
17692 public final Flowable<T> timeout(long timeout, @NonNull TimeUnit unit, @NonNull Scheduler scheduler, @NonNull Publisher<? extends T> fallback) {
17693 Objects.requireNonNull(fallback, "fallback is null");
17694 return timeout0(timeout, unit, fallback, scheduler);
17695 }
17696
17697 /**
17698 * Returns a {@code Flowable} that mirrors the current {@code Flowable} but applies a timeout policy for each emitted
17699 * item, where this policy is governed by a specified {@link Scheduler}. If the next item isn't emitted within the
17700 * specified timeout duration starting from its predecessor, the resulting {@code Flowable} terminates and
17701 * notifies {@link Subscriber}s of a {@link TimeoutException}.
17702 * <p>
17703 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/timeout.1s.v3.png" alt="">
17704 * <dl>
17705 * <dt><b>Backpressure:</b></dt>
17706 * <dd>The operator doesn't interfere with backpressure which is determined by the current {@code Flowable}'s backpressure
17707 * behavior.</dd>
17708 * <dt><b>Scheduler:</b></dt>
17709 * <dd>You specify which {@code Scheduler} this operator will use.</dd>
17710 * </dl>
17711 *
17712 * @param timeout
17713 * maximum duration between items before a timeout occurs
17714 * @param unit
17715 * the unit of time that applies to the {@code timeout} argument
17716 * @param scheduler
17717 * the {@code Scheduler} to run the timeout timers on
17718 * @return the new {@code Flowable} instance
17719 * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null}
17720 * @see <a href="http://reactivex.io/documentation/operators/timeout.html">ReactiveX operators documentation: Timeout</a>
17721 */
17722 @CheckReturnValue
17723 @BackpressureSupport(BackpressureKind.PASS_THROUGH)
17724 @SchedulerSupport(SchedulerSupport.CUSTOM)
17725 @NonNull
17726 public final Flowable<T> timeout(long timeout, @NonNull TimeUnit unit, @NonNull Scheduler scheduler) {
17727 return timeout0(timeout, unit, null, scheduler);
17728 }
17729
17730 /**
17731 * Returns a {@code Flowable} that mirrors the current {@code Flowable}, but notifies {@link Subscriber}s of a
17732 * {@link TimeoutException} if either the first item emitted by the current {@code Flowable} or any subsequent item
17733 * doesn't arrive within time windows defined by other {@link Publisher}s.
17734 * <p>
17735 * <img width="640" height="400" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/timeout5.v3.png" alt="">
17736 * <dl>
17737 * <dt><b>Backpressure:</b></dt>
17738 * <dd>The operator honors backpressure from downstream. Both this and the returned {@code Publisher}s
17739 * are expected to honor backpressure as well. If any of then violates this rule, it <em>may</em> throw an
17740 * {@link IllegalStateException} when the {@code Publisher} completes.</dd>
17741 * <dt><b>Scheduler:</b></dt>
17742 * <dd>{@code timeout} does not operate by default on any {@link Scheduler}.</dd>
17743 * </dl>
17744 *
17745 * @param <U>
17746 * the first timeout value type (ignored)
17747 * @param <V>
17748 * the subsequent timeout value type (ignored)
17749 * @param firstTimeoutIndicator
17750 * a function that returns a {@code Publisher} that determines the timeout window for the first source
17751 * item
17752 * @param itemTimeoutIndicator
17753 * a function that returns a {@code Publisher} for each item emitted by the current {@code Flowable} and that
17754 * determines the timeout window in which the subsequent source item must arrive in order to
17755 * continue the sequence
17756 * @return the new {@code Flowable} instance
17757 * @throws NullPointerException if {@code firstTimeoutIndicator} or {@code itemTimeoutIndicator} is {@code null}
17758 * @see <a href="http://reactivex.io/documentation/operators/timeout.html">ReactiveX operators documentation: Timeout</a>
17759 */
17760 @CheckReturnValue
17761 @NonNull
17762 @BackpressureSupport(BackpressureKind.PASS_THROUGH)
17763 @SchedulerSupport(SchedulerSupport.NONE)
17764 public final <@NonNull U, @NonNull V> Flowable<T> timeout(@NonNull Publisher<U> firstTimeoutIndicator,
17765 @NonNull Function<? super T, @NonNull ? extends Publisher<V>> itemTimeoutIndicator) {
17766 Objects.requireNonNull(firstTimeoutIndicator, "firstTimeoutIndicator is null");
17767 return timeout0(firstTimeoutIndicator, itemTimeoutIndicator, null);
17768 }
17769
17770 /**
17771 * Returns a {@code Flowable} that mirrors the current {@code Flowable}, but switches to a fallback {@link Publisher} if either
17772 * the first item emitted by the current {@code Flowable} or any subsequent item doesn't arrive within time windows
17773 * defined by other {@code Publisher}s.
17774 * <p>
17775 * <img width="640" height="400" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/timeout6.v3.png" alt="">
17776 * <dl>
17777 * <dt><b>Backpressure:</b></dt>
17778 * <dd>The operator honors backpressure from downstream. The {@code Publisher}
17779 * sources are expected to honor backpressure as well.
17780 * If any of the current {@code Flowable}s violate this, it <em>may</em> throw an
17781 * {@link IllegalStateException} when the current {@code Flowable} completes.</dd>
17782 * <dt><b>Scheduler:</b></dt>
17783 * <dd>{@code timeout} does not operate by default on any {@link Scheduler}.</dd>
17784 * </dl>
17785 *
17786 * @param <U>
17787 * the first timeout value type (ignored)
17788 * @param <V>
17789 * the subsequent timeout value type (ignored)
17790 * @param firstTimeoutIndicator
17791 * a function that returns a {@code Publisher} which determines the timeout window for the first source
17792 * item
17793 * @param itemTimeoutIndicator
17794 * a function that returns a {@code Publisher} for each item emitted by the current {@code Flowable} and that
17795 * determines the timeout window in which the subsequent source item must arrive in order to
17796 * continue the sequence
17797 * @param fallback
17798 * the fallback {@code Publisher} to switch to if the current {@code Flowable} times out
17799 * @return the new {@code Flowable} instance
17800 * @throws NullPointerException if {@code firstTimeoutIndicator}, {@code itemTimeoutIndicator} or {@code fallback} is {@code null}
17801 * @see <a href="http://reactivex.io/documentation/operators/timeout.html">ReactiveX operators documentation: Timeout</a>
17802 */
17803 @CheckReturnValue
17804 @NonNull
17805 @BackpressureSupport(BackpressureKind.FULL)
17806 @SchedulerSupport(SchedulerSupport.NONE)
17807 public final <@NonNull U, @NonNull V> Flowable<T> timeout(
17808 @NonNull Publisher<U> firstTimeoutIndicator,
17809 @NonNull Function<? super T, @NonNull ? extends Publisher<V>> itemTimeoutIndicator,
17810 @NonNull Publisher<? extends T> fallback) {
17811 Objects.requireNonNull(firstTimeoutIndicator, "firstTimeoutIndicator is null");
17812 Objects.requireNonNull(fallback, "fallback is null");
17813 return timeout0(firstTimeoutIndicator, itemTimeoutIndicator, fallback);
17814 }
17815
17816 private Flowable<T> timeout0(long timeout, TimeUnit unit, Publisher<? extends T> fallback,
17817 Scheduler scheduler) {
17818 Objects.requireNonNull(unit, "unit is null");
17819 Objects.requireNonNull(scheduler, "scheduler is null");
17820 return RxJavaPlugins.onAssembly(new FlowableTimeoutTimed<>(this, timeout, unit, scheduler, fallback));
17821 }
17822
17823 private <@NonNull U, @NonNull V> Flowable<T> timeout0(
17824 Publisher<U> firstTimeoutIndicator,
17825 Function<? super T, @NonNull ? extends Publisher<V>> itemTimeoutIndicator,
17826 Publisher<? extends T> fallback) {
17827 Objects.requireNonNull(itemTimeoutIndicator, "itemTimeoutIndicator is null");
17828 return RxJavaPlugins.onAssembly(new FlowableTimeout<>(this, firstTimeoutIndicator, itemTimeoutIndicator, fallback));
17829 }
17830
17831 /**
17832 * Returns a {@code Flowable} that emits each item emitted by the current {@code Flowable}, wrapped in a
17833 * {@link Timed} object.
17834 * <p>
17835 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/timestamp.v3.png" alt="">
17836 * <dl>
17837 * <dt><b>Backpressure:</b></dt>
17838 * <dd>The operator doesn't interfere with backpressure which is determined by the current {@code Flowable}'s backpressure
17839 * behavior.</dd>
17840 * <dt><b>Scheduler:</b></dt>
17841 * <dd>{@code timestamp} does not operate on any particular scheduler but uses the current time
17842 * from the {@code computation} {@link Scheduler}.</dd>
17843 * </dl>
17844 *
17845 * @return the new {@code Flowable} instance
17846 * @see <a href="http://reactivex.io/documentation/operators/timestamp.html">ReactiveX operators documentation: Timestamp</a>
17847 */
17848 @CheckReturnValue
17849 @BackpressureSupport(BackpressureKind.PASS_THROUGH)
17850 @SchedulerSupport(SchedulerSupport.NONE)
17851 @NonNull
17852 public final Flowable<Timed<T>> timestamp() {
17853 return timestamp(TimeUnit.MILLISECONDS, Schedulers.computation());
17854 }
17855
17856 /**
17857 * Returns a {@code Flowable} that emits each item emitted by the current {@code Flowable}, wrapped in a
17858 * {@link Timed} object whose timestamps are provided by a specified {@link Scheduler}.
17859 * <p>
17860 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/timestamp.s.v3.png" alt="">
17861 * <dl>
17862 * <dt><b>Backpressure:</b></dt>
17863 * <dd>The operator doesn't interfere with backpressure which is determined by the current {@code Flowable}'s backpressure
17864 * behavior.</dd>
17865 * <dt><b>Scheduler:</b></dt>
17866 * <dd>This operator does not operate on any particular scheduler but uses the current time
17867 * from the specified {@code Scheduler}.</dd>
17868 * </dl>
17869 *
17870 * @param scheduler
17871 * the {@code Scheduler} to use as a time source
17872 * @return the new {@code Flowable} instance
17873 * @throws NullPointerException if {@code scheduler} is {@code null}
17874 * @see <a href="http://reactivex.io/documentation/operators/timestamp.html">ReactiveX operators documentation: Timestamp</a>
17875 */
17876 @CheckReturnValue
17877 @BackpressureSupport(BackpressureKind.PASS_THROUGH)
17878 @SchedulerSupport(SchedulerSupport.NONE) // Supplied scheduler is only used for creating timestamps.
17879 @NonNull
17880 public final Flowable<Timed<T>> timestamp(@NonNull Scheduler scheduler) {
17881 return timestamp(TimeUnit.MILLISECONDS, scheduler);
17882 }
17883
17884 /**
17885 * Returns a {@code Flowable} that emits each item emitted by the current {@code Flowable}, wrapped in a
17886 * {@link Timed} object.
17887 * <p>
17888 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/timestamp.v3.png" alt="">
17889 * <dl>
17890 * <dt><b>Backpressure:</b></dt>
17891 * <dd>The operator doesn't interfere with backpressure which is determined by the current {@code Flowable}'s backpressure
17892 * behavior.</dd>
17893 * <dt><b>Scheduler:</b></dt>
17894 * <dd>{@code timestamp} does not operate on any particular scheduler but uses the current time
17895 * from the {@code computation} {@link Scheduler}.</dd>
17896 * </dl>
17897 *
17898 * @param unit the time unit for the current time
17899 * @return the new {@code Flowable} instance
17900 * @throws NullPointerException if {@code unit} is {@code null}
17901 * @see <a href="http://reactivex.io/documentation/operators/timestamp.html">ReactiveX operators documentation: Timestamp</a>
17902 */
17903 @CheckReturnValue
17904 @BackpressureSupport(BackpressureKind.PASS_THROUGH)
17905 @SchedulerSupport(SchedulerSupport.NONE)
17906 @NonNull
17907 public final Flowable<Timed<T>> timestamp(@NonNull TimeUnit unit) {
17908 return timestamp(unit, Schedulers.computation());
17909 }
17910
17911 /**
17912 * Returns a {@code Flowable} that emits each item emitted by the current {@code Flowable}, wrapped in a
17913 * {@link Timed} object whose timestamps are provided by a specified {@link Scheduler}.
17914 * <p>
17915 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/timestamp.s.v3.png" alt="">
17916 * <dl>
17917 * <dt><b>Backpressure:</b></dt>
17918 * <dd>The operator doesn't interfere with backpressure which is determined by the current {@code Flowable}'s backpressure
17919 * behavior.</dd>
17920 * <dt><b>Scheduler:</b></dt>
17921 * <dd>This operator does not operate on any particular scheduler but uses the current time
17922 * from the specified {@code Scheduler}.</dd>
17923 * </dl>
17924 *
17925 * @param unit the time unit for the current time
17926 * @param scheduler
17927 * the {@code Scheduler} to use as a time source
17928 * @return the new {@code Flowable} instance
17929 * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null}
17930 * @see <a href="http://reactivex.io/documentation/operators/timestamp.html">ReactiveX operators documentation: Timestamp</a>
17931 */
17932 @CheckReturnValue
17933 @NonNull
17934 @BackpressureSupport(BackpressureKind.PASS_THROUGH)
17935 @SchedulerSupport(SchedulerSupport.NONE) // Supplied scheduler is only used for creating timestamps.
17936 public final Flowable<Timed<T>> timestamp(@NonNull TimeUnit unit, @NonNull Scheduler scheduler) {
17937 Objects.requireNonNull(unit, "unit is null");
17938 Objects.requireNonNull(scheduler, "scheduler is null");
17939 return map(Functions.timestampWith(unit, scheduler));
17940 }
17941
17942 /**
17943 * Calls the specified converter function during assembly time and returns its resulting value.
17944 * <p>
17945 * This allows fluent conversion to any other type.
17946 * <dl>
17947 * <dt><b>Backpressure:</b></dt>
17948 * <dd>The backpressure behavior depends on what happens in the {@code converter} function.</dd>
17949 * <dt><b>Scheduler:</b></dt>
17950 * <dd>{@code to} does not operate by default on a particular {@link Scheduler}.</dd>
17951 * </dl>
17952 * <p>History: 2.1.7 - experimental
17953 * @param <R> the resulting object type
17954 * @param converter the function that receives the current {@code Flowable} instance and returns a value
17955 * @return the converted value
17956 * @throws NullPointerException if {@code converter} is {@code null}
17957 * @since 2.2
17958 */
17959 @CheckReturnValue
17960 @BackpressureSupport(BackpressureKind.SPECIAL)
17961 @SchedulerSupport(SchedulerSupport.NONE)
17962 public final <@NonNull R> R to(@NonNull FlowableConverter<T, ? extends R> converter) {
17963 return Objects.requireNonNull(converter, "converter is null").apply(this);
17964 }
17965
17966 /**
17967 * Returns a {@link Single} that emits a single item, a list composed of all the items emitted by the
17968 * finite upstream source {@link Publisher}.
17969 * <p>
17970 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/toList.v3.png" alt="">
17971 * <p>
17972 * Normally, a {@code Publisher} that returns multiple items will do so by invoking its {@link Subscriber}'s
17973 * {@link Subscriber#onNext onNext} method for each such item. You can change this behavior by having the
17974 * operator compose a list of all of these items and then to invoke the {@link SingleObserver}'s {@code onSuccess}
17975 * method once, passing it the entire list, by calling the {@code Flowable}'s {@code toList} method prior to
17976 * calling its {@link #subscribe} method.
17977 * <p>
17978 * Note that this operator requires the upstream to signal {@code onComplete} for the accumulated list to
17979 * be emitted. Sources that are infinite and never complete will never emit anything through this
17980 * operator and an infinite source may lead to a fatal {@link OutOfMemoryError}.
17981 * <dl>
17982 * <dt><b>Backpressure:</b></dt>
17983 * <dd>The operator honors backpressure from downstream and consumes the current {@code Flowable} in an
17984 * unbounded manner (i.e., without applying backpressure to it).</dd>
17985 * <dt><b>Scheduler:</b></dt>
17986 * <dd>{@code toList} does not operate by default on a particular {@link Scheduler}.</dd>
17987 * </dl>
17988 *
17989 * @return the new {@code Single} instance
17990 * @see <a href="http://reactivex.io/documentation/operators/to.html">ReactiveX operators documentation: To</a>
17991 */
17992 @CheckReturnValue
17993 @BackpressureSupport(BackpressureKind.UNBOUNDED_IN)
17994 @SchedulerSupport(SchedulerSupport.NONE)
17995 @NonNull
17996 public final Single<List<T>> toList() {
17997 return RxJavaPlugins.onAssembly(new FlowableToListSingle<>(this));
17998 }
17999
18000 /**
18001 * Returns a {@link Single} that emits a single item, a list composed of all the items emitted by the
18002 * finite source {@link Publisher}.
18003 * <p>
18004 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/toList.v3.png" alt="">
18005 * <p>
18006 * Normally, a {@code Publisher} that returns multiple items will do so by invoking its {@link Subscriber}'s
18007 * {@link Subscriber#onNext onNext} method for each such item. You can change this behavior by having the
18008 * operator compose a list of all of these items and then to invoke the {@link SingleObserver}'s {@code onSuccess}
18009 * method once, passing it the entire list, by calling the {@code Flowable}'s {@code toList} method prior to
18010 * calling its {@link #subscribe} method.
18011 * <p>
18012 * Note that this operator requires the upstream to signal {@code onComplete} for the accumulated list to
18013 * be emitted. Sources that are infinite and never complete will never emit anything through this
18014 * operator and an infinite source may lead to a fatal {@link OutOfMemoryError}.
18015 * <dl>
18016 * <dt><b>Backpressure:</b></dt>
18017 * <dd>The operator honors backpressure from downstream and consumes the current {@code Flowable} in an
18018 * unbounded manner (i.e., without applying backpressure to it).</dd>
18019 * <dt><b>Scheduler:</b></dt>
18020 * <dd>{@code toList} does not operate by default on a particular {@link Scheduler}.</dd>
18021 * </dl>
18022 *
18023 * @param capacityHint
18024 * the number of elements expected from the current {@code Flowable}
18025 * @return the new {@code Single} instance
18026 * @throws IllegalArgumentException if {@code capacityHint} is non-positive
18027 * @see <a href="http://reactivex.io/documentation/operators/to.html">ReactiveX operators documentation: To</a>
18028 */
18029 @CheckReturnValue
18030 @BackpressureSupport(BackpressureKind.UNBOUNDED_IN)
18031 @SchedulerSupport(SchedulerSupport.NONE)
18032 @NonNull
18033 public final Single<List<T>> toList(int capacityHint) {
18034 ObjectHelper.verifyPositive(capacityHint, "capacityHint");
18035 return RxJavaPlugins.onAssembly(new FlowableToListSingle<>(this, Functions.createArrayList(capacityHint)));
18036 }
18037
18038 /**
18039 * Returns a {@link Single} that emits a single item, a list composed of all the items emitted by the
18040 * finite source {@link Publisher}.
18041 * <p>
18042 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/toList.v3.png" alt="">
18043 * <p>
18044 * Normally, a {@code Publisher} that returns multiple items will do so by invoking its {@link Subscriber}'s
18045 * {@link Subscriber#onNext onNext} method for each such item. You can change this behavior by having the
18046 * operator compose a collection of all of these items and then to invoke the {@link SingleObserver}'s {@code onSuccess}
18047 * method once, passing it the entire collection, by calling the {@code Flowable}'s {@code toList} method prior to
18048 * calling its {@link #subscribe} method.
18049 * <p>
18050 * Note that this operator requires the upstream to signal {@code onComplete} for the accumulated collection to
18051 * be emitted. Sources that are infinite and never complete will never emit anything through this
18052 * operator and an infinite source may lead to a fatal {@link OutOfMemoryError}.
18053 * <dl>
18054 * <dt><b>Backpressure:</b></dt>
18055 * <dd>The operator honors backpressure from downstream and consumes the current {@code Flowable} in an
18056 * unbounded manner (i.e., without applying backpressure to it).</dd>
18057 * <dt><b>Scheduler:</b></dt>
18058 * <dd>{@code toList} does not operate by default on a particular {@link Scheduler}.</dd>
18059 * </dl>
18060 *
18061 * @param <U> the subclass of a collection of Ts
18062 * @param collectionSupplier
18063 * the {@link Supplier} returning the collection (for each individual {@code Subscriber}) to be filled in
18064 * @return the new {@code Single} instance
18065 * @throws NullPointerException if {@code collectionSupplier} is {@code null}
18066 * @see <a href="http://reactivex.io/documentation/operators/to.html">ReactiveX operators documentation: To</a>
18067 */
18068 @CheckReturnValue
18069 @BackpressureSupport(BackpressureKind.UNBOUNDED_IN)
18070 @SchedulerSupport(SchedulerSupport.NONE)
18071 @NonNull
18072 public final <@NonNull U extends Collection<? super T>> Single<U> toList(@NonNull Supplier<U> collectionSupplier) {
18073 Objects.requireNonNull(collectionSupplier, "collectionSupplier is null");
18074 return RxJavaPlugins.onAssembly(new FlowableToListSingle<>(this, collectionSupplier));
18075 }
18076
18077 /**
18078 * Returns a {@link Single} that emits a single {@link HashMap} containing all items emitted by the finite source {@link Publisher},
18079 * mapped by the keys returned by a specified {@code keySelector} function.
18080 * <p>
18081 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/toMap.v3.png" alt="">
18082 * <p>
18083 * If more than one source item maps to the same key, the {@code HashMap} will contain the latest of those items.
18084 * <p>
18085 * Note that this operator requires the upstream to signal {@code onComplete} for the accumulated map to
18086 * be emitted. Sources that are infinite and never complete will never emit anything through this
18087 * operator and an infinite source may lead to a fatal {@link OutOfMemoryError}.
18088 * <dl>
18089 * <dt><b>Backpressure:</b></dt>
18090 * <dd>The operator honors backpressure from downstream and consumes the current {@code Flowable} in an
18091 * unbounded manner (i.e., without applying backpressure to it).</dd>
18092 * <dt><b>Scheduler:</b></dt>
18093 * <dd>{@code toMap} does not operate by default on a particular {@link Scheduler}.</dd>
18094 * </dl>
18095 *
18096 * @param <K> the key type of the Map
18097 * @param keySelector
18098 * the function that extracts the key from a source item to be used in the {@code HashMap}
18099 * @return the new {@code Single} instance
18100 * @throws NullPointerException if {@code keySelector} is {@code null}
18101 * @see <a href="http://reactivex.io/documentation/operators/to.html">ReactiveX operators documentation: To</a>
18102 */
18103 @CheckReturnValue
18104 @NonNull
18105 @BackpressureSupport(BackpressureKind.UNBOUNDED_IN)
18106 @SchedulerSupport(SchedulerSupport.NONE)
18107 public final <@NonNull K> Single<Map<K, T>> toMap(@NonNull Function<? super T, ? extends K> keySelector) {
18108 Objects.requireNonNull(keySelector, "keySelector is null");
18109 return collect(HashMapSupplier.asSupplier(), Functions.toMapKeySelector(keySelector));
18110 }
18111
18112 /**
18113 * Returns a {@link Single} that emits a single {@link HashMap} containing values corresponding to items emitted by the
18114 * finite source {@link Publisher}, mapped by the keys returned by a specified {@code keySelector} function.
18115 * <p>
18116 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/toMap.v3.png" alt="">
18117 * <p>
18118 * If more than one source item maps to the same key, the {@code HashMap} will contain a single entry that
18119 * corresponds to the latest of those items.
18120 * <p>
18121 * Note that this operator requires the upstream to signal {@code onComplete} for the accumulated map to
18122 * be emitted. Sources that are infinite and never complete will never emit anything through this
18123 * operator and an infinite source may lead to a fatal {@link OutOfMemoryError}.
18124 * <dl>
18125 * <dt><b>Backpressure:</b></dt>
18126 * <dd>The operator honors backpressure from downstream and consumes the current {@code Flowable} in an
18127 * unbounded manner (i.e., without applying backpressure to it).</dd>
18128 * <dt><b>Scheduler:</b></dt>
18129 * <dd>{@code toMap} does not operate by default on a particular {@link Scheduler}.</dd>
18130 * </dl>
18131 *
18132 * @param <K> the key type of the Map
18133 * @param <V> the value type of the Map
18134 * @param keySelector
18135 * the function that extracts the key from a source item to be used in the {@code HashMap}
18136 * @param valueSelector
18137 * the function that extracts the value from a source item to be used in the {@code HashMap}
18138 * @return the new {@code Single} instance
18139 * @throws NullPointerException if {@code keySelector} or {@code valueSelector} is {@code null}
18140 * @see <a href="http://reactivex.io/documentation/operators/to.html">ReactiveX operators documentation: To</a>
18141 */
18142 @CheckReturnValue
18143 @NonNull
18144 @BackpressureSupport(BackpressureKind.UNBOUNDED_IN)
18145 @SchedulerSupport(SchedulerSupport.NONE)
18146 public final <@NonNull K, @NonNull V> Single<Map<K, V>> toMap(@NonNull Function<? super T, ? extends K> keySelector, @NonNull Function<? super T, ? extends V> valueSelector) {
18147 Objects.requireNonNull(keySelector, "keySelector is null");
18148 Objects.requireNonNull(valueSelector, "valueSelector is null");
18149 return collect(HashMapSupplier.asSupplier(), Functions.toMapKeyValueSelector(keySelector, valueSelector));
18150 }
18151
18152 /**
18153 * Returns a {@link Single} that emits a single {@link Map}, returned by a specified {@code mapFactory} function, that
18154 * contains keys and values extracted from the items emitted by the finite source {@link Publisher}.
18155 * <p>
18156 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/toMap.v3.png" alt="">
18157 * <p>
18158 * Note that this operator requires the upstream to signal {@code onComplete} for the accumulated map to
18159 * be emitted. Sources that are infinite and never complete will never emit anything through this
18160 * operator and an infinite source may lead to a fatal {@link OutOfMemoryError}.
18161 * <dl>
18162 * <dt><b>Backpressure:</b></dt>
18163 * <dd>The operator honors backpressure from downstream and consumes the current {@code Flowable} in an
18164 * unbounded manner (i.e., without applying backpressure to it).</dd>
18165 * <dt><b>Scheduler:</b></dt>
18166 * <dd>{@code toMap} does not operate by default on a particular {@link Scheduler}.</dd>
18167 * </dl>
18168 *
18169 * @param <K> the key type of the Map
18170 * @param <V> the value type of the Map
18171 * @param keySelector
18172 * the function that extracts the key from a source item to be used in the Map
18173 * @param valueSelector
18174 * the function that extracts the value from the source items to be used as value in the Map
18175 * @param mapSupplier
18176 * the function that returns a {@code Map} instance to be used
18177 * @return the new {@code Single} instance
18178 * @throws NullPointerException if {@code keySelector}, {@code valueSelector} or {@code mapSupplier} is {@code null}
18179 * @see <a href="http://reactivex.io/documentation/operators/to.html">ReactiveX operators documentation: To</a>
18180 */
18181 @CheckReturnValue
18182 @NonNull
18183 @BackpressureSupport(BackpressureKind.UNBOUNDED_IN)
18184 @SchedulerSupport(SchedulerSupport.NONE)
18185 public final <@NonNull K, @NonNull V> Single<Map<K, V>> toMap(@NonNull Function<? super T, ? extends K> keySelector,
18186 @NonNull Function<? super T, ? extends V> valueSelector,
18187 @NonNull Supplier<? extends Map<K, V>> mapSupplier) {
18188 Objects.requireNonNull(keySelector, "keySelector is null");
18189 Objects.requireNonNull(valueSelector, "valueSelector is null");
18190 return collect(mapSupplier, Functions.toMapKeyValueSelector(keySelector, valueSelector));
18191 }
18192
18193 /**
18194 * Returns a {@link Single} that emits a single {@link HashMap} that contains an {@link ArrayList} of items emitted by the
18195 * finite source {@link Publisher} keyed by a specified {@code keySelector} function.
18196 * <p>
18197 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/toMultiMap.v3.png" alt="">
18198 * <p>
18199 * Note that this operator requires the upstream to signal {@code onComplete} for the accumulated map to
18200 * be emitted. Sources that are infinite and never complete will never emit anything through this
18201 * operator and an infinite source may lead to a fatal {@link OutOfMemoryError}.
18202 * <dl>
18203 * <dt><b>Backpressure:</b></dt>
18204 * <dd>This operator does not support backpressure as by intent it is requesting and buffering everything.</dd>
18205 * <dt><b>Scheduler:</b></dt>
18206 * <dd>{@code toMultimap} does not operate by default on a particular {@link Scheduler}.</dd>
18207 * </dl>
18208 *
18209 * @param <K> the key type of the Map
18210 * @param keySelector
18211 * the function that extracts the key from the source items to be used as key in the {@code HashMap}
18212 * @return the new {@code Single} instance
18213 * @throws NullPointerException if {@code keySelector} is {@code null}
18214 * @see <a href="http://reactivex.io/documentation/operators/to.html">ReactiveX operators documentation: To</a>
18215 */
18216 @CheckReturnValue
18217 @BackpressureSupport(BackpressureKind.UNBOUNDED_IN)
18218 @SchedulerSupport(SchedulerSupport.NONE)
18219 @NonNull
18220 public final <@NonNull K> Single<Map<K, Collection<T>>> toMultimap(@NonNull Function<? super T, ? extends K> keySelector) {
18221 Function<T, T> valueSelector = Functions.identity();
18222 Supplier<Map<K, Collection<T>>> mapSupplier = HashMapSupplier.asSupplier();
18223 Function<K, List<T>> collectionFactory = ArrayListSupplier.asFunction();
18224 return toMultimap(keySelector, valueSelector, mapSupplier, collectionFactory);
18225 }
18226
18227 /**
18228 * Returns a {@link Single} that emits a single {@link HashMap} that contains an {@link ArrayList} of values extracted by a
18229 * specified {@code valueSelector} function from items emitted by the finite source {@link Publisher}, keyed by a
18230 * specified {@code keySelector} function.
18231 * <p>
18232 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/toMultiMap.v3.png" alt="">
18233 * <p>
18234 * Note that this operator requires the upstream to signal {@code onComplete} for the accumulated map to
18235 * be emitted. Sources that are infinite and never complete will never emit anything through this
18236 * operator and an infinite source may lead to a fatal {@link OutOfMemoryError}.
18237 * <dl>
18238 * <dt><b>Backpressure:</b></dt>
18239 * <dd>The operator honors backpressure from downstream and consumes the current {@code Flowable} in an
18240 * unbounded manner (i.e., without applying backpressure to it).</dd>
18241 * <dt><b>Scheduler:</b></dt>
18242 * <dd>{@code toMultimap} does not operate by default on a particular {@link Scheduler}.</dd>
18243 * </dl>
18244 *
18245 * @param <K> the key type of the Map
18246 * @param <V> the value type of the Map
18247 * @param keySelector
18248 * the function that extracts a key from the source items to be used as key in the {@code HashMap}
18249 * @param valueSelector
18250 * the function that extracts a value from the source items to be used as value in the {@code HashMap}
18251 * @return the new {@code Single} instance
18252 * @throws NullPointerException if {@code keySelector} or {@code valueSelector} is {@code null}
18253 * @see <a href="http://reactivex.io/documentation/operators/to.html">ReactiveX operators documentation: To</a>
18254 */
18255 @CheckReturnValue
18256 @BackpressureSupport(BackpressureKind.UNBOUNDED_IN)
18257 @SchedulerSupport(SchedulerSupport.NONE)
18258 @NonNull
18259 public final <@NonNull K, @NonNull V> Single<Map<K, Collection<V>>> toMultimap(@NonNull Function<? super T, ? extends K> keySelector, @NonNull Function<? super T, ? extends V> valueSelector) {
18260 Supplier<Map<K, Collection<V>>> mapSupplier = HashMapSupplier.asSupplier();
18261 Function<K, List<V>> collectionFactory = ArrayListSupplier.asFunction();
18262 return toMultimap(keySelector, valueSelector, mapSupplier, collectionFactory);
18263 }
18264
18265 /**
18266 * Returns a {@link Single} that emits a single {@link Map}, returned by a specified {@code mapFactory} function, that
18267 * contains a custom collection of values, extracted by a specified {@code valueSelector} function from
18268 * items emitted by the finite source {@link Publisher}, and keyed by the {@code keySelector} function.
18269 * <p>
18270 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/toMultiMap.v3.png" alt="">
18271 * <p>
18272 * Note that this operator requires the upstream to signal {@code onComplete} for the accumulated map to
18273 * be emitted. Sources that are infinite and never complete will never emit anything through this
18274 * operator and an infinite source may lead to a fatal {@link OutOfMemoryError}.
18275 * <dl>
18276 * <dt><b>Backpressure:</b></dt>
18277 * <dd>The operator honors backpressure from downstream and consumes the current {@code Flowable} in an
18278 * unbounded manner (i.e., without applying backpressure to it).</dd>
18279 * <dt><b>Scheduler:</b></dt>
18280 * <dd>{@code toMultimap} does not operate by default on a particular {@link Scheduler}.</dd>
18281 * </dl>
18282 *
18283 * @param <K> the key type of the Map
18284 * @param <V> the value type of the Map
18285 * @param keySelector
18286 * the function that extracts a key from the source items to be used as the key in the Map
18287 * @param valueSelector
18288 * the function that extracts a value from the source items to be used as the value in the {@code Map}
18289 * @param mapSupplier
18290 * the function that returns a Map instance to be used
18291 * @param collectionFactory
18292 * the function that returns a {@link Collection} instance for a particular key to be used in the {@code Map}
18293 * @return the new {@code Single} instance
18294 * @throws NullPointerException if {@code keySelector}, {@code valueSelector}, {@code mapSupplier} or {@code collectionFactory} is {@code null}
18295 * @see <a href="http://reactivex.io/documentation/operators/to.html">ReactiveX operators documentation: To</a>
18296 */
18297 @CheckReturnValue
18298 @NonNull
18299 @BackpressureSupport(BackpressureKind.UNBOUNDED_IN)
18300 @SchedulerSupport(SchedulerSupport.NONE)
18301 public final <@NonNull K, @NonNull V> Single<Map<K, Collection<V>>> toMultimap(
18302 @NonNull Function<? super T, ? extends K> keySelector,
18303 @NonNull Function<? super T, ? extends V> valueSelector,
18304 @NonNull Supplier<? extends Map<K, Collection<V>>> mapSupplier,
18305 @NonNull Function<? super K, ? extends Collection<? super V>> collectionFactory) {
18306 Objects.requireNonNull(keySelector, "keySelector is null");
18307 Objects.requireNonNull(valueSelector, "valueSelector is null");
18308 Objects.requireNonNull(mapSupplier, "mapSupplier is null");
18309 Objects.requireNonNull(collectionFactory, "collectionFactory is null");
18310 return collect(mapSupplier, Functions.toMultimapKeyValueSelector(keySelector, valueSelector, collectionFactory));
18311 }
18312
18313 /**
18314 * Returns a {@link Single} that emits a single {@link Map}, returned by a specified {@code mapFactory} function, that
18315 * contains an {@link ArrayList} of values, extracted by a specified {@code valueSelector} function from items
18316 * emitted by the finite source {@link Publisher} and keyed by the {@code keySelector} function.
18317 * <p>
18318 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/toMultiMap.v3.png" alt="">
18319 * <p>
18320 * Note that this operator requires the upstream to signal {@code onComplete} for the accumulated map to
18321 * be emitted. Sources that are infinite and never complete will never emit anything through this
18322 * operator and an infinite source may lead to a fatal {@link OutOfMemoryError}.
18323 * <dl>
18324 * <dt><b>Backpressure:</b></dt>
18325 * <dd>The operator honors backpressure from downstream and consumes the current {@code Flowable} in an
18326 * unbounded manner (i.e., without applying backpressure to it).</dd>
18327 * <dt><b>Scheduler:</b></dt>
18328 * <dd>{@code toMultimap} does not operate by default on a particular {@link Scheduler}.</dd>
18329 * </dl>
18330 *
18331 * @param <K> the key type of the {@code Map}
18332 * @param <V> the value type of the {@code Map}
18333 * @param keySelector
18334 * the function that extracts a key from the source items to be used as the key in the {@code Map}
18335 * @param valueSelector
18336 * the function that extracts a value from the source items to be used as the value in the {@code Map}
18337 * @param mapSupplier
18338 * the function that returns a {@code Map} instance to be used
18339 * @return the new {@code Single} instance
18340 * @throws NullPointerException if {@code keySelector}, {@code valueSelector} or {@code mapSupplier} is {@code null}
18341 * @see <a href="http://reactivex.io/documentation/operators/to.html">ReactiveX operators documentation: To</a>
18342 */
18343 @CheckReturnValue
18344 @BackpressureSupport(BackpressureKind.UNBOUNDED_IN)
18345 @SchedulerSupport(SchedulerSupport.NONE)
18346 @NonNull
18347 public final <@NonNull K, @NonNull V> Single<Map<K, Collection<V>>> toMultimap(
18348 @NonNull Function<? super T, ? extends K> keySelector,
18349 @NonNull Function<? super T, ? extends V> valueSelector,
18350 @NonNull Supplier<Map<K, Collection<V>>> mapSupplier
18351 ) {
18352 return toMultimap(keySelector, valueSelector, mapSupplier, ArrayListSupplier.asFunction());
18353 }
18354
18355 /**
18356 * Converts the current {@code Flowable} into a non-backpressured {@link Observable}.
18357 * <dl>
18358 * <dt><b>Backpressure:</b></dt>
18359 * <dd>{@code Observable}s don't support backpressure thus the current {@code Flowable} is consumed in an unbounded
18360 * manner (by requesting {@link Long#MAX_VALUE}).</dd>
18361 * <dt><b>Scheduler:</b></dt>
18362 * <dd>{@code toObservable} does not operate by default on a particular {@link Scheduler}.</dd>
18363 * </dl>
18364 * @return the new {@code Observable} instance
18365 * @since 2.0
18366 */
18367 @CheckReturnValue
18368 @BackpressureSupport(BackpressureKind.UNBOUNDED_IN)
18369 @SchedulerSupport(SchedulerSupport.NONE)
18370 @NonNull
18371 public final Observable<T> toObservable() {
18372 return RxJavaPlugins.onAssembly(new ObservableFromPublisher<>(this));
18373 }
18374
18375 /**
18376 * Returns a {@link Single} that emits a {@link List} that contains the items emitted by the finite source {@link Publisher}, in a
18377 * sorted order. Each item emitted by the {@code Publisher} must implement {@link Comparable} with respect to all
18378 * other items in the sequence.
18379 *
18380 * <p>If any item emitted by this {@code Flowable} does not implement {@code Comparable} with respect to
18381 * all other items emitted by this {@code Flowable}, no items will be emitted and the
18382 * sequence is terminated with a {@link ClassCastException}.
18383 * <p>
18384 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/toSortedList.v3.png" alt="">
18385 * <p>
18386 * Note that this operator requires the upstream to signal {@code onComplete} for the accumulated list to
18387 * be emitted. Sources that are infinite and never complete will never emit anything through this
18388 * operator and an infinite source may lead to a fatal {@link OutOfMemoryError}.
18389 * <dl>
18390 * <dt><b>Backpressure:</b></dt>
18391 * <dd>The operator honors backpressure from downstream and consumes the current {@code Flowable} in an
18392 * unbounded manner (i.e., without applying backpressure to it).</dd>
18393 * <dt><b>Scheduler:</b></dt>
18394 * <dd>{@code toSortedList} does not operate by default on a particular {@link Scheduler}.</dd>
18395 * </dl>
18396 * @return the new {@code Single} instance
18397 * @see <a href="http://reactivex.io/documentation/operators/to.html">ReactiveX operators documentation: To</a>
18398 */
18399 @CheckReturnValue
18400 @BackpressureSupport(BackpressureKind.UNBOUNDED_IN)
18401 @SchedulerSupport(SchedulerSupport.NONE)
18402 @NonNull
18403 public final Single<List<T>> toSortedList() {
18404 return toSortedList(Functions.naturalComparator());
18405 }
18406
18407 /**
18408 * Returns a {@link Single} that emits a {@link List} that contains the items emitted by the finite source {@link Publisher}, in a
18409 * sorted order based on a specified comparison function.
18410 * <p>
18411 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/toSortedList.f.v3.png" alt="">
18412 * <p>
18413 * Note that this operator requires the upstream to signal {@code onComplete} for the accumulated list to
18414 * be emitted. Sources that are infinite and never complete will never emit anything through this
18415 * operator and an infinite source may lead to a fatal {@link OutOfMemoryError}.
18416 * <dl>
18417 * <dt><b>Backpressure:</b></dt>
18418 * <dd>The operator honors backpressure from downstream and consumes the current {@code Flowable} in an
18419 * unbounded manner (i.e., without applying backpressure to it).</dd>
18420 * <dt><b>Scheduler:</b></dt>
18421 * <dd>{@code toSortedList} does not operate by default on a particular {@link Scheduler}.</dd>
18422 * </dl>
18423 *
18424 * @param comparator
18425 * a function that compares two items emitted by the current {@code Flowable} and returns an {@code int}
18426 * that indicates their sort order
18427 * @return the new {@code Single} instance
18428 * @throws NullPointerException if {@code comparator} is {@code null}
18429 * @see <a href="http://reactivex.io/documentation/operators/to.html">ReactiveX operators documentation: To</a>
18430 */
18431 @CheckReturnValue
18432 @NonNull
18433 @BackpressureSupport(BackpressureKind.UNBOUNDED_IN)
18434 @SchedulerSupport(SchedulerSupport.NONE)
18435 public final Single<List<T>> toSortedList(@NonNull Comparator<? super T> comparator) {
18436 Objects.requireNonNull(comparator, "comparator is null");
18437 return toList().map(Functions.listSorter(comparator));
18438 }
18439
18440 /**
18441 * Returns a {@link Single} that emits a {@link List} that contains the items emitted by the finite source {@link Publisher}, in a
18442 * sorted order based on a specified comparison function.
18443 * <p>
18444 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/toSortedList.f.v3.png" alt="">
18445 * <p>
18446 * Note that this operator requires the upstream to signal {@code onComplete} for the accumulated list to
18447 * be emitted. Sources that are infinite and never complete will never emit anything through this
18448 * operator and an infinite source may lead to a fatal {@link OutOfMemoryError}.
18449 * <dl>
18450 * <dt><b>Backpressure:</b></dt>
18451 * <dd>The operator honors backpressure from downstream and consumes the current {@code Flowable} in an
18452 * unbounded manner (i.e., without applying backpressure to it).</dd>
18453 * <dt><b>Scheduler:</b></dt>
18454 * <dd>{@code toSortedList} does not operate by default on a particular {@link Scheduler}.</dd>
18455 * </dl>
18456 *
18457 * @param comparator
18458 * a function that compares two items emitted by the current {@code Flowable} and returns an {@code int}
18459 * that indicates their sort order
18460 * @param capacityHint
18461 * the initial capacity of the {@link ArrayList} used to accumulate items before sorting
18462 * @return the new {@code Single} instance
18463 * @throws NullPointerException if {@code comparator} is {@code null}
18464 * @throws IllegalArgumentException if {@code capacityHint} is non-positive
18465 * @see <a href="http://reactivex.io/documentation/operators/to.html">ReactiveX operators documentation: To</a>
18466 * @since 2.0
18467 */
18468 @CheckReturnValue
18469 @NonNull
18470 @BackpressureSupport(BackpressureKind.UNBOUNDED_IN)
18471 @SchedulerSupport(SchedulerSupport.NONE)
18472 public final Single<List<T>> toSortedList(@NonNull Comparator<? super T> comparator, int capacityHint) {
18473 Objects.requireNonNull(comparator, "comparator is null");
18474 return toList(capacityHint).map(Functions.listSorter(comparator));
18475 }
18476
18477 /**
18478 * Returns a {@link Single} that emits a {@link List} that contains the items emitted by the finite source {@link Publisher}, in a
18479 * sorted order. Each item emitted by the {@code Publisher} must implement {@link Comparable} with respect to all
18480 * other items in the sequence.
18481 *
18482 * <p>If any item emitted by this {@code Flowable} does not implement {@code Comparable} with respect to
18483 * all other items emitted by this {@code Flowable}, no items will be emitted and the
18484 * sequence is terminated with a {@link ClassCastException}.
18485 * <p>
18486 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/toSortedList.v3.png" alt="">
18487 * <p>
18488 * Note that this operator requires the upstream to signal {@code onComplete} for the accumulated list to
18489 * be emitted. Sources that are infinite and never complete will never emit anything through this
18490 * operator and an infinite source may lead to a fatal {@link OutOfMemoryError}.
18491 * <dl>
18492 * <dt><b>Backpressure:</b></dt>
18493 * <dd>The operator honors backpressure from downstream and consumes the current {@code Flowable} in an
18494 * unbounded manner (i.e., without applying backpressure to it).</dd>
18495 * <dt><b>Scheduler:</b></dt>
18496 * <dd>{@code toSortedList} does not operate by default on a particular {@link Scheduler}.</dd>
18497 * </dl>
18498 *
18499 * @param capacityHint
18500 * the initial capacity of the {@link ArrayList} used to accumulate items before sorting
18501 * @return the new {@code Single} instance
18502 * @throws IllegalArgumentException if {@code capacityHint} is non-positive
18503 * @see <a href="http://reactivex.io/documentation/operators/to.html">ReactiveX operators documentation: To</a>
18504 * @since 2.0
18505 */
18506 @CheckReturnValue
18507 @BackpressureSupport(BackpressureKind.UNBOUNDED_IN)
18508 @SchedulerSupport(SchedulerSupport.NONE)
18509 @NonNull
18510 public final Single<List<T>> toSortedList(int capacityHint) {
18511 return toSortedList(Functions.naturalComparator(), capacityHint);
18512 }
18513
18514 /**
18515 * Cancels the current {@code Flowable} asynchronously by invoking {@link Subscription#cancel()}
18516 * on the specified {@link Scheduler}.
18517 * <p>
18518 * The operator suppresses signals from the current {@code Flowable} immediately when the
18519 * downstream cancels the flow because the actual cancellation itself could take an arbitrary amount of time
18520 * to take effect and make the flow stop producing items.
18521 * <dl>
18522 * <dt><b>Backpressure:</b></dt>
18523 * <dd>The operator doesn't interfere with backpressure which is determined by the current {@code Flowable}'s backpressure
18524 * behavior.</dd>
18525 * <dt><b>Scheduler:</b></dt>
18526 * <dd>You specify which {@code Scheduler} this operator will use.</dd>
18527 * </dl>
18528 *
18529 * @param scheduler
18530 * the {@code Scheduler} to perform cancellation actions on
18531 * @return the new {@code Flowable} instance
18532 * @throws NullPointerException if {@code scheduler} is {@code null}
18533 * @see <a href="http://reactivex.io/documentation/operators/subscribeon.html">ReactiveX operators documentation: SubscribeOn</a>
18534 */
18535 @CheckReturnValue
18536 @NonNull
18537 @BackpressureSupport(BackpressureKind.PASS_THROUGH)
18538 @SchedulerSupport(SchedulerSupport.CUSTOM)
18539 public final Flowable<T> unsubscribeOn(@NonNull Scheduler scheduler) {
18540 Objects.requireNonNull(scheduler, "scheduler is null");
18541 return RxJavaPlugins.onAssembly(new FlowableUnsubscribeOn<>(this, scheduler));
18542 }
18543
18544 /**
18545 * Returns a {@code Flowable} that emits windows of items it collects from the current {@code Flowable}. The resulting
18546 * {@code Flowable} emits connected, non-overlapping windows, each containing {@code count} items. When the current
18547 * {@code Flowable} completes or encounters an error, the resulting {@code Flowable} emits the current window and
18548 * propagates the notification from the current {@code Flowable}.
18549 * <p>
18550 * <img width="640" height="400" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/window3.v3.png" alt="">
18551 * <p>
18552 * Note that ignoring windows or subscribing later (i.e., on another thread) will result in
18553 * so-called window abandonment where a window will only contain one element. The behavior is
18554 * a trade-off between no-dataloss and ensuring upstream cancellation can happen.
18555 * <dl>
18556 * <dt><b>Backpressure:</b></dt>
18557 * <dd>The operator honors backpressure of its inner and outer subscribers, however, the inner {@code Flowable} uses an
18558 * unbounded buffer that may hold at most {@code count} elements.</dd>
18559 * <dt><b>Scheduler:</b></dt>
18560 * <dd>This version of {@code window} does not operate by default on a particular {@link Scheduler}.</dd>
18561 * </dl>
18562 *
18563 * @param count
18564 * the maximum size of each window before it should be emitted
18565 * @return the new {@code Flowable} instance
18566 * @throws IllegalArgumentException if {@code count} is non-positive
18567 * @see <a href="http://reactivex.io/documentation/operators/window.html">ReactiveX operators documentation: Window</a>
18568 */
18569 @CheckReturnValue
18570 @BackpressureSupport(BackpressureKind.FULL)
18571 @SchedulerSupport(SchedulerSupport.NONE)
18572 @NonNull
18573 public final Flowable<Flowable<T>> window(long count) {
18574 return window(count, count, bufferSize());
18575 }
18576
18577 /**
18578 * Returns a {@code Flowable} that emits windows of items it collects from the current {@code Flowable}. The resulting
18579 * {@code Flowable} emits windows every {@code skip} items, each containing no more than {@code count} items. When
18580 * the current {@code Flowable} completes or encounters an error, the resulting {@code Flowable} emits the current window
18581 * and propagates the notification from the current {@code Flowable}.
18582 * <p>
18583 * <img width="640" height="365" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/window4.v3.png" alt="">
18584 * <p>
18585 * Note that ignoring windows or subscribing later (i.e., on another thread) will result in
18586 * so-called window abandonment where a window may not contain any elements. In this case, subsequent
18587 * elements will be dropped until the condition for the next window boundary is satisfied. The behavior is
18588 * a trade-off between no-dataloss and ensuring upstream cancellation can happen under some race conditions.
18589 * <dl>
18590 * <dt><b>Backpressure:</b></dt>
18591 * <dd>The operator honors backpressure of its inner and outer subscribers, however, the inner {@code Flowable} uses an
18592 * unbounded buffer that may hold at most {@code count} elements.</dd>
18593 * <dt><b>Scheduler:</b></dt>
18594 * <dd>This version of {@code window} does not operate by default on a particular {@link Scheduler}.</dd>
18595 * </dl>
18596 *
18597 * @param count
18598 * the maximum size of each window before it should be emitted
18599 * @param skip
18600 * how many items need to be skipped before starting a new window. Note that if {@code skip} and
18601 * {@code count} are equal this is the same operation as {@link #window(long)}.
18602 * @return the new {@code Flowable} instance
18603 * @throws IllegalArgumentException if {@code count} or {@code skip} is non-positive
18604 * @see <a href="http://reactivex.io/documentation/operators/window.html">ReactiveX operators documentation: Window</a>
18605 */
18606 @CheckReturnValue
18607 @BackpressureSupport(BackpressureKind.FULL)
18608 @SchedulerSupport(SchedulerSupport.NONE)
18609 @NonNull
18610 public final Flowable<Flowable<T>> window(long count, long skip) {
18611 return window(count, skip, bufferSize());
18612 }
18613
18614 /**
18615 * Returns a {@code Flowable} that emits windows of items it collects from the current {@code Flowable}. The resulting
18616 * {@code Flowable} emits windows every {@code skip} items, each containing no more than {@code count} items. When
18617 * the current {@code Flowable} completes or encounters an error, the resulting {@code Flowable} emits the current window
18618 * and propagates the notification from the current {@code Flowable}.
18619 * <p>
18620 * <img width="640" height="365" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/window4.v3.png" alt="">
18621 * <p>
18622 * Note that ignoring windows or subscribing later (i.e., on another thread) will result in
18623 * so-called window abandonment where a window may not contain any elements. In this case, subsequent
18624 * elements will be dropped until the condition for the next window boundary is satisfied. The behavior is
18625 * a trade-off between no-dataloss and ensuring upstream cancellation can happen under some race conditions.
18626 * <dl>
18627 * <dt><b>Backpressure:</b></dt>
18628 * <dd>The operator honors backpressure of its inner and outer subscribers, however, the inner {@code Flowable} uses an
18629 * unbounded buffer that may hold at most {@code count} elements.</dd>
18630 * <dt><b>Scheduler:</b></dt>
18631 * <dd>This version of {@code window} does not operate by default on a particular {@link Scheduler}.</dd>
18632 * </dl>
18633 *
18634 * @param count
18635 * the maximum size of each window before it should be emitted
18636 * @param skip
18637 * how many items need to be skipped before starting a new window. Note that if {@code skip} and
18638 * {@code count} are equal this is the same operation as {@link #window(long)}.
18639 * @param bufferSize
18640 * the capacity hint for the buffer in the inner windows
18641 * @return the new {@code Flowable} instance
18642 * @throws IllegalArgumentException if {@code count}, {@code skip} or {@code bufferSize} is non-positive
18643 * @see <a href="http://reactivex.io/documentation/operators/window.html">ReactiveX operators documentation: Window</a>
18644 */
18645 @CheckReturnValue
18646 @BackpressureSupport(BackpressureKind.FULL)
18647 @SchedulerSupport(SchedulerSupport.NONE)
18648 @NonNull
18649 public final Flowable<Flowable<T>> window(long count, long skip, int bufferSize) {
18650 ObjectHelper.verifyPositive(skip, "skip");
18651 ObjectHelper.verifyPositive(count, "count");
18652 ObjectHelper.verifyPositive(bufferSize, "bufferSize");
18653 return RxJavaPlugins.onAssembly(new FlowableWindow<>(this, count, skip, bufferSize));
18654 }
18655
18656 /**
18657 * Returns a {@code Flowable} that emits windows of items it collects from the current {@code Flowable}. The resulting
18658 * {@code Flowable} starts a new window periodically, as determined by the {@code timeskip} argument. It emits
18659 * each window after a fixed timespan, specified by the {@code timespan} argument. When the current
18660 * {@code Flowable} completes or encounters an error, the resulting {@code Flowable} emits the
18661 * current window and propagates the notification from the current {@code Flowable}.
18662 * <p>
18663 * <img width="640" height="335" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/window7.v3.png" alt="">
18664 * <p>
18665 * Note that ignoring windows or subscribing later (i.e., on another thread) will result in
18666 * so-called window abandonment where a window may not contain any elements. In this case, subsequent
18667 * elements will be dropped until the condition for the next window boundary is satisfied. The behavior is
18668 * a trade-off for ensuring upstream cancellation can happen under some race conditions.
18669 * <dl>
18670 * <dt><b>Backpressure:</b></dt>
18671 * <dd>The operator consumes the current {@code Flowable} in an unbounded manner.
18672 * The resulting {@code Flowable} doesn't support backpressure as it uses
18673 * time to control the creation of windows. The emitted inner {@code Flowable}s honor
18674 * backpressure but have an unbounded inner buffer that <em>may</em> lead to {@link OutOfMemoryError}
18675 * if left unconsumed.</dd>
18676 * <dt><b>Scheduler:</b></dt>
18677 * <dd>This version of {@code window} operates by default on the {@code computation} {@link Scheduler}.</dd>
18678 * </dl>
18679 *
18680 * @param timespan
18681 * the period of time each window collects items before it should be emitted
18682 * @param timeskip
18683 * the period of time after which a new window will be created
18684 * @param unit
18685 * the unit of time that applies to the {@code timespan} and {@code timeskip} arguments
18686 * @return the new {@code Flowable} instance
18687 * @throws NullPointerException if {@code unit} is {@code null}
18688 * @see <a href="http://reactivex.io/documentation/operators/window.html">ReactiveX operators documentation: Window</a>
18689 */
18690 @CheckReturnValue
18691 @BackpressureSupport(BackpressureKind.ERROR)
18692 @SchedulerSupport(SchedulerSupport.COMPUTATION)
18693 @NonNull
18694 public final Flowable<Flowable<T>> window(long timespan, long timeskip, @NonNull TimeUnit unit) {
18695 return window(timespan, timeskip, unit, Schedulers.computation(), bufferSize());
18696 }
18697
18698 /**
18699 * Returns a {@code Flowable} that emits windows of items it collects from the current {@code Flowable}. The resulting
18700 * {@code Flowable} starts a new window periodically, as determined by the {@code timeskip} argument. It emits
18701 * each window after a fixed timespan, specified by the {@code timespan} argument. When the current
18702 * {@code Flowable} completes or encounters an error, the resulting {@code Flowable} emits the
18703 * current window and propagates the notification from the current {@code Flowable}.
18704 * <p>
18705 * <img width="640" height="335" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/window7.s.v3.png" alt="">
18706 * <p>
18707 * Note that ignoring windows or subscribing later (i.e., on another thread) will result in
18708 * so-called window abandonment where a window may not contain any elements. In this case, subsequent
18709 * elements will be dropped until the condition for the next window boundary is satisfied. The behavior is
18710 * a trade-off for ensuring upstream cancellation can happen under some race conditions.
18711 * <dl>
18712 * <dt><b>Backpressure:</b></dt>
18713 * <dd>The operator consumes the current {@code Flowable} in an unbounded manner.
18714 * The resulting {@code Flowable} doesn't support backpressure as it uses
18715 * time to control the creation of windows. The returned inner {@code Flowable}s honor
18716 * backpressure but have an unbounded inner buffer that <em>may</em> lead to {@link OutOfMemoryError}
18717 * if left unconsumed.</dd>
18718 * <dt><b>Scheduler:</b></dt>
18719 * <dd>You specify which {@link Scheduler} this operator will use.</dd>
18720 * </dl>
18721 *
18722 * @param timespan
18723 * the period of time each window collects items before it should be emitted
18724 * @param timeskip
18725 * the period of time after which a new window will be created
18726 * @param unit
18727 * the unit of time that applies to the {@code timespan} and {@code timeskip} arguments
18728 * @param scheduler
18729 * the {@code Scheduler} to use when determining the end and start of a window
18730 * @return the new {@code Flowable} instance
18731 * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null}
18732 * @see <a href="http://reactivex.io/documentation/operators/window.html">ReactiveX operators documentation: Window</a>
18733 */
18734 @CheckReturnValue
18735 @BackpressureSupport(BackpressureKind.ERROR)
18736 @SchedulerSupport(SchedulerSupport.CUSTOM)
18737 @NonNull
18738 public final Flowable<Flowable<T>> window(long timespan, long timeskip, @NonNull TimeUnit unit, @NonNull Scheduler scheduler) {
18739 return window(timespan, timeskip, unit, scheduler, bufferSize());
18740 }
18741
18742 /**
18743 * Returns a {@code Flowable} that emits windows of items it collects from the current {@code Flowable}. The resulting
18744 * {@code Flowable} starts a new window periodically, as determined by the {@code timeskip} argument. It emits
18745 * each window after a fixed timespan, specified by the {@code timespan} argument. When the current
18746 * {@code Flowable} completes or encounters an error, the resulting {@code Flowable} emits the
18747 * current window and propagates the notification from the current {@code Flowable}.
18748 * <p>
18749 * <img width="640" height="335" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/window7.s.v3.png" alt="">
18750 * <p>
18751 * Note that ignoring windows or subscribing later (i.e., on another thread) will result in
18752 * so-called window abandonment where a window may not contain any elements. In this case, subsequent
18753 * elements will be dropped until the condition for the next window boundary is satisfied. The behavior is
18754 * a trade-off for ensuring upstream cancellation can happen under some race conditions.
18755 * <dl>
18756 * <dt><b>Backpressure:</b></dt>
18757 * <dd>The operator consumes the current {@code Flowable} in an unbounded manner.
18758 * The resulting {@code Flowable} doesn't support backpressure as it uses
18759 * time to control the creation of windows. The returned inner {@code Flowable}s honor
18760 * backpressure but have an unbounded inner buffer that <em>may</em> lead to {@link OutOfMemoryError}
18761 * if left unconsumed.</dd>
18762 * <dt><b>Scheduler:</b></dt>
18763 * <dd>You specify which {@link Scheduler} this operator will use.</dd>
18764 * </dl>
18765 *
18766 * @param timespan
18767 * the period of time each window collects items before it should be emitted
18768 * @param timeskip
18769 * the period of time after which a new window will be created
18770 * @param unit
18771 * the unit of time that applies to the {@code timespan} and {@code timeskip} arguments
18772 * @param scheduler
18773 * the {@code Scheduler} to use when determining the end and start of a window
18774 * @param bufferSize
18775 * the capacity hint for the buffer in the inner windows
18776 * @return the new {@code Flowable} instance
18777 * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null}
18778 * @throws IllegalArgumentException if {@code timespan}, {@code timeskip} or {@code bufferSize} is non-positive
18779 * @see <a href="http://reactivex.io/documentation/operators/window.html">ReactiveX operators documentation: Window</a>
18780 */
18781 @CheckReturnValue
18782 @NonNull
18783 @BackpressureSupport(BackpressureKind.ERROR)
18784 @SchedulerSupport(SchedulerSupport.CUSTOM)
18785 public final Flowable<Flowable<T>> window(long timespan, long timeskip, @NonNull TimeUnit unit, @NonNull Scheduler scheduler, int bufferSize) {
18786 ObjectHelper.verifyPositive(bufferSize, "bufferSize");
18787 ObjectHelper.verifyPositive(timespan, "timespan");
18788 ObjectHelper.verifyPositive(timeskip, "timeskip");
18789 Objects.requireNonNull(scheduler, "scheduler is null");
18790 Objects.requireNonNull(unit, "unit is null");
18791 return RxJavaPlugins.onAssembly(new FlowableWindowTimed<>(this, timespan, timeskip, unit, scheduler, Long.MAX_VALUE, bufferSize, false));
18792 }
18793
18794 /**
18795 * Returns a {@code Flowable} that emits windows of items it collects from the current {@code Flowable}. The resulting
18796 * {@code Flowable} emits connected, non-overlapping windows, each of a fixed duration specified by the
18797 * {@code timespan} argument. When the current {@code Flowable} completes or encounters an error, the resulting
18798 * {@code Flowable} emits the current window and propagates the notification from the current {@code Flowable}.
18799 * <p>
18800 * <img width="640" height="375" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/window5.v3.png" alt="">
18801 * <p>
18802 * Note that ignoring windows or subscribing later (i.e., on another thread) will result in
18803 * so-called window abandonment where a window may not contain any elements. In this case, subsequent
18804 * elements will be dropped until the condition for the next window boundary is satisfied. The behavior is
18805 * a trade-off for ensuring upstream cancellation can happen under some race conditions.
18806 * <dl>
18807 * <dt><b>Backpressure:</b></dt>
18808 * <dd>The operator consumes the current {@code Flowable} in an unbounded manner.
18809 * The resulting {@code Flowable} doesn't support backpressure as it uses
18810 * time to control the creation of windows. The emitted inner {@code Flowable}s honor
18811 * backpressure and may hold up to {@code count} elements at most.</dd>
18812 * <dt><b>Scheduler:</b></dt>
18813 * <dd>This version of {@code window} operates by default on the {@code computation} {@link Scheduler}.</dd>
18814 * </dl>
18815 *
18816 * @param timespan
18817 * the period of time each window collects items before it should be emitted and replaced with a
18818 * new window
18819 * @param unit
18820 * the unit of time that applies to the {@code timespan} argument
18821 * @return the new {@code Flowable} instance
18822 * @throws NullPointerException if {@code unit} is {@code null}
18823 * @see <a href="http://reactivex.io/documentation/operators/window.html">ReactiveX operators documentation: Window</a>
18824 */
18825 @CheckReturnValue
18826 @BackpressureSupport(BackpressureKind.ERROR)
18827 @SchedulerSupport(SchedulerSupport.COMPUTATION)
18828 @NonNull
18829 public final Flowable<Flowable<T>> window(long timespan, @NonNull TimeUnit unit) {
18830 return window(timespan, unit, Schedulers.computation(), Long.MAX_VALUE, false);
18831 }
18832
18833 /**
18834 * Returns a {@code Flowable} that emits windows of items it collects from the current {@code Flowable}. The resulting
18835 * {@code Flowable} emits connected, non-overlapping windows, each of a fixed duration as specified by the
18836 * {@code timespan} argument or a maximum size as specified by the {@code count} argument (whichever is
18837 * reached first). When the current {@code Flowable} completes or encounters an error, the resulting {@code Flowable}
18838 * emits the current window and propagates the notification from the current {@code Flowable}.
18839 * <p>
18840 * <img width="640" height="370" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/window6.v3.png" alt="">
18841 * <p>
18842 * Note that ignoring windows or subscribing later (i.e., on another thread) will result in
18843 * so-called window abandonment where a window may not contain any elements. In this case, subsequent
18844 * elements will be dropped until the condition for the next window boundary is satisfied. The behavior is
18845 * a trade-off for ensuring upstream cancellation can happen under some race conditions.
18846 * <dl>
18847 * <dt><b>Backpressure:</b></dt>
18848 * <dd>The operator consumes the current {@code Flowable} in an unbounded manner.
18849 * The resulting {@code Flowable} doesn't support backpressure as it uses
18850 * time to control the creation of windows. The emitted inner {@code Flowable}s honor
18851 * backpressure and may hold up to {@code count} elements at most.</dd>
18852 * <dt><b>Scheduler:</b></dt>
18853 * <dd>This version of {@code window} operates by default on the {@code computation} {@link Scheduler}.</dd>
18854 * </dl>
18855 *
18856 * @param timespan
18857 * the period of time each window collects items before it should be emitted and replaced with a
18858 * new window
18859 * @param unit
18860 * the unit of time that applies to the {@code timespan} argument
18861 * @param count
18862 * the maximum size of each window before it should be emitted
18863 * @return the new {@code Flowable} instance
18864 * @throws NullPointerException if {@code unit} is {@code null}
18865 * @throws IllegalArgumentException if {@code count} is non-positive
18866 * @see <a href="http://reactivex.io/documentation/operators/window.html">ReactiveX operators documentation: Window</a>
18867 */
18868 @CheckReturnValue
18869 @BackpressureSupport(BackpressureKind.ERROR)
18870 @SchedulerSupport(SchedulerSupport.COMPUTATION)
18871 @NonNull
18872 public final Flowable<Flowable<T>> window(long timespan, @NonNull TimeUnit unit,
18873 long count) {
18874 return window(timespan, unit, Schedulers.computation(), count, false);
18875 }
18876
18877 /**
18878 * Returns a {@code Flowable} that emits windows of items it collects from the current {@code Flowable}. The resulting
18879 * {@code Flowable} emits connected, non-overlapping windows, each of a fixed duration as specified by the
18880 * {@code timespan} argument or a maximum size as specified by the {@code count} argument (whichever is
18881 * reached first). When the current {@code Flowable} completes or encounters an error, the resulting {@code Flowable}
18882 * emits the current window and propagates the notification from the current {@code Flowable}.
18883 * <p>
18884 * <img width="640" height="370" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/window6.v3.png" alt="">
18885 * <p>
18886 * Note that ignoring windows or subscribing later (i.e., on another thread) will result in
18887 * so-called window abandonment where a window may not contain any elements. In this case, subsequent
18888 * elements will be dropped until the condition for the next window boundary is satisfied. The behavior is
18889 * a trade-off for ensuring upstream cancellation can happen under some race conditions.
18890 * <dl>
18891 * <dt><b>Backpressure:</b></dt>
18892 * <dd>The operator consumes the current {@code Flowable} in an unbounded manner.
18893 * The resulting {@code Flowable} doesn't support backpressure as it uses
18894 * time to control the creation of windows. The emitted inner {@code Flowable}s honor
18895 * backpressure and may hold up to {@code count} elements at most.</dd>
18896 * <dt><b>Scheduler:</b></dt>
18897 * <dd>This version of {@code window} operates by default on the {@code computation} {@link Scheduler}.</dd>
18898 * </dl>
18899 *
18900 * @param timespan
18901 * the period of time each window collects items before it should be emitted and replaced with a
18902 * new window
18903 * @param unit
18904 * the unit of time that applies to the {@code timespan} argument
18905 * @param count
18906 * the maximum size of each window before it should be emitted
18907 * @param restart
18908 * if {@code true}, when a window reaches the capacity limit, the timer is restarted as well
18909 * @return the new {@code Flowable} instance
18910 * @throws NullPointerException if {@code unit} is {@code null}
18911 * @throws IllegalArgumentException if {@code count} is non-positive
18912 * @see <a href="http://reactivex.io/documentation/operators/window.html">ReactiveX operators documentation: Window</a>
18913 */
18914 @CheckReturnValue
18915 @BackpressureSupport(BackpressureKind.ERROR)
18916 @SchedulerSupport(SchedulerSupport.COMPUTATION)
18917 @NonNull
18918 public final Flowable<Flowable<T>> window(long timespan, @NonNull TimeUnit unit,
18919 long count, boolean restart) {
18920 return window(timespan, unit, Schedulers.computation(), count, restart);
18921 }
18922
18923 /**
18924 * Returns a {@code Flowable} that emits windows of items it collects from the current {@code Flowable}. The resulting
18925 * {@code Flowable} emits connected, non-overlapping windows, each of a fixed duration as specified by the
18926 * {@code timespan} argument. When the current {@code Flowable} completes or encounters an error, the resulting
18927 * {@code Flowable} emits the current window and propagates the notification from the current {@code Flowable}.
18928 * <p>
18929 * <img width="640" height="375" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/window5.s.v3.png" alt="">
18930 * <p>
18931 * Note that ignoring windows or subscribing later (i.e., on another thread) will result in
18932 * so-called window abandonment where a window may not contain any elements. In this case, subsequent
18933 * elements will be dropped until the condition for the next window boundary is satisfied. The behavior is
18934 * a trade-off for ensuring upstream cancellation can happen under some race conditions.
18935 * <dl>
18936 * <dt><b>Backpressure:</b></dt>
18937 * <dd>The operator consumes the current {@code Flowable} in an unbounded manner.
18938 * The resulting {@code Flowable} doesn't support backpressure as it uses
18939 * time to control the creation of windows. The emitted inner {@code Flowable}s honor
18940 * backpressure but have an unbounded inner buffer that <em>may</em> lead to {@link OutOfMemoryError}
18941 * if left unconsumed.</dd>
18942 * <dt><b>Scheduler:</b></dt>
18943 * <dd>You specify which {@link Scheduler} this operator will use.</dd>
18944 * </dl>
18945 *
18946 * @param timespan
18947 * the period of time each window collects items before it should be emitted and replaced with a
18948 * new window
18949 * @param unit
18950 * the unit of time which applies to the {@code timespan} argument
18951 * @param scheduler
18952 * the {@code Scheduler} to use when determining the end and start of a window
18953 * @return the new {@code Flowable} instance
18954 * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null}
18955 * @see <a href="http://reactivex.io/documentation/operators/window.html">ReactiveX operators documentation: Window</a>
18956 */
18957 @CheckReturnValue
18958 @BackpressureSupport(BackpressureKind.ERROR)
18959 @SchedulerSupport(SchedulerSupport.CUSTOM)
18960 @NonNull
18961 public final Flowable<Flowable<T>> window(long timespan, @NonNull TimeUnit unit,
18962 @NonNull Scheduler scheduler) {
18963 return window(timespan, unit, scheduler, Long.MAX_VALUE, false);
18964 }
18965
18966 /**
18967 * Returns a {@code Flowable} that emits windows of items it collects from the current {@code Flowable}. The resulting
18968 * {@code Flowable} emits connected, non-overlapping windows, each of a fixed duration specified by the
18969 * {@code timespan} argument or a maximum size specified by the {@code count} argument (whichever is reached
18970 * first). When the current {@code Flowable} completes or encounters an error, the resulting {@code Flowable} emits the
18971 * current window and propagates the notification from the current {@code Flowable}.
18972 * <p>
18973 * <img width="640" height="370" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/window6.s.v3.png" alt="">
18974 * <p>
18975 * Note that ignoring windows or subscribing later (i.e., on another thread) will result in
18976 * so-called window abandonment where a window may not contain any elements. In this case, subsequent
18977 * elements will be dropped until the condition for the next window boundary is satisfied. The behavior is
18978 * a trade-off for ensuring upstream cancellation can happen under some race conditions.
18979 * <dl>
18980 * <dt><b>Backpressure:</b></dt>
18981 * <dd>The operator consumes the current {@code Flowable} in an unbounded manner.
18982 * The resulting {@code Flowable} doesn't support backpressure as it uses
18983 * time to control the creation of windows. The emitted inner {@code Flowable}s honor
18984 * backpressure and may hold up to {@code count} elements at most.</dd>
18985 * <dt><b>Scheduler:</b></dt>
18986 * <dd>You specify which {@link Scheduler} this operator will use.</dd>
18987 * </dl>
18988 *
18989 * @param timespan
18990 * the period of time each window collects items before it should be emitted and replaced with a
18991 * new window
18992 * @param unit
18993 * the unit of time which applies to the {@code timespan} argument
18994 * @param count
18995 * the maximum size of each window before it should be emitted
18996 * @param scheduler
18997 * the {@code Scheduler} to use when determining the end and start of a window
18998 * @return the new {@code Flowable} instance
18999 * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null}
19000 * @throws IllegalArgumentException if {@code count} is non-positive
19001 * @see <a href="http://reactivex.io/documentation/operators/window.html">ReactiveX operators documentation: Window</a>
19002 */
19003 @CheckReturnValue
19004 @BackpressureSupport(BackpressureKind.ERROR)
19005 @SchedulerSupport(SchedulerSupport.CUSTOM)
19006 @NonNull
19007 public final Flowable<Flowable<T>> window(long timespan, @NonNull TimeUnit unit,
19008 @NonNull Scheduler scheduler, long count) {
19009 return window(timespan, unit, scheduler, count, false);
19010 }
19011
19012 /**
19013 * Returns a {@code Flowable} that emits windows of items it collects from the current {@code Flowable}. The resulting
19014 * {@code Flowable} emits connected, non-overlapping windows, each of a fixed duration specified by the
19015 * {@code timespan} argument or a maximum size specified by the {@code count} argument (whichever is reached
19016 * first). When the current {@code Flowable} completes or encounters an error, the resulting {@code Flowable} emits the
19017 * current window and propagates the notification from the current {@code Flowable}.
19018 * <p>
19019 * <img width="640" height="370" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/window6.s.v3.png" alt="">
19020 * <p>
19021 * Note that ignoring windows or subscribing later (i.e., on another thread) will result in
19022 * so-called window abandonment where a window may not contain any elements. In this case, subsequent
19023 * elements will be dropped until the condition for the next window boundary is satisfied. The behavior is
19024 * a trade-off for ensuring upstream cancellation can happen under some race conditions.
19025 * <dl>
19026 * <dt><b>Backpressure:</b></dt>
19027 * <dd>The operator consumes the current {@code Flowable} in an unbounded manner.
19028 * The resulting {@code Flowable} doesn't support backpressure as it uses
19029 * time to control the creation of windows. The emitted inner {@code Flowable}s honor
19030 * backpressure and may hold up to {@code count} elements at most.</dd>
19031 * <dt><b>Scheduler:</b></dt>
19032 * <dd>You specify which {@link Scheduler} this operator will use.</dd>
19033 * </dl>
19034 *
19035 * @param timespan
19036 * the period of time each window collects items before it should be emitted and replaced with a
19037 * new window
19038 * @param unit
19039 * the unit of time which applies to the {@code timespan} argument
19040 * @param count
19041 * the maximum size of each window before it should be emitted
19042 * @param scheduler
19043 * the {@code Scheduler} to use when determining the end and start of a window
19044 * @param restart
19045 * if {@code true}, when a window reaches the capacity limit, the timer is restarted as well
19046 * @return the new {@code Flowable} instance
19047 * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null}
19048 * @throws IllegalArgumentException if {@code count} is non-positive
19049 * @see <a href="http://reactivex.io/documentation/operators/window.html">ReactiveX operators documentation: Window</a>
19050 */
19051 @CheckReturnValue
19052 @BackpressureSupport(BackpressureKind.ERROR)
19053 @SchedulerSupport(SchedulerSupport.CUSTOM)
19054 @NonNull
19055 public final Flowable<Flowable<T>> window(long timespan, @NonNull TimeUnit unit,
19056 @NonNull Scheduler scheduler, long count, boolean restart) {
19057 return window(timespan, unit, scheduler, count, restart, bufferSize());
19058 }
19059
19060 /**
19061 * Returns a {@code Flowable} that emits windows of items it collects from the current {@code Flowable}. The resulting
19062 * {@code Flowable} emits connected, non-overlapping windows, each of a fixed duration specified by the
19063 * {@code timespan} argument or a maximum size specified by the {@code count} argument (whichever is reached
19064 * first). When the current {@code Flowable} completes or encounters an error, the resulting {@code Flowable} emits the
19065 * current window and propagates the notification from the current {@code Flowable}.
19066 * <p>
19067 * <img width="640" height="370" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/window6.s.v3.png" alt="">
19068 * <p>
19069 * Note that ignoring windows or subscribing later (i.e., on another thread) will result in
19070 * so-called window abandonment where a window may not contain any elements. In this case, subsequent
19071 * elements will be dropped until the condition for the next window boundary is satisfied. The behavior is
19072 * a trade-off for ensuring upstream cancellation can happen under some race conditions.
19073 * <dl>
19074 * <dt><b>Backpressure:</b></dt>
19075 * <dd>The operator consumes the current {@code Flowable} in an unbounded manner.
19076 * The resulting {@code Flowable} doesn't support backpressure as it uses
19077 * time to control the creation of windows. The emitted inner {@code Flowable}s honor
19078 * backpressure and may hold up to {@code count} elements at most.</dd>
19079 * <dt><b>Scheduler:</b></dt>
19080 * <dd>You specify which {@link Scheduler} this operator will use.</dd>
19081 * </dl>
19082 *
19083 * @param timespan
19084 * the period of time each window collects items before it should be emitted and replaced with a
19085 * new window
19086 * @param unit
19087 * the unit of time which applies to the {@code timespan} argument
19088 * @param count
19089 * the maximum size of each window before it should be emitted
19090 * @param scheduler
19091 * the {@code Scheduler} to use when determining the end and start of a window
19092 * @param restart
19093 * if {@code true}, when a window reaches the capacity limit, the timer is restarted as well
19094 * @param bufferSize
19095 * the capacity hint for the buffer in the inner windows
19096 * @return the new {@code Flowable} instance
19097 * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null}
19098 * @throws IllegalArgumentException if {@code count}, {@code timespan} or {@code bufferSize} is non-positive
19099 * @see <a href="http://reactivex.io/documentation/operators/window.html">ReactiveX operators documentation: Window</a>
19100 */
19101 @CheckReturnValue
19102 @NonNull
19103 @BackpressureSupport(BackpressureKind.ERROR)
19104 @SchedulerSupport(SchedulerSupport.CUSTOM)
19105 public final Flowable<Flowable<T>> window(
19106 long timespan, @NonNull TimeUnit unit, @NonNull Scheduler scheduler,
19107 long count, boolean restart, int bufferSize) {
19108 ObjectHelper.verifyPositive(bufferSize, "bufferSize");
19109 Objects.requireNonNull(scheduler, "scheduler is null");
19110 Objects.requireNonNull(unit, "unit is null");
19111 ObjectHelper.verifyPositive(count, "count");
19112 return RxJavaPlugins.onAssembly(new FlowableWindowTimed<>(this, timespan, timespan, unit, scheduler, count, bufferSize, restart));
19113 }
19114
19115 /**
19116 * Returns a {@code Flowable} that emits non-overlapping windows of items it collects from the current {@code Flowable}
19117 * where the boundary of each window is determined by the items emitted from a specified boundary-governing
19118 * {@link Publisher}.
19119 * <p>
19120 * <img width="640" height="475" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/window8.v3.png" alt="">
19121 * <p>
19122 * Note that ignoring windows or subscribing later (i.e., on another thread) will result in
19123 * so-called window abandonment where a window may not contain any elements. In this case, subsequent
19124 * elements will be dropped until the condition for the next window boundary is satisfied. The behavior is
19125 * a trade-off for ensuring upstream cancellation can happen under some race conditions.
19126 * <dl>
19127 * <dt><b>Backpressure:</b></dt>
19128 * <dd>The outer {@code Publisher} of this operator does not support backpressure as it uses a {@code boundary} {@code Publisher} to control data
19129 * flow. The inner {@code Publisher}s honor backpressure and buffer everything until the boundary signals the next element.</dd>
19130 * <dt><b>Scheduler:</b></dt>
19131 * <dd>This version of {@code window} does not operate by default on a particular {@link Scheduler}.</dd>
19132 * </dl>
19133 *
19134 * @param <B>
19135 * the window element type (ignored)
19136 * @param boundaryIndicator
19137 * a {@code Publisher} whose emitted items close and open windows
19138 * @return the new {@code Flowable} instance
19139 * @throws NullPointerException if {@code boundaryIndicator} is {@code null}
19140 * @see <a href="http://reactivex.io/documentation/operators/window.html">ReactiveX operators documentation: Window</a>
19141 */
19142 @CheckReturnValue
19143 @BackpressureSupport(BackpressureKind.ERROR)
19144 @SchedulerSupport(SchedulerSupport.NONE)
19145 @NonNull
19146 public final <@NonNull B> Flowable<Flowable<T>> window(@NonNull Publisher<B> boundaryIndicator) {
19147 return window(boundaryIndicator, bufferSize());
19148 }
19149
19150 /**
19151 * Returns a {@code Flowable} that emits non-overlapping windows of items it collects from the current {@code Flowable}
19152 * where the boundary of each window is determined by the items emitted from a specified boundary-governing
19153 * {@link Publisher}.
19154 * <p>
19155 * <img width="640" height="475" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/window8.v3.png" alt="">
19156 * <p>
19157 * Note that ignoring windows or subscribing later (i.e., on another thread) will result in
19158 * so-called window abandonment where a window may not contain any elements. In this case, subsequent
19159 * elements will be dropped until the condition for the next window boundary is satisfied. The behavior is
19160 * a trade-off for ensuring upstream cancellation can happen under some race conditions.
19161 * <dl>
19162 * <dt><b>Backpressure:</b></dt>
19163 * <dd>The outer {@code Publisher} of this operator does not support backpressure as it uses a {@code boundary} {@code Publisher} to control data
19164 * flow. The inner {@code Publisher}s honor backpressure and buffer everything until the boundary signals the next element.</dd>
19165 * <dt><b>Scheduler:</b></dt>
19166 * <dd>This version of {@code window} does not operate by default on a particular {@link Scheduler}.</dd>
19167 * </dl>
19168 *
19169 * @param <B>
19170 * the window element type (ignored)
19171 * @param boundaryIndicator
19172 * a {@code Publisher} whose emitted items close and open windows
19173 * @param bufferSize
19174 * the capacity hint for the buffer in the inner windows
19175 * @return the new {@code Flowable} instance
19176 * @throws NullPointerException if {@code boundaryIndicator} is {@code null}
19177 * @throws IllegalArgumentException if {@code bufferSize} is non-positive
19178 * @see <a href="http://reactivex.io/documentation/operators/window.html">ReactiveX operators documentation: Window</a>
19179 */
19180 @CheckReturnValue
19181 @NonNull
19182 @BackpressureSupport(BackpressureKind.ERROR)
19183 @SchedulerSupport(SchedulerSupport.NONE)
19184 public final <@NonNull B> Flowable<Flowable<T>> window(@NonNull Publisher<B> boundaryIndicator, int bufferSize) {
19185 Objects.requireNonNull(boundaryIndicator, "boundaryIndicator is null");
19186 ObjectHelper.verifyPositive(bufferSize, "bufferSize");
19187 return RxJavaPlugins.onAssembly(new FlowableWindowBoundary<>(this, boundaryIndicator, bufferSize));
19188 }
19189
19190 /**
19191 * Returns a {@code Flowable} that emits windows of items it collects from the current {@code Flowable}. The resulting
19192 * {@code Flowable} emits windows that contain those items emitted by the current {@code Flowable} between the time when
19193 * the {@code windowOpenings} {@link Publisher} emits an item and when the {@code Publisher} returned by
19194 * {@code closingSelector} emits an item.
19195 * <p>
19196 * <img width="640" height="550" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/window2.v3.png" alt="">
19197 * <p>
19198 * Note that ignoring windows or subscribing later (i.e., on another thread) will result in
19199 * so-called window abandonment where a window may not contain any elements. In this case, subsequent
19200 * elements will be dropped until the condition for the next window boundary is satisfied. The behavior is
19201 * a trade-off for ensuring upstream cancellation can happen under some race conditions.
19202 * <dl>
19203 * <dt><b>Backpressure:</b></dt>
19204 * <dd>The outer {@code Publisher} of this operator doesn't support backpressure because the emission of new
19205 * inner {@code Publisher}s are controlled by the {@code windowOpenings} {@code Publisher}.
19206 * The inner {@code Publisher}s honor backpressure and buffer everything until the associated closing
19207 * {@code Publisher} signals or completes.</dd>
19208 * <dt><b>Scheduler:</b></dt>
19209 * <dd>This version of {@code window} does not operate by default on a particular {@link Scheduler}.</dd>
19210 * </dl>
19211 *
19212 * @param <U> the element type of the window-opening {@code Publisher}
19213 * @param <V> the element type of the window-closing {@code Publisher}s
19214 * @param openingIndicator
19215 * a {@code Publisher} that, when it emits an item, causes another window to be created
19216 * @param closingIndicator
19217 * a {@link Function} that produces a {@code Publisher} for every window created. When this {@code Publisher}
19218 * emits an item, the associated window is closed and emitted
19219 * @return the new {@code Flowable} instance
19220 * @throws NullPointerException if {@code openingIndicator} or {@code closingIndicator} is {@code null}
19221 * @see <a href="http://reactivex.io/documentation/operators/window.html">ReactiveX operators documentation: Window</a>
19222 */
19223 @CheckReturnValue
19224 @BackpressureSupport(BackpressureKind.ERROR)
19225 @SchedulerSupport(SchedulerSupport.NONE)
19226 @NonNull
19227 public final <@NonNull U, @NonNull V> Flowable<Flowable<T>> window(
19228 @NonNull Publisher<U> openingIndicator,
19229 @NonNull Function<? super U, @NonNull ? extends Publisher<V>> closingIndicator) {
19230 return window(openingIndicator, closingIndicator, bufferSize());
19231 }
19232
19233 /**
19234 * Returns a {@code Flowable} that emits windows of items it collects from the current {@code Flowable}. The resulting
19235 * {@code Flowable} emits windows that contain those items emitted by the current {@code Flowable} between the time when
19236 * the {@code windowOpenings} {@link Publisher} emits an item and when the {@code Publisher} returned by
19237 * {@code closingSelector} emits an item.
19238 * <p>
19239 * <img width="640" height="550" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/window2.v3.png" alt="">
19240 * <p>
19241 * Note that ignoring windows or subscribing later (i.e., on another thread) will result in
19242 * so-called window abandonment where a window may not contain any elements. In this case, subsequent
19243 * elements will be dropped until the condition for the next window boundary is satisfied. The behavior is
19244 * a trade-off for ensuring upstream cancellation can happen under some race conditions.
19245 * <dl>
19246 * <dt><b>Backpressure:</b></dt>
19247 * <dd>The outer {@code Publisher} of this operator doesn't support backpressure because the emission of new
19248 * inner {@code Publisher}s are controlled by the {@code windowOpenings} {@code Publisher}.
19249 * The inner {@code Publisher}s honor backpressure and buffer everything until the associated closing
19250 * {@code Publisher} signals or completes.</dd>
19251 * <dt><b>Scheduler:</b></dt>
19252 * <dd>This version of {@code window} does not operate by default on a particular {@link Scheduler}.</dd>
19253 * </dl>
19254 *
19255 * @param <U> the element type of the window-opening {@code Publisher}
19256 * @param <V> the element type of the window-closing {@code Publisher}s
19257 * @param openingIndicator
19258 * a {@code Publisher} that, when it emits an item, causes another window to be created
19259 * @param closingIndicator
19260 * a {@link Function} that produces a {@code Publisher} for every window created. When this {@code Publisher}
19261 * emits an item, the associated window is closed and emitted
19262 * @param bufferSize
19263 * the capacity hint for the buffer in the inner windows
19264 * @return the new {@code Flowable} instance
19265 * @throws NullPointerException if {@code openingIndicator} or {@code closingIndicator} is {@code null}
19266 * @throws IllegalArgumentException if {@code bufferSize} is non-positive
19267 * @see <a href="http://reactivex.io/documentation/operators/window.html">ReactiveX operators documentation: Window</a>
19268 */
19269 @CheckReturnValue
19270 @NonNull
19271 @BackpressureSupport(BackpressureKind.ERROR)
19272 @SchedulerSupport(SchedulerSupport.NONE)
19273 public final <@NonNull U, @NonNull V> Flowable<Flowable<T>> window(
19274 @NonNull Publisher<U> openingIndicator,
19275 @NonNull Function<? super U, @NonNull ? extends Publisher<V>> closingIndicator, int bufferSize) {
19276 Objects.requireNonNull(openingIndicator, "openingIndicator is null");
19277 Objects.requireNonNull(closingIndicator, "closingIndicator is null");
19278 ObjectHelper.verifyPositive(bufferSize, "bufferSize");
19279 return RxJavaPlugins.onAssembly(new FlowableWindowBoundarySelector<>(this, openingIndicator, closingIndicator, bufferSize));
19280 }
19281
19282 /**
19283 * Merges the specified {@link Publisher} into the current {@code Flowable} sequence by using the {@code resultSelector}
19284 * function only when the current {@code Flowable} (this instance) emits an item.
19285 *
19286 * <p>Note that this operator doesn't emit anything until the other source has produced at
19287 * least one value. The resulting emission only happens when the current {@code Flowable} emits (and
19288 * not when the other source emits, unlike combineLatest).
19289 * If the other source doesn't produce any value and just completes, the sequence is completed immediately.
19290 * If the upstream completes before the other source has produced at least one value, the sequence completes
19291 * without emission.
19292 * <p>
19293 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/withLatestFrom.v3.png" alt="">
19294 *
19295 * <dl>
19296 * <dt><b>Backpressure:</b></dt>
19297 * <dd>The operator is a pass-through for backpressure: the backpressure support
19298 * depends on the upstream and downstream's backpressure behavior. The other {@code Publisher}
19299 * is consumed in an unbounded fashion.</dd>
19300 * <dt><b>Scheduler:</b></dt>
19301 * <dd>This operator, by default, doesn't run any particular {@link Scheduler}.</dd>
19302 * </dl>
19303 *
19304 * @param <U> the element type of the other {@code Publisher}
19305 * @param <R> the result type of the combination
19306 * @param other
19307 * the other {@code Publisher}
19308 * @param combiner
19309 * the function to call when the current {@code Flowable} emits an item and the other {@code Publisher} has already
19310 * emitted an item, to generate the item to be emitted by the resulting {@code Flowable}
19311 * @return the new {@code Flowable} instance
19312 * @throws NullPointerException if {@code other} or {@code combiner} is {@code null}
19313 * @since 2.0
19314 * @see <a href="http://reactivex.io/documentation/operators/combinelatest.html">ReactiveX operators documentation: CombineLatest</a>
19315 */
19316 @CheckReturnValue
19317 @NonNull
19318 @BackpressureSupport(BackpressureKind.PASS_THROUGH)
19319 @SchedulerSupport(SchedulerSupport.NONE)
19320 public final <@NonNull U, @NonNull R> Flowable<R> withLatestFrom(@NonNull Publisher<? extends U> other,
19321 @NonNull BiFunction<? super T, ? super U, ? extends R> combiner) {
19322 Objects.requireNonNull(other, "other is null");
19323 Objects.requireNonNull(combiner, "combiner is null");
19324
19325 return RxJavaPlugins.onAssembly(new FlowableWithLatestFrom<T, U, R>(this, combiner, other));
19326 }
19327
19328 /**
19329 * Combines the value emission from the current {@code Flowable} with the latest emissions from the
19330 * other {@link Publisher}s via a function to produce the output item.
19331 *
19332 * <p>Note that this operator doesn't emit anything until all other sources have produced at
19333 * least one value. The resulting emission only happens when the current {@code Flowable} emits (and
19334 * not when any of the other sources emit, unlike combineLatest).
19335 * If a source doesn't produce any value and just completes, the sequence is completed immediately.
19336 * If the upstream completes before all other sources have produced at least one value, the sequence completes
19337 * without emission.
19338 *
19339 * <dl>
19340 * <dt><b>Backpressure:</b></dt>
19341 * <dd>This operator is a pass-through for backpressure behavior between the current {@code Flowable}
19342 * and the downstream {@link Subscriber}. The other {@code Publisher}s are consumed in an unbounded manner.</dd>
19343 * <dt><b>Scheduler:</b></dt>
19344 * <dd>This operator does not operate by default on a particular {@link Scheduler}.</dd>
19345 * </dl>
19346 *
19347 * @param <T1> the first other source's value type
19348 * @param <T2> the second other source's value type
19349 * @param <R> the result value type
19350 * @param source1 the first other {@code Publisher}
19351 * @param source2 the second other {@code Publisher}
19352 * @param combiner the function called with an array of values from each participating {@code Publisher}
19353 * @return the new {@code Flowable} instance
19354 * @throws NullPointerException if {@code source1}, {@code source2} or {@code combiner} is {@code null}
19355 * @since 2.0
19356 */
19357 @CheckReturnValue
19358 @NonNull
19359 @BackpressureSupport(BackpressureKind.PASS_THROUGH)
19360 @SchedulerSupport(SchedulerSupport.NONE)
19361 public final <@NonNull T1, @NonNull T2, @NonNull R> Flowable<R> withLatestFrom(@NonNull Publisher<T1> source1, @NonNull Publisher<T2> source2,
19362 @NonNull Function3<? super T, ? super T1, ? super T2, R> combiner) {
19363 Objects.requireNonNull(source1, "source1 is null");
19364 Objects.requireNonNull(source2, "source2 is null");
19365 Objects.requireNonNull(combiner, "combiner is null");
19366 Function<Object[], R> f = Functions.toFunction(combiner);
19367 return withLatestFrom(new Publisher[] { source1, source2 }, f);
19368 }
19369
19370 /**
19371 * Combines the value emission from the current {@code Flowable} with the latest emissions from the
19372 * other {@link Publisher}s via a function to produce the output item.
19373 *
19374 * <p>Note that this operator doesn't emit anything until all other sources have produced at
19375 * least one value. The resulting emission only happens when the current {@code Flowable} emits (and
19376 * not when any of the other sources emit, unlike combineLatest).
19377 * If a source doesn't produce any value and just completes, the sequence is completed immediately.
19378 * If the upstream completes before all other sources have produced at least one value, the sequence completes
19379 * without emission.
19380 *
19381 * <dl>
19382 * <dt><b>Backpressure:</b></dt>
19383 * <dd>This operator is a pass-through for backpressure behavior between the current {@code Flowable}
19384 * and the downstream {@link Subscriber}. The other {@code Publisher}s are consumed in an unbounded manner.</dd>
19385 * <dt><b>Scheduler:</b></dt>
19386 * <dd>This operator does not operate by default on a particular {@link Scheduler}.</dd>
19387 * </dl>
19388 *
19389 * @param <T1> the first other source's value type
19390 * @param <T2> the second other source's value type
19391 * @param <T3> the third other source's value type
19392 * @param <R> the result value type
19393 * @param source1 the first other {@code Publisher}
19394 * @param source2 the second other {@code Publisher}
19395 * @param source3 the third other {@code Publisher}
19396 * @param combiner the function called with an array of values from each participating {@code Publisher}
19397 * @return the new {@code Flowable} instance
19398 * @throws NullPointerException if {@code source1}, {@code source2}, {@code source3} or {@code combiner} is {@code null}
19399 * @since 2.0
19400 */
19401 @CheckReturnValue
19402 @NonNull
19403 @BackpressureSupport(BackpressureKind.PASS_THROUGH)
19404 @SchedulerSupport(SchedulerSupport.NONE)
19405 public final <@NonNull T1, @NonNull T2, @NonNull T3, @NonNull R> Flowable<R> withLatestFrom(
19406 @NonNull Publisher<T1> source1, @NonNull Publisher<T2> source2,
19407 @NonNull Publisher<T3> source3,
19408 @NonNull Function4<? super T, ? super T1, ? super T2, ? super T3, R> combiner) {
19409 Objects.requireNonNull(source1, "source1 is null");
19410 Objects.requireNonNull(source2, "source2 is null");
19411 Objects.requireNonNull(source3, "source3 is null");
19412 Objects.requireNonNull(combiner, "combiner is null");
19413 Function<Object[], R> f = Functions.toFunction(combiner);
19414 return withLatestFrom(new Publisher[] { source1, source2, source3 }, f);
19415 }
19416
19417 /**
19418 * Combines the value emission from the current {@code Flowable} with the latest emissions from the
19419 * other {@link Publisher}s via a function to produce the output item.
19420 *
19421 * <p>Note that this operator doesn't emit anything until all other sources have produced at
19422 * least one value. The resulting emission only happens when the current {@code Flowable} emits (and
19423 * not when any of the other sources emit, unlike combineLatest).
19424 * If a source doesn't produce any value and just completes, the sequence is completed immediately.
19425 * If the upstream completes before all other sources have produced at least one value, the sequence completes
19426 * without emission.
19427 *
19428 * <dl>
19429 * <dt><b>Backpressure:</b></dt>
19430 * <dd>This operator is a pass-through for backpressure behavior between the current {@code Flowable}
19431 * and the downstream {@link Subscriber}. The other {@code Publisher}s are consumed in an unbounded manner.</dd>
19432 * <dt><b>Scheduler:</b></dt>
19433 * <dd>This operator does not operate by default on a particular {@link Scheduler}.</dd>
19434 * </dl>
19435 *
19436 * @param <T1> the first other source's value type
19437 * @param <T2> the second other source's value type
19438 * @param <T3> the third other source's value type
19439 * @param <T4> the fourth other source's value type
19440 * @param <R> the result value type
19441 * @param source1 the first other {@code Publisher}
19442 * @param source2 the second other {@code Publisher}
19443 * @param source3 the third other {@code Publisher}
19444 * @param source4 the fourth other {@code Publisher}
19445 * @param combiner the function called with an array of values from each participating {@code Publisher}
19446 * @return the new {@code Flowable} instance
19447 * @throws NullPointerException if {@code source1}, {@code source2}, {@code source3},
19448 * {@code source4} or {@code combiner} is {@code null}
19449 * @since 2.0
19450 */
19451 @CheckReturnValue
19452 @NonNull
19453 @BackpressureSupport(BackpressureKind.PASS_THROUGH)
19454 @SchedulerSupport(SchedulerSupport.NONE)
19455 public final <@NonNull T1, @NonNull T2, @NonNull T3, @NonNull T4, @NonNull R> Flowable<R> withLatestFrom(
19456 @NonNull Publisher<T1> source1, @NonNull Publisher<T2> source2,
19457 @NonNull Publisher<T3> source3, @NonNull Publisher<T4> source4,
19458 @NonNull Function5<? super T, ? super T1, ? super T2, ? super T3, ? super T4, R> combiner) {
19459 Objects.requireNonNull(source1, "source1 is null");
19460 Objects.requireNonNull(source2, "source2 is null");
19461 Objects.requireNonNull(source3, "source3 is null");
19462 Objects.requireNonNull(source4, "source4 is null");
19463 Objects.requireNonNull(combiner, "combiner is null");
19464 Function<Object[], R> f = Functions.toFunction(combiner);
19465 return withLatestFrom(new Publisher[] { source1, source2, source3, source4 }, f);
19466 }
19467
19468 /**
19469 * Combines the value emission from the current {@code Flowable} with the latest emissions from the
19470 * other {@link Publisher}s via a function to produce the output item.
19471 *
19472 * <p>Note that this operator doesn't emit anything until all other sources have produced at
19473 * least one value. The resulting emission only happens when the current {@code Flowable} emits (and
19474 * not when any of the other sources emit, unlike combineLatest).
19475 * If a source doesn't produce any value and just completes, the sequence is completed immediately.
19476 * If the upstream completes before all other sources have produced at least one value, the sequence completes
19477 * without emission.
19478 *
19479 * <dl>
19480 * <dt><b>Backpressure:</b></dt>
19481 * <dd>This operator is a pass-through for backpressure behavior between the current {@code Flowable}
19482 * and the downstream {@link Subscriber}. The other {@code Publisher}s are consumed in an unbounded manner.</dd>
19483 * <dt><b>Scheduler:</b></dt>
19484 * <dd>This operator does not operate by default on a particular {@link Scheduler}.</dd>
19485 * </dl>
19486 *
19487 * @param <R> the result value type
19488 * @param others the array of other sources
19489 * @param combiner the function called with an array of values from each participating {@code Publisher}
19490 * @return the new {@code Flowable} instance
19491 * @throws NullPointerException if {@code others} or {@code combiner} is {@code null}
19492 * @since 2.0
19493 */
19494 @CheckReturnValue
19495 @NonNull
19496 @BackpressureSupport(BackpressureKind.PASS_THROUGH)
19497 @SchedulerSupport(SchedulerSupport.NONE)
19498 public final <@NonNull R> Flowable<R> withLatestFrom(@NonNull Publisher<@NonNull ?>[] others, @NonNull Function<? super Object[], R> combiner) {
19499 Objects.requireNonNull(others, "others is null");
19500 Objects.requireNonNull(combiner, "combiner is null");
19501 return RxJavaPlugins.onAssembly(new FlowableWithLatestFromMany<>(this, others, combiner));
19502 }
19503
19504 /**
19505 * Combines the value emission from the current {@code Flowable} with the latest emissions from the
19506 * other {@link Publisher}s via a function to produce the output item.
19507 *
19508 * <p>Note that this operator doesn't emit anything until all other sources have produced at
19509 * least one value. The resulting emission only happens when the current {@code Flowable} emits (and
19510 * not when any of the other sources emit, unlike combineLatest).
19511 * If a source doesn't produce any value and just completes, the sequence is completed immediately.
19512 * If the upstream completes before all other sources have produced at least one value, the sequence completes
19513 * without emission.
19514 *
19515 * <dl>
19516 * <dt><b>Backpressure:</b></dt>
19517 * <dd>This operator is a pass-through for backpressure behavior between the current {@code Flowable}
19518 * and the downstream {@link Subscriber}. The other {@code Publisher}s are consumed in an unbounded manner.</dd>
19519 * <dt><b>Scheduler:</b></dt>
19520 * <dd>This operator does not operate by default on a particular {@link Scheduler}.</dd>
19521 * </dl>
19522 *
19523 * @param <R> the result value type
19524 * @param others the iterable of other sources
19525 * @param combiner the function called with an array of values from each participating {@code Publisher}
19526 * @return the new {@code Flowable} instance
19527 * @throws NullPointerException if {@code others} or {@code combiner} is {@code null}
19528 * @since 2.0
19529 */
19530 @CheckReturnValue
19531 @NonNull
19532 @BackpressureSupport(BackpressureKind.PASS_THROUGH)
19533 @SchedulerSupport(SchedulerSupport.NONE)
19534 public final <@NonNull R> Flowable<R> withLatestFrom(@NonNull Iterable<@NonNull ? extends Publisher<@NonNull ?>> others, @NonNull Function<? super Object[], R> combiner) {
19535 Objects.requireNonNull(others, "others is null");
19536 Objects.requireNonNull(combiner, "combiner is null");
19537 return RxJavaPlugins.onAssembly(new FlowableWithLatestFromMany<>(this, others, combiner));
19538 }
19539
19540 /**
19541 * Returns a {@code Flowable} that emits items that are the result of applying a specified function to pairs of
19542 * values, one each from the current {@code Flowable} and a specified {@link Iterable} sequence.
19543 * <p>
19544 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/zip.i.v3.png" alt="">
19545 * <p>
19546 * Note that the {@code other} {@code Iterable} is evaluated as items are observed from the current {@code Flowable}; it is
19547 * not pre-consumed. This allows you to zip infinite streams on either side.
19548 * <dl>
19549 * <dt><b>Backpressure:</b></dt>
19550 * <dd>The operator expects backpressure from the sources and honors backpressure from the downstream.
19551 * (I.e., zipping with {@link #interval(long, TimeUnit)} may result in {@link MissingBackpressureException}, use
19552 * one of the {@code onBackpressureX} to handle similar, backpressure-ignoring sources.</dd>
19553 * <dt><b>Scheduler:</b></dt>
19554 * <dd>{@code zipWith} does not operate by default on a particular {@link Scheduler}.</dd>
19555 * </dl>
19556 *
19557 * @param <U>
19558 * the type of items in the {@code other} {@code Iterable}
19559 * @param <R>
19560 * the type of items emitted by the resulting {@code Flowable}
19561 * @param other
19562 * the {@code Iterable} sequence
19563 * @param zipper
19564 * a function that combines the pairs of items from the current {@code Flowable} and the {@code Iterable} to generate
19565 * the items to be emitted by the resulting {@code Flowable}
19566 * @return the new {@code Flowable} instance
19567 * @throws NullPointerException if {@code other} or {@code zipper} is {@code null}
19568 * @see <a href="http://reactivex.io/documentation/operators/zip.html">ReactiveX operators documentation: Zip</a>
19569 */
19570 @CheckReturnValue
19571 @NonNull
19572 @BackpressureSupport(BackpressureKind.FULL)
19573 @SchedulerSupport(SchedulerSupport.NONE)
19574 public final <@NonNull U, @NonNull R> Flowable<R> zipWith(@NonNull Iterable<U> other, @NonNull BiFunction<? super T, ? super U, ? extends R> zipper) {
19575 Objects.requireNonNull(other, "other is null");
19576 Objects.requireNonNull(zipper, "zipper is null");
19577 return RxJavaPlugins.onAssembly(new FlowableZipIterable<>(this, other, zipper));
19578 }
19579
19580 /**
19581 * Returns a {@code Flowable} that emits items that are the result of applying a specified function to pairs of
19582 * values, one each from the current {@code Flowable} and another specified {@link Publisher}.
19583 * <p>
19584 * The operator subscribes to its sources in the order they are specified and completes eagerly if
19585 * one of the sources is shorter than the rest while canceling the other sources. Therefore, it
19586 * is possible those other sources will never be able to run to completion (and thus not calling
19587 * {@code doOnComplete()}). This can also happen if the sources are exactly the same length; if
19588 * source A completes and B has been consumed and is about to complete, the operator detects A won't
19589 * be sending further values and it will cancel B immediately. For example:
19590 * <pre><code>range(1, 5).doOnComplete(action1).zipWith(range(6, 5).doOnComplete(action2), (a, b) -&gt; a + b)</code></pre>
19591 * {@code action1} will be called but {@code action2} won't.
19592 * <br>To work around this termination property,
19593 * use {@link #doOnCancel(Action)} as well or use {@code using()} to do cleanup in case of completion
19594 * or cancellation.
19595 * <p>
19596 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/zip.v3.png" alt="">
19597 * <dl>
19598 * <dt><b>Backpressure:</b></dt>
19599 * <dd>The operator expects backpressure from the sources and honors backpressure from the downstream.
19600 * (I.e., zipping with {@link #interval(long, TimeUnit)} may result in {@link MissingBackpressureException}, use
19601 * one of the {@code onBackpressureX} to handle similar, backpressure-ignoring sources.</dd>
19602 * <dt><b>Scheduler:</b></dt>
19603 * <dd>{@code zipWith} does not operate by default on a particular {@link Scheduler}.</dd>
19604 * </dl>
19605 *
19606 * @param <U>
19607 * the type of items emitted by the {@code other} {@code Publisher}
19608 * @param <R>
19609 * the type of items emitted by the resulting {@code Flowable}
19610 * @param other
19611 * the other {@code Publisher}
19612 * @param zipper
19613 * a function that combines the pairs of items from the two {@code Publisher}s to generate the items to
19614 * be emitted by the resulting {@code Flowable}
19615 * @return the new {@code Flowable} instance
19616 * @throws NullPointerException if {@code other} or {@code zipper} is {@code null}
19617 * @see <a href="http://reactivex.io/documentation/operators/zip.html">ReactiveX operators documentation: Zip</a>
19618 */
19619 @CheckReturnValue
19620 @NonNull
19621 @BackpressureSupport(BackpressureKind.FULL)
19622 @SchedulerSupport(SchedulerSupport.NONE)
19623 public final <@NonNull U, @NonNull R> Flowable<R> zipWith(@NonNull Publisher<? extends U> other, @NonNull BiFunction<? super T, ? super U, ? extends R> zipper) {
19624 Objects.requireNonNull(other, "other is null");
19625 return zip(this, other, zipper);
19626 }
19627
19628 /**
19629 * Returns a {@code Flowable} that emits items that are the result of applying a specified function to pairs of
19630 * values, one each from the current {@code Flowable} and another specified {@link Publisher}.
19631 * <p>
19632 * The operator subscribes to its sources in the order they are specified and completes eagerly if
19633 * one of the sources is shorter than the rest while canceling the other sources. Therefore, it
19634 * is possible those other sources will never be able to run to completion (and thus not calling
19635 * {@code doOnComplete()}). This can also happen if the sources are exactly the same length; if
19636 * source A completes and B has been consumed and is about to complete, the operator detects A won't
19637 * be sending further values and it will cancel B immediately. For example:
19638 * <pre><code>range(1, 5).doOnComplete(action1).zipWith(range(6, 5).doOnComplete(action2), (a, b) -&gt; a + b)</code></pre>
19639 * {@code action1} will be called but {@code action2} won't.
19640 * <br>To work around this termination property,
19641 * use {@link #doOnCancel(Action)} as well or use {@code using()} to do cleanup in case of completion
19642 * or cancellation.
19643 * <p>
19644 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/zip.v3.png" alt="">
19645 * <dl>
19646 * <dt><b>Backpressure:</b></dt>
19647 * <dd>The operator expects backpressure from the sources and honors backpressure from the downstream.
19648 * (I.e., zipping with {@link #interval(long, TimeUnit)} may result in {@link MissingBackpressureException}, use
19649 * one of the {@code onBackpressureX} to handle similar, backpressure-ignoring sources.</dd>
19650 * <dt><b>Scheduler:</b></dt>
19651 * <dd>{@code zipWith} does not operate by default on a particular {@link Scheduler}.</dd>
19652 * </dl>
19653 *
19654 * @param <U>
19655 * the type of items emitted by the {@code other} {@code Publisher}
19656 * @param <R>
19657 * the type of items emitted by the resulting {@code Flowable}
19658 * @param other
19659 * the other {@code Publisher}
19660 * @param zipper
19661 * a function that combines the pairs of items from the two {@code Publisher}s to generate the items to
19662 * be emitted by the resulting {@code Flowable}
19663 * @param delayError
19664 * if {@code true}, errors from the current {@code Flowable} or the other {@code Publisher} is delayed until both terminate
19665 * @return the new {@code Flowable} instance
19666 * @throws NullPointerException if {@code other} or {@code zipper} is {@code null}
19667 * @see <a href="http://reactivex.io/documentation/operators/zip.html">ReactiveX operators documentation: Zip</a>
19668 * @since 2.0
19669 */
19670 @CheckReturnValue
19671 @BackpressureSupport(BackpressureKind.FULL)
19672 @SchedulerSupport(SchedulerSupport.NONE)
19673 @NonNull
19674 public final <@NonNull U, @NonNull R> Flowable<R> zipWith(@NonNull Publisher<? extends U> other,
19675 @NonNull BiFunction<? super T, ? super U, ? extends R> zipper, boolean delayError) {
19676 return zip(this, other, zipper, delayError);
19677 }
19678
19679 /**
19680 * Returns a {@code Flowable} that emits items that are the result of applying a specified function to pairs of
19681 * values, one each from the current {@code Flowable} and another specified {@link Publisher}.
19682 * <p>
19683 * The operator subscribes to its sources in the order they are specified and completes eagerly if
19684 * one of the sources is shorter than the rest while canceling the other sources. Therefore, it
19685 * is possible those other sources will never be able to run to completion (and thus not calling
19686 * {@code doOnComplete()}). This can also happen if the sources are exactly the same length; if
19687 * source A completes and B has been consumed and is about to complete, the operator detects A won't
19688 * be sending further values and it will cancel B immediately. For example:
19689 * <pre><code>range(1, 5).doOnComplete(action1).zipWith(range(6, 5).doOnComplete(action2), (a, b) -&gt; a + b)</code></pre>
19690 * {@code action1} will be called but {@code action2} won't.
19691 * <br>To work around this termination property,
19692 * use {@link #doOnCancel(Action)} as well or use {@code using()} to do cleanup in case of completion
19693 * or cancellation.
19694 * <p>
19695 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/zip.v3.png" alt="">
19696 * <dl>
19697 * <dt><b>Backpressure:</b></dt>
19698 * <dd>The operator expects backpressure from the sources and honors backpressure from the downstream.
19699 * (I.e., zipping with {@link #interval(long, TimeUnit)} may result in {@link MissingBackpressureException}, use
19700 * one of the {@code onBackpressureX} to handle similar, backpressure-ignoring sources.</dd>
19701 * <dt><b>Scheduler:</b></dt>
19702 * <dd>{@code zipWith} does not operate by default on a particular {@link Scheduler}.</dd>
19703 * </dl>
19704 *
19705 * @param <U>
19706 * the type of items emitted by the {@code other} {@code Publisher}
19707 * @param <R>
19708 * the type of items emitted by the resulting {@code Flowable}
19709 * @param other
19710 * the other {@code Publisher}
19711 * @param zipper
19712 * a function that combines the pairs of items from the two {@code Publisher}s to generate the items to
19713 * be emitted by the resulting {@code Flowable}
19714 * @param bufferSize
19715 * the capacity hint for the buffer in the inner windows
19716 * @param delayError
19717 * if {@code true}, errors from the current {@code Flowable} or the other {@code Publisher} is delayed until both terminate
19718 * @return the new {@code Flowable} instance
19719 * @throws NullPointerException if {@code other} or {@code zipper} is {@code null}
19720 * @throws IllegalArgumentException if {@code bufferSize} is non-positive
19721 * @see <a href="http://reactivex.io/documentation/operators/zip.html">ReactiveX operators documentation: Zip</a>
19722 * @since 2.0
19723 */
19724 @CheckReturnValue
19725 @BackpressureSupport(BackpressureKind.FULL)
19726 @SchedulerSupport(SchedulerSupport.NONE)
19727 @NonNull
19728 public final <@NonNull U, @NonNull R> Flowable<R> zipWith(@NonNull Publisher<? extends U> other,
19729 @NonNull BiFunction<? super T, ? super U, ? extends R> zipper, boolean delayError, int bufferSize) {
19730 return zip(this, other, zipper, delayError, bufferSize);
19731 }
19732
19733 // -------------------------------------------------------------------------
19734 // Fluent test support, super handy and reduces test preparation boilerplate
19735 // -------------------------------------------------------------------------
19736 /**
19737 * Creates a {@link TestSubscriber} that requests {@link Long#MAX_VALUE} and subscribes
19738 * it to this {@code Flowable}.
19739 * <dl>
19740 * <dt><b>Backpressure:</b></dt>
19741 * <dd>The returned {@code TestSubscriber} consumes this {@code Flowable} in an unbounded fashion.</dd>
19742 * <dt><b>Scheduler:</b></dt>
19743 * <dd>{@code test} does not operate by default on a particular {@link Scheduler}.</dd>
19744 * </dl>
19745 * @return the new {@code TestSubscriber} instance
19746 * @since 2.0
19747 */
19748 @CheckReturnValue
19749 @BackpressureSupport(BackpressureKind.UNBOUNDED_IN)
19750 @SchedulerSupport(SchedulerSupport.NONE)
19751 @NonNull
19752 public final TestSubscriber<T> test() { // NoPMD
19753 TestSubscriber<T> ts = new TestSubscriber<>();
19754 subscribe(ts);
19755 return ts;
19756 }
19757
19758 /**
19759 * Creates a {@link TestSubscriber} with the given initial request amount and subscribes
19760 * it to this {@code Flowable}.
19761 * <dl>
19762 * <dt><b>Backpressure:</b></dt>
19763 * <dd>The returned {@code TestSubscriber} requests the given {@code initialRequest} amount upfront.</dd>
19764 * <dt><b>Scheduler:</b></dt>
19765 * <dd>{@code test} does not operate by default on a particular {@link Scheduler}.</dd>
19766 * </dl>
19767 * @param initialRequest the initial request amount, positive
19768 * @return the new {@code TestSubscriber} instance
19769 * @since 2.0
19770 */
19771 @CheckReturnValue
19772 @BackpressureSupport(BackpressureKind.FULL)
19773 @SchedulerSupport(SchedulerSupport.NONE)
19774 @NonNull
19775 public final TestSubscriber<T> test(long initialRequest) { // NoPMD
19776 TestSubscriber<T> ts = new TestSubscriber<>(initialRequest);
19777 subscribe(ts);
19778 return ts;
19779 }
19780
19781 /**
19782 * Creates a {@link TestSubscriber} with the given initial request amount,
19783 * optionally cancels it before the subscription and subscribes
19784 * it to this {@code Flowable}.
19785 * <dl>
19786 * <dt><b>Backpressure:</b></dt>
19787 * <dd>The returned {@code TestSubscriber} requests the given {@code initialRequest} amount upfront.</dd>
19788 * <dt><b>Scheduler:</b></dt>
19789 * <dd>{@code test} does not operate by default on a particular {@link Scheduler}.</dd>
19790 * </dl>
19791 * @param initialRequest the initial request amount, positive
19792 * @param cancel should the {@code TestSubscriber} be canceled before the subscription?
19793 * @return the new {@code TestSubscriber} instance
19794 * @since 2.0
19795 */
19796 @CheckReturnValue
19797 @BackpressureSupport(BackpressureKind.FULL)
19798 @SchedulerSupport(SchedulerSupport.NONE)
19799 @NonNull
19800 public final TestSubscriber<T> test(long initialRequest, boolean cancel) { // NoPMD
19801 TestSubscriber<T> ts = new TestSubscriber<>(initialRequest);
19802 if (cancel) {
19803 ts.cancel();
19804 }
19805 subscribe(ts);
19806 return ts;
19807 }
19808
19809 // -------------------------------------------------------------------------
19810 // JDK 8 Support
19811 // -------------------------------------------------------------------------
19812
19813 /**
19814 * Converts the existing value of the provided optional into a {@link #just(Object)}
19815 * or an empty optional into an {@link #empty()} {@code Flowable} instance.
19816 * <p>
19817 * <img width="640" height="335" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/fromOptional.f.png" alt="">
19818 * <p>
19819 * Note that the operator takes an already instantiated optional reference and does not
19820 * by any means create this original optional. If the optional is to be created per
19821 * consumer upon subscription, use {@link #defer(Supplier)} around {@code fromOptional}:
19822 * <pre><code>
19823 * Flowable.defer(() -&gt; Flowable.fromOptional(createOptional()));
19824 * </code></pre>
19825 * <dl>
19826 * <dt><b>Backpressure:</b></dt>
19827 * <dd>The returned {@code Flowable} supports backpressure.</dd>
19828 * <dt><b>Scheduler:</b></dt>
19829 * <dd>{@code fromOptional} does not operate by default on a particular {@link Scheduler}.</dd>
19830 * </dl>
19831 * @param <T> the element type of the optional value
19832 * @param optional the optional value to convert into a {@code Flowable}
19833 * @return the new {@code Flowable} instance
19834 * @throws NullPointerException if {@code optional} is {@code null}
19835 * @since 3.0.0
19836 * @see #just(Object)
19837 * @see #empty()
19838 */
19839 @CheckReturnValue
19840 @BackpressureSupport(BackpressureKind.FULL)
19841 @SchedulerSupport(SchedulerSupport.NONE)
19842 @NonNull
19843 public static <@NonNull T> Flowable<@NonNull T> fromOptional(@NonNull Optional<T> optional) {
19844 Objects.requireNonNull(optional, "optional is null");
19845 return optional.map(Flowable::just).orElseGet(Flowable::empty);
19846 }
19847
19848 /**
19849 * Signals the completion value or error of the given (hot) {@link CompletionStage}-based asynchronous calculation.
19850 * <p>
19851 * <img width="640" height="262" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/fromCompletionStage.f.png" alt="">
19852 * <p>
19853 * Note that the operator takes an already instantiated, running or terminated {@code CompletionStage}.
19854 * If the optional is to be created per consumer upon subscription, use {@link #defer(Supplier)}
19855 * around {@code fromCompletionStage}:
19856 * <pre><code>
19857 * Flowable.defer(() -&gt; Flowable.fromCompletionStage(createCompletionStage()));
19858 * </code></pre>
19859 * <p>
19860 * If the {@code CompletionStage} completes with {@code null}, a {@link NullPointerException} is signaled.
19861 * <p>
19862 * Canceling the flow can't cancel the execution of the {@code CompletionStage} because {@code CompletionStage}
19863 * itself doesn't support cancellation. Instead, the operator detaches from the {@code CompletionStage}.
19864 * <dl>
19865 * <dt><b>Backpressure:</b></dt>
19866 * <dd>The returned {@code Flowable} supports backpressure and caches the completion value until the
19867 * downstream is ready to receive it.</dd>
19868 * <dt><b>Scheduler:</b></dt>
19869 * <dd>{@code fromCompletionStage} does not operate by default on a particular {@link Scheduler}.</dd>
19870 * </dl>
19871 * @param <T> the element type of the {@code CompletionStage}
19872 * @param stage the {@code CompletionStage} to convert to {@code Flowable} and signal its terminal value or error
19873 * @return the new {@code Flowable} instance
19874 * @throws NullPointerException if {@code stage} is {@code null}
19875 * @since 3.0.0
19876 */
19877 @CheckReturnValue
19878 @BackpressureSupport(BackpressureKind.FULL)
19879 @SchedulerSupport(SchedulerSupport.NONE)
19880 @NonNull
19881 public static <@NonNull T> Flowable<@NonNull T> fromCompletionStage(@NonNull CompletionStage<T> stage) {
19882 Objects.requireNonNull(stage, "stage is null");
19883 return RxJavaPlugins.onAssembly(new FlowableFromCompletionStage<>(stage));
19884 }
19885
19886 /**
19887 * Converts a {@link Stream} into a finite {@code Flowable} and emits its items in the sequence.
19888 * <p>
19889 * <img width="640" height="347" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/fromStream.f.png" alt="">
19890 * <p>
19891 * The operator closes the {@code Stream} upon cancellation and when it terminates. Any exceptions raised when
19892 * closing a {@code Stream} are routed to the global error handler ({@link RxJavaPlugins#onError(Throwable)}.
19893 * If a {@code Stream} should not be closed, turn it into an {@link Iterable} and use {@link #fromIterable(Iterable)}:
19894 * <pre><code>
19895 * Stream&lt;T&gt; stream = ...
19896 * Flowable.fromIterable(stream::iterator);
19897 * </code></pre>
19898 * <p>
19899 * Note that {@code Stream}s can be consumed only once; any subsequent attempt to consume a {@code Stream}
19900 * will result in an {@link IllegalStateException}.
19901 * <p>
19902 * Primitive streams are not supported and items have to be boxed manually (e.g., via {@link IntStream#boxed()}):
19903 * <pre><code>
19904 * IntStream intStream = IntStream.rangeClosed(1, 10);
19905 * Flowable.fromStream(intStream.boxed());
19906 * </code></pre>
19907 * <p>
19908 * {@code Stream} does not support concurrent usage so creating and/or consuming the same instance multiple times
19909 * from multiple threads can lead to undefined behavior.
19910 * <dl>
19911 * <dt><b>Backpressure:</b></dt>
19912 * <dd>The operator honors backpressure from downstream and iterates the given {@code Stream}
19913 * on demand (i.e., when requested).</dd>
19914 * <dt><b>Scheduler:</b></dt>
19915 * <dd>{@code fromStream} does not operate by default on a particular {@link Scheduler}.</dd>
19916 * </dl>
19917 * @param <T> the element type of the source {@code Stream}
19918 * @param stream the {@code Stream} of values to emit
19919 * @return the new {@code Flowable} instance
19920 * @throws NullPointerException if {@code stream} is {@code null}
19921 * @since 3.0.0
19922 * @see #fromIterable(Iterable)
19923 */
19924 @CheckReturnValue
19925 @BackpressureSupport(BackpressureKind.FULL)
19926 @SchedulerSupport(SchedulerSupport.NONE)
19927 @NonNull
19928 public static <@NonNull T> Flowable<@NonNull T> fromStream(@NonNull Stream<T> stream) {
19929 Objects.requireNonNull(stream, "stream is null");
19930 return RxJavaPlugins.onAssembly(new FlowableFromStream<>(stream));
19931 }
19932
19933 /**
19934 * Maps each upstream value into an {@link Optional} and emits the contained item if not empty.
19935 * <p>
19936 * <img width="640" height="308" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/mapOptional.f.png" alt="">
19937 *
19938 * <dl>
19939 * <dt><b>Backpressure:</b></dt>
19940 * <dd>The operator is a pass-through for downstream requests but issues {@code request(1)} whenever the
19941 * mapped {@code Optional} is empty.</dd>
19942 * <dt><b>Scheduler:</b></dt>
19943 * <dd>{@code mapOptional} does not operate by default on a particular {@link Scheduler}.</dd>
19944 * </dl>
19945 * @param <R> the non-{@code null} output type
19946 * @param mapper the function that receives the upstream item and should return a <em>non-empty</em> {@code Optional}
19947 * to emit as the output or an <em>empty</em> {@code Optional} to skip to the next upstream value
19948 * @return the new {@code Flowable} instance
19949 * @throws NullPointerException if {@code mapper} is {@code null}
19950 * @since 3.0.0
19951 * @see #map(Function)
19952 * @see #filter(Predicate)
19953 */
19954 @CheckReturnValue
19955 @BackpressureSupport(BackpressureKind.FULL)
19956 @SchedulerSupport(SchedulerSupport.NONE)
19957 @NonNull
19958 public final <@NonNull R> Flowable<R> mapOptional(@NonNull Function<? super T, @NonNull Optional<? extends R>> mapper) {
19959 Objects.requireNonNull(mapper, "mapper is null");
19960 return RxJavaPlugins.onAssembly(new FlowableMapOptional<>(this, mapper));
19961 }
19962
19963 /**
19964 * Collects the finite upstream's values into a container via a {@link Stream} {@link Collector} callback set and emits
19965 * it as the success result.
19966 * <p>
19967 * <img width="640" height="360" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/collector.f.png" alt="">
19968 *
19969 * <dl>
19970 * <dt><b>Backpressure:</b></dt>
19971 * <dd>The operator consumes the upstream in an unbounded manner.</dd>
19972 * <dt><b>Scheduler:</b></dt>
19973 * <dd>{@code collect} does not operate by default on a particular {@link Scheduler}.</dd>
19974 * </dl>
19975 * @param <R> the non-{@code null} result type
19976 * @param <A> the intermediate container type used for the accumulation
19977 * @param collector the interface defining the container supplier, accumulator and finisher functions;
19978 * see {@link Collectors} for some standard implementations
19979 * @return the new {@link Single} instance
19980 * @throws NullPointerException if {@code collector} is {@code null}
19981 * @since 3.0.0
19982 * @see Collectors
19983 * @see #collect(Supplier, BiConsumer)
19984 */
19985 @CheckReturnValue
19986 @BackpressureSupport(BackpressureKind.UNBOUNDED_IN)
19987 @SchedulerSupport(SchedulerSupport.NONE)
19988 @NonNull
19989 public final <@NonNull R, @NonNull A> Single<R> collect(@NonNull Collector<? super T, A, R> collector) {
19990 Objects.requireNonNull(collector, "collector is null");
19991 return RxJavaPlugins.onAssembly(new FlowableCollectWithCollectorSingle<>(this, collector));
19992 }
19993
19994 /**
19995 * Signals the first upstream item (or the default item if the upstream is empty) via
19996 * a {@link CompletionStage}.
19997 * <p>
19998 * <img width="640" height="315" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/firstStage.f.png" alt="">
19999 * <p>
20000 * The upstream can be canceled by converting the resulting {@code CompletionStage} into
20001 * {@link CompletableFuture} via {@link CompletionStage#toCompletableFuture()} and
20002 * calling {@link CompletableFuture#cancel(boolean)} on it.
20003 * The upstream will be also cancelled if the resulting {@code CompletionStage} is converted to and
20004 * completed manually by {@link CompletableFuture#complete(Object)} or {@link CompletableFuture#completeExceptionally(Throwable)}.
20005 * <p>
20006 * {@code CompletionStage}s don't have a notion of emptiness and allow {@code null}s, therefore, one can either use
20007 * a {@code defaultItem} of {@code null} or turn the flow into a sequence of {@link Optional}s and default to {@link Optional#empty()}:
20008 * <pre><code>
20009 * CompletionStage&lt;Optional&lt;T&gt;&gt; stage = source.map(Optional::of).firstStage(Optional.empty());
20010 * </code></pre>
20011 * <dl>
20012 * <dt><b>Backpressure:</b></dt>
20013 * <dd>The operator requests one item from upstream and then when received, cancels the upstream.</dd>
20014 * <dt><b>Scheduler:</b></dt>
20015 * <dd>{@code firstStage} does not operate by default on a particular {@link Scheduler}.</dd>
20016 * </dl>
20017 * @param defaultItem the item to signal if the upstream is empty
20018 * @return the new {@code CompletionStage} instance
20019 * @since 3.0.0
20020 * @see #firstOrErrorStage()
20021 */
20022 @CheckReturnValue
20023 @BackpressureSupport(BackpressureKind.FULL)
20024 @SchedulerSupport(SchedulerSupport.NONE)
20025 @NonNull
20026 public final CompletionStage<T> firstStage(@Nullable T defaultItem) {
20027 return subscribeWith(new FlowableFirstStageSubscriber<>(true, defaultItem));
20028 }
20029
20030 /**
20031 * Signals the only expected upstream item (or the default item if the upstream is empty)
20032 * or signals {@link IllegalArgumentException} if the upstream has more than one item
20033 * via a {@link CompletionStage}.
20034 * <p>
20035 * <img width="640" height="229" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/singleStage.f.png" alt="">
20036 * <p>
20037 * The upstream can be canceled by converting the resulting {@code CompletionStage} into
20038 * {@link CompletableFuture} via {@link CompletionStage#toCompletableFuture()} and
20039 * calling {@link CompletableFuture#cancel(boolean)} on it.
20040 * The upstream will be also cancelled if the resulting {@code CompletionStage} is converted to and
20041 * completed manually by {@link CompletableFuture#complete(Object)} or {@link CompletableFuture#completeExceptionally(Throwable)}.
20042 * <p>
20043 * {@code CompletionStage}s don't have a notion of emptiness and allow {@code null}s, therefore, one can either use
20044 * a {@code defaultItem} of {@code null} or turn the flow into a sequence of {@link Optional}s and default to {@link Optional#empty()}:
20045 * <pre><code>
20046 * CompletionStage&lt;Optional&lt;T&gt;&gt; stage = source.map(Optional::of).singleStage(Optional.empty());
20047 * </code></pre>
20048 * <dl>
20049 * <dt><b>Backpressure:</b></dt>
20050 * <dd>The operator requests two items from upstream and then when more than one item is received, cancels the upstream.</dd>
20051 * <dt><b>Scheduler:</b></dt>
20052 * <dd>{@code singleStage} does not operate by default on a particular {@link Scheduler}.</dd>
20053 * </dl>
20054 * @param defaultItem the item to signal if the upstream is empty
20055 * @return the new {@code CompletionStage} instance
20056 * @since 3.0.0
20057 * @see #singleOrErrorStage()
20058 */
20059 @CheckReturnValue
20060 @BackpressureSupport(BackpressureKind.FULL)
20061 @SchedulerSupport(SchedulerSupport.NONE)
20062 @NonNull
20063 public final CompletionStage<T> singleStage(@Nullable T defaultItem) {
20064 return subscribeWith(new FlowableSingleStageSubscriber<>(true, defaultItem));
20065 }
20066
20067 /**
20068 * Signals the last upstream item (or the default item if the upstream is empty) via
20069 * a {@link CompletionStage}.
20070 * <p>
20071 * <img width="640" height="315" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/lastStage.f.png" alt="">
20072 * <p>
20073 * The upstream can be canceled by converting the resulting {@code CompletionStage} into
20074 * {@link CompletableFuture} via {@link CompletionStage#toCompletableFuture()} and
20075 * calling {@link CompletableFuture#cancel(boolean)} on it.
20076 * The upstream will be also cancelled if the resulting {@code CompletionStage} is converted to and
20077 * completed manually by {@link CompletableFuture#complete(Object)} or {@link CompletableFuture#completeExceptionally(Throwable)}.
20078 * <p>
20079 * {@code CompletionStage}s don't have a notion of emptiness and allow {@code null}s, therefore, one can either use
20080 * a {@code defaultItem} of {@code null} or turn the flow into a sequence of {@link Optional}s and default to {@link Optional#empty()}:
20081 * <pre><code>
20082 * CompletionStage&lt;Optional&lt;T&gt;&gt; stage = source.map(Optional::of).lastStage(Optional.empty());
20083 * </code></pre>
20084 * <dl>
20085 * <dt><b>Backpressure:</b></dt>
20086 * <dd>The operator requests an unbounded number of items from the upstream.</dd>
20087 * <dt><b>Scheduler:</b></dt>
20088 * <dd>{@code lastStage} does not operate by default on a particular {@link Scheduler}.</dd>
20089 * </dl>
20090 * @param defaultItem the item to signal if the upstream is empty
20091 * @return the new {@code CompletionStage} instance
20092 * @since 3.0.0
20093 * @see #lastOrErrorStage()
20094 */
20095 @CheckReturnValue
20096 @BackpressureSupport(BackpressureKind.UNBOUNDED_IN)
20097 @SchedulerSupport(SchedulerSupport.NONE)
20098 @NonNull
20099 public final CompletionStage<T> lastStage(@Nullable T defaultItem) {
20100 return subscribeWith(new FlowableLastStageSubscriber<>(true, defaultItem));
20101 }
20102
20103 /**
20104 * Signals the first upstream item or a {@link NoSuchElementException} if the upstream is empty via
20105 * a {@link CompletionStage}.
20106 * <p>
20107 * <img width="640" height="343" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/firstOrErrorStage.f.png" alt="">
20108 * <p>
20109 * The upstream can be canceled by converting the resulting {@code CompletionStage} into
20110 * {@link CompletableFuture} via {@link CompletionStage#toCompletableFuture()} and
20111 * calling {@link CompletableFuture#cancel(boolean)} on it.
20112 * The upstream will be also cancelled if the resulting {@code CompletionStage} is converted to and
20113 * completed manually by {@link CompletableFuture#complete(Object)} or {@link CompletableFuture#completeExceptionally(Throwable)}.
20114 * <dl>
20115 * <dt><b>Backpressure:</b></dt>
20116 * <dd>The operator requests one item from upstream and then when received, cancels the upstream.</dd>
20117 * <dt><b>Scheduler:</b></dt>
20118 * <dd>{@code firstOrErrorStage} does not operate by default on a particular {@link Scheduler}.</dd>
20119 * </dl>
20120 * @return the new {@code CompletionStage} instance
20121 * @since 3.0.0
20122 * @see #firstStage(Object)
20123 */
20124 @CheckReturnValue
20125 @BackpressureSupport(BackpressureKind.FULL)
20126 @SchedulerSupport(SchedulerSupport.NONE)
20127 @NonNull
20128 public final CompletionStage<T> firstOrErrorStage() {
20129 return subscribeWith(new FlowableFirstStageSubscriber<>(false, null));
20130 }
20131
20132 /**
20133 * Signals the only expected upstream item, a {@link NoSuchElementException} if the upstream is empty
20134 * or signals {@link IllegalArgumentException} if the upstream has more than one item
20135 * via a {@link CompletionStage}.
20136 * <p>
20137 * <img width="640" height="229" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/singleOrErrorStage.f.png" alt="">
20138 * <p>
20139 * The upstream can be canceled by converting the resulting {@code CompletionStage} into
20140 * {@link CompletableFuture} via {@link CompletionStage#toCompletableFuture()} and
20141 * calling {@link CompletableFuture#cancel(boolean)} on it.
20142 * The upstream will be also cancelled if the resulting {@code CompletionStage} is converted to and
20143 * completed manually by {@link CompletableFuture#complete(Object)} or {@link CompletableFuture#completeExceptionally(Throwable)}.
20144 * <dl>
20145 * <dt><b>Backpressure:</b></dt>
20146 * <dd>The operator requests two items from upstream and then when more than one item is received, cancels the upstream.</dd>
20147 * <dt><b>Scheduler:</b></dt>
20148 * <dd>{@code singleOrErrorStage} does not operate by default on a particular {@link Scheduler}.</dd>
20149 * </dl>
20150 * @return the new {@code CompletionStage} instance
20151 * @since 3.0.0
20152 * @see #singleStage(Object)
20153 */
20154 @CheckReturnValue
20155 @BackpressureSupport(BackpressureKind.FULL)
20156 @SchedulerSupport(SchedulerSupport.NONE)
20157 @NonNull
20158 public final CompletionStage<T> singleOrErrorStage() {
20159 return subscribeWith(new FlowableSingleStageSubscriber<>(false, null));
20160 }
20161
20162 /**
20163 * Signals the last upstream item or a {@link NoSuchElementException} if the upstream is empty via
20164 * a {@link CompletionStage}.
20165 * <p>
20166 * <img width="640" height="346" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/lastOrErrorStage.f.png" alt="">
20167 * <p>
20168 * The upstream can be canceled by converting the resulting {@code CompletionStage} into
20169 * {@link CompletableFuture} via {@link CompletionStage#toCompletableFuture()} and
20170 * calling {@link CompletableFuture#cancel(boolean)} on it.
20171 * The upstream will be also cancelled if the resulting {@code CompletionStage} is converted to and
20172 * completed manually by {@link CompletableFuture#complete(Object)} or {@link CompletableFuture#completeExceptionally(Throwable)}.
20173 * <dl>
20174 * <dt><b>Backpressure:</b></dt>
20175 * <dd>The operator requests an unbounded number of items from the upstream.</dd>
20176 * <dt><b>Scheduler:</b></dt>
20177 * <dd>{@code lastOrErrorStage} does not operate by default on a particular {@link Scheduler}.</dd>
20178 * </dl>
20179 * @return the new {@code CompletionStage} instance
20180 * @since 3.0.0
20181 * @see #lastStage(Object)
20182 */
20183 @CheckReturnValue
20184 @BackpressureSupport(BackpressureKind.FULL)
20185 @SchedulerSupport(SchedulerSupport.NONE)
20186 @NonNull
20187 public final CompletionStage<T> lastOrErrorStage() {
20188 return subscribeWith(new FlowableLastStageSubscriber<>(false, null));
20189 }
20190
20191 /**
20192 * Creates a sequential {@link Stream} to consume or process this {@code Flowable} in a blocking manner via
20193 * the Java {@code Stream} API.
20194 * <p>
20195 * <img width="640" height="446" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/blockingStream.f.png" alt="">
20196 * <p>
20197 * Cancellation of the upstream is done via {@link Stream#close()}, therefore, it is strongly recommended the
20198 * consumption is performed within a try-with-resources construct:
20199 * <pre><code>
20200 * Flowable&lt;Integer&gt; source = Flowable.range(1, 10)
20201 * .subscribeOn(Schedulers.computation());
20202 *
20203 * try (Stream&lt;Integer&gt; stream = source.blockingStream()) {
20204 * stream.limit(3).forEach(System.out::println);
20205 * }
20206 * </code></pre>
20207 * <dl>
20208 * <dt><b>Backpressure:</b></dt>
20209 * <dd>The operator requests {@link #bufferSize()} amount upfront and 75% of it after each 75% of the amount received.</dd>
20210 * <dt><b>Scheduler:</b></dt>
20211 * <dd>{@code blockingStream} does not operate by default on a particular {@link Scheduler}.</dd>
20212 * </dl>
20213 *
20214 * @return the new {@code Stream} instance
20215 * @since 3.0.0
20216 * @see #blockingStream(int)
20217 */
20218 @CheckReturnValue
20219 @BackpressureSupport(BackpressureKind.FULL)
20220 @SchedulerSupport(SchedulerSupport.NONE)
20221 @NonNull
20222 public final Stream<T> blockingStream() {
20223 return blockingStream(bufferSize());
20224 }
20225
20226 /**
20227 * Creates a sequential {@link Stream} to consume or process this {@code Flowable} in a blocking manner via
20228 * the Java {@code Stream} API.
20229 * <p>
20230 * <img width="640" height="410" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/blockingStream.fi.png" alt="">
20231 * <p>
20232 * Cancellation of the upstream is done via {@link Stream#close()}, therefore, it is strongly recommended the
20233 * consumption is performed within a try-with-resources construct:
20234 * <pre><code>
20235 * Flowable&lt;Integer&gt; source = Flowable.range(1, 10)
20236 * .subscribeOn(Schedulers.computation());
20237 *
20238 * try (Stream&lt;Integer&gt; stream = source.blockingStream(4)) {
20239 * stream.limit(3).forEach(System.out::println);
20240 * }
20241 * </code></pre>
20242 * <dl>
20243 * <dt><b>Backpressure:</b></dt>
20244 * <dd>The operator requests the given {@code prefetch} amount upfront and 75% of it after each 75% of the amount received.</dd>
20245 * <dt><b>Scheduler:</b></dt>
20246 * <dd>{@code blockingStream} does not operate by default on a particular {@link Scheduler}.</dd>
20247 * </dl>
20248 *
20249 * @param prefetch the number of items to request from the upstream to limit the number of
20250 * in-flight items and item generation.
20251 * @return the new {@code Stream} instance
20252 * @throws IllegalArgumentException if {@code prefetch} is non-positive
20253 * @since 3.0.0
20254 */
20255 @CheckReturnValue
20256 @BackpressureSupport(BackpressureKind.FULL)
20257 @SchedulerSupport(SchedulerSupport.NONE)
20258 @NonNull
20259 public final Stream<T> blockingStream(int prefetch) {
20260 Iterator<T> iterator = blockingIterable(prefetch).iterator();
20261 return StreamSupport.stream(Spliterators.spliteratorUnknownSize(iterator, 0), false)
20262 .onClose(((Disposable) iterator)::dispose);
20263 }
20264
20265 /**
20266 * Maps each upstream item into a {@link Stream} and emits the {@code Stream}'s items to the downstream in a sequential fashion.
20267 * <p>
20268 * <img width="640" height="327" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/concatMapStream.f.png" alt="">
20269 * <p>
20270 * Due to the blocking and sequential nature of Java {@code Stream}s, the streams are mapped and consumed in a sequential fashion
20271 * without interleaving (unlike a more general {@link #flatMap(Function)}). Therefore, {@code flatMapStream} and
20272 * {@code concatMapStream} are identical operators and are provided as aliases.
20273 * <p>
20274 * The operator closes the {@code Stream} upon cancellation and when it terminates. Any exceptions raised when
20275 * closing a {@code Stream} are routed to the global error handler ({@link RxJavaPlugins#onError(Throwable)}.
20276 * If a {@code Stream} should not be closed, turn it into an {@link Iterable} and use {@link #concatMapIterable(Function)}:
20277 * <pre><code>
20278 * source.concatMapIterable(v -&gt; createStream(v)::iterator);
20279 * </code></pre>
20280 * <p>
20281 * Note that {@code Stream}s can be consumed only once; any subsequent attempt to consume a {@code Stream}
20282 * will result in an {@link IllegalStateException}.
20283 * <p>
20284 * Primitive streams are not supported and items have to be boxed manually (e.g., via {@link IntStream#boxed()}):
20285 * <pre><code>
20286 * source.concatMapStream(v -&gt; IntStream.rangeClosed(v + 1, v + 10).boxed());
20287 * </code></pre>
20288 * <p>
20289 * {@code Stream} does not support concurrent usage so creating and/or consuming the same instance multiple times
20290 * from multiple threads can lead to undefined behavior.
20291 * <dl>
20292 * <dt><b>Backpressure:</b></dt>
20293 * <dd>The operator honors the downstream backpressure and consumes the inner stream only on demand. The operator
20294 * prefetches {@link #bufferSize} items of the upstream (then 75% of it after the 75% received)
20295 * and caches them until they are ready to be mapped into {@code Stream}s
20296 * after the current {@code Stream} has been consumed.</dd>
20297 * <dt><b>Scheduler:</b></dt>
20298 * <dd>{@code concatMapStream} does not operate by default on a particular {@link Scheduler}.</dd>
20299 * </dl>
20300 *
20301 * @param <R> the element type of the {@code Stream}s and the result
20302 * @param mapper the function that receives an upstream item and should return a {@code Stream} whose elements
20303 * will be emitted to the downstream
20304 * @return the new {@code Flowable} instance
20305 * @throws NullPointerException if {@code mapper} is {@code null}
20306 * @since 3.0.0
20307 * @see #concatMap(Function)
20308 * @see #concatMapIterable(Function)
20309 * @see #concatMapStream(Function, int)
20310 */
20311 @CheckReturnValue
20312 @BackpressureSupport(BackpressureKind.FULL)
20313 @SchedulerSupport(SchedulerSupport.NONE)
20314 @NonNull
20315 public final <@NonNull R> Flowable<R> concatMapStream(@NonNull Function<? super T, @NonNull ? extends Stream<? extends R>> mapper) {
20316 return flatMapStream(mapper, bufferSize());
20317 }
20318
20319 /**
20320 * Maps each upstream item into a {@link Stream} and emits the {@code Stream}'s items to the downstream in a sequential fashion.
20321 * <p>
20322 * <img width="640" height="270" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/concatMapStream.fi.png" alt="">
20323 * <p>
20324 * Due to the blocking and sequential nature of Java {@code Stream}s, the streams are mapped and consumed in a sequential fashion
20325 * without interleaving (unlike a more general {@link #flatMap(Function)}). Therefore, {@code flatMapStream} and
20326 * {@code concatMapStream} are identical operators and are provided as aliases.
20327 * <p>
20328 * The operator closes the {@code Stream} upon cancellation and when it terminates. Any exceptions raised when
20329 * closing a {@code Stream} are routed to the global error handler ({@link RxJavaPlugins#onError(Throwable)}.
20330 * If a {@code Stream} should not be closed, turn it into an {@link Iterable} and use {@link #concatMapIterable(Function, int)}:
20331 * <pre><code>
20332 * source.concatMapIterable(v -&gt; createStream(v)::iterator, 32);
20333 * </code></pre>
20334 * <p>
20335 * Note that {@code Stream}s can be consumed only once; any subsequent attempt to consume a {@code Stream}
20336 * will result in an {@link IllegalStateException}.
20337 * <p>
20338 * Primitive streams are not supported and items have to be boxed manually (e.g., via {@link IntStream#boxed()}):
20339 * <pre><code>
20340 * source.concatMapStream(v -&gt; IntStream.rangeClosed(v + 1, v + 10).boxed(), 32);
20341 * </code></pre>
20342 * <p>
20343 * {@code Stream} does not support concurrent usage so creating and/or consuming the same instance multiple times
20344 * from multiple threads can lead to undefined behavior.
20345 * <dl>
20346 * <dt><b>Backpressure:</b></dt>
20347 * <dd>The operator honors the downstream backpressure and consumes the inner stream only on demand. The operator
20348 * prefetches the given amount of upstream items and caches them until they are ready to be mapped into {@code Stream}s
20349 * after the current {@code Stream} has been consumed.</dd>
20350 * <dt><b>Scheduler:</b></dt>
20351 * <dd>{@code concatMapStream} does not operate by default on a particular {@link Scheduler}.</dd>
20352 * </dl>
20353 *
20354 * @param <R> the element type of the {@code Stream}s and the result
20355 * @param mapper the function that receives an upstream item and should return a {@code Stream} whose elements
20356 * will be emitted to the downstream
20357 * @param prefetch the number of upstream items to request upfront, then 75% of this amount after each 75% upstream items received
20358 * @return the new {@code Flowable} instance
20359 * @throws NullPointerException if {@code mapper} is {@code null}
20360 * @throws IllegalArgumentException if {@code prefetch} is non-positive
20361 * @since 3.0.0
20362 * @see #concatMap(Function, int)
20363 * @see #concatMapIterable(Function, int)
20364 * @see #flatMapStream(Function, int)
20365 */
20366 @CheckReturnValue
20367 @BackpressureSupport(BackpressureKind.FULL)
20368 @SchedulerSupport(SchedulerSupport.NONE)
20369 @NonNull
20370 public final <@NonNull R> Flowable<R> concatMapStream(@NonNull Function<? super T, @NonNull ? extends Stream<? extends R>> mapper, int prefetch) {
20371 Objects.requireNonNull(mapper, "mapper is null");
20372 ObjectHelper.verifyPositive(prefetch, "prefetch");
20373 return RxJavaPlugins.onAssembly(new FlowableFlatMapStream<>(this, mapper, prefetch));
20374 }
20375
20376 /**
20377 * Maps each upstream item into a {@link Stream} and emits the {@code Stream}'s items to the downstream in a sequential fashion.
20378 * <p>
20379 * <img width="640" height="328" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/flatMapStream.f.png" alt="">
20380 * <p>
20381 * Due to the blocking and sequential nature of Java {@code Stream}s, the streams are mapped and consumed in a sequential fashion
20382 * without interleaving (unlike a more general {@link #flatMap(Function)}). Therefore, {@code flatMapStream} and
20383 * {@code concatMapStream} are identical operators and are provided as aliases.
20384 * <p>
20385 * The operator closes the {@code Stream} upon cancellation and when it terminates. Any exceptions raised when
20386 * closing a {@code Stream} are routed to the global error handler ({@link RxJavaPlugins#onError(Throwable)}.
20387 * If a {@code Stream} should not be closed, turn it into an {@link Iterable} and use {@link #flatMapIterable(Function)}:
20388 * <pre><code>
20389 * source.flatMapIterable(v -&gt; createStream(v)::iterator);
20390 * </code></pre>
20391 * <p>
20392 * Note that {@code Stream}s can be consumed only once; any subsequent attempt to consume a {@code Stream}
20393 * will result in an {@link IllegalStateException}.
20394 * <p>
20395 * Primitive streams are not supported and items have to be boxed manually (e.g., via {@link IntStream#boxed()}):
20396 * <pre><code>
20397 * source.flatMapStream(v -&gt; IntStream.rangeClosed(v + 1, v + 10).boxed());
20398 * </code></pre>
20399 * <p>
20400 * {@code Stream} does not support concurrent usage so creating and/or consuming the same instance multiple times
20401 * from multiple threads can lead to undefined behavior.
20402 * <dl>
20403 * <dt><b>Backpressure:</b></dt>
20404 * <dd>The operator honors the downstream backpressure and consumes the inner stream only on demand. The operator
20405 * prefetches {@link #bufferSize} items of the upstream (then 75% of it after the 75% received)
20406 * and caches them until they are ready to be mapped into {@code Stream}s
20407 * after the current {@code Stream} has been consumed.</dd>
20408 * <dt><b>Scheduler:</b></dt>
20409 * <dd>{@code flatMapStream} does not operate by default on a particular {@link Scheduler}.</dd>
20410 * </dl>
20411 *
20412 * @param <R> the element type of the {@code Stream}s and the result
20413 * @param mapper the function that receives an upstream item and should return a {@code Stream} whose elements
20414 * will be emitted to the downstream
20415 * @return the new {@code Flowable} instance
20416 * @throws NullPointerException if {@code mapper} is {@code null}
20417 * @since 3.0.0
20418 * @see #flatMap(Function)
20419 * @see #flatMapIterable(Function)
20420 * @see #flatMapStream(Function, int)
20421 */
20422 @CheckReturnValue
20423 @BackpressureSupport(BackpressureKind.FULL)
20424 @SchedulerSupport(SchedulerSupport.NONE)
20425 @NonNull
20426 public final <@NonNull R> Flowable<R> flatMapStream(@NonNull Function<? super T, @NonNull ? extends Stream<? extends R>> mapper) {
20427 return flatMapStream(mapper, bufferSize());
20428 }
20429
20430 /**
20431 * Maps each upstream item into a {@link Stream} and emits the {@code Stream}'s items to the downstream in a sequential fashion.
20432 * <p>
20433 * <img width="640" height="270" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/flatMapStream.fi.png" alt="">
20434 * <p>
20435 * Due to the blocking and sequential nature of Java {@code Stream}s, the streams are mapped and consumed in a sequential fashion
20436 * without interleaving (unlike a more general {@link #flatMap(Function)}). Therefore, {@code flatMapStream} and
20437 * {@code concatMapStream} are identical operators and are provided as aliases.
20438 * <p>
20439 * The operator closes the {@code Stream} upon cancellation and when it terminates. Any exceptions raised when
20440 * closing a {@code Stream} are routed to the global error handler ({@link RxJavaPlugins#onError(Throwable)}.
20441 * If a {@code Stream} should not be closed, turn it into an {@link Iterable} and use {@link #flatMapIterable(Function, int)}:
20442 * <pre><code>
20443 * source.flatMapIterable(v -&gt; createStream(v)::iterator, 32);
20444 * </code></pre>
20445 * <p>
20446 * Note that {@code Stream}s can be consumed only once; any subsequent attempt to consume a {@code Stream}
20447 * will result in an {@link IllegalStateException}.
20448 * <p>
20449 * Primitive streams are not supported and items have to be boxed manually (e.g., via {@link IntStream#boxed()}):
20450 * <pre><code>
20451 * source.flatMapStream(v -&gt; IntStream.rangeClosed(v + 1, v + 10).boxed(), 32);
20452 * </code></pre>
20453 * <p>
20454 * {@code Stream} does not support concurrent usage so creating and/or consuming the same instance multiple times
20455 * from multiple threads can lead to undefined behavior.
20456 * <dl>
20457 * <dt><b>Backpressure:</b></dt>
20458 * <dd>The operator honors the downstream backpressure and consumes the inner stream only on demand. The operator
20459 * prefetches the given amount of upstream items and caches them until they are ready to be mapped into {@code Stream}s
20460 * after the current {@code Stream} has been consumed.</dd>
20461 * <dt><b>Scheduler:</b></dt>
20462 * <dd>{@code flatMapStream} does not operate by default on a particular {@link Scheduler}.</dd>
20463 * </dl>
20464 *
20465 * @param <R> the element type of the {@code Stream}s and the result
20466 * @param mapper the function that receives an upstream item and should return a {@code Stream} whose elements
20467 * will be emitted to the downstream
20468 * @param prefetch the number of upstream items to request upfront, then 75% of this amount after each 75% upstream items received
20469 * @return the new {@code Flowable} instance
20470 * @throws NullPointerException if {@code mapper} is {@code null}
20471 * @throws IllegalArgumentException if {@code prefetch} is non-positive
20472 * @since 3.0.0
20473 * @see #flatMap(Function, int)
20474 * @see #flatMapIterable(Function, int)
20475 * @see #concatMapStream(Function, int)
20476 */
20477 @CheckReturnValue
20478 @BackpressureSupport(BackpressureKind.FULL)
20479 @SchedulerSupport(SchedulerSupport.NONE)
20480 @NonNull
20481 public final <@NonNull R> Flowable<R> flatMapStream(@NonNull Function<? super T, @NonNull ? extends Stream<? extends R>> mapper, int prefetch) {
20482 Objects.requireNonNull(mapper, "mapper is null");
20483 ObjectHelper.verifyPositive(prefetch, "prefetch");
20484 return RxJavaPlugins.onAssembly(new FlowableFlatMapStream<>(this, mapper, prefetch));
20485 }
20486 }