Debian Codegraph @

src/main/java/io/reactivex/rxjava3/core/Single.java

raw
1 /*
2 * Copyright (c) 2016-present, RxJava Contributors.
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in
5 * compliance with the License. You may obtain a copy of the License at
6 *
7 * http://www.apache.org/licenses/LICENSE-2.0
8 *
9 * Unless required by applicable law or agreed to in writing, software distributed under the License is
10 * distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See
11 * the License for the specific language governing permissions and limitations under the License.
12 */
13
14 package io.reactivex.rxjava3.core;
15
16 import java.util.*;
17 import java.util.concurrent.*;
18 import java.util.stream.*;
19
20 import org.reactivestreams.*;
21
22 import io.reactivex.rxjava3.annotations.*;
23 import io.reactivex.rxjava3.disposables.*;
24 import io.reactivex.rxjava3.exceptions.*;
25 import io.reactivex.rxjava3.functions.*;
26 import io.reactivex.rxjava3.internal.functions.*;
27 import io.reactivex.rxjava3.internal.fuseable.*;
28 import io.reactivex.rxjava3.internal.jdk8.*;
29 import io.reactivex.rxjava3.internal.observers.*;
30 import io.reactivex.rxjava3.internal.operators.completable.*;
31 import io.reactivex.rxjava3.internal.operators.flowable.*;
32 import io.reactivex.rxjava3.internal.operators.maybe.*;
33 import io.reactivex.rxjava3.internal.operators.mixed.*;
34 import io.reactivex.rxjava3.internal.operators.observable.ObservableSingleSingle;
35 import io.reactivex.rxjava3.internal.operators.single.*;
36 import io.reactivex.rxjava3.internal.util.ErrorMode;
37 import io.reactivex.rxjava3.observers.TestObserver;
38 import io.reactivex.rxjava3.plugins.RxJavaPlugins;
39 import io.reactivex.rxjava3.schedulers.*;
40
41 /**
42 * The {@code Single} class implements the Reactive Pattern for a single value response.
43 * <p>
44 * {@code Single} behaves similarly to {@link Observable} except that it can only emit either a single successful
45 * value or an error (there is no {@code onComplete} notification as there is for an {@code Observable}).
46 * <p>
47 * The {@code Single} class implements the {@link SingleSource} base interface and the default consumer
48 * type it interacts with is the {@link SingleObserver} via the {@link #subscribe(SingleObserver)} method.
49 * <p>
50 * The {@code Single} operates with the following sequential protocol:
51 * <pre>
52 * <code>onSubscribe (onSuccess | onError)?</code>
53 * </pre>
54 * <p>
55 * Note that {@code onSuccess} and {@code onError} are mutually exclusive events; unlike {@code Observable},
56 * {@code onSuccess} is never followed by {@code onError}.
57 * <p>
58 * Like {@code Observable}, a running {@code Single} can be stopped through the {@link Disposable} instance
59 * provided to consumers through {@link SingleObserver#onSubscribe}.
60 * <p>
61 * Like an {@code Observable}, a {@code Single} is lazy, can be either "hot" or "cold", synchronous or
62 * asynchronous. {@code Single} instances returned by the methods of this class are <em>cold</em>
63 * and there is a standard <em>hot</em> implementation in the form of a subject:
64 * {@link io.reactivex.rxjava3.subjects.SingleSubject SingleSubject}.
65 * <p>
66 * The documentation for this class makes use of marble diagrams. The following legend explains these diagrams:
67 * <p>
68 * <img width="640" height="301" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.legend.v3.png" alt="">
69 * <p>
70 * See {@link Flowable} or {@code Observable} for the
71 * implementation of the Reactive Pattern for a stream or vector of values.
72 * <p>
73 * For more information see the <a href="http://reactivex.io/documentation/single.html">ReactiveX
74 * documentation</a>.
75 * <p>
76 * Example:
77 * <pre><code>
78 * Disposable d = Single.just("Hello World")
79 * .delay(10, TimeUnit.SECONDS, Schedulers.io())
80 * .subscribeWith(new DisposableSingleObserver&lt;String&gt;() {
81 * &#64;Override
82 * public void onStart() {
83 * System.out.println("Started");
84 * }
85 *
86 * &#64;Override
87 * public void onSuccess(String value) {
88 * System.out.println("Success: " + value);
89 * }
90 *
91 * &#64;Override
92 * public void onError(Throwable error) {
93 * error.printStackTrace();
94 * }
95 * });
96 *
97 * Thread.sleep(5000);
98 *
99 * d.dispose();
100 * </code></pre>
101 * <p>
102 * Note that by design, subscriptions via {@link #subscribe(SingleObserver)} can't be disposed
103 * from the outside (hence the
104 * {@code void} return of the {@link #subscribe(SingleObserver)} method) and it is the
105 * responsibility of the implementor of the {@code SingleObserver} to allow this to happen.
106 * RxJava supports such usage with the standard
107 * {@link io.reactivex.rxjava3.observers.DisposableSingleObserver DisposableSingleObserver} instance.
108 * For convenience, the {@link #subscribeWith(SingleObserver)} method is provided as well to
109 * allow working with a {@code SingleObserver} (or subclass) instance to be applied with in
110 * a fluent manner (such as in the example above).
111 * @param <T>
112 * the type of the item emitted by the {@code Single}
113 * @since 2.0
114 * @see io.reactivex.rxjava3.observers.DisposableSingleObserver
115 */
116 public abstract class Single<@NonNull T> implements SingleSource<T> {
117
118 /**
119 * Runs multiple {@link SingleSource}s and signals the events of the first one that signals (disposing
120 * the rest).
121 * <p>
122 * <img width="640" height="516" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.amb.v3.png" alt="">
123 * <dl>
124 * <dt><b>Scheduler:</b></dt>
125 * <dd>{@code amb} does not operate by default on a particular {@link Scheduler}.</dd>
126 * </dl>
127 * @param <T> the value type
128 * @param sources the {@link Iterable} sequence of sources. A subscription to each source will
129 * occur in the same order as in this {@code Iterable}.
130 * @return the new {@code Single} instance
131 * @throws NullPointerException if {@code sources} is {@code null}
132 * @since 2.0
133 */
134 @CheckReturnValue
135 @NonNull
136 @SchedulerSupport(SchedulerSupport.NONE)
137 public static <@NonNull T> Single<T> amb(@NonNull Iterable<@NonNull ? extends SingleSource<? extends T>> sources) {
138 Objects.requireNonNull(sources, "sources is null");
139 return RxJavaPlugins.onAssembly(new SingleAmb<>(null, sources));
140 }
141
142 /**
143 * Runs multiple {@link SingleSource}s and signals the events of the first one that signals (disposing
144 * the rest).
145 * <p>
146 * <img width="640" height="516" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.ambArray.v3.png" alt="">
147 * <dl>
148 * <dt><b>Scheduler:</b></dt>
149 * <dd>{@code ambArray} does not operate by default on a particular {@link Scheduler}.</dd>
150 * </dl>
151 * @param <T> the value type
152 * @param sources the array of sources. A subscription to each source will
153 * occur in the same order as in this array.
154 * @return the new {@code Single} instance
155 * @throws NullPointerException if {@code sources} is {@code null}
156 * @since 2.0
157 */
158 @CheckReturnValue
159 @SchedulerSupport(SchedulerSupport.NONE)
160 @SafeVarargs
161 @NonNull
162 public static <@NonNull T> Single<T> ambArray(@NonNull SingleSource<? extends T>... sources) {
163 Objects.requireNonNull(sources, "sources is null");
164 if (sources.length == 0) {
165 return error(SingleInternalHelper.emptyThrower());
166 }
167 if (sources.length == 1) {
168 @SuppressWarnings("unchecked")
169 SingleSource<T> source = (SingleSource<T>)sources[0];
170 return wrap(source);
171 }
172 return RxJavaPlugins.onAssembly(new SingleAmb<>(sources, null));
173 }
174
175 /**
176 * Concatenate the single values, in a non-overlapping fashion, of the {@link SingleSource}s provided by
177 * an {@link Iterable} sequence.
178 * <p>
179 * <img width="640" height="319" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.concat.i.v3.png" alt="">
180 * <dl>
181 * <dt><b>Backpressure:</b></dt>
182 * <dd>The returned {@link Flowable} honors the backpressure of the downstream consumer.</dd>
183 * <dt><b>Scheduler:</b></dt>
184 * <dd>{@code concat} does not operate by default on a particular {@link Scheduler}.</dd>
185 * </dl>
186 * @param <T> the value type
187 * @param sources the {@code Iterable} sequence of {@code SingleSource} instances
188 * @return the new {@code Flowable} instance
189 * @throws NullPointerException if {@code sources} is {@code null}
190 * @since 2.0
191 */
192 @CheckReturnValue
193 @NonNull
194 @SchedulerSupport(SchedulerSupport.NONE)
195 @BackpressureSupport(BackpressureKind.FULL)
196 public static <@NonNull T> Flowable<T> concat(@NonNull Iterable<@NonNull ? extends SingleSource<? extends T>> sources) {
197 return Flowable.fromIterable(sources).concatMapSingleDelayError(Functions.identity(), false);
198 }
199
200 /**
201 * Concatenate the single values, in a non-overlapping fashion, of the {@link SingleSource}s provided by
202 * an {@link ObservableSource} sequence.
203 * <p>
204 * <img width="640" height="319" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.concat.o.v3.png" alt="">
205 * <dl>
206 * <dt><b>Scheduler:</b></dt>
207 * <dd>{@code concat} does not operate by default on a particular {@link Scheduler}.</dd>
208 * </dl>
209 * @param <T> the value type
210 * @param sources the {@code ObservableSource} of {@code SingleSource} instances
211 * @return the new {@link Observable} instance
212 * @throws NullPointerException if {@code sources} is {@code null}
213 * @since 2.0
214 */
215 @CheckReturnValue
216 @NonNull
217 @SchedulerSupport(SchedulerSupport.NONE)
218 public static <@NonNull T> Observable<T> concat(@NonNull ObservableSource<? extends SingleSource<? extends T>> sources) {
219 Objects.requireNonNull(sources, "sources is null");
220 return RxJavaPlugins.onAssembly(new ObservableConcatMapSingle<>(sources, Functions.identity(), ErrorMode.IMMEDIATE, 2));
221 }
222
223 /**
224 * Concatenate the single values, in a non-overlapping fashion, of the {@link SingleSource}s provided by
225 * a {@link Publisher} sequence.
226 * <p>
227 * <img width="640" height="309" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.concat.p.v3.png" alt="">
228 * <dl>
229 * <dt><b>Backpressure:</b></dt>
230 * <dd>The returned {@link Flowable} honors the backpressure of the downstream consumer
231 * and the sources {@code Publisher} is expected to honor it as well.</dd>
232 * <dt><b>Scheduler:</b></dt>
233 * <dd>{@code concat} does not operate by default on a particular {@link Scheduler}.</dd>
234 * </dl>
235 * @param <T> the value type
236 * @param sources the {@code Publisher} of {@code SingleSource} instances
237 * @return the new {@code Flowable} instance
238 * @throws NullPointerException if {@code sources} is {@code null}
239 * @since 2.0
240 */
241 @CheckReturnValue
242 @NonNull
243 @BackpressureSupport(BackpressureKind.FULL)
244 @SchedulerSupport(SchedulerSupport.NONE)
245 public static <@NonNull T> Flowable<T> concat(@NonNull Publisher<@NonNull ? extends SingleSource<? extends T>> sources) {
246 return concat(sources, 2);
247 }
248
249 /**
250 * Concatenate the single values, in a non-overlapping fashion, of the {@link SingleSource}s provided by
251 * a {@link Publisher} sequence and prefetched by the specified amount.
252 * <p>
253 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.concat.pn.v3.png" alt="">
254 * <dl>
255 * <dt><b>Backpressure:</b></dt>
256 * <dd>The returned {@link Flowable} honors the backpressure of the downstream consumer
257 * and the sources {@code Publisher} is expected to honor it as well.</dd>
258 * <dt><b>Scheduler:</b></dt>
259 * <dd>{@code concat} does not operate by default on a particular {@link Scheduler}.</dd>
260 * </dl>
261 * @param <T> the value type
262 * @param sources the {@code Publisher} of {@code SingleSource} instances
263 * @param prefetch the number of {@code SingleSource}s to prefetch from the {@code Publisher}
264 * @return the new {@code Flowable} instance
265 * @throws NullPointerException if {@code sources} is {@code null}
266 * @throws IllegalArgumentException if {@code prefetch} is non-positive
267 * @since 2.0
268 */
269 @CheckReturnValue
270 @NonNull
271 @BackpressureSupport(BackpressureKind.FULL)
272 @SchedulerSupport(SchedulerSupport.NONE)
273 public static <@NonNull T> Flowable<T> concat(@NonNull Publisher<@NonNull ? extends SingleSource<? extends T>> sources, int prefetch) {
274 Objects.requireNonNull(sources, "sources is null");
275 ObjectHelper.verifyPositive(prefetch, "prefetch");
276 return RxJavaPlugins.onAssembly(new FlowableConcatMapSinglePublisher<>(sources, Functions.identity(), ErrorMode.IMMEDIATE, prefetch));
277 }
278
279 /**
280 * Returns a {@link Flowable} that emits the items emitted by two {@link SingleSource}s, one after the other.
281 * <p>
282 * <img width="640" height="366" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.concat.v3.png" alt="">
283 * <dl>
284 * <dt><b>Backpressure:</b></dt>
285 * <dd>The returned {@code Flowable} honors the backpressure of the downstream consumer.</dd>
286 * <dt><b>Scheduler:</b></dt>
287 * <dd>{@code concat} does not operate by default on a particular {@link Scheduler}.</dd>
288 * </dl>
289 *
290 * @param <T> the common value type
291 * @param source1
292 * a {@code SingleSource} to be concatenated
293 * @param source2
294 * a {@code SingleSource} to be concatenated
295 * @return the new {@code Flowable} instance
296 * @throws NullPointerException if {@code source1} or {@code source2} is {@code null}
297 * @see <a href="http://reactivex.io/documentation/operators/concat.html">ReactiveX operators documentation: Concat</a>
298 */
299 @CheckReturnValue
300 @NonNull
301 @BackpressureSupport(BackpressureKind.FULL)
302 @SchedulerSupport(SchedulerSupport.NONE)
303 public static <@NonNull T> Flowable<T> concat(
304 @NonNull SingleSource<? extends T> source1, @NonNull SingleSource<? extends T> source2
305 ) {
306 Objects.requireNonNull(source1, "source1 is null");
307 Objects.requireNonNull(source2, "source2 is null");
308 return Flowable.fromArray(source1, source2).concatMapSingleDelayError(Functions.identity(), false);
309 }
310
311 /**
312 * Returns a {@link Flowable} that emits the items emitted by three {@link SingleSource}s, one after the other.
313 * <p>
314 * <img width="640" height="366" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.concat.o3.v3.png" alt="">
315 * <dl>
316 * <dt><b>Backpressure:</b></dt>
317 * <dd>The returned {@code Flowable} honors the backpressure of the downstream consumer.</dd>
318 * <dt><b>Scheduler:</b></dt>
319 * <dd>{@code concat} does not operate by default on a particular {@link Scheduler}.</dd>
320 * </dl>
321 *
322 * @param <T> the common value type
323 * @param source1
324 * a {@code SingleSource} to be concatenated
325 * @param source2
326 * a {@code SingleSource} to be concatenated
327 * @param source3
328 * a {@code SingleSource} to be concatenated
329 * @return the new {@code Flowable} instance
330 * @throws NullPointerException if {@code source1}, {@code source2} or {@code source3} is {@code null}
331 * @see <a href="http://reactivex.io/documentation/operators/concat.html">ReactiveX operators documentation: Concat</a>
332 */
333 @CheckReturnValue
334 @NonNull
335 @BackpressureSupport(BackpressureKind.FULL)
336 @SchedulerSupport(SchedulerSupport.NONE)
337 public static <@NonNull T> Flowable<T> concat(
338 @NonNull SingleSource<? extends T> source1, @NonNull SingleSource<? extends T> source2,
339 @NonNull SingleSource<? extends T> source3
340 ) {
341 Objects.requireNonNull(source1, "source1 is null");
342 Objects.requireNonNull(source2, "source2 is null");
343 Objects.requireNonNull(source3, "source3 is null");
344 return Flowable.fromArray(source1, source2, source3).concatMapSingleDelayError(Functions.identity(), false);
345 }
346
347 /**
348 * Returns a {@link Flowable} that emits the items emitted by four {@link SingleSource}s, one after the other.
349 * <p>
350 * <img width="640" height="362" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.concat.o4.v3.png" alt="">
351 * <dl>
352 * <dt><b>Backpressure:</b></dt>
353 * <dd>The returned {@code Flowable} honors the backpressure of the downstream consumer.</dd>
354 * <dt><b>Scheduler:</b></dt>
355 * <dd>{@code concat} does not operate by default on a particular {@link Scheduler}.</dd>
356 * </dl>
357 *
358 * @param <T> the common value type
359 * @param source1
360 * a {@code SingleSource} to be concatenated
361 * @param source2
362 * a {@code SingleSource} to be concatenated
363 * @param source3
364 * a {@code SingleSource} to be concatenated
365 * @param source4
366 * a {@code SingleSource} to be concatenated
367 * @return the new {@code Flowable} instance
368 * @throws NullPointerException if {@code source1}, {@code source2}, {@code source3} or {@code source4} is {@code null}
369 * @see <a href="http://reactivex.io/documentation/operators/concat.html">ReactiveX operators documentation: Concat</a>
370 */
371 @CheckReturnValue
372 @NonNull
373 @BackpressureSupport(BackpressureKind.FULL)
374 @SchedulerSupport(SchedulerSupport.NONE)
375 public static <@NonNull T> Flowable<T> concat(
376 @NonNull SingleSource<? extends T> source1, @NonNull SingleSource<? extends T> source2,
377 @NonNull SingleSource<? extends T> source3, @NonNull SingleSource<? extends T> source4
378 ) {
379 Objects.requireNonNull(source1, "source1 is null");
380 Objects.requireNonNull(source2, "source2 is null");
381 Objects.requireNonNull(source3, "source3 is null");
382 Objects.requireNonNull(source4, "source4 is null");
383 return Flowable.fromArray(source1, source2, source3, source4).concatMapSingleDelayError(Functions.identity(), false);
384 }
385
386 /**
387 * Concatenate the single values, in a non-overlapping fashion, of the {@link SingleSource}s provided in
388 * an array.
389 * <p>
390 * <img width="640" height="319" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.concatArray.v3.png" alt="">
391 * <dl>
392 * <dt><b>Backpressure:</b></dt>
393 * <dd>The returned {@link Flowable} honors the backpressure of the downstream consumer.</dd>
394 * <dt><b>Scheduler:</b></dt>
395 * <dd>{@code concatArray} does not operate by default on a particular {@link Scheduler}.</dd>
396 * </dl>
397 * @param <T> the value type
398 * @param sources the array of {@code SingleSource} instances
399 * @return the new {@code Flowable} instance
400 * @throws NullPointerException if {@code sources} is {@code null}
401 * @since 2.0
402 */
403 @CheckReturnValue
404 @NonNull
405 @BackpressureSupport(BackpressureKind.FULL)
406 @SchedulerSupport(SchedulerSupport.NONE)
407 @SafeVarargs
408 public static <@NonNull T> Flowable<T> concatArray(@NonNull SingleSource<? extends T>... sources) {
409 return Flowable.fromArray(sources).concatMapSingleDelayError(Functions.identity(), false);
410 }
411
412 /**
413 * Concatenate the single values, in a non-overlapping fashion, of the {@link SingleSource}s provided in
414 * an array.
415 * <p>
416 * <img width="640" height="408" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.concatArrayDelayError.png" alt="">
417 * <dl>
418 * <dt><b>Backpressure:</b></dt>
419 * <dd>The returned {@link Flowable} honors the backpressure of the downstream consumer.</dd>
420 * <dt><b>Scheduler:</b></dt>
421 * <dd>{@code concatArrayDelayError} does not operate by default on a particular {@link Scheduler}.</dd>
422 * </dl>
423 * @param <T> the value type
424 * @param sources the array of {@code SingleSource} instances
425 * @return the new {@code Flowable} instance
426 * @throws NullPointerException if {@code sources} is {@code null}
427 * @since 3.0.0
428 */
429 @CheckReturnValue
430 @NonNull
431 @BackpressureSupport(BackpressureKind.FULL)
432 @SchedulerSupport(SchedulerSupport.NONE)
433 @SafeVarargs
434 public static <@NonNull T> Flowable<T> concatArrayDelayError(@NonNull SingleSource<? extends T>... sources) {
435 return Flowable.fromArray(sources).concatMapSingleDelayError(Functions.identity(), true);
436 }
437
438 /**
439 * Concatenates a sequence of {@link SingleSource} eagerly into a single stream of values.
440 * <p>
441 * <img width="640" height="257" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.concatArrayEager.png" alt="">
442 * <p>
443 * Eager concatenation means that once a subscriber subscribes, this operator subscribes to all of the
444 * source {@code SingleSource}s. The operator buffers the value emitted by these {@code SingleSource}s and then drains them
445 * in order, each one after the previous one succeeds.
446 * <dl>
447 * <dt><b>Backpressure:</b></dt>
448 * <dd>The operator honors backpressure from downstream.</dd>
449 * <dt><b>Scheduler:</b></dt>
450 * <dd>This method does not operate by default on a particular {@link Scheduler}.</dd>
451 * </dl>
452 * @param <T> the value type
453 * @param sources a sequence of {@code SingleSource}s that need to be eagerly concatenated
454 * @return the new {@link Flowable} instance with the specified concatenation behavior
455 * @throws NullPointerException if {@code sources} is {@code null}
456 */
457 @BackpressureSupport(BackpressureKind.FULL)
458 @CheckReturnValue
459 @NonNull
460 @SchedulerSupport(SchedulerSupport.NONE)
461 @SafeVarargs
462 public static <@NonNull T> Flowable<T> concatArrayEager(@NonNull SingleSource<? extends T>... sources) {
463 return Flowable.fromArray(sources).concatMapEager(SingleInternalHelper.toFlowable());
464 }
465
466 /**
467 * Concatenates a sequence of {@link SingleSource} eagerly into a single stream of values.
468 * <p>
469 * <img width="640" height="426" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.concatArrayEagerDelayError.png" alt="">
470 * <p>
471 * Eager concatenation means that once a subscriber subscribes, this operator subscribes to all of the
472 * source {@code SingleSource}s. The operator buffers the value emitted by these {@code SingleSource}s and then drains them
473 * in order, each one after the previous one succeeds.
474 * <dl>
475 * <dt><b>Backpressure:</b></dt>
476 * <dd>The operator honors backpressure from downstream.</dd>
477 * <dt><b>Scheduler:</b></dt>
478 * <dd>This method does not operate by default on a particular {@link Scheduler}.</dd>
479 * </dl>
480 * @param <T> the value type
481 * @param sources a sequence of {@code SingleSource}s that need to be eagerly concatenated
482 * @return the new {@link Flowable} instance with the specified concatenation behavior
483 * @throws NullPointerException if {@code sources} is {@code null}
484 * @since 3.0.0
485 */
486 @BackpressureSupport(BackpressureKind.FULL)
487 @CheckReturnValue
488 @NonNull
489 @SchedulerSupport(SchedulerSupport.NONE)
490 @SafeVarargs
491 public static <@NonNull T> Flowable<T> concatArrayEagerDelayError(@NonNull SingleSource<? extends T>... sources) {
492 return Flowable.fromArray(sources).concatMapEagerDelayError(SingleInternalHelper.toFlowable(), true);
493 }
494
495 /**
496 * Concatenates the {@link Iterable} sequence of {@link SingleSource}s into a single sequence by subscribing to each {@code SingleSource},
497 * one after the other, one at a time and delays any errors till the all inner {@code SingleSource}s terminate
498 * as a {@link Flowable} sequence.
499 * <p>
500 * <img width="640" height="451" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.concatDelayError.i.png" alt="">
501 * <dl>
502 * <dt><b>Backpressure:</b></dt>
503 * <dd>The operator honors backpressure from downstream.</dd>
504 * <dt><b>Scheduler:</b></dt>
505 * <dd>{@code concatDelayError} does not operate by default on a particular {@link Scheduler}.</dd>
506 * </dl>
507 *
508 * @param <T> the common element base type
509 * @param sources the {@code Iterable} sequence of {@code SingleSource}s
510 * @return the new {@code Flowable} with the concatenating behavior
511 * @throws NullPointerException if {@code sources} is {@code null}
512 * @since 3.0.0
513 */
514 @BackpressureSupport(BackpressureKind.FULL)
515 @CheckReturnValue
516 @NonNull
517 @SchedulerSupport(SchedulerSupport.NONE)
518 public static <@NonNull T> Flowable<T> concatDelayError(@NonNull Iterable<@NonNull ? extends SingleSource<? extends T>> sources) {
519 return Flowable.fromIterable(sources).concatMapSingleDelayError(Functions.identity());
520 }
521
522 /**
523 * Concatenates the {@link Publisher} sequence of {@link SingleSource}s into a single sequence by subscribing to each inner {@code SingleSource},
524 * one after the other, one at a time and delays any errors till the all inner and the outer {@code Publisher} terminate
525 * as a {@link Flowable} sequence.
526 * <p>
527 * <img width="640" height="345" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.concatDelayError.p.png" alt="">
528 * <dl>
529 * <dt><b>Backpressure:</b></dt>
530 * <dd>{@code concatDelayError} fully supports backpressure.</dd>
531 * <dt><b>Scheduler:</b></dt>
532 * <dd>{@code concatDelayError} does not operate by default on a particular {@link Scheduler}.</dd>
533 * </dl>
534 *
535 * @param <T> the common element base type
536 * @param sources the {@code Publisher} sequence of {@code SingleSource}s
537 * @return the new {@code Flowable} with the concatenating behavior
538 * @throws NullPointerException if {@code sources} is {@code null}
539 * @since 3.0.0
540 */
541 @BackpressureSupport(BackpressureKind.FULL)
542 @CheckReturnValue
543 @SchedulerSupport(SchedulerSupport.NONE)
544 @NonNull
545 public static <@NonNull T> Flowable<T> concatDelayError(@NonNull Publisher<@NonNull ? extends SingleSource<? extends T>> sources) {
546 return Flowable.fromPublisher(sources).concatMapSingleDelayError(Functions.identity());
547 }
548
549 /**
550 * Concatenates the {@link Publisher} sequence of {@link SingleSource}s into a single sequence by subscribing to each inner {@code SingleSource},
551 * one after the other, one at a time and delays any errors till the all inner and the outer {@code Publisher} terminate
552 * as a {@link Flowable} sequence.
553 * <p>
554 * <img width="640" height="299" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.concatDelayError.pn.png" alt="">
555 * <dl>
556 * <dt><b>Backpressure:</b></dt>
557 * <dd>{@code concatDelayError} fully supports backpressure.</dd>
558 * <dt><b>Scheduler:</b></dt>
559 * <dd>{@code concatDelayError} does not operate by default on a particular {@link Scheduler}.</dd>
560 * </dl>
561 *
562 * @param <T> the common element base type
563 * @param sources the {@code Publisher} sequence of {@code SingleSource}s
564 * @param prefetch The number of upstream items to prefetch so that fresh items are
565 * ready to be mapped when a previous {@code SingleSource} terminates.
566 * The operator replenishes after half of the prefetch amount has been consumed
567 * and turned into {@code SingleSource}s.
568 * @return the new {@code Flowable} with the concatenating behavior
569 * @throws NullPointerException if {@code sources} is {@code null}
570 * @throws IllegalArgumentException if {@code prefetch} is non-positive
571 * @since 3.0.0
572 */
573 @BackpressureSupport(BackpressureKind.FULL)
574 @CheckReturnValue
575 @SchedulerSupport(SchedulerSupport.NONE)
576 @NonNull
577 public static <@NonNull T> Flowable<T> concatDelayError(@NonNull Publisher<@NonNull ? extends SingleSource<? extends T>> sources, int prefetch) {
578 return Flowable.fromPublisher(sources).concatMapSingleDelayError(Functions.identity(), true, prefetch);
579 }
580
581 /**
582 * Concatenates an {@link Iterable} sequence of {@link SingleSource}s eagerly into a single stream of values.
583 * <p>
584 * <img width="640" height="319" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.concatEager.i.v3.png" alt="">
585 * <p>
586 * Eager concatenation means that once a subscriber subscribes, this operator subscribes to all of the
587 * source {@code SingleSource}s. The operator buffers the values emitted by these {@code SingleSource}s and then drains them
588 * in order, each one after the previous one succeeds.
589 * <dl>
590 * <dt><b>Backpressure:</b></dt>
591 * <dd>Backpressure is honored towards the downstream.</dd>
592 * <dt><b>Scheduler:</b></dt>
593 * <dd>This method does not operate by default on a particular {@link Scheduler}.</dd>
594 * </dl>
595 * @param <T> the value type
596 * @param sources an {@code Iterable} sequence of {@code SingleSource} that need to be eagerly concatenated
597 * @return the new {@link Flowable} instance with the specified concatenation behavior
598 * @throws NullPointerException if {@code sources} is {@code null}
599 */
600 @BackpressureSupport(BackpressureKind.FULL)
601 @CheckReturnValue
602 @NonNull
603 @SchedulerSupport(SchedulerSupport.NONE)
604 public static <@NonNull T> Flowable<T> concatEager(@NonNull Iterable<@NonNull ? extends SingleSource<? extends T>> sources) {
605 return Flowable.fromIterable(sources).concatMapEagerDelayError(SingleInternalHelper.toFlowable(), false);
606 }
607
608 /**
609 * Concatenates an {@link Iterable} sequence of {@link SingleSource}s eagerly into a single stream of values and
610 * runs a limited number of the inner sources at once.
611 * <p>
612 * <img width="640" height="439" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.concatEager.in.png" alt="">
613 * <p>
614 * Eager concatenation means that once a subscriber subscribes, this operator subscribes to all of the
615 * source {@code SingleSource}s. The operator buffers the values emitted by these {@code SingleSource}s and then drains them
616 * in order, each one after the previous one succeeds.
617 * <dl>
618 * <dt><b>Backpressure:</b></dt>
619 * <dd>Backpressure is honored towards the downstream.</dd>
620 * <dt><b>Scheduler:</b></dt>
621 * <dd>This method does not operate by default on a particular {@link Scheduler}.</dd>
622 * </dl>
623 * @param <T> the value type
624 * @param sources an {@code Iterable} sequence of {@code SingleSource} that need to be eagerly concatenated
625 * @param maxConcurrency the maximum number of concurrently running inner {@code SingleSource}s; {@link Integer#MAX_VALUE}
626 * is interpreted as all inner {@code SingleSource}s can be active at the same time
627 * @return the new {@link Flowable} instance with the specified concatenation behavior
628 * @throws NullPointerException if {@code sources} is {@code null}
629 * @throws IllegalArgumentException if {@code maxConcurrency} is non-positive
630 * @since 3.0.0
631 */
632 @BackpressureSupport(BackpressureKind.FULL)
633 @CheckReturnValue
634 @NonNull
635 @SchedulerSupport(SchedulerSupport.NONE)
636 public static <@NonNull T> Flowable<T> concatEager(@NonNull Iterable<@NonNull ? extends SingleSource<? extends T>> sources, int maxConcurrency) {
637 return Flowable.fromIterable(sources).concatMapEagerDelayError(SingleInternalHelper.toFlowable(), false, maxConcurrency, 1);
638 }
639
640 /**
641 * Concatenates a {@link Publisher} sequence of {@link SingleSource}s eagerly into a single stream of values.
642 * <p>
643 * <img width="640" height="307" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.concatEager.p.v3.png" alt="">
644 * <p>
645 * Eager concatenation means that once a subscriber subscribes, this operator subscribes to all of the
646 * emitted source {@code SingleSource}s as they are observed. The operator buffers the values emitted by these
647 * {@code SingleSource}s and then drains them in order, each one after the previous one succeeds.
648 * <dl>
649 * <dt><b>Backpressure:</b></dt>
650 * <dd>Backpressure is honored towards the downstream and the outer {@code Publisher} is
651 * expected to support backpressure. Violating this assumption, the operator will
652 * signal {@link io.reactivex.rxjava3.exceptions.MissingBackpressureException}.</dd>
653 * <dt><b>Scheduler:</b></dt>
654 * <dd>This method does not operate by default on a particular {@link Scheduler}.</dd>
655 * </dl>
656 * @param <T> the value type
657 * @param sources a sequence of {@code SingleSource}s that need to be eagerly concatenated
658 * @return the new {@link Flowable} instance with the specified concatenation behavior
659 * @throws NullPointerException if {@code sources} is {@code null}
660 */
661 @BackpressureSupport(BackpressureKind.FULL)
662 @CheckReturnValue
663 @NonNull
664 @SchedulerSupport(SchedulerSupport.NONE)
665 public static <@NonNull T> Flowable<T> concatEager(@NonNull Publisher<@NonNull ? extends SingleSource<? extends T>> sources) {
666 return Flowable.fromPublisher(sources).concatMapEager(SingleInternalHelper.toFlowable());
667 }
668
669 /**
670 * Concatenates a {@link Publisher} sequence of {@link SingleSource}s eagerly into a single stream of values and
671 * runs a limited number of those inner {@code SingleSource}s at once.
672 * <p>
673 * <img width="640" height="425" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.concatEager.pn.png" alt="">
674 * <p>
675 * Eager concatenation means that once a subscriber subscribes, this operator subscribes to all of the
676 * emitted source {@code SingleSource}s as they are observed. The operator buffers the values emitted by these
677 * {@code SingleSource}s and then drains them in order, each one after the previous one succeeds.
678 * <dl>
679 * <dt><b>Backpressure:</b></dt>
680 * <dd>Backpressure is honored towards the downstream and the outer {@code Publisher} is
681 * expected to support backpressure. Violating this assumption, the operator will
682 * signal {@link io.reactivex.rxjava3.exceptions.MissingBackpressureException}.</dd>
683 * <dt><b>Scheduler:</b></dt>
684 * <dd>This method does not operate by default on a particular {@link Scheduler}.</dd>
685 * </dl>
686 * @param <T> the value type
687 * @param sources a sequence of {@code SingleSource}s that need to be eagerly concatenated
688 * @param maxConcurrency the maximum number of concurrently running inner {@code SingleSource}s; {@link Integer#MAX_VALUE}
689 * is interpreted as all inner {@code SingleSource}s can be active at the same time
690 * @return the new {@link Flowable} instance with the specified concatenation behavior
691 * @throws NullPointerException if {@code sources} is {@code null}
692 * @throws IllegalArgumentException if {@code maxConcurrency} is non-positive
693 * @since 3.0.0
694 */
695 @BackpressureSupport(BackpressureKind.FULL)
696 @CheckReturnValue
697 @NonNull
698 @SchedulerSupport(SchedulerSupport.NONE)
699 public static <@NonNull T> Flowable<T> concatEager(@NonNull Publisher<@NonNull ? extends SingleSource<? extends T>> sources, int maxConcurrency) {
700 return Flowable.fromPublisher(sources).concatMapEager(SingleInternalHelper.toFlowable(), maxConcurrency, 1);
701 }
702
703 /**
704 * Concatenates an {@link Iterable} sequence of {@link SingleSource}s eagerly into a single stream of values,
705 * delaying errors until all the inner sources terminate.
706 * <p>
707 * <img width="640" height="431" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.concatEagerDelayError.i.png" alt="">
708 * <p>
709 * Eager concatenation means that once a subscriber subscribes, this operator subscribes to all of the
710 * source {@code SingleSource}s. The operator buffers the values emitted by these {@code SingleSource}s and then drains them
711 * in order, each one after the previous one succeeds.
712 * <dl>
713 * <dt><b>Backpressure:</b></dt>
714 * <dd>Backpressure is honored towards the downstream.</dd>
715 * <dt><b>Scheduler:</b></dt>
716 * <dd>This method does not operate by default on a particular {@link Scheduler}.</dd>
717 * </dl>
718 * @param <T> the value type
719 * @param sources an {@code Iterable} sequence of {@code SingleSource} that need to be eagerly concatenated
720 * @return the new {@link Flowable} instance with the specified concatenation behavior
721 * @throws NullPointerException if {@code sources} is {@code null}
722 * @since 3.0.0
723 */
724 @BackpressureSupport(BackpressureKind.FULL)
725 @CheckReturnValue
726 @NonNull
727 @SchedulerSupport(SchedulerSupport.NONE)
728 public static <@NonNull T> Flowable<T> concatEagerDelayError(@NonNull Iterable<@NonNull ? extends SingleSource<? extends T>> sources) {
729 return Flowable.fromIterable(sources).concatMapEagerDelayError(SingleInternalHelper.toFlowable(), true);
730 }
731
732 /**
733 * Concatenates an {@link Iterable} sequence of {@link SingleSource}s eagerly into a single stream of values,
734 * delaying errors until all the inner sources terminate.
735 * <p>
736 * <img width="640" height="378" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.concatEagerDelayError.in.png" alt="">
737 * <p>
738 * Eager concatenation means that once a subscriber subscribes, this operator subscribes to all of the
739 * source {@code SingleSource}s. The operator buffers the values emitted by these {@code SingleSource}s and then drains them
740 * in order, each one after the previous one succeeds.
741 * <dl>
742 * <dt><b>Backpressure:</b></dt>
743 * <dd>Backpressure is honored towards the downstream.</dd>
744 * <dt><b>Scheduler:</b></dt>
745 * <dd>This method does not operate by default on a particular {@link Scheduler}.</dd>
746 * </dl>
747 * @param <T> the value type
748 * @param sources an {@code Iterable} sequence of {@code SingleSource} that need to be eagerly concatenated
749 * @param maxConcurrency the maximum number of concurrently running inner {@code SingleSource}s; {@link Integer#MAX_VALUE}
750 * is interpreted as all inner {@code SingleSource}s can be active at the same time
751 * @return the new {@link Flowable} instance with the specified concatenation behavior
752 * @throws NullPointerException if {@code sources} is {@code null}
753 * @throws IllegalArgumentException if {@code maxConcurrency} is non-positive
754 * @since 3.0.0
755 */
756 @BackpressureSupport(BackpressureKind.FULL)
757 @CheckReturnValue
758 @NonNull
759 @SchedulerSupport(SchedulerSupport.NONE)
760 public static <@NonNull T> Flowable<T> concatEagerDelayError(@NonNull Iterable<@NonNull ? extends SingleSource<? extends T>> sources, int maxConcurrency) {
761 return Flowable.fromIterable(sources).concatMapEagerDelayError(SingleInternalHelper.toFlowable(), true, maxConcurrency, 1);
762 }
763
764 /**
765 * Concatenates a {@link Publisher} sequence of {@link SingleSource}s eagerly into a single stream of values,
766 * delaying errors until all the inner and the outer sequence terminate.
767 * <p>
768 * <img width="640" height="444" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.concatEagerDelayError.p.png" alt="">
769 * <p>
770 * Eager concatenation means that once a subscriber subscribes, this operator subscribes to all of the
771 * emitted source {@code SingleSource}s as they are observed. The operator buffers the values emitted by these
772 * {@code SingleSource}s and then drains them in order, each one after the previous one succeeds.
773 * <dl>
774 * <dt><b>Backpressure:</b></dt>
775 * <dd>Backpressure is honored towards the downstream and the outer {@code Publisher} is
776 * expected to support backpressure. Violating this assumption, the operator will
777 * signal {@link io.reactivex.rxjava3.exceptions.MissingBackpressureException}.</dd>
778 * <dt><b>Scheduler:</b></dt>
779 * <dd>This method does not operate by default on a particular {@link Scheduler}.</dd>
780 * </dl>
781 * @param <T> the value type
782 * @param sources a sequence of {@code SingleSource}s that need to be eagerly concatenated
783 * @return the new {@link Flowable} instance with the specified concatenation behavior
784 * @throws NullPointerException if {@code sources} is {@code null}
785 * @since 3.0.0
786 */
787 @BackpressureSupport(BackpressureKind.FULL)
788 @CheckReturnValue
789 @NonNull
790 @SchedulerSupport(SchedulerSupport.NONE)
791 public static <@NonNull T> Flowable<T> concatEagerDelayError(@NonNull Publisher<@NonNull ? extends SingleSource<? extends T>> sources) {
792 return Flowable.fromPublisher(sources).concatMapEagerDelayError(SingleInternalHelper.toFlowable(), true);
793 }
794
795 /**
796 * Concatenates a {@link Publisher} sequence of {@link SingleSource}s eagerly into a single stream of values,
797 * running at most the specified number of those inner {@code SingleSource}s at once and
798 * delaying errors until all the inner and the outer sequence terminate.
799 * <p>
800 * <img width="640" height="421" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.concatEagerDelayError.pn.png" alt="">
801 * <p>
802 * Eager concatenation means that once a subscriber subscribes, this operator subscribes to all of the
803 * emitted source {@code SingleSource}s as they are observed. The operator buffers the values emitted by these
804 * {@code SingleSource}s and then drains them in order, each one after the previous one succeeds.
805 * <dl>
806 * <dt><b>Backpressure:</b></dt>
807 * <dd>Backpressure is honored towards the downstream and the outer {@code Publisher} is
808 * expected to support backpressure. Violating this assumption, the operator will
809 * signal {@link io.reactivex.rxjava3.exceptions.MissingBackpressureException}.</dd>
810 * <dt><b>Scheduler:</b></dt>
811 * <dd>This method does not operate by default on a particular {@link Scheduler}.</dd>
812 * </dl>
813 * @param <T> the value type
814 * @param sources a sequence of {@code SingleSource}s that need to be eagerly concatenated
815 * @param maxConcurrency the number of inner {@code SingleSource}s to run at once
816 * @return the new {@link Flowable} instance with the specified concatenation behavior
817 * @throws NullPointerException if {@code sources} is {@code null}
818 * @throws IllegalArgumentException if {@code maxConcurrency} is non-positive
819 * @since 3.0.0
820 */
821 @BackpressureSupport(BackpressureKind.FULL)
822 @CheckReturnValue
823 @NonNull
824 @SchedulerSupport(SchedulerSupport.NONE)
825 public static <@NonNull T> Flowable<T> concatEagerDelayError(@NonNull Publisher<@NonNull ? extends SingleSource<? extends T>> sources, int maxConcurrency) {
826 return Flowable.fromPublisher(sources).concatMapEagerDelayError(SingleInternalHelper.toFlowable(), true, maxConcurrency, 1);
827 }
828
829 /**
830 * Provides an API (via a cold {@code Single}) that bridges the reactive world with the callback-style world.
831 * <p>
832 * <img width="640" height="454" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.create.v3.png" alt="">
833 * <p>
834 * Example:
835 * <pre><code>
836 * Single.&lt;Event&gt;create(emitter -&gt; {
837 * Callback listener = new Callback() {
838 * &#64;Override
839 * public void onEvent(Event e) {
840 * emitter.onSuccess(e);
841 * }
842 *
843 * &#64;Override
844 * public void onFailure(Exception e) {
845 * emitter.onError(e);
846 * }
847 * };
848 *
849 * AutoCloseable c = api.someMethod(listener);
850 *
851 * emitter.setCancellable(c::close);
852 *
853 * });
854 * </code></pre>
855 * <p>
856 * Whenever a {@link SingleObserver} subscribes to the returned {@code Single}, the provided
857 * {@link SingleOnSubscribe} callback is invoked with a fresh instance of a {@link SingleEmitter}
858 * that will interact only with that specific {@code SingleObserver}. If this {@code SingleObserver}
859 * disposes the flow (making {@link SingleEmitter#isDisposed} return {@code true}),
860 * other observers subscribed to the same returned {@code Single} are not affected.
861 * <dl>
862 * <dt><b>Scheduler:</b></dt>
863 * <dd>{@code create} does not operate by default on a particular {@link Scheduler}.</dd>
864 * </dl>
865 * @param <T> the value type
866 * @param source the emitter that is called when a {@code SingleObserver} subscribes to the returned {@code Single}
867 * @return the new {@code Single} instance
868 * @throws NullPointerException if {@code source} is {@code null}
869 * @see SingleOnSubscribe
870 * @see Cancellable
871 */
872 @CheckReturnValue
873 @NonNull
874 @SchedulerSupport(SchedulerSupport.NONE)
875 public static <@NonNull T> Single<T> create(@NonNull SingleOnSubscribe<T> source) {
876 Objects.requireNonNull(source, "source is null");
877 return RxJavaPlugins.onAssembly(new SingleCreate<>(source));
878 }
879
880 /**
881 * Calls a {@link Supplier} for each individual {@link SingleObserver} to return the actual {@link SingleSource} to
882 * be subscribed to.
883 * <p>
884 * <img width="640" height="515" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.defer.v3.png" alt="">
885 * <dl>
886 * <dt><b>Scheduler:</b></dt>
887 * <dd>{@code defer} does not operate by default on a particular {@link Scheduler}.</dd>
888 * </dl>
889 * @param <T> the value type
890 * @param supplier the {@code Supplier} that is called for each individual {@code SingleObserver} and
891 * returns a {@code SingleSource} instance to subscribe to
892 * @throws NullPointerException if {@code supplier} is {@code null}
893 * @return the new {@code Single} instance
894 */
895 @CheckReturnValue
896 @NonNull
897 @SchedulerSupport(SchedulerSupport.NONE)
898 public static <@NonNull T> Single<T> defer(@NonNull Supplier<? extends @NonNull SingleSource<? extends T>> supplier) {
899 Objects.requireNonNull(supplier, "supplier is null");
900 return RxJavaPlugins.onAssembly(new SingleDefer<>(supplier));
901 }
902
903 /**
904 * Signals a {@link Throwable} returned by the callback function for each individual {@link SingleObserver}.
905 * <p>
906 * <img width="640" height="283" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.error.c.v3.png" alt="">
907 * <dl>
908 * <dt><b>Scheduler:</b></dt>
909 * <dd>{@code error} does not operate by default on a particular {@link Scheduler}.</dd>
910 * </dl>
911 * @param <T> the value type
912 * @param supplier the {@link Supplier} that is called for each individual {@code SingleObserver} and
913 * returns a {@code Throwable} instance to be emitted.
914 * @throws NullPointerException if {@code supplier} is {@code null}
915 * @return the new {@code Single} instance
916 */
917 @CheckReturnValue
918 @NonNull
919 @SchedulerSupport(SchedulerSupport.NONE)
920 public static <@NonNull T> Single<T> error(@NonNull Supplier<? extends @NonNull Throwable> supplier) {
921 Objects.requireNonNull(supplier, "supplier is null");
922 return RxJavaPlugins.onAssembly(new SingleError<>(supplier));
923 }
924
925 /**
926 * Returns a {@code Single} that invokes a subscriber's {@link SingleObserver#onError onError} method when the
927 * subscriber subscribes to it.
928 * <p>
929 * <img width="640" height="283" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.error.v3.png" alt="">
930 * <dl>
931 * <dt><b>Scheduler:</b></dt>
932 * <dd>{@code error} does not operate by default on a particular {@link Scheduler}.</dd>
933 * </dl>
934 *
935 * @param throwable
936 * the particular {@link Throwable} to pass to {@link SingleObserver#onError onError}
937 * @param <T>
938 * the type of the item (ostensibly) emitted by the {@code Single}
939 * @return the new {@code Single} that invokes the subscriber's {@link SingleObserver#onError onError} method when
940 * the subscriber subscribes to it
941 * @throws NullPointerException if {@code throwable} is {@code null}
942 * @see <a href="http://reactivex.io/documentation/operators/empty-never-throw.html">ReactiveX operators documentation: Throw</a>
943 */
944 @CheckReturnValue
945 @NonNull
946 @SchedulerSupport(SchedulerSupport.NONE)
947 public static <@NonNull T> Single<T> error(@NonNull Throwable throwable) {
948 Objects.requireNonNull(throwable, "throwable is null");
949 return error(Functions.justSupplier(throwable));
950 }
951
952 /**
953 * Returns a {@code Single} that invokes the given {@link Callable} for each incoming {@link SingleObserver}
954 * and emits its value or exception to them.
955 * <p>
956 * Allows you to defer execution of passed function until {@code SingleObserver} subscribes to the {@code Single}.
957 * It makes passed function "lazy".
958 * Result of the function invocation will be emitted by the {@link Single}.
959 * <p>
960 * <img width="640" height="467" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.fromCallable.v3.png" alt="">
961 * <dl>
962 * <dt><b>Scheduler:</b></dt>
963 * <dd>{@code fromCallable} does not operate by default on a particular {@link Scheduler}.</dd>
964 * <dt><b>Error handling:</b></dt>
965 * <dd> If the {@code Callable} throws an exception, the respective {@link Throwable} is
966 * delivered to the downstream via {@link SingleObserver#onError(Throwable)},
967 * except when the downstream has disposed this {@code Single} source.
968 * In this latter case, the {@code Throwable} is delivered to the global error handler via
969 * {@link RxJavaPlugins#onError(Throwable)} as an {@link io.reactivex.rxjava3.exceptions.UndeliverableException UndeliverableException}.
970 * </dd>
971 * </dl>
972 *
973 * @param callable
974 * function which execution should be deferred, it will be invoked when {@code SingleObserver} will subscribe to the {@link Single}.
975 * @param <T>
976 * the type of the item emitted by the {@code Single}.
977 * @return the new {@code Single} whose {@code SingleObserver}s' subscriptions trigger an invocation of the given function.
978 * @throws NullPointerException if {@code callable} is {@code null}
979 * @see #defer(Supplier)
980 * @see #fromSupplier(Supplier)
981 */
982 @CheckReturnValue
983 @NonNull
984 @SchedulerSupport(SchedulerSupport.NONE)
985 public static <@NonNull T> Single<T> fromCallable(@NonNull Callable<? extends T> callable) {
986 Objects.requireNonNull(callable, "callable is null");
987 return RxJavaPlugins.onAssembly(new SingleFromCallable<>(callable));
988 }
989
990 /**
991 * Converts a {@link Future} into a {@code Single} and awaits its outcome in a blocking fashion.
992 * <p>
993 * <img width="640" height="315" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.from.Future.v3.png" alt="">
994 * <p>
995 * The operator calls {@link Future#get()}, which is a blocking method, on the subscription thread.
996 * It is recommended applying {@link #subscribeOn(Scheduler)} to move this blocking wait to a
997 * background thread, and if the {@link Scheduler} supports it, interrupt the wait when the flow
998 * is disposed.
999 * <p>
1000 * A non-{@code null} value is then emitted via {@code onSuccess} or any exception is emitted via
1001 * {@code onError}. If the {@code Future} completes with {@code null}, a {@link NullPointerException}
1002 * is signaled.
1003 * <dl>
1004 * <dt><b>Scheduler:</b></dt>
1005 * <dd>{@code fromFuture} does not operate by default on a particular {@code Scheduler}.</dd>
1006 * </dl>
1007 *
1008 * @param future
1009 * the source {@code Future}
1010 * @param <T>
1011 * the type of object that the {@code Future} returns, and also the type of item to be emitted by
1012 * the resulting {@code Single}
1013 * @return the new {@code Single} that emits the item from the source {@code Future}
1014 * @throws NullPointerException if {@code future} is {@code null}
1015 * @see <a href="http://reactivex.io/documentation/operators/from.html">ReactiveX operators documentation: From</a>
1016 * @see #fromFuture(Future, long, TimeUnit)
1017 * @see #fromCompletionStage(CompletionStage)
1018 */
1019 @CheckReturnValue
1020 @SchedulerSupport(SchedulerSupport.NONE)
1021 @NonNull
1022 public static <@NonNull T> Single<T> fromFuture(@NonNull Future<? extends T> future) {
1023 return toSingle(Flowable.fromFuture(future));
1024 }
1025
1026 /**
1027 * Converts a {@link Future} into a {@code Single} and awaits its outcome, or timeout, in a blocking fashion.
1028 * <p>
1029 * <img width="640" height="315" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.from.Future.v3.png" alt="">
1030 * <p>
1031 * The operator calls {@link Future#get(long, TimeUnit)}, which is a blocking method, on the subscription thread.
1032 * It is recommended applying {@link #subscribeOn(Scheduler)} to move this blocking wait to a
1033 * background thread, and if the {@link Scheduler} supports it, interrupt the wait when the flow
1034 * is disposed.
1035 * <p>
1036 * A non-{@code null} value is then emitted via {@code onSuccess} or any exception is emitted via
1037 * {@code onError}. If the {@code Future} completes with {@code null}, a {@link NullPointerException}
1038 * is signaled.
1039 * <dl>
1040 * <dt><b>Scheduler:</b></dt>
1041 * <dd>{@code fromFuture} does not operate by default on a particular {@code Scheduler}.</dd>
1042 * </dl>
1043 *
1044 * @param future
1045 * the source {@code Future}
1046 * @param timeout
1047 * the maximum time to wait before calling {@code get}
1048 * @param unit
1049 * the {@link TimeUnit} of the {@code timeout} argument
1050 * @param <T>
1051 * the type of object that the {@code Future} returns, and also the type of item to be emitted by
1052 * the resulting {@code Single}
1053 * @return the new {@code Single} that emits the item from the source {@code Future}
1054 * @throws NullPointerException if {@code future} or {@code unit} is {@code null}
1055 * @see <a href="http://reactivex.io/documentation/operators/from.html">ReactiveX operators documentation: From</a>
1056 */
1057 @CheckReturnValue
1058 @SchedulerSupport(SchedulerSupport.NONE)
1059 @NonNull
1060 public static <@NonNull T> Single<T> fromFuture(@NonNull Future<? extends T> future, long timeout, @NonNull TimeUnit unit) {
1061 return toSingle(Flowable.fromFuture(future, timeout, unit));
1062 }
1063
1064 /**
1065 * Returns a {@code Single} instance that when subscribed to, subscribes to the {@link MaybeSource} instance and
1066 * emits {@code onSuccess} as a single item, turns an {@code onComplete} into {@link NoSuchElementException} error signal or
1067 * forwards the {@code onError} signal.
1068 * <p>
1069 * <img width="640" height="241" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.fromMaybe.png" alt="">
1070 * <dl>
1071 * <dt><b>Scheduler:</b></dt>
1072 * <dd>{@code fromMaybe} does not operate by default on a particular {@link Scheduler}.</dd>
1073 * </dl>
1074 * @param <T> the value type of the {@code MaybeSource} element
1075 * @param maybe the {@code MaybeSource} instance to subscribe to, not {@code null}
1076 * @return the new {@code Single} instance
1077 * @throws NullPointerException if {@code maybe} is {@code null}
1078 * @since 3.0.0
1079 */
1080 @CheckReturnValue
1081 @NonNull
1082 @SchedulerSupport(SchedulerSupport.NONE)
1083 public static <@NonNull T> Single<T> fromMaybe(@NonNull MaybeSource<T> maybe) {
1084 Objects.requireNonNull(maybe, "maybe is null");
1085 return RxJavaPlugins.onAssembly(new MaybeToSingle<>(maybe, null));
1086 }
1087
1088 /**
1089 * Returns a {@code Single} instance that when subscribed to, subscribes to the {@link MaybeSource} instance and
1090 * emits {@code onSuccess} as a single item, emits the {@code defaultItem} for an {@code onComplete} signal or
1091 * forwards the {@code onError} signal.
1092 * <p>
1093 * <img width="640" height="353" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.fromMaybe.v.png" alt="">
1094 * <dl>
1095 * <dt><b>Scheduler:</b></dt>
1096 * <dd>{@code fromMaybe} does not operate by default on a particular {@link Scheduler}.</dd>
1097 * </dl>
1098 * @param <T> the value type of the {@code MaybeSource} element
1099 * @param maybe the {@code MaybeSource} instance to subscribe to, not {@code null}
1100 * @param defaultItem the item to signal if the current {@code MaybeSource} is empty
1101 * @return the new {@code Single} instance
1102 * @throws NullPointerException if {@code maybe} or {@code defaultItem} is {@code null}
1103 * @since 3.0.0
1104 */
1105 @CheckReturnValue
1106 @NonNull
1107 @SchedulerSupport(SchedulerSupport.NONE)
1108 public static <@NonNull T> Single<T> fromMaybe(@NonNull MaybeSource<T> maybe, @NonNull T defaultItem) {
1109 Objects.requireNonNull(maybe, "maybe is null");
1110 Objects.requireNonNull(defaultItem, "defaultItem is null");
1111 return RxJavaPlugins.onAssembly(new MaybeToSingle<>(maybe, defaultItem));
1112 }
1113
1114 /**
1115 * Wraps a specific {@link Publisher} into a {@code Single} and signals its single element or error.
1116 * <p>
1117 * <img width="640" height="322" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.fromPublisher.v3.png" alt="">
1118 * <p>
1119 * If the source {@code Publisher} is empty, a {@link NoSuchElementException} is signaled. If
1120 * the source has more than one element, an {@link IndexOutOfBoundsException} is signaled.
1121 * <p>
1122 * The {@code Publisher} must follow the
1123 * <a href="https://github.com/reactive-streams/reactive-streams-jvm#reactive-streams">Reactive Streams specification</a>.
1124 * Violating the specification may result in undefined behavior.
1125 * <p>
1126 * If possible, use {@link #create(SingleOnSubscribe)} to create a
1127 * source-like {@code Single} instead.
1128 * <p>
1129 * Note that even though {@code Publisher} appears to be a functional interface, it
1130 * is not recommended to implement it through a lambda as the specification requires
1131 * state management that is not achievable with a stateless lambda.
1132 * <dl>
1133 * <dt><b>Backpressure:</b></dt>
1134 * <dd>The {@code publisher} is consumed in an unbounded fashion but will be cancelled
1135 * if it produced more than one item.</dd>
1136 * <dt><b>Scheduler:</b></dt>
1137 * <dd>{@code fromPublisher} does not operate by default on a particular {@link Scheduler}.</dd>
1138 * </dl>
1139 * @param <T> the value type
1140 * @param publisher the source {@code Publisher} instance, not {@code null}
1141 * @return the new {@code Single} instance
1142 * @throws NullPointerException if {@code publisher} is {@code null}
1143 * @see #create(SingleOnSubscribe)
1144 */
1145 @BackpressureSupport(BackpressureKind.UNBOUNDED_IN)
1146 @CheckReturnValue
1147 @NonNull
1148 @SchedulerSupport(SchedulerSupport.NONE)
1149 public static <@NonNull T> Single<T> fromPublisher(@NonNull Publisher<? extends T> publisher) {
1150 Objects.requireNonNull(publisher, "publisher is null");
1151 return RxJavaPlugins.onAssembly(new SingleFromPublisher<>(publisher));
1152 }
1153
1154 /**
1155 * Wraps a specific {@link ObservableSource} into a {@code Single} and signals its single element or error.
1156 * <p>
1157 * <img width="640" height="343" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.fromObservable.v3.png" alt="">
1158 * <p>
1159 * If the {@code ObservableSource} is empty, a {@link NoSuchElementException} is signaled.
1160 * If the source has more than one element, an {@link IndexOutOfBoundsException} is signaled.
1161 * <dl>
1162 * <dt><b>Scheduler:</b></dt>
1163 * <dd>{@code fromObservable} does not operate by default on a particular {@link Scheduler}.</dd>
1164 * </dl>
1165 *
1166 * @param observable the source sequence to wrap, not {@code null}
1167 * @param <T>
1168 * the type of the item emitted by the {@code Single}.
1169 * @return the new {@code Single} instance
1170 * @throws NullPointerException if {@code observable} is {@code null}
1171 */
1172 @CheckReturnValue
1173 @NonNull
1174 @SchedulerSupport(SchedulerSupport.NONE)
1175 public static <@NonNull T> Single<T> fromObservable(@NonNull ObservableSource<? extends T> observable) {
1176 Objects.requireNonNull(observable, "observable is null");
1177 return RxJavaPlugins.onAssembly(new ObservableSingleSingle<>(observable, null));
1178 }
1179
1180 /**
1181 * Returns a {@code Single} that invokes passed supplier and emits its result
1182 * for each individual {@link SingleObserver} that subscribes.
1183 * <p>
1184 * Allows you to defer execution of passed function until a {@code SingleObserver} subscribes to the {@link Single}.
1185 * It makes passed function "lazy".
1186 * Result of the function invocation will be emitted by the {@link Single}.
1187 * <p>
1188 * <img width="640" height="467" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.fromSupplier.v3.png" alt="">
1189 * <dl>
1190 * <dt><b>Scheduler:</b></dt>
1191 * <dd>{@code fromSupplier} does not operate by default on a particular {@link Scheduler}.</dd>
1192 * <dt><b>Error handling:</b></dt>
1193 * <dd> If the {@link Supplier} throws an exception, the respective {@link Throwable} is
1194 * delivered to the downstream via {@link SingleObserver#onError(Throwable)},
1195 * except when the downstream has disposed this {@code Single} source.
1196 * In this latter case, the {@code Throwable} is delivered to the global error handler via
1197 * {@link RxJavaPlugins#onError(Throwable)} as an {@link io.reactivex.rxjava3.exceptions.UndeliverableException UndeliverableException}.
1198 * </dd>
1199 * </dl>
1200 *
1201 * @param supplier
1202 * function which execution should be deferred, it will be invoked when {@code SingleObserver} subscribes to the {@code Single}.
1203 * @param <T>
1204 * the type of the item emitted by the {@code Single}.
1205 * @return the new {@code Single} whose {@code SingleObserver}s' subscriptions trigger an invocation of the given function.
1206 * @throws NullPointerException if {@code supplier} is {@code null}
1207 * @see #defer(Supplier)
1208 * @see #fromCallable(Callable)
1209 * @since 3.0.0
1210 */
1211 @CheckReturnValue
1212 @NonNull
1213 @SchedulerSupport(SchedulerSupport.NONE)
1214 public static <@NonNull T> Single<T> fromSupplier(@NonNull Supplier<? extends T> supplier) {
1215 Objects.requireNonNull(supplier, "supplier is null");
1216 return RxJavaPlugins.onAssembly(new SingleFromSupplier<>(supplier));
1217 }
1218
1219 /**
1220 * Returns a {@code Single} that emits a specified item.
1221 * <p>
1222 * <img width="640" height="310" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.just.v3.png" alt="">
1223 * <p>
1224 * To convert any object into a {@code Single} that emits that object, pass that object into the
1225 * {@code just} method.
1226 * <dl>
1227 * <dt><b>Scheduler:</b></dt>
1228 * <dd>{@code just} does not operate by default on a particular {@link Scheduler}.</dd>
1229 * </dl>
1230 *
1231 * @param item
1232 * the item to emit
1233 * @param <T>
1234 * the type of that item
1235 * @return the new {@code Single} that emits {@code item}
1236 * @throws NullPointerException if {@code item} is {@code null}
1237 * @see <a href="http://reactivex.io/documentation/operators/just.html">ReactiveX operators documentation: Just</a>
1238 */
1239 @CheckReturnValue
1240 @SchedulerSupport(SchedulerSupport.NONE)
1241 @NonNull
1242 public static <@NonNull T> Single<T> just(T item) {
1243 Objects.requireNonNull(item, "item is null");
1244 return RxJavaPlugins.onAssembly(new SingleJust<>(item));
1245 }
1246
1247 /**
1248 * Merges an {@link Iterable} sequence of {@link SingleSource} instances into a single {@link Flowable} sequence,
1249 * running all {@code SingleSource}s at once.
1250 * <p>
1251 * <img width="640" height="319" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.merge.i.v3.png" alt="">
1252 * <dl>
1253 * <dt><b>Backpressure:</b></dt>
1254 * <dd>The returned {@code Flowable} honors the backpressure of the downstream consumer.</dd>
1255 * <dt><b>Scheduler:</b></dt>
1256 * <dd>{@code merge} does not operate by default on a particular {@link Scheduler}.</dd>
1257 * <dt><b>Error handling:</b></dt>
1258 * <dd>If any of the source {@code SingleSource}s signal a {@link Throwable} via {@code onError}, the resulting
1259 * {@code Flowable} terminates with that {@code Throwable} and all other source {@code SingleSource}s are disposed.
1260 * If more than one {@code SingleSource} signals an error, the resulting {@code Flowable} may terminate with the
1261 * first one's error or, depending on the concurrency of the sources, may terminate with a
1262 * {@link CompositeException} containing two or more of the various error signals.
1263 * {@code Throwable}s that didn't make into the composite will be sent (individually) to the global error handler via
1264 * {@link RxJavaPlugins#onError(Throwable)} method as {@link UndeliverableException} errors. Similarly, {@code Throwable}s
1265 * signaled by source(s) after the returned {@code Flowable} has been cancelled or terminated with a
1266 * (composite) error will be sent to the same global error handler.
1267 * Use {@link #mergeDelayError(Iterable)} to merge sources and terminate only when all source {@code SingleSource}s
1268 * have completed or failed with an error.
1269 * </dd>
1270 * </dl>
1271 * @param <T> the common and resulting value type
1272 * @param sources the {@code Iterable} sequence of {@code SingleSource} sources
1273 * @return the new {@code Flowable} instance
1274 * @throws NullPointerException if {@code sources} is {@code null}
1275 * @since 2.0
1276 * @see #mergeDelayError(Iterable)
1277 */
1278 @CheckReturnValue
1279 @NonNull
1280 @BackpressureSupport(BackpressureKind.FULL)
1281 @SchedulerSupport(SchedulerSupport.NONE)
1282 public static <@NonNull T> Flowable<T> merge(@NonNull Iterable<@NonNull ? extends SingleSource<? extends T>> sources) {
1283 return Flowable.fromIterable(sources).flatMapSingle(Functions.identity());
1284 }
1285
1286 /**
1287 * Merges a sequence of {@link SingleSource} instances emitted by a {@link Publisher} into a single {@link Flowable} sequence,
1288 * running all {@code SingleSource}s at once.
1289 * <p>
1290 * <img width="640" height="307" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.merge.p.v3.png" alt="">
1291 * <dl>
1292 * <dt><b>Backpressure:</b></dt>
1293 * <dd>The returned {@code Flowable} honors the backpressure of the downstream consumer.</dd>
1294 * <dt><b>Scheduler:</b></dt>
1295 * <dd>{@code merge} does not operate by default on a particular {@link Scheduler}.</dd>
1296 * <dt><b>Error handling:</b></dt>
1297 * <dd>If any of the source {@code SingleSource}s signal a {@link Throwable} via {@code onError}, the resulting
1298 * {@code Flowable} terminates with that {@code Throwable} and all other source {@code SingleSource}s are disposed.
1299 * If more than one {@code SingleSource} signals an error, the resulting {@code Flowable} may terminate with the
1300 * first one's error or, depending on the concurrency of the sources, may terminate with a
1301 * {@link CompositeException} containing two or more of the various error signals.
1302 * {@code Throwable}s that didn't make into the composite will be sent (individually) to the global error handler via
1303 * {@link RxJavaPlugins#onError(Throwable)} method as {@link UndeliverableException} errors. Similarly, {@code Throwable}s
1304 * signaled by source(s) after the returned {@code Flowable} has been cancelled or terminated with a
1305 * (composite) error will be sent to the same global error handler.
1306 * Use {@link #mergeDelayError(Publisher)} to merge sources and terminate only when all source {@code SingleSource}s
1307 * have completed or failed with an error.
1308 * </dd>
1309 * </dl>
1310 * @param <T> the common and resulting value type
1311 * @param sources the {@code Publisher} emitting a sequence of {@code SingleSource}s
1312 * @return the new {@code Flowable} instance
1313 * @throws NullPointerException if {@code sources} is {@code null}
1314 * @see #mergeDelayError(Publisher)
1315 * @since 2.0
1316 */
1317 @CheckReturnValue
1318 @NonNull
1319 @BackpressureSupport(BackpressureKind.FULL)
1320 @SchedulerSupport(SchedulerSupport.NONE)
1321 public static <@NonNull T> Flowable<T> merge(@NonNull Publisher<@NonNull ? extends SingleSource<? extends T>> sources) {
1322 Objects.requireNonNull(sources, "sources is null");
1323 return RxJavaPlugins.onAssembly(new FlowableFlatMapSinglePublisher<>(sources, Functions.identity(), false, Integer.MAX_VALUE));
1324 }
1325
1326 /**
1327 * Flattens a {@link SingleSource} that emits a {@code SingleSingle} into a single {@code Single} that emits the item
1328 * emitted by the nested {@code SingleSource}, without any transformation.
1329 * <p>
1330 * <img width="640" height="412" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.merge.oo.v3.png" alt="">
1331 * <dl>
1332 * <dt><b>Scheduler:</b></dt>
1333 * <dd>{@code merge} does not operate by default on a particular {@link Scheduler}.</dd>
1334 * <dd>The resulting {@code Single} emits the outer source's or the inner {@code SingleSource}'s {@link Throwable} as is.
1335 * Unlike the other {@code merge()} operators, this operator won't and can't produce a {@link CompositeException} because there is
1336 * only one possibility for the outer or the inner {@code SingleSource} to emit an {@code onError} signal.
1337 * Therefore, there is no need for a {@code mergeDelayError(SingleSource<SingleSource<T>>)} operator.
1338 * </dd>
1339 * </dl>
1340 *
1341 * @param <T> the value type of the sources and the output
1342 * @param source
1343 * a {@code Single} that emits a {@code Single}
1344 * @return the new {@code Single} that emits the item that is the result of flattening the {@code Single} emitted
1345 * by {@code source}
1346 * @throws NullPointerException if {@code source} is {@code null}
1347 * @see <a href="http://reactivex.io/documentation/operators/merge.html">ReactiveX operators documentation: Merge</a>
1348 */
1349 @CheckReturnValue
1350 @NonNull
1351 @SchedulerSupport(SchedulerSupport.NONE)
1352 public static <@NonNull T> Single<T> merge(@NonNull SingleSource<? extends SingleSource<? extends T>> source) {
1353 Objects.requireNonNull(source, "source is null");
1354 return RxJavaPlugins.onAssembly(new SingleFlatMap<SingleSource<? extends T>, T>(source, Functions.identity()));
1355 }
1356
1357 /**
1358 * Flattens two {@link SingleSource}s into one {@link Flowable} sequence, without any transformation.
1359 * <p>
1360 * <img width="640" height="414" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.merge.v3.png" alt="">
1361 * <p>
1362 * You can combine items emitted by multiple {@code SingleSource}s so that they appear as a single {@code Flowable}, by
1363 * using the {@code merge} method.
1364 * <dl>
1365 * <dt><b>Backpressure:</b></dt>
1366 * <dd>The returned {@code Flowable} honors the backpressure of the downstream consumer.</dd>
1367 * <dt><b>Scheduler:</b></dt>
1368 * <dd>{@code merge} does not operate by default on a particular {@link Scheduler}.</dd>
1369 * <dt><b>Error handling:</b></dt>
1370 * <dd>If any of the source {@code SingleSource}s signal a {@link Throwable} via {@code onError}, the resulting
1371 * {@code Flowable} terminates with that {@code Throwable} and all other source {@code SingleSource}s are disposed.
1372 * If more than one {@code SingleSource} signals an error, the resulting {@code Flowable} may terminate with the
1373 * first one's error or, depending on the concurrency of the sources, may terminate with a
1374 * {@link CompositeException} containing two or more of the various error signals.
1375 * {@code Throwable}s that didn't make into the composite will be sent (individually) to the global error handler via
1376 * {@link RxJavaPlugins#onError(Throwable)} method as {@link UndeliverableException} errors. Similarly, {@code Throwable}s
1377 * signaled by source(s) after the returned {@code Flowable} has been cancelled or terminated with a
1378 * (composite) error will be sent to the same global error handler.
1379 * Use {@link #mergeDelayError(SingleSource, SingleSource)} to merge sources and terminate only when all source {@code SingleSource}s
1380 * have completed or failed with an error.
1381 * </dd>
1382 * </dl>
1383 *
1384 * @param <T> the common value type
1385 * @param source1
1386 * a {@code SingleSource} to be merged
1387 * @param source2
1388 * a {@code SingleSource} to be merged
1389 * @return the new {@code Flowable} that emits all of the items emitted by the source {@code SingleSource}s
1390 * @throws NullPointerException if {@code source1} or {@code source2} is {@code null}
1391 * @see <a href="http://reactivex.io/documentation/operators/merge.html">ReactiveX operators documentation: Merge</a>
1392 * @see #mergeDelayError(SingleSource, SingleSource)
1393 */
1394 @CheckReturnValue
1395 @NonNull
1396 @BackpressureSupport(BackpressureKind.FULL)
1397 @SchedulerSupport(SchedulerSupport.NONE)
1398 public static <@NonNull T> Flowable<T> merge(
1399 @NonNull SingleSource<? extends T> source1, @NonNull SingleSource<? extends T> source2
1400 ) {
1401 Objects.requireNonNull(source1, "source1 is null");
1402 Objects.requireNonNull(source2, "source2 is null");
1403 return Flowable.fromArray(source1, source2).flatMapSingle(Functions.identity(), false, Integer.MAX_VALUE);
1404 }
1405
1406 /**
1407 * Flattens three {@link SingleSource}s into one {@link Flowable} sequence, without any transformation.
1408 * <p>
1409 * <img width="640" height="366" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.merge.o3.v3.png" alt="">
1410 * <p>
1411 * You can combine items emitted by multiple {@code SingleSource}s so that they appear as a single {@code Flowable}, by
1412 * the {@code merge} method.
1413 * <dl>
1414 * <dt><b>Backpressure:</b></dt>
1415 * <dd>The returned {@code Flowable} honors the backpressure of the downstream consumer.</dd>
1416 * <dt><b>Scheduler:</b></dt>
1417 * <dd>{@code merge} does not operate by default on a particular {@link Scheduler}.</dd>
1418 * <dt><b>Error handling:</b></dt>
1419 * <dd>If any of the source {@code SingleSource}s signal a {@link Throwable} via {@code onError}, the resulting
1420 * {@code Flowable} terminates with that {@code Throwable} and all other source {@code SingleSource}s are disposed.
1421 * If more than one {@code SingleSource} signals an error, the resulting {@code Flowable} may terminate with the
1422 * first one's error or, depending on the concurrency of the sources, may terminate with a
1423 * {@link CompositeException} containing two or more of the various error signals.
1424 * {@code Throwable}s that didn't make into the composite will be sent (individually) to the global error handler via
1425 * {@link RxJavaPlugins#onError(Throwable)} method as {@link UndeliverableException} errors. Similarly, {@code Throwable}s
1426 * signaled by source(s) after the returned {@code Flowable} has been cancelled or terminated with a
1427 * (composite) error will be sent to the same global error handler.
1428 * Use {@link #mergeDelayError(SingleSource, SingleSource, SingleSource)} to merge sources and terminate only when all source {@code SingleSource}s
1429 * have completed or failed with an error.
1430 * </dd>
1431 * </dl>
1432 *
1433 * @param <T> the common value type
1434 * @param source1
1435 * a {@code SingleSource} to be merged
1436 * @param source2
1437 * a {@code SingleSource} to be merged
1438 * @param source3
1439 * a {@code SingleSource} to be merged
1440 * @return the new {@code Flowable} that emits all of the items emitted by the source {@code SingleSource}s
1441 * @throws NullPointerException if {@code source1}, {@code source2} or {@code source3} is {@code null}
1442 * @see <a href="http://reactivex.io/documentation/operators/merge.html">ReactiveX operators documentation: Merge</a>
1443 * @see #mergeDelayError(SingleSource, SingleSource, SingleSource)
1444 */
1445 @CheckReturnValue
1446 @NonNull
1447 @BackpressureSupport(BackpressureKind.FULL)
1448 @SchedulerSupport(SchedulerSupport.NONE)
1449 public static <@NonNull T> Flowable<T> merge(
1450 @NonNull SingleSource<? extends T> source1, @NonNull SingleSource<? extends T> source2,
1451 @NonNull SingleSource<? extends T> source3
1452 ) {
1453 Objects.requireNonNull(source1, "source1 is null");
1454 Objects.requireNonNull(source2, "source2 is null");
1455 Objects.requireNonNull(source3, "source3 is null");
1456 return Flowable.fromArray(source1, source2, source3).flatMapSingle(Functions.identity(), false, Integer.MAX_VALUE);
1457 }
1458
1459 /**
1460 * Flattens four {@link SingleSource}s into one {@link Flowable} sequence, without any transformation.
1461 * <p>
1462 * <img width="640" height="362" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.merge.o4.v3.png" alt="">
1463 * <p>
1464 * You can combine items emitted by multiple {@code SingleSource}s so that they appear as a single {@code Flowable}, by
1465 * the {@code merge} method.
1466 * <dl>
1467 * <dt><b>Backpressure:</b></dt>
1468 * <dd>The returned {@code Flowable} honors the backpressure of the downstream consumer.</dd>
1469 * <dt><b>Scheduler:</b></dt>
1470 * <dd>{@code merge} does not operate by default on a particular {@link Scheduler}.</dd>
1471 * <dt><b>Error handling:</b></dt>
1472 * <dd>If any of the source {@code SingleSource}s signal a {@link Throwable} via {@code onError}, the resulting
1473 * {@code Flowable} terminates with that {@code Throwable} and all other source {@code SingleSource}s are disposed.
1474 * If more than one {@code SingleSource} signals an error, the resulting {@code Flowable} may terminate with the
1475 * first one's error or, depending on the concurrency of the sources, may terminate with a
1476 * {@link CompositeException} containing two or more of the various error signals.
1477 * {@code Throwable}s that didn't make into the composite will be sent (individually) to the global error handler via
1478 * {@link RxJavaPlugins#onError(Throwable)} method as {@link UndeliverableException} errors. Similarly, {@code Throwable}s
1479 * signaled by source(s) after the returned {@code Flowable} has been cancelled or terminated with a
1480 * (composite) error will be sent to the same global error handler.
1481 * Use {@link #mergeDelayError(SingleSource, SingleSource, SingleSource, SingleSource)} to merge sources and terminate only when all source {@code SingleSource}s
1482 * have completed or failed with an error.
1483 * </dd>
1484 * </dl>
1485 *
1486 * @param <T> the common value type
1487 * @param source1
1488 * a {@code SingleSource} to be merged
1489 * @param source2
1490 * a {@code SingleSource} to be merged
1491 * @param source3
1492 * a {@code SingleSource} to be merged
1493 * @param source4
1494 * a {@code SingleSource} to be merged
1495 * @return the new {@code Flowable} that emits all of the items emitted by the source {@code SingleSource}s
1496 * @throws NullPointerException if {@code source1}, {@code source2}, {@code source3} or {@code source4} is {@code null}
1497 * @see <a href="http://reactivex.io/documentation/operators/merge.html">ReactiveX operators documentation: Merge</a>
1498 * @see #mergeDelayError(SingleSource, SingleSource, SingleSource, SingleSource)
1499 */
1500 @CheckReturnValue
1501 @NonNull
1502 @BackpressureSupport(BackpressureKind.FULL)
1503 @SchedulerSupport(SchedulerSupport.NONE)
1504 public static <@NonNull T> Flowable<T> merge(
1505 @NonNull SingleSource<? extends T> source1, @NonNull SingleSource<? extends T> source2,
1506 @NonNull SingleSource<? extends T> source3, @NonNull SingleSource<? extends T> source4
1507 ) {
1508 Objects.requireNonNull(source1, "source1 is null");
1509 Objects.requireNonNull(source2, "source2 is null");
1510 Objects.requireNonNull(source3, "source3 is null");
1511 Objects.requireNonNull(source4, "source4 is null");
1512 return Flowable.fromArray(source1, source2, source3, source4).flatMapSingle(Functions.identity(), false, Integer.MAX_VALUE);
1513 }
1514
1515 /**
1516 * Merges an array of {@link SingleSource} instances into a single {@link Flowable} sequence,
1517 * running all {@code SingleSource}s at once.
1518 * <p>
1519 * <img width="640" height="272" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.mergeArray.png" alt="">
1520 * <dl>
1521 * <dt><b>Backpressure:</b></dt>
1522 * <dd>The operator honors backpressure from downstream.</dd>
1523 * <dt><b>Scheduler:</b></dt>
1524 * <dd>{@code mergeArray} does not operate by default on a particular {@link Scheduler}.</dd>
1525 * <dt><b>Error handling:</b></dt>
1526 * <dd>If any of the source {@code SingleSource}s signal a {@link Throwable} via {@code onError}, the resulting
1527 * {@code Flowable} terminates with that {@code Throwable} and all other source {@code SingleSource}s are disposed.
1528 * If more than one {@code SingleSource} signals an error, the resulting {@code Flowable} may terminate with the
1529 * first one's error or, depending on the concurrency of the sources, may terminate with a
1530 * {@link CompositeException} containing two or more of the various error signals.
1531 * {@code Throwable}s that didn't make into the composite will be sent (individually) to the global error handler via
1532 * {@link RxJavaPlugins#onError(Throwable)} method as {@link UndeliverableException} errors. Similarly, {@code Throwable}s
1533 * signaled by source(s) after the returned {@code Flowable} has been cancelled or terminated with a
1534 * (composite) error will be sent to the same global error handler.
1535 * Use {@link #mergeArrayDelayError(SingleSource...)} to merge sources and terminate only when all source {@code SingleSource}s
1536 * have completed or failed with an error.
1537 * </dd>
1538 * </dl>
1539 * @param <T> the common and resulting value type
1540 * @param sources the array sequence of {@code SingleSource} sources
1541 * @return the new {@code Flowable} instance
1542 * @throws NullPointerException if {@code sources} is {@code null}
1543 * @see #mergeArrayDelayError(SingleSource...)
1544 */
1545 @BackpressureSupport(BackpressureKind.FULL)
1546 @CheckReturnValue
1547 @NonNull
1548 @SchedulerSupport(SchedulerSupport.NONE)
1549 @SafeVarargs
1550 public static <@NonNull T> Flowable<T> mergeArray(SingleSource<? extends T>... sources) {
1551 return Flowable.fromArray(sources).flatMapSingle(Functions.identity(), false, Math.max(1, sources.length));
1552 }
1553
1554 /**
1555 * Flattens an array of {@link SingleSource}s into one {@link Flowable}, in a way that allows a subscriber to receive all
1556 * successfully emitted items from each of the source {@code SingleSource}s without being interrupted by an error
1557 * notification from one of them.
1558 * <p>
1559 * <img width="640" height="422" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.mergeArrayDelayError.png" alt="">
1560 * <p>
1561 * This behaves like {@link #merge(Publisher)} except that if any of the merged {@code SingleSource}s notify of an
1562 * error via {@link Subscriber#onError onError}, {@code mergeArrayDelayError} will refrain from propagating that
1563 * error notification until all of the merged {@code SingleSource}s have finished emitting items.
1564 * <p>
1565 * Even if multiple merged {@code SingleSource}s send {@code onError} notifications, {@code mergeArrayDelayError} will only
1566 * invoke the {@code onError} method of its subscribers once.
1567 * <dl>
1568 * <dt><b>Backpressure:</b></dt>
1569 * <dd>The operator honors backpressure from downstream.</dd>
1570 * <dt><b>Scheduler:</b></dt>
1571 * <dd>{@code mergeArrayDelayError} does not operate by default on a particular {@link Scheduler}.</dd>
1572 * </dl>
1573 *
1574 * @param <T> the common element base type
1575 * @param sources
1576 * the array of {@code SingleSource}s
1577 * @return the new {@code Flowable} instance
1578 * @throws NullPointerException if {@code sources} is {@code null}
1579 * @see <a href="http://reactivex.io/documentation/operators/merge.html">ReactiveX operators documentation: Merge</a>
1580 */
1581 @BackpressureSupport(BackpressureKind.FULL)
1582 @CheckReturnValue
1583 @SchedulerSupport(SchedulerSupport.NONE)
1584 @SafeVarargs
1585 @NonNull
1586 public static <@NonNull T> Flowable<T> mergeArrayDelayError(@NonNull SingleSource<? extends T>... sources) {
1587 return Flowable.fromArray(sources).flatMapSingle(Functions.identity(), true, Math.max(1, sources.length));
1588 }
1589
1590 /**
1591 * Merges an {@link Iterable} sequence of {@link SingleSource} instances into one {@link Flowable} sequence,
1592 * running all {@code SingleSource}s at once and delaying any error(s) until all sources succeed or fail.
1593 * <p>
1594 * <img width="640" height="469" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.mergeDelayError.i.png" alt="">
1595 * <dl>
1596 * <dt><b>Backpressure:</b></dt>
1597 * <dd>The returned {@code Flowable} honors the backpressure of the downstream consumer.</dd>
1598 * <dt><b>Scheduler:</b></dt>
1599 * <dd>{@code mergeDelayError} does not operate by default on a particular {@link Scheduler}.</dd>
1600 * </dl>
1601 * <p>History: 2.1.9 - experimental
1602 * @param <T> the common and resulting value type
1603 * @param sources the {@code Iterable} sequence of {@code SingleSource}s
1604 * @return the new {@code Flowable} instance
1605 * @throws NullPointerException if {@code sources} is {@code null}
1606 * @see #merge(Iterable)
1607 * @since 2.2
1608 */
1609 @CheckReturnValue
1610 @NonNull
1611 @BackpressureSupport(BackpressureKind.FULL)
1612 @SchedulerSupport(SchedulerSupport.NONE)
1613 public static <@NonNull T> Flowable<T> mergeDelayError(@NonNull Iterable<@NonNull ? extends SingleSource<? extends T>> sources) {
1614 return Flowable.fromIterable(sources).flatMapSingle(Functions.identity(), true, Integer.MAX_VALUE);
1615 }
1616
1617 /**
1618 * Merges a sequence of {@link SingleSource} instances emitted by a {@link Publisher} into a {@link Flowable} sequence,
1619 * running all {@code SingleSource}s at once and delaying any error(s) until all sources succeed or fail.
1620 * <p>
1621 * <img width="640" height="356" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.mergeDelayError.p.png" alt="">
1622 * <dl>
1623 * <dt><b>Backpressure:</b></dt>
1624 * <dd>The returned {@code Flowable} honors the backpressure of the downstream consumer.</dd>
1625 * <dt><b>Scheduler:</b></dt>
1626 * <dd>{@code mergeDelayError} does not operate by default on a particular {@link Scheduler}.</dd>
1627 * </dl>
1628 * <p>History: 2.1.9 - experimental
1629 * @param <T> the common and resulting value type
1630 * @param sources the {@code Flowable} sequence of {@code SingleSource}s
1631 * @return the new {@code Flowable} instance
1632 * @throws NullPointerException if {@code sources} is {@code null}
1633 * @since 2.2
1634 * @see #merge(Publisher)
1635 */
1636 @CheckReturnValue
1637 @NonNull
1638 @BackpressureSupport(BackpressureKind.FULL)
1639 @SchedulerSupport(SchedulerSupport.NONE)
1640 public static <@NonNull T> Flowable<T> mergeDelayError(@NonNull Publisher<@NonNull ? extends SingleSource<? extends T>> sources) {
1641 Objects.requireNonNull(sources, "sources is null");
1642 return RxJavaPlugins.onAssembly(new FlowableFlatMapSinglePublisher<>(sources, Functions.identity(), true, Integer.MAX_VALUE));
1643 }
1644
1645 /**
1646 * Flattens two {@link SingleSource}s into one {@link Flowable}, without any transformation, delaying
1647 * any error(s) until all sources succeed or fail.
1648 * <p>
1649 * <img width="640" height="554" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.mergeDelayError.2.png" alt="">
1650 * <p>
1651 * You can combine items emitted by multiple {@code SingleSource}s so that they appear as one {@code Flowable}, by
1652 * using the {@code mergeDelayError} method.
1653 * <dl>
1654 * <dt><b>Backpressure:</b></dt>
1655 * <dd>The returned {@code Flowable} honors the backpressure of the downstream consumer.</dd>
1656 * <dt><b>Scheduler:</b></dt>
1657 * <dd>{@code mergeDelayError} does not operate by default on a particular {@link Scheduler}.</dd>
1658 * </dl>
1659 * <p>History: 2.1.9 - experimental
1660 * @param <T> the common value type
1661 * @param source1
1662 * a {@code SingleSource} to be merged
1663 * @param source2
1664 * a {@code SingleSource} to be merged
1665 * @return the new {@code Flowable} that emits all of the items emitted by the source {@code SingleSource}s
1666 * @throws NullPointerException if {@code source1} or {@code source2} is {@code null}
1667 * @see <a href="http://reactivex.io/documentation/operators/merge.html">ReactiveX operators documentation: Merge</a>
1668 * @see #merge(SingleSource, SingleSource)
1669 * @since 2.2
1670 */
1671 @CheckReturnValue
1672 @NonNull
1673 @BackpressureSupport(BackpressureKind.FULL)
1674 @SchedulerSupport(SchedulerSupport.NONE)
1675 public static <@NonNull T> Flowable<T> mergeDelayError(
1676 @NonNull SingleSource<? extends T> source1, @NonNull SingleSource<? extends T> source2
1677 ) {
1678 Objects.requireNonNull(source1, "source1 is null");
1679 Objects.requireNonNull(source2, "source2 is null");
1680 return Flowable.fromArray(source1, source2).flatMapSingle(Functions.identity(), true, Integer.MAX_VALUE);
1681 }
1682
1683 /**
1684 * Flattens two {@link SingleSource}s into one {@link Flowable}, without any transformation, delaying
1685 * any error(s) until all sources succeed or fail.
1686 * <p>
1687 * <img width="640" height="496" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.mergeDelayError.3.png" alt="">
1688 * <p>
1689 * You can combine items emitted by multiple {@code SingleSource}s so that they appear as one {@code Flowable}, by
1690 * the {@code mergeDelayError} method.
1691 * <dl>
1692 * <dt><b>Backpressure:</b></dt>
1693 * <dd>The returned {@code Flowable} honors the backpressure of the downstream consumer.</dd>
1694 * <dt><b>Scheduler:</b></dt>
1695 * <dd>{@code mergeDelayError} does not operate by default on a particular {@link Scheduler}.</dd>
1696 * </dl>
1697 * <p>History: 2.1.9 - experimental
1698 * @param <T> the common value type
1699 * @param source1
1700 * a {@code SingleSource} to be merged
1701 * @param source2
1702 * a {@code SingleSource} to be merged
1703 * @param source3
1704 * a {@code SingleSource} to be merged
1705 * @return the new {@code Flowable} that emits all of the items emitted by the source {@code SingleSource}s
1706 * @throws NullPointerException if {@code source1}, {@code source2} or {@code source3} is {@code null}
1707 * @see <a href="http://reactivex.io/documentation/operators/merge.html">ReactiveX operators documentation: Merge</a>
1708 * @see #merge(SingleSource, SingleSource, SingleSource)
1709 * @since 2.2
1710 */
1711 @CheckReturnValue
1712 @NonNull
1713 @BackpressureSupport(BackpressureKind.FULL)
1714 @SchedulerSupport(SchedulerSupport.NONE)
1715 public static <@NonNull T> Flowable<T> mergeDelayError(
1716 @NonNull SingleSource<? extends T> source1, @NonNull SingleSource<? extends T> source2,
1717 @NonNull SingleSource<? extends T> source3
1718 ) {
1719 Objects.requireNonNull(source1, "source1 is null");
1720 Objects.requireNonNull(source2, "source2 is null");
1721 Objects.requireNonNull(source3, "source3 is null");
1722 return Flowable.fromArray(source1, source2, source3).flatMapSingle(Functions.identity(), true, Integer.MAX_VALUE);
1723 }
1724
1725 /**
1726 * Flattens two {@link SingleSource}s into one {@link Flowable}, without any transformation, delaying
1727 * any error(s) until all sources succeed or fail.
1728 * <p>
1729 * <img width="640" height="509" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.mergeDelayError.4.png" alt="">
1730 * <p>
1731 * You can combine items emitted by multiple {@code SingleSource}s so that they appear as one {@code Flowable}, by
1732 * the {@code mergeDelayError} method.
1733 * <dl>
1734 * <dt><b>Backpressure:</b></dt>
1735 * <dd>The returned {@code Flowable} honors the backpressure of the downstream consumer.</dd>
1736 * <dt><b>Scheduler:</b></dt>
1737 * <dd>{@code mergeDelayError} does not operate by default on a particular {@link Scheduler}.</dd>
1738 * </dl>
1739 * <p>History: 2.1.9 - experimental
1740 * @param <T> the common value type
1741 * @param source1
1742 * a {@code SingleSource} to be merged
1743 * @param source2
1744 * a {@code SingleSource} to be merged
1745 * @param source3
1746 * a {@code SingleSource} to be merged
1747 * @param source4
1748 * a {@code SingleSource} to be merged
1749 * @return the new {@code Flowable} that emits all of the items emitted by the source {@code SingleSource}s
1750 * @throws NullPointerException if {@code source1}, {@code source2}, {@code source3} or {@code source4} is {@code null}
1751 * @see <a href="http://reactivex.io/documentation/operators/merge.html">ReactiveX operators documentation: Merge</a>
1752 * @see #merge(SingleSource, SingleSource, SingleSource, SingleSource)
1753 * @since 2.2
1754 */
1755 @CheckReturnValue
1756 @NonNull
1757 @BackpressureSupport(BackpressureKind.FULL)
1758 @SchedulerSupport(SchedulerSupport.NONE)
1759 public static <@NonNull T> Flowable<T> mergeDelayError(
1760 @NonNull SingleSource<? extends T> source1, @NonNull SingleSource<? extends T> source2,
1761 @NonNull SingleSource<? extends T> source3, @NonNull SingleSource<? extends T> source4
1762 ) {
1763 Objects.requireNonNull(source1, "source1 is null");
1764 Objects.requireNonNull(source2, "source2 is null");
1765 Objects.requireNonNull(source3, "source3 is null");
1766 Objects.requireNonNull(source4, "source4 is null");
1767 return Flowable.fromArray(source1, source2, source3, source4).flatMapSingle(Functions.identity(), true, Integer.MAX_VALUE);
1768 }
1769
1770 /**
1771 * Returns a singleton instance of a never-signaling {@code Single} (only calls {@code onSubscribe}).
1772 * <p>
1773 * <img width="640" height="244" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.never.v3.png" alt="">
1774 * <dl>
1775 * <dt><b>Scheduler:</b></dt>
1776 * <dd>{@code never} does not operate by default on a particular {@link Scheduler}.</dd>
1777 * </dl>
1778 * @param <T> the target value type
1779 * @return the singleton never instance
1780 * @since 2.0
1781 */
1782 @CheckReturnValue
1783 @SchedulerSupport(SchedulerSupport.NONE)
1784 @SuppressWarnings("unchecked")
1785 @NonNull
1786 public static <@NonNull T> Single<T> never() {
1787 return RxJavaPlugins.onAssembly((Single<T>) SingleNever.INSTANCE);
1788 }
1789
1790 /**
1791 * Signals success with 0L value after the given delay when a {@link SingleObserver} subscribes.
1792 * <p>
1793 * <img width="640" height="292" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.timer.v3.png" alt="">
1794 * <dl>
1795 * <dt><b>Scheduler:</b></dt>
1796 * <dd>{@code timer} operates by default on the {@code computation} {@link Scheduler}.</dd>
1797 * </dl>
1798 * @param delay the delay amount
1799 * @param unit the time unit of the delay
1800 * @return the new {@code Single} instance
1801 * @throws NullPointerException if {@code unit} is {@code null}
1802 * @since 2.0
1803 */
1804 @CheckReturnValue
1805 @SchedulerSupport(SchedulerSupport.COMPUTATION)
1806 @NonNull
1807 public static Single<Long> timer(long delay, @NonNull TimeUnit unit) {
1808 return timer(delay, unit, Schedulers.computation());
1809 }
1810
1811 /**
1812 * Signals success with 0L value on the specified {@link Scheduler} after the given
1813 * delay when a {@link SingleObserver} subscribes.
1814 * <p>
1815 * <img width="640" height="292" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.timer.s.v3.png" alt="">
1816 * <dl>
1817 * <dt><b>Scheduler:</b></dt>
1818 * <dd>you specify the {@code Scheduler} to signal on.</dd>
1819 * </dl>
1820 * @param delay the delay amount
1821 * @param unit the time unit of the delay
1822 * @param scheduler the {@code Scheduler} where the single 0L will be emitted
1823 * @return the new {@code Single} instance
1824 * @throws NullPointerException
1825 * if {@code unit} is {@code null}, or
1826 * if {@code scheduler} is {@code null}
1827 * @since 2.0
1828 */
1829 @CheckReturnValue
1830 @NonNull
1831 @SchedulerSupport(SchedulerSupport.CUSTOM)
1832 public static Single<Long> timer(long delay, @NonNull TimeUnit unit, @NonNull Scheduler scheduler) {
1833 Objects.requireNonNull(unit, "unit is null");
1834 Objects.requireNonNull(scheduler, "scheduler is null");
1835 return RxJavaPlugins.onAssembly(new SingleTimer(delay, unit, scheduler));
1836 }
1837
1838 /**
1839 * Compares two {@link SingleSource}s and emits {@code true} if they emit the same value (compared via {@link Object#equals(Object)}).
1840 * <p>
1841 * <img width="640" height="465" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.equals.v3.png" alt="">
1842 * <dl>
1843 * <dt><b>Scheduler:</b></dt>
1844 * <dd>{@code sequenceEqual} does not operate by default on a particular {@link Scheduler}.</dd>
1845 * </dl>
1846 * @param <T> the common value type
1847 * @param source1 the first {@code SingleSource} instance
1848 * @param source2 the second {@code SingleSource} instance
1849 * @return the new {@code Single} instance
1850 * @throws NullPointerException if {@code source1} or {@code source2} is {@code null}
1851 * @since 2.0
1852 */
1853 @CheckReturnValue
1854 @NonNull
1855 @SchedulerSupport(SchedulerSupport.NONE)
1856 public static <@NonNull T> Single<Boolean> sequenceEqual(@NonNull SingleSource<? extends T> source1, @NonNull SingleSource<? extends T> source2) { // NOPMD
1857 Objects.requireNonNull(source1, "source1 is null");
1858 Objects.requireNonNull(source2, "source2 is null");
1859 return RxJavaPlugins.onAssembly(new SingleEquals<>(source1, source2));
1860 }
1861
1862 /**
1863 * Switches between {@link SingleSource}s emitted by the source {@link Publisher} whenever
1864 * a new {@code SingleSource} is emitted, disposing the previously running {@code SingleSource},
1865 * exposing the success items as a {@link Flowable} sequence.
1866 * <p>
1867 * <img width="640" height="521" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.switchOnNext.png" alt="">
1868 * <dl>
1869 * <dt><b>Backpressure:</b></dt>
1870 * <dd>The {@code sources} {@code Publisher} is consumed in an unbounded manner (requesting {@link Long#MAX_VALUE}).
1871 * The returned {@code Flowable} respects the backpressure from the downstream.</dd>
1872 * <dt><b>Scheduler:</b></dt>
1873 * <dd>{@code switchOnNext} does not operate by default on a particular {@link Scheduler}.</dd>
1874 * <dt><b>Error handling:</b></dt>
1875 * <dd>The returned sequence fails with the first error signaled by the {@code sources} {@code Publisher}
1876 * or the currently running {@code SingleSource}, disposing the rest. Late errors are
1877 * forwarded to the global error handler via {@link RxJavaPlugins#onError(Throwable)}.</dd>
1878 * </dl>
1879 * @param <T> the element type of the {@code SingleSource}s
1880 * @param sources the {@code Publisher} sequence of inner {@code SingleSource}s to switch between
1881 * @return the new {@code Flowable} instance
1882 * @throws NullPointerException if {@code sources} is {@code null}
1883 * @since 3.0.0
1884 * @see #switchOnNextDelayError(Publisher)
1885 * @see <a href="http://reactivex.io/documentation/operators/switch.html">ReactiveX operators documentation: Switch</a>
1886 */
1887 @BackpressureSupport(BackpressureKind.FULL)
1888 @CheckReturnValue
1889 @NonNull
1890 @SchedulerSupport(SchedulerSupport.NONE)
1891 public static <@NonNull T> Flowable<T> switchOnNext(@NonNull Publisher<@NonNull ? extends SingleSource<? extends T>> sources) {
1892 Objects.requireNonNull(sources, "sources is null");
1893 return RxJavaPlugins.onAssembly(new FlowableSwitchMapSinglePublisher<>(sources, Functions.identity(), false));
1894 }
1895
1896 /**
1897 * Switches between {@link SingleSource}s emitted by the source {@link Publisher} whenever
1898 * a new {@code SingleSource} is emitted, disposing the previously running {@code SingleSource},
1899 * exposing the success items as a {@link Flowable} sequence and delaying all errors from
1900 * all of them until all terminate.
1901 * <p>
1902 * <img width="640" height="423" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Maybe.switchOnNextDelayError.png" alt="">
1903 * <dl>
1904 * <dt><b>Backpressure:</b></dt>
1905 * <dd>The {@code sources} {@code Publisher} is consumed in an unbounded manner (requesting {@link Long#MAX_VALUE}).
1906 * The returned {@code Flowable} respects the backpressure from the downstream.</dd>
1907 * <dt><b>Scheduler:</b></dt>
1908 * <dd>{@code switchOnNextDelayError} does not operate by default on a particular {@link Scheduler}.</dd>
1909 * <dt><b>Error handling:</b></dt>
1910 * <dd>The returned {@code Flowable} collects all errors emitted by either the {@code sources}
1911 * {@code Publisher} or any inner {@code SingleSource} and emits them as a {@link CompositeException}
1912 * when all sources terminate. If only one source ever failed, its error is emitted as-is at the end.</dd>
1913 * </dl>
1914 * @param <T> the element type of the {@code SingleSource}s
1915 * @param sources the {@code Publisher} sequence of inner {@code SingleSource}s to switch between
1916 * @return the new {@code Flowable} instance
1917 * @throws NullPointerException if {@code sources} is {@code null}
1918 * @since 3.0.0
1919 * @see #switchOnNext(Publisher)
1920 * @see <a href="http://reactivex.io/documentation/operators/switch.html">ReactiveX operators documentation: Switch</a>
1921 */
1922 @BackpressureSupport(BackpressureKind.FULL)
1923 @CheckReturnValue
1924 @NonNull
1925 @SchedulerSupport(SchedulerSupport.NONE)
1926 public static <@NonNull T> Flowable<T> switchOnNextDelayError(@NonNull Publisher<@NonNull ? extends SingleSource<? extends T>> sources) {
1927 Objects.requireNonNull(sources, "sources is null");
1928 return RxJavaPlugins.onAssembly(new FlowableSwitchMapSinglePublisher<>(sources, Functions.identity(), true));
1929 }
1930
1931 /**
1932 * <strong>Advanced use only:</strong> creates a {@code Single} instance without
1933 * any safeguards by using a callback that is called with a {@link SingleObserver}.
1934 * <p>
1935 * <img width="640" height="261" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.unsafeCreate.png" alt="">
1936 * <dl>
1937 * <dt><b>Scheduler:</b></dt>
1938 * <dd>{@code unsafeCreate} does not operate by default on a particular {@link Scheduler}.</dd>
1939 * </dl>
1940 * @param <T> the value type
1941 * @param onSubscribe the function that is called with the subscribing {@code SingleObserver}
1942 * @return the new {@code Single} instance
1943 * @throws NullPointerException if {@code onSubscribe} is {@code null}
1944 * @throws IllegalArgumentException if {@code source} is a subclass of {@code Single}; such
1945 * instances don't need conversion and is possibly a port remnant from 1.x or one should use {@link #hide()}
1946 * instead.
1947 * @since 2.0
1948 */
1949 @CheckReturnValue
1950 @NonNull
1951 @SchedulerSupport(SchedulerSupport.NONE)
1952 public static <@NonNull T> Single<T> unsafeCreate(@NonNull SingleSource<T> onSubscribe) {
1953 Objects.requireNonNull(onSubscribe, "onSubscribe is null");
1954 if (onSubscribe instanceof Single) {
1955 throw new IllegalArgumentException("unsafeCreate(Single) should be upgraded");
1956 }
1957 return RxJavaPlugins.onAssembly(new SingleFromUnsafeSource<>(onSubscribe));
1958 }
1959
1960 /**
1961 * Allows using and disposing a resource while running a {@link SingleSource} instance generated from
1962 * that resource (similar to a try-with-resources).
1963 * <p>
1964 * <img width="640" height="380" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.using.v3.png" alt="">
1965 * <dl>
1966 * <dt><b>Scheduler:</b></dt>
1967 * <dd>{@code using} does not operate by default on a particular {@link Scheduler}.</dd>
1968 * </dl>
1969 * @param <T> the value type of the {@code SingleSource} generated
1970 * @param <U> the resource type
1971 * @param resourceSupplier the {@link Supplier} called for each {@link SingleObserver} to generate a resource object
1972 * @param sourceSupplier the function called with the returned resource
1973 * object from {@code resourceSupplier} and should return a {@code SingleSource} instance
1974 * to be run by the operator
1975 * @param resourceCleanup the consumer of the generated resource that is called exactly once for
1976 * that particular resource when the generated {@code SingleSource} terminates
1977 * (successfully or with an error) or gets disposed.
1978 * @return the new {@code Single} instance
1979 * @throws NullPointerException if {@code resourceSupplier}, {@code sourceSupplier} and {@code resourceCleanup} is {@code null}
1980 * @since 2.0
1981 */
1982 @CheckReturnValue
1983 @SchedulerSupport(SchedulerSupport.NONE)
1984 @NonNull
1985 public static <@NonNull T, @NonNull U> Single<T> using(@NonNull Supplier<U> resourceSupplier,
1986 @NonNull Function<? super U, ? extends SingleSource<? extends T>> sourceSupplier,
1987 @NonNull Consumer<? super U> resourceCleanup) {
1988 return using(resourceSupplier, sourceSupplier, resourceCleanup, true);
1989 }
1990
1991 /**
1992 * Allows using and disposing a resource while running a {@link SingleSource} instance generated from
1993 * that resource (similar to a try-with-resources).
1994 * <p>
1995 * <img width="640" height="325" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.using.b.png" alt="">
1996 * <dl>
1997 * <dt><b>Scheduler:</b></dt>
1998 * <dd>{@code using} does not operate by default on a particular {@link Scheduler}.</dd>
1999 * </dl>
2000 * @param <T> the value type of the {@code SingleSource} generated
2001 * @param <U> the resource type
2002 * @param resourceSupplier the {@link Supplier} called for each {@link SingleObserver} to generate a resource object
2003 * @param sourceSupplier the function called with the returned resource
2004 * object from {@code resourceSupplier} and should return a {@code SingleSource} instance
2005 * to be run by the operator
2006 * @param resourceCleanup the consumer of the generated resource that is called exactly once for
2007 * that particular resource when the generated {@code SingleSource} terminates
2008 * (successfully or with an error) or gets disposed.
2009 * @param eager
2010 * If {@code true} then resource disposal will happen either on a {@code dispose()} call before the upstream is disposed
2011 * or just before the emission of a terminal event ({@code onSuccess} or {@code onError}).
2012 * If {@code false} the resource disposal will happen either on a {@code dispose()} call after the upstream is disposed
2013 * or just after the emission of a terminal event ({@code onSuccess} or {@code onError}).
2014 * @return the new {@code Single} instance
2015 * @throws NullPointerException if {@code resourceSupplier}, {@code sourceSupplier} or {@code resourceCleanup} is {@code null}
2016 * @since 2.0
2017 */
2018 @CheckReturnValue
2019 @NonNull
2020 @SchedulerSupport(SchedulerSupport.NONE)
2021 public static <@NonNull T, @NonNull U> Single<T> using(
2022 @NonNull Supplier<U> resourceSupplier,
2023 @NonNull Function<? super U, ? extends SingleSource<? extends T>> sourceSupplier,
2024 @NonNull Consumer<? super U> resourceCleanup,
2025 boolean eager) {
2026 Objects.requireNonNull(resourceSupplier, "resourceSupplier is null");
2027 Objects.requireNonNull(sourceSupplier, "sourceSupplier is null");
2028 Objects.requireNonNull(resourceCleanup, "resourceCleanup is null");
2029
2030 return RxJavaPlugins.onAssembly(new SingleUsing<>(resourceSupplier, sourceSupplier, resourceCleanup, eager));
2031 }
2032
2033 /**
2034 * Wraps a {@link SingleSource} instance into a new {@code Single} instance if not already a {@code Single}
2035 * instance.
2036 * <p>
2037 * <img width="640" height="350" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.wrap.png" alt="">
2038 * <dl>
2039 * <dt><b>Scheduler:</b></dt>
2040 * <dd>{@code wrap} does not operate by default on a particular {@link Scheduler}.</dd>
2041 * </dl>
2042 * @param <T> the value type
2043 * @param source the source to wrap
2044 * @return the new {@code Single} instance
2045 * @throws NullPointerException if {@code source} is {@code null}
2046 */
2047 @CheckReturnValue
2048 @NonNull
2049 @SchedulerSupport(SchedulerSupport.NONE)
2050 public static <@NonNull T> Single<T> wrap(@NonNull SingleSource<T> source) {
2051 Objects.requireNonNull(source, "source is null");
2052 if (source instanceof Single) {
2053 return RxJavaPlugins.onAssembly((Single<T>)source);
2054 }
2055 return RxJavaPlugins.onAssembly(new SingleFromUnsafeSource<>(source));
2056 }
2057
2058 /**
2059 * Waits until all {@link SingleSource} sources provided by the {@link Iterable} sequence signal a success
2060 * value and calls a zipper function with an array of these values to return a result
2061 * to be emitted to the downstream.
2062 * <p>
2063 * If the {@code Iterable} of {@code SingleSource}s is empty a {@link NoSuchElementException} error is signaled after subscription.
2064 * <p>
2065 * Note on method signature: since Java doesn't allow creating a generic array with {@code new T[]}, the
2066 * implementation of this operator has to create an {@code Object[]} instead. Unfortunately, a
2067 * {@code Function<Integer[], R>} passed to the method would trigger a {@link ClassCastException}.
2068 *
2069 * <p>
2070 * <img width="640" height="340" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.zip.i.png" alt="">
2071 * <p>
2072 * If any of the {@code SingleSources} signal an error, all other {@code SingleSource}s get disposed and the
2073 * error emitted to downstream immediately.
2074 * <dl>
2075 * <dt><b>Scheduler:</b></dt>
2076 * <dd>{@code zip} does not operate by default on a particular {@link Scheduler}.</dd>
2077 * </dl>
2078 * @param <T> the common value type
2079 * @param <R> the result value type
2080 * @param sources the {@code Iterable} sequence of {@code SingleSource} instances. An empty sequence will result in an
2081 * {@code onError} signal of {@code NoSuchElementException}.
2082 * @param zipper the function that receives an array with values from each {@code SingleSource}
2083 * and should return a value to be emitted to downstream
2084 * @return the new {@code Single} instance
2085 * @throws NullPointerException if {@code zipper} or {@code sources} is {@code null}
2086 * @since 2.0
2087 */
2088 @CheckReturnValue
2089 @NonNull
2090 @SchedulerSupport(SchedulerSupport.NONE)
2091 public static <@NonNull T, @NonNull R> Single<R> zip(@NonNull Iterable<@NonNull ? extends SingleSource<? extends T>> sources,
2092 @NonNull Function<? super Object[], ? extends R> zipper) {
2093 Objects.requireNonNull(zipper, "zipper is null");
2094 Objects.requireNonNull(sources, "sources is null");
2095 return RxJavaPlugins.onAssembly(new SingleZipIterable<>(sources, zipper));
2096 }
2097
2098 /**
2099 * Returns a {@code Single} that emits the results of a specified combiner function applied to two items emitted by
2100 * two other {@link SingleSource}s.
2101 * <p>
2102 * <img width="640" height="434" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.zip.n.png" alt="">
2103 * <dl>
2104 * <dt><b>Scheduler:</b></dt>
2105 * <dd>{@code zip} does not operate by default on a particular {@link Scheduler}.</dd>
2106 * </dl>
2107 *
2108 * @param <T1> the first source {@code SingleSource}'s value type
2109 * @param <T2> the second source {@code SingleSource}'s value type
2110 * @param <R> the result value type
2111 * @param source1
2112 * the first source {@code SingleSource}
2113 * @param source2
2114 * a second source {@code SingleSource}
2115 * @param zipper
2116 * a function that, when applied to the item emitted by each of the source {@code SingleSource}s, results in an
2117 * item that will be emitted by the resulting {@code Single}
2118 * @return the new {@code Single} that emits the zipped results
2119 * @throws NullPointerException if {@code source1}, {@code source2} or {@code zipper} is {@code null}
2120 * @see <a href="http://reactivex.io/documentation/operators/zip.html">ReactiveX operators documentation: Zip</a>
2121 */
2122 @CheckReturnValue
2123 @NonNull
2124 @SchedulerSupport(SchedulerSupport.NONE)
2125 public static <@NonNull T1, @NonNull T2, @NonNull R> Single<R> zip(
2126 @NonNull SingleSource<? extends T1> source1, @NonNull SingleSource<? extends T2> source2,
2127 @NonNull BiFunction<? super T1, ? super T2, ? extends R> zipper
2128 ) {
2129 Objects.requireNonNull(source1, "source1 is null");
2130 Objects.requireNonNull(source2, "source2 is null");
2131 Objects.requireNonNull(zipper, "zipper is null");
2132 return zipArray(Functions.toFunction(zipper), source1, source2);
2133 }
2134
2135 /**
2136 * Returns a {@code Single} that emits the results of a specified combiner function applied to three items emitted
2137 * by three other {@link SingleSource}s.
2138 * <p>
2139 * <img width="640" height="434" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.zip.n.png" alt="">
2140 * <dl>
2141 * <dt><b>Scheduler:</b></dt>
2142 * <dd>{@code zip} does not operate by default on a particular {@link Scheduler}.</dd>
2143 * </dl>
2144 *
2145 * @param <T1> the first source {@code SingleSource}'s value type
2146 * @param <T2> the second source {@code SingleSource}'s value type
2147 * @param <T3> the third source {@code SingleSource}'s value type
2148 * @param <R> the result value type
2149 * @param source1
2150 * the first source {@code SingleSource}
2151 * @param source2
2152 * a second source {@code SingleSource}
2153 * @param source3
2154 * a third source {@code SingleSource}
2155 * @param zipper
2156 * a function that, when applied to the item emitted by each of the source {@code SingleSource}s, results in an
2157 * item that will be emitted by the resulting {@code Single}
2158 * @return the new {@code Single} that emits the zipped results
2159 * @throws NullPointerException if {@code source1}, {@code source2}, {@code source3} or {@code zipper} is {@code null}
2160 * @see <a href="http://reactivex.io/documentation/operators/zip.html">ReactiveX operators documentation: Zip</a>
2161 */
2162 @CheckReturnValue
2163 @NonNull
2164 @SchedulerSupport(SchedulerSupport.NONE)
2165 public static <@NonNull T1, @NonNull T2, @NonNull T3, @NonNull R> Single<R> zip(
2166 @NonNull SingleSource<? extends T1> source1, @NonNull SingleSource<? extends T2> source2,
2167 @NonNull SingleSource<? extends T3> source3,
2168 @NonNull Function3<? super T1, ? super T2, ? super T3, ? extends R> zipper
2169 ) {
2170 Objects.requireNonNull(source1, "source1 is null");
2171 Objects.requireNonNull(source2, "source2 is null");
2172 Objects.requireNonNull(source3, "source3 is null");
2173 Objects.requireNonNull(zipper, "zipper is null");
2174 return zipArray(Functions.toFunction(zipper), source1, source2, source3);
2175 }
2176
2177 /**
2178 * Returns a {@code Single} that emits the results of a specified combiner function applied to four items
2179 * emitted by four other {@link SingleSource}s.
2180 * <p>
2181 * <img width="640" height="434" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.zip.n.png" alt="">
2182 * <dl>
2183 * <dt><b>Scheduler:</b></dt>
2184 * <dd>{@code zip} does not operate by default on a particular {@link Scheduler}.</dd>
2185 * </dl>
2186 *
2187 * @param <T1> the first source {@code SingleSource}'s value type
2188 * @param <T2> the second source {@code SingleSource}'s value type
2189 * @param <T3> the third source {@code SingleSource}'s value type
2190 * @param <T4> the fourth source {@code SingleSource}'s value type
2191 * @param <R> the result value type
2192 * @param source1
2193 * the first source {@code SingleSource}
2194 * @param source2
2195 * a second source {@code SingleSource}
2196 * @param source3
2197 * a third source {@code SingleSource}
2198 * @param source4
2199 * a fourth source {@code SingleSource}
2200 * @param zipper
2201 * a function that, when applied to the item emitted by each of the source {@code SingleSource}s, results in an
2202 * item that will be emitted by the resulting {@code Single}
2203 * @return the new {@code Single} that emits the zipped results
2204 * @throws NullPointerException if {@code source1}, {@code source2}, {@code source3}, {@code source4} or {@code zipper} is {@code null}
2205 * @see <a href="http://reactivex.io/documentation/operators/zip.html">ReactiveX operators documentation: Zip</a>
2206 */
2207 @CheckReturnValue
2208 @NonNull
2209 @SchedulerSupport(SchedulerSupport.NONE)
2210 public static <@NonNull T1, @NonNull T2, @NonNull T3, @NonNull T4, @NonNull R> Single<R> zip(
2211 @NonNull SingleSource<? extends T1> source1, @NonNull SingleSource<? extends T2> source2,
2212 @NonNull SingleSource<? extends T3> source3, @NonNull SingleSource<? extends T4> source4,
2213 @NonNull Function4<? super T1, ? super T2, ? super T3, ? super T4, ? extends R> zipper
2214 ) {
2215 Objects.requireNonNull(source1, "source1 is null");
2216 Objects.requireNonNull(source2, "source2 is null");
2217 Objects.requireNonNull(source3, "source3 is null");
2218 Objects.requireNonNull(source4, "source4 is null");
2219 Objects.requireNonNull(zipper, "zipper is null");
2220 return zipArray(Functions.toFunction(zipper), source1, source2, source3, source4);
2221 }
2222
2223 /**
2224 * Returns a {@code Single} that emits the results of a specified combiner function applied to five items
2225 * emitted by five other {@link SingleSource}s.
2226 * <p>
2227 * <img width="640" height="434" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.zip.n.png" alt="">
2228 * <dl>
2229 * <dt><b>Scheduler:</b></dt>
2230 * <dd>{@code zip} does not operate by default on a particular {@link Scheduler}.</dd>
2231 * </dl>
2232 *
2233 * @param <T1> the first source {@code SingleSource}'s value type
2234 * @param <T2> the second source {@code SingleSource}'s value type
2235 * @param <T3> the third source {@code SingleSource}'s value type
2236 * @param <T4> the fourth source {@code SingleSource}'s value type
2237 * @param <T5> the fifth source {@code SingleSource}'s value type
2238 * @param <R> the result value type
2239 * @param source1
2240 * the first source {@code SingleSource}
2241 * @param source2
2242 * a second source {@code SingleSource}
2243 * @param source3
2244 * a third source {@code SingleSource}
2245 * @param source4
2246 * a fourth source {@code SingleSource}
2247 * @param source5
2248 * a fifth source {@code SingleSource}
2249 * @param zipper
2250 * a function that, when applied to the item emitted by each of the source {@code SingleSource}s, results in an
2251 * item that will be emitted by the resulting {@code Single}
2252 * @return the new {@code Single} that emits the zipped results
2253 * @throws NullPointerException if {@code source1}, {@code source2}, {@code source3}, {@code source4}
2254 * {@code source5} or {@code zipper} is {@code null}
2255 * @see <a href="http://reactivex.io/documentation/operators/zip.html">ReactiveX operators documentation: Zip</a>
2256 */
2257 @CheckReturnValue
2258 @NonNull
2259 @SchedulerSupport(SchedulerSupport.NONE)
2260 public static <@NonNull T1, @NonNull T2, @NonNull T3, @NonNull T4, @NonNull T5, @NonNull R> Single<R> zip(
2261 @NonNull SingleSource<? extends T1> source1, @NonNull SingleSource<? extends T2> source2,
2262 @NonNull SingleSource<? extends T3> source3, @NonNull SingleSource<? extends T4> source4,
2263 @NonNull SingleSource<? extends T5> source5,
2264 @NonNull Function5<? super T1, ? super T2, ? super T3, ? super T4, ? super T5, ? extends R> zipper
2265 ) {
2266 Objects.requireNonNull(source1, "source1 is null");
2267 Objects.requireNonNull(source2, "source2 is null");
2268 Objects.requireNonNull(source3, "source3 is null");
2269 Objects.requireNonNull(source4, "source4 is null");
2270 Objects.requireNonNull(source5, "source5 is null");
2271 Objects.requireNonNull(zipper, "zipper is null");
2272 return zipArray(Functions.toFunction(zipper), source1, source2, source3, source4, source5);
2273 }
2274
2275 /**
2276 * Returns a {@code Single} that emits the results of a specified combiner function applied to six items
2277 * emitted by six other {@link SingleSource}s.
2278 * <p>
2279 * <img width="640" height="434" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.zip.n.png" alt="">
2280 * <dl>
2281 * <dt><b>Scheduler:</b></dt>
2282 * <dd>{@code zip} does not operate by default on a particular {@link Scheduler}.</dd>
2283 * </dl>
2284 *
2285 * @param <T1> the first source {@code SingleSource}'s value type
2286 * @param <T2> the second source {@code SingleSource}'s value type
2287 * @param <T3> the third source {@code SingleSource}'s value type
2288 * @param <T4> the fourth source {@code SingleSource}'s value type
2289 * @param <T5> the fifth source {@code SingleSource}'s value type
2290 * @param <T6> the sixth source {@code SingleSource}'s value type
2291 * @param <R> the result value type
2292 * @param source1
2293 * the first source {@code SingleSource}
2294 * @param source2
2295 * a second source {@code SingleSource}
2296 * @param source3
2297 * a third source {@code SingleSource}
2298 * @param source4
2299 * a fourth source {@code SingleSource}
2300 * @param source5
2301 * a fifth source {@code SingleSource}
2302 * @param source6
2303 * a sixth source {@code SingleSource}
2304 * @param zipper
2305 * a function that, when applied to the item emitted by each of the source {@code SingleSource}s, results in an
2306 * item that will be emitted by the resulting {@code Single}
2307 * @return the new {@code Single} that emits the zipped results
2308 * @throws NullPointerException if {@code source1}, {@code source2}, {@code source3}, {@code source4}
2309 * {@code source5}, {@code source6} or {@code zipper} is {@code null}
2310 * @see <a href="http://reactivex.io/documentation/operators/zip.html">ReactiveX operators documentation: Zip</a>
2311 */
2312 @CheckReturnValue
2313 @NonNull
2314 @SchedulerSupport(SchedulerSupport.NONE)
2315 public static <@NonNull T1, @NonNull T2, @NonNull T3, @NonNull T4, @NonNull T5, @NonNull T6, @NonNull R> Single<R> zip(
2316 @NonNull SingleSource<? extends T1> source1, @NonNull SingleSource<? extends T2> source2,
2317 @NonNull SingleSource<? extends T3> source3, @NonNull SingleSource<? extends T4> source4,
2318 @NonNull SingleSource<? extends T5> source5, @NonNull SingleSource<? extends T6> source6,
2319 @NonNull Function6<? super T1, ? super T2, ? super T3, ? super T4, ? super T5, ? super T6, ? extends R> zipper
2320 ) {
2321 Objects.requireNonNull(source1, "source1 is null");
2322 Objects.requireNonNull(source2, "source2 is null");
2323 Objects.requireNonNull(source3, "source3 is null");
2324 Objects.requireNonNull(source4, "source4 is null");
2325 Objects.requireNonNull(source5, "source5 is null");
2326 Objects.requireNonNull(source6, "source6 is null");
2327 Objects.requireNonNull(zipper, "zipper is null");
2328 return zipArray(Functions.toFunction(zipper), source1, source2, source3, source4, source5, source6);
2329 }
2330
2331 /**
2332 * Returns a {@code Single} that emits the results of a specified combiner function applied to seven items
2333 * emitted by seven other {@link SingleSource}s.
2334 * <p>
2335 * <img width="640" height="434" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.zip.n.png" alt="">
2336 * <dl>
2337 * <dt><b>Scheduler:</b></dt>
2338 * <dd>{@code zip} does not operate by default on a particular {@link Scheduler}.</dd>
2339 * </dl>
2340 *
2341 * @param <T1> the first source {@code SingleSource}'s value type
2342 * @param <T2> the second source {@code SingleSource}'s value type
2343 * @param <T3> the third source {@code SingleSource}'s value type
2344 * @param <T4> the fourth source {@code SingleSource}'s value type
2345 * @param <T5> the fifth source {@code SingleSource}'s value type
2346 * @param <T6> the sixth source {@code SingleSource}'s value type
2347 * @param <T7> the seventh source {@code SingleSource}'s value type
2348 * @param <R> the result value type
2349 * @param source1
2350 * the first source {@code SingleSource}
2351 * @param source2
2352 * a second source {@code SingleSource}
2353 * @param source3
2354 * a third source {@code SingleSource}
2355 * @param source4
2356 * a fourth source {@code SingleSource}
2357 * @param source5
2358 * a fifth source {@code SingleSource}
2359 * @param source6
2360 * a sixth source {@code SingleSource}
2361 * @param source7
2362 * a seventh source {@code SingleSource}
2363 * @param zipper
2364 * a function that, when applied to the item emitted by each of the source {@code SingleSource}s, results in an
2365 * item that will be emitted by the resulting {@code Single}
2366 * @return the new {@code Single} that emits the zipped results
2367 * @throws NullPointerException if {@code source1}, {@code source2}, {@code source3}, {@code source4}
2368 * {@code source5}, {@code source6}, {@code source7} or {@code zipper} is {@code null}
2369 * @see <a href="http://reactivex.io/documentation/operators/zip.html">ReactiveX operators documentation: Zip</a>
2370 */
2371 @CheckReturnValue
2372 @NonNull
2373 @SchedulerSupport(SchedulerSupport.NONE)
2374 public static <@NonNull T1, @NonNull T2, @NonNull T3, @NonNull T4, @NonNull T5, @NonNull T6, @NonNull T7, @NonNull R> Single<R> zip(
2375 @NonNull SingleSource<? extends T1> source1, @NonNull SingleSource<? extends T2> source2,
2376 @NonNull SingleSource<? extends T3> source3, @NonNull SingleSource<? extends T4> source4,
2377 @NonNull SingleSource<? extends T5> source5, @NonNull SingleSource<? extends T6> source6,
2378 @NonNull SingleSource<? extends T7> source7,
2379 @NonNull Function7<? super T1, ? super T2, ? super T3, ? super T4, ? super T5, ? super T6, ? super T7, ? extends R> zipper
2380 ) {
2381 Objects.requireNonNull(source1, "source1 is null");
2382 Objects.requireNonNull(source2, "source2 is null");
2383 Objects.requireNonNull(source3, "source3 is null");
2384 Objects.requireNonNull(source4, "source4 is null");
2385 Objects.requireNonNull(source5, "source5 is null");
2386 Objects.requireNonNull(source6, "source6 is null");
2387 Objects.requireNonNull(source7, "source7 is null");
2388 Objects.requireNonNull(zipper, "zipper is null");
2389 return zipArray(Functions.toFunction(zipper), source1, source2, source3, source4, source5, source6, source7);
2390 }
2391
2392 /**
2393 * Returns a {@code Single} that emits the results of a specified combiner function applied to eight items
2394 * emitted by eight other {@link SingleSource}s.
2395 * <p>
2396 * <img width="640" height="434" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.zip.n.png" alt="">
2397 * <dl>
2398 * <dt><b>Scheduler:</b></dt>
2399 * <dd>{@code zip} does not operate by default on a particular {@link Scheduler}.</dd>
2400 * </dl>
2401 *
2402 * @param <T1> the first source {@code SingleSource}'s value type
2403 * @param <T2> the second source {@code SingleSource}'s value type
2404 * @param <T3> the third source {@code SingleSource}'s value type
2405 * @param <T4> the fourth source {@code SingleSource}'s value type
2406 * @param <T5> the fifth source {@code SingleSource}'s value type
2407 * @param <T6> the sixth source {@code SingleSource}'s value type
2408 * @param <T7> the seventh source {@code SingleSource}'s value type
2409 * @param <T8> the eighth source {@code SingleSource}'s value type
2410 * @param <R> the result value type
2411 * @param source1
2412 * the first source {@code SingleSource}
2413 * @param source2
2414 * a second source {@code SingleSource}
2415 * @param source3
2416 * a third source {@code SingleSource}
2417 * @param source4
2418 * a fourth source {@code SingleSource}
2419 * @param source5
2420 * a fifth source {@code SingleSource}
2421 * @param source6
2422 * a sixth source {@code SingleSource}
2423 * @param source7
2424 * a seventh source {@code SingleSource}
2425 * @param source8
2426 * an eighth source {@code SingleSource}
2427 * @param zipper
2428 * a function that, when applied to the item emitted by each of the source {@code SingleSource}s, results in an
2429 * item that will be emitted by the resulting {@code Single}
2430 * @return the new {@code Single} that emits the zipped results
2431 * @throws NullPointerException if {@code source1}, {@code source2}, {@code source3}, {@code source4}
2432 * {@code source5}, {@code source6}, {@code source7}, {@code source8} or {@code zipper} is {@code null}
2433 * @see <a href="http://reactivex.io/documentation/operators/zip.html">ReactiveX operators documentation: Zip</a>
2434 */
2435 @CheckReturnValue
2436 @NonNull
2437 @SchedulerSupport(SchedulerSupport.NONE)
2438 public static <@NonNull T1, @NonNull T2, @NonNull T3, @NonNull T4, @NonNull T5, @NonNull T6, @NonNull T7, @NonNull T8, @NonNull R> Single<R> zip(
2439 @NonNull SingleSource<? extends T1> source1, @NonNull SingleSource<? extends T2> source2,
2440 @NonNull SingleSource<? extends T3> source3, @NonNull SingleSource<? extends T4> source4,
2441 @NonNull SingleSource<? extends T5> source5, @NonNull SingleSource<? extends T6> source6,
2442 @NonNull SingleSource<? extends T7> source7, @NonNull SingleSource<? extends T8> source8,
2443 @NonNull Function8<? super T1, ? super T2, ? super T3, ? super T4, ? super T5, ? super T6, ? super T7, ? super T8, ? extends R> zipper
2444 ) {
2445 Objects.requireNonNull(source1, "source1 is null");
2446 Objects.requireNonNull(source2, "source2 is null");
2447 Objects.requireNonNull(source3, "source3 is null");
2448 Objects.requireNonNull(source4, "source4 is null");
2449 Objects.requireNonNull(source5, "source5 is null");
2450 Objects.requireNonNull(source6, "source6 is null");
2451 Objects.requireNonNull(source7, "source7 is null");
2452 Objects.requireNonNull(source8, "source8 is null");
2453 Objects.requireNonNull(zipper, "zipper is null");
2454 return zipArray(Functions.toFunction(zipper), source1, source2, source3, source4, source5, source6, source7, source8);
2455 }
2456
2457 /**
2458 * Returns a {@code Single} that emits the results of a specified combiner function applied to nine items
2459 * emitted by nine other {@link SingleSource}s.
2460 * <p>
2461 * <img width="640" height="434" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.zip.n.png" alt="">
2462 * <dl>
2463 * <dt><b>Scheduler:</b></dt>
2464 * <dd>{@code zip} does not operate by default on a particular {@link Scheduler}.</dd>
2465 * </dl>
2466 *
2467 * @param <T1> the first source {@code SingleSource}'s value type
2468 * @param <T2> the second source {@code SingleSource}'s value type
2469 * @param <T3> the third source {@code SingleSource}'s value type
2470 * @param <T4> the fourth source {@code SingleSource}'s value type
2471 * @param <T5> the fifth source {@code SingleSource}'s value type
2472 * @param <T6> the sixth source {@code SingleSource}'s value type
2473 * @param <T7> the seventh source {@code SingleSource}'s value type
2474 * @param <T8> the eighth source {@code SingleSource}'s value type
2475 * @param <T9> the ninth source {@code SingleSource}'s value type
2476 * @param <R> the result value type
2477 * @param source1
2478 * the first source {@code SingleSource}
2479 * @param source2
2480 * a second source {@code SingleSource}
2481 * @param source3
2482 * a third source {@code SingleSource}
2483 * @param source4
2484 * a fourth source {@code SingleSource}
2485 * @param source5
2486 * a fifth source {@code SingleSource}
2487 * @param source6
2488 * a sixth source {@code SingleSource}
2489 * @param source7
2490 * a seventh source {@code SingleSource}
2491 * @param source8
2492 * an eighth source {@code SingleSource}
2493 * @param source9
2494 * a ninth source {@code SingleSource}
2495 * @param zipper
2496 * a function that, when applied to the item emitted by each of the source {@code SingleSource}s, results in an
2497 * item that will be emitted by the resulting {@code Single}
2498 * @return the new {@code Single} that emits the zipped results
2499 * @throws NullPointerException if {@code source1}, {@code source2}, {@code source3}, {@code source4}
2500 * {@code source5}, {@code source6}, {@code source7}, {@code source8},
2501 * {@code source9} or {@code zipper} is {@code null}
2502 * @see <a href="http://reactivex.io/documentation/operators/zip.html">ReactiveX operators documentation: Zip</a>
2503 */
2504 @CheckReturnValue
2505 @NonNull
2506 @SchedulerSupport(SchedulerSupport.NONE)
2507 public static <@NonNull T1, @NonNull T2, @NonNull T3, @NonNull T4, @NonNull T5, @NonNull T6, @NonNull T7, @NonNull T8, @NonNull T9, @NonNull R> Single<R> zip(
2508 @NonNull SingleSource<? extends T1> source1, @NonNull SingleSource<? extends T2> source2,
2509 @NonNull SingleSource<? extends T3> source3, @NonNull SingleSource<? extends T4> source4,
2510 @NonNull SingleSource<? extends T5> source5, @NonNull SingleSource<? extends T6> source6,
2511 @NonNull SingleSource<? extends T7> source7, @NonNull SingleSource<? extends T8> source8,
2512 @NonNull SingleSource<? extends T9> source9,
2513 @NonNull Function9<? super T1, ? super T2, ? super T3, ? super T4, ? super T5, ? super T6, ? super T7, ? super T8, ? super T9, ? extends R> zipper
2514 ) {
2515 Objects.requireNonNull(source1, "source1 is null");
2516 Objects.requireNonNull(source2, "source2 is null");
2517 Objects.requireNonNull(source3, "source3 is null");
2518 Objects.requireNonNull(source4, "source4 is null");
2519 Objects.requireNonNull(source5, "source5 is null");
2520 Objects.requireNonNull(source6, "source6 is null");
2521 Objects.requireNonNull(source7, "source7 is null");
2522 Objects.requireNonNull(source8, "source8 is null");
2523 Objects.requireNonNull(source9, "source9 is null");
2524 Objects.requireNonNull(zipper, "zipper is null");
2525 return zipArray(Functions.toFunction(zipper), source1, source2, source3, source4, source5, source6, source7, source8, source9);
2526 }
2527
2528 /**
2529 * Waits until all {@link SingleSource} sources provided via an array signal a success
2530 * value and calls a zipper function with an array of these values to return a result
2531 * to be emitted to downstream.
2532 * <p>
2533 * <img width="640" height="340" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.zipArray.png" alt="">
2534 * <p>
2535 * If the array of {@code SingleSource}s is empty a {@link NoSuchElementException} error is signaled immediately.
2536 * <p>
2537 * Note on method signature: since Java doesn't allow creating a generic array with {@code new T[]}, the
2538 * implementation of this operator has to create an {@code Object[]} instead. Unfortunately, a
2539 * {@code Function<Integer[], R>} passed to the method would trigger a {@link ClassCastException}.
2540 * <p>
2541 * If any of the {@code SingleSource}s signal an error, all other {@code SingleSource}s get disposed and the
2542 * error emitted to downstream immediately.
2543 * <dl>
2544 * <dt><b>Scheduler:</b></dt>
2545 * <dd>{@code zipArray} does not operate by default on a particular {@link Scheduler}.</dd>
2546 * </dl>
2547 * @param <T> the common value type
2548 * @param <R> the result value type
2549 * @param sources the array of {@code SingleSource} instances. An empty sequence will result in an
2550 * {@code onError} signal of {@code NoSuchElementException}.
2551 * @param zipper the function that receives an array with values from each {@code SingleSource}
2552 * and should return a value to be emitted to downstream
2553 * @return the new {@code Single} instance
2554 * @throws NullPointerException if {@code zipper} or {@code sources} is {@code null}
2555 * @since 2.0
2556 */
2557 @CheckReturnValue
2558 @NonNull
2559 @SchedulerSupport(SchedulerSupport.NONE)
2560 @SafeVarargs
2561 public static <@NonNull T, @NonNull R> Single<R> zipArray(@NonNull Function<? super Object[], ? extends R> zipper, @NonNull SingleSource<? extends T>... sources) {
2562 Objects.requireNonNull(zipper, "zipper is null");
2563 Objects.requireNonNull(sources, "sources is null");
2564 if (sources.length == 0) {
2565 return error(new NoSuchElementException());
2566 }
2567 return RxJavaPlugins.onAssembly(new SingleZipArray<>(sources, zipper));
2568 }
2569
2570 /**
2571 * Signals the event of this or the other {@link SingleSource} whichever signals first.
2572 * <p>
2573 * <img width="640" height="463" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.ambWith.v3.png" alt="">
2574 * <dl>
2575 * <dt><b>Scheduler:</b></dt>
2576 * <dd>{@code ambWith} does not operate by default on a particular {@link Scheduler}.</dd>
2577 * </dl>
2578 * @param other the other {@code SingleSource} to race for the first emission of success or error
2579 * @return the new {@code Single} instance. A subscription to this provided source will occur after subscribing
2580 * to the current source.
2581 * @throws NullPointerException if {@code other} is {@code null}
2582 * @since 2.0
2583 */
2584 @CheckReturnValue
2585 @NonNull
2586 @SchedulerSupport(SchedulerSupport.NONE)
2587 public final Single<T> ambWith(@NonNull SingleSource<? extends T> other) {
2588 Objects.requireNonNull(other, "other is null");
2589 return ambArray(this, other);
2590 }
2591
2592 /**
2593 * Hides the identity of the current {@code Single}, including the {@link Disposable} that is sent
2594 * to the downstream via {@code onSubscribe()}.
2595 * <p>
2596 * <img width="640" height="458" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.hide.v3.png" alt="">
2597 * <dl>
2598 * <dt><b>Scheduler:</b></dt>
2599 * <dd>{@code hide} does not operate by default on a particular {@link Scheduler}.</dd>
2600 * </dl>
2601 * @return the new {@code Single} instance
2602 * @since 2.0
2603 */
2604 @CheckReturnValue
2605 @SchedulerSupport(SchedulerSupport.NONE)
2606 @NonNull
2607 public final Single<T> hide() {
2608 return RxJavaPlugins.onAssembly(new SingleHide<>(this));
2609 }
2610
2611 /**
2612 * Transform a {@code Single} by applying a particular {@link SingleTransformer} function to it.
2613 * <p>
2614 * <img width="640" height="612" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.compose.v3.png" alt="">
2615 * <p>
2616 * This method operates on the {@code Single} itself whereas {@link #lift} operates on {@link SingleObserver}s.
2617 * <p>
2618 * If the operator you are creating is designed to act on the individual item emitted by a {@code Single}, use
2619 * {@link #lift}. If your operator is designed to transform the current {@code Single} as a whole (for instance, by
2620 * applying a particular set of existing RxJava operators to it) use {@code compose}.
2621 * <dl>
2622 * <dt><b>Scheduler:</b></dt>
2623 * <dd>{@code compose} does not operate by default on a particular {@link Scheduler}.</dd>
2624 * </dl>
2625 *
2626 * @param <R> the value type of the single returned by the transformer function
2627 * @param transformer the transformer function, not {@code null}
2628 * @return the new {@code Single} instance
2629 * @throws NullPointerException if {@code transformer} is {@code null}
2630 * @see <a href="https://github.com/ReactiveX/RxJava/wiki/Implementing-Your-Own-Operators">RxJava wiki: Implementing Your Own Operators</a>
2631 */
2632 @SuppressWarnings("unchecked")
2633 @CheckReturnValue
2634 @SchedulerSupport(SchedulerSupport.NONE)
2635 @NonNull
2636 public final <@NonNull R> Single<R> compose(@NonNull SingleTransformer<? super T, ? extends R> transformer) {
2637 return wrap(((SingleTransformer<T, R>) Objects.requireNonNull(transformer, "transformer is null")).apply(this));
2638 }
2639
2640 /**
2641 * Stores the success value or exception from the current {@code Single} and replays it to late {@link SingleObserver}s.
2642 * <p>
2643 * <img width="640" height="363" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.cache.png" alt="">
2644 * <p>
2645 * The returned {@code Single} subscribes to the current {@code Single} when the first {@code SingleObserver} subscribes.
2646 * <dl>
2647 * <dt><b>Scheduler:</b></dt>
2648 * <dd>{@code cache} does not operate by default on a particular {@link Scheduler}.</dd>
2649 * </dl>
2650 *
2651 * @return the new {@code Single} instance
2652 * @since 2.0
2653 */
2654 @CheckReturnValue
2655 @SchedulerSupport(SchedulerSupport.NONE)
2656 @NonNull
2657 public final Single<T> cache() {
2658 return RxJavaPlugins.onAssembly(new SingleCache<>(this));
2659 }
2660
2661 /**
2662 * Casts the success value of the current {@code Single} into the target type or signals a
2663 * {@link ClassCastException} if not compatible.
2664 * <p>
2665 * <img width="640" height="393" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.cast.png" alt="">
2666 * <dl>
2667 * <dt><b>Scheduler:</b></dt>
2668 * <dd>{@code cast} does not operate by default on a particular {@link Scheduler}.</dd>
2669 * </dl>
2670 * @param <U> the target type
2671 * @param clazz the type token to use for casting the success result from the current {@code Single}
2672 * @return the new {@code Single} instance
2673 * @throws NullPointerException if {@code clazz} is {@code null}
2674 * @since 2.0
2675 */
2676 @CheckReturnValue
2677 @NonNull
2678 @SchedulerSupport(SchedulerSupport.NONE)
2679 public final <@NonNull U> Single<U> cast(@NonNull Class<? extends U> clazz) {
2680 Objects.requireNonNull(clazz, "clazz is null");
2681 return map(Functions.castFunction(clazz));
2682 }
2683
2684 /**
2685 * Returns a {@code Single} that is based on applying a specified function to the item emitted by the current {@code Single},
2686 * where that function returns a {@link SingleSource}.
2687 * <p>
2688 * <img width="640" height="313" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.concatMap.png" alt="">
2689 * <p>
2690 * The operator is an alias for {@link #flatMap(Function)}
2691 * <dl>
2692 * <dt><b>Scheduler:</b></dt>
2693 * <dd>{@code concatMap} does not operate by default on a particular {@link Scheduler}.</dd>
2694 * </dl>
2695 *
2696 * @param <R> the result value type
2697 * @param mapper
2698 * a function that, when applied to the item emitted by the current {@code Single}, returns a {@code SingleSource}
2699 * @return the new {@code Single} returned from {@code mapper} when applied to the item emitted by the current {@code Single}
2700 * @throws NullPointerException if {@code mapper} is {@code null}
2701 * @see <a href="http://reactivex.io/documentation/operators/flatmap.html">ReactiveX operators documentation: FlatMap</a>
2702 * @since 3.0.0
2703 */
2704 @CheckReturnValue
2705 @NonNull
2706 @SchedulerSupport(SchedulerSupport.NONE)
2707 public final <@NonNull R> Single<R> concatMap(@NonNull Function<? super T, ? extends SingleSource<? extends R>> mapper) {
2708 Objects.requireNonNull(mapper, "mapper is null");
2709 return RxJavaPlugins.onAssembly(new SingleFlatMap<>(this, mapper));
2710 }
2711
2712 /**
2713 * Returns a {@link Completable} that completes based on applying a specified function to the item emitted by the
2714 * current {@code Single}, where that function returns a {@link CompletableSource}.
2715 * <p>
2716 * <img width="640" height="298" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.concatMapCompletable.png" alt="">
2717 * <p>
2718 * The operator is an alias for {@link #flatMapCompletable(Function)}.
2719 * <dl>
2720 * <dt><b>Scheduler:</b></dt>
2721 * <dd>{@code concatMapCompletable} does not operate by default on a particular {@link Scheduler}.</dd>
2722 * </dl>
2723 *
2724 * @param mapper
2725 * a function that, when applied to the item emitted by the current {@code Single}, returns a
2726 * {@code CompletableSource}
2727 * @return the new {@code Completable} instance
2728 * @throws NullPointerException if {@code mapper} is {@code null}
2729 * @see <a href="http://reactivex.io/documentation/operators/flatmap.html">ReactiveX operators documentation: FlatMap</a>
2730 * @since 3.0.0
2731 */
2732 @CheckReturnValue
2733 @NonNull
2734 @SchedulerSupport(SchedulerSupport.NONE)
2735 public final Completable concatMapCompletable(@NonNull Function<? super T, ? extends CompletableSource> mapper) {
2736 return flatMapCompletable(mapper);
2737 }
2738
2739 /**
2740 * Returns a {@link Maybe} that is based on applying a specified function to the item emitted by the current {@code Single},
2741 * where that function returns a {@link MaybeSource}.
2742 * <p>
2743 * <img width="640" height="254" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.concatMapMaybe.png" alt="">
2744 * <p>
2745 * The operator is an alias for {@link #flatMapMaybe(Function)}.
2746 * <dl>
2747 * <dt><b>Scheduler:</b></dt>
2748 * <dd>{@code concatMapMaybe} does not operate by default on a particular {@link Scheduler}.</dd>
2749 * </dl>
2750 *
2751 * @param <R> the result value type
2752 * @param mapper
2753 * a function that, when applied to the item emitted by the current {@code Single}, returns a {@code MaybeSource}
2754 * @return the new {@code Maybe} returned from {@code mapper} when applied to the item emitted by the current {@code Single}
2755 * @throws NullPointerException if {@code mapper} is {@code null}
2756 * @see <a href="http://reactivex.io/documentation/operators/flatmap.html">ReactiveX operators documentation: FlatMap</a>
2757 * @since 3.0.0
2758 */
2759 @CheckReturnValue
2760 @NonNull
2761 @SchedulerSupport(SchedulerSupport.NONE)
2762 public final <@NonNull R> Maybe<R> concatMapMaybe(@NonNull Function<? super T, ? extends MaybeSource<? extends R>> mapper) {
2763 return flatMapMaybe(mapper);
2764 }
2765
2766 /**
2767 * Returns a {@link Flowable} that emits the item emitted by the current {@code Single}, then the item emitted by the
2768 * specified {@link SingleSource}.
2769 * <p>
2770 * <img width="640" height="335" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.concatWith.v3.png" alt="">
2771 * <dl>
2772 * <dt><b>Backpressure:</b></dt>
2773 * <dd>The returned {@code Flowable} honors the backpressure of the downstream consumer.</dd>
2774 * <dt><b>Scheduler:</b></dt>
2775 * <dd>{@code concatWith} does not operate by default on a particular {@link Scheduler}.</dd>
2776 * </dl>
2777 *
2778 * @param other
2779 * a {@code SingleSource} to be concatenated after the current
2780 * @return the new {@code Flowable} that emits the item emitted by the current {@code Single}, followed by the item emitted by
2781 * {@code other}
2782 * @throws NullPointerException if {@code other} is {@code null}
2783 * @see <a href="http://reactivex.io/documentation/operators/concat.html">ReactiveX operators documentation: Concat</a>
2784 */
2785 @BackpressureSupport(BackpressureKind.FULL)
2786 @CheckReturnValue
2787 @SchedulerSupport(SchedulerSupport.NONE)
2788 @NonNull
2789 public final Flowable<T> concatWith(@NonNull SingleSource<? extends T> other) {
2790 return concat(this, other);
2791 }
2792
2793 /**
2794 * Delays the emission of the success signal from the current {@code Single} by the specified amount.
2795 * An error signal will not be delayed.
2796 * <p>
2797 * <img width="640" height="457" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.delay.v3.png" alt="">
2798 * <dl>
2799 * <dt><b>Scheduler:</b></dt>
2800 * <dd>{@code delay} operates by default on the {@code computation} {@link Scheduler}.</dd>
2801 * </dl>
2802 *
2803 * @param time the amount of time the success signal should be delayed for
2804 * @param unit the time unit
2805 * @return the new {@code Single} instance
2806 * @since 2.0
2807 * @throws NullPointerException if {@code unit} is {@code null}
2808 * @see #delay(long, TimeUnit, boolean)
2809 */
2810 @CheckReturnValue
2811 @SchedulerSupport(SchedulerSupport.COMPUTATION)
2812 @NonNull
2813 public final Single<T> delay(long time, @NonNull TimeUnit unit) {
2814 return delay(time, unit, Schedulers.computation(), false);
2815 }
2816
2817 /**
2818 * Delays the emission of the success or error signal from the current {@code Single} by the specified amount.
2819 * <p>
2820 * <img width="640" height="457" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.delay.e.v3.png" alt="">
2821 * <dl>
2822 * <dt><b>Scheduler:</b></dt>
2823 * <dd>{@code delay} operates by default on the {@code computation} {@link Scheduler}.</dd>
2824 * </dl>
2825 * <p>History: 2.1.5 - experimental
2826 * @param time the amount of time the success or error signal should be delayed for
2827 * @param unit the time unit
2828 * @param delayError if {@code true}, both success and error signals are delayed. if {@code false}, only success signals are delayed.
2829 * @return the new {@code Single} instance
2830 * @throws NullPointerException if {@code unit} is {@code null}
2831 * @since 2.2
2832 */
2833 @CheckReturnValue
2834 @SchedulerSupport(SchedulerSupport.COMPUTATION)
2835 @NonNull
2836 public final Single<T> delay(long time, @NonNull TimeUnit unit, boolean delayError) {
2837 return delay(time, unit, Schedulers.computation(), delayError);
2838 }
2839
2840 /**
2841 * Delays the emission of the success signal from the current {@code Single} by the specified amount.
2842 * An error signal will not be delayed.
2843 * <p>
2844 * <img width="640" height="457" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.delay.s.v3.png" alt="">
2845 * <dl>
2846 * <dt><b>Scheduler:</b></dt>
2847 * <dd>you specify the {@link Scheduler} where the non-blocking wait and emission happens</dd>
2848 * </dl>
2849 *
2850 * @param time the amount of time the success signal should be delayed for
2851 * @param unit the time unit
2852 * @param scheduler the target scheduler to use for the non-blocking wait and emission
2853 * @return the new {@code Single} instance
2854 * @throws NullPointerException
2855 * if {@code unit} is {@code null}, or
2856 * if {@code scheduler} is {@code null}
2857 * @since 2.0
2858 * @see #delay(long, TimeUnit, Scheduler, boolean)
2859 */
2860 @CheckReturnValue
2861 @SchedulerSupport(SchedulerSupport.CUSTOM)
2862 @NonNull
2863 public final Single<T> delay(long time, @NonNull TimeUnit unit, @NonNull Scheduler scheduler) {
2864 return delay(time, unit, scheduler, false);
2865 }
2866
2867 /**
2868 * Delays the emission of the success or error signal from the current {@code Single} by the specified amount.
2869 * <p>
2870 * <img width="640" height="457" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.delay.se.v3.png" alt="">
2871 * <dl>
2872 * <dt><b>Scheduler:</b></dt>
2873 * <dd>you specify the {@link Scheduler} where the non-blocking wait and emission happens</dd>
2874 * </dl>
2875 * <p>History: 2.1.5 - experimental
2876 * @param time the amount of time the success or error signal should be delayed for
2877 * @param unit the time unit
2878 * @param scheduler the target scheduler to use for the non-blocking wait and emission
2879 * @param delayError if {@code true}, both success and error signals are delayed. if {@code false}, only success signals are delayed.
2880 * @return the new {@code Single} instance
2881 * @throws NullPointerException
2882 * if {@code unit} is {@code null}, or
2883 * if {@code scheduler} is {@code null}
2884 * @since 2.2
2885 */
2886 @CheckReturnValue
2887 @NonNull
2888 @SchedulerSupport(SchedulerSupport.CUSTOM)
2889 public final Single<T> delay(long time, @NonNull TimeUnit unit, @NonNull Scheduler scheduler, boolean delayError) {
2890 Objects.requireNonNull(unit, "unit is null");
2891 Objects.requireNonNull(scheduler, "scheduler is null");
2892 return RxJavaPlugins.onAssembly(new SingleDelay<>(this, time, unit, scheduler, delayError));
2893 }
2894
2895 /**
2896 * Delays the actual subscription to the current {@code Single} until the given other {@link CompletableSource}
2897 * completes.
2898 * <p>
2899 * <img width="640" height="309" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.delaySubscription.c.png" alt="">
2900 * <p>If the delaying source signals an error, that error is re-emitted and no subscription
2901 * to the current {@code Single} happens.
2902 * <dl>
2903 * <dt><b>Scheduler:</b></dt>
2904 * <dd>{@code delaySubscription} does not operate by default on a particular {@link Scheduler}.</dd>
2905 * </dl>
2906 * @param subscriptionIndicator the {@code CompletableSource} that has to complete before the subscription to the
2907 * current {@code Single} happens
2908 * @return the new {@code Single} instance
2909 * @throws NullPointerException if {@code subscriptionIndicator} is {@code null}
2910 * @since 2.0
2911 */
2912 @CheckReturnValue
2913 @NonNull
2914 @SchedulerSupport(SchedulerSupport.NONE)
2915 public final Single<T> delaySubscription(@NonNull CompletableSource subscriptionIndicator) {
2916 Objects.requireNonNull(subscriptionIndicator, "subscriptionIndicator is null");
2917 return RxJavaPlugins.onAssembly(new SingleDelayWithCompletable<>(this, subscriptionIndicator));
2918 }
2919
2920 /**
2921 * Delays the actual subscription to the current {@code Single} until the given other {@link SingleSource}
2922 * signals success.
2923 * <p>
2924 * <img width="640" height="309" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.delaySubscription.s.png" alt="">
2925 * <p>If the delaying source signals an error, that error is re-emitted and no subscription
2926 * to the current {@code Single} happens.
2927 * <dl>
2928 * <dt><b>Scheduler:</b></dt>
2929 * <dd>{@code delaySubscription} does not operate by default on a particular {@link Scheduler}.</dd>
2930 * </dl>
2931 * @param <U> the element type of the other source
2932 * @param subscriptionIndicator the {@code SingleSource} that has to complete before the subscription to the
2933 * current {@code Single} happens
2934 * @return the new {@code Single} instance
2935 * @throws NullPointerException if {@code subscriptionIndicator} is {@code null}
2936 * @since 2.0
2937 */
2938 @CheckReturnValue
2939 @NonNull
2940 @SchedulerSupport(SchedulerSupport.NONE)
2941 public final <@NonNull U> Single<T> delaySubscription(@NonNull SingleSource<U> subscriptionIndicator) {
2942 Objects.requireNonNull(subscriptionIndicator, "subscriptionIndicator is null");
2943 return RxJavaPlugins.onAssembly(new SingleDelayWithSingle<>(this, subscriptionIndicator));
2944 }
2945
2946 /**
2947 * Delays the actual subscription to the current {@code Single} until the given other {@link ObservableSource}
2948 * signals its first value or completes.
2949 * <p>
2950 * <img width="640" height="214" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.delaySubscription.o.png" alt="">
2951 * <p>If the delaying source signals an error, that error is re-emitted and no subscription
2952 * to the current {@code Single} happens.
2953 * <dl>
2954 * <dt><b>Scheduler:</b></dt>
2955 * <dd>{@code delaySubscription} does not operate by default on a particular {@link Scheduler}.</dd>
2956 * </dl>
2957 * @param <U> the element type of the other source
2958 * @param subscriptionIndicator the {@code ObservableSource} that has to signal a value or complete before the
2959 * subscription to the current {@code Single} happens
2960 * @return the new {@code Single} instance
2961 * @throws NullPointerException if {@code subscriptionIndicator} is {@code null}
2962 * @since 2.0
2963 */
2964 @CheckReturnValue
2965 @NonNull
2966 @SchedulerSupport(SchedulerSupport.NONE)
2967 public final <@NonNull U> Single<T> delaySubscription(@NonNull ObservableSource<U> subscriptionIndicator) {
2968 Objects.requireNonNull(subscriptionIndicator, "subscriptionIndicator is null");
2969 return RxJavaPlugins.onAssembly(new SingleDelayWithObservable<>(this, subscriptionIndicator));
2970 }
2971
2972 /**
2973 * Delays the actual subscription to the current {@code Single} until the given other {@link Publisher}
2974 * signals its first value or completes.
2975 * <p>
2976 * <img width="640" height="214" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.delaySubscription.p.png" alt="">
2977 * <p>If the delaying source signals an error, that error is re-emitted and no subscription
2978 * to the current {@code Single} happens.
2979 * <p>The other source is consumed in an unbounded manner (requesting {@link Long#MAX_VALUE} from it).
2980 * <dl>
2981 * <dt><b>Backpressure:</b></dt>
2982 * <dd>The {@code other} publisher is consumed in an unbounded fashion but will be
2983 * cancelled after the first item it produced.</dd>
2984 * <dt><b>Scheduler:</b></dt>
2985 * <dd>{@code delaySubscription} does not operate by default on a particular {@link Scheduler}.</dd>
2986 * </dl>
2987 * @param <U> the element type of the other source
2988 * @param subscriptionIndicator the {@code Publisher} that has to signal a value or complete before the
2989 * subscription to the current {@code Single} happens
2990 * @return the new {@code Single} instance
2991 * @throws NullPointerException if {@code subscriptionIndicator} is {@code null}
2992 * @since 2.0
2993 */
2994 @BackpressureSupport(BackpressureKind.FULL)
2995 @CheckReturnValue
2996 @NonNull
2997 @SchedulerSupport(SchedulerSupport.NONE)
2998 public final <@NonNull U> Single<T> delaySubscription(@NonNull Publisher<U> subscriptionIndicator) {
2999 Objects.requireNonNull(subscriptionIndicator, "subscriptionIndicator is null");
3000 return RxJavaPlugins.onAssembly(new SingleDelayWithPublisher<>(this, subscriptionIndicator));
3001 }
3002
3003 /**
3004 * Delays the actual subscription to the current {@code Single} until the given time delay elapsed.
3005 * <p>
3006 * <img width="640" height="472" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.delaySubscription.t.png" alt="">
3007 * <dl>
3008 * <dt><b>Scheduler:</b></dt>
3009 * <dd>{@code delaySubscription} does by default subscribe to the current {@code Single}
3010 * on the {@code computation} {@link Scheduler} after the delay.</dd>
3011 * </dl>
3012 * @param time the time amount to wait with the subscription
3013 * @param unit the time unit of the waiting
3014 * @return the new {@code Single} instance
3015 * @throws NullPointerException if {@code unit} is {@code null}
3016 * @since 2.0
3017 */
3018 @CheckReturnValue
3019 @SchedulerSupport(SchedulerSupport.COMPUTATION)
3020 @NonNull
3021 public final Single<T> delaySubscription(long time, @NonNull TimeUnit unit) {
3022 return delaySubscription(time, unit, Schedulers.computation());
3023 }
3024
3025 /**
3026 * Delays the actual subscription to the current {@code Single} until the given time delay elapsed.
3027 * <p>
3028 * <img width="640" height="420" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.delaySubscription.ts.png" alt="">
3029 * <dl>
3030 * <dt><b>Scheduler:</b></dt>
3031 * <dd>{@code delaySubscription} does by default subscribe to the current {@code Single}
3032 * on the {@link Scheduler} you provided, after the delay.</dd>
3033 * </dl>
3034 * @param time the time amount to wait with the subscription
3035 * @param unit the time unit of the waiting
3036 * @param scheduler the {@code Scheduler} to wait on and subscribe on to the current {@code Single}
3037 * @return the new {@code Single} instance
3038 * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null}
3039 * @since 2.0
3040 */
3041 @CheckReturnValue
3042 @SchedulerSupport(SchedulerSupport.CUSTOM)
3043 @NonNull
3044 public final Single<T> delaySubscription(long time, @NonNull TimeUnit unit, @NonNull Scheduler scheduler) {
3045 return delaySubscription(Observable.timer(time, unit, scheduler));
3046 }
3047
3048 /**
3049 * Maps the {@link Notification} success value of the current {@code Single} back into normal
3050 * {@code onSuccess}, {@code onError} or {@code onComplete} signals as a
3051 * {@link Maybe} source.
3052 * <p>
3053 * <img width="640" height="341" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.dematerialize.png" alt="">
3054 * <p>
3055 * The intended use of the {@code selector} function is to perform a
3056 * type-safe identity mapping (see example) on a source that is already of type
3057 * {@code Notification<T>}. The Java language doesn't allow
3058 * limiting instance methods to a certain generic argument shape, therefore,
3059 * a function is used to ensure the conversion remains type safe.
3060 * <dl>
3061 * <dt><b>Scheduler:</b></dt>
3062 * <dd>{@code dematerialize} does not operate by default on a particular {@link Scheduler}.</dd>
3063 * </dl>
3064 * <p>
3065 * Example:
3066 * <pre><code>
3067 * Single.just(Notification.createOnNext(1))
3068 * .dematerialize(notification -&gt; notification)
3069 * .test()
3070 * .assertResult(1);
3071 * </code></pre>
3072 * <p>History: 2.2.4 - experimental
3073 * @param <R> the result type
3074 * @param selector the function called with the success item and should
3075 * return a {@code Notification} instance.
3076 * @return the new {@code Maybe} instance
3077 * @throws NullPointerException if {@code selector} is {@code null}
3078 * @since 3.0.0
3079 * @see #materialize()
3080 */
3081 @CheckReturnValue
3082 @NonNull
3083 @SchedulerSupport(SchedulerSupport.NONE)
3084 public final <@NonNull R> Maybe<R> dematerialize(@NonNull Function<? super T, @NonNull Notification<R>> selector) {
3085 Objects.requireNonNull(selector, "selector is null");
3086 return RxJavaPlugins.onAssembly(new SingleDematerialize<>(this, selector));
3087 }
3088
3089 /**
3090 * Calls the specified consumer with the success item after this item has been emitted to the downstream.
3091 * <p>
3092 * <img width="640" height="461" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.doAfterSuccess.v3.png" alt="">
3093 * <p>
3094 * Note that the {@code doAfterSuccess} action is shared between subscriptions and as such
3095 * should be thread-safe.
3096 * <dl>
3097 * <dt><b>Scheduler:</b></dt>
3098 * <dd>{@code doAfterSuccess} does not operate by default on a particular {@link Scheduler}.</dd>
3099 * </dl>
3100 * <p>History: 2.0.1 - experimental
3101 * @param onAfterSuccess the {@link Consumer} that will be called after emitting an item from upstream to the downstream
3102 * @return the new {@code Single} instance
3103 * @throws NullPointerException if {@code onAfterSuccess} is {@code null}
3104 * @since 2.1
3105 */
3106 @CheckReturnValue
3107 @NonNull
3108 @SchedulerSupport(SchedulerSupport.NONE)
3109 public final Single<T> doAfterSuccess(@NonNull Consumer<? super T> onAfterSuccess) {
3110 Objects.requireNonNull(onAfterSuccess, "onAfterSuccess is null");
3111 return RxJavaPlugins.onAssembly(new SingleDoAfterSuccess<>(this, onAfterSuccess));
3112 }
3113
3114 /**
3115 * Registers an {@link Action} to be called after this {@code Single} invokes either {@code onSuccess} or {@code onError}.
3116 * <p>
3117 * <img width="640" height="461" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.doAfterTerminate.v3.png" alt="">
3118 * <p>
3119 * Note that the {@code doAfterTerminate} action is shared between subscriptions and as such
3120 * should be thread-safe.</p>
3121 *
3122 * <dl>
3123 * <dt><b>Scheduler:</b></dt>
3124 * <dd>{@code doAfterTerminate} does not operate by default on a particular {@link Scheduler}.</dd>
3125 * </dl>
3126 *
3127 * <p>History: 2.0.6 - experimental
3128 * @param onAfterTerminate
3129 * an {@code Action} to be invoked when the current {@code Single} finishes
3130 * @return the new {@code Single} that emits the same items as the current {@code Single}, then invokes the
3131 * {@code Action}
3132 * @throws NullPointerException if {@code onAfterTerminate} is {@code null}
3133 * @see <a href="http://reactivex.io/documentation/operators/do.html">ReactiveX operators documentation: Do</a>
3134 * @since 2.1
3135 */
3136 @CheckReturnValue
3137 @NonNull
3138 @SchedulerSupport(SchedulerSupport.NONE)
3139 public final Single<T> doAfterTerminate(@NonNull Action onAfterTerminate) {
3140 Objects.requireNonNull(onAfterTerminate, "onAfterTerminate is null");
3141 return RxJavaPlugins.onAssembly(new SingleDoAfterTerminate<>(this, onAfterTerminate));
3142 }
3143
3144 /**
3145 * Calls the specified action after this {@code Single} signals {@code onSuccess} or {@code onError} or gets disposed by
3146 * the downstream.
3147 * <p>In case of a race between a terminal event and a dispose call, the provided {@code onFinally} action
3148 * is executed once per subscription.
3149 * <p>Note that the {@code onFinally} action is shared between subscriptions and as such
3150 * should be thread-safe.
3151 * <p>
3152 * <img width="640" height="291" src="https://raw.githubusercontent.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.doFinally.v3.png" alt="">
3153 * </p>
3154 * <dl>
3155 * <dt><b>Scheduler:</b></dt>
3156 * <dd>{@code doFinally} does not operate by default on a particular {@link Scheduler}.</dd>
3157 * </dl>
3158 * <p>History: 2.0.1 - experimental
3159 * @param onFinally the action called when this {@code Single} terminates or gets disposed
3160 * @return the new {@code Single} instance
3161 * @throws NullPointerException if {@code onFinally} is {@code null}
3162 * @since 2.1
3163 */
3164 @CheckReturnValue
3165 @NonNull
3166 @SchedulerSupport(SchedulerSupport.NONE)
3167 public final Single<T> doFinally(@NonNull Action onFinally) {
3168 Objects.requireNonNull(onFinally, "onFinally is null");
3169 return RxJavaPlugins.onAssembly(new SingleDoFinally<>(this, onFinally));
3170 }
3171
3172 /**
3173 * Calls the appropriate {@code onXXX} method (shared between all {@link SingleObserver}s) for the lifecycle events of
3174 * the sequence (subscription, disposal).
3175 * <p>
3176 * <img width="640" height="232" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.doOnLifecycle.png" alt="">
3177 * <dl>
3178 * <dt><b>Scheduler:</b></dt>
3179 * <dd>{@code doOnLifecycle} does not operate by default on a particular {@link Scheduler}.</dd>
3180 * </dl>
3181 *
3182 * @param onSubscribe
3183 * a {@link Consumer} called with the {@link Disposable} sent via {@link SingleObserver#onSubscribe(Disposable)}
3184 * @param onDispose
3185 * called when the downstream disposes the {@code Disposable} via {@code dispose()}
3186 * @return the new {@code Single} instance
3187 * @throws NullPointerException if {@code onSubscribe} or {@code onDispose} is {@code null}
3188 * @see <a href="http://reactivex.io/documentation/operators/do.html">ReactiveX operators documentation: Do</a>
3189 * @since 3.0.0
3190 */
3191 @CheckReturnValue
3192 @SchedulerSupport(SchedulerSupport.NONE)
3193 @NonNull
3194 public final Single<T> doOnLifecycle(@NonNull Consumer<? super Disposable> onSubscribe, @NonNull Action onDispose) {
3195 Objects.requireNonNull(onSubscribe, "onSubscribe is null");
3196 Objects.requireNonNull(onDispose, "onDispose is null");
3197 return RxJavaPlugins.onAssembly(new SingleDoOnLifecycle<>(this, onSubscribe, onDispose));
3198 }
3199
3200 /**
3201 * Calls the shared consumer with the {@link Disposable} sent through the {@code onSubscribe} for each
3202 * {@link SingleObserver} that subscribes to the current {@code Single}.
3203 * <p>
3204 * <img width="640" height="347" src="https://raw.githubusercontent.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.doOnSubscribe.v3.png" alt="">
3205 * </p>
3206 * <dl>
3207 * <dt><b>Scheduler:</b></dt>
3208 * <dd>{@code doOnSubscribe} does not operate by default on a particular {@link Scheduler}.</dd>
3209 * </dl>
3210 * @param onSubscribe the consumer called with the {@code Disposable} sent via {@code onSubscribe}
3211 * @return the new {@code Single} instance
3212 * @throws NullPointerException if {@code onSubscribe} is {@code null}
3213 * @since 2.0
3214 */
3215 @CheckReturnValue
3216 @NonNull
3217 @SchedulerSupport(SchedulerSupport.NONE)
3218 public final Single<T> doOnSubscribe(@NonNull Consumer<? super Disposable> onSubscribe) {
3219 Objects.requireNonNull(onSubscribe, "onSubscribe is null");
3220 return RxJavaPlugins.onAssembly(new SingleDoOnSubscribe<>(this, onSubscribe));
3221 }
3222
3223 /**
3224 * Returns a {@code Single} instance that calls the given {@code onTerminate} callback
3225 * just before this {@code Single} completes normally or with an exception.
3226 * <p>
3227 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/doOnTerminate.v3.png" alt="">
3228 * <p>
3229 * This differs from {@code doAfterTerminate} in that this happens <em>before</em> the {@code onSuccess} or
3230 * {@code onError} notification.
3231 * <dl>
3232 * <dt><b>Scheduler:</b></dt>
3233 * <dd>{@code doOnTerminate} does not operate by default on a particular {@link Scheduler}.</dd>
3234 * </dl>
3235 * <p>History: 2.2.7 - experimental
3236 * @param onTerminate the action to invoke when the consumer calls {@code onSuccess} or {@code onError}
3237 * @return the new {@code Single} instance
3238 * @throws NullPointerException if {@code onTerminate} is {@code null}
3239 * @see <a href="http://reactivex.io/documentation/operators/do.html">ReactiveX operators documentation: Do</a>
3240 * @see #doOnTerminate(Action)
3241 * @since 3.0.0
3242 */
3243 @CheckReturnValue
3244 @NonNull
3245 @SchedulerSupport(SchedulerSupport.NONE)
3246 public final Single<T> doOnTerminate(@NonNull Action onTerminate) {
3247 Objects.requireNonNull(onTerminate, "onTerminate is null");
3248 return RxJavaPlugins.onAssembly(new SingleDoOnTerminate<>(this, onTerminate));
3249 }
3250
3251 /**
3252 * Calls the shared consumer with the success value sent via {@code onSuccess} for each
3253 * {@link SingleObserver} that subscribes to the current {@code Single}.
3254 * <p>
3255 * <img width="640" height="347" src="https://raw.githubusercontent.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.doOnSuccess.2.v3.png" alt="">
3256 * </p>
3257 * <dl>
3258 * <dt><b>Scheduler:</b></dt>
3259 * <dd>{@code doOnSuccess} does not operate by default on a particular {@link Scheduler}.</dd>
3260 * </dl>
3261 * @param onSuccess the consumer called with the success value of {@code onSuccess}
3262 * @return the new {@code Single} instance
3263 * @throws NullPointerException if {@code onSuccess} is {@code null}
3264 * @since 2.0
3265 */
3266 @CheckReturnValue
3267 @NonNull
3268 @SchedulerSupport(SchedulerSupport.NONE)
3269 public final Single<T> doOnSuccess(@NonNull Consumer<? super T> onSuccess) {
3270 Objects.requireNonNull(onSuccess, "onSuccess is null");
3271 return RxJavaPlugins.onAssembly(new SingleDoOnSuccess<>(this, onSuccess));
3272 }
3273
3274 /**
3275 * Calls the shared consumer with the error sent via {@code onError} or the value
3276 * via {@code onSuccess} for each {@link SingleObserver} that subscribes to the current {@code Single}.
3277 * <p>
3278 * <img width="640" height="264" src="https://raw.githubusercontent.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.doOnEvent.png" alt="">
3279 * <dl>
3280 * <dt><b>Scheduler:</b></dt>
3281 * <dd>{@code doOnEvent} does not operate by default on a particular {@link Scheduler}.</dd>
3282 * </dl>
3283 * @param onEvent the consumer called with the success value of onEvent
3284 * @return the new {@code Single} instance
3285 * @throws NullPointerException if {@code onEvent} is {@code null}
3286 * @since 2.0
3287 */
3288 @CheckReturnValue
3289 @NonNull
3290 @SchedulerSupport(SchedulerSupport.NONE)
3291 public final Single<T> doOnEvent(@NonNull BiConsumer<@Nullable ? super T, @Nullable ? super Throwable> onEvent) {
3292 Objects.requireNonNull(onEvent, "onEvent is null");
3293 return RxJavaPlugins.onAssembly(new SingleDoOnEvent<>(this, onEvent));
3294 }
3295
3296 /**
3297 * Calls the shared consumer with the error sent via {@code onError} for each
3298 * {@link SingleObserver} that subscribes to the current {@code Single}.
3299 * <p>
3300 * <img width="640" height="349" src="https://raw.githubusercontent.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.doOnError.2.v3.png" alt="">
3301 * </p>
3302 * <dl>
3303 * <dt><b>Scheduler:</b></dt>
3304 * <dd>{@code doOnError} does not operate by default on a particular {@link Scheduler}.</dd>
3305 * </dl>
3306 * @param onError the consumer called with the success value of {@code onError}
3307 * @return the new {@code Single} instance
3308 * @throws NullPointerException if {@code onError} is {@code null}
3309 * @since 2.0
3310 */
3311 @CheckReturnValue
3312 @NonNull
3313 @SchedulerSupport(SchedulerSupport.NONE)
3314 public final Single<T> doOnError(@NonNull Consumer<? super Throwable> onError) {
3315 Objects.requireNonNull(onError, "onError is null");
3316 return RxJavaPlugins.onAssembly(new SingleDoOnError<>(this, onError));
3317 }
3318
3319 /**
3320 * Calls the shared {@link Action} if a {@link SingleObserver} subscribed to the current {@code Single}
3321 * disposes the common {@link Disposable} it received via {@code onSubscribe}.
3322 * <p>
3323 * <img width="640" height="332" src="https://raw.githubusercontent.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.doOnDispose.v3.png" alt="">
3324 * </p>
3325 * <dl>
3326 * <dt><b>Scheduler:</b></dt>
3327 * <dd>{@code doOnDispose} does not operate by default on a particular {@link Scheduler}.</dd>
3328 * </dl>
3329 * @param onDispose the action called when the subscription is disposed
3330 * @return the new {@code Single} instance
3331 * @throws NullPointerException if {@code onDispose} is {@code null}
3332 * @since 2.0
3333 */
3334 @CheckReturnValue
3335 @NonNull
3336 @SchedulerSupport(SchedulerSupport.NONE)
3337 public final Single<T> doOnDispose(@NonNull Action onDispose) {
3338 Objects.requireNonNull(onDispose, "onDispose is null");
3339 return RxJavaPlugins.onAssembly(new SingleDoOnDispose<>(this, onDispose));
3340 }
3341
3342 /**
3343 * Filters the success item of the {@code Single} via a predicate function and emitting it if the predicate
3344 * returns {@code true}, completing otherwise.
3345 * <p>
3346 * <img width="640" height="457" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.filter.v3.png" alt="">
3347 * <dl>
3348 * <dt><b>Scheduler:</b></dt>
3349 * <dd>{@code filter} does not operate by default on a particular {@link Scheduler}.</dd>
3350 * </dl>
3351 *
3352 * @param predicate
3353 * a function that evaluates the item emitted by the current {@code Single}, returning {@code true}
3354 * if it passes the filter
3355 * @return the new {@link Maybe} that emit the item emitted by the current {@code Single} that the filter
3356 * evaluates as {@code true}
3357 * @throws NullPointerException if {@code predicate} is {@code null}
3358 * @see <a href="http://reactivex.io/documentation/operators/filter.html">ReactiveX operators documentation: Filter</a>
3359 */
3360 @CheckReturnValue
3361 @NonNull
3362 @SchedulerSupport(SchedulerSupport.NONE)
3363 public final Maybe<T> filter(@NonNull Predicate<? super T> predicate) {
3364 Objects.requireNonNull(predicate, "predicate is null");
3365 return RxJavaPlugins.onAssembly(new MaybeFilterSingle<>(this, predicate));
3366 }
3367
3368 /**
3369 * Returns a {@code Single} that is based on applying a specified function to the item emitted by the current {@code Single},
3370 * where that function returns a {@link SingleSource}.
3371 * <p>
3372 * <img width="640" height="300" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.flatMap.v3.png" alt="">
3373 * <dl>
3374 * <dt><b>Scheduler:</b></dt>
3375 * <dd>{@code flatMap} does not operate by default on a particular {@link Scheduler}.</dd>
3376 * </dl>
3377 *
3378 * @param <R> the result value type
3379 * @param mapper
3380 * a function that, when applied to the item emitted by the current {@code Single}, returns a {@code SingleSource}
3381 * @return the new {@code Single} returned from {@code mapper} when applied to the item emitted by the current {@code Single}
3382 * @throws NullPointerException if {@code mapper} is {@code null}
3383 * @see <a href="http://reactivex.io/documentation/operators/flatmap.html">ReactiveX operators documentation: FlatMap</a>
3384 */
3385 @CheckReturnValue
3386 @NonNull
3387 @SchedulerSupport(SchedulerSupport.NONE)
3388 public final <@NonNull R> Single<R> flatMap(@NonNull Function<? super T, ? extends SingleSource<? extends R>> mapper) {
3389 Objects.requireNonNull(mapper, "mapper is null");
3390 return RxJavaPlugins.onAssembly(new SingleFlatMap<>(this, mapper));
3391 }
3392
3393 /**
3394 * Returns a {@code Single} that emits the results of a specified function to the pair of values emitted by the
3395 * current {@code Single} and a specified mapped {@link SingleSource}.
3396 * <p>
3397 * <img width="640" height="268" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.flatMap.combiner.png" alt="">
3398 * <dl>
3399 * <dt><b>Scheduler:</b></dt>
3400 * <dd>{@code flatMap} does not operate by default on a particular {@link Scheduler}.</dd>
3401 * </dl>
3402 *
3403 * @param <U>
3404 * the type of items emitted by the {@code SingleSource} returned by the {@code mapper} function
3405 * @param <R>
3406 * the type of items emitted by the resulting {@code Single}
3407 * @param mapper
3408 * a function that returns a {@code SingleSource} for the item emitted by the current {@code Single}
3409 * @param combiner
3410 * a function that combines one item emitted by each of the source and collection {@code SingleSource} and
3411 * returns an item to be emitted by the resulting {@code SingleSource}
3412 * @return the new {@code Single} instance
3413 * @throws NullPointerException if {@code mapper} or {@code combiner} is {@code null}
3414 * @see <a href="http://reactivex.io/documentation/operators/flatmap.html">ReactiveX operators documentation: FlatMap</a>
3415 * @since 3.0.0
3416 */
3417 @CheckReturnValue
3418 @NonNull
3419 @SchedulerSupport(SchedulerSupport.NONE)
3420 public final <@NonNull U, @NonNull R> Single<R> flatMap(@NonNull Function<? super T, ? extends SingleSource<? extends U>> mapper,
3421 @NonNull BiFunction<? super T, ? super U, ? extends R> combiner) {
3422 Objects.requireNonNull(mapper, "mapper is null");
3423 Objects.requireNonNull(combiner, "combiner is null");
3424 return RxJavaPlugins.onAssembly(new SingleFlatMapBiSelector<>(this, mapper, combiner));
3425 }
3426
3427 /**
3428 * Maps the {@code onSuccess} or {@code onError} signals of the current {@code Single} into a {@link SingleSource} and emits that
3429 * {@code SingleSource}'s signals.
3430 * <p>
3431 * <img width="640" height="449" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.flatMap.notification.png" alt="">
3432 * <dl>
3433 * <dt><b>Scheduler:</b></dt>
3434 * <dd>{@code flatMap} does not operate by default on a particular {@link Scheduler}.</dd>
3435 * </dl>
3436 *
3437 * @param <R>
3438 * the result type
3439 * @param onSuccessMapper
3440 * a function that returns a {@code SingleSource} to merge for the {@code onSuccess} item emitted by this {@code Single}
3441 * @param onErrorMapper
3442 * a function that returns a {@code SingleSource} to merge for an {@code onError} notification from this {@code Single}
3443 * @return the new {@code Single} instance
3444 * @throws NullPointerException if {@code onSuccessMapper} or {@code onErrorMapper} is {@code null}
3445 * @see <a href="http://reactivex.io/documentation/operators/flatmap.html">ReactiveX operators documentation: FlatMap</a>
3446 * @since 3.0.0
3447 */
3448 @CheckReturnValue
3449 @NonNull
3450 @SchedulerSupport(SchedulerSupport.NONE)
3451 public final <@NonNull R> Single<R> flatMap(
3452 @NonNull Function<? super T, ? extends SingleSource<? extends R>> onSuccessMapper,
3453 @NonNull Function<? super Throwable, ? extends SingleSource<? extends R>> onErrorMapper) {
3454 Objects.requireNonNull(onSuccessMapper, "onSuccessMapper is null");
3455 Objects.requireNonNull(onErrorMapper, "onErrorMapper is null");
3456 return RxJavaPlugins.onAssembly(new SingleFlatMapNotification<>(this, onSuccessMapper, onErrorMapper));
3457 }
3458
3459 /**
3460 * Returns a {@link Maybe} that is based on applying a specified function to the item emitted by the current {@code Single},
3461 * where that function returns a {@link MaybeSource}.
3462 * <p>
3463 * <img width="640" height="191" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.flatMapMaybe.png" alt="">
3464 * <dl>
3465 * <dt><b>Scheduler:</b></dt>
3466 * <dd>{@code flatMapMaybe} does not operate by default on a particular {@link Scheduler}.</dd>
3467 * </dl>
3468 *
3469 * @param <R> the result value type
3470 * @param mapper
3471 * a function that, when applied to the item emitted by the current {@code Single}, returns a {@code MaybeSource}
3472 * @return the new {@code Maybe} returned from {@code mapper} when applied to the item emitted by the current {@code Single}
3473 * @throws NullPointerException if {@code mapper} is {@code null}
3474 * @see <a href="http://reactivex.io/documentation/operators/flatmap.html">ReactiveX operators documentation: FlatMap</a>
3475 */
3476 @CheckReturnValue
3477 @NonNull
3478 @SchedulerSupport(SchedulerSupport.NONE)
3479 public final <@NonNull R> Maybe<R> flatMapMaybe(@NonNull Function<? super T, ? extends MaybeSource<? extends R>> mapper) {
3480 Objects.requireNonNull(mapper, "mapper is null");
3481 return RxJavaPlugins.onAssembly(new SingleFlatMapMaybe<>(this, mapper));
3482 }
3483
3484 /**
3485 * Returns a {@link Flowable} that emits items based on applying a specified function to the item emitted by the
3486 * current {@code Single}, where that function returns a {@link Publisher}.
3487 * <p>
3488 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.flatMapPublisher.v3.png" alt="">
3489 * <dl>
3490 * <dt><b>Backpressure:</b></dt>
3491 * <dd>The returned {@code Flowable} honors the backpressure of the downstream consumer
3492 * and the {@code Publisher} returned by the mapper function is expected to honor it as well.</dd>
3493 * <dt><b>Scheduler:</b></dt>
3494 * <dd>{@code flatMapPublisher} does not operate by default on a particular {@link Scheduler}.</dd>
3495 * </dl>
3496 *
3497 * @param <R> the result value type
3498 * @param mapper
3499 * a function that, when applied to the item emitted by the current {@code Single}, returns a
3500 * {@code Publisher}
3501 * @return the new {@code Flowable} instance
3502 * @throws NullPointerException if {@code mapper} is {@code null}
3503 * @see <a href="http://reactivex.io/documentation/operators/flatmap.html">ReactiveX operators documentation: FlatMap</a>
3504 */
3505 @BackpressureSupport(BackpressureKind.FULL)
3506 @CheckReturnValue
3507 @NonNull
3508 @SchedulerSupport(SchedulerSupport.NONE)
3509 public final <@NonNull R> Flowable<R> flatMapPublisher(@NonNull Function<? super T, @NonNull ? extends Publisher<? extends R>> mapper) {
3510 Objects.requireNonNull(mapper, "mapper is null");
3511 return RxJavaPlugins.onAssembly(new SingleFlatMapPublisher<>(this, mapper));
3512 }
3513
3514 /**
3515 * Maps the success value of the current {@code Single} into an {@link Iterable} and emits its items as a
3516 * {@link Flowable} sequence.
3517 * <p>
3518 * <img width="640" height="373" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/flattenAsFlowable.png" alt="">
3519 * <dl>
3520 * <dt><b>Backpressure:</b></dt>
3521 * <dd>The operator honors backpressure from downstream.</dd>
3522 * <dt><b>Scheduler:</b></dt>
3523 * <dd>{@code flattenAsFlowable} does not operate by default on a particular {@link Scheduler}.</dd>
3524 * </dl>
3525 *
3526 * @param <U>
3527 * the type of item emitted by the resulting {@code Iterable}
3528 * @param mapper
3529 * a function that returns an {@code Iterable} sequence of values for when given an item emitted by the
3530 * current {@code Single}
3531 * @return the new {@code Flowable} instance
3532 * @throws NullPointerException if {@code mapper} is {@code null}
3533 * @see <a href="http://reactivex.io/documentation/operators/flatmap.html">ReactiveX operators documentation: FlatMap</a>
3534 * @see #flattenStreamAsFlowable(Function)
3535 */
3536 @BackpressureSupport(BackpressureKind.FULL)
3537 @CheckReturnValue
3538 @NonNull
3539 @SchedulerSupport(SchedulerSupport.NONE)
3540 public final <@NonNull U> Flowable<U> flattenAsFlowable(@NonNull Function<? super T, @NonNull ? extends Iterable<? extends U>> mapper) {
3541 Objects.requireNonNull(mapper, "mapper is null");
3542 return RxJavaPlugins.onAssembly(new SingleFlatMapIterableFlowable<>(this, mapper));
3543 }
3544
3545 /**
3546 * Maps the success value of the current {@code Single} into an {@link Iterable} and emits its items as an
3547 * {@link Observable} sequence.
3548 * <p>
3549 * <img width="640" height="373" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/flattenAsObservable.png" alt="">
3550 * <dl>
3551 * <dt><b>Scheduler:</b></dt>
3552 * <dd>{@code flattenAsObservable} does not operate by default on a particular {@link Scheduler}.</dd>
3553 * </dl>
3554 *
3555 * @param <U>
3556 * the type of item emitted by the resulting {@code Iterable}
3557 * @param mapper
3558 * a function that returns an {@code Iterable} sequence of values for when given an item emitted by the
3559 * current {@code Single}
3560 * @return the new {@code Observable} instance
3561 * @throws NullPointerException if {@code mapper} is {@code null}
3562 * @see <a href="http://reactivex.io/documentation/operators/flatmap.html">ReactiveX operators documentation: FlatMap</a>
3563 * @see #flattenStreamAsObservable(Function)
3564 */
3565 @CheckReturnValue
3566 @NonNull
3567 @SchedulerSupport(SchedulerSupport.NONE)
3568 public final <@NonNull U> Observable<U> flattenAsObservable(@NonNull Function<@NonNull ? super T, @NonNull ? extends Iterable<? extends U>> mapper) {
3569 Objects.requireNonNull(mapper, "mapper is null");
3570 return RxJavaPlugins.onAssembly(new SingleFlatMapIterableObservable<>(this, mapper));
3571 }
3572
3573 /**
3574 * Returns an {@link Observable} that is based on applying a specified function to the item emitted by the current {@code Single},
3575 * where that function returns an {@link ObservableSource}.
3576 * <p>
3577 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.flatMapObservable.v3.png" alt="">
3578 * <dl>
3579 * <dt><b>Scheduler:</b></dt>
3580 * <dd>{@code flatMapObservable} does not operate by default on a particular {@link Scheduler}.</dd>
3581 * </dl>
3582 *
3583 * @param <R> the result value type
3584 * @param mapper
3585 * a function that, when applied to the item emitted by the current {@code Single}, returns an {@code ObservableSource}
3586 * @return the new {@code Observable} instance
3587 * @throws NullPointerException if {@code mapper} is {@code null}
3588 * @see <a href="http://reactivex.io/documentation/operators/flatmap.html">ReactiveX operators documentation: FlatMap</a>
3589 */
3590 @CheckReturnValue
3591 @NonNull
3592 @SchedulerSupport(SchedulerSupport.NONE)
3593 public final <@NonNull R> Observable<R> flatMapObservable(@NonNull Function<? super T, ? extends ObservableSource<? extends R>> mapper) {
3594 Objects.requireNonNull(mapper, "mapper is null");
3595 return RxJavaPlugins.onAssembly(new SingleFlatMapObservable<>(this, mapper));
3596 }
3597
3598 /**
3599 * Returns a {@link Completable} that completes based on applying a specified function to the item emitted by the
3600 * current {@code Single}, where that function returns a {@link CompletableSource}.
3601 * <p>
3602 * <img width="640" height="267" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.flatMapCompletable.png" alt="">
3603 * <dl>
3604 * <dt><b>Scheduler:</b></dt>
3605 * <dd>{@code flatMapCompletable} does not operate by default on a particular {@link Scheduler}.</dd>
3606 * </dl>
3607 *
3608 * @param mapper
3609 * a function that, when applied to the item emitted by the current {@code Single}, returns a
3610 * {@code CompletableSource}
3611 * @return the new {@code Completable} instance
3612 * @throws NullPointerException if {@code mapper} is {@code null}
3613 * @see <a href="http://reactivex.io/documentation/operators/flatmap.html">ReactiveX operators documentation: FlatMap</a>
3614 * @since 2.0
3615 */
3616 @CheckReturnValue
3617 @NonNull
3618 @SchedulerSupport(SchedulerSupport.NONE)
3619 public final Completable flatMapCompletable(@NonNull Function<? super T, ? extends CompletableSource> mapper) {
3620 Objects.requireNonNull(mapper, "mapper is null");
3621 return RxJavaPlugins.onAssembly(new SingleFlatMapCompletable<>(this, mapper));
3622 }
3623
3624 /**
3625 * Waits in a blocking fashion until the current {@code Single} signals a success value (which is returned) or
3626 * an exception (which is propagated).
3627 * <p>
3628 * <img width="640" height="429" src="https://raw.githubusercontent.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.blockingGet.png" alt="">
3629 * <dl>
3630 * <dt><b>Scheduler:</b></dt>
3631 * <dd>{@code blockingGet} does not operate by default on a particular {@link Scheduler}.</dd>
3632 * <dt><b>Error handling:</b></dt>
3633 * <dd>If the source signals an error, the operator wraps a checked {@link Exception}
3634 * into {@link RuntimeException} and throws that. Otherwise, {@code RuntimeException}s and
3635 * {@link Error}s are rethrown as they are.</dd>
3636 * </dl>
3637 * @return the success value
3638 */
3639 @CheckReturnValue
3640 @SchedulerSupport(SchedulerSupport.NONE)
3641 @NonNull
3642 public final T blockingGet() {
3643 BlockingMultiObserver<T> observer = new BlockingMultiObserver<>();
3644 subscribe(observer);
3645 return observer.blockingGet();
3646 }
3647
3648 /**
3649 * Subscribes to the current {@code Single} and <em>blocks the current thread</em> until it terminates.
3650 * <p>
3651 * <img width="640" height="329" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.blockingSubscribe.png" alt="">
3652 * <dl>
3653 * <dt><b>Scheduler:</b></dt>
3654 * <dd>{@code blockingSubscribe} does not operate by default on a particular {@link Scheduler}.</dd>
3655 * <dt><b>Error handling:</b></dt>
3656 * <dd>If the current {@code Single} signals an error,
3657 * the {@link Throwable} is routed to the global error handler via {@link RxJavaPlugins#onError(Throwable)}.
3658 * If the current thread is interrupted, an {@link InterruptedException} is routed to the same global error handler.
3659 * </dd>
3660 * </dl>
3661 * @since 3.0.0
3662 * @see #blockingSubscribe(Consumer)
3663 * @see #blockingSubscribe(Consumer, Consumer)
3664 */
3665 @SchedulerSupport(SchedulerSupport.NONE)
3666 public final void blockingSubscribe() {
3667 blockingSubscribe(Functions.emptyConsumer(), Functions.ERROR_CONSUMER);
3668 }
3669
3670 /**
3671 * Subscribes to the current {@code Single} and calls given {@code onSuccess} callback on the <em>current thread</em>
3672 * when it completes normally.
3673 * <p>
3674 * <img width="640" height="351" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.blockingSubscribe.c.png" alt="">
3675 * <dl>
3676 * <dt><b>Scheduler:</b></dt>
3677 * <dd>{@code blockingSubscribe} does not operate by default on a particular {@link Scheduler}.</dd>
3678 * <dt><b>Error handling:</b></dt>
3679 * <dd>If either the current {@code Single} signals an error or {@code onSuccess} throws,
3680 * the respective {@link Throwable} is routed to the global error handler via {@link RxJavaPlugins#onError(Throwable)}.
3681 * If the current thread is interrupted, an {@link InterruptedException} is routed to the same global error handler.
3682 * </dd>
3683 * </dl>
3684 * @param onSuccess the {@link Consumer} to call if the current {@code Single} succeeds
3685 * @throws NullPointerException if {@code onSuccess} is {@code null}
3686 * @since 3.0.0
3687 * @see #blockingSubscribe(Consumer, Consumer)
3688 */
3689 @SchedulerSupport(SchedulerSupport.NONE)
3690 public final void blockingSubscribe(@NonNull Consumer<? super T> onSuccess) {
3691 blockingSubscribe(onSuccess, Functions.ERROR_CONSUMER);
3692 }
3693
3694 /**
3695 * Subscribes to the current {@code Single} and calls the appropriate callback on the <em>current thread</em>
3696 * when it terminates.
3697 * <p>
3698 * <img width="640" height="348" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.blockingSubscribe.cc.png" alt="">
3699 * <dl>
3700 * <dt><b>Scheduler:</b></dt>
3701 * <dd>{@code blockingSubscribe} does not operate by default on a particular {@link Scheduler}.</dd>
3702 * <dt><b>Error handling:</b></dt>
3703 * <dd>If either {@code onSuccess} or {@code onError} throw, the {@link Throwable} is routed to the
3704 * global error handler via {@link RxJavaPlugins#onError(Throwable)}.
3705 * If the current thread is interrupted, the {@code onError} consumer is called with an {@link InterruptedException}.
3706 * </dd>
3707 * </dl>
3708 * @param onSuccess the {@link Consumer} to call if the current {@code Single} succeeds
3709 * @param onError the {@code Consumer} to call if the current {@code Single} signals an error
3710 * @throws NullPointerException if {@code onSuccess} or {@code onError} is {@code null}
3711 * @since 3.0.0
3712 */
3713 @SchedulerSupport(SchedulerSupport.NONE)
3714 public final void blockingSubscribe(@NonNull Consumer<? super T> onSuccess, @NonNull Consumer<? super Throwable> onError) {
3715 Objects.requireNonNull(onSuccess, "onSuccess is null");
3716 Objects.requireNonNull(onError, "onError is null");
3717 BlockingMultiObserver<T> observer = new BlockingMultiObserver<>();
3718 subscribe(observer);
3719 observer.blockingConsume(onSuccess, onError, Functions.EMPTY_ACTION);
3720 }
3721
3722 /**
3723 * Subscribes to the current {@code Single} and calls the appropriate {@link SingleObserver} method on the <em>current thread</em>.
3724 * <p>
3725 * <img width="640" height="479" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.blockingSubscribe.o.png" alt="">
3726 * <dl>
3727 * <dt><b>Scheduler:</b></dt>
3728 * <dd>{@code blockingSubscribe} does not operate by default on a particular {@link Scheduler}.</dd>
3729 * <dt><b>Error handling:</b></dt>
3730 * <dd>An {@code onError} signal is delivered to the {@link SingleObserver#onError(Throwable)} method.
3731 * If any of the {@code SingleObserver}'s methods throw, the {@link RuntimeException} is propagated to the caller of this method.
3732 * If the current thread is interrupted, an {@link InterruptedException} is delivered to {@code observer.onError}.
3733 * </dd>
3734 * </dl>
3735 * @param observer the {@code SingleObserver} to call methods on the current thread
3736 * @throws NullPointerException if {@code observer} is {@code null}
3737 * @since 3.0.0
3738 */
3739 @SchedulerSupport(SchedulerSupport.NONE)
3740 public final void blockingSubscribe(@NonNull SingleObserver<? super T> observer) {
3741 Objects.requireNonNull(observer, "observer is null");
3742 BlockingDisposableMultiObserver<T> blockingObserver = new BlockingDisposableMultiObserver<>();
3743 observer.onSubscribe(blockingObserver);
3744 subscribe(blockingObserver);
3745 blockingObserver.blockingConsume(observer);
3746 }
3747
3748 /**
3749 * <strong>This method requires advanced knowledge about building operators, please consider
3750 * other standard composition methods first;</strong>
3751 * Returns a {@code Single} which, when subscribed to, invokes the {@link SingleOperator#apply(SingleObserver) apply(SingleObserver)} method
3752 * of the provided {@link SingleOperator} for each individual downstream {@link Single} and allows the
3753 * insertion of a custom operator by accessing the downstream's {@link SingleObserver} during this subscription phase
3754 * and providing a new {@code SingleObserver}, containing the custom operator's intended business logic, that will be
3755 * used in the subscription process going further upstream.
3756 * <p>
3757 * <img width="640" height="304" src="https://raw.githubusercontent.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.lift.png" alt="">
3758 * <p>
3759 * Generally, such a new {@code SingleObserver} will wrap the downstream's {@code SingleObserver} and forwards the
3760 * {@code onSuccess} and {@code onError} events from the upstream directly or according to the
3761 * emission pattern the custom operator's business logic requires. In addition, such operator can intercept the
3762 * flow control calls of {@code dispose} and {@code isDisposed} that would have traveled upstream and perform
3763 * additional actions depending on the same business logic requirements.
3764 * <p>
3765 * Example:
3766 * <pre><code>
3767 * // Step 1: Create the consumer type that will be returned by the SingleOperator.apply():
3768 *
3769 * public final class CustomSingleObserver&lt;T&gt; implements SingleObserver&lt;T&gt;, Disposable {
3770 *
3771 * // The downstream's SingleObserver that will receive the onXXX events
3772 * final SingleObserver&lt;? super String&gt; downstream;
3773 *
3774 * // The connection to the upstream source that will call this class' onXXX methods
3775 * Disposable upstream;
3776 *
3777 * // The constructor takes the downstream subscriber and usually any other parameters
3778 * public CustomSingleObserver(SingleObserver&lt;? super String&gt; downstream) {
3779 * this.downstream = downstream;
3780 * }
3781 *
3782 * // In the subscription phase, the upstream sends a Disposable to this class
3783 * // and subsequently this class has to send a Disposable to the downstream.
3784 * // Note that relaying the upstream's Disposable directly is not allowed in RxJava
3785 * &#64;Override
3786 * public void onSubscribe(Disposable d) {
3787 * if (upstream != null) {
3788 * d.dispose();
3789 * } else {
3790 * upstream = d;
3791 * downstream.onSubscribe(this);
3792 * }
3793 * }
3794 *
3795 * // The upstream calls this with the next item and the implementation's
3796 * // responsibility is to emit an item to the downstream based on the intended
3797 * // business logic, or if it can't do so for the particular item,
3798 * // request more from the upstream
3799 * &#64;Override
3800 * public void onSuccess(T item) {
3801 * String str = item.toString();
3802 * if (str.length() &lt; 2) {
3803 * downstream.onSuccess(str);
3804 * } else {
3805 * // Single is usually expected to produce one of the onXXX events
3806 * downstream.onError(new NoSuchElementException());
3807 * }
3808 * }
3809 *
3810 * // Some operators may handle the upstream's error while others
3811 * // could just forward it to the downstream.
3812 * &#64;Override
3813 * public void onError(Throwable throwable) {
3814 * downstream.onError(throwable);
3815 * }
3816 *
3817 * // Some operators may use their own resources which should be cleaned up if
3818 * // the downstream disposes the flow before it completed. Operators without
3819 * // resources can simply forward the dispose to the upstream.
3820 * // In some cases, a disposed flag may be set by this method so that other parts
3821 * // of this class may detect the dispose and stop sending events
3822 * // to the downstream.
3823 * &#64;Override
3824 * public void dispose() {
3825 * upstream.dispose();
3826 * }
3827 *
3828 * // Some operators may simply forward the call to the upstream while others
3829 * // can return the disposed flag set in dispose().
3830 * &#64;Override
3831 * public boolean isDisposed() {
3832 * return upstream.isDisposed();
3833 * }
3834 * }
3835 *
3836 * // Step 2: Create a class that implements the SingleOperator interface and
3837 * // returns the custom consumer type from above in its apply() method.
3838 * // Such class may define additional parameters to be submitted to
3839 * // the custom consumer type.
3840 *
3841 * final class CustomSingleOperator&lt;T&gt; implements SingleOperator&lt;String&gt; {
3842 * &#64;Override
3843 * public SingleObserver&lt;? super String&gt; apply(SingleObserver&lt;? super T&gt; upstream) {
3844 * return new CustomSingleObserver&lt;T&gt;(upstream);
3845 * }
3846 * }
3847 *
3848 * // Step 3: Apply the custom operator via lift() in a flow by creating an instance of it
3849 * // or reusing an existing one.
3850 *
3851 * Single.just(5)
3852 * .lift(new CustomSingleOperator&lt;Integer&gt;())
3853 * .test()
3854 * .assertResult("5");
3855 *
3856 * Single.just(15)
3857 * .lift(new CustomSingleOperator&lt;Integer&gt;())
3858 * .test()
3859 * .assertFailure(NoSuchElementException.class);
3860 * </code></pre>
3861 * <p>
3862 * Creating custom operators can be complicated and it is recommended one consults the
3863 * <a href="https://github.com/ReactiveX/RxJava/wiki/Writing-operators-for-2.0">RxJava wiki: Writing operators</a> page about
3864 * the tools, requirements, rules, considerations and pitfalls of implementing them.
3865 * <p>
3866 * Note that implementing custom operators via this {@code lift()} method adds slightly more overhead by requiring
3867 * an additional allocation and indirection per assembled flows. Instead, extending the abstract {@code Single}
3868 * class and creating a {@link SingleTransformer} with it is recommended.
3869 * <p>
3870 * Note also that it is not possible to stop the subscription phase in {@code lift()} as the {@code apply()} method
3871 * requires a non-{@code null} {@code SingleObserver} instance to be returned, which is then unconditionally subscribed to
3872 * the current {@code Single}. For example, if the operator decided there is no reason to subscribe to the
3873 * upstream source because of some optimization possibility or a failure to prepare the operator, it still has to
3874 * return a {@code SingleObserver} that should immediately dispose the upstream's {@link Disposable} in its
3875 * {@code onSubscribe} method. Again, using a {@code SingleTransformer} and extending the {@code Single} is
3876 * a better option as {@link #subscribeActual} can decide to not subscribe to its upstream after all.
3877 * <dl>
3878 * <dt><b>Scheduler:</b></dt>
3879 * <dd>{@code lift} does not operate by default on a particular {@link Scheduler}, however, the
3880 * {@code SingleOperator} may use a {@code Scheduler} to support its own asynchronous behavior.</dd>
3881 * </dl>
3882 *
3883 * @param <R> the output value type
3884 * @param lift the {@code SingleOperator} that receives the downstream's {@code SingleObserver} and should return
3885 * a {@code SingleObserver} with custom behavior to be used as the consumer for the current
3886 * {@code Single}.
3887 * @return the new {@code Single} instance
3888 * @throws NullPointerException if {@code lift} is {@code null}
3889 * @see <a href="https://github.com/ReactiveX/RxJava/wiki/Writing-operators-for-2.0">RxJava wiki: Writing operators</a>
3890 * @see #compose(SingleTransformer)
3891 */
3892 @CheckReturnValue
3893 @NonNull
3894 @SchedulerSupport(SchedulerSupport.NONE)
3895 public final <@NonNull R> Single<R> lift(@NonNull SingleOperator<? extends R, ? super T> lift) {
3896 Objects.requireNonNull(lift, "lift is null");
3897 return RxJavaPlugins.onAssembly(new SingleLift<>(this, lift));
3898 }
3899
3900 /**
3901 * Returns a {@code Single} that applies a specified function to the item emitted by the current {@code Single} and
3902 * emits the result of this function application.
3903 * <p>
3904 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.map.v3.png" alt="">
3905 * <dl>
3906 * <dt><b>Scheduler:</b></dt>
3907 * <dd>{@code map} does not operate by default on a particular {@link Scheduler}.</dd>
3908 * </dl>
3909 *
3910 * @param <R> the result value type
3911 * @param mapper
3912 * a function to apply to the item emitted by the {@code Single}
3913 * @return the new {@code Single} that emits the item from the current {@code Single}, transformed by the specified function
3914 * @throws NullPointerException if {@code mapper} is {@code null}
3915 * @see <a href="http://reactivex.io/documentation/operators/map.html">ReactiveX operators documentation: Map</a>
3916 */
3917 @CheckReturnValue
3918 @NonNull
3919 @SchedulerSupport(SchedulerSupport.NONE)
3920 public final <@NonNull R> Single<R> map(@NonNull Function<? super T, ? extends R> mapper) {
3921 Objects.requireNonNull(mapper, "mapper is null");
3922 return RxJavaPlugins.onAssembly(new SingleMap<>(this, mapper));
3923 }
3924
3925 /**
3926 * Maps the signal types of this {@code Single} into a {@link Notification} of the same kind
3927 * and emits it as a single success value to downstream.
3928 * <p>
3929 * <img width="640" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/materialize.v3.png" alt="">
3930 * <dl>
3931 * <dt><b>Scheduler:</b></dt>
3932 * <dd>{@code materialize} does not operate by default on a particular {@link Scheduler}.</dd>
3933 * </dl>
3934 * <p>History: 2.2.4 - experimental
3935 * @return the new {@code Single} instance
3936 * @since 3.0.0
3937 * @see #dematerialize(Function)
3938 */
3939 @CheckReturnValue
3940 @SchedulerSupport(SchedulerSupport.NONE)
3941 @NonNull
3942 public final Single<Notification<T>> materialize() {
3943 return RxJavaPlugins.onAssembly(new SingleMaterialize<>(this));
3944 }
3945
3946 /**
3947 * Signals {@code true} if the current {@code Single} signals a success value that is {@link Object#equals(Object)} with the value
3948 * provided.
3949 * <p>
3950 * <img width="640" height="401" src="https://raw.githubusercontent.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.contains.png" alt="">
3951 * <p>
3952 * <img width="640" height="401" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.contains.png" alt="">
3953 * <dl>
3954 * <dt><b>Scheduler:</b></dt>
3955 * <dd>{@code contains} does not operate by default on a particular {@link Scheduler}.</dd>
3956 * </dl>
3957 * @param item the value to compare against the success value of this {@code Single}
3958 * @return the new {@code Single} instance
3959 * @throws NullPointerException if {@code item} is {@code null}
3960 * @since 2.0
3961 */
3962 @CheckReturnValue
3963 @SchedulerSupport(SchedulerSupport.NONE)
3964 @NonNull
3965 public final Single<Boolean> contains(@NonNull Object item) {
3966 return contains(item, ObjectHelper.equalsPredicate());
3967 }
3968
3969 /**
3970 * Signals {@code true} if the current {@code Single} signals a success value that is equal with
3971 * the value provided by calling a {@link BiPredicate}.
3972 * <p>
3973 * <img width="640" height="401" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.contains.f.png" alt="">
3974 * <dl>
3975 * <dt><b>Scheduler:</b></dt>
3976 * <dd>{@code contains} does not operate by default on a particular {@link Scheduler}.</dd>
3977 * </dl>
3978 * @param item the value to compare against the success value of this {@code Single}
3979 * @param comparer the function that receives the success value of this {@code Single}, the value provided
3980 * and should return {@code true} if they are considered equal
3981 * @return the new {@code Single} instance
3982 * @throws NullPointerException if {@code item} or {@code comparer} is {@code null}
3983 * @since 2.0
3984 */
3985 @CheckReturnValue
3986 @NonNull
3987 @SchedulerSupport(SchedulerSupport.NONE)
3988 public final Single<Boolean> contains(@NonNull Object item, @NonNull BiPredicate<Object, Object> comparer) {
3989 Objects.requireNonNull(item, "item is null");
3990 Objects.requireNonNull(comparer, "comparer is null");
3991 return RxJavaPlugins.onAssembly(new SingleContains<>(this, item, comparer));
3992 }
3993
3994 /**
3995 * Flattens this {@code Single} and another {@link SingleSource} into one {@link Flowable}, without any transformation.
3996 * <p>
3997 * <img width="640" height="416" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.mergeWith.v3.png" alt="">
3998 * <p>
3999 * You can combine items emitted by multiple {@code SingleSource}s so that they appear as one {@code Flowable}, by using
4000 * the {@code mergeWith} method.
4001 * <dl>
4002 * <dt><b>Backpressure:</b></dt>
4003 * <dd>The returned {@code Flowable} honors the backpressure of the downstream consumer.</dd>
4004 * <dt><b>Scheduler:</b></dt>
4005 * <dd>{@code mergeWith} does not operate by default on a particular {@link Scheduler}.</dd>
4006 * </dl>
4007 *
4008 * @param other
4009 * a {@code SingleSource} to be merged
4010 * @return the new {@code Flowable} instance
4011 * @throws NullPointerException if {@code other} is {@code null}
4012 * @see <a href="http://reactivex.io/documentation/operators/merge.html">ReactiveX operators documentation: Merge</a>
4013 */
4014 @BackpressureSupport(BackpressureKind.FULL)
4015 @CheckReturnValue
4016 @SchedulerSupport(SchedulerSupport.NONE)
4017 @NonNull
4018 public final Flowable<T> mergeWith(@NonNull SingleSource<? extends T> other) {
4019 return merge(this, other);
4020 }
4021 /**
4022 * Filters the items emitted by the current {@code Single}, only emitting its success value if that
4023 * is an instance of the supplied {@link Class}.
4024 * <p>
4025 * <img width="640" height="399" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.ofType.png" alt="">
4026 * <dl>
4027 * <dt><b>Scheduler:</b></dt>
4028 * <dd>{@code ofType} does not operate by default on a particular {@link Scheduler}.</dd>
4029 * </dl>
4030 *
4031 * @param <U> the output type
4032 * @param clazz
4033 * the class type to filter the items emitted by the current {@code Single}
4034 * @return the new {@link Maybe} instance
4035 * @throws NullPointerException if {@code clazz} is {@code null}
4036 * @see <a href="http://reactivex.io/documentation/operators/filter.html">ReactiveX operators documentation: Filter</a>
4037 * @since 3.0.0
4038 */
4039 @CheckReturnValue
4040 @NonNull
4041 @SchedulerSupport(SchedulerSupport.NONE)
4042 public final <@NonNull U> Maybe<U> ofType(@NonNull Class<U> clazz) {
4043 Objects.requireNonNull(clazz, "clazz is null");
4044 return filter(Functions.isInstanceOf(clazz)).cast(clazz);
4045 }
4046
4047 /**
4048 * Signals the success item or the terminal signals of the current {@code Single} on the specified {@link Scheduler},
4049 * asynchronously.
4050 * <p>
4051 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.observeOn.v3.png" alt="">
4052 * <dl>
4053 * <dt><b>Scheduler:</b></dt>
4054 * <dd>you specify which {@code Scheduler} this operator will use.</dd>
4055 * </dl>
4056 *
4057 * @param scheduler
4058 * the {@code Scheduler} to notify subscribers on
4059 * @return the new {@code Single} instance
4060 * @throws NullPointerException if {@code scheduler} is {@code null}
4061 * @see <a href="http://reactivex.io/documentation/operators/observeon.html">ReactiveX operators documentation: ObserveOn</a>
4062 * @see <a href="http://www.grahamlea.com/2014/07/rxjava-threading-examples/">RxJava Threading Examples</a>
4063 * @see #subscribeOn
4064 */
4065 @CheckReturnValue
4066 @NonNull
4067 @SchedulerSupport(SchedulerSupport.CUSTOM)
4068 public final Single<T> observeOn(@NonNull Scheduler scheduler) {
4069 Objects.requireNonNull(scheduler, "scheduler is null");
4070 return RxJavaPlugins.onAssembly(new SingleObserveOn<>(this, scheduler));
4071 }
4072
4073 /**
4074 * Ends the flow with a success item returned by a function for the {@link Throwable} error signaled by the current
4075 * {@code Single} instead of signaling the error via {@code onError}.
4076 * <p>
4077 * <img width="640" height="461" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.onErrorReturn.v3.png" alt="">
4078 * <p>
4079 * By default, when a {@code Single} encounters an error that prevents it from emitting the expected item to its
4080 * subscriber, the {@code Single} invokes its subscriber's {@link SingleObserver#onError} method, and then quits
4081 * without invoking any more of its observer's methods. The {@code onErrorReturn} method changes this
4082 * behavior. If you pass a function ({@code resumeFunction}) to a {@code Single}'s {@code onErrorReturn} method, if
4083 * the original {@code Single} encounters an error, instead of invoking its observer's
4084 * {@link SingleObserver#onError} method, it will instead emit the return value of {@code resumeFunction}.
4085 * <p>
4086 * You can use this to prevent errors from propagating or to supply fallback data should errors be
4087 * encountered.
4088 * <dl>
4089 * <dt><b>Scheduler:</b></dt>
4090 * <dd>{@code onErrorReturn} does not operate by default on a particular {@link Scheduler}.</dd>
4091 * </dl>
4092 *
4093 * @param itemSupplier
4094 * a function that returns an item that the new {@code Single} will emit if the current {@code Single} encounters
4095 * an error
4096 * @return the new {@code Single} instance
4097 * @throws NullPointerException if {@code itemSupplier} is {@code null}
4098 * @see <a href="http://reactivex.io/documentation/operators/catch.html">ReactiveX operators documentation: Catch</a>
4099 */
4100 @CheckReturnValue
4101 @NonNull
4102 @SchedulerSupport(SchedulerSupport.NONE)
4103 public final Single<T> onErrorReturn(@NonNull Function<Throwable, ? extends T> itemSupplier) {
4104 Objects.requireNonNull(itemSupplier, "itemSupplier is null");
4105 return RxJavaPlugins.onAssembly(new SingleOnErrorReturn<>(this, itemSupplier, null));
4106 }
4107
4108 /**
4109 * Signals the specified value as success in case the current {@code Single} signals an error.
4110 * <p>
4111 * <img width="640" height="461" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.onErrorReturnItem.v3.png" alt="">
4112 * <dl>
4113 * <dt><b>Scheduler:</b></dt>
4114 * <dd>{@code onErrorReturnItem} does not operate by default on a particular {@link Scheduler}.</dd>
4115 * </dl>
4116 * @param item the value to signal if the current {@code Single} fails
4117 * @return the new {@code Single} instance
4118 * @throws NullPointerException if {@code item} is {@code null}
4119 * @since 2.0
4120 */
4121 @CheckReturnValue
4122 @NonNull
4123 @SchedulerSupport(SchedulerSupport.NONE)
4124 public final Single<T> onErrorReturnItem(@NonNull T item) {
4125 Objects.requireNonNull(item, "item is null");
4126 return RxJavaPlugins.onAssembly(new SingleOnErrorReturn<>(this, null, item));
4127 }
4128
4129 /**
4130 * Resumes the flow with the given {@link SingleSource} when the current {@code Single} fails instead of
4131 * signaling the error via {@code onError}.
4132 * <p>
4133 * <img width="640" height="461" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.onErrorResumeWith.png" alt="">
4134 * <p>
4135 * By default, when a {@code Single} encounters an error that prevents it from emitting the expected item to
4136 * its {@link SingleObserver}, the {@code Single} invokes its {@code SingleObserver}'s {@code onError} method, and then quits
4137 * without invoking any more of its {@code SingleObserver}'s methods. The {@code onErrorResumeWith} method changes this
4138 * behavior. If you pass another {@code Single} ({@code resumeSingleInCaseOfError}) to a {@code Single}'s
4139 * {@code onErrorResumeWith} method, if the original {@code Single} encounters an error, instead of invoking its
4140 * {@code SingleObserver}'s {@code onError} method, it will instead relinquish control to {@code resumeSingleInCaseOfError} which
4141 * will invoke the {@code SingleObserver}'s {@link SingleObserver#onSuccess onSuccess} method if it is able to do so. In such a case,
4142 * because no {@code Single} necessarily invokes {@code onError}, the {@code SingleObserver} may never know that an error
4143 * happened.
4144 * <p>
4145 * You can use this to prevent errors from propagating or to supply fallback data should errors be
4146 * encountered.
4147 * <dl>
4148 * <dt><b>Scheduler:</b></dt>
4149 * <dd>{@code onErrorResumeWith} does not operate by default on a particular {@link Scheduler}.</dd>
4150 * </dl>
4151 *
4152 * @param fallback a {@code Single} that will take control if source {@code Single} encounters an error.
4153 * @return the new {@code Single} instance
4154 * @throws NullPointerException if {@code fallback} is {@code null}
4155 * @see <a href="http://reactivex.io/documentation/operators/catch.html">ReactiveX operators documentation: Catch</a>
4156 */
4157 @CheckReturnValue
4158 @NonNull
4159 @SchedulerSupport(SchedulerSupport.NONE)
4160 public final Single<T> onErrorResumeWith(@NonNull SingleSource<? extends T> fallback) {
4161 Objects.requireNonNull(fallback, "fallback is null");
4162 return onErrorResumeNext(Functions.justFunction(fallback));
4163 }
4164
4165 /**
4166 * Returns a {@link Maybe} instance that if the current {@code Single} emits an error, it will emit an {@code onComplete}
4167 * and swallow the throwable.
4168 * <p>
4169 * <img width="640" height="554" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.onErrorComplete.png" alt="">
4170 * <dl>
4171 * <dt><b>Scheduler:</b></dt>
4172 * <dd>{@code onErrorComplete} does not operate by default on a particular {@link Scheduler}.</dd>
4173 * </dl>
4174 * @return the new {@code Maybe} instance
4175 * @since 3.0.0
4176 */
4177 @CheckReturnValue
4178 @SchedulerSupport(SchedulerSupport.NONE)
4179 @NonNull
4180 public final Maybe<T> onErrorComplete() {
4181 return onErrorComplete(Functions.alwaysTrue());
4182 }
4183
4184 /**
4185 * Returns a {@link Maybe} instance that if this {@code Single} emits an error and the predicate returns
4186 * {@code true}, it will emit an {@code onComplete} and swallow the throwable.
4187 * <p>
4188 * <img width="640" height="270" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.onErrorComplete.f.png" alt="">
4189 * <dl>
4190 * <dt><b>Scheduler:</b></dt>
4191 * <dd>{@code onErrorComplete} does not operate by default on a particular {@link Scheduler}.</dd>
4192 * </dl>
4193 * @param predicate the predicate to call when an {@link Throwable} is emitted which should return {@code true}
4194 * if the {@code Throwable} should be swallowed and replaced with an {@code onComplete}.
4195 * @return the new {@code Maybe} instance
4196 * @throws NullPointerException if {@code predicate} is {@code null}
4197 * @since 3.0.0
4198 */
4199 @CheckReturnValue
4200 @NonNull
4201 @SchedulerSupport(SchedulerSupport.NONE)
4202 public final Maybe<T> onErrorComplete(@NonNull Predicate<? super Throwable> predicate) {
4203 Objects.requireNonNull(predicate, "predicate is null");
4204
4205 return RxJavaPlugins.onAssembly(new SingleOnErrorComplete<>(this, predicate));
4206 }
4207
4208 /**
4209 * Resumes the flow with a {@link SingleSource} returned for the failure {@link Throwable} of the current {@code Single} by a
4210 * function instead of signaling the error via {@code onError}.
4211 * <p>
4212 * <img width="640" height="461" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.onErrorResumeNext.f.v3.png" alt="">
4213 * <p>
4214 * By default, when a {@code Single} encounters an error that prevents it from emitting the expected item to
4215 * its {@link SingleObserver}, the {@code Single} invokes its {@code SingleObserver}'s {@code onError} method, and then quits
4216 * without invoking any more of its {@code SingleObserver}'s methods. The {@code onErrorResumeNext} method changes this
4217 * behavior. If you pass a function that will return another {@code Single} ({@code resumeFunctionInCaseOfError}) to a {@code Single}'s
4218 * {@code onErrorResumeNext} method, if the original {@code Single} encounters an error, instead of invoking its
4219 * {@code SingleObserver}'s {@code onError} method, it will instead relinquish control to {@code resumeSingleInCaseOfError} which
4220 * will invoke the {@code SingleObserver}'s {@link SingleObserver#onSuccess onSuccess} method if it is able to do so. In such a case,
4221 * because no {@code Single} necessarily invokes {@code onError}, the {@code SingleObserver} may never know that an error
4222 * happened.
4223 * <p>
4224 * You can use this to prevent errors from propagating or to supply fallback data should errors be
4225 * encountered.
4226 * <dl>
4227 * <dt><b>Scheduler:</b></dt>
4228 * <dd>{@code onErrorResumeNext} does not operate by default on a particular {@link Scheduler}.</dd>
4229 * </dl>
4230 *
4231 * @param fallbackSupplier a function that returns a {@code SingleSource} that will take control if source {@code Single} encounters an error.
4232 * @return the new {@code Single} instance
4233 * @throws NullPointerException if {@code fallbackSupplier} is {@code null}
4234 * @see <a href="http://reactivex.io/documentation/operators/catch.html">ReactiveX operators documentation: Catch</a>
4235 * @since .20
4236 */
4237 @CheckReturnValue
4238 @NonNull
4239 @SchedulerSupport(SchedulerSupport.NONE)
4240 public final Single<T> onErrorResumeNext(
4241 @NonNull Function<? super Throwable, ? extends SingleSource<? extends T>> fallbackSupplier) {
4242 Objects.requireNonNull(fallbackSupplier, "fallbackSupplier is null");
4243 return RxJavaPlugins.onAssembly(new SingleResumeNext<>(this, fallbackSupplier));
4244 }
4245
4246 /**
4247 * Nulls out references to the upstream producer and downstream {@link SingleObserver} if
4248 * the sequence is terminated or downstream calls {@code dispose()}.
4249 * <p>
4250 * <img width="640" height="346" src="https://raw.githubusercontent.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.onTerminateDetach.png" alt="">
4251 * <dl>
4252 * <dt><b>Scheduler:</b></dt>
4253 * <dd>{@code onTerminateDetach} does not operate by default on a particular {@link Scheduler}.</dd>
4254 * </dl>
4255 * <p>History: 2.1.5 - experimental
4256 * @return the new {@code Single} which {@code null}s out references to the upstream producer and downstream {@code SingleObserver} if
4257 * the sequence is terminated or downstream calls {@code dispose()}
4258 * @since 2.2
4259 */
4260 @CheckReturnValue
4261 @SchedulerSupport(SchedulerSupport.NONE)
4262 @NonNull
4263 public final Single<T> onTerminateDetach() {
4264 return RxJavaPlugins.onAssembly(new SingleDetach<>(this));
4265 }
4266
4267 /**
4268 * Repeatedly re-subscribes to the current {@code Single} and emits each success value as a {@link Flowable} sequence.
4269 * <p>
4270 * <img width="640" height="463" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.repeat.v3.png" alt="">
4271 * <dl>
4272 * <dt><b>Backpressure:</b></dt>
4273 * <dd>The returned {@code Flowable} honors the backpressure of the downstream consumer.</dd>
4274 * <dt><b>Scheduler:</b></dt>
4275 * <dd>{@code repeat} does not operate by default on a particular {@link Scheduler}.</dd>
4276 * </dl>
4277 * @return the new {@code Flowable} instance
4278 * @since 2.0
4279 */
4280 @BackpressureSupport(BackpressureKind.FULL)
4281 @CheckReturnValue
4282 @SchedulerSupport(SchedulerSupport.NONE)
4283 @NonNull
4284 public final Flowable<T> repeat() {
4285 return toFlowable().repeat();
4286 }
4287
4288 /**
4289 * Re-subscribes to the current {@code Single} at most the given number of times and emits each success value as a {@link Flowable} sequence.
4290 * <p>
4291 * <img width="640" height="463" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.repeat.n.v3.png" alt="">
4292 * <dl>
4293 * <dt><b>Backpressure:</b></dt>
4294 * <dd>The returned {@code Flowable} honors the backpressure of the downstream consumer.</dd>
4295 * <dt><b>Scheduler:</b></dt>
4296 * <dd>{@code repeat} does not operate by default on a particular {@link Scheduler}.</dd>
4297 * </dl>
4298 * @param times the number of times to re-subscribe to the current {@code Single}
4299 * @return the new {@code Flowable} instance
4300 * @throws IllegalArgumentException if {@code times} is negative
4301 * @since 2.0
4302 */
4303 @BackpressureSupport(BackpressureKind.FULL)
4304 @CheckReturnValue
4305 @SchedulerSupport(SchedulerSupport.NONE)
4306 @NonNull
4307 public final Flowable<T> repeat(long times) {
4308 return toFlowable().repeat(times);
4309 }
4310
4311 /**
4312 * Re-subscribes to the current {@code Single} if
4313 * the {@link Publisher} returned by the handler function signals a value in response to a
4314 * value signaled through the {@link Flowable} the handler receives.
4315 * <p>
4316 * <img width="640" height="1480" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.repeatWhen.v3.png" alt="">
4317 * <dl>
4318 * <dt><b>Backpressure:</b></dt>
4319 * <dd>The returned {@code Flowable} honors the backpressure of the downstream consumer.
4320 * The {@code Publisher} returned by the handler function is expected to honor backpressure as well.</dd>
4321 * <dt><b>Scheduler:</b></dt>
4322 * <dd>{@code repeatWhen} does not operate by default on a particular {@link Scheduler}.</dd>
4323 * </dl>
4324 * @param handler the function that is called with a {@code Flowable} that signals a value when the {@code Single}
4325 * signaled a success value and returns a {@code Publisher} that has to signal a value to
4326 * trigger a resubscription to the current {@code Single}, otherwise the terminal signal of
4327 * the {@code Publisher} will be the terminal signal of the sequence as well.
4328 * @return the new {@code Flowable} instance
4329 * @throws NullPointerException if {@code handler} is {@code null}
4330 * @since 2.0
4331 */
4332 @BackpressureSupport(BackpressureKind.FULL)
4333 @CheckReturnValue
4334 @SchedulerSupport(SchedulerSupport.NONE)
4335 @NonNull
4336 public final Flowable<T> repeatWhen(@NonNull Function<? super Flowable<Object>, @NonNull ? extends Publisher<@NonNull ?>> handler) {
4337 return toFlowable().repeatWhen(handler);
4338 }
4339
4340 /**
4341 * Re-subscribes to the current {@code Single} until the given {@link BooleanSupplier} returns {@code true}
4342 * and emits the success items as a {@link Flowable} sequence.
4343 * <p>
4344 * <img width="640" height="463" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.repeatUntil.v3.png" alt="">
4345 * <dl>
4346 * <dt><b>Backpressure:</b></dt>
4347 * <dd>The returned {@code Flowable} honors the backpressure of the downstream consumer.</dd>
4348 * <dt><b>Scheduler:</b></dt>
4349 * <dd>{@code repeatUntil} does not operate by default on a particular {@link Scheduler}.</dd>
4350 * </dl>
4351 * @param stop the {@code BooleanSupplier} called after the current {@code Single} succeeds and if returns {@code false},
4352 * the {@code Single} is re-subscribed; otherwise the sequence completes.
4353 * @return the new {@code Flowable} instance
4354 * @throws NullPointerException if {@code stop} is {@code null}
4355 * @since 2.0
4356 */
4357 @BackpressureSupport(BackpressureKind.FULL)
4358 @CheckReturnValue
4359 @SchedulerSupport(SchedulerSupport.NONE)
4360 @NonNull
4361 public final Flowable<T> repeatUntil(@NonNull BooleanSupplier stop) {
4362 return toFlowable().repeatUntil(stop);
4363 }
4364
4365 /**
4366 * Repeatedly re-subscribes to the current {@code Single} indefinitely if it fails with an {@code onError}.
4367 * <p>
4368 * <img width="640" height="399" src="https://raw.githubusercontent.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.retry.png" alt="">
4369 * <dl>
4370 * <dt><b>Scheduler:</b></dt>
4371 * <dd>{@code retry} does not operate by default on a particular {@link Scheduler}.</dd>
4372 * </dl>
4373 * @return the new {@code Single} instance
4374 * @since 2.0
4375 */
4376 @CheckReturnValue
4377 @SchedulerSupport(SchedulerSupport.NONE)
4378 @NonNull
4379 public final Single<T> retry() {
4380 return toSingle(toFlowable().retry());
4381 }
4382
4383 /**
4384 * Repeatedly re-subscribe at most the specified times to the current {@code Single}
4385 * if it fails with an {@code onError}.
4386 * <p>
4387 * <img width="640" height="329" src="https://raw.githubusercontent.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.retry.n.png" alt="">
4388 * <dl>
4389 * <dt><b>Scheduler:</b></dt>
4390 * <dd>{@code retry} does not operate by default on a particular {@link Scheduler}.</dd>
4391 * </dl>
4392 * @param times the number of times to resubscribe if the current {@code Single} fails
4393 * @return the new {@code Single} instance
4394 * @throws IllegalArgumentException if {@code times} is negative
4395 * @since 2.0
4396 */
4397 @CheckReturnValue
4398 @SchedulerSupport(SchedulerSupport.NONE)
4399 @NonNull
4400 public final Single<T> retry(long times) {
4401 return toSingle(toFlowable().retry(times));
4402 }
4403
4404 /**
4405 * Re-subscribe to the current {@code Single} if the given predicate returns {@code true} when the {@code Single} fails
4406 * with an {@code onError}.
4407 * <p>
4408 * <img width="640" height="230" src="https://raw.githubusercontent.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.retry.f2.png" alt="">
4409 * <dl>
4410 * <dt><b>Scheduler:</b></dt>
4411 * <dd>{@code retry} does not operate by default on a particular {@link Scheduler}.</dd>
4412 * </dl>
4413 * @param predicate the predicate called with the resubscription count and the failure {@link Throwable}
4414 * and should return {@code true} if a resubscription should happen
4415 * @return the new {@code Single} instance
4416 * @throws NullPointerException if {@code predicate} is {@code null}
4417 * @since 2.0
4418 */
4419 @CheckReturnValue
4420 @SchedulerSupport(SchedulerSupport.NONE)
4421 @NonNull
4422 public final Single<T> retry(@NonNull BiPredicate<? super Integer, ? super Throwable> predicate) {
4423 return toSingle(toFlowable().retry(predicate));
4424 }
4425
4426 /**
4427 * Repeatedly re-subscribe at most times or until the predicate returns {@code false}, whichever happens first
4428 * if it fails with an {@code onError}.
4429 * <p>
4430 * <img width="640" height="259" src="https://raw.githubusercontent.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.retry.nf.png" alt="">
4431 * <dl>
4432 * <dt><b>Scheduler:</b></dt>
4433 * <dd>{@code retry} does not operate by default on a particular {@link Scheduler}.</dd>
4434 * </dl>
4435 * <p>History: 2.1.8 - experimental
4436 * @param times the number of times to resubscribe if the current {@code Single} fails
4437 * @param predicate the predicate called with the failure {@link Throwable}
4438 * and should return {@code true} if a resubscription should happen
4439 * @return the new {@code Single} instance
4440 * @throws NullPointerException if {@code predicate} is {@code null}
4441 * @throws IllegalArgumentException if {@code times} is negative
4442 * @since 2.2
4443 */
4444 @CheckReturnValue
4445 @SchedulerSupport(SchedulerSupport.NONE)
4446 @NonNull
4447 public final Single<T> retry(long times, @NonNull Predicate<? super Throwable> predicate) {
4448 return toSingle(toFlowable().retry(times, predicate));
4449 }
4450
4451 /**
4452 * Re-subscribe to the current {@code Single} if the given predicate returns {@code true} when the {@code Single} fails
4453 * with an {@code onError}.
4454 * <p>
4455 * <img width="640" height="240" src="https://raw.githubusercontent.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.retry.f.png" alt="">
4456 * <dl>
4457 * <dt><b>Scheduler:</b></dt>
4458 * <dd>{@code retry} does not operate by default on a particular {@link Scheduler}.</dd>
4459 * </dl>
4460 * @param predicate the predicate called with the failure {@link Throwable}
4461 * and should return {@code true} if a resubscription should happen
4462 * @return the new {@code Single} instance
4463 * @throws NullPointerException if {@code predicate} is {@code null}
4464 * @since 2.0
4465 */
4466 @CheckReturnValue
4467 @SchedulerSupport(SchedulerSupport.NONE)
4468 @NonNull
4469 public final Single<T> retry(@NonNull Predicate<? super Throwable> predicate) {
4470 return toSingle(toFlowable().retry(predicate));
4471 }
4472
4473 /**
4474 * Retries until the given stop function returns {@code true}.
4475 * <p>
4476 * <img width="640" height="364" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.retryUntil.png" alt="">
4477 * <dl>
4478 * <dt><b>Scheduler:</b></dt>
4479 * <dd>{@code retryUntil} does not operate by default on a particular {@link Scheduler}.</dd>
4480 * </dl>
4481 * @param stop the function that should return {@code true} to stop retrying
4482 * @return the new {@code Single} instance
4483 * @throws NullPointerException if {@code stop} is {@code null}
4484 * @since 3.0.0
4485 */
4486 @CheckReturnValue
4487 @NonNull
4488 @SchedulerSupport(SchedulerSupport.NONE)
4489 public final Single<T> retryUntil(@NonNull BooleanSupplier stop) {
4490 Objects.requireNonNull(stop, "stop is null");
4491 return retry(Long.MAX_VALUE, Functions.predicateReverseFor(stop));
4492 }
4493
4494 /**
4495 * Re-subscribes to the current {@code Single} if and when the {@link Publisher} returned by the handler
4496 * function signals a value.
4497 * <p>
4498 * <img width="640" height="405" src="https://raw.githubusercontent.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.retryWhen.png" alt="">
4499 * <p>
4500 * If the {@code Publisher} signals an {@code onComplete}, the resulting {@code Single} will signal a {@link NoSuchElementException}.
4501 * <p>
4502 * Note that the inner {@code Publisher} returned by the handler function should signal
4503 * either {@code onNext}, {@code onError} or {@code onComplete} in response to the received
4504 * {@link Throwable} to indicate the operator should retry or terminate. If the upstream to
4505 * the operator is asynchronous, signaling {@code onNext} followed by {@code onComplete} immediately may
4506 * result in the sequence to be completed immediately. Similarly, if this inner
4507 * {@code Publisher} signals {@code onError} or {@code onComplete} while the upstream is
4508 * active, the sequence is terminated with the same signal immediately.
4509 * <p>
4510 * The following example demonstrates how to retry an asynchronous source with a delay:
4511 * <pre><code>
4512 * Single.timer(1, TimeUnit.SECONDS)
4513 * .doOnSubscribe(s -&gt; System.out.println("subscribing"))
4514 * .map(v -&gt; { throw new RuntimeException(); })
4515 * .retryWhen(errors -&gt; {
4516 * AtomicInteger counter = new AtomicInteger();
4517 * return errors
4518 * .takeWhile(e -&gt; counter.getAndIncrement() != 3)
4519 * .flatMap(e -&gt; {
4520 * System.out.println("delay retry by " + counter.get() + " second(s)");
4521 * return Flowable.timer(counter.get(), TimeUnit.SECONDS);
4522 * });
4523 * })
4524 * .blockingGet();
4525 * </code></pre>
4526 * <dl>
4527 * <dt><b>Scheduler:</b></dt>
4528 * <dd>{@code retryWhen} does not operate by default on a particular {@link Scheduler}.</dd>
4529 * </dl>
4530 *
4531 * @param handler the function that receives a {@link Flowable} of the error the {@code Single} emits and should
4532 * return a {@code Publisher} that should signal a normal value (in response to the
4533 * throwable the {@code Flowable} emits) to trigger a resubscription or signal an error to
4534 * be the output of the resulting {@code Single}
4535 * @return the new {@code Single} instance
4536 * @throws NullPointerException if {@code handler} is {@code null}
4537 */
4538 @CheckReturnValue
4539 @SchedulerSupport(SchedulerSupport.NONE)
4540 @NonNull
4541 public final Single<T> retryWhen(@NonNull Function<? super Flowable<Throwable>, @NonNull ? extends Publisher<@NonNull ?>> handler) {
4542 return toSingle(toFlowable().retryWhen(handler));
4543 }
4544
4545 /**
4546 * Wraps the given {@link SingleObserver}, catches any {@link RuntimeException}s thrown by its
4547 * {@link SingleObserver#onSubscribe(Disposable)}, {@link SingleObserver#onSuccess(Object)} or
4548 * {@link SingleObserver#onError(Throwable)} methods* and routes those to the global error handler
4549 * via {@link RxJavaPlugins#onError(Throwable)}.
4550 * <p>
4551 * By default, the {@code Single} protocol forbids the {@code onXXX} methods to throw, but some
4552 * {@code SingleObserver} implementation may do it anyway, causing undefined behavior in the
4553 * upstream. This method and the underlying safe wrapper ensures such misbehaving consumers don't
4554 * disrupt the protocol.
4555 * <dl>
4556 * <dt><b>Scheduler:</b></dt>
4557 * <dd>{@code safeSubscribe} does not operate by default on a particular {@link Scheduler}.</dd>
4558 * </dl>
4559 * @param observer the potentially misbehaving {@code SingleObserver}
4560 * @throws NullPointerException if {@code observer} is {@code null}
4561 * @see #subscribe(Consumer,Consumer)
4562 * @since 3.0.0
4563 */
4564 @SchedulerSupport(SchedulerSupport.NONE)
4565 public final void safeSubscribe(@NonNull SingleObserver<? super T> observer) {
4566 Objects.requireNonNull(observer, "observer is null");
4567 subscribe(new SafeSingleObserver<>(observer));
4568 }
4569
4570 /**
4571 * Returns a {@link Flowable} which first runs the other {@link CompletableSource}
4572 * then the current {@code Single} if the other completed normally.
4573 * <p>
4574 * <img width="640" height="360" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.startWith.c.png" alt="">
4575 * <dl>
4576 * <dt><b>Backpressure:</b></dt>
4577 * <dd>The returned {@code Flowable} honors the backpressure of the downstream consumer.</dd>
4578 * <dt><b>Scheduler:</b></dt>
4579 * <dd>{@code startWith} does not operate by default on a particular {@link Scheduler}.</dd>
4580 * </dl>
4581 * @param other the other {@code CompletableSource} to run first
4582 * @return the new {@code Flowable} instance
4583 * @throws NullPointerException if {@code other} is {@code null}
4584 * @since 3.0.0
4585 */
4586 @CheckReturnValue
4587 @NonNull
4588 @SchedulerSupport(SchedulerSupport.NONE)
4589 @BackpressureSupport(BackpressureKind.FULL)
4590 public final Flowable<T> startWith(@NonNull CompletableSource other) {
4591 Objects.requireNonNull(other, "other is null");
4592 return Flowable.concat(Completable.wrap(other).<T>toFlowable(), toFlowable());
4593 }
4594
4595 /**
4596 * Returns a {@link Flowable} which first runs the other {@link SingleSource}
4597 * then the current {@code Single} if the other succeeded normally.
4598 * <p>
4599 * <img width="640" height="341" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.startWith.s.png" alt="">
4600 * <dl>
4601 * <dt><b>Backpressure:</b></dt>
4602 * <dd>The returned {@code Flowable} honors the backpressure of the downstream consumer.</dd>
4603 * <dt><b>Scheduler:</b></dt>
4604 * <dd>{@code startWith} does not operate by default on a particular {@link Scheduler}.</dd>
4605 * </dl>
4606 * @param other the other {@code SingleSource} to run first
4607 * @return the new {@code Flowable} instance
4608 * @throws NullPointerException if {@code other} is {@code null}
4609 * @since 3.0.0
4610 */
4611 @CheckReturnValue
4612 @NonNull
4613 @SchedulerSupport(SchedulerSupport.NONE)
4614 @BackpressureSupport(BackpressureKind.FULL)
4615 public final Flowable<T> startWith(@NonNull SingleSource<T> other) {
4616 Objects.requireNonNull(other, "other is null");
4617 return Flowable.concat(Single.wrap(other).toFlowable(), toFlowable());
4618 }
4619
4620 /**
4621 * Returns a {@link Flowable} which first runs the other {@link MaybeSource}
4622 * then the current {@code Single} if the other succeeded or completed normally.
4623 * <p>
4624 * <img width="640" height="232" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.startWith.m.png" alt="">
4625 * <dl>
4626 * <dt><b>Backpressure:</b></dt>
4627 * <dd>The returned {@code Flowable} honors the backpressure of the downstream consumer.</dd>
4628 * <dt><b>Scheduler:</b></dt>
4629 * <dd>{@code startWith} does not operate by default on a particular {@link Scheduler}.</dd>
4630 * </dl>
4631 * @param other the other {@code MaybeSource} to run first
4632 * @return the new {@code Flowable} instance
4633 * @throws NullPointerException if {@code other} is {@code null}
4634 * @since 3.0.0
4635 */
4636 @CheckReturnValue
4637 @NonNull
4638 @SchedulerSupport(SchedulerSupport.NONE)
4639 @BackpressureSupport(BackpressureKind.FULL)
4640 public final Flowable<T> startWith(@NonNull MaybeSource<T> other) {
4641 Objects.requireNonNull(other, "other is null");
4642 return Flowable.concat(Maybe.wrap(other).toFlowable(), toFlowable());
4643 }
4644
4645 /**
4646 * Returns an {@link Observable} which first delivers the events
4647 * of the other {@link ObservableSource} then runs the current {@code Single}.
4648 * <p>
4649 * <img width="640" height="175" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.startWith.o.png" alt="">
4650 * <dl>
4651 * <dt><b>Scheduler:</b></dt>
4652 * <dd>{@code startWith} does not operate by default on a particular {@link Scheduler}.</dd>
4653 * </dl>
4654 * @param other the other {@code ObservableSource} to run first
4655 * @return the new {@code Observable} instance
4656 * @throws NullPointerException if {@code other} is {@code null}
4657 * @since 3.0.0
4658 */
4659 @CheckReturnValue
4660 @NonNull
4661 @SchedulerSupport(SchedulerSupport.NONE)
4662 public final Observable<T> startWith(@NonNull ObservableSource<T> other) {
4663 Objects.requireNonNull(other, "other is null");
4664 return Observable.wrap(other).concatWith(this.toObservable());
4665 }
4666
4667 /**
4668 * Returns a {@link Flowable} which first delivers the events
4669 * of the other {@link Publisher} then runs the current {@code Single}.
4670 * <p>
4671 * <img width="640" height="175" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.startWith.p.png" alt="">
4672 * <dl>
4673 * <dt><b>Backpressure:</b></dt>
4674 * <dd>The returned {@code Flowable} honors the backpressure of the downstream consumer
4675 * and expects the other {@code Publisher} to honor it as well.</dd>
4676 * <dt><b>Scheduler:</b></dt>
4677 * <dd>{@code startWith} does not operate by default on a particular {@link Scheduler}.</dd>
4678 * </dl>
4679 * @param other the other {@code Publisher} to run first
4680 * @return the new {@code Flowable} instance
4681 * @throws NullPointerException if {@code other} is {@code null}
4682 * @since 3.0.0
4683 */
4684 @CheckReturnValue
4685 @NonNull
4686 @BackpressureSupport(BackpressureKind.FULL)
4687 @SchedulerSupport(SchedulerSupport.NONE)
4688 public final Flowable<T> startWith(@NonNull Publisher<T> other) {
4689 Objects.requireNonNull(other, "other is null");
4690 return toFlowable().startWith(other);
4691 }
4692
4693 /**
4694 * Subscribes to a {@code Single} but ignore its emission or notification.
4695 * <p>
4696 * <img width="640" height="340" src="https://raw.githubusercontent.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.subscribe.png" alt="">
4697 * <p>
4698 * If the {@code Single} emits an error, it is wrapped into an
4699 * {@link io.reactivex.rxjava3.exceptions.OnErrorNotImplementedException OnErrorNotImplementedException}
4700 * and routed to the {@link RxJavaPlugins#onError(Throwable)} handler.
4701 * <dl>
4702 * <dt><b>Scheduler:</b></dt>
4703 * <dd>{@code subscribe} does not operate by default on a particular {@link Scheduler}.</dd>
4704 * </dl>
4705 *
4706 * @return the new {@link Disposable} instance that can be used for disposing the subscription at any time
4707 * @see <a href="http://reactivex.io/documentation/operators/subscribe.html">ReactiveX operators documentation: Subscribe</a>
4708 * @see #subscribe(Consumer, Consumer, DisposableContainer)
4709 */
4710 @SchedulerSupport(SchedulerSupport.NONE)
4711 @NonNull
4712 public final Disposable subscribe() {
4713 return subscribe(Functions.emptyConsumer(), Functions.ON_ERROR_MISSING);
4714 }
4715
4716 /**
4717 * Subscribes to a {@code Single} and provides a composite callback to handle the item it emits
4718 * or any error notification it issues.
4719 * <p>
4720 * <img width="640" height="340" src="https://raw.githubusercontent.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.subscribe.c2.png" alt="">
4721 * <dl>
4722 * <dt><b>Scheduler:</b></dt>
4723 * <dd>{@code subscribe} does not operate by default on a particular {@link Scheduler}.</dd>
4724 * </dl>
4725 *
4726 * @param onCallback
4727 * the callback that receives either the success value or the failure {@link Throwable}
4728 * (whichever is not {@code null})
4729 * @return the new {@link Disposable} instance that can be used for disposing the subscription at any time
4730 * @throws NullPointerException
4731 * if {@code onCallback} is {@code null}
4732 * @see #subscribe(Consumer, Consumer, DisposableContainer)
4733 * @see <a href="http://reactivex.io/documentation/operators/subscribe.html">ReactiveX operators documentation: Subscribe</a>
4734 */
4735 @CheckReturnValue
4736 @NonNull
4737 @SchedulerSupport(SchedulerSupport.NONE)
4738 public final Disposable subscribe(@NonNull BiConsumer<@Nullable ? super T, @Nullable ? super Throwable> onCallback) {
4739 Objects.requireNonNull(onCallback, "onCallback is null");
4740
4741 BiConsumerSingleObserver<T> observer = new BiConsumerSingleObserver<>(onCallback);
4742 subscribe(observer);
4743 return observer;
4744 }
4745
4746 /**
4747 * Subscribes to a {@code Single} and provides a callback to handle the item it emits.
4748 * <p>
4749 * <img width="640" height="341" src="https://raw.githubusercontent.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.subscribe.c.png" alt="">
4750 * <p>
4751 * If the {@code Single} emits an error, it is wrapped into an
4752 * {@link io.reactivex.rxjava3.exceptions.OnErrorNotImplementedException OnErrorNotImplementedException}
4753 * and routed to the {@link RxJavaPlugins#onError(Throwable)} handler.
4754 * <dl>
4755 * <dt><b>Scheduler:</b></dt>
4756 * <dd>{@code subscribe} does not operate by default on a particular {@link Scheduler}.</dd>
4757 * </dl>
4758 *
4759 * @param onSuccess
4760 * the {@code Consumer<T>} you have designed to accept the emission from the {@code Single}
4761 * @return the new {@link Disposable} instance that can be used for disposing the subscription at any time
4762 * @throws NullPointerException
4763 * if {@code onSuccess} is {@code null}
4764 * @see <a href="http://reactivex.io/documentation/operators/subscribe.html">ReactiveX operators documentation: Subscribe</a>
4765 * @see #subscribe(Consumer, Consumer, DisposableContainer)
4766 */
4767 @CheckReturnValue
4768 @SchedulerSupport(SchedulerSupport.NONE)
4769 @NonNull
4770 public final Disposable subscribe(@NonNull Consumer<? super T> onSuccess) {
4771 return subscribe(onSuccess, Functions.ON_ERROR_MISSING);
4772 }
4773
4774 /**
4775 * Subscribes to a {@code Single} and provides callbacks to handle the item it emits or any error notification it
4776 * issues.
4777 * <p>
4778 * <img width="640" height="340" src="https://raw.githubusercontent.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.subscribe.cc.png" alt="">
4779 * <dl>
4780 * <dt><b>Scheduler:</b></dt>
4781 * <dd>{@code subscribe} does not operate by default on a particular {@link Scheduler}.</dd>
4782 * </dl>
4783 *
4784 * @param onSuccess
4785 * the {@code Consumer<T>} you have designed to accept the emission from the {@code Single}
4786 * @param onError
4787 * the {@code Consumer<Throwable>} you have designed to accept any error notification from the
4788 * {@code Single}
4789 * @return the new {@link Disposable} instance that can be used for disposing the subscription at any time
4790 * @throws NullPointerException
4791 * if {@code onSuccess} or {@code onError} is {@code null}
4792 * @see <a href="http://reactivex.io/documentation/operators/subscribe.html">ReactiveX operators documentation: Subscribe</a>
4793 * @see #subscribe(Consumer, Consumer, DisposableContainer)
4794 */
4795 @CheckReturnValue
4796 @NonNull
4797 @SchedulerSupport(SchedulerSupport.NONE)
4798 public final Disposable subscribe(@NonNull Consumer<? super T> onSuccess, @NonNull Consumer<? super Throwable> onError) {
4799 Objects.requireNonNull(onSuccess, "onSuccess is null");
4800 Objects.requireNonNull(onError, "onError is null");
4801
4802 ConsumerSingleObserver<T> observer = new ConsumerSingleObserver<>(onSuccess, onError);
4803 subscribe(observer);
4804 return observer;
4805 }
4806
4807 /**
4808 * Wraps the given onXXX callbacks into a {@link Disposable} {@link SingleObserver},
4809 * adds it to the given {@link DisposableContainer} and ensures, that if the upstream
4810 * terminates or this particular {@code Disposable} is disposed, the {@code SingleObserver} is removed
4811 * from the given container.
4812 * <p>
4813 * The {@code SingleObserver} will be removed after the callback for the terminal event has been invoked.
4814 * <dl>
4815 * <dt><b>Scheduler:</b></dt>
4816 * <dd>{@code subscribe} does not operate by default on a particular {@link Scheduler}.</dd>
4817 * </dl>
4818 * @param onSuccess the callback for upstream items
4819 * @param onError the callback for an upstream error if any
4820 * @param container the {@code DisposableContainer} (such as {@link CompositeDisposable}) to add and remove the
4821 * created {@code Disposable} {@code SingleObserver}
4822 * @return the {@code Disposable} that allows disposing the particular subscription.
4823 * @throws NullPointerException
4824 * if {@code onSuccess}, {@code onError}
4825 * or {@code container} is {@code null}
4826 * @since 3.1.0
4827 */
4828 @SchedulerSupport(SchedulerSupport.NONE)
4829 @NonNull
4830 public final Disposable subscribe(
4831 @NonNull Consumer<? super T> onSuccess,
4832 @NonNull Consumer<? super Throwable> onError,
4833 @NonNull DisposableContainer container) {
4834 Objects.requireNonNull(onSuccess, "onSuccess is null");
4835 Objects.requireNonNull(onError, "onError is null");
4836 Objects.requireNonNull(container, "container is null");
4837
4838 DisposableAutoReleaseMultiObserver<T> observer = new DisposableAutoReleaseMultiObserver<>(
4839 container, onSuccess, onError, Functions.EMPTY_ACTION);
4840 container.add(observer);
4841 subscribe(observer);
4842 return observer;
4843 }
4844
4845 @SchedulerSupport(SchedulerSupport.NONE)
4846 @Override
4847 public final void subscribe(@NonNull SingleObserver<? super T> observer) {
4848 Objects.requireNonNull(observer, "observer is null");
4849
4850 observer = RxJavaPlugins.onSubscribe(this, observer);
4851
4852 Objects.requireNonNull(observer, "The RxJavaPlugins.onSubscribe hook returned a null SingleObserver. Please check the handler provided to RxJavaPlugins.setOnSingleSubscribe for invalid null returns. Further reading: https://github.com/ReactiveX/RxJava/wiki/Plugins");
4853
4854 try {
4855 subscribeActual(observer);
4856 } catch (NullPointerException ex) {
4857 throw ex;
4858 } catch (Throwable ex) {
4859 Exceptions.throwIfFatal(ex);
4860 NullPointerException npe = new NullPointerException("subscribeActual failed");
4861 npe.initCause(ex);
4862 throw npe;
4863 }
4864 }
4865
4866 /**
4867 * Implement this method in subclasses to handle the incoming {@link SingleObserver}s.
4868 * <p>There is no need to call any of the plugin hooks on the current {@code Single} instance or
4869 * the {@code SingleObserver}; all hooks and basic safeguards have been
4870 * applied by {@link #subscribe(SingleObserver)} before this method gets called.
4871 * @param observer the {@code SingleObserver} to handle, not {@code null}
4872 */
4873 protected abstract void subscribeActual(@NonNull SingleObserver<? super T> observer);
4874
4875 /**
4876 * Subscribes a given {@link SingleObserver} (subclass) to this {@code Single} and returns the given
4877 * {@code SingleObserver} as is.
4878 * <p>
4879 * <img width="640" height="338" src="https://raw.githubusercontent.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.subscribeWith.png" alt="">
4880 * <p>Usage example:
4881 * <pre><code>
4882 * Single&lt;Integer&gt; source = Single.just(1);
4883 * CompositeDisposable composite = new CompositeDisposable();
4884 *
4885 * DisposableSingleObserver&lt;Integer&gt; ds = new DisposableSingleObserver&lt;&gt;() {
4886 * // ...
4887 * };
4888 *
4889 * composite.add(source.subscribeWith(ds));
4890 * </code></pre>
4891 * <dl>
4892 * <dt><b>Scheduler:</b></dt>
4893 * <dd>{@code subscribeWith} does not operate by default on a particular {@link Scheduler}.</dd>
4894 * </dl>
4895 * @param <E> the type of the {@code SingleObserver} to use and return
4896 * @param observer the {@code SingleObserver} (subclass) to use and return, not {@code null}
4897 * @return the input {@code observer}
4898 * @throws NullPointerException if {@code observer} is {@code null}
4899 * @since 2.0
4900 */
4901 @CheckReturnValue
4902 @SchedulerSupport(SchedulerSupport.NONE)
4903 @NonNull
4904 public final <@NonNull E extends SingleObserver<? super T>> E subscribeWith(E observer) {
4905 subscribe(observer);
4906 return observer;
4907 }
4908
4909 /**
4910 * Asynchronously subscribes {@link SingleObserver}s to this {@code Single} on the specified {@link Scheduler}.
4911 * <p>
4912 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.subscribeOn.v3.png" alt="">
4913 * <dl>
4914 * <dt><b>Scheduler:</b></dt>
4915 * <dd>You specify which {@code Scheduler} this operator will use.</dd>
4916 * </dl>
4917 *
4918 * @param scheduler
4919 * the {@code Scheduler} to perform subscription actions on
4920 * @return the new {@code Single} instance
4921 * @throws NullPointerException if {@code scheduler} is {@code null}
4922 * @see <a href="http://reactivex.io/documentation/operators/subscribeon.html">ReactiveX operators documentation: SubscribeOn</a>
4923 * @see <a href="http://www.grahamlea.com/2014/07/rxjava-threading-examples/">RxJava Threading Examples</a>
4924 * @see #observeOn
4925 */
4926 @CheckReturnValue
4927 @NonNull
4928 @SchedulerSupport(SchedulerSupport.CUSTOM)
4929 public final Single<T> subscribeOn(@NonNull Scheduler scheduler) {
4930 Objects.requireNonNull(scheduler, "scheduler is null");
4931 return RxJavaPlugins.onAssembly(new SingleSubscribeOn<>(this, scheduler));
4932 }
4933
4934 /**
4935 * Measures the time (in milliseconds) between the subscription and success item emission
4936 * of the current {@code Single} and signals it as a tuple ({@link Timed})
4937 * success value.
4938 * <p>
4939 * <img width="640" height="466" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.timeInterval.png" alt="">
4940 * <p>
4941 * If the current {@code Single} fails, the resulting {@code Single} will
4942 * pass along the signal to the downstream. To measure the time to error,
4943 * use {@link #materialize()} and apply {@link #timeInterval()}.
4944 * <dl>
4945 * <dt><b>Scheduler:</b></dt>
4946 * <dd>{@code timeInterval} uses the {@code computation} {@link Scheduler}
4947 * for determining the current time upon subscription and upon receiving the
4948 * success item from the current {@code Single}.</dd>
4949 * </dl>
4950 * @return the new {@code Single} instance
4951 * @since 3.0.0
4952 */
4953 @CheckReturnValue
4954 @NonNull
4955 @SchedulerSupport(SchedulerSupport.COMPUTATION)
4956 public final Single<Timed<T>> timeInterval() {
4957 return timeInterval(TimeUnit.MILLISECONDS, Schedulers.computation());
4958 }
4959
4960 /**
4961 * Measures the time (in milliseconds) between the subscription and success item emission
4962 * of the current {@code Single} and signals it as a tuple ({@link Timed})
4963 * success value.
4964 * <p>
4965 * <img width="640" height="463" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.timeInterval.s.png" alt="">
4966 * <p>
4967 * If the current {@code Single} fails, the resulting {@code Single} will
4968 * pass along the signal to the downstream. To measure the time to error,
4969 * use {@link #materialize()} and apply {@link #timeInterval(Scheduler)}.
4970 * <dl>
4971 * <dt><b>Scheduler:</b></dt>
4972 * <dd>{@code timeInterval} uses the provided {@link Scheduler}
4973 * for determining the current time upon subscription and upon receiving the
4974 * success item from the current {@code Single}.</dd>
4975 * </dl>
4976 * @param scheduler the {@code Scheduler} used for providing the current time
4977 * @return the new {@code Single} instance
4978 * @throws NullPointerException if {@code scheduler} is {@code null}
4979 * @since 3.0.0
4980 */
4981 @CheckReturnValue
4982 @NonNull
4983 @SchedulerSupport(SchedulerSupport.CUSTOM)
4984 public final Single<Timed<T>> timeInterval(@NonNull Scheduler scheduler) {
4985 return timeInterval(TimeUnit.MILLISECONDS, scheduler);
4986 }
4987
4988 /**
4989 * Measures the time between the subscription and success item emission
4990 * of the current {@code Single} and signals it as a tuple ({@link Timed})
4991 * success value.
4992 * <p>
4993 * <img width="640" height="466" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.timeInterval.png" alt="">
4994 * <p>
4995 * If the current {@code Single} fails, the resulting {@code Single} will
4996 * pass along the signals to the downstream. To measure the time to error,
4997 * use {@link #materialize()} and apply {@link #timeInterval(TimeUnit, Scheduler)}.
4998 * <dl>
4999 * <dt><b>Scheduler:</b></dt>
5000 * <dd>{@code timeInterval} uses the {@code computation} {@link Scheduler}
5001 * for determining the current time upon subscription and upon receiving the
5002 * success item from the current {@code Single}.</dd>
5003 * </dl>
5004 * @param unit the time unit for measurement
5005 * @return the new {@code Single} instance
5006 * @throws NullPointerException if {@code unit} is {@code null}
5007 * @since 3.0.0
5008 */
5009 @CheckReturnValue
5010 @NonNull
5011 @SchedulerSupport(SchedulerSupport.COMPUTATION)
5012 public final Single<Timed<T>> timeInterval(@NonNull TimeUnit unit) {
5013 return timeInterval(unit, Schedulers.computation());
5014 }
5015
5016 /**
5017 * Measures the time between the subscription and success item emission
5018 * of the current {@code Single} and signals it as a tuple ({@link Timed})
5019 * success value.
5020 * <p>
5021 * <img width="640" height="463" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.timeInterval.s.png" alt="">
5022 * <p>
5023 * If the current {@code Single} is empty or fails, the resulting {@code Single} will
5024 * pass along the signals to the downstream. To measure the time to termination,
5025 * use {@link #materialize()} and apply {@link #timeInterval(TimeUnit, Scheduler)}.
5026 * <dl>
5027 * <dt><b>Scheduler:</b></dt>
5028 * <dd>{@code timeInterval} uses the provided {@link Scheduler}
5029 * for determining the current time upon subscription and upon receiving the
5030 * success item from the current {@code Single}.</dd>
5031 * </dl>
5032 * @param unit the time unit for measurement
5033 * @param scheduler the {@code Scheduler} used for providing the current time
5034 * @return the new {@code Single} instance
5035 * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null}
5036 * @since 3.0.0
5037 */
5038 @CheckReturnValue
5039 @NonNull
5040 @SchedulerSupport(SchedulerSupport.CUSTOM)
5041 public final Single<Timed<T>> timeInterval(@NonNull TimeUnit unit, @NonNull Scheduler scheduler) {
5042 Objects.requireNonNull(unit, "unit is null");
5043 Objects.requireNonNull(scheduler, "scheduler is null");
5044 return RxJavaPlugins.onAssembly(new SingleTimeInterval<>(this, unit, scheduler, true));
5045 }
5046
5047 /**
5048 * Combines the success value from the current {@code Single} with the current time (in milliseconds) of
5049 * its reception, using the {@code computation} {@link Scheduler} as time source,
5050 * then signals them as a {@link Timed} instance.
5051 * <p>
5052 * <img width="640" height="465" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.timestamp.png" alt="">
5053 * <p>
5054 * If the current {@code Single} is empty or fails, the resulting {@code Single} will
5055 * pass along the signals to the downstream. To get the timestamp of the error,
5056 * use {@link #materialize()} and apply {@link #timestamp()}.
5057 * <dl>
5058 * <dt><b>Scheduler:</b></dt>
5059 * <dd>{@code timestamp} uses the {@code computation} {@code Scheduler}
5060 * for determining the current time upon receiving the
5061 * success item from the current {@code Single}.</dd>
5062 * </dl>
5063 * @return the new {@code Single} instance
5064 * @since 3.0.0
5065 */
5066 @CheckReturnValue
5067 @NonNull
5068 @SchedulerSupport(SchedulerSupport.COMPUTATION)
5069 public final Single<Timed<T>> timestamp() {
5070 return timestamp(TimeUnit.MILLISECONDS, Schedulers.computation());
5071 }
5072
5073 /**
5074 * Combines the success value from the current {@code Single} with the current time (in milliseconds) of
5075 * its reception, using the given {@link Scheduler} as time source,
5076 * then signals them as a {@link Timed} instance.
5077 * <p>
5078 * <img width="640" height="465" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.timestamp.s.png" alt="">
5079 * <p>
5080 * If the current {@code Single} is empty or fails, the resulting {@code Single} will
5081 * pass along the signals to the downstream. To get the timestamp of the error,
5082 * use {@link #materialize()} and apply {@link #timestamp(Scheduler)}.
5083 * <dl>
5084 * <dt><b>Scheduler:</b></dt>
5085 * <dd>{@code timestamp} uses the provided {@code Scheduler}
5086 * for determining the current time upon receiving the
5087 * success item from the current {@code Single}.</dd>
5088 * </dl>
5089 * @param scheduler the {@code Scheduler} used for providing the current time
5090 * @return the new {@code Single} instance
5091 * @throws NullPointerException if {@code scheduler} is {@code null}
5092 * @since 3.0.0
5093 */
5094 @CheckReturnValue
5095 @NonNull
5096 @SchedulerSupport(SchedulerSupport.CUSTOM)
5097 public final Single<Timed<T>> timestamp(@NonNull Scheduler scheduler) {
5098 return timestamp(TimeUnit.MILLISECONDS, scheduler);
5099 }
5100
5101 /**
5102 * Combines the success value from the current {@code Single} with the current time of
5103 * its reception, using the {@code computation} {@link Scheduler} as time source,
5104 * then signals it as a {@link Timed} instance.
5105 * <p>
5106 * <img width="640" height="465" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.timestamp.png" alt="">
5107 * <p>
5108 * If the current {@code Single} is empty or fails, the resulting {@code Single} will
5109 * pass along the signals to the downstream. To get the timestamp of the error,
5110 * use {@link #materialize()} and apply {@link #timestamp(TimeUnit)}.
5111 * <dl>
5112 * <dt><b>Scheduler:</b></dt>
5113 * <dd>{@code timestamp} uses the {@code computation} {@code Scheduler},
5114 * for determining the current time upon receiving the
5115 * success item from the current {@code Single}.</dd>
5116 * </dl>
5117 * @param unit the time unit for measurement
5118 * @return the new {@code Single} instance
5119 * @throws NullPointerException if {@code unit} is {@code null}
5120 * @since 3.0.0
5121 */
5122 @CheckReturnValue
5123 @NonNull
5124 @SchedulerSupport(SchedulerSupport.COMPUTATION)
5125 public final Single<Timed<T>> timestamp(@NonNull TimeUnit unit) {
5126 return timestamp(unit, Schedulers.computation());
5127 }
5128
5129 /**
5130 * Combines the success value from the current {@code Single} with the current time of
5131 * its reception, using the given {@link Scheduler} as time source,
5132 * then signals it as a {@link Timed} instance.
5133 * <p>
5134 * <img width="640" height="465" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.timestamp.s.png" alt="">
5135 * <p>
5136 * If the current {@code Single} is empty or fails, the resulting {@code Single} will
5137 * pass along the signals to the downstream. To get the timestamp of the error,
5138 * use {@link #materialize()} and apply {@link #timestamp(TimeUnit, Scheduler)}.
5139 * <dl>
5140 * <dt><b>Scheduler:</b></dt>
5141 * <dd>{@code timestamp} uses the provided {@code Scheduler},
5142 * which is used for determining the current time upon receiving the
5143 * success item from the current {@code Single}.</dd>
5144 * </dl>
5145 * @param unit the time unit for measurement
5146 * @param scheduler the {@code Scheduler} used for providing the current time
5147 * @return the new {@code Single} instance
5148 * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null}
5149 * @since 3.0.0
5150 */
5151 @CheckReturnValue
5152 @NonNull
5153 @SchedulerSupport(SchedulerSupport.CUSTOM)
5154 public final Single<Timed<T>> timestamp(@NonNull TimeUnit unit, @NonNull Scheduler scheduler) {
5155 Objects.requireNonNull(unit, "unit is null");
5156 Objects.requireNonNull(scheduler, "scheduler is null");
5157 return RxJavaPlugins.onAssembly(new SingleTimeInterval<>(this, unit, scheduler, false));
5158 }
5159
5160 /**
5161 * Returns a {@code Single} that emits the item emitted by the current {@code Single} until a {@link CompletableSource} terminates. Upon
5162 * termination of {@code other}, this will emit a {@link CancellationException} rather than go to
5163 * {@link SingleObserver#onSuccess(Object)}.
5164 * <p>
5165 * <img width="640" height="333" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.takeUntil.c.png" alt="">
5166 * <dl>
5167 * <dt><b>Scheduler:</b></dt>
5168 * <dd>{@code takeUntil} does not operate by default on a particular {@link Scheduler}.</dd>
5169 * </dl>
5170 *
5171 * @param other
5172 * the {@code CompletableSource} whose termination will cause {@code takeUntil} to emit the item from the current
5173 * {@code Single}
5174 * @return the new {@code Single} that emits the item emitted by the current {@code Single} until such time as {@code other} terminates.
5175 * @throws NullPointerException if {@code other} is {@code null}
5176 * @see <a href="http://reactivex.io/documentation/operators/takeuntil.html">ReactiveX operators documentation: TakeUntil</a>
5177 */
5178 @CheckReturnValue
5179 @NonNull
5180 @SchedulerSupport(SchedulerSupport.NONE)
5181 public final Single<T> takeUntil(@NonNull CompletableSource other) {
5182 Objects.requireNonNull(other, "other is null");
5183 return takeUntil(new CompletableToFlowable<T>(other));
5184 }
5185
5186 /**
5187 * Returns a {@code Single} that emits the item emitted by the current {@code Single} until a {@link Publisher} emits an item or completes. Upon
5188 * emission of an item from {@code other}, this will emit a {@link CancellationException} rather than go to
5189 * {@link SingleObserver#onSuccess(Object)}.
5190 * <p>
5191 * <img width="640" height="215" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.takeUntil.p.png" alt="">
5192 * <dl>
5193 * <dt><b>Backpressure:</b></dt>
5194 * <dd>The {@code other} publisher is consumed in an unbounded fashion but will be
5195 * cancelled after the first item it produced.</dd>
5196 * <dt><b>Scheduler:</b></dt>
5197 * <dd>{@code takeUntil} does not operate by default on a particular {@link Scheduler}.</dd>
5198 * </dl>
5199 *
5200 * @param other
5201 * the {@code Publisher} whose first emitted item or completion will cause {@code takeUntil} to emit {@code CancellationException}
5202 * if the current {@code Single} hasn't completed till then
5203 * @param <E>
5204 * the type of items emitted by {@code other}
5205 * @return the new {@code Single} that emits the item emitted by the current {@code Single} until such time as {@code other} emits
5206 * its first item
5207 * @throws NullPointerException if {@code other} is {@code null}
5208 * @see <a href="http://reactivex.io/documentation/operators/takeuntil.html">ReactiveX operators documentation: TakeUntil</a>
5209 */
5210 @BackpressureSupport(BackpressureKind.FULL)
5211 @CheckReturnValue
5212 @NonNull
5213 @SchedulerSupport(SchedulerSupport.NONE)
5214 public final <@NonNull E> Single<T> takeUntil(@NonNull Publisher<E> other) {
5215 Objects.requireNonNull(other, "other is null");
5216 return RxJavaPlugins.onAssembly(new SingleTakeUntil<>(this, other));
5217 }
5218
5219 /**
5220 * Returns a {@code Single} that emits the item emitted by the current {@code Single} until a second {@code Single} emits an item. Upon
5221 * emission of an item from {@code other}, this will emit a {@link CancellationException} rather than go to
5222 * {@link SingleObserver#onSuccess(Object)}.
5223 * <p>
5224 * <img width="640" height="314" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.takeUntil.s.png" alt="">
5225 * <dl>
5226 * <dt><b>Scheduler:</b></dt>
5227 * <dd>{@code takeUntil} does not operate by default on a particular {@link Scheduler}.</dd>
5228 * </dl>
5229 *
5230 * @param other
5231 * the {@code Single} whose emitted item will cause {@code takeUntil} to emit {@code CancellationException}
5232 * if the current {@code Single} hasn't completed till then
5233 * @param <E>
5234 * the type of item emitted by {@code other}
5235 * @return the new {@code Single} that emits the item emitted by the current {@code Single} until such time as {@code other} emits its item
5236 * @throws NullPointerException if {@code other} is {@code null}
5237 * @see <a href="http://reactivex.io/documentation/operators/takeuntil.html">ReactiveX operators documentation: TakeUntil</a>
5238 */
5239 @CheckReturnValue
5240 @NonNull
5241 @SchedulerSupport(SchedulerSupport.NONE)
5242 public final <@NonNull E> Single<T> takeUntil(@NonNull SingleSource<? extends E> other) {
5243 Objects.requireNonNull(other, "other is null");
5244 return takeUntil(new SingleToFlowable<E>(other));
5245 }
5246
5247 /**
5248 * Signals a {@link TimeoutException} if the current {@code Single} doesn't signal a success value within the
5249 * specified timeout window.
5250 * <p>
5251 * <img width="640" height="334" src="https://raw.githubusercontent.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.timeout.png" alt="">
5252 * <dl>
5253 * <dt><b>Scheduler:</b></dt>
5254 * <dd>{@code timeout} signals the {@code TimeoutException} on the {@code computation} {@link Scheduler}.</dd>
5255 * </dl>
5256 * @param timeout the timeout amount
5257 * @param unit the time unit
5258 * @return the new {@code Single} instance
5259 * @throws NullPointerException if {@code unit} is {@code null}
5260 * @since 2.0
5261 */
5262 @CheckReturnValue
5263 @SchedulerSupport(SchedulerSupport.COMPUTATION)
5264 @NonNull
5265 public final Single<T> timeout(long timeout, @NonNull TimeUnit unit) {
5266 return timeout0(timeout, unit, Schedulers.computation(), null);
5267 }
5268
5269 /**
5270 * Signals a {@link TimeoutException} if the current {@code Single} doesn't signal a success value within the
5271 * specified timeout window.
5272 * <p>
5273 * <img width="640" height="334" src="https://raw.githubusercontent.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.timeout.s.png" alt="">
5274 * <dl>
5275 * <dt><b>Scheduler:</b></dt>
5276 * <dd>{@code timeout} signals the {@code TimeoutException} on the {@link Scheduler} you specify.</dd>
5277 * </dl>
5278 * @param timeout the timeout amount
5279 * @param unit the time unit
5280 * @param scheduler the target {@code Scheduler} where the timeout is awaited and the {@code TimeoutException}
5281 * signaled
5282 * @return the new {@code Single} instance
5283 * @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null}
5284 * @since 2.0
5285 */
5286 @CheckReturnValue
5287 @SchedulerSupport(SchedulerSupport.CUSTOM)
5288 @NonNull
5289 public final Single<T> timeout(long timeout, @NonNull TimeUnit unit, @NonNull Scheduler scheduler) {
5290 return timeout0(timeout, unit, scheduler, null);
5291 }
5292
5293 /**
5294 * Runs the current {@code Single} and if it doesn't signal within the specified timeout window, it is
5295 * disposed and the other {@link SingleSource} subscribed to.
5296 * <p>
5297 * <img width="640" height="283" src="https://raw.githubusercontent.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.timeout.sb.png" alt="">
5298 * <dl>
5299 * <dt><b>Scheduler:</b></dt>
5300 * <dd>{@code timeout} subscribes to the other {@code SingleSource} on the {@link Scheduler} you specify.</dd>
5301 * </dl>
5302 * @param timeout the timeout amount
5303 * @param unit the time unit
5304 * @param scheduler the {@code Scheduler} where the timeout is awaited and the subscription to other happens
5305 * @param fallback the other {@code SingleSource} that gets subscribed to if the current {@code Single} times out
5306 * @return the new {@code Single} instance
5307 * @throws NullPointerException if {@code unit}, {@code scheduler} or {@code fallback} is {@code null}
5308 * @since 2.0
5309 */
5310 @CheckReturnValue
5311 @NonNull
5312 @SchedulerSupport(SchedulerSupport.CUSTOM)
5313 public final Single<T> timeout(long timeout, @NonNull TimeUnit unit, @NonNull Scheduler scheduler, @NonNull SingleSource<? extends T> fallback) {
5314 Objects.requireNonNull(fallback, "fallback is null");
5315 return timeout0(timeout, unit, scheduler, fallback);
5316 }
5317
5318 /**
5319 * Runs the current {@code Single} and if it doesn't signal within the specified timeout window, it is
5320 * disposed and the other {@link SingleSource} subscribed to.
5321 * <p>
5322 * <img width="640" height="282" src="https://raw.githubusercontent.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.timeout.b.png" alt="">
5323 * <dl>
5324 * <dt><b>Scheduler:</b></dt>
5325 * <dd>{@code timeout} subscribes to the other {@code SingleSource} on
5326 * the {@code computation} {@link Scheduler}.</dd>
5327 * </dl>
5328 * @param timeout the timeout amount
5329 * @param unit the time unit
5330 * @param fallback the other {@code SingleSource} that gets subscribed to if the current {@code Single} times out
5331 * @return the new {@code Single} instance
5332 * @throws NullPointerException
5333 * if {@code fallback} or {@code unit} is {@code null}
5334 * @since 2.0
5335 */
5336 @CheckReturnValue
5337 @NonNull
5338 @SchedulerSupport(SchedulerSupport.COMPUTATION)
5339 public final Single<T> timeout(long timeout, @NonNull TimeUnit unit, @NonNull SingleSource<? extends T> fallback) {
5340 Objects.requireNonNull(fallback, "fallback is null");
5341 return timeout0(timeout, unit, Schedulers.computation(), fallback);
5342 }
5343
5344 private Single<T> timeout0(final long timeout, final TimeUnit unit, final Scheduler scheduler, final SingleSource<? extends T> fallback) {
5345 Objects.requireNonNull(unit, "unit is null");
5346 Objects.requireNonNull(scheduler, "scheduler is null");
5347 return RxJavaPlugins.onAssembly(new SingleTimeout<>(this, timeout, unit, scheduler, fallback));
5348 }
5349
5350 /**
5351 * Calls the specified converter function during assembly time and returns its resulting value.
5352 * <p>
5353 * <img width="640" height="553" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.to.v3.png" alt="">
5354 * <p>
5355 * This allows fluent conversion to any other type.
5356 * <dl>
5357 * <dt><b>Scheduler:</b></dt>
5358 * <dd>{@code to} does not operate by default on a particular {@link Scheduler}.</dd>
5359 * </dl>
5360 * <p>History: 2.1.7 - experimental
5361 * @param <R> the resulting object type
5362 * @param converter the function that receives the current {@code Single} instance and returns a value
5363 * @return the converted value
5364 * @throws NullPointerException if {@code converter} is {@code null}
5365 * @since 2.2
5366 */
5367 @CheckReturnValue
5368 @SchedulerSupport(SchedulerSupport.NONE)
5369 public final <R> R to(@NonNull SingleConverter<T, ? extends R> converter) {
5370 return Objects.requireNonNull(converter, "converter is null").apply(this);
5371 }
5372
5373 /**
5374 * Returns a {@link Completable} that ignores the success value of this {@code Single}
5375 * and signals {@code onComplete} instead.
5376 * <p>
5377 * <img width="640" height="436" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.ignoreElement.png" alt="">
5378 * <dl>
5379 * <dt><b>Scheduler:</b></dt>
5380 * <dd>{@code ignoreElement} does not operate by default on a particular {@link Scheduler}.</dd>
5381 * </dl>
5382 *
5383 * @return the new {@code Completable} instance
5384 * @since 2.1.13
5385 */
5386 @CheckReturnValue
5387 @SchedulerSupport(SchedulerSupport.NONE)
5388 @NonNull
5389 public final Completable ignoreElement() {
5390 return RxJavaPlugins.onAssembly(new CompletableFromSingle<>(this));
5391 }
5392
5393 /**
5394 * Converts this {@code Single} into a {@link Flowable}.
5395 * <p>
5396 * <img width="640" height="462" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.toFlowable.v3.png" alt="">
5397 * <dl>
5398 * <dt><b>Backpressure:</b></dt>
5399 * <dd>The returned {@code Flowable} honors the backpressure of the downstream consumer.</dd>
5400 * <dt><b>Scheduler:</b></dt>
5401 * <dd>{@code toFlowable} does not operate by default on a particular {@link Scheduler}.</dd>
5402 * </dl>
5403 *
5404 * @return the new {@code Flowable} instance
5405 */
5406 @BackpressureSupport(BackpressureKind.FULL)
5407 @CheckReturnValue
5408 @SchedulerSupport(SchedulerSupport.NONE)
5409 @SuppressWarnings("unchecked")
5410 @NonNull
5411 public final Flowable<T> toFlowable() {
5412 if (this instanceof FuseToFlowable) {
5413 return ((FuseToFlowable<T>)this).fuseToFlowable();
5414 }
5415 return RxJavaPlugins.onAssembly(new SingleToFlowable<>(this));
5416 }
5417
5418 /**
5419 * Returns a {@link Future} representing the single value emitted by this {@code Single}.
5420 * <p>
5421 * <img width="640" height="467" src="https://github.com/ReactiveX/RxJava/wiki/images/rx-operators/Single.toFuture.v3.png" alt="">
5422 * <p>
5423 * Cancelling the {@code Future} will cancel the subscription to the current {@code Single}.
5424 * <dl>
5425 * <dt><b>Scheduler:</b></dt>
5426 * <dd>{@code toFuture} does not operate by default on a particular {@link Scheduler}.</dd>
5427 * </dl>
5428 *
5429 * @return the new {@code Future} instance
5430 * @see <a href="http://reactivex.io/documentation/operators/to.html">ReactiveX documentation: To</a>
5431 */
5432 @CheckReturnValue
5433 @SchedulerSupport(SchedulerSupport.NONE)
5434 @NonNull
5435 public final Future<T> toFuture() {
5436 return subscribeWith(new FutureMultiObserver<>());
5437 }
5438
5439 /**
5440 * Converts this {@code Single} into a {@link Maybe}.
5441 * <p>
5442 * <img width="640" height="463" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.toMaybe.v3.png" alt="">
5443 * <dl>
5444 * <dt><b>Scheduler:</b></dt>
5445 * <dd>{@code toMaybe} does not operate by default on a particular {@link Scheduler}.</dd>
5446 * </dl>
5447 *
5448 * @return the new {@code Maybe} instance
5449 */
5450 @CheckReturnValue
5451 @SchedulerSupport(SchedulerSupport.NONE)
5452 @SuppressWarnings("unchecked")
5453 @NonNull
5454 public final Maybe<T> toMaybe() {
5455 if (this instanceof FuseToMaybe) {
5456 return ((FuseToMaybe<T>)this).fuseToMaybe();
5457 }
5458 return RxJavaPlugins.onAssembly(new MaybeFromSingle<>(this));
5459 }
5460 /**
5461 * Converts this {@code Single} into an {@link Observable}.
5462 * <p>
5463 * <img width="640" height="305" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.toObservable.v3.png" alt="">
5464 * <dl>
5465 * <dt><b>Scheduler:</b></dt>
5466 * <dd>{@code toObservable} does not operate by default on a particular {@link Scheduler}.</dd>
5467 * </dl>
5468 *
5469 * @return the new {@code Observable} instance
5470 */
5471 @CheckReturnValue
5472 @SchedulerSupport(SchedulerSupport.NONE)
5473 @SuppressWarnings("unchecked")
5474 @NonNull
5475 public final Observable<T> toObservable() {
5476 if (this instanceof FuseToObservable) {
5477 return ((FuseToObservable<T>)this).fuseToObservable();
5478 }
5479 return RxJavaPlugins.onAssembly(new SingleToObservable<>(this));
5480 }
5481
5482 /**
5483 * Returns a {@code Single} which makes sure when a {@link SingleObserver} disposes the {@link Disposable},
5484 * that call is propagated up on the specified {@link Scheduler}.
5485 * <p>
5486 * <img width="640" height="693" src="https://raw.githubusercontent.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.unsubscribeOn.png" alt="">
5487 * <dl>
5488 * <dt><b>Scheduler:</b></dt>
5489 * <dd>{@code unsubscribeOn} calls {@code dispose()} of the upstream on the {@code Scheduler} you specify.</dd>
5490 * </dl>
5491 * <p>History: 2.0.9 - experimental
5492 * @param scheduler the target scheduler where to execute the disposal
5493 * @return the new {@code Single} instance
5494 * @throws NullPointerException if {@code scheduler} is {@code null}
5495 * @since 2.2
5496 */
5497 @CheckReturnValue
5498 @NonNull
5499 @SchedulerSupport(SchedulerSupport.CUSTOM)
5500 public final Single<T> unsubscribeOn(@NonNull Scheduler scheduler) {
5501 Objects.requireNonNull(scheduler, "scheduler is null");
5502 return RxJavaPlugins.onAssembly(new SingleUnsubscribeOn<>(this, scheduler));
5503 }
5504
5505 /**
5506 * Returns a {@code Single} that emits the result of applying a specified function to the pair of items emitted by
5507 * the current {@code Single} and another specified {@link SingleSource}.
5508 * <p>
5509 * <img width="640" height="422" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.zipWith.png" alt="">
5510 * <dl>
5511 * <dt><b>Scheduler:</b></dt>
5512 * <dd>{@code zipWith} does not operate by default on a particular {@link Scheduler}.</dd>
5513 * </dl>
5514 *
5515 * @param <U>
5516 * the type of items emitted by the {@code other} {@code Single}
5517 * @param <R>
5518 * the type of items emitted by the resulting {@code Single}
5519 * @param other
5520 * the other {@code SingleSource}
5521 * @param zipper
5522 * a function that combines the pairs of items from the two {@code SingleSource}s to generate the items to
5523 * be emitted by the resulting {@code Single}
5524 * @return the new {@code Single} that pairs up values from the current {@code Single} and the {@code other} {@code SingleSource}
5525 * and emits the results of {@code zipFunction} applied to these pairs
5526 * @throws NullPointerException if {@code other} or {@code zipper} is {@code null}
5527 * @see <a href="http://reactivex.io/documentation/operators/zip.html">ReactiveX operators documentation: Zip</a>
5528 */
5529 @CheckReturnValue
5530 @SchedulerSupport(SchedulerSupport.NONE)
5531 @NonNull
5532 public final <@NonNull U, @NonNull R> Single<R> zipWith(@NonNull SingleSource<U> other, @NonNull BiFunction<? super T, ? super U, ? extends R> zipper) {
5533 return zip(this, other, zipper);
5534 }
5535
5536 // -------------------------------------------------------------------------
5537 // Fluent test support, super handy and reduces test preparation boilerplate
5538 // -------------------------------------------------------------------------
5539 /**
5540 * Creates a {@link TestObserver} and subscribes it to this {@code Single}.
5541 * <p>
5542 * <img width="640" height="442" src="https://raw.githubusercontent.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.test.png" alt="">
5543 * <dl>
5544 * <dt><b>Scheduler:</b></dt>
5545 * <dd>{@code test} does not operate by default on a particular {@link Scheduler}.</dd>
5546 * </dl>
5547 * @return the new {@code TestObserver} instance
5548 * @since 2.0
5549 */
5550 @CheckReturnValue
5551 @SchedulerSupport(SchedulerSupport.NONE)
5552 @NonNull
5553 public final TestObserver<T> test() {
5554 TestObserver<T> to = new TestObserver<>();
5555 subscribe(to);
5556 return to;
5557 }
5558
5559 /**
5560 * Creates a {@link TestObserver} optionally in cancelled state, then subscribes it to this {@code Single}.
5561 * <p>
5562 * <img width="640" height="482" src="https://raw.githubusercontent.com/wiki/ReactiveX/RxJava/images/rx-operators/Single.test.b.png" alt="">
5563 * <dl>
5564 * <dt><b>Scheduler:</b></dt>
5565 * <dd>{@code test} does not operate by default on a particular {@link Scheduler}.</dd>
5566 * </dl>
5567 * @param dispose if {@code true}, the {@code TestObserver} will be cancelled before subscribing to this
5568 * {@code Single}.
5569 * @return the new {@code TestObserver} instance
5570 * @since 2.0
5571 */
5572 @CheckReturnValue
5573 @SchedulerSupport(SchedulerSupport.NONE)
5574 @NonNull
5575 public final TestObserver<T> test(boolean dispose) {
5576 TestObserver<T> to = new TestObserver<>();
5577
5578 if (dispose) {
5579 to.dispose();
5580 }
5581
5582 subscribe(to);
5583 return to;
5584 }
5585
5586 @NonNull
5587 private static <T> Single<T> toSingle(@NonNull Flowable<T> source) {
5588 return RxJavaPlugins.onAssembly(new FlowableSingleSingle<>(source, null));
5589 }
5590
5591 // -------------------------------------------------------------------------
5592 // JDK 8 Support
5593 // -------------------------------------------------------------------------
5594
5595 /**
5596 * Signals the completion value or error of the given (hot) {@link CompletionStage}-based asynchronous calculation.
5597 * <p>
5598 * <img width="640" height="262" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/fromCompletionStage.s.png" alt="">
5599 * <p>
5600 * Note that the operator takes an already instantiated, running or terminated {@code CompletionStage}.
5601 * If the optional is to be created per consumer upon subscription, use {@link #defer(Supplier)}
5602 * around {@code fromCompletionStage}:
5603 * <pre><code>
5604 * Single.defer(() -&gt; Single.fromCompletionStage(createCompletionStage()));
5605 * </code></pre>
5606 * <p>
5607 * If the {@code CompletionStage} completes with {@code null}, the resulting {@code Single} is terminated with
5608 * a {@link NullPointerException}.
5609 * <p>
5610 * Canceling the flow can't cancel the execution of the {@code CompletionStage} because {@code CompletionStage}
5611 * itself doesn't support cancellation. Instead, the operator detaches from the {@code CompletionStage}.
5612 * <dl>
5613 * <dt><b>Scheduler:</b></dt>
5614 * <dd>{@code fromCompletionStage} does not operate by default on a particular {@link Scheduler}.</dd>
5615 * </dl>
5616 * @param <T> the element type of the {@code CompletionStage}
5617 * @param stage the {@code CompletionStage} to convert to {@code Single} and signal its success value or error
5618 * @return the new {@code Single} instance
5619 * @throws NullPointerException if {@code stage} is {@code null}
5620 * @since 3.0.0
5621 */
5622 @CheckReturnValue
5623 @SchedulerSupport(SchedulerSupport.NONE)
5624 @NonNull
5625 public static <@NonNull T> Single<@NonNull T> fromCompletionStage(@NonNull CompletionStage<T> stage) {
5626 Objects.requireNonNull(stage, "stage is null");
5627 return RxJavaPlugins.onAssembly(new SingleFromCompletionStage<>(stage));
5628 }
5629
5630 /**
5631 * Maps the upstream success value into an {@link Optional} and emits the contained item if not empty as a {@link Maybe}.
5632 * <p>
5633 * <img width="640" height="323" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/mapOptional.s.png" alt="">
5634 *
5635 * <dl>
5636 * <dt><b>Scheduler:</b></dt>
5637 * <dd>{@code mapOptional} does not operate by default on a particular {@link Scheduler}.</dd>
5638 * </dl>
5639 * @param <R> the non-{@code null} output type
5640 * @param mapper the function that receives the upstream success item and should return a <em>non-empty</em> {@code Optional}
5641 * to emit as the success output or an <em>empty</em> {@code Optional} to complete the {@code Maybe}
5642 * @return the new {@code Maybe} instance
5643 * @throws NullPointerException if {@code mapper} is {@code null}
5644 * @since 3.0.0
5645 * @see #map(Function)
5646 * @see #filter(Predicate)
5647 */
5648 @CheckReturnValue
5649 @SchedulerSupport(SchedulerSupport.NONE)
5650 @NonNull
5651 public final <@NonNull R> Maybe<R> mapOptional(@NonNull Function<? super T, @NonNull Optional<? extends R>> mapper) {
5652 Objects.requireNonNull(mapper, "mapper is null");
5653 return RxJavaPlugins.onAssembly(new SingleMapOptional<>(this, mapper));
5654 }
5655
5656 /**
5657 * Signals the upstream success item (or error) via a {@link CompletionStage}.
5658 * <p>
5659 * <img width="640" height="321" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/toCompletionStage.s.png" alt="">
5660 * <p>
5661 * The upstream can be canceled by converting the resulting {@code CompletionStage} into
5662 * {@link CompletableFuture} via {@link CompletionStage#toCompletableFuture()} and
5663 * calling {@link CompletableFuture#cancel(boolean)} on it.
5664 * The upstream will be also cancelled if the resulting {@code CompletionStage} is converted to and
5665 * completed manually by {@link CompletableFuture#complete(Object)} or {@link CompletableFuture#completeExceptionally(Throwable)}.
5666 * <dl>
5667 * <dt><b>Scheduler:</b></dt>
5668 * <dd>{@code toCompletionStage} does not operate by default on a particular {@link Scheduler}.</dd>
5669 * </dl>
5670 * @return the new {@code CompletionStage} instance
5671 * @since 3.0.0
5672 */
5673 @CheckReturnValue
5674 @SchedulerSupport(SchedulerSupport.NONE)
5675 @NonNull
5676 public final CompletionStage<T> toCompletionStage() {
5677 return subscribeWith(new CompletionStageConsumer<>(false, null));
5678 }
5679
5680 /**
5681 * Maps the upstream succecss value into a Java {@link Stream} and emits its
5682 * items to the downstream consumer as a {@link Flowable}.
5683 * <img width="640" height="247" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/flattenStreamAsFlowable.s.png" alt="">
5684 * <p>
5685 * The operator closes the {@code Stream} upon cancellation and when it terminates. The exceptions raised when
5686 * closing a {@code Stream} are routed to the global error handler ({@link RxJavaPlugins#onError(Throwable)}.
5687 * If a {@code Stream} should not be closed, turn it into an {@link Iterable} and use {@link #flattenAsFlowable(Function)}:
5688 * <pre><code>
5689 * source.flattenAsFlowable(item -&gt; createStream(item)::iterator);
5690 * </code></pre>
5691 * <p>
5692 * Primitive streams are not supported and items have to be boxed manually (e.g., via {@link IntStream#boxed()}):
5693 * <pre><code>
5694 * source.flattenStreamAsFlowable(item -&gt; IntStream.rangeClosed(1, 10).boxed());
5695 * </code></pre>
5696 * <p>
5697 * {@code Stream} does not support concurrent usage so creating and/or consuming the same instance multiple times
5698 * from multiple threads can lead to undefined behavior.
5699 * <dl>
5700 * <dt><b>Backpressure:</b></dt>
5701 * <dd>The operator honors backpressure from downstream and iterates the given {@code Stream}
5702 * on demand (i.e., when requested).</dd>
5703 * <dt><b>Scheduler:</b></dt>
5704 * <dd>{@code flattenStreamAsFlowable} does not operate by default on a particular {@link Scheduler}.</dd>
5705 * </dl>
5706 * @param <R> the element type of the {@code Stream} and the output {@code Flowable}
5707 * @param mapper the function that receives the upstream success item and should
5708 * return a {@code Stream} of values to emit.
5709 * @return the new {@code Flowable} instance
5710 * @throws NullPointerException if {@code mapper} is {@code null}
5711 * @since 3.0.0
5712 * @see #flattenAsFlowable(Function)
5713 * @see #flattenStreamAsObservable(Function)
5714 */
5715 @CheckReturnValue
5716 @SchedulerSupport(SchedulerSupport.NONE)
5717 @BackpressureSupport(BackpressureKind.FULL)
5718 @NonNull
5719 public final <@NonNull R> Flowable<R> flattenStreamAsFlowable(@NonNull Function<? super T, @NonNull ? extends Stream<? extends R>> mapper) {
5720 Objects.requireNonNull(mapper, "mapper is null");
5721 return RxJavaPlugins.onAssembly(new SingleFlattenStreamAsFlowable<>(this, mapper));
5722 }
5723
5724 /**
5725 * Maps the upstream succecss value into a Java {@link Stream} and emits its
5726 * items to the downstream consumer as an {@link Observable}.
5727 * <p>
5728 * <img width="640" height="241" src="https://raw.github.com/wiki/ReactiveX/RxJava/images/rx-operators/flattenStreamAsObservable.s.png" alt="">
5729 * <p>
5730 * The operator closes the {@code Stream} upon cancellation and when it terminates. The exceptions raised when
5731 * closing a {@code Stream} are routed to the global error handler ({@link RxJavaPlugins#onError(Throwable)}.
5732 * If a {@code Stream} should not be closed, turn it into an {@link Iterable} and use {@link #flattenAsObservable(Function)}:
5733 * <pre><code>
5734 * source.flattenAsObservable(item -&gt; createStream(item)::iterator);
5735 * </code></pre>
5736 * <p>
5737 * Primitive streams are not supported and items have to be boxed manually (e.g., via {@link IntStream#boxed()}):
5738 * <pre><code>
5739 * source.flattenStreamAsObservable(item -&gt; IntStream.rangeClosed(1, 10).boxed());
5740 * </code></pre>
5741 * <p>
5742 * {@code Stream} does not support concurrent usage so creating and/or consuming the same instance multiple times
5743 * from multiple threads can lead to undefined behavior.
5744 * <dl>
5745 * <dt><b>Scheduler:</b></dt>
5746 * <dd>{@code flattenStreamAsObservable} does not operate by default on a particular {@link Scheduler}.</dd>
5747 * </dl>
5748 * @param <R> the element type of the {@code Stream} and the output {@code Observable}
5749 * @param mapper the function that receives the upstream success item and should
5750 * return a {@code Stream} of values to emit.
5751 * @return the new {@code Observable} instance
5752 * @throws NullPointerException if {@code mapper} is {@code null}
5753 * @since 3.0.0
5754 * @see #flattenAsObservable(Function)
5755 * @see #flattenStreamAsFlowable(Function)
5756 */
5757 @CheckReturnValue
5758 @SchedulerSupport(SchedulerSupport.NONE)
5759 @NonNull
5760 public final <@NonNull R> Observable<R> flattenStreamAsObservable(@NonNull Function<? super T, @NonNull ? extends Stream<? extends R>> mapper) {
5761 Objects.requireNonNull(mapper, "mapper is null");
5762 return RxJavaPlugins.onAssembly(new SingleFlattenStreamAsObservable<>(this, mapper));
5763 }
5764 }