Debian Codegraph @

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