io.reactivex.rxjava3.core.Maybe Maven / Gradle / Ivy
Show all versions of rxjava Show documentation
/*
* Copyright (c) 2016-present, RxJava Contributors.
*
* Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in
* compliance with the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software distributed under the License is
* distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See
* the License for the specific language governing permissions and limitations under the License.
*/
package io.reactivex.rxjava3.core;
import java.util.*;
import java.util.concurrent.*;
import java.util.stream.*;
import org.reactivestreams.*;
import io.reactivex.rxjava3.annotations.*;
import io.reactivex.rxjava3.disposables.*;
import io.reactivex.rxjava3.exceptions.*;
import io.reactivex.rxjava3.functions.*;
import io.reactivex.rxjava3.internal.functions.*;
import io.reactivex.rxjava3.internal.fuseable.*;
import io.reactivex.rxjava3.internal.jdk8.*;
import io.reactivex.rxjava3.internal.observers.*;
import io.reactivex.rxjava3.internal.operators.flowable.*;
import io.reactivex.rxjava3.internal.operators.maybe.*;
import io.reactivex.rxjava3.internal.operators.mixed.*;
import io.reactivex.rxjava3.internal.operators.observable.ObservableElementAtMaybe;
import io.reactivex.rxjava3.internal.util.ErrorMode;
import io.reactivex.rxjava3.observers.TestObserver;
import io.reactivex.rxjava3.plugins.RxJavaPlugins;
import io.reactivex.rxjava3.schedulers.*;
/**
* The {@code Maybe} class represents a deferred computation and emission of a single value, no value at all or an exception.
*
* The {@code Maybe} class implements the {@link MaybeSource} base interface and the default consumer
* type it interacts with is the {@link MaybeObserver} via the {@link #subscribe(MaybeObserver)} method.
*
* The {@code Maybe} operates with the following sequential protocol:
*
* onSubscribe (onSuccess | onError | onComplete)?
*
*
* Note that {@code onSuccess}, {@code onError} and {@code onComplete} are mutually exclusive events; unlike {@link Observable},
* {@code onSuccess} is never followed by {@code onError} or {@code onComplete}.
*
* Like {@code Observable}, a running {@code Maybe} can be stopped through the {@link Disposable} instance
* provided to consumers through {@link MaybeObserver#onSubscribe}.
*
* Like an {@code Observable}, a {@code Maybe} is lazy, can be either "hot" or "cold", synchronous or
* asynchronous. {@code Maybe} instances returned by the methods of this class are cold
* and there is a standard hot implementation in the form of a subject:
* {@link io.reactivex.rxjava3.subjects.MaybeSubject MaybeSubject}.
*
* The documentation for this class makes use of marble diagrams. The following legend explains these diagrams:
*
* 
*
* See {@link Flowable} or {@code Observable} for the
* implementation of the Reactive Pattern for a stream or vector of values.
*
* Example:
*
* Disposable d = Maybe.just("Hello World")
* .delay(10, TimeUnit.SECONDS, Schedulers.io())
* .subscribeWith(new DisposableMaybeObserver<String>() {
* @Override
* public void onStart() {
* System.out.println("Started");
* }
*
* @Override
* public void onSuccess(String value) {
* System.out.println("Success: " + value);
* }
*
* @Override
* public void onError(Throwable error) {
* error.printStackTrace();
* }
*
* @Override
* public void onComplete() {
* System.out.println("Done!");
* }
* });
*
* Thread.sleep(5000);
*
* d.dispose();
*
*
* Note that by design, subscriptions via {@link #subscribe(MaybeObserver)} can't be disposed
* from the outside (hence the
* {@code void} return of the {@link #subscribe(MaybeObserver)} method) and it is the
* responsibility of the implementor of the {@code MaybeObserver} to allow this to happen.
* RxJava supports such usage with the standard
* {@link io.reactivex.rxjava3.observers.DisposableMaybeObserver DisposableMaybeObserver} instance.
* For convenience, the {@link #subscribeWith(MaybeObserver)} method is provided as well to
* allow working with a {@code MaybeObserver} (or subclass) instance to be applied with in
* a fluent manner (such as in the example above).
*
* @param the value type
* @since 2.0
* @see io.reactivex.rxjava3.observers.DisposableMaybeObserver
*/
public abstract class Maybe implements MaybeSource {
/**
* Runs multiple {@link MaybeSource}s provided by an {@link Iterable} sequence and
* signals the events of the first one that signals (disposing the rest).
*
* 
*
* - Scheduler:
* - {@code amb} does not operate by default on a particular {@link Scheduler}.
*
* @param the value type
* @param sources the {@code Iterable} sequence of sources. A subscription to each source will
* occur in the same order as in the {@code Iterable}.
* @return the new {@code Maybe} instance
* @throws NullPointerException if {@code sources} is {@code null}
*/
@CheckReturnValue
@NonNull
@SchedulerSupport(SchedulerSupport.NONE)
public static <@NonNull T> Maybe amb(@NonNull Iterable<@NonNull ? extends MaybeSource> sources) {
Objects.requireNonNull(sources, "sources is null");
return RxJavaPlugins.onAssembly(new MaybeAmb<>(null, sources));
}
/**
* Runs multiple {@link MaybeSource}s and signals the events of the first one that signals (disposing
* the rest).
*
* 
*
* - Scheduler:
* - {@code ambArray} does not operate by default on a particular {@link Scheduler}.
*
* @param the value type
* @param sources the array of sources. A subscription to each source will
* occur in the same order as in the array.
* @return the new {@code Maybe} instance
* @throws NullPointerException if {@code sources} is {@code null}
*/
@CheckReturnValue
@SchedulerSupport(SchedulerSupport.NONE)
@NonNull
@SafeVarargs
public static <@NonNull T> Maybe ambArray(@NonNull MaybeSource... sources) {
Objects.requireNonNull(sources, "sources is null");
if (sources.length == 0) {
return empty();
}
if (sources.length == 1) {
@SuppressWarnings("unchecked")
MaybeSource source = (MaybeSource)sources[0];
return wrap(source);
}
return RxJavaPlugins.onAssembly(new MaybeAmb<>(sources, null));
}
/**
* Concatenate the single values, in a non-overlapping fashion, of the {@link MaybeSource} sources provided by
* an {@link Iterable} sequence as a {@link Flowable} sequence.
*
* 
*
* - Backpressure:
* - The returned {@code Flowable} honors the backpressure of the downstream consumer.
* - Scheduler:
* - {@code concat} does not operate by default on a particular {@link Scheduler}.
*
* @param the value type
* @param sources the {@code Iterable} sequence of {@code MaybeSource} instances
* @return the new {@code Flowable} instance
* @throws NullPointerException if {@code sources} is {@code null}
*/
@BackpressureSupport(BackpressureKind.FULL)
@CheckReturnValue
@NonNull
@SchedulerSupport(SchedulerSupport.NONE)
public static <@NonNull T> Flowable concat(@NonNull Iterable<@NonNull ? extends MaybeSource> sources) {
Objects.requireNonNull(sources, "sources is null");
return RxJavaPlugins.onAssembly(new MaybeConcatIterable<>(sources));
}
/**
* Returns a {@link Flowable} that emits the items emitted by two {@link MaybeSource}s, one after the other.
*
* 
*
* - Backpressure:
* - The returned {@code Flowable} honors the backpressure of the downstream consumer.
* - Scheduler:
* - {@code concat} does not operate by default on a particular {@link Scheduler}.
*
*
* @param the common value type
* @param source1
* a {@code MaybeSource} to be concatenated
* @param source2
* a {@code MaybeSource} to be concatenated
* @return the new {@code Flowable} instance
* @throws NullPointerException if {@code source1} or {@code source2} is {@code null}
* @see ReactiveX operators documentation: Concat
*/
@BackpressureSupport(BackpressureKind.FULL)
@CheckReturnValue
@NonNull
@SchedulerSupport(SchedulerSupport.NONE)
public static <@NonNull T> Flowable concat(@NonNull MaybeSource source1, @NonNull MaybeSource source2) {
Objects.requireNonNull(source1, "source1 is null");
Objects.requireNonNull(source2, "source2 is null");
return concatArray(source1, source2);
}
/**
* Returns a {@link Flowable} that emits the items emitted by three {@link MaybeSource}s, one after the other.
*
*
*
* - Backpressure:
* - The returned {@code Flowable} honors the backpressure of the downstream consumer.
* - Scheduler:
* - {@code concat} does not operate by default on a particular {@link Scheduler}.
*
*
* @param the common value type
* @param source1
* a {@code MaybeSource} to be concatenated
* @param source2
* a {@code MaybeSource} to be concatenated
* @param source3
* a {@code MaybeSource} to be concatenated
* @return the new {@code Flowable} instance
* @throws NullPointerException if {@code source1}, {@code source2} or {@code source3} is {@code null}
* @see ReactiveX operators documentation: Concat
*/
@BackpressureSupport(BackpressureKind.FULL)
@CheckReturnValue
@NonNull
@SchedulerSupport(SchedulerSupport.NONE)
public static <@NonNull T> Flowable concat(
@NonNull MaybeSource source1, @NonNull MaybeSource source2, @NonNull MaybeSource source3) {
Objects.requireNonNull(source1, "source1 is null");
Objects.requireNonNull(source2, "source2 is null");
Objects.requireNonNull(source3, "source3 is null");
return concatArray(source1, source2, source3);
}
/**
* Returns a {@link Flowable} that emits the items emitted by four {@link MaybeSource}s, one after the other.
*
*
*
* - Backpressure:
* - The returned {@code Flowable} honors the backpressure of the downstream consumer.
* - Scheduler:
* - {@code concat} does not operate by default on a particular {@link Scheduler}.
*
*
* @param the common value type
* @param source1
* a {@code MaybeSource} to be concatenated
* @param source2
* a {@code MaybeSource} to be concatenated
* @param source3
* a {@code MaybeSource} to be concatenated
* @param source4
* a {@code MaybeSource} to be concatenated
* @return the new {@code Flowable} instance
* @throws NullPointerException if {@code source1}, {@code source2}, {@code source3} or {@code source4} is {@code null}
* @see ReactiveX operators documentation: Concat
*/
@BackpressureSupport(BackpressureKind.FULL)
@CheckReturnValue
@NonNull
@SchedulerSupport(SchedulerSupport.NONE)
public static <@NonNull T> Flowable concat(
@NonNull MaybeSource source1, @NonNull MaybeSource source2, @NonNull MaybeSource source3, @NonNull MaybeSource source4) {
Objects.requireNonNull(source1, "source1 is null");
Objects.requireNonNull(source2, "source2 is null");
Objects.requireNonNull(source3, "source3 is null");
Objects.requireNonNull(source4, "source4 is null");
return concatArray(source1, source2, source3, source4);
}
/**
* Concatenate the single values, in a non-overlapping fashion, of the {@link MaybeSource} sources provided by
* a {@link Publisher} sequence as a {@link Flowable} sequence.
*
* 
*
* - Backpressure:
* - The returned {@code Flowable} honors the backpressure of the downstream consumer and
* expects the {@code Publisher} to honor backpressure as well. If the sources {@code Publisher}
* violates this, a {@link io.reactivex.rxjava3.exceptions.MissingBackpressureException} is signaled.
* - Scheduler:
* - {@code concat} does not operate by default on a particular {@link Scheduler}.
*
* @param the value type
* @param sources the {@code Publisher} of {@code MaybeSource} instances
* @return the new {@code Flowable} instance
* @throws NullPointerException if {@code sources} is {@code null}
*/
@BackpressureSupport(BackpressureKind.FULL)
@CheckReturnValue
@SchedulerSupport(SchedulerSupport.NONE)
@NonNull
public static <@NonNull T> Flowable concat(@NonNull Publisher<@NonNull ? extends MaybeSource> sources) {
return concat(sources, 2);
}
/**
* Concatenate the single values, in a non-overlapping fashion, of the {@link MaybeSource} sources provided by
* a {@link Publisher} sequence as a {@link Flowable} sequence.
*
* 
*
* - Backpressure:
* - The returned {@code Flowable} honors the backpressure of the downstream consumer and
* expects the {@code Publisher} to honor backpressure as well. If the sources {@code Publisher}
* violates this, a {@link io.reactivex.rxjava3.exceptions.MissingBackpressureException} is signaled.
* - Scheduler:
* - {@code concat} does not operate by default on a particular {@link Scheduler}.
*
* @param the value type
* @param sources the {@code Publisher} of {@code MaybeSource} instances
* @param prefetch the number of {@code MaybeSource}s to prefetch from the {@code Publisher}
* @throws NullPointerException if {@code sources} is {@code null}
* @throws IllegalArgumentException if {@code prefetch} is non-positive
* @return the new {@code Flowable} instance
*/
@BackpressureSupport(BackpressureKind.FULL)
@CheckReturnValue
@NonNull
@SchedulerSupport(SchedulerSupport.NONE)
public static <@NonNull T> Flowable concat(@NonNull Publisher<@NonNull ? extends MaybeSource> sources, int prefetch) {
Objects.requireNonNull(sources, "sources is null");
ObjectHelper.verifyPositive(prefetch, "prefetch");
return RxJavaPlugins.onAssembly(new FlowableConcatMapMaybePublisher<>(sources, Functions.identity(), ErrorMode.IMMEDIATE, prefetch));
}
/**
* Concatenate the single values, in a non-overlapping fashion, of the {@link MaybeSource} sources in the array
* as a {@link Flowable} sequence.
*
* 
*
* - Backpressure:
* - The returned {@code Flowable} honors the backpressure of the downstream consumer.
* - Scheduler:
* - {@code concatArray} does not operate by default on a particular {@link Scheduler}.
*
* @param the value type
* @param sources the array of {@code MaybeSource} instances
* @return the new {@code Flowable} instance
* @throws NullPointerException if {@code sources} is {@code null}
*/
@BackpressureSupport(BackpressureKind.FULL)
@CheckReturnValue
@NonNull
@SchedulerSupport(SchedulerSupport.NONE)
@SafeVarargs
public static <@NonNull T> Flowable concatArray(@NonNull MaybeSource... sources) {
Objects.requireNonNull(sources, "sources is null");
if (sources.length == 0) {
return Flowable.empty();
}
if (sources.length == 1) {
@SuppressWarnings("unchecked")
MaybeSource source = (MaybeSource)sources[0];
return RxJavaPlugins.onAssembly(new MaybeToFlowable<>(source));
}
return RxJavaPlugins.onAssembly(new MaybeConcatArray<>(sources));
}
/**
* Concatenates a variable number of {@link MaybeSource} sources and delays errors from any of them
* till all terminate as a {@link Flowable} sequence.
*
* 
*
* - Backpressure:
* - The operator honors backpressure from downstream.
* - Scheduler:
* - {@code concatArrayDelayError} does not operate by default on a particular {@link Scheduler}.
*
* @param sources the array of sources
* @param the common base value type
* @return the new {@code Flowable} instance
* @throws NullPointerException if {@code sources} is {@code null}
*/
@BackpressureSupport(BackpressureKind.FULL)
@CheckReturnValue
@SchedulerSupport(SchedulerSupport.NONE)
@SafeVarargs
@NonNull
public static <@NonNull T> Flowable concatArrayDelayError(@NonNull MaybeSource... sources) {
Objects.requireNonNull(sources, "sources is null");
if (sources.length == 0) {
return Flowable.empty();
} else
if (sources.length == 1) {
@SuppressWarnings("unchecked")
MaybeSource source = (MaybeSource)sources[0];
return RxJavaPlugins.onAssembly(new MaybeToFlowable<>(source));
}
return RxJavaPlugins.onAssembly(new MaybeConcatArrayDelayError<>(sources));
}
/**
* Concatenates a sequence of {@link MaybeSource} eagerly into a {@link Flowable} sequence.
*
* Eager concatenation means that once an observer subscribes, this operator subscribes to all of the
* source {@code MaybeSource}s. The operator buffers the value emitted by these {@code MaybeSource}s and then drains them
* in order, each one after the previous one completes.
*
* 
*
* - Backpressure:
* - The operator honors backpressure from downstream.
* - Scheduler:
* - This method does not operate by default on a particular {@link Scheduler}.
*
* @param the value type
* @param sources a sequence of {@code MaybeSource}s that need to be eagerly concatenated
* @return the new {@code Flowable} instance with the specified concatenation behavior
* @throws NullPointerException if {@code sources} is {@code null}
*/
@SuppressWarnings({ "rawtypes", "unchecked" })
@BackpressureSupport(BackpressureKind.FULL)
@CheckReturnValue
@SchedulerSupport(SchedulerSupport.NONE)
@NonNull
@SafeVarargs
public static <@NonNull T> Flowable concatArrayEager(@NonNull MaybeSource... sources) {
return Flowable.fromArray(sources).concatMapEager((Function)MaybeToPublisher.instance());
}
/**
* Concatenates a sequence of {@link MaybeSource} eagerly into a {@link Flowable} sequence.
*
* Eager concatenation means that once an observer subscribes, this operator subscribes to all of the
* source {@code MaybeSource}s. The operator buffers the value emitted by these {@code MaybeSource}s and then drains them
* in order, each one after the previous one completes.
*
* 
*
* - Backpressure:
* - The operator honors backpressure from downstream.
* - Scheduler:
* - This method does not operate by default on a particular {@link Scheduler}.
*
* @param the value type
* @param sources a sequence of {@code MaybeSource}s that need to be eagerly concatenated
* @return the new {@code Flowable} instance with the specified concatenation behavior
* @throws NullPointerException if {@code sources} is {@code null}
* @since 3.0.0
*/
@SuppressWarnings({ "rawtypes", "unchecked" })
@BackpressureSupport(BackpressureKind.FULL)
@CheckReturnValue
@SchedulerSupport(SchedulerSupport.NONE)
@NonNull
@SafeVarargs
public static <@NonNull T> Flowable concatArrayEagerDelayError(@NonNull MaybeSource... sources) {
return Flowable.fromArray(sources).concatMapEagerDelayError((Function)MaybeToPublisher.instance(), true);
}
/**
* Concatenates the {@link Iterable} sequence of {@link MaybeSource}s into a single sequence by subscribing to each {@code MaybeSource},
* one after the other, one at a time and delays any errors till the all inner {@code MaybeSource}s terminate
* as a {@link Flowable} sequence.
*
* 
*
* - Backpressure:
* - The operator honors backpressure from downstream.
* - Scheduler:
* - {@code concatDelayError} does not operate by default on a particular {@link Scheduler}.
*
*
* @param the common element base type
* @param sources the {@code Iterable} sequence of {@code MaybeSource}s
* @return the new {@code Flowable} with the concatenating behavior
* @throws NullPointerException if {@code sources} is {@code null}
*/
@BackpressureSupport(BackpressureKind.FULL)
@CheckReturnValue
@NonNull
@SchedulerSupport(SchedulerSupport.NONE)
public static <@NonNull T> Flowable concatDelayError(@NonNull Iterable<@NonNull ? extends MaybeSource> sources) {
return Flowable.fromIterable(sources).concatMapMaybeDelayError(Functions.identity());
}
/**
* Concatenates the {@link Publisher} sequence of {@link MaybeSource}s into a single sequence by subscribing to each inner {@code MaybeSource},
* one after the other, one at a time and delays any errors till the all inner and the outer {@code Publisher} terminate
* as a {@link Flowable} sequence.
*
* 
*
* - Backpressure:
* - {@code concatDelayError} fully supports backpressure.
* - Scheduler:
* - {@code concatDelayError} does not operate by default on a particular {@link Scheduler}.
*
*
* @param the common element base type
* @param sources the {@code Publisher} sequence of {@code MaybeSource}s
* @return the new {@code Flowable} with the concatenating behavior
* @throws NullPointerException if {@code sources} is {@code null}
*/
@BackpressureSupport(BackpressureKind.FULL)
@CheckReturnValue
@SchedulerSupport(SchedulerSupport.NONE)
@NonNull
public static <@NonNull T> Flowable concatDelayError(@NonNull Publisher<@NonNull ? extends MaybeSource> sources) {
return Flowable.fromPublisher(sources).concatMapMaybeDelayError(Functions.identity());
}
/**
* Concatenates the {@link Publisher} sequence of {@link MaybeSource}s into a single sequence by subscribing to each inner {@code MaybeSource},
* one after the other, one at a time and delays any errors till the all inner and the outer {@code Publisher} terminate
* as a {@link Flowable} sequence.
*
* 
*
* - Backpressure:
* - {@code concatDelayError} fully supports backpressure.
* - Scheduler:
* - {@code concatDelayError} does not operate by default on a particular {@link Scheduler}.
*
*
* @param the common element base type
* @param sources the {@code Publisher} sequence of {@code MaybeSource}s
* @param prefetch The number of upstream items to prefetch so that fresh items are
* ready to be mapped when a previous {@code MaybeSource} terminates.
* The operator replenishes after half of the prefetch amount has been consumed
* and turned into {@code MaybeSource}s.
* @return the new {@code Flowable} with the concatenating behavior
* @throws NullPointerException if {@code sources} is {@code null}
* @throws IllegalArgumentException if {@code prefetch} is non-positive
* @since 3.0.0
*/
@BackpressureSupport(BackpressureKind.FULL)
@CheckReturnValue
@SchedulerSupport(SchedulerSupport.NONE)
@NonNull
public static <@NonNull T> Flowable concatDelayError(@NonNull Publisher<@NonNull ? extends MaybeSource> sources, int prefetch) {
return Flowable.fromPublisher(sources).concatMapMaybeDelayError(Functions.identity(), true, prefetch);
}
/**
* Concatenates a sequence of {@link MaybeSource}s eagerly into a {@link Flowable} sequence.
*
* 
*
* Eager concatenation means that once an observer subscribes, this operator subscribes to all of the
* source {@code MaybeSource}s. The operator buffers the values emitted by these {@code MaybeSource}s and then drains them
* in order, each one after the previous one completes.
*
* - Backpressure:
* - Backpressure is honored towards the downstream.
* - Scheduler:
* - This method does not operate by default on a particular {@link Scheduler}.
*
* @param the value type
* @param sources a sequence of {@code MaybeSource} that need to be eagerly concatenated
* @return the new {@code Flowable} instance with the specified concatenation behavior
* @throws NullPointerException if {@code sources} is {@code null}
*/
@SuppressWarnings({ "rawtypes", "unchecked" })
@BackpressureSupport(BackpressureKind.FULL)
@CheckReturnValue
@SchedulerSupport(SchedulerSupport.NONE)
@NonNull
public static <@NonNull T> Flowable concatEager(@NonNull Iterable<@NonNull ? extends MaybeSource> sources) {
return Flowable.fromIterable(sources).concatMapEagerDelayError((Function)MaybeToPublisher.instance(), false);
}
/**
* Concatenates a sequence of {@link MaybeSource}s eagerly into a {@link Flowable} sequence and
* runs a limited number of the inner sequences at once.
*
* 
*
* Eager concatenation means that once an observer subscribes, this operator subscribes to all of the
* source {@code MaybeSource}s. The operator buffers the values emitted by these {@code MaybeSource}s and then drains them
* in order, each one after the previous one completes.
*
* - Backpressure:
* - Backpressure is honored towards the downstream.
* - Scheduler:
* - This method does not operate by default on a particular {@link Scheduler}.
*
* @param the value type
* @param sources a sequence of {@code MaybeSource} that need to be eagerly concatenated
* @param maxConcurrency the maximum number of concurrently running inner {@code MaybeSource}s; {@link Integer#MAX_VALUE}
* is interpreted as all inner {@code MaybeSource}s can be active at the same time
* @return the new {@code Flowable} instance with the specified concatenation behavior
* @throws NullPointerException if {@code sources} is {@code null}
* @throws IllegalArgumentException if {@code maxConcurrency} is non-positive
* @since 3.0.0
*/
@SuppressWarnings({ "rawtypes", "unchecked" })
@BackpressureSupport(BackpressureKind.FULL)
@CheckReturnValue
@SchedulerSupport(SchedulerSupport.NONE)
@NonNull
public static <@NonNull T> Flowable concatEager(@NonNull Iterable<@NonNull ? extends MaybeSource> sources, int maxConcurrency) {
return Flowable.fromIterable(sources).concatMapEagerDelayError((Function)MaybeToPublisher.instance(), false, maxConcurrency, 1);
}
/**
* Concatenates a {@link Publisher} sequence of {@link MaybeSource}s eagerly into a {@link Flowable} sequence.
*
* Eager concatenation means that once a subscriber subscribes, this operator subscribes to all of the
* emitted source {@code MaybeSource}s as they are observed. The operator buffers the values emitted by these
* {@code MaybeSource}s and then drains them in order, each one after the previous one completes.
*
* 
*
* - Backpressure:
* - Backpressure is honored towards the downstream and the outer {@code Publisher} is
* expected to support backpressure. Violating this assumption, the operator will
* signal {@link io.reactivex.rxjava3.exceptions.MissingBackpressureException}.
* - Scheduler:
* - This method does not operate by default on a particular {@link Scheduler}.
*
* @param the value type
* @param sources a sequence of {@code MaybeSource}s that need to be eagerly concatenated
* @return the new {@code Flowable} instance with the specified concatenation behavior
* @throws NullPointerException if {@code sources} is {@code null}
*/
@SuppressWarnings({ "rawtypes", "unchecked" })
@BackpressureSupport(BackpressureKind.FULL)
@CheckReturnValue
@SchedulerSupport(SchedulerSupport.NONE)
@NonNull
public static <@NonNull T> Flowable concatEager(@NonNull Publisher<@NonNull ? extends MaybeSource> sources) {
return Flowable.fromPublisher(sources).concatMapEager((Function)MaybeToPublisher.instance());
}
/**
* Concatenates a {@link Publisher} sequence of {@link MaybeSource}s eagerly into a {@link Flowable} sequence,
* running at most the given number of inner {@code MaybeSource}s at once.
*
* 
*
* Eager concatenation means that once a subscriber subscribes, this operator subscribes to all of the
* emitted source {@code MaybeSource}s as they are observed. The operator buffers the values emitted by these
* {@code MaybeSource}s and then drains them in order, each one after the previous one completes.
*
* - Backpressure:
* - Backpressure is honored towards the downstream and the outer {@code Publisher} is
* expected to support backpressure. Violating this assumption, the operator will
* signal {@link io.reactivex.rxjava3.exceptions.MissingBackpressureException}.
* - Scheduler:
* - This method does not operate by default on a particular {@link Scheduler}.
*
* @param the value type
* @param sources a sequence of {@code MaybeSource}s that need to be eagerly concatenated
* @param maxConcurrency the maximum number of concurrently running inner {@code MaybeSource}s; {@link Integer#MAX_VALUE}
* is interpreted as all inner {@code MaybeSource}s can be active at the same time
* @return the new {@code Flowable} instance with the specified concatenation behavior
* @throws NullPointerException if {@code sources} is {@code null}
* @throws IllegalArgumentException if {@code maxConcurrency} is non-positive
* @since 3.0.0
*/
@SuppressWarnings({ "rawtypes", "unchecked" })
@BackpressureSupport(BackpressureKind.FULL)
@CheckReturnValue
@SchedulerSupport(SchedulerSupport.NONE)
@NonNull
public static <@NonNull T> Flowable concatEager(@NonNull Publisher<@NonNull ? extends MaybeSource> sources, int maxConcurrency) {
return Flowable.fromPublisher(sources).concatMapEager((Function)MaybeToPublisher.instance(), maxConcurrency, 1);
}
/**
* Concatenates a sequence of {@link MaybeSource}s eagerly into a {@link Flowable} sequence,
* delaying errors until all inner {@code MaybeSource}s terminate.
*
* 
*
* Eager concatenation means that once an observer subscribes, this operator subscribes to all of the
* source {@code MaybeSource}s. The operator buffers the values emitted by these {@code MaybeSource}s and then drains them
* in order, each one after the previous one completes.
*
* - Backpressure:
* - Backpressure is honored towards the downstream.
* - Scheduler:
* - This method does not operate by default on a particular {@link Scheduler}.
*
* @param the value type
* @param sources a sequence of {@code MaybeSource} that need to be eagerly concatenated
* @return the new {@code Flowable} instance with the specified concatenation behavior
* @throws NullPointerException if {@code sources} is {@code null}
* @since 3.0.0
*/
@SuppressWarnings({ "rawtypes", "unchecked" })
@BackpressureSupport(BackpressureKind.FULL)
@CheckReturnValue
@SchedulerSupport(SchedulerSupport.NONE)
@NonNull
public static <@NonNull T> Flowable concatEagerDelayError(@NonNull Iterable<@NonNull ? extends MaybeSource> sources) {
return Flowable.fromIterable(sources).concatMapEagerDelayError((Function)MaybeToPublisher.instance(), true);
}
/**
* Concatenates a sequence of {@link MaybeSource}s eagerly into a {@link Flowable} sequence,
* delaying errors until all inner {@code MaybeSource}s terminate and
* runs a limited number of inner {@code MaybeSource}s at once.
*
* 
*
* Eager concatenation means that once an observer subscribes, this operator subscribes to all of the
* source {@code MaybeSource}s. The operator buffers the values emitted by these {@code MaybeSource}s and then drains them
* in order, each one after the previous one completes.
*
* - Backpressure:
* - Backpressure is honored towards the downstream.
* - Scheduler:
* - This method does not operate by default on a particular {@link Scheduler}.
*
* @param the value type
* @param sources a sequence of {@code MaybeSource} that need to be eagerly concatenated
* @param maxConcurrency the maximum number of concurrently running inner {@code MaybeSource}s; {@link Integer#MAX_VALUE}
* is interpreted as all inner {@code MaybeSource}s can be active at the same time
* @return the new {@code Flowable} instance with the specified concatenation behavior
* @throws NullPointerException if {@code sources} is {@code null}
* @throws IllegalArgumentException if {@code maxConcurrency} is non-positive
* @since 3.0.0
*/
@SuppressWarnings({ "rawtypes", "unchecked" })
@BackpressureSupport(BackpressureKind.FULL)
@CheckReturnValue
@SchedulerSupport(SchedulerSupport.NONE)
@NonNull
public static <@NonNull T> Flowable concatEagerDelayError(@NonNull Iterable<@NonNull ? extends MaybeSource> sources, int maxConcurrency) {
return Flowable.fromIterable(sources).concatMapEagerDelayError((Function)MaybeToPublisher.instance(), true, maxConcurrency, 1);
}
/**
* Concatenates a {@link Publisher} sequence of {@link MaybeSource}s eagerly into a {@link Flowable} sequence,
* delaying errors until all the inner and the outer sequence terminate.
*
* 
*
* Eager concatenation means that once a subscriber subscribes, this operator subscribes to all of the
* emitted source {@code MaybeSource}s as they are observed. The operator buffers the values emitted by these
* {@code MaybeSource}s and then drains them in order, each one after the previous one completes.
*
* - Backpressure:
* - Backpressure is honored towards the downstream and the outer {@code Publisher} is
* expected to support backpressure. Violating this assumption, the operator will
* signal {@link io.reactivex.rxjava3.exceptions.MissingBackpressureException}.
* - Scheduler:
* - This method does not operate by default on a particular {@link Scheduler}.
*
* @param the value type
* @param sources a sequence of {@code MaybeSource}s that need to be eagerly concatenated
* @return the new {@code Flowable} instance with the specified concatenation behavior
* @throws NullPointerException if {@code sources} is {@code null}
* @since 3.0.0
*/
@SuppressWarnings({ "rawtypes", "unchecked" })
@BackpressureSupport(BackpressureKind.FULL)
@CheckReturnValue
@SchedulerSupport(SchedulerSupport.NONE)
@NonNull
public static <@NonNull T> Flowable concatEagerDelayError(@NonNull Publisher<@NonNull ? extends MaybeSource> sources) {
return Flowable.fromPublisher(sources).concatMapEagerDelayError((Function)MaybeToPublisher.instance(), true);
}
/**
* Concatenates a {@link Publisher} sequence of {@link MaybeSource}s eagerly into a {@link Flowable} sequence,
* delaying errors until all the inner and the outer sequence terminate and
* runs a limited number of the inner {@code MaybeSource}s at once.
*
* 
*
* Eager concatenation means that once a subscriber subscribes, this operator subscribes to all of the
* emitted source {@code MaybeSource}s as they are observed. The operator buffers the values emitted by these
* {@code MaybeSource}s and then drains them in order, each one after the previous one completes.
*
* - Backpressure:
* - Backpressure is honored towards the downstream and the outer {@code Publisher} is
* expected to support backpressure. Violating this assumption, the operator will
* signal {@link io.reactivex.rxjava3.exceptions.MissingBackpressureException}.
* - Scheduler:
* - This method does not operate by default on a particular {@link Scheduler}.
*
* @param the value type
* @param sources a sequence of {@code MaybeSource}s that need to be eagerly concatenated
* @param maxConcurrency the maximum number of concurrently running inner {@code MaybeSource}s; {@link Integer#MAX_VALUE}
* is interpreted as all inner {@code MaybeSource}s can be active at the same time
* @return the new {@code Flowable} instance with the specified concatenation behavior
* @throws NullPointerException if {@code sources} is {@code null}
* @throws IllegalArgumentException if {@code maxConcurrency} is non-positive
* @since 3.0.0
*/
@SuppressWarnings({ "rawtypes", "unchecked" })
@BackpressureSupport(BackpressureKind.FULL)
@CheckReturnValue
@SchedulerSupport(SchedulerSupport.NONE)
@NonNull
public static <@NonNull T> Flowable concatEagerDelayError(@NonNull Publisher<@NonNull ? extends MaybeSource> sources, int maxConcurrency) {
return Flowable.fromPublisher(sources).concatMapEagerDelayError((Function)MaybeToPublisher.instance(), true, maxConcurrency, 1);
}
/**
* Provides an API (via a cold {@code Maybe}) that bridges the reactive world with the callback-style world.
*
* 
*
* Example:
*
* Maybe.<Event>create(emitter -> {
* Callback listener = new Callback() {
* @Override
* public void onEvent(Event e) {
* if (e.isNothing()) {
* emitter.onComplete();
* } else {
* emitter.onSuccess(e);
* }
* }
*
* @Override
* public void onFailure(Exception e) {
* emitter.onError(e);
* }
* };
*
* AutoCloseable c = api.someMethod(listener);
*
* emitter.setCancellable(c::close);
*
* });
*
*
* Whenever a {@link MaybeObserver} subscribes to the returned {@code Maybe}, the provided
* {@link MaybeOnSubscribe} callback is invoked with a fresh instance of a {@link MaybeEmitter}
* that will interact only with that specific {@code MaybeObserver}. If this {@code MaybeObserver}
* disposes the flow (making {@link MaybeEmitter#isDisposed} return {@code true}),
* other observers subscribed to the same returned {@code Maybe} are not affected.
*
* - Scheduler:
* - {@code create} does not operate by default on a particular {@link Scheduler}.
*
* @param the value type
* @param onSubscribe the emitter that is called when a {@code MaybeObserver} subscribes to the returned {@code Maybe}
* @return the new {@code Maybe} instance
* @throws NullPointerException if {@code onSubscribe} is {@code null}
* @see MaybeOnSubscribe
* @see Cancellable
*/
@CheckReturnValue
@NonNull
@SchedulerSupport(SchedulerSupport.NONE)
public static <@NonNull T> Maybe create(@NonNull MaybeOnSubscribe onSubscribe) {
Objects.requireNonNull(onSubscribe, "onSubscribe is null");
return RxJavaPlugins.onAssembly(new MaybeCreate<>(onSubscribe));
}
/**
* Calls a {@link Supplier} for each individual {@link MaybeObserver} to return the actual {@link MaybeSource} source to
* be subscribed to.
*
* 
*
* - Scheduler:
* - {@code defer} does not operate by default on a particular {@link Scheduler}.
*
* @param the value type
* @param supplier the {@code Supplier} that is called for each individual {@code MaybeObserver} and
* returns a {@code MaybeSource} instance to subscribe to
* @return the new {@code Maybe} instance
* @throws NullPointerException if {@code supplier} is {@code null}
*/
@CheckReturnValue
@NonNull
@SchedulerSupport(SchedulerSupport.NONE)
public static <@NonNull T> Maybe defer(@NonNull Supplier> supplier) {
Objects.requireNonNull(supplier, "supplier is null");
return RxJavaPlugins.onAssembly(new MaybeDefer<>(supplier));
}
/**
* Returns a (singleton) {@code Maybe} instance that calls {@link MaybeObserver#onComplete onComplete}
* immediately.
*
* 
*
* - Scheduler:
* - {@code empty} does not operate by default on a particular {@link Scheduler}.
*
* @param the value type
* @return the shared {@code Maybe} instance
*/
@CheckReturnValue
@SchedulerSupport(SchedulerSupport.NONE)
@SuppressWarnings("unchecked")
@NonNull
public static <@NonNull T> Maybe empty() {
return RxJavaPlugins.onAssembly((Maybe)MaybeEmpty.INSTANCE);
}
/**
* Returns a {@code Maybe} that invokes a subscriber's {@link MaybeObserver#onError onError} method when the
* subscriber subscribes to it.
*
* 
*
* - Scheduler:
* - {@code error} does not operate by default on a particular {@link Scheduler}.
*
*
* @param throwable
* the particular {@link Throwable} to pass to {@link MaybeObserver#onError onError}
* @param
* the type of the item (ostensibly) emitted by the {@code Maybe}
* @return the new {@code Maybe} instance
* @throws NullPointerException if {@code throwable} is {@code null}
* @see ReactiveX operators documentation: Throw
*/
@CheckReturnValue
@NonNull
@SchedulerSupport(SchedulerSupport.NONE)
public static <@NonNull T> Maybe error(@NonNull Throwable throwable) {
Objects.requireNonNull(throwable, "throwable is null");
return RxJavaPlugins.onAssembly(new MaybeError<>(throwable));
}
/**
* Returns a {@code Maybe} that invokes a {@link MaybeObserver}'s {@link MaybeObserver#onError onError} method when the
* {@code MaybeObserver} subscribes to it.
*
* 
*
* - Scheduler:
* - {@code error} does not operate by default on a particular {@link Scheduler}.
*
*
* @param supplier
* a {@link Supplier} factory to return a {@link Throwable} for each individual {@code MaybeObserver}
* @param
* the type of the items (ostensibly) emitted by the {@code Maybe}
* @return the new {@code Maybe} instance
* @throws NullPointerException if {@code supplier} is {@code null}
* @see ReactiveX operators documentation: Throw
*/
@CheckReturnValue
@NonNull
@SchedulerSupport(SchedulerSupport.NONE)
public static <@NonNull T> Maybe error(@NonNull Supplier supplier) {
Objects.requireNonNull(supplier, "supplier is null");
return RxJavaPlugins.onAssembly(new MaybeErrorCallable<>(supplier));
}
/**
* Returns a {@code Maybe} instance that runs the given {@link Action} for each {@link MaybeObserver} and
* emits either its exception or simply completes.
*
* 
*
* - Scheduler:
* - {@code fromAction} does not operate by default on a particular {@link Scheduler}.
* - Error handling:
* - If the {@code Action} throws an exception, the respective {@link Throwable} is
* delivered to the downstream via {@link MaybeObserver#onError(Throwable)},
* except when the downstream has disposed the resulting {@code Maybe} source.
* In this latter case, the {@code Throwable} is delivered to the global error handler via
* {@link RxJavaPlugins#onError(Throwable)} as an {@link io.reactivex.rxjava3.exceptions.UndeliverableException UndeliverableException}.
*
*
* @param the target type
* @param action the {@code Action} to run for each {@code MaybeObserver}
* @return the new {@code Maybe} instance
* @throws NullPointerException if {@code action} is {@code null}
*/
@CheckReturnValue
@NonNull
@SchedulerSupport(SchedulerSupport.NONE)
public static <@NonNull T> Maybe fromAction(@NonNull Action action) {
Objects.requireNonNull(action, "action is null");
return RxJavaPlugins.onAssembly(new MaybeFromAction<>(action));
}
/**
* Wraps a {@link CompletableSource} into a {@code Maybe}.
*
* 
*
* - Scheduler:
* - {@code fromCompletable} does not operate by default on a particular {@link Scheduler}.
*
* @param the target type
* @param completableSource the {@code CompletableSource} to convert from
* @return the new {@code Maybe} instance
* @throws NullPointerException if {@code completableSource} is {@code null}
*/
@CheckReturnValue
@NonNull
@SchedulerSupport(SchedulerSupport.NONE)
public static <@NonNull T> Maybe fromCompletable(@NonNull CompletableSource completableSource) {
Objects.requireNonNull(completableSource, "completableSource is null");
return RxJavaPlugins.onAssembly(new MaybeFromCompletable<>(completableSource));
}
/**
* Wraps a {@link SingleSource} into a {@code Maybe}.
*
* 
*
* - Scheduler:
* - {@code fromSingle} does not operate by default on a particular {@link Scheduler}.
*
* @param the target type
* @param single the {@code SingleSource} to convert from
* @return the new {@code Maybe} instance
* @throws NullPointerException if {@code single} is {@code null}
*/
@CheckReturnValue
@NonNull
@SchedulerSupport(SchedulerSupport.NONE)
public static <@NonNull T> Maybe fromSingle(@NonNull SingleSource single) {
Objects.requireNonNull(single, "single is null");
return RxJavaPlugins.onAssembly(new MaybeFromSingle<>(single));
}
/**
* Returns a {@code Maybe} that invokes the given {@link Callable} for each individual {@link MaybeObserver} that
* subscribes and emits the resulting non-{@code null} item via {@code onSuccess} while
* considering a {@code null} result from the {@code Callable} as indication for valueless completion
* via {@code onComplete}.
*
* 
*
* This operator allows you to defer the execution of the given {@code Callable} until a {@code MaybeObserver}
* subscribes to the returned {@code Maybe}. In other terms, this source operator evaluates the given
* {@code Callable} "lazily".
*
* Note that the {@code null} handling of this operator differs from the similar source operators in the other
* {@link io.reactivex.rxjava3.core base reactive classes}. Those operators signal a {@link NullPointerException} if the value returned by their
* {@code Callable} is {@code null} while this {@code fromCallable} considers it to indicate the
* returned {@code Maybe} is empty.
*
* - Scheduler:
* - {@code fromCallable} does not operate by default on a particular {@link Scheduler}.
* - Error handling:
* - Any non-fatal exception thrown by {@link Callable#call()} will be forwarded to {@code onError},
* except if the {@code MaybeObserver} disposed the subscription in the meantime. In this latter case,
* the exception is forwarded to the global error handler via
* {@link io.reactivex.rxjava3.plugins.RxJavaPlugins#onError(Throwable)} wrapped into a
* {@link io.reactivex.rxjava3.exceptions.UndeliverableException UndeliverableException}.
* Fatal exceptions are rethrown and usually will end up in the executing thread's
* {@link java.lang.Thread.UncaughtExceptionHandler#uncaughtException(Thread, Throwable)} handler.
*
*
* @param callable
* a {@code Callable} instance whose execution should be deferred and performed for each individual
* {@code MaybeObserver} that subscribes to the returned {@code Maybe}.
* @param
* the type of the item emitted by the {@code Maybe}.
* @return the new {@code Maybe} instance
* @throws NullPointerException if {@code callable} is {@code null}
* @see #defer(Supplier)
* @see #fromSupplier(Supplier)
*/
@CheckReturnValue
@NonNull
@SchedulerSupport(SchedulerSupport.NONE)
public static <@NonNull T> Maybe fromCallable(@NonNull Callable callable) {
Objects.requireNonNull(callable, "callable is null");
return RxJavaPlugins.onAssembly(new MaybeFromCallable<>(callable));
}
/**
* Converts a {@link Future} into a {@code Maybe}, treating a {@code null} result as an indication of emptiness.
*
* 
*
* The operator calls {@link Future#get()}, which is a blocking method, on the subscription thread.
* It is recommended applying {@link #subscribeOn(Scheduler)} to move this blocking wait to a
* background thread, and if the {@link Scheduler} supports it, interrupt the wait when the flow
* is disposed.
*
* Unlike 1.x, disposing the {@code Maybe} won't cancel the future. If necessary, one can use composition to achieve the
* cancellation effect: {@code futureMaybe.doOnDispose(() -> future.cancel(true));}.
*
* - Scheduler:
* - {@code fromFuture} does not operate by default on a particular {@code Scheduler}.
*
*
* @param future
* the source {@code Future}
* @param
* the type of object that the {@code Future} returns, and also the type of item to be emitted by
* the resulting {@code Maybe}
* @return the new {@code Maybe} instance
* @throws NullPointerException if {@code future} is {@code null}
* @see ReactiveX operators documentation: From
*/
@CheckReturnValue
@NonNull
@SchedulerSupport(SchedulerSupport.NONE)
public static <@NonNull T> Maybe fromFuture(@NonNull Future future) {
Objects.requireNonNull(future, "future is null");
return RxJavaPlugins.onAssembly(new MaybeFromFuture<>(future, 0L, null));
}
/**
* Converts a {@link Future} into a {@code Maybe}, with a timeout on the {@code Future}.
*
* 
*
* The operator calls {@link Future#get(long, TimeUnit)}, which is a blocking method, on the subscription thread.
* It is recommended applying {@link #subscribeOn(Scheduler)} to move this blocking wait to a
* background thread, and if the {@link Scheduler} supports it, interrupt the wait when the flow
* is disposed.
*
* Unlike 1.x, disposing the {@code Maybe} won't cancel the future. If necessary, one can use composition to achieve the
* cancellation effect: {@code futureMaybe.doOnCancel(() -> future.cancel(true));}.
*
* - Scheduler:
* - {@code fromFuture} does not operate by default on a particular {@code Scheduler}.
*
*
* @param future
* the source {@code Future}
* @param timeout
* the maximum time to wait before calling {@code get}
* @param unit
* the {@link TimeUnit} of the {@code timeout} argument
* @param
* the type of object that the {@code Future} returns, and also the type of item to be emitted by
* the resulting {@code Maybe}
* @return the new {@code Maybe} instance
* @throws NullPointerException if {@code future} or {@code unit} is {@code null}
* @see ReactiveX operators documentation: From
*/
@CheckReturnValue
@NonNull
@SchedulerSupport(SchedulerSupport.NONE)
public static <@NonNull T> Maybe fromFuture(@NonNull Future future, long timeout, @NonNull TimeUnit unit) {
Objects.requireNonNull(future, "future is null");
Objects.requireNonNull(unit, "unit is null");
return RxJavaPlugins.onAssembly(new MaybeFromFuture<>(future, timeout, unit));
}
/**
* Wraps an {@link ObservableSource} into a {@code Maybe} and emits the very first item
* or completes if the source is empty.
*
* 
*
* - Scheduler:
* - {@code fromObservable} does not operate by default on a particular {@link Scheduler}.
*
* @param the target type
* @param source the {@code ObservableSource} to convert from
* @return the new {@code Maybe} instance
* @throws NullPointerException if {@code source} is {@code null}
* @since 3.0.0
*/
@CheckReturnValue
@NonNull
@SchedulerSupport(SchedulerSupport.NONE)
public static <@NonNull T> Maybe fromObservable(@NonNull ObservableSource source) {
Objects.requireNonNull(source, "source is null");
return RxJavaPlugins.onAssembly(new ObservableElementAtMaybe<>(source, 0L));
}
/**
* Wraps a {@link Publisher} into a {@code Maybe} and emits the very first item
* or completes if the source is empty.
*
* 
*
* - Backpressure:
* - The operator consumes the given {@code Publisher} in an unbounded manner
* (requesting {@link Long#MAX_VALUE}) but cancels it after one item received.
* - Scheduler:
* - {@code fromPublisher} does not operate by default on a particular {@link Scheduler}.
*
* @param the target type
* @param source the {@code Publisher} to convert from
* @return the new {@code Maybe} instance
* @throws NullPointerException if {@code source} is {@code null}
* @since 3.0.0
*/
@CheckReturnValue
@NonNull
@SchedulerSupport(SchedulerSupport.NONE)
@BackpressureSupport(BackpressureKind.UNBOUNDED_IN)
public static <@NonNull T> Maybe fromPublisher(@NonNull Publisher source) {
Objects.requireNonNull(source, "source is null");
return RxJavaPlugins.onAssembly(new FlowableElementAtMaybePublisher<>(source, 0L));
}
/**
* Returns a {@code Maybe} instance that runs the given {@link Runnable} for each {@link MaybeObserver} and
* emits either its unchecked exception or simply completes.
*
* 
*
* If the code to be wrapped needs to throw a checked or more broader {@link Throwable} exception, that
* exception has to be converted to an unchecked exception by the wrapped code itself. Alternatively,
* use the {@link #fromAction(Action)} method which allows the wrapped code to throw any {@code Throwable}
* exception and will signal it to observers as-is.
*
* - Scheduler:
* - {@code fromRunnable} does not operate by default on a particular {@link Scheduler}.
* - Error handling:
* - If the {@code Runnable} throws an exception, the respective {@code Throwable} is
* delivered to the downstream via {@link MaybeObserver#onError(Throwable)},
* except when the downstream has disposed this {@code Maybe} source.
* In this latter case, the {@code Throwable} is delivered to the global error handler via
* {@link RxJavaPlugins#onError(Throwable)} as an {@link io.reactivex.rxjava3.exceptions.UndeliverableException UndeliverableException}.
*
*
* @param the target type
* @param run the {@code Runnable} to run for each {@code MaybeObserver}
* @return the new {@code Maybe} instance
* @throws NullPointerException if {@code run} is {@code null}
* @see #fromAction(Action)
*/
@CheckReturnValue
@NonNull
@SchedulerSupport(SchedulerSupport.NONE)
public static <@NonNull T> Maybe fromRunnable(@NonNull Runnable run) {
Objects.requireNonNull(run, "run is null");
return RxJavaPlugins.onAssembly(new MaybeFromRunnable<>(run));
}
/**
* Returns a {@code Maybe} that invokes the given {@link Supplier} for each individual {@link MaybeObserver} that
* subscribes and emits the resulting non-{@code null} item via {@code onSuccess} while
* considering a {@code null} result from the {@code Supplier} as indication for valueless completion
* via {@code onComplete}.
*
* This operator allows you to defer the execution of the given {@code Supplier} until a {@code MaybeObserver}
* subscribes to the returned {@code Maybe}. In other terms, this source operator evaluates the given
* {@code Supplier} "lazily".
*
* 
*
* Note that the {@code null} handling of this operator differs from the similar source operators in the other
* {@link io.reactivex.rxjava3.core base reactive classes}. Those operators signal a {@link NullPointerException} if the value returned by their
* {@code Supplier} is {@code null} while this {@code fromSupplier} considers it to indicate the
* returned {@code Maybe} is empty.
*
* - Scheduler:
* - {@code fromSupplier} does not operate by default on a particular {@link Scheduler}.
* - Error handling:
* - Any non-fatal exception thrown by {@link Supplier#get()} will be forwarded to {@code onError},
* except if the {@code MaybeObserver} disposed the subscription in the meantime. In this latter case,
* the exception is forwarded to the global error handler via
* {@link io.reactivex.rxjava3.plugins.RxJavaPlugins#onError(Throwable)} wrapped into a
* {@link io.reactivex.rxjava3.exceptions.UndeliverableException UndeliverableException}.
* Fatal exceptions are rethrown and usually will end up in the executing thread's
* {@link java.lang.Thread.UncaughtExceptionHandler#uncaughtException(Thread, Throwable)} handler.
*
*
* @param supplier
* a {@code Supplier} instance whose execution should be deferred and performed for each individual
* {@code MaybeObserver} that subscribes to the returned {@code Maybe}.
* @param
* the type of the item emitted by the {@code Maybe}.
* @return the new {@code Maybe} instance
* @throws NullPointerException if {@code supplier} is {@code null}
* @see #defer(Supplier)
* @see #fromCallable(Callable)
* @since 3.0.0
*/
@CheckReturnValue
@NonNull
@SchedulerSupport(SchedulerSupport.NONE)
public static <@NonNull T> Maybe fromSupplier(@NonNull Supplier supplier) {
Objects.requireNonNull(supplier, "supplier is null");
return RxJavaPlugins.onAssembly(new MaybeFromSupplier<>(supplier));
}
/**
* Returns a {@code Maybe} that emits a specified item.
*
* 
*
* To convert any object into a {@code Maybe} that emits that object, pass that object into the
* {@code just} method.
*
* - Scheduler:
* - {@code just} does not operate by default on a particular {@link Scheduler}.
*
*
* @param item
* the item to emit
* @param
* the type of that item
* @return the new {@code Maybe} instance
* @throws NullPointerException if {@code item} is {@code null}
* @see ReactiveX operators documentation: Just
*/
@CheckReturnValue
@NonNull
@SchedulerSupport(SchedulerSupport.NONE)
public static <@NonNull T> Maybe just(T item) {
Objects.requireNonNull(item, "item is null");
return RxJavaPlugins.onAssembly(new MaybeJust<>(item));
}
/**
* Merges an {@link Iterable} sequence of {@link MaybeSource} instances into a single {@link Flowable} sequence,
* running all {@code MaybeSource}s at once.
*
* 
*
* - Backpressure:
* - The operator honors backpressure from downstream.
* - Scheduler:
* - {@code merge} does not operate by default on a particular {@link Scheduler}.
* - Error handling:
* - If any of the source {@code MaybeSource}s signal a {@link Throwable} via {@code onError}, the resulting
* {@code Flowable} terminates with that {@code Throwable} and all other source {@code MaybeSource}s are disposed.
* If more than one {@code MaybeSource} signals an error, the resulting {@code Flowable} may terminate with the
* first one's error or, depending on the concurrency of the sources, may terminate with a
* {@link CompositeException} containing two or more of the various error signals.
* {@code Throwable}s that didn't make into the composite will be sent (individually) to the global error handler via
* {@link RxJavaPlugins#onError(Throwable)} method as {@link UndeliverableException} errors. Similarly, {@code Throwable}s
* signaled by source(s) after the returned {@code Flowable} has been cancelled or terminated with a
* (composite) error will be sent to the same global error handler.
* Use {@link #mergeDelayError(Iterable)} to merge sources and terminate only when all source {@code MaybeSource}s
* have completed or failed with an error.
*
*
* @param the common and resulting value type
* @param sources the {@code Iterable} sequence of {@code MaybeSource} sources
* @return the new {@code Flowable} instance
* @throws NullPointerException if {@code sources} is {@code null}
* @see #mergeDelayError(Iterable)
*/
@BackpressureSupport(BackpressureKind.FULL)
@CheckReturnValue
@SchedulerSupport(SchedulerSupport.NONE)
@NonNull
public static <@NonNull T> Flowable merge(@NonNull Iterable<@NonNull ? extends MaybeSource> sources) {
return Flowable.fromIterable(sources).flatMapMaybe(Functions.identity(), false, Integer.MAX_VALUE);
}
/**
* Merges a {@link Publisher} sequence of {@link MaybeSource} instances into a single {@link Flowable} sequence,
* running all {@code MaybeSource}s at once.
*
* 
*
* - Backpressure:
* - The operator honors backpressure from downstream.
* - Scheduler:
* - {@code merge} does not operate by default on a particular {@link Scheduler}.
* - Error handling:
* - If any of the source {@code MaybeSource}s signal a {@link Throwable} via {@code onError}, the resulting
* {@code Flowable} terminates with that {@code Throwable} and all other source {@code MaybeSource}s are disposed.
* If more than one {@code MaybeSource} signals an error, the resulting {@code Flowable} may terminate with the
* first one's error or, depending on the concurrency of the sources, may terminate with a
* {@link CompositeException} containing two or more of the various error signals.
* {@code Throwable}s that didn't make into the composite will be sent (individually) to the global error handler via
* {@link RxJavaPlugins#onError(Throwable)} method as {@link UndeliverableException} errors. Similarly, {@code Throwable}s
* signaled by source(s) after the returned {@code Flowable} has been cancelled or terminated with a
* (composite) error will be sent to the same global error handler.
* Use {@link #mergeDelayError(Publisher)} to merge sources and terminate only when all source {@code MaybeSource}s
* have completed or failed with an error.
*
*
* @param the common and resulting value type
* @param sources the {@code Flowable} sequence of {@code MaybeSource} sources
* @return the new {@code Flowable} instance
* @throws NullPointerException if {@code sources} is {@code null}
* @see #mergeDelayError(Publisher)
*/
@BackpressureSupport(BackpressureKind.FULL)
@CheckReturnValue
@SchedulerSupport(SchedulerSupport.NONE)
@NonNull
public static <@NonNull T> Flowable merge(@NonNull Publisher<@NonNull ? extends MaybeSource> sources) {
return merge(sources, Integer.MAX_VALUE);
}
/**
* Merges a {@link Publisher} sequence of {@link MaybeSource} instances into a single {@link Flowable} sequence,
* running at most maxConcurrency {@code MaybeSource}s at once.
*
* 
*
* - Backpressure:
* - The operator honors backpressure from downstream.
* - Scheduler:
* - {@code merge} does not operate by default on a particular {@link Scheduler}.
* - Error handling:
* - If any of the source {@code MaybeSource}s signal a {@link Throwable} via {@code onError}, the resulting
* {@code Flowable} terminates with that {@code Throwable} and all other source {@code MaybeSource}s are disposed.
* If more than one {@code MaybeSource} signals an error, the resulting {@code Flowable} may terminate with the
* first one's error or, depending on the concurrency of the sources, may terminate with a
* {@link CompositeException} containing two or more of the various error signals.
* {@code Throwable}s that didn't make into the composite will be sent (individually) to the global error handler via
* {@link RxJavaPlugins#onError(Throwable)} method as {@link UndeliverableException} errors. Similarly, {@code Throwable}s
* signaled by source(s) after the returned {@code Flowable} has been cancelled or terminated with a
* (composite) error will be sent to the same global error handler.
* Use {@link #mergeDelayError(Publisher, int)} to merge sources and terminate only when all source {@code MaybeSource}s
* have completed or failed with an error.
*
*
* @param the common and resulting value type
* @param sources the {@code Flowable} sequence of {@code MaybeSource} sources
* @param maxConcurrency the maximum number of concurrently running {@code MaybeSource}s
* @return the new {@code Flowable} instance
* @throws NullPointerException if {@code sources} is {@code null}
* @throws IllegalArgumentException if {@code maxConcurrency} is non-positive
* @see #mergeDelayError(Publisher, int)
*/
@BackpressureSupport(BackpressureKind.FULL)
@CheckReturnValue
@NonNull
@SchedulerSupport(SchedulerSupport.NONE)
public static <@NonNull T> Flowable merge(@NonNull Publisher<@NonNull ? extends MaybeSource> sources, int maxConcurrency) {
Objects.requireNonNull(sources, "sources is null");
ObjectHelper.verifyPositive(maxConcurrency, "maxConcurrency");
return RxJavaPlugins.onAssembly(new FlowableFlatMapMaybePublisher<>(sources, Functions.identity(), false, maxConcurrency));
}
/**
* Flattens a {@link MaybeSource} that emits a {@code MaybeSource} into a single {@code MaybeSource} that emits the item
* emitted by the nested {@code MaybeSource}, without any transformation.
*
* 
*
* - Scheduler:
* - {@code merge} does not operate by default on a particular {@link Scheduler}.
* - Error handling:
* - The resulting {@code Maybe} emits the outer source's or the inner {@code MaybeSource}'s {@link Throwable} as is.
* Unlike the other {@code merge()} operators, this operator won't and can't produce a {@link CompositeException} because there is
* only one possibility for the outer or the inner {@code MaybeSource} to emit an {@code onError} signal.
* Therefore, there is no need for a {@code mergeDelayError(MaybeSource
>)} operator.
*
*
*
* @param the value type of the sources and the output
* @param source
* a {@code MaybeSource} that emits a {@code MaybeSource}
* @return the new {@code Maybe} instance
* @throws NullPointerException if {@code source} is {@code null}
* @see ReactiveX operators documentation: Merge
*/
@CheckReturnValue
@NonNull
@SchedulerSupport(SchedulerSupport.NONE)
@SuppressWarnings({ "unchecked", "rawtypes" })
public static <@NonNull T> Maybe merge(@NonNull MaybeSource> source) {
Objects.requireNonNull(source, "source is null");
return RxJavaPlugins.onAssembly(new MaybeFlatten(source, Functions.identity()));
}
/**
* Flattens two {@link MaybeSource}s into a single {@link Flowable}, without any transformation.
*
* 
*
* You can combine items emitted by multiple {@code MaybeSource}s so that they appear as a single {@code Flowable}, by
* using the {@code merge} method.
*
* - Backpressure:
* - The operator honors backpressure from downstream.
* - Scheduler:
* - {@code merge} does not operate by default on a particular {@link Scheduler}.
* - Error handling:
* - If any of the source {@code MaybeSource}s signal a {@link Throwable} via {@code onError}, the resulting
* {@code Flowable} terminates with that {@code Throwable} and all other source {@code MaybeSource}s are disposed.
* If more than one {@code MaybeSource} signals an error, the resulting {@code Flowable} may terminate with the
* first one's error or, depending on the concurrency of the sources, may terminate with a
* {@link CompositeException} containing two or more of the various error signals.
* {@code Throwable}s that didn't make into the composite will be sent (individually) to the global error handler via
* {@link RxJavaPlugins#onError(Throwable)} method as {@link UndeliverableException} errors. Similarly, {@code Throwable}s
* signaled by source(s) after the returned {@code Flowable} has been cancelled or terminated with a
* (composite) error will be sent to the same global error handler.
* Use {@link #mergeDelayError(MaybeSource, MaybeSource)} to merge sources and terminate only when all source {@code MaybeSource}s
* have completed or failed with an error.
*
*
*
* @param the common value type
* @param source1
* a {@code MaybeSource} to be merged
* @param source2
* a {@code MaybeSource} to be merged
* @return the new {@code Flowable} instance
* @throws NullPointerException if {@code source1} or {@code source2} is {@code null}
* @see ReactiveX operators documentation: Merge
* @see #mergeDelayError(MaybeSource, MaybeSource)
*/
@BackpressureSupport(BackpressureKind.FULL)
@CheckReturnValue
@NonNull
@SchedulerSupport(SchedulerSupport.NONE)
public static <@NonNull T> Flowable merge(
@NonNull MaybeSource source1, @NonNull MaybeSource source2
) {
Objects.requireNonNull(source1, "source1 is null");
Objects.requireNonNull(source2, "source2 is null");
return mergeArray(source1, source2);
}
/**
* Flattens three {@link MaybeSource}s into a single {@link Flowable}, without any transformation.
*
* 
*
* You can combine items emitted by multiple {@code MaybeSource}s so that they appear as a single {@code Flowable}, by using
* the {@code merge} method.
*
* - Backpressure:
* - The operator honors backpressure from downstream.
* - Scheduler:
* - {@code merge} does not operate by default on a particular {@link Scheduler}.
* - Error handling:
* - If any of the source {@code MaybeSource}s signal a {@link Throwable} via {@code onError}, the resulting
* {@code Flowable} terminates with that {@code Throwable} and all other source {@code MaybeSource}s are disposed.
* If more than one {@code MaybeSource} signals an error, the resulting {@code Flowable} may terminate with the
* first one's error or, depending on the concurrency of the sources, may terminate with a
* {@link CompositeException} containing two or more of the various error signals.
* {@code Throwable}s that didn't make into the composite will be sent (individually) to the global error handler via
* {@link RxJavaPlugins#onError(Throwable)} method as {@link UndeliverableException} errors. Similarly, {@code Throwable}s
* signaled by source(s) after the returned {@code Flowable} has been cancelled or terminated with a
* (composite) error will be sent to the same global error handler.
* Use {@link #mergeDelayError(MaybeSource, MaybeSource, MaybeSource)} to merge sources and terminate only when all source {@code MaybeSource}s
* have completed or failed with an error.
*
*
*
* @param the common value type
* @param source1
* a {@code MaybeSource} to be merged
* @param source2
* a {@code MaybeSource} to be merged
* @param source3
* a {@code MaybeSource} to be merged
* @return the new {@code Flowable} instance
* @throws NullPointerException if {@code source1}, {@code source2} or {@code source3} is {@code null}
* @see ReactiveX operators documentation: Merge
* @see #mergeDelayError(MaybeSource, MaybeSource, MaybeSource)
*/
@BackpressureSupport(BackpressureKind.FULL)
@CheckReturnValue
@NonNull
@SchedulerSupport(SchedulerSupport.NONE)
public static <@NonNull T> Flowable merge(
@NonNull MaybeSource source1, @NonNull MaybeSource source2,
@NonNull MaybeSource source3
) {
Objects.requireNonNull(source1, "source1 is null");
Objects.requireNonNull(source2, "source2 is null");
Objects.requireNonNull(source3, "source3 is null");
return mergeArray(source1, source2, source3);
}
/**
* Flattens four {@link MaybeSource}s into a single {@link Flowable}, without any transformation.
*
* 
*
* You can combine items emitted by multiple {@code MaybeSource}s so that they appear as a single {@code Flowable}, by using
* the {@code merge} method.
*
* - Backpressure:
* - The operator honors backpressure from downstream.
* - Scheduler:
* - {@code merge} does not operate by default on a particular {@link Scheduler}.
* - Error handling:
* - If any of the source {@code MaybeSource}s signal a {@link Throwable} via {@code onError}, the resulting
* {@code Flowable} terminates with that {@code Throwable} and all other source {@code MaybeSource}s are disposed.
* If more than one {@code MaybeSource} signals an error, the resulting {@code Flowable} may terminate with the
* first one's error or, depending on the concurrency of the sources, may terminate with a
* {@link CompositeException} containing two or more of the various error signals.
* {@code Throwable}s that didn't make into the composite will be sent (individually) to the global error handler via
* {@link RxJavaPlugins#onError(Throwable)} method as {@link UndeliverableException} errors. Similarly, {@code Throwable}s
* signaled by source(s) after the returned {@code Flowable} has been cancelled or terminated with a
* (composite) error will be sent to the same global error handler.
* Use {@link #mergeDelayError(MaybeSource, MaybeSource, MaybeSource, MaybeSource)} to merge sources and terminate only when all source {@code MaybeSource}s
* have completed or failed with an error.
*
*
*
* @param the common value type
* @param source1
* a {@code MaybeSource} to be merged
* @param source2
* a {@code MaybeSource} to be merged
* @param source3
* a {@code MaybeSource} to be merged
* @param source4
* a {@code MaybeSource} to be merged
* @return the new {@code Flowable} instance
* @throws NullPointerException if {@code source1}, {@code source2}, {@code source3} or {@code source4} is {@code null}
* @see ReactiveX operators documentation: Merge
* @see #mergeDelayError(MaybeSource, MaybeSource, MaybeSource, MaybeSource)
*/
@BackpressureSupport(BackpressureKind.FULL)
@CheckReturnValue
@NonNull
@SchedulerSupport(SchedulerSupport.NONE)
public static <@NonNull T> Flowable merge(
@NonNull MaybeSource source1, @NonNull MaybeSource source2,
@NonNull MaybeSource source3, @NonNull MaybeSource source4
) {
Objects.requireNonNull(source1, "source1 is null");
Objects.requireNonNull(source2, "source2 is null");
Objects.requireNonNull(source3, "source3 is null");
Objects.requireNonNull(source4, "source4 is null");
return mergeArray(source1, source2, source3, source4);
}
/**
* Merges an array of {@link MaybeSource} instances into a single {@link Flowable} sequence,
* running all {@code MaybeSource}s at once.
*
* 
*
* - Backpressure:
* - The operator honors backpressure from downstream.
* - Scheduler:
* - {@code mergeArray} does not operate by default on a particular {@link Scheduler}.
* - Error handling:
* - If any of the source {@code MaybeSource}s signal a {@link Throwable} via {@code onError}, the resulting
* {@code Flowable} terminates with that {@code Throwable} and all other source {@code MaybeSource}s are disposed.
* If more than one {@code MaybeSource} signals an error, the resulting {@code Flowable} may terminate with the
* first one's error or, depending on the concurrency of the sources, may terminate with a
* {@link CompositeException} containing two or more of the various error signals.
* {@code Throwable}s that didn't make into the composite will be sent (individually) to the global error handler via
* {@link RxJavaPlugins#onError(Throwable)} method as {@link UndeliverableException} errors. Similarly, {@code Throwable}s
* signaled by source(s) after the returned {@code Flowable} has been cancelled or terminated with a
* (composite) error will be sent to the same global error handler.
* Use {@link #mergeArrayDelayError(MaybeSource...)} to merge sources and terminate only when all source {@code MaybeSource}s
* have completed or failed with an error.
*
*
* @param the common and resulting value type
* @param sources the array sequence of {@code MaybeSource} sources
* @return the new {@code Flowable} instance
* @throws NullPointerException if {@code sources} is {@code null}
* @see #mergeArrayDelayError(MaybeSource...)
*/
@BackpressureSupport(BackpressureKind.FULL)
@CheckReturnValue
@NonNull
@SchedulerSupport(SchedulerSupport.NONE)
@SafeVarargs
public static <@NonNull T> Flowable mergeArray(MaybeSource... sources) {
Objects.requireNonNull(sources, "sources is null");
if (sources.length == 0) {
return Flowable.empty();
}
if (sources.length == 1) {
@SuppressWarnings("unchecked")
MaybeSource source = (MaybeSource)sources[0];
return RxJavaPlugins.onAssembly(new MaybeToFlowable<>(source));
}
return RxJavaPlugins.onAssembly(new MaybeMergeArray<>(sources));
}
/**
* Flattens an array of {@link MaybeSource}s into one {@link Flowable}, in a way that allows a subscriber to receive all
* successfully emitted items from each of the source {@code MaybeSource}s without being interrupted by an error
* notification from one of them.
*
* 
*
* This behaves like {@link #merge(Publisher)} except that if any of the merged {@code MaybeSource}s notify of an
* error via {@link Subscriber#onError onError}, {@code mergeArrayDelayError} will refrain from propagating that
* error notification until all of the merged {@code MaybeSource}s have finished emitting items.
*
* Even if multiple merged {@code MaybeSource}s send {@code onError} notifications, {@code mergeArrayDelayError} will only
* invoke the {@code onError} method of its subscribers once.
*
* - Backpressure:
* - The operator honors backpressure from downstream.
* - Scheduler:
* - {@code mergeArrayDelayError} does not operate by default on a particular {@link Scheduler}.
*
*
* @param the common element base type
* @param sources
* the array of {@code MaybeSource}s
* @return the new {@code Flowable} instance
* @throws NullPointerException if {@code sources} is {@code null}
* @see ReactiveX operators documentation: Merge
*/
@BackpressureSupport(BackpressureKind.FULL)
@CheckReturnValue
@SchedulerSupport(SchedulerSupport.NONE)
@SafeVarargs
@NonNull
public static <@NonNull T> Flowable mergeArrayDelayError(@NonNull MaybeSource... sources) {
Objects.requireNonNull(sources, "sources is null");
return Flowable.fromArray(sources).flatMapMaybe(Functions.identity(), true, Math.max(1, sources.length));
}
/**
* Flattens an {@link Iterable} sequence of {@link MaybeSource}s into one {@link Flowable}, in a way that allows a subscriber to receive all
* successfully emitted items from each of the source {@code MaybeSource}s without being interrupted by an error
* notification from one of them.
*
* 
*
* This behaves like {@link #merge(Publisher)} except that if any of the merged {@code MaybeSource}s notify of an
* error via {@link Subscriber#onError onError}, {@code mergeDelayError} will refrain from propagating that
* error notification until all of the merged {@code MaybeSource}s have finished emitting items.
*
*
*
* Even if multiple merged {@code MaybeSource}s send {@code onError} notifications, {@code mergeDelayError} will only
* invoke the {@code onError} method of its subscribers once.
*
* - Backpressure:
* - The operator honors backpressure from downstream.
* - Scheduler:
* - {@code mergeDelayError} does not operate by default on a particular {@link Scheduler}.
*
*
* @param the common element base type
* @param sources
* the {@code Iterable} of {@code MaybeSource}s
* @return the new {@code Flowable} instance
* @throws NullPointerException if {@code sources} is {@code null}
* @see ReactiveX operators documentation: Merge
*/
@BackpressureSupport(BackpressureKind.FULL)
@CheckReturnValue
@SchedulerSupport(SchedulerSupport.NONE)
@NonNull
public static <@NonNull T> Flowable mergeDelayError(@NonNull Iterable<@NonNull ? extends MaybeSource> sources) {
return Flowable.fromIterable(sources).flatMapMaybe(Functions.identity(), true, Integer.MAX_VALUE);
}
/**
* Flattens a {@link Publisher} that emits {@link MaybeSource}s into one {@link Flowable}, in a way that allows a subscriber to
* receive all successfully emitted items from all of the source {@code MaybeSource}s without being interrupted by
* an error notification from one of them or even the main {@code Publisher}.
*
* 
*
* This behaves like {@link #merge(Publisher)} except that if any of the merged {@code MaybeSource}s notify of an
* error via {@link Subscriber#onError onError}, {@code mergeDelayError} will refrain from propagating that
* error notification until all of the merged {@code MaybeSource}s and the main {@code Publisher} have finished emitting items.
*
* Even if multiple merged {@code MaybeSource}s send {@code onError} notifications, {@code mergeDelayError} will only
* invoke the {@code onError} method of its subscribers once.
*
* - Backpressure:
* - The operator honors backpressure from downstream. The outer {@code Publisher} is consumed
* in unbounded mode (i.e., no backpressure is applied to it).
* - Scheduler:
* - {@code mergeDelayError} does not operate by default on a particular {@link Scheduler}.
*
*
* @param the common element base type
* @param sources
* a {@code Publisher} that emits {@code MaybeSource}s
* @return the new {@code Flowable} instance
* @throws NullPointerException if {@code sources} is {@code null}
* @see ReactiveX operators documentation: Merge
*/
@BackpressureSupport(BackpressureKind.FULL)
@CheckReturnValue
@SchedulerSupport(SchedulerSupport.NONE)
@NonNull
public static <@NonNull T> Flowable mergeDelayError(@NonNull Publisher<@NonNull ? extends MaybeSource> sources) {
return mergeDelayError(sources, Integer.MAX_VALUE);
}
/**
* Flattens a {@link Publisher} that emits {@link MaybeSource}s into one {@link Flowable}, in a way that allows a subscriber to
* receive all successfully emitted items from all of the source {@code MaybeSource}s without being interrupted by
* 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.
*
* 
*
* This behaves like {@link #merge(Publisher, int)} except that if any of the merged {@code MaybeSource}s notify of an
* error via {@link Subscriber#onError onError}, {@code mergeDelayError} will refrain from propagating that
* error notification until all of the merged {@code MaybeSource}s and the main {@code Publisher} have finished emitting items.
*
* Even if multiple merged {@code MaybeSource}s send {@code onError} notifications, {@code mergeDelayError} will only
* invoke the {@code onError} method of its subscribers once.
*
* - Backpressure:
* - The operator honors backpressure from downstream. The outer {@code Publisher} is consumed
* in unbounded mode (i.e., no backpressure is applied to it).
* - Scheduler:
* - {@code mergeDelayError} does not operate by default on a particular {@link Scheduler}.
*
* History: 2.1.9 - experimental
* @param the common element base type
* @param sources
* a {@code Publisher} that emits {@code MaybeSource}s
* @param maxConcurrency the maximum number of active inner {@code MaybeSource}s to be merged at a time
* @return the new {@code Flowable} instance
* @throws NullPointerException if {@code sources} is {@code null}
* @throws IllegalArgumentException if {@code maxConcurrency} is non-positive
* @see ReactiveX operators documentation: Merge
* @since 2.2
*/
@BackpressureSupport(BackpressureKind.FULL)
@CheckReturnValue
@NonNull
@SchedulerSupport(SchedulerSupport.NONE)
public static <@NonNull T> Flowable mergeDelayError(@NonNull Publisher<@NonNull ? extends MaybeSource> sources, int maxConcurrency) {
Objects.requireNonNull(sources, "sources is null");
ObjectHelper.verifyPositive(maxConcurrency, "maxConcurrency");
return RxJavaPlugins.onAssembly(new FlowableFlatMapMaybePublisher<>(sources, Functions.identity(), true, maxConcurrency));
}
/**
* Flattens two {@link MaybeSource}s into one {@link Flowable}, in a way that allows a subscriber to receive all
* successfully emitted items from each of the source {@code MaybeSource}s without being interrupted by an error
* notification from one of them.
*
* 
*
* This behaves like {@link #merge(MaybeSource, MaybeSource)} except that if any of the merged {@code MaybeSource}s
* notify of an error via {@link Subscriber#onError onError}, {@code mergeDelayError} will refrain from
* propagating that error notification until all of the merged {@code MaybeSource}s have finished emitting items.
*
* Even if both merged {@code MaybeSource}s send {@code onError} notifications, {@code mergeDelayError} will only
* invoke the {@code onError} method of its subscribers once.
*
* - Backpressure:
* - The operator honors backpressure from downstream.
* - Scheduler:
* - {@code mergeDelayError} does not operate by default on a particular {@link Scheduler}.
*
*
* @param the common element base type
* @param source1
* a {@code MaybeSource} to be merged
* @param source2
* a {@code MaybeSource} to be merged
* @return the new {@code Flowable} instance
* @throws NullPointerException if {@code source1} or {@code source2} is {@code null}
* @see ReactiveX operators documentation: Merge
*/
@BackpressureSupport(BackpressureKind.FULL)
@CheckReturnValue
@NonNull
@SchedulerSupport(SchedulerSupport.NONE)
public static <@NonNull T> Flowable mergeDelayError(@NonNull MaybeSource source1, @NonNull MaybeSource source2) {
Objects.requireNonNull(source1, "source1 is null");
Objects.requireNonNull(source2, "source2 is null");
return mergeArrayDelayError(source1, source2);
}
/**
* Flattens three {@link MaybeSource} into one {@link Flowable}, in a way that allows a subscriber to receive all
* successfully emitted items from all of the source {@code MaybeSource}s without being interrupted by an error
* notification from one of them.
*
* 
*
* This behaves like {@link #merge(MaybeSource, MaybeSource, MaybeSource)} except that if any of the merged
* {@code MaybeSource}s notify of an error via {@link Subscriber#onError onError}, {@code mergeDelayError} will refrain
* from propagating that error notification until all of the merged {@code MaybeSource}s have finished emitting
* items.
*
* Even if multiple merged {@code MaybeSource}s send {@code onError} notifications, {@code mergeDelayError} will only
* invoke the {@code onError} method of its subscribers once.
*
* - Backpressure:
* - The operator honors backpressure from downstream.
* - Scheduler:
* - {@code mergeDelayError} does not operate by default on a particular {@link Scheduler}.
*
*
* @param the common element base type
* @param source1
* a {@code MaybeSource} to be merged
* @param source2
* a {@code MaybeSource} to be merged
* @param source3
* a {@code MaybeSource} to be merged
* @return the new {@code Flowable} instance
* @throws NullPointerException if {@code source1}, {@code source2} or {@code source3} is {@code null}
* @see ReactiveX operators documentation: Merge
*/
@BackpressureSupport(BackpressureKind.FULL)
@CheckReturnValue
@NonNull
@SchedulerSupport(SchedulerSupport.NONE)
public static <@NonNull T> Flowable mergeDelayError(@NonNull MaybeSource source1,
@NonNull MaybeSource source2, @NonNull MaybeSource source3) {
Objects.requireNonNull(source1, "source1 is null");
Objects.requireNonNull(source2, "source2 is null");
Objects.requireNonNull(source3, "source3 is null");
return mergeArrayDelayError(source1, source2, source3);
}
/**
* Flattens four {@link MaybeSource}s into one {@link Flowable}, in a way that allows a subscriber to receive all
* successfully emitted items from all of the source {@code MaybeSource}s without being interrupted by an error
* notification from one of them.
*
* 
*
* This behaves like {@link #merge(MaybeSource, MaybeSource, MaybeSource, MaybeSource)} except that if any of
* the merged {@code MaybeSource}s notify of an error via {@link Subscriber#onError onError}, {@code mergeDelayError}
* will refrain from propagating that error notification until all of the merged {@code MaybeSource}s have finished
* emitting items.
*
* Even if multiple merged {@code MaybeSource}s send {@code onError} notifications, {@code mergeDelayError} will only
* invoke the {@code onError} method of its subscribers once.
*
* - Backpressure:
* - The operator honors backpressure from downstream.
* - Scheduler:
* - {@code mergeDelayError} does not operate by default on a particular {@link Scheduler}.
*
*
* @param the common element base type
* @param source1
* a {@code MaybeSource} to be merged
* @param source2
* a {@code MaybeSource} to be merged
* @param source3
* a {@code MaybeSource} to be merged
* @param source4
* a {@code MaybeSource} to be merged
* @return the new {@code Flowable} instance
* @throws NullPointerException if {@code source1}, {@code source2}, {@code source3} or {@code source4} is {@code null}
* @see ReactiveX operators documentation: Merge
*/
@BackpressureSupport(BackpressureKind.FULL)
@CheckReturnValue
@NonNull
@SchedulerSupport(SchedulerSupport.NONE)
public static <@NonNull T> Flowable mergeDelayError(
@NonNull MaybeSource source1, @NonNull MaybeSource source2,
@NonNull MaybeSource source3, @NonNull MaybeSource source4) {
Objects.requireNonNull(source1, "source1 is null");
Objects.requireNonNull(source2, "source2 is null");
Objects.requireNonNull(source3, "source3 is null");
Objects.requireNonNull(source4, "source4 is null");
return mergeArrayDelayError(source1, source2, source3, source4);
}
/**
* Returns a {@code Maybe} that never sends any items or notifications to a {@link MaybeObserver}.
*
* 
*
* This {@code Maybe} is useful primarily for testing purposes.
*
* - Scheduler:
* - {@code never} does not operate by default on a particular {@link Scheduler}.
*
*
* @param
* the type of items (not) emitted by the {@code Maybe}
* @return the shared {@code Maybe} instance
* @see ReactiveX operators documentation: Never
*/
@CheckReturnValue
@SchedulerSupport(SchedulerSupport.NONE)
@SuppressWarnings("unchecked")
@NonNull
public static <@NonNull T> Maybe never() {
return RxJavaPlugins.onAssembly((Maybe)MaybeNever.INSTANCE);
}
/**
* Returns a {@link Single} that emits a {@link Boolean} value that indicates whether two {@link MaybeSource} sequences are the
* same by comparing the items emitted by each {@code MaybeSource} pairwise.
*
* 
*
* - Scheduler:
* - {@code sequenceEqual} does not operate by default on a particular {@link Scheduler}.
*
*
* @param source1
* the first {@code MaybeSource} to compare
* @param source2
* the second {@code MaybeSource} to compare
* @param
* the type of items emitted by each {@code MaybeSource}
* @return the new {@code Single} instance
* @throws NullPointerException if {@code source1} or {@code source2} is {@code null}
* @see ReactiveX operators documentation: SequenceEqual
*/
@CheckReturnValue
@SchedulerSupport(SchedulerSupport.NONE)
@NonNull
public static <@NonNull T> Single sequenceEqual(@NonNull MaybeSource source1, @NonNull MaybeSource source2) {
return sequenceEqual(source1, source2, ObjectHelper.equalsPredicate());
}
/**
* Returns a {@link Single} that emits a {@link Boolean} value that indicates whether two {@link MaybeSource}s are the
* same by comparing the items emitted by each {@code MaybeSource} pairwise based on the results of a specified
* equality function.
*
* 
*
* - Scheduler:
* - {@code sequenceEqual} does not operate by default on a particular {@link Scheduler}.
*
*
* @param source1
* the first {@code MaybeSource} to compare
* @param source2
* the second {@code MaybeSource} to compare
* @param isEqual
* a function used to compare items emitted by each {@code MaybeSource}
* @param
* the type of items emitted by each {@code MaybeSource}
* @return the new {@code Single} instance
* @throws NullPointerException if {@code source1}, {@code source2} or {@code isEqual} is {@code null}
* @see ReactiveX operators documentation: SequenceEqual
*/
@CheckReturnValue
@NonNull
@SchedulerSupport(SchedulerSupport.NONE)
public static <@NonNull T> Single sequenceEqual(@NonNull MaybeSource source1, @NonNull MaybeSource source2,
@NonNull BiPredicate isEqual) {
Objects.requireNonNull(source1, "source1 is null");
Objects.requireNonNull(source2, "source2 is null");
Objects.requireNonNull(isEqual, "isEqual is null");
return RxJavaPlugins.onAssembly(new MaybeEqualSingle<>(source1, source2, isEqual));
}
/**
* Switches between {@link MaybeSource}s emitted by the source {@link Publisher} whenever
* a new {@code MaybeSource} is emitted, disposing the previously running {@code MaybeSource},
* exposing the success items as a {@link Flowable} sequence.
*
* 
*
* - Backpressure:
* - The {@code sources} {@code Publisher} is consumed in an unbounded manner (requesting {@link Long#MAX_VALUE}).
* The returned {@code Flowable} respects the backpressure from the downstream.
* - Scheduler:
* - {@code switchOnNext} does not operate by default on a particular {@link Scheduler}.
* - Error handling:
* - The returned sequence fails with the first error signaled by the {@code sources} {@code Publisher}
* or the currently running {@code MaybeSource}, disposing the rest. Late errors are
* forwarded to the global error handler via {@link RxJavaPlugins#onError(Throwable)}.
*
* @param the element type of the {@code MaybeSource}s
* @param sources the {@code Publisher} sequence of inner {@code MaybeSource}s to switch between
* @return the new {@code Flowable} instance
* @throws NullPointerException if {@code sources} is {@code null}
* @since 3.0.0
* @see #switchOnNextDelayError(Publisher)
* @see ReactiveX operators documentation: Switch
*/
@BackpressureSupport(BackpressureKind.UNBOUNDED_IN)
@CheckReturnValue
@NonNull
@SchedulerSupport(SchedulerSupport.NONE)
public static <@NonNull T> Flowable switchOnNext(@NonNull Publisher<@NonNull ? extends MaybeSource> sources) {
Objects.requireNonNull(sources, "sources is null");
return RxJavaPlugins.onAssembly(new FlowableSwitchMapMaybePublisher<>(sources, Functions.identity(), false));
}
/**
* Switches between {@link MaybeSource}s emitted by the source {@link Publisher} whenever
* a new {@code MaybeSource} is emitted, disposing the previously running {@code MaybeSource},
* exposing the success items as a {@link Flowable} sequence and delaying all errors from
* all of them until all terminate.
*
* 
*
* - Backpressure:
* - The {@code sources} {@code Publisher} is consumed in an unbounded manner (requesting {@link Long#MAX_VALUE}).
* The returned {@code Flowable} respects the backpressure from the downstream.
* - Scheduler:
* - {@code switchOnNextDelayError} does not operate by default on a particular {@link Scheduler}.
* - Error handling:
* - The returned {@code Flowable} collects all errors emitted by either the {@code sources}
* {@code Publisher} or any inner {@code MaybeSource} and emits them as a {@link CompositeException}
* when all sources terminate. If only one source ever failed, its error is emitted as-is at the end.
*
* @param the element type of the {@code MaybeSource}s
* @param sources the {@code Publisher} sequence of inner {@code MaybeSource}s to switch between
* @return the new {@code Flowable} instance
* @throws NullPointerException if {@code sources} is {@code null}
* @since 3.0.0
* @see #switchOnNext(Publisher)
* @see ReactiveX operators documentation: Switch
*/
@BackpressureSupport(BackpressureKind.FULL)
@CheckReturnValue
@NonNull
@SchedulerSupport(SchedulerSupport.NONE)
public static <@NonNull T> Flowable switchOnNextDelayError(@NonNull Publisher<@NonNull ? extends MaybeSource> sources) {
Objects.requireNonNull(sources, "sources is null");
return RxJavaPlugins.onAssembly(new FlowableSwitchMapMaybePublisher<>(sources, Functions.identity(), true));
}
/**
* Returns a {@code Maybe} that emits {@code 0L} after a specified delay.
*
* 
*
* - Scheduler:
* - {@code timer} operates by default on the {@code computation} {@link Scheduler}.
*
*
* @param delay
* the initial delay before emitting a single {@code 0L}
* @param unit
* time units to use for {@code delay}
* @return the new {@code Maybe} instance
* @throws NullPointerException if {@code unit} is {@code null}
* @see ReactiveX operators documentation: Timer
*/
@CheckReturnValue
@SchedulerSupport(SchedulerSupport.COMPUTATION)
@NonNull
public static Maybe timer(long delay, @NonNull TimeUnit unit) {
return timer(delay, unit, Schedulers.computation());
}
/**
* Returns a {@code Maybe} that emits {@code 0L} after a specified delay on a specified {@link Scheduler}.
*
* 
*
* - Scheduler:
* - You specify which {@code Scheduler} this operator will use.
*
*
* @param delay
* the initial delay before emitting a single 0L
* @param unit
* time units to use for {@code delay}
* @param scheduler
* the {@code Scheduler} to use for scheduling the item
* @return the new {@code Maybe} instance
* @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null}
* @see ReactiveX operators documentation: Timer
*/
@CheckReturnValue
@NonNull
@SchedulerSupport(SchedulerSupport.CUSTOM)
public static Maybe timer(long delay, @NonNull TimeUnit unit, @NonNull Scheduler scheduler) {
Objects.requireNonNull(unit, "unit is null");
Objects.requireNonNull(scheduler, "scheduler is null");
return RxJavaPlugins.onAssembly(new MaybeTimer(Math.max(0L, delay), unit, scheduler));
}
/**
* Advanced use only: creates a {@code Maybe} instance without
* any safeguards by using a callback that is called with a {@link MaybeObserver}.
*
* 
*
* - Scheduler:
* - {@code unsafeCreate} does not operate by default on a particular {@link Scheduler}.
*
* @param the value type
* @param onSubscribe the function that is called with the subscribing {@code MaybeObserver}
* @return the new {@code Maybe} instance
* @throws IllegalArgumentException if {@code onSubscribe} is a {@code Maybe}
* @throws NullPointerException if {@code onSubscribe} is {@code null}
*/
@CheckReturnValue
@NonNull
@SchedulerSupport(SchedulerSupport.NONE)
public static <@NonNull T> Maybe unsafeCreate(@NonNull MaybeSource onSubscribe) {
if (onSubscribe instanceof Maybe) {
throw new IllegalArgumentException("unsafeCreate(Maybe) should be upgraded");
}
Objects.requireNonNull(onSubscribe, "onSubscribe is null");
return RxJavaPlugins.onAssembly(new MaybeUnsafeCreate<>(onSubscribe));
}
/**
* Constructs a {@code Maybe} that creates a dependent resource object which is disposed of when the
* generated {@link MaybeSource} terminates or the downstream calls dispose().
*
* 
*
* - Scheduler:
* - {@code using} does not operate by default on a particular {@link Scheduler}.
*
*
* @param the element type of the generated {@code MaybeSource}
* @param the type of the resource associated with the output sequence
* @param resourceSupplier
* the factory function to create a resource object that depends on the {@code Maybe}
* @param sourceSupplier
* the factory function to create a {@code MaybeSource}
* @param resourceCleanup
* the function that will dispose of the resource
* @return the new {@code Maybe} instance
* @throws NullPointerException if {@code resourceSupplier}, {@code sourceSupplier} or {@code resourceCleanup} is {@code null}
* @see ReactiveX operators documentation: Using
*/
@CheckReturnValue
@SchedulerSupport(SchedulerSupport.NONE)
@NonNull
public static <@NonNull T, @NonNull D> Maybe using(@NonNull Supplier resourceSupplier,
@NonNull Function> sourceSupplier,
@NonNull Consumer resourceCleanup) {
return using(resourceSupplier, sourceSupplier, resourceCleanup, true);
}
/**
* Constructs a {@code Maybe} that creates a dependent resource object which is disposed first ({code eager == true})
* when the generated {@link MaybeSource} terminates or the downstream disposes; or after ({code eager == false}).
*
* 
*
* Eager disposal is particularly appropriate for a synchronous {@code Maybe} that reuses resources. {@code disposeAction} will
* only be called once per subscription.
*
* - Scheduler:
* - {@code using} does not operate by default on a particular {@link Scheduler}.
*
*
* @param the element type of the generated {@code MaybeSource}
* @param the type of the resource associated with the output sequence
* @param resourceSupplier
* the factory function to create a resource object that depends on the {@code Maybe}
* @param sourceSupplier
* the factory function to create a {@code MaybeSource}
* @param resourceCleanup
* the function that will dispose of the resource
* @param eager
* If {@code true} then resource disposal will happen either on a {@code dispose()} call before the upstream is disposed
* or just before the emission of a terminal event ({@code onSuccess}, {@code onComplete} or {@code onError}).
* If {@code false} the resource disposal will happen either on a {@code dispose()} call after the upstream is disposed
* or just after the emission of a terminal event ({@code onSuccess}, {@code onComplete} or {@code onError}).
* @return the new {@code Maybe} instance
* @throws NullPointerException if {@code resourceSupplier}, {@code sourceSupplier} or {@code resourceCleanup} is {@code null}
* @see ReactiveX operators documentation: Using
*/
@CheckReturnValue
@NonNull
@SchedulerSupport(SchedulerSupport.NONE)
public static <@NonNull T, @NonNull D> Maybe using(@NonNull Supplier resourceSupplier,
@NonNull Function> sourceSupplier,
@NonNull Consumer resourceCleanup, boolean eager) {
Objects.requireNonNull(resourceSupplier, "resourceSupplier is null");
Objects.requireNonNull(sourceSupplier, "sourceSupplier is null");
Objects.requireNonNull(resourceCleanup, "resourceCleanup is null");
return RxJavaPlugins.onAssembly(new MaybeUsing(resourceSupplier, sourceSupplier, resourceCleanup, eager));
}
/**
* Wraps a {@link MaybeSource} instance into a new {@code Maybe} instance if not already a {@code Maybe}
* instance.
*
* 
*
* - Scheduler:
* - {@code wrap} does not operate by default on a particular {@link Scheduler}.
*
* @param the value type
* @param source the source to wrap
* @return the new wrapped or cast {@code Maybe} instance
* @throws NullPointerException if {@code source} is {@code null}
*/
@CheckReturnValue
@NonNull
@SchedulerSupport(SchedulerSupport.NONE)
public static <@NonNull T> Maybe wrap(@NonNull MaybeSource source) {
if (source instanceof Maybe) {
return RxJavaPlugins.onAssembly((Maybe)source);
}
Objects.requireNonNull(source, "source is null");
return RxJavaPlugins.onAssembly(new MaybeUnsafeCreate<>(source));
}
/**
* Returns a {@code Maybe} that emits the results of a specified combiner function applied to combinations of
* items emitted, in sequence, by an {@link Iterable} of other {@link MaybeSource}s.
*
* 
*
* Note on method signature: since Java doesn't allow creating a generic array with {@code new T[]}, the
* implementation of this operator has to create an {@code Object[]} instead. Unfortunately, a
* {@code Function} passed to the method would trigger a {@link ClassCastException}.
*
* This operator terminates eagerly if any of the source {@code MaybeSource}s signal an {@code onError} or {@code onComplete}. This
* also means it is possible some sources may not get subscribed to at all.
*
* - Scheduler:
* - {@code zip} does not operate by default on a particular {@link Scheduler}.
*
*
* @param the common value type
* @param the zipped result type
* @param sources
* an {@code Iterable} of source {@code MaybeSource}s
* @param zipper
* a function that, when applied to an item emitted by each of the source {@code MaybeSource}s, results in
* an item that will be emitted by the resulting {@code Maybe}
* @return the new {@code Maybe} instance
* @throws NullPointerException if {@code zipper} or {@code sources} is {@code null}
* @see ReactiveX operators documentation: Zip
*/
@CheckReturnValue
@NonNull
@SchedulerSupport(SchedulerSupport.NONE)
public static <@NonNull T, @NonNull R> Maybe zip(@NonNull Iterable<@NonNull ? extends MaybeSource> sources, @NonNull Function zipper) {
Objects.requireNonNull(zipper, "zipper is null");
Objects.requireNonNull(sources, "sources is null");
return RxJavaPlugins.onAssembly(new MaybeZipIterable<>(sources, zipper));
}
/**
* Returns a {@code Maybe} that emits the results of a specified combiner function applied to combinations of
* two items emitted, in sequence, by two other {@link MaybeSource}s.
*
* 
*
* This operator terminates eagerly if any of the source {@code MaybeSource}s signal an {@code onError} or {@code onComplete}. This
* also means it is possible some sources may not get subscribed to at all.
*
* - Scheduler:
* - {@code zip} does not operate by default on a particular {@link Scheduler}.
*
*
* @param the value type of the first source
* @param the value type of the second source
* @param the zipped result type
* @param source1
* the first source {@code MaybeSource}
* @param source2
* a second source {@code MaybeSource}
* @param zipper
* a function that, when applied to an item emitted by each of the source {@code MaybeSource}s, results
* in an item that will be emitted by the resulting {@code Maybe}
* @return the new {@code Maybe} instance
* @throws NullPointerException if {@code source1}, {@code source2} or {@code zipper} is {@code null}
* @see ReactiveX operators documentation: Zip
*/
@CheckReturnValue
@NonNull
@SchedulerSupport(SchedulerSupport.NONE)
public static <@NonNull T1, @NonNull T2, @NonNull R> Maybe zip(
@NonNull MaybeSource source1, @NonNull MaybeSource source2,
@NonNull BiFunction zipper) {
Objects.requireNonNull(source1, "source1 is null");
Objects.requireNonNull(source2, "source2 is null");
Objects.requireNonNull(zipper, "zipper is null");
return zipArray(Functions.toFunction(zipper), source1, source2);
}
/**
* Returns a {@code Maybe} that emits the results of a specified combiner function applied to combinations of
* three items emitted, in sequence, by three other {@link MaybeSource}s.
*
*
*
* This operator terminates eagerly if any of the source {@code MaybeSource}s signal an {@code onError} or {@code onComplete}. This
* also means it is possible some sources may not get subscribed to at all.
*
* - Scheduler:
* - {@code zip} does not operate by default on a particular {@link Scheduler}.
*
*
* @param the value type of the first source
* @param the value type of the second source
* @param the value type of the third source
* @param the zipped result type
* @param source1
* the first source {@code MaybeSource}
* @param source2
* a second source {@code MaybeSource}
* @param source3
* a third source {@code MaybeSource}
* @param zipper
* a function that, when applied to an item emitted by each of the source {@code MaybeSource}s, results in
* an item that will be emitted by the resulting {@code Maybe}
* @return the new {@code Maybe} instance
* @throws NullPointerException if {@code source1}, {@code source2}, {@code source3} or {@code zipper} is {@code null}
* @see ReactiveX operators documentation: Zip
*/
@CheckReturnValue
@NonNull
@SchedulerSupport(SchedulerSupport.NONE)
public static <@NonNull T1, @NonNull T2, @NonNull T3, @NonNull R> Maybe zip(
@NonNull MaybeSource source1, @NonNull MaybeSource source2, @NonNull MaybeSource source3,
@NonNull Function3 zipper) {
Objects.requireNonNull(source1, "source1 is null");
Objects.requireNonNull(source2, "source2 is null");
Objects.requireNonNull(source3, "source3 is null");
Objects.requireNonNull(zipper, "zipper is null");
return zipArray(Functions.toFunction(zipper), source1, source2, source3);
}
/**
* Returns a {@code Maybe} that emits the results of a specified combiner function applied to combinations of
* four items emitted, in sequence, by four other {@link MaybeSource}s.
*
*
*
* This operator terminates eagerly if any of the source {@code MaybeSource}s signal an {@code onError} or {@code onComplete}. This
* also means it is possible some sources may not get subscribed to at all.
*
* - Scheduler:
* - {@code zip} does not operate by default on a particular {@link Scheduler}.
*
*
* @param the value type of the first source
* @param the value type of the second source
* @param the value type of the third source
* @param the value type of the fourth source
* @param the zipped result type
* @param source1
* the first source {@code MaybeSource}
* @param source2
* a second source {@code MaybeSource}
* @param source3
* a third source {@code MaybeSource}
* @param source4
* a fourth source {@code MaybeSource}
* @param zipper
* a function that, when applied to an item emitted by each of the source {@code MaybeSource}s, results in
* an item that will be emitted by the resulting {@code Maybe}
* @return the new {@code Maybe} instance
* @throws NullPointerException if {@code source1}, {@code source2}, {@code source3},
* {@code source4} or {@code zipper} is {@code null}
* @see ReactiveX operators documentation: Zip
*/
@CheckReturnValue
@NonNull
@SchedulerSupport(SchedulerSupport.NONE)
public static <@NonNull T1, @NonNull T2, @NonNull T3, @NonNull T4, @NonNull R> Maybe zip(
@NonNull MaybeSource source1, @NonNull MaybeSource source2, @NonNull MaybeSource source3,
@NonNull MaybeSource source4,
@NonNull Function4 zipper) {
Objects.requireNonNull(source1, "source1 is null");
Objects.requireNonNull(source2, "source2 is null");
Objects.requireNonNull(source3, "source3 is null");
Objects.requireNonNull(source4, "source4 is null");
Objects.requireNonNull(zipper, "zipper is null");
return zipArray(Functions.toFunction(zipper), source1, source2, source3, source4);
}
/**
* Returns a {@code Maybe} that emits the results of a specified combiner function applied to combinations of
* five items emitted, in sequence, by five other {@link MaybeSource}s.
*
*
*
* This operator terminates eagerly if any of the source {@code MaybeSource}s signal an {@code onError} or {@code onComplete}. This
* also means it is possible some sources may not get subscribed to at all.
*
* - Scheduler:
* - {@code zip} does not operate by default on a particular {@link Scheduler}.
*
*
* @param the value type of the first source
* @param the value type of the second source
* @param the value type of the third source
* @param the value type of the fourth source
* @param the value type of the fifth source
* @param the zipped result type
* @param source1
* the first source {@code MaybeSource}
* @param source2
* a second source {@code MaybeSource}
* @param source3
* a third source {@code MaybeSource}
* @param source4
* a fourth source {@code MaybeSource}
* @param source5
* a fifth source {@code MaybeSource}
* @param zipper
* a function that, when applied to an item emitted by each of the source {@code MaybeSource}s, results in
* an item that will be emitted by the resulting {@code Maybe}
* @return the new {@code Maybe} instance
* @throws NullPointerException if {@code source1}, {@code source2}, {@code source3},
* {@code source4}, {@code source5} or {@code zipper} is {@code null}
* @see ReactiveX operators documentation: Zip
*/
@CheckReturnValue
@NonNull
@SchedulerSupport(SchedulerSupport.NONE)
public static <@NonNull T1, @NonNull T2, @NonNull T3, @NonNull T4, @NonNull T5, @NonNull R> Maybe zip(
@NonNull MaybeSource source1, @NonNull MaybeSource source2, @NonNull MaybeSource source3,
@NonNull MaybeSource source4, @NonNull MaybeSource source5,
@NonNull Function5 zipper) {
Objects.requireNonNull(source1, "source1 is null");
Objects.requireNonNull(source2, "source2 is null");
Objects.requireNonNull(source3, "source3 is null");
Objects.requireNonNull(source4, "source4 is null");
Objects.requireNonNull(source5, "source5 is null");
Objects.requireNonNull(zipper, "zipper is null");
return zipArray(Functions.toFunction(zipper), source1, source2, source3, source4, source5);
}
/**
* Returns a {@code Maybe} that emits the results of a specified combiner function applied to combinations of
* six items emitted, in sequence, by six other {@link MaybeSource}s.
*
*
*
* This operator terminates eagerly if any of the source {@code MaybeSource}s signal an {@code onError} or {@code onComplete}. This
* also means it is possible some sources may not get subscribed to at all.
*
* - Scheduler:
* - {@code zip} does not operate by default on a particular {@link Scheduler}.
*
*
* @param the value type of the first source
* @param the value type of the second source
* @param the value type of the third source
* @param the value type of the fourth source
* @param the value type of the fifth source
* @param the value type of the sixth source
* @param the zipped result type
* @param source1
* the first source {@code MaybeSource}
* @param source2
* a second source {@code MaybeSource}
* @param source3
* a third source {@code MaybeSource}
* @param source4
* a fourth source {@code MaybeSource}
* @param source5
* a fifth source {@code MaybeSource}
* @param source6
* a sixth source {@code MaybeSource}
* @param zipper
* a function that, when applied to an item emitted by each of the source {@code MaybeSource}s, results in
* an item that will be emitted by the resulting {@code Maybe}
* @return the new {@code Maybe} instance
* @throws NullPointerException if {@code source1}, {@code source2}, {@code source3},
* {@code source4}, {@code source5}, {@code source6} or {@code zipper} is {@code null}
* @see ReactiveX operators documentation: Zip
*/
@CheckReturnValue
@NonNull
@SchedulerSupport(SchedulerSupport.NONE)
public static <@NonNull T1, @NonNull T2, @NonNull T3, @NonNull T4, @NonNull T5, @NonNull T6, @NonNull R> Maybe zip(
@NonNull MaybeSource source1, @NonNull MaybeSource source2, @NonNull MaybeSource source3,
@NonNull MaybeSource source4, @NonNull MaybeSource source5, @NonNull MaybeSource source6,
@NonNull Function6 zipper) {
Objects.requireNonNull(source1, "source1 is null");
Objects.requireNonNull(source2, "source2 is null");
Objects.requireNonNull(source3, "source3 is null");
Objects.requireNonNull(source4, "source4 is null");
Objects.requireNonNull(source5, "source5 is null");
Objects.requireNonNull(source6, "source6 is null");
Objects.requireNonNull(zipper, "zipper is null");
return zipArray(Functions.toFunction(zipper), source1, source2, source3, source4, source5, source6);
}
/**
* Returns a {@code Maybe} that emits the results of a specified combiner function applied to combinations of
* seven items emitted, in sequence, by seven other {@link MaybeSource}s.
*
*
*
* This operator terminates eagerly if any of the source {@code MaybeSource}s signal an {@code onError} or {@code onComplete}. This
* also means it is possible some sources may not get subscribed to at all.
*
* - Scheduler:
* - {@code zip} does not operate by default on a particular {@link Scheduler}.
*
*
* @param the value type of the first source
* @param the value type of the second source
* @param the value type of the third source
* @param the value type of the fourth source
* @param the value type of the fifth source
* @param the value type of the sixth source
* @param the value type of the seventh source
* @param the zipped result type
* @param source1
* the first source {@code MaybeSource}
* @param source2
* a second source {@code MaybeSource}
* @param source3
* a third source {@code MaybeSource}
* @param source4
* a fourth source {@code MaybeSource}
* @param source5
* a fifth source {@code MaybeSource}
* @param source6
* a sixth source {@code MaybeSource}
* @param source7
* a seventh source {@code MaybeSource}
* @param zipper
* a function that, when applied to an item emitted by each of the source {@code MaybeSource}s, results in
* an item that will be emitted by the resulting {@code Maybe}
* @throws NullPointerException if {@code source1}, {@code source2}, {@code source3},
* {@code source4}, {@code source5}, {@code source6},
* {@code source7} or {@code zipper} is {@code null}
* @return the new {@code Maybe} instance
* @see ReactiveX operators documentation: Zip
*/
@CheckReturnValue
@NonNull
@SchedulerSupport(SchedulerSupport.NONE)
public static <@NonNull T1, @NonNull T2, @NonNull T3, @NonNull T4, @NonNull T5, @NonNull T6, @NonNull T7, @NonNull R> Maybe zip(
@NonNull MaybeSource source1, @NonNull MaybeSource source2, @NonNull MaybeSource source3,
@NonNull MaybeSource source4, @NonNull MaybeSource source5, @NonNull MaybeSource source6,
@NonNull MaybeSource source7,
@NonNull Function7 zipper) {
Objects.requireNonNull(source1, "source1 is null");
Objects.requireNonNull(source2, "source2 is null");
Objects.requireNonNull(source3, "source3 is null");
Objects.requireNonNull(source4, "source4 is null");
Objects.requireNonNull(source5, "source5 is null");
Objects.requireNonNull(source6, "source6 is null");
Objects.requireNonNull(source7, "source7 is null");
Objects.requireNonNull(zipper, "zipper is null");
return zipArray(Functions.toFunction(zipper), source1, source2, source3, source4, source5, source6, source7);
}
/**
* Returns a {@code Maybe} that emits the results of a specified combiner function applied to combinations of
* eight items emitted, in sequence, by eight other {@link MaybeSource}s.
*
*
*
* This operator terminates eagerly if any of the source {@code MaybeSource}s signal an {@code onError} or {@code onComplete}. This
* also means it is possible some sources may not get subscribed to at all.
*
* - Scheduler:
* - {@code zip} does not operate by default on a particular {@link Scheduler}.
*
*
* @param the value type of the first source
* @param the value type of the second source
* @param the value type of the third source
* @param the value type of the fourth source
* @param the value type of the fifth source
* @param the value type of the sixth source
* @param the value type of the seventh source
* @param the value type of the eighth source
* @param the zipped result type
* @param source1
* the first source {@code MaybeSource}
* @param source2
* a second source {@code MaybeSource}
* @param source3
* a third source {@code MaybeSource}
* @param source4
* a fourth source {@code MaybeSource}
* @param source5
* a fifth source {@code MaybeSource}
* @param source6
* a sixth source {@code MaybeSource}
* @param source7
* a seventh source {@code MaybeSource}
* @param source8
* an eighth source {@code MaybeSource}
* @param zipper
* a function that, when applied to an item emitted by each of the source {@code MaybeSource}s, results in
* an item that will be emitted by the resulting {@code Maybe}
* @return the new {@code Maybe} instance
* @throws NullPointerException if {@code source1}, {@code source2}, {@code source3},
* {@code source4}, {@code source5}, {@code source6},
* {@code source7}, {@code source8} or {@code zipper} is {@code null}
* @see ReactiveX operators documentation: Zip
*/
@CheckReturnValue
@NonNull
@SchedulerSupport(SchedulerSupport.NONE)
public static <@NonNull T1, @NonNull T2, @NonNull T3, @NonNull T4, @NonNull T5, @NonNull T6, @NonNull T7, @NonNull T8, @NonNull R> Maybe zip(
@NonNull MaybeSource source1, @NonNull MaybeSource source2, @NonNull MaybeSource source3,
@NonNull MaybeSource source4, @NonNull MaybeSource source5, @NonNull MaybeSource source6,
@NonNull MaybeSource source7, @NonNull MaybeSource source8,
@NonNull Function8 zipper) {
Objects.requireNonNull(source1, "source1 is null");
Objects.requireNonNull(source2, "source2 is null");
Objects.requireNonNull(source3, "source3 is null");
Objects.requireNonNull(source4, "source4 is null");
Objects.requireNonNull(source5, "source5 is null");
Objects.requireNonNull(source6, "source6 is null");
Objects.requireNonNull(source7, "source7 is null");
Objects.requireNonNull(source8, "source8 is null");
Objects.requireNonNull(zipper, "zipper is null");
return zipArray(Functions.toFunction(zipper), source1, source2, source3, source4, source5, source6, source7, source8);
}
/**
* Returns a {@code Maybe} that emits the results of a specified combiner function applied to combinations of
* nine items emitted, in sequence, by nine other {@link MaybeSource}s.
*
*
*
* This operator terminates eagerly if any of the source {@code MaybeSource}s signal an {@code onError} or {@code onComplete}. This
* also means it is possible some sources may not get subscribed to at all.
*
* - Scheduler:
* - {@code zip} does not operate by default on a particular {@link Scheduler}.
*
* @param the value type of the first source
* @param the value type of the second source
* @param the value type of the third source
* @param the value type of the fourth source
* @param the value type of the fifth source
* @param the value type of the sixth source
* @param the value type of the seventh source
* @param the value type of the eighth source
* @param the value type of the ninth source
* @param the zipped result type
* @param source1
* the first source {@code MaybeSource}
* @param source2
* a second source {@code MaybeSource}
* @param source3
* a third source {@code MaybeSource}
* @param source4
* a fourth source {@code MaybeSource}
* @param source5
* a fifth source {@code MaybeSource}
* @param source6
* a sixth source {@code MaybeSource}
* @param source7
* a seventh source {@code MaybeSource}
* @param source8
* an eighth source {@code MaybeSource}
* @param source9
* a ninth source {@code MaybeSource}
* @param zipper
* a function that, when applied to an item emitted by each of the source {@code MaybeSource}s, results in
* an item that will be emitted by the resulting {@code Maybe}
* @return the new {@code Maybe} instance
* @throws NullPointerException if {@code source1}, {@code source2}, {@code source3},
* {@code source4}, {@code source5}, {@code source6},
* {@code source7}, {@code source8}, {@code source9} or {@code zipper} is {@code null}
* @see ReactiveX operators documentation: Zip
*/
@CheckReturnValue
@NonNull
@SchedulerSupport(SchedulerSupport.NONE)
public static <@NonNull T1, @NonNull T2, @NonNull T3, @NonNull T4, @NonNull T5, @NonNull T6, @NonNull T7, @NonNull T8, @NonNull T9, @NonNull R> Maybe zip(
@NonNull MaybeSource source1, @NonNull MaybeSource source2, @NonNull MaybeSource source3,
@NonNull MaybeSource source4, @NonNull MaybeSource source5, @NonNull MaybeSource source6,
@NonNull MaybeSource source7, @NonNull MaybeSource source8, @NonNull MaybeSource source9,
@NonNull Function9 zipper) {
Objects.requireNonNull(source1, "source1 is null");
Objects.requireNonNull(source2, "source2 is null");
Objects.requireNonNull(source3, "source3 is null");
Objects.requireNonNull(source4, "source4 is null");
Objects.requireNonNull(source5, "source5 is null");
Objects.requireNonNull(source6, "source6 is null");
Objects.requireNonNull(source7, "source7 is null");
Objects.requireNonNull(source8, "source8 is null");
Objects.requireNonNull(source9, "source9 is null");
Objects.requireNonNull(zipper, "zipper is null");
return zipArray(Functions.toFunction(zipper), source1, source2, source3, source4, source5, source6, source7, source8, source9);
}
/**
* Returns a {@code Maybe} that emits the results of a specified combiner function applied to combinations of
* items emitted, in sequence, by an array of other {@link MaybeSource}s.
*
* Note on method signature: since Java doesn't allow creating a generic array with {@code new T[]}, the
* implementation of this operator has to create an {@code Object[]} instead. Unfortunately, a
* {@code Function} passed to the method would trigger a {@link ClassCastException}.
*
*
* 
*
This operator terminates eagerly if any of the source {@code MaybeSource}s signal an {@code onError} or {@code onComplete}. This
* also means it is possible some sources may not get subscribed to at all.
*
* - Scheduler:
* - {@code zipArray} does not operate by default on a particular {@link Scheduler}.
*
*
* @param the common element type
* @param the result type
* @param sources
* an array of source {@code MaybeSource}s
* @param zipper
* a function that, when applied to an item emitted by each of the source {@code MaybeSource}s, results in
* an item that will be emitted by the resulting {@code Maybe}
* @return the new {@code Maybe} instance
* @throws NullPointerException if {@code sources} or {@code zipper} is {@code null}
* @see ReactiveX operators documentation: Zip
*/
@CheckReturnValue
@NonNull
@SchedulerSupport(SchedulerSupport.NONE)
@SafeVarargs
public static <@NonNull T, @NonNull R> Maybe zipArray(@NonNull Function zipper,
@NonNull MaybeSource... sources) {
Objects.requireNonNull(sources, "sources is null");
if (sources.length == 0) {
return empty();
}
Objects.requireNonNull(zipper, "zipper is null");
return RxJavaPlugins.onAssembly(new MaybeZipArray<>(sources, zipper));
}
// ------------------------------------------------------------------
// Instance methods
// ------------------------------------------------------------------
/**
* Mirrors the {@link MaybeSource} (current or provided) that first signals an event.
*
* 
*
* - Scheduler:
* - {@code ambWith} does not operate by default on a particular {@link Scheduler}.
*
*
* @param other
* a {@code MaybeSource} competing to react first. A subscription to this provided source will occur after
* subscribing to the current source.
* @return the new {@code Maybe} instance
* @throws NullPointerException if {@code other} is {@code null}
* @see ReactiveX operators documentation: Amb
*/
@CheckReturnValue
@NonNull
@SchedulerSupport(SchedulerSupport.NONE)
public final Maybe ambWith(@NonNull MaybeSource other) {
Objects.requireNonNull(other, "other is null");
return ambArray(this, other);
}
/**
* Waits in a blocking fashion until the current {@code Maybe} signals a success value (which is returned),
* {@code null} if completed or an exception (which is propagated).
*
* 
*
* - Scheduler:
* - {@code blockingGet} does not operate by default on a particular {@link Scheduler}.
* - Error handling:
* - If the source signals an error, the operator wraps a checked {@link Exception}
* into {@link RuntimeException} and throws that. Otherwise, {@code RuntimeException}s and
* {@link Error}s are rethrown as they are.
*
* @return the success value
*/
@CheckReturnValue
@SchedulerSupport(SchedulerSupport.NONE)
@Nullable
public final T blockingGet() {
BlockingMultiObserver observer = new BlockingMultiObserver<>();
subscribe(observer);
return observer.blockingGet();
}
/**
* Waits in a blocking fashion until the current {@code Maybe} signals a success value (which is returned),
* defaultValue if completed or an exception (which is propagated).
*
* 
*
* - Scheduler:
* - {@code blockingGet} does not operate by default on a particular {@link Scheduler}.
* - Error handling:
* - If the source signals an error, the operator wraps a checked {@link Exception}
* into {@link RuntimeException} and throws that. Otherwise, {@code RuntimeException}s and
* {@link Error}s are rethrown as they are.
*
* @param defaultValue the default item to return if this {@code Maybe} is empty
* @return the success value
* @throws NullPointerException if {@code defaultValue} is {@code null}
*/
@CheckReturnValue
@SchedulerSupport(SchedulerSupport.NONE)
@NonNull
public final T blockingGet(@NonNull T defaultValue) {
Objects.requireNonNull(defaultValue, "defaultValue is null");
BlockingMultiObserver observer = new BlockingMultiObserver<>();
subscribe(observer);
return observer.blockingGet(defaultValue);
}
/**
* Subscribes to the current {@code Maybe} and blocks the current thread until it terminates.
*
* 
*
* - Scheduler:
* - {@code blockingSubscribe} does not operate by default on a particular {@link Scheduler}.
* - Error handling:
* - If the current {@code Maybe} signals an error,
* the {@link Throwable} is routed to the global error handler via {@link RxJavaPlugins#onError(Throwable)}.
* If the current thread is interrupted, an {@link InterruptedException} is routed to the same global error handler.
*
*
* @since 3.0.0
* @see #blockingSubscribe(Consumer)
* @see #blockingSubscribe(Consumer, Consumer)
* @see #blockingSubscribe(Consumer, Consumer, Action)
*/
@SchedulerSupport(SchedulerSupport.NONE)
public final void blockingSubscribe() {
blockingSubscribe(Functions.emptyConsumer(), Functions.ERROR_CONSUMER, Functions.EMPTY_ACTION);
}
/**
* Subscribes to the current {@code Maybe} and calls given {@code onSuccess} callback on the current thread
* when it completes normally.
*
* 
*
* - Scheduler:
* - {@code blockingSubscribe} does not operate by default on a particular {@link Scheduler}.
* - Error handling:
* - If either the current {@code Maybe} signals an error or {@code onSuccess} throws,
* the respective {@link Throwable} is routed to the global error handler via {@link RxJavaPlugins#onError(Throwable)}.
* If the current thread is interrupted, an {@link InterruptedException} is routed to the same global error handler.
*
*
* @param onSuccess the {@link Consumer} to call if the current {@code Maybe} succeeds
* @throws NullPointerException if {@code onSuccess} is {@code null}
* @since 3.0.0
* @see #blockingSubscribe(Consumer, Consumer)
* @see #blockingSubscribe(Consumer, Consumer, Action)
*/
@SchedulerSupport(SchedulerSupport.NONE)
public final void blockingSubscribe(@NonNull Consumer onSuccess) {
blockingSubscribe(onSuccess, Functions.ERROR_CONSUMER, Functions.EMPTY_ACTION);
}
/**
* Subscribes to the current {@code Maybe} and calls the appropriate callback on the current thread
* when it terminates.
*
* 
*
* - Scheduler:
* - {@code blockingSubscribe} does not operate by default on a particular {@link Scheduler}.
* - Error handling:
* - If either {@code onSuccess} or {@code onError} throw, the {@link Throwable} is routed to the
* global error handler via {@link RxJavaPlugins#onError(Throwable)}.
* If the current thread is interrupted, the {@code onError} consumer is called with an {@link InterruptedException}.
*
*
* @param onSuccess the {@link Consumer} to call if the current {@code Maybe} succeeds
* @param onError the {@code Consumer} to call if the current {@code Maybe} signals an error
* @throws NullPointerException if {@code onSuccess} or {@code onError} is {@code null}
* @since 3.0.0
* @see #blockingSubscribe(Consumer, Consumer, Action)
*/
@SchedulerSupport(SchedulerSupport.NONE)
public final void blockingSubscribe(@NonNull Consumer onSuccess, @NonNull Consumer onError) {
blockingSubscribe(onSuccess, onError, Functions.EMPTY_ACTION);
}
/**
* Subscribes to the current {@code Maybe} and calls the appropriate callback on the current thread
* when it terminates.
*
* 
*
* - Scheduler:
* - {@code blockingSubscribe} does not operate by default on a particular {@link Scheduler}.
* - Error handling:
* - If either {@code onSuccess}, {@code onError} or {@code onComplete} throw, the {@link Throwable} is routed to the
* global error handler via {@link RxJavaPlugins#onError(Throwable)}.
* If the current thread is interrupted, the {@code onError} consumer is called with an {@link InterruptedException}.
*
*
* @param onSuccess the {@link Consumer} to call if the current {@code Maybe} succeeds
* @param onError the {@code Consumer} to call if the current {@code Maybe} signals an error
* @param onComplete the {@link Action} to call if the current {@code Maybe} completes without a value
* @throws NullPointerException if {@code onSuccess}, {@code onError} or {@code onComplete} is {@code null}
* @since 3.0.0
*/
@SchedulerSupport(SchedulerSupport.NONE)
public final void blockingSubscribe(@NonNull Consumer onSuccess, @NonNull Consumer onError, @NonNull Action onComplete) {
Objects.requireNonNull(onSuccess, "onSuccess is null");
Objects.requireNonNull(onError, "onError is null");
Objects.requireNonNull(onComplete, "onComplete is null");
BlockingMultiObserver observer = new BlockingMultiObserver<>();
subscribe(observer);
observer.blockingConsume(onSuccess, onError, onComplete);
}
/**
* Subscribes to the current {@code Maybe} and calls the appropriate {@link MaybeObserver} method on the current thread.
*
* 
*
* - Scheduler:
* - {@code blockingSubscribe} does not operate by default on a particular {@link Scheduler}.
* - Error handling:
* - An {@code onError} signal is delivered to the {@link MaybeObserver#onError(Throwable)} method.
* If any of the {@code MaybeObserver}'s methods throw, the {@link RuntimeException} is propagated to the caller of this method.
* If the current thread is interrupted, an {@link InterruptedException} is delivered to {@code observer.onError}.
*
*
* @param observer the {@code MaybeObserver} to call methods on the current thread
* @throws NullPointerException if {@code observer} is {@code null}
* @since 3.0.0
*/
@SchedulerSupport(SchedulerSupport.NONE)
public final void blockingSubscribe(@NonNull MaybeObserver observer) {
Objects.requireNonNull(observer, "observer is null");
BlockingDisposableMultiObserver blockingObserver = new BlockingDisposableMultiObserver<>();
observer.onSubscribe(blockingObserver);
subscribe(blockingObserver);
blockingObserver.blockingConsume(observer);
}
/**
* Returns a {@code Maybe} that subscribes to this {@code Maybe} lazily, caches its event
* and replays it, to all the downstream subscribers.
*
* 
*
* The operator subscribes only when the first downstream subscriber subscribes and maintains
* a single subscription towards this {@code Maybe}.
*
* Note: You sacrifice the ability to dispose the origin when you use the {@code cache}.
*
* - Scheduler:
* - {@code cache} does not operate by default on a particular {@link Scheduler}.
*
*
* @return the new {@code Maybe} instance
* @see ReactiveX operators documentation: Replay
*/
@CheckReturnValue
@SchedulerSupport(SchedulerSupport.NONE)
@NonNull
public final Maybe cache() {
return RxJavaPlugins.onAssembly(new MaybeCache<>(this));
}
/**
* Casts the success value of the current {@code Maybe} into the target type or signals a
* {@link ClassCastException} if not compatible.
*
* 
*
* - Scheduler:
* - {@code cast} does not operate by default on a particular {@link Scheduler}.
*
* @param the target type
* @param clazz the type token to use for casting the success result from the current {@code Maybe}
* @return the new {@code Maybe} instance
* @throws NullPointerException if {@code clazz} is {@code null}
*/
@CheckReturnValue
@NonNull
@SchedulerSupport(SchedulerSupport.NONE)
public final <@NonNull U> Maybe cast(@NonNull Class clazz) {
Objects.requireNonNull(clazz, "clazz is null");
return map(Functions.castFunction(clazz));
}
/**
* Transform a {@code Maybe} by applying a particular {@link MaybeTransformer} function to it.
*
* 
*
* This method operates on the {@code Maybe} itself whereas {@link #lift} operates on the {@code Maybe}'s {@link MaybeObserver}s.
*
* If the operator you are creating is designed to act on the individual item emitted by a {@code Maybe}, use
* {@link #lift}. If your operator is designed to transform the current {@code Maybe} as a whole (for instance, by
* applying a particular set of existing RxJava operators to it) use {@code compose}.
*
* - Scheduler:
* - {@code compose} does not operate by default on a particular {@link Scheduler}.
*
*
* @param the value type of the {@code Maybe} returned by the transformer function
* @param transformer the transformer function, not {@code null}
* @return the new {@code Maybe} instance
* @throws NullPointerException if {@code transformer} is {@code null}
* @see RxJava wiki: Implementing Your Own Operators
*/
@SuppressWarnings("unchecked")
@CheckReturnValue
@SchedulerSupport(SchedulerSupport.NONE)
@NonNull
public final <@NonNull R> Maybe compose(@NonNull MaybeTransformer transformer) {
return wrap(((MaybeTransformer) Objects.requireNonNull(transformer, "transformer is null")).apply(this));
}
/**
* Returns a {@code Maybe} that is based on applying a specified function to the item emitted by the current {@code Maybe},
* where that function returns a {@link MaybeSource}.
*
* 
*
* Note that flatMap and concatMap for {@code Maybe} is the same operation.
*
* - Scheduler:
* - {@code concatMap} does not operate by default on a particular {@link Scheduler}.
*
* @param the result value type
* @param mapper
* a function that, when applied to the item emitted by the current {@code Maybe}, returns a {@code MaybeSource}
* @return the new {@code Maybe} instance
* @see ReactiveX operators documentation: FlatMap
* @throws NullPointerException if {@code mapper} is {@code null}
*/
@CheckReturnValue
@NonNull
@SchedulerSupport(SchedulerSupport.NONE)
public final <@NonNull R> Maybe concatMap(@NonNull Function> mapper) {
return flatMap(mapper);
}
/**
* Returns a {@link Completable} that completes based on applying a specified function to the item emitted by the
* current {@code Maybe}, where that function returns a {@code Completable}.
*
* 
*
* This operator is an alias for {@link #flatMapCompletable(Function)}.
*
* - Scheduler:
* - {@code concatMapCompletable} does not operate by default on a particular {@link Scheduler}.
*
*
* @param mapper
* a function that, when applied to the item emitted by the current {@code Maybe}, returns a
* {@code Completable}
* @return the new {@code Completable} instance
* @throws NullPointerException if {@code mapper} is {@code null}
* @see ReactiveX operators documentation: FlatMap
* @since 3.0.0
*/
@CheckReturnValue
@NonNull
@SchedulerSupport(SchedulerSupport.NONE)
public final Completable concatMapCompletable(@NonNull Function mapper) {
return flatMapCompletable(mapper);
}
/**
* Returns a {@code Maybe} based on applying a specified function to the item emitted by the
* current {@code Maybe}, where that function returns a {@link Single}.
* When this {@code Maybe} just completes the resulting {@code Maybe} completes as well.
*
* 
*
* This operator is an alias for {@link #flatMapSingle(Function)}.
*
* - Scheduler:
* - {@code concatMapSingle} does not operate by default on a particular {@link Scheduler}.
*
*
* @param the result value type
* @param mapper
* a function that, when applied to the item emitted by the current {@code Maybe}, returns a
* {@code Single}
* @return the new {@code Maybe} instance
* @throws NullPointerException if {@code mapper} is {@code null}
* @see ReactiveX operators documentation: FlatMap
* @since 3.0.0
*/
@CheckReturnValue
@NonNull
@SchedulerSupport(SchedulerSupport.NONE)
public final <@NonNull R> Maybe concatMapSingle(@NonNull Function> mapper) {
return flatMapSingle(mapper);
}
/**
* Returns a {@link Flowable} that emits the items emitted from the current {@code Maybe}, then the {@code other} {@link MaybeSource}, one after
* the other, without interleaving them.
*
* 
*
* - Backpressure:
* - The operator honors backpressure from downstream.
* - Scheduler:
* - {@code concatWith} does not operate by default on a particular {@link Scheduler}.
*
*
* @param other
* a {@code MaybeSource} to be concatenated after the current
* @return the new {@code Flowable} instance
* @throws NullPointerException if {@code other} is {@code null}
* @see ReactiveX operators documentation: Concat
*/
@BackpressureSupport(BackpressureKind.FULL)
@CheckReturnValue
@NonNull
@SchedulerSupport(SchedulerSupport.NONE)
public final Flowable concatWith(@NonNull MaybeSource other) {
Objects.requireNonNull(other, "other is null");
return concat(this, other);
}
/**
* Returns a {@link Single} that emits a {@link Boolean} that indicates whether the current {@code Maybe} emitted a
* specified item.
*
* 
*
* - Scheduler:
* - {@code contains} does not operate by default on a particular {@link Scheduler}.
*
*
* @param item
* the item to search for in the emissions from the current {@code Maybe}, not {@code null}
* @return the new {@code Single} instance
* @throws NullPointerException if {@code item} is {@code null}
* @see ReactiveX operators documentation: Contains
*/
@CheckReturnValue
@NonNull
@SchedulerSupport(SchedulerSupport.NONE)
public final Single contains(@NonNull Object item) {
Objects.requireNonNull(item, "item is null");
return RxJavaPlugins.onAssembly(new MaybeContains<>(this, item));
}
/**
* Returns a {@link Single} that counts the total number of items emitted (0 or 1) by the current {@code Maybe} and emits
* this count as a 64-bit {@link Long}.
*
* 
*
* - Scheduler:
* - {@code count} does not operate by default on a particular {@link Scheduler}.
*
*
* @return the new {@code Single} instance
* @see ReactiveX operators documentation: Count
*/
@CheckReturnValue
@SchedulerSupport(SchedulerSupport.NONE)
@NonNull
public final Single count() {
return RxJavaPlugins.onAssembly(new MaybeCount<>(this));
}
/**
* Returns a {@link Single} that emits the item emitted by the current {@code Maybe} or a specified default item
* if the current {@code Maybe} is empty.
*
* 
*
* - Scheduler:
* - {@code defaultIfEmpty} does not operate by default on a particular {@link Scheduler}.
*
*
* @param defaultItem
* the item to emit if the current {@code Maybe} emits no items
* @return the new {@code Single} instance
* @throws NullPointerException if {@code defaultItem} is {@code null}
* @see ReactiveX operators documentation: DefaultIfEmpty
*/
@CheckReturnValue
@NonNull
@SchedulerSupport(SchedulerSupport.NONE)
public final Single defaultIfEmpty(@NonNull T defaultItem) {
Objects.requireNonNull(defaultItem, "defaultItem is null");
return RxJavaPlugins.onAssembly(new MaybeToSingle<>(this, defaultItem));
}
/**
* Maps the {@link Notification} success value of the current {@code Maybe} back into normal
* {@code onSuccess}, {@code onError} or {@code onComplete} signals.
*
* 
*
* The intended use of the {@code selector} function is to perform a
* type-safe identity mapping (see example) on a source that is already of type
* {@code Notification}. The Java language doesn't allow
* limiting instance methods to a certain generic argument shape, therefore,
* a function is used to ensure the conversion remains type safe.
*
* Regular {@code onError} or {@code onComplete} signals from the current {@code Maybe} are passed along to the downstream.
*
* - Scheduler:
* - {@code dematerialize} does not operate by default on a particular {@link Scheduler}.
*
*
* Example:
*
* Maybe.just(Notification.createOnNext(1))
* .dematerialize(notification -> notification)
* .test()
* .assertResult(1);
*
* @param the result type
* @param selector the function called with the success item and should
* return a {@code Notification} instance.
* @return the new {@code Maybe} instance
* @throws NullPointerException if {@code selector} is {@code null}
* @since 3.0.0
* @see #materialize()
*/
@CheckReturnValue
@NonNull
@SchedulerSupport(SchedulerSupport.NONE)
public final <@NonNull R> Maybe dematerialize(@NonNull Function> selector) {
Objects.requireNonNull(selector, "selector is null");
return RxJavaPlugins.onAssembly(new MaybeDematerialize<>(this, selector));
}
/**
* Returns a {@code Maybe} that signals the events emitted by the current {@code Maybe} shifted forward in time by a
* specified delay.
* An error signal will not be delayed.
*
* 
*
* - Scheduler:
* - This version of {@code delay} operates by default on the {@code computation} {@link Scheduler}.
*
*
* @param time
* the delay to shift the source by
* @param unit
* the {@link TimeUnit} in which {@code time} is defined
* @return the new {@code Maybe} instance
* @throws NullPointerException if {@code unit} is {@code null}
* @see ReactiveX operators documentation: Delay
* @see #delay(long, TimeUnit, Scheduler, boolean)
*/
@CheckReturnValue
@SchedulerSupport(SchedulerSupport.COMPUTATION)
@NonNull
public final Maybe delay(long time, @NonNull TimeUnit unit) {
return delay(time, unit, Schedulers.computation(), false);
}
/**
* Returns a {@code Maybe} that signals the events emitted by the current {@code Maybe} shifted forward in time by a
* specified delay.
*
* 
*
* - Scheduler:
* - This version of {@code delay} operates by default on the {@code computation} {@link Scheduler}.
*
*
* @param time the delay to shift the source by
* @param unit the {@link TimeUnit} in which {@code time} is defined
* @param delayError if {@code true}, both success and error signals are delayed. if {@code false}, only success signals are delayed.
* @return the new {@code Maybe} instance
* @throws NullPointerException if {@code unit} is {@code null}
* @see ReactiveX operators documentation: Delay
* @see #delay(long, TimeUnit, Scheduler, boolean)
* @since 3.0.0
*/
@CheckReturnValue
@SchedulerSupport(SchedulerSupport.COMPUTATION)
@NonNull
public final Maybe delay(long time, @NonNull TimeUnit unit, boolean delayError) {
return delay(time, unit, Schedulers.computation(), delayError);
}
/**
* Returns a {@code Maybe} that signals the events emitted by the current {@code Maybe} shifted forward in time by a
* specified delay.
* An error signal will not be delayed.
*
* 
*
* - Scheduler:
* - you specify the {@link Scheduler} where the non-blocking wait and emission happens
*
*
* @param time the delay to shift the source by
* @param unit the {@link TimeUnit} in which {@code time} is defined
* @param scheduler the {@code Scheduler} to use for delaying
* @return the new {@code Maybe} instance
* @throws NullPointerException if {@code unit} or {@code scheduler} is {@code null}
* @see ReactiveX operators documentation: Delay
* @see #delay(long, TimeUnit, Scheduler, boolean)
*/
@CheckReturnValue
@SchedulerSupport(SchedulerSupport.CUSTOM)
@NonNull
public final Maybe delay(long time, @NonNull TimeUnit unit, @NonNull Scheduler scheduler) {
return delay(time, unit, scheduler, false);
}
/**
* Returns a {@code Maybe} that signals the events emitted by the current {@code Maybe} shifted forward in time by a
* specified delay running on the specified {@link Scheduler}.
*
* 
*
*