Debian Codegraph @

src/main/java/io/reactivex/rxjava3/core/Observable.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.Publisher;
21
22 import io.reactivex.rxjava3.annotations.*;
23 import io.reactivex.rxjava3.disposables.*;
24 import io.reactivex.rxjava3.exceptions.*;
25 import io.reactivex.rxjava3.functions.*;
26 import io.reactivex.rxjava3.internal.functions.*;
27 import io.reactivex.rxjava3.internal.jdk8.*;
28 import io.reactivex.rxjava3.internal.observers.*;
29 import io.reactivex.rxjava3.internal.operators.flowable.*;
30 import io.reactivex.rxjava3.internal.operators.maybe.MaybeToObservable;
31 import io.reactivex.rxjava3.internal.operators.mixed.*;
32 import io.reactivex.rxjava3.internal.operators.observable.*;
33 import io.reactivex.rxjava3.internal.operators.single.SingleToObservable;
34 import io.reactivex.rxjava3.internal.util.*;
35 import io.reactivex.rxjava3.observables.*;
36 import io.reactivex.rxjava3.observers.*;
37 import io.reactivex.rxjava3.operators.ScalarSupplier;
38 import io.reactivex.rxjava3.plugins.RxJavaPlugins;
39 import io.reactivex.rxjava3.schedulers.*;
40
41 /**
42 * The {@code Observable} class is the non-backpressured, optionally multi-valued base reactive class that
43 * offers factory methods, intermediate operators and the ability to consume synchronous
44 * and/or asynchronous reactive dataflows.
45 * <p>
46 * Many operators in the class accept {@link ObservableSource}(s), the base reactive interface
47 * for such non-backpressured flows, which {@code Observable} itself implements as well.
48 * <p>
49 * The {@code Observable}'s operators, by default, run with a buffer size of 128 elements (see {@link Flowable#bufferSize()}),
50 * that can be overridden globally via the system parameter {@code rx3.buffer-size}. Most operators, however, have
51 * overloads that allow setting their internal buffer size explicitly.
52 * <p>
53 * The documentation for this class makes use of marble diagrams. The following legend explains these diagrams:
54 * <p>
55 * <img width="640" height="317" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/legend.v3.png" alt="">
56 * <p>
57 * The design of this class was derived from the
58 * <a href="https://github.com/reactive-streams/reactive-streams-jvm">Reactive-Streams design and specification</a>
59 * by removing any backpressure-related infrastructure and implementation detail, replacing the
60 * {@code org.reactivestreams.Subscription} with {@link Disposable} as the primary means to dispose of
61 * a flow.
62 * <p>
63 * The {@code Observable} follows the protocol
64 * <pre><code>
65 * onSubscribe onNext* (onError | onComplete)?
66 * </code></pre>
67 * where
68 * the stream can be disposed through the {@code Disposable} instance provided to consumers through
69 * {@code Observer.onSubscribe}.
70 * <p>
71 * Unlike the {@code Observable} of version 1.x, {@link #subscribe(Observer)} does not allow external disposal
72 * of a subscription and the {@link Observer} instance is expected to expose such capability.
73 * <p>Example:
74 * <pre><code>
75 * Disposable d = Observable.just("Hello world!")
76 * .delay(1, TimeUnit.SECONDS)
77 * .subscribeWith(new DisposableObserver&lt;String&gt;() {
78 * &#64;Override public void onStart() {
79 * System.out.println("Start!");
80 * }
81 * &#64;Override public void onNext(String t) {
82 * System.out.println(t);
83 * }
84 * &#64;Override public void onError(Throwable t) {
85 * t.printStackTrace();
86 * }
87 * &#64;Override public void onComplete() {
88 * System.out.println("Done!");
89 * }
90 * });
91 *
92 * Thread.sleep(500);
93 * // the sequence can now be disposed via dispose()
94 * d.dispose();
95 * </code></pre>
96 *
97 * @param <T>
98 * the type of the items emitted by the {@code Observable}
99 * @see Flowable
100 * @see io.reactivex.rxjava3.observers.DisposableObserver
101 */
102 public abstract class Observable<@NonNull T> implements ObservableSource<T> {
103
104 /**
105 * Mirrors the one {@link ObservableSource} in an {@link Iterable} of several {@code ObservableSource}s that first either emits an item or sends
106 * a termination notification.
107 * <p>
108 * <img width="640" height="505" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Observable.amb.png" alt="">
109 * <p>
110 * When one of the {@code ObservableSource}s signal an item or terminates first, all subscriptions to the other
111 * {@code ObservableSource}s are disposed.
112 * <dl>
113 * <dt><b>Scheduler:</b></dt>
114 * <dd>{@code amb} does not operate by default on a particular {@link Scheduler}.</dd>
115 * <dt><b>Error handling:</b></dt>
116 * <dd>
117 * If any of the losing {@code ObservableSource}s signals an error, the error is routed to the global
118 * error handler via {@link RxJavaPlugins#onError(Throwable)}.
119 * </dd>
120 * </dl>
121 *
122 * @param <T> the common element type
123 * @param sources
124 * an {@code Iterable} of {@code ObservableSource} sources competing to react first. A subscription to each source will
125 * occur in the same order as in the {@code Iterable}.
126 * @return the new {@code Observable} instance
127 * @throws NullPointerException if {@code sources} is {@code null}
128 * @see <a href="http://reactivex.io/documentation/operators/amb.html">ReactiveX operators documentation: Amb</a>
129 */
130 @CheckReturnValue
131 @NonNull
132 @SchedulerSupport(SchedulerSupport.NONE)
133 public static <@NonNull T> Observable<T> amb(@NonNull Iterable<@NonNull ? extends ObservableSource<? extends T>> sources) {
134 Objects.requireNonNull(sources, "sources is null");
135 return RxJavaPlugins.onAssembly(new ObservableAmb<>(null, sources));
136 }
137
138 /**
139 * Mirrors the one {@link ObservableSource} in an array of several {@code ObservableSource}s that first either emits an item or sends
140 * a termination notification.
141 * <p>
142 * <img width="640" height="505" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Observable.ambArray.png" alt="">
143 * <p>
144 * When one of the {@code ObservableSource}s signal an item or terminates first, all subscriptions to the other
145 * {@code ObservableSource}s are disposed.
146 * <dl>
147 * <dt><b>Scheduler:</b></dt>
148 * <dd>{@code ambArray} does not operate by default on a particular {@link Scheduler}.</dd>
149 * <dt><b>Error handling:</b></dt>
150 * <dd>
151 * If any of the losing {@code ObservableSource}s signals an error, the error is routed to the global
152 * error handler via {@link RxJavaPlugins#onError(Throwable)}.
153 * </dd>
154 * </dl>
155 *
156 * @param <T> the common element type
157 * @param sources
158 * an array of {@code ObservableSource} sources competing to react first. A subscription to each source will
159 * occur in the same order as in the array.
160 * @return the new {@code Observable} instance
161 * @throws NullPointerException if {@code sources} is {@code null}
162 * @see <a href="http://reactivex.io/documentation/operators/amb.html">ReactiveX operators documentation: Amb</a>
163 */
164 @SuppressWarnings("unchecked")
165 @CheckReturnValue
166 @NonNull
167 @SchedulerSupport(SchedulerSupport.NONE)
168 @SafeVarargs
169 public static <@NonNull T> Observable<T> ambArray(@NonNull ObservableSource<? extends T>... sources) {
170 Objects.requireNonNull(sources, "sources is null");
171 int len = sources.length;
172 if (len == 0) {
173 return empty();
174 }
175 if (len == 1) {
176 return (Observable<T>)wrap(sources[0]);
177 }
178 return RxJavaPlugins.onAssembly(new ObservableAmb<>(sources, null));
179 }
180
181 /**
182 * Returns the default 'island' size or capacity-increment hint for unbounded buffers.
183 * <p>Delegates to {@link Flowable#bufferSize} but is public for convenience.
184 * <p>The value can be overridden via system parameter {@code rx3.buffer-size}
185 * <em>before</em> the {@link Flowable} class is loaded.
186 * @return the default 'island' size or capacity-increment hint
187 */
188 @CheckReturnValue
189 public static int bufferSize() {
190 return Flowable.bufferSize();
191 }
192
193 /**
194 * Combines a collection of source {@link ObservableSource}s by emitting an item that aggregates the latest values of each of
195 * the returned {@code ObservableSource}s each time an item is received from any of the returned {@code ObservableSource}s, where this
196 * aggregation is defined by a specified function.
197 * <p>
198 * Note on method signature: since Java doesn't allow creating a generic array with {@code new T[]}, the
199 * implementation of this operator has to create an {@code Object[]} instead. Unfortunately, a
200 * {@code Function<Integer[], R>} passed to the method would trigger a {@link ClassCastException}.
201 * <p>
202 * If any of the sources never produces an item but only terminates (normally or with an error), the
203 * resulting sequence terminates immediately (normally or with all the errors accumulated till that point).
204 * If that input source is also synchronous, other sources after it will not be subscribed to.
205 * <p>
206 * If the provided iterable of {@code ObservableSource}s is empty, the resulting sequence completes immediately without emitting
207 * any items and without any calls to the combiner function.
208 *
209 * <p>
210 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/combineLatest.v3.png" alt="">
211 * <dl>
212 * <dt><b>Scheduler:</b></dt>
213 * <dd>{@code combineLatest} does not operate by default on a particular {@link Scheduler}.</dd>
214 * </dl>
215 *
216 * @param <T>
217 * the common base type of source values
218 * @param <R>
219 * the result type
220 * @param sources
221 * the collection of source {@code ObservableSource}s
222 * @param combiner
223 * the aggregation function used to combine the items emitted by the returned {@code ObservableSource}s
224 * @return the new {@code Observable} instance
225 * @throws NullPointerException if {@code sources} or {@code combiner} is {@code null}
226 * @see <a href="http://reactivex.io/documentation/operators/combinelatest.html">ReactiveX operators documentation: CombineLatest</a>
227 */
228 @CheckReturnValue
229 @SchedulerSupport(SchedulerSupport.NONE)
230 @NonNull
231 public static <@NonNull T, @NonNull R> Observable<R> combineLatest(
232 @NonNull Iterable<@NonNull ? extends ObservableSource<? extends T>> sources,
233 @NonNull Function<? super Object[], ? extends R> combiner) {
234 return combineLatest(sources, combiner, bufferSize());
235 }
236
237 /**
238 * Combines an {@link Iterable} of source {@link ObservableSource}s by emitting an item that aggregates the latest values of each of
239 * the returned {@code ObservableSource}s each time an item is received from any of the returned {@code ObservableSource}s, where this
240 * aggregation is defined by a specified function.
241 * <p>
242 * Note on method signature: since Java doesn't allow creating a generic array with {@code new T[]}, the
243 * implementation of this operator has to create an {@code Object[]} instead. Unfortunately, a
244 * {@code Function<Integer[], R>} passed to the method would trigger a {@link ClassCastException}.
245 * <p>
246 * If any of the sources never produces an item but only terminates (normally or with an error), the
247 * resulting sequence terminates immediately (normally or with all the errors accumulated till that point).
248 * If that input source is also synchronous, other sources after it will not be subscribed to.
249 * <p>
250 * If the provided {@code Iterable} of {@code ObservableSource}s is empty, the resulting sequence completes immediately without emitting
251 * any items and without any calls to the combiner function.
252 *
253 * <p>
254 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/combineLatest.v3.png" alt="">
255 * <dl>
256 * <dt><b>Scheduler:</b></dt>
257 * <dd>{@code combineLatest} does not operate by default on a particular {@link Scheduler}.</dd>
258 * </dl>
259 *
260 * @param <T>
261 * the common base type of source values
262 * @param <R>
263 * the result type
264 * @param sources
265 * the collection of source {@code ObservableSource}s
266 * @param combiner
267 * the aggregation function used to combine the items emitted by the returned {@code ObservableSource}s
268 * @param bufferSize
269 * the expected number of row combination items to be buffered internally
270 * @return the new {@code Observable} instance
271 * @throws NullPointerException if {@code sources} or {@code combiner} is {@code null}
272 * @throws IllegalArgumentException if {@code bufferSize} is non-positive
273 * @see <a href="http://reactivex.io/documentation/operators/combinelatest.html">ReactiveX operators documentation: CombineLatest</a>
274 */
275 @CheckReturnValue
276 @NonNull
277 @SchedulerSupport(SchedulerSupport.NONE)
278 public static <@NonNull T, @NonNull R> Observable<R> combineLatest(
279 @NonNull Iterable<@NonNull ? extends ObservableSource<? extends T>> sources,
280 @NonNull Function<? super Object[], ? extends R> combiner, int bufferSize) {
281 Objects.requireNonNull(sources, "sources is null");
282 Objects.requireNonNull(combiner, "combiner is null");
283 ObjectHelper.verifyPositive(bufferSize, "bufferSize");
284
285 // the queue holds a pair of values so we need to double the capacity
286 int s = bufferSize << 1;
287 return RxJavaPlugins.onAssembly(new ObservableCombineLatest<>(null, sources, combiner, s, false));
288 }
289
290 /**
291 * Combines an array of source {@link ObservableSource}s by emitting an item that aggregates the latest values of each of
292 * the {@code ObservableSource}s each time an item is received from any of the returned {@code ObservableSource}s, where this
293 * aggregation is defined by a specified function.
294 * <p>
295 * Note on method signature: since Java doesn't allow creating a generic array with {@code new T[]}, the
296 * implementation of this operator has to create an {@code Object[]} instead. Unfortunately, a
297 * {@code Function<Integer[], R>} passed to the method would trigger a {@link ClassCastException}.
298 * <p>
299 * If any of the sources never produces an item but only terminates (normally or with an error), the
300 * resulting sequence terminates immediately (normally or with all the errors accumulated till that point).
301 * If that input source is also synchronous, other sources after it will not be subscribed to.
302 * <p>
303 * If the provided array of {@code ObservableSource}s is empty, the resulting sequence completes immediately without emitting
304 * any items and without any calls to the combiner function.
305 *
306 * <p>
307 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/combineLatest.v3.png" alt="">
308 * <dl>
309 * <dt><b>Scheduler:</b></dt>
310 * <dd>{@code combineLatestArray} does not operate by default on a particular {@link Scheduler}.</dd>
311 * </dl>
312 *
313 * @param <T>
314 * the common base type of source values
315 * @param <R>
316 * the result type
317 * @param sources
318 * the collection of source {@code ObservableSource}s
319 * @param combiner
320 * the aggregation function used to combine the items emitted by the {@code ObservableSource}s
321 * @return the new {@code Observable} instance
322 * @throws NullPointerException if {@code sources} or {@code combiner} is {@code null}
323 * @see <a href="http://reactivex.io/documentation/operators/combinelatest.html">ReactiveX operators documentation: CombineLatest</a>
324 */
325 @CheckReturnValue
326 @SchedulerSupport(SchedulerSupport.NONE)
327 @NonNull
328 public static <@NonNull T, @NonNull R> Observable<R> combineLatestArray(
329 @NonNull ObservableSource<? extends T>[] sources,
330 @NonNull Function<? super Object[], ? extends R> combiner) {
331 return combineLatestArray(sources, combiner, bufferSize());
332 }
333
334 /**
335 * Combines an array of source {@link ObservableSource}s by emitting an item that aggregates the latest values of each of
336 * the {@code ObservableSource}s each time an item is received from any of the {@code ObservableSource}s, where this
337 * aggregation is defined by a specified function.
338 * <p>
339 * Note on method signature: since Java doesn't allow creating a generic array with {@code new T[]}, the
340 * implementation of this operator has to create an {@code Object[]} instead. Unfortunately, a
341 * {@code Function<Integer[], R>} passed to the method would trigger a {@link ClassCastException}.
342 * <p>
343 * If any of the sources never produces an item but only terminates (normally or with an error), the
344 * resulting sequence terminates immediately (normally or with all the errors accumulated till that point).
345 * If that input source is also synchronous, other sources after it will not be subscribed to.
346 * <p>
347 * If the provided array of {@code ObservableSource}s is empty, the resulting sequence completes immediately without emitting
348 * any items and without any calls to the combiner function.
349 *
350 * <p>
351 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/combineLatest.v3.png" alt="">
352 * <dl>
353 * <dt><b>Scheduler:</b></dt>
354 * <dd>{@code combineLatestArray} does not operate by default on a particular {@link Scheduler}.</dd>
355 * </dl>
356 *
357 * @param <T>
358 * the common base type of source values
359 * @param <R>
360 * the result type
361 * @param sources
362 * the collection of source {@code ObservableSource}s
363 * @param combiner
364 * the aggregation function used to combine the items emitted by the {@code ObservableSource}s
365 * @param bufferSize
366 * the expected number of row combination items to be buffered internally
367 * @return the new {@code Observable} instance
368 * @throws NullPointerException if {@code sources} or {@code combiner} is {@code null}
369 * @throws IllegalArgumentException if {@code bufferSize} is non-positive
370 * @see <a href="http://reactivex.io/documentation/operators/combinelatest.html">ReactiveX operators documentation: CombineLatest</a>
371 */
372 @CheckReturnValue
373 @NonNull
374 @SchedulerSupport(SchedulerSupport.NONE)
375 public static <@NonNull T, @NonNull R> Observable<R> combineLatestArray(
376 @NonNull ObservableSource<? extends T>[] sources,
377 @NonNull Function<? super Object[], ? extends R> combiner, int bufferSize) {
378 Objects.requireNonNull(sources, "sources is null");
379 if (sources.length == 0) {
380 return empty();
381 }
382 Objects.requireNonNull(combiner, "combiner is null");
383 ObjectHelper.verifyPositive(bufferSize, "bufferSize");
384
385 // the queue holds a pair of values so we need to double the capacity
386 int s = bufferSize << 1;
387 return RxJavaPlugins.onAssembly(new ObservableCombineLatest<>(sources, null, combiner, s, false));
388 }
389
390 /**
391 * Combines two source {@link ObservableSource}s by emitting an item that aggregates the latest values of each of the
392 * {@code ObservableSource}s each time an item is received from either of the {@code ObservableSource}s, where this
393 * aggregation is defined by a specified function.
394 * <p>
395 * If any of the sources never produces an item but only terminates (normally or with an error), the
396 * resulting sequence terminates immediately (normally or with all the errors accumulated till that point).
397 * If that input source is also synchronous, other sources after it will not be subscribed to.
398 * <p>
399 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/combineLatest.v3.png" alt="">
400 * <dl>
401 * <dt><b>Scheduler:</b></dt>
402 * <dd>{@code combineLatest} does not operate by default on a particular {@link Scheduler}.</dd>
403 * </dl>
404 *
405 * @param <T1> the element type of the first source
406 * @param <T2> the element type of the second source
407 * @param <R> the combined output type
408 * @param source1
409 * the first source {@code ObservableSource}
410 * @param source2
411 * the second source {@code ObservableSource}
412 * @param combiner
413 * the aggregation function used to combine the items emitted by the {@code ObservableSource}s
414 * @return the new {@code Observable} instance
415 * @throws NullPointerException if {@code source1}, {@code source2} or {@code combiner} is {@code null}
416 * @see <a href="http://reactivex.io/documentation/operators/combinelatest.html">ReactiveX operators documentation: CombineLatest</a>
417 */
418 @SuppressWarnings("unchecked")
419 @CheckReturnValue
420 @NonNull
421 @SchedulerSupport(SchedulerSupport.NONE)
422 public static <@NonNull T1, @NonNull T2, @NonNull R> Observable<R> combineLatest(
423 @NonNull ObservableSource<? extends T1> source1, @NonNull ObservableSource<? extends T2> source2,
424 @NonNull BiFunction<? super T1, ? super T2, ? extends R> combiner) {
425 Objects.requireNonNull(source1, "source1 is null");
426 Objects.requireNonNull(source2, "source2 is null");
427 Objects.requireNonNull(combiner, "combiner is null");
428 return combineLatestArray(new ObservableSource[] { source1, source2 }, Functions.toFunction(combiner), bufferSize());
429 }
430
431 /**
432 * Combines three source {@link ObservableSource}s by emitting an item that aggregates the latest values of each of the
433 * {@code ObservableSource}s each time an item is received from any of the {@code ObservableSource}s, where this
434 * aggregation is defined by a specified function.
435 * <p>
436 * If any of the sources never produces an item but only terminates (normally or with an error), the
437 * resulting sequence terminates immediately (normally or with all the errors accumulated till that point).
438 * If that input source is also synchronous, other sources after it will not be subscribed to.
439 * <p>
440 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/combineLatest.v3.png" alt="">
441 * <dl>
442 * <dt><b>Scheduler:</b></dt>
443 * <dd>{@code combineLatest} does not operate by default on a particular {@link Scheduler}.</dd>
444 * </dl>
445 *
446 * @param <T1> the element type of the first source
447 * @param <T2> the element type of the second source
448 * @param <T3> the element type of the third source
449 * @param <R> the combined output type
450 * @param source1
451 * the first source {@code ObservableSource}
452 * @param source2
453 * the second source {@code ObservableSource}
454 * @param source3
455 * the third source {@code ObservableSource}
456 * @param combiner
457 * the aggregation function used to combine the items emitted by the {@code ObservableSource}s
458 * @return the new {@code Observable} instance
459 * @throws NullPointerException if {@code source1}, {@code source2}, {@code source3} or {@code combiner} is {@code null}
460 * @see <a href="http://reactivex.io/documentation/operators/combinelatest.html">ReactiveX operators documentation: CombineLatest</a>
461 */
462 @SuppressWarnings("unchecked")
463 @CheckReturnValue
464 @NonNull
465 @SchedulerSupport(SchedulerSupport.NONE)
466 public static <@NonNull T1, @NonNull T2, @NonNull T3, @NonNull R> Observable<R> combineLatest(
467 @NonNull ObservableSource<? extends T1> source1, @NonNull ObservableSource<? extends T2> source2,
468 @NonNull ObservableSource<? extends T3> source3,
469 @NonNull Function3<? super T1, ? super T2, ? super T3, ? extends R> combiner) {
470 Objects.requireNonNull(source1, "source1 is null");
471 Objects.requireNonNull(source2, "source2 is null");
472 Objects.requireNonNull(source3, "source3 is null");
473 Objects.requireNonNull(combiner, "combiner is null");
474 return combineLatestArray(new ObservableSource[] { source1, source2, source3 }, Functions.toFunction(combiner), bufferSize());
475 }
476
477 /**
478 * Combines four source {@link ObservableSource}s by emitting an item that aggregates the latest values of each of the
479 * {@code ObservableSource}s each time an item is received from any of the {@code ObservableSource}s, where this
480 * aggregation is defined by a specified function.
481 * <p>
482 * If any of the sources never produces an item but only terminates (normally or with an error), the
483 * resulting sequence terminates immediately (normally or with all the errors accumulated till that point).
484 * If that input source is also synchronous, other sources after it will not be subscribed to.
485 * <p>
486 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/combineLatest.v3.png" alt="">
487 * <dl>
488 * <dt><b>Scheduler:</b></dt>
489 * <dd>{@code combineLatest} does not operate by default on a particular {@link Scheduler}.</dd>
490 * </dl>
491 *
492 * @param <T1> the element type of the first source
493 * @param <T2> the element type of the second source
494 * @param <T3> the element type of the third source
495 * @param <T4> the element type of the fourth source
496 * @param <R> the combined output type
497 * @param source1
498 * the first source {@code ObservableSource}
499 * @param source2
500 * the second source {@code ObservableSource}
501 * @param source3
502 * the third source {@code ObservableSource}
503 * @param source4
504 * the fourth source {@code ObservableSource}
505 * @param combiner
506 * the aggregation function used to combine the items emitted by the {@code ObservableSource}s
507 * @return the new {@code Observable} instance
508 * @throws NullPointerException if {@code source1}, {@code source2}, {@code source3},
509 * {@code source4} or {@code combiner} is {@code null}
510 * @see <a href="http://reactivex.io/documentation/operators/combinelatest.html">ReactiveX operators documentation: CombineLatest</a>
511 */
512 @SuppressWarnings("unchecked")
513 @CheckReturnValue
514 @NonNull
515 @SchedulerSupport(SchedulerSupport.NONE)
516 public static <@NonNull T1, @NonNull T2, @NonNull T3, @NonNull T4, @NonNull R> Observable<R> combineLatest(
517 @NonNull ObservableSource<? extends T1> source1, @NonNull ObservableSource<? extends T2> source2,
518 @NonNull ObservableSource<? extends T3> source3, @NonNull ObservableSource<? extends T4> source4,
519 @NonNull Function4<? super T1, ? super T2, ? super T3, ? super T4, ? extends R> combiner) {
520 Objects.requireNonNull(source1, "source1 is null");
521 Objects.requireNonNull(source2, "source2 is null");
522 Objects.requireNonNull(source3, "source3 is null");
523 Objects.requireNonNull(source4, "source4 is null");
524 Objects.requireNonNull(combiner, "combiner is null");
525 return combineLatestArray(new ObservableSource[] { source1, source2, source3, source4 }, Functions.toFunction(combiner), bufferSize());
526 }
527
528 /**
529 * Combines five source {@link ObservableSource}s by emitting an item that aggregates the latest values of each of the
530 * {@code ObservableSource}s each time an item is received from any of the {@code ObservableSource}s, where this
531 * aggregation is defined by a specified function.
532 * <p>
533 * If any of the sources never produces an item but only terminates (normally or with an error), the
534 * resulting sequence terminates immediately (normally or with all the errors accumulated till that point).
535 * If that input source is also synchronous, other sources after it will not be subscribed to.
536 * <p>
537 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/combineLatest.v3.png" alt="">
538 * <dl>
539 * <dt><b>Scheduler:</b></dt>
540 * <dd>{@code combineLatest} does not operate by default on a particular {@link Scheduler}.</dd>
541 * </dl>
542 *
543 * @param <T1> the element type of the first source
544 * @param <T2> the element type of the second source
545 * @param <T3> the element type of the third source
546 * @param <T4> the element type of the fourth source
547 * @param <T5> the element type of the fifth source
548 * @param <R> the combined output type
549 * @param source1
550 * the first source {@code ObservableSource}
551 * @param source2
552 * the second source {@code ObservableSource}
553 * @param source3
554 * the third source {@code ObservableSource}
555 * @param source4
556 * the fourth source {@code ObservableSource}
557 * @param source5
558 * the fifth source {@code ObservableSource}
559 * @param combiner
560 * the aggregation function used to combine the items emitted by the {@code ObservableSource}s
561 * @return the new {@code Observable} instance
562 * @throws NullPointerException if {@code source1}, {@code source2}, {@code source3},
563 * {@code source4}, {@code source5} or {@code combiner} is {@code null}
564 * @see <a href="http://reactivex.io/documentation/operators/combinelatest.html">ReactiveX operators documentation: CombineLatest</a>
565 */
566 @SuppressWarnings("unchecked")
567 @CheckReturnValue
568 @NonNull
569 @SchedulerSupport(SchedulerSupport.NONE)
570 public static <@NonNull T1, @NonNull T2, @NonNull T3, @NonNull T4, @NonNull T5, @NonNull R> Observable<R> combineLatest(
571 @NonNull ObservableSource<? extends T1> source1, @NonNull ObservableSource<? extends T2> source2,
572 @NonNull ObservableSource<? extends T3> source3, @NonNull ObservableSource<? extends T4> source4,
573 @NonNull ObservableSource<? extends T5> source5,
574 @NonNull Function5<? super T1, ? super T2, ? super T3, ? super T4, ? super T5, ? extends R> combiner) {
575 Objects.requireNonNull(source1, "source1 is null");
576 Objects.requireNonNull(source2, "source2 is null");
577 Objects.requireNonNull(source3, "source3 is null");
578 Objects.requireNonNull(source4, "source4 is null");
579 Objects.requireNonNull(source5, "source5 is null");
580 Objects.requireNonNull(combiner, "combiner is null");
581 return combineLatestArray(new ObservableSource[] { source1, source2, source3, source4, source5 }, Functions.toFunction(combiner), bufferSize());
582 }
583
584 /**
585 * Combines six source {@link ObservableSource}s by emitting an item that aggregates the latest values of each of the
586 * {@code ObservableSource}s each time an item is received from any of the {@code ObservableSource}s, where this
587 * aggregation is defined by a specified function.
588 * <p>
589 * If any of the sources never produces an item but only terminates (normally or with an error), the
590 * resulting sequence terminates immediately (normally or with all the errors accumulated till that point).
591 * If that input source is also synchronous, other sources after it will not be subscribed to.
592 * <p>
593 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/combineLatest.v3.png" alt="">
594 * <dl>
595 * <dt><b>Scheduler:</b></dt>
596 * <dd>{@code combineLatest} does not operate by default on a particular {@link Scheduler}.</dd>
597 * </dl>
598 *
599 * @param <T1> the element type of the first source
600 * @param <T2> the element type of the second source
601 * @param <T3> the element type of the third source
602 * @param <T4> the element type of the fourth source
603 * @param <T5> the element type of the fifth source
604 * @param <T6> the element type of the sixth source
605 * @param <R> the combined output type
606 * @param source1
607 * the first source {@code ObservableSource}
608 * @param source2
609 * the second source {@code ObservableSource}
610 * @param source3
611 * the third source {@code ObservableSource}
612 * @param source4
613 * the fourth source {@code ObservableSource}
614 * @param source5
615 * the fifth source {@code ObservableSource}
616 * @param source6
617 * the sixth source {@code ObservableSource}
618 * @param combiner
619 * the aggregation function used to combine the items emitted by the {@code ObservableSource}s
620 * @return the new {@code Observable} instance
621 * @throws NullPointerException if {@code source1}, {@code source2}, {@code source3},
622 * {@code source4}, {@code source5}, {@code source6} or {@code combiner} is {@code null}
623 * @see <a href="http://reactivex.io/documentation/operators/combinelatest.html">ReactiveX operators documentation: CombineLatest</a>
624 */
625 @SuppressWarnings("unchecked")
626 @CheckReturnValue
627 @NonNull
628 @SchedulerSupport(SchedulerSupport.NONE)
629 public static <@NonNull T1, @NonNull T2, @NonNull T3, @NonNull T4, @NonNull T5, @NonNull T6, @NonNull R> Observable<R> combineLatest(
630 @NonNull ObservableSource<? extends T1> source1, @NonNull ObservableSource<? extends T2> source2,
631 @NonNull ObservableSource<? extends T3> source3, @NonNull ObservableSource<? extends T4> source4,
632 @NonNull ObservableSource<? extends T5> source5, @NonNull ObservableSource<? extends T6> source6,
633 @NonNull Function6<? super T1, ? super T2, ? super T3, ? super T4, ? super T5, ? super T6, ? extends R> combiner) {
634 Objects.requireNonNull(source1, "source1 is null");
635 Objects.requireNonNull(source2, "source2 is null");
636 Objects.requireNonNull(source3, "source3 is null");
637 Objects.requireNonNull(source4, "source4 is null");
638 Objects.requireNonNull(source5, "source5 is null");
639 Objects.requireNonNull(source6, "source6 is null");
640 Objects.requireNonNull(combiner, "combiner is null");
641 return combineLatestArray(new ObservableSource[] { source1, source2, source3, source4, source5, source6 }, Functions.toFunction(combiner), bufferSize());
642 }
643
644 /**
645 * Combines seven source {@link ObservableSource}s by emitting an item that aggregates the latest values of each of the
646 * {@code ObservableSource}s each time an item is received from any of the {@code ObservableSource}s, where this
647 * aggregation is defined by a specified function.
648 * <p>
649 * If any of the sources never produces an item but only terminates (normally or with an error), the
650 * resulting sequence terminates immediately (normally or with all the errors accumulated till that point).
651 * If that input source is also synchronous, other sources after it will not be subscribed to.
652 * <p>
653 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/combineLatest.v3.png" alt="">
654 * <dl>
655 * <dt><b>Scheduler:</b></dt>
656 * <dd>{@code combineLatest} does not operate by default on a particular {@link Scheduler}.</dd>
657 * </dl>
658 *
659 * @param <T1> the element type of the first source
660 * @param <T2> the element type of the second source
661 * @param <T3> the element type of the third source
662 * @param <T4> the element type of the fourth source
663 * @param <T5> the element type of the fifth source
664 * @param <T6> the element type of the sixth source
665 * @param <T7> the element type of the seventh source
666 * @param <R> the combined output type
667 * @param source1
668 * the first source {@code ObservableSource}
669 * @param source2
670 * the second source {@code ObservableSource}
671 * @param source3
672 * the third source {@code ObservableSource}
673 * @param source4
674 * the fourth source {@code ObservableSource}
675 * @param source5
676 * the fifth source {@code ObservableSource}
677 * @param source6
678 * the sixth source {@code ObservableSource}
679 * @param source7
680 * the seventh source {@code ObservableSource}
681 * @param combiner
682 * the aggregation function used to combine the items emitted by the {@code ObservableSource}s
683 * @return the new {@code Observable} instance
684 * @throws NullPointerException if {@code source1}, {@code source2}, {@code source3},
685 * {@code source4}, {@code source5}, {@code source6},
686 * {@code source7} 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 @NonNull
692 @SchedulerSupport(SchedulerSupport.NONE)
693 public static <@NonNull T1, @NonNull T2, @NonNull T3, @NonNull T4, @NonNull T5, @NonNull T6, @NonNull T7, @NonNull R> Observable<R> combineLatest(
694 @NonNull ObservableSource<? extends T1> source1, @NonNull ObservableSource<? extends T2> source2,
695 @NonNull ObservableSource<? extends T3> source3, @NonNull ObservableSource<? extends T4> source4,
696 @NonNull ObservableSource<? extends T5> source5, @NonNull ObservableSource<? extends T6> source6,
697 @NonNull ObservableSource<? extends T7> source7,
698 @NonNull Function7<? super T1, ? super T2, ? super T3, ? super T4, ? super T5, ? super T6, ? super T7, ? extends R> combiner) {
699 Objects.requireNonNull(source1, "source1 is null");
700 Objects.requireNonNull(source2, "source2 is null");
701 Objects.requireNonNull(source3, "source3 is null");
702 Objects.requireNonNull(source4, "source4 is null");
703 Objects.requireNonNull(source5, "source5 is null");
704 Objects.requireNonNull(source6, "source6 is null");
705 Objects.requireNonNull(source7, "source7 is null");
706 Objects.requireNonNull(combiner, "combiner is null");
707 return combineLatestArray(new ObservableSource[] { source1, source2, source3, source4, source5, source6, source7 }, Functions.toFunction(combiner), bufferSize());
708 }
709
710 /**
711 * Combines eight source {@link ObservableSource}s by emitting an item that aggregates the latest values of each of the
712 * {@code ObservableSource}s each time an item is received from any of the {@code ObservableSource}s, where this
713 * aggregation is defined by a specified function.
714 * <p>
715 * If any of the sources never produces an item but only terminates (normally or with an error), the
716 * resulting sequence terminates immediately (normally or with all the errors accumulated till that point).
717 * If that input source is also synchronous, other sources after it will not be subscribed to.
718 * <p>
719 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/combineLatest.v3.png" alt="">
720 * <dl>
721 * <dt><b>Scheduler:</b></dt>
722 * <dd>{@code combineLatest} does not operate by default on a particular {@link Scheduler}.</dd>
723 * </dl>
724 *
725 * @param <T1> the element type of the first source
726 * @param <T2> the element type of the second source
727 * @param <T3> the element type of the third source
728 * @param <T4> the element type of the fourth source
729 * @param <T5> the element type of the fifth source
730 * @param <T6> the element type of the sixth source
731 * @param <T7> the element type of the seventh source
732 * @param <T8> the element type of the eighth source
733 * @param <R> the combined output type
734 * @param source1
735 * the first source {@code ObservableSource}
736 * @param source2
737 * the second source {@code ObservableSource}
738 * @param source3
739 * the third source {@code ObservableSource}
740 * @param source4
741 * the fourth source {@code ObservableSource}
742 * @param source5
743 * the fifth source {@code ObservableSource}
744 * @param source6
745 * the sixth source {@code ObservableSource}
746 * @param source7
747 * the seventh source {@code ObservableSource}
748 * @param source8
749 * the eighth source {@code ObservableSource}
750 * @param combiner
751 * the aggregation function used to combine the items emitted by the {@code ObservableSource}s
752 * @return the new {@code Observable} instance
753 * @throws NullPointerException if {@code source1}, {@code source2}, {@code source3},
754 * {@code source4}, {@code source5}, {@code source6},
755 * {@code source7}, {@code source8} or {@code combiner} is {@code null}
756 * @see <a href="http://reactivex.io/documentation/operators/combinelatest.html">ReactiveX operators documentation: CombineLatest</a>
757 */
758 @SuppressWarnings("unchecked")
759 @CheckReturnValue
760 @NonNull
761 @SchedulerSupport(SchedulerSupport.NONE)
762 public static <@NonNull T1, @NonNull T2, @NonNull T3, @NonNull T4, @NonNull T5, @NonNull T6, @NonNull T7, @NonNull T8, @NonNull R> Observable<R> combineLatest(
763 @NonNull ObservableSource<? extends T1> source1, @NonNull ObservableSource<? extends T2> source2,
764 @NonNull ObservableSource<? extends T3> source3, @NonNull ObservableSource<? extends T4> source4,
765 @NonNull ObservableSource<? extends T5> source5, @NonNull ObservableSource<? extends T6> source6,
766 @NonNull ObservableSource<? extends T7> source7, @NonNull ObservableSource<? extends T8> source8,
767 @NonNull Function8<? super T1, ? super T2, ? super T3, ? super T4, ? super T5, ? super T6, ? super T7, ? super T8, ? extends R> combiner) {
768 Objects.requireNonNull(source1, "source1 is null");
769 Objects.requireNonNull(source2, "source2 is null");
770 Objects.requireNonNull(source3, "source3 is null");
771 Objects.requireNonNull(source4, "source4 is null");
772 Objects.requireNonNull(source5, "source5 is null");
773 Objects.requireNonNull(source6, "source6 is null");
774 Objects.requireNonNull(source7, "source7 is null");
775 Objects.requireNonNull(source8, "source8 is null");
776 Objects.requireNonNull(combiner, "combiner is null");
777 return combineLatestArray(new ObservableSource[] { source1, source2, source3, source4, source5, source6, source7, source8 }, Functions.toFunction(combiner), bufferSize());
778 }
779
780 /**
781 * Combines nine source {@link ObservableSource}s by emitting an item that aggregates the latest values of each of the
782 * {@code ObservableSource}s each time an item is received from any of the {@code ObservableSource}s, where this
783 * aggregation is defined by a specified function.
784 * <p>
785 * If any of the sources never produces an item but only terminates (normally or with an error), the
786 * resulting sequence terminates immediately (normally or with all the errors accumulated till that point).
787 * If that input source is also synchronous, other sources after it will not be subscribed to.
788 * <p>
789 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/combineLatest.v3.png" alt="">
790 * <dl>
791 * <dt><b>Scheduler:</b></dt>
792 * <dd>{@code combineLatest} does not operate by default on a particular {@link Scheduler}.</dd>
793 * </dl>
794 *
795 * @param <T1> the element type of the first source
796 * @param <T2> the element type of the second source
797 * @param <T3> the element type of the third source
798 * @param <T4> the element type of the fourth source
799 * @param <T5> the element type of the fifth source
800 * @param <T6> the element type of the sixth source
801 * @param <T7> the element type of the seventh source
802 * @param <T8> the element type of the eighth source
803 * @param <T9> the element type of the ninth source
804 * @param <R> the combined output type
805 * @param source1
806 * the first source {@code ObservableSource}
807 * @param source2
808 * the second source {@code ObservableSource}
809 * @param source3
810 * the third source {@code ObservableSource}
811 * @param source4
812 * the fourth source {@code ObservableSource}
813 * @param source5
814 * the fifth source {@code ObservableSource}
815 * @param source6
816 * the sixth source {@code ObservableSource}
817 * @param source7
818 * the seventh source {@code ObservableSource}
819 * @param source8
820 * the eighth source {@code ObservableSource}
821 * @param source9
822 * the ninth source {@code ObservableSource}
823 * @param combiner
824 * the aggregation function used to combine the items emitted by the {@code ObservableSource}s
825 * @return the new {@code Observable} instance
826 * @throws NullPointerException if {@code source1}, {@code source2}, {@code source3},
827 * {@code source4}, {@code source5}, {@code source6},
828 * {@code source7}, {@code source8}, {@code source9} or {@code combiner} is {@code null}
829 * @see <a href="http://reactivex.io/documentation/operators/combinelatest.html">ReactiveX operators documentation: CombineLatest</a>
830 */
831 @SuppressWarnings("unchecked")
832 @CheckReturnValue
833 @NonNull
834 @SchedulerSupport(SchedulerSupport.NONE)
835 public static <@NonNull T1, @NonNull T2, @NonNull T3, @NonNull T4, @NonNull T5, @NonNull T6, @NonNull T7, @NonNull T8, @NonNull T9, @NonNull R> Observable<R> combineLatest(
836 @NonNull ObservableSource<? extends T1> source1, @NonNull ObservableSource<? extends T2> source2,
837 @NonNull ObservableSource<? extends T3> source3, @NonNull ObservableSource<? extends T4> source4,
838 @NonNull ObservableSource<? extends T5> source5, @NonNull ObservableSource<? extends T6> source6,
839 @NonNull ObservableSource<? extends T7> source7, @NonNull ObservableSource<? extends T8> source8,
840 @NonNull ObservableSource<? extends T9> source9,
841 @NonNull Function9<? super T1, ? super T2, ? super T3, ? super T4, ? super T5, ? super T6, ? super T7, ? super T8, ? super T9, ? extends R> combiner) {
842 Objects.requireNonNull(source1, "source1 is null");
843 Objects.requireNonNull(source2, "source2 is null");
844 Objects.requireNonNull(source3, "source3 is null");
845 Objects.requireNonNull(source4, "source4 is null");
846 Objects.requireNonNull(source5, "source5 is null");
847 Objects.requireNonNull(source6, "source6 is null");
848 Objects.requireNonNull(source7, "source7 is null");
849 Objects.requireNonNull(source8, "source8 is null");
850 Objects.requireNonNull(source9, "source9 is null");
851 Objects.requireNonNull(combiner, "combiner is null");
852 return combineLatestArray(new ObservableSource[] { source1, source2, source3, source4, source5, source6, source7, source8, source9 }, Functions.toFunction(combiner), bufferSize());
853 }
854
855 /**
856 * Combines an array of {@link ObservableSource}s by emitting an item that aggregates the latest values of each of
857 * the {@code ObservableSource}s each time an item is received from any of the {@code ObservableSource}s, where this
858 * aggregation is defined by a specified function.
859 * <p>
860 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/combineLatestDelayError.v3.png" alt="">
861 * <p>
862 * Note on method signature: since Java doesn't allow creating a generic array with {@code new T[]}, the
863 * implementation of this operator has to create an {@code Object[]} instead. Unfortunately, a
864 * {@code Function<Integer[], R>} passed to the method would trigger a {@link ClassCastException}.
865 * <p>
866 * If any of the sources never produces an item but only terminates (normally or with an error), the
867 * resulting sequence terminates immediately (normally or with all the errors accumulated till that point).
868 * If that input source is also synchronous, other sources after it will not be subscribed to.
869 * <p>
870 * If the provided array of {@code ObservableSource}s is empty, the resulting sequence completes immediately without emitting
871 * any items and without any calls to the combiner function.
872 *
873 * <dl>
874 * <dt><b>Scheduler:</b></dt>
875 * <dd>{@code combineLatestArrayDelayError} does not operate by default on a particular {@link Scheduler}.</dd>
876 * </dl>
877 *
878 * @param <T>
879 * the common base type of source values
880 * @param <R>
881 * the result type
882 * @param sources
883 * the collection of source {@code ObservableSource}s
884 * @param combiner
885 * the aggregation function used to combine the items emitted by the {@code ObservableSource}s
886 * @return the new {@code Observable} instance
887 * @throws NullPointerException if {@code sources} or {@code combiner} is {@code null}
888 * @see <a href="http://reactivex.io/documentation/operators/combinelatest.html">ReactiveX operators documentation: CombineLatest</a>
889 */
890 @CheckReturnValue
891 @SchedulerSupport(SchedulerSupport.NONE)
892 @NonNull
893 public static <@NonNull T, @NonNull R> Observable<R> combineLatestArrayDelayError(
894 @NonNull ObservableSource<? extends T>[] sources,
895 @NonNull Function<? super Object[], ? extends R> combiner) {
896 return combineLatestArrayDelayError(sources, combiner, bufferSize());
897 }
898
899 /**
900 * Combines an array of {@link ObservableSource}s by emitting an item that aggregates the latest values of each of
901 * the {@code ObservableSource}s each time an item is received from any of the {@code ObservableSource}s, where this
902 * aggregation is defined by a specified function and delays any error from the sources until
903 * all source {@code ObservableSource}s terminate.
904 * <p>
905 * Note on method signature: since Java doesn't allow creating a generic array with {@code new T[]}, the
906 * implementation of this operator has to create an {@code Object[]} instead. Unfortunately, a
907 * {@code Function<Integer[], R>} passed to the method would trigger a {@link ClassCastException}.
908 * <p>
909 * If any of the sources never produces an item but only terminates (normally or with an error), the
910 * resulting sequence terminates immediately (normally or with all the errors accumulated till that point).
911 * If that input source is also synchronous, other sources after it will not be subscribed to.
912 * <p>
913 * If the provided array of {@code ObservableSource}s is empty, the resulting sequence completes immediately without emitting
914 * any items and without any calls to the combiner function.
915 *
916 * <p>
917 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/combineLatestDelayError.v3.png" alt="">
918 * <dl>
919 * <dt><b>Scheduler:</b></dt>
920 * <dd>{@code combineLatestArrayDelayError} does not operate by default on a particular {@link Scheduler}.</dd>
921 * </dl>
922 *
923 * @param <T>
924 * the common base type of source values
925 * @param <R>
926 * the result type
927 * @param sources
928 * the collection of source {@code ObservableSource}s
929 * @param combiner
930 * the aggregation function used to combine the items emitted by the {@code ObservableSource}s
931 * @param bufferSize
932 * the expected number of row combination items to be buffered internally
933 * @return the new {@code Observable} instance
934 * @throws NullPointerException if {@code sources} or {@code combiner} is {@code null}
935 * @throws IllegalArgumentException if {@code bufferSize} is non-positive
936 * @see <a href="http://reactivex.io/documentation/operators/combinelatest.html">ReactiveX operators documentation: CombineLatest</a>
937 */
938 @CheckReturnValue
939 @NonNull
940 @SchedulerSupport(SchedulerSupport.NONE)
941 public static <@NonNull T, @NonNull R> Observable<R> combineLatestArrayDelayError(@NonNull ObservableSource<? extends T>[] sources,
942 @NonNull Function<? super Object[], ? extends R> combiner, int bufferSize) {
943 Objects.requireNonNull(sources, "sources is null");
944 Objects.requireNonNull(combiner, "combiner is null");
945 ObjectHelper.verifyPositive(bufferSize, "bufferSize");
946 if (sources.length == 0) {
947 return empty();
948 }
949 // the queue holds a pair of values so we need to double the capacity
950 int s = bufferSize << 1;
951 return RxJavaPlugins.onAssembly(new ObservableCombineLatest<>(sources, null, combiner, s, true));
952 }
953
954 /**
955 * Combines an {@link Iterable} of {@link ObservableSource}s by emitting an item that aggregates the latest values of each of
956 * the {@code ObservableSource}s each time an item is received from any of the {@code ObservableSource}s, where this
957 * aggregation is defined by a specified function and delays any error from the sources until
958 * all source {@code ObservableSource}s terminate.
959 * <p>
960 * Note on method signature: since Java doesn't allow creating a generic array with {@code new T[]}, the
961 * implementation of this operator has to create an {@code Object[]} instead. Unfortunately, a
962 * {@code Function<Integer[], R>} passed to the method would trigger a {@link ClassCastException}.
963 * <p>
964 * If any of the sources never produces an item but only terminates (normally or with an error), the
965 * resulting sequence terminates immediately (normally or with all the errors accumulated till that point).
966 * If that input source is also synchronous, other sources after it will not be subscribed to.
967 * <p>
968 * If the provided iterable of {@code ObservableSource}s is empty, the resulting sequence completes immediately without emitting
969 * any items and without any calls to the combiner function.
970 *
971 * <p>
972 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/combineLatestDelayError.v3.png" alt="">
973 * <dl>
974 * <dt><b>Scheduler:</b></dt>
975 * <dd>{@code combineLatestDelayError} does not operate by default on a particular {@link Scheduler}.</dd>
976 * </dl>
977 *
978 * @param <T>
979 * the common base type of source values
980 * @param <R>
981 * the result type
982 * @param sources
983 * the {@code Iterable} of source {@code ObservableSource}s
984 * @param combiner
985 * the aggregation function used to combine the items emitted by the {@code ObservableSource}s
986 * @return the new {@code Observable} instance
987 * @throws NullPointerException if {@code sources} or {@code combiner} is {@code null}
988 * @see <a href="http://reactivex.io/documentation/operators/combinelatest.html">ReactiveX operators documentation: CombineLatest</a>
989 */
990 @CheckReturnValue
991 @SchedulerSupport(SchedulerSupport.NONE)
992 @NonNull
993 public static <@NonNull T, @NonNull R> Observable<R> combineLatestDelayError(@NonNull Iterable<@NonNull ? extends ObservableSource<? extends T>> sources,
994 @NonNull Function<? super Object[], ? extends R> combiner) {
995 return combineLatestDelayError(sources, combiner, bufferSize());
996 }
997
998 /**
999 * Combines an {@link Iterable} of {@link ObservableSource}s by emitting an item that aggregates the latest values of each of
1000 * the {@code ObservableSource}s each time an item is received from any of the {@code ObservableSource}s, where this
1001 * aggregation is defined by a specified function and delays any error from the sources until
1002 * all source {@code ObservableSource}s terminate.
1003 * <p>
1004 * Note on method signature: since Java doesn't allow creating a generic array with {@code new T[]}, the
1005 * implementation of this operator has to create an {@code Object[]} instead. Unfortunately, a
1006 * {@code Function<Integer[], R>} passed to the method would trigger a {@link ClassCastException}.
1007 * <p>
1008 * If any of the sources never produces an item but only terminates (normally or with an error), the
1009 * resulting sequence terminates immediately (normally or with all the errors accumulated till that point).
1010 * If that input source is also synchronous, other sources after it will not be subscribed to.
1011 * <p>
1012 * If the provided iterable of {@code ObservableSource}s is empty, the resulting sequence completes immediately without emitting
1013 * any items and without any calls to the combiner function.
1014 *
1015 * <p>
1016 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/combineLatestDelayError.v3.png" alt="">
1017 * <dl>
1018 * <dt><b>Scheduler:</b></dt>
1019 * <dd>{@code combineLatestDelayError} does not operate by default on a particular {@link Scheduler}.</dd>
1020 * </dl>
1021 *
1022 * @param <T>
1023 * the common base type of source values
1024 * @param <R>
1025 * the result type
1026 * @param sources
1027 * the collection of source {@code ObservableSource}s
1028 * @param combiner
1029 * the aggregation function used to combine the items emitted by the {@code ObservableSource}s
1030 * @param bufferSize
1031 * the expected number of row combination items to be buffered internally
1032 * @return the new {@code Observable} instance
1033 * @throws NullPointerException if {@code sources} or {@code combiner} is {@code null}
1034 * @throws IllegalArgumentException if {@code bufferSize} is non-positive
1035 * @see <a href="http://reactivex.io/documentation/operators/combinelatest.html">ReactiveX operators documentation: CombineLatest</a>
1036 */
1037 @CheckReturnValue
1038 @NonNull
1039 @SchedulerSupport(SchedulerSupport.NONE)
1040 public static <@NonNull T, @NonNull R> Observable<R> combineLatestDelayError(@NonNull Iterable<@NonNull ? extends ObservableSource<? extends T>> sources,
1041 @NonNull Function<? super Object[], ? extends R> combiner, int bufferSize) {
1042 Objects.requireNonNull(sources, "sources is null");
1043 Objects.requireNonNull(combiner, "combiner is null");
1044 ObjectHelper.verifyPositive(bufferSize, "bufferSize");
1045
1046 // the queue holds a pair of values so we need to double the capacity
1047 int s = bufferSize << 1;
1048 return RxJavaPlugins.onAssembly(new ObservableCombineLatest<>(null, sources, combiner, s, true));
1049 }
1050
1051 /**
1052 * Concatenates elements of each {@link ObservableSource} provided via an {@link Iterable} sequence into a single sequence
1053 * of elements without interleaving them.
1054 * <p>
1055 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/concat.v3.png" alt="">
1056 * <dl>
1057 * <dt><b>Scheduler:</b></dt>
1058 * <dd>{@code concat} does not operate by default on a particular {@link Scheduler}.</dd>
1059 * </dl>
1060 * @param <T> the common value type of the sources
1061 * @param sources the {@code Iterable} sequence of {@code ObservableSource}s
1062 * @return the new {@code Observable} instance
1063 * @throws NullPointerException if {@code sources} is {@code null}
1064 */
1065 @SuppressWarnings({ "unchecked", "rawtypes" })
1066 @CheckReturnValue
1067 @NonNull
1068 @SchedulerSupport(SchedulerSupport.NONE)
1069 public static <@NonNull T> Observable<T> concat(@NonNull Iterable<@NonNull ? extends ObservableSource<? extends T>> sources) {
1070 Objects.requireNonNull(sources, "sources is null");
1071 return fromIterable(sources).concatMapDelayError((Function)Functions.identity(), false, bufferSize());
1072 }
1073
1074 /**
1075 * Returns an {@code Observable} that emits the items emitted by each of the {@link ObservableSource}s emitted by the
1076 * {@code ObservableSource}, one after the other, without interleaving them.
1077 * <p>
1078 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/concat.v3.png" alt="">
1079 * <dl>
1080 * <dt><b>Scheduler:</b></dt>
1081 * <dd>{@code concat} does not operate by default on a particular {@link Scheduler}.</dd>
1082 * </dl>
1083 *
1084 * @param <T> the common element base type
1085 * @param sources
1086 * an {@code ObservableSource} that emits {@code ObservableSource}s
1087 * @return the new {@code Observable} instance
1088 * @throws NullPointerException if {@code sources} is {@code null}
1089 * @see <a href="http://reactivex.io/documentation/operators/concat.html">ReactiveX operators documentation: Concat</a>
1090 */
1091 @CheckReturnValue
1092 @SchedulerSupport(SchedulerSupport.NONE)
1093 @NonNull
1094 public static <@NonNull T> Observable<T> concat(@NonNull ObservableSource<? extends ObservableSource<? extends T>> sources) {
1095 return concat(sources, bufferSize());
1096 }
1097
1098 /**
1099 * Returns an {@code Observable} that emits the items emitted by each of the {@link ObservableSource}s emitted by the outer
1100 * {@code ObservableSource}, one after the other, without interleaving them.
1101 * <p>
1102 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/concat.v3.png" alt="">
1103 * <dl>
1104 * <dt><b>Scheduler:</b></dt>
1105 * <dd>{@code concat} does not operate by default on a particular {@link Scheduler}.</dd>
1106 * </dl>
1107 *
1108 * @param <T> the common element base type
1109 * @param sources
1110 * an {@code ObservableSource} that emits {@code ObservableSource}s
1111 * @param bufferSize
1112 * the number of inner {@code ObservableSource}s expected to be buffered.
1113 * @return the new {@code Observable} instance
1114 * @throws NullPointerException if {@code sources} is {@code null}
1115 * @throws IllegalArgumentException if {@code bufferSize} is non-positive
1116 * @see <a href="http://reactivex.io/documentation/operators/concat.html">ReactiveX operators documentation: Concat</a>
1117 */
1118 @SuppressWarnings({ "unchecked", "rawtypes" })
1119 @CheckReturnValue
1120 @NonNull
1121 @SchedulerSupport(SchedulerSupport.NONE)
1122 public static <@NonNull T> Observable<T> concat(@NonNull ObservableSource<? extends ObservableSource<? extends T>> sources, int bufferSize) {
1123 Objects.requireNonNull(sources, "sources is null");
1124 ObjectHelper.verifyPositive(bufferSize, "bufferSize");
1125 return RxJavaPlugins.onAssembly(new ObservableConcatMap(sources, Functions.identity(), bufferSize, ErrorMode.IMMEDIATE));
1126 }
1127
1128 /**
1129 * Returns an {@code Observable} that emits the items emitted by two {@link ObservableSource}s, one after the other, without
1130 * interleaving them.
1131 * <p>
1132 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/concat.v3.png" alt="">
1133 * <dl>
1134 * <dt><b>Scheduler:</b></dt>
1135 * <dd>{@code concat} does not operate by default on a particular {@link Scheduler}.</dd>
1136 * </dl>
1137 *
1138 * @param <T> the common element base type
1139 * @param source1
1140 * an {@code ObservableSource} to be concatenated
1141 * @param source2
1142 * an {@code ObservableSource} to be concatenated
1143 * @return the new {@code Observable} instance
1144 * @throws NullPointerException if {@code source1} or {@code source2} is {@code null}
1145 * @see <a href="http://reactivex.io/documentation/operators/concat.html">ReactiveX operators documentation: Concat</a>
1146 */
1147 @CheckReturnValue
1148 @NonNull
1149 @SchedulerSupport(SchedulerSupport.NONE)
1150 public static <@NonNull T> Observable<T> concat(@NonNull ObservableSource<? extends T> source1, ObservableSource<? extends T> source2) {
1151 Objects.requireNonNull(source1, "source1 is null");
1152 Objects.requireNonNull(source2, "source2 is null");
1153 return concatArray(source1, source2);
1154 }
1155
1156 /**
1157 * Returns an {@code Observable} that emits the items emitted by three {@link ObservableSource}s, one after the other, without
1158 * interleaving them.
1159 * <p>
1160 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/concat.v3.png" alt="">
1161 * <dl>
1162 * <dt><b>Scheduler:</b></dt>
1163 * <dd>{@code concat} does not operate by default on a particular {@link Scheduler}.</dd>
1164 * </dl>
1165 *
1166 * @param <T> the common element base type
1167 * @param source1
1168 * an {@code ObservableSource} to be concatenated
1169 * @param source2
1170 * an {@code ObservableSource} to be concatenated
1171 * @param source3
1172 * an {@code ObservableSource} to be concatenated
1173 * @return the new {@code Observable} instance
1174 * @throws NullPointerException if {@code source1}, {@code source2} or {@code source3} is {@code null}
1175 * @see <a href="http://reactivex.io/documentation/operators/concat.html">ReactiveX operators documentation: Concat</a>
1176 */
1177 @CheckReturnValue
1178 @NonNull
1179 @SchedulerSupport(SchedulerSupport.NONE)
1180 public static <@NonNull T> Observable<T> concat(
1181 @NonNull ObservableSource<? extends T> source1, @NonNull ObservableSource<? extends T> source2,
1182 @NonNull ObservableSource<? extends T> source3) {
1183 Objects.requireNonNull(source1, "source1 is null");
1184 Objects.requireNonNull(source2, "source2 is null");
1185 Objects.requireNonNull(source3, "source3 is null");
1186 return concatArray(source1, source2, source3);
1187 }
1188
1189 /**
1190 * Returns an {@code Observable} that emits the items emitted by four {@link ObservableSource}s, one after the other, without
1191 * interleaving them.
1192 * <p>
1193 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/concat.v3.png" alt="">
1194 * <dl>
1195 * <dt><b>Scheduler:</b></dt>
1196 * <dd>{@code concat} does not operate by default on a particular {@link Scheduler}.</dd>
1197 * </dl>
1198 *
1199 * @param <T> the common element base type
1200 * @param source1
1201 * an {@code ObservableSource} to be concatenated
1202 * @param source2
1203 * an {@code ObservableSource} to be concatenated
1204 * @param source3
1205 * an {@code ObservableSource} to be concatenated
1206 * @param source4
1207 * an {@code ObservableSource} to be concatenated
1208 * @return the new {@code Observable} instance
1209 * @throws NullPointerException if {@code source1}, {@code source2}, {@code source3} or {@code source4} is {@code null}
1210 * @see <a href="http://reactivex.io/documentation/operators/concat.html">ReactiveX operators documentation: Concat</a>
1211 */
1212 @CheckReturnValue
1213 @NonNull
1214 @SchedulerSupport(SchedulerSupport.NONE)
1215 public static <@NonNull T> Observable<T> concat(
1216 @NonNull ObservableSource<? extends T> source1, @NonNull ObservableSource<? extends T> source2,
1217 @NonNull ObservableSource<? extends T> source3, @NonNull ObservableSource<? extends T> source4) {
1218 Objects.requireNonNull(source1, "source1 is null");
1219 Objects.requireNonNull(source2, "source2 is null");
1220 Objects.requireNonNull(source3, "source3 is null");
1221 Objects.requireNonNull(source4, "source4 is null");
1222 return concatArray(source1, source2, source3, source4);
1223 }
1224
1225 /**
1226 * Concatenates a variable number of {@link ObservableSource} sources.
1227 * <p>
1228 * Note: named this way because of overload conflict with {@code concat(ObservableSource<ObservableSource>)}
1229 * <p>
1230 * <img width="640" height="290" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/concatArray.v3.png" alt="">
1231 * <dl>
1232 * <dt><b>Scheduler:</b></dt>
1233 * <dd>{@code concatArray} does not operate by default on a particular {@link Scheduler}.</dd>
1234 * </dl>
1235 * @param sources the array of sources
1236 * @param <T> the common base value type
1237 * @return the new {@code Observable} instance
1238 * @throws NullPointerException if {@code sources} is {@code null}
1239 */
1240 @SuppressWarnings({ "unchecked", "rawtypes" })
1241 @CheckReturnValue
1242 @SchedulerSupport(SchedulerSupport.NONE)
1243 @NonNull
1244 @SafeVarargs
1245 public static <@NonNull T> Observable<T> concatArray(@NonNull ObservableSource<? extends T>... sources) {
1246 Objects.requireNonNull(sources, "sources is null");
1247 if (sources.length == 0) {
1248 return empty();
1249 }
1250 if (sources.length == 1) {
1251 return wrap((ObservableSource<T>)sources[0]);
1252 }
1253 return RxJavaPlugins.onAssembly(new ObservableConcatMap(fromArray(sources), Functions.identity(), bufferSize(), ErrorMode.BOUNDARY));
1254 }
1255
1256 /**
1257 * Concatenates a variable number of {@link ObservableSource} sources and delays errors from any of them
1258 * till all terminate.
1259 * <p>
1260 * <img width="640" height="290" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/concatArray.v3.png" alt="">
1261 * <dl>
1262 * <dt><b>Scheduler:</b></dt>
1263 * <dd>{@code concatArrayDelayError} does not operate by default on a particular {@link Scheduler}.</dd>
1264 * </dl>
1265 * @param sources the array of sources
1266 * @param <T> the common base value type
1267 * @return the new {@code Observable} instance
1268 * @throws NullPointerException if {@code sources} is {@code null}
1269 */
1270 @CheckReturnValue
1271 @SchedulerSupport(SchedulerSupport.NONE)
1272 @NonNull
1273 @SafeVarargs
1274 public static <@NonNull T> Observable<T> concatArrayDelayError(@NonNull ObservableSource<? extends T>... sources) {
1275 Objects.requireNonNull(sources, "sources is null");
1276 if (sources.length == 0) {
1277 return empty();
1278 }
1279 if (sources.length == 1) {
1280 @SuppressWarnings("unchecked")
1281 Observable<T> source = (Observable<T>)wrap(sources[0]);
1282 return source;
1283 }
1284 return concatDelayError(fromArray(sources));
1285 }
1286
1287 /**
1288 * Concatenates an array of {@link ObservableSource}s eagerly into a single stream of values.
1289 * <p>
1290 * <img width="640" height="411" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/concatArrayEager.png" alt="">
1291 * <p>
1292 * Eager concatenation means that once a subscriber subscribes, this operator subscribes to all of the
1293 * {@code ObservableSource}s. The operator buffers the values emitted by these {@code ObservableSource}s and then drains them
1294 * in order, each one after the previous one completes.
1295 * <dl>
1296 * <dt><b>Scheduler:</b></dt>
1297 * <dd>This method does not operate by default on a particular {@link Scheduler}.</dd>
1298 * </dl>
1299 * @param <T> the value type
1300 * @param sources an array of {@code ObservableSource}s that need to be eagerly concatenated
1301 * @return the new {@code Observable} instance with the specified concatenation behavior
1302 * @throws NullPointerException if {@code sources} is {@code null}
1303 * @since 2.0
1304 */
1305 @CheckReturnValue
1306 @SchedulerSupport(SchedulerSupport.NONE)
1307 @SafeVarargs
1308 @NonNull
1309 public static <@NonNull T> Observable<T> concatArrayEager(@NonNull ObservableSource<? extends T>... sources) {
1310 return concatArrayEager(bufferSize(), bufferSize(), sources);
1311 }
1312
1313 /**
1314 * Concatenates an array of {@link ObservableSource}s eagerly into a single stream of values.
1315 * <p>
1316 * <img width="640" height="495" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/concatArrayEager.nn.png" alt="">
1317 * <p>
1318 * Eager concatenation means that once a subscriber subscribes, this operator subscribes to all of the
1319 * {@code ObservableSource}s. The operator buffers the values emitted by these {@code ObservableSource}s and then drains them
1320 * in order, each one after the previous one completes.
1321 * <dl>
1322 * <dt><b>Scheduler:</b></dt>
1323 * <dd>This method does not operate by default on a particular {@link Scheduler}.</dd>
1324 * </dl>
1325 * @param <T> the value type
1326 * @param sources an array of {@code ObservableSource}s that need to be eagerly concatenated
1327 * @param maxConcurrency the maximum number of concurrent subscriptions at a time, {@link Integer#MAX_VALUE}
1328 * is interpreted as indication to subscribe to all sources at once
1329 * @param bufferSize the number of elements expected from each {@code ObservableSource} to be buffered
1330 * @return the new {@code Observable} instance with the specified concatenation behavior
1331 * @throws NullPointerException if {@code sources} is {@code null}
1332 * @throws IllegalArgumentException if {@code maxConcurrency} or {@code bufferSize} is non-positive
1333 * @since 2.0
1334 */
1335 @SuppressWarnings({ "rawtypes", "unchecked" })
1336 @CheckReturnValue
1337 @SchedulerSupport(SchedulerSupport.NONE)
1338 @NonNull
1339 @SafeVarargs
1340 public static <@NonNull T> Observable<T> concatArrayEager(int maxConcurrency, int bufferSize, @NonNull ObservableSource<? extends T>... sources) {
1341 return fromArray(sources).concatMapEagerDelayError((Function)Functions.identity(), false, maxConcurrency, bufferSize);
1342 }
1343
1344 /**
1345 * Concatenates an array of {@link ObservableSource}s eagerly into a single stream of values
1346 * and delaying any errors until all sources terminate.
1347 * <p>
1348 * <img width="640" height="354" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/concatArrayEagerDelayError.png" alt="">
1349 * <p>
1350 * Eager concatenation means that once a subscriber subscribes, this operator subscribes to all of the
1351 * {@code ObservableSource}s. The operator buffers the values emitted by these {@code ObservableSource}s
1352 * and then drains them in order, each one after the previous one completes.
1353 * <dl>
1354 * <dt><b>Scheduler:</b></dt>
1355 * <dd>This method does not operate by default on a particular {@link Scheduler}.</dd>
1356 * </dl>
1357 * @param <T> the value type
1358 * @param sources an array of {@code ObservableSource}s that need to be eagerly concatenated
1359 * @return the new {@code Observable} instance with the specified concatenation behavior
1360 * @throws NullPointerException if {@code sources} is {@code null}
1361 * @since 2.2.1 - experimental
1362 */
1363 @CheckReturnValue
1364 @SchedulerSupport(SchedulerSupport.NONE)
1365 @SafeVarargs
1366 @NonNull
1367 public static <@NonNull T> Observable<T> concatArrayEagerDelayError(@NonNull ObservableSource<? extends T>... sources) {
1368 return concatArrayEagerDelayError(bufferSize(), bufferSize(), sources);
1369 }
1370
1371 /**
1372 * Concatenates an array of {@link ObservableSource}s eagerly into a single stream of values
1373 * and delaying any errors until all sources terminate.
1374 * <p>
1375 * <img width="640" height="460" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/concatArrayEagerDelayError.nn.png" alt="">
1376 * <p>
1377 * Eager concatenation means that once a subscriber subscribes, this operator subscribes to all of the
1378 * {@code ObservableSource}s. The operator buffers the values emitted by these {@code ObservableSource}s
1379 * and then drains them in order, each one after the previous one completes.
1380 * <dl>
1381 * <dt><b>Scheduler:</b></dt>
1382 * <dd>This method does not operate by default on a particular {@link Scheduler}.</dd>
1383 * </dl>
1384 * @param <T> the value type
1385 * @param sources an array of {@code ObservableSource}s that need to be eagerly concatenated
1386 * @param maxConcurrency the maximum number of concurrent subscriptions at a time, {@link Integer#MAX_VALUE}
1387 * is interpreted as indication to subscribe to all sources at once
1388 * @param bufferSize the number of elements expected from each {@code ObservableSource} to be buffered
1389 * @return the new {@code Observable} instance with the specified concatenation behavior
1390 * @throws NullPointerException if {@code sources} is {@code null}
1391 * @throws IllegalArgumentException if {@code maxConcurrency} or {@code bufferSize} is non-positive
1392 * @since 2.2.1 - experimental
1393 */
1394 @SuppressWarnings({ "rawtypes", "unchecked" })
1395 @CheckReturnValue
1396 @SchedulerSupport(SchedulerSupport.NONE)
1397 @NonNull
1398 @SafeVarargs
1399 public static <@NonNull T> Observable<T> concatArrayEagerDelayError(int maxConcurrency, int bufferSize, @NonNull ObservableSource<? extends T>... sources) {
1400 return fromArray(sources).concatMapEagerDelayError((Function)Functions.identity(), true, maxConcurrency, bufferSize);
1401 }
1402
1403 /**
1404 * Concatenates the {@link Iterable} sequence of {@link ObservableSource}s into a single {@code Observable} sequence
1405 * by subscribing to each {@code ObservableSource}, one after the other, one at a time and delays any errors till
1406 * the all inner {@code ObservableSource}s terminate.
1407 * <p>
1408 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/concatDelayError.v3.png" alt="">
1409 * <dl>
1410 * <dt><b>Scheduler:</b></dt>
1411 * <dd>{@code concatDelayError} does not operate by default on a particular {@link Scheduler}.</dd>
1412 * </dl>
1413 *
1414 * @param <T> the common element base type
1415 * @param sources the {@code Iterable} sequence of {@code ObservableSource}s
1416 * @return the new {@code Observable} with the concatenating behavior
1417 * @throws NullPointerException if {@code sources} is {@code null}
1418 */
1419 @CheckReturnValue
1420 @NonNull
1421 @SchedulerSupport(SchedulerSupport.NONE)
1422 public static <@NonNull T> Observable<T> concatDelayError(@NonNull Iterable<@NonNull ? extends ObservableSource<? extends T>> sources) {
1423 Objects.requireNonNull(sources, "sources is null");
1424 return concatDelayError(fromIterable(sources));
1425 }
1426
1427 /**
1428 * Concatenates the {@link ObservableSource} sequence of {@code ObservableSource}s into a single {@code Observable} sequence
1429 * by subscribing to each inner {@code ObservableSource}, one after the other, one at a time and delays any errors till the
1430 * all inner and the outer {@code ObservableSource}s terminate.
1431 * <p>
1432 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/concatDelayError.v3.png" alt="">
1433 * <dl>
1434 * <dt><b>Scheduler:</b></dt>
1435 * <dd>{@code concatDelayError} does not operate by default on a particular {@link Scheduler}.</dd>
1436 * </dl>
1437 *
1438 * @param <T> the common element base type
1439 * @param sources the {@code ObservableSource} sequence of {@code ObservableSource}s
1440 * @return the new {@code Observable} with the concatenating behavior
1441 * @throws NullPointerException if {@code sources} is {@code null}
1442 */
1443 @CheckReturnValue
1444 @SchedulerSupport(SchedulerSupport.NONE)
1445 @NonNull
1446 public static <@NonNull T> Observable<T> concatDelayError(@NonNull ObservableSource<? extends ObservableSource<? extends T>> sources) {
1447 return concatDelayError(sources, bufferSize(), true);
1448 }
1449
1450 /**
1451 * Concatenates the {@link ObservableSource} sequence of {@code ObservableSource}s into a single sequence by subscribing to each inner {@code ObservableSource},
1452 * one after the other, one at a time and delays any errors till the all inner and the outer {@code ObservableSource}s terminate.
1453 * <p>
1454 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/concatDelayError.v3.png" alt="">
1455 * <dl>
1456 * <dt><b>Scheduler:</b></dt>
1457 * <dd>{@code concatDelayError} does not operate by default on a particular {@link Scheduler}.</dd>
1458 * </dl>
1459 *
1460 * @param <T> the common element base type
1461 * @param sources the {@code ObservableSource} sequence of {@code ObservableSource}s
1462 * @param bufferSize the number of inner {@code ObservableSource}s expected to be buffered
1463 * @param tillTheEnd if {@code true}, exceptions from the outer and all inner {@code ObservableSource}s are delayed to the end
1464 * if {@code false}, exception from the outer {@code ObservableSource} is delayed till the active {@code ObservableSource} terminates
1465 * @return the new {@code Observable} with the concatenating behavior
1466 * @throws NullPointerException if {@code sources} is {@code null}
1467 * @throws IllegalArgumentException if {@code bufferSize} is non-positive
1468 */
1469 @SuppressWarnings({ "rawtypes", "unchecked" })
1470 @CheckReturnValue
1471 @NonNull
1472 @SchedulerSupport(SchedulerSupport.NONE)
1473 public static <@NonNull T> Observable<T> concatDelayError(@NonNull ObservableSource<? extends ObservableSource<? extends T>> sources, int bufferSize, boolean tillTheEnd) {
1474 Objects.requireNonNull(sources, "sources is null");
1475 ObjectHelper.verifyPositive(bufferSize, "bufferSize is null");
1476 return RxJavaPlugins.onAssembly(new ObservableConcatMap(sources, Functions.identity(), bufferSize, tillTheEnd ? ErrorMode.END : ErrorMode.BOUNDARY));
1477 }
1478
1479 /**
1480 * Concatenates a sequence of {@link ObservableSource}s eagerly into a single stream of values.
1481 * <p>
1482 * <img width="640" height="422" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Observable.concatEager.i.png" alt="">
1483 * <p>
1484 * Eager concatenation means that once a subscriber subscribes, this operator subscribes to all of the
1485 * {@code ObservableSource}s. The operator buffers the values emitted by these {@code ObservableSource}s and then drains them
1486 * in order, each one after the previous one completes.
1487 * <dl>
1488 * <dt><b>Scheduler:</b></dt>
1489 * <dd>This method does not operate by default on a particular {@link Scheduler}.</dd>
1490 * </dl>
1491 * @param <T> the value type
1492 * @param sources a sequence of {@code ObservableSource}s that need to be eagerly concatenated
1493 * @return the new {@code Observable} instance with the specified concatenation behavior
1494 * @throws NullPointerException if {@code sources} is {@code null}
1495 * @since 2.0
1496 */
1497 @CheckReturnValue
1498 @SchedulerSupport(SchedulerSupport.NONE)
1499 @NonNull
1500 public static <@NonNull T> Observable<T> concatEager(@NonNull Iterable<@NonNull ? extends ObservableSource<? extends T>> sources) {
1501 return concatEager(sources, bufferSize(), bufferSize());
1502 }
1503
1504 /**
1505 * Concatenates a sequence of {@link ObservableSource}s eagerly into a single stream of values and
1506 * runs a limited number of inner sequences at once.
1507 * <p>
1508 * <img width="640" height="379" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Observable.concatEager.in.png" alt="">
1509 * <p>
1510 * Eager concatenation means that once a subscriber subscribes, this operator subscribes to all of the
1511 * {@code ObservableSource}s. The operator buffers the values emitted by these {@code ObservableSource}s and then drains them
1512 * in order, each one after the previous one completes.
1513 * <dl>
1514 * <dt><b>Scheduler:</b></dt>
1515 * <dd>This method does not operate by default on a particular {@link Scheduler}.</dd>
1516 * </dl>
1517 * @param <T> the value type
1518 * @param sources a sequence of {@code ObservableSource}s that need to be eagerly concatenated
1519 * @param maxConcurrency the maximum number of concurrently running inner {@code ObservableSource}s; {@link Integer#MAX_VALUE}
1520 * is interpreted as all inner {@code ObservableSource}s can be active at the same time
1521 * @param bufferSize the number of elements expected from each inner {@code ObservableSource} to be buffered
1522 * @return the new {@code Observable} instance with the specified concatenation behavior
1523 * @throws NullPointerException if {@code sources} is {@code null}
1524 * @throws IllegalArgumentException if {@code maxConcurrency} or {@code bufferSize} is non-positive
1525 * @since 2.0
1526 */
1527 @SuppressWarnings({ "unchecked", "rawtypes" })
1528 @CheckReturnValue
1529 @SchedulerSupport(SchedulerSupport.NONE)
1530 @NonNull
1531 public static <@NonNull T> Observable<T> concatEager(@NonNull Iterable<@NonNull ? extends ObservableSource<? extends T>> sources, int maxConcurrency, int bufferSize) {
1532 return fromIterable(sources).concatMapEagerDelayError((Function)Functions.identity(), false, maxConcurrency, bufferSize);
1533 }
1534
1535 /**
1536 * Concatenates an {@link ObservableSource} sequence of {@code ObservableSource}s eagerly into a single stream of values.
1537 * <p>
1538 * <img width="640" height="495" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Observable.concatEager.o.png" alt="">
1539 * <p>
1540 * Eager concatenation means that once a subscriber subscribes, this operator subscribes to all of the
1541 * emitted source {@code ObservableSource}s as they are observed. The operator buffers the values emitted by these
1542 * {@code ObservableSource}s and then drains them in order, each one after the previous one completes.
1543 * <dl>
1544 * <dt><b>Scheduler:</b></dt>
1545 * <dd>This method does not operate by default on a particular {@link Scheduler}.</dd>
1546 * </dl>
1547 * @param <T> the value type
1548 * @param sources a sequence of {@code ObservableSource}s that need to be eagerly concatenated
1549 * @return the new {@code Observable} instance with the specified concatenation behavior
1550 * @throws NullPointerException if {@code sources} is {@code null}
1551 * @since 2.0
1552 */
1553 @CheckReturnValue
1554 @SchedulerSupport(SchedulerSupport.NONE)
1555 @NonNull
1556 public static <@NonNull T> Observable<T> concatEager(@NonNull ObservableSource<? extends ObservableSource<? extends T>> sources) {
1557 return concatEager(sources, bufferSize(), bufferSize());
1558 }
1559
1560 /**
1561 * Concatenates an {@link ObservableSource} sequence of {@code ObservableSource}s eagerly into a single stream of values
1562 * and runs a limited number of inner sequences at once.
1563 *
1564 * <p>
1565 * <img width="640" height="442" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Observable.concatEager.on.png" alt="">
1566 * <p>
1567 * Eager concatenation means that once a subscriber subscribes, this operator subscribes to all of the
1568 * emitted source {@code ObservableSource}s as they are observed. The operator buffers the values emitted by these
1569 * {@code ObservableSource}s and then drains them in order, each one after the previous one completes.
1570 * <dl>
1571 * <dt><b>Scheduler:</b></dt>
1572 * <dd>This method does not operate by default on a particular {@link Scheduler}.</dd>
1573 * </dl>
1574 * @param <T> the value type
1575 * @param sources a sequence of {@code ObservableSource}s that need to be eagerly concatenated
1576 * @param maxConcurrency the maximum number of concurrently running inner {@code ObservableSource}s; {@link Integer#MAX_VALUE}
1577 * is interpreted as all inner {@code ObservableSource}s can be active at the same time
1578 * @param bufferSize the number of inner {@code ObservableSource} expected to be buffered
1579 * @return the new {@code Observable} instance with the specified concatenation behavior
1580 * @throws NullPointerException if {@code sources} is {@code null}
1581 * @throws IllegalArgumentException if {@code maxConcurrency} or {@code bufferSize} is non-positive
1582 * @since 2.0
1583 */
1584 @SuppressWarnings({ "unchecked", "rawtypes" })
1585 @CheckReturnValue
1586 @SchedulerSupport(SchedulerSupport.NONE)
1587 @NonNull
1588 public static <@NonNull T> Observable<T> concatEager(@NonNull ObservableSource<? extends ObservableSource<? extends T>> sources, int maxConcurrency, int bufferSize) {
1589 return wrap(sources).concatMapEager((Function)Functions.identity(), maxConcurrency, bufferSize);
1590 }
1591
1592 /**
1593 * Concatenates a sequence of {@link ObservableSource}s eagerly into a single stream of values,
1594 * delaying errors until all the inner sequences terminate.
1595 * <p>
1596 * <img width="640" height="428" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Observable.concatEagerDelayError.i.png" alt="">
1597 * <p>
1598 * Eager concatenation means that once a subscriber subscribes, this operator subscribes to all of the
1599 * {@code ObservableSource}s. The operator buffers the values emitted by these {@code ObservableSource}s and then drains them
1600 * in order, each one after the previous one completes.
1601 * <dl>
1602 * <dt><b>Scheduler:</b></dt>
1603 * <dd>This method does not operate by default on a particular {@link Scheduler}.</dd>
1604 * </dl>
1605 * @param <T> the value type
1606 * @param sources a sequence of {@code ObservableSource}s that need to be eagerly concatenated
1607 * @return the new {@code Observable} instance with the specified concatenation behavior
1608 * @throws NullPointerException if {@code sources} is {@code null}
1609 * @since 3.0.0
1610 */
1611 @CheckReturnValue
1612 @SchedulerSupport(SchedulerSupport.NONE)
1613 @NonNull
1614 public static <@NonNull T> Observable<T> concatEagerDelayError(@NonNull Iterable<@NonNull ? extends ObservableSource<? extends T>> sources) {
1615 return concatEagerDelayError(sources, bufferSize(), bufferSize());
1616 }
1617
1618 /**
1619 * Concatenates a sequence of {@link ObservableSource}s eagerly into a single stream of values,
1620 * delaying errors until all the inner sequences terminate and runs a limited number of inner
1621 * sequences at once.
1622 * <p>
1623 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Observable.concatEagerDelayError.in.png" alt="">
1624 * <p>
1625 * Eager concatenation means that once a subscriber subscribes, this operator subscribes to all of the
1626 * {@code ObservableSource}s. The operator buffers the values emitted by these {@code ObservableSource}s and then drains them
1627 * in order, each one after the previous one completes.
1628 * <dl>
1629 * <dt><b>Scheduler:</b></dt>
1630 * <dd>This method does not operate by default on a particular {@link Scheduler}.</dd>
1631 * </dl>
1632 * @param <T> the value type
1633 * @param sources a sequence of {@code ObservableSource}s that need to be eagerly concatenated
1634 * @param maxConcurrency the maximum number of concurrently running inner {@code ObservableSource}s; {@link Integer#MAX_VALUE}
1635 * is interpreted as all inner {@code ObservableSource}s can be active at the same time
1636 * @param bufferSize the number of elements expected from each inner {@code ObservableSource} to be buffered
1637 * @return the new {@code Observable} instance with the specified concatenation behavior
1638 * @throws NullPointerException if {@code sources} is {@code null}
1639 * @throws IllegalArgumentException if {@code maxConcurrency} or {@code bufferSize} is non-positive
1640 * @since 3.0.0
1641 */
1642 @SuppressWarnings({ "unchecked", "rawtypes" })
1643 @CheckReturnValue
1644 @SchedulerSupport(SchedulerSupport.NONE)
1645 @NonNull
1646 public static <@NonNull T> Observable<T> concatEagerDelayError(@NonNull Iterable<@NonNull ? extends ObservableSource<? extends T>> sources, int maxConcurrency, int bufferSize) {
1647 return fromIterable(sources).concatMapEagerDelayError((Function)Functions.identity(), true, maxConcurrency, bufferSize);
1648 }
1649
1650 /**
1651 * Concatenates an {@link ObservableSource} sequence of {@code ObservableSource}s eagerly into a single stream of values,
1652 * delaying errors until all the inner and the outer sequence terminate.
1653 * <p>
1654 * <img width="640" height="496" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Observable.concatEagerDelayError.o.png" alt="">
1655 * <p>
1656 * Eager concatenation means that once a subscriber subscribes, this operator subscribes to all of the
1657 * emitted source {@code ObservableSource}s as they are observed. The operator buffers the values emitted by these
1658 * {@code ObservableSource}s and then drains them in order, each one after the previous one completes.
1659 * <dl>
1660 * <dt><b>Scheduler:</b></dt>
1661 * <dd>This method does not operate by default on a particular {@link Scheduler}.</dd>
1662 * </dl>
1663 * @param <T> the value type
1664 * @param sources a sequence of {@code ObservableSource}s that need to be eagerly concatenated
1665 * @return the new {@code Observable} instance with the specified concatenation behavior
1666 * @throws NullPointerException if {@code sources} is {@code null}
1667 * @since 3.0.0
1668 */
1669 @CheckReturnValue
1670 @SchedulerSupport(SchedulerSupport.NONE)
1671 @NonNull
1672 public static <@NonNull T> Observable<T> concatEagerDelayError(@NonNull ObservableSource<? extends ObservableSource<? extends T>> sources) {
1673 return concatEagerDelayError(sources, bufferSize(), bufferSize());
1674 }
1675
1676 /**
1677 * Concatenates an {@link ObservableSource} sequence of {@code ObservableSource}s eagerly into a single stream of values,
1678 * delaying errors until all the inner and the outer sequence terminate and runs a limited number of inner sequences at once.
1679 * <p>
1680 * <img width="640" height="421" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Observable.concatEagerDelayError.on.png" alt="">
1681 * <p>
1682 * Eager concatenation means that once a subscriber subscribes, this operator subscribes to all of the
1683 * emitted source {@code ObservableSource}s as they are observed. The operator buffers the values emitted by these
1684 * {@code ObservableSource}s and then drains them in order, each one after the previous one completes.
1685 * <dl>
1686 * <dt><b>Scheduler:</b></dt>
1687 * <dd>This method does not operate by default on a particular {@link Scheduler}.</dd>
1688 * </dl>
1689 * @param <T> the value type
1690 * @param sources a sequence of {@code ObservableSource}s that need to be eagerly concatenated
1691 * @param maxConcurrency the maximum number of concurrently running inner {@code ObservableSource}s; {@link Integer#MAX_VALUE}
1692 * is interpreted as all inner {@code ObservableSource}s can be active at the same time
1693 * @param bufferSize the number of inner {@code ObservableSource} expected to be buffered
1694 * @return the new {@code Observable} instance with the specified concatenation behavior
1695 * @throws NullPointerException if {@code sources} is {@code null}
1696 * @throws IllegalArgumentException if {@code maxConcurrency} or {@code bufferSize} is non-positive
1697 * @since 3.0.0
1698 */
1699 @SuppressWarnings({ "unchecked", "rawtypes" })
1700 @CheckReturnValue
1701 @SchedulerSupport(SchedulerSupport.NONE)
1702 @NonNull
1703 public static <@NonNull T> Observable<T> concatEagerDelayError(@NonNull ObservableSource<? extends ObservableSource<? extends T>> sources, int maxConcurrency, int bufferSize) {
1704 return wrap(sources).concatMapEagerDelayError((Function)Functions.identity(), true, maxConcurrency, bufferSize);
1705 }
1706
1707 /**
1708 * Provides an API (via a cold {@code Observable}) that bridges the reactive world with the callback-style world.
1709 * <p>
1710 * Example:
1711 * <pre><code>
1712 * Observable.&lt;Event&gt;create(emitter -&gt; {
1713 * Callback listener = new Callback() {
1714 * &#64;Override
1715 * public void onEvent(Event e) {
1716 * emitter.onNext(e);
1717 * if (e.isLast()) {
1718 * emitter.onComplete();
1719 * }
1720 * }
1721 *
1722 * &#64;Override
1723 * public void onFailure(Exception e) {
1724 * emitter.onError(e);
1725 * }
1726 * };
1727 *
1728 * AutoCloseable c = api.someMethod(listener);
1729 *
1730 * emitter.setCancellable(c::close);
1731 *
1732 * });
1733 * </code></pre>
1734 * <p>
1735 * Whenever an {@link Observer} subscribes to the returned {@code Observable}, the provided
1736 * {@link ObservableOnSubscribe} callback is invoked with a fresh instance of an {@link ObservableEmitter}
1737 * that will interact only with that specific {@code Observer}. If this {@code Observer}
1738 * disposes the flow (making {@link ObservableEmitter#isDisposed} return {@code true}),
1739 * other observers subscribed to the same returned {@code Observable} are not affected.
1740 * <p>
1741 * <img width="640" height="200" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/create.v3.png" alt="">
1742 * <p>
1743 * You should call the {@code ObservableEmitter}'s {@code onNext}, {@code onError} and {@code onComplete} methods in a serialized fashion. The
1744 * rest of its methods are thread-safe.
1745 * <dl>
1746 * <dt><b>Scheduler:</b></dt>
1747 * <dd>{@code create} does not operate by default on a particular {@link Scheduler}.</dd>
1748 * </dl>
1749 *
1750 * @param <T> the element type
1751 * @param source the emitter that is called when an {@code Observer} subscribes to the returned {@code Observable}
1752 * @return the new {@code Observable} instance
1753 * @throws NullPointerException if {@code source} is {@code null}
1754 * @see ObservableOnSubscribe
1755 * @see ObservableEmitter
1756 * @see Cancellable
1757 */
1758 @CheckReturnValue
1759 @NonNull
1760 @SchedulerSupport(SchedulerSupport.NONE)
1761 public static <@NonNull T> Observable<T> create(@NonNull ObservableOnSubscribe<T> source) {
1762 Objects.requireNonNull(source, "source is null");
1763 return RxJavaPlugins.onAssembly(new ObservableCreate<>(source));
1764 }
1765
1766 /**
1767 * Returns an {@code Observable} that calls an {@link ObservableSource} factory to create an {@code ObservableSource} for each new {@link Observer}
1768 * that subscribes. That is, for each subscriber, the actual {@code ObservableSource} that subscriber observes is
1769 * determined by the factory function.
1770 * <p>
1771 * <img width="640" height="340" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/defer.v3.png" alt="">
1772 * <p>
1773 * The {@code defer} operator allows you to defer or delay emitting items from an {@code ObservableSource} until such time as an
1774 * {@code Observer} subscribes to the {@code ObservableSource}. This allows an {@code Observer} to easily obtain updates or a
1775 * refreshed version of the sequence.
1776 * <dl>
1777 * <dt><b>Scheduler:</b></dt>
1778 * <dd>{@code defer} does not operate by default on a particular {@link Scheduler}.</dd>
1779 * </dl>
1780 *
1781 * @param supplier
1782 * the {@code ObservableSource} factory function to invoke for each {@code Observer} that subscribes to the
1783 * resulting {@code Observable}
1784 * @param <T>
1785 * the type of the items emitted by the {@code ObservableSource}
1786 * @return the new {@code Observable} instance
1787 * @throws NullPointerException if {@code supplier} is {@code null}
1788 * @see <a href="http://reactivex.io/documentation/operators/defer.html">ReactiveX operators documentation: Defer</a>
1789 */
1790 @CheckReturnValue
1791 @NonNull
1792 @SchedulerSupport(SchedulerSupport.NONE)
1793 public static <@NonNull T> Observable<T> defer(@NonNull Supplier<? extends @NonNull ObservableSource<? extends T>> supplier) {
1794 Objects.requireNonNull(supplier, "supplier is null");
1795 return RxJavaPlugins.onAssembly(new ObservableDefer<>(supplier));
1796 }
1797
1798 /**
1799 * Returns an {@code Observable} that emits no items to the {@link Observer} and immediately invokes its
1800 * {@link Observer#onComplete onComplete} method.
1801 * <p>
1802 * <img width="640" height="190" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/empty.v3.png" alt="">
1803 * <dl>
1804 * <dt><b>Scheduler:</b></dt>
1805 * <dd>{@code empty} does not operate by default on a particular {@link Scheduler}.</dd>
1806 * </dl>
1807 *
1808 * @param <T>
1809 * the type of the items (ostensibly) emitted by the {@code Observable}
1810 * @return the shared {@code Observable} instance
1811 * @see <a href="http://reactivex.io/documentation/operators/empty-never-throw.html">ReactiveX operators documentation: Empty</a>
1812 */
1813 @CheckReturnValue
1814 @SchedulerSupport(SchedulerSupport.NONE)
1815 @SuppressWarnings("unchecked")
1816 @NonNull
1817 public static <@NonNull T> Observable<T> empty() {
1818 return RxJavaPlugins.onAssembly((Observable<T>) ObservableEmpty.INSTANCE);
1819 }
1820
1821 /**
1822 * Returns an {@code Observable} that invokes an {@link Observer}'s {@link Observer#onError onError} method when the
1823 * {@code Observer} subscribes to it.
1824 * <p>
1825 * <img width="640" height="221" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/error.supplier.png" alt="">
1826 * <dl>
1827 * <dt><b>Scheduler:</b></dt>
1828 * <dd>{@code error} does not operate by default on a particular {@link Scheduler}.</dd>
1829 * </dl>
1830 *
1831 * @param supplier
1832 * a {@link Supplier} factory to return a {@link Throwable} for each individual {@code Observer}
1833 * @param <T>
1834 * the type of the items (ostensibly) emitted by the {@code Observable}
1835 * @return the new {@code Observable} instance
1836 * @throws NullPointerException if {@code supplier} is {@code null}
1837 * @see <a href="http://reactivex.io/documentation/operators/empty-never-throw.html">ReactiveX operators documentation: Throw</a>
1838 */
1839 @CheckReturnValue
1840 @NonNull
1841 @SchedulerSupport(SchedulerSupport.NONE)
1842 public static <@NonNull T> Observable<T> error(@NonNull Supplier<? extends @NonNull Throwable> supplier) {
1843 Objects.requireNonNull(supplier, "supplier is null");
1844 return RxJavaPlugins.onAssembly(new ObservableError<>(supplier));
1845 }
1846
1847 /**
1848 * Returns an {@code Observable} that invokes an {@link Observer}'s {@link Observer#onError onError} method when the
1849 * {@code Observer} subscribes to it.
1850 * <p>
1851 * <img width="640" height="221" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/error.item.png" alt="">
1852 * <dl>
1853 * <dt><b>Scheduler:</b></dt>
1854 * <dd>{@code error} does not operate by default on a particular {@link Scheduler}.</dd>
1855 * </dl>
1856 *
1857 * @param throwable
1858 * the particular {@link Throwable} to pass to {@link Observer#onError onError}
1859 * @param <T>
1860 * the type of the items (ostensibly) emitted by the {@code Observable}
1861 * @return the new {@code Observable} instance
1862 * @throws NullPointerException if {@code throwable} is {@code null}
1863 * @see <a href="http://reactivex.io/documentation/operators/empty-never-throw.html">ReactiveX operators documentation: Throw</a>
1864 */
1865 @CheckReturnValue
1866 @NonNull
1867 @SchedulerSupport(SchedulerSupport.NONE)
1868 public static <@NonNull T> Observable<T> error(@NonNull Throwable throwable) {
1869 Objects.requireNonNull(throwable, "throwable is null");
1870 return error(Functions.justSupplier(throwable));
1871 }
1872
1873 /**
1874 * Returns an {@code Observable} instance that runs the given {@link Action} for each {@link Observer} and
1875 * emits either its exception or simply completes.
1876 * <p>
1877 * <img width="640" height="287" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Observable.fromAction.png" alt="">
1878 * <dl>
1879 * <dt><b>Scheduler:</b></dt>
1880 * <dd>{@code fromAction} does not operate by default on a particular {@link Scheduler}.</dd>
1881 * <dt><b>Error handling:</b></dt>
1882 * <dd> If the {@code Action} throws an exception, the respective {@link Throwable} is
1883 * delivered to the downstream via {@link Observer#onError(Throwable)},
1884 * except when the downstream has canceled the resulting {@code Observable} source.
1885 * In this latter case, the {@code Throwable} is delivered to the global error handler via
1886 * {@link RxJavaPlugins#onError(Throwable)} as an {@link io.reactivex.rxjava3.exceptions.UndeliverableException UndeliverableException}.
1887 * </dd>
1888 * </dl>
1889 * @param <T> the target type
1890 * @param action the {@code Action} to run for each {@code Observer}
1891 * @return the new {@code Observable} instance
1892 * @throws NullPointerException if {@code action} is {@code null}
1893 * @since 3.0.0
1894 */
1895 @CheckReturnValue
1896 @NonNull
1897 @SchedulerSupport(SchedulerSupport.NONE)
1898 public static <@NonNull T> Observable<T> fromAction(@NonNull Action action) {
1899 Objects.requireNonNull(action, "action is null");
1900 return RxJavaPlugins.onAssembly(new ObservableFromAction<>(action));
1901 }
1902
1903 /**
1904 * Converts an array into an {@link ObservableSource} that emits the items in the array.
1905 * <p>
1906 * <img width="640" height="315" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/from.v3.png" alt="">
1907 * <dl>
1908 * <dt><b>Scheduler:</b></dt>
1909 * <dd>{@code fromArray} does not operate by default on a particular {@link Scheduler}.</dd>
1910 * </dl>
1911 *
1912 * @param items
1913 * the array of elements
1914 * @param <T>
1915 * the type of items in the array and the type of items to be emitted by the resulting {@code Observable}
1916 * @return the new {@code Observable} instance
1917 * @throws NullPointerException if {@code items} is {@code null}
1918 * @see <a href="http://reactivex.io/documentation/operators/from.html">ReactiveX operators documentation: From</a>
1919 */
1920 @CheckReturnValue
1921 @SchedulerSupport(SchedulerSupport.NONE)
1922 @NonNull
1923 @SafeVarargs
1924 public static <@NonNull T> Observable<T> fromArray(@NonNull T... items) {
1925 Objects.requireNonNull(items, "items is null");
1926 if (items.length == 0) {
1927 return empty();
1928 }
1929 if (items.length == 1) {
1930 return just(items[0]);
1931 }
1932 return RxJavaPlugins.onAssembly(new ObservableFromArray<>(items));
1933 }
1934
1935 /**
1936 * Returns an {@code Observable} that, when an observer subscribes to it, invokes a function you specify and then
1937 * emits the value returned from that function.
1938 * <p>
1939 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/fromCallable.v3.png" alt="">
1940 * <p>
1941 * This allows you to defer the execution of the function you specify until an observer subscribes to the
1942 * {@code Observable}. That is to say, it makes the function "lazy."
1943 * <dl>
1944 * <dt><b>Scheduler:</b></dt>
1945 * <dd>{@code fromCallable} does not operate by default on a particular {@link Scheduler}.</dd>
1946 * <dt><b>Error handling:</b></dt>
1947 * <dd> If the {@link Callable} throws an exception, the respective {@link Throwable} is
1948 * delivered to the downstream via {@link Observer#onError(Throwable)},
1949 * except when the downstream has disposed the current {@code Observable} source.
1950 * In this latter case, the {@code Throwable} is delivered to the global error handler via
1951 * {@link RxJavaPlugins#onError(Throwable)} as an {@link UndeliverableException}.
1952 * </dd>
1953 * </dl>
1954 * @param callable
1955 * a function, the execution of which should be deferred; {@code fromCallable} will invoke this
1956 * function only when an observer subscribes to the {@code Observable} that {@code fromCallable} returns
1957 * @param <T>
1958 * the type of the item returned by the {@code Callable} and emitted by the {@code Observable}
1959 * @return the new {@code Observable} instance
1960 * @throws NullPointerException if {@code callable} is {@code null}
1961 * @see #defer(Supplier)
1962 * @see #fromSupplier(Supplier)
1963 * @since 2.0
1964 */
1965 @CheckReturnValue
1966 @NonNull
1967 @SchedulerSupport(SchedulerSupport.NONE)
1968 public static <@NonNull T> Observable<T> fromCallable(@NonNull Callable<? extends T> callable) {
1969 Objects.requireNonNull(callable, "callable is null");
1970 return RxJavaPlugins.onAssembly(new ObservableFromCallable<>(callable));
1971 }
1972
1973 /**
1974 * Wraps a {@link CompletableSource} into an {@code Observable}.
1975 * <p>
1976 * <img width="640" height="278" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Observable.fromCompletable.png" alt="">
1977 * <dl>
1978 * <dt><b>Scheduler:</b></dt>
1979 * <dd>{@code fromCompletable} does not operate by default on a particular {@link Scheduler}.</dd>
1980 * </dl>
1981 * @param <T> the target type
1982 * @param completableSource the {@code CompletableSource} to convert from
1983 * @return the new {@code Observable} instance
1984 * @throws NullPointerException if {@code completableSource} is {@code null}
1985 */
1986 @CheckReturnValue
1987 @NonNull
1988 @SchedulerSupport(SchedulerSupport.NONE)
1989 public static <@NonNull T> Observable<T> fromCompletable(@NonNull CompletableSource completableSource) {
1990 Objects.requireNonNull(completableSource, "completableSource is null");
1991 return RxJavaPlugins.onAssembly(new ObservableFromCompletable<>(completableSource));
1992 }
1993
1994 /**
1995 * Converts a {@link Future} into an {@code Observable}.
1996 * <p>
1997 * <img width="640" height="284" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/fromFuture.noarg.png" alt="">
1998 * <p>
1999 * The operator calls {@link Future#get()}, which is a blocking method, on the subscription thread.
2000 * It is recommended applying {@link #subscribeOn(Scheduler)} to move this blocking wait to a
2001 * background thread, and if the {@link Scheduler} supports it, interrupt the wait when the flow
2002 * is disposed.
2003 * <p>
2004 * Unlike 1.x, disposing the {@code Observable} won't cancel the future. If necessary, one can use composition to achieve the
2005 * cancellation effect: {@code futureObservableSource.doOnDispose(() -> future.cancel(true));}.
2006 * <p>
2007 * Also note that this operator will consume a {@link CompletionStage}-based {@code Future} subclass (such as
2008 * {@link CompletableFuture}) in a blocking manner as well. Use the {@link #fromCompletionStage(CompletionStage)}
2009 * operator to convert and consume such sources in a non-blocking fashion instead.
2010 * <dl>
2011 * <dt><b>Scheduler:</b></dt>
2012 * <dd>{@code fromFuture} does not operate by default on a particular {@code Scheduler}.</dd>
2013 * </dl>
2014 *
2015 * @param future
2016 * the source {@code Future}
2017 * @param <T>
2018 * the type of object that the {@code Future} returns, and also the type of item to be emitted by
2019 * the resulting {@code Observable}
2020 * @return the new {@code Observable} instance
2021 * @throws NullPointerException if {@code future} is {@code null}
2022 * @see <a href="http://reactivex.io/documentation/operators/from.html">ReactiveX operators documentation: From</a>
2023 */
2024 @CheckReturnValue
2025 @NonNull
2026 @SchedulerSupport(SchedulerSupport.NONE)
2027 public static <@NonNull T> Observable<T> fromFuture(@NonNull Future<? extends T> future) {
2028 Objects.requireNonNull(future, "future is null");
2029 return RxJavaPlugins.onAssembly(new ObservableFromFuture<>(future, 0L, null));
2030 }
2031
2032 /**
2033 * Converts a {@link Future} into an {@code Observable}, with a timeout on the {@code Future}.
2034 * <p>
2035 * <img width="640" height="287" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/fromFuture.timeout.png" alt="">
2036 * <p>
2037 * The operator calls {@link Future#get(long, TimeUnit)}, which is a blocking method, on the subscription thread.
2038 * It is recommended applying {@link #subscribeOn(Scheduler)} to move this blocking wait to a
2039 * background thread, and if the {@link Scheduler} supports it, interrupt the wait when the flow
2040 * is disposed.
2041 * <p>
2042 * Unlike 1.x, disposing the {@code Observable} won't cancel the future. If necessary, one can use composition to achieve the
2043 * cancellation effect: {@code futureObservableSource.doOnDispose(() -> future.cancel(true));}.
2044 * <p>
2045 * Also note that this operator will consume a {@link CompletionStage}-based {@code Future} subclass (such as
2046 * {@link CompletableFuture}) in a blocking manner as well. Use the {@link #fromCompletionStage(CompletionStage)}
2047 * operator to convert and consume such sources in a non-blocking fashion instead.
2048 * <dl>
2049 * <dt><b>Scheduler:</b></dt>
2050 * <dd>{@code fromFuture} does not operate by default on a particular {@code Scheduler}.</dd>
2051 * </dl>
2052 *
2053 * @param future
2054 * the source {@code Future}
2055 * @param timeout
2056 * the maximum time to wait before calling {@code get}
2057 * @param unit
2058 * the {@link TimeUnit} of the {@code timeout} argument
2059 * @param <T>
2060 * the type of object that the {@code Future} returns, and also the type of item to be emitted by
2061 * the resulting {@code Observable}
2062 * @return the new {@code Observable} instance
2063 * @throws NullPointerException if {@code future} or {@code unit} is {@code null}
2064 * @see <a href="http://reactivex.io/documentation/operators/from.html">ReactiveX operators documentation: From</a>
2065 */
2066 @CheckReturnValue
2067 @NonNull
2068 @SchedulerSupport(SchedulerSupport.NONE)
2069 public static <@NonNull T> Observable<T> fromFuture(@NonNull Future<? extends T> future, long timeout, @NonNull TimeUnit unit) {
2070 Objects.requireNonNull(future, "future is null");
2071 Objects.requireNonNull(unit, "unit is null");
2072 return RxJavaPlugins.onAssembly(new ObservableFromFuture<>(future, timeout, unit));
2073 }
2074
2075 /**
2076 * Converts an {@link Iterable} sequence into an {@code Observable} that emits the items in the sequence.
2077 * <p>
2078 * <img width="640" height="187" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/fromIterable.v3.png" alt="">
2079 * <dl>
2080 * <dt><b>Scheduler:</b></dt>
2081 * <dd>{@code fromIterable} does not operate by default on a particular {@link Scheduler}.</dd>
2082 * </dl>
2083 *
2084 * @param source
2085 * the source {@code Iterable} sequence
2086 * @param <T>
2087 * the type of items in the {@code Iterable} sequence and the type of items to be emitted by the
2088 * resulting {@code Observable}
2089 * @return the new {@code Observable} instance
2090 * @throws NullPointerException if {@code source} is {@code null}
2091 * @see <a href="http://reactivex.io/documentation/operators/from.html">ReactiveX operators documentation: From</a>
2092 * @see #fromStream(Stream)
2093 */
2094 @CheckReturnValue
2095 @NonNull
2096 @SchedulerSupport(SchedulerSupport.NONE)
2097 public static <@NonNull T> Observable<T> fromIterable(@NonNull Iterable<? extends T> source) {
2098 Objects.requireNonNull(source, "source is null");
2099 return RxJavaPlugins.onAssembly(new ObservableFromIterable<>(source));
2100 }
2101
2102 /**
2103 * Returns an {@code Observable} instance that when subscribed to, subscribes to the {@link MaybeSource} instance and
2104 * emits {@code onSuccess} as a single item or forwards any {@code onComplete} or
2105 * {@code onError} signal.
2106 * <p>
2107 * <img width="640" height="226" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Observable.fromMaybe.png" alt="">
2108 * <dl>
2109 * <dt><b>Scheduler:</b></dt>
2110 * <dd>{@code fromMaybe} does not operate by default on a particular {@link Scheduler}.</dd>
2111 * </dl>
2112 * @param <T> the value type of the {@code MaybeSource} element
2113 * @param maybe the {@code MaybeSource} instance to subscribe to, not {@code null}
2114 * @return the new {@code Observable} instance
2115 * @throws NullPointerException if {@code maybe} is {@code null}
2116 * @since 3.0.0
2117 */
2118 @CheckReturnValue
2119 @NonNull
2120 @SchedulerSupport(SchedulerSupport.NONE)
2121 public static <@NonNull T> Observable<T> fromMaybe(@NonNull MaybeSource<T> maybe) {
2122 Objects.requireNonNull(maybe, "maybe is null");
2123 return RxJavaPlugins.onAssembly(new MaybeToObservable<>(maybe));
2124 }
2125
2126 /**
2127 * Converts an arbitrary <em>Reactive Streams</em> {@link Publisher} into an {@code Observable}.
2128 * <p>
2129 * <img width="640" height="344" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/fromPublisher.o.png" alt="">
2130 * <p>
2131 * The {@code Publisher} must follow the
2132 * <a href="https://github.com/reactive-streams/reactive-streams-jvm#reactive-streams">Reactive-Streams specification</a>.
2133 * Violating the specification may result in undefined behavior.
2134 * <p>
2135 * If possible, use {@link #create(ObservableOnSubscribe)} to create a
2136 * source-like {@code Observable} instead.
2137 * <p>
2138 * Note that even though {@code Publisher} appears to be a functional interface, it
2139 * is not recommended to implement it through a lambda as the specification requires
2140 * state management that is not achievable with a stateless lambda.
2141 * <dl>
2142 * <dt><b>Backpressure:</b></dt>
2143 * <dd>The source {@code publisher} is consumed in an unbounded fashion without applying any
2144 * backpressure to it.</dd>
2145 * <dt><b>Scheduler:</b></dt>
2146 * <dd>{@code fromPublisher} does not operate by default on a particular {@link Scheduler}.</dd>
2147 * </dl>
2148 * @param <T> the value type of the flow
2149 * @param publisher the {@code Publisher} to convert
2150 * @return the new {@code Observable} instance
2151 * @throws NullPointerException if {@code publisher} is {@code null}
2152 * @see #create(ObservableOnSubscribe)
2153 */
2154 @BackpressureSupport(BackpressureKind.UNBOUNDED_IN)
2155 @CheckReturnValue
2156 @NonNull
2157 @SchedulerSupport(SchedulerSupport.NONE)
2158 public static <@NonNull T> Observable<T> fromPublisher(@NonNull Publisher<? extends T> publisher) {
2159 Objects.requireNonNull(publisher, "publisher is null");
2160 return RxJavaPlugins.onAssembly(new ObservableFromPublisher<>(publisher));
2161 }
2162
2163 /**
2164 * Returns an {@code Observable} instance that runs the given {@link Runnable} for each {@link Observer} and
2165 * emits either its unchecked exception or simply completes.
2166 * <p>
2167 * <img width="640" height="286" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Observable.fromRunnable.png" alt="">
2168 * <p>
2169 * If the code to be wrapped needs to throw a checked or more broader {@link Throwable} exception, that
2170 * exception has to be converted to an unchecked exception by the wrapped code itself. Alternatively,
2171 * use the {@link #fromAction(Action)} method which allows the wrapped code to throw any {@code Throwable}
2172 * exception and will signal it to observers as-is.
2173 * <dl>
2174 * <dt><b>Scheduler:</b></dt>
2175 * <dd>{@code fromRunnable} does not operate by default on a particular {@link Scheduler}.</dd>
2176 * <dt><b>Error handling:</b></dt>
2177 * <dd> If the {@code Runnable} throws an exception, the respective {@code Throwable} is
2178 * delivered to the downstream via {@link Observer#onError(Throwable)},
2179 * except when the downstream has canceled the resulting {@code Observable} source.
2180 * In this latter case, the {@code Throwable} is delivered to the global error handler via
2181 * {@link RxJavaPlugins#onError(Throwable)} as an {@link io.reactivex.rxjava3.exceptions.UndeliverableException UndeliverableException}.
2182 * </dd>
2183 * </dl>
2184 * @param <T> the target type
2185 * @param run the {@code Runnable} to run for each {@code Observer}
2186 * @return the new {@code Observable} instance
2187 * @throws NullPointerException if {@code run} is {@code null}
2188 * @since 3.0.0
2189 * @see #fromAction(Action)
2190 */
2191 @CheckReturnValue
2192 @NonNull
2193 @SchedulerSupport(SchedulerSupport.NONE)
2194 public static <@NonNull T> Observable<T> fromRunnable(@NonNull Runnable run) {
2195 Objects.requireNonNull(run, "run is null");
2196 return RxJavaPlugins.onAssembly(new ObservableFromRunnable<>(run));
2197 }
2198
2199 /**
2200 * Returns an {@code Observable} instance that when subscribed to, subscribes to the {@link SingleSource} instance and
2201 * emits {@code onSuccess} as a single item or forwards the {@code onError} signal.
2202 * <p>
2203 * <img width="640" height="341" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Observable.fromSingle.png" alt="">
2204 * <dl>
2205 * <dt><b>Scheduler:</b></dt>
2206 * <dd>{@code fromSingle} does not operate by default on a particular {@link Scheduler}.</dd>
2207 * </dl>
2208 * @param <T> the value type of the {@code SingleSource} element
2209 * @param source the {@code SingleSource} instance to subscribe to, not {@code null}
2210 * @return the new {@code Observable} instance
2211 * @throws NullPointerException if {@code source} is {@code null}
2212 * @since 3.0.0
2213 */
2214 @CheckReturnValue
2215 @NonNull
2216 @SchedulerSupport(SchedulerSupport.NONE)
2217 public static <@NonNull T> Observable<T> fromSingle(@NonNull SingleSource<T> source) {
2218 Objects.requireNonNull(source, "source is null");
2219 return RxJavaPlugins.onAssembly(new SingleToObservable<>(source));
2220 }
2221
2222 /**
2223 * Returns an {@code Observable} that, when an observer subscribes to it, invokes a supplier function you specify and then
2224 * emits the value returned from that function.
2225 * <p>
2226 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Observable.fromSupplier.v3.png" alt="">
2227 * <p>
2228 * This allows you to defer the execution of the function you specify until an observer subscribes to the
2229 * {@code Observable}. That is to say, it makes the function "lazy."
2230 * <dl>
2231 * <dt><b>Scheduler:</b></dt>
2232 * <dd>{@code fromSupplier} does not operate by default on a particular {@link Scheduler}.</dd>
2233 * <dt><b>Error handling:</b></dt>
2234 * <dd> If the {@link Supplier} throws an exception, the respective {@link Throwable} is
2235 * delivered to the downstream via {@link Observer#onError(Throwable)},
2236 * except when the downstream has disposed the current {@code Observable} source.
2237 * In this latter case, the {@code Throwable} is delivered to the global error handler via
2238 * {@link RxJavaPlugins#onError(Throwable)} as an {@link UndeliverableException}.
2239 * </dd>
2240 * </dl>
2241 * @param supplier
2242 * a function, the execution of which should be deferred; {@code fromSupplier} will invoke this
2243 * function only when an observer subscribes to the {@code Observable} that {@code fromSupplier} returns
2244 * @param <T>
2245 * the type of the item emitted by the {@code Observable}
2246 * @return the new {@code Observable} instance
2247 * @throws NullPointerException if {@code supplier} is {@code null}
2248 * @see #defer(Supplier)
2249 * @see #fromCallable(Callable)
2250 * @since 3.0.0
2251 */
2252 @CheckReturnValue
2253 @NonNull
2254 @SchedulerSupport(SchedulerSupport.NONE)
2255 public static <@NonNull T> Observable<T> fromSupplier(@NonNull Supplier<? extends T> supplier) {
2256 Objects.requireNonNull(supplier, "supplier is null");
2257 return RxJavaPlugins.onAssembly(new ObservableFromSupplier<>(supplier));
2258 }
2259
2260 /**
2261 * Returns a cold, synchronous and stateless generator of values.
2262 * <p>
2263 * <img width="640" height="315" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/generate.2.v3.png" alt="">
2264 * <p>
2265 * Note that the {@link Emitter#onNext}, {@link Emitter#onError} and
2266 * {@link Emitter#onComplete} methods provided to the function via the {@link Emitter} instance should be called synchronously,
2267 * never concurrently and only while the function body is executing. Calling them from multiple threads
2268 * or outside the function call is not supported and leads to an undefined behavior.
2269 * <dl>
2270 * <dt><b>Scheduler:</b></dt>
2271 * <dd>{@code generate} does not operate by default on a particular {@link Scheduler}.</dd>
2272 * </dl>
2273 *
2274 * @param <T> the generated value type
2275 * @param generator the {@link Consumer} called in a loop after a downstream {@link Observer} has
2276 * subscribed. The callback then should call {@code onNext}, {@code onError} or
2277 * {@code onComplete} to signal a value or a terminal event. Signaling multiple {@code onNext}
2278 * in a call will make the operator signal {@link IllegalStateException}.
2279 * @return the new {@code Observable} instance
2280 * @throws NullPointerException if {@code generator} is {@code null}
2281 */
2282 @CheckReturnValue
2283 @NonNull
2284 @SchedulerSupport(SchedulerSupport.NONE)
2285 public static <@NonNull T> Observable<T> generate(@NonNull Consumer<Emitter<T>> generator) {
2286 Objects.requireNonNull(generator, "generator is null");
2287 return generate(Functions.nullSupplier(),
2288 ObservableInternalHelper.simpleGenerator(generator), Functions.emptyConsumer());
2289 }
2290
2291 /**
2292 * Returns a cold, synchronous and stateful generator of values.
2293 * <p>
2294 * <img width="640" height="315" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/generate.2.v3.png" alt="">
2295 * <p>
2296 * Note that the {@link Emitter#onNext}, {@link Emitter#onError} and
2297 * {@link Emitter#onComplete} methods provided to the function via the {@link Emitter} instance should be called synchronously,
2298 * never concurrently and only while the function body is executing. Calling them from multiple threads
2299 * or outside the function call is not supported and leads to an undefined behavior.
2300 * <dl>
2301 * <dt><b>Scheduler:</b></dt>
2302 * <dd>{@code generate} does not operate by default on a particular {@link Scheduler}.</dd>
2303 * </dl>
2304 *
2305 * @param <S> the type of the per-{@link Observer} state
2306 * @param <T> the generated value type
2307 * @param initialState the {@link Supplier} to generate the initial state for each {@code Observer}
2308 * @param generator the {@link BiConsumer} called in a loop after a downstream {@code Observer} has
2309 * subscribed. The callback then should call {@code onNext}, {@code onError} or
2310 * {@code onComplete} to signal a value or a terminal event. Signaling multiple {@code onNext}
2311 * in a call will make the operator signal {@link IllegalStateException}.
2312 * @return the new {@code Observable} instance
2313 * @throws NullPointerException if {@code initialState} or {@code generator} is {@code null}
2314 */
2315 @CheckReturnValue
2316 @NonNull
2317 @SchedulerSupport(SchedulerSupport.NONE)
2318 public static <@NonNull T, @NonNull S> Observable<T> generate(@NonNull Supplier<S> initialState, @NonNull BiConsumer<S, Emitter<T>> generator) {
2319 Objects.requireNonNull(generator, "generator is null");
2320 return generate(initialState, ObservableInternalHelper.simpleBiGenerator(generator), Functions.emptyConsumer());
2321 }
2322
2323 /**
2324 * Returns a cold, synchronous and stateful generator of values.
2325 * <p>
2326 * <img width="640" height="315" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/generate.2.v3.png" alt="">
2327 * <p>
2328 * Note that the {@link Emitter#onNext}, {@link Emitter#onError} and
2329 * {@link Emitter#onComplete} methods provided to the function via the {@link Emitter} instance should be called synchronously,
2330 * never concurrently and only while the function body is executing. Calling them from multiple threads
2331 * or outside the function call is not supported and leads to an undefined behavior.
2332 * <dl>
2333 * <dt><b>Scheduler:</b></dt>
2334 * <dd>{@code generate} does not operate by default on a particular {@link Scheduler}.</dd>
2335 * </dl>
2336 *
2337 * @param <S> the type of the per-{@link Observer} state
2338 * @param <T> the generated value type
2339 * @param initialState the {@link Supplier} to generate the initial state for each {@code Observer}
2340 * @param generator the {@link BiConsumer} called in a loop after a downstream {@code Observer} has
2341 * subscribed. The callback then should call {@code onNext}, {@code onError} or
2342 * {@code onComplete} to signal a value or a terminal event. Signaling multiple {@code onNext}
2343 * in a call will make the operator signal {@link IllegalStateException}.
2344 * @param disposeState the {@link Consumer} that is called with the current state when the generator
2345 * terminates the sequence or it gets disposed
2346 * @return the new {@code Observable} instance
2347 * @throws NullPointerException if {@code initialState}, {@code generator} or {@code disposeState} is {@code null}
2348 */
2349 @CheckReturnValue
2350 @NonNull
2351 @SchedulerSupport(SchedulerSupport.NONE)
2352 public static <@NonNull T, @NonNull S> Observable<T> generate(
2353 @NonNull Supplier<S> initialState,
2354 @NonNull BiConsumer<S, Emitter<T>> generator,
2355 @NonNull Consumer<? super S> disposeState) {
2356 Objects.requireNonNull(generator, "generator is null");
2357 return generate(initialState, ObservableInternalHelper.simpleBiGenerator(generator), disposeState);
2358 }
2359
2360 /**
2361 * Returns a cold, synchronous and stateful generator of values.
2362 * <p>
2363 * <img width="640" height="315" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/generate.2.v3.png" alt="">
2364 * <p>
2365 * Note that the {@link Emitter#onNext}, {@link Emitter#onError} and
2366 * {@link Emitter#onComplete} methods provided to the function via the {@link Emitter} instance should be called synchronously,
2367 * never concurrently and only while the function body is executing. Calling them from multiple threads
2368 * or outside the function call is not supported and leads to an undefined behavior.
2369 * <dl>
2370 * <dt><b>Scheduler:</b></dt>
2371 * <dd>{@code generate} does not operate by default on a particular {@link Scheduler}.</dd>
2372 * </dl>
2373 *
2374 * @param <S> the type of the per-{@link Observer} state
2375 * @param <T> the generated value type
2376 * @param initialState the {@link Supplier} to generate the initial state for each {@code Observer}
2377 * @param generator the {@link BiConsumer} called in a loop after a downstream {@code Observer} has
2378 * subscribed. The callback then should call {@code onNext}, {@code onError} or
2379 * {@code onComplete} to signal a value or a terminal event and should return a (new) state for
2380 * the next invocation. Signaling multiple {@code onNext}
2381 * in a call will make the operator signal {@link IllegalStateException}.
2382 * @return the new {@code Observable} instance
2383 * @throws NullPointerException if {@code initialState} or {@code generator} is {@code null}
2384 */
2385 @CheckReturnValue
2386 @SchedulerSupport(SchedulerSupport.NONE)
2387 @NonNull
2388 public static <@NonNull T, @NonNull S> Observable<T> generate(@NonNull Supplier<S> initialState, @NonNull BiFunction<S, Emitter<T>, S> generator) {
2389 return generate(initialState, generator, Functions.emptyConsumer());
2390 }
2391
2392 /**
2393 * Returns a cold, synchronous and stateful generator of values.
2394 * <p>
2395 * <img width="640" height="315" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/generate.2.v3.png" alt="">
2396 * <p>
2397 * Note that the {@link Emitter#onNext}, {@link Emitter#onError} and
2398 * {@link Emitter#onComplete} methods provided to the function via the {@link Emitter} instance should be called synchronously,
2399 * never concurrently and only while the function body is executing. Calling them from multiple threads
2400 * or outside the function call is not supported and leads to an undefined behavior.
2401 * <dl>
2402 * <dt><b>Scheduler:</b></dt>
2403 * <dd>{@code generate} does not operate by default on a particular {@link Scheduler}.</dd>
2404 * </dl>
2405 *
2406 * @param <S> the type of the per-{@link Observer} state
2407 * @param <T> the generated value type
2408 * @param initialState the {@link Supplier} to generate the initial state for each {@code Observer}
2409 * @param generator the {@link BiConsumer} called in a loop after a downstream {@code Observer} has
2410 * subscribed. The callback then should call {@code onNext}, {@code onError} or
2411 * {@code onComplete} to signal a value or a terminal event and should return a (new) state for
2412 * the next invocation. Signaling multiple {@code onNext}
2413 * in a call will make the operator signal {@link IllegalStateException}.
2414 * @param disposeState the {@link Consumer} that is called with the current state when the generator
2415 * terminates the sequence or it gets disposed
2416 * @return the new {@code Observable} instance
2417 * @throws NullPointerException if {@code initialState}, {@code generator} or {@code disposeState} is {@code null}
2418 */
2419 @CheckReturnValue
2420 @NonNull
2421 @SchedulerSupport(SchedulerSupport.NONE)
2422 public static <@NonNull T, @NonNull S> Observable<T> generate(@NonNull Supplier<S> initialState, @NonNull BiFunction<S, Emitter<T>, S> generator,
2423 @NonNull Consumer<? super S> disposeState) {
2424 Objects.requireNonNull(initialState, "initialState is null");
2425 Objects.requireNonNull(generator, "generator is null");
2426 Objects.requireNonNull(disposeState, "disposeState is null");
2427 return RxJavaPlugins.onAssembly(new ObservableGenerate<>(initialState, generator, disposeState));
2428 }
2429
2430 /**
2431 * Returns an {@code Observable} that emits a {@code 0L} after the {@code initialDelay} and ever increasing numbers
2432 * after each {@code period} of time thereafter.
2433 * <p>
2434 * <img width="640" height="200" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/timer.p.v3.png" alt="">
2435 * <dl>
2436 * <dt><b>Scheduler:</b></dt>
2437 * <dd>{@code interval} operates by default on the {@code computation} {@link Scheduler}.</dd>
2438 * </dl>
2439 *
2440 * @param initialDelay
2441 * the initial delay time to wait before emitting the first value of 0L
2442 * @param period
2443 * the period of time between emissions of the subsequent numbers
2444 * @param unit
2445 * the time unit for both {@code initialDelay} and {@code period}
2446 * @return the new {@code Observable} instance
2447 * @see <a href="http://reactivex.io/documentation/operators/interval.html">ReactiveX operators documentation: Interval</a>
2448 * @throws NullPointerException if {@code unit} is {@code null}
2449 * @since 1.0.12
2450 */
2451 @CheckReturnValue
2452 @SchedulerSupport(SchedulerSupport.COMPUTATION)
2453 @NonNull
2454 public static Observable<Long> interval(long initialDelay, long period, @NonNull TimeUnit unit) {
2455 return interval(initialDelay, period, unit, Schedulers.computation());
2456 }
2457
2458 /**
2459 * Returns an {@code Observable} that emits a {@code 0L} after the {@code initialDelay} and ever increasing numbers
2460 * after each {@code period} of time thereafter, on a specified {@link Scheduler}.
2461 * <p>
2462 * <img width="640" height="200" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/timer.ps.v3.png" alt="">
2463 * <dl>
2464 * <dt><b>Scheduler:</b></dt>
2465 * <dd>You specify which {@code Scheduler} this operator will use.</dd>
2466 * </dl>
2467 *
2468 * @param initialDelay
2469 * the initial delay time to wait before emitting the first value of 0L
2470 * @param period
2471 * the period of time between emissions of the subsequent numbers
2472 * @param unit
2473 * the time unit for both {@code initialDelay} and {@code period}
2474 * @param scheduler
2475 * the {@code Scheduler} on which the waiting happens and items are emitted
2476 * @return the new {@code Observable} instance
2477 * @see <a href="http://reactivex.io/documentation/operators/interval.html">ReactiveX operators documentation: Interval</a>
2478 * @since 1.0.12
2479 * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null}
2480 */
2481 @CheckReturnValue
2482 @NonNull
2483 @SchedulerSupport(SchedulerSupport.CUSTOM)
2484 public static Observable<Long> interval(long initialDelay, long period, @NonNull TimeUnit unit, @NonNull Scheduler scheduler) {
2485 Objects.requireNonNull(unit, "unit is null");
2486 Objects.requireNonNull(scheduler, "scheduler is null");
2487
2488 return RxJavaPlugins.onAssembly(new ObservableInterval(Math.max(0L, initialDelay), Math.max(0L, period), unit, scheduler));
2489 }
2490
2491 /**
2492 * Returns an {@code Observable} that emits a sequential number every specified interval of time.
2493 * <p>
2494 * <img width="640" height="195" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/interval.v3.png" alt="">
2495 * <dl>
2496 * <dt><b>Scheduler:</b></dt>
2497 * <dd>{@code interval} operates by default on the {@code computation} {@link Scheduler}.</dd>
2498 * </dl>
2499 *
2500 * @param period
2501 * the period size in time units (see below)
2502 * @param unit
2503 * time units to use for the interval size
2504 * @return the new {@code Observable} instance
2505 * @throws NullPointerException if {@code unit} is {@code null}
2506 * @see <a href="http://reactivex.io/documentation/operators/interval.html">ReactiveX operators documentation: Interval</a>
2507 */
2508 @CheckReturnValue
2509 @SchedulerSupport(SchedulerSupport.COMPUTATION)
2510 @NonNull
2511 public static Observable<Long> interval(long period, @NonNull TimeUnit unit) {
2512 return interval(period, period, unit, Schedulers.computation());
2513 }
2514
2515 /**
2516 * Returns an {@code Observable} that emits a sequential number every specified interval of time, on a
2517 * specified {@link Scheduler}.
2518 * <p>
2519 * <img width="640" height="200" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/interval.s.v3.png" alt="">
2520 * <dl>
2521 * <dt><b>Scheduler:</b></dt>
2522 * <dd>You specify which {@code Scheduler} this operator will use.</dd>
2523 * </dl>
2524 *
2525 * @param period
2526 * the period size in time units (see below)
2527 * @param unit
2528 * time units to use for the interval size
2529 * @param scheduler
2530 * the {@code Scheduler} to use for scheduling the items
2531 * @return the new {@code Observable} instance
2532 * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null}
2533 * @see <a href="http://reactivex.io/documentation/operators/interval.html">ReactiveX operators documentation: Interval</a>
2534 */
2535 @CheckReturnValue
2536 @SchedulerSupport(SchedulerSupport.CUSTOM)
2537 @NonNull
2538 public static Observable<Long> interval(long period, @NonNull TimeUnit unit, @NonNull Scheduler scheduler) {
2539 return interval(period, period, unit, scheduler);
2540 }
2541
2542 /**
2543 * Signals a range of long values, the first after some initial delay and the rest periodically after.
2544 * <p>
2545 * The sequence completes immediately after the last value (start + count - 1) has been reached.
2546 * <p>
2547 * <img width="640" height="195" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/intervalRange.v3.png" alt="">
2548 * <dl>
2549 * <dt><b>Scheduler:</b></dt>
2550 * <dd>{@code intervalRange} by default operates on the {@link Schedulers#computation() computation} {@link Scheduler}.</dd>
2551 * </dl>
2552 * @param start that start value of the range
2553 * @param count the number of values to emit in total, if zero, the operator emits an {@code onComplete} after the initial delay.
2554 * @param initialDelay the initial delay before signaling the first value (the start)
2555 * @param period the period between subsequent values
2556 * @param unit the unit of measure of the {@code initialDelay} and {@code period} amounts
2557 * @return the new {@code Observable} instance
2558 * @throws NullPointerException if {@code unit} is {@code null}
2559 * @throws IllegalArgumentException
2560 * if {@code count} is negative, or if {@code start} + {@code count} &minus; 1 exceeds
2561 * {@link Long#MAX_VALUE}
2562 * @see #range(int, int)
2563 */
2564 @CheckReturnValue
2565 @NonNull
2566 @SchedulerSupport(SchedulerSupport.COMPUTATION)
2567 public static Observable<Long> intervalRange(long start, long count, long initialDelay, long period, @NonNull TimeUnit unit) {
2568 return intervalRange(start, count, initialDelay, period, unit, Schedulers.computation());
2569 }
2570
2571 /**
2572 * Signals a range of long values, the first after some initial delay and the rest periodically after.
2573 * <p>
2574 * The sequence completes immediately after the last value (start + count - 1) has been reached.
2575 * <p>
2576 * <img width="640" height="195" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/intervalRange.s.v3.png" alt=""> * <dl>
2577 * <dt><b>Scheduler:</b></dt>
2578 * <dd>you provide the {@link Scheduler}.</dd>
2579 * </dl>
2580 * @param start that start value of the range
2581 * @param count the number of values to emit in total, if zero, the operator emits an {@code onComplete} after the initial delay.
2582 * @param initialDelay the initial delay before signaling the first value (the start)
2583 * @param period the period between subsequent values
2584 * @param unit the unit of measure of the {@code initialDelay} and {@code period} amounts
2585 * @param scheduler the target scheduler where the values and terminal signals will be emitted
2586 * @return the new {@code Observable} instance
2587 * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null}
2588 * @throws IllegalArgumentException
2589 * if {@code count} is negative, or if {@code start} + {@code count} &minus; 1 exceeds
2590 * {@link Long#MAX_VALUE}
2591 */
2592 @CheckReturnValue
2593 @NonNull
2594 @SchedulerSupport(SchedulerSupport.CUSTOM)
2595 public static Observable<Long> intervalRange(long start, long count, long initialDelay, long period, @NonNull TimeUnit unit, @NonNull Scheduler scheduler) {
2596 if (count < 0) {
2597 throw new IllegalArgumentException("count >= 0 required but it was " + count);
2598 }
2599
2600 if (count == 0L) {
2601 return Observable.<Long>empty().delay(initialDelay, unit, scheduler);
2602 }
2603
2604 long end = start + (count - 1);
2605 if (start > 0 && end < 0) {
2606 throw new IllegalArgumentException("Overflow! start + count is bigger than Long.MAX_VALUE");
2607 }
2608 Objects.requireNonNull(unit, "unit is null");
2609 Objects.requireNonNull(scheduler, "scheduler is null");
2610
2611 return RxJavaPlugins.onAssembly(new ObservableIntervalRange(start, end, Math.max(0L, initialDelay), Math.max(0L, period), unit, scheduler));
2612 }
2613
2614 /**
2615 * Returns an {@code Observable} that signals the given (constant reference) item and then completes.
2616 * <p>
2617 * <img width="640" height="290" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/just.item.png" alt="">
2618 * <p>
2619 * Note that the item is taken and re-emitted as is and not computed by any means by {@code just}. Use {@link #fromCallable(Callable)}
2620 * to generate a single item on demand (when {@link Observer}s subscribe to it).
2621 * <p>
2622 * See the multi-parameter overloads of {@code just} to emit more than one (constant reference) items one after the other.
2623 * Use {@link #fromArray(Object...)} to emit an arbitrary number of items that are known upfront.
2624 * <p>
2625 * To emit the items of an {@link Iterable} sequence (such as a {@link java.util.List}), use {@link #fromIterable(Iterable)}.
2626 * <dl>
2627 * <dt><b>Scheduler:</b></dt>
2628 * <dd>{@code just} does not operate by default on a particular {@link Scheduler}.</dd>
2629 * </dl>
2630 *
2631 * @param item
2632 * the item to emit
2633 * @param <T>
2634 * the type of that item
2635 * @return the new {@code Observable} instance
2636 * @throws NullPointerException if {@code item} is {@code null}
2637 * @see <a href="http://reactivex.io/documentation/operators/just.html">ReactiveX operators documentation: Just</a>
2638 * @see #just(Object, Object)
2639 * @see #fromCallable(Callable)
2640 * @see #fromArray(Object...)
2641 * @see #fromIterable(Iterable)
2642 */
2643 @CheckReturnValue
2644 @NonNull
2645 @SchedulerSupport(SchedulerSupport.NONE)
2646 public static <@NonNull T> Observable<T> just(@NonNull T item) {
2647 Objects.requireNonNull(item, "item is null");
2648 return RxJavaPlugins.onAssembly(new ObservableJust<>(item));
2649 }
2650
2651 /**
2652 * Converts two items into an {@code Observable} that emits those items.
2653 * <p>
2654 * <img width="640" height="186" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/just.2.v3.png" alt="">
2655 * <dl>
2656 * <dt><b>Scheduler:</b></dt>
2657 * <dd>{@code just} does not operate by default on a particular {@link Scheduler}.</dd>
2658 * </dl>
2659 *
2660 * @param item1
2661 * first item
2662 * @param item2
2663 * second item
2664 * @param <T>
2665 * the type of these items
2666 * @return the new {@code Observable} instance
2667 * @throws NullPointerException if {@code item1} or {@code item2} is {@code null}
2668 * @see <a href="http://reactivex.io/documentation/operators/just.html">ReactiveX operators documentation: Just</a>
2669 */
2670 @CheckReturnValue
2671 @NonNull
2672 @SchedulerSupport(SchedulerSupport.NONE)
2673 public static <@NonNull T> Observable<T> just(@NonNull T item1, @NonNull T item2) {
2674 Objects.requireNonNull(item1, "item1 is null");
2675 Objects.requireNonNull(item2, "item2 is null");
2676
2677 return fromArray(item1, item2);
2678 }
2679
2680 /**
2681 * Converts three items into an {@code Observable} that emits those items.
2682 * <p>
2683 * <img width="640" height="186" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/just.3.v3.png" alt="">
2684 * <dl>
2685 * <dt><b>Scheduler:</b></dt>
2686 * <dd>{@code just} does not operate by default on a particular {@link Scheduler}.</dd>
2687 * </dl>
2688 *
2689 * @param item1
2690 * first item
2691 * @param item2
2692 * second item
2693 * @param item3
2694 * third item
2695 * @param <T>
2696 * the type of these items
2697 * @return the new {@code Observable} instance
2698 * @throws NullPointerException if {@code item1}, {@code item2} or {@code item3} is {@code null}
2699 * @see <a href="http://reactivex.io/documentation/operators/just.html">ReactiveX operators documentation: Just</a>
2700 */
2701 @CheckReturnValue
2702 @NonNull
2703 @SchedulerSupport(SchedulerSupport.NONE)
2704 public static <@NonNull T> Observable<T> just(@NonNull T item1, @NonNull T item2, @NonNull T item3) {
2705 Objects.requireNonNull(item1, "item1 is null");
2706 Objects.requireNonNull(item2, "item2 is null");
2707 Objects.requireNonNull(item3, "item3 is null");
2708
2709 return fromArray(item1, item2, item3);
2710 }
2711
2712 /**
2713 * Converts four items into an {@code Observable} that emits those items.
2714 * <p>
2715 * <img width="640" height="186" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/just.4.v3.png" alt="">
2716 * <dl>
2717 * <dt><b>Scheduler:</b></dt>
2718 * <dd>{@code just} does not operate by default on a particular {@link Scheduler}.</dd>
2719 * </dl>
2720 *
2721 * @param item1
2722 * first item
2723 * @param item2
2724 * second item
2725 * @param item3
2726 * third item
2727 * @param item4
2728 * fourth item
2729 * @param <T>
2730 * the type of these items
2731 * @return the new {@code Observable} instance
2732 * @throws NullPointerException if {@code item1}, {@code item2}, {@code item3} or {@code item4} is {@code null}
2733 * @see <a href="http://reactivex.io/documentation/operators/just.html">ReactiveX operators documentation: Just</a>
2734 */
2735 @CheckReturnValue
2736 @NonNull
2737 @SchedulerSupport(SchedulerSupport.NONE)
2738 public static <@NonNull T> Observable<T> just(@NonNull T item1, @NonNull T item2, @NonNull T item3, @NonNull T item4) {
2739 Objects.requireNonNull(item1, "item1 is null");
2740 Objects.requireNonNull(item2, "item2 is null");
2741 Objects.requireNonNull(item3, "item3 is null");
2742 Objects.requireNonNull(item4, "item4 is null");
2743
2744 return fromArray(item1, item2, item3, item4);
2745 }
2746
2747 /**
2748 * Converts five items into an {@code Observable} that emits those items.
2749 * <p>
2750 * <img width="640" height="186" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/just.5.v3.png" alt="">
2751 * <dl>
2752 * <dt><b>Scheduler:</b></dt>
2753 * <dd>{@code just} does not operate by default on a particular {@link Scheduler}.</dd>
2754 * </dl>
2755 *
2756 * @param item1
2757 * first item
2758 * @param item2
2759 * second item
2760 * @param item3
2761 * third item
2762 * @param item4
2763 * fourth item
2764 * @param item5
2765 * fifth item
2766 * @param <T>
2767 * the type of these items
2768 * @return the new {@code Observable} instance
2769 * @throws NullPointerException if {@code item1}, {@code item2}, {@code item3},
2770 * {@code item4} or {@code item5} is {@code null}
2771 * @see <a href="http://reactivex.io/documentation/operators/just.html">ReactiveX operators documentation: Just</a>
2772 */
2773 @CheckReturnValue
2774 @NonNull
2775 @SchedulerSupport(SchedulerSupport.NONE)
2776 public static <@NonNull T> Observable<T> just(@NonNull T item1, @NonNull T item2, @NonNull T item3, @NonNull T item4, @NonNull T item5) {
2777 Objects.requireNonNull(item1, "item1 is null");
2778 Objects.requireNonNull(item2, "item2 is null");
2779 Objects.requireNonNull(item3, "item3 is null");
2780 Objects.requireNonNull(item4, "item4 is null");
2781 Objects.requireNonNull(item5, "item5 is null");
2782
2783 return fromArray(item1, item2, item3, item4, item5);
2784 }
2785
2786 /**
2787 * Converts six items into an {@code Observable} that emits those items.
2788 * <p>
2789 * <img width="640" height="186" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/just.6.v3.png" alt="">
2790 * <dl>
2791 * <dt><b>Scheduler:</b></dt>
2792 * <dd>{@code just} does not operate by default on a particular {@link Scheduler}.</dd>
2793 * </dl>
2794 *
2795 * @param item1
2796 * first item
2797 * @param item2
2798 * second item
2799 * @param item3
2800 * third item
2801 * @param item4
2802 * fourth item
2803 * @param item5
2804 * fifth item
2805 * @param item6
2806 * sixth item
2807 * @param <T>
2808 * the type of these items
2809 * @return the new {@code Observable} instance
2810 * @throws NullPointerException if {@code item1}, {@code item2}, {@code item3},
2811 * {@code item4}, {@code item5} or {@code item6} is {@code null}
2812 * @see <a href="http://reactivex.io/documentation/operators/just.html">ReactiveX operators documentation: Just</a>
2813 */
2814 @CheckReturnValue
2815 @NonNull
2816 @SchedulerSupport(SchedulerSupport.NONE)
2817 public static <@NonNull T> Observable<T> just(@NonNull T item1, @NonNull T item2, @NonNull T item3, @NonNull T item4, @NonNull T item5, @NonNull T item6) {
2818 Objects.requireNonNull(item1, "item1 is null");
2819 Objects.requireNonNull(item2, "item2 is null");
2820 Objects.requireNonNull(item3, "item3 is null");
2821 Objects.requireNonNull(item4, "item4 is null");
2822 Objects.requireNonNull(item5, "item5 is null");
2823 Objects.requireNonNull(item6, "item6 is null");
2824
2825 return fromArray(item1, item2, item3, item4, item5, item6);
2826 }
2827
2828 /**
2829 * Converts seven items into an {@code Observable} that emits those items.
2830 * <p>
2831 * <img width="640" height="186" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/just.7.v3.png" alt="">
2832 * <dl>
2833 * <dt><b>Scheduler:</b></dt>
2834 * <dd>{@code just} does not operate by default on a particular {@link Scheduler}.</dd>
2835 * </dl>
2836 *
2837 * @param item1
2838 * first item
2839 * @param item2
2840 * second item
2841 * @param item3
2842 * third item
2843 * @param item4
2844 * fourth item
2845 * @param item5
2846 * fifth item
2847 * @param item6
2848 * sixth item
2849 * @param item7
2850 * seventh item
2851 * @param <T>
2852 * the type of these items
2853 * @return the new {@code Observable} instance
2854 * @throws NullPointerException if {@code item1}, {@code item2}, {@code item3},
2855 * {@code item4}, {@code item5}, {@code item6}
2856 * or {@code item7} is {@code null}
2857 * @see <a href="http://reactivex.io/documentation/operators/just.html">ReactiveX operators documentation: Just</a>
2858 */
2859 @CheckReturnValue
2860 @NonNull
2861 @SchedulerSupport(SchedulerSupport.NONE)
2862 public static <@NonNull T> Observable<T> just(@NonNull T item1, @NonNull T item2, @NonNull T item3, @NonNull T item4, @NonNull T item5, @NonNull T item6, @NonNull T item7) {
2863 Objects.requireNonNull(item1, "item1 is null");
2864 Objects.requireNonNull(item2, "item2 is null");
2865 Objects.requireNonNull(item3, "item3 is null");
2866 Objects.requireNonNull(item4, "item4 is null");
2867 Objects.requireNonNull(item5, "item5 is null");
2868 Objects.requireNonNull(item6, "item6 is null");
2869 Objects.requireNonNull(item7, "item7 is null");
2870
2871 return fromArray(item1, item2, item3, item4, item5, item6, item7);
2872 }
2873
2874 /**
2875 * Converts eight items into an {@code Observable} that emits those items.
2876 * <p>
2877 * <img width="640" height="186" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/just.8.v3.png" alt="">
2878 * <dl>
2879 * <dt><b>Scheduler:</b></dt>
2880 * <dd>{@code just} does not operate by default on a particular {@link Scheduler}.</dd>
2881 * </dl>
2882 *
2883 * @param item1
2884 * first item
2885 * @param item2
2886 * second item
2887 * @param item3
2888 * third item
2889 * @param item4
2890 * fourth item
2891 * @param item5
2892 * fifth item
2893 * @param item6
2894 * sixth item
2895 * @param item7
2896 * seventh item
2897 * @param item8
2898 * eighth item
2899 * @param <T>
2900 * the type of these items
2901 * @return the new {@code Observable} instance
2902 * @throws NullPointerException if {@code item1}, {@code item2}, {@code item3},
2903 * {@code item4}, {@code item5}, {@code item6}
2904 * {@code item7} or {@code item8} is {@code null}
2905 * @see <a href="http://reactivex.io/documentation/operators/just.html">ReactiveX operators documentation: Just</a>
2906 */
2907 @CheckReturnValue
2908 @NonNull
2909 @SchedulerSupport(SchedulerSupport.NONE)
2910 public static <@NonNull T> Observable<T> just(@NonNull T item1, @NonNull T item2, @NonNull T item3, @NonNull T item4, @NonNull T item5, @NonNull T item6, @NonNull T item7, @NonNull T item8) {
2911 Objects.requireNonNull(item1, "item1 is null");
2912 Objects.requireNonNull(item2, "item2 is null");
2913 Objects.requireNonNull(item3, "item3 is null");
2914 Objects.requireNonNull(item4, "item4 is null");
2915 Objects.requireNonNull(item5, "item5 is null");
2916 Objects.requireNonNull(item6, "item6 is null");
2917 Objects.requireNonNull(item7, "item7 is null");
2918 Objects.requireNonNull(item8, "item8 is null");
2919
2920 return fromArray(item1, item2, item3, item4, item5, item6, item7, item8);
2921 }
2922
2923 /**
2924 * Converts nine items into an {@code Observable} that emits those items.
2925 * <p>
2926 * <img width="640" height="186" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/just.9.v3.png" alt="">
2927 * <dl>
2928 * <dt><b>Scheduler:</b></dt>
2929 * <dd>{@code just} does not operate by default on a particular {@link Scheduler}.</dd>
2930 * </dl>
2931 *
2932 * @param item1
2933 * first item
2934 * @param item2
2935 * second item
2936 * @param item3
2937 * third item
2938 * @param item4
2939 * fourth item
2940 * @param item5
2941 * fifth item
2942 * @param item6
2943 * sixth item
2944 * @param item7
2945 * seventh item
2946 * @param item8
2947 * eighth item
2948 * @param item9
2949 * ninth item
2950 * @param <T>
2951 * the type of these items
2952 * @return the new {@code Observable} instance
2953 * @throws NullPointerException if {@code item1}, {@code item2}, {@code item3},
2954 * {@code item4}, {@code item5}, {@code item6}
2955 * {@code item7}, {@code item8} or {@code item9} is {@code null}
2956 * @see <a href="http://reactivex.io/documentation/operators/just.html">ReactiveX operators documentation: Just</a>
2957 */
2958 @CheckReturnValue
2959 @NonNull
2960 @SchedulerSupport(SchedulerSupport.NONE)
2961 public static <@NonNull T> Observable<T> just(@NonNull T item1, @NonNull T item2, @NonNull T item3, @NonNull T item4, @NonNull T item5, @NonNull T item6, @NonNull T item7, @NonNull T item8, @NonNull T item9) {
2962 Objects.requireNonNull(item1, "item1 is null");
2963 Objects.requireNonNull(item2, "item2 is null");
2964 Objects.requireNonNull(item3, "item3 is null");
2965 Objects.requireNonNull(item4, "item4 is null");
2966 Objects.requireNonNull(item5, "item5 is null");
2967 Objects.requireNonNull(item6, "item6 is null");
2968 Objects.requireNonNull(item7, "item7 is null");
2969 Objects.requireNonNull(item8, "item8 is null");
2970 Objects.requireNonNull(item9, "item9 is null");
2971
2972 return fromArray(item1, item2, item3, item4, item5, item6, item7, item8, item9);
2973 }
2974
2975 /**
2976 * Converts ten items into an {@code Observable} that emits those items.
2977 * <p>
2978 * <img width="640" height="186" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/just.10.v3.png" alt="">
2979 * <dl>
2980 * <dt><b>Scheduler:</b></dt>
2981 * <dd>{@code just} does not operate by default on a particular {@link Scheduler}.</dd>
2982 * </dl>
2983 *
2984 * @param item1
2985 * first item
2986 * @param item2
2987 * second item
2988 * @param item3
2989 * third item
2990 * @param item4
2991 * fourth item
2992 * @param item5
2993 * fifth item
2994 * @param item6
2995 * sixth item
2996 * @param item7
2997 * seventh item
2998 * @param item8
2999 * eighth item
3000 * @param item9
3001 * ninth item
3002 * @param item10
3003 * tenth item
3004 * @param <T>
3005 * the type of these items
3006 * @return the new {@code Observable} instance
3007 * @throws NullPointerException if {@code item1}, {@code item2}, {@code item3},
3008 * {@code item4}, {@code item5}, {@code item6}
3009 * {@code item7}, {@code item8}, {@code item9}
3010 * or {@code item10} is {@code null}
3011 * @see <a href="http://reactivex.io/documentation/operators/just.html">ReactiveX operators documentation: Just</a>
3012 */
3013 @CheckReturnValue
3014 @NonNull
3015 @SchedulerSupport(SchedulerSupport.NONE)
3016 public static <@NonNull T> Observable<T> just(@NonNull T item1, @NonNull T item2, @NonNull T item3, @NonNull T item4, @NonNull T item5, @NonNull T item6, @NonNull T item7, @NonNull T item8, @NonNull T item9, @NonNull T item10) {
3017 Objects.requireNonNull(item1, "item1 is null");
3018 Objects.requireNonNull(item2, "item2 is null");
3019 Objects.requireNonNull(item3, "item3 is null");
3020 Objects.requireNonNull(item4, "item4 is null");
3021 Objects.requireNonNull(item5, "item5 is null");
3022 Objects.requireNonNull(item6, "item6 is null");
3023 Objects.requireNonNull(item7, "item7 is null");
3024 Objects.requireNonNull(item8, "item8 is null");
3025 Objects.requireNonNull(item9, "item9 is null");
3026 Objects.requireNonNull(item10, "item10 is null");
3027
3028 return fromArray(item1, item2, item3, item4, item5, item6, item7, item8, item9, item10);
3029 }
3030
3031 /**
3032 * Flattens an {@link Iterable} of {@link ObservableSource}s into one {@code Observable}, without any transformation, while limiting the
3033 * number of concurrent subscriptions to these {@code ObservableSource}s.
3034 * <p>
3035 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/merge.v3.png" alt="">
3036 * <p>
3037 * You can combine the items emitted by multiple {@code ObservableSource}s so that they appear as a single {@code ObservableSource}, by
3038 * using the {@code merge} method.
3039 * <dl>
3040 * <dt><b>Scheduler:</b></dt>
3041 * <dd>{@code merge} does not operate by default on a particular {@link Scheduler}.</dd>
3042 * <dt><b>Error handling:</b></dt>
3043 * <dd>If any of the returned {@code ObservableSource}s signal a {@link Throwable} via {@code onError}, the resulting
3044 * {@code Observable} terminates with that {@code Throwable} and all other source {@code ObservableSource}s are disposed.
3045 * If more than one {@code ObservableSource} signals an error, the resulting {@code Observable} may terminate with the
3046 * first one's error or, depending on the concurrency of the sources, may terminate with a
3047 * {@link CompositeException} containing two or more of the various error signals.
3048 * {@code Throwable}s that didn't make into the composite will be sent (individually) to the global error handler via
3049 * {@link RxJavaPlugins#onError(Throwable)} method as {@link UndeliverableException} errors. Similarly, {@code Throwable}s
3050 * signaled by source(s) after the returned {@code Observable} has been disposed or terminated with a
3051 * (composite) error will be sent to the same global error handler.
3052 * Use {@link #mergeDelayError(Iterable, int, int)} to merge sources and terminate only when all source {@code ObservableSource}s
3053 * have completed or failed with an error.
3054 * </dd>
3055 * </dl>
3056 *
3057 * @param <T> the common element base type
3058 * @param sources
3059 * the {@code Iterable} of {@code ObservableSource}s
3060 * @param maxConcurrency
3061 * the maximum number of {@code ObservableSource}s that may be subscribed to concurrently
3062 * @param bufferSize
3063 * the number of items expected from each inner {@code ObservableSource} to be buffered
3064 * @return the new {@code Observable} instance
3065 * @throws NullPointerException if {@code sources} is {@code null}
3066 * @throws IllegalArgumentException
3067 * if {@code maxConcurrency} or {@code bufferSize} is non-positive
3068 * @see <a href="http://reactivex.io/documentation/operators/merge.html">ReactiveX operators documentation: Merge</a>
3069 * @see #mergeDelayError(Iterable, int, int)
3070 */
3071 @SuppressWarnings({ "unchecked", "rawtypes" })
3072 @CheckReturnValue
3073 @SchedulerSupport(SchedulerSupport.NONE)
3074 @NonNull
3075 public static <@NonNull T> Observable<T> merge(@NonNull Iterable<@NonNull ? extends ObservableSource<? extends T>> sources, int maxConcurrency, int bufferSize) {
3076 return fromIterable(sources).flatMap((Function)Functions.identity(), false, maxConcurrency, bufferSize);
3077 }
3078
3079 /**
3080 * Flattens an array of {@link ObservableSource}s into one {@code Observable}, without any transformation, while limiting the
3081 * number of concurrent subscriptions to these {@code ObservableSource}s.
3082 * <p>
3083 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/merge.v3.png" alt="">
3084 * <p>
3085 * You can combine the items emitted by multiple {@code ObservableSource}s so that they appear as a single {@code ObservableSource}, by
3086 * using the {@code merge} method.
3087 * <dl>
3088 * <dt><b>Scheduler:</b></dt>
3089 * <dd>{@code mergeArray} does not operate by default on a particular {@link Scheduler}.</dd>
3090 * <dt><b>Error handling:</b></dt>
3091 * <dd>If any of the {@code ObservableSource}s signal a {@link Throwable} via {@code onError}, the resulting
3092 * {@code Observable} terminates with that {@code Throwable} and all other source {@code ObservableSource}s are disposed.
3093 * If more than one {@code ObservableSource} signals an error, the resulting {@code Observable} may terminate with the
3094 * first one's error or, depending on the concurrency of the sources, may terminate with a
3095 * {@link CompositeException} containing two or more of the various error signals.
3096 * {@code Throwable}s that didn't make into the composite will be sent (individually) to the global error handler via
3097 * {@link RxJavaPlugins#onError(Throwable)} method as {@link UndeliverableException} errors. Similarly, {@code Throwable}s
3098 * signaled by source(s) after the returned {@code Observable} has been disposed or terminated with a
3099 * (composite) error will be sent to the same global error handler.
3100 * Use {@link #mergeArrayDelayError(int, int, ObservableSource...)} to merge sources and terminate only when all source {@code ObservableSource}s
3101 * have completed or failed with an error.
3102 * </dd>
3103 * </dl>
3104 *
3105 * @param <T> the common element base type
3106 * @param sources
3107 * the array of {@code ObservableSource}s
3108 * @param maxConcurrency
3109 * the maximum number of {@code ObservableSource}s that may be subscribed to concurrently
3110 * @param bufferSize
3111 * the number of items expected from each inner {@code ObservableSource} to be buffered
3112 * @return the new {@code Observable} instance
3113 * @throws NullPointerException if {@code sources} is {@code null}
3114 * @throws IllegalArgumentException
3115 * if {@code maxConcurrency} or {@code bufferSize} is non-positive
3116 * @see <a href="http://reactivex.io/documentation/operators/merge.html">ReactiveX operators documentation: Merge</a>
3117 * @see #mergeArrayDelayError(int, int, ObservableSource...)
3118 */
3119 @SuppressWarnings({ "unchecked", "rawtypes" })
3120 @CheckReturnValue
3121 @SchedulerSupport(SchedulerSupport.NONE)
3122 @NonNull
3123 @SafeVarargs
3124 public static <@NonNull T> Observable<T> mergeArray(int maxConcurrency, int bufferSize, @NonNull ObservableSource<? extends T>... sources) {
3125 return fromArray(sources).flatMap((Function)Functions.identity(), false, maxConcurrency, bufferSize);
3126 }
3127
3128 /**
3129 * Flattens an {@link Iterable} of {@link ObservableSource}s into one {@code Observable}, without any transformation.
3130 * <p>
3131 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/merge.v3.png" alt="">
3132 * <p>
3133 * You can combine the items emitted by multiple {@code ObservableSource}s so that they appear as a single {@code ObservableSource}, by
3134 * using the {@code merge} method.
3135 * <dl>
3136 * <dt><b>Scheduler:</b></dt>
3137 * <dd>{@code merge} does not operate by default on a particular {@link Scheduler}.</dd>
3138 * <dt><b>Error handling:</b></dt>
3139 * <dd>If any of the returned {@code ObservableSource}s signal a {@link Throwable} via {@code onError}, the resulting
3140 * {@code Observable} terminates with that {@code Throwable} and all other source {@code ObservableSource}s are disposed.
3141 * If more than one {@code ObservableSource} signals an error, the resulting {@code Observable} may terminate with the
3142 * first one's error or, depending on the concurrency of the sources, may terminate with a
3143 * {@link CompositeException} containing two or more of the various error signals.
3144 * {@code Throwable}s that didn't make into the composite will be sent (individually) to the global error handler via
3145 * {@link RxJavaPlugins#onError(Throwable)} method as {@link UndeliverableException} errors. Similarly, {@code Throwable}s
3146 * signaled by source(s) after the returned {@code Observable} has been disposed or terminated with a
3147 * (composite) error will be sent to the same global error handler.
3148 * Use {@link #mergeDelayError(Iterable)} to merge sources and terminate only when all source {@code ObservableSource}s
3149 * have completed or failed with an error.
3150 * </dd>
3151 * </dl>
3152 *
3153 * @param <T> the common element base type
3154 * @param sources
3155 * the {@code Iterable} of {@code ObservableSource}s
3156 * @return the new {@code Observable} instance
3157 * @throws NullPointerException if {@code sources} is {@code null}
3158 * @see <a href="http://reactivex.io/documentation/operators/merge.html">ReactiveX operators documentation: Merge</a>
3159 * @see #mergeDelayError(Iterable)
3160 */
3161 @SuppressWarnings({ "unchecked", "rawtypes" })
3162 @CheckReturnValue
3163 @SchedulerSupport(SchedulerSupport.NONE)
3164 @NonNull
3165 public static <@NonNull T> Observable<T> merge(@NonNull Iterable<@NonNull ? extends ObservableSource<? extends T>> sources) {
3166 return fromIterable(sources).flatMap((Function)Functions.identity());
3167 }
3168
3169 /**
3170 * Flattens an {@link Iterable} of {@link ObservableSource}s into one {@code Observable}, without any transformation, while limiting the
3171 * number of concurrent subscriptions to these {@code ObservableSource}s.
3172 * <p>
3173 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/merge.v3.png" alt="">
3174 * <p>
3175 * You can combine the items emitted by multiple {@code ObservableSource}s so that they appear as a single {@code ObservableSource}, by
3176 * using the {@code merge} method.
3177 * <dl>
3178 * <dt><b>Scheduler:</b></dt>
3179 * <dd>{@code merge} does not operate by default on a particular {@link Scheduler}.</dd>
3180 * <dt><b>Error handling:</b></dt>
3181 * <dd>If any of the returned {@code ObservableSource}s signal a {@link Throwable} via {@code onError}, the resulting
3182 * {@code Observable} terminates with that {@code Throwable} and all other source {@code ObservableSource}s are disposed.
3183 * If more than one {@code ObservableSource} signals an error, the resulting {@code Observable} may terminate with the
3184 * first one's error or, depending on the concurrency of the sources, may terminate with a
3185 * {@link CompositeException} containing two or more of the various error signals.
3186 * {@code Throwable}s that didn't make into the composite will be sent (individually) to the global error handler via
3187 * {@link RxJavaPlugins#onError(Throwable)} method as {@link UndeliverableException} errors. Similarly, {@code Throwable}s
3188 * signaled by source(s) after the returned {@code Observable} has been disposed or terminated with a
3189 * (composite) error will be sent to the same global error handler.
3190 * Use {@link #mergeDelayError(Iterable, int)} to merge sources and terminate only when all source {@code ObservableSource}s
3191 * have completed or failed with an error.
3192 * </dd>
3193 * </dl>
3194 *
3195 * @param <T> the common element base type
3196 * @param sources
3197 * the {@code Iterable} of {@code ObservableSource}s
3198 * @param maxConcurrency
3199 * the maximum number of {@code ObservableSource}s that may be subscribed to concurrently
3200 * @return the new {@code Observable} instance
3201 * @throws NullPointerException if {@code sources} is {@code null}
3202 * @throws IllegalArgumentException
3203 * if {@code maxConcurrency} is less than or equal to 0
3204 * @see <a href="http://reactivex.io/documentation/operators/merge.html">ReactiveX operators documentation: Merge</a>
3205 * @see #mergeDelayError(Iterable, int)
3206 */
3207 @SuppressWarnings({ "unchecked", "rawtypes" })
3208 @CheckReturnValue
3209 @SchedulerSupport(SchedulerSupport.NONE)
3210 @NonNull
3211 public static <@NonNull T> Observable<T> merge(@NonNull Iterable<@NonNull ? extends ObservableSource<? extends T>> sources, int maxConcurrency) {
3212 return fromIterable(sources).flatMap((Function)Functions.identity(), maxConcurrency);
3213 }
3214
3215 /**
3216 * Flattens an {@link ObservableSource} that emits {@code ObservableSource}s into a single {@code Observable} that emits the items emitted by
3217 * those {@code ObservableSource}s, without any transformation.
3218 * <p>
3219 * <img width="640" height="370" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/merge.oo.v3.png" alt="">
3220 * <p>
3221 * You can combine the items emitted by multiple {@code ObservableSource}s so that they appear as a single {@code ObservableSource}, by
3222 * using the {@code merge} method.
3223 * <dl>
3224 * <dt><b>Scheduler:</b></dt>
3225 * <dd>{@code merge} does not operate by default on a particular {@link Scheduler}.</dd>
3226 * <dt><b>Error handling:</b></dt>
3227 * <dd>If any of the returned {@code ObservableSource}s signal a {@link Throwable} via {@code onError}, the resulting
3228 * {@code Observable} terminates with that {@code Throwable} and all other source {@code ObservableSource}s are disposed.
3229 * If more than one {@code ObservableSource} signals an error, the resulting {@code Observable} may terminate with the
3230 * first one's error or, depending on the concurrency of the sources, may terminate with a
3231 * {@link CompositeException} containing two or more of the various error signals.
3232 * {@code Throwable}s that didn't make into the composite will be sent (individually) to the global error handler via
3233 * {@link RxJavaPlugins#onError(Throwable)} method as {@link UndeliverableException} errors. Similarly, {@code Throwable}s
3234 * signaled by source(s) after the returned {@code Observable} has been disposed or terminated with a
3235 * (composite) error will be sent to the same global error handler.
3236 * Use {@link #mergeDelayError(ObservableSource)} to merge sources and terminate only when all source {@code ObservableSource}s
3237 * have completed or failed with an error.
3238 * </dd>
3239 * </dl>
3240 *
3241 * @param <T> the common element base type
3242 * @param sources
3243 * an {@code ObservableSource} that emits {@code ObservableSource}s
3244 * @return the new {@code Observable} instance
3245 * @see <a href="http://reactivex.io/documentation/operators/merge.html">ReactiveX operators documentation: Merge</a>
3246 * @throws NullPointerException if {@code sources} is {@code null}
3247 * @see #mergeDelayError(ObservableSource)
3248 */
3249 @CheckReturnValue
3250 @SchedulerSupport(SchedulerSupport.NONE)
3251 @SuppressWarnings({ "unchecked", "rawtypes" })
3252 @NonNull
3253 public static <@NonNull T> Observable<T> merge(@NonNull ObservableSource<? extends ObservableSource<? extends T>> sources) {
3254 Objects.requireNonNull(sources, "sources is null");
3255 return RxJavaPlugins.onAssembly(new ObservableFlatMap(sources, Functions.identity(), false, Integer.MAX_VALUE, bufferSize()));
3256 }
3257
3258 /**
3259 * Flattens an {@link ObservableSource} that emits {@code ObservableSource}s into a single {@code Observable} that emits the items emitted by
3260 * those {@code ObservableSource}s, without any transformation, while limiting the maximum number of concurrent
3261 * subscriptions to these {@code ObservableSource}s.
3262 * <p>
3263 * <img width="640" height="370" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/merge.oo.v3.png" alt="">
3264 * <p>
3265 * You can combine the items emitted by multiple {@code ObservableSource}s so that they appear as a single {@code ObservableSource}, by
3266 * using the {@code merge} method.
3267 * <dl>
3268 * <dt><b>Scheduler:</b></dt>
3269 * <dd>{@code merge} does not operate by default on a particular {@link Scheduler}.</dd>
3270 * <dt><b>Error handling:</b></dt>
3271 * <dd>If any of the returned {@code ObservableSource}s signal a {@link Throwable} via {@code onError}, the resulting
3272 * {@code Observable} terminates with that {@code Throwable} and all other source {@code ObservableSource}s are disposed.
3273 * If more than one {@code ObservableSource} signals an error, the resulting {@code Observable} may terminate with the
3274 * first one's error or, depending on the concurrency of the sources, may terminate with a
3275 * {@link CompositeException} containing two or more of the various error signals.
3276 * {@code Throwable}s that didn't make into the composite will be sent (individually) to the global error handler via
3277 * {@link RxJavaPlugins#onError(Throwable)} method as {@link UndeliverableException} errors. Similarly, {@code Throwable}s
3278 * signaled by source(s) after the returned {@code Observable} has been disposed or terminated with a
3279 * (composite) error will be sent to the same global error handler.
3280 * Use {@link #mergeDelayError(ObservableSource, int)} to merge sources and terminate only when all source {@code ObservableSource}s
3281 * have completed or failed with an error.
3282 * </dd>
3283 * </dl>
3284 *
3285 * @param <T> the common element base type
3286 * @param sources
3287 * an {@code ObservableSource} that emits {@code ObservableSource}s
3288 * @param maxConcurrency
3289 * the maximum number of {@code ObservableSource}s that may be subscribed to concurrently
3290 * @return the new {@code Observable} instance
3291 * @throws NullPointerException if {@code sources} is {@code null}
3292 * @throws IllegalArgumentException
3293 * if {@code maxConcurrency} is non-positive
3294 * @see <a href="http://reactivex.io/documentation/operators/merge.html">ReactiveX operators documentation: Merge</a>
3295 * @since 1.1.0
3296 * @see #mergeDelayError(ObservableSource, int)
3297 */
3298 @SuppressWarnings({ "unchecked", "rawtypes" })
3299 @CheckReturnValue
3300 @SchedulerSupport(SchedulerSupport.NONE)
3301 @NonNull
3302 public static <@NonNull T> Observable<T> merge(@NonNull ObservableSource<? extends ObservableSource<? extends T>> sources, int maxConcurrency) {
3303 Objects.requireNonNull(sources, "sources is null");
3304 ObjectHelper.verifyPositive(maxConcurrency, "maxConcurrency");
3305 return RxJavaPlugins.onAssembly(new ObservableFlatMap(sources, Functions.identity(), false, maxConcurrency, bufferSize()));
3306 }
3307
3308 /**
3309 * Flattens two {@link ObservableSource}s into a single {@code Observable}, without any transformation.
3310 * <p>
3311 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/merge.v3.png" alt="">
3312 * <p>
3313 * You can combine items emitted by multiple {@code ObservableSource}s so that they appear as a single {@code ObservableSource}, by
3314 * using the {@code merge} method.
3315 * <dl>
3316 * <dt><b>Scheduler:</b></dt>
3317 * <dd>{@code merge} does not operate by default on a particular {@link Scheduler}.</dd>
3318 * <dt><b>Error handling:</b></dt>
3319 * <dd>If any of the {@code ObservableSource}s signal a {@link Throwable} via {@code onError}, the resulting
3320 * {@code Observable} terminates with that {@code Throwable} and all other source {@code ObservableSource}s are disposed.
3321 * If more than one {@code ObservableSource} signals an error, the resulting {@code Observable} may terminate with the
3322 * first one's error or, depending on the concurrency of the sources, may terminate with a
3323 * {@link CompositeException} containing two or more of the various error signals.
3324 * {@code Throwable}s that didn't make into the composite will be sent (individually) to the global error handler via
3325 * {@link RxJavaPlugins#onError(Throwable)} method as {@link UndeliverableException} errors. Similarly, {@code Throwable}s
3326 * signaled by source(s) after the returned {@code Observable} has been disposed or terminated with a
3327 * (composite) error will be sent to the same global error handler.
3328 * Use {@link #mergeDelayError(ObservableSource, ObservableSource)} to merge sources and terminate only when all source {@code ObservableSource}s
3329 * have completed or failed with an error.
3330 * </dd>
3331 * </dl>
3332 *
3333 * @param <T> the common element base type
3334 * @param source1
3335 * an {@code ObservableSource} to be merged
3336 * @param source2
3337 * an {@code ObservableSource} to be merged
3338 * @return the new {@code Observable} instance
3339 * @throws NullPointerException if {@code source1} or {@code source2} is {@code null}
3340 * @see <a href="http://reactivex.io/documentation/operators/merge.html">ReactiveX operators documentation: Merge</a>
3341 * @see #mergeDelayError(ObservableSource, ObservableSource)
3342 */
3343 @SuppressWarnings({ "unchecked", "rawtypes" })
3344 @CheckReturnValue
3345 @SchedulerSupport(SchedulerSupport.NONE)
3346 @NonNull
3347 public static <@NonNull T> Observable<T> merge(@NonNull ObservableSource<? extends T> source1, @NonNull ObservableSource<? extends T> source2) {
3348 Objects.requireNonNull(source1, "source1 is null");
3349 Objects.requireNonNull(source2, "source2 is null");
3350 return fromArray(source1, source2).flatMap((Function)Functions.identity(), false, 2);
3351 }
3352
3353 /**
3354 * Flattens three {@link ObservableSource}s into a single {@code Observable}, without any transformation.
3355 * <p>
3356 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/merge.v3.png" alt="">
3357 * <p>
3358 * You can combine items emitted by multiple {@code ObservableSource}s so that they appear as a single {@code ObservableSource}, by
3359 * using the {@code merge} method.
3360 * <dl>
3361 * <dt><b>Scheduler:</b></dt>
3362 * <dd>{@code merge} does not operate by default on a particular {@link Scheduler}.</dd>
3363 * <dt><b>Error handling:</b></dt>
3364 * <dd>If any of the {@code ObservableSource}s signal a {@link Throwable} via {@code onError}, the resulting
3365 * {@code Observable} terminates with that {@code Throwable} and all other source {@code ObservableSource}s are disposed.
3366 * If more than one {@code ObservableSource} signals an error, the resulting {@code Observable} may terminate with the
3367 * first one's error or, depending on the concurrency of the sources, may terminate with a
3368 * {@link CompositeException} containing two or more of the various error signals.
3369 * {@code Throwable}s that didn't make into the composite will be sent (individually) to the global error handler via
3370 * {@link RxJavaPlugins#onError(Throwable)} method as {@link UndeliverableException} errors. Similarly, {@code Throwable}s
3371 * signaled by source(s) after the returned {@code Observable} has been disposed or terminated with a
3372 * (composite) error will be sent to the same global error handler.
3373 * Use {@link #mergeDelayError(ObservableSource, ObservableSource, ObservableSource)} to merge sources and terminate only when all source {@code ObservableSource}s
3374 * have completed or failed with an error.
3375 * </dd>
3376 * </dl>
3377 *
3378 * @param <T> the common element base type
3379 * @param source1
3380 * an {@code ObservableSource} to be merged
3381 * @param source2
3382 * an {@code ObservableSource} to be merged
3383 * @param source3
3384 * an {@code ObservableSource} to be merged
3385 * @return the new {@code Observable} instance
3386 * @throws NullPointerException if {@code source1}, {@code source2} or {@code source3} is {@code null}
3387 * @see <a href="http://reactivex.io/documentation/operators/merge.html">ReactiveX operators documentation: Merge</a>
3388 * @see #mergeDelayError(ObservableSource, ObservableSource, ObservableSource)
3389 */
3390 @SuppressWarnings({ "unchecked", "rawtypes" })
3391 @CheckReturnValue
3392 @SchedulerSupport(SchedulerSupport.NONE)
3393 @NonNull
3394 public static <@NonNull T> Observable<T> merge(
3395 @NonNull ObservableSource<? extends T> source1, @NonNull ObservableSource<? extends T> source2,
3396 @NonNull ObservableSource<? extends T> source3) {
3397 Objects.requireNonNull(source1, "source1 is null");
3398 Objects.requireNonNull(source2, "source2 is null");
3399 Objects.requireNonNull(source3, "source3 is null");
3400 return fromArray(source1, source2, source3).flatMap((Function)Functions.identity(), false, 3);
3401 }
3402
3403 /**
3404 * Flattens four {@link ObservableSource}s into a single {@code Observable}, without any transformation.
3405 * <p>
3406 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/merge.v3.png" alt="">
3407 * <p>
3408 * You can combine items emitted by multiple {@code ObservableSource}s so that they appear as a single {@code ObservableSource}, by
3409 * using the {@code merge} method.
3410 * <dl>
3411 * <dt><b>Scheduler:</b></dt>
3412 * <dd>{@code merge} does not operate by default on a particular {@link Scheduler}.</dd>
3413 * <dt><b>Error handling:</b></dt>
3414 * <dd>If any of the {@code ObservableSource}s signal a {@link Throwable} via {@code onError}, the resulting
3415 * {@code Observable} terminates with that {@code Throwable} and all other source {@code ObservableSource}s are disposed.
3416 * If more than one {@code ObservableSource} signals an error, the resulting {@code Observable} may terminate with the
3417 * first one's error or, depending on the concurrency of the sources, may terminate with a
3418 * {@link CompositeException} containing two or more of the various error signals.
3419 * {@code Throwable}s that didn't make into the composite will be sent (individually) to the global error handler via
3420 * {@link RxJavaPlugins#onError(Throwable)} method as {@link UndeliverableException} errors. Similarly, {@code Throwable}s
3421 * signaled by source(s) after the returned {@code Observable} has been disposed or terminated with a
3422 * (composite) error will be sent to the same global error handler.
3423 * Use {@link #mergeDelayError(ObservableSource, ObservableSource, ObservableSource, ObservableSource)} to merge sources and terminate only when all source {@code ObservableSource}s
3424 * have completed or failed with an error.
3425 * </dd>
3426 * </dl>
3427 *
3428 * @param <T> the common element base type
3429 * @param source1
3430 * an {@code ObservableSource} to be merged
3431 * @param source2
3432 * an {@code ObservableSource} to be merged
3433 * @param source3
3434 * an {@code ObservableSource} to be merged
3435 * @param source4
3436 * an {@code ObservableSource} to be merged
3437 * @return the new {@code Observable} instance
3438 * @throws NullPointerException if {@code source1}, {@code source2}, {@code source3} or {@code source4} is {@code null}
3439 * @see <a href="http://reactivex.io/documentation/operators/merge.html">ReactiveX operators documentation: Merge</a>
3440 * @see #mergeDelayError(ObservableSource, ObservableSource, ObservableSource, ObservableSource)
3441 */
3442 @SuppressWarnings({ "unchecked", "rawtypes" })
3443 @CheckReturnValue
3444 @SchedulerSupport(SchedulerSupport.NONE)
3445 @NonNull
3446 public static <@NonNull T> Observable<T> merge(
3447 @NonNull ObservableSource<? extends T> source1, @NonNull ObservableSource<? extends T> source2,
3448 @NonNull ObservableSource<? extends T> source3, @NonNull ObservableSource<? extends T> source4) {
3449 Objects.requireNonNull(source1, "source1 is null");
3450 Objects.requireNonNull(source2, "source2 is null");
3451 Objects.requireNonNull(source3, "source3 is null");
3452 Objects.requireNonNull(source4, "source4 is null");
3453 return fromArray(source1, source2, source3, source4).flatMap((Function)Functions.identity(), false, 4);
3454 }
3455
3456 /**
3457 * Flattens an array of {@link ObservableSource}s into one {@code Observable}, without any transformation.
3458 * <p>
3459 * <img width="640" height="370" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/merge.io.v3.png" alt="">
3460 * <p>
3461 * You can combine items emitted by multiple {@code ObservableSource}s so that they appear as a single {@code ObservableSource}, by
3462 * using the {@code merge} method.
3463 * <dl>
3464 * <dt><b>Scheduler:</b></dt>
3465 * <dd>{@code mergeArray} does not operate by default on a particular {@link Scheduler}.</dd>
3466 * <dt><b>Error handling:</b></dt>
3467 * <dd>If any of the {@code ObservableSource}s signal a {@link Throwable} via {@code onError}, the resulting
3468 * {@code Observable} terminates with that {@code Throwable} and all other source {@code ObservableSource}s are disposed.
3469 * If more than one {@code ObservableSource} signals an error, the resulting {@code Observable} may terminate with the
3470 * first one's error or, depending on the concurrency of the sources, may terminate with a
3471 * {@link CompositeException} containing two or more of the various error signals.
3472 * {@code Throwable}s that didn't make into the composite will be sent (individually) to the global error handler via
3473 * {@link RxJavaPlugins#onError(Throwable)} method as {@link UndeliverableException} errors. Similarly, {@code Throwable}s
3474 * signaled by source(s) after the returned {@code Observable} has been disposed or terminated with a
3475 * (composite) error will be sent to the same global error handler.
3476 * Use {@link #mergeArrayDelayError(ObservableSource...)} to merge sources and terminate only when all source {@code ObservableSource}s
3477 * have completed or failed with an error.
3478 * </dd>
3479 * </dl>
3480 *
3481 * @param <T> the common element base type
3482 * @param sources
3483 * the array of {@code ObservableSource}s
3484 * @return the new {@code Observable} instance
3485 * @throws NullPointerException if {@code sources} is {@code null}
3486 * @see <a href="http://reactivex.io/documentation/operators/merge.html">ReactiveX operators documentation: Merge</a>
3487 * @see #mergeArrayDelayError(ObservableSource...)
3488 */
3489 @SuppressWarnings({ "unchecked", "rawtypes" })
3490 @CheckReturnValue
3491 @SchedulerSupport(SchedulerSupport.NONE)
3492 @NonNull
3493 @SafeVarargs
3494 public static <@NonNull T> Observable<T> mergeArray(@NonNull ObservableSource<? extends T>... sources) {
3495 return fromArray(sources).flatMap((Function)Functions.identity(), sources.length);
3496 }
3497
3498 /**
3499 * Flattens an {@link Iterable} of {@link ObservableSource}s into one {@code Observable}, in a way that allows an {@link Observer} to receive all
3500 * successfully emitted items from each of the returned {@code ObservableSource}s without being interrupted by an error
3501 * notification from one of them.
3502 * <p>
3503 * This behaves like {@link #merge(ObservableSource)} except that if any of the merged {@code ObservableSource}s notify of an
3504 * error via {@link Observer#onError onError}, {@code mergeDelayError} will refrain from propagating that
3505 * error notification until all of the merged {@code ObservableSource}s have finished emitting items.
3506 * <p>
3507 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/mergeDelayError.v3.png" alt="">
3508 * <p>
3509 * Even if multiple merged {@code ObservableSource}s send {@code onError} notifications, {@code mergeDelayError} will only
3510 * invoke the {@code onError} method of its {@code Observer}s once.
3511 * <dl>
3512 * <dt><b>Scheduler:</b></dt>
3513 * <dd>{@code mergeDelayError} does not operate by default on a particular {@link Scheduler}.</dd>
3514 * </dl>
3515 *
3516 * @param <T> the common element base type
3517 * @param sources
3518 * the {@code Iterable} of {@code ObservableSource}s
3519 * @return the new {@code Observable} instance
3520 * @throws NullPointerException if {@code sources} is {@code null}
3521 * @see <a href="http://reactivex.io/documentation/operators/merge.html">ReactiveX operators documentation: Merge</a>
3522 */
3523 @SuppressWarnings({ "unchecked", "rawtypes" })
3524 @CheckReturnValue
3525 @SchedulerSupport(SchedulerSupport.NONE)
3526 @NonNull
3527 public static <@NonNull T> Observable<T> mergeDelayError(@NonNull Iterable<@NonNull ? extends ObservableSource<? extends T>> sources) {
3528 return fromIterable(sources).flatMap((Function)Functions.identity(), true);
3529 }
3530
3531 /**
3532 * Flattens an {@link Iterable} of {@link ObservableSource}s into one {@code Observable}, in a way that allows an {@link Observer} to receive all
3533 * successfully emitted items from each of the returned {@code ObservableSource}s without being interrupted by an error
3534 * notification from one of them, while limiting the number of concurrent subscriptions to these {@code ObservableSource}s.
3535 * <p>
3536 * This behaves like {@link #merge(ObservableSource)} except that if any of the merged {@code ObservableSource}s notify of an
3537 * error via {@link Observer#onError onError}, {@code mergeDelayError} will refrain from propagating that
3538 * error notification until all of the merged {@code ObservableSource}s have finished emitting items.
3539 * <p>
3540 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/mergeDelayError.v3.png" alt="">
3541 * <p>
3542 * Even if multiple merged {@code ObservableSource}s send {@code onError} notifications, {@code mergeDelayError} will only
3543 * invoke the {@code onError} method of its {@code Observer}s once.
3544 * <dl>
3545 * <dt><b>Scheduler:</b></dt>
3546 * <dd>{@code mergeDelayError} does not operate by default on a particular {@link Scheduler}.</dd>
3547 * </dl>
3548 *
3549 * @param <T> the common element base type
3550 * @param sources
3551 * the {@code Iterable} of {@code ObservableSource}s
3552 * @param maxConcurrency
3553 * the maximum number of {@code ObservableSource}s that may be subscribed to concurrently
3554 * @param bufferSize
3555 * the number of items expected from each inner {@code ObservableSource} to be buffered
3556 * @return the new {@code Observable} instance
3557 * @throws NullPointerException if {@code sources} is {@code null}
3558 * @throws IllegalArgumentException if {@code maxConcurrency} or {@code bufferSize} is non-positive
3559 * @see <a href="http://reactivex.io/documentation/operators/merge.html">ReactiveX operators documentation: Merge</a>
3560 */
3561 @SuppressWarnings({ "unchecked", "rawtypes" })
3562 @CheckReturnValue
3563 @SchedulerSupport(SchedulerSupport.NONE)
3564 @NonNull
3565 public static <@NonNull T> Observable<T> mergeDelayError(@NonNull Iterable<@NonNull ? extends ObservableSource<? extends T>> sources, int maxConcurrency, int bufferSize) {
3566 return fromIterable(sources).flatMap((Function)Functions.identity(), true, maxConcurrency, bufferSize);
3567 }
3568
3569 /**
3570 * Flattens an array of {@link ObservableSource}s into one {@code Observable}, in a way that allows an {@link Observer} to receive all
3571 * successfully emitted items from each of the {@code ObservableSource}s without being interrupted by an error
3572 * notification from one of them, while limiting the number of concurrent subscriptions to these {@code ObservableSource}s.
3573 * <p>
3574 * This behaves like {@link #merge(ObservableSource)} except that if any of the merged {@code ObservableSource}s notify of an
3575 * error via {@link Observer#onError onError}, {@code mergeDelayError} will refrain from propagating that
3576 * error notification until all of the merged {@code ObservableSource}s have finished emitting items.
3577 * <p>
3578 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/mergeDelayError.v3.png" alt="">
3579 * <p>
3580 * Even if multiple merged {@code ObservableSource}s send {@code onError} notifications, {@code mergeDelayError} will only
3581 * invoke the {@code onError} method of its {@code Observer}s once.
3582 * <dl>
3583 * <dt><b>Scheduler:</b></dt>
3584 * <dd>{@code mergeArrayDelayError} does not operate by default on a particular {@link Scheduler}.</dd>
3585 * </dl>
3586 *
3587 * @param <T> the common element base type
3588 * @param sources
3589 * the array of {@code ObservableSource}s
3590 * @param maxConcurrency
3591 * the maximum number of {@code ObservableSource}s that may be subscribed to concurrently
3592 * @param bufferSize
3593 * the number of items expected from each inner {@code ObservableSource} to be buffered
3594 * @return the new {@code Observable} instance
3595 * @throws NullPointerException if {@code sources} is {@code null}
3596 * @throws IllegalArgumentException if {@code maxConcurrency} or {@code bufferSize} is non-positive
3597 * @see <a href="http://reactivex.io/documentation/operators/merge.html">ReactiveX operators documentation: Merge</a>
3598 */
3599 @SuppressWarnings({ "unchecked", "rawtypes" })
3600 @CheckReturnValue
3601 @SchedulerSupport(SchedulerSupport.NONE)
3602 @NonNull
3603 @SafeVarargs
3604 public static <@NonNull T> Observable<T> mergeArrayDelayError(int maxConcurrency, int bufferSize, @NonNull ObservableSource<? extends T>... sources) {
3605 return fromArray(sources).flatMap((Function)Functions.identity(), true, maxConcurrency, bufferSize);
3606 }
3607
3608 /**
3609 * Flattens an {@link Iterable} of {@link ObservableSource}s into one {@code Observable}, in a way that allows an {@link Observer} to receive all
3610 * successfully emitted items from each of the returned {@code ObservableSource}s without being interrupted by an error
3611 * notification from one of them, while limiting the number of concurrent subscriptions to these {@code ObservableSource}s.
3612 * <p>
3613 * This behaves like {@link #merge(ObservableSource)} except that if any of the merged {@code ObservableSource}s notify of an
3614 * error via {@link Observer#onError onError}, {@code mergeDelayError} will refrain from propagating that
3615 * error notification until all of the merged {@code ObservableSource}s have finished emitting items.
3616 * <p>
3617 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/mergeDelayError.v3.png" alt="">
3618 * <p>
3619 * Even if multiple merged {@code ObservableSource}s send {@code onError} notifications, {@code mergeDelayError} will only
3620 * invoke the {@code onError} method of its {@code Observer}s once.
3621 * <dl>
3622 * <dt><b>Scheduler:</b></dt>
3623 * <dd>{@code mergeDelayError} does not operate by default on a particular {@link Scheduler}.</dd>
3624 * </dl>
3625 *
3626 * @param <T> the common element base type
3627 * @param sources
3628 * the {@code Iterable} of {@code ObservableSource}s
3629 * @param maxConcurrency
3630 * the maximum number of {@code ObservableSource}s that may be subscribed to concurrently
3631 * @return the new {@code Observable} instance
3632 * @throws NullPointerException if {@code sources} is {@code null}
3633 * @throws IllegalArgumentException if {@code maxConcurrency} is non-positive
3634 * @see <a href="http://reactivex.io/documentation/operators/merge.html">ReactiveX operators documentation: Merge</a>
3635 */
3636 @SuppressWarnings({ "unchecked", "rawtypes" })
3637 @CheckReturnValue
3638 @SchedulerSupport(SchedulerSupport.NONE)
3639 @NonNull
3640 public static <@NonNull T> Observable<T> mergeDelayError(@NonNull Iterable<@NonNull ? extends ObservableSource<? extends T>> sources, int maxConcurrency) {
3641 return fromIterable(sources).flatMap((Function)Functions.identity(), true, maxConcurrency);
3642 }
3643
3644 /**
3645 * Flattens an {@link ObservableSource} that emits {@code ObservableSource}s into one {@code Observable}, in a way that allows an {@link Observer} to
3646 * receive all successfully emitted items from all of the emitted {@code ObservableSource}s without being interrupted by
3647 * an error notification from one of them.
3648 * <p>
3649 * This behaves like {@link #merge(ObservableSource)} except that if any of the merged {@code ObservableSource}s notify of an
3650 * error via {@link Observer#onError onError}, {@code mergeDelayError} will refrain from propagating that
3651 * error notification until all of the merged {@code ObservableSource}s have finished emitting items.
3652 * <p>
3653 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/mergeDelayError.v3.png" alt="">
3654 * <p>
3655 * Even if multiple merged {@code ObservableSource}s send {@code onError} notifications, {@code mergeDelayError} will only
3656 * invoke the {@code onError} method of its {@code Observer}s once.
3657 * <dl>
3658 * <dt><b>Scheduler:</b></dt>
3659 * <dd>{@code mergeDelayError} does not operate by default on a particular {@link Scheduler}.</dd>
3660 * </dl>
3661 *
3662 * @param <T> the common element base type
3663 * @param sources
3664 * an {@code ObservableSource} that emits {@code ObservableSource}s
3665 * @return the new {@code Observable} instance
3666 * @throws NullPointerException if {@code sources} is {@code null}
3667 * @see <a href="http://reactivex.io/documentation/operators/merge.html">ReactiveX operators documentation: Merge</a>
3668 */
3669 @CheckReturnValue
3670 @SchedulerSupport(SchedulerSupport.NONE)
3671 @SuppressWarnings({ "unchecked", "rawtypes" })
3672 @NonNull
3673 public static <@NonNull T> Observable<T> mergeDelayError(@NonNull ObservableSource<? extends ObservableSource<? extends T>> sources) {
3674 Objects.requireNonNull(sources, "sources is null");
3675 return RxJavaPlugins.onAssembly(new ObservableFlatMap(sources, Functions.identity(), true, Integer.MAX_VALUE, bufferSize()));
3676 }
3677
3678 /**
3679 * Flattens an {@link ObservableSource} that emits {@code ObservableSource}s into one {@code Observable}, in a way that allows an {@link Observer} to
3680 * receive all successfully emitted items from all of the emitted {@code ObservableSource}s without being interrupted by
3681 * an error notification from one of them, while limiting the
3682 * number of concurrent subscriptions to these {@code ObservableSource}s.
3683 * <p>
3684 * This behaves like {@link #merge(ObservableSource)} except that if any of the merged {@code ObservableSource}s notify of an
3685 * error via {@link Observer#onError onError}, {@code mergeDelayError} will refrain from propagating that
3686 * error notification until all of the merged {@code ObservableSource}s have finished emitting items.
3687 * <p>
3688 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/mergeDelayError.v3.png" alt="">
3689 * <p>
3690 * Even if multiple merged {@code ObservableSource}s send {@code onError} notifications, {@code mergeDelayError} will only
3691 * invoke the {@code onError} method of its {@code Observer}s once.
3692 * <dl>
3693 * <dt><b>Scheduler:</b></dt>
3694 * <dd>{@code mergeDelayError} does not operate by default on a particular {@link Scheduler}.</dd>
3695 * </dl>
3696 *
3697 * @param <T> the common element base type
3698 * @param sources
3699 * an {@code ObservableSource} that emits {@code ObservableSource}s
3700 * @param maxConcurrency
3701 * the maximum number of {@code ObservableSource}s that may be subscribed to concurrently
3702 * @return the new {@code Observable} instance
3703 * @throws NullPointerException if {@code sources} is {@code null}
3704 * @throws IllegalArgumentException if {@code maxConcurrency} is non-positive
3705 * @see <a href="http://reactivex.io/documentation/operators/merge.html">ReactiveX operators documentation: Merge</a>
3706 * @since 2.0
3707 */
3708 @SuppressWarnings({ "unchecked", "rawtypes" })
3709 @CheckReturnValue
3710 @SchedulerSupport(SchedulerSupport.NONE)
3711 @NonNull
3712 public static <@NonNull T> Observable<T> mergeDelayError(@NonNull ObservableSource<? extends ObservableSource<? extends T>> sources, int maxConcurrency) {
3713 Objects.requireNonNull(sources, "sources is null");
3714 ObjectHelper.verifyPositive(maxConcurrency, "maxConcurrency");
3715 return RxJavaPlugins.onAssembly(new ObservableFlatMap(sources, Functions.identity(), true, maxConcurrency, bufferSize()));
3716 }
3717
3718 /**
3719 * Flattens two {@link ObservableSource}s into one {@code Observable}, in a way that allows an {@link Observer} to receive all
3720 * successfully emitted items from each of the {@code ObservableSource}s without being interrupted by an error
3721 * notification from one of them.
3722 * <p>
3723 * This behaves like {@link #merge(ObservableSource, ObservableSource)} except that if any of the merged {@code ObservableSource}s
3724 * notify of an error via {@link Observer#onError onError}, {@code mergeDelayError} will refrain from
3725 * propagating that error notification until all of the merged {@code ObservableSource}s have finished emitting items.
3726 * <p>
3727 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/mergeDelayError.v3.png" alt="">
3728 * <p>
3729 * Even if both merged {@code ObservableSource}s send {@code onError} notifications, {@code mergeDelayError} will only
3730 * invoke the {@code onError} method of its {@code Observer}s once.
3731 * <dl>
3732 * <dt><b>Scheduler:</b></dt>
3733 * <dd>{@code mergeDelayError} does not operate by default on a particular {@link Scheduler}.</dd>
3734 * </dl>
3735 *
3736 * @param <T> the common element base type
3737 * @param source1
3738 * an {@code ObservableSource} to be merged
3739 * @param source2
3740 * an {@code ObservableSource} to be merged
3741 * @return the new {@code Observable} instance
3742 * @throws NullPointerException if {@code source1} or {@code source2} is {@code null}
3743 * @see <a href="http://reactivex.io/documentation/operators/merge.html">ReactiveX operators documentation: Merge</a>
3744 */
3745 @SuppressWarnings({ "unchecked", "rawtypes" })
3746 @CheckReturnValue
3747 @SchedulerSupport(SchedulerSupport.NONE)
3748 @NonNull
3749 public static <@NonNull T> Observable<T> mergeDelayError(
3750 @NonNull ObservableSource<? extends T> source1, @NonNull ObservableSource<? extends T> source2) {
3751 Objects.requireNonNull(source1, "source1 is null");
3752 Objects.requireNonNull(source2, "source2 is null");
3753 return fromArray(source1, source2).flatMap((Function)Functions.identity(), true, 2);
3754 }
3755
3756 /**
3757 * Flattens three {@link ObservableSource}s into one {@code Observable}, in a way that allows an {@link Observer} to receive all
3758 * successfully emitted items from all of the {@code ObservableSource}s without being interrupted by an error
3759 * notification from one of them.
3760 * <p>
3761 * This behaves like {@link #merge(ObservableSource, ObservableSource, ObservableSource)} except that if any of the merged
3762 * {@code ObservableSource}s notify of an error via {@link Observer#onError onError}, {@code mergeDelayError} will refrain
3763 * from propagating that error notification until all of the merged {@code ObservableSource}s have finished emitting
3764 * items.
3765 * <p>
3766 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/mergeDelayError.v3.png" alt="">
3767 * <p>
3768 * Even if multiple merged {@code ObservableSource}s send {@code onError} notifications, {@code mergeDelayError} will only
3769 * invoke the {@code onError} method of its {@code Observer}s once.
3770 * <dl>
3771 * <dt><b>Scheduler:</b></dt>
3772 * <dd>{@code mergeDelayError} does not operate by default on a particular {@link Scheduler}.</dd>
3773 * </dl>
3774 *
3775 * @param <T> the common element base type
3776 * @param source1
3777 * an {@code ObservableSource} to be merged
3778 * @param source2
3779 * an {@code ObservableSource} to be merged
3780 * @param source3
3781 * an {@code ObservableSource} to be merged
3782 * @return the new {@code Observable} instance
3783 * @throws NullPointerException if {@code source1}, {@code source2} or {@code source3} is {@code null}
3784 * @see <a href="http://reactivex.io/documentation/operators/merge.html">ReactiveX operators documentation: Merge</a>
3785 */
3786 @SuppressWarnings({ "unchecked", "rawtypes" })
3787 @CheckReturnValue
3788 @SchedulerSupport(SchedulerSupport.NONE)
3789 @NonNull
3790 public static <@NonNull T> Observable<T> mergeDelayError(
3791 @NonNull ObservableSource<? extends T> source1, @NonNull ObservableSource<? extends T> source2,
3792 @NonNull ObservableSource<? extends T> source3) {
3793 Objects.requireNonNull(source1, "source1 is null");
3794 Objects.requireNonNull(source2, "source2 is null");
3795 Objects.requireNonNull(source3, "source3 is null");
3796 return fromArray(source1, source2, source3).flatMap((Function)Functions.identity(), true, 3);
3797 }
3798
3799 /**
3800 * Flattens four {@link ObservableSource}s into one {@code Observable}, in a way that allows an {@link Observer} to receive all
3801 * successfully emitted items from all of the {@code ObservableSource}s without being interrupted by an error
3802 * notification from one of them.
3803 * <p>
3804 * This behaves like {@link #merge(ObservableSource, ObservableSource, ObservableSource, ObservableSource)} except that if any of
3805 * the merged {@code ObservableSource}s notify of an error via {@link Observer#onError onError}, {@code mergeDelayError}
3806 * will refrain from propagating that error notification until all of the merged {@code ObservableSource}s have finished
3807 * emitting items.
3808 * <p>
3809 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/mergeDelayError.v3.png" alt="">
3810 * <p>
3811 * Even if multiple merged {@code ObservableSource}s send {@code onError} notifications, {@code mergeDelayError} will only
3812 * invoke the {@code onError} method of its {@code Observer}s once.
3813 * <dl>
3814 * <dt><b>Scheduler:</b></dt>
3815 * <dd>{@code mergeDelayError} does not operate by default on a particular {@link Scheduler}.</dd>
3816 * </dl>
3817 *
3818 * @param <T> the common element base type
3819 * @param source1
3820 * an {@code ObservableSource} to be merged
3821 * @param source2
3822 * an {@code ObservableSource} to be merged
3823 * @param source3
3824 * an {@code ObservableSource} to be merged
3825 * @param source4
3826 * an {@code ObservableSource} to be merged
3827 * @return the new {@code Observable} instance
3828 * @throws NullPointerException if {@code source1}, {@code source2}, {@code source3} or {@code source4} is {@code null}
3829 * @see <a href="http://reactivex.io/documentation/operators/merge.html">ReactiveX operators documentation: Merge</a>
3830 */
3831 @SuppressWarnings({ "unchecked", "rawtypes" })
3832 @CheckReturnValue
3833 @SchedulerSupport(SchedulerSupport.NONE)
3834 @NonNull
3835 public static <@NonNull T> Observable<T> mergeDelayError(
3836 @NonNull ObservableSource<? extends T> source1, @NonNull ObservableSource<? extends T> source2,
3837 @NonNull ObservableSource<? extends T> source3, @NonNull ObservableSource<? extends T> source4) {
3838 Objects.requireNonNull(source1, "source1 is null");
3839 Objects.requireNonNull(source2, "source2 is null");
3840 Objects.requireNonNull(source3, "source3 is null");
3841 Objects.requireNonNull(source4, "source4 is null");
3842 return fromArray(source1, source2, source3, source4).flatMap((Function)Functions.identity(), true, 4);
3843 }
3844
3845 /**
3846 * Flattens an array of {@link ObservableSource}s into one {@code Observable}, in a way that allows an {@link Observer} to receive all
3847 * successfully emitted items from each of the {@code ObservableSource}s without being interrupted by an error
3848 * notification from one of them.
3849 * <p>
3850 * This behaves like {@link #merge(ObservableSource)} except that if any of the merged {@code ObservableSource}s notify of an
3851 * error via {@link Observer#onError onError}, {@code mergeDelayError} will refrain from propagating that
3852 * error notification until all of the merged {@code ObservableSource}s have finished emitting items.
3853 * <p>
3854 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/mergeDelayError.v3.png" alt="">
3855 * <p>
3856 * Even if multiple merged {@code ObservableSource}s send {@code onError} notifications, {@code mergeDelayError} will only
3857 * invoke the {@code onError} method of its {@code Observer}s once.
3858 * <dl>
3859 * <dt><b>Scheduler:</b></dt>
3860 * <dd>{@code mergeArrayDelayError} does not operate by default on a particular {@link Scheduler}.</dd>
3861 * </dl>
3862 *
3863 * @param <T> the common element base type
3864 * @param sources
3865 * the array of {@code ObservableSource}s
3866 * @return the new {@code Observable} instance
3867 * @throws NullPointerException if {@code sources} is {@code null}
3868 * @see <a href="http://reactivex.io/documentation/operators/merge.html">ReactiveX operators documentation: Merge</a>
3869 */
3870 @SuppressWarnings({ "unchecked", "rawtypes" })
3871 @CheckReturnValue
3872 @SchedulerSupport(SchedulerSupport.NONE)
3873 @NonNull
3874 @SafeVarargs
3875 public static <@NonNull T> Observable<T> mergeArrayDelayError(@NonNull ObservableSource<? extends T>... sources) {
3876 return fromArray(sources).flatMap((Function)Functions.identity(), true, sources.length);
3877 }
3878
3879 /**
3880 * Returns an {@code Observable} that never sends any items or notifications to an {@link Observer}.
3881 * <p>
3882 * <img width="640" height="185" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/never.v3.png" alt="">
3883 * <p>
3884 * The returned {@code Observable} is useful primarily for testing purposes.
3885 * <dl>
3886 * <dt><b>Scheduler:</b></dt>
3887 * <dd>{@code never} does not operate by default on a particular {@link Scheduler}.</dd>
3888 * </dl>
3889 *
3890 * @param <T>
3891 * the type of items (not) emitted by the {@code Observable}
3892 * @return the shared {@code Observable} instance
3893 * @see <a href="http://reactivex.io/documentation/operators/empty-never-throw.html">ReactiveX operators documentation: Never</a>
3894 */
3895 @CheckReturnValue
3896 @SchedulerSupport(SchedulerSupport.NONE)
3897 @SuppressWarnings("unchecked")
3898 @NonNull
3899 public static <@NonNull T> Observable<T> never() {
3900 return RxJavaPlugins.onAssembly((Observable<T>) ObservableNever.INSTANCE);
3901 }
3902
3903 /**
3904 * Returns an {@code Observable} that emits a sequence of {@link Integer}s within a specified range.
3905 * <p>
3906 * <img width="640" height="195" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/range.v3.png" alt="">
3907 * <dl>
3908 * <dt><b>Scheduler:</b></dt>
3909 * <dd>{@code range} does not operate by default on a particular {@link Scheduler}.</dd>
3910 * </dl>
3911 *
3912 * @param start
3913 * the value of the first {@code Integer} in the sequence
3914 * @param count
3915 * the number of sequential {@code Integer}s to generate
3916 * @return the new {@code Observable} instance
3917 * @throws IllegalArgumentException
3918 * if {@code count} is negative, or if {@code start} + {@code count} &minus; 1 exceeds
3919 * {@link Integer#MAX_VALUE}
3920 * @see <a href="http://reactivex.io/documentation/operators/range.html">ReactiveX operators documentation: Range</a>
3921 * @see #rangeLong(long, long)
3922 * @see #intervalRange(long, long, long, long, TimeUnit)
3923 */
3924 @CheckReturnValue
3925 @SchedulerSupport(SchedulerSupport.NONE)
3926 @NonNull
3927 public static Observable<Integer> range(int start, int count) {
3928 if (count < 0) {
3929 throw new IllegalArgumentException("count >= 0 required but it was " + count);
3930 }
3931 if (count == 0) {
3932 return empty();
3933 }
3934 if (count == 1) {
3935 return just(start);
3936 }
3937 if ((long)start + (count - 1) > Integer.MAX_VALUE) {
3938 throw new IllegalArgumentException("Integer overflow");
3939 }
3940 return RxJavaPlugins.onAssembly(new ObservableRange(start, count));
3941 }
3942
3943 /**
3944 * Returns an {@code Observable} that emits a sequence of {@link Long}s within a specified range.
3945 * <p>
3946 * <img width="640" height="195" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/rangeLong.png" alt="">
3947 * <dl>
3948 * <dt><b>Scheduler:</b></dt>
3949 * <dd>{@code rangeLong} does not operate by default on a particular {@link Scheduler}.</dd>
3950 * </dl>
3951 *
3952 * @param start
3953 * the value of the first {@code Long} in the sequence
3954 * @param count
3955 * the number of sequential {@code Long}s to generate
3956 * @return the new {@code Observable} instance
3957 * @throws IllegalArgumentException
3958 * if {@code count} is negative, or if {@code start} + {@code count} &minus; 1 exceeds
3959 * {@link Long#MAX_VALUE}
3960 * @see <a href="http://reactivex.io/documentation/operators/range.html">ReactiveX operators documentation: Range</a>
3961 * @see #intervalRange(long, long, long, long, TimeUnit)
3962 */
3963 @CheckReturnValue
3964 @SchedulerSupport(SchedulerSupport.NONE)
3965 @NonNull
3966 public static Observable<Long> rangeLong(long start, long count) {
3967 if (count < 0) {
3968 throw new IllegalArgumentException("count >= 0 required but it was " + count);
3969 }
3970
3971 if (count == 0) {
3972 return empty();
3973 }
3974
3975 if (count == 1) {
3976 return just(start);
3977 }
3978
3979 long end = start + (count - 1);
3980 if (start > 0 && end < 0) {
3981 throw new IllegalArgumentException("Overflow! start + count is bigger than Long.MAX_VALUE");
3982 }
3983
3984 return RxJavaPlugins.onAssembly(new ObservableRangeLong(start, count));
3985 }
3986
3987 /**
3988 * Returns a {@link Single} that emits a {@link Boolean} value that indicates whether two {@link ObservableSource} sequences are the
3989 * same by comparing the items emitted by each {@code ObservableSource} pairwise.
3990 * <p>
3991 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/sequenceEqual.2.v3.png" alt="">
3992 * <dl>
3993 * <dt><b>Scheduler:</b></dt>
3994 * <dd>{@code sequenceEqual} does not operate by default on a particular {@link Scheduler}.</dd>
3995 * </dl>
3996 *
3997 * @param source1
3998 * the first {@code ObservableSource} to compare
3999 * @param source2
4000 * the second {@code ObservableSource} to compare
4001 * @param <T>
4002 * the type of items emitted by each {@code ObservableSource}
4003 * @return the new {@code Single} instance
4004 * @throws NullPointerException if {@code source1} or {@code source2} is {@code null}
4005 * @see <a href="http://reactivex.io/documentation/operators/sequenceequal.html">ReactiveX operators documentation: SequenceEqual</a>
4006 */
4007 @CheckReturnValue
4008 @SchedulerSupport(SchedulerSupport.NONE)
4009 @NonNull
4010 public static <@NonNull T> Single<Boolean> sequenceEqual(@NonNull ObservableSource<? extends T> source1, @NonNull ObservableSource<? extends T> source2) {
4011 return sequenceEqual(source1, source2, ObjectHelper.equalsPredicate(), bufferSize());
4012 }
4013
4014 /**
4015 * Returns a {@link Single} that emits a {@link Boolean} value that indicates whether two {@link ObservableSource} sequences are the
4016 * same by comparing the items emitted by each {@code ObservableSource} pairwise based on the results of a specified
4017 * equality function.
4018 * <p>
4019 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/sequenceEqual.2.v3.png" alt="">
4020 * <dl>
4021 * <dt><b>Scheduler:</b></dt>
4022 * <dd>{@code sequenceEqual} does not operate by default on a particular {@link Scheduler}.</dd>
4023 * </dl>
4024 *
4025 * @param source1
4026 * the first {@code ObservableSource} to compare
4027 * @param source2
4028 * the second {@code ObservableSource} to compare
4029 * @param isEqual
4030 * a function used to compare items emitted by each {@code ObservableSource}
4031 * @param <T>
4032 * the type of items emitted by each {@code ObservableSource}
4033 * @return the new {@code Single} instance
4034 * @throws NullPointerException if {@code source1}, {@code source2} or {@code isEqual} is {@code null}
4035 * @see <a href="http://reactivex.io/documentation/operators/sequenceequal.html">ReactiveX operators documentation: SequenceEqual</a>
4036 */
4037 @CheckReturnValue
4038 @SchedulerSupport(SchedulerSupport.NONE)
4039 @NonNull
4040 public static <@NonNull T> Single<Boolean> sequenceEqual(
4041 @NonNull ObservableSource<? extends T> source1, @NonNull ObservableSource<? extends T> source2,
4042 @NonNull BiPredicate<? super T, ? super T> isEqual) {
4043 return sequenceEqual(source1, source2, isEqual, bufferSize());
4044 }
4045
4046 /**
4047 * Returns a {@link Single} that emits a {@link Boolean} value that indicates whether two {@link ObservableSource} sequences are the
4048 * same by comparing the items emitted by each {@code ObservableSource} pairwise based on the results of a specified
4049 * equality function.
4050 * <p>
4051 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/sequenceEqual.2.v3.png" alt="">
4052 * <dl>
4053 * <dt><b>Scheduler:</b></dt>
4054 * <dd>{@code sequenceEqual} does not operate by default on a particular {@link Scheduler}.</dd>
4055 * </dl>
4056 *
4057 * @param source1
4058 * the first {@code ObservableSource} to compare
4059 * @param source2
4060 * the second {@code ObservableSource} to compare
4061 * @param isEqual
4062 * a function used to compare items emitted by each {@code ObservableSource}
4063 * @param bufferSize
4064 * the number of items expected from the first and second source {@code ObservableSource} to be buffered
4065 * @param <T>
4066 * the type of items emitted by each {@code ObservableSource}
4067 * @return the new {@code Single} instance
4068 * @throws NullPointerException if {@code source1}, {@code source2} or {@code isEqual} is {@code null}
4069 * @throws IllegalArgumentException if {@code bufferSize} is non-positive
4070 * @see <a href="http://reactivex.io/documentation/operators/sequenceequal.html">ReactiveX operators documentation: SequenceEqual</a>
4071 */
4072 @CheckReturnValue
4073 @SchedulerSupport(SchedulerSupport.NONE)
4074 @NonNull
4075 public static <@NonNull T> Single<Boolean> sequenceEqual(
4076 @NonNull ObservableSource<? extends T> source1, @NonNull ObservableSource<? extends T> source2,
4077 @NonNull BiPredicate<? super T, ? super T> isEqual, int bufferSize) {
4078 Objects.requireNonNull(source1, "source1 is null");
4079 Objects.requireNonNull(source2, "source2 is null");
4080 Objects.requireNonNull(isEqual, "isEqual is null");
4081 ObjectHelper.verifyPositive(bufferSize, "bufferSize");
4082 return RxJavaPlugins.onAssembly(new ObservableSequenceEqualSingle<>(source1, source2, isEqual, bufferSize));
4083 }
4084
4085 /**
4086 * Returns a {@link Single} that emits a {@link Boolean} value that indicates whether two {@link ObservableSource} sequences are the
4087 * same by comparing the items emitted by each {@code ObservableSource} pairwise.
4088 * <p>
4089 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/sequenceEqual.2.v3.png" alt="">
4090 * <dl>
4091 * <dt><b>Scheduler:</b></dt>
4092 * <dd>{@code sequenceEqual} does not operate by default on a particular {@link Scheduler}.</dd>
4093 * </dl>
4094 *
4095 * @param source1
4096 * the first {@code ObservableSource} to compare
4097 * @param source2
4098 * the second {@code ObservableSource} to compare
4099 * @param bufferSize
4100 * the number of items expected from the first and second source {@code ObservableSource} to be buffered
4101 * @param <T>
4102 * the type of items emitted by each {@code ObservableSource}
4103 * @return the new {@code Single} instance
4104 * @throws NullPointerException if {@code source1} or {@code source2} is {@code null}
4105 * @throws IllegalArgumentException if {@code bufferSize} is non-positive
4106 * @see <a href="http://reactivex.io/documentation/operators/sequenceequal.html">ReactiveX operators documentation: SequenceEqual</a>
4107 */
4108 @CheckReturnValue
4109 @SchedulerSupport(SchedulerSupport.NONE)
4110 @NonNull
4111 public static <@NonNull T> Single<Boolean> sequenceEqual(@NonNull ObservableSource<? extends T> source1, @NonNull ObservableSource<? extends T> source2,
4112 int bufferSize) {
4113 return sequenceEqual(source1, source2, ObjectHelper.equalsPredicate(), bufferSize);
4114 }
4115
4116 /**
4117 * Converts an {@link ObservableSource} that emits {@code ObservableSource}s into an {@code Observable} that emits the items emitted by the
4118 * most recently emitted of those {@code ObservableSource}s.
4119 * <p>
4120 * <img width="640" height="370" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/switchDo.v3.png" alt="">
4121 * <p>
4122 * {@code switchOnNext} subscribes to an {@code ObservableSource} that emits {@code ObservableSource}s. Each time it observes one of
4123 * these emitted {@code ObservableSource}s, the {@code ObservableSource} returned by {@code switchOnNext} begins emitting the items
4124 * emitted by that {@code ObservableSource}. When a new inner {@code ObservableSource} is emitted, {@code switchOnNext} stops emitting items
4125 * from the earlier-emitted {@code ObservableSource} and begins emitting items from the new one.
4126 * <p>
4127 * The resulting {@code Observable} completes if both the outer {@code ObservableSource} and the last inner {@code ObservableSource}, if any, complete.
4128 * If the outer {@code ObservableSource} signals an {@code onError}, the inner {@code ObservableSource} is disposed and the error delivered in-sequence.
4129 * <dl>
4130 * <dt><b>Scheduler:</b></dt>
4131 * <dd>{@code switchOnNext} does not operate by default on a particular {@link Scheduler}.</dd>
4132 * </dl>
4133 *
4134 * @param <T> the item type
4135 * @param sources
4136 * the {@code ObservableSource} that emits {@code ObservableSource}s
4137 * @param bufferSize
4138 * the expected number of items to cache from the inner {@code ObservableSource}s
4139 * @return the new {@code Observable} instance
4140 * @throws NullPointerException if {@code sources} is {@code null}
4141 * @throws IllegalArgumentException if {@code bufferSize} is non-positive
4142 * @see <a href="http://reactivex.io/documentation/operators/switch.html">ReactiveX operators documentation: Switch</a>
4143 */
4144 @SuppressWarnings({ "rawtypes", "unchecked" })
4145 @CheckReturnValue
4146 @SchedulerSupport(SchedulerSupport.NONE)
4147 @NonNull
4148 public static <@NonNull T> Observable<T> switchOnNext(@NonNull ObservableSource<? extends ObservableSource<? extends T>> sources, int bufferSize) {
4149 Objects.requireNonNull(sources, "sources is null");
4150 ObjectHelper.verifyPositive(bufferSize, "bufferSize");
4151 return RxJavaPlugins.onAssembly(new ObservableSwitchMap(sources, Functions.identity(), bufferSize, false));
4152 }
4153
4154 /**
4155 * Converts an {@link ObservableSource} that emits {@code ObservableSource}s into an {@code Observable} that emits the items emitted by the
4156 * most recently emitted of those {@code ObservableSource}s.
4157 * <p>
4158 * <img width="640" height="370" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/switchDo.v3.png" alt="">
4159 * <p>
4160 * {@code switchOnNext} subscribes to an {@code ObservableSource} that emits {@code ObservableSource}s. Each time it observes one of
4161 * these emitted {@code ObservableSource}s, the {@code ObservableSource} returned by {@code switchOnNext} begins emitting the items
4162 * emitted by that {@code ObservableSource}. When a new inner {@code ObservableSource} is emitted, {@code switchOnNext} stops emitting items
4163 * from the earlier-emitted {@code ObservableSource} and begins emitting items from the new one.
4164 * <p>
4165 * The resulting {@code Observable} completes if both the outer {@code ObservableSource} and the last inner {@code ObservableSource}, if any, complete.
4166 * If the outer {@code ObservableSource} signals an {@code onError}, the inner {@code ObservableSource} is disposed and the error delivered in-sequence.
4167 * <dl>
4168 * <dt><b>Scheduler:</b></dt>
4169 * <dd>{@code switchOnNext} does not operate by default on a particular {@link Scheduler}.</dd>
4170 * </dl>
4171 *
4172 * @param <T> the item type
4173 * @param sources
4174 * the {@code ObservableSource} that emits {@code ObservableSource}s
4175 * @return the new {@code Observable} instance
4176 * @throws NullPointerException if {@code sources} is {@code null}
4177 * @see <a href="http://reactivex.io/documentation/operators/switch.html">ReactiveX operators documentation: Switch</a>
4178 */
4179 @CheckReturnValue
4180 @SchedulerSupport(SchedulerSupport.NONE)
4181 @NonNull
4182 public static <@NonNull T> Observable<T> switchOnNext(@NonNull ObservableSource<? extends ObservableSource<? extends T>> sources) {
4183 return switchOnNext(sources, bufferSize());
4184 }
4185
4186 /**
4187 * Converts an {@link ObservableSource} that emits {@code ObservableSource}s into an {@code Observable} that emits the items emitted by the
4188 * most recently emitted of those {@code ObservableSource}s and delays any exception until all {@code ObservableSource}s terminate.
4189 * <p>
4190 * <img width="640" height="370" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/switchOnNextDelayError.v3.png" alt="">
4191 * <p>
4192 * {@code switchOnNext} subscribes to an {@code ObservableSource} that emits {@code ObservableSource}s. Each time it observes one of
4193 * these emitted {@code ObservableSource}s, the {@code ObservableSource} returned by {@code switchOnNext} begins emitting the items
4194 * emitted by that {@code ObservableSource}. When a new inner {@code ObservableSource} is emitted, {@code switchOnNext} stops emitting items
4195 * from the earlier-emitted {@code ObservableSource} and begins emitting items from the new one.
4196 * <p>
4197 * The resulting {@code Observable} completes if both the main {@code ObservableSource} and the last inner {@code ObservableSource}, if any, complete.
4198 * If the main {@code ObservableSource} signals an {@code onError}, the termination of the last inner {@code ObservableSource} will emit that error as is
4199 * or wrapped into a {@link CompositeException} along with the other possible errors the former inner {@code ObservableSource}s signaled.
4200 * <dl>
4201 * <dt><b>Scheduler:</b></dt>
4202 * <dd>{@code switchOnNextDelayError} does not operate by default on a particular {@link Scheduler}.</dd>
4203 * </dl>
4204 *
4205 * @param <T> the item type
4206 * @param sources
4207 * the {@code ObservableSource} that emits {@code ObservableSource}s
4208 * @return the new {@code Observable} instance
4209 * @throws NullPointerException if {@code sources} is {@code null}
4210 * @see <a href="http://reactivex.io/documentation/operators/switch.html">ReactiveX operators documentation: Switch</a>
4211 * @since 2.0
4212 */
4213 @CheckReturnValue
4214 @SchedulerSupport(SchedulerSupport.NONE)
4215 @NonNull
4216 public static <@NonNull T> Observable<T> switchOnNextDelayError(@NonNull ObservableSource<? extends ObservableSource<? extends T>> sources) {
4217 return switchOnNextDelayError(sources, bufferSize());
4218 }
4219
4220 /**
4221 * Converts an {@link ObservableSource} that emits {@code ObservableSource}s into an {@code Observable} that emits the items emitted by the
4222 * most recently emitted of those {@code ObservableSource}s and delays any exception until all {@code ObservableSource}s terminate.
4223 * <p>
4224 * <img width="640" height="370" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/switchOnNextDelayError.v3.png" alt="">
4225 * <p>
4226 * {@code switchOnNext} subscribes to an {@code ObservableSource} that emits {@code ObservableSource}s. Each time it observes one of
4227 * these emitted {@code ObservableSource}s, the {@code ObservableSource} returned by {@code switchOnNext} begins emitting the items
4228 * emitted by that {@code ObservableSource}. When a new inner {@code ObservableSource} is emitted, {@code switchOnNext} stops emitting items
4229 * from the earlier-emitted {@code ObservableSource} and begins emitting items from the new one.
4230 * <p>
4231 * The resulting {@code Observable} completes if both the main {@code ObservableSource} and the last inner {@code ObservableSource}, if any, complete.
4232 * If the main {@code ObservableSource} signals an {@code onError}, the termination of the last inner {@code ObservableSource} will emit that error as is
4233 * or wrapped into a {@link CompositeException} along with the other possible errors the former inner {@code ObservableSource}s signaled.
4234 * <dl>
4235 * <dt><b>Scheduler:</b></dt>
4236 * <dd>{@code switchOnNextDelayError} does not operate by default on a particular {@link Scheduler}.</dd>
4237 * </dl>
4238 *
4239 * @param <T> the item type
4240 * @param sources
4241 * the {@code ObservableSource} that emits {@code ObservableSource}s
4242 * @param bufferSize
4243 * the expected number of items to cache from the inner {@code ObservableSource}s
4244 * @return the new {@code Observable} instance
4245 * @throws NullPointerException if {@code sources} is {@code null}
4246 * @throws IllegalArgumentException if {@code bufferSize} is non-positive
4247 * @see <a href="http://reactivex.io/documentation/operators/switch.html">ReactiveX operators documentation: Switch</a>
4248 * @since 2.0
4249 */
4250 @SuppressWarnings({ "rawtypes", "unchecked" })
4251 @CheckReturnValue
4252 @SchedulerSupport(SchedulerSupport.NONE)
4253 @NonNull
4254 public static <@NonNull T> Observable<T> switchOnNextDelayError(@NonNull ObservableSource<? extends ObservableSource<? extends T>> sources, int bufferSize) {
4255 Objects.requireNonNull(sources, "sources is null");
4256 ObjectHelper.verifyPositive(bufferSize, "bufferSize");
4257 return RxJavaPlugins.onAssembly(new ObservableSwitchMap(sources, Functions.identity(), bufferSize, true));
4258 }
4259
4260 /**
4261 * Returns an {@code Observable} that emits {@code 0L} after a specified delay, and then completes.
4262 * <p>
4263 * <img width="640" height="200" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/timer.v3.png" alt="">
4264 * <dl>
4265 * <dt><b>Scheduler:</b></dt>
4266 * <dd>{@code timer} operates by default on the {@code computation} {@link Scheduler}.</dd>
4267 * </dl>
4268 *
4269 * @param delay
4270 * the initial delay before emitting a single {@code 0L}
4271 * @param unit
4272 * time units to use for {@code delay}
4273 * @return the new {@code Observable} instance
4274 * @throws NullPointerException if {@code unit} is {@code null}
4275 * @see <a href="http://reactivex.io/documentation/operators/timer.html">ReactiveX operators documentation: Timer</a>
4276 */
4277 @CheckReturnValue
4278 @SchedulerSupport(SchedulerSupport.COMPUTATION)
4279 @NonNull
4280 public static Observable<Long> timer(long delay, @NonNull TimeUnit unit) {
4281 return timer(delay, unit, Schedulers.computation());
4282 }
4283
4284 /**
4285 * Returns an {@code Observable} that emits {@code 0L} after a specified delay, on a specified {@link Scheduler}, and then
4286 * completes.
4287 * <p>
4288 * <img width="640" height="200" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/timer.s.v3.png" alt="">
4289 * <dl>
4290 * <dt><b>Scheduler:</b></dt>
4291 * <dd>You specify which {@code Scheduler} this operator will use.</dd>
4292 * </dl>
4293 *
4294 * @param delay
4295 * the initial delay before emitting a single 0L
4296 * @param unit
4297 * time units to use for {@code delay}
4298 * @param scheduler
4299 * the {@code Scheduler} to use for scheduling the item
4300 * @throws NullPointerException
4301 * if {@code unit} or {@code scheduler} is {@code null}
4302 * @return the new {@code Observable} instance
4303 * @see <a href="http://reactivex.io/documentation/operators/timer.html">ReactiveX operators documentation: Timer</a>
4304 */
4305 @CheckReturnValue
4306 @SchedulerSupport(SchedulerSupport.CUSTOM)
4307 @NonNull
4308 public static Observable<Long> timer(long delay, @NonNull TimeUnit unit, @NonNull Scheduler scheduler) {
4309 Objects.requireNonNull(unit, "unit is null");
4310 Objects.requireNonNull(scheduler, "scheduler is null");
4311
4312 return RxJavaPlugins.onAssembly(new ObservableTimer(Math.max(delay, 0L), unit, scheduler));
4313 }
4314
4315 /**
4316 * Create an {@code Observable} by wrapping an {@link ObservableSource} <em>which has to be implemented according
4317 * to the {@code Observable} specification derived from the <b>Reactive Streams</b> specification by handling
4318 * disposal correctly; no safeguards are provided by the {@code Observable} itself</em>.
4319 * <dl>
4320 * <dt><b>Scheduler:</b></dt>
4321 * <dd>{@code unsafeCreate} by default doesn't operate on any particular {@link Scheduler}.</dd>
4322 * </dl>
4323 * @param <T> the value type emitted
4324 * @param onSubscribe the {@code ObservableSource} instance to wrap
4325 * @return the new {@code Observable} instance
4326 * @throws NullPointerException if {@code onSubscribe} is {@code null}
4327 * @throws IllegalArgumentException if the {@code onSubscribe} is already an {@code Observable}, use
4328 * {@link #wrap(ObservableSource)} in this case
4329 * @see #wrap(ObservableSource)
4330 */
4331 @CheckReturnValue
4332 @SchedulerSupport(SchedulerSupport.NONE)
4333 @NonNull
4334 public static <@NonNull T> Observable<T> unsafeCreate(@NonNull ObservableSource<T> onSubscribe) {
4335 Objects.requireNonNull(onSubscribe, "onSubscribe is null");
4336 if (onSubscribe instanceof Observable) {
4337 throw new IllegalArgumentException("unsafeCreate(Observable) should be upgraded");
4338 }
4339 return RxJavaPlugins.onAssembly(new ObservableFromUnsafeSource<>(onSubscribe));
4340 }
4341
4342 /**
4343 * Constructs an {@code Observable} that creates a dependent resource object, an {@link ObservableSource} with
4344 * that resource and calls the provided {@code resourceDisposer} function if this inner source terminates or the
4345 * downstream disposes the flow.
4346 * <p>
4347 * <img width="640" height="400" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/using.v3.png" alt="">
4348 * <dl>
4349 * <dt><b>Scheduler:</b></dt>
4350 * <dd>{@code using} does not operate by default on a particular {@link Scheduler}.</dd>
4351 * </dl>
4352 *
4353 * @param <T> the element type of the generated {@code Observable}
4354 * @param <D> the type of the resource associated with the output sequence
4355 * @param resourceSupplier
4356 * the factory function to create a resource object that depends on the {@code ObservableSource}
4357 * @param sourceSupplier
4358 * the factory function to create an {@code ObservableSource}
4359 * @param resourceCleanup
4360 * the function that will dispose of the resource
4361 * @return the new {@code Observable} instance
4362 * @throws NullPointerException if {@code resourceSupplier}, {@code sourceSupplier} or {@code resourceCleanup} is {@code null}
4363 * @see <a href="http://reactivex.io/documentation/operators/using.html">ReactiveX operators documentation: Using</a>
4364 */
4365 @CheckReturnValue
4366 @SchedulerSupport(SchedulerSupport.NONE)
4367 @NonNull
4368 public static <@NonNull T, @NonNull D> Observable<T> using(
4369 @NonNull Supplier<? extends D> resourceSupplier,
4370 @NonNull Function<? super D, ? extends ObservableSource<? extends T>> sourceSupplier,
4371 @NonNull Consumer<? super D> resourceCleanup) {
4372 return using(resourceSupplier, sourceSupplier, resourceCleanup, true);
4373 }
4374
4375 /**
4376 * Constructs an {@code Observable} that creates a dependent resource object, an {@link ObservableSource} with
4377 * that resource and calls the provided {@code disposer} function if this inner source terminates or the
4378 * downstream disposes the flow; doing it before these end-states have been reached if {@code eager == true}, after otherwise.
4379 * <p>
4380 * <img width="640" height="400" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/using.v3.png" alt="">
4381 * <dl>
4382 * <dt><b>Scheduler:</b></dt>
4383 * <dd>{@code using} does not operate by default on a particular {@link Scheduler}.</dd>
4384 * </dl>
4385 *
4386 * @param <T> the element type of the generated {@code ObservableSource}
4387 * @param <D> the type of the resource associated with the output sequence
4388 * @param resourceSupplier
4389 * the factory function to create a resource object that depends on the {@code ObservableSource}
4390 * @param sourceSupplier
4391 * the factory function to create an {@code ObservableSource}
4392 * @param resourceCleanup
4393 * the function that will dispose of the resource
4394 * @param eager
4395 * If {@code true}, the resource disposal will happen either on a {@code dispose()} call before the upstream is disposed
4396 * or just before the emission of a terminal event ({@code onComplete} or {@code onError}).
4397 * If {@code false}, the resource disposal will happen either on a {@code dispose()} call after the upstream is disposed
4398 * or just after the emission of a terminal event ({@code onComplete} or {@code onError}).
4399 * @return the new {@code Observable} instance
4400 * @throws NullPointerException if {@code resourceSupplier}, {@code sourceSupplier} and {@code resourceCleanup} is {@code null}
4401 * @see <a href="http://reactivex.io/documentation/operators/using.html">ReactiveX operators documentation: Using</a>
4402 * @since 2.0
4403 */
4404 @CheckReturnValue
4405 @SchedulerSupport(SchedulerSupport.NONE)
4406 @NonNull
4407 public static <@NonNull T, @NonNull D> Observable<T> using(
4408 @NonNull Supplier<? extends D> resourceSupplier,
4409 @NonNull Function<? super D, ? extends ObservableSource<? extends T>> sourceSupplier,
4410 @NonNull Consumer<? super D> resourceCleanup, boolean eager) {
4411 Objects.requireNonNull(resourceSupplier, "resourceSupplier is null");
4412 Objects.requireNonNull(sourceSupplier, "sourceSupplier is null");
4413 Objects.requireNonNull(resourceCleanup, "resourceCleanup is null");
4414 return RxJavaPlugins.onAssembly(new ObservableUsing<T, D>(resourceSupplier, sourceSupplier, resourceCleanup, eager));
4415 }
4416
4417 /**
4418 * Wraps an {@link ObservableSource} into an {@code Observable} if not already an {@code Observable}.
4419 *
4420 * <dl>
4421 * <dt><b>Scheduler:</b></dt>
4422 * <dd>{@code wrap} does not operate by default on a particular {@link Scheduler}.</dd>
4423 * </dl>
4424 *
4425 * @param <T> the value type
4426 * @param source the {@code ObservableSource} instance to wrap or cast to {@code Observable}
4427 * @return the new {@code Observable} instance or the same as the source
4428 * @throws NullPointerException if {@code source} is {@code null}
4429 */
4430 @CheckReturnValue
4431 @SchedulerSupport(SchedulerSupport.NONE)
4432 @NonNull
4433 public static <@NonNull T> Observable<T> wrap(@NonNull ObservableSource<T> source) {
4434 Objects.requireNonNull(source, "source is null");
4435 if (source instanceof Observable) {
4436 return RxJavaPlugins.onAssembly((Observable<T>)source);
4437 }
4438 return RxJavaPlugins.onAssembly(new ObservableFromUnsafeSource<>(source));
4439 }
4440
4441 /**
4442 * Returns an {@code Observable} that emits the results of a specified combiner function applied to combinations of
4443 * items emitted, in sequence, by an {@link Iterable} of other {@link ObservableSource}s.
4444 * <p>
4445 * {@code zip} applies this function in strict sequence, so the first item emitted by the resulting {@code Observable}
4446 * will be the result of the function applied to the first item emitted by each of the {@code ObservableSource}s;
4447 * the second item emitted by the resulting {@code Observable} will be the result of the function applied to the second
4448 * item emitted by each of those {@code ObservableSource}s; and so forth.
4449 * <p>
4450 * The resulting {@code Observable<R>} returned from {@code zip} will invoke {@code onNext} as many times as
4451 * the number of {@code onNext} invocations of the {@code ObservableSource} that emits the fewest items.
4452 * <p>
4453 * The operator subscribes to its sources in order they are specified and completes eagerly if
4454 * one of the sources is shorter than the rest while disposing the other sources. Therefore, it
4455 * is possible those other sources will never be able to run to completion (and thus not calling
4456 * {@code doOnComplete()}). This can also happen if the sources are exactly the same length; if
4457 * source A completes and B has been consumed and is about to complete, the operator detects A won't
4458 * be sending further values and it will dispose B immediately. For example:
4459 * <pre><code>zip(Arrays.asList(range(1, 5).doOnComplete(action1), range(6, 5).doOnComplete(action2)), (a) -&gt; a)</code></pre>
4460 * {@code action1} will be called but {@code action2} won't.
4461 * <br>To work around this termination property,
4462 * use {@link #doOnDispose(Action)} as well or use {@code using()} to do cleanup in case of completion
4463 * or a dispose() call.
4464 * <p>
4465 * Note on method signature: since Java doesn't allow creating a generic array with {@code new T[]}, the
4466 * implementation of this operator has to create an {@code Object[]} instead. Unfortunately, a
4467 * {@code Function<Integer[], R>} passed to the method would trigger a {@link ClassCastException}.
4468 *
4469 * <p>
4470 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/zip.v3.png" alt="">
4471 * <dl>
4472 * <dt><b>Scheduler:</b></dt>
4473 * <dd>{@code zip} does not operate by default on a particular {@link Scheduler}.</dd>
4474 * </dl>
4475 *
4476 * @param <T> the common value type
4477 * @param <R> the zipped result type
4478 * @param sources
4479 * an {@code Iterable} of source {@code ObservableSource}s
4480 * @param zipper
4481 * a function that, when applied to an item emitted by each of the {@code ObservableSource}s, results in
4482 * an item that will be emitted by the resulting {@code Observable}
4483 * @return the new {@code Observable} instance
4484 * @throws NullPointerException if {@code sources} or {@code zipper} is {@code null}
4485 * @see <a href="http://reactivex.io/documentation/operators/zip.html">ReactiveX operators documentation: Zip</a>
4486 */
4487 @CheckReturnValue
4488 @SchedulerSupport(SchedulerSupport.NONE)
4489 @NonNull
4490 public static <@NonNull T, @NonNull R> Observable<R> zip(@NonNull Iterable<@NonNull ? extends ObservableSource<? extends T>> sources, @NonNull Function<? super Object[], ? extends R> zipper) {
4491 Objects.requireNonNull(zipper, "zipper is null");
4492 Objects.requireNonNull(sources, "sources is null");
4493 return RxJavaPlugins.onAssembly(new ObservableZip<>(null, sources, zipper, bufferSize(), false));
4494 }
4495
4496 /**
4497 * Returns an {@code Observable} that emits the results of a specified combiner function applied to combinations of
4498 * items emitted, in sequence, by an {@link Iterable} of other {@link ObservableSource}s.
4499 * <p>
4500 * {@code zip} applies this function in strict sequence, so the first item emitted by the resulting {@code Observable}
4501 * will be the result of the function applied to the first item emitted by each of the {@code ObservableSource}s;
4502 * the second item emitted by the resulting {@code Observable} will be the result of the function applied to the second
4503 * item emitted by each of those {@code ObservableSource}s; and so forth.
4504 * <p>
4505 * The resulting {@code Observable<R>} returned from {@code zip} will invoke {@code onNext} as many times as
4506 * the number of {@code onNext} invocations of the {@code ObservableSource} that emits the fewest items.
4507 * <p>
4508 * The operator subscribes to its sources in order they are specified and completes eagerly if
4509 * one of the sources is shorter than the rest while disposing the other sources. Therefore, it
4510 * is possible those other sources will never be able to run to completion (and thus not calling
4511 * {@code doOnComplete()}). This can also happen if the sources are exactly the same length; if
4512 * source A completes and B has been consumed and is about to complete, the operator detects A won't
4513 * be sending further values and it will dispose B immediately. For example:
4514 * <pre><code>zip(Arrays.asList(range(1, 5).doOnComplete(action1), range(6, 5).doOnComplete(action2)), (a) -&gt; a)</code></pre>
4515 * {@code action1} will be called but {@code action2} won't.
4516 * <br>To work around this termination property,
4517 * use {@link #doOnDispose(Action)} as well or use {@code using()} to do cleanup in case of completion
4518 * or a dispose() call.
4519 * <p>
4520 * Note on method signature: since Java doesn't allow creating a generic array with {@code new T[]}, the
4521 * implementation of this operator has to create an {@code Object[]} instead. Unfortunately, a
4522 * {@code Function<Integer[], R>} passed to the method would trigger a {@link ClassCastException}.
4523 *
4524 * <p>
4525 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/zipIterable.o.v3.png" alt="">
4526 * <dl>
4527 * <dt><b>Scheduler:</b></dt>
4528 * <dd>{@code zip} does not operate by default on a particular {@link Scheduler}.</dd>
4529 * </dl>
4530 *
4531 *
4532 * @param sources
4533 * an {@code Iterable} of source {@code ObservableSource}s
4534 * @param zipper
4535 * a function that, when applied to an item emitted by each of the {@code ObservableSource}s, results in
4536 * an item that will be emitted by the resulting {@code Observable}
4537 * @param delayError
4538 * delay errors signaled by any of the {@code ObservableSource} until all {@code ObservableSource}s terminate
4539 * @param bufferSize
4540 * the number of elements expected from each source {@code ObservableSource} to be buffered
4541 * @param <T> the common source value type
4542 * @param <R> the zipped result type
4543 * @return the new {@code Observable} instance
4544 * @throws NullPointerException if {@code sources} or {@code zipper} is {@code null}
4545 * @throws IllegalArgumentException if {@code bufferSize} is non-positive
4546 * @see <a href="http://reactivex.io/documentation/operators/zip.html">ReactiveX operators documentation: Zip</a>
4547 */
4548 @CheckReturnValue
4549 @SchedulerSupport(SchedulerSupport.NONE)
4550 @NonNull
4551 public static <@NonNull T, @NonNull R> Observable<R> zip(@NonNull Iterable<@NonNull ? extends ObservableSource<? extends T>> sources,
4552 @NonNull Function<? super Object[], ? extends R> zipper, boolean delayError,
4553 int bufferSize) {
4554 Objects.requireNonNull(zipper, "zipper is null");
4555 Objects.requireNonNull(sources, "sources is null");
4556 ObjectHelper.verifyPositive(bufferSize, "bufferSize");
4557 return RxJavaPlugins.onAssembly(new ObservableZip<>(null, sources, zipper, bufferSize, delayError));
4558 }
4559
4560 /**
4561 * Returns an {@code Observable} that emits the results of a specified combiner function applied to combinations of
4562 * two items emitted, in sequence, by two other {@link ObservableSource}s.
4563 * <p>
4564 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/zip.v3.png" alt="">
4565 * <p>
4566 * {@code zip} applies this function in strict sequence, so the first item emitted by the resulting {@code Observable}
4567 * will be the result of the function applied to the first item emitted by {@code o1} and the first item
4568 * emitted by {@code o2}; the second item emitted by the resulting {@code Observable} will be the result of the function
4569 * applied to the second item emitted by {@code o1} and the second item emitted by {@code o2}; and so forth.
4570 * <p>
4571 * The resulting {@code Observable<R>} returned from {@code zip} will invoke {@link Observer#onNext onNext}
4572 * as many times as the number of {@code onNext} invocations of the {@code ObservableSource} that emits the fewest
4573 * items.
4574 * <p>
4575 * The operator subscribes to its sources in order they are specified and completes eagerly if
4576 * one of the sources is shorter than the rest while disposing the other sources. Therefore, it
4577 * is possible those other sources will never be able to run to completion (and thus not calling
4578 * {@code doOnComplete()}). This can also happen if the sources are exactly the same length; if
4579 * source A completes and B has been consumed and is about to complete, the operator detects A won't
4580 * be sending further values and it will dispose B immediately. For example:
4581 * <pre><code>zip(range(1, 5).doOnComplete(action1), range(6, 5).doOnComplete(action2), (a, b) -&gt; a + b)</code></pre>
4582 * {@code action1} will be called but {@code action2} won't.
4583 * <br>To work around this termination property,
4584 * use {@link #doOnDispose(Action)} as well or use {@code using()} to do cleanup in case of completion
4585 * or a dispose() call.
4586 * <dl>
4587 * <dt><b>Scheduler:</b></dt>
4588 * <dd>{@code zip} does not operate by default on a particular {@link Scheduler}.</dd>
4589 * </dl>
4590 *
4591 * @param <T1> the value type of the first source
4592 * @param <T2> the value type of the second source
4593 * @param <R> the zipped result type
4594 * @param source1
4595 * the first source {@code ObservableSource}
4596 * @param source2
4597 * a second source {@code ObservableSource}
4598 * @param zipper
4599 * a function that, when applied to an item emitted by each of the {@code ObservableSource}s, results
4600 * in an item that will be emitted by the resulting {@code Observable}
4601 * @return the new {@code Observable} instance
4602 * @throws NullPointerException if {@code source1}, {@code source2} or {@code zipper} is {@code null}
4603 * @see <a href="http://reactivex.io/documentation/operators/zip.html">ReactiveX operators documentation: Zip</a>
4604 */
4605 @CheckReturnValue
4606 @SchedulerSupport(SchedulerSupport.NONE)
4607 @NonNull
4608 public static <@NonNull T1, @NonNull T2, @NonNull R> Observable<R> zip(
4609 @NonNull ObservableSource<? extends T1> source1, @NonNull ObservableSource<? extends T2> source2,
4610 @NonNull BiFunction<? super T1, ? super T2, ? extends R> zipper) {
4611 Objects.requireNonNull(source1, "source1 is null");
4612 Objects.requireNonNull(source2, "source2 is null");
4613 Objects.requireNonNull(zipper, "zipper is null");
4614 return zipArray(Functions.toFunction(zipper), false, bufferSize(), source1, source2);
4615 }
4616
4617 /**
4618 * Returns an {@code Observable} that emits the results of a specified combiner function applied to combinations of
4619 * two items emitted, in sequence, by two other {@link ObservableSource}s.
4620 * <p>
4621 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/zip.v3.png" alt="">
4622 * <p>
4623 * {@code zip} applies this function in strict sequence, so the first item emitted by the resulting {@code Observable}
4624 * will be the result of the function applied to the first item emitted by {@code o1} and the first item
4625 * emitted by {@code o2}; the second item emitted by the resulting {@code Observable} will be the result of the function
4626 * applied to the second item emitted by {@code o1} and the second item emitted by {@code o2}; and so forth.
4627 * <p>
4628 * The resulting {@code Observable<R>} returned from {@code zip} will invoke {@link Observer#onNext onNext}
4629 * as many times as the number of {@code onNext} invocations of the {@code ObservableSource} that emits the fewest
4630 * items.
4631 * <p>
4632 * The operator subscribes to its sources in order they are specified and completes eagerly if
4633 * one of the sources is shorter than the rest while disposing the other sources. Therefore, it
4634 * is possible those other sources will never be able to run to completion (and thus not calling
4635 * {@code doOnComplete()}). This can also happen if the sources are exactly the same length; if
4636 * source A completes and B has been consumed and is about to complete, the operator detects A won't
4637 * be sending further values and it will dispose B immediately. For example:
4638 * <pre><code>zip(range(1, 5).doOnComplete(action1), range(6, 5).doOnComplete(action2), (a, b) -&gt; a + b)</code></pre>
4639 * {@code action1} will be called but {@code action2} won't.
4640 * <br>To work around this termination property,
4641 * use {@link #doOnDispose(Action)} as well or use {@code using()} to do cleanup in case of completion
4642 * or a dispose() call.
4643 * <dl>
4644 * <dt><b>Scheduler:</b></dt>
4645 * <dd>{@code zip} does not operate by default on a particular {@link Scheduler}.</dd>
4646 * </dl>
4647 *
4648 * @param <T1> the value type of the first source
4649 * @param <T2> the value type of the second source
4650 * @param <R> the zipped result type
4651 * @param source1
4652 * the first source {@code ObservableSource}
4653 * @param source2
4654 * a second source {@code ObservableSource}
4655 * @param zipper
4656 * a function that, when applied to an item emitted by each of the {@code ObservableSource}s, results
4657 * in an item that will be emitted by the resulting {@code Observable}
4658 * @param delayError delay errors from any of the {@code ObservableSource}s till the other terminates
4659 * @return the new {@code Observable} instance
4660 * @throws NullPointerException if {@code source1}, {@code source2} or {@code zipper} is {@code null}
4661 * @see <a href="http://reactivex.io/documentation/operators/zip.html">ReactiveX operators documentation: Zip</a>
4662 */
4663 @CheckReturnValue
4664 @SchedulerSupport(SchedulerSupport.NONE)
4665 @NonNull
4666 public static <@NonNull T1, @NonNull T2, @NonNull R> Observable<R> zip(
4667 @NonNull ObservableSource<? extends T1> source1, @NonNull ObservableSource<? extends T2> source2,
4668 @NonNull BiFunction<? super T1, ? super T2, ? extends R> zipper, boolean delayError) {
4669 Objects.requireNonNull(source1, "source1 is null");
4670 Objects.requireNonNull(source2, "source2 is null");
4671 Objects.requireNonNull(zipper, "zipper is null");
4672 return zipArray(Functions.toFunction(zipper), delayError, bufferSize(), source1, source2);
4673 }
4674
4675 /**
4676 * Returns an {@code Observable} that emits the results of a specified combiner function applied to combinations of
4677 * two items emitted, in sequence, by two other {@link ObservableSource}s.
4678 * <p>
4679 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/zip.v3.png" alt="">
4680 * <p>
4681 * {@code zip} applies this function in strict sequence, so the first item emitted by the resulting {@code Observable}
4682 * will be the result of the function applied to the first item emitted by {@code o1} and the first item
4683 * emitted by {@code o2}; the second item emitted by the resulting {@code Observable} will be the result of the function
4684 * applied to the second item emitted by {@code o1} and the second item emitted by {@code o2}; and so forth.
4685 * <p>
4686 * The resulting {@code Observable<R>} returned from {@code zip} will invoke {@link Observer#onNext onNext}
4687 * as many times as the number of {@code onNext} invocations of the {@code ObservableSource} that emits the fewest
4688 * items.
4689 * <p>
4690 * The operator subscribes to its sources in order they are specified and completes eagerly if
4691 * one of the sources is shorter than the rest while disposing the other sources. Therefore, it
4692 * is possible those other sources will never be able to run to completion (and thus not calling
4693 * {@code doOnComplete()}). This can also happen if the sources are exactly the same length; if
4694 * source A completes and B has been consumed and is about to complete, the operator detects A won't
4695 * be sending further values and it will dispose B immediately. For example:
4696 * <pre><code>zip(range(1, 5).doOnComplete(action1), range(6, 5).doOnComplete(action2), (a, b) -&gt; a + b)</code></pre>
4697 * {@code action1} will be called but {@code action2} won't.
4698 * <br>To work around this termination property,
4699 * use {@link #doOnDispose(Action)} as well or use {@code using()} to do cleanup in case of completion
4700 * or a dispose() call.
4701 * <dl>
4702 * <dt><b>Scheduler:</b></dt>
4703 * <dd>{@code zip} does not operate by default on a particular {@link Scheduler}.</dd>
4704 * </dl>
4705 *
4706 * @param <T1> the value type of the first source
4707 * @param <T2> the value type of the second source
4708 * @param <R> the zipped result type
4709 * @param source1
4710 * the first source {@code ObservableSource}
4711 * @param source2
4712 * a second source {@code ObservableSource}
4713 * @param zipper
4714 * a function that, when applied to an item emitted by each of the {@code ObservableSource}s, results
4715 * in an item that will be emitted by the resulting {@code Observable}
4716 * @param delayError delay errors from any of the {@code ObservableSource}s till the other terminates
4717 * @param bufferSize the number of elements expected from each source {@code ObservableSource} to be buffered
4718 * @return the new {@code Observable} instance
4719 * @throws NullPointerException if {@code source1}, {@code source2} or {@code zipper} is {@code null}
4720 * @throws IllegalArgumentException if {@code bufferSize} is non-positive
4721 * @see <a href="http://reactivex.io/documentation/operators/zip.html">ReactiveX operators documentation: Zip</a>
4722 */
4723 @CheckReturnValue
4724 @SchedulerSupport(SchedulerSupport.NONE)
4725 @NonNull
4726 public static <@NonNull T1, @NonNull T2, @NonNull R> Observable<R> zip(
4727 @NonNull ObservableSource<? extends T1> source1, @NonNull ObservableSource<? extends T2> source2,
4728 @NonNull BiFunction<? super T1, ? super T2, ? extends R> zipper, boolean delayError, int bufferSize) {
4729 Objects.requireNonNull(source1, "source1 is null");
4730 Objects.requireNonNull(source2, "source2 is null");
4731 Objects.requireNonNull(zipper, "zipper is null");
4732 return zipArray(Functions.toFunction(zipper), delayError, bufferSize, source1, source2);
4733 }
4734
4735 /**
4736 * Returns an {@code Observable} that emits the results of a specified combiner function applied to combinations of
4737 * three items emitted, in sequence, by three other {@link ObservableSource}s.
4738 * <p>
4739 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/zip.v3.png" alt="">
4740 * <p>
4741 * {@code zip} applies this function in strict sequence, so the first item emitted by the resulting {@code Observable}
4742 * will be the result of the function applied to the first item emitted by {@code o1}, the first item
4743 * emitted by {@code o2}, and the first item emitted by {@code o3}; the second item emitted by the resulting
4744 * {@code Observable} will be the result of the function applied to the second item emitted by {@code o1}, the
4745 * second item emitted by {@code o2}, and the second item emitted by {@code o3}; and so forth.
4746 * <p>
4747 * The resulting {@code Observable<R>} returned from {@code zip} will invoke {@link Observer#onNext onNext}
4748 * as many times as the number of {@code onNext} invocations of the {@code ObservableSource} that emits the fewest
4749 * items.
4750 * <p>
4751 * The operator subscribes to its sources in order they are specified and completes eagerly if
4752 * one of the sources is shorter than the rest while disposing the other sources. Therefore, it
4753 * is possible those other sources will never be able to run to completion (and thus not calling
4754 * {@code doOnComplete()}). This can also happen if the sources are exactly the same length; if
4755 * source A completes and B has been consumed and is about to complete, the operator detects A won't
4756 * be sending further values and it will dispose B immediately. For example:
4757 * <pre><code>zip(range(1, 5).doOnComplete(action1), range(6, 5).doOnComplete(action2), ..., (a, b, c) -&gt; a + b)</code></pre>
4758 * {@code action1} will be called but {@code action2} won't.
4759 * <br>To work around this termination property,
4760 * use {@link #doOnDispose(Action)} as well or use {@code using()} to do cleanup in case of completion
4761 * or a dispose() call.
4762 * <dl>
4763 * <dt><b>Scheduler:</b></dt>
4764 * <dd>{@code zip} does not operate by default on a particular {@link Scheduler}.</dd>
4765 * </dl>
4766 *
4767 * @param <T1> the value type of the first source
4768 * @param <T2> the value type of the second source
4769 * @param <T3> the value type of the third source
4770 * @param <R> the zipped result type
4771 * @param source1
4772 * the first source {@code ObservableSource}
4773 * @param source2
4774 * a second source {@code ObservableSource}
4775 * @param source3
4776 * a third source {@code ObservableSource}
4777 * @param zipper
4778 * a function that, when applied to an item emitted by each of the {@code ObservableSource}s, results in
4779 * an item that will be emitted by the resulting {@code Observable}
4780 * @return the new {@code Observable} instance
4781 * @throws NullPointerException if {@code source1}, {@code source2}, {@code source3} or {@code zipper} is {@code null}
4782 * @see <a href="http://reactivex.io/documentation/operators/zip.html">ReactiveX operators documentation: Zip</a>
4783 */
4784 @CheckReturnValue
4785 @SchedulerSupport(SchedulerSupport.NONE)
4786 @NonNull
4787 public static <@NonNull T1, @NonNull T2, @NonNull T3, @NonNull R> Observable<R> zip(
4788 @NonNull ObservableSource<? extends T1> source1, @NonNull ObservableSource<? extends T2> source2,
4789 @NonNull ObservableSource<? extends T3> source3,
4790 @NonNull Function3<? super T1, ? super T2, ? super T3, ? extends R> zipper) {
4791 Objects.requireNonNull(source1, "source1 is null");
4792 Objects.requireNonNull(source2, "source2 is null");
4793 Objects.requireNonNull(source3, "source3 is null");
4794 Objects.requireNonNull(zipper, "zipper is null");
4795 return zipArray(Functions.toFunction(zipper), false, bufferSize(), source1, source2, source3);
4796 }
4797
4798 /**
4799 * Returns an {@code Observable} that emits the results of a specified combiner function applied to combinations of
4800 * four items emitted, in sequence, by four other {@link ObservableSource}s.
4801 * <p>
4802 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/zip.v3.png" alt="">
4803 * <p>
4804 * {@code zip} applies this function in strict sequence, so the first item emitted by the resulting {@code Observable}
4805 * will be the result of the function applied to the first item emitted by {@code o1}, the first item
4806 * emitted by {@code o2}, the first item emitted by {@code o3}, and the first item emitted by {@code 04};
4807 * the second item emitted by the resulting {@code Observable} will be the result of the function applied to the second
4808 * item emitted by each of those {@code ObservableSource}s; and so forth.
4809 * <p>
4810 * The resulting {@code Observable<R>} returned from {@code zip} will invoke {@link Observer#onNext onNext}
4811 * as many times as the number of {@code onNext} invocations of the {@code ObservableSource} that emits the fewest
4812 * items.
4813 * <p>
4814 * The operator subscribes to its sources in order they are specified and completes eagerly if
4815 * one of the sources is shorter than the rest while disposing the other sources. Therefore, it
4816 * is possible those other sources will never be able to run to completion (and thus not calling
4817 * {@code doOnComplete()}). This can also happen if the sources are exactly the same length; if
4818 * source A completes and B has been consumed and is about to complete, the operator detects A won't
4819 * be sending further values and it will dispose B immediately. For example:
4820 * <pre><code>zip(range(1, 5).doOnComplete(action1), range(6, 5).doOnComplete(action2), ..., (a, b, c, d) -&gt; a + b)</code></pre>
4821 * {@code action1} will be called but {@code action2} won't.
4822 * <br>To work around this termination property,
4823 * use {@link #doOnDispose(Action)} as well or use {@code using()} to do cleanup in case of completion
4824 * or a dispose() call.
4825 * <dl>
4826 * <dt><b>Scheduler:</b></dt>
4827 * <dd>{@code zip} does not operate by default on a particular {@link Scheduler}.</dd>
4828 * </dl>
4829 *
4830 * @param <T1> the value type of the first source
4831 * @param <T2> the value type of the second source
4832 * @param <T3> the value type of the third source
4833 * @param <T4> the value type of the fourth source
4834 * @param <R> the zipped result type
4835 * @param source1
4836 * the first source {@code ObservableSource}
4837 * @param source2
4838 * a second source {@code ObservableSource}
4839 * @param source3
4840 * a third source {@code ObservableSource}
4841 * @param source4
4842 * a fourth source {@code ObservableSource}
4843 * @param zipper
4844 * a function that, when applied to an item emitted by each of the {@code ObservableSource}s, results in
4845 * an item that will be emitted by the resulting {@code Observable}
4846 * @return the new {@code Observable} instance
4847 * @throws NullPointerException if {@code source1}, {@code source2}, {@code source3},
4848 * {@code source4} or {@code zipper} is {@code null}
4849 * @see <a href="http://reactivex.io/documentation/operators/zip.html">ReactiveX operators documentation: Zip</a>
4850 */
4851 @CheckReturnValue
4852 @SchedulerSupport(SchedulerSupport.NONE)
4853 @NonNull
4854 public static <@NonNull T1, @NonNull T2, @NonNull T3, @NonNull T4, @NonNull R> Observable<R> zip(
4855 @NonNull ObservableSource<? extends T1> source1, @NonNull ObservableSource<? extends T2> source2,
4856 @NonNull ObservableSource<? extends T3> source3, @NonNull ObservableSource<? extends T4> source4,
4857 @NonNull Function4<? super T1, ? super T2, ? super T3, ? super T4, ? extends R> zipper) {
4858 Objects.requireNonNull(source1, "source1 is null");
4859 Objects.requireNonNull(source2, "source2 is null");
4860 Objects.requireNonNull(source3, "source3 is null");
4861 Objects.requireNonNull(source4, "source4 is null");
4862 Objects.requireNonNull(zipper, "zipper is null");
4863 return zipArray(Functions.toFunction(zipper), false, bufferSize(), source1, source2, source3, source4);
4864 }
4865
4866 /**
4867 * Returns an {@code Observable} that emits the results of a specified combiner function applied to combinations of
4868 * five items emitted, in sequence, by five other {@link ObservableSource}s.
4869 * <p>
4870 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/zip.v3.png" alt="">
4871 * <p>
4872 * {@code zip} applies this function in strict sequence, so the first item emitted by the resulting {@code Observable}
4873 * will be the result of the function applied to the first item emitted by {@code o1}, the first item
4874 * emitted by {@code o2}, the first item emitted by {@code o3}, the first item emitted by {@code o4}, and
4875 * the first item emitted by {@code o5}; the second item emitted by the resulting {@code Observable} will be the result of
4876 * the function applied to the second item emitted by each of those {@code ObservableSource}s; and so forth.
4877 * <p>
4878 * The resulting {@code Observable<R>} returned from {@code zip} will invoke {@link Observer#onNext onNext}
4879 * as many times as the number of {@code onNext} invocations of the {@code ObservableSource} that emits the fewest
4880 * items.
4881 * <p>
4882 * The operator subscribes to its sources in order they are specified and completes eagerly if
4883 * one of the sources is shorter than the rest while disposing the other sources. Therefore, it
4884 * is possible those other sources will never be able to run to completion (and thus not calling
4885 * {@code doOnComplete()}). This can also happen if the sources are exactly the same length; if
4886 * source A completes and B has been consumed and is about to complete, the operator detects A won't
4887 * be sending further values and it will dispose B immediately. For example:
4888 * <pre><code>zip(range(1, 5).doOnComplete(action1), range(6, 5).doOnComplete(action2), ..., (a, b, c, d, e) -&gt; a + b)</code></pre>
4889 * {@code action1} will be called but {@code action2} won't.
4890 * <br>To work around this termination property,
4891 * use {@link #doOnDispose(Action)} as well or use {@code using()} to do cleanup in case of completion
4892 * or a dispose() call.
4893 * <dl>
4894 * <dt><b>Scheduler:</b></dt>
4895 * <dd>{@code zip} does not operate by default on a particular {@link Scheduler}.</dd>
4896 * </dl>
4897 *
4898 * @param <T1> the value type of the first source
4899 * @param <T2> the value type of the second source
4900 * @param <T3> the value type of the third source
4901 * @param <T4> the value type of the fourth source
4902 * @param <T5> the value type of the fifth source
4903 * @param <R> the zipped result type
4904 * @param source1
4905 * the first source {@code ObservableSource}
4906 * @param source2
4907 * a second source {@code ObservableSource}
4908 * @param source3
4909 * a third source {@code ObservableSource}
4910 * @param source4
4911 * a fourth source {@code ObservableSource}
4912 * @param source5
4913 * a fifth source {@code ObservableSource}
4914 * @param zipper
4915 * a function that, when applied to an item emitted by each of the {@code ObservableSource}s, results in
4916 * an item that will be emitted by the resulting {@code Observable}
4917 * @return the new {@code Observable} instance
4918 * @throws NullPointerException if {@code source1}, {@code source2}, {@code source3},
4919 * {@code source4}, {@code source5} or {@code zipper} is {@code null}
4920 * @see <a href="http://reactivex.io/documentation/operators/zip.html">ReactiveX operators documentation: Zip</a>
4921 */
4922 @CheckReturnValue
4923 @SchedulerSupport(SchedulerSupport.NONE)
4924 @NonNull
4925 public static <@NonNull T1, @NonNull T2, @NonNull T3, @NonNull T4, @NonNull T5, @NonNull R> Observable<R> zip(
4926 @NonNull ObservableSource<? extends T1> source1, @NonNull ObservableSource<? extends T2> source2, @NonNull ObservableSource<? extends T3> source3,
4927 @NonNull ObservableSource<? extends T4> source4, @NonNull ObservableSource<? extends T5> source5,
4928 @NonNull Function5<? super T1, ? super T2, ? super T3, ? super T4, ? super T5, ? extends R> zipper) {
4929 Objects.requireNonNull(source1, "source1 is null");
4930 Objects.requireNonNull(source2, "source2 is null");
4931 Objects.requireNonNull(source3, "source3 is null");
4932 Objects.requireNonNull(source4, "source4 is null");
4933 Objects.requireNonNull(source5, "source5 is null");
4934 Objects.requireNonNull(zipper, "zipper is null");
4935 return zipArray(Functions.toFunction(zipper), false, bufferSize(), source1, source2, source3, source4, source5);
4936 }
4937
4938 /**
4939 * Returns an {@code Observable} that emits the results of a specified combiner function applied to combinations of
4940 * six items emitted, in sequence, by six other {@link ObservableSource}s.
4941 * <p>
4942 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/zip.v3.png" alt="">
4943 * <p>
4944 * {@code zip} applies this function in strict sequence, so the first item emitted by the resulting {@code Observable}
4945 * will be the result of the function applied to the first item emitted by each source {@code ObservableSource}, the
4946 * second item emitted by the resulting {@code Observable} will be the result of the function applied to the second item
4947 * emitted by each of those {@code ObservableSource}s, and so forth.
4948 * <p>
4949 * The resulting {@code Observable<R>} returned from {@code zip} will invoke {@link Observer#onNext onNext}
4950 * as many times as the number of {@code onNext} invocations of the {@code ObservableSource} that emits the fewest
4951 * items.
4952 * <p>
4953 * The operator subscribes to its sources in order they are specified and completes eagerly if
4954 * one of the sources is shorter than the rest while disposing the other sources. Therefore, it
4955 * is possible those other sources will never be able to run to completion (and thus not calling
4956 * {@code doOnComplete()}). This can also happen if the sources are exactly the same length; if
4957 * source A completes and B has been consumed and is about to complete, the operator detects A won't
4958 * be sending further values and it will dispose B immediately. For example:
4959 * <pre><code>zip(range(1, 5).doOnComplete(action1), range(6, 5).doOnComplete(action2), ..., (a, b, c, d, e, f) -&gt; a + b)</code></pre>
4960 * {@code action1} will be called but {@code action2} won't.
4961 * <br>To work around this termination property,
4962 * use {@link #doOnDispose(Action)} as well or use {@code using()} to do cleanup in case of completion
4963 * or a dispose() call.
4964 * <dl>
4965 * <dt><b>Scheduler:</b></dt>
4966 * <dd>{@code zip} does not operate by default on a particular {@link Scheduler}.</dd>
4967 * </dl>
4968 *
4969 * @param <T1> the value type of the first source
4970 * @param <T2> the value type of the second source
4971 * @param <T3> the value type of the third source
4972 * @param <T4> the value type of the fourth source
4973 * @param <T5> the value type of the fifth source
4974 * @param <T6> the value type of the sixth source
4975 * @param <R> the zipped result type
4976 * @param source1
4977 * the first source {@code ObservableSource}
4978 * @param source2
4979 * a second source {@code ObservableSource}
4980 * @param source3
4981 * a third source {@code ObservableSource}
4982 * @param source4
4983 * a fourth source {@code ObservableSource}
4984 * @param source5
4985 * a fifth source {@code ObservableSource}
4986 * @param source6
4987 * a sixth source {@code ObservableSource}
4988 * @param zipper
4989 * a function that, when applied to an item emitted by each of the {@code ObservableSource}s, results in
4990 * an item that will be emitted by the resulting {@code Observable}
4991 * @return the new {@code Observable} instance
4992 * @throws NullPointerException if {@code source1}, {@code source2}, {@code source3},
4993 * {@code source4}, {@code source5}, {@code source6} or {@code zipper} is {@code null}
4994 * @see <a href="http://reactivex.io/documentation/operators/zip.html">ReactiveX operators documentation: Zip</a>
4995 */
4996 @CheckReturnValue
4997 @SchedulerSupport(SchedulerSupport.NONE)
4998 @NonNull
4999 public static <@NonNull T1, @NonNull T2, @NonNull T3, @NonNull T4, @NonNull T5, @NonNull T6, @NonNull R> Observable<R> zip(
5000 @NonNull ObservableSource<? extends T1> source1, @NonNull ObservableSource<? extends T2> source2, @NonNull ObservableSource<? extends T3> source3,
5001 @NonNull ObservableSource<? extends T4> source4, @NonNull ObservableSource<? extends T5> source5, @NonNull ObservableSource<? extends T6> source6,
5002 @NonNull Function6<? super T1, ? super T2, ? super T3, ? super T4, ? super T5, ? super T6, ? extends R> zipper) {
5003 Objects.requireNonNull(source1, "source1 is null");
5004 Objects.requireNonNull(source2, "source2 is null");
5005 Objects.requireNonNull(source3, "source3 is null");
5006 Objects.requireNonNull(source4, "source4 is null");
5007 Objects.requireNonNull(source5, "source5 is null");
5008 Objects.requireNonNull(source6, "source6 is null");
5009 Objects.requireNonNull(zipper, "zipper is null");
5010 return zipArray(Functions.toFunction(zipper), false, bufferSize(), source1, source2, source3, source4, source5, source6);
5011 }
5012
5013 /**
5014 * Returns an {@code Observable} that emits the results of a specified combiner function applied to combinations of
5015 * seven items emitted, in sequence, by seven other {@link ObservableSource}s.
5016 * <p>
5017 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/zip.v3.png" alt="">
5018 * <p>
5019 * {@code zip} applies this function in strict sequence, so the first item emitted by the resulting {@code Observable}
5020 * will be the result of the function applied to the first item emitted by each source {@code ObservableSource}, the
5021 * second item emitted by the resulting {@code Observable} will be the result of the function applied to the second item
5022 * emitted by each of those {@code ObservableSource}s, and so forth.
5023 * <p>
5024 * The resulting {@code Observable<R>} returned from {@code zip} will invoke {@link Observer#onNext onNext}
5025 * as many times as the number of {@code onNext} invocations of the {@code ObservableSource} that emits the fewest
5026 * items.
5027 * <p>
5028 * The operator subscribes to its sources in order they are specified and completes eagerly if
5029 * one of the sources is shorter than the rest while disposing the other sources. Therefore, it
5030 * is possible those other sources will never be able to run to completion (and thus not calling
5031 * {@code doOnComplete()}). This can also happen if the sources are exactly the same length; if
5032 * source A completes and B has been consumed and is about to complete, the operator detects A won't
5033 * be sending further values and it will dispose B immediately. For example:
5034 * <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>
5035 * {@code action1} will be called but {@code action2} won't.
5036 * <br>To work around this termination property,
5037 * use {@link #doOnDispose(Action)} as well or use {@code using()} to do cleanup in case of completion
5038 * or a dispose() call.
5039 * <dl>
5040 * <dt><b>Scheduler:</b></dt>
5041 * <dd>{@code zip} does not operate by default on a particular {@link Scheduler}.</dd>
5042 * </dl>
5043 *
5044 * @param <T1> the value type of the first source
5045 * @param <T2> the value type of the second source
5046 * @param <T3> the value type of the third source
5047 * @param <T4> the value type of the fourth source
5048 * @param <T5> the value type of the fifth source
5049 * @param <T6> the value type of the sixth source
5050 * @param <T7> the value type of the seventh source
5051 * @param <R> the zipped result type
5052 * @param source1
5053 * the first source {@code ObservableSource}
5054 * @param source2
5055 * a second source {@code ObservableSource}
5056 * @param source3
5057 * a third source {@code ObservableSource}
5058 * @param source4
5059 * a fourth source {@code ObservableSource}
5060 * @param source5
5061 * a fifth source {@code ObservableSource}
5062 * @param source6
5063 * a sixth source {@code ObservableSource}
5064 * @param source7
5065 * a seventh source {@code ObservableSource}
5066 * @param zipper
5067 * a function that, when applied to an item emitted by each of the {@code ObservableSource}s, results in
5068 * an item that will be emitted by the resulting {@code Observable}
5069 * @return the new {@code Observable} instance
5070 * @throws NullPointerException if {@code source1}, {@code source2}, {@code source3},
5071 * {@code source4}, {@code source5}, {@code source6},
5072 * {@code source7} or {@code zipper} is {@code null}
5073 * @see <a href="http://reactivex.io/documentation/operators/zip.html">ReactiveX operators documentation: Zip</a>
5074 */
5075 @CheckReturnValue
5076 @SchedulerSupport(SchedulerSupport.NONE)
5077 @NonNull
5078 public static <@NonNull T1, @NonNull T2, @NonNull T3, @NonNull T4, @NonNull T5, @NonNull T6, @NonNull T7, @NonNull R> Observable<R> zip(
5079 @NonNull ObservableSource<? extends T1> source1, @NonNull ObservableSource<? extends T2> source2, @NonNull ObservableSource<? extends T3> source3,
5080 @NonNull ObservableSource<? extends T4> source4, @NonNull ObservableSource<? extends T5> source5, @NonNull ObservableSource<? extends T6> source6,
5081 @NonNull ObservableSource<? extends T7> source7,
5082 @NonNull Function7<? super T1, ? super T2, ? super T3, ? super T4, ? super T5, ? super T6, ? super T7, ? extends R> zipper) {
5083 Objects.requireNonNull(source1, "source1 is null");
5084 Objects.requireNonNull(source2, "source2 is null");
5085 Objects.requireNonNull(source3, "source3 is null");
5086 Objects.requireNonNull(source4, "source4 is null");
5087 Objects.requireNonNull(source5, "source5 is null");
5088 Objects.requireNonNull(source6, "source6 is null");
5089 Objects.requireNonNull(source7, "source7 is null");
5090 Objects.requireNonNull(zipper, "zipper is null");
5091 return zipArray(Functions.toFunction(zipper), false, bufferSize(), source1, source2, source3, source4, source5, source6, source7);
5092 }
5093
5094 /**
5095 * Returns an {@code Observable} that emits the results of a specified combiner function applied to combinations of
5096 * eight items emitted, in sequence, by eight other {@link ObservableSource}s.
5097 * <p>
5098 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/zip.v3.png" alt="">
5099 * <p>
5100 * {@code zip} applies this function in strict sequence, so the first item emitted by the resulting {@code Observable}
5101 * will be the result of the function applied to the first item emitted by each source {@code ObservableSource}, the
5102 * second item emitted by the resulting {@code Observable} will be the result of the function applied to the second item
5103 * emitted by each of those {@code ObservableSource}s, and so forth.
5104 * <p>
5105 * The resulting {@code Observable<R>} returned from {@code zip} will invoke {@link Observer#onNext onNext}
5106 * as many times as the number of {@code onNext} invocations of the {@code ObservableSource} that emits the fewest
5107 * items.
5108 * <p>
5109 * The operator subscribes to its sources in order they are specified and completes eagerly if
5110 * one of the sources is shorter than the rest while disposing the other sources. Therefore, it
5111 * is possible those other sources will never be able to run to completion (and thus not calling
5112 * {@code doOnComplete()}). This can also happen if the sources are exactly the same length; if
5113 * source A completes and B has been consumed and is about to complete, the operator detects A won't
5114 * be sending further values and it will dispose B immediately. For example:
5115 * <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>
5116 * {@code action1} will be called but {@code action2} won't.
5117 * <br>To work around this termination property,
5118 * use {@link #doOnDispose(Action)} as well or use {@code using()} to do cleanup in case of completion
5119 * or a dispose() call.
5120 * <dl>
5121 * <dt><b>Scheduler:</b></dt>
5122 * <dd>{@code zip} does not operate by default on a particular {@link Scheduler}.</dd>
5123 * </dl>
5124 *
5125 * @param <T1> the value type of the first source
5126 * @param <T2> the value type of the second source
5127 * @param <T3> the value type of the third source
5128 * @param <T4> the value type of the fourth source
5129 * @param <T5> the value type of the fifth source
5130 * @param <T6> the value type of the sixth source
5131 * @param <T7> the value type of the seventh source
5132 * @param <T8> the value type of the eighth source
5133 * @param <R> the zipped result type
5134 * @param source1
5135 * the first source {@code ObservableSource}
5136 * @param source2
5137 * a second source {@code ObservableSource}
5138 * @param source3
5139 * a third source {@code ObservableSource}
5140 * @param source4
5141 * a fourth source {@code ObservableSource}
5142 * @param source5
5143 * a fifth source {@code ObservableSource}
5144 * @param source6
5145 * a sixth source {@code ObservableSource}
5146 * @param source7
5147 * a seventh source {@code ObservableSource}
5148 * @param source8
5149 * an eighth source {@code ObservableSource}
5150 * @param zipper
5151 * a function that, when applied to an item emitted by each of the {@code ObservableSource}s, results in
5152 * an item that will be emitted by the resulting {@code Observable}
5153 * @return the new {@code Observable} instance
5154 * @throws NullPointerException if {@code source1}, {@code source2}, {@code source3},
5155 * {@code source4}, {@code source5}, {@code source6},
5156 * {@code source7}, {@code source8} or {@code zipper} is {@code null}
5157 * @see <a href="http://reactivex.io/documentation/operators/zip.html">ReactiveX operators documentation: Zip</a>
5158 */
5159 @CheckReturnValue
5160 @SchedulerSupport(SchedulerSupport.NONE)
5161 @NonNull
5162 public static <@NonNull T1, @NonNull T2, @NonNull T3, @NonNull T4, @NonNull T5, @NonNull T6, @NonNull T7, @NonNull T8, @NonNull R> Observable<R> zip(
5163 @NonNull ObservableSource<? extends T1> source1, @NonNull ObservableSource<? extends T2> source2, @NonNull ObservableSource<? extends T3> source3,
5164 @NonNull ObservableSource<? extends T4> source4, @NonNull ObservableSource<? extends T5> source5, @NonNull ObservableSource<? extends T6> source6,
5165 @NonNull ObservableSource<? extends T7> source7, @NonNull ObservableSource<? extends T8> source8,
5166 @NonNull Function8<? super T1, ? super T2, ? super T3, ? super T4, ? super T5, ? super T6, ? super T7, ? super T8, ? extends R> zipper) {
5167 Objects.requireNonNull(source1, "source1 is null");
5168 Objects.requireNonNull(source2, "source2 is null");
5169 Objects.requireNonNull(source3, "source3 is null");
5170 Objects.requireNonNull(source4, "source4 is null");
5171 Objects.requireNonNull(source5, "source5 is null");
5172 Objects.requireNonNull(source6, "source6 is null");
5173 Objects.requireNonNull(source7, "source7 is null");
5174 Objects.requireNonNull(source8, "source8 is null");
5175 Objects.requireNonNull(zipper, "zipper is null");
5176 return zipArray(Functions.toFunction(zipper), false, bufferSize(), source1, source2, source3, source4, source5, source6, source7, source8);
5177 }
5178
5179 /**
5180 * Returns an {@code Observable} that emits the results of a specified combiner function applied to combinations of
5181 * nine items emitted, in sequence, by nine other {@link ObservableSource}s.
5182 * <p>
5183 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/zip.v3.png" alt="">
5184 * <p>
5185 * {@code zip} applies this function in strict sequence, so the first item emitted by the resulting {@code Observable}
5186 * will be the result of the function applied to the first item emitted by each source {@code ObservableSource}, the
5187 * second item emitted by the resulting {@code Observable} will be the result of the function applied to the second item
5188 * emitted by each of those {@code ObservableSource}s, and so forth.
5189 * <p>
5190 * The resulting {@code Observable<R>} returned from {@code zip} will invoke {@link Observer#onNext onNext}
5191 * as many times as the number of {@code onNext} invocations of the {@code ObservableSource} that emits the fewest
5192 * items.
5193 * <p>
5194 * The operator subscribes to its sources in order they are specified and completes eagerly if
5195 * one of the sources is shorter than the rest while disposing the other sources. Therefore, it
5196 * is possible those other sources will never be able to run to completion (and thus not calling
5197 * {@code doOnComplete()}). This can also happen if the sources are exactly the same length; if
5198 * source A completes and B has been consumed and is about to complete, the operator detects A won't
5199 * be sending further values and it will dispose B immediately. For example:
5200 * <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>
5201 * {@code action1} will be called but {@code action2} won't.
5202 * <br>To work around this termination property,
5203 * use {@link #doOnDispose(Action)} as well or use {@code using()} to do cleanup in case of completion
5204 * or a dispose() call.
5205 * <dl>
5206 * <dt><b>Scheduler:</b></dt>
5207 * <dd>{@code zip} does not operate by default on a particular {@link Scheduler}.</dd>
5208 * </dl>
5209 *
5210 * @param <T1> the value type of the first source
5211 * @param <T2> the value type of the second source
5212 * @param <T3> the value type of the third source
5213 * @param <T4> the value type of the fourth source
5214 * @param <T5> the value type of the fifth source
5215 * @param <T6> the value type of the sixth source
5216 * @param <T7> the value type of the seventh source
5217 * @param <T8> the value type of the eighth source
5218 * @param <T9> the value type of the ninth source
5219 * @param <R> the zipped result type
5220 * @param source1
5221 * the first source {@code ObservableSource}
5222 * @param source2
5223 * a second source {@code ObservableSource}
5224 * @param source3
5225 * a third source {@code ObservableSource}
5226 * @param source4
5227 * a fourth source {@code ObservableSource}
5228 * @param source5
5229 * a fifth source {@code ObservableSource}
5230 * @param source6
5231 * a sixth source {@code ObservableSource}
5232 * @param source7
5233 * a seventh source {@code ObservableSource}
5234 * @param source8
5235 * an eighth source {@code ObservableSource}
5236 * @param source9
5237 * a ninth source {@code ObservableSource}
5238 * @param zipper
5239 * a function that, when applied to an item emitted by each of the {@code ObservableSource}s, results in
5240 * an item that will be emitted by the resulting {@code Observable}
5241 * @return the new {@code Observable} instance
5242 * @throws NullPointerException if {@code source1}, {@code source2}, {@code source3},
5243 * {@code source4}, {@code source5}, {@code source6},
5244 * {@code source7}, {@code source8}, {@code source9} or {@code zipper} is {@code null}
5245 * @see <a href="http://reactivex.io/documentation/operators/zip.html">ReactiveX operators documentation: Zip</a>
5246 */
5247 @CheckReturnValue
5248 @SchedulerSupport(SchedulerSupport.NONE)
5249 @NonNull
5250 public static <@NonNull T1, @NonNull T2, @NonNull T3, @NonNull T4, @NonNull T5, @NonNull T6, @NonNull T7, @NonNull T8, @NonNull T9, @NonNull R> Observable<R> zip(
5251 @NonNull ObservableSource<? extends T1> source1, @NonNull ObservableSource<? extends T2> source2, @NonNull ObservableSource<? extends T3> source3,
5252 @NonNull ObservableSource<? extends T4> source4, @NonNull ObservableSource<? extends T5> source5, @NonNull ObservableSource<? extends T6> source6,
5253 @NonNull ObservableSource<? extends T7> source7, @NonNull ObservableSource<? extends T8> source8, @NonNull ObservableSource<? extends T9> source9,
5254 @NonNull Function9<? super T1, ? super T2, ? super T3, ? super T4, ? super T5, ? super T6, ? super T7, ? super T8, ? super T9, ? extends R> zipper) {
5255 Objects.requireNonNull(source1, "source1 is null");
5256 Objects.requireNonNull(source2, "source2 is null");
5257 Objects.requireNonNull(source3, "source3 is null");
5258 Objects.requireNonNull(source4, "source4 is null");
5259 Objects.requireNonNull(source5, "source5 is null");
5260 Objects.requireNonNull(source6, "source6 is null");
5261 Objects.requireNonNull(source7, "source7 is null");
5262 Objects.requireNonNull(source8, "source8 is null");
5263 Objects.requireNonNull(source9, "source9 is null");
5264 Objects.requireNonNull(zipper, "zipper is null");
5265 return zipArray(Functions.toFunction(zipper), false, bufferSize(), source1, source2, source3, source4, source5, source6, source7, source8, source9);
5266 }
5267
5268 /**
5269 * Returns an {@code Observable} that emits the results of a specified combiner function applied to combinations of
5270 * items emitted, in sequence, by an array of other {@link ObservableSource}s.
5271 * <p>
5272 * {@code zip} applies this function in strict sequence, so the first item emitted by the resulting {@code Observable}
5273 * will be the result of the function applied to the first item emitted by each of the {@code ObservableSource}s;
5274 * the second item emitted by the resulting {@code Observable} will be the result of the function applied to the second
5275 * item emitted by each of those {@code ObservableSource}s; and so forth.
5276 * <p>
5277 * The resulting {@code Observable<R>} returned from {@code zip} will invoke {@code onNext} as many times as
5278 * the number of {@code onNext} invocations of the {@code ObservableSource} that emits the fewest items.
5279 * <p>
5280 * The operator subscribes to its sources in order they are specified and completes eagerly if
5281 * one of the sources is shorter than the rest while disposing the other sources. Therefore, it
5282 * is possible those other sources will never be able to run to completion (and thus not calling
5283 * {@code doOnComplete()}). This can also happen if the sources are exactly the same length; if
5284 * source A completes and B has been consumed and is about to complete, the operator detects A won't
5285 * be sending further values and it will dispose B immediately. For example:
5286 * <pre><code>zip(new ObservableSource[]{range(1, 5).doOnComplete(action1), range(6, 5).doOnComplete(action2)}, (a) -&gt;
5287 * a)</code></pre>
5288 * {@code action1} will be called but {@code action2} won't.
5289 * <br>To work around this termination property,
5290 * use {@link #doOnDispose(Action)} as well or use {@code using()} to do cleanup in case of completion
5291 * or a dispose() call.
5292 * <p>
5293 * Note on method signature: since Java doesn't allow creating a generic array with {@code new T[]}, the
5294 * implementation of this operator has to create an {@code Object[]} instead. Unfortunately, a
5295 * {@code Function<Integer[], R>} passed to the method would trigger a {@link ClassCastException}.
5296 *
5297 * <p>
5298 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/zipArray.o.v3.png" alt="">
5299 * <dl>
5300 * <dt><b>Scheduler:</b></dt>
5301 * <dd>{@code zipArray} does not operate by default on a particular {@link Scheduler}.</dd>
5302 * </dl>
5303 *
5304 * @param <T> the common element type
5305 * @param <R> the result type
5306 * @param sources
5307 * an array of source {@code ObservableSource}s
5308 * @param zipper
5309 * a function that, when applied to an item emitted by each of the {@code ObservableSource}s, results in
5310 * an item that will be emitted by the resulting {@code Observable}
5311 * @param delayError
5312 * delay errors signaled by any of the {@code ObservableSource} until all {@code ObservableSource}s terminate
5313 * @param bufferSize
5314 * the number of elements expected from each source {@code ObservableSource} to be buffered
5315 * @return the new {@code Observable} instance
5316 * @throws NullPointerException if {@code sources} or {@code zipper} is {@code null}
5317 * @throws IllegalArgumentException if {@code bufferSize} is non-positive
5318 * @see <a href="http://reactivex.io/documentation/operators/zip.html">ReactiveX operators documentation: Zip</a>
5319 */
5320 @CheckReturnValue
5321 @SchedulerSupport(SchedulerSupport.NONE)
5322 @SafeVarargs
5323 @NonNull
5324 public static <@NonNull T, @NonNull R> Observable<R> zipArray(
5325 @NonNull Function<? super Object[], ? extends R> zipper,
5326 boolean delayError, int bufferSize,
5327 @NonNull ObservableSource<? extends T>... sources) {
5328 Objects.requireNonNull(sources, "sources is null");
5329 if (sources.length == 0) {
5330 return empty();
5331 }
5332 Objects.requireNonNull(zipper, "zipper is null");
5333 ObjectHelper.verifyPositive(bufferSize, "bufferSize");
5334 return RxJavaPlugins.onAssembly(new ObservableZip<>(sources, null, zipper, bufferSize, delayError));
5335 }
5336
5337 // ***************************************************************************************************
5338 // Instance operators
5339 // ***************************************************************************************************
5340
5341 /**
5342 * Returns a {@link Single} that emits a {@link Boolean} that indicates whether all of the items emitted by the current
5343 * {@code Observable} satisfy a condition.
5344 * <p>
5345 * <img width="640" height="265" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/all.o.png" alt="">
5346 * <dl>
5347 * <dt><b>Scheduler:</b></dt>
5348 * <dd>{@code all} does not operate by default on a particular {@link Scheduler}.</dd>
5349 * </dl>
5350 *
5351 * @param predicate
5352 * a function that evaluates an item and returns a {@code Boolean}
5353 * @return the new {@code Single} instance
5354 * @throws NullPointerException if {@code predicate} is {@code null}
5355 * @see <a href="http://reactivex.io/documentation/operators/all.html">ReactiveX operators documentation: All</a>
5356 */
5357 @CheckReturnValue
5358 @SchedulerSupport(SchedulerSupport.NONE)
5359 @NonNull
5360 public final Single<Boolean> all(@NonNull Predicate<? super T> predicate) {
5361 Objects.requireNonNull(predicate, "predicate is null");
5362 return RxJavaPlugins.onAssembly(new ObservableAllSingle<>(this, predicate));
5363 }
5364
5365 /**
5366 * Mirrors the current {@code Observable} or the other {@link ObservableSource} provided of which the first either emits an item or sends a termination
5367 * notification.
5368 * <p>
5369 * <img width="640" height="448" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Observable.ambWith.png" alt="">
5370 * <p>
5371 * When the current {@code Observable} signals an item or terminates first, the subscription to the other
5372 * {@code ObservableSource} is disposed. If the other {@code ObservableSource} signals an item or terminates first,
5373 * the subscription to the current {@code Observable} is disposed.
5374 * <dl>
5375 * <dt><b>Scheduler:</b></dt>
5376 * <dd>{@code ambWith} does not operate by default on a particular {@link Scheduler}.</dd>
5377 * <dt><b>Error handling:</b></dt>
5378 * <dd>
5379 * If the losing {@code ObservableSource} signals an error, the error is routed to the global
5380 * error handler via {@link RxJavaPlugins#onError(Throwable)}.
5381 * </dd>
5382 * </dl>
5383 *
5384 * @param other
5385 * an {@code ObservableSource} competing to react first. A subscription to this provided source will occur after
5386 * subscribing to the current source.
5387 * @return the new {@code Observable} instance
5388 * @throws NullPointerException if {@code other} is {@code null}
5389 * @see <a href="http://reactivex.io/documentation/operators/amb.html">ReactiveX operators documentation: Amb</a>
5390 */
5391 @CheckReturnValue
5392 @SchedulerSupport(SchedulerSupport.NONE)
5393 @NonNull
5394 public final Observable<T> ambWith(@NonNull ObservableSource<? extends T> other) {
5395 Objects.requireNonNull(other, "other is null");
5396 return ambArray(this, other);
5397 }
5398
5399 /**
5400 * Returns a {@link Single} that emits {@code true} if any item emitted by the current {@code Observable} satisfies a
5401 * specified condition, otherwise {@code false}. <em>Note:</em> this always emits {@code false} if the
5402 * current {@code Observable} is empty.
5403 * <p>
5404 * <img width="640" height="320" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/any.2.v3.png" alt="">
5405 * <p>
5406 * In Rx.Net this is the {@code any} {@link Observer} but we renamed it in RxJava to better match Java naming
5407 * idioms.
5408 * <dl>
5409 * <dt><b>Scheduler:</b></dt>
5410 * <dd>{@code any} does not operate by default on a particular {@link Scheduler}.</dd>
5411 * </dl>
5412 *
5413 * @param predicate
5414 * the condition to test items emitted by the current {@code Observable}
5415 * @return the new {@code Single} instance
5416 * @throws NullPointerException if {@code predicate} is {@code null}
5417 * @see <a href="http://reactivex.io/documentation/operators/contains.html">ReactiveX operators documentation: Contains</a>
5418 */
5419 @CheckReturnValue
5420 @SchedulerSupport(SchedulerSupport.NONE)
5421 @NonNull
5422 public final Single<Boolean> any(@NonNull Predicate<? super T> predicate) {
5423 Objects.requireNonNull(predicate, "predicate is null");
5424 return RxJavaPlugins.onAssembly(new ObservableAnySingle<>(this, predicate));
5425 }
5426
5427 /**
5428 * Returns the first item emitted by the current {@code Observable}, or throws
5429 * {@link NoSuchElementException} if it emits no items.
5430 * <p>
5431 * <img width="640" height="413" src="https://github.com/ReactiveX/RxJava/wiki/images/rx-operators/blockingFirst.o.png" alt="">
5432 * <dl>
5433 * <dt><b>Scheduler:</b></dt>
5434 * <dd>{@code blockingFirst} does not operate by default on a particular {@link Scheduler}.</dd>
5435 * <dt><b>Error handling:</b></dt>
5436 * <dd>If the source signals an error, the operator wraps a checked {@link Exception}
5437 * into {@link RuntimeException} and throws that. Otherwise, {@code RuntimeException}s and
5438 * {@link Error}s are rethrown as they are.</dd>
5439 * </dl>
5440 *
5441 * @return the first item emitted by the current {@code Observable}
5442 * @throws NoSuchElementException
5443 * if the current {@code Observable} emits no items
5444 * @see <a href="http://reactivex.io/documentation/operators/first.html">ReactiveX documentation: First</a>
5445 */
5446 @CheckReturnValue
5447 @SchedulerSupport(SchedulerSupport.NONE)
5448 @NonNull
5449 public final T blockingFirst() {
5450 BlockingFirstObserver<T> observer = new BlockingFirstObserver<>();
5451 subscribe(observer);
5452 T v = observer.blockingGet();
5453 if (v != null) {
5454 return v;
5455 }
5456 throw new NoSuchElementException();
5457 }
5458
5459 /**
5460 * Returns the first item emitted by the current {@code Observable}, or a default value if it emits no
5461 * items.
5462 * <p>
5463 * <img width="640" height="329" src="https://github.com/ReactiveX/RxJava/wiki/images/rx-operators/blockingFirst.o.default.png" alt="">
5464 * <dl>
5465 * <dt><b>Scheduler:</b></dt>
5466 * <dd>{@code blockingFirst} does not operate by default on a particular {@link Scheduler}.</dd>
5467 * <dt><b>Error handling:</b></dt>
5468 * <dd>If the source signals an error, the operator wraps a checked {@link Exception}
5469 * into {@link RuntimeException} and throws that. Otherwise, {@code RuntimeException}s and
5470 * {@link Error}s are rethrown as they are.</dd>
5471 * </dl>
5472 *
5473 * @param defaultItem
5474 * a default value to return if the current {@code Observable} emits no items
5475 * @return the first item emitted by the current {@code Observable}, or the default value if it emits no
5476 * items
5477 * @throws NullPointerException if {@code defaultItem} is {@code null}
5478 * @see <a href="http://reactivex.io/documentation/operators/first.html">ReactiveX documentation: First</a>
5479 */
5480 @CheckReturnValue
5481 @SchedulerSupport(SchedulerSupport.NONE)
5482 @NonNull
5483 public final T blockingFirst(@NonNull T defaultItem) {
5484 Objects.requireNonNull(defaultItem, "defaultItem is null");
5485 BlockingFirstObserver<T> observer = new BlockingFirstObserver<>();
5486 subscribe(observer);
5487 T v = observer.blockingGet();
5488 return v != null ? v : defaultItem;
5489 }
5490
5491 /**
5492 * Consumes the current {@code Observable} in a blocking fashion and invokes the given
5493 * {@link Consumer} with each upstream item on the <em>current thread</em> until the
5494 * upstream terminates.
5495 * <p>
5496 * <img width="640" height="330" src="https://github.com/ReactiveX/RxJava/wiki/images/rx-operators/blockingForEach.o.v3.png" alt="">
5497 * <p>
5498 * <em>Note:</em> the method will only return if the upstream terminates or the current
5499 * thread is interrupted.
5500 * <p>
5501 * This method executes the {@code Consumer} on the current thread while
5502 * {@link #subscribe(Consumer)} executes the consumer on the original caller thread of the
5503 * sequence.
5504 * <dl>
5505 * <dt><b>Scheduler:</b></dt>
5506 * <dd>{@code blockingForEach} does not operate by default on a particular {@link Scheduler}.</dd>
5507 * <dt><b>Error handling:</b></dt>
5508 * <dd>If the source signals an error, the operator wraps a checked {@link Exception}
5509 * into {@link RuntimeException} and throws that. Otherwise, {@code RuntimeException}s and
5510 * {@link Error}s are rethrown as they are.</dd>
5511 * </dl>
5512 *
5513 * @param onNext
5514 * the {@code Consumer} to invoke for each item emitted by the {@code Observable}
5515 * @throws NullPointerException if {@code onNext} is {@code null}
5516 * @throws RuntimeException
5517 * if an error occurs
5518 * @see <a href="http://reactivex.io/documentation/operators/subscribe.html">ReactiveX documentation: Subscribe</a>
5519 * @see #subscribe(Consumer)
5520 * @see #blockingForEach(Consumer, int)
5521 */
5522 @SchedulerSupport(SchedulerSupport.NONE)
5523 public final void blockingForEach(@NonNull Consumer<? super T> onNext) {
5524 blockingForEach(onNext, bufferSize());
5525 }
5526
5527 /**
5528 * Consumes the current {@code Observable} in a blocking fashion and invokes the given
5529 * {@link Consumer} with each upstream item on the <em>current thread</em> until the
5530 * upstream terminates.
5531 * <p>
5532 * <img width="640" height="330" src="https://github.com/ReactiveX/RxJava/wiki/images/rx-operators/blockingForEach.o.v3.png" alt="">
5533 * <p>
5534 * <em>Note:</em> the method will only return if the upstream terminates or the current
5535 * thread is interrupted.
5536 * <p>
5537 * This method executes the {@code Consumer} on the current thread while
5538 * {@link #subscribe(Consumer)} executes the consumer on the original caller thread of the
5539 * sequence.
5540 * <dl>
5541 * <dt><b>Scheduler:</b></dt>
5542 * <dd>{@code blockingForEach} does not operate by default on a particular {@link Scheduler}.</dd>
5543 * <dt><b>Error handling:</b></dt>
5544 * <dd>If the source signals an error, the operator wraps a checked {@link Exception}
5545 * into {@link RuntimeException} and throws that. Otherwise, {@code RuntimeException}s and
5546 * {@link Error}s are rethrown as they are.</dd>
5547 * </dl>
5548 *
5549 * @param onNext
5550 * the {@code Consumer} to invoke for each item emitted by the {@code Observable}
5551 * @param capacityHint
5552 * the number of items expected to be buffered (allows reducing buffer reallocations)
5553 * @throws NullPointerException if {@code onNext} is {@code null}
5554 * @throws IllegalArgumentException if {@code capacityHint} is non-positive
5555 * @throws RuntimeException
5556 * if an error occurs; {@code Error}s and {@code RuntimeException}s are rethrown
5557 * as they are, checked {@code Exception}s are wrapped into {@code RuntimeException}s
5558 * @see <a href="http://reactivex.io/documentation/operators/subscribe.html">ReactiveX documentation: Subscribe</a>
5559 * @see #subscribe(Consumer)
5560 */
5561 @SchedulerSupport(SchedulerSupport.NONE)
5562 public final void blockingForEach(@NonNull Consumer<? super T> onNext, int capacityHint) {
5563 Objects.requireNonNull(onNext, "onNext is null");
5564 Iterator<T> it = blockingIterable(capacityHint).iterator();
5565 while (it.hasNext()) {
5566 try {
5567 onNext.accept(it.next());
5568 } catch (Throwable e) {
5569 Exceptions.throwIfFatal(e);
5570 ((Disposable)it).dispose();
5571 throw ExceptionHelper.wrapOrThrow(e);
5572 }
5573 }
5574 }
5575
5576 /**
5577 * Exposes the current {@code Observable} as an {@link Iterable} which, when iterated,
5578 * subscribes to the current {@code Observable} and blocks
5579 * until the current {@code Observable} emits items or terminates.
5580 * <p>
5581 * <img width="640" height="315" src="https://github.com/ReactiveX/RxJava/wiki/images/rx-operators/blockingIterable.o.v3.png" alt="">
5582 * <dl>
5583 * <dt><b>Scheduler:</b></dt>
5584 * <dd>{@code blockingIterable} does not operate by default on a particular {@link Scheduler}.</dd>
5585 * </dl>
5586 *
5587 * @return the new {@code Iterable} instance
5588 * @see <a href="http://reactivex.io/documentation/operators/to.html">ReactiveX documentation: To</a>
5589 */
5590 @CheckReturnValue
5591 @SchedulerSupport(SchedulerSupport.NONE)
5592 @NonNull
5593 public final Iterable<T> blockingIterable() {
5594 return blockingIterable(bufferSize());
5595 }
5596
5597 /**
5598 * Exposes the current {@code Observable} as an {@link Iterable} which, when iterated,
5599 * subscribes to the current {@code Observable} and blocks
5600 * until the current {@code Observable} emits items or terminates.
5601 * <p>
5602 * <img width="640" height="315" src="https://github.com/ReactiveX/RxJava/wiki/images/rx-operators/blockingIterable.o.v3.png" alt="">
5603 * <dl>
5604 * <dt><b>Scheduler:</b></dt>
5605 * <dd>{@code blockingIterable} does not operate by default on a particular {@link Scheduler}.</dd>
5606 * </dl>
5607 *
5608 * @param capacityHint the expected number of items to be buffered
5609 * @return the new {@code Iterable} instance
5610 * @throws IllegalArgumentException if {@code capacityHint} is non-positive
5611 * @see <a href="http://reactivex.io/documentation/operators/to.html">ReactiveX documentation: To</a>
5612 */
5613 @CheckReturnValue
5614 @SchedulerSupport(SchedulerSupport.NONE)
5615 @NonNull
5616 public final Iterable<T> blockingIterable(int capacityHint) {
5617 ObjectHelper.verifyPositive(capacityHint, "capacityHint");
5618 return new BlockingObservableIterable<>(this, capacityHint);
5619 }
5620
5621 /**
5622 * Returns the last item emitted by the current {@code Observable}, or throws
5623 * {@link NoSuchElementException} if the current {@code Observable} emits no items.
5624 * <p>
5625 * <img width="640" height="315" src="https://github.com/ReactiveX/RxJava/wiki/images/rx-operators/blockingLast.o.v3.png" alt="">
5626 * <dl>
5627 * <dt><b>Scheduler:</b></dt>
5628 * <dd>{@code blockingLast} does not operate by default on a particular {@link Scheduler}.</dd>
5629 * <dt><b>Error handling:</b></dt>
5630 * <dd>If the source signals an error, the operator wraps a checked {@link Exception}
5631 * into {@link RuntimeException} and throws that. Otherwise, {@code RuntimeException}s and
5632 * {@link Error}s are rethrown as they are.</dd>
5633 * </dl>
5634 *
5635 * @return the last item emitted by the current {@code Observable}
5636 * @throws NoSuchElementException
5637 * if the current {@code Observable} emits no items
5638 * @see <a href="http://reactivex.io/documentation/operators/last.html">ReactiveX documentation: Last</a>
5639 */
5640 @CheckReturnValue
5641 @SchedulerSupport(SchedulerSupport.NONE)
5642 @NonNull
5643 public final T blockingLast() {
5644 BlockingLastObserver<T> observer = new BlockingLastObserver<>();
5645 subscribe(observer);
5646 T v = observer.blockingGet();
5647 if (v != null) {
5648 return v;
5649 }
5650 throw new NoSuchElementException();
5651 }
5652
5653 /**
5654 * Returns the last item emitted by the current {@code Observable}, or a default value if it emits no
5655 * items.
5656 * <p>
5657 * <img width="640" height="310" src="https://github.com/ReactiveX/RxJava/wiki/images/rx-operators/blockingLastDefault.o.v3.png" alt="">
5658 * <dl>
5659 * <dt><b>Scheduler:</b></dt>
5660 * <dd>{@code blockingLast} does not operate by default on a particular {@link Scheduler}.</dd>
5661 * <dt><b>Error handling:</b></dt>
5662 * <dd>If the source signals an error, the operator wraps a checked {@link Exception}
5663 * into {@link RuntimeException} and throws that. Otherwise, {@code RuntimeException}s and
5664 * {@link Error}s are rethrown as they are.</dd>
5665 * </dl>
5666 *
5667 * @param defaultItem
5668 * a default value to return if the current {@code Observable} emits no items
5669 * @return the last item emitted by the {@code Observable}, or the default value if it emits no
5670 * items
5671 * @throws NullPointerException if {@code defaultItem} is {@code null}
5672 * @see <a href="http://reactivex.io/documentation/operators/last.html">ReactiveX documentation: Last</a>
5673 */
5674 @CheckReturnValue
5675 @SchedulerSupport(SchedulerSupport.NONE)
5676 @NonNull
5677 public final T blockingLast(@NonNull T defaultItem) {
5678 Objects.requireNonNull(defaultItem, "defaultItem is null");
5679 BlockingLastObserver<T> observer = new BlockingLastObserver<>();
5680 subscribe(observer);
5681 T v = observer.blockingGet();
5682 return v != null ? v : defaultItem;
5683 }
5684
5685 /**
5686 * Returns an {@link Iterable} that returns the latest item emitted by the current {@code Observable},
5687 * waiting if necessary for one to become available.
5688 * <p>
5689 * <img width="640" height="350" src="https://github.com/ReactiveX/RxJava/wiki/images/rx-operators/blockingLatest.o.png" alt="">
5690 * <p>
5691 * If the current {@code Observable} produces items faster than {@code Iterator.next} takes them,
5692 * {@code onNext} events might be skipped, but {@code onError} or {@code onComplete} events are not.
5693 * <p>
5694 * Note also that an {@code onNext} directly followed by {@code onComplete} might hide the {@code onNext}
5695 * event.
5696 * <dl>
5697 * <dt><b>Scheduler:</b></dt>
5698 * <dd>{@code blockingLatest} does not operate by default on a particular {@link Scheduler}.</dd>
5699 * </dl>
5700 *
5701 * @return the new {@code Iterable} instance
5702 * @see <a href="http://reactivex.io/documentation/operators/first.html">ReactiveX documentation: First</a>
5703 */
5704 @CheckReturnValue
5705 @SchedulerSupport(SchedulerSupport.NONE)
5706 @NonNull
5707 public final Iterable<T> blockingLatest() {
5708 return new BlockingObservableLatest<>(this);
5709 }
5710
5711 /**
5712 * Returns an {@link Iterable} that always returns the item most recently emitted by the current
5713 * {@code Observable}.
5714 * <p>
5715 * <img width="640" height="426" src="https://github.com/ReactiveX/RxJava/wiki/images/rx-operators/blockingMostRecent.o.v3.png" alt="">
5716 * <dl>
5717 * <dt><b>Scheduler:</b></dt>
5718 * <dd>{@code blockingMostRecent} does not operate by default on a particular {@link Scheduler}.</dd>
5719 * </dl>
5720 *
5721 * @param initialItem
5722 * the initial value that the {@code Iterable} sequence will yield if the current
5723 * {@code Observable} has not yet emitted an item
5724 * @return the new {@code Iterable} instance
5725 * @throws NullPointerException if {@code initialItem} is {@code null}
5726 * @see <a href="http://reactivex.io/documentation/operators/first.html">ReactiveX documentation: First</a>
5727 */
5728 @CheckReturnValue
5729 @SchedulerSupport(SchedulerSupport.NONE)
5730 @NonNull
5731 public final Iterable<T> blockingMostRecent(@NonNull T initialItem) {
5732 Objects.requireNonNull(initialItem, "initialItem is null");
5733 return new BlockingObservableMostRecent<>(this, initialItem);
5734 }
5735
5736 /**
5737 * Returns an {@link Iterable} that blocks until the current {@code Observable} emits another item, then
5738 * returns that item.
5739 * <p>
5740 * <img width="640" height="427" src="https://github.com/ReactiveX/RxJava/wiki/images/rx-operators/blockingNext.o.v3.png" alt="">
5741 * <dl>
5742 * <dt><b>Scheduler:</b></dt>
5743 * <dd>{@code blockingNext} does not operate by default on a particular {@link Scheduler}.</dd>
5744 * </dl>
5745 *
5746 * @return the new {@code Iterable} instance
5747 * @see <a href="http://reactivex.io/documentation/operators/takelast.html">ReactiveX documentation: TakeLast</a>
5748 */
5749 @CheckReturnValue
5750 @SchedulerSupport(SchedulerSupport.NONE)
5751 @NonNull
5752 public final Iterable<T> blockingNext() {
5753 return new BlockingObservableNext<>(this);
5754 }
5755
5756 /**
5757 * If the current {@code Observable} completes after emitting a single item, return that item, otherwise
5758 * throw a {@link NoSuchElementException}.
5759 * <p>
5760 * <img width="640" height="315" src="https://github.com/ReactiveX/RxJava/wiki/images/rx-operators/blockingSingle.o.v3.png" alt="">
5761 * <dl>
5762 * <dt><b>Scheduler:</b></dt>
5763 * <dd>{@code blockingSingle} does not operate by default on a particular {@link Scheduler}.</dd>
5764 * <dt><b>Error handling:</b></dt>
5765 * <dd>If the source signals an error, the operator wraps a checked {@link Exception}
5766 * into {@link RuntimeException} and throws that. Otherwise, {@code RuntimeException}s and
5767 * {@link Error}s are rethrown as they are.</dd>
5768 * </dl>
5769 *
5770 * @return the single item emitted by the current {@code Observable}
5771 * @see <a href="http://reactivex.io/documentation/operators/first.html">ReactiveX documentation: First</a>
5772 */
5773 @CheckReturnValue
5774 @SchedulerSupport(SchedulerSupport.NONE)
5775 @NonNull
5776 public final T blockingSingle() {
5777 T v = singleElement().blockingGet();
5778 if (v == null) {
5779 throw new NoSuchElementException();
5780 }
5781 return v;
5782 }
5783
5784 /**
5785 * If the current {@code Observable} completes after emitting a single item, return that item; if it emits
5786 * more than one item, throw an {@link IllegalArgumentException}; if it emits no items, return a default
5787 * value.
5788 * <p>
5789 * <img width="640" height="315" src="https://github.com/ReactiveX/RxJava/wiki/images/rx-operators/blockingSingleDefault.o.v3.png" alt="">
5790 * <dl>
5791 * <dt><b>Scheduler:</b></dt>
5792 * <dd>{@code blockingSingle} does not operate by default on a particular {@link Scheduler}.</dd>
5793 * <dt><b>Error handling:</b></dt>
5794 * <dd>If the source signals an error, the operator wraps a checked {@link Exception}
5795 * into {@link RuntimeException} and throws that. Otherwise, {@code RuntimeException}s and
5796 * {@link Error}s are rethrown as they are.</dd>
5797 * </dl>
5798 *
5799 * @param defaultItem
5800 * a default value to return if the current {@code Observable} emits no items
5801 * @return the single item emitted by the current {@code Observable}, or the default value if it emits no
5802 * items
5803 * @throws NullPointerException if {@code defaultItem} is {@code null}
5804 * @see <a href="http://reactivex.io/documentation/operators/first.html">ReactiveX documentation: First</a>
5805 */
5806 @CheckReturnValue
5807 @SchedulerSupport(SchedulerSupport.NONE)
5808 @NonNull
5809 public final T blockingSingle(@NonNull T defaultItem) {
5810 return single(defaultItem).blockingGet();
5811 }
5812
5813 /**
5814 * Returns a {@link Future} representing the only value emitted by the current {@code Observable}.
5815 * <p>
5816 * <img width="640" height="299" src="https://github.com/ReactiveX/RxJava/wiki/images/rx-operators/toFuture.o.png" alt="">
5817 * <p>
5818 * If the {@code Observable} emits more than one item, {@code Future} will receive an
5819 * {@link IndexOutOfBoundsException}. If the {@code Observable} is empty, {@code Future}
5820 * will receive an {@link NoSuchElementException}. The {@code Observable} source has to terminate in order
5821 * for the returned {@code Future} to terminate as well.
5822 * <p>
5823 * If the {@code Observable} may emit more than one item, use {@code Observable.toList().toFuture()}.
5824 * <dl>
5825 * <dt><b>Scheduler:</b></dt>
5826 * <dd>{@code toFuture} does not operate by default on a particular {@link Scheduler}.</dd>
5827 * </dl>
5828 *
5829 * @return the new {@code Future} instance
5830 * @see <a href="http://reactivex.io/documentation/operators/to.html">ReactiveX documentation: To</a>
5831 * @see #singleOrErrorStage()
5832 */
5833 @CheckReturnValue
5834 @SchedulerSupport(SchedulerSupport.NONE)
5835 @NonNull
5836 public final Future<T> toFuture() {
5837 return subscribeWith(new FutureObserver<>());
5838 }
5839
5840 /**
5841 * Runs the current {@code Observable} to a terminal event, ignoring any values and rethrowing any exception.
5842 * <p>
5843 * <img width="640" height="270" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/blockingSubscribe.o.0.png" alt="">
5844 * <p>
5845 * Note that calling this method will block the caller thread until the upstream terminates
5846 * normally or with an error. Therefore, calling this method from special threads such as the
5847 * Android Main Thread or the Swing Event Dispatch Thread is not recommended.
5848 * <dl>
5849 * <dt><b>Scheduler:</b></dt>
5850 * <dd>{@code blockingSubscribe} does not operate by default on a particular {@link Scheduler}.</dd>
5851 * </dl>
5852 * @since 2.0
5853 * @see #blockingSubscribe(Consumer)
5854 * @see #blockingSubscribe(Consumer, Consumer)
5855 * @see #blockingSubscribe(Consumer, Consumer, Action)
5856 */
5857 @SchedulerSupport(SchedulerSupport.NONE)
5858 public final void blockingSubscribe() {
5859 ObservableBlockingSubscribe.subscribe(this);
5860 }
5861
5862 /**
5863 * Subscribes to the source and calls the given callbacks <strong>on the current thread</strong>.
5864 * <p>
5865 * <img width="640" height="394" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/blockingSubscribe.o.1.png" alt="">
5866 * <p>
5867 * If the {@code Observable} emits an error, it is wrapped into an
5868 * {@link OnErrorNotImplementedException}
5869 * and routed to the {@link RxJavaPlugins#onError(Throwable)} handler.
5870 * Using the overloads {@link #blockingSubscribe(Consumer, Consumer)}
5871 * or {@link #blockingSubscribe(Consumer, Consumer, Action)} instead is recommended.
5872 * <p>
5873 * Note that calling this method will block the caller thread until the upstream terminates
5874 * normally or with an error. Therefore, calling this method from special threads such as the
5875 * Android Main Thread or the Swing Event Dispatch Thread is not recommended.
5876 * <dl>
5877 * <dt><b>Scheduler:</b></dt>
5878 * <dd>{@code blockingSubscribe} does not operate by default on a particular {@link Scheduler}.</dd>
5879 * </dl>
5880 * @param onNext the callback action for each source value
5881 * @throws NullPointerException if {@code onNext} is {@code null}
5882 * @since 2.0
5883 * @see #blockingSubscribe(Consumer, Consumer)
5884 * @see #blockingSubscribe(Consumer, Consumer, Action)
5885 */
5886 @SchedulerSupport(SchedulerSupport.NONE)
5887 public final void blockingSubscribe(@NonNull Consumer<? super T> onNext) {
5888 ObservableBlockingSubscribe.subscribe(this, onNext, Functions.ON_ERROR_MISSING, Functions.EMPTY_ACTION);
5889 }
5890
5891 /**
5892 * Subscribes to the source and calls the given callbacks <strong>on the current thread</strong>.
5893 * <p>
5894 * <img width="640" height="397" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/blockingSubscribe.o.2.png" alt="">
5895 * <p>
5896 * Note that calling this method will block the caller thread until the upstream terminates
5897 * normally or with an error. Therefore, calling this method from special threads such as the
5898 * Android Main Thread or the Swing Event Dispatch Thread is not recommended.
5899 * <dl>
5900 * <dt><b>Scheduler:</b></dt>
5901 * <dd>{@code blockingSubscribe} does not operate by default on a particular {@link Scheduler}.</dd>
5902 * </dl>
5903 * @param onNext the callback action for each source value
5904 * @param onError the callback action for an error event
5905 * @throws NullPointerException if {@code onNext} or {@code onError} is {@code null}
5906 * @since 2.0
5907 * @see #blockingSubscribe(Consumer, Consumer, Action)
5908 */
5909 @SchedulerSupport(SchedulerSupport.NONE)
5910 public final void blockingSubscribe(@NonNull Consumer<? super T> onNext, @NonNull Consumer<? super Throwable> onError) {
5911 ObservableBlockingSubscribe.subscribe(this, onNext, onError, Functions.EMPTY_ACTION);
5912 }
5913
5914 /**
5915 * Subscribes to the source and calls the given callbacks <strong>on the current thread</strong>.
5916 * <p>
5917 * <img width="640" height="394" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/blockingSubscribe.o.png" alt="">
5918 * <p>
5919 * Note that calling this method will block the caller thread until the upstream terminates
5920 * normally or with an error. Therefore, calling this method from special threads such as the
5921 * Android Main Thread or the Swing Event Dispatch Thread is not recommended.
5922 * <dl>
5923 * <dt><b>Scheduler:</b></dt>
5924 * <dd>{@code blockingSubscribe} does not operate by default on a particular {@link Scheduler}.</dd>
5925 * </dl>
5926 * @param onNext the callback action for each source value
5927 * @param onError the callback action for an error event
5928 * @param onComplete the callback action for the completion event.
5929 * @throws NullPointerException if {@code onNext}, {@code onError} or {@code onComplete} is {@code null}
5930 * @since 2.0
5931 */
5932 @SchedulerSupport(SchedulerSupport.NONE)
5933 public final void blockingSubscribe(@NonNull Consumer<? super T> onNext, @NonNull Consumer<? super Throwable> onError, @NonNull Action onComplete) {
5934 ObservableBlockingSubscribe.subscribe(this, onNext, onError, onComplete);
5935 }
5936
5937 /**
5938 * Subscribes to the source and calls the {@link Observer} methods <strong>on the current thread</strong>.
5939 * <p>
5940 * Note that calling this method will block the caller thread until the upstream terminates
5941 * normally, with an error or the {@code Observer} disposes the {@link Disposable} it receives via
5942 * {@link Observer#onSubscribe(Disposable)}.
5943 * Therefore, calling this method from special threads such as the
5944 * Android Main Thread or the Swing Event Dispatch Thread is not recommended.
5945 * <dl>
5946 * <dt><b>Scheduler:</b></dt>
5947 * <dd>{@code blockingSubscribe} does not operate by default on a particular {@link Scheduler}.</dd>
5948 * </dl>
5949 * The a dispose() call is composed through.
5950 * @param observer the {@code Observer} instance to forward events and calls to in the current thread
5951 * @throws NullPointerException if {@code observer} is {@code null}
5952 * @since 2.0
5953 */
5954 @SchedulerSupport(SchedulerSupport.NONE)
5955 public final void blockingSubscribe(@NonNull Observer<? super T> observer) {
5956 Objects.requireNonNull(observer, "observer is null");
5957 ObservableBlockingSubscribe.subscribe(this, observer);
5958 }
5959
5960 /**
5961 * Returns an {@code Observable} that emits buffers of items it collects from the current {@code Observable}. The resulting
5962 * {@code Observable} emits connected, non-overlapping buffers, each containing {@code count} items. When the current
5963 * {@code Observable} completes, the resulting {@code Observable} emits the current buffer and propagates the notification
5964 * from the current {@code Observable}. Note that if the current {@code Observable} issues an {@code onError} notification
5965 * the event is passed on immediately without first emitting the buffer it is in the process of assembling.
5966 * <p>
5967 * <img width="640" height="320" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/buffer3.v3.png" alt="">
5968 * <dl>
5969 * <dt><b>Scheduler:</b></dt>
5970 * <dd>This version of {@code buffer} does not operate by default on a particular {@link Scheduler}.</dd>
5971 * </dl>
5972 *
5973 * @param count
5974 * the maximum number of items in each buffer before it should be emitted
5975 * @return the new {@code Observable} instance
5976 * @throws IllegalArgumentException if {@code count} is non-positive
5977 * @see <a href="http://reactivex.io/documentation/operators/buffer.html">ReactiveX operators documentation: Buffer</a>
5978 */
5979 @CheckReturnValue
5980 @SchedulerSupport(SchedulerSupport.NONE)
5981 @NonNull
5982 public final Observable<@NonNull List<T>> buffer(int count) {
5983 return buffer(count, count);
5984 }
5985
5986 /**
5987 * Returns an {@code Observable} that emits buffers of items it collects from the current {@code Observable}. The resulting
5988 * {@code Observable} emits buffers every {@code skip} items, each containing {@code count} items. When the current
5989 * {@code Observable} completes, the resulting {@code Observable} emits the current buffer and propagates the notification
5990 * from the current {@code Observable}. Note that if the current {@code Observable} issues an {@code onError} notification
5991 * the event is passed on immediately without first emitting the buffer it is in the process of assembling.
5992 * <p>
5993 * <img width="640" height="320" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/buffer4.v3.png" alt="">
5994 * <dl>
5995 * <dt><b>Scheduler:</b></dt>
5996 * <dd>This version of {@code buffer} does not operate by default on a particular {@link Scheduler}.</dd>
5997 * </dl>
5998 *
5999 * @param count
6000 * the maximum size of each buffer before it should be emitted
6001 * @param skip
6002 * how many items emitted by the current {@code Observable} should be skipped before starting a new
6003 * buffer. Note that when {@code skip} and {@code count} are equal, this is the same operation as
6004 * {@link #buffer(int)}.
6005 * @return the new {@code Observable} instance
6006 * @throws IllegalArgumentException if {@code count} or {@code skip} is non-positive
6007 * @see <a href="http://reactivex.io/documentation/operators/buffer.html">ReactiveX operators documentation: Buffer</a>
6008 */
6009 @CheckReturnValue
6010 @SchedulerSupport(SchedulerSupport.NONE)
6011 @NonNull
6012 public final Observable<@NonNull List<T>> buffer(int count, int skip) {
6013 return buffer(count, skip, ArrayListSupplier.asSupplier());
6014 }
6015
6016 /**
6017 * Returns an {@code Observable} that emits buffers of items it collects from the current {@code Observable}. The resulting
6018 * {@code Observable} emits buffers every {@code skip} items, each containing {@code count} items. When the current
6019 * {@code Observable} completes, the resulting {@code Observable} emits the current buffer and propagates the notification
6020 * from the current {@code Observable}. Note that if the current {@code Observable} issues an {@code onError} notification
6021 * the event is passed on immediately without first emitting the buffer it is in the process of assembling.
6022 * <p>
6023 * <img width="640" height="320" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/buffer4.v3.png" alt="">
6024 * <dl>
6025 * <dt><b>Scheduler:</b></dt>
6026 * <dd>This version of {@code buffer} does not operate by default on a particular {@link Scheduler}.</dd>
6027 * </dl>
6028 *
6029 * @param <U> the collection subclass type to buffer into
6030 * @param count
6031 * the maximum size of each buffer before it should be emitted
6032 * @param skip
6033 * how many items emitted by the current {@code Observable} should be skipped before starting a new
6034 * buffer. Note that when {@code skip} and {@code count} are equal, this is the same operation as
6035 * {@link #buffer(int)}.
6036 * @param bufferSupplier
6037 * a factory function that returns an instance of the collection subclass to be used and returned
6038 * as the buffer
6039 * @return the new {@code Observable} instance
6040 * @throws NullPointerException if {@code bufferSupplier} is {@code null}
6041 * @throws IllegalArgumentException if {@code count} or {@code skip} is non-positive
6042 * @see <a href="http://reactivex.io/documentation/operators/buffer.html">ReactiveX operators documentation: Buffer</a>
6043 */
6044 @CheckReturnValue
6045 @SchedulerSupport(SchedulerSupport.NONE)
6046 @NonNull
6047 public final <@NonNull U extends Collection<? super T>> Observable<U> buffer(int count, int skip, @NonNull Supplier<U> bufferSupplier) {
6048 ObjectHelper.verifyPositive(count, "count");
6049 ObjectHelper.verifyPositive(skip, "skip");
6050 Objects.requireNonNull(bufferSupplier, "bufferSupplier is null");
6051 return RxJavaPlugins.onAssembly(new ObservableBuffer<>(this, count, skip, bufferSupplier));
6052 }
6053
6054 /**
6055 * Returns an {@code Observable} that emits buffers of items it collects from the current {@code Observable}. The resulting
6056 * {@code Observable} emits connected, non-overlapping buffers, each containing {@code count} items. When the current
6057 * {@code Observable} completes, the resulting {@code Observable} emits the current buffer and propagates the notification
6058 * from the current {@code Observable}. Note that if the current {@code Observable} issues an {@code onError} notification
6059 * the event is passed on immediately without first emitting the buffer it is in the process of assembling.
6060 * <p>
6061 * <img width="640" height="320" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/buffer3.v3.png" alt="">
6062 * <dl>
6063 * <dt><b>Scheduler:</b></dt>
6064 * <dd>This version of {@code buffer} does not operate by default on a particular {@link Scheduler}.</dd>
6065 * </dl>
6066 *
6067 * @param <U> the collection subclass type to buffer into
6068 * @param count
6069 * the maximum number of items in each buffer before it should be emitted
6070 * @param bufferSupplier
6071 * a factory function that returns an instance of the collection subclass to be used and returned
6072 * as the buffer
6073 * @return the new {@code Observable} instance
6074 * @throws NullPointerException if {@code bufferSupplier} is {@code null}
6075 * @throws IllegalArgumentException if {@code count} is non-positive
6076 * @see <a href="http://reactivex.io/documentation/operators/buffer.html">ReactiveX operators documentation: Buffer</a>
6077 */
6078 @CheckReturnValue
6079 @SchedulerSupport(SchedulerSupport.NONE)
6080 @NonNull
6081 public final <@NonNull U extends Collection<? super T>> Observable<U> buffer(int count, @NonNull Supplier<U> bufferSupplier) {
6082 return buffer(count, count, bufferSupplier);
6083 }
6084
6085 /**
6086 * Returns an {@code Observable} that emits buffers of items it collects from the current {@code Observable}. The resulting
6087 * {@code Observable} starts a new buffer periodically, as determined by the {@code timeskip} argument. It emits
6088 * each buffer after a fixed timespan, specified by the {@code timespan} argument. When the current
6089 * {@code Observable} completes, the resulting {@code Observable} emits the current buffer and propagates the notification
6090 * from the current {@code Observable}. Note that if the current {@code Observable} issues an {@code onError} notification
6091 * the event is passed on immediately without first emitting the buffer it is in the process of assembling.
6092 * <p>
6093 * <img width="640" height="320" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/buffer7.v3.png" alt="">
6094 * <dl>
6095 * <dt><b>Scheduler:</b></dt>
6096 * <dd>This version of {@code buffer} operates by default on the {@code computation} {@link Scheduler}.</dd>
6097 * </dl>
6098 *
6099 * @param timespan
6100 * the period of time each buffer collects items before it is emitted
6101 * @param timeskip
6102 * the period of time after which a new buffer will be created
6103 * @param unit
6104 * the unit of time that applies to the {@code timespan} and {@code timeskip} arguments
6105 * @return the new {@code Observable} instance
6106 * @throws NullPointerException if {@code unit} is {@code null}
6107 * @see <a href="http://reactivex.io/documentation/operators/buffer.html">ReactiveX operators documentation: Buffer</a>
6108 */
6109 @CheckReturnValue
6110 @SchedulerSupport(SchedulerSupport.COMPUTATION)
6111 @NonNull
6112 public final Observable<@NonNull List<T>> buffer(long timespan, long timeskip, @NonNull TimeUnit unit) {
6113 return buffer(timespan, timeskip, unit, Schedulers.computation(), ArrayListSupplier.asSupplier());
6114 }
6115
6116 /**
6117 * Returns an {@code Observable} that emits buffers of items it collects from the current {@code Observable}. The resulting
6118 * {@code Observable} starts a new buffer periodically, as determined by the {@code timeskip} argument, and on the
6119 * specified {@code scheduler}. It emits each buffer after a fixed timespan, specified by the
6120 * {@code timespan} argument. When the current {@code Observable} completes, the resulting {@code Observable} emits the
6121 * current buffer and propagates the notification from the current {@code Observable}. Note that if the current
6122 * {@code Observable} issues an {@code onError} notification the event is passed on immediately without first emitting the
6123 * buffer it is in the process of assembling.
6124 * <p>
6125 * <img width="640" height="320" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/buffer7.s.v3.png" alt="">
6126 * <dl>
6127 * <dt><b>Scheduler:</b></dt>
6128 * <dd>You specify which {@link Scheduler} this operator will use.</dd>
6129 * </dl>
6130 *
6131 * @param timespan
6132 * the period of time each buffer collects items before it is emitted
6133 * @param timeskip
6134 * the period of time after which a new buffer will be created
6135 * @param unit
6136 * the unit of time that applies to the {@code timespan} and {@code timeskip} arguments
6137 * @param scheduler
6138 * the {@code Scheduler} to use when determining the end and start of a buffer
6139 * @return the new {@code Observable} instance
6140 * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null}
6141 * @see <a href="http://reactivex.io/documentation/operators/buffer.html">ReactiveX operators documentation: Buffer</a>
6142 */
6143 @CheckReturnValue
6144 @SchedulerSupport(SchedulerSupport.CUSTOM)
6145 @NonNull
6146 public final Observable<@NonNull List<T>> buffer(long timespan, long timeskip, @NonNull TimeUnit unit, @NonNull Scheduler scheduler) {
6147 return buffer(timespan, timeskip, unit, scheduler, ArrayListSupplier.asSupplier());
6148 }
6149
6150 /**
6151 * Returns an {@code Observable} that emits buffers of items it collects from the current {@code Observable}. The resulting
6152 * {@code Observable} starts a new buffer periodically, as determined by the {@code timeskip} argument, and on the
6153 * specified {@code scheduler}. It emits each buffer after a fixed timespan, specified by the
6154 * {@code timespan} argument. When the current {@code Observable} completes, the resulting {@code Observable} emits the
6155 * current buffer and propagates the notification from the current {@code Observable}. Note that if the current
6156 * {@code Observable} issues an {@code onError} notification the event is passed on immediately without first emitting the
6157 * buffer it is in the process of assembling.
6158 * <p>
6159 * <img width="640" height="320" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/buffer7.s.v3.png" alt="">
6160 * <dl>
6161 * <dt><b>Scheduler:</b></dt>
6162 * <dd>You specify which {@link Scheduler} this operator will use.</dd>
6163 * </dl>
6164 *
6165 * @param <U> the collection subclass type to buffer into
6166 * @param timespan
6167 * the period of time each buffer collects items before it is emitted
6168 * @param timeskip
6169 * the period of time after which a new buffer will be created
6170 * @param unit
6171 * the unit of time that applies to the {@code timespan} and {@code timeskip} arguments
6172 * @param scheduler
6173 * the {@code Scheduler} to use when determining the end and start of a buffer
6174 * @param bufferSupplier
6175 * a factory function that returns an instance of the collection subclass to be used and returned
6176 * as the buffer
6177 * @return the new {@code Observable} instance
6178 * @throws NullPointerException if {@code unit}, {@code scheduler} or {@code bufferSupplier} is {@code null}
6179 * @see <a href="http://reactivex.io/documentation/operators/buffer.html">ReactiveX operators documentation: Buffer</a>
6180 */
6181 @CheckReturnValue
6182 @SchedulerSupport(SchedulerSupport.CUSTOM)
6183 @NonNull
6184 public final <@NonNull U extends Collection<? super T>> Observable<U> buffer(long timespan, long timeskip, @NonNull TimeUnit unit, @NonNull Scheduler scheduler, @NonNull Supplier<U> bufferSupplier) {
6185 Objects.requireNonNull(unit, "unit is null");
6186 Objects.requireNonNull(scheduler, "scheduler is null");
6187 Objects.requireNonNull(bufferSupplier, "bufferSupplier is null");
6188 return RxJavaPlugins.onAssembly(new ObservableBufferTimed<>(this, timespan, timeskip, unit, scheduler, bufferSupplier, Integer.MAX_VALUE, false));
6189 }
6190
6191 /**
6192 * Returns an {@code Observable} that emits buffers of items it collects from the current {@code Observable}. The resulting
6193 * {@code Observable} emits connected, non-overlapping buffers, each of a fixed duration specified by the
6194 * {@code timespan} argument. When the current {@code Observable} completes, the resulting {@code Observable} emits the
6195 * current buffer and propagates the notification from the current {@code Observable}. Note that if the current
6196 * {@code Observable} issues an {@code onError} notification the event is passed on immediately without first emitting the
6197 * buffer it is in the process of assembling.
6198 * <p>
6199 * <img width="640" height="320" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/buffer5.v3.png" alt="">
6200 * <dl>
6201 * <dt><b>Scheduler:</b></dt>
6202 * <dd>This version of {@code buffer} operates by default on the {@code computation} {@link Scheduler}.</dd>
6203 * </dl>
6204 *
6205 * @param timespan
6206 * the period of time each buffer collects items before it is emitted and replaced with a new
6207 * buffer
6208 * @param unit
6209 * the unit of time that applies to the {@code timespan} argument
6210 * @return the new {@code Observable} instance
6211 * @throws NullPointerException if {@code unit} is {@code null}
6212 * @see <a href="http://reactivex.io/documentation/operators/buffer.html">ReactiveX operators documentation: Buffer</a>
6213 */
6214 @CheckReturnValue
6215 @SchedulerSupport(SchedulerSupport.COMPUTATION)
6216 @NonNull
6217 public final Observable<@NonNull List<T>> buffer(long timespan, @NonNull TimeUnit unit) {
6218 return buffer(timespan, unit, Schedulers.computation(), Integer.MAX_VALUE);
6219 }
6220
6221 /**
6222 * Returns an {@code Observable} that emits buffers of items it collects from the current {@code Observable}. The resulting
6223 * {@code Observable} emits connected, non-overlapping buffers, each of a fixed duration specified by the
6224 * {@code timespan} argument or a maximum size specified by the {@code count} argument (whichever is reached
6225 * first). When the current {@code Observable} completes, the resulting {@code Observable} emits the current buffer and
6226 * propagates the notification from the current {@code Observable}. Note that if the current {@code Observable} issues an
6227 * {@code onError} notification the event is passed on immediately without first emitting the buffer it is in the process of
6228 * assembling.
6229 * <p>
6230 * <img width="640" height="320" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/buffer6.v3.png" alt="">
6231 * <dl>
6232 * <dt><b>Scheduler:</b></dt>
6233 * <dd>This version of {@code buffer} operates by default on the {@code computation} {@link Scheduler}.</dd>
6234 * </dl>
6235 *
6236 * @param timespan
6237 * the period of time each buffer collects items before it is emitted and replaced with a new
6238 * buffer
6239 * @param unit
6240 * the unit of time which applies to the {@code timespan} argument
6241 * @param count
6242 * the maximum size of each buffer before it is emitted
6243 * @return the new {@code Observable} instance
6244 * @throws NullPointerException if {@code unit} is {@code null}
6245 * @throws IllegalArgumentException if {@code count} is non-positive
6246 * @see <a href="http://reactivex.io/documentation/operators/buffer.html">ReactiveX operators documentation: Buffer</a>
6247 */
6248 @CheckReturnValue
6249 @SchedulerSupport(SchedulerSupport.COMPUTATION)
6250 @NonNull
6251 public final Observable<@NonNull List<T>> buffer(long timespan, @NonNull TimeUnit unit, int count) {
6252 return buffer(timespan, unit, Schedulers.computation(), count);
6253 }
6254
6255 /**
6256 * Returns an {@code Observable} that emits buffers of items it collects from the current {@code Observable}. The resulting
6257 * {@code Observable} emits connected, non-overlapping buffers, each of a fixed duration specified by the
6258 * {@code timespan} argument as measured on the specified {@code scheduler}, or a maximum size specified by
6259 * the {@code count} argument (whichever is reached first). When the current {@code Observable} completes, the resulting
6260 * {@code Observable} emits the current buffer and propagates the notification from the current {@code Observable}. Note
6261 * that if the current {@code Observable} issues an {@code onError} notification the event is passed on immediately without
6262 * first emitting the buffer it is in the process of assembling.
6263 * <p>
6264 * <img width="640" height="320" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/buffer6.s.v3.png" alt="">
6265 * <dl>
6266 * <dt><b>Scheduler:</b></dt>
6267 * <dd>You specify which {@link Scheduler} this operator will use.</dd>
6268 * </dl>
6269 *
6270 * @param timespan
6271 * the period of time each buffer collects items before it is emitted and replaced with a new
6272 * buffer
6273 * @param unit
6274 * the unit of time which applies to the {@code timespan} argument
6275 * @param scheduler
6276 * the {@code Scheduler} to use when determining the end and start of a buffer
6277 * @param count
6278 * the maximum size of each buffer before it is emitted
6279 * @return the new {@code Observable} instance
6280 * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null}
6281 * @throws IllegalArgumentException if {@code count} is non-positive
6282 * @see <a href="http://reactivex.io/documentation/operators/buffer.html">ReactiveX operators documentation: Buffer</a>
6283 */
6284 @CheckReturnValue
6285 @SchedulerSupport(SchedulerSupport.CUSTOM)
6286 @NonNull
6287 public final Observable<@NonNull List<T>> buffer(long timespan, @NonNull TimeUnit unit, @NonNull Scheduler scheduler, int count) {
6288 return buffer(timespan, unit, scheduler, count, ArrayListSupplier.asSupplier(), false);
6289 }
6290
6291 /**
6292 * Returns an {@code Observable} that emits buffers of items it collects from the current {@code Observable}. The resulting
6293 * {@code Observable} emits connected, non-overlapping buffers, each of a fixed duration specified by the
6294 * {@code timespan} argument as measured on the specified {@code scheduler}, or a maximum size specified by
6295 * the {@code count} argument (whichever is reached first). When the current {@code Observable} completes, the resulting
6296 * {@code Observable} emits the current buffer and propagates the notification from the current {@code Observable}. Note
6297 * that if the current {@code Observable} issues an {@code onError} notification the event is passed on immediately without
6298 * first emitting the buffer it is in the process of assembling.
6299 * <p>
6300 * <img width="640" height="320" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/buffer6.s.v3.png" alt="">
6301 * <dl>
6302 * <dt><b>Scheduler:</b></dt>
6303 * <dd>You specify which {@link Scheduler} this operator will use.</dd>
6304 * </dl>
6305 *
6306 * @param <U> the collection subclass type to buffer into
6307 * @param timespan
6308 * the period of time each buffer collects items before it is emitted and replaced with a new
6309 * buffer
6310 * @param unit
6311 * the unit of time which applies to the {@code timespan} argument
6312 * @param scheduler
6313 * the {@code Scheduler} to use when determining the end and start of a buffer
6314 * @param count
6315 * the maximum size of each buffer before it is emitted
6316 * @param bufferSupplier
6317 * a factory function that returns an instance of the collection subclass to be used and returned
6318 * as the buffer
6319 * @param restartTimerOnMaxSize if {@code true}, the time window is restarted when the max capacity of the current buffer
6320 * is reached
6321 * @return the new {@code Observable} instance
6322 * @throws NullPointerException if {@code unit}, {@code scheduler} or {@code bufferSupplier} is {@code null}
6323 * @throws IllegalArgumentException if {@code count} is non-positive
6324 * @see <a href="http://reactivex.io/documentation/operators/buffer.html">ReactiveX operators documentation: Buffer</a>
6325 */
6326 @CheckReturnValue
6327 @SchedulerSupport(SchedulerSupport.CUSTOM)
6328 @NonNull
6329 public final <@NonNull U extends Collection<? super T>> Observable<U> buffer(
6330 long timespan, @NonNull TimeUnit unit,
6331 @NonNull Scheduler scheduler, int count,
6332 @NonNull Supplier<U> bufferSupplier,
6333 boolean restartTimerOnMaxSize) {
6334 Objects.requireNonNull(unit, "unit is null");
6335 Objects.requireNonNull(scheduler, "scheduler is null");
6336 Objects.requireNonNull(bufferSupplier, "bufferSupplier is null");
6337 ObjectHelper.verifyPositive(count, "count");
6338 return RxJavaPlugins.onAssembly(new ObservableBufferTimed<>(this, timespan, timespan, unit, scheduler, bufferSupplier, count, restartTimerOnMaxSize));
6339 }
6340
6341 /**
6342 * Returns an {@code Observable} that emits buffers of items it collects from the current {@code Observable}. The resulting
6343 * {@code Observable} emits connected, non-overlapping buffers, each of a fixed duration specified by the
6344 * {@code timespan} argument and on the specified {@code scheduler}. When the current {@code Observable} completes,
6345 * the resulting {@code Observable} emits the current buffer and propagates the notification from the current
6346 * {@code Observable}. Note that if the current {@code Observable} issues an {@code onError} notification the event is passed on
6347 * immediately without first emitting the buffer it is in the process of assembling.
6348 * <p>
6349 * <img width="640" height="320" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/buffer5.s.v3.png" alt="">
6350 * <dl>
6351 * <dt><b>Scheduler:</b></dt>
6352 * <dd>You specify which {@link Scheduler} this operator will use.</dd>
6353 * </dl>
6354 *
6355 * @param timespan
6356 * the period of time each buffer collects items before it is emitted and replaced with a new
6357 * buffer
6358 * @param unit
6359 * the unit of time which applies to the {@code timespan} argument
6360 * @param scheduler
6361 * the {@code Scheduler} to use when determining the end and start of a buffer
6362 * @return the new {@code Observable} instance
6363 * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null}
6364 * @see <a href="http://reactivex.io/documentation/operators/buffer.html">ReactiveX operators documentation: Buffer</a>
6365 */
6366 @CheckReturnValue
6367 @SchedulerSupport(SchedulerSupport.CUSTOM)
6368 @NonNull
6369 public final Observable<@NonNull List<T>> buffer(long timespan, @NonNull TimeUnit unit, @NonNull Scheduler scheduler) {
6370 return buffer(timespan, unit, scheduler, Integer.MAX_VALUE, ArrayListSupplier.asSupplier(), false);
6371 }
6372
6373 /**
6374 * Returns an {@code Observable} that emits buffers of items it collects from the current {@code Observable}. The resulting
6375 * {@code Observable} emits buffers that it creates when the specified {@code openingIndicator} {@link ObservableSource} emits an
6376 * item, and closes when the {@code ObservableSource} returned from {@code closingIndicator} emits an item. If any of the
6377 * current {@code Observable}, {@code openingIndicator} or {@code closingIndicator} issues an {@code onError} notification the
6378 * event is passed on immediately without first emitting the buffer it is in the process of assembling.
6379 * <p>
6380 * <img width="640" height="470" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/buffer2.v3.png" alt="">
6381 * <dl>
6382 * <dt><b>Scheduler:</b></dt>
6383 * <dd>This version of {@code buffer} does not operate by default on a particular {@link Scheduler}.</dd>
6384 * </dl>
6385 *
6386 * @param <TOpening> the element type of the buffer-opening {@code ObservableSource}
6387 * @param <TClosing> the element type of the individual buffer-closing {@code ObservableSource}s
6388 * @param openingIndicator
6389 * the {@code ObservableSource} that, when it emits an item, causes a new buffer to be created
6390 * @param closingIndicator
6391 * the {@link Function} that is used to produce an {@code ObservableSource} for every buffer created. When this indicator
6392 * {@code ObservableSource} emits an item, the associated buffer is emitted.
6393 * @return the new {@code Observable} instance
6394 * @throws NullPointerException if {@code openingIndicator} or {@code closingIndicator} is {@code null}
6395 * @see <a href="http://reactivex.io/documentation/operators/buffer.html">ReactiveX operators documentation: Buffer</a>
6396 */
6397 @CheckReturnValue
6398 @SchedulerSupport(SchedulerSupport.NONE)
6399 @NonNull
6400 public final <@NonNull TOpening, @NonNull TClosing> Observable<@NonNull List<T>> buffer(
6401 @NonNull ObservableSource<? extends TOpening> openingIndicator,
6402 @NonNull Function<? super TOpening, ? extends ObservableSource<? extends TClosing>> closingIndicator) {
6403 return buffer(openingIndicator, closingIndicator, ArrayListSupplier.asSupplier());
6404 }
6405
6406 /**
6407 * Returns an {@code Observable} that emits buffers of items it collects from the current {@code Observable}. The resulting
6408 * {@code Observable} emits buffers that it creates when the specified {@code openingIndicator} {@link ObservableSource} emits an
6409 * item, and closes when the {@code ObservableSource} returned from {@code closingIndicator} emits an item. If any of the
6410 * current {@code Observable}, {@code openingIndicator} or {@code closingIndicator} issues an {@code onError} notification the
6411 * event is passed on immediately without first emitting the buffer it is in the process of assembling.
6412 * <p>
6413 * <img width="640" height="470" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/buffer2.v3.png" alt="">
6414 * <dl>
6415 * <dt><b>Scheduler:</b></dt>
6416 * <dd>This version of {@code buffer} does not operate by default on a particular {@link Scheduler}.</dd>
6417 * </dl>
6418 *
6419 * @param <U> the collection subclass type to buffer into
6420 * @param <TOpening> the element type of the buffer-opening {@code ObservableSource}
6421 * @param <TClosing> the element type of the individual buffer-closing {@code ObservableSource}s
6422 * @param openingIndicator
6423 * the {@code ObservableSource} that, when it emits an item, causes a new buffer to be created
6424 * @param closingIndicator
6425 * the {@link Function} that is used to produce an {@code ObservableSource} for every buffer created. When this indicator
6426 * {@code ObservableSource} emits an item, the associated buffer is emitted.
6427 * @param bufferSupplier
6428 * a factory function that returns an instance of the collection subclass to be used and returned
6429 * as the buffer
6430 * @return the new {@code Observable} instance
6431 * @throws NullPointerException if {@code openingIndicator}, {@code closingIndicator} or {@code bufferSupplier} is {@code null}
6432 * @see <a href="http://reactivex.io/documentation/operators/buffer.html">ReactiveX operators documentation: Buffer</a>
6433 */
6434 @CheckReturnValue
6435 @SchedulerSupport(SchedulerSupport.NONE)
6436 @NonNull
6437 public final <@NonNull TOpening, @NonNull TClosing, @NonNull U extends Collection<? super T>> Observable<U> buffer(
6438 @NonNull ObservableSource<? extends TOpening> openingIndicator,
6439 @NonNull Function<? super TOpening, ? extends ObservableSource<? extends TClosing>> closingIndicator,
6440 @NonNull Supplier<U> bufferSupplier) {
6441 Objects.requireNonNull(openingIndicator, "openingIndicator is null");
6442 Objects.requireNonNull(closingIndicator, "closingIndicator is null");
6443 Objects.requireNonNull(bufferSupplier, "bufferSupplier is null");
6444 return RxJavaPlugins.onAssembly(new ObservableBufferBoundary<T, U, TOpening, TClosing>(this, openingIndicator, closingIndicator, bufferSupplier));
6445 }
6446
6447 /**
6448 * Returns an {@code Observable} that emits non-overlapping buffered items from the current {@code Observable} each time the
6449 * specified boundary {@link ObservableSource} emits an item.
6450 * <p>
6451 * <img width="640" height="395" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/buffer8.v3.png" alt="">
6452 * <p>
6453 * Completion of either the source or the boundary {@code ObservableSource} causes the returned {@code ObservableSource} to emit the
6454 * latest buffer and complete. If either the current {@code Observable} or the boundary {@code ObservableSource} issues an
6455 * {@code onError} notification the event is passed on immediately without first emitting the buffer it is in the process of
6456 * assembling.
6457 * <dl>
6458 * <dt><b>Scheduler:</b></dt>
6459 * <dd>This version of {@code buffer} does not operate by default on a particular {@link Scheduler}.</dd>
6460 * </dl>
6461 *
6462 * @param <B>
6463 * the boundary value type (ignored)
6464 * @param boundaryIndicator
6465 * the boundary {@code ObservableSource}
6466 * @return the new {@code Observable} instance
6467 * @throws NullPointerException if {@code boundaryIndicator} is {@code null}
6468 * @see #buffer(ObservableSource, int)
6469 * @see <a href="http://reactivex.io/documentation/operators/buffer.html">ReactiveX operators documentation: Buffer</a>
6470 */
6471 @CheckReturnValue
6472 @SchedulerSupport(SchedulerSupport.NONE)
6473 @NonNull
6474 public final <@NonNull B> Observable<@NonNull List<T>> buffer(@NonNull ObservableSource<B> boundaryIndicator) {
6475 return buffer(boundaryIndicator, ArrayListSupplier.asSupplier());
6476 }
6477
6478 /**
6479 * Returns an {@code Observable} that emits non-overlapping buffered items from the current {@code Observable} each time the
6480 * specified boundary {@link ObservableSource} emits an item.
6481 * <p>
6482 * <img width="640" height="395" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/buffer8.v3.png" alt="">
6483 * <p>
6484 * Completion of either the source or the boundary {@code ObservableSource} causes the returned {@code ObservableSource} to emit the
6485 * latest buffer and complete. If either the current {@code Observable} or the boundary {@code ObservableSource} issues an
6486 * {@code onError} notification the event is passed on immediately without first emitting the buffer it is in the process of
6487 * assembling.
6488 * <dl>
6489 * <dt><b>Scheduler:</b></dt>
6490 * <dd>This version of {@code buffer} does not operate by default on a particular {@link Scheduler}.</dd>
6491 * </dl>
6492 *
6493 * @param <B>
6494 * the boundary value type (ignored)
6495 * @param boundaryIndicator
6496 * the boundary {@code ObservableSource}
6497 * @param initialCapacity
6498 * the initial capacity of each buffer chunk
6499 * @return the new {@code Observable} instance
6500 * @see <a href="http://reactivex.io/documentation/operators/buffer.html">ReactiveX operators documentation: Buffer</a>
6501 * @throws NullPointerException if {@code boundaryIndicator} is {@code null}
6502 * @throws IllegalArgumentException if {@code initialCapacity} is non-positive
6503 * @see #buffer(ObservableSource)
6504 */
6505 @CheckReturnValue
6506 @SchedulerSupport(SchedulerSupport.NONE)
6507 @NonNull
6508 public final <@NonNull B> Observable<@NonNull List<T>> buffer(@NonNull ObservableSource<B> boundaryIndicator, int initialCapacity) {
6509 ObjectHelper.verifyPositive(initialCapacity, "initialCapacity");
6510 return buffer(boundaryIndicator, Functions.createArrayList(initialCapacity));
6511 }
6512
6513 /**
6514 * Returns an {@code Observable} that emits non-overlapping buffered items from the current {@code Observable} each time the
6515 * specified boundary {@link ObservableSource} emits an item.
6516 * <p>
6517 * <img width="640" height="395" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/buffer8.v3.png" alt="">
6518 * <p>
6519 * Completion of either the source or the boundary {@code ObservableSource} causes the returned {@code ObservableSource} to emit the
6520 * latest buffer and complete. If either the current {@code Observable} or the boundary {@code ObservableSource} issues an
6521 * {@code onError} notification the event is passed on immediately without first emitting the buffer it is in the process of
6522 * assembling.
6523 * <dl>
6524 * <dt><b>Scheduler:</b></dt>
6525 * <dd>This version of {@code buffer} does not operate by default on a particular {@link Scheduler}.</dd>
6526 * </dl>
6527 *
6528 * @param <U> the collection subclass type to buffer into
6529 * @param <B>
6530 * the boundary value type (ignored)
6531 * @param boundaryIndicator
6532 * the boundary {@code ObservableSource}
6533 * @param bufferSupplier
6534 * a factory function that returns an instance of the collection subclass to be used and returned
6535 * as the buffer
6536 * @return the new {@code Observable} instance
6537 * @throws NullPointerException if {@code boundaryIndicator} or {@code bufferSupplier} is {@code null}
6538 * @see #buffer(ObservableSource, int)
6539 * @see <a href="http://reactivex.io/documentation/operators/buffer.html">ReactiveX operators documentation: Buffer</a>
6540 */
6541 @CheckReturnValue
6542 @SchedulerSupport(SchedulerSupport.NONE)
6543 @NonNull
6544 public final <@NonNull B, @NonNull U extends Collection<? super T>> Observable<U> buffer(@NonNull ObservableSource<B> boundaryIndicator, @NonNull Supplier<U> bufferSupplier) {
6545 Objects.requireNonNull(boundaryIndicator, "boundaryIndicator is null");
6546 Objects.requireNonNull(bufferSupplier, "bufferSupplier is null");
6547 return RxJavaPlugins.onAssembly(new ObservableBufferExactBoundary<>(this, boundaryIndicator, bufferSupplier));
6548 }
6549
6550 /**
6551 * Returns an {@code Observable} that subscribes to the current {@code Observable} lazily, caches all of its events
6552 * and replays them, in the same order as received, to all the downstream observers.
6553 * <p>
6554 * <img width="640" height="410" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/cache.v3.png" alt="">
6555 * <p>
6556 * This is useful when you want an {@code Observable} to cache responses and you can't control the
6557 * subscribe/dispose behavior of all the {@link Observer}s.
6558 * <p>
6559 * The operator subscribes only when the first downstream observer subscribes and maintains
6560 * a single subscription towards the current {@code Observable}. In contrast, the operator family of {@link #replay()}
6561 * that return a {@link ConnectableObservable} require an explicit call to {@link ConnectableObservable#connect()}.
6562 * <p>
6563 * <em>Note:</em> You sacrifice the ability to dispose the origin when you use the {@code cache}
6564 * operator so be careful not to use this operator on {@code Observable}s that emit an infinite or very large number
6565 * of items that will use up memory.
6566 * A possible workaround is to apply {@code takeUntil} with a predicate or
6567 * another source before (and perhaps after) the application of {@code cache()}.
6568 * <pre><code>
6569 * AtomicBoolean shouldStop = new AtomicBoolean();
6570 *
6571 * source.takeUntil(v -&gt; shouldStop.get())
6572 * .cache()
6573 * .takeUntil(v -&gt; shouldStop.get())
6574 * .subscribe(...);
6575 * </code></pre>
6576 * Since the operator doesn't allow clearing the cached values either, the possible workaround is
6577 * to forget all references to it via {@link #onTerminateDetach()} applied along with the previous
6578 * workaround:
6579 * <pre><code>
6580 * AtomicBoolean shouldStop = new AtomicBoolean();
6581 *
6582 * source.takeUntil(v -&gt; shouldStop.get())
6583 * .onTerminateDetach()
6584 * .cache()
6585 * .takeUntil(v -&gt; shouldStop.get())
6586 * .onTerminateDetach()
6587 * .subscribe(...);
6588 * </code></pre>
6589 * <dl>
6590 * <dt><b>Scheduler:</b></dt>
6591 * <dd>{@code cache} does not operate by default on a particular {@link Scheduler}.</dd>
6592 * </dl>
6593 *
6594 * @return the new {@code Observable} instance
6595 * @see <a href="http://reactivex.io/documentation/operators/replay.html">ReactiveX operators documentation: Replay</a>
6596 * @see #takeUntil(Predicate)
6597 * @see #takeUntil(ObservableSource)
6598 */
6599 @CheckReturnValue
6600 @SchedulerSupport(SchedulerSupport.NONE)
6601 @NonNull
6602 public final Observable<T> cache() {
6603 return cacheWithInitialCapacity(16);
6604 }
6605
6606 /**
6607 * Returns an {@code Observable} that subscribes to the current {@code Observable} lazily, caches all of its events
6608 * and replays them, in the same order as received, to all the downstream observers.
6609 * <p>
6610 * <img width="640" height="410" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/cacheWithInitialCapacity.o.v3.png" alt="">
6611 * <p>
6612 * This is useful when you want an {@code Observable} to cache responses and you can't control the
6613 * subscribe/dispose behavior of all the {@link Observer}s.
6614 * <p>
6615 * The operator subscribes only when the first downstream observer subscribes and maintains
6616 * a single subscription towards the current {@code Observable}. In contrast, the operator family of {@link #replay()}
6617 * that return a {@link ConnectableObservable} require an explicit call to {@link ConnectableObservable#connect()}.
6618 * <p>
6619 * <em>Note:</em> You sacrifice the ability to dispose the origin when you use the {@code cache}
6620 * operator so be careful not to use this operator on {@code Observable}s that emit an infinite or very large number
6621 * of items that will use up memory.
6622 * A possible workaround is to apply `takeUntil` with a predicate or
6623 * another source before (and perhaps after) the application of {@code cache()}.
6624 * <pre><code>
6625 * AtomicBoolean shouldStop = new AtomicBoolean();
6626 *
6627 * source.takeUntil(v -&gt; shouldStop.get())
6628 * .cache()
6629 * .takeUntil(v -&gt; shouldStop.get())
6630 * .subscribe(...);
6631 * </code></pre>
6632 * Since the operator doesn't allow clearing the cached values either, the possible workaround is
6633 * to forget all references to it via {@link #onTerminateDetach()} applied along with the previous
6634 * workaround:
6635 * <pre><code>
6636 * AtomicBoolean shouldStop = new AtomicBoolean();
6637 *
6638 * source.takeUntil(v -&gt; shouldStop.get())
6639 * .onTerminateDetach()
6640 * .cache()
6641 * .takeUntil(v -&gt; shouldStop.get())
6642 * .onTerminateDetach()
6643 * .subscribe(...);
6644 * </code></pre>
6645 * <dl>
6646 * <dt><b>Scheduler:</b></dt>
6647 * <dd>{@code cacheWithInitialCapacity} does not operate by default on a particular {@link Scheduler}.</dd>
6648 * </dl>
6649 * <p>
6650 * <em>Note:</em> The capacity hint is not an upper bound on cache size. For that, consider
6651 * {@link #replay(int)} in combination with {@link ConnectableObservable#autoConnect()} or similar.
6652 *
6653 * @param initialCapacity hint for number of items to cache (for optimizing underlying data structure)
6654 * @return the new {@code Observable} instance
6655 * @throws IllegalArgumentException if {@code initialCapacity} is non-positive
6656 * @see <a href="http://reactivex.io/documentation/operators/replay.html">ReactiveX operators documentation: Replay</a>
6657 * @see #takeUntil(Predicate)
6658 * @see #takeUntil(ObservableSource)
6659 */
6660 @CheckReturnValue
6661 @SchedulerSupport(SchedulerSupport.NONE)
6662 @NonNull
6663 public final Observable<T> cacheWithInitialCapacity(int initialCapacity) {
6664 ObjectHelper.verifyPositive(initialCapacity, "initialCapacity");
6665 return RxJavaPlugins.onAssembly(new ObservableCache<>(this, initialCapacity));
6666 }
6667
6668 /**
6669 * Returns an {@code Observable} that emits the items emitted by the current {@code Observable}, converted to the specified
6670 * type.
6671 * <p>
6672 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/cast.v3.png" alt="">
6673 * <dl>
6674 * <dt><b>Scheduler:</b></dt>
6675 * <dd>{@code cast} does not operate by default on a particular {@link Scheduler}.</dd>
6676 * </dl>
6677 *
6678 * @param <U> the output value type cast to
6679 * @param clazz
6680 * the target class type that {@code cast} will cast the items emitted by the current {@code Observable}
6681 * into before emitting them from the resulting {@code Observable}
6682 * @return the new {@code Observable} instance
6683 * @throws NullPointerException if {@code clazz} is {@code null}
6684 * @see <a href="http://reactivex.io/documentation/operators/map.html">ReactiveX operators documentation: Map</a>
6685 */
6686 @CheckReturnValue
6687 @SchedulerSupport(SchedulerSupport.NONE)
6688 @NonNull
6689 public final <@NonNull U> Observable<U> cast(@NonNull Class<U> clazz) {
6690 Objects.requireNonNull(clazz, "clazz is null");
6691 return map(Functions.castFunction(clazz));
6692 }
6693
6694 /**
6695 * Collects items emitted by the finite source {@code Observable} into a single mutable data structure and returns
6696 * a {@link Single} that emits this structure.
6697 * <p>
6698 * <img width="640" height="330" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/collect.2.v3.png" alt="">
6699 * <p>
6700 * This is a simplified version of {@code reduce} that does not need to return the state on each pass.
6701 * <p>
6702 * Note that this operator requires the upstream to signal {@code onComplete} for the accumulator object to
6703 * be emitted. Sources that are infinite and never complete will never emit anything through this
6704 * operator and an infinite source may lead to a fatal {@link OutOfMemoryError}.
6705 * <dl>
6706 * <dt><b>Scheduler:</b></dt>
6707 * <dd>{@code collect} does not operate by default on a particular {@link Scheduler}.</dd>
6708 * </dl>
6709 *
6710 * @param <U> the accumulator and output type
6711 * @param initialItemSupplier
6712 * the mutable data structure that will collect the items
6713 * @param collector
6714 * a function that accepts the {@code state} and an emitted item, and modifies the accumulator accordingly
6715 * accordingly
6716 * @return the new {@code Single} instance
6717 * @throws NullPointerException if {@code initialItemSupplier} or {@code collector} is {@code null}
6718 * @see <a href="http://reactivex.io/documentation/operators/reduce.html">ReactiveX operators documentation: Reduce</a>
6719 */
6720 @CheckReturnValue
6721 @SchedulerSupport(SchedulerSupport.NONE)
6722 @NonNull
6723 public final <@NonNull U> Single<U> collect(@NonNull Supplier<? extends U> initialItemSupplier, @NonNull BiConsumer<? super U, ? super T> collector) {
6724 Objects.requireNonNull(initialItemSupplier, "initialItemSupplier is null");
6725 Objects.requireNonNull(collector, "collector is null");
6726 return RxJavaPlugins.onAssembly(new ObservableCollectSingle<>(this, initialItemSupplier, collector));
6727 }
6728
6729 /**
6730 * Collects items emitted by the finite source {@code Observable} into a single mutable data structure and returns
6731 * a {@link Single} that emits this structure.
6732 * <p>
6733 * <img width="640" height="330" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/collectInto.o.v3.png" alt="">
6734 * <p>
6735 * This is a simplified version of {@code reduce} that does not need to return the state on each pass.
6736 * <p>
6737 * Note that this operator requires the upstream to signal {@code onComplete} for the accumulator object to
6738 * be emitted. Sources that are infinite and never complete will never emit anything through this
6739 * operator and an infinite source may lead to a fatal {@link OutOfMemoryError}.
6740 * <dl>
6741 * <dt><b>Scheduler:</b></dt>
6742 * <dd>{@code collectInto} does not operate by default on a particular {@link Scheduler}.</dd>
6743 * </dl>
6744 *
6745 * @param <U> the accumulator and output type
6746 * @param initialItem
6747 * the mutable data structure that will collect the items
6748 * @param collector
6749 * a function that accepts the {@code state} and an emitted item, and modifies the accumulator accordingly
6750 * accordingly
6751 * @return the new {@code Single} instance
6752 * @throws NullPointerException if {@code initialItem} or {@code collector} is {@code null}
6753 * @see <a href="http://reactivex.io/documentation/operators/reduce.html">ReactiveX operators documentation: Reduce</a>
6754 */
6755 @CheckReturnValue
6756 @SchedulerSupport(SchedulerSupport.NONE)
6757 @NonNull
6758 public final <@NonNull U> Single<U> collectInto(@NonNull U initialItem, @NonNull BiConsumer<? super U, ? super T> collector) {
6759 Objects.requireNonNull(initialItem, "initialItem is null");
6760 return collect(Functions.justSupplier(initialItem), collector);
6761 }
6762
6763 /**
6764 * Transform the current {@code Observable} by applying a particular {@link ObservableTransformer} function to it.
6765 * <p>
6766 * This method operates on the {@code Observable} itself whereas {@link #lift} operates on the {@link ObservableSource}'s
6767 * {@link Observer}s.
6768 * <p>
6769 * If the operator you are creating is designed to act on the individual items emitted by the current
6770 * {@code Observable}, use {@link #lift}. If your operator is designed to transform the current {@code Observable} as a whole
6771 * (for instance, by applying a particular set of existing RxJava operators to it) use {@code compose}.
6772 * <dl>
6773 * <dt><b>Scheduler:</b></dt>
6774 * <dd>{@code compose} does not operate by default on a particular {@link Scheduler}.</dd>
6775 * </dl>
6776 *
6777 * @param <R> the value type of the output {@code ObservableSource}
6778 * @param composer implements the function that transforms the current {@code Observable}
6779 * @return the new {@code Observable} instance
6780 * @throws NullPointerException if {@code composer} is {@code null}
6781 * @see <a href="https://github.com/ReactiveX/RxJava/wiki/Implementing-Your-Own-Operators">RxJava wiki: Implementing Your Own Operators</a>
6782 */
6783 @SuppressWarnings("unchecked")
6784 @CheckReturnValue
6785 @SchedulerSupport(SchedulerSupport.NONE)
6786 @NonNull
6787 public final <@NonNull R> Observable<R> compose(@NonNull ObservableTransformer<? super T, ? extends R> composer) {
6788 return wrap(((ObservableTransformer<T, R>) Objects.requireNonNull(composer, "composer is null")).apply(this));
6789 }
6790
6791 /**
6792 * Returns a new {@code Observable} that emits items resulting from applying a function that you supply to each item
6793 * emitted by the current {@code Observable}, where that function returns an {@link ObservableSource}, and then emitting the items
6794 * that result from concatenating those returned {@code ObservableSource}s.
6795 * <p>
6796 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/concatMap.v3.png" alt="">
6797 * <p>
6798 * Note that there is no guarantee where the given {@code mapper} function will be executed; it could be on the subscribing thread,
6799 * on the upstream thread signaling the new item to be mapped or on the thread where the inner source terminates. To ensure
6800 * the {@code mapper} function is confined to a known thread, use the {@link #concatMap(Function, int, Scheduler)} overload.
6801 * <dl>
6802 * <dt><b>Scheduler:</b></dt>
6803 * <dd>{@code concatMap} does not operate by default on a particular {@link Scheduler}.</dd>
6804 * </dl>
6805 *
6806 * @param <R> the type of the inner {@code ObservableSource} sources and thus the output type
6807 * @param mapper
6808 * a function that, when applied to an item emitted by the current {@code Observable}, returns an
6809 * {@code ObservableSource}
6810 * @return the new {@code Observable} instance
6811 * @throws NullPointerException if {@code mapper} is {@code null}
6812 * @see <a href="http://reactivex.io/documentation/operators/flatmap.html">ReactiveX operators documentation: FlatMap</a>
6813 * @see #concatMap(Function, int, Scheduler)
6814 */
6815 @CheckReturnValue
6816 @SchedulerSupport(SchedulerSupport.NONE)
6817 @NonNull
6818 public final <@NonNull R> Observable<R> concatMap(@NonNull Function<? super T, ? extends ObservableSource<? extends R>> mapper) {
6819 return concatMap(mapper, 2);
6820 }
6821
6822 /**
6823 * Returns a new {@code Observable} that emits items resulting from applying a function that you supply to each item
6824 * emitted by the current {@code Observable}, where that function returns an {@link ObservableSource}, and then emitting the items
6825 * that result from concatenating those returned {@code ObservableSource}s.
6826 * <p>
6827 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/concatMap.v3.png" alt="">
6828 * <p>
6829 * Note that there is no guarantee where the given {@code mapper} function will be executed; it could be on the subscribing thread,
6830 * on the upstream thread signaling the new item to be mapped or on the thread where the inner source terminates. To ensure
6831 * the {@code mapper} function is confined to a known thread, use the {@link #concatMap(Function, int, Scheduler)} overload.
6832 * <dl>
6833 * <dt><b>Scheduler:</b></dt>
6834 * <dd>{@code concatMap} does not operate by default on a particular {@link Scheduler}.</dd>
6835 * </dl>
6836 *
6837 * @param <R> the type of the inner {@code ObservableSource} sources and thus the output type
6838 * @param mapper
6839 * a function that, when applied to an item emitted by the current {@code Observable}, returns an
6840 * {@code ObservableSource}
6841 * @param bufferSize
6842 * the number of elements expected from the current {@code Observable} to be buffered
6843 * @return the new {@code Observable} instance
6844 * @throws NullPointerException if {@code mapper} is {@code null}
6845 * @throws IllegalArgumentException if {@code bufferSize} is non-positive
6846 * @see <a href="http://reactivex.io/documentation/operators/flatmap.html">ReactiveX operators documentation: FlatMap</a>
6847 * @see #concatMap(Function, int, Scheduler)
6848 */
6849 @CheckReturnValue
6850 @SchedulerSupport(SchedulerSupport.NONE)
6851 @NonNull
6852 public final <@NonNull R> Observable<R> concatMap(@NonNull Function<? super T, ? extends ObservableSource<? extends R>> mapper, int bufferSize) {
6853 Objects.requireNonNull(mapper, "mapper is null");
6854 ObjectHelper.verifyPositive(bufferSize, "bufferSize");
6855 if (this instanceof ScalarSupplier) {
6856 @SuppressWarnings("unchecked")
6857 T v = ((ScalarSupplier<T>)this).get();
6858 if (v == null) {
6859 return empty();
6860 }
6861 return ObservableScalarXMap.scalarXMap(v, mapper);
6862 }
6863 return RxJavaPlugins.onAssembly(new ObservableConcatMap<>(this, mapper, bufferSize, ErrorMode.IMMEDIATE));
6864 }
6865
6866 /**
6867 * Returns a new {@code Observable} that emits items resulting from applying a function that you supply to each item
6868 * emitted by the current {@code Observable}, where that function returns an {@link ObservableSource}, and then emitting the items
6869 * that result from concatenating those returned {@code ObservableSource}s.
6870 * <p>
6871 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/concatMap.v3.png" alt="">
6872 * <p>
6873 * The difference between {@link #concatMap(Function, int)} and this operator is that this operator guarantees the {@code mapper}
6874 * function is executed on the specified scheduler.
6875 * <dl>
6876 * <dt><b>Scheduler:</b></dt>
6877 * <dd>{@code concatMap} executes the given {@code mapper} function on the provided {@link Scheduler}.</dd>
6878 * </dl>
6879 *
6880 * @param <R> the type of the inner {@code ObservableSource} sources and thus the output type
6881 * @param mapper
6882 * a function that, when applied to an item emitted by the current {@code Observable}, returns an
6883 * {@code ObservableSource}
6884 * @param bufferSize
6885 * the number of elements expected from the current {@code Observable} to be buffered
6886 * @param scheduler
6887 * the scheduler where the {@code mapper} function will be executed
6888 * @return the new {@code Observable} instance
6889 * @throws NullPointerException if {@code mapper} or {@code scheduler} is {@code null}
6890 * @throws IllegalArgumentException if {@code bufferSize} is non-positive
6891 * @since 3.0.0
6892 * @see <a href="http://reactivex.io/documentation/operators/flatmap.html">ReactiveX operators documentation: FlatMap</a>
6893 */
6894 @CheckReturnValue
6895 @SchedulerSupport(SchedulerSupport.CUSTOM)
6896 @NonNull
6897 public final <@NonNull R> Observable<R> concatMap(@NonNull Function<? super T, ? extends ObservableSource<? extends R>> mapper, int bufferSize, @NonNull Scheduler scheduler) {
6898 Objects.requireNonNull(mapper, "mapper is null");
6899 ObjectHelper.verifyPositive(bufferSize, "bufferSize");
6900 Objects.requireNonNull(scheduler, "scheduler is null");
6901 return RxJavaPlugins.onAssembly(new ObservableConcatMapScheduler<>(this, mapper, bufferSize, ErrorMode.IMMEDIATE, scheduler));
6902 }
6903
6904 /**
6905 * Maps each of the items into an {@link ObservableSource}, subscribes to them one after the other,
6906 * one at a time and emits their values in order
6907 * while delaying any error from either this or any of the inner {@code ObservableSource}s
6908 * till all of them terminate.
6909 * <p>
6910 * <img width="640" height="348" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/concatMapDelayError.o.png" alt="">
6911 * <p>
6912 * Note that there is no guarantee where the given {@code mapper} function will be executed; it could be on the subscribing thread,
6913 * on the upstream thread signaling the new item to be mapped or on the thread where the inner source terminates. To ensure
6914 * the {@code mapper} function is confined to a known thread, use the {@link #concatMapDelayError(Function, boolean, int, Scheduler)} overload.
6915 * <dl>
6916 * <dt><b>Scheduler:</b></dt>
6917 * <dd>{@code concatMapDelayError} does not operate by default on a particular {@link Scheduler}.</dd>
6918 * </dl>
6919 *
6920 * @param <R> the result value type
6921 * @param mapper the function that maps the items of the current {@code Observable} into the inner {@code ObservableSource}s.
6922 * @return the new {@code Observable} instance with the concatenation behavior
6923 * @throws NullPointerException if {@code mapper} is {@code null}
6924 * @see #concatMapDelayError(Function, boolean, int, Scheduler)
6925 */
6926 @CheckReturnValue
6927 @SchedulerSupport(SchedulerSupport.NONE)
6928 @NonNull
6929 public final <@NonNull R> Observable<R> concatMapDelayError(@NonNull Function<? super T, ? extends ObservableSource<? extends R>> mapper) {
6930 return concatMapDelayError(mapper, true, bufferSize());
6931 }
6932
6933 /**
6934 * Maps each of the items into an {@link ObservableSource}, subscribes to them one after the other,
6935 * one at a time and emits their values in order
6936 * while delaying any error from either this or any of the inner {@code ObservableSource}s
6937 * till all of them terminate.
6938 * <p>
6939 * <img width="640" height="348" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/concatMapDelayError.o.png" alt="">
6940 * <p>
6941 * Note that there is no guarantee where the given {@code mapper} function will be executed; it could be on the subscribing thread,
6942 * on the upstream thread signaling the new item to be mapped or on the thread where the inner source terminates. To ensure
6943 * the {@code mapper} function is confined to a known thread, use the {@link #concatMapDelayError(Function, boolean, int, Scheduler)} overload.
6944 * <dl>
6945 * <dt><b>Scheduler:</b></dt>
6946 * <dd>{@code concatMapDelayError} does not operate by default on a particular {@link Scheduler}.</dd>
6947 * </dl>
6948 *
6949 * @param <R> the result value type
6950 * @param mapper the function that maps the items of the current {@code Observable} into the inner {@code ObservableSource}s.
6951 * @param tillTheEnd
6952 * if {@code true}, all errors from the outer and inner {@code ObservableSource} sources are delayed until the end,
6953 * if {@code false}, an error from the main source is signaled when the current {@code Observable} source terminates
6954 * @param bufferSize
6955 * the number of elements expected from the current {@code Observable} to be buffered
6956 * @return the new {@code Observable} instance with the concatenation behavior
6957 * @throws NullPointerException if {@code mapper} is {@code null}
6958 * @throws IllegalArgumentException if {@code bufferSize} is non-positive
6959 * @see #concatMapDelayError(Function, boolean, int, Scheduler)
6960 */
6961 @CheckReturnValue
6962 @SchedulerSupport(SchedulerSupport.NONE)
6963 @NonNull
6964 public final <@NonNull R> Observable<R> concatMapDelayError(@NonNull Function<? super T, ? extends ObservableSource<? extends R>> mapper,
6965 boolean tillTheEnd, int bufferSize) {
6966 Objects.requireNonNull(mapper, "mapper is null");
6967 ObjectHelper.verifyPositive(bufferSize, "bufferSize");
6968 if (this instanceof ScalarSupplier) {
6969 @SuppressWarnings("unchecked")
6970 T v = ((ScalarSupplier<T>)this).get();
6971 if (v == null) {
6972 return empty();
6973 }
6974 return ObservableScalarXMap.scalarXMap(v, mapper);
6975 }
6976 return RxJavaPlugins.onAssembly(new ObservableConcatMap<>(this, mapper, bufferSize, tillTheEnd ? ErrorMode.END : ErrorMode.BOUNDARY));
6977 }
6978
6979 /**
6980 * Maps each of the items into an {@link ObservableSource}, subscribes to them one after the other,
6981 * one at a time and emits their values in order
6982 * while delaying any error from either this or any of the inner {@code ObservableSource}s
6983 * till all of them terminate.
6984 * <p>
6985 * <img width="640" height="348" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/concatMapDelayError.o.png" alt="">
6986 * <dl>
6987 * <dt><b>Scheduler:</b></dt>
6988 * <dd>{@code concatMapDelayError} does not operate by default on a particular {@link Scheduler}.</dd>
6989 * </dl>
6990 *
6991 * @param <R> the result value type
6992 * @param mapper the function that maps the items of the current {@code Observable} into the inner {@code ObservableSource}s.
6993 * @param tillTheEnd
6994 * if {@code true}, all errors from the outer and inner {@code ObservableSource} sources are delayed until the end,
6995 * if {@code false}, an error from the main source is signaled when the current {@code Observable} source terminates
6996 * @param bufferSize
6997 * the number of elements expected from the current {@code Observable} to be buffered
6998 * @param scheduler
6999 * the scheduler where the {@code mapper} function will be executed
7000 * @return the new {@code Observable} instance with the concatenation behavior
7001 * @throws NullPointerException if {@code mapper} or {@code scheduler} is {@code null}
7002 * @throws IllegalArgumentException if {@code bufferSize} is non-positive
7003 * @see #concatMapDelayError(Function, boolean, int)
7004 * @since 3.0.0
7005 */
7006 @CheckReturnValue
7007 @SchedulerSupport(SchedulerSupport.CUSTOM)
7008 @NonNull
7009 public final <@NonNull R> Observable<R> concatMapDelayError(@NonNull Function<? super T, ? extends ObservableSource<? extends R>> mapper,
7010 boolean tillTheEnd, int bufferSize, @NonNull Scheduler scheduler) {
7011 Objects.requireNonNull(mapper, "mapper is null");
7012 ObjectHelper.verifyPositive(bufferSize, "bufferSize");
7013 Objects.requireNonNull(scheduler, "scheduler is null");
7014 return RxJavaPlugins.onAssembly(new ObservableConcatMapScheduler<>(this, mapper, bufferSize, tillTheEnd ? ErrorMode.END : ErrorMode.BOUNDARY, scheduler));
7015 }
7016
7017 /**
7018 * Maps a sequence of values into {@link ObservableSource}s and concatenates these {@code ObservableSource}s eagerly into a single
7019 * {@code Observable} sequence.
7020 * <p>
7021 * Eager concatenation means that once a subscriber subscribes, this operator subscribes to all of the
7022 * current {@code Observable}s. The operator buffers the values emitted by these {@code ObservableSource}s and then drains them in
7023 * order, each one after the previous one completes.
7024 * <p>
7025 * <img width="640" height="361" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/concatMapEager.o.png" alt="">
7026 * <dl>
7027 * <dt><b>Scheduler:</b></dt>
7028 * <dd>This method does not operate by default on a particular {@link Scheduler}.</dd>
7029 * </dl>
7030 * @param <R> the value type
7031 * @param mapper the function that maps a sequence of values into a sequence of {@code ObservableSource}s that will be
7032 * eagerly concatenated
7033 * @return the new {@code Observable} instance with the specified concatenation behavior
7034 * @throws NullPointerException if {@code mapper} is {@code null}
7035 * @since 2.0
7036 */
7037 @CheckReturnValue
7038 @SchedulerSupport(SchedulerSupport.NONE)
7039 @NonNull
7040 public final <@NonNull R> Observable<R> concatMapEager(@NonNull Function<? super T, ? extends ObservableSource<? extends R>> mapper) {
7041 return concatMapEager(mapper, Integer.MAX_VALUE, bufferSize());
7042 }
7043
7044 /**
7045 * Maps a sequence of values into {@link ObservableSource}s and concatenates these {@code ObservableSource}s eagerly into a single
7046 * {@code Observable} sequence.
7047 * <p>
7048 * Eager concatenation means that once a subscriber subscribes, this operator subscribes to all of the
7049 * current {@code Observable}s. The operator buffers the values emitted by these {@code ObservableSource}s and then drains them in
7050 * order, each one after the previous one completes.
7051 * <p>
7052 * <img width="640" height="361" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/concatMapEager.o.png" alt="">
7053 * <dl>
7054 * <dt><b>Scheduler:</b></dt>
7055 * <dd>This method does not operate by default on a particular {@link Scheduler}.</dd>
7056 * </dl>
7057 * @param <R> the value type
7058 * @param mapper the function that maps a sequence of values into a sequence of {@code ObservableSource}s that will be
7059 * eagerly concatenated
7060 * @param maxConcurrency the maximum number of concurrent subscribed {@code ObservableSource}s
7061 * @param bufferSize hints about the number of expected items from each inner {@code ObservableSource}, must be positive
7062 * @return the new {@code Observable} instance with the specified concatenation behavior
7063 * @throws NullPointerException if {@code mapper} is {@code null}
7064 * @throws IllegalArgumentException if {@code maxConcurrency} or {@code bufferSize} is non-positive
7065 * @since 2.0
7066 */
7067 @CheckReturnValue
7068 @SchedulerSupport(SchedulerSupport.NONE)
7069 @NonNull
7070 public final <@NonNull R> Observable<R> concatMapEager(@NonNull Function<? super T, ? extends ObservableSource<? extends R>> mapper,
7071 int maxConcurrency, int bufferSize) {
7072 Objects.requireNonNull(mapper, "mapper is null");
7073 ObjectHelper.verifyPositive(maxConcurrency, "maxConcurrency");
7074 ObjectHelper.verifyPositive(bufferSize, "bufferSize");
7075 return RxJavaPlugins.onAssembly(new ObservableConcatMapEager<>(this, mapper, ErrorMode.IMMEDIATE, maxConcurrency, bufferSize));
7076 }
7077
7078 /**
7079 * Maps a sequence of values into {@link ObservableSource}s and concatenates these {@code ObservableSource}s eagerly into a single
7080 * {@code Observable} sequence.
7081 * <p>
7082 * Eager concatenation means that once a subscriber subscribes, this operator subscribes to all of the
7083 * current {@code Observable}s. The operator buffers the values emitted by these {@code ObservableSource}s and then drains them in
7084 * order, each one after the previous one completes.
7085 * <p>
7086 * <img width="640" height="390" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/concatMapEagerDelayError.o.png" alt="">
7087 * <dl>
7088 * <dt><b>Scheduler:</b></dt>
7089 * <dd>This method does not operate by default on a particular {@link Scheduler}.</dd>
7090 * </dl>
7091 * @param <R> the value type
7092 * @param mapper the function that maps a sequence of values into a sequence of {@code ObservableSource}s that will be
7093 * eagerly concatenated
7094 * @param tillTheEnd
7095 * if {@code true}, all errors from the outer and inner {@code ObservableSource} sources are delayed until the end,
7096 * if {@code false}, an error from the main source is signaled when the current {@code Observable} source terminates
7097 * @return the new {@code Observable} instance with the specified concatenation behavior
7098 * @throws NullPointerException if {@code mapper} is {@code null}
7099 * @since 2.0
7100 */
7101 @CheckReturnValue
7102 @SchedulerSupport(SchedulerSupport.NONE)
7103 @NonNull
7104 public final <@NonNull R> Observable<R> concatMapEagerDelayError(@NonNull Function<? super T, ? extends ObservableSource<? extends R>> mapper,
7105 boolean tillTheEnd) {
7106 return concatMapEagerDelayError(mapper, tillTheEnd, Integer.MAX_VALUE, bufferSize());
7107 }
7108
7109 /**
7110 * Maps a sequence of values into {@link ObservableSource}s and concatenates these {@code ObservableSource}s eagerly into a single
7111 * {@code Observable} sequence.
7112 * <p>
7113 * Eager concatenation means that once a subscriber subscribes, this operator subscribes to all of the
7114 * current {@code Observable}s. The operator buffers the values emitted by these {@code ObservableSource}s and then drains them in
7115 * order, each one after the previous one completes.
7116 * <p>
7117 * <img width="640" height="390" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/concatMapEagerDelayError.o.png" alt="">
7118 * <dl>
7119 * <dt><b>Scheduler:</b></dt>
7120 * <dd>This method does not operate by default on a particular {@link Scheduler}.</dd>
7121 * </dl>
7122 * @param <R> the value type
7123 * @param mapper the function that maps a sequence of values into a sequence of {@code ObservableSource}s that will be
7124 * eagerly concatenated
7125 * @param tillTheEnd
7126 * if {@code true}, exceptions from the current {@code Observable} and all the inner {@code ObservableSource}s are delayed until
7127 * all of them terminate, if {@code false}, exception from the current {@code Observable} is delayed until the
7128 * currently running {@code ObservableSource} terminates
7129 * @param maxConcurrency the maximum number of concurrent subscribed {@code ObservableSource}s
7130 * @param bufferSize
7131 * the number of elements expected from the current {@code Observable} and each inner {@code ObservableSource} to be buffered
7132 * @return the new {@code Observable} instance with the specified concatenation behavior
7133 * @throws NullPointerException if {@code mapper} is {@code null}
7134 * @throws IllegalArgumentException if {@code maxConcurrency} or {@code bufferSize} is non-positive
7135 * @since 2.0
7136 */
7137 @CheckReturnValue
7138 @SchedulerSupport(SchedulerSupport.NONE)
7139 @NonNull
7140 public final <@NonNull R> Observable<R> concatMapEagerDelayError(@NonNull Function<? super T, ? extends ObservableSource<? extends R>> mapper,
7141 boolean tillTheEnd, int maxConcurrency, int bufferSize) {
7142 Objects.requireNonNull(mapper, "mapper is null");
7143 ObjectHelper.verifyPositive(maxConcurrency, "maxConcurrency");
7144 ObjectHelper.verifyPositive(bufferSize, "bufferSize");
7145 return RxJavaPlugins.onAssembly(new ObservableConcatMapEager<>(this, mapper, tillTheEnd ? ErrorMode.END : ErrorMode.BOUNDARY, maxConcurrency, bufferSize));
7146 }
7147
7148 /**
7149 * Maps each element of the current {@code Observable} into {@link CompletableSource}s, subscribes to them one at a time in
7150 * order and waits until the upstream and all {@code CompletableSource}s complete.
7151 * <p>
7152 * <img width="640" height="506" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/concatMapCompletable.o.png" alt="">
7153 * <dl>
7154 * <dt><b>Scheduler:</b></dt>
7155 * <dd>{@code concatMapCompletable} does not operate by default on a particular {@link Scheduler}.</dd>
7156 * </dl>
7157 * <p>History: 2.1.6 - experimental
7158 * @param mapper
7159 * a function that, when applied to an item emitted by the current {@code Observable}, returns a {@code CompletableSource}
7160 * @return the new {@link Completable} instance
7161 * @throws NullPointerException if {@code mapper} is {@code null}
7162 * @since 2.2
7163 */
7164 @CheckReturnValue
7165 @SchedulerSupport(SchedulerSupport.NONE)
7166 @NonNull
7167 public final Completable concatMapCompletable(@NonNull Function<? super T, ? extends CompletableSource> mapper) {
7168 return concatMapCompletable(mapper, 2);
7169 }
7170
7171 /**
7172 * Maps each element of the current {@code Observable} into {@link CompletableSource}s, subscribes to them one at a time in
7173 * order and waits until the upstream and all {@code CompletableSource}s complete.
7174 * <p>
7175 * <img width="640" height="506" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/concatMapCompletable.o.png" alt="">
7176 * <dl>
7177 * <dt><b>Scheduler:</b></dt>
7178 * <dd>{@code concatMapCompletable} does not operate by default on a particular {@link Scheduler}.</dd>
7179 * </dl>
7180 * <p>History: 2.1.6 - experimental
7181 * @param mapper
7182 * a function that, when applied to an item emitted by the current {@code Observable}, returns a {@code CompletableSource}
7183 *
7184 * @param capacityHint
7185 * the number of upstream items expected to be buffered until the current {@code CompletableSource}, mapped from
7186 * the current item, completes.
7187 * @return the new {@link Completable} instance
7188 * @throws NullPointerException if {@code mapper} is {@code null}
7189 * @throws IllegalArgumentException if {@code capacityHint} is non-positive
7190 * @since 2.2
7191 */
7192 @CheckReturnValue
7193 @SchedulerSupport(SchedulerSupport.NONE)
7194 @NonNull
7195 public final Completable concatMapCompletable(@NonNull Function<? super T, ? extends CompletableSource> mapper, int capacityHint) {
7196 Objects.requireNonNull(mapper, "mapper is null");
7197 ObjectHelper.verifyPositive(capacityHint, "capacityHint");
7198 return RxJavaPlugins.onAssembly(new ObservableConcatMapCompletable<>(this, mapper, ErrorMode.IMMEDIATE, capacityHint));
7199 }
7200
7201 /**
7202 * Maps the upstream items into {@link CompletableSource}s and subscribes to them one after the
7203 * other terminates, delaying all errors till both the current {@code Observable} and all
7204 * inner {@code CompletableSource}s terminate.
7205 * <p>
7206 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/concatMap.v3.png" alt="">
7207 * <dl>
7208 * <dt><b>Scheduler:</b></dt>
7209 * <dd>{@code concatMapCompletableDelayError} does not operate by default on a particular {@link Scheduler}.</dd>
7210 * </dl>
7211 * <p>History: 2.1.11 - experimental
7212 * @param mapper the function called with the upstream item and should return
7213 * a {@code CompletableSource} to become the next source to
7214 * be subscribed to
7215 * @return the new {@link Completable} instance
7216 * @throws NullPointerException if {@code mapper} is {@code null}
7217 * @see #concatMapCompletable(Function, int)
7218 * @since 2.2
7219 */
7220 @CheckReturnValue
7221 @SchedulerSupport(SchedulerSupport.NONE)
7222 @NonNull
7223 public final Completable concatMapCompletableDelayError(@NonNull Function<? super T, ? extends CompletableSource> mapper) {
7224 return concatMapCompletableDelayError(mapper, true, 2);
7225 }
7226
7227 /**
7228 * Maps the upstream items into {@link CompletableSource}s and subscribes to them one after the
7229 * other terminates, optionally delaying all errors till both the current {@code Observable} and all
7230 * inner {@code CompletableSource}s terminate.
7231 * <p>
7232 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/concatMap.v3.png" alt="">
7233 * <dl>
7234 * <dt><b>Scheduler:</b></dt>
7235 * <dd>{@code concatMapCompletableDelayError} does not operate by default on a particular {@link Scheduler}.</dd>
7236 * </dl>
7237 * <p>History: 2.1.11 - experimental
7238 * @param mapper the function called with the upstream item and should return
7239 * a {@code CompletableSource} to become the next source to
7240 * be subscribed to
7241 * @param tillTheEnd If {@code true}, errors from the current {@code Observable} or any of the
7242 * inner {@code CompletableSource}s are delayed until all
7243 * of them terminate. If {@code false}, an error from the current
7244 * {@code Observable} is delayed until the current inner
7245 * {@code CompletableSource} terminates and only then is
7246 * it emitted to the downstream.
7247 * @return the new {@link Completable} instance
7248 * @throws NullPointerException if {@code mapper} is {@code null}
7249 * @see #concatMapCompletable(Function)
7250 * @since 2.2
7251 */
7252 @CheckReturnValue
7253 @SchedulerSupport(SchedulerSupport.NONE)
7254 @NonNull
7255 public final Completable concatMapCompletableDelayError(@NonNull Function<? super T, ? extends CompletableSource> mapper, boolean tillTheEnd) {
7256 return concatMapCompletableDelayError(mapper, tillTheEnd, 2);
7257 }
7258
7259 /**
7260 * Maps the upstream items into {@link CompletableSource}s and subscribes to them one after the
7261 * other terminates, optionally delaying all errors till both the current {@code Observable} and all
7262 * inner {@code CompletableSource}s terminate.
7263 * <p>
7264 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/concatMap.v3.png" alt="">
7265 * <dl>
7266 * <dt><b>Scheduler:</b></dt>
7267 * <dd>{@code concatMapCompletableDelayError} does not operate by default on a particular {@link Scheduler}.</dd>
7268 * </dl>
7269 * <p>History: 2.1.11 - experimental
7270 * @param mapper the function called with the upstream item and should return
7271 * a {@code CompletableSource} to become the next source to
7272 * be subscribed to
7273 * @param tillTheEnd If {@code true}, errors from the current {@code Observable} or any of the
7274 * inner {@code CompletableSource}s are delayed until all
7275 * of them terminate. If {@code false}, an error from the current
7276 * {@code Observable} is delayed until the current inner
7277 * {@code CompletableSource} terminates and only then is
7278 * it emitted to the downstream.
7279 * @param bufferSize The number of upstream items expected to be buffered so that fresh items are
7280 * ready to be mapped when a previous {@code CompletableSource} terminates.
7281 * @return the new {@link Completable} instance
7282 * @throws NullPointerException if {@code mapper} is {@code null}
7283 * @throws IllegalArgumentException if {@code bufferSize} is non-positive
7284 * @see #concatMapCompletable(Function, int)
7285 * @since 2.2
7286 */
7287 @CheckReturnValue
7288 @SchedulerSupport(SchedulerSupport.NONE)
7289 @NonNull
7290 public final Completable concatMapCompletableDelayError(@NonNull Function<? super T, ? extends CompletableSource> mapper, boolean tillTheEnd, int bufferSize) {
7291 Objects.requireNonNull(mapper, "mapper is null");
7292 ObjectHelper.verifyPositive(bufferSize, "bufferSize");
7293 return RxJavaPlugins.onAssembly(new ObservableConcatMapCompletable<>(this, mapper, tillTheEnd ? ErrorMode.END : ErrorMode.BOUNDARY, bufferSize));
7294 }
7295
7296 /**
7297 * Returns an {@code Observable} that concatenate each item emitted by the current {@code Observable} with the values in an
7298 * {@link Iterable} corresponding to that item that is generated by a selector.
7299 * <p>
7300 * <img width="640" height="275" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/concatMapIterable.o.png" alt="">
7301 *
7302 * <dl>
7303 * <dt><b>Scheduler:</b></dt>
7304 * <dd>{@code concatMapIterable} does not operate by default on a particular {@link Scheduler}.</dd>
7305 * </dl>
7306 *
7307 * @param <U>
7308 * the type of item emitted by the resulting {@code Observable}
7309 * @param mapper
7310 * a function that returns an {@code Iterable} sequence of values for when given an item emitted by the
7311 * current {@code Observable}
7312 * @return the new {@code Observable} instance
7313 * @throws NullPointerException if {@code mapper} is {@code null}
7314 * @see <a href="http://reactivex.io/documentation/operators/flatmap.html">ReactiveX operators documentation: FlatMap</a>
7315 */
7316 @CheckReturnValue
7317 @SchedulerSupport(SchedulerSupport.NONE)
7318 @NonNull
7319 public final <@NonNull U> Observable<U> concatMapIterable(@NonNull Function<? super T, @NonNull ? extends Iterable<? extends U>> mapper) {
7320 Objects.requireNonNull(mapper, "mapper is null");
7321 return RxJavaPlugins.onAssembly(new ObservableFlattenIterable<>(this, mapper));
7322 }
7323
7324 /**
7325 * Maps the upstream items into {@link MaybeSource}s and subscribes to them one after the
7326 * other succeeds or completes, emits their success value if available or terminates immediately if
7327 * either the current {@code Observable} or the current inner {@code MaybeSource} fail.
7328 * <p>
7329 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/concatMap.v3.png" alt="">
7330 * <dl>
7331 * <dt><b>Scheduler:</b></dt>
7332 * <dd>{@code concatMapMaybe} does not operate by default on a particular {@link Scheduler}.</dd>
7333 * </dl>
7334 * <p>History: 2.1.11 - experimental
7335 * @param <R> the result type of the inner {@code MaybeSource}s
7336 * @param mapper the function called with the upstream item and should return
7337 * a {@code MaybeSource} to become the next source to
7338 * be subscribed to
7339 * @return the new {@code Observable} instance
7340 * @throws NullPointerException if {@code mapper} is {@code null}
7341 * @see #concatMapMaybeDelayError(Function)
7342 * @see #concatMapMaybe(Function, int)
7343 * @since 2.2
7344 */
7345 @CheckReturnValue
7346 @SchedulerSupport(SchedulerSupport.NONE)
7347 @NonNull
7348 public final <@NonNull R> Observable<R> concatMapMaybe(@NonNull Function<? super T, ? extends MaybeSource<? extends R>> mapper) {
7349 return concatMapMaybe(mapper, 2);
7350 }
7351
7352 /**
7353 * Maps the upstream items into {@link MaybeSource}s and subscribes to them one after the
7354 * other succeeds or completes, emits their success value if available or terminates immediately if
7355 * either the current {@code Observable} or the current inner {@code MaybeSource} fail.
7356 * <p>
7357 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/concatMap.v3.png" alt="">
7358 * <dl>
7359 * <dt><b>Scheduler:</b></dt>
7360 * <dd>{@code concatMapMaybe} does not operate by default on a particular {@link Scheduler}.</dd>
7361 * </dl>
7362 * <p>History: 2.1.11 - experimental
7363 * @param <R> the result type of the inner {@code MaybeSource}s
7364 * @param mapper the function called with the upstream item and should return
7365 * a {@code MaybeSource} to become the next source to
7366 * be subscribed to
7367 * @param bufferSize The number of upstream items expected to be buffered so that fresh items are
7368 * ready to be mapped when a previous {@code MaybeSource} terminates.
7369 * @return the new {@code Observable} instance
7370 * @throws NullPointerException if {@code mapper} is {@code null}
7371 * @throws IllegalArgumentException if {@code bufferSize} is non-positive
7372 * @see #concatMapMaybe(Function)
7373 * @see #concatMapMaybeDelayError(Function, boolean, int)
7374 * @since 2.2
7375 */
7376 @CheckReturnValue
7377 @SchedulerSupport(SchedulerSupport.NONE)
7378 @NonNull
7379 public final <@NonNull R> Observable<R> concatMapMaybe(@NonNull Function<? super T, ? extends MaybeSource<? extends R>> mapper, int bufferSize) {
7380 Objects.requireNonNull(mapper, "mapper is null");
7381 ObjectHelper.verifyPositive(bufferSize, "bufferSize");
7382 return RxJavaPlugins.onAssembly(new ObservableConcatMapMaybe<>(this, mapper, ErrorMode.IMMEDIATE, bufferSize));
7383 }
7384
7385 /**
7386 * Maps the upstream items into {@link MaybeSource}s and subscribes to them one after the
7387 * other terminates, emits their success value if available and delaying all errors
7388 * till both the current {@code Observable} and all inner {@code MaybeSource}s terminate.
7389 * <p>
7390 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/concatMap.v3.png" alt="">
7391 * <dl>
7392 * <dt><b>Scheduler:</b></dt>
7393 * <dd>{@code concatMapMaybeDelayError} does not operate by default on a particular {@link Scheduler}.</dd>
7394 * </dl>
7395 * <p>History: 2.1.11 - experimental
7396 * @param <R> the result type of the inner {@code MaybeSource}s
7397 * @param mapper the function called with the upstream item and should return
7398 * a {@code MaybeSource} to become the next source to
7399 * be subscribed to
7400 * @return the new {@code Observable} instance
7401 * @throws NullPointerException if {@code mapper} is {@code null}
7402 * @see #concatMapMaybe(Function)
7403 * @see #concatMapMaybeDelayError(Function, boolean)
7404 * @since 2.2
7405 */
7406 @CheckReturnValue
7407 @SchedulerSupport(SchedulerSupport.NONE)
7408 @NonNull
7409 public final <@NonNull R> Observable<R> concatMapMaybeDelayError(@NonNull Function<? super T, ? extends MaybeSource<? extends R>> mapper) {
7410 return concatMapMaybeDelayError(mapper, true, 2);
7411 }
7412
7413 /**
7414 * Maps the upstream items into {@link MaybeSource}s and subscribes to them one after the
7415 * other terminates, emits their success value if available and optionally delaying all errors
7416 * till both the current {@code Observable} and all inner {@code MaybeSource}s terminate.
7417 * <p>
7418 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/concatMap.v3.png" alt="">
7419 * <dl>
7420 * <dt><b>Scheduler:</b></dt>
7421 * <dd>{@code concatMapMaybeDelayError} does not operate by default on a particular {@link Scheduler}.</dd>
7422 * </dl>
7423 * <p>History: 2.1.11 - experimental
7424 * @param <R> the result type of the inner {@code MaybeSource}s
7425 * @param mapper the function called with the upstream item and should return
7426 * a {@code MaybeSource} to become the next source to
7427 * be subscribed to
7428 * @param tillTheEnd If {@code true}, errors from the current {@code Observable} or any of the
7429 * inner {@code MaybeSource}s are delayed until all
7430 * of them terminate. If {@code false}, an error from the current
7431 * {@code Observable} is delayed until the current inner
7432 * {@code MaybeSource} terminates and only then is
7433 * it emitted to the downstream.
7434 * @return the new {@code Observable} instance
7435 * @throws NullPointerException if {@code mapper} is {@code null}
7436 * @see #concatMapMaybe(Function, int)
7437 * @see #concatMapMaybeDelayError(Function, boolean, int)
7438 * @since 2.2
7439 */
7440 @CheckReturnValue
7441 @SchedulerSupport(SchedulerSupport.NONE)
7442 @NonNull
7443 public final <@NonNull R> Observable<R> concatMapMaybeDelayError(@NonNull Function<? super T, ? extends MaybeSource<? extends R>> mapper, boolean tillTheEnd) {
7444 return concatMapMaybeDelayError(mapper, tillTheEnd, 2);
7445 }
7446
7447 /**
7448 * Maps the upstream items into {@link MaybeSource}s and subscribes to them one after the
7449 * other terminates, emits their success value if available and optionally delaying all errors
7450 * till both the current {@code Observable} and all inner {@code MaybeSource}s terminate.
7451 * <p>
7452 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/concatMap.v3.png" alt="">
7453 * <dl>
7454 * <dt><b>Scheduler:</b></dt>
7455 * <dd>{@code concatMapMaybeDelayError} does not operate by default on a particular {@link Scheduler}.</dd>
7456 * </dl>
7457 * <p>History: 2.1.11 - experimental
7458 * @param <R> the result type of the inner {@code MaybeSource}s
7459 * @param mapper the function called with the upstream item and should return
7460 * a {@code MaybeSource} to become the next source to
7461 * be subscribed to
7462 * @param tillTheEnd If {@code true}, errors from the current {@code Observable} or any of the
7463 * inner {@code MaybeSource}s are delayed until all
7464 * of them terminate. If {@code false}, an error from the current
7465 * {@code Observable} is delayed until the current inner
7466 * {@code MaybeSource} terminates and only then is
7467 * it emitted to the downstream.
7468 * @param bufferSize The number of upstream items expected to be buffered so that fresh items are
7469 * ready to be mapped when a previous {@code MaybeSource} terminates.
7470 * @return the new {@code Observable} instance
7471 * @throws NullPointerException if {@code mapper} is {@code null}
7472 * @throws IllegalArgumentException if {@code bufferSize} is non-positive
7473 * @see #concatMapMaybe(Function, int)
7474 * @since 2.2
7475 */
7476 @CheckReturnValue
7477 @SchedulerSupport(SchedulerSupport.NONE)
7478 @NonNull
7479 public final <@NonNull R> Observable<R> concatMapMaybeDelayError(@NonNull Function<? super T, ? extends MaybeSource<? extends R>> mapper, boolean tillTheEnd, int bufferSize) {
7480 Objects.requireNonNull(mapper, "mapper is null");
7481 ObjectHelper.verifyPositive(bufferSize, "bufferSize");
7482 return RxJavaPlugins.onAssembly(new ObservableConcatMapMaybe<>(this, mapper, tillTheEnd ? ErrorMode.END : ErrorMode.BOUNDARY, bufferSize));
7483 }
7484
7485 /**
7486 * Maps the upstream items into {@link SingleSource}s and subscribes to them one after the
7487 * other succeeds, emits their success values or terminates immediately if
7488 * either the current {@code Observable} or the current inner {@code SingleSource} fail.
7489 * <p>
7490 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/concatMap.v3.png" alt="">
7491 * <dl>
7492 * <dt><b>Scheduler:</b></dt>
7493 * <dd>{@code concatMapSingle} does not operate by default on a particular {@link Scheduler}.</dd>
7494 * </dl>
7495 * <p>History: 2.1.11 - experimental
7496 * @param <R> the result type of the inner {@code SingleSource}s
7497 * @param mapper the function called with the upstream item and should return
7498 * a {@code SingleSource} to become the next source to
7499 * be subscribed to
7500 * @return the new {@code Observable} instance
7501 * @throws NullPointerException if {@code mapper} is {@code null}
7502 * @see #concatMapSingleDelayError(Function)
7503 * @see #concatMapSingle(Function, int)
7504 * @since 2.2
7505 */
7506 @CheckReturnValue
7507 @SchedulerSupport(SchedulerSupport.NONE)
7508 @NonNull
7509 public final <@NonNull R> Observable<R> concatMapSingle(@NonNull Function<? super T, ? extends SingleSource<? extends R>> mapper) {
7510 return concatMapSingle(mapper, 2);
7511 }
7512
7513 /**
7514 * Maps the upstream items into {@link SingleSource}s and subscribes to them one after the
7515 * other succeeds, emits their success values or terminates immediately if
7516 * either the current {@code Observable} or the current inner {@code SingleSource} fail.
7517 * <p>
7518 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/concatMap.v3.png" alt="">
7519 * <dl>
7520 * <dt><b>Scheduler:</b></dt>
7521 * <dd>{@code concatMapSingle} does not operate by default on a particular {@link Scheduler}.</dd>
7522 * </dl>
7523 * <p>History: 2.1.11 - experimental
7524 * @param <R> the result type of the inner {@code SingleSource}s
7525 * @param mapper the function called with the upstream item and should return
7526 * a {@code SingleSource} to become the next source to
7527 * be subscribed to
7528 * @param bufferSize The number of upstream items expected to be buffered so that fresh items are
7529 * ready to be mapped when a previous {@code SingleSource} terminates.
7530 * @return the new {@code Observable} instance
7531 * @throws NullPointerException if {@code mapper} is {@code null}
7532 * @throws IllegalArgumentException if {@code bufferSize} is non-positive
7533 * @see #concatMapSingle(Function)
7534 * @see #concatMapSingleDelayError(Function, boolean, int)
7535 * @since 2.2
7536 */
7537 @CheckReturnValue
7538 @SchedulerSupport(SchedulerSupport.NONE)
7539 @NonNull
7540 public final <@NonNull R> Observable<R> concatMapSingle(@NonNull Function<? super T, ? extends SingleSource<? extends R>> mapper, int bufferSize) {
7541 Objects.requireNonNull(mapper, "mapper is null");
7542 ObjectHelper.verifyPositive(bufferSize, "bufferSize");
7543 return RxJavaPlugins.onAssembly(new ObservableConcatMapSingle<>(this, mapper, ErrorMode.IMMEDIATE, bufferSize));
7544 }
7545
7546 /**
7547 * Maps the upstream items into {@link SingleSource}s and subscribes to them one after the
7548 * other succeeds or fails, emits their success values and delays all errors
7549 * till both the current {@code Observable} and all inner {@code SingleSource}s terminate.
7550 * <p>
7551 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/concatMap.v3.png" alt="">
7552 * <dl>
7553 * <dt><b>Scheduler:</b></dt>
7554 * <dd>{@code concatMapSingleDelayError} does not operate by default on a particular {@link Scheduler}.</dd>
7555 * </dl>
7556 * <p>History: 2.1.11 - experimental
7557 * @param <R> the result type of the inner {@code SingleSource}s
7558 * @param mapper the function called with the upstream item and should return
7559 * a {@code SingleSource} to become the next source to
7560 * be subscribed to
7561 * @return the new {@code Observable} instance
7562 * @throws NullPointerException if {@code mapper} is {@code null}
7563 * @see #concatMapSingle(Function)
7564 * @see #concatMapSingleDelayError(Function, boolean)
7565 * @since 2.2
7566 */
7567 @CheckReturnValue
7568 @SchedulerSupport(SchedulerSupport.NONE)
7569 @NonNull
7570 public final <@NonNull R> Observable<R> concatMapSingleDelayError(@NonNull Function<? super T, ? extends SingleSource<? extends R>> mapper) {
7571 return concatMapSingleDelayError(mapper, true, 2);
7572 }
7573
7574 /**
7575 * Maps the upstream items into {@link SingleSource}s and subscribes to them one after the
7576 * other succeeds or fails, emits their success values and optionally delays all errors
7577 * till both the current {@code Observable} and all inner {@code SingleSource}s terminate.
7578 * <p>
7579 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/concatMap.v3.png" alt="">
7580 * <dl>
7581 * <dt><b>Scheduler:</b></dt>
7582 * <dd>{@code concatMapSingleDelayError} does not operate by default on a particular {@link Scheduler}.</dd>
7583 * </dl>
7584 * <p>History: 2.1.11 - experimental
7585 * @param <R> the result type of the inner {@code SingleSource}s
7586 * @param mapper the function called with the upstream item and should return
7587 * a {@code SingleSource} to become the next source to
7588 * be subscribed to
7589 * @param tillTheEnd If {@code true}, errors from the current {@code Observable} or any of the
7590 * inner {@code SingleSource}s are delayed until all
7591 * of them terminate. If {@code false}, an error from the current
7592 * {@code Observable} is delayed until the current inner
7593 * {@code SingleSource} terminates and only then is
7594 * it emitted to the downstream.
7595 * @return the new {@code Observable} instance
7596 * @throws NullPointerException if {@code mapper} is {@code null}
7597 * @see #concatMapSingle(Function, int)
7598 * @see #concatMapSingleDelayError(Function, boolean, int)
7599 * @since 2.2
7600 */
7601 @CheckReturnValue
7602 @SchedulerSupport(SchedulerSupport.NONE)
7603 @NonNull
7604 public final <@NonNull R> Observable<R> concatMapSingleDelayError(@NonNull Function<? super T, ? extends SingleSource<? extends R>> mapper, boolean tillTheEnd) {
7605 return concatMapSingleDelayError(mapper, tillTheEnd, 2);
7606 }
7607
7608 /**
7609 * Maps the upstream items into {@link SingleSource}s and subscribes to them one after the
7610 * other succeeds or fails, emits their success values and optionally delays errors
7611 * till both the current {@code Observable} and all inner {@code SingleSource}s terminate.
7612 * <p>
7613 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/concatMap.v3.png" alt="">
7614 * <dl>
7615 * <dt><b>Scheduler:</b></dt>
7616 * <dd>{@code concatMapSingleDelayError} does not operate by default on a particular {@link Scheduler}.</dd>
7617 * </dl>
7618 * <p>History: 2.1.11 - experimental
7619 * @param <R> the result type of the inner {@code SingleSource}s
7620 * @param mapper the function called with the upstream item and should return
7621 * a {@code SingleSource} to become the next source to
7622 * be subscribed to
7623 * @param tillTheEnd If {@code true}, errors from the current {@code Observable} or any of the
7624 * inner {@code SingleSource}s are delayed until all
7625 * of them terminate. If {@code false}, an error from the current
7626 * {@code Observable} is delayed until the current inner
7627 * {@code SingleSource} terminates and only then is
7628 * it emitted to the downstream.
7629 * @param bufferSize The number of upstream items expected to be buffered so that fresh items are
7630 * ready to be mapped when a previous {@code SingleSource} terminates.
7631 * @return the new {@code Observable} instance
7632 * @throws NullPointerException if {@code mapper} is {@code null}
7633 * @throws IllegalArgumentException if {@code bufferSize} is non-positive
7634 * @see #concatMapSingle(Function, int)
7635 * @since 2.2
7636 */
7637 @CheckReturnValue
7638 @SchedulerSupport(SchedulerSupport.NONE)
7639 @NonNull
7640 public final <@NonNull R> Observable<R> concatMapSingleDelayError(@NonNull Function<? super T, ? extends SingleSource<? extends R>> mapper, boolean tillTheEnd, int bufferSize) {
7641 Objects.requireNonNull(mapper, "mapper is null");
7642 ObjectHelper.verifyPositive(bufferSize, "bufferSize");
7643 return RxJavaPlugins.onAssembly(new ObservableConcatMapSingle<>(this, mapper, tillTheEnd ? ErrorMode.END : ErrorMode.BOUNDARY, bufferSize));
7644 }
7645
7646 /**
7647 * Returns an {@code Observable} that first emits the items emitted from the current {@code Observable}, then items
7648 * from the {@code other} {@link ObservableSource} without interleaving them.
7649 * <p>
7650 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/concat.v3.png" alt="">
7651 * <dl>
7652 * <dt><b>Scheduler:</b></dt>
7653 * <dd>{@code concatWith} does not operate by default on a particular {@link Scheduler}.</dd>
7654 * </dl>
7655 *
7656 * @param other
7657 * an {@code ObservableSource} to be concatenated after the current
7658 * @return the new {@code Observable} instance
7659 * @throws NullPointerException if {@code other} is {@code null}
7660 * @see <a href="http://reactivex.io/documentation/operators/concat.html">ReactiveX operators documentation: Concat</a>
7661 */
7662 @CheckReturnValue
7663 @SchedulerSupport(SchedulerSupport.NONE)
7664 @NonNull
7665 public final Observable<T> concatWith(@NonNull ObservableSource<? extends T> other) {
7666 Objects.requireNonNull(other, "other is null");
7667 return concat(this, other);
7668 }
7669
7670 /**
7671 * Returns an {@code Observable} that emits the items from the current {@code Observable} followed by the success item or error event
7672 * of the {@code other} {@link SingleSource}.
7673 * <p>
7674 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/concat.v3.png" alt="">
7675 * <dl>
7676 * <dt><b>Scheduler:</b></dt>
7677 * <dd>{@code concatWith} does not operate by default on a particular {@link Scheduler}.</dd>
7678 * </dl>
7679 * <p>History: 2.1.10 - experimental
7680 * @param other the {@code SingleSource} whose signal should be emitted after the current {@code Observable} completes normally.
7681 * @return the new {@code Observable} instance
7682 * @throws NullPointerException if {@code other} is {@code null}
7683 * @since 2.2
7684 */
7685 @CheckReturnValue
7686 @SchedulerSupport(SchedulerSupport.NONE)
7687 @NonNull
7688 public final Observable<T> concatWith(@NonNull SingleSource<? extends T> other) {
7689 Objects.requireNonNull(other, "other is null");
7690 return RxJavaPlugins.onAssembly(new ObservableConcatWithSingle<>(this, other));
7691 }
7692
7693 /**
7694 * Returns an {@code Observable} that emits the items from the current {@code Observable} followed by the success item or terminal events
7695 * of the other {@link MaybeSource}.
7696 * <p>
7697 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/concat.v3.png" alt="">
7698 * <dl>
7699 * <dt><b>Scheduler:</b></dt>
7700 * <dd>{@code concatWith} does not operate by default on a particular {@link Scheduler}.</dd>
7701 * </dl>
7702 * <p>History: 2.1.10 - experimental
7703 * @param other the {@code MaybeSource} whose signal should be emitted after the current {@code Observable} completes normally.
7704 * @return the new {@code Observable} instance
7705 * @throws NullPointerException if {@code other} is {@code null}
7706 * @since 2.2
7707 */
7708 @CheckReturnValue
7709 @SchedulerSupport(SchedulerSupport.NONE)
7710 @NonNull
7711 public final Observable<T> concatWith(@NonNull MaybeSource<? extends T> other) {
7712 Objects.requireNonNull(other, "other is null");
7713 return RxJavaPlugins.onAssembly(new ObservableConcatWithMaybe<>(this, other));
7714 }
7715
7716 /**
7717 * Returns an {@code Observable} that emits items from the current {@code Observable} and when it completes normally, the
7718 * other {@link CompletableSource} is subscribed to and the returned {@code Observable} emits its terminal events.
7719 * <p>
7720 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/concat.v3.png" alt="">
7721 * <dl>
7722 * <dt><b>Scheduler:</b></dt>
7723 * <dd>{@code concatWith} does not operate by default on a particular {@link Scheduler}.</dd>
7724 * </dl>
7725 * <p>History: 2.1.10 - experimental
7726 * @param other the {@code CompletableSource} to subscribe to once the current {@code Observable} completes normally
7727 * @return the new {@code Observable} instance
7728 * @throws NullPointerException if {@code other} is {@code null}
7729 * @since 2.2
7730 */
7731 @CheckReturnValue
7732 @SchedulerSupport(SchedulerSupport.NONE)
7733 @NonNull
7734 public final Observable<T> concatWith(@NonNull CompletableSource other) {
7735 Objects.requireNonNull(other, "other is null");
7736 return RxJavaPlugins.onAssembly(new ObservableConcatWithCompletable<>(this, other));
7737 }
7738
7739 /**
7740 * Returns a {@link Single} that emits a {@link Boolean} that indicates whether the current {@code Observable} emitted a
7741 * specified item.
7742 * <p>
7743 * <img width="640" height="320" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/contains.2.v3.png" alt="">
7744 * <dl>
7745 * <dt><b>Scheduler:</b></dt>
7746 * <dd>{@code contains} does not operate by default on a particular {@link Scheduler}.</dd>
7747 * </dl>
7748 *
7749 * @param item
7750 * the item to search for in the emissions from the current {@code Observable}
7751 * @return the new {@code Single} instance
7752 * @throws NullPointerException if {@code item} is {@code null}
7753 * @see <a href="http://reactivex.io/documentation/operators/contains.html">ReactiveX operators documentation: Contains</a>
7754 */
7755 @CheckReturnValue
7756 @SchedulerSupport(SchedulerSupport.NONE)
7757 @NonNull
7758 public final Single<Boolean> contains(@NonNull Object item) {
7759 Objects.requireNonNull(item, "item is null");
7760 return any(Functions.equalsWith(item));
7761 }
7762
7763 /**
7764 * Returns a {@link Single} that counts the total number of items emitted by the current {@code Observable} and emits
7765 * this count as a 64-bit {@link Long}.
7766 * <p>
7767 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/count.2.v3.png" alt="">
7768 * <dl>
7769 * <dt><b>Scheduler:</b></dt>
7770 * <dd>{@code count} does not operate by default on a particular {@link Scheduler}.</dd>
7771 * </dl>
7772 *
7773 * @return the new {@code Single} instance
7774 * @see <a href="http://reactivex.io/documentation/operators/count.html">ReactiveX operators documentation: Count</a>
7775 */
7776 @CheckReturnValue
7777 @SchedulerSupport(SchedulerSupport.NONE)
7778 @NonNull
7779 public final Single<Long> count() {
7780 return RxJavaPlugins.onAssembly(new ObservableCountSingle<>(this));
7781 }
7782
7783 /**
7784 * Returns an {@code Observable} that mirrors the current {@code Observable}, except that it drops items emitted by the
7785 * current {@code Observable} that are followed by another item within a computed debounce duration
7786 * denoted by an item emission or completion from a generated inner {@link ObservableSource} for that original item.
7787 * <p>
7788 * <img width="640" height="425" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/debounce.f.v3.png" alt="">
7789 * <p>
7790 * The delivery of the item happens on the thread of the first {@code onNext} or {@code onComplete}
7791 * signal of the generated {@code ObservableSource} sequence,
7792 * which if takes too long, a newer item may arrive from the upstream, causing the
7793 * generated sequence to get disposed, which may also interrupt any downstream blocking operation
7794 * (yielding an {@code InterruptedException}). It is recommended processing items
7795 * that may take long time to be moved to another thread via {@link #observeOn} applied after
7796 * {@code debounce} itself.
7797 * <dl>
7798 * <dt><b>Scheduler:</b></dt>
7799 * <dd>This version of {@code debounce} does not operate by default on a particular {@link Scheduler}.</dd>
7800 * </dl>
7801 *
7802 * @param <U>
7803 * the debounce value type (ignored)
7804 * @param debounceIndicator
7805 * function to return a sequence that indicates the throttle duration for each item via its own emission or completion
7806 * @return the new {@code Observable} instance
7807 * @throws NullPointerException if {@code debounceIndicator} is {@code null}
7808 * @see <a href="http://reactivex.io/documentation/operators/debounce.html">ReactiveX operators documentation: Debounce</a>
7809 */
7810 @CheckReturnValue
7811 @SchedulerSupport(SchedulerSupport.NONE)
7812 @NonNull
7813 public final <@NonNull U> Observable<T> debounce(@NonNull Function<? super T, ? extends ObservableSource<U>> debounceIndicator) {
7814 Objects.requireNonNull(debounceIndicator, "debounceIndicator is null");
7815 return RxJavaPlugins.onAssembly(new ObservableDebounce<>(this, debounceIndicator));
7816 }
7817
7818 /**
7819 * Returns an {@code Observable} that mirrors the current {@code Observable}, except that it drops items emitted by the
7820 * current {@code Observable} that are followed by newer items before a timeout value expires. The timer resets on
7821 * each emission.
7822 * <p>
7823 * <em>Note:</em> If items keep being emitted by the current {@code Observable} faster than the timeout then no items
7824 * will be emitted by the resulting {@code Observable}.
7825 * <p>
7826 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/debounce.v3.png" alt="">
7827 * <p>
7828 * Delivery of the item after the grace period happens on the {@code computation} {@link Scheduler}'s
7829 * {@code Worker} which if takes too long, a newer item may arrive from the upstream, causing the
7830 * {@code Worker}'s task to get disposed, which may also interrupt any downstream blocking operation
7831 * (yielding an {@code InterruptedException}). It is recommended processing items
7832 * that may take long time to be moved to another thread via {@link #observeOn} applied after
7833 * {@code debounce} itself.
7834 * <dl>
7835 * <dt><b>Scheduler:</b></dt>
7836 * <dd>{@code debounce} operates by default on the {@code computation} {@code Scheduler}.</dd>
7837 * </dl>
7838 *
7839 * @param timeout
7840 * the length of the window of time that must pass after the emission of an item from the current
7841 * {@code Observable} in which the {@code Observable} emits no items in order for the item to be emitted by the
7842 * resulting {@code Observable}
7843 * @param unit
7844 * the unit of time for the specified {@code timeout}
7845 * @return the new {@code Observable} instance
7846 * @throws NullPointerException if {@code unit} is {@code null}
7847 * @see <a href="http://reactivex.io/documentation/operators/debounce.html">ReactiveX operators documentation: Debounce</a>
7848 * @see #throttleWithTimeout(long, TimeUnit)
7849 */
7850 @CheckReturnValue
7851 @SchedulerSupport(SchedulerSupport.COMPUTATION)
7852 @NonNull
7853 public final Observable<T> debounce(long timeout, @NonNull TimeUnit unit) {
7854 return debounce(timeout, unit, Schedulers.computation());
7855 }
7856
7857 /**
7858 * Returns an {@code Observable} that mirrors the current {@code Observable}, except that it drops items emitted by the
7859 * current {@code Observable} that are followed by newer items before a timeout value expires on a specified
7860 * {@link Scheduler}. The timer resets on each emission.
7861 * <p>
7862 * <em>Note:</em> If items keep being emitted by the current {@code Observable} faster than the timeout then no items
7863 * will be emitted by the resulting {@code Observable}.
7864 * <p>
7865 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/debounce.s.v3.png" alt="">
7866 * <p>
7867 * Delivery of the item after the grace period happens on the given {@code Scheduler}'s
7868 * {@code Worker} which if takes too long, a newer item may arrive from the upstream, causing the
7869 * {@code Worker}'s task to get disposed, which may also interrupt any downstream blocking operation
7870 * (yielding an {@code InterruptedException}). It is recommended processing items
7871 * that may take long time to be moved to another thread via {@link #observeOn} applied after
7872 * {@code debounce} itself.
7873 * <dl>
7874 * <dt><b>Scheduler:</b></dt>
7875 * <dd>You specify which {@code Scheduler} this operator will use.</dd>
7876 * </dl>
7877 *
7878 * @param timeout
7879 * the time each item has to be "the most recent" of those emitted by the current {@code Observable} to
7880 * ensure that it's not dropped
7881 * @param unit
7882 * the unit of time for the specified {@code timeout}
7883 * @param scheduler
7884 * the {@code Scheduler} to use internally to manage the timers that handle the timeout for each
7885 * item
7886 * @return the new {@code Observable} instance
7887 * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null}
7888 * @see <a href="http://reactivex.io/documentation/operators/debounce.html">ReactiveX operators documentation: Debounce</a>
7889 * @see #throttleWithTimeout(long, TimeUnit, Scheduler)
7890 */
7891 @CheckReturnValue
7892 @SchedulerSupport(SchedulerSupport.CUSTOM)
7893 @NonNull
7894 public final Observable<T> debounce(long timeout, @NonNull TimeUnit unit, @NonNull Scheduler scheduler) {
7895 Objects.requireNonNull(unit, "unit is null");
7896 Objects.requireNonNull(scheduler, "scheduler is null");
7897 return RxJavaPlugins.onAssembly(new ObservableDebounceTimed<>(this, timeout, unit, scheduler));
7898 }
7899
7900 /**
7901 * Returns an {@code Observable} that emits the items emitted by the current {@code Observable} or a specified default item
7902 * if the current {@code Observable} is empty.
7903 * <p>
7904 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/defaultIfEmpty.v3.png" alt="">
7905 * <dl>
7906 * <dt><b>Scheduler:</b></dt>
7907 * <dd>{@code defaultIfEmpty} does not operate by default on a particular {@link Scheduler}.</dd>
7908 * </dl>
7909 *
7910 * @param defaultItem
7911 * the item to emit if the current {@code Observable} emits no items
7912 * @return the new {@code Observable} instance
7913 * @throws NullPointerException if {@code defaultItem} is {@code null}
7914 * @see <a href="http://reactivex.io/documentation/operators/defaultifempty.html">ReactiveX operators documentation: DefaultIfEmpty</a>
7915 */
7916 @CheckReturnValue
7917 @SchedulerSupport(SchedulerSupport.NONE)
7918 @NonNull
7919 public final Observable<T> defaultIfEmpty(@NonNull T defaultItem) {
7920 Objects.requireNonNull(defaultItem, "defaultItem is null");
7921 return switchIfEmpty(just(defaultItem));
7922 }
7923
7924 /**
7925 * Returns an {@code Observable} that delays the emissions of the current {@code Observable} via
7926 * a per-item derived {@link ObservableSource}'s item emission or termination, on a per source item basis.
7927 * <p>
7928 * <img width="640" height="450" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/delay.o.v3.png" alt="">
7929 * <p>
7930 * <em>Note:</em> the resulting {@code Observable} will immediately propagate any {@code onError} notification
7931 * from the current {@code Observable}.
7932 * <dl>
7933 * <dt><b>Scheduler:</b></dt>
7934 * <dd>This version of {@code delay} does not operate by default on a particular {@link Scheduler}.</dd>
7935 * </dl>
7936 *
7937 * @param <U>
7938 * the item delay value type (ignored)
7939 * @param itemDelayIndicator
7940 * a function that returns an {@code ObservableSource} for each item emitted by the current {@code Observable}, which is
7941 * then used to delay the emission of that item by the resulting {@code Observable} until the {@code ObservableSource}
7942 * returned from {@code itemDelay} emits an item
7943 * @return the new {@code Observable} instance
7944 * @throws NullPointerException if {@code itemDelayIndicator} is {@code null}
7945 * @see <a href="http://reactivex.io/documentation/operators/delay.html">ReactiveX operators documentation: Delay</a>
7946 */
7947 @CheckReturnValue
7948 @SchedulerSupport(SchedulerSupport.NONE)
7949 @NonNull
7950 public final <@NonNull U> Observable<T> delay(@NonNull Function<? super T, ? extends ObservableSource<U>> itemDelayIndicator) {
7951 Objects.requireNonNull(itemDelayIndicator, "itemDelayIndicator is null");
7952 return flatMap(ObservableInternalHelper.itemDelay(itemDelayIndicator));
7953 }
7954
7955 /**
7956 * Returns an {@code Observable} that emits the items emitted by the current {@code Observable} shifted forward in time by a
7957 * specified delay. An error notification from the current {@code Observable} is not delayed.
7958 * <p>
7959 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/delay.v3.png" alt="">
7960 * <dl>
7961 * <dt><b>Scheduler:</b></dt>
7962 * <dd>This version of {@code delay} operates by default on the {@code computation} {@link Scheduler}.</dd>
7963 * </dl>
7964 *
7965 * @param time
7966 * the delay to shift the source by
7967 * @param unit
7968 * the {@link TimeUnit} in which {@code period} is defined
7969 * @return the new {@code Observable} instance
7970 * @throws NullPointerException if {@code unit} is {@code null}
7971 * @see <a href="http://reactivex.io/documentation/operators/delay.html">ReactiveX operators documentation: Delay</a>
7972 * @see #delay(long, TimeUnit, boolean)
7973 * @see #delay(long, TimeUnit, Scheduler)
7974 */
7975 @CheckReturnValue
7976 @SchedulerSupport(SchedulerSupport.COMPUTATION)
7977 @NonNull
7978 public final Observable<T> delay(long time, @NonNull TimeUnit unit) {
7979 return delay(time, unit, Schedulers.computation(), false);
7980 }
7981
7982 /**
7983 * Returns an {@code Observable} that emits the items emitted by the current {@code Observable} shifted forward in time by a
7984 * specified delay. If {@code delayError} is {@code true}, error notifications will also be delayed.
7985 * <p>
7986 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/delay.v3.png" alt="">
7987 * <dl>
7988 * <dt><b>Scheduler:</b></dt>
7989 * <dd>This version of {@code delay} operates by default on the {@code computation} {@link Scheduler}.</dd>
7990 * </dl>
7991 *
7992 * @param time
7993 * the delay to shift the source by
7994 * @param unit
7995 * the {@link TimeUnit} in which {@code period} is defined
7996 * @param delayError
7997 * if {@code true}, the upstream exception is signaled with the given delay, after all preceding normal elements,
7998 * if {@code false}, the upstream exception is signaled immediately
7999 * @return the new {@code Observable} instance
8000 * @throws NullPointerException if {@code unit} is {@code null}
8001 * @see <a href="http://reactivex.io/documentation/operators/delay.html">ReactiveX operators documentation: Delay</a>
8002 * @see #delay(long, TimeUnit, Scheduler, boolean)
8003 */
8004 @CheckReturnValue
8005 @SchedulerSupport(SchedulerSupport.COMPUTATION)
8006 @NonNull
8007 public final Observable<T> delay(long time, @NonNull TimeUnit unit, boolean delayError) {
8008 return delay(time, unit, Schedulers.computation(), delayError);
8009 }
8010
8011 /**
8012 * Returns an {@code Observable} that emits the items emitted by the current {@code Observable} shifted forward in time by a
8013 * specified delay. An error notification from the current {@code Observable} is not delayed.
8014 * <p>
8015 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/delay.s.v3.png" alt="">
8016 * <dl>
8017 * <dt><b>Scheduler:</b></dt>
8018 * <dd>You specify which {@link Scheduler} this operator will use.</dd>
8019 * </dl>
8020 *
8021 * @param time
8022 * the delay to shift the source by
8023 * @param unit
8024 * the time unit of {@code delay}
8025 * @param scheduler
8026 * the {@code Scheduler} to use for delaying
8027 * @return the new {@code Observable} instance
8028 * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null}
8029 * @see <a href="http://reactivex.io/documentation/operators/delay.html">ReactiveX operators documentation: Delay</a>
8030 */
8031 @CheckReturnValue
8032 @SchedulerSupport(SchedulerSupport.CUSTOM)
8033 @NonNull
8034 public final Observable<T> delay(long time, @NonNull TimeUnit unit, @NonNull Scheduler scheduler) {
8035 return delay(time, unit, scheduler, false);
8036 }
8037
8038 /**
8039 * Returns an {@code Observable} that emits the items emitted by the current {@code Observable} shifted forward in time by a
8040 * specified delay. If {@code delayError} is {@code true}, error notifications will also be delayed.
8041 * <p>
8042 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/delay.s.v3.png" alt="">
8043 * <dl>
8044 * <dt><b>Scheduler:</b></dt>
8045 * <dd>You specify which {@link Scheduler} this operator will use.</dd>
8046 * </dl>
8047 *
8048 * @param time
8049 * the delay to shift the source by
8050 * @param unit
8051 * the time unit of {@code delay}
8052 * @param scheduler
8053 * the {@code Scheduler} to use for delaying
8054 * @param delayError
8055 * if {@code true}, the upstream exception is signaled with the given delay, after all preceding normal elements,
8056 * if {@code false}, the upstream exception is signaled immediately
8057 * @return the new {@code Observable} instance
8058 * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null}
8059 * @see <a href="http://reactivex.io/documentation/operators/delay.html">ReactiveX operators documentation: Delay</a>
8060 */
8061 @CheckReturnValue
8062 @SchedulerSupport(SchedulerSupport.CUSTOM)
8063 @NonNull
8064 public final Observable<T> delay(long time, @NonNull TimeUnit unit, @NonNull Scheduler scheduler, boolean delayError) {
8065 Objects.requireNonNull(unit, "unit is null");
8066 Objects.requireNonNull(scheduler, "scheduler is null");
8067
8068 return RxJavaPlugins.onAssembly(new ObservableDelay<>(this, time, unit, scheduler, delayError));
8069 }
8070
8071 /**
8072 * Returns an {@code Observable} that delays the subscription to and emissions from the current {@code Observable} via
8073 * {@link ObservableSource}s for the subscription itself and on a per-item basis.
8074 * <p>
8075 * <img width="640" height="450" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/delay.oo.v3.png" alt="">
8076 * <p>
8077 * <em>Note:</em> the resulting {@code Observable} will immediately propagate any {@code onError} notification
8078 * from the current {@code Observable}.
8079 * <dl>
8080 * <dt><b>Scheduler:</b></dt>
8081 * <dd>This version of {@code delay} does not operate by default on a particular {@link Scheduler}.</dd>
8082 * </dl>
8083 *
8084 * @param <U>
8085 * the subscription delay value type (ignored)
8086 * @param <V>
8087 * the item delay value type (ignored)
8088 * @param subscriptionIndicator
8089 * a function that returns an {@code ObservableSource} that triggers the subscription to the current {@code Observable}
8090 * once it emits any item
8091 * @param itemDelayIndicator
8092 * a function that returns an {@code ObservableSource} for each item emitted by the current {@code Observable}, which is
8093 * then used to delay the emission of that item by the resulting {@code Observable} until the {@code ObservableSource}
8094 * returned from {@code itemDelay} emits an item
8095 * @return the new {@code Observable} instance
8096 * @throws NullPointerException if {@code subscriptionIndicator} or {@code itemDelayIndicator} is {@code null}
8097 * @see <a href="http://reactivex.io/documentation/operators/delay.html">ReactiveX operators documentation: Delay</a>
8098 */
8099 @CheckReturnValue
8100 @SchedulerSupport(SchedulerSupport.NONE)
8101 @NonNull
8102 public final <@NonNull U, @NonNull V> Observable<T> delay(@NonNull ObservableSource<U> subscriptionIndicator,
8103 @NonNull Function<? super T, ? extends ObservableSource<V>> itemDelayIndicator) {
8104 return delaySubscription(subscriptionIndicator).delay(itemDelayIndicator);
8105 }
8106
8107 /**
8108 * Returns an {@code Observable} that delays the subscription to the current {@code Observable}
8109 * until the other {@link ObservableSource} emits an element or completes normally.
8110 * <p>
8111 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/delaySubscription.o.v3.png" alt="">
8112 * <dl>
8113 * <dt><b>Scheduler:</b></dt>
8114 * <dd>This method does not operate by default on a particular {@link Scheduler}.</dd>
8115 * </dl>
8116 *
8117 * @param <U> the value type of the other {@code Observable}, irrelevant
8118 * @param subscriptionIndicator the other {@code ObservableSource} that should trigger the subscription
8119 * to the current {@code Observable}.
8120 * @return the new {@code Observable} instance
8121 * @throws NullPointerException if {@code subscriptionIndicator} is {@code null}
8122 * @since 2.0
8123 */
8124 @CheckReturnValue
8125 @SchedulerSupport(SchedulerSupport.NONE)
8126 @NonNull
8127 public final <@NonNull U> Observable<T> delaySubscription(@NonNull ObservableSource<U> subscriptionIndicator) {
8128 Objects.requireNonNull(subscriptionIndicator, "subscriptionIndicator is null");
8129 return RxJavaPlugins.onAssembly(new ObservableDelaySubscriptionOther<>(this, subscriptionIndicator));
8130 }
8131
8132 /**
8133 * Returns an {@code Observable} that delays the subscription to the current {@code Observable} by a given amount of time.
8134 * <p>
8135 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/delaySubscription.v3.png" alt="">
8136 * <dl>
8137 * <dt><b>Scheduler:</b></dt>
8138 * <dd>This version of {@code delaySubscription} operates by default on the {@code computation} {@link Scheduler}.</dd>
8139 * </dl>
8140 *
8141 * @param time
8142 * the time to delay the subscription
8143 * @param unit
8144 * the time unit of {@code delay}
8145 * @return the new {@code Observable} instance
8146 * @throws NullPointerException if {@code unit} is {@code null}
8147 * @see <a href="http://reactivex.io/documentation/operators/delay.html">ReactiveX operators documentation: Delay</a>
8148 */
8149 @CheckReturnValue
8150 @SchedulerSupport(SchedulerSupport.COMPUTATION)
8151 @NonNull
8152 public final Observable<T> delaySubscription(long time, @NonNull TimeUnit unit) {
8153 return delaySubscription(time, unit, Schedulers.computation());
8154 }
8155
8156 /**
8157 * Returns an {@code Observable} that delays the subscription to the current {@code Observable} by a given amount of time,
8158 * both waiting and subscribing on a given {@link Scheduler}.
8159 * <p>
8160 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/delaySubscription.s.v3.png" alt="">
8161 * <dl>
8162 * <dt><b>Scheduler:</b></dt>
8163 * <dd>You specify which {@code Scheduler} this operator will use.</dd>
8164 * </dl>
8165 *
8166 * @param time
8167 * the time to delay the subscription
8168 * @param unit
8169 * the time unit of {@code delay}
8170 * @param scheduler
8171 * the {@code Scheduler} on which the waiting and subscription will happen
8172 * @return the new {@code Observable} instance
8173 * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null}
8174 * @see <a href="http://reactivex.io/documentation/operators/delay.html">ReactiveX operators documentation: Delay</a>
8175 */
8176 @CheckReturnValue
8177 @SchedulerSupport(SchedulerSupport.CUSTOM)
8178 @NonNull
8179 public final Observable<T> delaySubscription(long time, @NonNull TimeUnit unit, @NonNull Scheduler scheduler) {
8180 return delaySubscription(timer(time, unit, scheduler));
8181 }
8182
8183 /**
8184 * Returns an {@code Observable} that reverses the effect of {@link #materialize materialize} by transforming the
8185 * {@link Notification} objects extracted from the source items via a selector function
8186 * into their respective {@link Observer} signal types.
8187 * <p>
8188 * <img width="640" height="335" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/dematerialize.v3.png" alt="">
8189 * <p>
8190 * The intended use of the {@code selector} function is to perform a
8191 * type-safe identity mapping (see example) on a source that is already of type
8192 * {@code Notification<T>}. The Java language doesn't allow
8193 * limiting instance methods to a certain generic argument shape, therefore,
8194 * a function is used to ensure the conversion remains type safe.
8195 * <p>
8196 * When the upstream signals an {@link Notification#createOnError(Throwable) onError} or
8197 * {@link Notification#createOnComplete() onComplete} item, the
8198 * returned {@code Observable} disposes of the flow and terminates with that type of terminal event:
8199 * <pre><code>
8200 * Observable.just(createOnNext(1), createOnComplete(), createOnNext(2))
8201 * .doOnDispose(() -&gt; System.out.println("Disposed!"));
8202 * .dematerialize(notification -&gt; notification)
8203 * .test()
8204 * .assertResult(1);
8205 * </code></pre>
8206 * If the upstream signals {@code onError} or {@code onComplete} directly, the flow is terminated
8207 * with the same event.
8208 * <pre><code>
8209 * Observable.just(createOnNext(1), createOnNext(2))
8210 * .dematerialize(notification -&gt; notification)
8211 * .test()
8212 * .assertResult(1, 2);
8213 * </code></pre>
8214 * If this behavior is not desired, the completion can be suppressed by applying {@link #concatWith(ObservableSource)}
8215 * with a {@link #never()} source.
8216 * <dl>
8217 * <dt><b>Scheduler:</b></dt>
8218 * <dd>{@code dematerialize} does not operate by default on a particular {@link Scheduler}.</dd>
8219 * </dl>
8220 * <p>History: 2.2.4 - experimental
8221 *
8222 * @param <R> the output value type
8223 * @param selector function that returns the upstream item and should return a {@code Notification} to signal
8224 * the corresponding {@code Observer} event to the downstream.
8225 * @return the new {@code Observable} instance
8226 * @throws NullPointerException if {@code selector} is {@code null}
8227 * @see <a href="http://reactivex.io/documentation/operators/materialize-dematerialize.html">ReactiveX operators documentation: Dematerialize</a>
8228 * @since 3.0.0
8229 */
8230 @CheckReturnValue
8231 @SchedulerSupport(SchedulerSupport.NONE)
8232 @NonNull
8233 public final <@NonNull R> Observable<R> dematerialize(@NonNull Function<? super T, Notification<R>> selector) {
8234 Objects.requireNonNull(selector, "selector is null");
8235 return RxJavaPlugins.onAssembly(new ObservableDematerialize<>(this, selector));
8236 }
8237
8238 /**
8239 * Returns an {@code Observable} that emits all items emitted by the current {@code Observable} that are distinct
8240 * based on {@link Object#equals(Object)} comparison.
8241 * <p>
8242 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/distinct.v3.png" alt="">
8243 * <p>
8244 * It is recommended the elements' class {@code T} in the flow overrides the default {@code Object.equals()}
8245 * and {@link Object#hashCode()} to provide meaningful comparison between items as the default Java
8246 * implementation only considers reference equivalence.
8247 * <p>
8248 * By default, {@code distinct()} uses an internal {@link HashSet} per {@link Observer} to remember
8249 * previously seen items and uses {@link java.util.Set#add(Object)} returning {@code false} as the
8250 * indicator for duplicates.
8251 * <p>
8252 * Note that this internal {@code HashSet} may grow unbounded as items won't be removed from it by
8253 * the operator. Therefore, using very long or infinite upstream (with very distinct elements) may lead
8254 * to {@link OutOfMemoryError}.
8255 * <p>
8256 * Customizing the retention policy can happen only by providing a custom {@link java.util.Collection} implementation
8257 * to the {@link #distinct(Function, Supplier)} overload.
8258 * <dl>
8259 * <dt><b>Scheduler:</b></dt>
8260 * <dd>{@code distinct} does not operate by default on a particular {@link Scheduler}.</dd>
8261 * </dl>
8262 *
8263 * @return the new {@code Observable} instance
8264 * @see <a href="http://reactivex.io/documentation/operators/distinct.html">ReactiveX operators documentation: Distinct</a>
8265 * @see #distinct(Function)
8266 * @see #distinct(Function, Supplier)
8267 */
8268 @CheckReturnValue
8269 @SchedulerSupport(SchedulerSupport.NONE)
8270 @NonNull
8271 public final Observable<T> distinct() {
8272 return distinct(Functions.identity(), Functions.createHashSet());
8273 }
8274
8275 /**
8276 * Returns an {@code Observable} that emits all items emitted by the current {@code Observable} that are distinct according
8277 * to a key selector function and based on {@link Object#equals(Object)} comparison of the objects
8278 * returned by the key selector function.
8279 * <p>
8280 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/distinct.key.v3.png" alt="">
8281 * <p>
8282 * It is recommended the keys' class {@code K} overrides the default {@code Object.equals()}
8283 * and {@link Object#hashCode()} to provide meaningful comparison between the key objects as the default
8284 * Java implementation only considers reference equivalence.
8285 * <p>
8286 * By default, {@code distinct()} uses an internal {@link HashSet} per {@link Observer} to remember
8287 * previously seen keys and uses {@link java.util.Set#add(Object)} returning {@code false} as the
8288 * indicator for duplicates.
8289 * <p>
8290 * Note that this internal {@code HashSet} may grow unbounded as keys won't be removed from it by
8291 * the operator. Therefore, using very long or infinite upstream (with very distinct keys) may lead
8292 * to {@link OutOfMemoryError}.
8293 * <p>
8294 * Customizing the retention policy can happen only by providing a custom {@link java.util.Collection} implementation
8295 * to the {@link #distinct(Function, Supplier)} overload.
8296 * <dl>
8297 * <dt><b>Scheduler:</b></dt>
8298 * <dd>{@code distinct} does not operate by default on a particular {@link Scheduler}.</dd>
8299 * </dl>
8300 *
8301 * @param <K> the key type
8302 * @param keySelector
8303 * a function that projects an emitted item to a key value that is used to decide whether an item
8304 * is distinct from another one or not
8305 * @return the new {@code Observable} instance
8306 * @throws NullPointerException if {@code keySelector} is {@code null}
8307 * @see <a href="http://reactivex.io/documentation/operators/distinct.html">ReactiveX operators documentation: Distinct</a>
8308 * @see #distinct(Function, Supplier)
8309 */
8310 @CheckReturnValue
8311 @SchedulerSupport(SchedulerSupport.NONE)
8312 @NonNull
8313 public final <@NonNull K> Observable<T> distinct(@NonNull Function<? super T, K> keySelector) {
8314 return distinct(keySelector, Functions.createHashSet());
8315 }
8316
8317 /**
8318 * Returns an {@code Observable} that emits all items emitted by the current {@code Observable} that are distinct according
8319 * to a key selector function and based on {@link Object#equals(Object)} comparison of the objects
8320 * returned by the key selector function.
8321 * <p>
8322 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/distinct.key.v3.png" alt="">
8323 * <p>
8324 * It is recommended the keys' class {@code K} overrides the default {@code Object.equals()}
8325 * and {@link Object#hashCode()} to provide meaningful comparison between the key objects as
8326 * the default Java implementation only considers reference equivalence.
8327 * <dl>
8328 * <dt><b>Scheduler:</b></dt>
8329 * <dd>{@code distinct} does not operate by default on a particular {@link Scheduler}.</dd>
8330 * </dl>
8331 *
8332 * @param <K> the key type
8333 * @param keySelector
8334 * a function that projects an emitted item to a key value that is used to decide whether an item
8335 * is distinct from another one or not
8336 * @param collectionSupplier
8337 * function called for each individual {@link Observer} to return a {@link Collection} subtype for holding the extracted
8338 * keys and whose {@code add()} method's return indicates uniqueness.
8339 * @return the new {@code Observable} instance
8340 * @throws NullPointerException if {@code keySelector} or {@code collectionSupplier} is {@code null}
8341 * @see <a href="http://reactivex.io/documentation/operators/distinct.html">ReactiveX operators documentation: Distinct</a>
8342 */
8343 @CheckReturnValue
8344 @SchedulerSupport(SchedulerSupport.NONE)
8345 @NonNull
8346 public final <@NonNull K> Observable<T> distinct(@NonNull Function<? super T, K> keySelector, @NonNull Supplier<? extends Collection<? super K>> collectionSupplier) {
8347 Objects.requireNonNull(keySelector, "keySelector is null");
8348 Objects.requireNonNull(collectionSupplier, "collectionSupplier is null");
8349 return RxJavaPlugins.onAssembly(new ObservableDistinct<>(this, keySelector, collectionSupplier));
8350 }
8351
8352 /**
8353 * Returns an {@code Observable} that emits all items emitted by the current {@code Observable} that are distinct from their
8354 * immediate predecessors based on {@link Object#equals(Object)} comparison.
8355 * <p>
8356 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/distinctUntilChanged.v3.png" alt="">
8357 * <p>
8358 * It is recommended the elements' class {@code T} in the flow overrides the default {@code Object.equals()} to provide
8359 * meaningful comparison between items as the default Java implementation only considers reference equivalence.
8360 * Alternatively, use the {@link #distinctUntilChanged(BiPredicate)} overload and provide a comparison function
8361 * in case the class {@code T} can't be overridden with custom {@code equals()} or the comparison itself
8362 * should happen on different terms or properties of the class {@code T}.
8363 * <p>
8364 * Note that the operator always retains the latest item from upstream regardless of the comparison result
8365 * and uses it in the next comparison with the next upstream item.
8366 * <p>
8367 * Note that if element type {@code T} in the flow is mutable, the comparison of the previous and current
8368 * item may yield unexpected results if the items are mutated externally. Common cases are mutable
8369 * {@link CharSequence}s or {@link List}s where the objects will actually have the same
8370 * references when they are modified and {@code distinctUntilChanged} will evaluate subsequent items as same.
8371 * To avoid such situation, it is recommended that mutable data is converted to an immutable one,
8372 * for example using {@code map(CharSequence::toString)} or {@code map(list -> Collections.unmodifiableList(new ArrayList<>(list)))}.
8373 * <dl>
8374 * <dt><b>Scheduler:</b></dt>
8375 * <dd>{@code distinctUntilChanged} does not operate by default on a particular {@link Scheduler}.</dd>
8376 * </dl>
8377 *
8378 * @return the new {@code Observable} instance
8379 * @see <a href="http://reactivex.io/documentation/operators/distinct.html">ReactiveX operators documentation: Distinct</a>
8380 * @see #distinctUntilChanged(BiPredicate)
8381 */
8382 @CheckReturnValue
8383 @SchedulerSupport(SchedulerSupport.NONE)
8384 @NonNull
8385 public final Observable<T> distinctUntilChanged() {
8386 return distinctUntilChanged(Functions.identity());
8387 }
8388
8389 /**
8390 * Returns an {@code Observable} that emits all items emitted by the current {@code Observable} that are distinct from their
8391 * immediate predecessors, according to a key selector function and based on {@link Object#equals(Object)} comparison
8392 * of those objects returned by the key selector function.
8393 * <p>
8394 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/distinctUntilChanged.key.v3.png" alt="">
8395 * <p>
8396 * It is recommended the keys' class {@code K} overrides the default {@code Object.equals()} to provide
8397 * meaningful comparison between the key objects as the default Java implementation only considers reference equivalence.
8398 * Alternatively, use the {@link #distinctUntilChanged(BiPredicate)} overload and provide a comparison function
8399 * in case the class {@code K} can't be overridden with custom {@code equals()} or the comparison itself
8400 * should happen on different terms or properties of the item class {@code T} (for which the keys can be
8401 * derived via a similar selector).
8402 * <p>
8403 * Note that the operator always retains the latest key from upstream regardless of the comparison result
8404 * and uses it in the next comparison with the next key derived from the next upstream item.
8405 * <p>
8406 * Note that if element type {@code T} in the flow is mutable, the comparison of the previous and current
8407 * item may yield unexpected results if the items are mutated externally. Common cases are mutable
8408 * {@link CharSequence}s or {@link List}s where the objects will actually have the same
8409 * references when they are modified and {@code distinctUntilChanged} will evaluate subsequent items as same.
8410 * To avoid such situation, it is recommended that mutable data is converted to an immutable one,
8411 * for example using {@code map(CharSequence::toString)} or {@code map(list -> Collections.unmodifiableList(new ArrayList<>(list)))}.
8412 * <dl>
8413 * <dt><b>Scheduler:</b></dt>
8414 * <dd>{@code distinctUntilChanged} does not operate by default on a particular {@link Scheduler}.</dd>
8415 * </dl>
8416 *
8417 * @param <K> the key type
8418 * @param keySelector
8419 * a function that projects an emitted item to a key value that is used to decide whether an item
8420 * is distinct from another one or not
8421 * @return the new {@code Observable} instance
8422 * @throws NullPointerException if {@code keySelector} is {@code null}
8423 * @see <a href="http://reactivex.io/documentation/operators/distinct.html">ReactiveX operators documentation: Distinct</a>
8424 */
8425 @CheckReturnValue
8426 @SchedulerSupport(SchedulerSupport.NONE)
8427 @NonNull
8428 public final <@NonNull K> Observable<T> distinctUntilChanged(@NonNull Function<? super T, K> keySelector) {
8429 Objects.requireNonNull(keySelector, "keySelector is null");
8430 return RxJavaPlugins.onAssembly(new ObservableDistinctUntilChanged<>(this, keySelector, ObjectHelper.equalsPredicate()));
8431 }
8432
8433 /**
8434 * Returns an {@code Observable} that emits all items emitted by the current {@code Observable} that are distinct from their
8435 * immediate predecessors when compared with each other via the provided comparator function.
8436 * <p>
8437 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/distinctUntilChanged.v3.png" alt="">
8438 * <p>
8439 * Note that the operator always retains the latest item from upstream regardless of the comparison result
8440 * and uses it in the next comparison with the next upstream item.
8441 * <p>
8442 * Note that if element type {@code T} in the flow is mutable, the comparison of the previous and current
8443 * item may yield unexpected results if the items are mutated externally. Common cases are mutable
8444 * {@link CharSequence}s or {@link List}s where the objects will actually have the same
8445 * references when they are modified and {@code distinctUntilChanged} will evaluate subsequent items as same.
8446 * To avoid such situation, it is recommended that mutable data is converted to an immutable one,
8447 * for example using {@code map(CharSequence::toString)} or {@code map(list -> Collections.unmodifiableList(new ArrayList<>(list)))}.
8448 * <dl>
8449 * <dt><b>Scheduler:</b></dt>
8450 * <dd>{@code distinctUntilChanged} does not operate by default on a particular {@link Scheduler}.</dd>
8451 * </dl>
8452 *
8453 * @param comparer the function that receives the previous item and the current item and is
8454 * expected to return {@code true} if the two are equal, thus skipping the current value.
8455 * @return the new {@code Observable} instance
8456 * @throws NullPointerException if {@code comparer} is {@code null}
8457 * @see <a href="http://reactivex.io/documentation/operators/distinct.html">ReactiveX operators documentation: Distinct</a>
8458 * @since 2.0
8459 */
8460 @CheckReturnValue
8461 @SchedulerSupport(SchedulerSupport.NONE)
8462 @NonNull
8463 public final Observable<T> distinctUntilChanged(@NonNull BiPredicate<? super T, ? super T> comparer) {
8464 Objects.requireNonNull(comparer, "comparer is null");
8465 return RxJavaPlugins.onAssembly(new ObservableDistinctUntilChanged<>(this, Functions.identity(), comparer));
8466 }
8467
8468 /**
8469 * Calls the specified {@link Consumer} with the current item after this item has been emitted to the downstream.
8470 * <p>
8471 * Note that the {@code onAfterNext} action is shared between subscriptions and as such
8472 * should be thread-safe.
8473 * <p>
8474 * <img width="640" height="360" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/doAfterNext.o.v3.png" alt="">
8475 * <dl>
8476 * <dt><b>Scheduler:</b></dt>
8477 * <dd>{@code doAfterNext} does not operate by default on a particular {@link Scheduler}.</dd>
8478 * <dt><b>Operator-fusion:</b></dt>
8479 * <dd>This operator supports boundary-limited synchronous or asynchronous queue-fusion.</dd>
8480 * </dl>
8481 * <p>History: 2.0.1 - experimental
8482 * @param onAfterNext the {@code Consumer} that will be called after emitting an item from upstream to the downstream
8483 * @return the new {@code Observable} instance
8484 * @throws NullPointerException if {@code onAfterNext} is {@code null}
8485 * @since 2.1
8486 */
8487 @CheckReturnValue
8488 @SchedulerSupport(SchedulerSupport.NONE)
8489 @NonNull
8490 public final Observable<T> doAfterNext(@NonNull Consumer<? super T> onAfterNext) {
8491 Objects.requireNonNull(onAfterNext, "onAfterNext is null");
8492 return RxJavaPlugins.onAssembly(new ObservableDoAfterNext<>(this, onAfterNext));
8493 }
8494
8495 /**
8496 * Registers an {@link Action} to be called when the current {@code Observable} invokes either
8497 * {@link Observer#onComplete onComplete} or {@link Observer#onError onError}.
8498 * <p>
8499 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/doAfterTerminate.v3.png" alt="">
8500 * <dl>
8501 * <dt><b>Scheduler:</b></dt>
8502 * <dd>{@code doAfterTerminate} does not operate by default on a particular {@link Scheduler}.</dd>
8503 * </dl>
8504 *
8505 * @param onAfterTerminate
8506 * an {@code Action} to be invoked after the current {@code Observable} finishes
8507 * @return the new {@code Observable} instance
8508 * @throws NullPointerException if {@code onAfterTerminate} is {@code null}
8509 * @see <a href="http://reactivex.io/documentation/operators/do.html">ReactiveX operators documentation: Do</a>
8510 * @see #doOnTerminate(Action)
8511 */
8512 @CheckReturnValue
8513 @SchedulerSupport(SchedulerSupport.NONE)
8514 @NonNull
8515 public final Observable<T> doAfterTerminate(@NonNull Action onAfterTerminate) {
8516 Objects.requireNonNull(onAfterTerminate, "onAfterTerminate is null");
8517 return doOnEach(Functions.emptyConsumer(), Functions.emptyConsumer(), Functions.EMPTY_ACTION, onAfterTerminate);
8518 }
8519
8520 /**
8521 * Calls the specified action after the current {@code Observable} signals {@code onError} or {@code onCompleted} or gets disposed by
8522 * the downstream.
8523 * <p>In case of a race between a terminal event and a dispose call, the provided {@code onFinally} action
8524 * is executed once per subscription.
8525 * <p>Note that the {@code onFinally} action is shared between subscriptions and as such
8526 * should be thread-safe.
8527 * <p>
8528 * <img width="640" height="282" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/doFinally.o.png" alt="">
8529 * <dl>
8530 * <dt><b>Scheduler:</b></dt>
8531 * <dd>{@code doFinally} does not operate by default on a particular {@link Scheduler}.</dd>
8532 * <dt><b>Operator-fusion:</b></dt>
8533 * <dd>This operator supports boundary-limited synchronous or asynchronous queue-fusion.</dd>
8534 * </dl>
8535 * <p>History: 2.0.1 - experimental
8536 * @param onFinally the action called when the current {@code Observable} terminates or gets disposed
8537 * @return the new {@code Observable} instance
8538 * @throws NullPointerException if {@code onFinally} is {@code null}
8539 * @since 2.1
8540 */
8541 @CheckReturnValue
8542 @SchedulerSupport(SchedulerSupport.NONE)
8543 @NonNull
8544 public final Observable<T> doFinally(@NonNull Action onFinally) {
8545 Objects.requireNonNull(onFinally, "onFinally is null");
8546 return RxJavaPlugins.onAssembly(new ObservableDoFinally<>(this, onFinally));
8547 }
8548
8549 /**
8550 * Calls the given shared {@link Action} if the downstream disposes the sequence.
8551 * <p>
8552 * The action is shared between subscriptions and thus may be called concurrently from multiple
8553 * threads; the action must be thread safe.
8554 * <p>
8555 * If the action throws a runtime exception, that exception is rethrown by the {@code dispose()} call,
8556 * sometimes as a {@link CompositeException} if there were multiple exceptions along the way.
8557 * <p>
8558 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/doOnDispose.v3.png" alt="">
8559 * <dl>
8560 * <dt><b>Scheduler:</b></dt>
8561 * <dd>{@code doOnDispose} does not operate by default on a particular {@link Scheduler}.</dd>
8562 * </dl>
8563 *
8564 * @param onDispose
8565 * the action that gets called when the current {@code Observable}'s {@link Disposable} is disposed
8566 * @return the new {@code Observable} instance
8567 * @throws NullPointerException if {@code onDispose} is {@code null}
8568 * @see <a href="http://reactivex.io/documentation/operators/do.html">ReactiveX operators documentation: Do</a>
8569 */
8570 @CheckReturnValue
8571 @SchedulerSupport(SchedulerSupport.NONE)
8572 @NonNull
8573 public final Observable<T> doOnDispose(@NonNull Action onDispose) {
8574 return doOnLifecycle(Functions.emptyConsumer(), onDispose);
8575 }
8576
8577 /**
8578 * Returns an {@code Observable} that invokes an {@link Action} when the current {@code Observable} calls {@code onComplete}.
8579 * <p>
8580 * <img width="640" height="358" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/doOnComplete.o.v3.png" alt="">
8581 * <dl>
8582 * <dt><b>Scheduler:</b></dt>
8583 * <dd>{@code doOnComplete} does not operate by default on a particular {@link Scheduler}.</dd>
8584 * </dl>
8585 *
8586 * @param onComplete
8587 * the action to invoke when the current {@code Observable} calls {@code onComplete}
8588 * @return the new {@code Observable} instance
8589 * @throws NullPointerException if {@code onComplete} is {@code null}
8590 * @see <a href="http://reactivex.io/documentation/operators/do.html">ReactiveX operators documentation: Do</a>
8591 */
8592 @CheckReturnValue
8593 @SchedulerSupport(SchedulerSupport.NONE)
8594 @NonNull
8595 public final Observable<T> doOnComplete(@NonNull Action onComplete) {
8596 return doOnEach(Functions.emptyConsumer(), Functions.emptyConsumer(), onComplete, Functions.EMPTY_ACTION);
8597 }
8598
8599 /**
8600 * Calls the appropriate {@code onXXX} consumer (shared between all {@link Observer}s) whenever a signal with the same type
8601 * passes through, before forwarding them to the downstream.
8602 * <p>
8603 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/doOnEach.v3.png" alt="">
8604 * <dl>
8605 * <dt><b>Scheduler:</b></dt>
8606 * <dd>{@code doOnEach} does not operate by default on a particular {@link Scheduler}.</dd>
8607 * </dl>
8608 *
8609 * @param onNext the {@link Consumer} to invoke when the current {@code Observable} calls {@code onNext}
8610 * @param onError the {@code Consumer} to invoke when the current {@code Observable} calls {@code onError}
8611 * @param onComplete the {@link Action} to invoke when the current {@code Observable} calls {@code onComplete}
8612 * @param onAfterTerminate the {@code Action} to invoke when the current {@code Observable} calls {@code onAfterTerminate}
8613 * @return the new {@code Observable} instance
8614 * @throws NullPointerException if {@code onNext}, {@code onError}, {@code onComplete} or {@code onAfterTerminate} is {@code null}
8615 * @see <a href="http://reactivex.io/documentation/operators/do.html">ReactiveX operators documentation: Do</a>
8616 */
8617 @CheckReturnValue
8618 @SchedulerSupport(SchedulerSupport.NONE)
8619 @NonNull
8620 private Observable<T> doOnEach(@NonNull Consumer<? super T> onNext, @NonNull Consumer<? super Throwable> onError, @NonNull Action onComplete, @NonNull Action onAfterTerminate) {
8621 Objects.requireNonNull(onNext, "onNext is null");
8622 Objects.requireNonNull(onError, "onError is null");
8623 Objects.requireNonNull(onComplete, "onComplete is null");
8624 Objects.requireNonNull(onAfterTerminate, "onAfterTerminate is null");
8625 return RxJavaPlugins.onAssembly(new ObservableDoOnEach<>(this, onNext, onError, onComplete, onAfterTerminate));
8626 }
8627
8628 /**
8629 * Returns an {@code Observable} that invokes a {@link Consumer} with the appropriate {@link Notification}
8630 * object when the current {@code Observable} signals an item or terminates.
8631 * <p>
8632 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/doOnEach.v3.png" alt="">
8633 * <dl>
8634 * <dt><b>Scheduler:</b></dt>
8635 * <dd>{@code doOnEach} does not operate by default on a particular {@link Scheduler}.</dd>
8636 * </dl>
8637 *
8638 * @param onNotification
8639 * the action to invoke for each item emitted by the current {@code Observable}
8640 * @return the new {@code Observable} instance
8641 * @throws NullPointerException if {@code onNotification} is {@code null}
8642 * @see <a href="http://reactivex.io/documentation/operators/do.html">ReactiveX operators documentation: Do</a>
8643 */
8644 @CheckReturnValue
8645 @SchedulerSupport(SchedulerSupport.NONE)
8646 @NonNull
8647 public final Observable<T> doOnEach(@NonNull Consumer<? super Notification<T>> onNotification) {
8648 Objects.requireNonNull(onNotification, "onNotification is null");
8649 return doOnEach(
8650 Functions.notificationOnNext(onNotification),
8651 Functions.notificationOnError(onNotification),
8652 Functions.notificationOnComplete(onNotification),
8653 Functions.EMPTY_ACTION
8654 );
8655 }
8656
8657 /**
8658 * Returns an {@code Observable} that forwards the items and terminal events of the current
8659 * {@code Observable} to its {@link Observer}s and to the given shared {@code Observer} instance.
8660 * <p>
8661 * In case the {@code onError} of the supplied observer throws, the downstream will receive a composite
8662 * exception containing the original exception and the exception thrown by {@code onError}. If either the
8663 * {@code onNext} or the {@code onComplete} method of the supplied observer throws, the downstream will be
8664 * terminated and will receive this thrown exception.
8665 * <p>
8666 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/doOnEach.o.v3.png" alt="">
8667 * <dl>
8668 * <dt><b>Scheduler:</b></dt>
8669 * <dd>{@code doOnEach} does not operate by default on a particular {@link Scheduler}.</dd>
8670 * </dl>
8671 *
8672 * @param observer
8673 * the observer to be notified about {@code onNext}, {@code onError} and {@code onComplete} events on its
8674 * respective methods before the actual downstream {@code Observer} gets notified.
8675 * @return the new {@code Observable} instance
8676 * @throws NullPointerException if {@code observer} is {@code null}
8677 * @see <a href="http://reactivex.io/documentation/operators/do.html">ReactiveX operators documentation: Do</a>
8678 */
8679 @CheckReturnValue
8680 @SchedulerSupport(SchedulerSupport.NONE)
8681 @NonNull
8682 public final Observable<T> doOnEach(@NonNull Observer<? super T> observer) {
8683 Objects.requireNonNull(observer, "observer is null");
8684 return doOnEach(
8685 ObservableInternalHelper.observerOnNext(observer),
8686 ObservableInternalHelper.observerOnError(observer),
8687 ObservableInternalHelper.observerOnComplete(observer),
8688 Functions.EMPTY_ACTION);
8689 }
8690
8691 /**
8692 * Calls the given {@link Consumer} with the error {@link Throwable} if the current {@code Observable} failed before forwarding it to
8693 * the downstream.
8694 * <p>
8695 * In case the {@code onError} action throws, the downstream will receive a composite exception containing
8696 * the original exception and the exception thrown by {@code onError}.
8697 * <p>
8698 * <img width="640" height="355" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/doOnError.o.v3.png" alt="">
8699 * <dl>
8700 * <dt><b>Scheduler:</b></dt>
8701 * <dd>{@code doOnError} does not operate by default on a particular {@link Scheduler}.</dd>
8702 * </dl>
8703 *
8704 * @param onError
8705 * the action to invoke if the current {@code Observable} calls {@code onError}
8706 * @return the new {@code Observable} instance
8707 * @throws NullPointerException if {@code onError} is {@code null}
8708 * @see <a href="http://reactivex.io/documentation/operators/do.html">ReactiveX operators documentation: Do</a>
8709 */
8710 @CheckReturnValue
8711 @SchedulerSupport(SchedulerSupport.NONE)
8712 @NonNull
8713 public final Observable<T> doOnError(@NonNull Consumer<? super Throwable> onError) {
8714 return doOnEach(Functions.emptyConsumer(), onError, Functions.EMPTY_ACTION, Functions.EMPTY_ACTION);
8715 }
8716
8717 /**
8718 * Calls the appropriate {@code onXXX} method (shared between all {@link Observer}s) for the lifecycle events of
8719 * the sequence (subscription, disposal).
8720 * <p>
8721 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/doOnLifecycle.o.v3.png" alt="">
8722 * <dl>
8723 * <dt><b>Scheduler:</b></dt>
8724 * <dd>{@code doOnLifecycle} does not operate by default on a particular {@link Scheduler}.</dd>
8725 * </dl>
8726 *
8727 * @param onSubscribe
8728 * a {@link Consumer} called with the {@link Disposable} sent via {@link Observer#onSubscribe(Disposable)}
8729 * @param onDispose
8730 * called when the downstream disposes the {@code Disposable} via {@code dispose()}
8731 * @return the new {@code Observable} instance
8732 * @throws NullPointerException if {@code onSubscribe} or {@code onDispose} is {@code null}
8733 * @see <a href="http://reactivex.io/documentation/operators/do.html">ReactiveX operators documentation: Do</a>
8734 */
8735 @CheckReturnValue
8736 @SchedulerSupport(SchedulerSupport.NONE)
8737 @NonNull
8738 public final Observable<T> doOnLifecycle(@NonNull Consumer<? super Disposable> onSubscribe, @NonNull Action onDispose) {
8739 Objects.requireNonNull(onSubscribe, "onSubscribe is null");
8740 Objects.requireNonNull(onDispose, "onDispose is null");
8741 return RxJavaPlugins.onAssembly(new ObservableDoOnLifecycle<>(this, onSubscribe, onDispose));
8742 }
8743
8744 /**
8745 * Calls the given {@link Consumer} with the value emitted by the current {@code Observable} before forwarding it to the downstream.
8746 * <p>
8747 * <img width="640" height="360" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/doOnNext.o.v3.png" alt="">
8748 * <dl>
8749 * <dt><b>Scheduler:</b></dt>
8750 * <dd>{@code doOnNext} does not operate by default on a particular {@link Scheduler}.</dd>
8751 * </dl>
8752 *
8753 * @param onNext
8754 * the action to invoke when the current {@code Observable} calls {@code onNext}
8755 * @return the new {@code Observable} instance
8756 * @throws NullPointerException if {@code onNext} is {@code null}
8757 * @see <a href="http://reactivex.io/documentation/operators/do.html">ReactiveX operators documentation: Do</a>
8758 */
8759 @CheckReturnValue
8760 @SchedulerSupport(SchedulerSupport.NONE)
8761 @NonNull
8762 public final Observable<T> doOnNext(@NonNull Consumer<? super T> onNext) {
8763 return doOnEach(onNext, Functions.emptyConsumer(), Functions.EMPTY_ACTION, Functions.EMPTY_ACTION);
8764 }
8765
8766 /**
8767 * Returns an {@code Observable} so that it invokes the given {@link Consumer} when the current {@code Observable} is subscribed from
8768 * its {@link Observer}s. Each subscription will result in an invocation of the given action except when the
8769 * current {@code Observable} is reference counted, in which case the current {@code Observable} will invoke
8770 * the given action for the first subscription.
8771 * <p>
8772 * <img width="640" height="390" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/doOnSubscribe.v3.png" alt="">
8773 * <dl>
8774 * <dt><b>Scheduler:</b></dt>
8775 * <dd>{@code doOnSubscribe} does not operate by default on a particular {@link Scheduler}.</dd>
8776 * </dl>
8777 *
8778 * @param onSubscribe
8779 * the {@code Consumer} that gets called when an {@code Observer} subscribes to the current {@code Observable}
8780 * @return the new {@code Observable} instance
8781 * @throws NullPointerException if {@code onSubscribe} is {@code null}
8782 * @see <a href="http://reactivex.io/documentation/operators/do.html">ReactiveX operators documentation: Do</a>
8783 */
8784 @CheckReturnValue
8785 @SchedulerSupport(SchedulerSupport.NONE)
8786 @NonNull
8787 public final Observable<T> doOnSubscribe(@NonNull Consumer<? super Disposable> onSubscribe) {
8788 return doOnLifecycle(onSubscribe, Functions.EMPTY_ACTION);
8789 }
8790
8791 /**
8792 * Returns an {@code Observable} so that it invokes an action when the current {@code Observable} calls {@code onComplete} or
8793 * {@code onError}.
8794 * <p>
8795 * <img width="640" height="327" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/doOnTerminate.o.png" alt="">
8796 * <p>
8797 * This differs from {@code doAfterTerminate} in that this happens <em>before</em> the {@code onComplete} or
8798 * {@code onError} notification.
8799 * <dl>
8800 * <dt><b>Scheduler:</b></dt>
8801 * <dd>{@code doOnTerminate} does not operate by default on a particular {@link Scheduler}.</dd>
8802 * </dl>
8803 *
8804 * @param onTerminate
8805 * the action to invoke when the current {@code Observable} calls {@code onComplete} or {@code onError}
8806 * @return the new {@code Observable} instance
8807 * @throws NullPointerException if {@code onTerminate} is {@code null}
8808 * @see <a href="http://reactivex.io/documentation/operators/do.html">ReactiveX operators documentation: Do</a>
8809 * @see #doAfterTerminate(Action)
8810 */
8811 @CheckReturnValue
8812 @SchedulerSupport(SchedulerSupport.NONE)
8813 @NonNull
8814 public final Observable<T> doOnTerminate(@NonNull Action onTerminate) {
8815 Objects.requireNonNull(onTerminate, "onTerminate is null");
8816 return doOnEach(Functions.emptyConsumer(),
8817 Functions.actionConsumer(onTerminate), onTerminate,
8818 Functions.EMPTY_ACTION);
8819 }
8820
8821 /**
8822 * Returns a {@link Maybe} that emits the single item at a specified index in a sequence of emissions from
8823 * the current {@code Observable} or completes if the current {@code Observable} signals fewer elements than index.
8824 * <p>
8825 * <img width="640" height="363" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/elementAt.o.png" alt="">
8826 * <dl>
8827 * <dt><b>Scheduler:</b></dt>
8828 * <dd>{@code elementAt} does not operate by default on a particular {@link Scheduler}.</dd>
8829 * </dl>
8830 *
8831 * @param index
8832 * the zero-based index of the item to retrieve
8833 * @return the new {@code Maybe} instance
8834 * @throws IndexOutOfBoundsException
8835 * if {@code index} is negative
8836 * @see <a href="http://reactivex.io/documentation/operators/elementat.html">ReactiveX operators documentation: ElementAt</a>
8837 */
8838 @CheckReturnValue
8839 @SchedulerSupport(SchedulerSupport.NONE)
8840 @NonNull
8841 public final Maybe<T> elementAt(long index) {
8842 if (index < 0) {
8843 throw new IndexOutOfBoundsException("index >= 0 required but it was " + index);
8844 }
8845 return RxJavaPlugins.onAssembly(new ObservableElementAtMaybe<>(this, index));
8846 }
8847
8848 /**
8849 * Returns a {@link Single} that emits the item found at a specified index in a sequence of emissions from
8850 * the current {@code Observable}, or a default item if that index is out of range.
8851 * <p>
8852 * <img width="640" height="354" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/elementAtDefault.o.png" alt="">
8853 * <dl>
8854 * <dt><b>Scheduler:</b></dt>
8855 * <dd>{@code elementAt} does not operate by default on a particular {@link Scheduler}.</dd>
8856 * </dl>
8857 *
8858 * @param index
8859 * the zero-based index of the item to retrieve
8860 * @param defaultItem
8861 * the default item
8862 * @return the new {@code Single} instance
8863 * @throws NullPointerException if {@code defaultItem} is {@code null}
8864 * @throws IndexOutOfBoundsException
8865 * if {@code index} is negative
8866 * @see <a href="http://reactivex.io/documentation/operators/elementat.html">ReactiveX operators documentation: ElementAt</a>
8867 */
8868 @CheckReturnValue
8869 @SchedulerSupport(SchedulerSupport.NONE)
8870 @NonNull
8871 public final Single<T> elementAt(long index, @NonNull T defaultItem) {
8872 if (index < 0) {
8873 throw new IndexOutOfBoundsException("index >= 0 required but it was " + index);
8874 }
8875 Objects.requireNonNull(defaultItem, "defaultItem is null");
8876 return RxJavaPlugins.onAssembly(new ObservableElementAtSingle<>(this, index, defaultItem));
8877 }
8878
8879 /**
8880 * Returns a {@link Single} that emits the item found at a specified index in a sequence of emissions from the current {@code Observable}
8881 * or signals a {@link NoSuchElementException} if the current {@code Observable} signals fewer elements than index.
8882 * <p>
8883 * <img width="640" height="362" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/elementAtOrError.o.png" alt="">
8884 * <dl>
8885 * <dt><b>Scheduler:</b></dt>
8886 * <dd>{@code elementAtOrError} does not operate by default on a particular {@link Scheduler}.</dd>
8887 * </dl>
8888 *
8889 * @param index
8890 * the zero-based index of the item to retrieve
8891 * @return the new {@code Single} instance
8892 * @throws IndexOutOfBoundsException
8893 * if {@code index} is negative
8894 * @see <a href="http://reactivex.io/documentation/operators/elementat.html">ReactiveX operators documentation: ElementAt</a>
8895 */
8896 @CheckReturnValue
8897 @SchedulerSupport(SchedulerSupport.NONE)
8898 @NonNull
8899 public final Single<T> elementAtOrError(long index) {
8900 if (index < 0) {
8901 throw new IndexOutOfBoundsException("index >= 0 required but it was " + index);
8902 }
8903 return RxJavaPlugins.onAssembly(new ObservableElementAtSingle<>(this, index, null));
8904 }
8905
8906 /**
8907 * Filters items emitted by the current {@code Observable} by only emitting those that satisfy a specified {@link Predicate}.
8908 * <p>
8909 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/filter.v3.png" alt="">
8910 * <dl>
8911 * <dt><b>Scheduler:</b></dt>
8912 * <dd>{@code filter} does not operate by default on a particular {@link Scheduler}.</dd>
8913 * </dl>
8914 *
8915 * @param predicate
8916 * a function that evaluates each item emitted by the current {@code Observable}, returning {@code true}
8917 * if it passes the filter
8918 * @return the new {@code Observable} instance
8919 * @throws NullPointerException if {@code predicate} is {@code null}
8920 * @see <a href="http://reactivex.io/documentation/operators/filter.html">ReactiveX operators documentation: Filter</a>
8921 */
8922 @CheckReturnValue
8923 @SchedulerSupport(SchedulerSupport.NONE)
8924 @NonNull
8925 public final Observable<T> filter(@NonNull Predicate<? super T> predicate) {
8926 Objects.requireNonNull(predicate, "predicate is null");
8927 return RxJavaPlugins.onAssembly(new ObservableFilter<>(this, predicate));
8928 }
8929
8930 /**
8931 * Returns a {@link Maybe} that emits only the very first item emitted by the current {@code Observable}, or
8932 * completes if the current {@code Observable} is empty.
8933 * <p>
8934 * <img width="640" height="286" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/firstElement.m.png" alt="">
8935 * <dl>
8936 * <dt><b>Scheduler:</b></dt>
8937 * <dd>{@code firstElement} does not operate by default on a particular {@link Scheduler}.</dd>
8938 * </dl>
8939 *
8940 * @return the new {@code Maybe} instance
8941 * @see <a href="http://reactivex.io/documentation/operators/first.html">ReactiveX operators documentation: First</a>
8942 */
8943 @CheckReturnValue
8944 @SchedulerSupport(SchedulerSupport.NONE)
8945 @NonNull
8946 public final Maybe<T> firstElement() {
8947 return elementAt(0L);
8948 }
8949
8950 /**
8951 * Returns a {@link Single} that emits only the very first item emitted by the current {@code Observable}, or a default item
8952 * if the current {@code Observable} completes without emitting any items.
8953 * <p>
8954 * <img width="640" height="283" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/first.s.png" alt="">
8955 * <dl>
8956 * <dt><b>Scheduler:</b></dt>
8957 * <dd>{@code first} does not operate by default on a particular {@link Scheduler}.</dd>
8958 * </dl>
8959 *
8960 * @param defaultItem
8961 * the default item to emit if the current {@code Observable} doesn't emit anything
8962 * @return the new {@code Single} instance
8963 * @throws NullPointerException if {@code defaultItem} is {@code null}
8964 * @see <a href="http://reactivex.io/documentation/operators/first.html">ReactiveX operators documentation: First</a>
8965 */
8966 @CheckReturnValue
8967 @SchedulerSupport(SchedulerSupport.NONE)
8968 @NonNull
8969 public final Single<T> first(@NonNull T defaultItem) {
8970 return elementAt(0L, defaultItem);
8971 }
8972
8973 /**
8974 * Returns a {@link Single} that emits only the very first item emitted by the current {@code Observable} or
8975 * signals a {@link NoSuchElementException} if the current {@code Observable} is empty.
8976 * <p>
8977 * <img width="640" height="435" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/firstOrError.o.png" alt="">
8978 * <dl>
8979 * <dt><b>Scheduler:</b></dt>
8980 * <dd>{@code firstOrError} does not operate by default on a particular {@link Scheduler}.</dd>
8981 * </dl>
8982 *
8983 * @return the new {@code Single} instance
8984 * @see <a href="http://reactivex.io/documentation/operators/first.html">ReactiveX operators documentation: First</a>
8985 */
8986 @CheckReturnValue
8987 @SchedulerSupport(SchedulerSupport.NONE)
8988 @NonNull
8989 public final Single<T> firstOrError() {
8990 return elementAtOrError(0L);
8991 }
8992
8993 /**
8994 * Returns an {@code Observable} that emits items based on applying a function that you supply to each item emitted
8995 * by the current {@code Observable}, where that function returns an {@link ObservableSource}, and then merging those returned
8996 * {@code ObservableSource}s and emitting the results of this merger.
8997 * <p>
8998 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/flatMap.v3.png" alt="">
8999 * <dl>
9000 * <dt><b>Scheduler:</b></dt>
9001 * <dd>{@code flatMap} does not operate by default on a particular {@link Scheduler}.</dd>
9002 * </dl>
9003 *
9004 * @param <R> the value type of the inner {@code ObservableSource}s and the output type
9005 * @param mapper
9006 * a function that, when applied to an item emitted by the current {@code Observable}, returns an
9007 * {@code ObservableSource}
9008 * @return the new {@code Observable} instance
9009 * @throws NullPointerException if {@code mapper} is {@code null}
9010 * @see <a href="http://reactivex.io/documentation/operators/flatmap.html">ReactiveX operators documentation: FlatMap</a>
9011 */
9012 @CheckReturnValue
9013 @SchedulerSupport(SchedulerSupport.NONE)
9014 @NonNull
9015 public final <@NonNull R> Observable<R> flatMap(@NonNull Function<? super T, ? extends ObservableSource<? extends R>> mapper) {
9016 return flatMap(mapper, false);
9017 }
9018
9019 /**
9020 * Returns an {@code Observable} that emits items based on applying a function that you supply to each item emitted
9021 * by the current {@code Observable}, where that function returns an {@link ObservableSource}, and then merging those returned
9022 * {@code ObservableSource}s and emitting the results of this merger.
9023 * <p>
9024 * <img width="640" height="356" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/flatMapDelayError.o.png" alt="">
9025 * <dl>
9026 * <dt><b>Scheduler:</b></dt>
9027 * <dd>{@code flatMap} does not operate by default on a particular {@link Scheduler}.</dd>
9028 * </dl>
9029 *
9030 * @param <R> the value type of the inner {@code ObservableSource}s and the output type
9031 * @param mapper
9032 * a function that, when applied to an item emitted by the current {@code Observable}, returns an
9033 * {@code ObservableSource}
9034 * @param delayErrors
9035 * if {@code true}, exceptions from the current {@code Observable} and all inner {@code ObservableSource}s are delayed until all of them terminate
9036 * if {@code false}, the first one signaling an exception will terminate the whole sequence immediately
9037 * @return the new {@code Observable} instance
9038 * @throws NullPointerException if {@code mapper} is {@code null}
9039 * @see <a href="http://reactivex.io/documentation/operators/flatmap.html">ReactiveX operators documentation: FlatMap</a>
9040 */
9041 @CheckReturnValue
9042 @SchedulerSupport(SchedulerSupport.NONE)
9043 @NonNull
9044 public final <@NonNull R> Observable<R> flatMap(@NonNull Function<? super T, ? extends ObservableSource<? extends R>> mapper, boolean delayErrors) {
9045 return flatMap(mapper, delayErrors, Integer.MAX_VALUE);
9046 }
9047
9048 /**
9049 * Returns an {@code Observable} that emits items based on applying a function that you supply to each item emitted
9050 * by the current {@code Observable}, where that function returns an {@link ObservableSource}, and then merging those returned
9051 * {@code ObservableSource}s and emitting the results of this merger, while limiting the maximum number of concurrent
9052 * subscriptions to these {@code ObservableSource}s.
9053 * <p>
9054 * <img width="640" height="442" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/flatMapMaxConcurrency.o.png" alt="">
9055 * <dl>
9056 * <dt><b>Scheduler:</b></dt>
9057 * <dd>{@code flatMap} does not operate by default on a particular {@link Scheduler}.</dd>
9058 * </dl>
9059 *
9060 * @param <R> the value type of the inner {@code ObservableSource}s and the output type
9061 * @param mapper
9062 * a function that, when applied to an item emitted by the current {@code Observable}, returns an
9063 * {@code ObservableSource}
9064 * @param maxConcurrency
9065 * the maximum number of {@code ObservableSource}s that may be subscribed to concurrently
9066 * @param delayErrors
9067 * if {@code true}, exceptions from the current {@code Observable} and all inner {@code ObservableSource}s are delayed until all of them terminate
9068 * if {@code false}, the first one signaling an exception will terminate the whole sequence immediately
9069 * @return the new {@code Observable} instance
9070 * @throws NullPointerException if {@code mapper} is {@code null}
9071 * @throws IllegalArgumentException if {@code maxConcurrency} is non-positive
9072 * @see <a href="http://reactivex.io/documentation/operators/flatmap.html">ReactiveX operators documentation: FlatMap</a>
9073 * @since 2.0
9074 */
9075 @CheckReturnValue
9076 @SchedulerSupport(SchedulerSupport.NONE)
9077 @NonNull
9078 public final <@NonNull R> Observable<R> flatMap(@NonNull Function<? super T, ? extends ObservableSource<? extends R>> mapper, boolean delayErrors, int maxConcurrency) {
9079 return flatMap(mapper, delayErrors, maxConcurrency, bufferSize());
9080 }
9081
9082 /**
9083 * Returns an {@code Observable} that emits items based on applying a function that you supply to each item emitted
9084 * by the current {@code Observable}, where that function returns an {@link ObservableSource}, and then merging those returned
9085 * {@code ObservableSource}s and emitting the results of this merger, while limiting the maximum number of concurrent
9086 * subscriptions to these {@code ObservableSource}s.
9087 * <p>
9088 * <img width="640" height="442" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/flatMapMaxConcurrency.o.png" alt="">
9089 * <dl>
9090 * <dt><b>Scheduler:</b></dt>
9091 * <dd>{@code flatMap} does not operate by default on a particular {@link Scheduler}.</dd>
9092 * </dl>
9093 *
9094 * @param <R> the value type of the inner {@code ObservableSource}s and the output type
9095 * @param mapper
9096 * a function that, when applied to an item emitted by the current {@code Observable}, returns an
9097 * {@code ObservableSource}
9098 * @param maxConcurrency
9099 * the maximum number of {@code ObservableSource}s that may be subscribed to concurrently
9100 * @param delayErrors
9101 * if {@code true}, exceptions from the current {@code Observable} and all inner {@code ObservableSource}s are delayed until all of them terminate
9102 * if {@code false}, the first one signaling an exception will terminate the whole sequence immediately
9103 * @param bufferSize
9104 * the number of elements expected from each inner {@code ObservableSource} to be buffered
9105 * @return the new {@code Observable} instance
9106 * @throws NullPointerException if {@code mapper} is {@code null}
9107 * @throws IllegalArgumentException if {@code maxConcurrency} or {@code bufferSize} is non-positive
9108 * @see <a href="http://reactivex.io/documentation/operators/flatmap.html">ReactiveX operators documentation: FlatMap</a>
9109 * @since 2.0
9110 */
9111 @CheckReturnValue
9112 @SchedulerSupport(SchedulerSupport.NONE)
9113 @NonNull
9114 public final <@NonNull R> Observable<R> flatMap(@NonNull Function<? super T, ? extends ObservableSource<? extends R>> mapper,
9115 boolean delayErrors, int maxConcurrency, int bufferSize) {
9116 Objects.requireNonNull(mapper, "mapper is null");
9117 ObjectHelper.verifyPositive(maxConcurrency, "maxConcurrency");
9118 ObjectHelper.verifyPositive(bufferSize, "bufferSize");
9119 if (this instanceof ScalarSupplier) {
9120 @SuppressWarnings("unchecked")
9121 T v = ((ScalarSupplier<T>)this).get();
9122 if (v == null) {
9123 return empty();
9124 }
9125 return ObservableScalarXMap.scalarXMap(v, mapper);
9126 }
9127 return RxJavaPlugins.onAssembly(new ObservableFlatMap<>(this, mapper, delayErrors, maxConcurrency, bufferSize));
9128 }
9129
9130 /**
9131 * Returns an {@code Observable} that applies a function to each item emitted or notification raised by the current
9132 * {@code Observable} and then flattens the {@link ObservableSource}s returned from these functions and emits the resulting items.
9133 * <p>
9134 * <img width="640" height="410" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/mergeMap.nce.v3.png" alt="">
9135 * <dl>
9136 * <dt><b>Scheduler:</b></dt>
9137 * <dd>{@code flatMap} does not operate by default on a particular {@link Scheduler}.</dd>
9138 * </dl>
9139 *
9140 * @param <R>
9141 * the result type
9142 * @param onNextMapper
9143 * a function that returns an {@code ObservableSource} to merge for each item emitted by the current {@code Observable}
9144 * @param onErrorMapper
9145 * a function that returns an {@code ObservableSource} to merge for an {@code onError} notification from the current
9146 * {@code Observable}
9147 * @param onCompleteSupplier
9148 * a function that returns an {@code ObservableSource} to merge for an {@code onComplete} notification from the current
9149 * {@code Observable}
9150 * @return the new {@code Observable} instance
9151 * @throws NullPointerException if {@code onNextMapper} or {@code onErrorMapper} or {@code onCompleteSupplier} is {@code null}
9152 * @see <a href="http://reactivex.io/documentation/operators/flatmap.html">ReactiveX operators documentation: FlatMap</a>
9153 */
9154 @CheckReturnValue
9155 @SchedulerSupport(SchedulerSupport.NONE)
9156 @NonNull
9157 public final <@NonNull R> Observable<R> flatMap(
9158 @NonNull Function<? super T, ? extends ObservableSource<? extends R>> onNextMapper,
9159 @NonNull Function<? super Throwable, ? extends ObservableSource<? extends R>> onErrorMapper,
9160 @NonNull Supplier<? extends ObservableSource<? extends R>> onCompleteSupplier) {
9161 Objects.requireNonNull(onNextMapper, "onNextMapper is null");
9162 Objects.requireNonNull(onErrorMapper, "onErrorMapper is null");
9163 Objects.requireNonNull(onCompleteSupplier, "onCompleteSupplier is null");
9164 return merge(new ObservableMapNotification<>(this, onNextMapper, onErrorMapper, onCompleteSupplier));
9165 }
9166
9167 /**
9168 * Returns an {@code Observable} that applies a function to each item emitted or notification raised by the current
9169 * {@code Observable} and then flattens the {@link ObservableSource}s returned from these functions and emits the resulting items,
9170 * while limiting the maximum number of concurrent subscriptions to these {@code ObservableSource}s.
9171 * <p>
9172 * <img width="640" height="410" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/mergeMap.nce.v3.png" alt="">
9173 * <dl>
9174 * <dt><b>Scheduler:</b></dt>
9175 * <dd>{@code flatMap} does not operate by default on a particular {@link Scheduler}.</dd>
9176 * </dl>
9177 *
9178 * @param <R>
9179 * the result type
9180 * @param onNextMapper
9181 * a function that returns an {@code ObservableSource} to merge for each item emitted by the current {@code Observable}
9182 * @param onErrorMapper
9183 * a function that returns an {@code ObservableSource} to merge for an {@code onError} notification from the current
9184 * {@code Observable}
9185 * @param onCompleteSupplier
9186 * a function that returns an {@code ObservableSource} to merge for an {@code onComplete} notification from the current
9187 * {@code Observable}
9188 * @param maxConcurrency
9189 * the maximum number of {@code ObservableSource}s that may be subscribed to concurrently
9190 * @return the new {@code Observable} instance
9191 * @throws NullPointerException if {@code onNextMapper} or {@code onErrorMapper} or {@code onCompleteSupplier} is {@code null}
9192 * @throws IllegalArgumentException if {@code maxConcurrency} is non-positive
9193 * @see <a href="http://reactivex.io/documentation/operators/flatmap.html">ReactiveX operators documentation: FlatMap</a>
9194 * @since 2.0
9195 */
9196 @CheckReturnValue
9197 @SchedulerSupport(SchedulerSupport.NONE)
9198 @NonNull
9199 public final <@NonNull R> Observable<R> flatMap(
9200 @NonNull Function<? super T, ? extends ObservableSource<? extends R>> onNextMapper,
9201 @NonNull Function<Throwable, ? extends ObservableSource<? extends R>> onErrorMapper,
9202 @NonNull Supplier<? extends ObservableSource<? extends R>> onCompleteSupplier,
9203 int maxConcurrency) {
9204 Objects.requireNonNull(onNextMapper, "onNextMapper is null");
9205 Objects.requireNonNull(onErrorMapper, "onErrorMapper is null");
9206 Objects.requireNonNull(onCompleteSupplier, "onCompleteSupplier is null");
9207 return merge(new ObservableMapNotification<>(this, onNextMapper, onErrorMapper, onCompleteSupplier), maxConcurrency);
9208 }
9209
9210 /**
9211 * Returns an {@code Observable} that emits items based on applying a function that you supply to each item emitted
9212 * by the current {@code Observable}, where that function returns an {@link ObservableSource}, and then merging those returned
9213 * {@code ObservableSource}s and emitting the results of this merger, while limiting the maximum number of concurrent
9214 * subscriptions to these {@code ObservableSource}s.
9215 * <p>
9216 * <img width="640" height="442" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/flatMapMaxConcurrency.o.png" alt="">
9217 * <dl>
9218 * <dt><b>Scheduler:</b></dt>
9219 * <dd>{@code flatMap} does not operate by default on a particular {@link Scheduler}.</dd>
9220 * </dl>
9221 *
9222 * @param <R> the value type of the inner {@code ObservableSource}s and the output type
9223 * @param mapper
9224 * a function that, when applied to an item emitted by the current {@code Observable}, returns an
9225 * {@code ObservableSource}
9226 * @param maxConcurrency
9227 * the maximum number of {@code ObservableSource}s that may be subscribed to concurrently
9228 * @return the new {@code Observable} instance
9229 * @throws NullPointerException if {@code mapper} is {@code null}
9230 * @throws IllegalArgumentException if {@code maxConcurrency} is non-positive
9231 * @see <a href="http://reactivex.io/documentation/operators/flatmap.html">ReactiveX operators documentation: FlatMap</a>
9232 * @since 2.0
9233 */
9234 @CheckReturnValue
9235 @SchedulerSupport(SchedulerSupport.NONE)
9236 @NonNull
9237 public final <@NonNull R> Observable<R> flatMap(@NonNull Function<? super T, ? extends ObservableSource<? extends R>> mapper, int maxConcurrency) {
9238 return flatMap(mapper, false, maxConcurrency, bufferSize());
9239 }
9240
9241 /**
9242 * Returns an {@code Observable} that emits the results of a specified function to the pair of values emitted by the
9243 * current {@code Observable} and the mapped inner {@link ObservableSource}.
9244 * <p>
9245 * <img width="640" height="390" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/mergeMap.r.v3.png" alt="">
9246 * <dl>
9247 * <dt><b>Scheduler:</b></dt>
9248 * <dd>{@code flatMap} does not operate by default on a particular {@link Scheduler}.</dd>
9249 * </dl>
9250 *
9251 * @param <U>
9252 * the type of items emitted by the collection {@code ObservableSource}
9253 * @param <R>
9254 * the type of items emitted by the resulting {@code Observable}
9255 * @param mapper
9256 * a function that returns an {@code ObservableSource} for each item emitted by the current {@code Observable}
9257 * @param combiner
9258 * a function that combines one item emitted by each of the source and collection {@code ObservableSource}s and
9259 * returns an item to be emitted by the resulting {@code Observable}
9260 * @return the new {@code Observable} instance
9261 * @throws NullPointerException if {@code mapper} or {@code combiner} is {@code null}
9262 * @see <a href="http://reactivex.io/documentation/operators/flatmap.html">ReactiveX operators documentation: FlatMap</a>
9263 */
9264 @CheckReturnValue
9265 @SchedulerSupport(SchedulerSupport.NONE)
9266 @NonNull
9267 public final <@NonNull U, @NonNull R> Observable<R> flatMap(@NonNull Function<? super T, ? extends ObservableSource<? extends U>> mapper,
9268 @NonNull BiFunction<? super T, ? super U, ? extends R> combiner) {
9269 return flatMap(mapper, combiner, false, bufferSize(), bufferSize());
9270 }
9271
9272 /**
9273 * Returns an {@code Observable} that emits the results of a specified function to the pair of values emitted by the
9274 * current {@code Observable} and the mapped inner {@link ObservableSource}.
9275 * <p>
9276 * <img width="640" height="390" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/mergeMap.r.v3.png" alt="">
9277 * <dl>
9278 * <dt><b>Scheduler:</b></dt>
9279 * <dd>{@code flatMap} does not operate by default on a particular {@link Scheduler}.</dd>
9280 * </dl>
9281 *
9282 * @param <U>
9283 * the type of items emitted by the collection {@code ObservableSource}
9284 * @param <R>
9285 * the type of items emitted by the resulting {@code Observable}
9286 * @param mapper
9287 * a function that returns an {@code ObservableSource} for each item emitted by the current {@code Observable}
9288 * @param combiner
9289 * a function that combines one item emitted by each of the source and collection {@code ObservableSource}s and
9290 * returns an item to be emitted by the resulting {@code Observable}
9291 * @param delayErrors
9292 * if {@code true}, exceptions from the current {@code Observable} and all inner {@code ObservableSource}s are delayed until all of them terminate
9293 * if {@code false}, the first one signaling an exception will terminate the whole sequence immediately
9294 * @return the new {@code Observable} instance
9295 * @throws NullPointerException if {@code mapper} or {@code combiner} is {@code null}
9296 * @see <a href="http://reactivex.io/documentation/operators/flatmap.html">ReactiveX operators documentation: FlatMap</a>
9297 */
9298 @CheckReturnValue
9299 @SchedulerSupport(SchedulerSupport.NONE)
9300 @NonNull
9301 public final <@NonNull U, @NonNull R> Observable<R> flatMap(@NonNull Function<? super T, ? extends ObservableSource<? extends U>> mapper,
9302 @NonNull BiFunction<? super T, ? super U, ? extends R> combiner, boolean delayErrors) {
9303 return flatMap(mapper, combiner, delayErrors, bufferSize(), bufferSize());
9304 }
9305
9306 /**
9307 * Returns an {@code Observable} that emits the results of a specified function to the pair of values emitted by the
9308 * current {@code Observable} and the mapped inner {@link ObservableSource}, while limiting the maximum number of concurrent
9309 * subscriptions to these {@code ObservableSource}s.
9310 * <p>
9311 * <img width="640" height="390" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/mergeMap.r.v3.png" alt="">
9312 * <dl>
9313 * <dt><b>Scheduler:</b></dt>
9314 * <dd>{@code flatMap} does not operate by default on a particular {@link Scheduler}.</dd>
9315 * </dl>
9316 *
9317 * @param <U>
9318 * the type of items emitted by the collection {@code ObservableSource}
9319 * @param <R>
9320 * the type of items emitted by the resulting {@code Observable}
9321 * @param mapper
9322 * a function that returns an {@code ObservableSource} for each item emitted by the current {@code Observable}
9323 * @param combiner
9324 * a function that combines one item emitted by each of the source and collection {@code ObservableSource}s and
9325 * returns an item to be emitted by the resulting {@code Observable}
9326 * @param maxConcurrency
9327 * the maximum number of {@code ObservableSource}s that may be subscribed to concurrently
9328 * @param delayErrors
9329 * if {@code true}, exceptions from the current {@code Observable} and all inner {@code ObservableSource}s are delayed until all of them terminate
9330 * if {@code false}, the first one signaling an exception will terminate the whole sequence immediately
9331 * @return the new {@code Observable} instance
9332 * @throws NullPointerException if {@code mapper} or {@code combiner} is {@code null}
9333 * @throws IllegalArgumentException if {@code maxConcurrency} is non-positive
9334 * @see <a href="http://reactivex.io/documentation/operators/flatmap.html">ReactiveX operators documentation: FlatMap</a>
9335 * @since 2.0
9336 */
9337 @CheckReturnValue
9338 @SchedulerSupport(SchedulerSupport.NONE)
9339 @NonNull
9340 public final <@NonNull U, @NonNull R> Observable<R> flatMap(@NonNull Function<? super T, ? extends ObservableSource<? extends U>> mapper,
9341 @NonNull BiFunction<? super T, ? super U, ? extends R> combiner, boolean delayErrors, int maxConcurrency) {
9342 return flatMap(mapper, combiner, delayErrors, maxConcurrency, bufferSize());
9343 }
9344
9345 /**
9346 * Returns an {@code Observable} that emits the results of a specified function to the pair of values emitted by the
9347 * current {@code Observable} and the mapped inner {@link ObservableSource}, while limiting the maximum number of concurrent
9348 * subscriptions to these {@code ObservableSource}s.
9349 * <p>
9350 * <img width="640" height="390" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/mergeMap.r.v3.png" alt="">
9351 * <dl>
9352 * <dt><b>Scheduler:</b></dt>
9353 * <dd>{@code flatMap} does not operate by default on a particular {@link Scheduler}.</dd>
9354 * </dl>
9355 *
9356 * @param <U>
9357 * the type of items emitted by the collection {@code ObservableSource}
9358 * @param <R>
9359 * the type of items emitted by the resulting {@code Observable}
9360 * @param mapper
9361 * a function that returns an {@code ObservableSource} for each item emitted by the current {@code Observable}
9362 * @param combiner
9363 * a function that combines one item emitted by each of the source and collection {@code ObservableSource}s and
9364 * returns an item to be emitted by the resulting {@code Observable}
9365 * @param maxConcurrency
9366 * the maximum number of {@code ObservableSource}s that may be subscribed to concurrently
9367 * @param delayErrors
9368 * if {@code true}, exceptions from the current {@code Observable} and all inner {@code ObservableSource}s are delayed until all of them terminate
9369 * if {@code false}, the first one signaling an exception will terminate the whole sequence immediately
9370 * @param bufferSize
9371 * the number of elements expected from the inner {@code ObservableSource} to be buffered
9372 * @return the new {@code Observable} instance
9373 * @throws NullPointerException if {@code mapper} or {@code combiner} is {@code null}
9374 * @throws IllegalArgumentException if {@code maxConcurrency} or {@code bufferSize} is non-positive
9375 * @see <a href="http://reactivex.io/documentation/operators/flatmap.html">ReactiveX operators documentation: FlatMap</a>
9376 * @since 2.0
9377 */
9378 @CheckReturnValue
9379 @SchedulerSupport(SchedulerSupport.NONE)
9380 @NonNull
9381 public final <@NonNull U, @NonNull R> Observable<R> flatMap(@NonNull Function<? super T, ? extends ObservableSource<? extends U>> mapper,
9382 @NonNull BiFunction<? super T, ? super U, ? extends R> combiner, boolean delayErrors, int maxConcurrency, int bufferSize) {
9383 Objects.requireNonNull(mapper, "mapper is null");
9384 Objects.requireNonNull(combiner, "combiner is null");
9385 return flatMap(ObservableInternalHelper.flatMapWithCombiner(mapper, combiner), delayErrors, maxConcurrency, bufferSize);
9386 }
9387
9388 /**
9389 * Returns an {@code Observable} that emits the results of a specified function to the pair of values emitted by the
9390 * current {@code Observable} and the mapped inner {@link ObservableSource}, while limiting the maximum number of concurrent
9391 * subscriptions to these {@code ObservableSource}s.
9392 * <p>
9393 * <img width="640" height="390" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/mergeMap.r.v3.png" alt="">
9394 * <dl>
9395 * <dt><b>Scheduler:</b></dt>
9396 * <dd>{@code flatMap} does not operate by default on a particular {@link Scheduler}.</dd>
9397 * </dl>
9398 *
9399 * @param <U>
9400 * the type of items emitted by the collection {@code ObservableSource}
9401 * @param <R>
9402 * the type of items emitted by the resulting {@code Observable}
9403 * @param mapper
9404 * a function that returns an {@code ObservableSource} for each item emitted by the current {@code Observable}
9405 * @param combiner
9406 * a function that combines one item emitted by each of the source and collection {@code ObservableSource}s and
9407 * returns an item to be emitted by the resulting {@code Observable}
9408 * @param maxConcurrency
9409 * the maximum number of {@code ObservableSource}s that may be subscribed to concurrently
9410 * @return the new {@code Observable} instance
9411 * @throws NullPointerException if {@code mapper} or {@code combiner} is {@code null}
9412 * @throws IllegalArgumentException if {@code maxConcurrency} is non-positive
9413 * @see <a href="http://reactivex.io/documentation/operators/flatmap.html">ReactiveX operators documentation: FlatMap</a>
9414 * @since 2.0
9415 */
9416 @CheckReturnValue
9417 @SchedulerSupport(SchedulerSupport.NONE)
9418 @NonNull
9419 public final <@NonNull U, @NonNull R> Observable<R> flatMap(@NonNull Function<? super T, ? extends ObservableSource<? extends U>> mapper,
9420 @NonNull BiFunction<? super T, ? super U, ? extends R> combiner, int maxConcurrency) {
9421 return flatMap(mapper, combiner, false, maxConcurrency, bufferSize());
9422 }
9423
9424 /**
9425 * Maps each element of the current {@code Observable} into {@link CompletableSource}s, subscribes to them and
9426 * waits until the upstream and all {@code CompletableSource}s complete.
9427 * <p>
9428 * <img width="640" height="424" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/flatMapCompletable.o.png" alt="">
9429 * <dl>
9430 * <dt><b>Scheduler:</b></dt>
9431 * <dd>{@code flatMapCompletable} does not operate by default on a particular {@link Scheduler}.</dd>
9432 * </dl>
9433 * @param mapper the function that received each source value and transforms them into {@code CompletableSource}s.
9434 * @throws NullPointerException if {@code mapper} is {@code null}
9435 * @return the new {@link Completable} instance
9436 */
9437 @CheckReturnValue
9438 @SchedulerSupport(SchedulerSupport.NONE)
9439 @NonNull
9440 public final Completable flatMapCompletable(@NonNull Function<? super T, ? extends CompletableSource> mapper) {
9441 return flatMapCompletable(mapper, false);
9442 }
9443
9444 /**
9445 * Maps each element of the current {@code Observable} into {@link CompletableSource}s, subscribes to them and
9446 * waits until the upstream and all {@code CompletableSource}s complete, optionally delaying all errors.
9447 * <p>
9448 * <img width="640" height="362" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/flatMapCompletableDelayError.o.png" alt="">
9449 * <dl>
9450 * <dt><b>Scheduler:</b></dt>
9451 * <dd>{@code flatMapCompletable} does not operate by default on a particular {@link Scheduler}.</dd>
9452 * </dl>
9453 * @param mapper the function that received each source value and transforms them into {@code CompletableSource}s.
9454 * @param delayErrors if {@code true}, errors from the upstream and inner {@code CompletableSource}s are delayed until all of them
9455 * terminate.
9456 * @return the new {@link Completable} instance
9457 * @throws NullPointerException if {@code mapper} is {@code null}
9458 */
9459 @CheckReturnValue
9460 @SchedulerSupport(SchedulerSupport.NONE)
9461 @NonNull
9462 public final Completable flatMapCompletable(@NonNull Function<? super T, ? extends CompletableSource> mapper, boolean delayErrors) {
9463 Objects.requireNonNull(mapper, "mapper is null");
9464 return RxJavaPlugins.onAssembly(new ObservableFlatMapCompletableCompletable<>(this, mapper, delayErrors));
9465 }
9466
9467 /**
9468 * Merges {@link Iterable}s generated by a mapper {@link Function} for each individual item emitted by
9469 * the current {@code Observable} into a single {@code Observable} sequence.
9470 * <p>
9471 * <img width="640" height="343" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/flatMapIterable.o.png" alt="">
9472 * <dl>
9473 * <dt><b>Scheduler:</b></dt>
9474 * <dd>{@code flatMapIterable} does not operate by default on a particular {@link Scheduler}.</dd>
9475 * </dl>
9476 *
9477 * @param <U>
9478 * the output type and the element type of the {@code Iterable}s
9479 * @param mapper
9480 * a function that returns an {@code Iterable} sequence of values for when given an item emitted by the
9481 * current {@code Observable}
9482 * @return the new {@code Observable} instance
9483 * @throws NullPointerException if {@code mapper} is {@code null}
9484 * @see <a href="http://reactivex.io/documentation/operators/flatmap.html">ReactiveX operators documentation: FlatMap</a>
9485 */
9486 @CheckReturnValue
9487 @SchedulerSupport(SchedulerSupport.NONE)
9488 @NonNull
9489 public final <@NonNull U> Observable<U> flatMapIterable(@NonNull Function<? super T, @NonNull ? extends Iterable<? extends U>> mapper) {
9490 Objects.requireNonNull(mapper, "mapper is null");
9491 return RxJavaPlugins.onAssembly(new ObservableFlattenIterable<>(this, mapper));
9492 }
9493
9494 /**
9495 * Merges {@link Iterable}s generated by a mapper {@link Function} for each individual item emitted by
9496 * the current {@code Observable} into a single {@code Observable} sequence where the resulting items will
9497 * be the combination of the original item and each inner item of the respective {@code Iterable} as returned
9498 * by the {@code resultSelector} {@link BiFunction}.
9499 * <p>
9500 * <img width="640" height="410" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/flatMapIterable.o.r.png" alt="">
9501 * <dl>
9502 * <dt><b>Scheduler:</b></dt>
9503 * <dd>{@code flatMapIterable} does not operate by default on a particular {@link Scheduler}.</dd>
9504 * </dl>
9505 *
9506 * @param <U>
9507 * the element type of the {@code Iterable}s
9508 * @param <V>
9509 * the output type as determined by the {@code resultSelector} function
9510 * @param mapper
9511 * a function that returns an {@code Iterable} sequence of values for each item emitted by the current
9512 * {@code Observable}
9513 * @param combiner
9514 * a function that returns an item based on the item emitted by the current {@code Observable} and the
9515 * next item of the {@code Iterable} returned for that original item by the {@code mapper}
9516 * @return the new {@code Observable} instance
9517 * @throws NullPointerException if {@code mapper} or {@code combiner} is {@code null}
9518 * @see <a href="http://reactivex.io/documentation/operators/flatmap.html">ReactiveX operators documentation: FlatMap</a>
9519 */
9520 @CheckReturnValue
9521 @SchedulerSupport(SchedulerSupport.NONE)
9522 @NonNull
9523 public final <@NonNull U, @NonNull V> Observable<V> flatMapIterable(@NonNull Function<? super T, @NonNull ? extends Iterable<? extends U>> mapper,
9524 @NonNull BiFunction<? super T, ? super U, ? extends V> combiner) {
9525 Objects.requireNonNull(mapper, "mapper is null");
9526 Objects.requireNonNull(combiner, "combiner is null");
9527 return flatMap(ObservableInternalHelper.flatMapIntoIterable(mapper), combiner, false, bufferSize(), bufferSize());
9528 }
9529
9530 /**
9531 * Maps each element of the current {@code Observable} into {@link MaybeSource}s, subscribes to all of them
9532 * and merges their {@code onSuccess} values, in no particular order, into a single {@code Observable} sequence.
9533 * <p>
9534 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/flatMapMaybe.v3.png" alt="">
9535 * <dl>
9536 * <dt><b>Scheduler:</b></dt>
9537 * <dd>{@code flatMapMaybe} does not operate by default on a particular {@link Scheduler}.</dd>
9538 * </dl>
9539 * @param <R> the result value type
9540 * @param mapper the function that received each source value and transforms them into {@code MaybeSource}s.
9541 * @return the new {@code Observable} instance
9542 * @throws NullPointerException if {@code mapper} is {@code null}
9543 */
9544 @CheckReturnValue
9545 @SchedulerSupport(SchedulerSupport.NONE)
9546 @NonNull
9547 public final <@NonNull R> Observable<R> flatMapMaybe(@NonNull Function<? super T, ? extends MaybeSource<? extends R>> mapper) {
9548 return flatMapMaybe(mapper, false);
9549 }
9550
9551 /**
9552 * Maps each element of the current {@code Observable} into {@link MaybeSource}s, subscribes to them
9553 * and merges their {@code onSuccess} values, in no particular order, into a single {@code Observable} sequence,
9554 * optionally delaying all errors.
9555 * <p>
9556 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/flatMapMaybe.v3.png" alt="">
9557 * <dl>
9558 * <dt><b>Scheduler:</b></dt>
9559 * <dd>{@code flatMapMaybe} does not operate by default on a particular {@link Scheduler}.</dd>
9560 * </dl>
9561 * @param <R> the result value type
9562 * @param mapper the function that received each source value and transforms them into {@code MaybeSource}s.
9563 * @param delayErrors if {@code true}, errors from the upstream and inner {@code MaybeSource}s are delayed until all of them
9564 * terminate.
9565 * @return the new {@code Observable} instance
9566 * @throws NullPointerException if {@code mapper} is {@code null}
9567 */
9568 @CheckReturnValue
9569 @SchedulerSupport(SchedulerSupport.NONE)
9570 @NonNull
9571 public final <@NonNull R> Observable<R> flatMapMaybe(@NonNull Function<? super T, ? extends MaybeSource<? extends R>> mapper, boolean delayErrors) {
9572 Objects.requireNonNull(mapper, "mapper is null");
9573 return RxJavaPlugins.onAssembly(new ObservableFlatMapMaybe<>(this, mapper, delayErrors));
9574 }
9575
9576 /**
9577 * Maps each element of the current {@code Observable} into {@link SingleSource}s, subscribes to all of them
9578 * and merges their {@code onSuccess} values, in no particular order, into a single {@code Observable} sequence.
9579 * <p>
9580 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/flatMapSingle.v3.png" alt="">
9581 * <dl>
9582 * <dt><b>Scheduler:</b></dt>
9583 * <dd>{@code flatMapSingle} does not operate by default on a particular {@link Scheduler}.</dd>
9584 * </dl>
9585 * @param <R> the result value type
9586 * @param mapper the function that received each source value and transforms them into {@code SingleSource}s.
9587 * @return the new {@code Observable} instance
9588 * @throws NullPointerException if {@code mapper} is {@code null}
9589 */
9590 @CheckReturnValue
9591 @SchedulerSupport(SchedulerSupport.NONE)
9592 @NonNull
9593 public final <@NonNull R> Observable<R> flatMapSingle(@NonNull Function<? super T, ? extends SingleSource<? extends R>> mapper) {
9594 return flatMapSingle(mapper, false);
9595 }
9596
9597 /**
9598 * Maps each element of the current {@code Observable} into {@link SingleSource}s, subscribes to them
9599 * and merges their {@code onSuccess} values, in no particular order, into a single {@code Observable} sequence,
9600 * optionally delaying all errors.
9601 * <p>
9602 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/flatMapSingle.v3.png" alt="">
9603 * <dl>
9604 * <dt><b>Scheduler:</b></dt>
9605 * <dd>{@code flatMapSingle} does not operate by default on a particular {@link Scheduler}.</dd>
9606 * </dl>
9607 * @param <R> the result value type
9608 * @param mapper the function that received each source value and transforms them into {@code SingleSource}s.
9609 * @param delayErrors if {@code true}, errors from the upstream and inner {@code SingleSource}s are delayed until each of them
9610 * terminates.
9611 * @return the new {@code Observable} instance
9612 * @throws NullPointerException if {@code mapper} is {@code null}
9613 */
9614 @CheckReturnValue
9615 @SchedulerSupport(SchedulerSupport.NONE)
9616 @NonNull
9617 public final <@NonNull R> Observable<R> flatMapSingle(@NonNull Function<? super T, ? extends SingleSource<? extends R>> mapper, boolean delayErrors) {
9618 Objects.requireNonNull(mapper, "mapper is null");
9619 return RxJavaPlugins.onAssembly(new ObservableFlatMapSingle<>(this, mapper, delayErrors));
9620 }
9621
9622 /**
9623 * Subscribes to the {@link ObservableSource} and calls a {@link Consumer} for each item of the current {@code Observable}
9624 * on its emission thread.
9625 * <p>
9626 * <img width="640" height="264" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/forEach.o.png" alt="">
9627 * <p>
9628 * Alias to {@link #subscribe(Consumer)}
9629 * <dl>
9630 * <dt><b>Scheduler:</b></dt>
9631 * <dd>{@code forEach} does not operate by default on a particular {@link Scheduler}.</dd>
9632 * </dl>
9633 *
9634 * @param onNext
9635 * the {@code Consumer} to execute for each item.
9636 * @return
9637 * a {@link Disposable} that allows disposing the sequence if the current {@code Observable} runs asynchronously
9638 * @throws NullPointerException
9639 * if {@code onNext} is {@code null}
9640 * @see <a href="http://reactivex.io/documentation/operators/subscribe.html">ReactiveX operators documentation: Subscribe</a>
9641 */
9642 @CheckReturnValue
9643 @SchedulerSupport(SchedulerSupport.NONE)
9644 @NonNull
9645 public final Disposable forEach(@NonNull Consumer<? super T> onNext) {
9646 return subscribe(onNext);
9647 }
9648
9649 /**
9650 * Subscribes to the {@link ObservableSource} and calls a {@link Predicate} for each item of the current {@code Observable},
9651 * on its emission thread, until the predicate returns {@code false}.
9652 * <p>
9653 * <img width="640" height="273" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/forEachWhile.o.png" alt="">
9654 * <p>
9655 * If the {@code Observable} emits an error, it is wrapped into an
9656 * {@link OnErrorNotImplementedException}
9657 * and routed to the {@link RxJavaPlugins#onError(Throwable)} handler.
9658 * <dl>
9659 * <dt><b>Scheduler:</b></dt>
9660 * <dd>{@code forEachWhile} does not operate by default on a particular {@link Scheduler}.</dd>
9661 * </dl>
9662 *
9663 * @param onNext
9664 * the {@code Predicate} to execute for each item.
9665 * @return
9666 * a {@link Disposable} that allows disposing the sequence if the current {@code Observable} runs asynchronously
9667 * @throws NullPointerException
9668 * if {@code onNext} is {@code null}
9669 * @see <a href="http://reactivex.io/documentation/operators/subscribe.html">ReactiveX operators documentation: Subscribe</a>
9670 */
9671 @CheckReturnValue
9672 @SchedulerSupport(SchedulerSupport.NONE)
9673 @NonNull
9674 public final Disposable forEachWhile(@NonNull Predicate<? super T> onNext) {
9675 return forEachWhile(onNext, Functions.ON_ERROR_MISSING, Functions.EMPTY_ACTION);
9676 }
9677
9678 /**
9679 * Subscribes to the {@link ObservableSource} and calls a {@link Predicate} for each item or a {@link Consumer} with the error
9680 * of the current {@code Observable}, on their original emission threads, until the predicate returns {@code false}.
9681 * <dl>
9682 * <dt><b>Scheduler:</b></dt>
9683 * <dd>{@code forEachWhile} does not operate by default on a particular {@link Scheduler}.</dd>
9684 * </dl>
9685 *
9686 * @param onNext
9687 * the {@code Predicate} to execute for each item.
9688 * @param onError
9689 * the {@code Consumer} to execute when an error is emitted.
9690 * @return
9691 * a {@link Disposable} that allows disposing the sequence if the current {@code Observable} runs asynchronously
9692 * @throws NullPointerException
9693 * if {@code onNext} or {@code onError} is {@code null}
9694 * @see <a href="http://reactivex.io/documentation/operators/subscribe.html">ReactiveX operators documentation: Subscribe</a>
9695 */
9696 @CheckReturnValue
9697 @SchedulerSupport(SchedulerSupport.NONE)
9698 @NonNull
9699 public final Disposable forEachWhile(@NonNull Predicate<? super T> onNext, @NonNull Consumer<? super Throwable> onError) {
9700 return forEachWhile(onNext, onError, Functions.EMPTY_ACTION);
9701 }
9702
9703 /**
9704 * Subscribes to the {@link ObservableSource} and calls a {@link Predicate} for each item, a {@link Consumer} with the error
9705 * or an {@link Action} upon completion of the current {@code Observable}, on their original emission threads,
9706 * until the predicate returns {@code false}.
9707 * <dl>
9708 * <dt><b>Scheduler:</b></dt>
9709 * <dd>{@code forEachWhile} does not operate by default on a particular {@link Scheduler}.</dd>
9710 * </dl>
9711 *
9712 * @param onNext
9713 * the {@code Predicate} to execute for each item.
9714 * @param onError
9715 * the {@code Consumer} to execute when an error is emitted.
9716 * @param onComplete
9717 * the {@code Action} to execute when completion is signaled.
9718 * @return
9719 * a {@link Disposable} that allows disposing the sequence if the current {@code Observable} runs asynchronously
9720 * @throws NullPointerException
9721 * if {@code onNext} or {@code onError} or {@code onComplete} is {@code null}
9722 * @see <a href="http://reactivex.io/documentation/operators/subscribe.html">ReactiveX operators documentation: Subscribe</a>
9723 */
9724 @CheckReturnValue
9725 @SchedulerSupport(SchedulerSupport.NONE)
9726 @NonNull
9727 public final Disposable forEachWhile(@NonNull Predicate<? super T> onNext, @NonNull Consumer<? super Throwable> onError,
9728 @NonNull Action onComplete) {
9729 Objects.requireNonNull(onNext, "onNext is null");
9730 Objects.requireNonNull(onError, "onError is null");
9731 Objects.requireNonNull(onComplete, "onComplete is null");
9732
9733 ForEachWhileObserver<T> o = new ForEachWhileObserver<>(onNext, onError, onComplete);
9734 subscribe(o);
9735 return o;
9736 }
9737
9738 /**
9739 * Groups the items emitted by the current {@code Observable} according to a specified criterion, and emits these
9740 * grouped items as {@link GroupedObservable}s.
9741 * <p>
9742 * <img width="640" height="360" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/groupBy.v3.png" alt="">
9743 * <p>
9744 * Each emitted {@code GroupedObservable} allows only a single {@link Observer} to subscribe to it during its
9745 * lifetime and if this {@code Observer} calls {@code dispose()} before the
9746 * source terminates, the next emission by the source having the same key will trigger a new
9747 * {@code GroupedObservable} emission.
9748 * <p>
9749 * <em>Note:</em> A {@code GroupedObservable} will cache the items it is to emit until such time as it
9750 * is subscribed to. For this reason, in order to avoid memory leaks, you should not simply ignore those
9751 * {@code GroupedObservable}s that do not concern you. Instead, you can signal to them that they may
9752 * discard their buffers by applying an operator like {@link #ignoreElements} to them.
9753 * <p>
9754 * Note also that ignoring groups or subscribing later (i.e., on another thread) will result in
9755 * so-called group abandonment where a group will only contain one element and the group will be
9756 * re-created over and over as new upstream items trigger a new group. The behavior is
9757 * a trade-off between no-dataloss, upstream cancellation and excessive group creation.
9758 *
9759 * <dl>
9760 * <dt><b>Scheduler:</b></dt>
9761 * <dd>{@code groupBy} does not operate by default on a particular {@link Scheduler}.</dd>
9762 * </dl>
9763 *
9764 * @param keySelector
9765 * a function that extracts the key for each item
9766 * @param <K>
9767 * the key type
9768 * @return the new {@code Observable} instance
9769 * @throws NullPointerException if {@code keySelector} is {@code null}
9770 * @see <a href="http://reactivex.io/documentation/operators/groupby.html">ReactiveX operators documentation: GroupBy</a>
9771 */
9772 @SuppressWarnings({ "unchecked", "rawtypes" })
9773 @CheckReturnValue
9774 @SchedulerSupport(SchedulerSupport.NONE)
9775 @NonNull
9776 public final <@NonNull K> Observable<GroupedObservable<K, T>> groupBy(@NonNull Function<? super T, ? extends K> keySelector) {
9777 return groupBy(keySelector, (Function)Functions.identity(), false, bufferSize());
9778 }
9779
9780 /**
9781 * Groups the items emitted by the current {@code Observable} according to a specified criterion, and emits these
9782 * grouped items as {@link GroupedObservable}s.
9783 * <p>
9784 * <img width="640" height="360" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/groupBy.v3.png" alt="">
9785 * <p>
9786 * Each emitted {@code GroupedObservable} allows only a single {@link Observer} to subscribe to it during its
9787 * lifetime and if this {@code Observer} calls {@code dispose()} before the
9788 * source terminates, the next emission by the source having the same key will trigger a new
9789 * {@code GroupedObservable} emission.
9790 * <p>
9791 * <em>Note:</em> A {@code GroupedObservable} will cache the items it is to emit until such time as it
9792 * is subscribed to. For this reason, in order to avoid memory leaks, you should not simply ignore those
9793 * {@code GroupedObservable}s that do not concern you. Instead, you can signal to them that they may
9794 * discard their buffers by applying an operator like {@link #ignoreElements} to them.
9795 * <p>
9796 * Note also that ignoring groups or subscribing later (i.e., on another thread) will result in
9797 * so-called group abandonment where a group will only contain one element and the group will be
9798 * re-created over and over as new upstream items trigger a new group. The behavior is
9799 * a trade-off between no-dataloss, upstream cancellation and excessive group creation.
9800 *
9801 * <dl>
9802 * <dt><b>Scheduler:</b></dt>
9803 * <dd>{@code groupBy} does not operate by default on a particular {@link Scheduler}.</dd>
9804 * </dl>
9805 *
9806 * @param keySelector
9807 * a function that extracts the key for each item
9808 * @param <K>
9809 * the key type
9810 * @param delayError
9811 * if {@code true}, the exception from the current {@code Observable} is delayed in each group until that specific group emitted
9812 * the normal values; if {@code false}, the exception bypasses values in the groups and is reported immediately.
9813 * @return the new {@code Observable} instance
9814 * @throws NullPointerException if {@code keySelector} is {@code null}
9815 * @see <a href="http://reactivex.io/documentation/operators/groupby.html">ReactiveX operators documentation: GroupBy</a>
9816 */
9817 @SuppressWarnings({ "unchecked", "rawtypes" })
9818 @CheckReturnValue
9819 @SchedulerSupport(SchedulerSupport.NONE)
9820 @NonNull
9821 public final <@NonNull K> Observable<GroupedObservable<K, T>> groupBy(@NonNull Function<? super T, ? extends K> keySelector, boolean delayError) {
9822 return groupBy(keySelector, (Function)Functions.identity(), delayError, bufferSize());
9823 }
9824
9825 /**
9826 * Groups the items emitted by the current {@code Observable} according to a specified criterion, and emits these
9827 * grouped items as {@link GroupedObservable}s.
9828 * <p>
9829 * <img width="640" height="360" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/groupBy.v3.png" alt="">
9830 * <p>
9831 * Each emitted {@code GroupedObservable} allows only a single {@link Observer} to subscribe to it during its
9832 * lifetime and if this {@code Observer} calls {@code dispose()} before the
9833 * source terminates, the next emission by the source having the same key will trigger a new
9834 * {@code GroupedObservable} emission.
9835 * <p>
9836 * <em>Note:</em> A {@code GroupedObservable} will cache the items it is to emit until such time as it
9837 * is subscribed to. For this reason, in order to avoid memory leaks, you should not simply ignore those
9838 * {@code GroupedObservable}s that do not concern you. Instead, you can signal to them that they may
9839 * discard their buffers by applying an operator like {@link #ignoreElements} to them.
9840 * <p>
9841 * Note also that ignoring groups or subscribing later (i.e., on another thread) will result in
9842 * so-called group abandonment where a group will only contain one element and the group will be
9843 * re-created over and over as new upstream items trigger a new group. The behavior is
9844 * a trade-off between no-dataloss, upstream cancellation and excessive group creation.
9845 *
9846 * <dl>
9847 * <dt><b>Scheduler:</b></dt>
9848 * <dd>{@code groupBy} does not operate by default on a particular {@link Scheduler}.</dd>
9849 * </dl>
9850 *
9851 * @param keySelector
9852 * a function that extracts the key for each item
9853 * @param valueSelector
9854 * a function that extracts the return element for each item
9855 * @param <K>
9856 * the key type
9857 * @param <V>
9858 * the element type
9859 * @return the new {@code Observable} instance
9860 * @throws NullPointerException if {@code keySelector} or {@code valueSelector} is {@code null}
9861 * @see <a href="http://reactivex.io/documentation/operators/groupby.html">ReactiveX operators documentation: GroupBy</a>
9862 */
9863 @CheckReturnValue
9864 @SchedulerSupport(SchedulerSupport.NONE)
9865 @NonNull
9866 public final <@NonNull K, @NonNull V> Observable<GroupedObservable<K, V>> groupBy(@NonNull Function<? super T, ? extends K> keySelector,
9867 Function<? super T, ? extends V> valueSelector) {
9868 return groupBy(keySelector, valueSelector, false, bufferSize());
9869 }
9870
9871 /**
9872 * Groups the items emitted by the current {@code Observable} according to a specified criterion, and emits these
9873 * grouped items as {@link GroupedObservable}s.
9874 * <p>
9875 * <img width="640" height="360" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/groupBy.v3.png" alt="">
9876 * <p>
9877 * Each emitted {@code GroupedObservable} allows only a single {@link Observer} to subscribe to it during its
9878 * lifetime and if this {@code Observer} calls {@code dispose()} before the
9879 * source terminates, the next emission by the source having the same key will trigger a new
9880 * {@code GroupedObservable} emission.
9881 * <p>
9882 * <em>Note:</em> A {@code GroupedObservable} will cache the items it is to emit until such time as it
9883 * is subscribed to. For this reason, in order to avoid memory leaks, you should not simply ignore those
9884 * {@code GroupedObservable}s that do not concern you. Instead, you can signal to them that they may
9885 * discard their buffers by applying an operator like {@link #ignoreElements} to them.
9886 * <p>
9887 * Note also that ignoring groups or subscribing later (i.e., on another thread) will result in
9888 * so-called group abandonment where a group will only contain one element and the group will be
9889 * re-created over and over as new upstream items trigger a new group. The behavior is
9890 * a trade-off between no-dataloss, upstream cancellation and excessive group creation.
9891 *
9892 * <dl>
9893 * <dt><b>Scheduler:</b></dt>
9894 * <dd>{@code groupBy} does not operate by default on a particular {@link Scheduler}.</dd>
9895 * </dl>
9896 *
9897 * @param keySelector
9898 * a function that extracts the key for each item
9899 * @param valueSelector
9900 * a function that extracts the return element for each item
9901 * @param <K>
9902 * the key type
9903 * @param <V>
9904 * the element type
9905 * @param delayError
9906 * if {@code true}, the exception from the current {@code Observable} is delayed in each group until that specific group emitted
9907 * the normal values; if {@code false}, the exception bypasses values in the groups and is reported immediately.
9908 * @return the new {@code Observable} instance
9909 * @throws NullPointerException if {@code keySelector} or {@code valueSelector} is {@code null}
9910 * @see <a href="http://reactivex.io/documentation/operators/groupby.html">ReactiveX operators documentation: GroupBy</a>
9911 */
9912 @CheckReturnValue
9913 @SchedulerSupport(SchedulerSupport.NONE)
9914 @NonNull
9915 public final <@NonNull K, @NonNull V> Observable<GroupedObservable<K, V>> groupBy(@NonNull Function<? super T, ? extends K> keySelector,
9916 @NonNull Function<? super T, ? extends V> valueSelector, boolean delayError) {
9917 return groupBy(keySelector, valueSelector, delayError, bufferSize());
9918 }
9919
9920 /**
9921 * Groups the items emitted by the current {@code Observable} according to a specified criterion, and emits these
9922 * grouped items as {@link GroupedObservable}s.
9923 * <p>
9924 * <img width="640" height="360" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/groupBy.v3.png" alt="">
9925 * <p>
9926 * Each emitted {@code GroupedObservable} allows only a single {@link Observer} to subscribe to it during its
9927 * lifetime and if this {@code Observer} calls {@code dispose()} before the
9928 * source terminates, the next emission by the source having the same key will trigger a new
9929 * {@code GroupedObservable} emission.
9930 * <p>
9931 * <em>Note:</em> A {@code GroupedObservable} will cache the items it is to emit until such time as it
9932 * is subscribed to. For this reason, in order to avoid memory leaks, you should not simply ignore those
9933 * {@code GroupedObservable}s that do not concern you. Instead, you can signal to them that they may
9934 * discard their buffers by applying an operator like {@link #ignoreElements} to them.
9935 * <p>
9936 * Note also that ignoring groups or subscribing later (i.e., on another thread) will result in
9937 * so-called group abandonment where a group will only contain one element and the group will be
9938 * re-created over and over as new upstream items trigger a new group. The behavior is
9939 * a trade-off between no-dataloss, upstream cancellation and excessive group creation.
9940 *
9941 * <dl>
9942 * <dt><b>Scheduler:</b></dt>
9943 * <dd>{@code groupBy} does not operate by default on a particular {@link Scheduler}.</dd>
9944 * </dl>
9945 *
9946 * @param keySelector
9947 * a function that extracts the key for each item
9948 * @param valueSelector
9949 * a function that extracts the return element for each item
9950 * @param delayError
9951 * if {@code true}, the exception from the current {@code Observable} is delayed in each group until that specific group emitted
9952 * the normal values; if {@code false}, the exception bypasses values in the groups and is reported immediately.
9953 * @param bufferSize
9954 * the hint for how many {@code GroupedObservable}s and element in each {@code GroupedObservable} should be buffered
9955 * @param <K>
9956 * the key type
9957 * @param <V>
9958 * the element type
9959 * @return the new {@code Observable} instance
9960 * @throws NullPointerException if {@code keySelector} or {@code valueSelector} is {@code null}
9961 * @throws IllegalArgumentException if {@code bufferSize} is non-positive
9962 * @see <a href="http://reactivex.io/documentation/operators/groupby.html">ReactiveX operators documentation: GroupBy</a>
9963 */
9964 @CheckReturnValue
9965 @SchedulerSupport(SchedulerSupport.NONE)
9966 @NonNull
9967 public final <@NonNull K, @NonNull V> Observable<GroupedObservable<K, V>> groupBy(@NonNull Function<? super T, ? extends K> keySelector,
9968 @NonNull Function<? super T, ? extends V> valueSelector,
9969 boolean delayError, int bufferSize) {
9970 Objects.requireNonNull(keySelector, "keySelector is null");
9971 Objects.requireNonNull(valueSelector, "valueSelector is null");
9972 ObjectHelper.verifyPositive(bufferSize, "bufferSize");
9973
9974 return RxJavaPlugins.onAssembly(new ObservableGroupBy<>(this, keySelector, valueSelector, bufferSize, delayError));
9975 }
9976
9977 /**
9978 * Returns an {@code Observable} that correlates two {@link ObservableSource}s when they overlap in time and groups the results.
9979 * <p>
9980 * There are no guarantees in what order the items get combined when multiple
9981 * items from one or both source {@code ObservableSource}s overlap.
9982 * <p>
9983 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/groupJoin.v3.png" alt="">
9984 * <dl>
9985 * <dt><b>Scheduler:</b></dt>
9986 * <dd>{@code groupJoin} does not operate by default on a particular {@link Scheduler}.</dd>
9987 * </dl>
9988 *
9989 * @param <TRight> the value type of the right {@code ObservableSource} source
9990 * @param <TLeftEnd> the element type of the left duration {@code ObservableSource}s
9991 * @param <TRightEnd> the element type of the right duration {@code ObservableSource}s
9992 * @param <R> the result type
9993 * @param other
9994 * the other {@code ObservableSource} to correlate items from the current {@code Observable} with
9995 * @param leftEnd
9996 * a function that returns an {@code ObservableSource} whose emissions indicate the duration of the values of
9997 * the current {@code Observable}
9998 * @param rightEnd
9999 * a function that returns an {@code ObservableSource} whose emissions indicate the duration of the values of
10000 * the {@code right} {@code ObservableSource}
10001 * @param resultSelector
10002 * a function that takes an item emitted by each {@code ObservableSource} and returns the value to be emitted
10003 * by the resulting {@code Observable}
10004 * @return the new {@code Observable} instance
10005 * @throws NullPointerException if {@code other}, {@code leftEnd}, {@code rightEnd} or {@code resultSelector} is {@code null}
10006 * @see <a href="http://reactivex.io/documentation/operators/join.html">ReactiveX operators documentation: Join</a>
10007 */
10008 @CheckReturnValue
10009 @SchedulerSupport(SchedulerSupport.NONE)
10010 @NonNull
10011 public final <@NonNull TRight, @NonNull TLeftEnd, @NonNull TRightEnd, @NonNull R> Observable<R> groupJoin(
10012 @NonNull ObservableSource<? extends TRight> other,
10013 @NonNull Function<? super T, ? extends ObservableSource<TLeftEnd>> leftEnd,
10014 @NonNull Function<? super TRight, ? extends ObservableSource<TRightEnd>> rightEnd,
10015 @NonNull BiFunction<? super T, ? super Observable<TRight>, ? extends R> resultSelector
10016 ) {
10017 Objects.requireNonNull(other, "other is null");
10018 Objects.requireNonNull(leftEnd, "leftEnd is null");
10019 Objects.requireNonNull(rightEnd, "rightEnd is null");
10020 Objects.requireNonNull(resultSelector, "resultSelector is null");
10021 return RxJavaPlugins.onAssembly(new ObservableGroupJoin<>(
10022 this, other, leftEnd, rightEnd, resultSelector));
10023 }
10024
10025 /**
10026 * Hides the identity of the current {@code Observable} and its {@link Disposable}.
10027 * <p>
10028 * Allows hiding extra features such as {@link io.reactivex.rxjava3.subjects.Subject}'s
10029 * {@link Observer} methods or preventing certain identity-based
10030 * optimizations (fusion).
10031 * <p>
10032 * <img width="640" height="283" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/hide.o.png" alt="">
10033 * <dl>
10034 * <dt><b>Scheduler:</b></dt>
10035 * <dd>{@code hide} does not operate by default on a particular {@link Scheduler}.</dd>
10036 * </dl>
10037 * @return the new {@code Observable} instance
10038 *
10039 * @since 2.0
10040 */
10041 @CheckReturnValue
10042 @SchedulerSupport(SchedulerSupport.NONE)
10043 @NonNull
10044 public final Observable<T> hide() {
10045 return RxJavaPlugins.onAssembly(new ObservableHide<>(this));
10046 }
10047
10048 /**
10049 * Ignores all items emitted by the current {@code Observable} and only calls {@code onComplete} or {@code onError}.
10050 * <p>
10051 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/ignoreElements.2.v3.png" alt="">
10052 * <dl>
10053 * <dt><b>Scheduler:</b></dt>
10054 * <dd>{@code ignoreElements} does not operate by default on a particular {@link Scheduler}.</dd>
10055 * </dl>
10056 *
10057 * @return the new {@link Completable} instance
10058 * @see <a href="http://reactivex.io/documentation/operators/ignoreelements.html">ReactiveX operators documentation: IgnoreElements</a>
10059 */
10060 @CheckReturnValue
10061 @SchedulerSupport(SchedulerSupport.NONE)
10062 @NonNull
10063 public final Completable ignoreElements() {
10064 return RxJavaPlugins.onAssembly(new ObservableIgnoreElementsCompletable<>(this));
10065 }
10066
10067 /**
10068 * Returns a {@link Single} that emits {@code true} if the current {@code Observable} is empty, otherwise {@code false}.
10069 * <p>
10070 * In Rx.Net this is negated as the {@code any} {@link Observer} but we renamed this in RxJava to better match Java
10071 * naming idioms.
10072 * <p>
10073 * <img width="640" height="320" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/isEmpty.2.v3.png" alt="">
10074 * <dl>
10075 * <dt><b>Scheduler:</b></dt>
10076 * <dd>{@code isEmpty} does not operate by default on a particular {@link Scheduler}.</dd>
10077 * </dl>
10078 *
10079 * @return the new {@code Single} instance
10080 * @see <a href="http://reactivex.io/documentation/operators/contains.html">ReactiveX operators documentation: Contains</a>
10081 */
10082 @CheckReturnValue
10083 @SchedulerSupport(SchedulerSupport.NONE)
10084 @NonNull
10085 public final Single<Boolean> isEmpty() {
10086 return all(Functions.alwaysFalse());
10087 }
10088
10089 /**
10090 * Correlates the items emitted by two {@link ObservableSource}s based on overlapping durations.
10091 * <p>
10092 * There are no guarantees in what order the items get combined when multiple
10093 * items from one or both source {@code ObservableSource}s overlap.
10094 * <p>
10095 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/join_.v3.png" alt="">
10096 * <dl>
10097 * <dt><b>Scheduler:</b></dt>
10098 * <dd>{@code join} does not operate by default on a particular {@link Scheduler}.</dd>
10099 * </dl>
10100 *
10101 * @param <TRight> the value type of the right {@code ObservableSource} source
10102 * @param <TLeftEnd> the element type of the left duration {@code ObservableSource}s
10103 * @param <TRightEnd> the element type of the right duration {@code ObservableSource}s
10104 * @param <R> the result type
10105 * @param other
10106 * the second {@code ObservableSource} to join items from
10107 * @param leftEnd
10108 * a function to select a duration for each item emitted by the current {@code Observable}, used to
10109 * determine overlap
10110 * @param rightEnd
10111 * a function to select a duration for each item emitted by the {@code right} {@code ObservableSource}, used to
10112 * determine overlap
10113 * @param resultSelector
10114 * a function that computes an item to be emitted by the resulting {@code Observable} for any two
10115 * overlapping items emitted by the two {@code ObservableSource}s
10116 * @return the new {@code Observable} instance
10117 * @throws NullPointerException if {@code other}, {@code leftEnd}, {@code rightEnd} or {@code resultSelector} is {@code null}
10118 * @see <a href="http://reactivex.io/documentation/operators/join.html">ReactiveX operators documentation: Join</a>
10119 */
10120 @CheckReturnValue
10121 @SchedulerSupport(SchedulerSupport.NONE)
10122 @NonNull
10123 public final <@NonNull TRight, @NonNull TLeftEnd, @NonNull TRightEnd, @NonNull R> Observable<R> join(
10124 @NonNull ObservableSource<? extends TRight> other,
10125 @NonNull Function<? super T, ? extends ObservableSource<TLeftEnd>> leftEnd,
10126 @NonNull Function<? super TRight, ? extends ObservableSource<TRightEnd>> rightEnd,
10127 @NonNull BiFunction<? super T, ? super TRight, ? extends R> resultSelector
10128 ) {
10129 Objects.requireNonNull(other, "other is null");
10130 Objects.requireNonNull(leftEnd, "leftEnd is null");
10131 Objects.requireNonNull(rightEnd, "rightEnd is null");
10132 Objects.requireNonNull(resultSelector, "resultSelector is null");
10133 return RxJavaPlugins.onAssembly(new ObservableJoin<T, TRight, TLeftEnd, TRightEnd, R>(
10134 this, other, leftEnd, rightEnd, resultSelector));
10135 }
10136
10137 /**
10138 * Returns a {@link Maybe} that emits the last item emitted by the current {@code Observable} or
10139 * completes if the current {@code Observable} is empty.
10140 * <p>
10141 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/lastElement.v3.png" alt="">
10142 * <dl>
10143 * <dt><b>Scheduler:</b></dt>
10144 * <dd>{@code lastElement} does not operate by default on a particular {@link Scheduler}.</dd>
10145 * </dl>
10146 *
10147 * @return the new {@code Maybe} instance
10148 * @see <a href="http://reactivex.io/documentation/operators/last.html">ReactiveX operators documentation: Last</a>
10149 */
10150 @CheckReturnValue
10151 @SchedulerSupport(SchedulerSupport.NONE)
10152 @NonNull
10153 public final Maybe<T> lastElement() {
10154 return RxJavaPlugins.onAssembly(new ObservableLastMaybe<>(this));
10155 }
10156
10157 /**
10158 * Returns a {@link Single} that emits only the last item emitted by the current {@code Observable}, or a default item
10159 * if the current {@code Observable} completes without emitting any items.
10160 * <p>
10161 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/last.2.v3.png" alt="">
10162 * <dl>
10163 * <dt><b>Scheduler:</b></dt>
10164 * <dd>{@code last} does not operate by default on a particular {@link Scheduler}.</dd>
10165 * </dl>
10166 *
10167 * @param defaultItem
10168 * the default item to emit if the current {@code Observable} is empty
10169 * @return the new {@code Single} instance
10170 * @throws NullPointerException if {@code defaultItem} is {@code null}
10171 * @see <a href="http://reactivex.io/documentation/operators/last.html">ReactiveX operators documentation: Last</a>
10172 */
10173 @CheckReturnValue
10174 @SchedulerSupport(SchedulerSupport.NONE)
10175 @NonNull
10176 public final Single<T> last(@NonNull T defaultItem) {
10177 Objects.requireNonNull(defaultItem, "defaultItem is null");
10178 return RxJavaPlugins.onAssembly(new ObservableLastSingle<>(this, defaultItem));
10179 }
10180
10181 /**
10182 * Returns a {@link Single} that emits only the last item emitted by the current {@code Observable} or
10183 * signals a {@link NoSuchElementException} if the current {@code Observable} is empty.
10184 * <p>
10185 * <img width="640" height="236" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/lastOrError.png" alt="">
10186 * <dl>
10187 * <dt><b>Scheduler:</b></dt>
10188 * <dd>{@code lastOrError} does not operate by default on a particular {@link Scheduler}.</dd>
10189 * </dl>
10190 *
10191 * @return the new {@code Single} instance
10192 * @see <a href="http://reactivex.io/documentation/operators/last.html">ReactiveX operators documentation: Last</a>
10193 */
10194 @CheckReturnValue
10195 @SchedulerSupport(SchedulerSupport.NONE)
10196 @NonNull
10197 public final Single<T> lastOrError() {
10198 return RxJavaPlugins.onAssembly(new ObservableLastSingle<>(this, null));
10199 }
10200
10201 /**
10202 * <strong>This method requires advanced knowledge about building operators, please consider
10203 * other standard composition methods first;</strong>
10204 * Returns an {@code Observable} which, when subscribed to, invokes the {@link ObservableOperator#apply(Observer) apply(Observer)} method
10205 * of the provided {@link ObservableOperator} for each individual downstream {@link Observer} and allows the
10206 * insertion of a custom operator by accessing the downstream's {@code Observer} during this subscription phase
10207 * and providing a new {@code Observer}, containing the custom operator's intended business logic, that will be
10208 * used in the subscription process going further upstream.
10209 * <p>
10210 * Generally, such a new {@code Observer} will wrap the downstream's {@code Observer} and forwards the
10211 * {@code onNext}, {@code onError} and {@code onComplete} events from the upstream directly or according to the
10212 * emission pattern the custom operator's business logic requires. In addition, such operator can intercept the
10213 * flow control calls of {@code dispose} and {@code isDisposed} that would have traveled upstream and perform
10214 * additional actions depending on the same business logic requirements.
10215 * <p>
10216 * Example:
10217 * <pre><code>
10218 * // Step 1: Create the consumer type that will be returned by the ObservableOperator.apply():
10219 *
10220 * public final class CustomObserver&lt;T&gt; implements Observer&lt;T&gt;, Disposable {
10221 *
10222 * // The downstream's Observer that will receive the onXXX events
10223 * final Observer&lt;? super String&gt; downstream;
10224 *
10225 * // The connection to the upstream source that will call this class' onXXX methods
10226 * Disposable upstream;
10227 *
10228 * // The constructor takes the downstream subscriber and usually any other parameters
10229 * public CustomObserver(Observer&lt;? super String&gt; downstream) {
10230 * this.downstream = downstream;
10231 * }
10232 *
10233 * // In the subscription phase, the upstream sends a Disposable to this class
10234 * // and subsequently this class has to send a Disposable to the downstream.
10235 * // Note that relaying the upstream's Disposable directly is not allowed in RxJava
10236 * &#64;Override
10237 * public void onSubscribe(Disposable d) {
10238 * if (upstream != null) {
10239 * d.dispose();
10240 * } else {
10241 * upstream = d;
10242 * downstream.onSubscribe(this);
10243 * }
10244 * }
10245 *
10246 * // The upstream calls this with the next item and the implementation's
10247 * // responsibility is to emit an item to the downstream based on the intended
10248 * // business logic, or if it can't do so for the particular item,
10249 * // request more from the upstream
10250 * &#64;Override
10251 * public void onNext(T item) {
10252 * String str = item.toString();
10253 * if (str.length() &lt; 2) {
10254 * downstream.onNext(str);
10255 * }
10256 * // Observable doesn't support backpressure, therefore, there is no
10257 * // need or opportunity to call upstream.request(1) if an item
10258 * // is not produced to the downstream
10259 * }
10260 *
10261 * // Some operators may handle the upstream's error while others
10262 * // could just forward it to the downstream.
10263 * &#64;Override
10264 * public void onError(Throwable throwable) {
10265 * downstream.onError(throwable);
10266 * }
10267 *
10268 * // When the upstream completes, usually the downstream should complete as well.
10269 * &#64;Override
10270 * public void onComplete() {
10271 * downstream.onComplete();
10272 * }
10273 *
10274 * // Some operators may use their own resources which should be cleaned up if
10275 * // the downstream disposes the flow before it completed. Operators without
10276 * // resources can simply forward the dispose to the upstream.
10277 * // In some cases, a disposed flag may be set by this method so that other parts
10278 * // of this class may detect the dispose and stop sending events
10279 * // to the downstream.
10280 * &#64;Override
10281 * public void dispose() {
10282 * upstream.dispose();
10283 * }
10284 *
10285 * // Some operators may simply forward the call to the upstream while others
10286 * // can return the disposed flag set in dispose().
10287 * &#64;Override
10288 * public boolean isDisposed() {
10289 * return upstream.isDisposed();
10290 * }
10291 * }
10292 *
10293 * // Step 2: Create a class that implements the ObservableOperator interface and
10294 * // returns the custom consumer type from above in its apply() method.
10295 * // Such class may define additional parameters to be submitted to
10296 * // the custom consumer type.
10297 *
10298 * final class CustomOperator&lt;T&gt; implements ObservableOperator&lt;String, T&gt; {
10299 * &#64;Override
10300 * public Observer&lt;T&gt; apply(Observer&lt;? super String&gt; downstream) {
10301 * return new CustomObserver&lt;T&gt;(downstream);
10302 * }
10303 * }
10304 *
10305 * // Step 3: Apply the custom operator via lift() in a flow by creating an instance of it
10306 * // or reusing an existing one.
10307 *
10308 * Observable.range(5, 10)
10309 * .lift(new CustomOperator&lt;Integer&gt;())
10310 * .test()
10311 * .assertResult("5", "6", "7", "8", "9");
10312 * </code></pre>
10313 * <p>
10314 * Creating custom operators can be complicated and it is recommended one consults the
10315 * <a href="https://github.com/ReactiveX/RxJava/wiki/Writing-operators-for-2.0">RxJava wiki: Writing operators</a> page about
10316 * the tools, requirements, rules, considerations and pitfalls of implementing them.
10317 * <p>
10318 * Note that implementing custom operators via this {@code lift()} method adds slightly more overhead by requiring
10319 * an additional allocation and indirection per assembled flows. Instead, extending the abstract {@code Observable}
10320 * class and creating an {@link ObservableTransformer} with it is recommended.
10321 * <p>
10322 * Note also that it is not possible to stop the subscription phase in {@code lift()} as the {@code apply()} method
10323 * requires a non-{@code null} {@code Observer} instance to be returned, which is then unconditionally subscribed to
10324 * the current {@code Observable}. For example, if the operator decided there is no reason to subscribe to the
10325 * upstream source because of some optimization possibility or a failure to prepare the operator, it still has to
10326 * return an {@code Observer} that should immediately dispose the upstream's {@link Disposable} in its
10327 * {@code onSubscribe} method. Again, using an {@code ObservableTransformer} and extending the {@code Observable} is
10328 * a better option as {@link #subscribeActual} can decide to not subscribe to its upstream after all.
10329 * <dl>
10330 * <dt><b>Scheduler:</b></dt>
10331 * <dd>{@code lift} does not operate by default on a particular {@link Scheduler}, however, the
10332 * {@code ObservableOperator} may use a {@code Scheduler} to support its own asynchronous behavior.</dd>
10333 * </dl>
10334 *
10335 * @param <R> the output value type
10336 * @param lifter the {@code ObservableOperator} that receives the downstream's {@code Observer} and should return
10337 * an {@code Observer} with custom behavior to be used as the consumer for the current
10338 * {@code Observable}.
10339 * @return the new {@code Observable} instance
10340 * @throws NullPointerException if {@code lifter} is {@code null}
10341 * @see <a href="https://github.com/ReactiveX/RxJava/wiki/Writing-operators-for-2.0">RxJava wiki: Writing operators</a>
10342 * @see #compose(ObservableTransformer)
10343 */
10344 @CheckReturnValue
10345 @SchedulerSupport(SchedulerSupport.NONE)
10346 @NonNull
10347 public final <@NonNull R> Observable<R> lift(@NonNull ObservableOperator<? extends R, ? super T> lifter) {
10348 Objects.requireNonNull(lifter, "lifter is null");
10349 return RxJavaPlugins.onAssembly(new ObservableLift<>(this, lifter));
10350 }
10351
10352 /**
10353 * Returns an {@code Observable} that applies a specified function to each item emitted by the current {@code Observable} and
10354 * emits the results of these function applications.
10355 * <p>
10356 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/map.v3.png" alt="">
10357 * <dl>
10358 * <dt><b>Scheduler:</b></dt>
10359 * <dd>{@code map} does not operate by default on a particular {@link Scheduler}.</dd>
10360 * </dl>
10361 *
10362 * @param <R> the output type
10363 * @param mapper
10364 * a function to apply to each item emitted by the current {@code Observable}
10365 * @return the new {@code Observable} instance
10366 * @throws NullPointerException if {@code mapper} is {@code null}
10367 * @see <a href="http://reactivex.io/documentation/operators/map.html">ReactiveX operators documentation: Map</a>
10368 */
10369 @CheckReturnValue
10370 @SchedulerSupport(SchedulerSupport.NONE)
10371 @NonNull
10372 public final <@NonNull R> Observable<R> map(@NonNull Function<? super T, ? extends R> mapper) {
10373 Objects.requireNonNull(mapper, "mapper is null");
10374 return RxJavaPlugins.onAssembly(new ObservableMap<>(this, mapper));
10375 }
10376
10377 /**
10378 * Returns an {@code Observable} that represents all of the emissions <em>and</em> notifications from the current
10379 * {@code Observable} into emissions marked with their original types within {@link Notification} objects.
10380 * <p>
10381 * <img width="640" height="315" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/materialize.v3.png" alt="">
10382 * <dl>
10383 * <dt><b>Scheduler:</b></dt>
10384 * <dd>{@code materialize} does not operate by default on a particular {@link Scheduler}.</dd>
10385 * </dl>
10386 *
10387 * @return the new {@code Observable} instance
10388 * @see <a href="http://reactivex.io/documentation/operators/materialize-dematerialize.html">ReactiveX operators documentation: Materialize</a>
10389 * @see #dematerialize(Function)
10390 */
10391 @CheckReturnValue
10392 @SchedulerSupport(SchedulerSupport.NONE)
10393 @NonNull
10394 public final Observable<Notification<T>> materialize() {
10395 return RxJavaPlugins.onAssembly(new ObservableMaterialize<>(this));
10396 }
10397
10398 /**
10399 * Flattens the current {@code Observable} and another {@link ObservableSource} into a single {@code Observable} sequence, without any transformation.
10400 * <p>
10401 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/merge.v3.png" alt="">
10402 * <p>
10403 * You can combine items emitted by multiple {@code ObservableSource}s so that they appear as a single {@code ObservableSource}, by
10404 * using the {@code mergeWith} method.
10405 * <dl>
10406 * <dt><b>Scheduler:</b></dt>
10407 * <dd>{@code mergeWith} does not operate by default on a particular {@link Scheduler}.</dd>
10408 * </dl>
10409 *
10410 * @param other
10411 * an {@code ObservableSource} to be merged
10412 * @return the new {@code Observable} instance
10413 * @throws NullPointerException if {@code other} is {@code null}
10414 * @see <a href="http://reactivex.io/documentation/operators/merge.html">ReactiveX operators documentation: Merge</a>
10415 */
10416 @CheckReturnValue
10417 @SchedulerSupport(SchedulerSupport.NONE)
10418 @NonNull
10419 public final Observable<T> mergeWith(@NonNull ObservableSource<? extends T> other) {
10420 Objects.requireNonNull(other, "other is null");
10421 return merge(this, other);
10422 }
10423
10424 /**
10425 * Merges the sequence of items of the current {@code Observable} with the success value of the other {@link SingleSource}.
10426 * <p>
10427 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/merge.v3.png" alt="">
10428 * <p>
10429 * The success value of the other {@code SingleSource} can get interleaved at any point of the current
10430 * {@code Observable} sequence.
10431 * <dl>
10432 * <dt><b>Scheduler:</b></dt>
10433 * <dd>{@code mergeWith} does not operate by default on a particular {@link Scheduler}.</dd>
10434 * </dl>
10435 * <p>History: 2.1.10 - experimental
10436 * @param other the {@code SingleSource} whose success value to merge with
10437 * @return the new {@code Observable} instance
10438 * @throws NullPointerException if {@code other} is {@code null}
10439 * @since 2.2
10440 */
10441 @CheckReturnValue
10442 @SchedulerSupport(SchedulerSupport.NONE)
10443 @NonNull
10444 public final Observable<T> mergeWith(@NonNull SingleSource<? extends T> other) {
10445 Objects.requireNonNull(other, "other is null");
10446 return RxJavaPlugins.onAssembly(new ObservableMergeWithSingle<>(this, other));
10447 }
10448
10449 /**
10450 * Merges the sequence of items of the current {@code Observable} with the success value of the other {@link MaybeSource}
10451 * or waits both to complete normally if the {@code MaybeSource} is empty.
10452 * <p>
10453 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/merge.v3.png" alt="">
10454 * <p>
10455 * The success value of the other {@code MaybeSource} can get interleaved at any point of the current
10456 * {@code Observable} sequence.
10457 * <dl>
10458 * <dt><b>Scheduler:</b></dt>
10459 * <dd>{@code mergeWith} does not operate by default on a particular {@link Scheduler}.</dd>
10460 * </dl>
10461 * <p>History: 2.1.10 - experimental
10462 * @param other the {@code MaybeSource} which provides a success value to merge with or completes
10463 * @return the new {@code Observable} instance
10464 * @throws NullPointerException if {@code other} is {@code null}
10465 * @since 2.2
10466 */
10467 @CheckReturnValue
10468 @SchedulerSupport(SchedulerSupport.NONE)
10469 @NonNull
10470 public final Observable<T> mergeWith(@NonNull MaybeSource<? extends T> other) {
10471 Objects.requireNonNull(other, "other is null");
10472 return RxJavaPlugins.onAssembly(new ObservableMergeWithMaybe<>(this, other));
10473 }
10474
10475 /**
10476 * Relays the items of the current {@code Observable} and completes only when the other {@link CompletableSource} completes
10477 * as well.
10478 * <p>
10479 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/merge.v3.png" alt="">
10480 * <dl>
10481 * <dt><b>Scheduler:</b></dt>
10482 * <dd>{@code mergeWith} does not operate by default on a particular {@link Scheduler}.</dd>
10483 * </dl>
10484 * <p>History: 2.1.10 - experimental
10485 * @param other the {@code CompletableSource} to await for completion
10486 * @return the new {@code Observable} instance
10487 * @throws NullPointerException if {@code other} is {@code null}
10488 * @since 2.2
10489 */
10490 @CheckReturnValue
10491 @SchedulerSupport(SchedulerSupport.NONE)
10492 @NonNull
10493 public final Observable<T> mergeWith(@NonNull CompletableSource other) {
10494 Objects.requireNonNull(other, "other is null");
10495 return RxJavaPlugins.onAssembly(new ObservableMergeWithCompletable<>(this, other));
10496 }
10497
10498 /**
10499 * Returns an {@code Observable} to perform the current {@code Observable}'s emissions and notifications on a specified {@link Scheduler},
10500 * asynchronously with an unbounded buffer with {@link Flowable#bufferSize()} "island size".
10501 *
10502 * <p>Note that {@code onError} notifications will cut ahead of {@code onNext} notifications on the emission thread if {@code Scheduler} is truly
10503 * asynchronous. If strict event ordering is required, consider using the {@link #observeOn(Scheduler, boolean)} overload.
10504 * <p>
10505 * <img width="640" height="308" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/observeOn.v3.png" alt="">
10506 * <p>
10507 * This operator keeps emitting as many signals as it can on the given {@code Scheduler}'s worker thread,
10508 * which may result in a longer than expected occupation of this thread. In other terms,
10509 * it does not allow per-signal fairness in case the worker runs on a shared underlying thread.
10510 * If such fairness and signal/work interleaving is preferred, use the delay operator with zero time instead.
10511 * <dl>
10512 * <dt><b>Scheduler:</b></dt>
10513 * <dd>You specify which {@code Scheduler} this operator will use.</dd>
10514 * </dl>
10515 * <p>"Island size" indicates how large chunks the unbounded buffer allocates to store the excess elements waiting to be consumed
10516 * on the other side of the asynchronous boundary.
10517 *
10518 * @param scheduler
10519 * the {@code Scheduler} to notify {@link Observer}s on
10520 * @return the new {@code Observable} instance
10521 * @throws NullPointerException if {@code scheduler} is {@code null}
10522 * @see <a href="http://reactivex.io/documentation/operators/observeon.html">ReactiveX operators documentation: ObserveOn</a>
10523 * @see <a href="http://www.grahamlea.com/2014/07/rxjava-threading-examples/">RxJava Threading Examples</a>
10524 * @see #subscribeOn
10525 * @see #observeOn(Scheduler, boolean)
10526 * @see #observeOn(Scheduler, boolean, int)
10527 * @see #delay(long, TimeUnit, Scheduler)
10528 */
10529 @CheckReturnValue
10530 @SchedulerSupport(SchedulerSupport.CUSTOM)
10531 @NonNull
10532 public final Observable<T> observeOn(@NonNull Scheduler scheduler) {
10533 return observeOn(scheduler, false, bufferSize());
10534 }
10535
10536 /**
10537 * Returns an {@code Observable} to perform the current {@code Observable}'s emissions and notifications on a specified {@link Scheduler},
10538 * asynchronously with an unbounded buffer with {@link Flowable#bufferSize()} "island size" and optionally delays {@code onError} notifications.
10539 * <p>
10540 * <img width="640" height="308" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/observeOn.v3.png" alt="">
10541 * <p>
10542 * This operator keeps emitting as many signals as it can on the given {@code Scheduler}'s worker thread,
10543 * which may result in a longer than expected occupation of this thread. In other terms,
10544 * it does not allow per-signal fairness in case the worker runs on a shared underlying thread.
10545 * If such fairness and signal/work interleaving is preferred, use the delay operator with zero time instead.
10546 * <dl>
10547 * <dt><b>Scheduler:</b></dt>
10548 * <dd>You specify which {@code Scheduler} this operator will use.</dd>
10549 * </dl>
10550 * <p>"Island size" indicates how large chunks the unbounded buffer allocates to store the excess elements waiting to be consumed
10551 * on the other side of the asynchronous boundary.
10552 *
10553 * @param scheduler
10554 * the {@code Scheduler} to notify {@link Observer}s on
10555 * @param delayError
10556 * indicates if the {@code onError} notification may not cut ahead of {@code onNext} notification on the other side of the
10557 * scheduling boundary. If {@code true}, a sequence ending in {@code onError} will be replayed in the same order as was received
10558 * from the current {@code Observable}
10559 * @return the new {@code Observable} instance
10560 * @throws NullPointerException if {@code scheduler} is {@code null}
10561 * @see <a href="http://reactivex.io/documentation/operators/observeon.html">ReactiveX operators documentation: ObserveOn</a>
10562 * @see <a href="http://www.grahamlea.com/2014/07/rxjava-threading-examples/">RxJava Threading Examples</a>
10563 * @see #subscribeOn
10564 * @see #observeOn(Scheduler)
10565 * @see #observeOn(Scheduler, boolean, int)
10566 * @see #delay(long, TimeUnit, Scheduler, boolean)
10567 */
10568 @CheckReturnValue
10569 @SchedulerSupport(SchedulerSupport.CUSTOM)
10570 @NonNull
10571 public final Observable<T> observeOn(@NonNull Scheduler scheduler, boolean delayError) {
10572 return observeOn(scheduler, delayError, bufferSize());
10573 }
10574
10575 /**
10576 * Returns an {@code Observable} to perform the current {@code Observable}'s emissions and notifications on a specified {@link Scheduler},
10577 * asynchronously with an unbounded buffer of configurable "island size" and optionally delays {@code onError} notifications.
10578 * <p>
10579 * <img width="640" height="308" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/observeOn.v3.png" alt="">
10580 * <p>
10581 * This operator keeps emitting as many signals as it can on the given {@code Scheduler}'s worker thread,
10582 * which may result in a longer than expected occupation of this thread. In other terms,
10583 * it does not allow per-signal fairness in case the worker runs on a shared underlying thread.
10584 * If such fairness and signal/work interleaving is preferred, use the delay operator with zero time instead.
10585 * <dl>
10586 * <dt><b>Scheduler:</b></dt>
10587 * <dd>You specify which {@code Scheduler} this operator will use.</dd>
10588 * </dl>
10589 * <p>"Island size" indicates how large chunks the unbounded buffer allocates to store the excess elements waiting to be consumed
10590 * on the other side of the asynchronous boundary. Values below 16 are not recommended in performance sensitive scenarios.
10591 *
10592 * @param scheduler
10593 * the {@code Scheduler} to notify {@link Observer}s on
10594 * @param delayError
10595 * indicates if the {@code onError} notification may not cut ahead of {@code onNext} notification on the other side of the
10596 * scheduling boundary. If {@code true} a sequence ending in {@code onError} will be replayed in the same order as was received
10597 * from upstream
10598 * @param bufferSize the size of the buffer.
10599 * @return the new {@code Observable} instance
10600 * @throws NullPointerException if {@code scheduler} is {@code null}
10601 * @throws IllegalArgumentException if {@code bufferSize} is non-positive
10602 * @see <a href="http://reactivex.io/documentation/operators/observeon.html">ReactiveX operators documentation: ObserveOn</a>
10603 * @see <a href="http://www.grahamlea.com/2014/07/rxjava-threading-examples/">RxJava Threading Examples</a>
10604 * @see #subscribeOn
10605 * @see #observeOn(Scheduler)
10606 * @see #observeOn(Scheduler, boolean)
10607 * @see #delay(long, TimeUnit, Scheduler, boolean)
10608 */
10609 @CheckReturnValue
10610 @SchedulerSupport(SchedulerSupport.CUSTOM)
10611 @NonNull
10612 public final Observable<T> observeOn(@NonNull Scheduler scheduler, boolean delayError, int bufferSize) {
10613 Objects.requireNonNull(scheduler, "scheduler is null");
10614 ObjectHelper.verifyPositive(bufferSize, "bufferSize");
10615 return RxJavaPlugins.onAssembly(new ObservableObserveOn<>(this, scheduler, delayError, bufferSize));
10616 }
10617
10618 /**
10619 * Filters the items emitted by the current {@code Observable}, only emitting those of the specified type.
10620 * <p>
10621 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/ofClass.v3.png" alt="">
10622 * <dl>
10623 * <dt><b>Scheduler:</b></dt>
10624 * <dd>{@code ofType} does not operate by default on a particular {@link Scheduler}.</dd>
10625 * </dl>
10626 *
10627 * @param <U> the output type
10628 * @param clazz
10629 * the class type to filter the items emitted by the current {@code Observable}
10630 * @return the new {@code Observable} instance
10631 * @throws NullPointerException if {@code clazz} is {@code null}
10632 * @see <a href="http://reactivex.io/documentation/operators/filter.html">ReactiveX operators documentation: Filter</a>
10633 */
10634 @CheckReturnValue
10635 @SchedulerSupport(SchedulerSupport.NONE)
10636 @NonNull
10637 public final <@NonNull U> Observable<U> ofType(@NonNull Class<U> clazz) {
10638 Objects.requireNonNull(clazz, "clazz is null");
10639 return filter(Functions.isInstanceOf(clazz)).cast(clazz);
10640 }
10641
10642 /**
10643 * Returns an {@code Observable} instance that if the current {@code Observable} emits an error, it will emit an {@code onComplete}
10644 * and swallow the throwable.
10645 * <p>
10646 * <img width="640" height="373" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Observable.onErrorComplete.png" alt="">
10647 * <dl>
10648 * <dt><b>Scheduler:</b></dt>
10649 * <dd>{@code onErrorComplete} does not operate by default on a particular {@link Scheduler}.</dd>
10650 * </dl>
10651 * @return the new {@code Observable} instance
10652 * @since 3.0.0
10653 */
10654 @CheckReturnValue
10655 @SchedulerSupport(SchedulerSupport.NONE)
10656 @NonNull
10657 public final Observable<T> onErrorComplete() {
10658 return onErrorComplete(Functions.alwaysTrue());
10659 }
10660
10661 /**
10662 * Returns an {@code Observable} instance that if the current {@code Observable} emits an error and the predicate returns
10663 * {@code true}, it will emit an {@code onComplete} and swallow the throwable.
10664 * <p>
10665 * <img width="640" height="215" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Observable.onErrorComplete.f.png" alt="">
10666 * <dl>
10667 * <dt><b>Scheduler:</b></dt>
10668 * <dd>{@code onErrorComplete} does not operate by default on a particular {@link Scheduler}.</dd>
10669 * </dl>
10670 * @param predicate the predicate to call when an {@link Throwable} is emitted which should return {@code true}
10671 * if the {@code Throwable} should be swallowed and replaced with an {@code onComplete}.
10672 * @return the new {@code Observable} instance
10673 * @throws NullPointerException if {@code predicate} is {@code null}
10674 * @since 3.0.0
10675 */
10676 @CheckReturnValue
10677 @NonNull
10678 @SchedulerSupport(SchedulerSupport.NONE)
10679 public final Observable<T> onErrorComplete(@NonNull Predicate<? super Throwable> predicate) {
10680 Objects.requireNonNull(predicate, "predicate is null");
10681
10682 return RxJavaPlugins.onAssembly(new ObservableOnErrorComplete<>(this, predicate));
10683 }
10684
10685 /**
10686 * Resumes the flow with an {@link ObservableSource} returned for the failure {@link Throwable} of the current {@code Observable} by a
10687 * function instead of signaling the error via {@code onError}.
10688 * <p>
10689 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/onErrorResumeNext.v3.png" alt="">
10690 * <p>
10691 * By default, when an {@code ObservableSource} encounters an error that prevents it from emitting the expected item to
10692 * its {@link Observer}, the {@code ObservableSource} invokes its {@code Observer}'s {@code onError} method, and then quits
10693 * without invoking any more of its {@code Observer}'s methods. The {@code onErrorResumeNext} method changes this
10694 * behavior. If you pass a function that returns an {@code ObservableSource} ({@code resumeFunction}) to
10695 * {@code onErrorResumeNext}, if the original {@code ObservableSource} encounters an error, instead of invoking its
10696 * {@code Observer}'s {@code onError} method, it will instead relinquish control to the {@code ObservableSource} returned from
10697 * {@code resumeFunction}, which will invoke the {@code Observer}'s {@link Observer#onNext onNext} method if it is
10698 * able to do so. In such a case, because no {@code ObservableSource} necessarily invokes {@code onError}, the {@code Observer}
10699 * may never know that an error happened.
10700 * <p>
10701 * You can use this to prevent errors from propagating or to supply fallback data should errors be
10702 * encountered.
10703 * <dl>
10704 * <dt><b>Scheduler:</b></dt>
10705 * <dd>{@code onErrorResumeNext} does not operate by default on a particular {@link Scheduler}.</dd>
10706 * </dl>
10707 *
10708 * @param fallbackSupplier
10709 * a function that returns an {@code ObservableSource} that will take over if the current {@code Observable} encounters
10710 * an error
10711 * @return the new {@code Observable} instance
10712 * @throws NullPointerException if {@code fallbackSupplier} is {@code null}
10713 * @see <a href="http://reactivex.io/documentation/operators/catch.html">ReactiveX operators documentation: Catch</a>
10714 */
10715 @CheckReturnValue
10716 @SchedulerSupport(SchedulerSupport.NONE)
10717 @NonNull
10718 public final Observable<T> onErrorResumeNext(@NonNull Function<? super Throwable, ? extends ObservableSource<? extends T>> fallbackSupplier) {
10719 Objects.requireNonNull(fallbackSupplier, "fallbackSupplier is null");
10720 return RxJavaPlugins.onAssembly(new ObservableOnErrorNext<>(this, fallbackSupplier));
10721 }
10722
10723 /**
10724 * Resumes the flow with the given {@link ObservableSource} when the current {@code Observable} fails instead of
10725 * signaling the error via {@code onError}.
10726 * <p>
10727 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/onErrorResumeWith.v3.png" alt="">
10728 * <p>
10729 * By default, when an {@code ObservableSource} encounters an error that prevents it from emitting the expected item to
10730 * its {@link Observer}, the {@code ObservableSource} invokes its {@code Observer}'s {@code onError} method, and then quits
10731 * without invoking any more of its {@code Observer}'s methods. The {@code onErrorResumeWith} method changes this
10732 * behavior. If you pass another {@code ObservableSource} ({@code next}) to an {@code ObservableSource}'s
10733 * {@code onErrorResumeWith} method, if the original {@code ObservableSource} encounters an error, instead of invoking its
10734 * {@code Observer}'s {@code onError} method, it will instead relinquish control to {@code next} which
10735 * will invoke the {@code Observer}'s {@link Observer#onNext onNext} method if it is able to do so. In such a case,
10736 * because no {@code ObservableSource} necessarily invokes {@code onError}, the {@code Observer} may never know that an error
10737 * happened.
10738 * <p>
10739 * You can use this to prevent errors from propagating or to supply fallback data should errors be
10740 * encountered.
10741 * <dl>
10742 * <dt><b>Scheduler:</b></dt>
10743 * <dd>{@code onErrorResumeWith} does not operate by default on a particular {@link Scheduler}.</dd>
10744 * </dl>
10745 *
10746 * @param fallback
10747 * the next {@code ObservableSource} source that will take over if the current {@code Observable} encounters
10748 * an error
10749 * @return the new {@code Observable} instance
10750 * @throws NullPointerException if {@code fallback} is {@code null}
10751 * @see <a href="http://reactivex.io/documentation/operators/catch.html">ReactiveX operators documentation: Catch</a>
10752 */
10753 @CheckReturnValue
10754 @SchedulerSupport(SchedulerSupport.NONE)
10755 @NonNull
10756 public final Observable<T> onErrorResumeWith(@NonNull ObservableSource<? extends T> fallback) {
10757 Objects.requireNonNull(fallback, "fallback is null");
10758 return onErrorResumeNext(Functions.justFunction(fallback));
10759 }
10760
10761 /**
10762 * Ends the flow with a last item returned by a function for the {@link Throwable} error signaled by the current
10763 * {@code Observable} instead of signaling the error via {@code onError}.
10764 * <p>
10765 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/onErrorReturn.o.v3.png" alt="">
10766 * <p>
10767 * By default, when an {@link ObservableSource} encounters an error that prevents it from emitting the expected item to
10768 * its {@link Observer}, the {@code ObservableSource} invokes its {@code Observer}'s {@code onError} method, and then quits
10769 * without invoking any more of its {@code Observer}'s methods. The {@code onErrorReturn} method changes this
10770 * behavior. If you pass a function ({@code resumeFunction}) to an {@code ObservableSource}'s {@code onErrorReturn}
10771 * method, if the original {@code ObservableSource} encounters an error, instead of invoking its {@code Observer}'s
10772 * {@code onError} method, it will instead emit the return value of {@code resumeFunction}.
10773 * <p>
10774 * You can use this to prevent errors from propagating or to supply fallback data should errors be
10775 * encountered.
10776 * <dl>
10777 * <dt><b>Scheduler:</b></dt>
10778 * <dd>{@code onErrorReturn} does not operate by default on a particular {@link Scheduler}.</dd>
10779 * </dl>
10780 *
10781 * @param itemSupplier
10782 * a function that returns a single value that will be emitted along with a regular {@code onComplete} in case
10783 * the current {@code Observable} signals an {@code onError} event
10784 * @return the new {@code Observable} instance
10785 * @throws NullPointerException if {@code itemSupplier} is {@code null}
10786 * @see <a href="http://reactivex.io/documentation/operators/catch.html">ReactiveX operators documentation: Catch</a>
10787 */
10788 @CheckReturnValue
10789 @SchedulerSupport(SchedulerSupport.NONE)
10790 @NonNull
10791 public final Observable<T> onErrorReturn(@NonNull Function<? super Throwable, ? extends T> itemSupplier) {
10792 Objects.requireNonNull(itemSupplier, "itemSupplier is null");
10793 return RxJavaPlugins.onAssembly(new ObservableOnErrorReturn<>(this, itemSupplier));
10794 }
10795
10796 /**
10797 * Ends the flow with the given last item when the current {@code Observable} fails instead of signaling the error via {@code onError}.
10798 * <p>
10799 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/onErrorReturnItem.o.v3.png" alt="">
10800 * <p>
10801 * By default, when an {@link ObservableSource} encounters an error that prevents it from emitting the expected item to
10802 * its {@link Observer}, the {@code ObservableSource} invokes its {@code Observer}'s {@code onError} method, and then quits
10803 * without invoking any more of its {@code Observer}'s methods. The {@code onErrorReturn} method changes this
10804 * behavior. If you pass a function ({@code resumeFunction}) to an {@code ObservableSource}'s {@code onErrorReturn}
10805 * method, if the original {@code ObservableSource} encounters an error, instead of invoking its {@code Observer}'s
10806 * {@code onError} method, it will instead emit the return value of {@code resumeFunction}.
10807 * <p>
10808 * You can use this to prevent errors from propagating or to supply fallback data should errors be
10809 * encountered.
10810 * <dl>
10811 * <dt><b>Scheduler:</b></dt>
10812 * <dd>{@code onErrorReturnItem} does not operate by default on a particular {@link Scheduler}.</dd>
10813 * </dl>
10814 *
10815 * @param item
10816 * the value that is emitted along with a regular {@code onComplete} in case the current
10817 * {@code Observable} signals an exception
10818 * @return the new {@code Observable} instance
10819 * @throws NullPointerException if {@code item} is {@code null}
10820 * @see <a href="http://reactivex.io/documentation/operators/catch.html">ReactiveX operators documentation: Catch</a>
10821 */
10822 @CheckReturnValue
10823 @SchedulerSupport(SchedulerSupport.NONE)
10824 @NonNull
10825 public final Observable<T> onErrorReturnItem(@NonNull T item) {
10826 Objects.requireNonNull(item, "item is null");
10827 return onErrorReturn(Functions.justFunction(item));
10828 }
10829
10830 /**
10831 * Nulls out references to the upstream producer and downstream {@link Observer} if
10832 * the sequence is terminated or downstream calls {@code dispose()}.
10833 * <p>
10834 * <img width="640" height="247" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/onTerminateDetach.o.png" alt="">
10835 * <dl>
10836 * <dt><b>Scheduler:</b></dt>
10837 * <dd>{@code onTerminateDetach} does not operate by default on a particular {@link Scheduler}.</dd>
10838 * </dl>
10839 * @return the new {@code Observable} instance
10840 * the sequence is terminated or downstream calls {@code dispose()}
10841 * @since 2.0
10842 */
10843 @CheckReturnValue
10844 @SchedulerSupport(SchedulerSupport.NONE)
10845 @NonNull
10846 public final Observable<T> onTerminateDetach() {
10847 return RxJavaPlugins.onAssembly(new ObservableDetach<>(this));
10848 }
10849
10850 /**
10851 * Returns a {@link ConnectableObservable}, which is a variety of {@link ObservableSource} that waits until its
10852 * {@link ConnectableObservable#connect connect} method is called before it begins emitting items to those
10853 * {@link Observer}s that have subscribed to it.
10854 * <p>
10855 * <img width="640" height="510" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/publishConnect.v3.png" alt="">
10856 * <dl>
10857 * <dt><b>Scheduler:</b></dt>
10858 * <dd>{@code publish} does not operate by default on a particular {@link Scheduler}.</dd>
10859 * </dl>
10860 *
10861 * @return the new {@code ConnectableObservable} instance
10862 * @see <a href="http://reactivex.io/documentation/operators/publish.html">ReactiveX operators documentation: Publish</a>
10863 */
10864 @CheckReturnValue
10865 @SchedulerSupport(SchedulerSupport.NONE)
10866 @NonNull
10867 public final ConnectableObservable<T> publish() {
10868 return RxJavaPlugins.onAssembly(new ObservablePublish<>(this));
10869 }
10870
10871 /**
10872 * Returns an {@code Observable} that emits the results of invoking a specified selector on items emitted by a
10873 * {@link ConnectableObservable} that shares a single subscription to the current {@code Observable} sequence.
10874 * <p>
10875 * <img width="640" height="647" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/publishFunction.o.png" alt="">
10876 * <dl>
10877 * <dt><b>Scheduler:</b></dt>
10878 * <dd>{@code publish} does not operate by default on a particular {@link Scheduler}.</dd>
10879 * </dl>
10880 *
10881 * @param <R>
10882 * the type of items emitted by the resulting {@code Observable}
10883 * @param selector
10884 * a function that can use the multicasted source sequence as many times as needed, without
10885 * causing multiple subscriptions to the source sequence. {@link Observer}s to the given source will
10886 * receive all notifications of the source from the time of the subscription forward.
10887 * @return the new {@code Observable} instance
10888 * @throws NullPointerException if {@code selector} is {@code null}
10889 * @see <a href="http://reactivex.io/documentation/operators/publish.html">ReactiveX operators documentation: Publish</a>
10890 */
10891 @CheckReturnValue
10892 @SchedulerSupport(SchedulerSupport.NONE)
10893 @NonNull
10894 public final <@NonNull R> Observable<R> publish(@NonNull Function<? super Observable<T>, ? extends ObservableSource<R>> selector) {
10895 Objects.requireNonNull(selector, "selector is null");
10896 return RxJavaPlugins.onAssembly(new ObservablePublishSelector<>(this, selector));
10897 }
10898
10899 /**
10900 * Returns a {@link Maybe} that applies a specified accumulator function to the first item emitted by the current
10901 * {@code Observable}, then feeds the result of that function along with the second item emitted by the current
10902 * {@code Observable} into the same function, and so on until all items have been emitted by the current and finite {@code Observable},
10903 * and emits the final result from the final call to your function as its sole item.
10904 * <p>
10905 * <img width="640" height="320" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/reduce.2.v3.png" alt="">
10906 * <p>
10907 * This technique, which is called "reduce" here, is sometimes called "aggregate," "fold," "accumulate,"
10908 * "compress," or "inject" in other programming contexts. Groovy, for instance, has an {@code inject} method
10909 * that does a similar operation on lists.
10910 * <p>
10911 * Note that this operator requires the upstream to signal {@code onComplete} for the accumulator object to
10912 * be emitted. Sources that are infinite and never complete will never emit anything through this
10913 * operator and an infinite source may lead to a fatal {@link OutOfMemoryError}.
10914 * <dl>
10915 * <dt><b>Scheduler:</b></dt>
10916 * <dd>{@code reduce} does not operate by default on a particular {@link Scheduler}.</dd>
10917 * </dl>
10918 *
10919 * @param reducer
10920 * an accumulator function to be invoked on each item emitted by the current {@code Observable}, whose
10921 * result will be used in the next accumulator call
10922 * @return the new {@code Maybe} instance
10923 * @throws NullPointerException if {@code reducer} is {@code null}
10924 * @see <a href="http://reactivex.io/documentation/operators/reduce.html">ReactiveX operators documentation: Reduce</a>
10925 * @see <a href="http://en.wikipedia.org/wiki/Fold_(higher-order_function)">Wikipedia: Fold (higher-order function)</a>
10926 */
10927 @CheckReturnValue
10928 @SchedulerSupport(SchedulerSupport.NONE)
10929 @NonNull
10930 public final Maybe<T> reduce(@NonNull BiFunction<T, T, T> reducer) {
10931 Objects.requireNonNull(reducer, "reducer is null");
10932 return RxJavaPlugins.onAssembly(new ObservableReduceMaybe<>(this, reducer));
10933 }
10934
10935 /**
10936 * Returns a {@link Single} that applies a specified accumulator function to the first item emitted by the current
10937 * {@code Observable} and a specified seed value, then feeds the result of that function along with the second item
10938 * emitted by the current {@code Observable} into the same function, and so on until all items have been emitted by the
10939 * current and finite {@code Observable}, emitting the final result from the final call to your function as its sole item.
10940 * <p>
10941 * <img width="640" height="325" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/reduceSeed.o.v3.png" alt="">
10942 * <p>
10943 * This technique, which is called "reduce" here, is sometimes called "aggregate," "fold," "accumulate,"
10944 * "compress," or "inject" in other programming contexts. Groovy, for instance, has an {@code inject} method
10945 * that does a similar operation on lists.
10946 * <p>
10947 * Note that the {@code seed} is shared among all subscribers to the resulting {@code Observable}
10948 * and may cause problems if it is mutable. To make sure each subscriber gets its own value, defer
10949 * the application of this operator via {@link #defer(Supplier)}:
10950 * <pre><code>
10951 * ObservableSource&lt;T&gt; source = ...
10952 * Single.defer(() -&gt; source.reduce(new ArrayList&lt;&gt;(), (list, item) -&gt; list.add(item)));
10953 *
10954 * // alternatively, by using compose to stay fluent
10955 *
10956 * source.compose(o -&gt;
10957 * Observable.defer(() -&gt; o.reduce(new ArrayList&lt;&gt;(), (list, item) -&gt; list.add(item)).toObservable())
10958 * ).firstOrError();
10959 *
10960 * // or, by using reduceWith instead of reduce
10961 *
10962 * source.reduceWith(() -&gt; new ArrayList&lt;&gt;(), (list, item) -&gt; list.add(item)));
10963 * </code></pre>
10964 * <p>
10965 * Note that this operator requires the upstream to signal {@code onComplete} for the accumulator object to
10966 * be emitted. Sources that are infinite and never complete will never emit anything through this
10967 * operator and an infinite source may lead to a fatal {@link OutOfMemoryError}.
10968 * <dl>
10969 * <dt><b>Scheduler:</b></dt>
10970 * <dd>{@code reduce} does not operate by default on a particular {@link Scheduler}.</dd>
10971 * </dl>
10972 *
10973 * @param <R> the accumulator and output value type
10974 * @param seed
10975 * the initial (seed) accumulator value
10976 * @param reducer
10977 * an accumulator function to be invoked on each item emitted by the current {@code Observable}, the
10978 * result of which will be used in the next accumulator call
10979 * @return the new {@code Single} instance
10980 * @throws NullPointerException if {@code seed} or {@code reducer} is {@code null}
10981 * @see <a href="http://reactivex.io/documentation/operators/reduce.html">ReactiveX operators documentation: Reduce</a>
10982 * @see <a href="http://en.wikipedia.org/wiki/Fold_(higher-order_function)">Wikipedia: Fold (higher-order function)</a>
10983 * @see #reduceWith(Supplier, BiFunction)
10984 */
10985 @CheckReturnValue
10986 @SchedulerSupport(SchedulerSupport.NONE)
10987 @NonNull
10988 public final <@NonNull R> Single<R> reduce(R seed, @NonNull BiFunction<R, ? super T, R> reducer) {
10989 Objects.requireNonNull(seed, "seed is null");
10990 Objects.requireNonNull(reducer, "reducer is null");
10991 return RxJavaPlugins.onAssembly(new ObservableReduceSeedSingle<>(this, seed, reducer));
10992 }
10993
10994 /**
10995 * Returns a {@link Single} that applies a specified accumulator function to the first item emitted by the current
10996 * {@code Observable} and a seed value derived from calling a specified {@code seedSupplier}, then feeds the result
10997 * of that function along with the second item emitted by the current {@code Observable} into the same function,
10998 * and so on until all items have been emitted by the current and finite {@code Observable}, emitting the final result
10999 * from the final call to your function as its sole item.
11000 * <p>
11001 * <img width="640" height="325" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/reduceWith.o.v3.png" alt="">
11002 * <p>
11003 * This technique, which is called "reduce" here, is sometimes called "aggregate," "fold," "accumulate,"
11004 * "compress," or "inject" in other programming contexts. Groovy, for instance, has an {@code inject} method
11005 * that does a similar operation on lists.
11006 * <p>
11007 * Note that this operator requires the upstream to signal {@code onComplete} for the accumulator object to
11008 * be emitted. Sources that are infinite and never complete will never emit anything through this
11009 * operator and an infinite source may lead to a fatal {@link OutOfMemoryError}.
11010 * <dl>
11011 * <dt><b>Scheduler:</b></dt>
11012 * <dd>{@code reduceWith} does not operate by default on a particular {@link Scheduler}.</dd>
11013 * </dl>
11014 *
11015 * @param <R> the accumulator and output value type
11016 * @param seedSupplier
11017 * the {@link Supplier} that provides the initial (seed) accumulator value for each individual {@link Observer}
11018 * @param reducer
11019 * an accumulator function to be invoked on each item emitted by the current {@code Observable}, the
11020 * result of which will be used in the next accumulator call
11021 * @return the new {@code Single} instance
11022 * @throws NullPointerException if {@code seedSupplier} or {@code reducer} is {@code null}
11023 * @see <a href="http://reactivex.io/documentation/operators/reduce.html">ReactiveX operators documentation: Reduce</a>
11024 * @see <a href="http://en.wikipedia.org/wiki/Fold_(higher-order_function)">Wikipedia: Fold (higher-order function)</a>
11025 */
11026 @CheckReturnValue
11027 @SchedulerSupport(SchedulerSupport.NONE)
11028 @NonNull
11029 public final <@NonNull R> Single<R> reduceWith(@NonNull Supplier<R> seedSupplier, @NonNull BiFunction<R, ? super T, R> reducer) {
11030 Objects.requireNonNull(seedSupplier, "seedSupplier is null");
11031 Objects.requireNonNull(reducer, "reducer is null");
11032 return RxJavaPlugins.onAssembly(new ObservableReduceWithSingle<>(this, seedSupplier, reducer));
11033 }
11034
11035 /**
11036 * Returns an {@code Observable} that repeats the sequence of items emitted by the current {@code Observable} indefinitely.
11037 * <p>
11038 * <img width="640" height="287" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/repeatInf.o.png" alt="">
11039 * <dl>
11040 * <dt><b>Scheduler:</b></dt>
11041 * <dd>{@code repeat} does not operate by default on a particular {@link Scheduler}.</dd>
11042 * </dl>
11043 *
11044 * @return the new {@code Observable} instance
11045 * @see <a href="http://reactivex.io/documentation/operators/repeat.html">ReactiveX operators documentation: Repeat</a>
11046 */
11047 @CheckReturnValue
11048 @SchedulerSupport(SchedulerSupport.NONE)
11049 @NonNull
11050 public final Observable<T> repeat() {
11051 return repeat(Long.MAX_VALUE);
11052 }
11053
11054 /**
11055 * Returns an {@code Observable} that repeats the sequence of items emitted by the current {@code Observable} at most
11056 * {@code count} times.
11057 * <p>
11058 * <img width="640" height="336" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/repeatCount.o.png" alt="">
11059 * <dl>
11060 * <dt><b>Scheduler:</b></dt>
11061 * <dd>{@code repeat} does not operate by default on a particular {@link Scheduler}.</dd>
11062 * </dl>
11063 *
11064 * @param times
11065 * the number of times the current {@code Observable} items are repeated, a count of 0 will yield an empty
11066 * sequence
11067 * @return the new {@code Observable} instance
11068 * @throws IllegalArgumentException
11069 * if {@code times} is negative
11070 * @see <a href="http://reactivex.io/documentation/operators/repeat.html">ReactiveX operators documentation: Repeat</a>
11071 */
11072 @CheckReturnValue
11073 @SchedulerSupport(SchedulerSupport.NONE)
11074 @NonNull
11075 public final Observable<T> repeat(long times) {
11076 if (times < 0) {
11077 throw new IllegalArgumentException("times >= 0 required but it was " + times);
11078 }
11079 if (times == 0) {
11080 return empty();
11081 }
11082 return RxJavaPlugins.onAssembly(new ObservableRepeat<>(this, times));
11083 }
11084
11085 /**
11086 * Returns an {@code Observable} that repeats the sequence of items emitted by the current {@code Observable} until
11087 * the provided stop function returns {@code true}.
11088 * <p>
11089 * <img width="640" height="263" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/repeatUntil.o.png" alt="">
11090 * <dl>
11091 * <dt><b>Scheduler:</b></dt>
11092 * <dd>{@code repeatUntil} does not operate by default on a particular {@link Scheduler}.</dd>
11093 * </dl>
11094 *
11095 * @param stop
11096 * a boolean supplier that is called when the current {@code Observable} completes;
11097 * if it returns {@code true}, the returned {@code Observable} completes; if it returns {@code false},
11098 * the current {@code Observable} is resubscribed.
11099 * @return the new {@code Observable} instance
11100 * @throws NullPointerException
11101 * if {@code stop} is {@code null}
11102 * @see <a href="http://reactivex.io/documentation/operators/repeat.html">ReactiveX operators documentation: Repeat</a>
11103 */
11104 @CheckReturnValue
11105 @SchedulerSupport(SchedulerSupport.NONE)
11106 @NonNull
11107 public final Observable<T> repeatUntil(@NonNull BooleanSupplier stop) {
11108 Objects.requireNonNull(stop, "stop is null");
11109 return RxJavaPlugins.onAssembly(new ObservableRepeatUntil<>(this, stop));
11110 }
11111
11112 /**
11113 * Returns an {@code Observable} that emits the same values as the current {@code Observable} with the exception of an
11114 * {@code onComplete}. An {@code onComplete} notification from the source will result in the emission of
11115 * a {@code void} item to the {@link ObservableSource} provided as an argument to the {@code notificationHandler}
11116 * function. If that {@code ObservableSource} calls {@code onComplete} or {@code onError} then {@code repeatWhen} will
11117 * call {@code onComplete} or {@code onError} on the child subscription. Otherwise, the current {@code Observable}
11118 * will be resubscribed.
11119 * <p>
11120 * <img width="640" height="430" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/repeatWhen.f.v3.png" alt="">
11121 * <dl>
11122 * <dt><b>Scheduler:</b></dt>
11123 * <dd>{@code repeatWhen} does not operate by default on a particular {@link Scheduler}.</dd>
11124 * </dl>
11125 *
11126 * @param handler
11127 * receives an {@code ObservableSource} of notifications with which a user can complete or error, aborting the repeat.
11128 * @return the new {@code Observable} instance
11129 * @throws NullPointerException if {@code handler} is {@code null}
11130 * @see <a href="http://reactivex.io/documentation/operators/repeat.html">ReactiveX operators documentation: Repeat</a>
11131 */
11132 @CheckReturnValue
11133 @SchedulerSupport(SchedulerSupport.NONE)
11134 @NonNull
11135 public final Observable<T> repeatWhen(@NonNull Function<? super Observable<Object>, ? extends ObservableSource<?>> handler) {
11136 Objects.requireNonNull(handler, "handler is null");
11137 return RxJavaPlugins.onAssembly(new ObservableRepeatWhen<>(this, handler));
11138 }
11139
11140 /**
11141 * Returns a {@link ConnectableObservable} that shares a single subscription to the current {@code Observable}
11142 * that will replay all of its items and notifications to any future {@link Observer}. A connectable
11143 * {@code Observable} resembles an ordinary {@code Observable}, except that it does not begin emitting items when it is
11144 * subscribed to, but only when its {@code connect} method is called.
11145 * <p>
11146 * <img width="640" height="445" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/replay.o.v3.png" alt="">
11147 * <dl>
11148 * <dt><b>Scheduler:</b></dt>
11149 * <dd>This version of {@code replay} does not operate by default on a particular {@link Scheduler}.</dd>
11150 * </dl>
11151 *
11152 * @return the new {@code ConnectableObservable} instance
11153 * @see <a href="http://reactivex.io/documentation/operators/replay.html">ReactiveX operators documentation: Replay</a>
11154 */
11155 @CheckReturnValue
11156 @SchedulerSupport(SchedulerSupport.NONE)
11157 @NonNull
11158 public final ConnectableObservable<T> replay() {
11159 return ObservableReplay.createFrom(this);
11160 }
11161
11162 /**
11163 * Returns an {@code Observable} that emits items that are the results of invoking a specified selector on the items
11164 * emitted by a {@link ConnectableObservable} that shares a single subscription to the current {@code Observable}.
11165 * <p>
11166 * <img width="640" height="449" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/replay.o.f.png" alt="">
11167 * <dl>
11168 * <dt><b>Scheduler:</b></dt>
11169 * <dd>This version of {@code replay} does not operate by default on a particular {@link Scheduler}.</dd>
11170 * </dl>
11171 *
11172 * @param <R>
11173 * the type of items emitted by the resulting {@code Observable}
11174 * @param selector
11175 * the selector function, which can use the multicasted sequence as many times as needed, without
11176 * causing multiple subscriptions to the current {@code Observable}
11177 * @return the new {@code Observable} instance
11178 * @throws NullPointerException if {@code selector} is {@code null}
11179 * @see <a href="http://reactivex.io/documentation/operators/replay.html">ReactiveX operators documentation: Replay</a>
11180 */
11181 @CheckReturnValue
11182 @SchedulerSupport(SchedulerSupport.NONE)
11183 @NonNull
11184 public final <@NonNull R> Observable<R> replay(@NonNull Function<? super Observable<T>, ? extends ObservableSource<R>> selector) {
11185 Objects.requireNonNull(selector, "selector is null");
11186 return ObservableReplay.multicastSelector(ObservableInternalHelper.replaySupplier(this), selector);
11187 }
11188
11189 /**
11190 * Returns an {@code Observable} that emits items that are the results of invoking a specified selector on items
11191 * emitted by a {@link ConnectableObservable} that shares a single subscription to the current {@code Observable},
11192 * replaying {@code bufferSize} notifications.
11193 * <p>
11194 * Note that due to concurrency requirements, {@code replay(bufferSize)} may hold strong references to more than
11195 * {@code bufferSize} source emissions.
11196 * <p>
11197 * <img width="640" height="392" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/replay.o.fn.png" alt="">
11198 * <dl>
11199 * <dt><b>Scheduler:</b></dt>
11200 * <dd>This version of {@code replay} does not operate by default on a particular {@link Scheduler}.</dd>
11201 * </dl>
11202 *
11203 * @param <R>
11204 * the type of items emitted by the resulting {@code Observable}
11205 * @param selector
11206 * the selector function, which can use the multicasted sequence as many times as needed, without
11207 * causing multiple subscriptions to the current {@code Observable}
11208 * @param bufferSize
11209 * the buffer size that limits the number of items the connectable {@code Observable} can replay
11210 * @return the new {@code Observable} instance
11211 * @throws NullPointerException if {@code selector} is {@code null}
11212 * @throws IllegalArgumentException if {@code bufferSize} is non-positive
11213 * @see <a href="http://reactivex.io/documentation/operators/replay.html">ReactiveX operators documentation: Replay</a>
11214 * @see #replay(Function, int, boolean)
11215 */
11216 @CheckReturnValue
11217 @SchedulerSupport(SchedulerSupport.NONE)
11218 @NonNull
11219 public final <@NonNull R> Observable<R> replay(@NonNull Function<? super Observable<T>, ? extends ObservableSource<R>> selector, int bufferSize) {
11220 Objects.requireNonNull(selector, "selector is null");
11221 ObjectHelper.verifyPositive(bufferSize, "bufferSize");
11222 return ObservableReplay.multicastSelector(ObservableInternalHelper.replaySupplier(this, bufferSize, false), selector);
11223 }
11224
11225 /**
11226 * Returns an {@code Observable} that emits items that are the results of invoking a specified selector on items
11227 * emitted by a {@link ConnectableObservable} that shares a single subscription to the current {@code Observable},
11228 * replaying {@code bufferSize} notifications.
11229 * <p>
11230 * Note that due to concurrency requirements, {@code replay(bufferSize)} may hold strong references to more than
11231 * {@code bufferSize} source emissions.
11232 * <p>
11233 * <img width="640" height="392" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/replay.o.fn.png" alt="">
11234 * <dl>
11235 * <dt><b>Scheduler:</b></dt>
11236 * <dd>This version of {@code replay} does not operate by default on a particular {@link Scheduler}.</dd>
11237 * </dl>
11238 *
11239 * @param <R>
11240 * the type of items emitted by the resulting {@code Observable}
11241 * @param selector
11242 * the selector function, which can use the multicasted sequence as many times as needed, without
11243 * causing multiple subscriptions to the current {@code Observable}
11244 * @param bufferSize
11245 * the buffer size that limits the number of items the connectable {@code Observable} can replay
11246 * @param eagerTruncate
11247 * if {@code true}, whenever the internal buffer is truncated to the given bufferSize, the
11248 * oldest item will be guaranteed dereferenced, thus avoiding unexpected retention
11249 * @return the new {@code Observable} instance
11250 * @throws NullPointerException if {@code selector} is {@code null}
11251 * @throws IllegalArgumentException if {@code bufferSize} is non-positive
11252 * @see <a href="http://reactivex.io/documentation/operators/replay.html">ReactiveX operators documentation: Replay</a>
11253 */
11254 @CheckReturnValue
11255 @SchedulerSupport(SchedulerSupport.NONE)
11256 @NonNull
11257 public final <@NonNull R> Observable<R> replay(@NonNull Function<? super Observable<T>, ? extends ObservableSource<R>> selector, int bufferSize, boolean eagerTruncate) {
11258 Objects.requireNonNull(selector, "selector is null");
11259 ObjectHelper.verifyPositive(bufferSize, "bufferSize");
11260 return ObservableReplay.multicastSelector(ObservableInternalHelper.replaySupplier(this, bufferSize, eagerTruncate), selector);
11261 }
11262
11263 /**
11264 * Returns an {@code Observable} that emits items that are the results of invoking a specified selector on items
11265 * emitted by a {@link ConnectableObservable} that shares a single subscription to the current {@code Observable},
11266 * replaying no more than {@code bufferSize} items that were emitted within a specified time window.
11267 * <p>
11268 * Note that due to concurrency requirements, {@code replay(bufferSize)} may hold strong references to more than
11269 * {@code bufferSize} source emissions.
11270 * <p>
11271 * <img width="640" height="350" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/replay.o.fnt.png" alt="">
11272 * <dl>
11273 * <dt><b>Scheduler:</b></dt>
11274 * <dd>This version of {@code replay} operates by default on the {@code computation} {@link Scheduler}.</dd>
11275 * </dl>
11276 *
11277 * @param <R>
11278 * the type of items emitted by the resulting {@code Observable}
11279 * @param selector
11280 * a selector function, which can use the multicasted sequence as many times as needed, without
11281 * causing multiple subscriptions to the current {@code Observable}
11282 * @param bufferSize
11283 * the buffer size that limits the number of items the connectable {@code Observable} can replay
11284 * @param time
11285 * the duration of the window in which the replayed items must have been emitted
11286 * @param unit
11287 * the time unit of {@code time}
11288 * @return the new {@code Observable} instance
11289 * @throws NullPointerException if {@code selector} or {@code unit} is {@code null}
11290 * @throws IllegalArgumentException if {@code bufferSize} is non-positive
11291 * @see <a href="http://reactivex.io/documentation/operators/replay.html">ReactiveX operators documentation: Replay</a>
11292 */
11293 @CheckReturnValue
11294 @SchedulerSupport(SchedulerSupport.COMPUTATION)
11295 @NonNull
11296 public final <@NonNull R> Observable<R> replay(@NonNull Function<? super Observable<T>, ? extends ObservableSource<R>> selector, int bufferSize, long time, @NonNull TimeUnit unit) {
11297 return replay(selector, bufferSize, time, unit, Schedulers.computation());
11298 }
11299
11300 /**
11301 * Returns an {@code Observable} that emits items that are the results of invoking a specified selector on items
11302 * emitted by a {@link ConnectableObservable} that shares a single subscription to the current {@code Observable},
11303 * replaying no more than {@code bufferSize} items that were emitted within a specified time window.
11304 * <p>
11305 * Note that due to concurrency requirements, {@code replay(bufferSize)} may hold strong references to more than
11306 * {@code bufferSize} source emissions.
11307 * <p>
11308 * <img width="640" height="329" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/replay.o.fnts.png" alt="">
11309 * <dl>
11310 * <dt><b>Scheduler:</b></dt>
11311 * <dd>You specify which {@link Scheduler} this operator will use.</dd>
11312 * </dl>
11313 *
11314 * @param <R>
11315 * the type of items emitted by the resulting {@code Observable}
11316 * @param selector
11317 * a selector function, which can use the multicasted sequence as many times as needed, without
11318 * causing multiple subscriptions to the current {@code Observable}
11319 * @param bufferSize
11320 * the buffer size that limits the number of items the connectable {@code Observable} can replay
11321 * @param time
11322 * the duration of the window in which the replayed items must have been emitted
11323 * @param unit
11324 * the time unit of {@code time}
11325 * @param scheduler
11326 * the {@code Scheduler} that is the time source for the window
11327 * @return the new {@code Observable} instance
11328 * @throws IllegalArgumentException
11329 * if {@code bufferSize} is non-positive
11330 * @throws NullPointerException if {@code selector}, {@code unit} or {@code scheduler} is {@code null}
11331 * @throws IllegalArgumentException if {@code bufferSize} is non-positive
11332 * @see <a href="http://reactivex.io/documentation/operators/replay.html">ReactiveX operators documentation: Replay</a>
11333 * @see #replay(Function, int, long, TimeUnit, Scheduler, boolean)
11334 */
11335 @CheckReturnValue
11336 @SchedulerSupport(SchedulerSupport.CUSTOM)
11337 @NonNull
11338 public final <@NonNull R> Observable<R> replay(@NonNull Function<? super Observable<T>, ? extends ObservableSource<R>> selector, int bufferSize, long time, @NonNull TimeUnit unit, @NonNull Scheduler scheduler) {
11339 Objects.requireNonNull(selector, "selector is null");
11340 ObjectHelper.verifyPositive(bufferSize, "bufferSize");
11341 Objects.requireNonNull(unit, "unit is null");
11342 Objects.requireNonNull(scheduler, "scheduler is null");
11343 return ObservableReplay.multicastSelector(
11344 ObservableInternalHelper.replaySupplier(this, bufferSize, time, unit, scheduler, false), selector);
11345 }
11346
11347 /**
11348 * Returns an {@code Observable} that emits items that are the results of invoking a specified selector on items
11349 * emitted by a {@link ConnectableObservable} that shares a single subscription to the current {@code Observable},
11350 * replaying no more than {@code bufferSize} items that were emitted within a specified time window.
11351 * <p>
11352 * Note that due to concurrency requirements, {@code replay(bufferSize)} may hold strong references to more than
11353 * {@code bufferSize} source emissions.
11354 * <p>
11355 * <img width="640" height="329" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/replay.o.fnts.png" alt="">
11356 * <dl>
11357 * <dt><b>Scheduler:</b></dt>
11358 * <dd>You specify which {@link Scheduler} this operator will use.</dd>
11359 * </dl>
11360 *
11361 * @param <R>
11362 * the type of items emitted by the resulting {@code Observable}
11363 * @param selector
11364 * a selector function, which can use the multicasted sequence as many times as needed, without
11365 * causing multiple subscriptions to the current {@code Observable}
11366 * @param bufferSize
11367 * the buffer size that limits the number of items the connectable {@code Observable} can replay
11368 * @param time
11369 * the duration of the window in which the replayed items must have been emitted
11370 * @param unit
11371 * the time unit of {@code time}
11372 * @param scheduler
11373 * the {@code Scheduler} that is the time source for the window
11374 * @param eagerTruncate
11375 * if {@code true}, whenever the internal buffer is truncated to the given bufferSize/age, the
11376 * oldest item will be guaranteed dereferenced, thus avoiding unexpected retention
11377 * @return the new {@code Observable} instance
11378 * @throws NullPointerException if {@code selector}, {@code unit} or {@code scheduler} is {@code null}
11379 * @throws IllegalArgumentException
11380 * if {@code bufferSize} is non-positive
11381 * @see <a href="http://reactivex.io/documentation/operators/replay.html">ReactiveX operators documentation: Replay</a>
11382 */
11383 @CheckReturnValue
11384 @SchedulerSupport(SchedulerSupport.CUSTOM)
11385 @NonNull
11386 public final <@NonNull R> Observable<R> replay(@NonNull Function<? super Observable<T>, ? extends ObservableSource<R>> selector, int bufferSize, long time, @NonNull TimeUnit unit, @NonNull Scheduler scheduler, boolean eagerTruncate) {
11387 Objects.requireNonNull(selector, "selector is null");
11388 ObjectHelper.verifyPositive(bufferSize, "bufferSize");
11389 Objects.requireNonNull(unit, "unit is null");
11390 Objects.requireNonNull(scheduler, "scheduler is null");
11391 return ObservableReplay.multicastSelector(
11392 ObservableInternalHelper.replaySupplier(this, bufferSize, time, unit, scheduler, eagerTruncate), selector);
11393 }
11394
11395 /**
11396 * Returns an {@code Observable} that emits items that are the results of invoking a specified selector on items
11397 * emitted by a {@link ConnectableObservable} that shares a single subscription to the current {@code Observable},
11398 * replaying all items that were emitted within a specified time window.
11399 * <p>
11400 * <img width="640" height="394" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/replay.o.ft.png" alt="">
11401 * <dl>
11402 * <dt><b>Scheduler:</b></dt>
11403 * <dd>This version of {@code replay} operates by default on the {@code computation} {@link Scheduler}.</dd>
11404 * </dl>
11405 *
11406 * @param <R>
11407 * the type of items emitted by the resulting {@code Observable}
11408 * @param selector
11409 * a selector function, which can use the multicasted sequence as many times as needed, without
11410 * causing multiple subscriptions to the current {@code Observable}
11411 * @param time
11412 * the duration of the window in which the replayed items must have been emitted
11413 * @param unit
11414 * the time unit of {@code time}
11415 * @return the new {@code Observable} instance
11416 * @throws NullPointerException if {@code selector} or {@code unit} is {@code null}
11417 * @see <a href="http://reactivex.io/documentation/operators/replay.html">ReactiveX operators documentation: Replay</a>
11418 */
11419 @CheckReturnValue
11420 @SchedulerSupport(SchedulerSupport.COMPUTATION)
11421 @NonNull
11422 public final <@NonNull R> Observable<R> replay(@NonNull Function<? super Observable<T>, ? extends ObservableSource<R>> selector, long time, @NonNull TimeUnit unit) {
11423 return replay(selector, time, unit, Schedulers.computation());
11424 }
11425
11426 /**
11427 * Returns an {@code Observable} that emits items that are the results of invoking a specified selector on items
11428 * emitted by a {@link ConnectableObservable} that shares a single subscription to the current {@code Observable},
11429 * replaying all items that were emitted within a specified time window.
11430 * <p>
11431 * <img width="640" height="367" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/replay.o.fts.png" alt="">
11432 * <dl>
11433 * <dt><b>Scheduler:</b></dt>
11434 * <dd>You specify which {@link Scheduler} this operator will use.</dd>
11435 * </dl>
11436 *
11437 * @param <R>
11438 * the type of items emitted by the resulting {@code Observable}
11439 * @param selector
11440 * a selector function, which can use the multicasted sequence as many times as needed, without
11441 * causing multiple subscriptions to the current {@code Observable}
11442 * @param time
11443 * the duration of the window in which the replayed items must have been emitted
11444 * @param unit
11445 * the time unit of {@code time}
11446 * @param scheduler
11447 * the scheduler that is the time source for the window
11448 * @return the new {@code Observable} instance
11449 * @throws NullPointerException if {@code selector}, {@code unit} or {@code scheduler} is {@code null}
11450 * @see <a href="http://reactivex.io/documentation/operators/replay.html">ReactiveX operators documentation: Replay</a>
11451 * @see #replay(Function, long, TimeUnit, Scheduler, boolean)
11452 */
11453 @CheckReturnValue
11454 @SchedulerSupport(SchedulerSupport.CUSTOM)
11455 @NonNull
11456 public final <@NonNull R> Observable<R> replay(@NonNull Function<? super Observable<T>, ? extends ObservableSource<R>> selector, long time, @NonNull TimeUnit unit, @NonNull Scheduler scheduler) {
11457 Objects.requireNonNull(selector, "selector is null");
11458 Objects.requireNonNull(unit, "unit is null");
11459 Objects.requireNonNull(scheduler, "scheduler is null");
11460 return ObservableReplay.multicastSelector(ObservableInternalHelper.replaySupplier(this, time, unit, scheduler, false), selector);
11461 }
11462
11463 /**
11464 * Returns an {@code Observable} that emits items that are the results of invoking a specified selector on items
11465 * emitted by a {@link ConnectableObservable} that shares a single subscription to the current {@code Observable},
11466 * replaying all items that were emitted within a specified time window.
11467 * <p>
11468 * <img width="640" height="367" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/replay.o.fts.png" alt="">
11469 * <dl>
11470 * <dt><b>Scheduler:</b></dt>
11471 * <dd>You specify which {@link Scheduler} this operator will use.</dd>
11472 * </dl>
11473 *
11474 * @param <R>
11475 * the type of items emitted by the resulting {@code Observable}
11476 * @param selector
11477 * a selector function, which can use the multicasted sequence as many times as needed, without
11478 * causing multiple subscriptions to the current {@code Observable}
11479 * @param time
11480 * the duration of the window in which the replayed items must have been emitted
11481 * @param unit
11482 * the time unit of {@code time}
11483 * @param scheduler
11484 * the scheduler that is the time source for the window
11485 * @param eagerTruncate
11486 * if {@code true}, whenever the internal buffer is truncated to the given age, the
11487 * oldest item will be guaranteed dereferenced, thus avoiding unexpected retention
11488 * @return the new {@code Observable} instance
11489 * @throws NullPointerException if {@code selector}, {@code unit} or {@code scheduler} is {@code null}
11490 * @see <a href="http://reactivex.io/documentation/operators/replay.html">ReactiveX operators documentation: Replay</a>
11491 */
11492 @CheckReturnValue
11493 @SchedulerSupport(SchedulerSupport.CUSTOM)
11494 @NonNull
11495 public final <@NonNull R> Observable<R> replay(@NonNull Function<? super Observable<T>, ? extends ObservableSource<R>> selector, long time, @NonNull TimeUnit unit, @NonNull Scheduler scheduler, boolean eagerTruncate) {
11496 Objects.requireNonNull(selector, "selector is null");
11497 Objects.requireNonNull(unit, "unit is null");
11498 Objects.requireNonNull(scheduler, "scheduler is null");
11499 return ObservableReplay.multicastSelector(ObservableInternalHelper.replaySupplier(this, time, unit, scheduler, eagerTruncate), selector);
11500 }
11501
11502 /**
11503 * Returns a {@link ConnectableObservable} that shares a single subscription to the current {@code Observable} that
11504 * replays at most {@code bufferSize} items emitted by the current {@code Observable}. A connectable {@code Observable} resembles
11505 * an ordinary {@code Observable}, except that it does not begin emitting items when it is subscribed to, but only
11506 * when its {@code connect} method is called.
11507 * <p>
11508 * <img width="640" height="445" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/replay.o.n.v3.png" alt="">
11509 * <p>
11510 * Note that due to concurrency requirements, {@code replay(bufferSize)} may hold strong references to more than
11511 * {@code bufferSize} source emissions.
11512 * To ensure no beyond-bufferSize items are referenced,
11513 * use the {@link #replay(int, boolean)} overload with {@code eagerTruncate = true}.
11514 * <dl>
11515 * <dt><b>Scheduler:</b></dt>
11516 * <dd>This version of {@code replay} does not operate by default on a particular {@link Scheduler}.</dd>
11517 * </dl>
11518 *
11519 * @param bufferSize
11520 * the buffer size that limits the number of items that can be replayed
11521 * @return the new {@code ConnectableObservable} instance
11522 * @throws IllegalArgumentException if {@code bufferSize} is non-positive
11523 * @see <a href="http://reactivex.io/documentation/operators/replay.html">ReactiveX operators documentation: Replay</a>
11524 * @see #replay(int, boolean)
11525 */
11526 @CheckReturnValue
11527 @SchedulerSupport(SchedulerSupport.NONE)
11528 @NonNull
11529 public final ConnectableObservable<T> replay(int bufferSize) {
11530 ObjectHelper.verifyPositive(bufferSize, "bufferSize");
11531 return ObservableReplay.create(this, bufferSize, false);
11532 }
11533
11534 /**
11535 * Returns a {@link ConnectableObservable} that shares a single subscription to the current {@code Observable} that
11536 * replays at most {@code bufferSize} items emitted by the current {@code Observable}. A connectable {@code Observable} resembles
11537 * an ordinary {@code Observable}, except that it does not begin emitting items when it is subscribed to, but only
11538 * when its {@code connect} method is called.
11539 * <p>
11540 * <img width="640" height="445" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/replay.o.n.v3.png" alt="">
11541 * <p>
11542 * Note that due to concurrency requirements, {@code replay(bufferSize)} may hold strong references to more than
11543 * {@code bufferSize} source emissions.
11544 * To ensure no beyond-bufferSize items are referenced, set {@code eagerTruncate = true}.
11545 * <dl>
11546 * <dt><b>Scheduler:</b></dt>
11547 * <dd>This version of {@code replay} does not operate by default on a particular {@link Scheduler}.</dd>
11548 * </dl>
11549 *
11550 * @param bufferSize
11551 * the buffer size that limits the number of items that can be replayed
11552 * @param eagerTruncate
11553 * if {@code true}, whenever the internal buffer is truncated to the given bufferSize/age, the
11554 * oldest item will be guaranteed dereferenced, thus avoiding unexpected retention
11555 * @return the new {@code ConnectableObservable} instance
11556 * @throws IllegalArgumentException if {@code bufferSize} is non-positive
11557 * @see <a href="http://reactivex.io/documentation/operators/replay.html">ReactiveX operators documentation: Replay</a>
11558 */
11559 @CheckReturnValue
11560 @SchedulerSupport(SchedulerSupport.NONE)
11561 @NonNull
11562 public final ConnectableObservable<T> replay(int bufferSize, boolean eagerTruncate) {
11563 ObjectHelper.verifyPositive(bufferSize, "bufferSize");
11564 return ObservableReplay.create(this, bufferSize, eagerTruncate);
11565 }
11566
11567 /**
11568 * Returns a {@link ConnectableObservable} that shares a single subscription to the current {@code Observable} and
11569 * replays at most {@code bufferSize} items that were emitted during a specified time window. A connectable
11570 * {@code Observable} resembles an ordinary {@code Observable}, except that it does not begin emitting items when it is
11571 * subscribed to, but only when its {@code connect} method is called.
11572 * <p>
11573 * <img width="640" height="445" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/replay.o.nt.v3.png" alt="">
11574 * <p>
11575 * Note that due to concurrency requirements, {@code replay(bufferSize)} may hold strong references to more than
11576 * {@code bufferSize} source emissions.
11577 * To ensure no out-of-date or beyond-bufferSize items are referenced,
11578 * use the {@link #replay(int, long, TimeUnit, Scheduler, boolean)} overload with {@code eagerTruncate = true}.
11579 * <dl>
11580 * <dt><b>Scheduler:</b></dt>
11581 * <dd>This version of {@code replay} operates by default on the {@code computation} {@link Scheduler}.</dd>
11582 * </dl>
11583 *
11584 * @param bufferSize
11585 * the buffer size that limits the number of items that can be replayed
11586 * @param time
11587 * the duration of the window in which the replayed items must have been emitted
11588 * @param unit
11589 * the time unit of {@code time}
11590 * @return the new {@code ConnectableObservable} instance
11591 * @throws NullPointerException if {@code unit} is {@code null}
11592 * @throws IllegalArgumentException if {@code bufferSize} is non-positive
11593 * @see <a href="http://reactivex.io/documentation/operators/replay.html">ReactiveX operators documentation: Replay</a>
11594 * @see #replay(int, long, TimeUnit, Scheduler, boolean)
11595 */
11596 @CheckReturnValue
11597 @SchedulerSupport(SchedulerSupport.COMPUTATION)
11598 @NonNull
11599 public final ConnectableObservable<T> replay(int bufferSize, long time, @NonNull TimeUnit unit) {
11600 return replay(bufferSize, time, unit, Schedulers.computation());
11601 }
11602
11603 /**
11604 * Returns a {@link ConnectableObservable} that shares a single subscription to the current {@code Observable} and
11605 * that replays a maximum of {@code bufferSize} items that are emitted within a specified time window. A
11606 * connectable {@code Observable} resembles an ordinary {@code Observable}, except that it does not begin emitting items
11607 * when it is subscribed to, but only when its {@code connect} method is called.
11608 * <p>
11609 * Note that due to concurrency requirements, {@code replay(bufferSize)} may hold strong references to more than
11610 * {@code bufferSize} source emissions.
11611 * To ensure no out-of-date or beyond-bufferSize items are referenced,
11612 * use the {@link #replay(int, long, TimeUnit, Scheduler, boolean)} overload with {@code eagerTruncate = true}.
11613 * <p>
11614 * <img width="640" height="445" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/replay.o.nts.v3.png" alt="">
11615 * <dl>
11616 * <dt><b>Scheduler:</b></dt>
11617 * <dd>You specify which {@link Scheduler} this operator will use.</dd>
11618 * </dl>
11619 *
11620 * @param bufferSize
11621 * the buffer size that limits the number of items that can be replayed
11622 * @param time
11623 * the duration of the window in which the replayed items must have been emitted
11624 * @param unit
11625 * the time unit of {@code time}
11626 * @param scheduler
11627 * the scheduler that is used as a time source for the window
11628 * @return the new {@code ConnectableObservable} instance
11629 * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null}
11630 * @throws IllegalArgumentException
11631 * if {@code bufferSize} is non-positive
11632 * @see <a href="http://reactivex.io/documentation/operators/replay.html">ReactiveX operators documentation: Replay</a>
11633 * @see #replay(int, long, TimeUnit, Scheduler, boolean)
11634 */
11635 @CheckReturnValue
11636 @SchedulerSupport(SchedulerSupport.CUSTOM)
11637 @NonNull
11638 public final ConnectableObservable<T> replay(int bufferSize, long time, @NonNull TimeUnit unit, @NonNull Scheduler scheduler) {
11639 ObjectHelper.verifyPositive(bufferSize, "bufferSize");
11640 Objects.requireNonNull(unit, "unit is null");
11641 Objects.requireNonNull(scheduler, "scheduler is null");
11642 return ObservableReplay.create(this, time, unit, scheduler, bufferSize, false);
11643 }
11644
11645 /**
11646 * Returns a {@link ConnectableObservable} that shares a single subscription to the current {@code Observable} and
11647 * that replays a maximum of {@code bufferSize} items that are emitted within a specified time window. A
11648 * connectable {@code Observable} resembles an ordinary {@code Observable}, except that it does not begin emitting items
11649 * when it is subscribed to, but only when its {@code connect} method is called.
11650 * <p>
11651 * <img width="640" height="445" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/replay.o.nts.v3.png" alt="">
11652 * <p>
11653 * Note that due to concurrency requirements, {@code replay(bufferSize)} may hold strong references to more than
11654 * {@code bufferSize} source emissions.
11655 * To ensure no out-of-date or beyond-bufferSize items
11656 * are referenced, set {@code eagerTruncate = true}.
11657 * <dl>
11658 * <dt><b>Scheduler:</b></dt>
11659 * <dd>You specify which {@link Scheduler} this operator will use.</dd>
11660 * </dl>
11661 *
11662 * @param bufferSize
11663 * the buffer size that limits the number of items that can be replayed
11664 * @param time
11665 * the duration of the window in which the replayed items must have been emitted
11666 * @param unit
11667 * the time unit of {@code time}
11668 * @param scheduler
11669 * the scheduler that is used as a time source for the window
11670 * @return the new {@code ConnectableObservable} instance
11671 * @param eagerTruncate
11672 * if {@code true}, whenever the internal buffer is truncated to the given bufferSize/age, the
11673 * oldest item will be guaranteed dereferenced, thus avoiding unexpected retention
11674 * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null}
11675 * @throws IllegalArgumentException
11676 * if {@code bufferSize} is non-positive
11677 * @see <a href="http://reactivex.io/documentation/operators/replay.html">ReactiveX operators documentation: Replay</a>
11678 */
11679 @CheckReturnValue
11680 @SchedulerSupport(SchedulerSupport.CUSTOM)
11681 @NonNull
11682 public final ConnectableObservable<T> replay(int bufferSize, long time, @NonNull TimeUnit unit, @NonNull Scheduler scheduler, boolean eagerTruncate) {
11683 ObjectHelper.verifyPositive(bufferSize, "bufferSize");
11684 Objects.requireNonNull(unit, "unit is null");
11685 Objects.requireNonNull(scheduler, "scheduler is null");
11686 return ObservableReplay.create(this, time, unit, scheduler, bufferSize, eagerTruncate);
11687 }
11688
11689 /**
11690 * Returns a {@link ConnectableObservable} that shares a single subscription to the current {@code Observable} and
11691 * replays all items emitted by the current {@code Observable} within a specified time window. A connectable {@code Observable}
11692 * resembles an ordinary {@code Observable}, except that it does not begin emitting items when it is subscribed to,
11693 * but only when its {@code connect} method is called.
11694 * <p>
11695 * <img width="640" height="445" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/replay.o.t.v3.png" alt="">
11696 * <dl>
11697 * <dt><b>Scheduler:</b></dt>
11698 * <dd>This version of {@code replay} operates by default on the {@code computation} {@link Scheduler}.</dd>
11699 * </dl>
11700 *
11701 * @param time
11702 * the duration of the window in which the replayed items must have been emitted
11703 * @param unit
11704 * the time unit of {@code time}
11705 * @return the new {@code ConnectableObservable} instance
11706 * @throws NullPointerException if {@code unit} is {@code null}
11707 * @see <a href="http://reactivex.io/documentation/operators/replay.html">ReactiveX operators documentation: Replay</a>
11708 */
11709 @CheckReturnValue
11710 @SchedulerSupport(SchedulerSupport.COMPUTATION)
11711 @NonNull
11712 public final ConnectableObservable<T> replay(long time, @NonNull TimeUnit unit) {
11713 return replay(time, unit, Schedulers.computation());
11714 }
11715
11716 /**
11717 * Returns a {@link ConnectableObservable} that shares a single subscription to the current {@code Observable} and
11718 * replays all items emitted by the current {@code Observable} within a specified time window. A connectable {@code Observable}
11719 * resembles an ordinary {@code Observable}, except that it does not begin emitting items when it is subscribed to,
11720 * but only when its {@code connect} method is called.
11721 * <p>
11722 * <img width="640" height="445" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/replay.o.ts.v3.png" alt="">
11723 * <p>
11724 * Note that the internal buffer may retain strong references to the oldest item. To ensure no out-of-date items
11725 * are referenced, use the {@link #replay(long, TimeUnit, Scheduler, boolean)} overload with {@code eagerTruncate = true}.
11726 * <dl>
11727 * <dt><b>Scheduler:</b></dt>
11728 * <dd>You specify which {@link Scheduler} this operator will use.</dd>
11729 * </dl>
11730 *
11731 * @param time
11732 * the duration of the window in which the replayed items must have been emitted
11733 * @param unit
11734 * the time unit of {@code time}
11735 * @param scheduler
11736 * the {@code Scheduler} that is the time source for the window
11737 * @return the new {@code ConnectableObservable} instance
11738 * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null}
11739 * @see <a href="http://reactivex.io/documentation/operators/replay.html">ReactiveX operators documentation: Replay</a>
11740 * @see #replay(long, TimeUnit, Scheduler, boolean)
11741 */
11742 @CheckReturnValue
11743 @SchedulerSupport(SchedulerSupport.CUSTOM)
11744 @NonNull
11745 public final ConnectableObservable<T> replay(long time, @NonNull TimeUnit unit, @NonNull Scheduler scheduler) {
11746 Objects.requireNonNull(unit, "unit is null");
11747 Objects.requireNonNull(scheduler, "scheduler is null");
11748 return ObservableReplay.create(this, time, unit, scheduler, false);
11749 }
11750
11751 /**
11752 * Returns a {@link ConnectableObservable} that shares a single subscription to the current {@code Observable} and
11753 * replays all items emitted by the current {@code Observable} within a specified time window. A connectable {@code Observable}
11754 * resembles an ordinary {@code Observable}, except that it does not begin emitting items when it is subscribed to,
11755 * but only when its {@code connect} method is called.
11756 * <p>
11757 * <img width="640" height="445" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/replay.o.ts.v3.png" alt="">
11758 * <p>
11759 * Note that the internal buffer may retain strong references to the oldest item. To ensure no out-of-date items
11760 * are referenced, set {@code eagerTruncate = true}.
11761 * <dl>
11762 * <dt><b>Scheduler:</b></dt>
11763 * <dd>You specify which {@link Scheduler} this operator will use.</dd>
11764 * </dl>
11765 *
11766 * @param time
11767 * the duration of the window in which the replayed items must have been emitted
11768 * @param unit
11769 * the time unit of {@code time}
11770 * @param scheduler
11771 * the {@code Scheduler} that is the time source for the window
11772 * @param eagerTruncate
11773 * if {@code true}, whenever the internal buffer is truncated to the given bufferSize/age, the
11774 * oldest item will be guaranteed dereferenced, thus avoiding unexpected retention
11775 * @return the new {@code ConnectableObservable} instance
11776 * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null}
11777 * @see <a href="http://reactivex.io/documentation/operators/replay.html">ReactiveX operators documentation: Replay</a>
11778 */
11779 @CheckReturnValue
11780 @SchedulerSupport(SchedulerSupport.CUSTOM)
11781 @NonNull
11782 public final ConnectableObservable<T> replay(long time, @NonNull TimeUnit unit, @NonNull Scheduler scheduler, boolean eagerTruncate) {
11783 Objects.requireNonNull(unit, "unit is null");
11784 Objects.requireNonNull(scheduler, "scheduler is null");
11785 return ObservableReplay.create(this, time, unit, scheduler, eagerTruncate);
11786 }
11787
11788 /**
11789 * Returns an {@code Observable} that mirrors the current {@code Observable}, resubscribing to it if it calls {@code onError}
11790 * (infinite retry count).
11791 * <p>
11792 * <img width="640" height="315" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/retry.v3.png" alt="">
11793 * <p>
11794 * If the current {@code Observable} calls {@link Observer#onError}, this method will resubscribe to the current
11795 * {@code Observable} rather than propagating the {@code onError} call.
11796 * <p>
11797 * Any and all items emitted by the current {@code Observable} will be emitted by the resulting {@code Observable}, even
11798 * those emitted during failed subscriptions. For example, if the current {@code Observable} fails at first but emits
11799 * {@code [1, 2]} then succeeds the second time and emits {@code [1, 2, 3, 4, 5]} then the complete sequence
11800 * of emissions and notifications would be {@code [1, 2, 1, 2, 3, 4, 5, onComplete]}.
11801 * <dl>
11802 * <dt><b>Scheduler:</b></dt>
11803 * <dd>{@code retry} does not operate by default on a particular {@link Scheduler}.</dd>
11804 * </dl>
11805 *
11806 * @return the new {@code Observable} instance
11807 * @see <a href="http://reactivex.io/documentation/operators/retry.html">ReactiveX operators documentation: Retry</a>
11808 */
11809 @CheckReturnValue
11810 @SchedulerSupport(SchedulerSupport.NONE)
11811 @NonNull
11812 public final Observable<T> retry() {
11813 return retry(Long.MAX_VALUE, Functions.alwaysTrue());
11814 }
11815
11816 /**
11817 * Returns an {@code Observable} that mirrors the current {@code Observable}, resubscribing to it if it calls {@code onError}
11818 * and the predicate returns {@code true} for that specific exception and retry count.
11819 * <p>
11820 * <img width="640" height="236" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/retry.o.ne.png" alt="">
11821 * <dl>
11822 * <dt><b>Scheduler:</b></dt>
11823 * <dd>{@code retry} does not operate by default on a particular {@link Scheduler}.</dd>
11824 * </dl>
11825 *
11826 * @param predicate
11827 * the predicate that determines if a resubscription may happen in case of a specific exception
11828 * and retry count
11829 * @return the new {@code Observable} instance
11830 * @throws NullPointerException if {@code predicate} is {@code null}
11831 * @see #retry()
11832 * @see <a href="http://reactivex.io/documentation/operators/retry.html">ReactiveX operators documentation: Retry</a>
11833 */
11834 @CheckReturnValue
11835 @SchedulerSupport(SchedulerSupport.NONE)
11836 @NonNull
11837 public final Observable<T> retry(@NonNull BiPredicate<? super Integer, ? super Throwable> predicate) {
11838 Objects.requireNonNull(predicate, "predicate is null");
11839
11840 return RxJavaPlugins.onAssembly(new ObservableRetryBiPredicate<>(this, predicate));
11841 }
11842
11843 /**
11844 * Returns an {@code Observable} that mirrors the current {@code Observable}, resubscribing to it if it calls {@code onError}
11845 * up to a specified number of retries.
11846 * <p>
11847 * <img width="640" height="327" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/retry.o.n.v3.png" alt="">
11848 * <p>
11849 * If the current {@code Observable} calls {@link Observer#onError}, this method will resubscribe to the current
11850 * {@code Observable} for a maximum of {@code count} resubscriptions rather than propagating the
11851 * {@code onError} call.
11852 * <p>
11853 * Any and all items emitted by the current {@code Observable} will be emitted by the resulting {@code Observable}, even
11854 * those emitted during failed subscriptions. For example, if the current {@code Observable} fails at first but emits
11855 * {@code [1, 2]} then succeeds the second time and emits {@code [1, 2, 3, 4, 5]} then the complete sequence
11856 * of emissions and notifications would be {@code [1, 2, 1, 2, 3, 4, 5, onComplete]}.
11857 * <dl>
11858 * <dt><b>Scheduler:</b></dt>
11859 * <dd>{@code retry} does not operate by default on a particular {@link Scheduler}.</dd>
11860 * </dl>
11861 *
11862 * @param times
11863 * the number of times to resubscribe if the current {@code Observable} fails
11864 * @return the new {@code Observable} instance
11865 * @throws IllegalArgumentException if {@code times} is negative
11866 * @see <a href="http://reactivex.io/documentation/operators/retry.html">ReactiveX operators documentation: Retry</a>
11867 */
11868 @CheckReturnValue
11869 @SchedulerSupport(SchedulerSupport.NONE)
11870 @NonNull
11871 public final Observable<T> retry(long times) {
11872 return retry(times, Functions.alwaysTrue());
11873 }
11874
11875 /**
11876 * Retries at most times or until the predicate returns {@code false}, whichever happens first.
11877 * <p>
11878 * <img width="640" height="270" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/retry.o.nfe.png" alt="">
11879 * <dl>
11880 * <dt><b>Scheduler:</b></dt>
11881 * <dd>{@code retry} does not operate by default on a particular {@link Scheduler}.</dd>
11882 * </dl>
11883 * @param times the number of times to resubscribe if the current {@code Observable} fails
11884 * @param predicate the predicate called with the failure {@link Throwable} and should return {@code true} to trigger a retry.
11885 * @throws NullPointerException if {@code predicate} is {@code null}
11886 * @throws IllegalArgumentException if {@code times} is negative
11887 * @return the new {@code Observable} instance
11888 */
11889 @CheckReturnValue
11890 @SchedulerSupport(SchedulerSupport.NONE)
11891 @NonNull
11892 public final Observable<T> retry(long times, @NonNull Predicate<? super Throwable> predicate) {
11893 if (times < 0) {
11894 throw new IllegalArgumentException("times >= 0 required but it was " + times);
11895 }
11896 Objects.requireNonNull(predicate, "predicate is null");
11897
11898 return RxJavaPlugins.onAssembly(new ObservableRetryPredicate<>(this, times, predicate));
11899 }
11900
11901 /**
11902 * Retries the current {@code Observable} if the predicate returns {@code true}.
11903 * <p>
11904 * <img width="640" height="249" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/retry.o.e.png" alt="">
11905 * <dl>
11906 * <dt><b>Scheduler:</b></dt>
11907 * <dd>{@code retry} does not operate by default on a particular {@link Scheduler}.</dd>
11908 * </dl>
11909 *
11910 * @param predicate the predicate that receives the failure {@link Throwable} and should return {@code true} to trigger a retry.
11911 * @return the new {@code Observable} instance
11912 * @throws NullPointerException if {@code predicate} is {@code null}
11913 */
11914 @CheckReturnValue
11915 @SchedulerSupport(SchedulerSupport.NONE)
11916 @NonNull
11917 public final Observable<T> retry(@NonNull Predicate<? super Throwable> predicate) {
11918 return retry(Long.MAX_VALUE, predicate);
11919 }
11920
11921 /**
11922 * Retries until the given stop function returns {@code true}.
11923 * <p>
11924 * <img width="640" height="262" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/retryUntil.o.png" alt="">
11925 * <dl>
11926 * <dt><b>Scheduler:</b></dt>
11927 * <dd>{@code retryUntil} does not operate by default on a particular {@link Scheduler}.</dd>
11928 * </dl>
11929 * @param stop the function that should return {@code true} to stop retrying
11930 * @return the new {@code Observable} instance
11931 * @throws NullPointerException if {@code stop} is {@code null}
11932 */
11933 @CheckReturnValue
11934 @SchedulerSupport(SchedulerSupport.NONE)
11935 @NonNull
11936 public final Observable<T> retryUntil(@NonNull BooleanSupplier stop) {
11937 Objects.requireNonNull(stop, "stop is null");
11938 return retry(Long.MAX_VALUE, Functions.predicateReverseFor(stop));
11939 }
11940
11941 /**
11942 * Returns an {@code Observable} that emits the same values as the current {@code Observable} with the exception of an
11943 * {@code onError}. An {@code onError} notification from the source will result in the emission of a
11944 * {@link Throwable} item to the {@code Observable} provided as an argument to the {@code notificationHandler}
11945 * function. If that {@code Observable} calls {@code onComplete} or {@code onError} then {@code retry} will call
11946 * {@code onComplete} or {@code onError} on the child subscription. Otherwise, the current {@code Observable}
11947 * will be resubscribed.
11948 * <p>
11949 * <img width="640" height="430" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/retryWhen.f.v3.png" alt="">
11950 * <p>
11951 * Example:
11952 *
11953 * This retries 3 times, each time incrementing the number of seconds it waits.
11954 *
11955 * <pre><code>
11956 * Observable.create((ObservableEmitter&lt;? super String&gt; s) -&gt; {
11957 * System.out.println("subscribing");
11958 * s.onError(new RuntimeException("always fails"));
11959 * }).retryWhen(attempts -&gt; {
11960 * return attempts.zipWith(Observable.range(1, 3), (n, i) -&gt; i).flatMap(i -&gt; {
11961 * System.out.println("delay retry by " + i + " second(s)");
11962 * return Observable.timer(i, TimeUnit.SECONDS);
11963 * });
11964 * }).blockingForEach(System.out::println);
11965 * </code></pre>
11966 *
11967 * Output is:
11968 *
11969 * <pre> {@code
11970 * subscribing
11971 * delay retry by 1 second(s)
11972 * subscribing
11973 * delay retry by 2 second(s)
11974 * subscribing
11975 * delay retry by 3 second(s)
11976 * subscribing
11977 * } </pre>
11978 * <p>
11979 * Note that the inner {@link ObservableSource} returned by the handler function should signal
11980 * either {@code onNext}, {@code onError} or {@code onComplete} in response to the received
11981 * {@code Throwable} to indicate the operator should retry or terminate. If the upstream to
11982 * the operator is asynchronous, signaling {@code onNext} followed by {@code onComplete} immediately may
11983 * result in the sequence to be completed immediately. Similarly, if this inner
11984 * {@code ObservableSource} signals {@code onError} or {@code onComplete} while the upstream is
11985 * active, the sequence is terminated with the same signal immediately.
11986 * <p>
11987 * The following example demonstrates how to retry an asynchronous source with a delay:
11988 * <pre><code>
11989 * Observable.timer(1, TimeUnit.SECONDS)
11990 * .doOnSubscribe(s -&gt; System.out.println("subscribing"))
11991 * .map(v -&gt; { throw new RuntimeException(); })
11992 * .retryWhen(errors -&gt; {
11993 * AtomicInteger counter = new AtomicInteger();
11994 * return errors
11995 * .takeWhile(e -&gt; counter.getAndIncrement() != 3)
11996 * .flatMap(e -&gt; {
11997 * System.out.println("delay retry by " + counter.get() + " second(s)");
11998 * return Observable.timer(counter.get(), TimeUnit.SECONDS);
11999 * });
12000 * })
12001 * .blockingSubscribe(System.out::println, System.out::println);
12002 * </code></pre>
12003 * <dl>
12004 * <dt><b>Scheduler:</b></dt>
12005 * <dd>{@code retryWhen} does not operate by default on a particular {@link Scheduler}.</dd>
12006 * </dl>
12007 *
12008 * @param handler
12009 * receives an {@code Observable} of notifications with which a user can complete or error, aborting the
12010 * retry
12011 * @return the new {@code Observable} instance
12012 * @throws NullPointerException if {@code handler} is {@code null}
12013 * @see <a href="http://reactivex.io/documentation/operators/retry.html">ReactiveX operators documentation: Retry</a>
12014 */
12015 @CheckReturnValue
12016 @SchedulerSupport(SchedulerSupport.NONE)
12017 @NonNull
12018 public final Observable<T> retryWhen(
12019 @NonNull Function<? super Observable<Throwable>, ? extends ObservableSource<?>> handler) {
12020 Objects.requireNonNull(handler, "handler is null");
12021 return RxJavaPlugins.onAssembly(new ObservableRetryWhen<>(this, handler));
12022 }
12023
12024 /**
12025 * Subscribes to the current {@code Observable} and wraps the given {@link Observer} into a {@link SafeObserver}
12026 * (if not already a {@code SafeObserver}) that
12027 * deals with exceptions thrown by a misbehaving {@code Observer} (that doesn't follow the
12028 * <em>Reactive Streams</em> specification).
12029 * <dl>
12030 * <dt><b>Scheduler:</b></dt>
12031 * <dd>{@code safeSubscribe} does not operate by default on a particular {@link Scheduler}.</dd>
12032 * </dl>
12033 * @param observer the incoming {@code Observer} instance
12034 * @throws NullPointerException if {@code observer} is {@code null}
12035 */
12036 @SchedulerSupport(SchedulerSupport.NONE)
12037 public final void safeSubscribe(@NonNull Observer<? super T> observer) {
12038 Objects.requireNonNull(observer, "observer is null");
12039 if (observer instanceof SafeObserver) {
12040 subscribe(observer);
12041 } else {
12042 subscribe(new SafeObserver<>(observer));
12043 }
12044 }
12045
12046 /**
12047 * Returns an {@code Observable} that emits the most recently emitted item (if any) emitted by the current {@code Observable}
12048 * within periodic time intervals.
12049 * <p>
12050 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/sample.v3.png" alt="">
12051 * <dl>
12052 * <dt><b>Scheduler:</b></dt>
12053 * <dd>{@code sample} operates by default on the {@code computation} {@link Scheduler}.</dd>
12054 * </dl>
12055 *
12056 * @param period
12057 * the sampling rate
12058 * @param unit
12059 * the {@link TimeUnit} in which {@code period} is defined
12060 * @return the new {@code Observable} instance
12061 * @throws NullPointerException if {@code unit} is {@code null}
12062 * @see <a href="http://reactivex.io/documentation/operators/sample.html">ReactiveX operators documentation: Sample</a>
12063 * @see #throttleLast(long, TimeUnit)
12064 */
12065 @CheckReturnValue
12066 @SchedulerSupport(SchedulerSupport.COMPUTATION)
12067 @NonNull
12068 public final Observable<T> sample(long period, @NonNull TimeUnit unit) {
12069 return sample(period, unit, Schedulers.computation());
12070 }
12071
12072 /**
12073 * Returns an {@code Observable} that emits the most recently emitted item (if any) emitted by the current {@code Observable}
12074 * within periodic time intervals and optionally emit the very last upstream item when the upstream completes.
12075 * <p>
12076 * <img width="640" height="277" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/sample.emitlast.png" alt="">
12077 * <dl>
12078 * <dt><b>Scheduler:</b></dt>
12079 * <dd>{@code sample} operates by default on the {@code computation} {@link Scheduler}.</dd>
12080 * </dl>
12081 *
12082 * <p>History: 2.0.5 - experimental
12083 * @param period
12084 * the sampling rate
12085 * @param unit
12086 * the {@link TimeUnit} in which {@code period} is defined
12087 * @param emitLast
12088 * if {@code true} and the upstream completes while there is still an unsampled item available,
12089 * that item is emitted to downstream before completion
12090 * if {@code false}, an unsampled last item is ignored.
12091 * @return the new {@code Observable} instance
12092 * @throws NullPointerException if {@code unit} is {@code null}
12093 * @see <a href="http://reactivex.io/documentation/operators/sample.html">ReactiveX operators documentation: Sample</a>
12094 * @see #throttleLast(long, TimeUnit)
12095 * @since 2.1
12096 */
12097 @CheckReturnValue
12098 @SchedulerSupport(SchedulerSupport.COMPUTATION)
12099 @NonNull
12100 public final Observable<T> sample(long period, @NonNull TimeUnit unit, boolean emitLast) {
12101 return sample(period, unit, Schedulers.computation(), emitLast);
12102 }
12103
12104 /**
12105 * Returns an {@code Observable} that emits the most recently emitted item (if any) emitted by the current {@code Observable}
12106 * within periodic time intervals, where the intervals are defined on a particular {@link Scheduler}.
12107 * <p>
12108 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/sample.s.v3.png" alt="">
12109 * <dl>
12110 * <dt><b>Scheduler:</b></dt>
12111 * <dd>You specify which {@code Scheduler} this operator will use.</dd>
12112 * </dl>
12113 *
12114 * @param period
12115 * the sampling rate
12116 * @param unit
12117 * the {@link TimeUnit} in which {@code period} is defined
12118 * @param scheduler
12119 * the {@code Scheduler} to use when sampling
12120 * @return the new {@code Observable} instance
12121 * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null}
12122 * @see <a href="http://reactivex.io/documentation/operators/sample.html">ReactiveX operators documentation: Sample</a>
12123 * @see #throttleLast(long, TimeUnit, Scheduler)
12124 */
12125 @CheckReturnValue
12126 @SchedulerSupport(SchedulerSupport.CUSTOM)
12127 @NonNull
12128 public final Observable<T> sample(long period, @NonNull TimeUnit unit, @NonNull Scheduler scheduler) {
12129 Objects.requireNonNull(unit, "unit is null");
12130 Objects.requireNonNull(scheduler, "scheduler is null");
12131 return RxJavaPlugins.onAssembly(new ObservableSampleTimed<>(this, period, unit, scheduler, false));
12132 }
12133
12134 /**
12135 * Returns an {@code Observable} that emits the most recently emitted item (if any) emitted by the current {@code Observable}
12136 * within periodic time intervals, where the intervals are defined on a particular {@link Scheduler}
12137 * and optionally emit the very last upstream item when the upstream completes.
12138 * <p>
12139 * <img width="640" height="277" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/sample.s.emitlast.png" alt="">
12140 * <dl>
12141 * <dt><b>Scheduler:</b></dt>
12142 * <dd>You specify which {@code Scheduler} this operator will use.</dd>
12143 * </dl>
12144 *
12145 * <p>History: 2.0.5 - experimental
12146 * @param period
12147 * the sampling rate
12148 * @param unit
12149 * the {@link TimeUnit} in which {@code period} is defined
12150 * @param scheduler
12151 * the {@code Scheduler} to use when sampling
12152 * @param emitLast
12153 * if {@code true} and the upstream completes while there is still an unsampled item available,
12154 * that item is emitted to downstream before completion
12155 * if {@code false}, an unsampled last item is ignored.
12156 * @return the new {@code Observable} instance
12157 * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null}
12158 * @see <a href="http://reactivex.io/documentation/operators/sample.html">ReactiveX operators documentation: Sample</a>
12159 * @see #throttleLast(long, TimeUnit, Scheduler)
12160 * @since 2.1
12161 */
12162 @CheckReturnValue
12163 @SchedulerSupport(SchedulerSupport.CUSTOM)
12164 @NonNull
12165 public final Observable<T> sample(long period, @NonNull TimeUnit unit, @NonNull Scheduler scheduler, boolean emitLast) {
12166 Objects.requireNonNull(unit, "unit is null");
12167 Objects.requireNonNull(scheduler, "scheduler is null");
12168 return RxJavaPlugins.onAssembly(new ObservableSampleTimed<>(this, period, unit, scheduler, emitLast));
12169 }
12170
12171 /**
12172 * Returns an {@code Observable} that, when the specified {@code sampler} {@link ObservableSource} emits an item or completes,
12173 * emits the most recently emitted item (if any) emitted by the current {@code Observable} since the previous
12174 * emission from the {@code sampler} {@code ObservableSource}.
12175 * <p>
12176 * <img width="640" height="290" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/sample.o.nolast.png" alt="">
12177 * <dl>
12178 * <dt><b>Scheduler:</b></dt>
12179 * <dd>This version of {@code sample} does not operate by default on a particular {@link Scheduler}.</dd>
12180 * </dl>
12181 *
12182 * @param <U> the element type of the sampler {@code ObservableSource}
12183 * @param sampler
12184 * the {@code ObservableSource} to use for sampling the current {@code Observable}
12185 * @return the new {@code Observable} instance
12186 * @throws NullPointerException if {@code sampler} is {@code null}
12187 * @see <a href="http://reactivex.io/documentation/operators/sample.html">ReactiveX operators documentation: Sample</a>
12188 */
12189 @CheckReturnValue
12190 @SchedulerSupport(SchedulerSupport.NONE)
12191 @NonNull
12192 public final <@NonNull U> Observable<T> sample(@NonNull ObservableSource<U> sampler) {
12193 Objects.requireNonNull(sampler, "sampler is null");
12194 return RxJavaPlugins.onAssembly(new ObservableSampleWithObservable<>(this, sampler, false));
12195 }
12196
12197 /**
12198 * Returns an {@code Observable} that, when the specified {@code sampler} {@link ObservableSource} emits an item or completes,
12199 * emits the most recently emitted item (if any) emitted by the current {@code Observable} since the previous
12200 * emission from the {@code sampler} {@code ObservableSource}
12201 * and optionally emit the very last upstream item when the upstream or other {@code ObservableSource} complete.
12202 * <p>
12203 * <img width="640" height="290" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/sample.o.emitlast.png" alt="">
12204 * <dl>
12205 * <dt><b>Scheduler:</b></dt>
12206 * <dd>This version of {@code sample} does not operate by default on a particular {@link Scheduler}.</dd>
12207 * </dl>
12208 *
12209 * <p>History: 2.0.5 - experimental
12210 * @param <U> the element type of the sampler {@code ObservableSource}
12211 * @param sampler
12212 * the {@code ObservableSource} to use for sampling the current {@code Observable}
12213 * @param emitLast
12214 * if {@code true} and the upstream completes while there is still an unsampled item available,
12215 * that item is emitted to downstream before completion
12216 * if {@code false}, an unsampled last item is ignored.
12217 * @return the new {@code Observable} instance
12218 * @throws NullPointerException if {@code sampler} is {@code null}
12219 * @see <a href="http://reactivex.io/documentation/operators/sample.html">ReactiveX operators documentation: Sample</a>
12220 * @since 2.1
12221 */
12222 @CheckReturnValue
12223 @SchedulerSupport(SchedulerSupport.NONE)
12224 @NonNull
12225 public final <@NonNull U> Observable<T> sample(@NonNull ObservableSource<U> sampler, boolean emitLast) {
12226 Objects.requireNonNull(sampler, "sampler is null");
12227 return RxJavaPlugins.onAssembly(new ObservableSampleWithObservable<>(this, sampler, emitLast));
12228 }
12229
12230 /**
12231 * Returns an {@code Observable} that emits the first value emitted by the current {@code Observable}, then emits one value
12232 * for each subsequent value emitted by the current {@code Observable}. Each emission after the first is the result of
12233 * applying the specified accumulator function to the previous emission and the corresponding value from the current {@code Observable}.
12234 * <p>
12235 * <img width="640" height="320" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/scan.v3.png" alt="">
12236 * <p>
12237 * This sort of function is sometimes called an accumulator.
12238 * <dl>
12239 * <dt><b>Scheduler:</b></dt>
12240 * <dd>{@code scan} does not operate by default on a particular {@link Scheduler}.</dd>
12241 * </dl>
12242 *
12243 * @param accumulator
12244 * an accumulator function to be invoked on each item emitted by the current {@code Observable}, whose
12245 * result will be emitted to {@link Observer}s via {@link Observer#onNext onNext} and used in the
12246 * next accumulator call
12247 * @return the new {@code Observable} instance
12248 * @throws NullPointerException if {@code accumulator} is {@code null}
12249 * @see <a href="http://reactivex.io/documentation/operators/scan.html">ReactiveX operators documentation: Scan</a>
12250 */
12251 @CheckReturnValue
12252 @SchedulerSupport(SchedulerSupport.NONE)
12253 @NonNull
12254 public final Observable<T> scan(@NonNull BiFunction<T, T, T> accumulator) {
12255 Objects.requireNonNull(accumulator, "accumulator is null");
12256 return RxJavaPlugins.onAssembly(new ObservableScan<>(this, accumulator));
12257 }
12258
12259 /**
12260 * Returns an {@code Observable} that emits the provided initial (seed) value, then emits one value for each value emitted
12261 * by the current {@code Observable}. Each emission after the first is the result of applying the specified accumulator
12262 * function to the previous emission and the corresponding value from the current {@code Observable}.
12263 * <p>
12264 * <img width="640" height="320" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/scanSeed.v3.png" alt="">
12265 * <p>
12266 * This sort of function is sometimes called an accumulator.
12267 * <p>
12268 * Note that the {@code Observable} that results from this method will emit {@code initialValue} as its first
12269 * emitted item.
12270 * <p>
12271 * Note that the {@code initialValue} is shared among all subscribers to the resulting {@code Observable}
12272 * and may cause problems if it is mutable. To make sure each subscriber gets its own value, defer
12273 * the application of this operator via {@link #defer(Supplier)}:
12274 * <pre><code>
12275 * ObservableSource&lt;T&gt; source = ...
12276 * Observable.defer(() -&gt; source.scan(new ArrayList&lt;&gt;(), (list, item) -&gt; list.add(item)));
12277 *
12278 * // alternatively, by using compose to stay fluent
12279 *
12280 * source.compose(o -&gt;
12281 * Observable.defer(() -&gt; o.scan(new ArrayList&lt;&gt;(), (list, item) -&gt; list.add(item)))
12282 * );
12283 * </code></pre>
12284 * <dl>
12285 * <dt><b>Scheduler:</b></dt>
12286 * <dd>{@code scan} does not operate by default on a particular {@link Scheduler}.</dd>
12287 * </dl>
12288 *
12289 * @param <R> the initial, accumulator and result type
12290 * @param initialValue
12291 * the initial (seed) accumulator item
12292 * @param accumulator
12293 * an accumulator function to be invoked on each item emitted by the current {@code Observable}, whose
12294 * result will be emitted to {@link Observer}s via {@link Observer#onNext onNext} and used in the
12295 * next accumulator call
12296 * @return the new {@code Observable} instance
12297 * @throws NullPointerException if {@code initialValue} or {@code accumulator} is {@code null}
12298 * @see <a href="http://reactivex.io/documentation/operators/scan.html">ReactiveX operators documentation: Scan</a>
12299 */
12300 @CheckReturnValue
12301 @SchedulerSupport(SchedulerSupport.NONE)
12302 @NonNull
12303 public final <@NonNull R> Observable<R> scan(@NonNull R initialValue, @NonNull BiFunction<R, ? super T, R> accumulator) {
12304 Objects.requireNonNull(initialValue, "initialValue is null");
12305 return scanWith(Functions.justSupplier(initialValue), accumulator);
12306 }
12307
12308 /**
12309 * Returns an {@code Observable} that emits the provided initial (seed) value, then emits one value for each value emitted
12310 * by the current {@code Observable}. Each emission after the first is the result of applying the specified accumulator
12311 * function to the previous emission and the corresponding value from the current {@code Observable}.
12312 * <p>
12313 * <img width="640" height="320" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/scanSeed.v3.png" alt="">
12314 * <p>
12315 * This sort of function is sometimes called an accumulator.
12316 * <p>
12317 * Note that the {@code Observable} that results from this method will emit the value returned
12318 * by the {@code seedSupplier} as its first item.
12319 * <dl>
12320 * <dt><b>Scheduler:</b></dt>
12321 * <dd>{@code scanWith} does not operate by default on a particular {@link Scheduler}.</dd>
12322 * </dl>
12323 *
12324 * @param <R> the initial, accumulator and result type
12325 * @param seedSupplier
12326 * a {@link Supplier} that returns the initial (seed) accumulator item for each individual {@link Observer}
12327 * @param accumulator
12328 * an accumulator function to be invoked on each item emitted by the current {@code Observable}, whose
12329 * result will be emitted to {@code Observer}s via {@link Observer#onNext onNext} and used in the
12330 * next accumulator call
12331 * @return the new {@code Observable} instance
12332 * @throws NullPointerException if {@code seedSupplier} or {@code accumulator} is {@code null}
12333 * @see <a href="http://reactivex.io/documentation/operators/scan.html">ReactiveX operators documentation: Scan</a>
12334 */
12335 @CheckReturnValue
12336 @SchedulerSupport(SchedulerSupport.NONE)
12337 @NonNull
12338 public final <@NonNull R> Observable<R> scanWith(@NonNull Supplier<R> seedSupplier, @NonNull BiFunction<R, ? super T, R> accumulator) {
12339 Objects.requireNonNull(seedSupplier, "seedSupplier is null");
12340 Objects.requireNonNull(accumulator, "accumulator is null");
12341 return RxJavaPlugins.onAssembly(new ObservableScanSeed<>(this, seedSupplier, accumulator));
12342 }
12343
12344 /**
12345 * Forces the current {@code Observable}'s emissions and notifications to be serialized and for it to obey
12346 * <a href="http://reactivex.io/documentation/contract.html">the {@code ObservableSource} contract</a> in other ways.
12347 * <p>
12348 * It is possible for an {@code Observable} to invoke its {@link Observer}s' methods asynchronously, perhaps from
12349 * different threads. This could make such an {@code Observable} poorly-behaved, in that it might try to invoke
12350 * {@code onComplete} or {@code onError} before one of its {@code onNext} invocations, or it might call
12351 * {@code onNext} from two different threads concurrently. You can force such an {@code Observable} to be
12352 * well-behaved and sequential by applying the {@code serialize} method to it.
12353 * <p>
12354 * <img width="640" height="400" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/synchronize.v3.png" alt="">
12355 * <dl>
12356 * <dt><b>Scheduler:</b></dt>
12357 * <dd>{@code serialize} does not operate by default on a particular {@link Scheduler}.</dd>
12358 * </dl>
12359 *
12360 * @return the new {@code Observable} instance
12361 * @see <a href="http://reactivex.io/documentation/operators/serialize.html">ReactiveX operators documentation: Serialize</a>
12362 */
12363 @CheckReturnValue
12364 @SchedulerSupport(SchedulerSupport.NONE)
12365 @NonNull
12366 public final Observable<T> serialize() {
12367 return RxJavaPlugins.onAssembly(new ObservableSerialized<>(this));
12368 }
12369
12370 /**
12371 * Returns a new {@code Observable} that multicasts (and shares a single subscription to) the current {@code Observable}. As long as
12372 * there is at least one {@link Observer}, the current {@code Observable} will stay subscribed and keep emitting signals.
12373 * When all observers have disposed, the operator will dispose the subscription to the current {@code Observable}.
12374 * <p>
12375 * This is an alias for {@link #publish()}.{@link ConnectableObservable#refCount() refCount()}.
12376 * <p>
12377 * <img width="640" height="510" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/publishRefCount.o.v3.png" alt="">
12378 * <dl>
12379 * <dt><b>Scheduler:</b></dt>
12380 * <dd>{@code share} does not operate by default on a particular {@link Scheduler}.</dd>
12381 * </dl>
12382 *
12383 * @return the new {@code Observable} instance
12384 * @see <a href="http://reactivex.io/documentation/operators/refcount.html">ReactiveX operators documentation: RefCount</a>
12385 */
12386 @CheckReturnValue
12387 @SchedulerSupport(SchedulerSupport.NONE)
12388 @NonNull
12389 public final Observable<T> share() {
12390 return publish().refCount();
12391 }
12392
12393 /**
12394 * Returns a {@link Maybe} that completes if the current {@code Observable} is empty or emits the single item
12395 * emitted by the current {@code Observable}, or signals an {@link IllegalArgumentException} if the current
12396 * {@code Observable} emits more than one item.
12397 * <p>
12398 * <img width="640" height="217" src="https://raw.githubusercontent.com/wiki/ReactiveX/RxJava/images/rx-operators/singleElement.o.v3.png" alt="">
12399 * <dl>
12400 * <dt><b>Scheduler:</b></dt>
12401 * <dd>{@code singleElement} does not operate by default on a particular {@link Scheduler}.</dd>
12402 * </dl>
12403 *
12404 * @return the new {@code Maybe} instance
12405 * @see <a href="http://reactivex.io/documentation/operators/first.html">ReactiveX operators documentation: First</a>
12406 */
12407 @CheckReturnValue
12408 @SchedulerSupport(SchedulerSupport.NONE)
12409 @NonNull
12410 public final Maybe<T> singleElement() {
12411 return RxJavaPlugins.onAssembly(new ObservableSingleMaybe<>(this));
12412 }
12413
12414 /**
12415 * Returns a {@link Single} that emits the single item emitted by the current {@code Observable}, if the current {@code Observable}
12416 * emits only a single item, or a default item if the current {@code Observable} emits no items. If the current
12417 * {@code Observable} emits more than one item, an {@link IllegalArgumentException} is signaled instead.
12418 * <p>
12419 * <img width="640" height="315" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/single.2.v3.png" alt="">
12420 * <dl>
12421 * <dt><b>Scheduler:</b></dt>
12422 * <dd>{@code single} does not operate by default on a particular {@link Scheduler}.</dd>
12423 * </dl>
12424 *
12425 * @param defaultItem
12426 * a default value to emit if the current {@code Observable} emits no item
12427 * @return the new {@code Single} instance
12428 * @throws NullPointerException if {@code defaultItem} is {@code null}
12429 * @see <a href="http://reactivex.io/documentation/operators/first.html">ReactiveX operators documentation: First</a>
12430 */
12431 @CheckReturnValue
12432 @SchedulerSupport(SchedulerSupport.NONE)
12433 @NonNull
12434 public final Single<T> single(@NonNull T defaultItem) {
12435 Objects.requireNonNull(defaultItem, "defaultItem is null");
12436 return RxJavaPlugins.onAssembly(new ObservableSingleSingle<>(this, defaultItem));
12437 }
12438
12439 /**
12440 * Returns a {@link Single} that emits the single item emitted by the current {@code Observable} if it
12441 * emits only a single item, otherwise
12442 * if the current {@code Observable} completes without emitting any items or emits more than one item a
12443 * {@link NoSuchElementException} or {@link IllegalArgumentException} will be signaled respectively.
12444 * <p>
12445 * <img width="640" height="206" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/singleOrError.png" alt="">
12446 * <dl>
12447 * <dt><b>Scheduler:</b></dt>
12448 * <dd>{@code singleOrError} does not operate by default on a particular {@link Scheduler}.</dd>
12449 * </dl>
12450 *
12451 * @return the new {@code Single} instance
12452 * @see <a href="http://reactivex.io/documentation/operators/first.html">ReactiveX operators documentation: First</a>
12453 */
12454 @CheckReturnValue
12455 @SchedulerSupport(SchedulerSupport.NONE)
12456 @NonNull
12457 public final Single<T> singleOrError() {
12458 return RxJavaPlugins.onAssembly(new ObservableSingleSingle<>(this, null));
12459 }
12460
12461 /**
12462 * Returns an {@code Observable} that skips the first {@code count} items emitted by the current {@code Observable} and emits
12463 * the remainder.
12464 * <p>
12465 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/skip.v3.png" alt="">
12466 * <dl>
12467 * <dt><b>Scheduler:</b></dt>
12468 * <dd>This version of {@code skip} does not operate by default on a particular {@link Scheduler}.</dd>
12469 * </dl>
12470 *
12471 * @param count
12472 * the number of items to skip
12473 * @return the new {@code Observable} instance
12474 * @throws IllegalArgumentException if {@code count} is negative
12475 * @see <a href="http://reactivex.io/documentation/operators/skip.html">ReactiveX operators documentation: Skip</a>
12476 */
12477 @CheckReturnValue
12478 @SchedulerSupport(SchedulerSupport.NONE)
12479 @NonNull
12480 public final Observable<T> skip(long count) {
12481 if (count < 0) {
12482 throw new IllegalArgumentException("count >= 0 expected but it was " + count);
12483 }
12484 if (count == 0) {
12485 return RxJavaPlugins.onAssembly(this);
12486 }
12487 return RxJavaPlugins.onAssembly(new ObservableSkip<>(this, count));
12488 }
12489
12490 /**
12491 * Returns an {@code Observable} that skips values emitted by the current {@code Observable} before a specified time window
12492 * elapses.
12493 * <p>
12494 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/skip.t.v3.png" alt="">
12495 * <dl>
12496 * <dt><b>Scheduler:</b></dt>
12497 * <dd>{@code skip} does not operate on any particular scheduler but uses the current time
12498 * from the {@code computation} {@link Scheduler}.</dd>
12499 * </dl>
12500 *
12501 * @param time
12502 * the length of the time window to skip
12503 * @param unit
12504 * the time unit of {@code time}
12505 * @return the new {@code Observable} instance
12506 * @throws NullPointerException if {@code unit} is {@code null}
12507 * @see <a href="http://reactivex.io/documentation/operators/skip.html">ReactiveX operators documentation: Skip</a>
12508 */
12509 @CheckReturnValue
12510 @SchedulerSupport(SchedulerSupport.COMPUTATION)
12511 @NonNull
12512 public final Observable<T> skip(long time, @NonNull TimeUnit unit) {
12513 return skipUntil(timer(time, unit));
12514 }
12515
12516 /**
12517 * Returns an {@code Observable} that skips values emitted by the current {@code Observable} before a specified time window
12518 * on a specified {@link Scheduler} elapses.
12519 * <p>
12520 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/skip.ts.v3.png" alt="">
12521 * <dl>
12522 * <dt><b>Scheduler:</b></dt>
12523 * <dd>You specify which {@code Scheduler} this operator will use for the timed skipping</dd>
12524 * </dl>
12525 *
12526 * @param time
12527 * the length of the time window to skip
12528 * @param unit
12529 * the time unit of {@code time}
12530 * @param scheduler
12531 * the {@code Scheduler} on which the timed wait happens
12532 * @return the new {@code Observable} instance
12533 * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null}
12534 * @see <a href="http://reactivex.io/documentation/operators/skip.html">ReactiveX operators documentation: Skip</a>
12535 */
12536 @CheckReturnValue
12537 @SchedulerSupport(SchedulerSupport.CUSTOM)
12538 @NonNull
12539 public final Observable<T> skip(long time, @NonNull TimeUnit unit, @NonNull Scheduler scheduler) {
12540 return skipUntil(timer(time, unit, scheduler));
12541 }
12542
12543 /**
12544 * Returns an {@code Observable} that drops a specified number of items from the end of the sequence emitted by the
12545 * current {@code Observable}.
12546 * <p>
12547 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/skipLast.v3.png" alt="">
12548 * <p>
12549 * This {@link Observer} accumulates a queue long enough to store the first {@code count} items. As more items are
12550 * received, items are taken from the front of the queue and emitted by the returned {@code Observable}. This causes
12551 * such items to be delayed.
12552 * <dl>
12553 * <dt><b>Scheduler:</b></dt>
12554 * <dd>This version of {@code skipLast} does not operate by default on a particular {@link Scheduler}.</dd>
12555 * </dl>
12556 *
12557 * @param count
12558 * number of items to drop from the end of the source sequence
12559 * @return the new {@code Observable} instance
12560 * @throws IllegalArgumentException
12561 * if {@code count} is negative
12562 * @see <a href="http://reactivex.io/documentation/operators/skiplast.html">ReactiveX operators documentation: SkipLast</a>
12563 */
12564 @CheckReturnValue
12565 @SchedulerSupport(SchedulerSupport.NONE)
12566 @NonNull
12567 public final Observable<T> skipLast(int count) {
12568 if (count < 0) {
12569 throw new IllegalArgumentException("count >= 0 required but it was " + count);
12570 }
12571 if (count == 0) {
12572 return RxJavaPlugins.onAssembly(this);
12573 }
12574 return RxJavaPlugins.onAssembly(new ObservableSkipLast<>(this, count));
12575 }
12576
12577 /**
12578 * Returns an {@code Observable} that drops items emitted by the current {@code Observable} during a specified time window
12579 * before the source completes.
12580 * <p>
12581 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/skipLast.t.v3.png" alt="">
12582 * <p>
12583 * Note: this action will cache the latest items arriving in the specified time window.
12584 * <dl>
12585 * <dt><b>Scheduler:</b></dt>
12586 * <dd>{@code skipLast} does not operate on any particular scheduler but uses the current time
12587 * from the {@code trampoline} {@link Scheduler}.</dd>
12588 * </dl>
12589 *
12590 * @param time
12591 * the length of the time window
12592 * @param unit
12593 * the time unit of {@code time}
12594 * @return the new {@code Observable} instance
12595 * @throws NullPointerException if {@code unit} is {@code null}
12596 * @see <a href="http://reactivex.io/documentation/operators/skiplast.html">ReactiveX operators documentation: SkipLast</a>
12597 */
12598 @CheckReturnValue
12599 @SchedulerSupport(SchedulerSupport.TRAMPOLINE)
12600 @NonNull
12601 public final Observable<T> skipLast(long time, @NonNull TimeUnit unit) {
12602 return skipLast(time, unit, Schedulers.trampoline(), false, bufferSize());
12603 }
12604
12605 /**
12606 * Returns an {@code Observable} that drops items emitted by the current {@code Observable} during a specified time window
12607 * before the source completes.
12608 * <p>
12609 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/skipLast.t.v3.png" alt="">
12610 * <p>
12611 * Note: this action will cache the latest items arriving in the specified time window.
12612 * <dl>
12613 * <dt><b>Scheduler:</b></dt>
12614 * <dd>{@code skipLast} does not operate on any particular scheduler but uses the current time
12615 * from the {@code computation} {@link Scheduler}.</dd>
12616 * </dl>
12617 *
12618 * @param time
12619 * the length of the time window
12620 * @param unit
12621 * the time unit of {@code time}
12622 * @param delayError
12623 * if {@code true}, an exception signaled by the current {@code Observable} is delayed until the regular elements are consumed
12624 * by the downstream; if {@code false}, an exception is immediately signaled and all regular elements dropped
12625 * @return the new {@code Observable} instance
12626 * @throws NullPointerException if {@code unit} is {@code null}
12627 * @see <a href="http://reactivex.io/documentation/operators/skiplast.html">ReactiveX operators documentation: SkipLast</a>
12628 */
12629 @CheckReturnValue
12630 @SchedulerSupport(SchedulerSupport.TRAMPOLINE)
12631 @NonNull
12632 public final Observable<T> skipLast(long time, @NonNull TimeUnit unit, boolean delayError) {
12633 return skipLast(time, unit, Schedulers.trampoline(), delayError, bufferSize());
12634 }
12635
12636 /**
12637 * Returns an {@code Observable} that drops items emitted by the current {@code Observable} during a specified time window
12638 * (defined on a specified scheduler) before the source completes.
12639 * <p>
12640 * <img width="640" height="340" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/skipLast.ts.v3.png" alt="">
12641 * <p>
12642 * Note: this action will cache the latest items arriving in the specified time window.
12643 * <dl>
12644 * <dt><b>Scheduler:</b></dt>
12645 * <dd>You specify which {@link Scheduler} this operator will use for tracking the current time</dd>
12646 * </dl>
12647 *
12648 * @param time
12649 * the length of the time window
12650 * @param unit
12651 * the time unit of {@code time}
12652 * @param scheduler
12653 * the scheduler used as the time source
12654 * @return the new {@code Observable} instance
12655 * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null}
12656 * @see <a href="http://reactivex.io/documentation/operators/skiplast.html">ReactiveX operators documentation: SkipLast</a>
12657 */
12658 @CheckReturnValue
12659 @SchedulerSupport(SchedulerSupport.CUSTOM)
12660 @NonNull
12661 public final Observable<T> skipLast(long time, @NonNull TimeUnit unit, @NonNull Scheduler scheduler) {
12662 return skipLast(time, unit, scheduler, false, bufferSize());
12663 }
12664
12665 /**
12666 * Returns an {@code Observable} that drops items emitted by the current {@code Observable} during a specified time window
12667 * (defined on a specified scheduler) before the source completes.
12668 * <p>
12669 * <img width="640" height="340" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/skipLast.ts.v3.png" alt="">
12670 * <p>
12671 * Note: this action will cache the latest items arriving in the specified time window.
12672 * <dl>
12673 * <dt><b>Scheduler:</b></dt>
12674 * <dd>You specify which {@link Scheduler} this operator will use to track the current time</dd>
12675 * </dl>
12676 *
12677 * @param time
12678 * the length of the time window
12679 * @param unit
12680 * the time unit of {@code time}
12681 * @param scheduler
12682 * the scheduler used as the time source
12683 * @param delayError
12684 * if {@code true}, an exception signaled by the current {@code Observable} is delayed until the regular elements are consumed
12685 * by the downstream; if {@code false}, an exception is immediately signaled and all regular elements dropped
12686 * @return the new {@code Observable} instance
12687 * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null}
12688 * @see <a href="http://reactivex.io/documentation/operators/skiplast.html">ReactiveX operators documentation: SkipLast</a>
12689 */
12690 @CheckReturnValue
12691 @SchedulerSupport(SchedulerSupport.CUSTOM)
12692 @NonNull
12693 public final Observable<T> skipLast(long time, @NonNull TimeUnit unit, @NonNull Scheduler scheduler, boolean delayError) {
12694 return skipLast(time, unit, scheduler, delayError, bufferSize());
12695 }
12696
12697 /**
12698 * Returns an {@code Observable} that drops items emitted by the current {@code Observable} during a specified time window
12699 * (defined on a specified scheduler) before the source completes.
12700 * <p>
12701 * <img width="640" height="340" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/skipLast.ts.v3.png" alt="">
12702 * <p>
12703 * Note: this action will cache the latest items arriving in the specified time window.
12704 * <dl>
12705 * <dt><b>Scheduler:</b></dt>
12706 * <dd>You specify which {@link Scheduler} this operator will use.</dd>
12707 * </dl>
12708 *
12709 * @param time
12710 * the length of the time window
12711 * @param unit
12712 * the time unit of {@code time}
12713 * @param scheduler
12714 * the scheduler used as the time source
12715 * @param delayError
12716 * if {@code true}, an exception signaled by the current {@code Observable} is delayed until the regular elements are consumed
12717 * by the downstream; if {@code false}, an exception is immediately signaled and all regular elements dropped
12718 * @param bufferSize
12719 * the hint about how many elements to expect to be skipped
12720 * @return the new {@code Observable} instance
12721 * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null}
12722 * @throws IllegalArgumentException if {@code bufferSize} is non-positive
12723 * @see <a href="http://reactivex.io/documentation/operators/skiplast.html">ReactiveX operators documentation: SkipLast</a>
12724 */
12725 @CheckReturnValue
12726 @SchedulerSupport(SchedulerSupport.CUSTOM)
12727 @NonNull
12728 public final Observable<T> skipLast(long time, @NonNull TimeUnit unit, @NonNull Scheduler scheduler, boolean delayError, int bufferSize) {
12729 Objects.requireNonNull(unit, "unit is null");
12730 Objects.requireNonNull(scheduler, "scheduler is null");
12731 ObjectHelper.verifyPositive(bufferSize, "bufferSize");
12732 // the internal buffer holds pairs of (timestamp, value) so double the default buffer size
12733 int s = bufferSize << 1;
12734 return RxJavaPlugins.onAssembly(new ObservableSkipLastTimed<>(this, time, unit, scheduler, s, delayError));
12735 }
12736
12737 /**
12738 * Returns an {@code Observable} that skips items emitted by the current {@code Observable} until a second {@link ObservableSource} emits
12739 * an item.
12740 * <p>
12741 * <img width="640" height="375" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/skipUntil.v3.png" alt="">
12742 * <dl>
12743 * <dt><b>Scheduler:</b></dt>
12744 * <dd>{@code skipUntil} does not operate by default on a particular {@link Scheduler}.</dd>
12745 * </dl>
12746 *
12747 * @param <U> the element type of the other {@code ObservableSource}
12748 * @param other
12749 * the second {@code ObservableSource} that has to emit an item before the current {@code Observable}'s elements begin
12750 * to be mirrored by the resulting {@code Observable}
12751 * @return the new {@code Observable} instance
12752 * @throws NullPointerException if {@code other} is {@code null}
12753 * @see <a href="http://reactivex.io/documentation/operators/skipuntil.html">ReactiveX operators documentation: SkipUntil</a>
12754 */
12755 @CheckReturnValue
12756 @SchedulerSupport(SchedulerSupport.NONE)
12757 @NonNull
12758 public final <@NonNull U> Observable<T> skipUntil(@NonNull ObservableSource<U> other) {
12759 Objects.requireNonNull(other, "other is null");
12760 return RxJavaPlugins.onAssembly(new ObservableSkipUntil<>(this, other));
12761 }
12762
12763 /**
12764 * Returns an {@code Observable} that skips all items emitted by the current {@code Observable} as long as a specified
12765 * condition holds {@code true}, but emits all further source items as soon as the condition becomes {@code false}.
12766 * <p>
12767 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/skipWhile.v3.png" alt="">
12768 * <dl>
12769 * <dt><b>Scheduler:</b></dt>
12770 * <dd>{@code skipWhile} does not operate by default on a particular {@link Scheduler}.</dd>
12771 * </dl>
12772 *
12773 * @param predicate
12774 * a function to test each item emitted from the current {@code Observable}
12775 * @return the new {@code Observable} instance
12776 * @throws NullPointerException if {@code predicate} is {@code null}
12777 * @see <a href="http://reactivex.io/documentation/operators/skipwhile.html">ReactiveX operators documentation: SkipWhile</a>
12778 */
12779 @CheckReturnValue
12780 @SchedulerSupport(SchedulerSupport.NONE)
12781 @NonNull
12782 public final Observable<T> skipWhile(@NonNull Predicate<? super T> predicate) {
12783 Objects.requireNonNull(predicate, "predicate is null");
12784 return RxJavaPlugins.onAssembly(new ObservableSkipWhile<>(this, predicate));
12785 }
12786
12787 /**
12788 * Returns an {@code Observable} that emits the events emitted by the current {@code Observable}, in a
12789 * sorted order. Each item emitted by the current {@code Observable} must implement {@link Comparable} with respect to all
12790 * other items in the sequence.
12791 * <p>
12792 * <img width="640" height="315" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/sorted.png" alt="">
12793 * <p>
12794 * If any item emitted by the current {@code Observable} does not implement {@code Comparable} with respect to
12795 * all other items emitted by the current {@code Observable}, no items will be emitted and the
12796 * sequence is terminated with a {@link ClassCastException}.
12797 *
12798 * <p>Note that calling {@code sorted} with long, non-terminating or infinite sources
12799 * might cause {@link OutOfMemoryError}
12800 *
12801 * <dl>
12802 * <dt><b>Scheduler:</b></dt>
12803 * <dd>{@code sorted} does not operate by default on a particular {@link Scheduler}.</dd>
12804 * </dl>
12805 * @return the new {@code Observable} instance
12806 */
12807 @CheckReturnValue
12808 @SchedulerSupport(SchedulerSupport.NONE)
12809 @NonNull
12810 public final Observable<T> sorted() {
12811 return toList().toObservable().map(Functions.listSorter(Functions.naturalComparator())).flatMapIterable(Functions.identity());
12812 }
12813
12814 /**
12815 * Returns an {@code Observable} that emits the events emitted by the current {@code Observable}, in a
12816 * sorted order based on a specified comparison function.
12817 *
12818 * <p>Note that calling {@code sorted} with long, non-terminating or infinite sources
12819 * might cause {@link OutOfMemoryError}
12820 *
12821 * <dl>
12822 * <dt><b>Scheduler:</b></dt>
12823 * <dd>{@code sorted} does not operate by default on a particular {@link Scheduler}.</dd>
12824 * </dl>
12825 *
12826 * @param comparator
12827 * a function that compares two items emitted by the current {@code Observable} and returns an {@code int}
12828 * that indicates their sort order
12829 * @throws NullPointerException if {@code comparator} is {@code null}
12830 * @return the new {@code Observable} instance
12831 */
12832 @CheckReturnValue
12833 @SchedulerSupport(SchedulerSupport.NONE)
12834 @NonNull
12835 public final Observable<T> sorted(@NonNull Comparator<? super T> comparator) {
12836 Objects.requireNonNull(comparator, "comparator is null");
12837 return toList().toObservable().map(Functions.listSorter(comparator)).flatMapIterable(Functions.identity());
12838 }
12839
12840 /**
12841 * Returns an {@code Observable} that emits the items in a specified {@link Iterable} before it begins to emit items
12842 * emitted by the current {@code Observable}.
12843 * <p>
12844 * <img width="640" height="315" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/startWith.v3.png" alt="">
12845 * <dl>
12846 * <dt><b>Scheduler:</b></dt>
12847 * <dd>{@code startWithIterable} does not operate by default on a particular {@link Scheduler}.</dd>
12848 * </dl>
12849 *
12850 * @param items
12851 * an {@code Iterable} that contains the items you want the resulting {@code Observable} to emit first
12852 * @return the new {@code Observable} instance
12853 * @throws NullPointerException if {@code items} is {@code null}
12854 * @see <a href="http://reactivex.io/documentation/operators/startwith.html">ReactiveX operators documentation: StartWith</a>
12855 * @since 3.0.0
12856 * @see #startWithItem(Object)
12857 * @see #startWithArray(Object...)
12858 */
12859 @CheckReturnValue
12860 @SchedulerSupport(SchedulerSupport.NONE)
12861 @NonNull
12862 public final Observable<T> startWithIterable(@NonNull Iterable<? extends T> items) {
12863 return concatArray(fromIterable(items), this);
12864 }
12865
12866 /**
12867 * Returns an {@code Observable} which first runs the other {@link CompletableSource}
12868 * then the current {@code Observable} if the other completed normally.
12869 * <p>
12870 * <img width="640" height="268" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Observable.startWith.c.png" alt="">
12871 * <dl>
12872 * <dt><b>Scheduler:</b></dt>
12873 * <dd>{@code startWith} does not operate by default on a particular {@link Scheduler}.</dd>
12874 * </dl>
12875 * @param other the other {@code CompletableSource} to run first
12876 * @return the new {@code Observable} instance
12877 * @throws NullPointerException if {@code other} is {@code null}
12878 * @since 3.0.0
12879 */
12880 @CheckReturnValue
12881 @NonNull
12882 @SchedulerSupport(SchedulerSupport.NONE)
12883 public final Observable<T> startWith(@NonNull CompletableSource other) {
12884 Objects.requireNonNull(other, "other is null");
12885 return Observable.concat(Completable.wrap(other).<T>toObservable(), this);
12886 }
12887
12888 /**
12889 * Returns an {@code Observable} which first runs the other {@link SingleSource}
12890 * then the current {@code Observable} if the other succeeded normally.
12891 * <p>
12892 * <img width="640" height="248" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Observable.startWith.s.png" alt="">
12893 * <dl>
12894 * <dt><b>Scheduler:</b></dt>
12895 * <dd>{@code startWith} does not operate by default on a particular {@link Scheduler}.</dd>
12896 * </dl>
12897 * @param other the other {@code SingleSource} to run first
12898 * @return the new {@code Observable} instance
12899 * @throws NullPointerException if {@code other} is {@code null}
12900 * @since 3.0.0
12901 */
12902 @CheckReturnValue
12903 @NonNull
12904 @SchedulerSupport(SchedulerSupport.NONE)
12905 public final Observable<T> startWith(@NonNull SingleSource<T> other) {
12906 Objects.requireNonNull(other, "other is null");
12907 return Observable.concat(Single.wrap(other).toObservable(), this);
12908 }
12909
12910 /**
12911 * Returns an {@code Observable} which first runs the other {@link MaybeSource}
12912 * then the current {@code Observable} if the other succeeded or completed normally.
12913 * <p>
12914 * <img width="640" height="168" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Observable.startWith.m.png" alt="">
12915 * <dl>
12916 * <dt><b>Scheduler:</b></dt>
12917 * <dd>{@code startWith} does not operate by default on a particular {@link Scheduler}.</dd>
12918 * </dl>
12919 * @param other the other {@code MaybeSource} to run first
12920 * @return the new {@code Observable} instance
12921 * @throws NullPointerException if {@code other} is {@code null}
12922 * @since 3.0.0
12923 */
12924 @CheckReturnValue
12925 @NonNull
12926 @SchedulerSupport(SchedulerSupport.NONE)
12927 public final Observable<T> startWith(@NonNull MaybeSource<T> other) {
12928 Objects.requireNonNull(other, "other is null");
12929 return Observable.concat(Maybe.wrap(other).toObservable(), this);
12930 }
12931
12932 /**
12933 * Returns an {@code Observable} that emits the items in a specified {@link ObservableSource} before it begins to emit
12934 * items emitted by the current {@code Observable}.
12935 * <p>
12936 * <img width="640" height="315" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/startWith.o.v3.png" alt="">
12937 * <dl>
12938 * <dt><b>Scheduler:</b></dt>
12939 * <dd>{@code startWith} does not operate by default on a particular {@link Scheduler}.</dd>
12940 * </dl>
12941 *
12942 * @param other
12943 * an {@code ObservableSource} that contains the items you want the modified {@code ObservableSource} to emit first
12944 * @return the new {@code Observable} instance
12945 * @throws NullPointerException if {@code other} is {@code null}
12946 * @see <a href="http://reactivex.io/documentation/operators/startwith.html">ReactiveX operators documentation: StartWith</a>
12947 */
12948 @CheckReturnValue
12949 @SchedulerSupport(SchedulerSupport.NONE)
12950 @NonNull
12951 public final Observable<T> startWith(@NonNull ObservableSource<? extends T> other) {
12952 Objects.requireNonNull(other, "other is null");
12953 return concatArray(other, this);
12954 }
12955
12956 /**
12957 * Returns an {@code Observable} that emits a specified item before it begins to emit items emitted by the current
12958 * {@code Observable}.
12959 * <p>
12960 * <img width="640" height="315" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/startWith.item.png" alt="">
12961 * <dl>
12962 * <dt><b>Scheduler:</b></dt>
12963 * <dd>{@code startWithItem} does not operate by default on a particular {@link Scheduler}.</dd>
12964 * </dl>
12965 *
12966 * @param item
12967 * the item to emit first
12968 * @return the new {@code Observable} instance
12969 * @throws NullPointerException if {@code item} is {@code null}
12970 * @see <a href="http://reactivex.io/documentation/operators/startwith.html">ReactiveX operators documentation: StartWith</a>
12971 * @see #startWithArray(Object...)
12972 * @see #startWithIterable(Iterable)
12973 * @since 3.0.0
12974 */
12975 @CheckReturnValue
12976 @SchedulerSupport(SchedulerSupport.NONE)
12977 @NonNull
12978 public final Observable<T> startWithItem(@NonNull T item) {
12979 return concatArray(just(item), this);
12980 }
12981
12982 /**
12983 * Returns an {@code Observable} that emits the specified items before it begins to emit items emitted by the current
12984 * {@code Observable}.
12985 * <p>
12986 * <img width="640" height="315" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/startWithArray.v3.png" alt="">
12987 * <dl>
12988 * <dt><b>Scheduler:</b></dt>
12989 * <dd>{@code startWithArray} does not operate by default on a particular {@link Scheduler}.</dd>
12990 * </dl>
12991 *
12992 * @param items
12993 * the array of values to emit first
12994 * @return the new {@code Observable} instance
12995 * @throws NullPointerException if {@code items} is {@code null}
12996 * @see <a href="http://reactivex.io/documentation/operators/startwith.html">ReactiveX operators documentation: StartWith</a>
12997 * @see #startWithItem(Object)
12998 * @see #startWithIterable(Iterable)
12999 */
13000 @CheckReturnValue
13001 @SchedulerSupport(SchedulerSupport.NONE)
13002 @SafeVarargs
13003 @NonNull
13004 public final Observable<T> startWithArray(@NonNull T... items) {
13005 Observable<T> fromArray = fromArray(items);
13006 if (fromArray == empty()) {
13007 return RxJavaPlugins.onAssembly(this);
13008 }
13009 return concatArray(fromArray, this);
13010 }
13011
13012 /**
13013 * Subscribes to the current {@code Observable} and ignores {@code onNext} and {@code onComplete} emissions.
13014 * <p>
13015 * If the {@code Observable} emits an error, it is wrapped into an
13016 * {@link OnErrorNotImplementedException}
13017 * and routed to the {@link RxJavaPlugins#onError(Throwable)} handler.
13018 * <dl>
13019 * <dt><b>Scheduler:</b></dt>
13020 * <dd>{@code subscribe} does not operate by default on a particular {@link Scheduler}.</dd>
13021 * </dl>
13022 *
13023 * @return the new {@link Disposable} instance that can be used to dispose the subscription at any time
13024 * @see <a href="http://reactivex.io/documentation/operators/subscribe.html">ReactiveX operators documentation: Subscribe</a>
13025 * @see #subscribe(Consumer, Consumer, Action, DisposableContainer)
13026 */
13027 @SchedulerSupport(SchedulerSupport.NONE)
13028 @NonNull
13029 public final Disposable subscribe() {
13030 return subscribe(Functions.emptyConsumer(), Functions.ON_ERROR_MISSING, Functions.EMPTY_ACTION);
13031 }
13032
13033 /**
13034 * Subscribes to the current {@code Observable} and provides a callback to handle the items it emits.
13035 * <p>
13036 * If the {@code Observable} emits an error, it is wrapped into an
13037 * {@link OnErrorNotImplementedException}
13038 * and routed to the {@link RxJavaPlugins#onError(Throwable)} handler.
13039 * <dl>
13040 * <dt><b>Scheduler:</b></dt>
13041 * <dd>{@code subscribe} does not operate by default on a particular {@link Scheduler}.</dd>
13042 * </dl>
13043 *
13044 * @param onNext
13045 * the {@code Consumer<T>} you have designed to accept emissions from the current {@code Observable}
13046 * @return the new {@link Disposable} instance that can be used to dispose the subscription at any time
13047 * @throws NullPointerException
13048 * if {@code onNext} is {@code null}
13049 * @see <a href="http://reactivex.io/documentation/operators/subscribe.html">ReactiveX operators documentation: Subscribe</a>
13050 * @see #subscribe(Consumer, Consumer, Action, DisposableContainer)
13051 */
13052 @CheckReturnValue
13053 @SchedulerSupport(SchedulerSupport.NONE)
13054 @NonNull
13055 public final Disposable subscribe(@NonNull Consumer<? super T> onNext) {
13056 return subscribe(onNext, Functions.ON_ERROR_MISSING, Functions.EMPTY_ACTION);
13057 }
13058
13059 /**
13060 * Subscribes to the current {@code Observable} and provides callbacks to handle the items it emits and any error
13061 * notification it signals.
13062 * <dl>
13063 * <dt><b>Scheduler:</b></dt>
13064 * <dd>{@code subscribe} does not operate by default on a particular {@link Scheduler}.</dd>
13065 * </dl>
13066 *
13067 * @param onNext
13068 * the {@code Consumer<T>} you have designed to accept emissions from the current {@code Observable}
13069 * @param onError
13070 * the {@code Consumer<Throwable>} you have designed to accept any error notification from the current
13071 * {@code Observable}
13072 * @return the new {@link Disposable} instance that can be used to dispose the subscription at any time
13073 * @throws NullPointerException
13074 * if {@code onNext} or {@code onError} is {@code null}
13075 * @see <a href="http://reactivex.io/documentation/operators/subscribe.html">ReactiveX operators documentation: Subscribe</a>
13076 * @see #subscribe(Consumer, Consumer, Action, DisposableContainer)
13077 */
13078 @CheckReturnValue
13079 @SchedulerSupport(SchedulerSupport.NONE)
13080 @NonNull
13081 public final Disposable subscribe(@NonNull Consumer<? super T> onNext, @NonNull Consumer<? super Throwable> onError) {
13082 return subscribe(onNext, onError, Functions.EMPTY_ACTION);
13083 }
13084
13085 /**
13086 * Subscribes to the current {@code Observable} and provides callbacks to handle the items it emits and any error or
13087 * completion notification it signals.
13088 * <dl>
13089 * <dt><b>Scheduler:</b></dt>
13090 * <dd>{@code subscribe} does not operate by default on a particular {@link Scheduler}.</dd>
13091 * </dl>
13092 *
13093 * @param onNext
13094 * the {@code Consumer<T>} you have designed to accept emissions from the current {@code Observable}
13095 * @param onError
13096 * the {@code Consumer<Throwable>} you have designed to accept any error notification from the current
13097 * {@code Observable}
13098 * @param onComplete
13099 * the {@link Action} you have designed to accept a completion notification from the current
13100 * {@code Observable}
13101 * @return the new {@link Disposable} instance that can be used to dispose the subscription at any time
13102 * @throws NullPointerException
13103 * if {@code onNext}, {@code onError} or {@code onComplete} is {@code null}
13104 * @see <a href="http://reactivex.io/documentation/operators/subscribe.html">ReactiveX operators documentation: Subscribe</a>
13105 * @see #subscribe(Consumer, Consumer, Action, DisposableContainer)
13106 */
13107 @CheckReturnValue
13108 @SchedulerSupport(SchedulerSupport.NONE)
13109 @NonNull
13110 public final Disposable subscribe(@NonNull Consumer<? super T> onNext, @NonNull Consumer<? super Throwable> onError,
13111 @NonNull Action onComplete) {
13112 Objects.requireNonNull(onNext, "onNext is null");
13113 Objects.requireNonNull(onError, "onError is null");
13114 Objects.requireNonNull(onComplete, "onComplete is null");
13115
13116 LambdaObserver<T> ls = new LambdaObserver<>(onNext, onError, onComplete, Functions.emptyConsumer());
13117
13118 subscribe(ls);
13119
13120 return ls;
13121 }
13122
13123 /**
13124 * Wraps the given onXXX callbacks into a {@link Disposable} {@link Observer},
13125 * adds it to the given {@code DisposableContainer} and ensures, that if the upstream
13126 * terminates or this particular {@code Disposable} is disposed, the {@code Observer} is removed
13127 * from the given container.
13128 * <p>
13129 * The {@code Observer} will be removed after the callback for the terminal event has been invoked.
13130 * <dl>
13131 * <dt><b>Scheduler:</b></dt>
13132 * <dd>{@code subscribe} does not operate by default on a particular {@link Scheduler}.</dd>
13133 * </dl>
13134 * @param onNext the callback for upstream items
13135 * @param onError the callback for an upstream error if any
13136 * @param onComplete the callback for the upstream completion if any
13137 * @param container the {@code DisposableContainer} (such as {@link CompositeDisposable}) to add and remove the
13138 * created {@code Disposable} {@code Observer}
13139 * @return the {@code Disposable} that allows disposing the particular subscription.
13140 * @throws NullPointerException
13141 * if {@code onNext}, {@code onError},
13142 * {@code onComplete} or {@code container} is {@code null}
13143 * @since 3.1.0
13144 */
13145 @SchedulerSupport(SchedulerSupport.NONE)
13146 @NonNull
13147 public final Disposable subscribe(
13148 @NonNull Consumer<? super T> onNext,
13149 @NonNull Consumer<? super Throwable> onError,
13150 @NonNull Action onComplete,
13151 @NonNull DisposableContainer container) {
13152 Objects.requireNonNull(onNext, "onNext is null");
13153 Objects.requireNonNull(onError, "onError is null");
13154 Objects.requireNonNull(onComplete, "onComplete is null");
13155 Objects.requireNonNull(container, "container is null");
13156
13157 DisposableAutoReleaseObserver<T> observer = new DisposableAutoReleaseObserver<>(
13158 container, onNext, onError, onComplete);
13159 container.add(observer);
13160 subscribe(observer);
13161 return observer;
13162 }
13163
13164 @SchedulerSupport(SchedulerSupport.NONE)
13165 @Override
13166 public final void subscribe(@NonNull Observer<? super T> observer) {
13167 Objects.requireNonNull(observer, "observer is null");
13168 try {
13169 observer = RxJavaPlugins.onSubscribe(this, observer);
13170
13171 Objects.requireNonNull(observer, "The RxJavaPlugins.onSubscribe hook returned a null Observer. Please change the handler provided to RxJavaPlugins.setOnObservableSubscribe for invalid null returns. Further reading: https://github.com/ReactiveX/RxJava/wiki/Plugins");
13172
13173 subscribeActual(observer);
13174 } catch (NullPointerException e) { // NOPMD
13175 throw e;
13176 } catch (Throwable e) {
13177 Exceptions.throwIfFatal(e);
13178 // can't call onError because no way to know if a Disposable has been set or not
13179 // can't call onSubscribe because the call might have set a Subscription already
13180 RxJavaPlugins.onError(e);
13181
13182 NullPointerException npe = new NullPointerException("Actually not, but can't throw other exceptions due to RS");
13183 npe.initCause(e);
13184 throw npe;
13185 }
13186 }
13187
13188 /**
13189 * Operator implementations (both source and intermediate) should implement this method that
13190 * performs the necessary business logic and handles the incoming {@link Observer}s.
13191 * <p>There is no need to call any of the plugin hooks on the current {@code Observable} instance or
13192 * the {@code Observer}; all hooks and basic safeguards have been
13193 * applied by {@link #subscribe(Observer)} before this method gets called.
13194 * @param observer the incoming {@code Observer}, never {@code null}
13195 */
13196 protected abstract void subscribeActual(@NonNull Observer<? super T> observer);
13197
13198 /**
13199 * Subscribes a given {@link Observer} (subclass) to the current {@code Observable} and returns the given
13200 * {@code Observer} instance as is.
13201 * <p>Usage example:
13202 * <pre><code>
13203 * Observable&lt;Integer&gt; source = Observable.range(1, 10);
13204 * CompositeDisposable composite = new CompositeDisposable();
13205 *
13206 * DisposableObserver&lt;Integer&gt; ds = new DisposableObserver&lt;&gt;() {
13207 * // ...
13208 * };
13209 *
13210 * composite.add(source.subscribeWith(ds));
13211 * </code></pre>
13212 * <dl>
13213 * <dt><b>Scheduler:</b></dt>
13214 * <dd>{@code subscribeWith} does not operate by default on a particular {@link Scheduler}.</dd>
13215 * </dl>
13216 * @param <E> the type of the {@code Observer} to use and return
13217 * @param observer the {@code Observer} (subclass) to use and return, not {@code null}
13218 * @return the input {@code observer}
13219 * @throws NullPointerException if {@code observer} is {@code null}
13220 * @since 2.0
13221 */
13222 @CheckReturnValue
13223 @SchedulerSupport(SchedulerSupport.NONE)
13224 @NonNull
13225 public final <@NonNull E extends Observer<? super T>> E subscribeWith(E observer) {
13226 subscribe(observer);
13227 return observer;
13228 }
13229
13230 /**
13231 * Asynchronously subscribes {@link Observer}s to the current {@code Observable} on the specified {@link Scheduler}.
13232 * <p>
13233 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/subscribeOn.v3.png" alt="">
13234 * <dl>
13235 * <dt><b>Scheduler:</b></dt>
13236 * <dd>You specify which {@code Scheduler} this operator will use.</dd>
13237 * </dl>
13238 *
13239 * @param scheduler
13240 * the {@code Scheduler} to perform subscription actions on
13241 * @return the new {@code Observable} instance
13242 * @throws NullPointerException if {@code scheduler} is {@code null}
13243 * @see <a href="http://reactivex.io/documentation/operators/subscribeon.html">ReactiveX operators documentation: SubscribeOn</a>
13244 * @see <a href="http://www.grahamlea.com/2014/07/rxjava-threading-examples/">RxJava Threading Examples</a>
13245 * @see #observeOn
13246 */
13247 @CheckReturnValue
13248 @SchedulerSupport(SchedulerSupport.CUSTOM)
13249 @NonNull
13250 public final Observable<T> subscribeOn(@NonNull Scheduler scheduler) {
13251 Objects.requireNonNull(scheduler, "scheduler is null");
13252 return RxJavaPlugins.onAssembly(new ObservableSubscribeOn<>(this, scheduler));
13253 }
13254
13255 /**
13256 * Returns an {@code Observable} that emits the items emitted by the current {@code Observable} or the items of an alternate
13257 * {@link ObservableSource} if the current {@code Observable} is empty.
13258 * <p>
13259 * <img width="640" height="256" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/switchifempty.png" alt="">
13260 * <dl>
13261 * <dt><b>Scheduler:</b></dt>
13262 * <dd>{@code switchIfEmpty} does not operate by default on a particular {@link Scheduler}.</dd>
13263 * </dl>
13264 *
13265 * @param other
13266 * the alternate {@code ObservableSource} to subscribe to if the source does not emit any items
13267 * @return the new {@code Observable} instance
13268 * @throws NullPointerException if {@code other} is {@code null}
13269 * @since 1.1.0
13270 */
13271 @CheckReturnValue
13272 @SchedulerSupport(SchedulerSupport.NONE)
13273 @NonNull
13274 public final Observable<T> switchIfEmpty(@NonNull ObservableSource<? extends T> other) {
13275 Objects.requireNonNull(other, "other is null");
13276 return RxJavaPlugins.onAssembly(new ObservableSwitchIfEmpty<>(this, other));
13277 }
13278
13279 /**
13280 * Returns a new {@code Observable} by applying a function that you supply to each item emitted by the current
13281 * {@code Observable} that returns an {@link ObservableSource}, and then emitting the items emitted by the most recently emitted
13282 * of these {@code ObservableSource}s.
13283 * <p>
13284 * The resulting {@code Observable} completes if both the current {@code Observable} and the last inner {@code ObservableSource}, if any, complete.
13285 * If the current {@code Observable} signals an {@code onError}, the inner {@code ObservableSource} is disposed and the error delivered in-sequence.
13286 * <p>
13287 * <img width="640" height="350" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/switchMap.v3.png" alt="">
13288 * <dl>
13289 * <dt><b>Scheduler:</b></dt>
13290 * <dd>{@code switchMap} does not operate by default on a particular {@link Scheduler}.</dd>
13291 * </dl>
13292 *
13293 * @param <R> the element type of the inner {@code ObservableSource}s and the output
13294 * @param mapper
13295 * a function that, when applied to an item emitted by the current {@code Observable}, returns an
13296 * {@code ObservableSource}
13297 * @return the new {@code Observable} instance
13298 * @throws NullPointerException if {@code mapper} is {@code null}
13299 * @see <a href="http://reactivex.io/documentation/operators/flatmap.html">ReactiveX operators documentation: FlatMap</a>
13300 * @see #switchMapDelayError(Function)
13301 */
13302 @CheckReturnValue
13303 @SchedulerSupport(SchedulerSupport.NONE)
13304 @NonNull
13305 public final <@NonNull R> Observable<R> switchMap(@NonNull Function<? super T, ? extends ObservableSource<? extends R>> mapper) {
13306 return switchMap(mapper, bufferSize());
13307 }
13308
13309 /**
13310 * Returns a new {@code Observable} by applying a function that you supply to each item emitted by the current
13311 * {@code Observable} that returns an {@link ObservableSource}, and then emitting the items emitted by the most recently emitted
13312 * of these {@code ObservableSource}s.
13313 * <p>
13314 * The resulting {@code Observable} completes if both the current {@code Observable} and the last inner {@code ObservableSource}, if any, complete.
13315 * If the current {@code Observable} signals an {@code onError}, the inner {@code ObservableSource} is disposed and the error delivered in-sequence.
13316 * <p>
13317 * <img width="640" height="350" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/switchMap.v3.png" alt="">
13318 * <dl>
13319 * <dt><b>Scheduler:</b></dt>
13320 * <dd>{@code switchMap} does not operate by default on a particular {@link Scheduler}.</dd>
13321 * </dl>
13322 *
13323 * @param <R> the element type of the inner {@code ObservableSource}s and the output
13324 * @param mapper
13325 * a function that, when applied to an item emitted by the current {@code Observable}, returns an
13326 * {@code ObservableSource}
13327 * @param bufferSize
13328 * the number of elements expected from the current active inner {@code ObservableSource} to be buffered
13329 * @return the new {@code Observable} instance
13330 * @throws NullPointerException if {@code mapper} is {@code null}
13331 * @throws IllegalArgumentException if {@code bufferSize} is non-positive
13332 * @see <a href="http://reactivex.io/documentation/operators/flatmap.html">ReactiveX operators documentation: FlatMap</a>
13333 * @see #switchMapDelayError(Function, int)
13334 */
13335 @CheckReturnValue
13336 @SchedulerSupport(SchedulerSupport.NONE)
13337 @NonNull
13338 public final <@NonNull R> Observable<R> switchMap(@NonNull Function<? super T, ? extends ObservableSource<? extends R>> mapper, int bufferSize) {
13339 Objects.requireNonNull(mapper, "mapper is null");
13340 ObjectHelper.verifyPositive(bufferSize, "bufferSize");
13341 if (this instanceof ScalarSupplier) {
13342 @SuppressWarnings("unchecked")
13343 T v = ((ScalarSupplier<T>)this).get();
13344 if (v == null) {
13345 return empty();
13346 }
13347 return ObservableScalarXMap.scalarXMap(v, mapper);
13348 }
13349 return RxJavaPlugins.onAssembly(new ObservableSwitchMap<>(this, mapper, bufferSize, false));
13350 }
13351
13352 /**
13353 * Maps the items of the current {@code Observable} into {@link CompletableSource}s, subscribes to the newer one while
13354 * disposing the subscription to the previous {@code CompletableSource}, thus keeping at most one
13355 * active {@code CompletableSource} running.
13356 * <p>
13357 * <img width="640" height="522" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/switchMapCompletable.f.png" alt="">
13358 * <p>
13359 * Since a {@code CompletableSource} doesn't produce any items, the resulting reactive type of
13360 * this operator is a {@link Completable} that can only indicate successful completion or
13361 * a failure in any of the inner {@code CompletableSource}s or the failure of the current
13362 * {@code Observable}.
13363 * <dl>
13364 * <dt><b>Scheduler:</b></dt>
13365 * <dd>{@code switchMapCompletable} does not operate by default on a particular {@link Scheduler}.</dd>
13366 * <dt><b>Error handling:</b></dt>
13367 * <dd>If either the current {@code Observable} or the active {@code CompletableSource} signals an {@code onError},
13368 * the resulting {@code Completable} is terminated immediately with that {@link Throwable}.
13369 * Use the {@link #switchMapCompletableDelayError(Function)} to delay such inner failures until
13370 * every inner {@code CompletableSource}s and the main {@code Observable} terminates in some fashion.
13371 * If they fail concurrently, the operator may combine the {@code Throwable}s into a
13372 * {@link CompositeException}
13373 * and signal it to the downstream instead. If any inactivated (switched out) {@code CompletableSource}
13374 * signals an {@code onError} late, the {@code Throwable}s will be signaled to the global error handler via
13375 * {@link RxJavaPlugins#onError(Throwable)} method as {@link UndeliverableException} errors.
13376 * </dd>
13377 * </dl>
13378 * <p>History: 2.1.11 - experimental
13379 * @param mapper the function called with each upstream item and should return a
13380 * {@code CompletableSource} to be subscribed to and awaited for
13381 * (non blockingly) for its terminal event
13382 * @return the new {@code Completable} instance
13383 * @throws NullPointerException if {@code mapper} is {@code null}
13384 * @see #switchMapCompletableDelayError(Function)
13385 * @since 2.2
13386 */
13387 @CheckReturnValue
13388 @SchedulerSupport(SchedulerSupport.NONE)
13389 @NonNull
13390 public final Completable switchMapCompletable(@NonNull Function<? super T, ? extends CompletableSource> mapper) {
13391 Objects.requireNonNull(mapper, "mapper is null");
13392 return RxJavaPlugins.onAssembly(new ObservableSwitchMapCompletable<>(this, mapper, false));
13393 }
13394
13395 /**
13396 * Maps the upstream values into {@link CompletableSource}s, subscribes to the newer one while
13397 * disposing the subscription to the previous {@code CompletableSource}, thus keeping at most one
13398 * active {@code CompletableSource} running and delaying any main or inner errors until all
13399 * of them terminate.
13400 * <p>
13401 * <img width="640" height="453" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/switchMapCompletableDelayError.f.png" alt="">
13402 * <p>
13403 * Since a {@code CompletableSource} doesn't produce any items, the resulting reactive type of
13404 * this operator is a {@link Completable} that can only indicate successful completion or
13405 * a failure in any of the inner {@code CompletableSource}s or the failure of the current
13406 * {@code Observable}.
13407 * <dl>
13408 * <dt><b>Scheduler:</b></dt>
13409 * <dd>{@code switchMapCompletableDelayError} does not operate by default on a particular {@link Scheduler}.</dd>
13410 * <dt><b>Error handling:</b></dt>
13411 * <dd>The errors of the current {@code Observable} and all the {@code CompletableSource}s, who had the chance
13412 * to run to their completion, are delayed until
13413 * all of them terminate in some fashion. At this point, if there was only one failure, the respective
13414 * {@link Throwable} is emitted to the downstream. It there were more than one failures, the
13415 * operator combines all {@code Throwable}s into a {@link CompositeException}
13416 * and signals that to the downstream.
13417 * If any inactivated (switched out) {@code CompletableSource}
13418 * signals an {@code onError} late, the {@code Throwable}s will be signaled to the global error handler via
13419 * {@link RxJavaPlugins#onError(Throwable)} method as {@link UndeliverableException} errors.
13420 * </dd>
13421 * </dl>
13422 * <p>History: 2.1.11 - experimental
13423 * @param mapper the function called with each upstream item and should return a
13424 * {@code CompletableSource} to be subscribed to and awaited for
13425 * (non blockingly) for its terminal event
13426 * @return the new {@code Completable} instance
13427 * @throws NullPointerException if {@code mapper} is {@code null}
13428 * @see #switchMapCompletable(Function)
13429 * @since 2.2
13430 */
13431 @CheckReturnValue
13432 @SchedulerSupport(SchedulerSupport.NONE)
13433 @NonNull
13434 public final Completable switchMapCompletableDelayError(@NonNull Function<? super T, ? extends CompletableSource> mapper) {
13435 Objects.requireNonNull(mapper, "mapper is null");
13436 return RxJavaPlugins.onAssembly(new ObservableSwitchMapCompletable<>(this, mapper, true));
13437 }
13438
13439 /**
13440 * Maps the items of the current {@code Observable} into {@link MaybeSource}s and switches (subscribes) to the newer ones
13441 * while disposing the older ones (and ignoring their signals) and emits the latest success value of the current one if
13442 * available while failing immediately if the current {@code Observable} or any of the
13443 * active inner {@code MaybeSource}s fail.
13444 * <p>
13445 * <img width="640" height="531" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/switchMapMaybe.o.png" alt="">
13446 * <dl>
13447 * <dt><b>Scheduler:</b></dt>
13448 * <dd>{@code switchMapMaybe} does not operate by default on a particular {@link Scheduler}.</dd>
13449 * <dt><b>Error handling:</b></dt>
13450 * <dd>This operator terminates with an {@code onError} if the current {@code Observable} or any of
13451 * the inner {@code MaybeSource}s fail while they are active. When this happens concurrently, their
13452 * individual {@link Throwable} errors may get combined and emitted as a single
13453 * {@link CompositeException}. Otherwise, a late
13454 * (i.e., inactive or switched out) {@code onError} from the current {@code Observable} or from any of
13455 * the inner {@code MaybeSource}s will be forwarded to the global error handler via
13456 * {@link RxJavaPlugins#onError(Throwable)} as
13457 * {@link UndeliverableException}</dd>
13458 * </dl>
13459 * <p>History: 2.1.11 - experimental
13460 * @param <R> the output value type
13461 * @param mapper the function called with the current upstream event and should
13462 * return a {@code MaybeSource} to replace the current active inner source
13463 * and get subscribed to.
13464 * @return the new {@code Observable} instance
13465 * @throws NullPointerException if {@code mapper} is {@code null}
13466 * @see #switchMapMaybeDelayError(Function)
13467 * @since 2.2
13468 */
13469 @CheckReturnValue
13470 @SchedulerSupport(SchedulerSupport.NONE)
13471 @NonNull
13472 public final <@NonNull R> Observable<R> switchMapMaybe(@NonNull Function<? super T, ? extends MaybeSource<? extends R>> mapper) {
13473 Objects.requireNonNull(mapper, "mapper is null");
13474 return RxJavaPlugins.onAssembly(new ObservableSwitchMapMaybe<>(this, mapper, false));
13475 }
13476
13477 /**
13478 * Maps the upstream items into {@link MaybeSource}s and switches (subscribes) to the newer ones
13479 * while disposing the older ones (and ignoring their signals) and emits the latest success value of the current one if
13480 * available, delaying errors from the current {@code Observable} or the inner {@code MaybeSource}s until all terminate.
13481 * <p>
13482 * <img width="640" height="469" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/switchMapMaybeDelayError.o.png" alt="">
13483 * <dl>
13484 * <dt><b>Scheduler:</b></dt>
13485 * <dd>{@code switchMapMaybeDelayError} does not operate by default on a particular {@link Scheduler}.</dd>
13486 * </dl>
13487 * <p>History: 2.1.11 - experimental
13488 * @param <R> the output value type
13489 * @param mapper the function called with the current upstream event and should
13490 * return a {@code MaybeSource} to replace the current active inner source
13491 * and get subscribed to.
13492 * @return the new {@code Observable} instance
13493 * @throws NullPointerException if {@code mapper} is {@code null}
13494 * @see #switchMapMaybe(Function)
13495 * @since 2.2
13496 */
13497 @CheckReturnValue
13498 @SchedulerSupport(SchedulerSupport.NONE)
13499 @NonNull
13500 public final <@NonNull R> Observable<R> switchMapMaybeDelayError(@NonNull Function<? super T, ? extends MaybeSource<? extends R>> mapper) {
13501 Objects.requireNonNull(mapper, "mapper is null");
13502 return RxJavaPlugins.onAssembly(new ObservableSwitchMapMaybe<>(this, mapper, true));
13503 }
13504
13505 /**
13506 * Returns a new {@code Observable} by applying a function that you supply to each item emitted by the current
13507 * {@code Observable} that returns a {@link SingleSource}, and then emitting the item emitted by the most recently emitted
13508 * of these {@code SingleSource}s.
13509 * <p>
13510 * The resulting {@code Observable} completes if both the current {@code Observable} and the last inner {@code SingleSource}, if any, complete.
13511 * If the current {@code Observable} signals an {@code onError}, the inner {@code SingleSource} is disposed and the error delivered in-sequence.
13512 * <p>
13513 * <img width="640" height="532" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/switchMapSingle.o.png" alt="">
13514 * <dl>
13515 * <dt><b>Scheduler:</b></dt>
13516 * <dd>{@code switchMapSingle} does not operate by default on a particular {@link Scheduler}.</dd>
13517 * </dl>
13518 * <p>History: 2.0.8 - experimental
13519 * @param <R> the element type of the inner {@code SingleSource}s and the output
13520 * @param mapper
13521 * a function that, when applied to an item emitted by the current {@code Observable}, returns a
13522 * {@code SingleSource}
13523 * @return the new {@code Observable} instance
13524 * @throws NullPointerException if {@code mapper} is {@code null}
13525 * @see <a href="http://reactivex.io/documentation/operators/flatmap.html">ReactiveX operators documentation: FlatMap</a>
13526 * @see #switchMapSingleDelayError(Function)
13527 * @since 2.2
13528 */
13529 @CheckReturnValue
13530 @SchedulerSupport(SchedulerSupport.NONE)
13531 @NonNull
13532 public final <@NonNull R> Observable<R> switchMapSingle(@NonNull Function<? super T, ? extends SingleSource<? extends R>> mapper) {
13533 Objects.requireNonNull(mapper, "mapper is null");
13534 return RxJavaPlugins.onAssembly(new ObservableSwitchMapSingle<>(this, mapper, false));
13535 }
13536
13537 /**
13538 * Returns a new {@code Observable} by applying a function that you supply to each item emitted by the current
13539 * {@code Observable} that returns a {@link SingleSource}, and then emitting the item emitted by the most recently emitted
13540 * of these {@code SingleSource}s and delays any error until all {@code SingleSource}s terminate.
13541 * <p>
13542 * The resulting {@code Observable} completes if both the current {@code Observable} and the last inner {@code SingleSource}, if any, complete.
13543 * If the current {@code Observable} signals an {@code onError}, the termination of the last inner {@code SingleSource} will emit that error as is
13544 * or wrapped into a {@link CompositeException} along with the other possible errors the former inner {@code SingleSource}s signaled.
13545 * <p>
13546 * <img width="640" height="467" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/switchMapSingleDelayError.o.png" alt="">
13547 * <dl>
13548 * <dt><b>Scheduler:</b></dt>
13549 * <dd>{@code switchMapSingleDelayError} does not operate by default on a particular {@link Scheduler}.</dd>
13550 * </dl>
13551 * <p>History: 2.0.8 - experimental
13552 * @param <R> the element type of the inner {@code SingleSource}s and the output
13553 * @param mapper
13554 * a function that, when applied to an item emitted by the current {@code Observable}, returns a
13555 * {@code SingleSource}
13556 * @return the new {@code Observable} instance
13557 * @throws NullPointerException if {@code mapper} is {@code null}
13558 * @see <a href="http://reactivex.io/documentation/operators/flatmap.html">ReactiveX operators documentation: FlatMap</a>
13559 * @see #switchMapSingle(Function)
13560 * @since 2.2
13561 */
13562 @CheckReturnValue
13563 @SchedulerSupport(SchedulerSupport.NONE)
13564 @NonNull
13565 public final <@NonNull R> Observable<R> switchMapSingleDelayError(@NonNull Function<? super T, ? extends SingleSource<? extends R>> mapper) {
13566 Objects.requireNonNull(mapper, "mapper is null");
13567 return RxJavaPlugins.onAssembly(new ObservableSwitchMapSingle<>(this, mapper, true));
13568 }
13569
13570 /**
13571 * Returns a new {@code Observable} by applying a function that you supply to each item emitted by the current
13572 * {@code Observable} that returns an {@link ObservableSource}, and then emitting the items emitted by the most recently emitted
13573 * of these {@code ObservableSource}s and delays any error until all {@code ObservableSource}s terminate.
13574 * <p>
13575 * The resulting {@code Observable} completes if both the current {@code Observable} and the last inner {@code ObservableSource}, if any, complete.
13576 * If the current {@code Observable} signals an {@code onError}, the termination of the last inner {@code ObservableSource} will emit that error as is
13577 * or wrapped into a {@link CompositeException} along with the other possible errors the former inner {@code ObservableSource}s signaled.
13578 * <p>
13579 * <img width="640" height="350" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/switchMap.v3.png" alt="">
13580 * <dl>
13581 * <dt><b>Scheduler:</b></dt>
13582 * <dd>{@code switchMapDelayError} does not operate by default on a particular {@link Scheduler}.</dd>
13583 * </dl>
13584 *
13585 * @param <R> the element type of the inner {@code ObservableSource}s and the output
13586 * @param mapper
13587 * a function that, when applied to an item emitted by the current {@code Observable}, returns an
13588 * {@code ObservableSource}
13589 * @return the new {@code Observable} instance
13590 * @throws NullPointerException if {@code mapper} is {@code null}
13591 * @see <a href="http://reactivex.io/documentation/operators/flatmap.html">ReactiveX operators documentation: FlatMap</a>
13592 * @see #switchMap(Function)
13593 * @since 2.0
13594 */
13595 @CheckReturnValue
13596 @SchedulerSupport(SchedulerSupport.NONE)
13597 @NonNull
13598 public final <@NonNull R> Observable<R> switchMapDelayError(@NonNull Function<? super T, ? extends ObservableSource<? extends R>> mapper) {
13599 return switchMapDelayError(mapper, bufferSize());
13600 }
13601
13602 /**
13603 * Returns a new {@code Observable} by applying a function that you supply to each item emitted by the current
13604 * {@code Observable} that returns an {@link ObservableSource}, and then emitting the items emitted by the most recently emitted
13605 * of these {@code ObservableSource}s and delays any error until all {@code ObservableSource}s terminate.
13606 * <p>
13607 * The resulting {@code Observable} completes if both the current {@code Observable} and the last inner {@code ObservableSource}, if any, complete.
13608 * If the current {@code Observable} signals an {@code onError}, the termination of the last inner {@code ObservableSource} will emit that error as is
13609 * or wrapped into a {@link CompositeException} along with the other possible errors the former inner {@code ObservableSource}s signaled.
13610 * <p>
13611 * <img width="640" height="350" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/switchMap.v3.png" alt="">
13612 * <dl>
13613 * <dt><b>Scheduler:</b></dt>
13614 * <dd>{@code switchMapDelayError} does not operate by default on a particular {@link Scheduler}.</dd>
13615 * </dl>
13616 *
13617 * @param <R> the element type of the inner {@code ObservableSource}s and the output
13618 * @param mapper
13619 * a function that, when applied to an item emitted by the current {@code Observable}, returns an
13620 * {@code ObservableSource}
13621 * @param bufferSize
13622 * the number of elements expected from the current active inner {@code ObservableSource} to be buffered
13623 * @return the new {@code Observable} instance
13624 * @throws NullPointerException if {@code mapper} is {@code null}
13625 * @throws IllegalArgumentException if {@code bufferSize} is non-positive
13626 * @see <a href="http://reactivex.io/documentation/operators/flatmap.html">ReactiveX operators documentation: FlatMap</a>
13627 * @see #switchMap(Function, int)
13628 * @since 2.0
13629 */
13630 @CheckReturnValue
13631 @SchedulerSupport(SchedulerSupport.NONE)
13632 @NonNull
13633 public final <@NonNull R> Observable<R> switchMapDelayError(@NonNull Function<? super T, ? extends ObservableSource<? extends R>> mapper, int bufferSize) {
13634 Objects.requireNonNull(mapper, "mapper is null");
13635 ObjectHelper.verifyPositive(bufferSize, "bufferSize");
13636 if (this instanceof ScalarSupplier) {
13637 @SuppressWarnings("unchecked")
13638 T v = ((ScalarSupplier<T>)this).get();
13639 if (v == null) {
13640 return empty();
13641 }
13642 return ObservableScalarXMap.scalarXMap(v, mapper);
13643 }
13644 return RxJavaPlugins.onAssembly(new ObservableSwitchMap<>(this, mapper, bufferSize, true));
13645 }
13646
13647 /**
13648 * Returns an {@code Observable} that emits only the first {@code count} items emitted by the current {@code Observable}.
13649 * If the source emits fewer than {@code count} items then all of its items are emitted.
13650 * <p>
13651 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/take.v3.png" alt="">
13652 * <p>
13653 * This method returns an {@code Observable} that will invoke a subscribing {@link Observer}'s
13654 * {@link Observer#onNext onNext} function a maximum of {@code count} times before invoking
13655 * {@link Observer#onComplete onComplete}.
13656 * <p>
13657 * Taking {@code 0} items from the current {@code Observable} will still subscribe to it, allowing the
13658 * subscription-time side-effects to happen there, but will be immediately disposed and the downstream completed
13659 * without any item emission.
13660 * <dl>
13661 * <dt><b>Scheduler:</b></dt>
13662 * <dd>This version of {@code take} does not operate by default on a particular {@link Scheduler}.</dd>
13663 * </dl>
13664 *
13665 * @param count
13666 * the maximum number of items to emit
13667 * @return the new {@code Observable} instance
13668 * @throws IllegalArgumentException if {@code count} is negative
13669 * @see <a href="http://reactivex.io/documentation/operators/take.html">ReactiveX operators documentation: Take</a>
13670 */
13671 @CheckReturnValue
13672 @SchedulerSupport(SchedulerSupport.NONE)
13673 @NonNull
13674 public final Observable<T> take(long count) {
13675 if (count < 0) {
13676 throw new IllegalArgumentException("count >= 0 required but it was " + count);
13677 }
13678 return RxJavaPlugins.onAssembly(new ObservableTake<>(this, count));
13679 }
13680
13681 /**
13682 * Returns an {@code Observable} that emits those items emitted by the current {@code Observable} before a specified time runs
13683 * out.
13684 * <p>
13685 * If time runs out before the {@code Observable} completes normally, the {@code onComplete} event will be
13686 * signaled on the default {@code computation} {@link Scheduler}.
13687 * <p>
13688 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/take.t.v3.png" alt="">
13689 * <dl>
13690 * <dt><b>Scheduler:</b></dt>
13691 * <dd>This version of {@code take} operates by default on the {@code computation} {@code Scheduler}.</dd>
13692 * </dl>
13693 *
13694 * @param time
13695 * the length of the time window
13696 * @param unit
13697 * the time unit of {@code time}
13698 * @return the new {@code Observable} instance
13699 * @throws NullPointerException if {@code unit} is {@code null}
13700 * @see <a href="http://reactivex.io/documentation/operators/take.html">ReactiveX operators documentation: Take</a>
13701 */
13702 @CheckReturnValue
13703 @SchedulerSupport(SchedulerSupport.NONE)
13704 @NonNull
13705 public final Observable<T> take(long time, @NonNull TimeUnit unit) {
13706 return takeUntil(timer(time, unit));
13707 }
13708
13709 /**
13710 * Returns an {@code Observable} that emits those items emitted by the current {@code Observable} before a specified time (on a
13711 * specified {@link Scheduler}) runs out.
13712 * <p>
13713 * If time runs out before the {@code Observable} completes normally, the {@code onComplete} event will be
13714 * signaled on the provided {@code Scheduler}.
13715 * <p>
13716 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/take.ts.v3.png" alt="">
13717 * <dl>
13718 * <dt><b>Scheduler:</b></dt>
13719 * <dd>You specify which {@code Scheduler} this operator will use.</dd>
13720 * </dl>
13721 *
13722 * @param time
13723 * the length of the time window
13724 * @param unit
13725 * the time unit of {@code time}
13726 * @param scheduler
13727 * the {@code Scheduler} used for time source
13728 * @return the new {@code Observable} instance
13729 * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null}
13730 * @see <a href="http://reactivex.io/documentation/operators/take.html">ReactiveX operators documentation: Take</a>
13731 */
13732 @CheckReturnValue
13733 @SchedulerSupport(SchedulerSupport.CUSTOM)
13734 @NonNull
13735 public final Observable<T> take(long time, @NonNull TimeUnit unit, @NonNull Scheduler scheduler) {
13736 return takeUntil(timer(time, unit, scheduler));
13737 }
13738
13739 /**
13740 * Returns an {@code Observable} that emits at most the last {@code count} items emitted by the current {@code Observable}.
13741 * If the source emits fewer than {@code count} items then all of its items are emitted.
13742 * <p>
13743 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/takeLast.n.v3.png" alt="">
13744 * <dl>
13745 * <dt><b>Scheduler:</b></dt>
13746 * <dd>This version of {@code takeLast} does not operate by default on a particular {@link Scheduler}.</dd>
13747 * </dl>
13748 *
13749 * @param count
13750 * the maximum number of items to emit from the end of the sequence of items emitted by the current
13751 * {@code Observable}
13752 * @return the new {@code Observable} instance
13753 * @throws IllegalArgumentException
13754 * if {@code count} is negative
13755 * @see <a href="http://reactivex.io/documentation/operators/takelast.html">ReactiveX operators documentation: TakeLast</a>
13756 */
13757 @CheckReturnValue
13758 @SchedulerSupport(SchedulerSupport.NONE)
13759 @NonNull
13760 public final Observable<T> takeLast(int count) {
13761 if (count < 0) {
13762 throw new IllegalArgumentException("count >= 0 required but it was " + count);
13763 }
13764 if (count == 0) {
13765 return RxJavaPlugins.onAssembly(new ObservableIgnoreElements<>(this));
13766 }
13767 if (count == 1) {
13768 return RxJavaPlugins.onAssembly(new ObservableTakeLastOne<>(this));
13769 }
13770 return RxJavaPlugins.onAssembly(new ObservableTakeLast<>(this, count));
13771 }
13772
13773 /**
13774 * Returns an {@code Observable} that emits at most a specified number of items from the current {@code Observable} that were
13775 * emitted in a specified window of time before the current {@code Observable} completed.
13776 * <p>
13777 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/takeLast.tn.v3.png" alt="">
13778 * <dl>
13779 * <dt><b>Scheduler:</b></dt>
13780 * <dd>{@code takeLast} does not operate on any particular scheduler but uses the current time
13781 * from the {@code trampoline} {@link Scheduler}.</dd>
13782 * </dl>
13783 *
13784 * @param count
13785 * the maximum number of items to emit
13786 * @param time
13787 * the length of the time window
13788 * @param unit
13789 * the time unit of {@code time}
13790 * @return the new {@code Observable} instance
13791 * @throws NullPointerException if {@code unit} is {@code null}
13792 * @throws IllegalArgumentException if {@code count} is negative
13793 * @see <a href="http://reactivex.io/documentation/operators/takelast.html">ReactiveX operators documentation: TakeLast</a>
13794 */
13795 @CheckReturnValue
13796 @SchedulerSupport(SchedulerSupport.TRAMPOLINE)
13797 @NonNull
13798 public final Observable<T> takeLast(long count, long time, @NonNull TimeUnit unit) {
13799 return takeLast(count, time, unit, Schedulers.trampoline(), false, bufferSize());
13800 }
13801
13802 /**
13803 * Returns an {@code Observable} that emits at most a specified number of items from the current {@code Observable} that were
13804 * emitted in a specified window of time before the current {@code Observable} completed, where the timing information is
13805 * provided by a given {@link Scheduler}.
13806 * <p>
13807 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/takeLast.tns.v3.png" alt="">
13808 * <dl>
13809 * <dt><b>Scheduler:</b></dt>
13810 * <dd>You specify which {@code Scheduler} this operator will use for tracking the current time</dd>
13811 * </dl>
13812 *
13813 * @param count
13814 * the maximum number of items to emit
13815 * @param time
13816 * the length of the time window
13817 * @param unit
13818 * the time unit of {@code time}
13819 * @param scheduler
13820 * the {@code Scheduler} that provides the timestamps for the observed items
13821 * @return the new {@code Observable} instance
13822 * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null}
13823 * @throws IllegalArgumentException
13824 * if {@code count} is negative
13825 * @see <a href="http://reactivex.io/documentation/operators/takelast.html">ReactiveX operators documentation: TakeLast</a>
13826 */
13827 @CheckReturnValue
13828 @SchedulerSupport(SchedulerSupport.CUSTOM)
13829 @NonNull
13830 public final Observable<T> takeLast(long count, long time, @NonNull TimeUnit unit, @NonNull Scheduler scheduler) {
13831 return takeLast(count, time, unit, scheduler, false, bufferSize());
13832 }
13833
13834 /**
13835 * Returns an {@code Observable} that emits at most a specified number of items from the current {@code Observable} that were
13836 * emitted in a specified window of time before the current {@code Observable} completed, where the timing information is
13837 * provided by a given {@link Scheduler}.
13838 * <p>
13839 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/takeLast.tns.v3.png" alt="">
13840 * <dl>
13841 * <dt><b>Scheduler:</b></dt>
13842 * <dd>You specify which {@code Scheduler} this operator will use for tracking the current time</dd>
13843 * </dl>
13844 *
13845 * @param count
13846 * the maximum number of items to emit
13847 * @param time
13848 * the length of the time window
13849 * @param unit
13850 * the time unit of {@code time}
13851 * @param scheduler
13852 * the {@code Scheduler} that provides the timestamps for the observed items
13853 * @param delayError
13854 * if {@code true}, an exception signaled by the current {@code Observable} is delayed until the regular elements are consumed
13855 * by the downstream; if {@code false}, an exception is immediately signaled and all regular elements dropped
13856 * @param bufferSize
13857 * the hint about how many elements to expect to be last
13858 * @return the new {@code Observable} instance
13859 * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null}
13860 * @throws IllegalArgumentException
13861 * if {@code count} is negative or {@code bufferSize} is non-positive
13862 * @see <a href="http://reactivex.io/documentation/operators/takelast.html">ReactiveX operators documentation: TakeLast</a>
13863 */
13864 @CheckReturnValue
13865 @SchedulerSupport(SchedulerSupport.CUSTOM)
13866 @NonNull
13867 public final Observable<T> takeLast(long count, long time, @NonNull TimeUnit unit, @NonNull Scheduler scheduler, boolean delayError, int bufferSize) {
13868 Objects.requireNonNull(unit, "unit is null");
13869 Objects.requireNonNull(scheduler, "scheduler is null");
13870 ObjectHelper.verifyPositive(bufferSize, "bufferSize");
13871 if (count < 0) {
13872 throw new IllegalArgumentException("count >= 0 required but it was " + count);
13873 }
13874 return RxJavaPlugins.onAssembly(new ObservableTakeLastTimed<>(this, count, time, unit, scheduler, bufferSize, delayError));
13875 }
13876
13877 /**
13878 * Returns an {@code Observable} that emits the items from the current {@code Observable} that were emitted in a specified
13879 * window of time before the current {@code Observable} completed.
13880 * <p>
13881 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/takeLast.t.v3.png" alt="">
13882 * <dl>
13883 * <dt><b>Scheduler:</b></dt>
13884 * <dd>{@code takeLast} does not operate on any particular scheduler but uses the current time
13885 * from the {@code trampoline} {@link Scheduler}.</dd>
13886 * </dl>
13887 *
13888 * @param time
13889 * the length of the time window
13890 * @param unit
13891 * the time unit of {@code time}
13892 * @return the new {@code Observable} instance
13893 * @throws NullPointerException if {@code unit} is {@code null}
13894 * @see <a href="http://reactivex.io/documentation/operators/takelast.html">ReactiveX operators documentation: TakeLast</a>
13895 */
13896 @CheckReturnValue
13897 @SchedulerSupport(SchedulerSupport.TRAMPOLINE)
13898 @NonNull
13899 public final Observable<T> takeLast(long time, @NonNull TimeUnit unit) {
13900 return takeLast(time, unit, Schedulers.trampoline(), false, bufferSize());
13901 }
13902
13903 /**
13904 * Returns an {@code Observable} that emits the items from the current {@code Observable} that were emitted in a specified
13905 * window of time before the current {@code Observable} completed.
13906 * <p>
13907 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/takeLast.t.v3.png" alt="">
13908 * <dl>
13909 * <dt><b>Scheduler:</b></dt>
13910 * <dd>{@code takeLast} does not operate on any particular scheduler but uses the current time
13911 * from the {@code trampoline} {@link Scheduler}.</dd>
13912 * </dl>
13913 *
13914 * @param time
13915 * the length of the time window
13916 * @param unit
13917 * the time unit of {@code time}
13918 * @param delayError
13919 * if {@code true}, an exception signaled by the current {@code Observable} is delayed until the regular elements are consumed
13920 * by the downstream; if {@code false}, an exception is immediately signaled and all regular elements dropped
13921 * @return the new {@code Observable} instance
13922 * @throws NullPointerException if {@code unit} is {@code null}
13923 * @throws IllegalArgumentException if {@code count} is non-positive
13924 * @see <a href="http://reactivex.io/documentation/operators/takelast.html">ReactiveX operators documentation: TakeLast</a>
13925 */
13926 @CheckReturnValue
13927 @SchedulerSupport(SchedulerSupport.TRAMPOLINE)
13928 @NonNull
13929 public final Observable<T> takeLast(long time, @NonNull TimeUnit unit, boolean delayError) {
13930 return takeLast(time, unit, Schedulers.trampoline(), delayError, bufferSize());
13931 }
13932
13933 /**
13934 * Returns an {@code Observable} that emits the items from the current {@code Observable} that were emitted in a specified
13935 * window of time before the current {@code Observable} completed, where the timing information is provided by a specified
13936 * {@link Scheduler}.
13937 * <p>
13938 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/takeLast.ts.v3.png" alt="">
13939 * <dl>
13940 * <dt><b>Scheduler:</b></dt>
13941 * <dd>You specify which {@code Scheduler} this operator will use.</dd>
13942 * </dl>
13943 *
13944 * @param time
13945 * the length of the time window
13946 * @param unit
13947 * the time unit of {@code time}
13948 * @param scheduler
13949 * the {@code Scheduler} that provides the timestamps for the observed items
13950 * @return the new {@code Observable} instance
13951 * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null}
13952 * @see <a href="http://reactivex.io/documentation/operators/takelast.html">ReactiveX operators documentation: TakeLast</a>
13953 */
13954 @CheckReturnValue
13955 @SchedulerSupport(SchedulerSupport.CUSTOM)
13956 @NonNull
13957 public final Observable<T> takeLast(long time, @NonNull TimeUnit unit, @NonNull Scheduler scheduler) {
13958 return takeLast(time, unit, scheduler, false, bufferSize());
13959 }
13960
13961 /**
13962 * Returns an {@code Observable} that emits the items from the current {@code Observable} that were emitted in a specified
13963 * window of time before the current {@code Observable} completed, where the timing information is provided by a specified
13964 * {@link Scheduler}.
13965 * <p>
13966 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/takeLast.ts.v3.png" alt="">
13967 * <dl>
13968 * <dt><b>Scheduler:</b></dt>
13969 * <dd>You specify which {@code Scheduler} this operator will use.</dd>
13970 * </dl>
13971 *
13972 * @param time
13973 * the length of the time window
13974 * @param unit
13975 * the time unit of {@code time}
13976 * @param scheduler
13977 * the {@code Scheduler} that provides the timestamps for the observed items
13978 * @param delayError
13979 * if {@code true}, an exception signaled by the current {@code Observable} is delayed until the regular elements are consumed
13980 * by the downstream; if {@code false}, an exception is immediately signaled and all regular elements dropped
13981 * @return the new {@code Observable} instance
13982 * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null}
13983 * @see <a href="http://reactivex.io/documentation/operators/takelast.html">ReactiveX operators documentation: TakeLast</a>
13984 */
13985 @CheckReturnValue
13986 @SchedulerSupport(SchedulerSupport.CUSTOM)
13987 @NonNull
13988 public final Observable<T> takeLast(long time, @NonNull TimeUnit unit, @NonNull Scheduler scheduler, boolean delayError) {
13989 return takeLast(time, unit, scheduler, delayError, bufferSize());
13990 }
13991
13992 /**
13993 * Returns an {@code Observable} that emits the items from the current {@code Observable} that were emitted in a specified
13994 * window of time before the current {@code Observable} completed, where the timing information is provided by a specified
13995 * {@link Scheduler}.
13996 * <p>
13997 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/takeLast.ts.v3.png" alt="">
13998 * <dl>
13999 * <dt><b>Scheduler:</b></dt>
14000 * <dd>You specify which {@code Scheduler} this operator will use.</dd>
14001 * </dl>
14002 *
14003 * @param time
14004 * the length of the time window
14005 * @param unit
14006 * the time unit of {@code time}
14007 * @param scheduler
14008 * the {@code Scheduler} that provides the timestamps for the observed items
14009 * @param delayError
14010 * if {@code true}, an exception signaled by the current {@code Observable} is delayed until the regular elements are consumed
14011 * by the downstream; if {@code false}, an exception is immediately signaled and all regular elements dropped
14012 * @param bufferSize
14013 * the hint about how many elements to expect to be last
14014 * @return the new {@code Observable} instance
14015 * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null}
14016 * @throws IllegalArgumentException if {@code bufferSize} is non-positive
14017 * @see <a href="http://reactivex.io/documentation/operators/takelast.html">ReactiveX operators documentation: TakeLast</a>
14018 */
14019 @CheckReturnValue
14020 @SchedulerSupport(SchedulerSupport.CUSTOM)
14021 @NonNull
14022 public final Observable<T> takeLast(long time, @NonNull TimeUnit unit, @NonNull Scheduler scheduler, boolean delayError, int bufferSize) {
14023 return takeLast(Long.MAX_VALUE, time, unit, scheduler, delayError, bufferSize);
14024 }
14025
14026 /**
14027 * Returns an {@code Observable} that emits the items emitted by the current {@code Observable} until a second {@link ObservableSource}
14028 * emits an item or completes.
14029 * <p>
14030 * <img width="640" height="213" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Observable.takeUntil.o.png" alt="">
14031 * <dl>
14032 * <dt><b>Scheduler:</b></dt>
14033 * <dd>{@code takeUntil} does not operate by default on a particular {@link Scheduler}.</dd>
14034 * </dl>
14035 *
14036 * @param other
14037 * the {@code ObservableSource} whose first emitted item or completion will cause {@code takeUntil} to stop emitting items
14038 * from the current {@code Observable}
14039 * @param <U>
14040 * the type of items emitted by {@code other}
14041 * @return the new {@code Observable} instance
14042 * @throws NullPointerException if {@code other} is {@code null}
14043 * @see <a href="http://reactivex.io/documentation/operators/takeuntil.html">ReactiveX operators documentation: TakeUntil</a>
14044 */
14045 @CheckReturnValue
14046 @SchedulerSupport(SchedulerSupport.NONE)
14047 @NonNull
14048 public final <@NonNull U> Observable<T> takeUntil(@NonNull ObservableSource<U> other) {
14049 Objects.requireNonNull(other, "other is null");
14050 return RxJavaPlugins.onAssembly(new ObservableTakeUntil<>(this, other));
14051 }
14052
14053 /**
14054 * Returns an {@code Observable} that emits items emitted by the current {@code Observable}, checks the specified predicate
14055 * for each item, and then completes when the condition is satisfied.
14056 * <p>
14057 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/takeUntil.p.v3.png" alt="">
14058 * <p>
14059 * The difference between this operator and {@link #takeWhile(Predicate)} is that here, the condition is
14060 * evaluated <em>after</em> the item is emitted.
14061 *
14062 * <dl>
14063 * <dt><b>Scheduler:</b></dt>
14064 * <dd>{@code takeUntil} does not operate by default on a particular {@link Scheduler}.</dd>
14065 * </dl>
14066 *
14067 * @param stopPredicate
14068 * a function that evaluates an item emitted by the current {@code Observable} and returns a {@link Boolean}
14069 * @return the new {@code Observable} instance
14070 * @throws NullPointerException if {@code stopPredicate} is {@code null}
14071 * @see <a href="http://reactivex.io/documentation/operators/takeuntil.html">ReactiveX operators documentation: TakeUntil</a>
14072 * @see Observable#takeWhile(Predicate)
14073 * @since 1.1.0
14074 */
14075 @CheckReturnValue
14076 @SchedulerSupport(SchedulerSupport.NONE)
14077 @NonNull
14078 public final Observable<T> takeUntil(@NonNull Predicate<? super T> stopPredicate) {
14079 Objects.requireNonNull(stopPredicate, "stopPredicate is null");
14080 return RxJavaPlugins.onAssembly(new ObservableTakeUntilPredicate<>(this, stopPredicate));
14081 }
14082
14083 /**
14084 * Returns an {@code Observable} that emits items emitted by the current {@code Observable} so long as each item satisfied a
14085 * specified condition, and then completes as soon as this condition is not satisfied.
14086 * <p>
14087 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/takeWhile.v3.png" alt="">
14088 * <dl>
14089 * <dt><b>Scheduler:</b></dt>
14090 * <dd>{@code takeWhile} does not operate by default on a particular {@link Scheduler}.</dd>
14091 * </dl>
14092 *
14093 * @param predicate
14094 * a function that evaluates an item emitted by the current {@code Observable} and returns a {@link Boolean}
14095 * @return the new {@code Observable} instance
14096 * @throws NullPointerException if {@code predicate} is {@code null}
14097 * @see <a href="http://reactivex.io/documentation/operators/takewhile.html">ReactiveX operators documentation: TakeWhile</a>
14098 * @see Observable#takeUntil(Predicate)
14099 */
14100 @CheckReturnValue
14101 @SchedulerSupport(SchedulerSupport.NONE)
14102 @NonNull
14103 public final Observable<T> takeWhile(@NonNull Predicate<? super T> predicate) {
14104 Objects.requireNonNull(predicate, "predicate is null");
14105 return RxJavaPlugins.onAssembly(new ObservableTakeWhile<>(this, predicate));
14106 }
14107
14108 /**
14109 * Returns an {@code Observable} that emits only the first item emitted by the current {@code Observable} during sequential
14110 * time windows of a specified duration.
14111 * <p>
14112 * This differs from {@link #throttleLast} in that this only tracks passage of time whereas
14113 * {@code throttleLast} ticks at scheduled intervals.
14114 * <p>
14115 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/throttleFirst.v3.png" alt="">
14116 * <dl>
14117 * <dt><b>Scheduler:</b></dt>
14118 * <dd>{@code throttleFirst} operates by default on the {@code computation} {@link Scheduler}.</dd>
14119 * </dl>
14120 *
14121 * @param windowDuration
14122 * time to wait before emitting another item after emitting the last item
14123 * @param unit
14124 * the unit of time of {@code windowDuration}
14125 * @return the new {@code Observable} instance
14126 * @throws NullPointerException if {@code unit} is {@code null}
14127 * @see <a href="http://reactivex.io/documentation/operators/sample.html">ReactiveX operators documentation: Sample</a>
14128 */
14129 @CheckReturnValue
14130 @SchedulerSupport(SchedulerSupport.COMPUTATION)
14131 @NonNull
14132 public final Observable<T> throttleFirst(long windowDuration, @NonNull TimeUnit unit) {
14133 return throttleFirst(windowDuration, unit, Schedulers.computation());
14134 }
14135
14136 /**
14137 * Returns an {@code Observable} that emits only the first item emitted by the current {@code Observable} during sequential
14138 * time windows of a specified duration, where the windows are managed by a specified {@link Scheduler}.
14139 * <p>
14140 * This differs from {@link #throttleLast} in that this only tracks passage of time whereas
14141 * {@code throttleLast} ticks at scheduled intervals.
14142 * <p>
14143 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/throttleFirst.s.v3.png" alt="">
14144 * <dl>
14145 * <dt><b>Scheduler:</b></dt>
14146 * <dd>You specify which {@code Scheduler} this operator will use.</dd>
14147 * </dl>
14148 *
14149 * @param skipDuration
14150 * time to wait before emitting another item after emitting the last item
14151 * @param unit
14152 * the unit of time of {@code skipDuration}
14153 * @param scheduler
14154 * the {@code Scheduler} to use internally to manage the timers that handle timeout for each
14155 * event
14156 * @return the new {@code Observable} instance
14157 * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null}
14158 * @see <a href="http://reactivex.io/documentation/operators/sample.html">ReactiveX operators documentation: Sample</a>
14159 */
14160 @CheckReturnValue
14161 @SchedulerSupport(SchedulerSupport.CUSTOM)
14162 @NonNull
14163 public final Observable<T> throttleFirst(long skipDuration, @NonNull TimeUnit unit, @NonNull Scheduler scheduler) {
14164 Objects.requireNonNull(unit, "unit is null");
14165 Objects.requireNonNull(scheduler, "scheduler is null");
14166 return RxJavaPlugins.onAssembly(new ObservableThrottleFirstTimed<>(this, skipDuration, unit, scheduler));
14167 }
14168
14169 /**
14170 * Returns an {@code Observable} that emits only the last item emitted by the current {@code Observable} during sequential
14171 * time windows of a specified duration.
14172 * <p>
14173 * This differs from {@link #throttleFirst} in that this ticks along at a scheduled interval whereas
14174 * {@code throttleFirst} does not tick, it just tracks passage of time.
14175 * <p>
14176 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/throttleLast.v3.png" alt="">
14177 * <dl>
14178 * <dt><b>Scheduler:</b></dt>
14179 * <dd>{@code throttleLast} operates by default on the {@code computation} {@link Scheduler}.</dd>
14180 * </dl>
14181 *
14182 * @param intervalDuration
14183 * duration of windows within which the last item emitted by the current {@code Observable} will be
14184 * emitted
14185 * @param unit
14186 * the unit of time of {@code intervalDuration}
14187 * @return the new {@code Observable} instance
14188 * @throws NullPointerException if {@code unit} is {@code null}
14189 * @see <a href="http://reactivex.io/documentation/operators/sample.html">ReactiveX operators documentation: Sample</a>
14190 * @see #sample(long, TimeUnit)
14191 */
14192 @CheckReturnValue
14193 @SchedulerSupport(SchedulerSupport.COMPUTATION)
14194 @NonNull
14195 public final Observable<T> throttleLast(long intervalDuration, @NonNull TimeUnit unit) {
14196 return sample(intervalDuration, unit);
14197 }
14198
14199 /**
14200 * Returns an {@code Observable} that emits only the last item emitted by the current {@code Observable} during sequential
14201 * time windows of a specified duration, where the duration is governed by a specified {@link Scheduler}.
14202 * <p>
14203 * This differs from {@link #throttleFirst} in that this ticks along at a scheduled interval whereas
14204 * {@code throttleFirst} does not tick, it just tracks passage of time.
14205 * <p>
14206 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/throttleLast.s.v3.png" alt="">
14207 * <dl>
14208 * <dt><b>Scheduler:</b></dt>
14209 * <dd>You specify which {@code Scheduler} this operator will use.</dd>
14210 * </dl>
14211 *
14212 * @param intervalDuration
14213 * duration of windows within which the last item emitted by the current {@code Observable} will be
14214 * emitted
14215 * @param unit
14216 * the unit of time of {@code intervalDuration}
14217 * @param scheduler
14218 * the {@code Scheduler} to use internally to manage the timers that handle timeout for each
14219 * event
14220 * @return the new {@code Observable} instance
14221 * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null}
14222 * @see <a href="http://reactivex.io/documentation/operators/sample.html">ReactiveX operators documentation: Sample</a>
14223 * @see #sample(long, TimeUnit, Scheduler)
14224 */
14225 @CheckReturnValue
14226 @SchedulerSupport(SchedulerSupport.CUSTOM)
14227 @NonNull
14228 public final Observable<T> throttleLast(long intervalDuration, @NonNull TimeUnit unit, @NonNull Scheduler scheduler) {
14229 return sample(intervalDuration, unit, scheduler);
14230 }
14231
14232 /**
14233 * Throttles items from the current {@code Observable} by first emitting the next
14234 * item from upstream, then periodically emitting the latest item (if any) when
14235 * the specified timeout elapses between them.
14236 * <p>
14237 * <img width="640" height="326" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/throttleLatest.png" alt="">
14238 * <p>
14239 * Unlike the option with {@link #throttleLatest(long, TimeUnit, boolean)}, the very last item being held back
14240 * (if any) is not emitted when the upstream completes.
14241 * <p>
14242 * If no items were emitted from the upstream during this timeout phase, the next
14243 * upstream item is emitted immediately and the timeout window starts from then.
14244 * <dl>
14245 * <dt><b>Scheduler:</b></dt>
14246 * <dd>{@code throttleLatest} operates by default on the {@code computation} {@link Scheduler}.</dd>
14247 * </dl>
14248 * <p>History: 2.1.14 - experimental
14249 * @param timeout the time to wait after an item emission towards the downstream
14250 * before trying to emit the latest item from upstream again
14251 * @param unit the time unit
14252 * @return the new {@code Observable} instance
14253 * @throws NullPointerException if {@code unit} is {@code null}
14254 * @see #throttleLatest(long, TimeUnit, boolean)
14255 * @see #throttleLatest(long, TimeUnit, Scheduler)
14256 * @since 2.2
14257 */
14258 @CheckReturnValue
14259 @SchedulerSupport(SchedulerSupport.COMPUTATION)
14260 @NonNull
14261 public final Observable<T> throttleLatest(long timeout, @NonNull TimeUnit unit) {
14262 return throttleLatest(timeout, unit, Schedulers.computation(), false);
14263 }
14264
14265 /**
14266 * Throttles items from the current {@code Observable} by first emitting the next
14267 * item from upstream, then periodically emitting the latest item (if any) when
14268 * the specified timeout elapses between them.
14269 * <p>
14270 * <img width="640" height="326" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/throttleLatest.e.png" alt="">
14271 * <p>
14272 * If no items were emitted from the upstream during this timeout phase, the next
14273 * upstream item is emitted immediately and the timeout window starts from then.
14274 * <dl>
14275 * <dt><b>Scheduler:</b></dt>
14276 * <dd>{@code throttleLatest} operates by default on the {@code computation} {@link Scheduler}.</dd>
14277 * </dl>
14278 * <p>History: 2.1.14 - experimental
14279 * @param timeout the time to wait after an item emission towards the downstream
14280 * before trying to emit the latest item from upstream again
14281 * @param unit the time unit
14282 * @param emitLast If {@code true}, the very last item from the upstream will be emitted
14283 * immediately when the upstream completes, regardless if there is
14284 * a timeout window active or not. If {@code false}, the very last
14285 * upstream item is ignored and the flow terminates.
14286 * @return the new {@code Observable} instance
14287 * @throws NullPointerException if {@code unit} is {@code null}
14288 * @see #throttleLatest(long, TimeUnit, Scheduler, boolean)
14289 * @since 2.2
14290 */
14291 @CheckReturnValue
14292 @SchedulerSupport(SchedulerSupport.COMPUTATION)
14293 @NonNull
14294 public final Observable<T> throttleLatest(long timeout, @NonNull TimeUnit unit, boolean emitLast) {
14295 return throttleLatest(timeout, unit, Schedulers.computation(), emitLast);
14296 }
14297
14298 /**
14299 * Throttles items from the current {@code Observable} by first emitting the next
14300 * item from upstream, then periodically emitting the latest item (if any) when
14301 * the specified timeout elapses between them.
14302 * <p>
14303 * <img width="640" height="326" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/throttleLatest.s.png" alt="">
14304 * <p>
14305 * Unlike the option with {@link #throttleLatest(long, TimeUnit, Scheduler, boolean)}, the very last item being held back
14306 * (if any) is not emitted when the upstream completes.
14307 * <p>
14308 * If no items were emitted from the upstream during this timeout phase, the next
14309 * upstream item is emitted immediately and the timeout window starts from then.
14310 * <dl>
14311 * <dt><b>Scheduler:</b></dt>
14312 * <dd>You specify which {@link Scheduler} this operator will use.</dd>
14313 * </dl>
14314 * <p>History: 2.1.14 - experimental
14315 * @param timeout the time to wait after an item emission towards the downstream
14316 * before trying to emit the latest item from upstream again
14317 * @param unit the time unit
14318 * @param scheduler the {@code Scheduler} where the timed wait and latest item
14319 * emission will be performed
14320 * @return the new {@code Observable} instance
14321 * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null}
14322 * @see #throttleLatest(long, TimeUnit, Scheduler, boolean)
14323 * @since 2.2
14324 */
14325 @CheckReturnValue
14326 @SchedulerSupport(SchedulerSupport.CUSTOM)
14327 @NonNull
14328 public final Observable<T> throttleLatest(long timeout, @NonNull TimeUnit unit, @NonNull Scheduler scheduler) {
14329 return throttleLatest(timeout, unit, scheduler, false);
14330 }
14331
14332 /**
14333 * Throttles items from the current {@code Observable} by first emitting the next
14334 * item from upstream, then periodically emitting the latest item (if any) when
14335 * the specified timeout elapses between them.
14336 * <p>
14337 * <img width="640" height="326" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/throttleLatest.se.png" alt="">
14338 * <p>
14339 * If no items were emitted from the upstream during this timeout phase, the next
14340 * upstream item is emitted immediately and the timeout window starts from then.
14341 * <dl>
14342 * <dt><b>Scheduler:</b></dt>
14343 * <dd>You specify which {@link Scheduler} this operator will use.</dd>
14344 * </dl>
14345 * <p>History: 2.1.14 - experimental
14346 * @param timeout the time to wait after an item emission towards the downstream
14347 * before trying to emit the latest item from upstream again
14348 * @param unit the time unit
14349 * @param scheduler the {@code Scheduler} where the timed wait and latest item
14350 * emission will be performed
14351 * @param emitLast If {@code true}, the very last item from the upstream will be emitted
14352 * immediately when the upstream completes, regardless if there is
14353 * a timeout window active or not. If {@code false}, the very last
14354 * upstream item is ignored and the flow terminates.
14355 * @return the new {@code Observable} instance
14356 * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null}
14357 * @since 2.2
14358 */
14359 @CheckReturnValue
14360 @SchedulerSupport(SchedulerSupport.CUSTOM)
14361 @NonNull
14362 public final Observable<T> throttleLatest(long timeout, @NonNull TimeUnit unit, @NonNull Scheduler scheduler, boolean emitLast) {
14363 Objects.requireNonNull(unit, "unit is null");
14364 Objects.requireNonNull(scheduler, "scheduler is null");
14365 return RxJavaPlugins.onAssembly(new ObservableThrottleLatest<>(this, timeout, unit, scheduler, emitLast));
14366 }
14367
14368 /**
14369 * Returns an {@code Observable} that mirrors the current {@code Observable}, except that it drops items emitted by the
14370 * current {@code Observable} that are followed by newer items before a timeout value expires. The timer resets on
14371 * each emission (alias to {@link #debounce(long, TimeUnit, Scheduler)}).
14372 * <p>
14373 * <em>Note:</em> If items keep being emitted by the current {@code Observable} faster than the timeout then no items
14374 * will be emitted by the resulting {@code Observable}.
14375 * <p>
14376 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/throttleWithTimeout.v3.png" alt="">
14377 * <dl>
14378 * <dt><b>Scheduler:</b></dt>
14379 * <dd>{@code throttleWithTimeout} operates by default on the {@code computation} {@link Scheduler}.</dd>
14380 * </dl>
14381 *
14382 * @param timeout
14383 * the length of the window of time that must pass after the emission of an item from the current
14384 * {@code Observable}, in which the current {@code Observable} emits no items, in order for the item to be emitted by the
14385 * resulting {@code Observable}
14386 * @param unit
14387 * the unit of time for the specified {@code timeout}
14388 * @return the new {@code Observable} instance
14389 * @throws NullPointerException if {@code unit} is {@code null}
14390 * @see <a href="http://reactivex.io/documentation/operators/debounce.html">ReactiveX operators documentation: Debounce</a>
14391 * @see #debounce(long, TimeUnit)
14392 */
14393 @CheckReturnValue
14394 @SchedulerSupport(SchedulerSupport.COMPUTATION)
14395 @NonNull
14396 public final Observable<T> throttleWithTimeout(long timeout, @NonNull TimeUnit unit) {
14397 return debounce(timeout, unit);
14398 }
14399
14400 /**
14401 * Returns an {@code Observable} that mirrors the current {@code Observable}, except that it drops items emitted by the
14402 * current {@code Observable} that are followed by newer items before a timeout value expires on a specified
14403 * {@link Scheduler}. The timer resets on each emission (Alias to {@link #debounce(long, TimeUnit, Scheduler)}).
14404 * <p>
14405 * <em>Note:</em> If items keep being emitted by the current {@code Observable} faster than the timeout then no items
14406 * will be emitted by the resulting {@code Observable}.
14407 * <p>
14408 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/throttleWithTimeout.s.v3.png" alt="">
14409 * <dl>
14410 * <dt><b>Scheduler:</b></dt>
14411 * <dd>You specify which {@code Scheduler} this operator will use.</dd>
14412 * </dl>
14413 *
14414 * @param timeout
14415 * the length of the window of time that must pass after the emission of an item from the current
14416 * {@code Observable}, in which the current {@code Observable} emits no items, in order for the item to be emitted by the
14417 * resulting {@code Observable}
14418 * @param unit
14419 * the unit of time for the specified {@code timeout}
14420 * @param scheduler
14421 * the {@code Scheduler} to use internally to manage the timers that handle the timeout for each
14422 * item
14423 * @return the new {@code Observable} instance
14424 * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null}
14425 * @see <a href="http://reactivex.io/documentation/operators/debounce.html">ReactiveX operators documentation: Debounce</a>
14426 * @see #debounce(long, TimeUnit, Scheduler)
14427 */
14428 @CheckReturnValue
14429 @SchedulerSupport(SchedulerSupport.CUSTOM)
14430 @NonNull
14431 public final Observable<T> throttleWithTimeout(long timeout, @NonNull TimeUnit unit, @NonNull Scheduler scheduler) {
14432 return debounce(timeout, unit, scheduler);
14433 }
14434
14435 /**
14436 * Returns an {@code Observable} that emits records of the time interval between consecutive items emitted by the
14437 * current {@code Observable}.
14438 * <p>
14439 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/timeInterval.v3.png" alt="">
14440 * <dl>
14441 * <dt><b>Scheduler:</b></dt>
14442 * <dd>{@code timeInterval} does not operate on any particular scheduler but uses the current time
14443 * from the {@code computation} {@link Scheduler}.</dd>
14444 * </dl>
14445 *
14446 * @return the new {@code Observable} instance
14447 * @see <a href="http://reactivex.io/documentation/operators/timeinterval.html">ReactiveX operators documentation: TimeInterval</a>
14448 */
14449 @CheckReturnValue
14450 @SchedulerSupport(SchedulerSupport.NONE)
14451 @NonNull
14452 public final Observable<Timed<T>> timeInterval() {
14453 return timeInterval(TimeUnit.MILLISECONDS, Schedulers.computation());
14454 }
14455
14456 /**
14457 * Returns an {@code Observable} that emits records of the time interval between consecutive items emitted by the
14458 * current {@code Observable}, where this interval is computed on a specified {@link Scheduler}.
14459 * <p>
14460 * <img width="640" height="315" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/timeInterval.s.v3.png" alt="">
14461 * <dl>
14462 * <dt><b>Scheduler:</b></dt>
14463 * <dd>The operator does not operate on any particular scheduler but uses the current time
14464 * from the specified {@code Scheduler}.</dd>
14465 * </dl>
14466 *
14467 * @param scheduler
14468 * the {@code Scheduler} used to compute time intervals
14469 * @return the new {@code Observable} instance
14470 * @throws NullPointerException if {@code scheduler} is {@code null}
14471 * @see <a href="http://reactivex.io/documentation/operators/timeinterval.html">ReactiveX operators documentation: TimeInterval</a>
14472 */
14473 @CheckReturnValue
14474 @SchedulerSupport(SchedulerSupport.NONE) // Supplied scheduler is only used for creating timestamps.
14475 @NonNull
14476 public final Observable<Timed<T>> timeInterval(@NonNull Scheduler scheduler) {
14477 return timeInterval(TimeUnit.MILLISECONDS, scheduler);
14478 }
14479
14480 /**
14481 * Returns an {@code Observable} that emits records of the time interval between consecutive items emitted by the
14482 * current {@code Observable}.
14483 * <p>
14484 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/timeInterval.v3.png" alt="">
14485 * <dl>
14486 * <dt><b>Scheduler:</b></dt>
14487 * <dd>{@code timeInterval} does not operate on any particular scheduler but uses the current time
14488 * from the {@code computation} {@link Scheduler}.</dd>
14489 * </dl>
14490 *
14491 * @param unit the time unit for the current time
14492 * @return the new {@code Observable} instance
14493 * @throws NullPointerException if {@code unit} is {@code null}
14494 * @see <a href="http://reactivex.io/documentation/operators/timeinterval.html">ReactiveX operators documentation: TimeInterval</a>
14495 */
14496 @CheckReturnValue
14497 @SchedulerSupport(SchedulerSupport.NONE)
14498 @NonNull
14499 public final Observable<Timed<T>> timeInterval(@NonNull TimeUnit unit) {
14500 return timeInterval(unit, Schedulers.computation());
14501 }
14502
14503 /**
14504 * Returns an {@code Observable} that emits records of the time interval between consecutive items emitted by the
14505 * current {@code Observable}, where this interval is computed on a specified {@link Scheduler}.
14506 * <p>
14507 * <img width="640" height="315" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/timeInterval.s.v3.png" alt="">
14508 * <dl>
14509 * <dt><b>Scheduler:</b></dt>
14510 * <dd>The operator does not operate on any particular scheduler but uses the current time
14511 * from the specified {@code Scheduler}.</dd>
14512 * </dl>
14513 *
14514 * @param unit the time unit for the current time
14515 * @param scheduler
14516 * the {@code Scheduler} used to compute time intervals
14517 * @return the new {@code Observable} instance
14518 * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null}
14519 * @see <a href="http://reactivex.io/documentation/operators/timeinterval.html">ReactiveX operators documentation: TimeInterval</a>
14520 */
14521 @CheckReturnValue
14522 @SchedulerSupport(SchedulerSupport.NONE) // Supplied scheduler is only used for creating timestamps.
14523 @NonNull
14524 public final Observable<Timed<T>> timeInterval(@NonNull TimeUnit unit, @NonNull Scheduler scheduler) {
14525 Objects.requireNonNull(unit, "unit is null");
14526 Objects.requireNonNull(scheduler, "scheduler is null");
14527 return RxJavaPlugins.onAssembly(new ObservableTimeInterval<>(this, unit, scheduler));
14528 }
14529
14530 /**
14531 * Returns an {@code Observable} that mirrors the current {@code Observable}, but notifies observers of a
14532 * {@link TimeoutException} if an item emitted by the current {@code Observable} doesn't arrive within a window of
14533 * time after the emission of the previous item, where that period of time is measured by an {@link ObservableSource} that
14534 * is a function of the previous item.
14535 * <p>
14536 * <img width="640" height="400" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/timeout3.v3.png" alt="">
14537 * <p>
14538 * Note: The arrival of the first source item is never timed out.
14539 * <dl>
14540 * <dt><b>Scheduler:</b></dt>
14541 * <dd>This version of {@code timeout} operates by default on the {@code immediate} {@link Scheduler}.</dd>
14542 * </dl>
14543 *
14544 * @param <V>
14545 * the timeout value type (ignored)
14546 * @param itemTimeoutIndicator
14547 * a function that returns an {@code ObservableSource} for each item emitted by the current
14548 * {@code Observable} and that determines the timeout window for the subsequent item
14549 * @return the new {@code Observable} instance
14550 * @throws NullPointerException if {@code itemTimeoutIndicator} is {@code null}
14551 * @see <a href="http://reactivex.io/documentation/operators/timeout.html">ReactiveX operators documentation: Timeout</a>
14552 */
14553 @CheckReturnValue
14554 @SchedulerSupport(SchedulerSupport.NONE)
14555 @NonNull
14556 public final <@NonNull V> Observable<T> timeout(@NonNull Function<? super T, ? extends ObservableSource<V>> itemTimeoutIndicator) {
14557 return timeout0(null, itemTimeoutIndicator, null);
14558 }
14559
14560 /**
14561 * Returns an {@code Observable} that mirrors the current {@code Observable}, but that switches to a fallback {@link ObservableSource} if
14562 * an item emitted by the current {@code Observable} doesn't arrive within a window of time after the emission of the
14563 * previous item, where that period of time is measured by an {@code ObservableSource} that is a function of the previous
14564 * item.
14565 * <p>
14566 * <img width="640" height="400" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/timeout4.v3.png" alt="">
14567 * <p>
14568 * Note: The arrival of the first source item is never timed out.
14569 * <dl>
14570 * <dt><b>Scheduler:</b></dt>
14571 * <dd>This version of {@code timeout} operates by default on the {@code immediate} {@link Scheduler}.</dd>
14572 * </dl>
14573 *
14574 * @param <V>
14575 * the timeout value type (ignored)
14576 * @param itemTimeoutIndicator
14577 * a function that returns an {@code ObservableSource}, for each item emitted by the current {@code Observable}, that
14578 * determines the timeout window for the subsequent item
14579 * @param fallback
14580 * the fallback {@code ObservableSource} to switch to if the current {@code Observable} times out
14581 * @return the new {@code Observable} instance
14582 * @throws NullPointerException if {@code itemTimeoutIndicator} or {@code fallback} is {@code null}
14583 * @see <a href="http://reactivex.io/documentation/operators/timeout.html">ReactiveX operators documentation: Timeout</a>
14584 */
14585 @CheckReturnValue
14586 @SchedulerSupport(SchedulerSupport.NONE)
14587 @NonNull
14588 public final <@NonNull V> Observable<T> timeout(@NonNull Function<? super T, ? extends ObservableSource<V>> itemTimeoutIndicator,
14589 @NonNull ObservableSource<? extends T> fallback) {
14590 Objects.requireNonNull(fallback, "fallback is null");
14591 return timeout0(null, itemTimeoutIndicator, fallback);
14592 }
14593
14594 /**
14595 * Returns an {@code Observable} that mirrors the current {@code Observable} but applies a timeout policy for each emitted
14596 * item. If the next item isn't emitted within the specified timeout duration starting from its predecessor,
14597 * the resulting {@code Observable} terminates and notifies observers of a {@link TimeoutException}.
14598 * <p>
14599 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/timeout.1.v3.png" alt="">
14600 * <dl>
14601 * <dt><b>Scheduler:</b></dt>
14602 * <dd>This version of {@code timeout} operates by default on the {@code computation} {@link Scheduler}.</dd>
14603 * </dl>
14604 *
14605 * @param timeout
14606 * maximum duration between emitted items before a timeout occurs
14607 * @param unit
14608 * the unit of time that applies to the {@code timeout} argument.
14609 * @return the new {@code Observable} instance
14610 * @throws NullPointerException if {@code unit} is {@code null}
14611 * @see <a href="http://reactivex.io/documentation/operators/timeout.html">ReactiveX operators documentation: Timeout</a>
14612 */
14613 @CheckReturnValue
14614 @SchedulerSupport(SchedulerSupport.COMPUTATION)
14615 @NonNull
14616 public final Observable<T> timeout(long timeout, @NonNull TimeUnit unit) {
14617 return timeout0(timeout, unit, null, Schedulers.computation());
14618 }
14619
14620 /**
14621 * Returns an {@code Observable} that mirrors the current {@code Observable} but applies a timeout policy for each emitted
14622 * item. If the next item isn't emitted within the specified timeout duration starting from its predecessor,
14623 * the current {@code Observable} is disposed and the resulting {@code Observable} begins instead
14624 * to mirror a fallback {@link ObservableSource}.
14625 * <p>
14626 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/timeout.2.v3.png" alt="">
14627 * <dl>
14628 * <dt><b>Scheduler:</b></dt>
14629 * <dd>This version of {@code timeout} operates by default on the {@code computation} {@link Scheduler}.</dd>
14630 * </dl>
14631 *
14632 * @param timeout
14633 * maximum duration between items before a timeout occurs
14634 * @param unit
14635 * the unit of time that applies to the {@code timeout} argument
14636 * @param fallback
14637 * the fallback {@code ObservableSource} to use in case of a timeout
14638 * @return the new {@code Observable} instance
14639 * @throws NullPointerException if {@code unit} or {@code fallback} is {@code null}
14640 * @see <a href="http://reactivex.io/documentation/operators/timeout.html">ReactiveX operators documentation: Timeout</a>
14641 */
14642 @CheckReturnValue
14643 @SchedulerSupport(SchedulerSupport.COMPUTATION)
14644 @NonNull
14645 public final Observable<T> timeout(long timeout, @NonNull TimeUnit unit, @NonNull ObservableSource<? extends T> fallback) {
14646 Objects.requireNonNull(fallback, "fallback is null");
14647 return timeout0(timeout, unit, fallback, Schedulers.computation());
14648 }
14649
14650 /**
14651 * Returns an {@code Observable} that mirrors the current {@code Observable} but applies a timeout policy for each emitted
14652 * item using a specified {@link Scheduler}. If the next item isn't emitted within the specified timeout duration
14653 * starting from its predecessor, the current {@code Observable} is disposed and returned {@code Observable}
14654 * begins instead to mirror a fallback {@link ObservableSource}.
14655 * <p>
14656 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/timeout.2s.v3.png" alt="">
14657 * <dl>
14658 * <dt><b>Scheduler:</b></dt>
14659 * <dd>You specify which {@code Scheduler} this operator will use.</dd>
14660 * </dl>
14661 *
14662 * @param timeout
14663 * maximum duration between items before a timeout occurs
14664 * @param unit
14665 * the unit of time that applies to the {@code timeout} argument
14666 * @param scheduler
14667 * the {@code Scheduler} to run the timeout timers on
14668 * @param fallback
14669 * the {@code ObservableSource} to use as the fallback in case of a timeout
14670 * @return the new {@code Observable} instance
14671 * @throws NullPointerException if {@code unit}, {@code scheduler} or {@code fallback} is {@code null}
14672 * @see <a href="http://reactivex.io/documentation/operators/timeout.html">ReactiveX operators documentation: Timeout</a>
14673 */
14674 @CheckReturnValue
14675 @SchedulerSupport(SchedulerSupport.CUSTOM)
14676 @NonNull
14677 public final Observable<T> timeout(long timeout, @NonNull TimeUnit unit, @NonNull Scheduler scheduler, @NonNull ObservableSource<? extends T> fallback) {
14678 Objects.requireNonNull(fallback, "fallback is null");
14679 return timeout0(timeout, unit, fallback, scheduler);
14680 }
14681
14682 /**
14683 * Returns an {@code Observable} that mirrors the current {@code Observable} but applies a timeout policy for each emitted
14684 * item, where this policy is governed on a specified {@link Scheduler}. If the next item isn't emitted within the
14685 * specified timeout duration starting from its predecessor, the resulting {@code Observable} terminates and
14686 * notifies observers of a {@link TimeoutException}.
14687 * <p>
14688 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/timeout.1s.v3.png" alt="">
14689 * <dl>
14690 * <dt><b>Scheduler:</b></dt>
14691 * <dd>You specify which {@code Scheduler} this operator will use.</dd>
14692 * </dl>
14693 *
14694 * @param timeout
14695 * maximum duration between items before a timeout occurs
14696 * @param unit
14697 * the unit of time that applies to the {@code timeout} argument
14698 * @param scheduler
14699 * the {@code Scheduler} to run the timeout timers on
14700 * @return the new {@code Observable} instance
14701 * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null}
14702 * @see <a href="http://reactivex.io/documentation/operators/timeout.html">ReactiveX operators documentation: Timeout</a>
14703 */
14704 @CheckReturnValue
14705 @SchedulerSupport(SchedulerSupport.CUSTOM)
14706 @NonNull
14707 public final Observable<T> timeout(long timeout, @NonNull TimeUnit unit, @NonNull Scheduler scheduler) {
14708 return timeout0(timeout, unit, null, scheduler);
14709 }
14710
14711 /**
14712 * Returns an {@code Observable} that mirrors the current {@code Observable}, but notifies observers of a
14713 * {@link TimeoutException} if either the first item emitted by the current {@code Observable} or any subsequent item
14714 * doesn't arrive within time windows defined by indicator {@link ObservableSource}s.
14715 * <p>
14716 * <img width="640" height="400" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/timeout5.v3.png" alt="">
14717 * <dl>
14718 * <dt><b>Scheduler:</b></dt>
14719 * <dd>This version of {@code timeout} operates by default on the {@code immediate} {@link Scheduler}.</dd>
14720 * </dl>
14721 *
14722 * @param <U>
14723 * the first timeout value type (ignored)
14724 * @param <V>
14725 * the subsequent timeout value type (ignored)
14726 * @param firstTimeoutIndicator
14727 * a function that returns an {@code ObservableSource} that determines the timeout window for the first source
14728 * item
14729 * @param itemTimeoutIndicator
14730 * a function that returns an {@code ObservableSource} for each item emitted by the current {@code Observable} and that
14731 * determines the timeout window in which the subsequent source item must arrive in order to
14732 * continue the sequence
14733 * @return the new {@code Observable} instance
14734 * @throws NullPointerException if {@code firstTimeoutIndicator} or {@code itemTimeoutIndicator} is {@code null}
14735 * @see <a href="http://reactivex.io/documentation/operators/timeout.html">ReactiveX operators documentation: Timeout</a>
14736 */
14737 @CheckReturnValue
14738 @SchedulerSupport(SchedulerSupport.NONE)
14739 @NonNull
14740 public final <@NonNull U, @NonNull V> Observable<T> timeout(@NonNull ObservableSource<U> firstTimeoutIndicator,
14741 @NonNull Function<? super T, ? extends ObservableSource<V>> itemTimeoutIndicator) {
14742 Objects.requireNonNull(firstTimeoutIndicator, "firstTimeoutIndicator is null");
14743 return timeout0(firstTimeoutIndicator, itemTimeoutIndicator, null);
14744 }
14745
14746 /**
14747 * Returns an {@code Observable} that mirrors the current {@code Observable}, but switches to a fallback {@link ObservableSource} if either
14748 * the first item emitted by the current {@code Observable} or any subsequent item doesn't arrive within time windows
14749 * defined by indicator {@code ObservableSource}s.
14750 * <p>
14751 * <img width="640" height="400" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/timeout6.v3.png" alt="">
14752 * <dl>
14753 * <dt><b>Scheduler:</b></dt>
14754 * <dd>This version of {@code timeout} operates by default on the {@code immediate} {@link Scheduler}.</dd>
14755 * </dl>
14756 *
14757 * @param <U>
14758 * the first timeout value type (ignored)
14759 * @param <V>
14760 * the subsequent timeout value type (ignored)
14761 * @param firstTimeoutIndicator
14762 * a function that returns an {@code ObservableSource} which determines the timeout window for the first source
14763 * item
14764 * @param itemTimeoutIndicator
14765 * a function that returns an {@code ObservableSource} for each item emitted by the current {@code Observable} and that
14766 * determines the timeout window in which the subsequent source item must arrive in order to
14767 * continue the sequence
14768 * @param fallback
14769 * the fallback {@code ObservableSource} to switch to if the current {@code Observable} times out
14770 * @return the new {@code Observable} instance
14771 * @throws NullPointerException
14772 * if {@code firstTimeoutIndicator}, {@code itemTimeoutIndicator} or {@code fallback} is {@code null}
14773 * @see <a href="http://reactivex.io/documentation/operators/timeout.html">ReactiveX operators documentation: Timeout</a>
14774 */
14775 @CheckReturnValue
14776 @SchedulerSupport(SchedulerSupport.NONE)
14777 @NonNull
14778 public final <@NonNull U, @NonNull V> Observable<T> timeout(
14779 @NonNull ObservableSource<U> firstTimeoutIndicator,
14780 @NonNull Function<? super T, ? extends ObservableSource<V>> itemTimeoutIndicator,
14781 @NonNull ObservableSource<? extends T> fallback) {
14782 Objects.requireNonNull(firstTimeoutIndicator, "firstTimeoutIndicator is null");
14783 Objects.requireNonNull(fallback, "fallback is null");
14784 return timeout0(firstTimeoutIndicator, itemTimeoutIndicator, fallback);
14785 }
14786
14787 @NonNull
14788 private Observable<T> timeout0(long timeout, @NonNull TimeUnit unit,
14789 @Nullable ObservableSource<? extends T> fallback,
14790 @NonNull Scheduler scheduler) {
14791 Objects.requireNonNull(unit, "unit is null");
14792 Objects.requireNonNull(scheduler, "scheduler is null");
14793 return RxJavaPlugins.onAssembly(new ObservableTimeoutTimed<>(this, timeout, unit, scheduler, fallback));
14794 }
14795
14796 @NonNull
14797 private <U, V> Observable<T> timeout0(
14798 @NonNull ObservableSource<U> firstTimeoutIndicator,
14799 @NonNull Function<? super T, ? extends ObservableSource<V>> itemTimeoutIndicator,
14800 @Nullable ObservableSource<? extends T> fallback) {
14801 Objects.requireNonNull(itemTimeoutIndicator, "itemTimeoutIndicator is null");
14802 return RxJavaPlugins.onAssembly(new ObservableTimeout<>(this, firstTimeoutIndicator, itemTimeoutIndicator, fallback));
14803 }
14804
14805 /**
14806 * Returns an {@code Observable} that emits each item emitted by the current {@code Observable}, wrapped in a
14807 * {@link Timed} object.
14808 * <p>
14809 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/timestamp.v3.png" alt="">
14810 * <dl>
14811 * <dt><b>Scheduler:</b></dt>
14812 * <dd>{@code timestamp} does not operate on any particular scheduler but uses the current time
14813 * from the {@code computation} {@link Scheduler}.</dd>
14814 * </dl>
14815 *
14816 * @return the new {@code Observable} instance
14817 * @see <a href="http://reactivex.io/documentation/operators/timestamp.html">ReactiveX operators documentation: Timestamp</a>
14818 */
14819 @CheckReturnValue
14820 @SchedulerSupport(SchedulerSupport.NONE)
14821 @NonNull
14822 public final Observable<Timed<T>> timestamp() {
14823 return timestamp(TimeUnit.MILLISECONDS, Schedulers.computation());
14824 }
14825
14826 /**
14827 * Returns an {@code Observable} that emits each item emitted by the current {@code Observable}, wrapped in a
14828 * {@link Timed} object whose timestamps are provided by a specified {@link Scheduler}.
14829 * <p>
14830 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/timestamp.s.v3.png" alt="">
14831 * <dl>
14832 * <dt><b>Scheduler:</b></dt>
14833 * <dd>This operator does not operate on any particular scheduler but uses the current time
14834 * from the specified {@code Scheduler}.</dd>
14835 * </dl>
14836 *
14837 * @param scheduler
14838 * the {@code Scheduler} to use as a time source
14839 * @return the new {@code Observable} instance
14840 * @throws NullPointerException if {@code scheduler} is {@code null}
14841 * @see <a href="http://reactivex.io/documentation/operators/timestamp.html">ReactiveX operators documentation: Timestamp</a>
14842 */
14843 @CheckReturnValue
14844 @SchedulerSupport(SchedulerSupport.NONE) // Supplied scheduler is only used for creating timestamps.
14845 @NonNull
14846 public final Observable<Timed<T>> timestamp(@NonNull Scheduler scheduler) {
14847 return timestamp(TimeUnit.MILLISECONDS, scheduler);
14848 }
14849
14850 /**
14851 * Returns an {@code Observable} that emits each item emitted by the current {@code Observable}, wrapped in a
14852 * {@link Timed} object.
14853 * <p>
14854 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/timestamp.v3.png" alt="">
14855 * <dl>
14856 * <dt><b>Scheduler:</b></dt>
14857 * <dd>{@code timestamp} does not operate on any particular scheduler but uses the current time
14858 * from the {@code computation} {@link Scheduler}.</dd>
14859 * </dl>
14860 *
14861 * @param unit the time unit for the current time
14862 * @return the new {@code Observable} instance
14863 * @throws NullPointerException if {@code unit} is {@code null}
14864 * @see <a href="http://reactivex.io/documentation/operators/timestamp.html">ReactiveX operators documentation: Timestamp</a>
14865 */
14866 @CheckReturnValue
14867 @SchedulerSupport(SchedulerSupport.NONE)
14868 @NonNull
14869 public final Observable<Timed<T>> timestamp(@NonNull TimeUnit unit) {
14870 return timestamp(unit, Schedulers.computation());
14871 }
14872
14873 /**
14874 * Returns an {@code Observable} that emits each item emitted by the current {@code Observable}, wrapped in a
14875 * {@link Timed} object whose timestamps are provided by a specified {@link Scheduler}.
14876 * <p>
14877 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/timestamp.s.v3.png" alt="">
14878 * <dl>
14879 * <dt><b>Scheduler:</b></dt>
14880 * <dd>This operator does not operate on any particular scheduler but uses the current time
14881 * from the specified {@code Scheduler}.</dd>
14882 * </dl>
14883 *
14884 * @param unit the time unit for the current time
14885 * @param scheduler
14886 * the {@code Scheduler} to use as a time source
14887 * @return the new {@code Observable} instance
14888 * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null}
14889 * @see <a href="http://reactivex.io/documentation/operators/timestamp.html">ReactiveX operators documentation: Timestamp</a>
14890 */
14891 @CheckReturnValue
14892 @SchedulerSupport(SchedulerSupport.NONE) // Supplied scheduler is only used for creating timestamps.
14893 @NonNull
14894 public final Observable<Timed<T>> timestamp(@NonNull TimeUnit unit, @NonNull Scheduler scheduler) {
14895 Objects.requireNonNull(unit, "unit is null");
14896 Objects.requireNonNull(scheduler, "scheduler is null");
14897 return map(Functions.timestampWith(unit, scheduler));
14898 }
14899
14900 /**
14901 * Calls the specified converter function during assembly time and returns its resulting value.
14902 * <p>
14903 * This allows fluent conversion to any other type.
14904 * <dl>
14905 * <dt><b>Scheduler:</b></dt>
14906 * <dd>{@code to} does not operate by default on a particular {@link Scheduler}.</dd>
14907 * </dl>
14908 * <p>History: 2.1.7 - experimental
14909 * @param <R> the resulting object type
14910 * @param converter the function that receives the current {@code Observable} instance and returns a value
14911 * @return the converted value
14912 * @throws NullPointerException if {@code converter} is {@code null}
14913 * @since 2.2
14914 */
14915 @CheckReturnValue
14916 @SchedulerSupport(SchedulerSupport.NONE)
14917 @NonNull
14918 public final <@NonNull R> R to(@NonNull ObservableConverter<T, ? extends R> converter) {
14919 return Objects.requireNonNull(converter, "converter is null").apply(this);
14920 }
14921
14922 /**
14923 * Returns a {@link Single} that emits a single item, a {@link List} composed of all the items emitted by the
14924 * current and finite {@code Observable}.
14925 * <p>
14926 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/toList.2.v3.png" alt="">
14927 * <p>
14928 * Normally, an {@link ObservableSource} that returns multiple items will do so by invoking its {@link Observer}'s
14929 * {@link Observer#onNext onNext} method for each such item. You can change this behavior by having the
14930 * operator to compose a list of all of these items and then to invoke the {@link SingleObserver}'s {@code onSuccess}
14931 * method once, passing it the entire list, by calling the {@code Observable}'s {@code toList} method prior to
14932 * calling its {@link #subscribe} method.
14933 * <p>
14934 * Note that this operator requires the upstream to signal {@code onComplete} for the accumulated list to
14935 * be emitted. Sources that are infinite and never complete will never emit anything through this
14936 * operator and an infinite source may lead to a fatal {@link OutOfMemoryError}.
14937 * <dl>
14938 * <dt><b>Scheduler:</b></dt>
14939 * <dd>{@code toList} does not operate by default on a particular {@link Scheduler}.</dd>
14940 * </dl>
14941 *
14942 * @return the new {@code Single} instance
14943 * @see <a href="http://reactivex.io/documentation/operators/to.html">ReactiveX operators documentation: To</a>
14944 */
14945 @CheckReturnValue
14946 @SchedulerSupport(SchedulerSupport.NONE)
14947 @NonNull
14948 public final Single<@NonNull List<T>> toList() {
14949 return toList(16);
14950 }
14951
14952 /**
14953 * Returns a {@link Single} that emits a single item, a {@link List} composed of all the items emitted by the
14954 * current and finite {@code Observable}.
14955 * <p>
14956 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/toList.2.v3.png" alt="">
14957 * <p>
14958 * Normally, an {@link ObservableSource} that returns multiple items will do so by invoking its {@link Observer}'s
14959 * {@link Observer#onNext onNext} method for each such item. You can change this behavior by having the
14960 * operator to compose a list of all of these items and then to invoke the {@link SingleObserver}'s {@code onSuccess}
14961 * method once, passing it the entire list, by calling the {@code Observable}'s {@code toList} method prior to
14962 * calling its {@link #subscribe} method.
14963 * <p>
14964 * Note that this operator requires the upstream to signal {@code onComplete} for the accumulated list to
14965 * be emitted. Sources that are infinite and never complete will never emit anything through this
14966 * operator and an infinite source may lead to a fatal {@link OutOfMemoryError}.
14967 * <dl>
14968 * <dt><b>Scheduler:</b></dt>
14969 * <dd>{@code toList} does not operate by default on a particular {@link Scheduler}.</dd>
14970 * </dl>
14971 *
14972 * @param capacityHint
14973 * the number of elements expected from the current {@code Observable}
14974 * @return the new {@code Single} instance
14975 * @throws IllegalArgumentException if {@code capacityHint} is non-positive
14976 * @see <a href="http://reactivex.io/documentation/operators/to.html">ReactiveX operators documentation: To</a>
14977 */
14978 @CheckReturnValue
14979 @SchedulerSupport(SchedulerSupport.NONE)
14980 @NonNull
14981 public final Single<@NonNull List<T>> toList(int capacityHint) {
14982 ObjectHelper.verifyPositive(capacityHint, "capacityHint");
14983 return RxJavaPlugins.onAssembly(new ObservableToListSingle<>(this, capacityHint));
14984 }
14985
14986 /**
14987 * Returns a {@link Single} that emits a single item, a {@link Collection} (subclass) composed of all the items emitted by the
14988 * finite upstream {@code Observable}.
14989 * <p>
14990 * <img width="640" height="365" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/toList.o.c.png" alt="">
14991 * <p>
14992 * Normally, an {@link ObservableSource} that returns multiple items will do so by invoking its {@link Observer}'s
14993 * {@link Observer#onNext onNext} method for each such item. You can change this behavior by having the
14994 * operator to compose a collection of all of these items and then to invoke the {@link SingleObserver}'s {@code onSuccess}
14995 * method once, passing it the entire collection, by calling the {@code Observable}'s {@code toList} method prior to
14996 * calling its {@link #subscribe} method.
14997 * <p>
14998 * Note that this operator requires the upstream to signal {@code onComplete} for the accumulated collection to
14999 * be emitted. Sources that are infinite and never complete will never emit anything through this
15000 * operator and an infinite source may lead to a fatal {@link OutOfMemoryError}.
15001 * <dl>
15002 * <dt><b>Scheduler:</b></dt>
15003 * <dd>{@code toList} does not operate by default on a particular {@link Scheduler}.</dd>
15004 * </dl>
15005 *
15006 * @param <U> the subclass of a collection of Ts
15007 * @param collectionSupplier
15008 * the {@link Supplier} returning the collection (for each individual {@code Observer}) to be filled in
15009 * @return the new {@code Single} instance
15010 * @throws NullPointerException if {@code collectionSupplier} is {@code null}
15011 * @see <a href="http://reactivex.io/documentation/operators/to.html">ReactiveX operators documentation: To</a>
15012 */
15013 @CheckReturnValue
15014 @SchedulerSupport(SchedulerSupport.NONE)
15015 @NonNull
15016 public final <@NonNull U extends Collection<? super T>> Single<U> toList(@NonNull Supplier<U> collectionSupplier) {
15017 Objects.requireNonNull(collectionSupplier, "collectionSupplier is null");
15018 return RxJavaPlugins.onAssembly(new ObservableToListSingle<>(this, collectionSupplier));
15019 }
15020
15021 /**
15022 * Returns a {@link Single} that emits a single {@link HashMap} containing all items emitted by the
15023 * current and finite {@code Observable}, mapped by the keys returned by a specified
15024 * {@code keySelector} function.
15025 * <p>
15026 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/toMap.2.v3.png" alt="">
15027 * <p>
15028 * If more than one source item maps to the same key, the {@code HashMap} will contain the latest of those items.
15029 * <p>
15030 * Note that this operator requires the upstream to signal {@code onComplete} for the accumulated {@code HashMap} to
15031 * be emitted. Sources that are infinite and never complete will never emit anything through this
15032 * operator and an infinite source may lead to a fatal {@link OutOfMemoryError}.
15033 * <dl>
15034 * <dt><b>Scheduler:</b></dt>
15035 * <dd>{@code toMap} does not operate by default on a particular {@link Scheduler}.</dd>
15036 * </dl>
15037 *
15038 * @param <K> the key type of the Map
15039 * @param keySelector
15040 * the function that extracts the key from a source item to be used in the {@code HashMap}
15041 * @return the new {@code Single} instance
15042 * @throws NullPointerException if {@code keySelector} is {@code null}
15043 * @see <a href="http://reactivex.io/documentation/operators/to.html">ReactiveX operators documentation: To</a>
15044 */
15045 @CheckReturnValue
15046 @SchedulerSupport(SchedulerSupport.NONE)
15047 @NonNull
15048 public final <@NonNull K> Single<@NonNull Map<K, T>> toMap(@NonNull Function<? super T, ? extends K> keySelector) {
15049 Objects.requireNonNull(keySelector, "keySelector is null");
15050 return collect(HashMapSupplier.asSupplier(), Functions.toMapKeySelector(keySelector));
15051 }
15052
15053 /**
15054 * Returns a {@link Single} that emits a single {@link HashMap} containing values corresponding to items emitted by the
15055 * current and finite {@code Observable}, mapped by the keys and values returned by the given selector functions.
15056 * <p>
15057 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/toMap.2.v3.png" alt="">
15058 * <p>
15059 * If more than one source item maps to the same key, the {@code HashMap} will contain a single entry that
15060 * corresponds to the latest of those items.
15061 * <p>
15062 * Note that this operator requires the upstream to signal {@code onComplete} for the accumulated {@code HashMap} to
15063 * be emitted. Sources that are infinite and never complete will never emit anything through this
15064 * operator and an infinite source may lead to a fatal {@link OutOfMemoryError}.
15065 * <dl>
15066 * <dt><b>Scheduler:</b></dt>
15067 * <dd>{@code toMap} does not operate by default on a particular {@link Scheduler}.</dd>
15068 * </dl>
15069 *
15070 * @param <K> the key type of the {@code HashMap}
15071 * @param <V> the value type of the {@code HashMap}
15072 * @param keySelector
15073 * the function that extracts the key from a source item to be used in the {@code HashMap}
15074 * @param valueSelector
15075 * the function that extracts the value from a source item to be used in the {@code HashMap}
15076 * @return the new {@code Single} instance
15077 * @throws NullPointerException if {@code keySelector} or {@code valueSelector} is {@code null}
15078 * @see <a href="http://reactivex.io/documentation/operators/to.html">ReactiveX operators documentation: To</a>
15079 */
15080 @CheckReturnValue
15081 @SchedulerSupport(SchedulerSupport.NONE)
15082 @NonNull
15083 public final <@NonNull K, @NonNull V> Single<Map<K, V>> toMap(
15084 @NonNull Function<? super T, ? extends K> keySelector,
15085 @NonNull Function<? super T, ? extends V> valueSelector) {
15086 Objects.requireNonNull(keySelector, "keySelector is null");
15087 Objects.requireNonNull(valueSelector, "valueSelector is null");
15088 return collect(HashMapSupplier.asSupplier(), Functions.toMapKeyValueSelector(keySelector, valueSelector));
15089 }
15090
15091 /**
15092 * Returns a {@link Single} that emits a single {@link Map} (subclass), returned by a specified {@code mapFactory} function, that
15093 * contains keys and values extracted from the items, via selector functions, emitted by the current and finite {@code Observable}.
15094 * <p>
15095 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/toMap.2.v3.png" alt="">
15096 * <p>
15097 * Note that this operator requires the upstream to signal {@code onComplete} for the accumulated {@code Map} to
15098 * be emitted. Sources that are infinite and never complete will never emit anything through this
15099 * operator and an infinite source may lead to a fatal {@link OutOfMemoryError}.
15100 * <dl>
15101 * <dt><b>Scheduler:</b></dt>
15102 * <dd>{@code toMap} does not operate by default on a particular {@link Scheduler}.</dd>
15103 * </dl>
15104 *
15105 * @param <K> the key type of the {@code Map}
15106 * @param <V> the value type of the {@code Map}
15107 * @param keySelector
15108 * the function that extracts the key from a source item to be used in the {@code Map}
15109 * @param valueSelector
15110 * the function that extracts the value from the source items to be used as value in the {@code Map}
15111 * @param mapSupplier
15112 * the function that returns a {@code Map} instance to be used
15113 * @return the new {@code Single} instance
15114 * @throws NullPointerException if {@code keySelector}, {@code valueSelector} or {@code mapSupplier} is {@code null}
15115 * @see <a href="http://reactivex.io/documentation/operators/to.html">ReactiveX operators documentation: To</a>
15116 */
15117 @CheckReturnValue
15118 @SchedulerSupport(SchedulerSupport.NONE)
15119 @NonNull
15120 public final <@NonNull K, @NonNull V> Single<Map<K, V>> toMap(
15121 @NonNull Function<? super T, ? extends K> keySelector,
15122 @NonNull Function<? super T, ? extends V> valueSelector,
15123 @NonNull Supplier<? extends Map<K, V>> mapSupplier) {
15124 Objects.requireNonNull(keySelector, "keySelector is null");
15125 Objects.requireNonNull(valueSelector, "valueSelector is null");
15126 Objects.requireNonNull(mapSupplier, "mapSupplier is null");
15127 return collect(mapSupplier, Functions.toMapKeyValueSelector(keySelector, valueSelector));
15128 }
15129
15130 /**
15131 * Returns a {@link Single} that emits a single {@link HashMap} that contains an {@link ArrayList} of items emitted by the
15132 * current and finite {@code Observable} keyed by a specified {@code keySelector} function.
15133 * <p>
15134 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/toMultiMap.2.v3.png" alt="">
15135 * <p>
15136 * Note that this operator requires the upstream to signal {@code onComplete} for the accumulated {@code HashMap} to
15137 * be emitted. Sources that are infinite and never complete will never emit anything through this
15138 * operator and an infinite source may lead to a fatal {@link OutOfMemoryError}.
15139 * <dl>
15140 * <dt><b>Scheduler:</b></dt>
15141 * <dd>{@code toMultimap} does not operate by default on a particular {@link Scheduler}.</dd>
15142 * </dl>
15143 *
15144 * @param <K> the key type of the {@code HashMap}
15145 * @param keySelector
15146 * the function that extracts the key from the source items to be used as key in the {@code HashMap}
15147 * @return the new {@code Single} instance
15148 * @throws NullPointerException if {@code keySelector} is {@code null}
15149 * @see <a href="http://reactivex.io/documentation/operators/to.html">ReactiveX operators documentation: To</a>
15150 */
15151 @CheckReturnValue
15152 @SchedulerSupport(SchedulerSupport.NONE)
15153 @NonNull
15154 public final <@NonNull K> Single<@NonNull Map<K, Collection<T>>> toMultimap(@NonNull Function<? super T, ? extends K> keySelector) {
15155 Function<? super T, ? extends T> valueSelector = Functions.identity();
15156 Supplier<Map<K, Collection<T>>> mapSupplier = HashMapSupplier.asSupplier();
15157 Function<K, List<T>> collectionFactory = ArrayListSupplier.asFunction();
15158 return toMultimap(keySelector, valueSelector, mapSupplier, collectionFactory);
15159 }
15160
15161 /**
15162 * Returns a {@link Single} that emits a single {@link HashMap} that contains an {@link ArrayList} of values extracted by a
15163 * specified {@code valueSelector} function from items emitted by the current and finite {@code Observable},
15164 * keyed by a specified {@code keySelector} function.
15165 * <p>
15166 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/toMultiMap.2.v3.png" alt="">
15167 * <p>
15168 * Note that this operator requires the upstream to signal {@code onComplete} for the accumulated {@code HashMap} to
15169 * be emitted. Sources that are infinite and never complete will never emit anything through this
15170 * operator and an infinite source may lead to a fatal {@link OutOfMemoryError}.
15171 * <dl>
15172 * <dt><b>Scheduler:</b></dt>
15173 * <dd>{@code toMultimap} does not operate by default on a particular {@link Scheduler}.</dd>
15174 * </dl>
15175 *
15176 * @param <K> the key type of the {@code HashMap}
15177 * @param <V> the value type of the {@code HashMap}
15178 * @param keySelector
15179 * the function that extracts a key from the source items to be used as key in the {@code HashMap}
15180 * @param valueSelector
15181 * the function that extracts a value from the source items to be used as value in the {@code HashMap}
15182 * @return the new {@code Single} instance
15183 * @throws NullPointerException if {@code keySelector} or {@code valueSelector} is {@code null}
15184 * @see <a href="http://reactivex.io/documentation/operators/to.html">ReactiveX operators documentation: To</a>
15185 */
15186 @CheckReturnValue
15187 @SchedulerSupport(SchedulerSupport.NONE)
15188 @NonNull
15189 public final <@NonNull K, @NonNull V> Single<@NonNull Map<K, Collection<V>>> toMultimap(@NonNull Function<? super T, ? extends K> keySelector, Function<? super T, ? extends V> valueSelector) {
15190 Supplier<Map<K, Collection<V>>> mapSupplier = HashMapSupplier.asSupplier();
15191 Function<K, List<V>> collectionFactory = ArrayListSupplier.asFunction();
15192 return toMultimap(keySelector, valueSelector, mapSupplier, collectionFactory);
15193 }
15194
15195 /**
15196 * Returns a {@link Single} that emits a single {@code Map} (subclass), returned by a specified {@code mapFactory} function, that
15197 * contains a custom {@link Collection} of values, extracted by a specified {@code valueSelector} function from
15198 * items emitted by the current and finite {@code Observable}, and keyed by the {@code keySelector} function.
15199 * <p>
15200 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/toMultiMap.2.v3.png" alt="">
15201 * <p>
15202 * Note that this operator requires the upstream to signal {@code onComplete} for the accumulated {@code Map} to
15203 * be emitted. Sources that are infinite and never complete will never emit anything through this
15204 * operator and an infinite source may lead to a fatal {@link OutOfMemoryError}.
15205 * <dl>
15206 * <dt><b>Scheduler:</b></dt>
15207 * <dd>{@code toMultimap} does not operate by default on a particular {@link Scheduler}.</dd>
15208 * </dl>
15209 *
15210 * @param <K> the key type of the {@code Map}
15211 * @param <V> the value type of the {@code Map}
15212 * @param keySelector
15213 * the function that extracts a key from the source items to be used as the key in the {@code Map}
15214 * @param valueSelector
15215 * the function that extracts a value from the source items to be used as the value in the {@code Map}
15216 * @param mapSupplier
15217 * the function that returns a {@code Map} instance to be used
15218 * @param collectionFactory
15219 * the function that returns a {@code Collection} instance for a particular key to be used in the {@code Map}
15220 * @return the new {@code Single} instance
15221 * @throws NullPointerException if {@code keySelector}, {@code valueSelector}, {@code mapSupplier} or {@code collectionFactory} is {@code null}
15222 * @see <a href="http://reactivex.io/documentation/operators/to.html">ReactiveX operators documentation: To</a>
15223 */
15224 @CheckReturnValue
15225 @SchedulerSupport(SchedulerSupport.NONE)
15226 @NonNull
15227 public final <@NonNull K, @NonNull V> Single<@NonNull Map<K, Collection<V>>> toMultimap(
15228 @NonNull Function<? super T, ? extends K> keySelector,
15229 @NonNull Function<? super T, ? extends V> valueSelector,
15230 @NonNull Supplier<? extends Map<K, Collection<V>>> mapSupplier,
15231 @NonNull Function<? super K, ? extends Collection<? super V>> collectionFactory) {
15232 Objects.requireNonNull(keySelector, "keySelector is null");
15233 Objects.requireNonNull(valueSelector, "valueSelector is null");
15234 Objects.requireNonNull(mapSupplier, "mapSupplier is null");
15235 Objects.requireNonNull(collectionFactory, "collectionFactory is null");
15236 return collect(mapSupplier, Functions.toMultimapKeyValueSelector(keySelector, valueSelector, collectionFactory));
15237 }
15238
15239 /**
15240 * Returns a {@link Single} that emits a single {@link Map} (subclass), returned by a specified {@code mapFactory} function, that
15241 * contains an {@link ArrayList} of values, extracted by a specified {@code valueSelector} function from items
15242 * emitted by the current and finite {@code Observable} and keyed by the {@code keySelector} function.
15243 * <p>
15244 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/toMultiMap.2.v3.png" alt="">
15245 * <p>
15246 * Note that this operator requires the upstream to signal {@code onComplete} for the accumulated {@code Map} to
15247 * be emitted. Sources that are infinite and never complete will never emit anything through this
15248 * operator and an infinite source may lead to a fatal {@link OutOfMemoryError}.
15249 * <dl>
15250 * <dt><b>Scheduler:</b></dt>
15251 * <dd>{@code toMultimap} does not operate by default on a particular {@link Scheduler}.</dd>
15252 * </dl>
15253 *
15254 * @param <K> the key type of the {@code Map}
15255 * @param <V> the value type of the {@code Map}
15256 * @param keySelector
15257 * the function that extracts a key from the source items to be used as the key in the {@code Map}
15258 * @param valueSelector
15259 * the function that extracts a value from the source items to be used as the value in the {@code Map}
15260 * @param mapSupplier
15261 * the function that returns a {@code Map} instance to be used
15262 * @return the new {@code Single} instance
15263 * @throws NullPointerException if {@code keySelector}, {@code valueSelector} or {@code mapSupplier} is {@code null}
15264 * @see <a href="http://reactivex.io/documentation/operators/to.html">ReactiveX operators documentation: To</a>
15265 */
15266 @CheckReturnValue
15267 @SchedulerSupport(SchedulerSupport.NONE)
15268 @NonNull
15269 public final <@NonNull K, @NonNull V> Single<@NonNull Map<K, Collection<V>>> toMultimap(
15270 @NonNull Function<? super T, ? extends K> keySelector,
15271 @NonNull Function<? super T, ? extends V> valueSelector,
15272 @NonNull Supplier<Map<K, Collection<V>>> mapSupplier
15273 ) {
15274 return toMultimap(keySelector, valueSelector, mapSupplier, ArrayListSupplier.asFunction());
15275 }
15276
15277 /**
15278 * Converts the current {@code Observable} into a {@link Flowable} by applying the specified backpressure strategy.
15279 * <p>
15280 * Marble diagrams for the various backpressure strategies are as follows:
15281 * <ul>
15282 * <li>{@link BackpressureStrategy#BUFFER}
15283 * <p>
15284 * <img width="640" height="274" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/toFlowable.o.buffer.png" alt="">
15285 * </li>
15286 * <li>{@link BackpressureStrategy#DROP}
15287 * <p>
15288 * <img width="640" height="389" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/toFlowable.o.drop.png" alt="">
15289 * </li>
15290 * <li>{@link BackpressureStrategy#LATEST}
15291 * <p>
15292 * <img width="640" height="297" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/toFlowable.o.latest.png" alt="">
15293 * </li>
15294 * <li>{@link BackpressureStrategy#ERROR}
15295 * <p>
15296 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/toFlowable.o.error.png" alt="">
15297 * </li>
15298 * <li>{@link BackpressureStrategy#MISSING}
15299 * <p>
15300 * <img width="640" height="412" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/toFlowable.o.missing.png" alt="">
15301 * </li>
15302 * </ul>
15303 * <dl>
15304 * <dt><b>Backpressure:</b></dt>
15305 * <dd>The operator applies the chosen backpressure strategy of {@link BackpressureStrategy} enum.</dd>
15306 * <dt><b>Scheduler:</b></dt>
15307 * <dd>{@code toFlowable} does not operate by default on a particular {@link Scheduler}.</dd>
15308 * </dl>
15309 *
15310 * @param strategy the backpressure strategy to apply
15311 * @return the new {@code Flowable} instance
15312 * @throws NullPointerException if {@code strategy} is {@code null}
15313 */
15314 @BackpressureSupport(BackpressureKind.SPECIAL)
15315 @CheckReturnValue
15316 @SchedulerSupport(SchedulerSupport.NONE)
15317 @NonNull
15318 public final Flowable<T> toFlowable(@NonNull BackpressureStrategy strategy) {
15319 Objects.requireNonNull(strategy, "strategy is null");
15320 Flowable<T> f = new FlowableFromObservable<>(this);
15321 switch (strategy) {
15322 case DROP:
15323 return f.onBackpressureDrop();
15324 case LATEST:
15325 return f.onBackpressureLatest();
15326 case MISSING:
15327 return f;
15328 case ERROR:
15329 return RxJavaPlugins.onAssembly(new FlowableOnBackpressureError<>(f));
15330 default:
15331 return f.onBackpressureBuffer();
15332 }
15333 }
15334
15335 /**
15336 * Returns a {@link Single} that emits a {@link List} that contains the items emitted by the current and finite {@code Observable}, in a
15337 * sorted order. Each item emitted by the current {@code Observable} must implement {@link Comparable} with respect to all
15338 * other items in the sequence.
15339 *
15340 * <p>
15341 * If any item emitted by the current {@code Observable} does not implement {@code Comparable} with respect to
15342 * all other items emitted by the current {@code Observable}, no items will be emitted and the
15343 * sequence is terminated with a {@link ClassCastException}.
15344 * <p>
15345 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/toSortedList.2.v3.png" alt="">
15346 * <p>
15347 * Note that this operator requires the upstream to signal {@code onComplete} for the accumulated {@code List} to
15348 * be emitted. Sources that are infinite and never complete will never emit anything through this
15349 * operator and an infinite source may lead to a fatal {@link OutOfMemoryError}.
15350 * <dl>
15351 * <dt><b>Scheduler:</b></dt>
15352 * <dd>{@code toSortedList} does not operate by default on a particular {@link Scheduler}.</dd>
15353 * </dl>
15354 * @return the new {@code Single} instance
15355 * @see <a href="http://reactivex.io/documentation/operators/to.html">ReactiveX operators documentation: To</a>
15356 * @see #toSortedList(int)
15357 * @see #toSortedList(Comparator)
15358 */
15359 @CheckReturnValue
15360 @SchedulerSupport(SchedulerSupport.NONE)
15361 @NonNull
15362 public final Single<@NonNull List<T>> toSortedList() {
15363 return toSortedList(Functions.naturalComparator());
15364 }
15365
15366 /**
15367 * Returns a {@link Single} that emits a {@link List} that contains the items emitted by the current and finite {@code Observable}, in a
15368 * sorted order based on a specified comparison function.
15369 * <p>
15370 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/toSortedList.f.2.v3.png" alt="">
15371 * <p>
15372 * Note that this operator requires the upstream to signal {@code onComplete} for the accumulated {@code List} to
15373 * be emitted. Sources that are infinite and never complete will never emit anything through this
15374 * operator and an infinite source may lead to a fatal {@link OutOfMemoryError}.
15375 * <dl>
15376 * <dt><b>Scheduler:</b></dt>
15377 * <dd>{@code toSortedList} does not operate by default on a particular {@link Scheduler}.</dd>
15378 * </dl>
15379 *
15380 * @param comparator
15381 * a function that compares two items emitted by the current {@code Observable} and returns an {@code int}
15382 * that indicates their sort order
15383 * @return the new {@code Single} instance
15384 * @throws NullPointerException if {@code comparator} is {@code null}
15385 * @see <a href="http://reactivex.io/documentation/operators/to.html">ReactiveX operators documentation: To</a>
15386 */
15387 @CheckReturnValue
15388 @SchedulerSupport(SchedulerSupport.NONE)
15389 @NonNull
15390 public final Single<@NonNull List<T>> toSortedList(@NonNull Comparator<? super T> comparator) {
15391 Objects.requireNonNull(comparator, "comparator is null");
15392 return toList().map(Functions.listSorter(comparator));
15393 }
15394
15395 /**
15396 * Returns a {@link Single} that emits a {@link List} that contains the items emitted by the current and finite {@code Observable}, in a
15397 * sorted order based on a specified comparison function.
15398 * <p>
15399 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/toSortedList.f.2.v3.png" alt="">
15400 * <p>
15401 * Note that this operator requires the upstream to signal {@code onComplete} for the accumulated {@code List} to
15402 * be emitted. Sources that are infinite and never complete will never emit anything through this
15403 * operator and an infinite source may lead to a fatal {@link OutOfMemoryError}.
15404 * <dl>
15405 * <dt><b>Scheduler:</b></dt>
15406 * <dd>{@code toSortedList} does not operate by default on a particular {@link Scheduler}.</dd>
15407 * </dl>
15408 *
15409 * @param comparator
15410 * a function that compares two items emitted by the current {@code Observable} and returns an {@code int}
15411 * that indicates their sort order
15412 * @param capacityHint
15413 * the initial capacity of the {@code List} used to accumulate items before sorting
15414 * @return the new {@code Single} instance
15415 * @throws NullPointerException if {@code comparator} is {@code null}
15416 * @throws IllegalArgumentException if {@code capacityHint} is non-positive
15417 * @see <a href="http://reactivex.io/documentation/operators/to.html">ReactiveX operators documentation: To</a>
15418 * @since 2.0
15419 */
15420 @CheckReturnValue
15421 @SchedulerSupport(SchedulerSupport.NONE)
15422 @NonNull
15423 public final Single<@NonNull List<T>> toSortedList(@NonNull Comparator<? super T> comparator, int capacityHint) {
15424 Objects.requireNonNull(comparator, "comparator is null");
15425 return toList(capacityHint).map(Functions.listSorter(comparator));
15426 }
15427
15428 /**
15429 * Returns a {@link Single} that emits a {@link List} that contains the items emitted by the current and finite {@code Observable}, in a
15430 * sorted order. Each item emitted by the current {@code Observable} must implement {@link Comparable} with respect to all
15431 * other items in the sequence.
15432 * <p>
15433 * If any item emitted by the current {@code Observable} does not implement {@code Comparable} with respect to
15434 * all other items emitted by the current {@code Observable}, no items will be emitted and the
15435 * sequence is terminated with a {@link ClassCastException}.
15436 * <p>
15437 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/toSortedList.2.v3.png" alt="">
15438 * <p>
15439 * Note that this operator requires the upstream to signal {@code onComplete} for the accumulated {@code List} to
15440 * be emitted. Sources that are infinite and never complete will never emit anything through this
15441 * operator and an infinite source may lead to a fatal {@link OutOfMemoryError}.
15442 * <dl>
15443 * <dt><b>Scheduler:</b></dt>
15444 * <dd>{@code toSortedList} does not operate by default on a particular {@link Scheduler}.</dd>
15445 * </dl>
15446 *
15447 * @param capacityHint
15448 * the initial capacity of the {@code List} used to accumulate items before sorting
15449 * @return the new {@code Single} instance
15450 * @throws IllegalArgumentException if {@code capacityHint} is non-positive
15451 * @see <a href="http://reactivex.io/documentation/operators/to.html">ReactiveX operators documentation: To</a>
15452 * @since 2.0
15453 * @see #toSortedList(Comparator, int)
15454 */
15455 @CheckReturnValue
15456 @SchedulerSupport(SchedulerSupport.NONE)
15457 @NonNull
15458 public final Single<@NonNull List<T>> toSortedList(int capacityHint) {
15459 return toSortedList(Functions.naturalComparator(), capacityHint);
15460 }
15461
15462 /**
15463 * Return an {@code Observable} that schedules the downstream {@link Observer}s' {@code dispose} calls
15464 * aimed at the current {@code Observable} on the given {@link Scheduler}.
15465 * <p>
15466 * <img width="640" height="453" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/unsubscribeOn.o.png" alt="">
15467 * <dl>
15468 * <dt><b>Scheduler:</b></dt>
15469 * <dd>You specify which {@code Scheduler} this operator will use.</dd>
15470 * </dl>
15471 *
15472 * @param scheduler
15473 * the {@code Scheduler} to perform the call to {@code dispose()} of the upstream {@link Disposable}
15474 * @return the new {@code Observable} instance
15475 * @throws NullPointerException if {@code scheduler} is {@code null}
15476 * @see <a href="http://reactivex.io/documentation/operators/subscribeon.html">ReactiveX operators documentation: SubscribeOn</a>
15477 */
15478 @CheckReturnValue
15479 @SchedulerSupport(SchedulerSupport.CUSTOM)
15480 @NonNull
15481 public final Observable<T> unsubscribeOn(@NonNull Scheduler scheduler) {
15482 Objects.requireNonNull(scheduler, "scheduler is null");
15483 return RxJavaPlugins.onAssembly(new ObservableUnsubscribeOn<>(this, scheduler));
15484 }
15485
15486 /**
15487 * Returns an {@code Observable} that emits windows of items it collects from the current {@code Observable}. The resulting
15488 * {@code Observable} emits connected, non-overlapping windows, each containing {@code count} items. When the current
15489 * {@code Observable} completes or encounters an error, the resulting {@code Observable} emits the current window and
15490 * propagates the notification from the current {@code Observable}.
15491 * <p>
15492 * <img width="640" height="400" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/window3.v3.png" alt="">
15493 * <dl>
15494 * <dt><b>Scheduler:</b></dt>
15495 * <dd>This version of {@code window} does not operate by default on a particular {@link Scheduler}.</dd>
15496 * </dl>
15497 *
15498 * @param count
15499 * the maximum size of each window before it should be emitted
15500 * @return the new {@code Observable} instance
15501 * @throws IllegalArgumentException if {@code count} is non-positive
15502 * @see <a href="http://reactivex.io/documentation/operators/window.html">ReactiveX operators documentation: Window</a>
15503 */
15504 @CheckReturnValue
15505 @SchedulerSupport(SchedulerSupport.NONE)
15506 @NonNull
15507 public final Observable<Observable<T>> window(long count) {
15508 return window(count, count, bufferSize());
15509 }
15510
15511 /**
15512 * Returns an {@code Observable} that emits windows of items it collects from the current {@code Observable}. The resulting
15513 * {@code Observable} emits windows every {@code skip} items, each containing no more than {@code count} items. When
15514 * the current {@code Observable} completes or encounters an error, the resulting {@code Observable} emits the current window
15515 * and propagates the notification from the current {@code Observable}.
15516 * <p>
15517 * <img width="640" height="365" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/window4.v3.png" alt="">
15518 * <dl>
15519 * <dt><b>Scheduler:</b></dt>
15520 * <dd>This version of {@code window} does not operate by default on a particular {@link Scheduler}.</dd>
15521 * </dl>
15522 *
15523 * @param count
15524 * the maximum size of each window before it should be emitted
15525 * @param skip
15526 * how many items need to be skipped before starting a new window. Note that if {@code skip} and
15527 * {@code count} are equal this is the same operation as {@link #window(long)}.
15528 * @return the new {@code Observable} instance
15529 * @throws IllegalArgumentException if {@code count} or {@code skip} is non-positive
15530 * @see <a href="http://reactivex.io/documentation/operators/window.html">ReactiveX operators documentation: Window</a>
15531 */
15532 @CheckReturnValue
15533 @SchedulerSupport(SchedulerSupport.NONE)
15534 @NonNull
15535 public final Observable<Observable<T>> window(long count, long skip) {
15536 return window(count, skip, bufferSize());
15537 }
15538
15539 /**
15540 * Returns an {@code Observable} that emits windows of items it collects from the current {@code Observable}. The resulting
15541 * {@code Observable} emits windows every {@code skip} items, each containing no more than {@code count} items. When
15542 * the current {@code Observable} completes or encounters an error, the resulting {@code Observable} emits the current window
15543 * and propagates the notification from the current {@code Observable}.
15544 * <p>
15545 * <img width="640" height="365" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/window4.v3.png" alt="">
15546 * <dl>
15547 * <dt><b>Scheduler:</b></dt>
15548 * <dd>This version of {@code window} does not operate by default on a particular {@link Scheduler}.</dd>
15549 * </dl>
15550 *
15551 * @param count
15552 * the maximum size of each window before it should be emitted
15553 * @param skip
15554 * how many items need to be skipped before starting a new window. Note that if {@code skip} and
15555 * {@code count} are equal this is the same operation as {@link #window(long)}.
15556 * @param bufferSize
15557 * the capacity hint for the buffer in the inner windows
15558 * @return the new {@code Observable} instance
15559 * @throws IllegalArgumentException if {@code count}, {@code skip} or {@code bufferSize} is non-positive
15560 * @see <a href="http://reactivex.io/documentation/operators/window.html">ReactiveX operators documentation: Window</a>
15561 */
15562 @CheckReturnValue
15563 @SchedulerSupport(SchedulerSupport.NONE)
15564 @NonNull
15565 public final Observable<Observable<T>> window(long count, long skip, int bufferSize) {
15566 ObjectHelper.verifyPositive(count, "count");
15567 ObjectHelper.verifyPositive(skip, "skip");
15568 ObjectHelper.verifyPositive(bufferSize, "bufferSize");
15569 return RxJavaPlugins.onAssembly(new ObservableWindow<>(this, count, skip, bufferSize));
15570 }
15571
15572 /**
15573 * Returns an {@code Observable} that emits windows of items it collects from the current {@code Observable}. The resulting
15574 * {@code Observable} starts a new window periodically, as determined by the {@code timeskip} argument. It emits
15575 * each window after a fixed timespan, specified by the {@code timespan} argument. When the current
15576 * {@code Observable} completes or encounters an error, the resulting {@code Observable} emits the
15577 * current window and propagates the notification from the current {@code Observable}.
15578 * <p>
15579 * <img width="640" height="335" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/window7.v3.png" alt="">
15580 * <p>
15581 * Note that ignoring windows or subscribing later (i.e., on another thread) will result in
15582 * so-called window abandonment where a window may not contain any elements. In this case, subsequent
15583 * elements will be dropped until the condition for the next window boundary is satisfied. The behavior is
15584 * a trade-off for ensuring upstream cancellation can happen under some race conditions.
15585 * <dl>
15586 * <dt><b>Scheduler:</b></dt>
15587 * <dd>This version of {@code window} operates by default on the {@code computation} {@link Scheduler}.</dd>
15588 * </dl>
15589 *
15590 * @param timespan
15591 * the period of time each window collects items before it should be emitted
15592 * @param timeskip
15593 * the period of time after which a new window will be created
15594 * @param unit
15595 * the unit of time that applies to the {@code timespan} and {@code timeskip} arguments
15596 * @return the new {@code Observable} instance
15597 * @throws NullPointerException if {@code unit} is {@code null}
15598 * @throws IllegalArgumentException if {@code timespan} or {@code timeskip} is non-positive
15599 * @see <a href="http://reactivex.io/documentation/operators/window.html">ReactiveX operators documentation: Window</a>
15600 */
15601 @CheckReturnValue
15602 @SchedulerSupport(SchedulerSupport.COMPUTATION)
15603 @NonNull
15604 public final Observable<Observable<T>> window(long timespan, long timeskip, @NonNull TimeUnit unit) {
15605 return window(timespan, timeskip, unit, Schedulers.computation(), bufferSize());
15606 }
15607
15608 /**
15609 * Returns an {@code Observable} that emits windows of items it collects from the current {@code Observable}. The resulting
15610 * {@code Observable} starts a new window periodically, as determined by the {@code timeskip} argument. It emits
15611 * each window after a fixed timespan, specified by the {@code timespan} argument. When the current
15612 * {@code Observable} completes or encounters an error, the resulting {@code Observable} emits the
15613 * current window and propagates the notification from the current {@code Observable}.
15614 * <p>
15615 * <img width="640" height="335" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/window7.s.v3.png" alt="">
15616 * <p>
15617 * Note that ignoring windows or subscribing later (i.e., on another thread) will result in
15618 * so-called window abandonment where a window may not contain any elements. In this case, subsequent
15619 * elements will be dropped until the condition for the next window boundary is satisfied. The behavior is
15620 * a trade-off for ensuring upstream cancellation can happen under some race conditions.
15621 * <dl>
15622 * <dt><b>Scheduler:</b></dt>
15623 * <dd>You specify which {@link Scheduler} this operator will use.</dd>
15624 * </dl>
15625 *
15626 * @param timespan
15627 * the period of time each window collects items before it should be emitted
15628 * @param timeskip
15629 * the period of time after which a new window will be created
15630 * @param unit
15631 * the unit of time that applies to the {@code timespan} and {@code timeskip} arguments
15632 * @param scheduler
15633 * the {@code Scheduler} to use when determining the end and start of a window
15634 * @return the new {@code Observable} instance
15635 * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null}
15636 * @throws IllegalArgumentException if {@code timespan} or {@code timeskip} is non-positive
15637 * @see <a href="http://reactivex.io/documentation/operators/window.html">ReactiveX operators documentation: Window</a>
15638 */
15639 @CheckReturnValue
15640 @SchedulerSupport(SchedulerSupport.CUSTOM)
15641 @NonNull
15642 public final Observable<Observable<T>> window(long timespan, long timeskip, @NonNull TimeUnit unit, @NonNull Scheduler scheduler) {
15643 return window(timespan, timeskip, unit, scheduler, bufferSize());
15644 }
15645
15646 /**
15647 * Returns an {@code Observable} that emits windows of items it collects from the current {@code Observable}. The resulting
15648 * {@code Observable} starts a new window periodically, as determined by the {@code timeskip} argument. It emits
15649 * each window after a fixed timespan, specified by the {@code timespan} argument. When the current
15650 * {@code Observable} completes or encounters an error, the resulting {@code Observable} emits the
15651 * current window and propagates the notification from the current {@code Observable}.
15652 * <p>
15653 * <img width="640" height="335" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/window7.s.v3.png" alt="">
15654 * <p>
15655 * Note that ignoring windows or subscribing later (i.e., on another thread) will result in
15656 * so-called window abandonment where a window may not contain any elements. In this case, subsequent
15657 * elements will be dropped until the condition for the next window boundary is satisfied. The behavior is
15658 * a trade-off for ensuring upstream cancellation can happen under some race conditions.
15659 * <dl>
15660 * <dt><b>Scheduler:</b></dt>
15661 * <dd>You specify which {@link Scheduler} this operator will use.</dd>
15662 * </dl>
15663 *
15664 * @param timespan
15665 * the period of time each window collects items before it should be emitted
15666 * @param timeskip
15667 * the period of time after which a new window will be created
15668 * @param unit
15669 * the unit of time that applies to the {@code timespan} and {@code timeskip} arguments
15670 * @param scheduler
15671 * the {@code Scheduler} to use when determining the end and start of a window
15672 * @param bufferSize
15673 * the capacity hint for the buffer in the inner windows
15674 * @return the new {@code Observable} instance
15675 * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null}
15676 * @throws IllegalArgumentException if {@code timespan}, {@code timeskip} or {@code bufferSize} is non-positive
15677 * @see <a href="http://reactivex.io/documentation/operators/window.html">ReactiveX operators documentation: Window</a>
15678 */
15679 @CheckReturnValue
15680 @SchedulerSupport(SchedulerSupport.CUSTOM)
15681 @NonNull
15682 public final Observable<Observable<T>> window(long timespan, long timeskip, @NonNull TimeUnit unit, @NonNull Scheduler scheduler, int bufferSize) {
15683 ObjectHelper.verifyPositive(timespan, "timespan");
15684 ObjectHelper.verifyPositive(timeskip, "timeskip");
15685 ObjectHelper.verifyPositive(bufferSize, "bufferSize");
15686 Objects.requireNonNull(scheduler, "scheduler is null");
15687 Objects.requireNonNull(unit, "unit is null");
15688 return RxJavaPlugins.onAssembly(new ObservableWindowTimed<>(this, timespan, timeskip, unit, scheduler, Long.MAX_VALUE, bufferSize, false));
15689 }
15690
15691 /**
15692 * Returns an {@code Observable} that emits windows of items it collects from the current {@code Observable}. The resulting
15693 * {@code Observable} emits connected, non-overlapping windows, each of a fixed duration specified by the
15694 * {@code timespan} argument. When the current {@code Observable} completes or encounters an error, the resulting
15695 * {@code Observable} emits the current window and propagates the notification from the current {@code Observable}.
15696 * <p>
15697 * <img width="640" height="375" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/window5.v3.png" alt="">
15698 * <p>
15699 * Note that ignoring windows or subscribing later (i.e., on another thread) will result in
15700 * so-called window abandonment where a window may not contain any elements. In this case, subsequent
15701 * elements will be dropped until the condition for the next window boundary is satisfied. The behavior is
15702 * a trade-off for ensuring upstream cancellation can happen under some race conditions.
15703 * <dl>
15704 * <dt><b>Scheduler:</b></dt>
15705 * <dd>This version of {@code window} operates by default on the {@code computation} {@link Scheduler}.</dd>
15706 * </dl>
15707 *
15708 * @param timespan
15709 * the period of time each window collects items before it should be emitted and replaced with a
15710 * new window
15711 * @param unit
15712 * the unit of time that applies to the {@code timespan} argument
15713 * @return the new {@code Observable} instance
15714 * @throws NullPointerException if {@code unit} is {@code null}
15715 * @see <a href="http://reactivex.io/documentation/operators/window.html">ReactiveX operators documentation: Window</a>
15716 */
15717 @CheckReturnValue
15718 @SchedulerSupport(SchedulerSupport.COMPUTATION)
15719 @NonNull
15720 public final Observable<Observable<T>> window(long timespan, @NonNull TimeUnit unit) {
15721 return window(timespan, unit, Schedulers.computation(), Long.MAX_VALUE, false);
15722 }
15723
15724 /**
15725 * Returns an {@code Observable} that emits windows of items it collects from the current {@code Observable}. The resulting
15726 * {@code Observable} emits connected, non-overlapping windows, each of a fixed duration as specified by the
15727 * {@code timespan} argument or a maximum size as specified by the {@code count} argument (whichever is
15728 * reached first). When the current {@code Observable} completes or encounters an error, the resulting {@code Observable}
15729 * emits the current window and propagates the notification from the current {@code Observable}.
15730 * <p>
15731 * <img width="640" height="370" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/window6.v3.png" alt="">
15732 * <p>
15733 * Note that ignoring windows or subscribing later (i.e., on another thread) will result in
15734 * so-called window abandonment where a window may not contain any elements. In this case, subsequent
15735 * elements will be dropped until the condition for the next window boundary is satisfied. The behavior is
15736 * a trade-off for ensuring upstream cancellation can happen under some race conditions.
15737 * <dl>
15738 * <dt><b>Scheduler:</b></dt>
15739 * <dd>This version of {@code window} operates by default on the {@code computation} {@link Scheduler}.</dd>
15740 * </dl>
15741 *
15742 * @param timespan
15743 * the period of time each window collects items before it should be emitted and replaced with a
15744 * new window
15745 * @param unit
15746 * the unit of time that applies to the {@code timespan} argument
15747 * @param count
15748 * the maximum size of each window before it should be emitted
15749 * @return the new {@code Observable} instance
15750 * @throws NullPointerException if {@code unit} is {@code null}
15751 * @throws IllegalArgumentException if {@code count} is non-positive
15752 * @see <a href="http://reactivex.io/documentation/operators/window.html">ReactiveX operators documentation: Window</a>
15753 */
15754 @CheckReturnValue
15755 @SchedulerSupport(SchedulerSupport.COMPUTATION)
15756 @NonNull
15757 public final Observable<Observable<T>> window(long timespan, @NonNull TimeUnit unit,
15758 long count) {
15759 return window(timespan, unit, Schedulers.computation(), count, false);
15760 }
15761
15762 /**
15763 * Returns an {@code Observable} that emits windows of items it collects from the current {@code Observable}. The resulting
15764 * {@code Observable} emits connected, non-overlapping windows, each of a fixed duration as specified by the
15765 * {@code timespan} argument or a maximum size as specified by the {@code count} argument (whichever is
15766 * reached first). When the current {@code Observable} completes or encounters an error, the resulting {@code Observable}
15767 * emits the current window and propagates the notification from the current {@code Observable}.
15768 * <p>
15769 * <img width="640" height="370" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/window6.v3.png" alt="">
15770 * <p>
15771 * Note that ignoring windows or subscribing later (i.e., on another thread) will result in
15772 * so-called window abandonment where a window may not contain any elements. In this case, subsequent
15773 * elements will be dropped until the condition for the next window boundary is satisfied. The behavior is
15774 * a trade-off for ensuring upstream cancellation can happen under some race conditions.
15775 * <dl>
15776 * <dt><b>Scheduler:</b></dt>
15777 * <dd>This version of {@code window} operates by default on the {@code computation} {@link Scheduler}.</dd>
15778 * </dl>
15779 *
15780 * @param timespan
15781 * the period of time each window collects items before it should be emitted and replaced with a
15782 * new window
15783 * @param unit
15784 * the unit of time that applies to the {@code timespan} argument
15785 * @param count
15786 * the maximum size of each window before it should be emitted
15787 * @param restart
15788 * if {@code true}, when a window reaches the capacity limit, the timer is restarted as well
15789 * @return the new {@code Observable} instance
15790 * @throws NullPointerException if {@code unit} is {@code null}
15791 * @throws IllegalArgumentException if {@code count} is non-positive
15792 * @see <a href="http://reactivex.io/documentation/operators/window.html">ReactiveX operators documentation: Window</a>
15793 */
15794 @CheckReturnValue
15795 @SchedulerSupport(SchedulerSupport.COMPUTATION)
15796 @NonNull
15797 public final Observable<Observable<T>> window(long timespan, @NonNull TimeUnit unit,
15798 long count, boolean restart) {
15799 return window(timespan, unit, Schedulers.computation(), count, restart);
15800 }
15801
15802 /**
15803 * Returns an {@code Observable} that emits windows of items it collects from the current {@code Observable}. The resulting
15804 * {@code Observable} emits connected, non-overlapping windows, each of a fixed duration as specified by the
15805 * {@code timespan} argument. When the current {@code Observable} completes or encounters an error, the resulting
15806 * {@code Observable} emits the current window and propagates the notification from the current {@code Observable}.
15807 * <p>
15808 * <img width="640" height="375" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/window5.s.v3.png" alt="">
15809 * <p>
15810 * Note that ignoring windows or subscribing later (i.e., on another thread) will result in
15811 * so-called window abandonment where a window may not contain any elements. In this case, subsequent
15812 * elements will be dropped until the condition for the next window boundary is satisfied. The behavior is
15813 * a trade-off for ensuring upstream cancellation can happen under some race conditions.
15814 * <dl>
15815 * <dt><b>Scheduler:</b></dt>
15816 * <dd>You specify which {@link Scheduler} this operator will use.</dd>
15817 * </dl>
15818 *
15819 * @param timespan
15820 * the period of time each window collects items before it should be emitted and replaced with a
15821 * new window
15822 * @param unit
15823 * the unit of time which applies to the {@code timespan} argument
15824 * @param scheduler
15825 * the {@code Scheduler} to use when determining the end and start of a window
15826 * @return the new {@code Observable} instance
15827 * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null}
15828 * @see <a href="http://reactivex.io/documentation/operators/window.html">ReactiveX operators documentation: Window</a>
15829 */
15830 @CheckReturnValue
15831 @SchedulerSupport(SchedulerSupport.CUSTOM)
15832 @NonNull
15833 public final Observable<Observable<T>> window(long timespan, @NonNull TimeUnit unit,
15834 @NonNull Scheduler scheduler) {
15835 return window(timespan, unit, scheduler, Long.MAX_VALUE, false);
15836 }
15837
15838 /**
15839 * Returns an {@code Observable} that emits windows of items it collects from the current {@code Observable}. The resulting
15840 * {@code Observable} emits connected, non-overlapping windows, each of a fixed duration specified by the
15841 * {@code timespan} argument or a maximum size specified by the {@code count} argument (whichever is reached
15842 * first). When the current {@code Observable} completes or encounters an error, the resulting {@code Observable} emits the
15843 * current window and propagates the notification from the current {@code Observable}.
15844 * <p>
15845 * <img width="640" height="370" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/window6.s.v3.png" alt="">
15846 * <p>
15847 * Note that ignoring windows or subscribing later (i.e., on another thread) will result in
15848 * so-called window abandonment where a window may not contain any elements. In this case, subsequent
15849 * elements will be dropped until the condition for the next window boundary is satisfied. The behavior is
15850 * a trade-off for ensuring upstream cancellation can happen under some race conditions.
15851 * <dl>
15852 * <dt><b>Scheduler:</b></dt>
15853 * <dd>You specify which {@link Scheduler} this operator will use.</dd>
15854 * </dl>
15855 *
15856 * @param timespan
15857 * the period of time each window collects items before it should be emitted and replaced with a
15858 * new window
15859 * @param unit
15860 * the unit of time which applies to the {@code timespan} argument
15861 * @param count
15862 * the maximum size of each window before it should be emitted
15863 * @param scheduler
15864 * the {@code Scheduler} to use when determining the end and start of a window
15865 * @return the new {@code Observable} instance
15866 * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null}
15867 * @throws IllegalArgumentException if {@code count} is non-positive
15868 * @see <a href="http://reactivex.io/documentation/operators/window.html">ReactiveX operators documentation: Window</a>
15869 */
15870 @CheckReturnValue
15871 @SchedulerSupport(SchedulerSupport.CUSTOM)
15872 @NonNull
15873 public final Observable<Observable<T>> window(long timespan, @NonNull TimeUnit unit,
15874 @NonNull Scheduler scheduler, long count) {
15875 return window(timespan, unit, scheduler, count, false);
15876 }
15877
15878 /**
15879 * Returns an {@code Observable} that emits windows of items it collects from the current {@code Observable}. The resulting
15880 * {@code Observable} emits connected, non-overlapping windows, each of a fixed duration specified by the
15881 * {@code timespan} argument or a maximum size specified by the {@code count} argument (whichever is reached
15882 * first). When the current {@code Observable} completes or encounters an error, the resulting {@code Observable} emits the
15883 * current window and propagates the notification from the current {@code Observable}.
15884 * <p>
15885 * <img width="640" height="370" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/window6.s.v3.png" alt="">
15886 * <p>
15887 * Note that ignoring windows or subscribing later (i.e., on another thread) will result in
15888 * so-called window abandonment where a window may not contain any elements. In this case, subsequent
15889 * elements will be dropped until the condition for the next window boundary is satisfied. The behavior is
15890 * a trade-off for ensuring upstream cancellation can happen under some race conditions.
15891 * <dl>
15892 * <dt><b>Scheduler:</b></dt>
15893 * <dd>You specify which {@link Scheduler} this operator will use.</dd>
15894 * </dl>
15895 *
15896 * @param timespan
15897 * the period of time each window collects items before it should be emitted and replaced with a
15898 * new window
15899 * @param unit
15900 * the unit of time which applies to the {@code timespan} argument
15901 * @param count
15902 * the maximum size of each window before it should be emitted
15903 * @param scheduler
15904 * the {@code Scheduler} to use when determining the end and start of a window
15905 * @param restart
15906 * if {@code true}, when a window reaches the capacity limit, the timer is restarted as well
15907 * @return the new {@code Observable} instance
15908 * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null}
15909 * @throws IllegalArgumentException if {@code count} is non-positive
15910 * @see <a href="http://reactivex.io/documentation/operators/window.html">ReactiveX operators documentation: Window</a>
15911 */
15912 @CheckReturnValue
15913 @SchedulerSupport(SchedulerSupport.CUSTOM)
15914 @NonNull
15915 public final Observable<Observable<T>> window(long timespan, @NonNull TimeUnit unit,
15916 @NonNull Scheduler scheduler, long count, boolean restart) {
15917 return window(timespan, unit, scheduler, count, restart, bufferSize());
15918 }
15919
15920 /**
15921 * Returns an {@code Observable} that emits windows of items it collects from the current {@code Observable}. The resulting
15922 * {@code Observable} emits connected, non-overlapping windows, each of a fixed duration specified by the
15923 * {@code timespan} argument or a maximum size specified by the {@code count} argument (whichever is reached
15924 * first). When the current {@code Observable} completes or encounters an error, the resulting {@code Observable} emits the
15925 * current window and propagates the notification from the current {@code Observable}.
15926 * <p>
15927 * <img width="640" height="370" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/window6.s.v3.png" alt="">
15928 * <p>
15929 * Note that ignoring windows or subscribing later (i.e., on another thread) will result in
15930 * so-called window abandonment where a window may not contain any elements. In this case, subsequent
15931 * elements will be dropped until the condition for the next window boundary is satisfied. The behavior is
15932 * a trade-off for ensuring upstream cancellation can happen under some race conditions.
15933 * <dl>
15934 * <dt><b>Scheduler:</b></dt>
15935 * <dd>You specify which {@link Scheduler} this operator will use.</dd>
15936 * </dl>
15937 *
15938 * @param timespan
15939 * the period of time each window collects items before it should be emitted and replaced with a
15940 * new window
15941 * @param unit
15942 * the unit of time which applies to the {@code timespan} argument
15943 * @param count
15944 * the maximum size of each window before it should be emitted
15945 * @param scheduler
15946 * the {@code Scheduler} to use when determining the end and start of a window
15947 * @param restart
15948 * if {@code true}, when a window reaches the capacity limit, the timer is restarted as well
15949 * @param bufferSize
15950 * the capacity hint for the buffer in the inner windows
15951 * @return the new {@code Observable} instance
15952 * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null}
15953 * @throws IllegalArgumentException if {@code count} or {@code bufferSize} is non-positive
15954 * @see <a href="http://reactivex.io/documentation/operators/window.html">ReactiveX operators documentation: Window</a>
15955 */
15956 @CheckReturnValue
15957 @SchedulerSupport(SchedulerSupport.CUSTOM)
15958 @NonNull
15959 public final Observable<Observable<T>> window(
15960 long timespan, @NonNull TimeUnit unit, @NonNull Scheduler scheduler,
15961 long count, boolean restart, int bufferSize) {
15962 ObjectHelper.verifyPositive(bufferSize, "bufferSize");
15963 Objects.requireNonNull(scheduler, "scheduler is null");
15964 Objects.requireNonNull(unit, "unit is null");
15965 ObjectHelper.verifyPositive(count, "count");
15966 return RxJavaPlugins.onAssembly(new ObservableWindowTimed<>(this, timespan, timespan, unit, scheduler, count, bufferSize, restart));
15967 }
15968
15969 /**
15970 * Returns an {@code Observable} that emits non-overlapping windows of items it collects from the current {@code Observable}
15971 * where the boundary of each window is determined by the items emitted from a specified boundary-governing
15972 * {@link ObservableSource}.
15973 * <p>
15974 * <img width="640" height="475" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/window8.v3.png" alt="">
15975 * <p>
15976 * Note that ignoring windows or subscribing later (i.e., on another thread) will result in
15977 * so-called window abandonment where a window may not contain any elements. In this case, subsequent
15978 * elements will be dropped until the condition for the next window boundary is satisfied. The behavior is
15979 * a trade-off for ensuring upstream cancellation can happen under some race conditions.
15980 * <dl>
15981 * <dt><b>Scheduler:</b></dt>
15982 * <dd>This version of {@code window} does not operate by default on a particular {@link Scheduler}.</dd>
15983 * </dl>
15984 *
15985 * @param <B>
15986 * the window element type (ignored)
15987 * @param boundaryIndicator
15988 * an {@code ObservableSource} whose emitted items close and open windows
15989 * @return the new {@code Observable} instance
15990 * @throws NullPointerException if {@code boundaryIndicator} is {@code null}
15991 * @see <a href="http://reactivex.io/documentation/operators/window.html">ReactiveX operators documentation: Window</a>
15992 */
15993 @CheckReturnValue
15994 @SchedulerSupport(SchedulerSupport.NONE)
15995 @NonNull
15996 public final <@NonNull B> Observable<Observable<T>> window(@NonNull ObservableSource<B> boundaryIndicator) {
15997 return window(boundaryIndicator, bufferSize());
15998 }
15999
16000 /**
16001 * Returns an {@code Observable} that emits non-overlapping windows of items it collects from the current {@code Observable}
16002 * where the boundary of each window is determined by the items emitted from a specified boundary-governing
16003 * {@link ObservableSource}.
16004 * <p>
16005 * <img width="640" height="475" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/window8.v3.png" alt="">
16006 * <p>
16007 * Note that ignoring windows or subscribing later (i.e., on another thread) will result in
16008 * so-called window abandonment where a window may not contain any elements. In this case, subsequent
16009 * elements will be dropped until the condition for the next window boundary is satisfied. The behavior is
16010 * a trade-off for ensuring upstream cancellation can happen under some race conditions.
16011 * <dl>
16012 * <dt><b>Scheduler:</b></dt>
16013 * <dd>This version of {@code window} does not operate by default on a particular {@link Scheduler}.</dd>
16014 * </dl>
16015 *
16016 * @param <B>
16017 * the window element type (ignored)
16018 * @param boundaryIndicator
16019 * an {@code ObservableSource} whose emitted items close and open windows
16020 * @param bufferSize
16021 * the capacity hint for the buffer in the inner windows
16022 * @return the new {@code Observable} instance
16023 * @throws NullPointerException if {@code boundaryIndicator} is {@code null}
16024 * @throws IllegalArgumentException if {@code bufferSize} is non-positive
16025 * @see <a href="http://reactivex.io/documentation/operators/window.html">ReactiveX operators documentation: Window</a>
16026 */
16027 @CheckReturnValue
16028 @SchedulerSupport(SchedulerSupport.NONE)
16029 @NonNull
16030 public final <@NonNull B> Observable<Observable<T>> window(@NonNull ObservableSource<B> boundaryIndicator, int bufferSize) {
16031 Objects.requireNonNull(boundaryIndicator, "boundaryIndicator is null");
16032 ObjectHelper.verifyPositive(bufferSize, "bufferSize");
16033 return RxJavaPlugins.onAssembly(new ObservableWindowBoundary<>(this, boundaryIndicator, bufferSize));
16034 }
16035
16036 /**
16037 * Returns an {@code Observable} that emits windows of items it collects from the current {@code Observable}. The resulting
16038 * {@code Observable} emits windows that contain those items emitted by the current {@code Observable} between the time when
16039 * the {@code openingIndicator} {@link ObservableSource} emits an item and when the {@code ObservableSource} returned by
16040 * {@code closingIndicator} emits an item.
16041 * <p>
16042 * <img width="640" height="550" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/window2.v3.png" alt="">
16043 * <p>
16044 * Note that ignoring windows or subscribing later (i.e., on another thread) will result in
16045 * so-called window abandonment where a window may not contain any elements. In this case, subsequent
16046 * elements will be dropped until the condition for the next window boundary is satisfied. The behavior is
16047 * a trade-off for ensuring upstream cancellation can happen under some race conditions.
16048 * <dl>
16049 * <dt><b>Scheduler:</b></dt>
16050 * <dd>This version of {@code window} does not operate by default on a particular {@link Scheduler}.</dd>
16051 * </dl>
16052 *
16053 * @param <U> the element type of the window-opening {@code ObservableSource}
16054 * @param <V> the element type of the window-closing {@code ObservableSource}s
16055 * @param openingIndicator
16056 * an {@code ObservableSource} that, when it emits an item, causes another window to be created
16057 * @param closingIndicator
16058 * a {@link Function} that produces an {@code ObservableSource} for every window created. When this indicator {@code ObservableSource}
16059 * emits an item, the associated window is completed
16060 * @return the new {@code Observable} instance
16061 * @throws NullPointerException if {@code openingIndicator} or {@code closingIndicator} is {@code null}
16062 * @see <a href="http://reactivex.io/documentation/operators/window.html">ReactiveX operators documentation: Window</a>
16063 */
16064 @CheckReturnValue
16065 @SchedulerSupport(SchedulerSupport.NONE)
16066 @NonNull
16067 public final <@NonNull U, @NonNull V> Observable<Observable<T>> window(
16068 @NonNull ObservableSource<U> openingIndicator,
16069 @NonNull Function<? super U, ? extends ObservableSource<V>> closingIndicator) {
16070 return window(openingIndicator, closingIndicator, bufferSize());
16071 }
16072
16073 /**
16074 * Returns an {@code Observable} that emits windows of items it collects from the current {@code Observable}. The resulting
16075 * {@code Observable} emits windows that contain those items emitted by the current {@code Observable} between the time when
16076 * the {@code openingIndicator} {@link ObservableSource} emits an item and when the {@code ObservableSource} returned by
16077 * {@code closingIndicator} emits an item.
16078 * <p>
16079 * <img width="640" height="550" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/window2.v3.png" alt="">
16080 * <p>
16081 * Note that ignoring windows or subscribing later (i.e., on another thread) will result in
16082 * so-called window abandonment where a window may not contain any elements. In this case, subsequent
16083 * elements will be dropped until the condition for the next window boundary is satisfied. The behavior is
16084 * a trade-off for ensuring upstream cancellation can happen under some race conditions.
16085 * <dl>
16086 * <dt><b>Scheduler:</b></dt>
16087 * <dd>This version of {@code window} does not operate by default on a particular {@link Scheduler}.</dd>
16088 * </dl>
16089 *
16090 * @param <U> the element type of the window-opening {@code ObservableSource}
16091 * @param <V> the element type of the window-closing {@code ObservableSource}s
16092 * @param openingIndicator
16093 * an {@code ObservableSource} that, when it emits an item, causes another window to be created
16094 * @param closingIndicator
16095 * a {@link Function} that produces an {@code ObservableSource} for every window created. When this indicator {@code ObservableSource}
16096 * emits an item, the associated window is completed
16097 * @param bufferSize
16098 * the capacity hint for the buffer in the inner windows
16099 * @return the new {@code Observable} instance
16100 * @throws NullPointerException if {@code openingIndicator} or {@code closingIndicator} is {@code null}
16101 * @throws IllegalArgumentException if {@code bufferSize} is non-positive
16102 * @see <a href="http://reactivex.io/documentation/operators/window.html">ReactiveX operators documentation: Window</a>
16103 */
16104 @CheckReturnValue
16105 @SchedulerSupport(SchedulerSupport.NONE)
16106 @NonNull
16107 public final <@NonNull U, @NonNull V> Observable<Observable<T>> window(
16108 @NonNull ObservableSource<U> openingIndicator,
16109 @NonNull Function<? super U, ? extends ObservableSource<V>> closingIndicator, int bufferSize) {
16110 Objects.requireNonNull(openingIndicator, "openingIndicator is null");
16111 Objects.requireNonNull(closingIndicator, "closingIndicator is null");
16112 ObjectHelper.verifyPositive(bufferSize, "bufferSize");
16113 return RxJavaPlugins.onAssembly(new ObservableWindowBoundarySelector<>(this, openingIndicator, closingIndicator, bufferSize));
16114 }
16115
16116 /**
16117 * Merges the specified {@link ObservableSource} into the current {@code Observable} sequence by using the {@code resultSelector}
16118 * function only when the current {@code Observable} emits an item.
16119 *
16120 * <p>Note that this operator doesn't emit anything until the other source has produced at
16121 * least one value. The resulting emission only happens when the current {@code Observable} emits (and
16122 * not when the other source emits, unlike combineLatest).
16123 * If the other source doesn't produce any value and just completes, the sequence is completed immediately.
16124 * If the upstream completes before the other source has produced at least one value, the sequence completes
16125 * without emission.
16126 * <p>
16127 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/withLatestFrom.v3.png" alt="">
16128 *
16129 * <dl>
16130 * <dt><b>Scheduler:</b></dt>
16131 * <dd>This operator, by default, doesn't run any particular {@link Scheduler}.</dd>
16132 * </dl>
16133 *
16134 * @param <U> the element type of the other {@code ObservableSource}
16135 * @param <R> the result type of the combination
16136 * @param other
16137 * the other {@code ObservableSource}
16138 * @param combiner
16139 * the function to call when the current {@code Observable} emits an item and the other {@code ObservableSource} has already
16140 * emitted an item, to generate the item to be emitted by the resulting {@code Observable}
16141 * @return the new {@code Observable} instance
16142 * @throws NullPointerException if {@code other} or {@code combiner} is {@code null}
16143 * @since 2.0
16144 * @see <a href="http://reactivex.io/documentation/operators/combinelatest.html">ReactiveX operators documentation: CombineLatest</a>
16145 */
16146 @CheckReturnValue
16147 @SchedulerSupport(SchedulerSupport.NONE)
16148 @NonNull
16149 public final <@NonNull U, @NonNull R> Observable<R> withLatestFrom(@NonNull ObservableSource<? extends U> other, @NonNull BiFunction<? super T, ? super U, ? extends R> combiner) {
16150 Objects.requireNonNull(other, "other is null");
16151 Objects.requireNonNull(combiner, "combiner is null");
16152
16153 return RxJavaPlugins.onAssembly(new ObservableWithLatestFrom<T, U, R>(this, combiner, other));
16154 }
16155
16156 /**
16157 * Combines the value emission from the current {@code Observable} with the latest emissions from the
16158 * other {@link ObservableSource}s via a function to produce the output item.
16159 *
16160 * <p>Note that this operator doesn't emit anything until all other sources have produced at
16161 * least one value. The resulting emission only happens when the current {@code Observable} emits (and
16162 * not when any of the other sources emit, unlike {@code combineLatest}).
16163 * If a source doesn't produce any value and just completes, the sequence is completed immediately.
16164 * If the upstream completes before all other sources have produced at least one value, the sequence completes
16165 * without emission.
16166 * <p>
16167 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/withLatestFrom.v3.png" alt="">
16168 * <dl>
16169 * <dt><b>Scheduler:</b></dt>
16170 * <dd>This operator does not operate by default on a particular {@link Scheduler}.</dd>
16171 * </dl>
16172 *
16173 * @param <T1> the first other source's value type
16174 * @param <T2> the second other source's value type
16175 * @param <R> the result value type
16176 * @param source1 the first other {@code ObservableSource}
16177 * @param source2 the second other {@code ObservableSource}
16178 * @param combiner the function called with an array of values from each participating {@code ObservableSource}
16179 * @return the new {@code Observable} instance
16180 * @throws NullPointerException if {@code source1}, {@code source2} or {@code combiner} is {@code null}
16181 * @since 2.0
16182 */
16183 @CheckReturnValue
16184 @SchedulerSupport(SchedulerSupport.NONE)
16185 @NonNull
16186 public final <@NonNull T1, @NonNull T2, @NonNull R> Observable<R> withLatestFrom(
16187 @NonNull ObservableSource<T1> source1, @NonNull ObservableSource<T2> source2,
16188 @NonNull Function3<? super T, ? super T1, ? super T2, R> combiner) {
16189 Objects.requireNonNull(source1, "source1 is null");
16190 Objects.requireNonNull(source2, "source2 is null");
16191 Objects.requireNonNull(combiner, "combiner is null");
16192 Function<Object[], R> f = Functions.toFunction(combiner);
16193 return withLatestFrom(new ObservableSource[] { source1, source2 }, f);
16194 }
16195
16196 /**
16197 * Combines the value emission from the current {@code Observable} with the latest emissions from the
16198 * other {@link ObservableSource}s via a function to produce the output item.
16199 *
16200 * <p>Note that this operator doesn't emit anything until all other sources have produced at
16201 * least one value. The resulting emission only happens when the current {@code Observable} emits (and
16202 * not when any of the other sources emit, unlike combineLatest).
16203 * If a source doesn't produce any value and just completes, the sequence is completed immediately.
16204 * If the upstream completes before all other sources have produced at least one value, the sequence completes
16205 * without emission.
16206 * <p>
16207 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/withLatestFrom.v3.png" alt="">
16208 * <dl>
16209 * <dt><b>Scheduler:</b></dt>
16210 * <dd>This operator does not operate by default on a particular {@link Scheduler}.</dd>
16211 * </dl>
16212 *
16213 * @param <T1> the first other source's value type
16214 * @param <T2> the second other source's value type
16215 * @param <T3> the third other source's value type
16216 * @param <R> the result value type
16217 * @param source1 the first other {@code ObservableSource}
16218 * @param source2 the second other {@code ObservableSource}
16219 * @param source3 the third other {@code ObservableSource}
16220 * @param combiner the function called with an array of values from each participating {@code ObservableSource}
16221 * @return the new {@code Observable} instance
16222 * @throws NullPointerException if {@code source1}, {@code source2}, {@code source3} or {@code combiner} is {@code null}
16223 * @since 2.0
16224 */
16225 @CheckReturnValue
16226 @SchedulerSupport(SchedulerSupport.NONE)
16227 @NonNull
16228 public final <@NonNull T1, @NonNull T2, @NonNull T3, @NonNull R> Observable<R> withLatestFrom(
16229 @NonNull ObservableSource<T1> source1, @NonNull ObservableSource<T2> source2,
16230 @NonNull ObservableSource<T3> source3,
16231 @NonNull Function4<? super T, ? super T1, ? super T2, ? super T3, R> combiner) {
16232 Objects.requireNonNull(source1, "source1 is null");
16233 Objects.requireNonNull(source2, "source2 is null");
16234 Objects.requireNonNull(source3, "source3 is null");
16235 Objects.requireNonNull(combiner, "combiner is null");
16236 Function<Object[], R> f = Functions.toFunction(combiner);
16237 return withLatestFrom(new ObservableSource[] { source1, source2, source3 }, f);
16238 }
16239
16240 /**
16241 * Combines the value emission from the current {@code Observable} with the latest emissions from the
16242 * other {@link ObservableSource}s via a function to produce the output item.
16243 *
16244 * <p>Note that this operator doesn't emit anything until all other sources have produced at
16245 * least one value. The resulting emission only happens when the current {@code Observable} emits (and
16246 * not when any of the other sources emit, unlike combineLatest).
16247 * If a source doesn't produce any value and just completes, the sequence is completed immediately.
16248 * If the upstream completes before all other sources have produced at least one value, the sequence completes
16249 * without emission.
16250 * <p>
16251 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/withLatestFrom.v3.png" alt="">
16252 * <dl>
16253 * <dt><b>Scheduler:</b></dt>
16254 * <dd>This operator does not operate by default on a particular {@link Scheduler}.</dd>
16255 * </dl>
16256 *
16257 * @param <T1> the first other source's value type
16258 * @param <T2> the second other source's value type
16259 * @param <T3> the third other source's value type
16260 * @param <T4> the fourth other source's value type
16261 * @param <R> the result value type
16262 * @param source1 the first other {@code ObservableSource}
16263 * @param source2 the second other {@code ObservableSource}
16264 * @param source3 the third other {@code ObservableSource}
16265 * @param source4 the fourth other {@code ObservableSource}
16266 * @param combiner the function called with an array of values from each participating {@code ObservableSource}
16267 * @return the new {@code Observable} instance
16268 * @throws NullPointerException if {@code source1}, {@code source2}, {@code source3},
16269 * {@code source4} or {@code combiner} is {@code null}
16270 * @since 2.0
16271 */
16272 @CheckReturnValue
16273 @SchedulerSupport(SchedulerSupport.NONE)
16274 @NonNull
16275 public final <@NonNull T1, @NonNull T2, @NonNull T3, @NonNull T4, @NonNull R> Observable<R> withLatestFrom(
16276 @NonNull ObservableSource<T1> source1, @NonNull ObservableSource<T2> source2,
16277 @NonNull ObservableSource<T3> source3, @NonNull ObservableSource<T4> source4,
16278 @NonNull Function5<? super T, ? super T1, ? super T2, ? super T3, ? super T4, R> combiner) {
16279 Objects.requireNonNull(source1, "source1 is null");
16280 Objects.requireNonNull(source2, "source2 is null");
16281 Objects.requireNonNull(source3, "source3 is null");
16282 Objects.requireNonNull(source4, "source4 is null");
16283 Objects.requireNonNull(combiner, "combiner is null");
16284 Function<Object[], R> f = Functions.toFunction(combiner);
16285 return withLatestFrom(new ObservableSource[] { source1, source2, source3, source4 }, f);
16286 }
16287
16288 /**
16289 * Combines the value emission from the current {@code Observable} with the latest emissions from the
16290 * other {@link ObservableSource}s via a function to produce the output item.
16291 *
16292 * <p>Note that this operator doesn't emit anything until all other sources have produced at
16293 * least one value. The resulting emission only happens when the current {@code Observable} emits (and
16294 * not when any of the other sources emit, unlike combineLatest).
16295 * If a source doesn't produce any value and just completes, the sequence is completed immediately.
16296 * If the upstream completes before all other sources have produced at least one value, the sequence completes
16297 * without emission.
16298 * <p>
16299 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/withLatestFrom.v3.png" alt="">
16300 * <dl>
16301 * <dt><b>Scheduler:</b></dt>
16302 * <dd>This operator does not operate by default on a particular {@link Scheduler}.</dd>
16303 * </dl>
16304 *
16305 * @param <R> the result value type
16306 * @param others the array of other sources
16307 * @param combiner the function called with an array of values from each participating {@code ObservableSource}
16308 * @return the new {@code Observable} instance
16309 * @throws NullPointerException if {@code others} or {@code combiner} is {@code null}
16310 * @since 2.0
16311 */
16312 @CheckReturnValue
16313 @SchedulerSupport(SchedulerSupport.NONE)
16314 @NonNull
16315 public final <@NonNull R> Observable<R> withLatestFrom(@NonNull ObservableSource<?>[] others, @NonNull Function<? super Object[], R> combiner) {
16316 Objects.requireNonNull(others, "others is null");
16317 Objects.requireNonNull(combiner, "combiner is null");
16318 return RxJavaPlugins.onAssembly(new ObservableWithLatestFromMany<>(this, others, combiner));
16319 }
16320
16321 /**
16322 * Combines the value emission from the current {@code Observable} with the latest emissions from the
16323 * other {@link ObservableSource}s via a function to produce the output item.
16324 *
16325 * <p>Note that this operator doesn't emit anything until all other sources have produced at
16326 * least one value. The resulting emission only happens when the current {@code Observable} emits (and
16327 * not when any of the other sources emit, unlike {@code combineLatest}).
16328 * If a source doesn't produce any value and just completes, the sequence is completed immediately.
16329 * If the upstream completes before all other sources have produced at least one value, the sequence completes
16330 * without emission.
16331 * <p>
16332 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/withLatestFrom.v3.png" alt="">
16333 * <dl>
16334 * <dt><b>Scheduler:</b></dt>
16335 * <dd>This operator does not operate by default on a particular {@link Scheduler}.</dd>
16336 * </dl>
16337 *
16338 * @param <R> the result value type
16339 * @param others the iterable of other sources
16340 * @param combiner the function called with an array of values from each participating {@code ObservableSource}
16341 * @return the new {@code Observable} instance
16342 * @throws NullPointerException if {@code others} or {@code combiner} is {@code null}
16343 * @since 2.0
16344 */
16345 @CheckReturnValue
16346 @SchedulerSupport(SchedulerSupport.NONE)
16347 @NonNull
16348 public final <@NonNull R> Observable<R> withLatestFrom(@NonNull Iterable<@NonNull ? extends ObservableSource<?>> others, @NonNull Function<? super Object[], R> combiner) {
16349 Objects.requireNonNull(others, "others is null");
16350 Objects.requireNonNull(combiner, "combiner is null");
16351 return RxJavaPlugins.onAssembly(new ObservableWithLatestFromMany<>(this, others, combiner));
16352 }
16353
16354 /**
16355 * Returns an {@code Observable} that emits items that are the result of applying a specified function to pairs of
16356 * values, one each from the current {@code Observable} and a specified {@link Iterable} sequence.
16357 * <p>
16358 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/zip.i.v3.png" alt="">
16359 * <p>
16360 * Note that the {@code other} {@code Iterable} is evaluated as items are observed from the current {@code Observable}; it is
16361 * not pre-consumed. This allows you to zip infinite streams on either side.
16362 * <dl>
16363 * <dt><b>Scheduler:</b></dt>
16364 * <dd>{@code zipWith} does not operate by default on a particular {@link Scheduler}.</dd>
16365 * </dl>
16366 *
16367 * @param <U>
16368 * the type of items in the {@code other} {@code Iterable}
16369 * @param <R>
16370 * the type of items emitted by the resulting {@code Observable}
16371 * @param other
16372 * the {@code Iterable} sequence
16373 * @param zipper
16374 * a function that combines the pairs of items from the current {@code Observable} and the {@code Iterable} to generate
16375 * the items to be emitted by the resulting {@code Observable}
16376 * @return the new {@code Observable} instance
16377 * @throws NullPointerException if {@code other} or {@code zipper} is {@code null}
16378 * @see <a href="http://reactivex.io/documentation/operators/zip.html">ReactiveX operators documentation: Zip</a>
16379 */
16380 @CheckReturnValue
16381 @SchedulerSupport(SchedulerSupport.NONE)
16382 @NonNull
16383 public final <@NonNull U, @NonNull R> Observable<R> zipWith(@NonNull Iterable<U> other, @NonNull BiFunction<? super T, ? super U, ? extends R> zipper) {
16384 Objects.requireNonNull(other, "other is null");
16385 Objects.requireNonNull(zipper, "zipper is null");
16386 return RxJavaPlugins.onAssembly(new ObservableZipIterable<>(this, other, zipper));
16387 }
16388
16389 /**
16390 * Returns an {@code Observable} that emits items that are the result of applying a specified function to pairs of
16391 * values, one each from the current {@code Observable} and another specified {@link ObservableSource}.
16392 * <p>
16393 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/zip.v3.png" alt="">
16394 * <p>
16395 * The operator subscribes to its sources in order they are specified and completes eagerly if
16396 * one of the sources is shorter than the rest while disposing the other sources. Therefore, it
16397 * is possible those other sources will never be able to run to completion (and thus not calling
16398 * {@code doOnComplete()}). This can also happen if the sources are exactly the same length; if
16399 * source A completes and B has been consumed and is about to complete, the operator detects A won't
16400 * be sending further values and it will dispose B immediately. For example:
16401 * <pre><code>range(1, 5).doOnComplete(action1).zipWith(range(6, 5).doOnComplete(action2), (a, b) -&gt; a + b)</code></pre>
16402 * {@code action1} will be called but {@code action2} won't.
16403 * <br>To work around this termination property,
16404 * use {@link #doOnDispose(Action)} as well or use {@code using()} to do cleanup in case of completion
16405 * or a dispose() call.
16406 * <dl>
16407 * <dt><b>Scheduler:</b></dt>
16408 * <dd>{@code zipWith} does not operate by default on a particular {@link Scheduler}.</dd>
16409 * </dl>
16410 *
16411 * @param <U>
16412 * the type of items emitted by the {@code other} {@code ObservableSource}
16413 * @param <R>
16414 * the type of items emitted by the resulting {@code Observable}
16415 * @param other
16416 * the other {@code ObservableSource}
16417 * @param zipper
16418 * a function that combines the pairs of items from the current {@code Observable} and the other {@code ObservableSource} to generate the items to
16419 * be emitted by the resulting {@code Observable}
16420 * @return the new {@code Observable} instance
16421 * @throws NullPointerException if {@code other} or {@code zipper} is {@code null}
16422 * @see <a href="http://reactivex.io/documentation/operators/zip.html">ReactiveX operators documentation: Zip</a>
16423 */
16424 @CheckReturnValue
16425 @SchedulerSupport(SchedulerSupport.NONE)
16426 @NonNull
16427 public final <@NonNull U, @NonNull R> Observable<R> zipWith(@NonNull ObservableSource<? extends U> other,
16428 @NonNull BiFunction<? super T, ? super U, ? extends R> zipper) {
16429 Objects.requireNonNull(other, "other is null");
16430 return zip(this, other, zipper);
16431 }
16432
16433 /**
16434 * Returns an {@code Observable} that emits items that are the result of applying a specified function to pairs of
16435 * values, one each from the current {@code Observable} and another specified {@link ObservableSource}.
16436 * <p>
16437 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/zip.v3.png" alt="">
16438 * <p>
16439 * The operator subscribes to its sources in order they are specified and completes eagerly if
16440 * one of the sources is shorter than the rest while disposing the other sources. Therefore, it
16441 * is possible those other sources will never be able to run to completion (and thus not calling
16442 * {@code doOnComplete()}). This can also happen if the sources are exactly the same length; if
16443 * source A completes and B has been consumed and is about to complete, the operator detects A won't
16444 * be sending further values and it will dispose B immediately. For example:
16445 * <pre><code>range(1, 5).doOnComplete(action1).zipWith(range(6, 5).doOnComplete(action2), (a, b) -&gt; a + b)</code></pre>
16446 * {@code action1} will be called but {@code action2} won't.
16447 * <br>To work around this termination property,
16448 * use {@link #doOnDispose(Action)} as well or use {@code using()} to do cleanup in case of completion
16449 * or a dispose() call.
16450 * <dl>
16451 * <dt><b>Scheduler:</b></dt>
16452 * <dd>{@code zipWith} does not operate by default on a particular {@link Scheduler}.</dd>
16453 * </dl>
16454 *
16455 * @param <U>
16456 * the type of items emitted by the {@code other} {@code ObservableSource}
16457 * @param <R>
16458 * the type of items emitted by the resulting {@code Observable}
16459 * @param other
16460 * the other {@code ObservableSource}
16461 * @param zipper
16462 * a function that combines the pairs of items from the current {@code Observable} and the other {@code ObservableSource} to generate the items to
16463 * be emitted by the resulting {@code Observable}
16464 * @param delayError
16465 * if {@code true}, errors from the current {@code Observable} or the other {@code ObservableSource} is delayed until both terminate
16466 * @return the new {@code Observable} instance
16467 * @throws NullPointerException if {@code other} or {@code zipper} is {@code null}
16468 * @see <a href="http://reactivex.io/documentation/operators/zip.html">ReactiveX operators documentation: Zip</a>
16469 * @since 2.0
16470 */
16471 @CheckReturnValue
16472 @SchedulerSupport(SchedulerSupport.NONE)
16473 @NonNull
16474 public final <@NonNull U, @NonNull R> Observable<R> zipWith(@NonNull ObservableSource<? extends U> other,
16475 @NonNull BiFunction<? super T, ? super U, ? extends R> zipper, boolean delayError) {
16476 return zip(this, other, zipper, delayError);
16477 }
16478
16479 /**
16480 * Returns an {@code Observable} that emits items that are the result of applying a specified function to pairs of
16481 * values, one each from the current {@code Observable} and another specified {@link ObservableSource}.
16482 * <p>
16483 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/zip.v3.png" alt="">
16484 * <p>
16485 * The operator subscribes to its sources in order they are specified and completes eagerly if
16486 * one of the sources is shorter than the rest while disposing the other sources. Therefore, it
16487 * is possible those other sources will never be able to run to completion (and thus not calling
16488 * {@code doOnComplete()}). This can also happen if the sources are exactly the same length; if
16489 * source A completes and B has been consumed and is about to complete, the operator detects A won't
16490 * be sending further values and it will dispose B immediately. For example:
16491 * <pre><code>range(1, 5).doOnComplete(action1).zipWith(range(6, 5).doOnComplete(action2), (a, b) -&gt; a + b)</code></pre>
16492 * {@code action1} will be called but {@code action2} won't.
16493 * <br>To work around this termination property,
16494 * use {@link #doOnDispose(Action)} as well or use {@code using()} to do cleanup in case of completion
16495 * or a dispose() call.
16496 * <dl>
16497 * <dt><b>Scheduler:</b></dt>
16498 * <dd>{@code zipWith} does not operate by default on a particular {@link Scheduler}.</dd>
16499 * </dl>
16500 *
16501 * @param <U>
16502 * the type of items emitted by the {@code other} {@code ObservableSource}
16503 * @param <R>
16504 * the type of items emitted by the resulting {@code Observable}
16505 * @param other
16506 * the other {@code ObservableSource}
16507 * @param zipper
16508 * a function that combines the pairs of items from the current {@code Observable} and the other {@code ObservableSource} to generate the items to
16509 * be emitted by the resulting {@code Observable}
16510 * @param bufferSize
16511 * the capacity hint for the buffer in the inner windows
16512 * @param delayError
16513 * if {@code true}, errors from the current {@code Observable} or the other {@code ObservableSource} is delayed until both terminate
16514 * @return the new {@code Observable} instance
16515 * @see <a href="http://reactivex.io/documentation/operators/zip.html">ReactiveX operators documentation: Zip</a>
16516 * @throws NullPointerException if {@code other} or {@code zipper} is {@code null}
16517 * @throws IllegalArgumentException if {@code bufferSize} is non-positive
16518 * @since 2.0
16519 */
16520 @CheckReturnValue
16521 @SchedulerSupport(SchedulerSupport.NONE)
16522 @NonNull
16523 public final <@NonNull U, @NonNull R> Observable<R> zipWith(@NonNull ObservableSource<? extends U> other,
16524 @NonNull BiFunction<? super T, ? super U, ? extends R> zipper, boolean delayError, int bufferSize) {
16525 return zip(this, other, zipper, delayError, bufferSize);
16526 }
16527
16528 // -------------------------------------------------------------------------
16529 // Fluent test support, super handy and reduces test preparation boilerplate
16530 // -------------------------------------------------------------------------
16531 /**
16532 * Creates a {@link TestObserver} and subscribes it to the current {@code Observable}.
16533 * <dl>
16534 * <dt><b>Scheduler:</b></dt>
16535 * <dd>{@code test} does not operate by default on a particular {@link Scheduler}.</dd>
16536 * </dl>
16537 * @return the new {@code TestObserver} instance
16538 * @since 2.0
16539 */
16540 @CheckReturnValue
16541 @SchedulerSupport(SchedulerSupport.NONE)
16542 @NonNull
16543 public final TestObserver<T> test() { // NoPMD
16544 TestObserver<T> to = new TestObserver<>();
16545 subscribe(to);
16546 return to;
16547 }
16548
16549 /**
16550 * Creates a {@link TestObserver}, optionally disposes it and then subscribes
16551 * it to the current {@code Observable}.
16552 *
16553 * <dl>
16554 * <dt><b>Scheduler:</b></dt>
16555 * <dd>{@code test} does not operate by default on a particular {@link Scheduler}.</dd>
16556 * </dl>
16557 * @param dispose indicates if the {@code TestObserver} should be disposed before
16558 * it is subscribed to the current {@code Observable}
16559 * @return the new {@code TestObserver} instance
16560 * @since 2.0
16561 */
16562 @CheckReturnValue
16563 @SchedulerSupport(SchedulerSupport.NONE)
16564 @NonNull
16565 public final TestObserver<T> test(boolean dispose) { // NoPMD
16566 TestObserver<T> to = new TestObserver<>();
16567 if (dispose) {
16568 to.dispose();
16569 }
16570 subscribe(to);
16571 return to;
16572 }
16573
16574 // -------------------------------------------------------------------------
16575 // JDK 8 Support
16576 // -------------------------------------------------------------------------
16577
16578 /**
16579 * Converts the existing value of the provided optional into a {@link #just(Object)}
16580 * or an empty optional into an {@link #empty()} {@code Observable} instance.
16581 * <p>
16582 * <img width="640" height="335" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/fromOptional.o.png" alt="">
16583 * <p>
16584 * Note that the operator takes an already instantiated optional reference and does not
16585 * by any means create this original optional. If the optional is to be created per
16586 * consumer upon subscription, use {@link #defer(Supplier)} around {@code fromOptional}:
16587 * <pre><code>
16588 * Observable.defer(() -&gt; Observable.fromOptional(createOptional()));
16589 * </code></pre>
16590 * <dl>
16591 * <dt><b>Scheduler:</b></dt>
16592 * <dd>{@code fromOptional} does not operate by default on a particular {@link Scheduler}.</dd>
16593 * </dl>
16594 * @param <T> the element type of the optional value
16595 * @param optional the optional value to convert into an {@code Observable}
16596 * @return the new {@code Observable} instance
16597 * @throws NullPointerException if {@code optional} is {@code null}
16598 * @since 3.0.0
16599 * @see #just(Object)
16600 * @see #empty()
16601 */
16602 @CheckReturnValue
16603 @SchedulerSupport(SchedulerSupport.NONE)
16604 @NonNull
16605 public static <@NonNull T> Observable<@NonNull T> fromOptional(@NonNull Optional<T> optional) {
16606 Objects.requireNonNull(optional, "optional is null");
16607 return optional.map(Observable::just).orElseGet(Observable::empty);
16608 }
16609
16610 /**
16611 * Signals the completion value or error of the given (hot) {@link CompletionStage}-based asynchronous calculation.
16612 * <p>
16613 * <img width="640" height="262" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/fromCompletionStage.o.png" alt="">
16614 * <p>
16615 * Note that the operator takes an already instantiated, running or terminated {@code CompletionStage}.
16616 * If the optional is to be created per consumer upon subscription, use {@link #defer(Supplier)}
16617 * around {@code fromCompletionStage}:
16618 * <pre><code>
16619 * Observable.defer(() -&gt; Observable.fromCompletionStage(createCompletionStage()));
16620 * </code></pre>
16621 * <p>
16622 * If the {@code CompletionStage} completes with {@code null}, a {@link NullPointerException} is signaled.
16623 * <p>
16624 * Canceling the flow can't cancel the execution of the {@code CompletionStage} because {@code CompletionStage}
16625 * itself doesn't support cancellation. Instead, the operator detaches from the {@code CompletionStage}.
16626 * <dl>
16627 * <dt><b>Scheduler:</b></dt>
16628 * <dd>{@code fromCompletionStage} does not operate by default on a particular {@link Scheduler}.</dd>
16629 * </dl>
16630 * @param <T> the element type of the {@code CompletionStage}
16631 * @param stage the {@code CompletionStage} to convert to {@code Observable} and signal its terminal value or error
16632 * @return the new {@code Observable} instance
16633 * @throws NullPointerException if {@code stage} is {@code null}
16634 * @since 3.0.0
16635 */
16636 @CheckReturnValue
16637 @SchedulerSupport(SchedulerSupport.NONE)
16638 @NonNull
16639 public static <@NonNull T> Observable<@NonNull T> fromCompletionStage(@NonNull CompletionStage<T> stage) {
16640 Objects.requireNonNull(stage, "stage is null");
16641 return RxJavaPlugins.onAssembly(new ObservableFromCompletionStage<>(stage));
16642 }
16643
16644 /**
16645 * Converts a {@link Stream} into a finite {@code Observable} and emits its items in the sequence.
16646 * <p>
16647 * <img width="640" height="407" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/fromStream.o.png" alt="">
16648 * <p>
16649 * The operator closes the {@code Stream} upon cancellation and when it terminates. The exceptions raised when
16650 * closing a {@code Stream} are routed to the global error handler ({@link RxJavaPlugins#onError(Throwable)}.
16651 * If a {@code Stream} should not be closed, turn it into an {@link Iterable} and use {@link #fromIterable(Iterable)}:
16652 * <pre><code>
16653 * Stream&lt;T&gt; stream = ...
16654 * Observable.fromIterable(stream::iterator);
16655 * </code></pre>
16656 * <p>
16657 * Note that {@code Stream}s can be consumed only once; any subsequent attempt to consume a {@code Stream}
16658 * will result in an {@link IllegalStateException}.
16659 * <p>
16660 * Primitive streams are not supported and items have to be boxed manually (e.g., via {@link IntStream#boxed()}):
16661 * <pre><code>
16662 * IntStream intStream = IntStream.rangeClosed(1, 10);
16663 * Observable.fromStream(intStream.boxed());
16664 * </code></pre>
16665 * <p>
16666 * {@code Stream} does not support concurrent usage so creating and/or consuming the same instance multiple times
16667 * from multiple threads can lead to undefined behavior.
16668 * <dl>
16669 * <dt><b>Scheduler:</b></dt>
16670 * <dd>{@code fromStream} does not operate by default on a particular {@link Scheduler}.</dd>
16671 * </dl>
16672 * @param <T> the element type of the source {@code Stream}
16673 * @param stream the {@code Stream} of values to emit
16674 * @return the new {@code Observable} instance
16675 * @throws NullPointerException if {@code stream} is {@code null}
16676 * @since 3.0.0
16677 * @see #fromIterable(Iterable)
16678 */
16679 @CheckReturnValue
16680 @SchedulerSupport(SchedulerSupport.NONE)
16681 @NonNull
16682 public static <@NonNull T> Observable<@NonNull T> fromStream(@NonNull Stream<T> stream) {
16683 Objects.requireNonNull(stream, "stream is null");
16684 return RxJavaPlugins.onAssembly(new ObservableFromStream<>(stream));
16685 }
16686
16687 /**
16688 * Maps each upstream value into an {@link Optional} and emits the contained item if not empty.
16689 * <p>
16690 * <img width="640" height="306" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/mapOptional.o.png" alt="">
16691 *
16692 * <dl>
16693 * <dt><b>Scheduler:</b></dt>
16694 * <dd>{@code mapOptional} does not operate by default on a particular {@link Scheduler}.</dd>
16695 * </dl>
16696 * @param <R> the non-{@code null} output type
16697 * @param mapper the function that receives the upstream item and should return a <em>non-empty</em> {@code Optional}
16698 * to emit as the output or an <em>empty</em> {@code Optional} to skip to the next upstream value
16699 * @return the new {@code Observable} instance
16700 * @throws NullPointerException if {@code mapper} is {@code null}
16701 * @since 3.0.0
16702 * @see #map(Function)
16703 * @see #filter(Predicate)
16704 */
16705 @CheckReturnValue
16706 @SchedulerSupport(SchedulerSupport.NONE)
16707 @NonNull
16708 public final <@NonNull R> Observable<R> mapOptional(@NonNull Function<? super T, @NonNull Optional<? extends R>> mapper) {
16709 Objects.requireNonNull(mapper, "mapper is null");
16710 return RxJavaPlugins.onAssembly(new ObservableMapOptional<>(this, mapper));
16711 }
16712
16713 /**
16714 * Collects the finite upstream's values into a container via a {@link Stream} {@link Collector} callback set and emits
16715 * it as the success result as a {@link Single}.
16716 * <p>
16717 * <img width="640" height="358" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/collector.o.png" alt="">
16718 *
16719 * <dl>
16720 * <dt><b>Scheduler:</b></dt>
16721 * <dd>{@code collect} does not operate by default on a particular {@link Scheduler}.</dd>
16722 * </dl>
16723 * @param <R> the non-{@code null} result type
16724 * @param <A> the intermediate container type used for the accumulation
16725 * @param collector the interface defining the container supplier, accumulator and finisher functions;
16726 * see {@link Collectors} for some standard implementations
16727 * @return the new {@code Single} instance
16728 * @throws NullPointerException if {@code collector} is {@code null}
16729 * @since 3.0.0
16730 * @see Collectors
16731 * @see #collect(Supplier, BiConsumer)
16732 */
16733 @CheckReturnValue
16734 @SchedulerSupport(SchedulerSupport.NONE)
16735 @NonNull
16736 public final <@NonNull R, @NonNull A> Single<R> collect(@NonNull Collector<? super T, A, R> collector) {
16737 Objects.requireNonNull(collector, "collector is null");
16738 return RxJavaPlugins.onAssembly(new ObservableCollectWithCollectorSingle<>(this, collector));
16739 }
16740
16741 /**
16742 * Signals the first upstream item (or the default item if the upstream is empty) via
16743 * a {@link CompletionStage}.
16744 * <p>
16745 * <img width="640" height="313" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/firstStage.o.png" alt="">
16746 * <p>
16747 * The upstream can be canceled by converting the resulting {@code CompletionStage} into
16748 * {@link CompletableFuture} via {@link CompletionStage#toCompletableFuture()} and
16749 * calling {@link CompletableFuture#cancel(boolean)} on it.
16750 * The upstream will be also cancelled if the resulting {@code CompletionStage} is converted to and
16751 * completed manually by {@link CompletableFuture#complete(Object)} or {@link CompletableFuture#completeExceptionally(Throwable)}.
16752 * <p>
16753 * {@code CompletionStage}s don't have a notion of emptiness and allow {@code null}s, therefore, one can either use
16754 * a {@code defaultItem} of {@code null} or turn the flow into a sequence of {@link Optional}s and default to {@link Optional#empty()}:
16755 * <pre><code>
16756 * CompletionStage&lt;Optional&lt;T&gt;&gt; stage = source.map(Optional::of).firstStage(Optional.empty());
16757 * </code></pre>
16758 * <dl>
16759 * <dt><b>Scheduler:</b></dt>
16760 * <dd>{@code firstStage} does not operate by default on a particular {@link Scheduler}.</dd>
16761 * </dl>
16762 * @param defaultItem the item to signal if the upstream is empty
16763 * @return the new {@code CompletionStage} instance
16764 * @throws NullPointerException if {@code defaultItem} is {@code null}
16765 * @since 3.0.0
16766 * @see #firstOrErrorStage()
16767 */
16768 @CheckReturnValue
16769 @SchedulerSupport(SchedulerSupport.NONE)
16770 @NonNull
16771 public final CompletionStage<T> firstStage(@Nullable T defaultItem) {
16772 return subscribeWith(new ObservableFirstStageObserver<>(true, defaultItem));
16773 }
16774
16775 /**
16776 * Signals the only expected upstream item (or the default item if the upstream is empty)
16777 * or signals {@link IllegalArgumentException} if the upstream has more than one item
16778 * via a {@link CompletionStage}.
16779 * <p>
16780 * <img width="640" height="227" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/singleStage.o.png" alt="">
16781 * <p>
16782 * The upstream can be canceled by converting the resulting {@code CompletionStage} into
16783 * {@link CompletableFuture} via {@link CompletionStage#toCompletableFuture()} and
16784 * calling {@link CompletableFuture#cancel(boolean)} on it.
16785 * The upstream will be also cancelled if the resulting {@code CompletionStage} is converted to and
16786 * completed manually by {@link CompletableFuture#complete(Object)} or {@link CompletableFuture#completeExceptionally(Throwable)}.
16787 * <p>
16788 * {@code CompletionStage}s don't have a notion of emptiness and allow {@code null}s, therefore, one can either use
16789 * a {@code defaultItem} of {@code null} or turn the flow into a sequence of {@link Optional}s and default to {@link Optional#empty()}:
16790 * <pre><code>
16791 * CompletionStage&lt;Optional&lt;T&gt;&gt; stage = source.map(Optional::of).singleStage(Optional.empty());
16792 * </code></pre>
16793 * <dl>
16794 * <dt><b>Scheduler:</b></dt>
16795 * <dd>{@code singleStage} does not operate by default on a particular {@link Scheduler}.</dd>
16796 * </dl>
16797 * @param defaultItem the item to signal if the upstream is empty
16798 * @return the new {@code CompletionStage} instance
16799 * @throws NullPointerException if {@code defaultItem} is {@code null}
16800 * @since 3.0.0
16801 * @see #singleOrErrorStage()
16802 */
16803 @CheckReturnValue
16804 @SchedulerSupport(SchedulerSupport.NONE)
16805 @NonNull
16806 public final CompletionStage<T> singleStage(@Nullable T defaultItem) {
16807 return subscribeWith(new ObservableSingleStageObserver<>(true, defaultItem));
16808 }
16809
16810 /**
16811 * Signals the last upstream item (or the default item if the upstream is empty) via
16812 * a {@link CompletionStage}.
16813 * <p>
16814 * <img width="640" height="313" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/lastStage.o.png" alt="">
16815 * <p>
16816 * The upstream can be canceled by converting the resulting {@code CompletionStage} into
16817 * {@link CompletableFuture} via {@link CompletionStage#toCompletableFuture()} and
16818 * calling {@link CompletableFuture#cancel(boolean)} on it.
16819 * The upstream will be also cancelled if the resulting {@code CompletionStage} is converted to and
16820 * completed manually by {@link CompletableFuture#complete(Object)} or {@link CompletableFuture#completeExceptionally(Throwable)}.
16821 * <p>
16822 * {@code CompletionStage}s don't have a notion of emptiness and allow {@code null}s, therefore, one can either use
16823 * a {@code defaultItem} of {@code null} or turn the flow into a sequence of {@link Optional}s and default to {@link Optional#empty()}:
16824 * <pre><code>
16825 * CompletionStage&lt;Optional&lt;T&gt;&gt; stage = source.map(Optional::of).lastStage(Optional.empty());
16826 * </code></pre>
16827 * <dl>
16828 * <dt><b>Scheduler:</b></dt>
16829 * <dd>{@code lastStage} does not operate by default on a particular {@link Scheduler}.</dd>
16830 * </dl>
16831 * @param defaultItem the item to signal if the upstream is empty
16832 * @return the new {@code CompletionStage} instance
16833 * @throws NullPointerException if {@code defaultItem} is {@code null}
16834 * @since 3.0.0
16835 * @see #lastOrErrorStage()
16836 */
16837 @CheckReturnValue
16838 @SchedulerSupport(SchedulerSupport.NONE)
16839 @NonNull
16840 public final CompletionStage<T> lastStage(@Nullable T defaultItem) {
16841 return subscribeWith(new ObservableLastStageObserver<>(true, defaultItem));
16842 }
16843
16844 /**
16845 * Signals the first upstream item or a {@link NoSuchElementException} if the upstream is empty via
16846 * a {@link CompletionStage}.
16847 * <p>
16848 * <img width="640" height="341" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/firstOrErrorStage.o.png" alt="">
16849 * <p>
16850 * The upstream can be canceled by converting the resulting {@code CompletionStage} into
16851 * {@link CompletableFuture} via {@link CompletionStage#toCompletableFuture()} and
16852 * calling {@link CompletableFuture#cancel(boolean)} on it.
16853 * The upstream will be also cancelled if the resulting {@code CompletionStage} is converted to and
16854 * completed manually by {@link CompletableFuture#complete(Object)} or {@link CompletableFuture#completeExceptionally(Throwable)}.
16855 * <dl>
16856 * <dt><b>Scheduler:</b></dt>
16857 * <dd>{@code firstOrErrorStage} does not operate by default on a particular {@link Scheduler}.</dd>
16858 * </dl>
16859 * @return the new {@code CompletionStage} instance
16860 * @since 3.0.0
16861 * @see #firstStage(Object)
16862 */
16863 @CheckReturnValue
16864 @SchedulerSupport(SchedulerSupport.NONE)
16865 @NonNull
16866 public final CompletionStage<T> firstOrErrorStage() {
16867 return subscribeWith(new ObservableFirstStageObserver<>(false, null));
16868 }
16869
16870 /**
16871 * Signals the only expected upstream item, a {@link NoSuchElementException} if the upstream is empty
16872 * or signals {@link IllegalArgumentException} if the upstream has more than one item
16873 * via a {@link CompletionStage}.
16874 * <p>
16875 * <img width="640" height="227" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/singleOrErrorStage.o.png" alt="">
16876 * <p>
16877 * The upstream can be canceled by converting the resulting {@code CompletionStage} into
16878 * {@link CompletableFuture} via {@link CompletionStage#toCompletableFuture()} and
16879 * calling {@link CompletableFuture#cancel(boolean)} on it.
16880 * The upstream will be also cancelled if the resulting {@code CompletionStage} is converted to and
16881 * completed manually by {@link CompletableFuture#complete(Object)} or {@link CompletableFuture#completeExceptionally(Throwable)}.
16882 * <dl>
16883 * <dt><b>Scheduler:</b></dt>
16884 * <dd>{@code singleOrErrorStage} does not operate by default on a particular {@link Scheduler}.</dd>
16885 * </dl>
16886 * @return the new {@code CompletionStage} instance
16887 * @since 3.0.0
16888 * @see #singleStage(Object)
16889 */
16890 @CheckReturnValue
16891 @SchedulerSupport(SchedulerSupport.NONE)
16892 @NonNull
16893 public final CompletionStage<T> singleOrErrorStage() {
16894 return subscribeWith(new ObservableSingleStageObserver<>(false, null));
16895 }
16896
16897 /**
16898 * Signals the last upstream item or a {@link NoSuchElementException} if the upstream is empty via
16899 * a {@link CompletionStage}.
16900 * <p>
16901 * <img width="640" height="343" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/lastOrErrorStage.o.png" alt="">
16902 * <p>
16903 * The upstream can be canceled by converting the resulting {@code CompletionStage} into
16904 * {@link CompletableFuture} via {@link CompletionStage#toCompletableFuture()} and
16905 * calling {@link CompletableFuture#cancel(boolean)} on it.
16906 * The upstream will be also cancelled if the resulting {@code CompletionStage} is converted to and
16907 * completed manually by {@link CompletableFuture#complete(Object)} or {@link CompletableFuture#completeExceptionally(Throwable)}.
16908 * <dl>
16909 * <dt><b>Scheduler:</b></dt>
16910 * <dd>{@code lastOrErrorStage} does not operate by default on a particular {@link Scheduler}.</dd>
16911 * </dl>
16912 * @return the new {@code CompletionStage} instance
16913 * @since 3.0.0
16914 * @see #lastStage(Object)
16915 */
16916 @CheckReturnValue
16917 @SchedulerSupport(SchedulerSupport.NONE)
16918 @NonNull
16919 public final CompletionStage<T> lastOrErrorStage() {
16920 return subscribeWith(new ObservableLastStageObserver<>(false, null));
16921 }
16922
16923 /**
16924 * Creates a sequential {@link Stream} to consume or process the current {@code Observable} in a blocking manner via
16925 * the Java {@code Stream} API.
16926 * <p>
16927 * <img width="640" height="399" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/blockingStream.o.png" alt="">
16928 * <p>
16929 * Cancellation of the upstream is done via {@link Stream#close()}, therefore, it is strongly recommended the
16930 * consumption is performed within a try-with-resources construct:
16931 * <pre><code>
16932 * Observable&lt;Integer&gt; source = Observable.range(1, 10)
16933 * .subscribeOn(Schedulers.computation());
16934 *
16935 * try (Stream&lt;Integer&gt; stream = source.blockingStream()) {
16936 * stream.limit(3).forEach(System.out::println);
16937 * }
16938 * </code></pre>
16939 * <dl>
16940 * <dt><b>Scheduler:</b></dt>
16941 * <dd>{@code blockingStream} does not operate by default on a particular {@link Scheduler}.</dd>
16942 * </dl>
16943 *
16944 * @return the new {@code Stream} instance
16945 * @since 3.0.0
16946 * @see #blockingStream(int)
16947 */
16948 @CheckReturnValue
16949 @SchedulerSupport(SchedulerSupport.NONE)
16950 @NonNull
16951 public final Stream<T> blockingStream() {
16952 return blockingStream(bufferSize());
16953 }
16954
16955 /**
16956 * Creates a sequential {@link Stream} to consume or process the current {@code Observable} in a blocking manner via
16957 * the Java {@code Stream} API.
16958 * <p>
16959 * <img width="640" height="399" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/blockingStream.oi.png" alt="">
16960 * <p>
16961 * Cancellation of the upstream is done via {@link Stream#close()}, therefore, it is strongly recommended the
16962 * consumption is performed within a try-with-resources construct:
16963 * <pre><code>
16964 * Observable&lt;Integer&gt; source = Observable.range(1, 10)
16965 * .subscribeOn(Schedulers.computation());
16966 *
16967 * try (Stream&lt;Integer&gt; stream = source.blockingStream(4)) {
16968 * stream.limit(3).forEach(System.out::println);
16969 * }
16970 * </code></pre>
16971 * <dl>
16972 * <dt><b>Scheduler:</b></dt>
16973 * <dd>{@code blockingStream} does not operate by default on a particular {@link Scheduler}.</dd>
16974 * </dl>
16975 *
16976 * @param capacityHint the expected number of items to be buffered
16977 * @return the new {@code Stream} instance
16978 * @throws IllegalArgumentException if {@code capacityHint} is non-positive
16979 * @since 3.0.0
16980 */
16981 @CheckReturnValue
16982 @SchedulerSupport(SchedulerSupport.NONE)
16983 @NonNull
16984 public final Stream<T> blockingStream(int capacityHint) {
16985 Iterator<T> iterator = blockingIterable(capacityHint).iterator();
16986 return StreamSupport.stream(Spliterators.spliteratorUnknownSize(iterator, 0), false)
16987 .onClose(((Disposable) iterator)::dispose);
16988 }
16989
16990 /**
16991 * Maps each upstream item into a {@link Stream} and emits the {@code Stream}'s items to the downstream in a sequential fashion.
16992 * <p>
16993 * <img width="640" height="299" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/concatMapStream.o.png" alt="">
16994 * <p>
16995 * Due to the blocking and sequential nature of Java {@code Stream}s, the streams are mapped and consumed in a sequential fashion
16996 * without interleaving (unlike a more general {@link #flatMap(Function)}). Therefore, {@code flatMapStream} and
16997 * {@code concatMapStream} are identical operators and are provided as aliases.
16998 * <p>
16999 * The operator closes the {@code Stream} upon cancellation and when it terminates. The exceptions raised when
17000 * closing a {@code Stream} are routed to the global error handler ({@link RxJavaPlugins#onError(Throwable)}.
17001 * If a {@code Stream} should not be closed, turn it into an {@link Iterable} and use {@link #concatMapIterable(Function)}:
17002 * <pre><code>
17003 * source.concatMapIterable(v -&gt; createStream(v)::iterator);
17004 * </code></pre>
17005 * <p>
17006 * Note that {@code Stream}s can be consumed only once; any subsequent attempt to consume a {@code Stream}
17007 * will result in an {@link IllegalStateException}.
17008 * <p>
17009 * Primitive streams are not supported and items have to be boxed manually (e.g., via {@link IntStream#boxed()}):
17010 * <pre><code>
17011 * source.concatMapStream(v -&gt; IntStream.rangeClosed(v + 1, v + 10).boxed());
17012 * </code></pre>
17013 * <p>
17014 * {@code Stream} does not support concurrent usage so creating and/or consuming the same instance multiple times
17015 * from multiple threads can lead to undefined behavior.
17016 * <dl>
17017 * <dt><b>Scheduler:</b></dt>
17018 * <dd>{@code concatMapStream} does not operate by default on a particular {@link Scheduler}.</dd>
17019 * </dl>
17020 *
17021 * @param <R> the element type of the {@code Stream}s and the result
17022 * @param mapper the function that receives an upstream item and should return a {@code Stream} whose elements
17023 * will be emitted to the downstream
17024 * @return the new {@code Observable} instance
17025 * @since 3.0.0
17026 * @throws NullPointerException if {@code mapper} is {@code null}
17027 * @see #concatMap(Function)
17028 * @see #concatMapIterable(Function)
17029 * @see #flatMapStream(Function)
17030 */
17031 @CheckReturnValue
17032 @SchedulerSupport(SchedulerSupport.NONE)
17033 @NonNull
17034 public final <@NonNull R> Observable<R> concatMapStream(@NonNull Function<? super T, @NonNull ? extends Stream<? extends R>> mapper) {
17035 return flatMapStream(mapper);
17036 }
17037
17038 /**
17039 * Maps each upstream item into a {@link Stream} and emits the {@code Stream}'s items to the downstream in a sequential fashion.
17040 * <p>
17041 * <img width="640" height="299" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/flatMapStream.o.png" alt="">
17042 * <p>
17043 * Due to the blocking and sequential nature of Java {@code Stream}s, the streams are mapped and consumed in a sequential fashion
17044 * without interleaving (unlike a more general {@link #flatMap(Function)}). Therefore, {@code flatMapStream} and
17045 * {@code concatMapStream} are identical operators and are provided as aliases.
17046 * <p>
17047 * The operator closes the {@code Stream} upon cancellation and when it terminates. The exceptions raised when
17048 * closing a {@code Stream} are routed to the global error handler ({@link RxJavaPlugins#onError(Throwable)}.
17049 * If a {@code Stream} should not be closed, turn it into an {@link Iterable} and use {@link #flatMapIterable(Function)}:
17050 * <pre><code>
17051 * source.flatMapIterable(v -&gt; createStream(v)::iterator);
17052 * </code></pre>
17053 * <p>
17054 * Note that {@code Stream}s can be consumed only once; any subsequent attempt to consume a {@code Stream}
17055 * will result in an {@link IllegalStateException}.
17056 * <p>
17057 * Primitive streams are not supported and items have to be boxed manually (e.g., via {@link IntStream#boxed()}):
17058 * <pre><code>
17059 * source.flatMapStream(v -&gt; IntStream.rangeClosed(v + 1, v + 10).boxed());
17060 * </code></pre>
17061 * <p>
17062 * {@code Stream} does not support concurrent usage so creating and/or consuming the same instance multiple times
17063 * from multiple threads can lead to undefined behavior.
17064 * <dl>
17065 * <dt><b>Scheduler:</b></dt>
17066 * <dd>{@code flatMapStream} does not operate by default on a particular {@link Scheduler}.</dd>
17067 * </dl>
17068 *
17069 * @param <R> the element type of the {@code Stream}s and the result
17070 * @param mapper the function that receives an upstream item and should return a {@code Stream} whose elements
17071 * will be emitted to the downstream
17072 * @return the new {@code Observable} instance
17073 * @since 3.0.0
17074 * @throws NullPointerException if {@code mapper} is {@code null}
17075 * @see #flatMap(Function)
17076 * @see #flatMapIterable(Function)
17077 */
17078 @CheckReturnValue
17079 @SchedulerSupport(SchedulerSupport.NONE)
17080 @NonNull
17081 public final <@NonNull R> Observable<R> flatMapStream(@NonNull Function<? super T, @NonNull ? extends Stream<? extends R>> mapper) {
17082 Objects.requireNonNull(mapper, "mapper is null");
17083 return RxJavaPlugins.onAssembly(new ObservableFlatMapStream<>(this, mapper));
17084 }
17085 }