io.reactivex.Single 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;
import java.util.NoSuchElementException;
import java.util.concurrent.*;
import org.reactivestreams.Publisher;
import io.reactivex.annotations.*;
import io.reactivex.disposables.Disposable;
import io.reactivex.exceptions.Exceptions;
import io.reactivex.functions.*;
import io.reactivex.internal.functions.*;
import io.reactivex.internal.fuseable.*;
import io.reactivex.internal.observers.*;
import io.reactivex.internal.operators.completable.*;
import io.reactivex.internal.operators.flowable.*;
import io.reactivex.internal.operators.maybe.*;
import io.reactivex.internal.operators.mixed.*;
import io.reactivex.internal.operators.observable.*;
import io.reactivex.internal.operators.single.*;
import io.reactivex.internal.util.*;
import io.reactivex.observers.TestObserver;
import io.reactivex.plugins.RxJavaPlugins;
import io.reactivex.schedulers.Schedulers;
/**
* The {@code Single} class implements the Reactive Pattern for a single value response.
*
* {@code Single} behaves similarly to {@link Observable} except that it can only emit either a single successful
* value or an error (there is no "onComplete" notification as there is for an {@link Observable}).
*
* The {@code Single} class implements the {@link SingleSource} base interface and the default consumer
* type it interacts with is the {@link SingleObserver} via the {@link #subscribe(SingleObserver)} method.
*
* The {@code Single} operates with the following sequential protocol:
*
* onSubscribe (onSuccess | onError)?
*
*
* Note that {@code onSuccess} and {@code onError} are mutually exclusive events; unlike {@code Observable},
* {@code onSuccess} is never followed by {@code onError}.
*
* Like {@code Observable}, a running {@code Single} can be stopped through the {@link Disposable} instance
* provided to consumers through {@link SingleObserver#onSubscribe}.
*
* Like an {@code Observable}, a {@code Single} is lazy, can be either "hot" or "cold", synchronous or
* asynchronous. {@code Single} 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.subjects.SingleSubject SingleSubject}.
*
* The documentation for this class makes use of marble diagrams. The following legend explains these diagrams:
*
* 
*
* See {@link Flowable} or {@link Observable} for the
* implementation of the Reactive Pattern for a stream or vector of values.
*
* For more information see the ReactiveX
* documentation.
*
* Example:
*
* Disposable d = Single.just("Hello World")
* .delay(10, TimeUnit.SECONDS, Schedulers.io())
* .subscribeWith(new DisposableSingleObserver<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();
* }
* });
*
* Thread.sleep(5000);
*
* d.dispose();
*
*
* Note that by design, subscriptions via {@link #subscribe(SingleObserver)} can't be disposed
* from the outside (hence the
* {@code void} return of the {@link #subscribe(SingleObserver)} method) and it is the
* responsibility of the implementor of the {@code SingleObserver} to allow this to happen.
* RxJava supports such usage with the standard
* {@link io.reactivex.observers.DisposableSingleObserver DisposableSingleObserver} instance.
* For convenience, the {@link #subscribeWith(SingleObserver)} method is provided as well to
* allow working with a {@code SingleObserver} (or subclass) instance to be applied with in
* a fluent manner (such as in the example above).
* @param
* the type of the item emitted by the Single
* @since 2.0
* @see io.reactivex.observers.DisposableSingleObserver
*/
public abstract class Single implements SingleSource {
/**
* Runs multiple SingleSources 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 Iterable sequence of sources. A subscription to each source will
* occur in the same order as in this Iterable.
* @return the new Single instance
* @since 2.0
*/
@CheckReturnValue
@NonNull
@SchedulerSupport(SchedulerSupport.NONE)
public static Single amb(final Iterable> sources) {
ObjectHelper.requireNonNull(sources, "sources is null");
return RxJavaPlugins.onAssembly(new SingleAmb(null, sources));
}
/**
* Runs multiple SingleSources 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 this array.
* @return the new Single instance
* @since 2.0
*/
@CheckReturnValue
@SchedulerSupport(SchedulerSupport.NONE)
@SuppressWarnings("unchecked")
public static Single ambArray(final SingleSource... sources) {
if (sources.length == 0) {
return error(SingleInternalHelper.emptyThrower());
}
if (sources.length == 1) {
return wrap((SingleSource)sources[0]);
}
return RxJavaPlugins.onAssembly(new SingleAmb(sources, null));
}
/**
* Concatenate the single values, in a non-overlapping fashion, of the SingleSources provided by
* an Iterable 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 Iterable sequence of SingleSource instances
* @return the new Flowable instance
* @since 2.0
*/
@CheckReturnValue
@NonNull
@SchedulerSupport(SchedulerSupport.NONE)
@BackpressureSupport(BackpressureKind.FULL)
public static Flowable concat(Iterable> sources) {
return concat(Flowable.fromIterable(sources));
}
/**
* Concatenate the single values, in a non-overlapping fashion, of the SingleSources provided by
* an Observable sequence.
*
* 
*
* - Scheduler:
* - {@code concat} does not operate by default on a particular {@link Scheduler}.
*
* @param the value type
* @param sources the ObservableSource of SingleSource instances
* @return the new Observable instance
* @since 2.0
*/
@CheckReturnValue
@NonNull
@SchedulerSupport(SchedulerSupport.NONE)
@SuppressWarnings({ "unchecked", "rawtypes" })
public static Observable concat(ObservableSource> sources) {
ObjectHelper.requireNonNull(sources, "sources is null");
return RxJavaPlugins.onAssembly(new ObservableConcatMap(sources, SingleInternalHelper.toObservable(), 2, ErrorMode.IMMEDIATE));
}
/**
* Concatenate the single values, in a non-overlapping fashion, of the SingleSources provided by
* a Publisher sequence.
*
* 
*
* - Backpressure:
* - The returned {@code Flowable} honors the backpressure of the downstream consumer
* and the sources {@code Publisher} is expected to honor it as well.
* - Scheduler:
* - {@code concat} does not operate by default on a particular {@link Scheduler}.
*
* @param the value type
* @param sources the Publisher of SingleSource instances
* @return the new Flowable instance
* @since 2.0
*/
@CheckReturnValue
@NonNull
@BackpressureSupport(BackpressureKind.FULL)
@SchedulerSupport(SchedulerSupport.NONE)
public static Flowable concat(Publisher> sources) {
return concat(sources, 2);
}
/**
* Concatenate the single values, in a non-overlapping fashion, of the SingleSources provided by
* a Publisher sequence and prefetched by the specified amount.
*
* 
*
* - Backpressure:
* - The returned {@code Flowable} honors the backpressure of the downstream consumer
* and the sources {@code Publisher} is expected to honor it as well.
* - Scheduler:
* - {@code concat} does not operate by default on a particular {@link Scheduler}.
*
* @param the value type
* @param sources the Publisher of SingleSource instances
* @param prefetch the number of SingleSources to prefetch from the Publisher
* @return the new Flowable instance
* @since 2.0
*/
@CheckReturnValue
@NonNull
@BackpressureSupport(BackpressureKind.FULL)
@SchedulerSupport(SchedulerSupport.NONE)
@SuppressWarnings({ "unchecked", "rawtypes" })
public static Flowable concat(Publisher> sources, int prefetch) {
ObjectHelper.requireNonNull(sources, "sources is null");
ObjectHelper.verifyPositive(prefetch, "prefetch");
return RxJavaPlugins.onAssembly(new FlowableConcatMapPublisher(sources, SingleInternalHelper.toFlowable(), prefetch, ErrorMode.IMMEDIATE));
}
/**
* Returns a Flowable that emits the items emitted by two Singles, 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 Single to be concatenated
* @param source2
* a Single to be concatenated
* @return a Flowable that emits items emitted by the two source Singles, one after the other.
* @see ReactiveX operators documentation: Concat
*/
@CheckReturnValue
@NonNull
@BackpressureSupport(BackpressureKind.FULL)
@SchedulerSupport(SchedulerSupport.NONE)
@SuppressWarnings("unchecked")
public static Flowable concat(
SingleSource source1, SingleSource source2
) {
ObjectHelper.requireNonNull(source1, "source1 is null");
ObjectHelper.requireNonNull(source2, "source2 is null");
return concat(Flowable.fromArray(source1, source2));
}
/**
* Returns a Flowable that emits the items emitted by three Singles, 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 Single to be concatenated
* @param source2
* a Single to be concatenated
* @param source3
* a Single to be concatenated
* @return a Flowable that emits items emitted by the three source Singles, one after the other.
* @see ReactiveX operators documentation: Concat
*/
@CheckReturnValue
@NonNull
@BackpressureSupport(BackpressureKind.FULL)
@SchedulerSupport(SchedulerSupport.NONE)
@SuppressWarnings("unchecked")
public static Flowable concat(
SingleSource source1, SingleSource source2,
SingleSource source3
) {
ObjectHelper.requireNonNull(source1, "source1 is null");
ObjectHelper.requireNonNull(source2, "source2 is null");
ObjectHelper.requireNonNull(source3, "source3 is null");
return concat(Flowable.fromArray(source1, source2, source3));
}
/**
* Returns a Flowable that emits the items emitted by four Singles, 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 Single to be concatenated
* @param source2
* a Single to be concatenated
* @param source3
* a Single to be concatenated
* @param source4
* a Single to be concatenated
* @return a Flowable that emits items emitted by the four source Singles, one after the other.
* @see ReactiveX operators documentation: Concat
*/
@CheckReturnValue
@NonNull
@BackpressureSupport(BackpressureKind.FULL)
@SchedulerSupport(SchedulerSupport.NONE)
@SuppressWarnings("unchecked")
public static Flowable concat(
SingleSource source1, SingleSource source2,
SingleSource source3, SingleSource source4
) {
ObjectHelper.requireNonNull(source1, "source1 is null");
ObjectHelper.requireNonNull(source2, "source2 is null");
ObjectHelper.requireNonNull(source3, "source3 is null");
ObjectHelper.requireNonNull(source4, "source4 is null");
return concat(Flowable.fromArray(source1, source2, source3, source4));
}
/**
* Concatenate the single values, in a non-overlapping fashion, of the SingleSources provided in
* an array.
*
* 
*
* - 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 SingleSource instances
* @return the new Flowable instance
* @since 2.0
*/
@CheckReturnValue
@NonNull
@BackpressureSupport(BackpressureKind.FULL)
@SchedulerSupport(SchedulerSupport.NONE)
@SuppressWarnings({ "unchecked", "rawtypes" })
public static Flowable concatArray(SingleSource... sources) {
return RxJavaPlugins.onAssembly(new FlowableConcatMap(Flowable.fromArray(sources), SingleInternalHelper.toFlowable(), 2, ErrorMode.BOUNDARY));
}
/**
* Concatenates a sequence of SingleSource eagerly into a single stream of values.
*
* Eager concatenation means that once a subscriber subscribes, this operator subscribes to all of the
* source SingleSources. The operator buffers the value emitted by these SingleSources 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 Single that need to be eagerly concatenated
* @return the new Flowable instance with the specified concatenation behavior
*/
@BackpressureSupport(BackpressureKind.FULL)
@CheckReturnValue
@NonNull
@SchedulerSupport(SchedulerSupport.NONE)
public static Flowable concatArrayEager(SingleSource... sources) {
return Flowable.fromArray(sources).concatMapEager(SingleInternalHelper.toFlowable());
}
/**
* Concatenates a Publisher sequence of SingleSources eagerly into a single stream of values.
*
* 
*
* Eager concatenation means that once a subscriber subscribes, this operator subscribes to all of the
* emitted source Publishers as they are observed. The operator buffers the values emitted by these
* Publishers and then drains them in order, each one after the previous one completes.
*
* - Backpressure:
* - Backpressure is honored towards the downstream and the outer Publisher is
* expected to support backpressure. Violating this assumption, the operator will
* signal {@link io.reactivex.exceptions.MissingBackpressureException}.
* - Scheduler:
* - This method does not operate by default on a particular {@link Scheduler}.
*
* @param the value type
* @param sources a sequence of Publishers that need to be eagerly concatenated
* @return the new Publisher instance with the specified concatenation behavior
*/
@BackpressureSupport(BackpressureKind.FULL)
@CheckReturnValue
@NonNull
@SchedulerSupport(SchedulerSupport.NONE)
public static Flowable concatEager(Publisher> sources) {
return Flowable.fromPublisher(sources).concatMapEager(SingleInternalHelper.toFlowable());
}
/**
* Concatenates a sequence of SingleSources eagerly into a single stream of values.
*
* 
*
* Eager concatenation means that once a subscriber subscribes, this operator subscribes to all of the
* source SingleSources. The operator buffers the values emitted by these SingleSources 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 SingleSource that need to be eagerly concatenated
* @return the new Flowable instance with the specified concatenation behavior
*/
@BackpressureSupport(BackpressureKind.FULL)
@CheckReturnValue
@NonNull
@SchedulerSupport(SchedulerSupport.NONE)
public static Flowable concatEager(Iterable> sources) {
return Flowable.fromIterable(sources).concatMapEager(SingleInternalHelper.toFlowable());
}
/**
* Provides an API (via a cold Completable) that bridges the reactive world with the callback-style world.
*
* 
*
* Example:
*
* Single.<Event>create(emitter -> {
* Callback listener = new Callback() {
* @Override
* public void onEvent(Event e) {
* emitter.onSuccess(e);
* }
*
* @Override
* public void onFailure(Exception e) {
* emitter.onError(e);
* }
* };
*
* AutoCloseable c = api.someMethod(listener);
*
* emitter.setCancellable(c::close);
*
* });
*
*
* - Scheduler:
* - {@code create} does not operate by default on a particular {@link Scheduler}.
*
* @param the value type
* @param source the emitter that is called when a SingleObserver subscribes to the returned {@code Single}
* @return the new Single instance
* @see SingleOnSubscribe
* @see Cancellable
*/
@CheckReturnValue
@NonNull
@SchedulerSupport(SchedulerSupport.NONE)
public static Single create(SingleOnSubscribe source) {
ObjectHelper.requireNonNull(source, "source is null");
return RxJavaPlugins.onAssembly(new SingleCreate(source));
}
/**
* Calls a {@link Callable} for each individual {@link SingleObserver} to return the actual {@link SingleSource} to
* be subscribed to.
*
* 
*
* - Scheduler:
* - {@code defer} does not operate by default on a particular {@link Scheduler}.
*
* @param the value type
* @param singleSupplier the {@code Callable} that is called for each individual {@code SingleObserver} and
* returns a SingleSource instance to subscribe to
* @return the new Single instance
*/
@CheckReturnValue
@NonNull
@SchedulerSupport(SchedulerSupport.NONE)
public static Single defer(final Callable> singleSupplier) {
ObjectHelper.requireNonNull(singleSupplier, "singleSupplier is null");
return RxJavaPlugins.onAssembly(new SingleDefer(singleSupplier));
}
/**
* Signals a Throwable returned by the callback function for each individual SingleObserver.
*
* 
*
* - Scheduler:
* - {@code error} does not operate by default on a particular {@link Scheduler}.
*
* @param the value type
* @param errorSupplier the callable that is called for each individual SingleObserver and
* returns a Throwable instance to be emitted.
* @return the new Single instance
*/
@CheckReturnValue
@NonNull
@SchedulerSupport(SchedulerSupport.NONE)
public static Single error(final Callable errorSupplier) {
ObjectHelper.requireNonNull(errorSupplier, "errorSupplier is null");
return RxJavaPlugins.onAssembly(new SingleError(errorSupplier));
}
/**
* Returns a Single that invokes a subscriber's {@link SingleObserver#onError onError} method when the
* subscriber subscribes to it.
*
* 
*
* - Scheduler:
* - {@code error} does not operate by default on a particular {@link Scheduler}.
*
*
* @param exception
* the particular Throwable to pass to {@link SingleObserver#onError onError}
* @param
* the type of the item (ostensibly) emitted by the Single
* @return a Single that invokes the subscriber's {@link SingleObserver#onError onError} method when
* the subscriber subscribes to it
* @see ReactiveX operators documentation: Throw
*/
@CheckReturnValue
@NonNull
@SchedulerSupport(SchedulerSupport.NONE)
public static Single error(final Throwable exception) {
ObjectHelper.requireNonNull(exception, "exception is null");
return error(Functions.justCallable(exception));
}
/**
* Returns a {@link Single} that invokes passed function and emits its result for each new SingleObserver that subscribes.
*
* Allows you to defer execution of passed function until SingleObserver subscribes to the {@link Single}.
* It makes passed function "lazy".
* Result of the function invocation will be emitted by the {@link Single}.
*
* 
*
* - Scheduler:
* - {@code fromCallable} does not operate by default on a particular {@link Scheduler}.
* - Error handling:
* - If the {@link Callable} throws an exception, the respective {@link Throwable} is
* delivered to the downstream via {@link SingleObserver#onError(Throwable)},
* except when the downstream has disposed this {@code Single} 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.exceptions.UndeliverableException UndeliverableException}.
*
*
*
* @param callable
* function which execution should be deferred, it will be invoked when SingleObserver will subscribe to the {@link Single}.
* @param
* the type of the item emitted by the {@link Single}.
* @return a {@link Single} whose {@link SingleObserver}s' subscriptions trigger an invocation of the given function.
*/
@CheckReturnValue
@NonNull
@SchedulerSupport(SchedulerSupport.NONE)
public static Single fromCallable(final Callable callable) {
ObjectHelper.requireNonNull(callable, "callable is null");
return RxJavaPlugins.onAssembly(new SingleFromCallable(callable));
}
/**
* Converts a {@link Future} into a {@code Single}.
*
* 
*
* You can convert any object that supports the {@link Future} interface into a Single that emits the return
* value of the {@link Future#get} method of that object, by passing the object into the {@code from}
* method.
*
* Important note: This Single is blocking; you cannot dispose it.
*
* - Scheduler:
* - {@code fromFuture} does not operate by default on a particular {@link Scheduler}.
*
*
* @param future
* the source {@link Future}
* @param
* the type of object that the {@link Future} returns, and also the type of item to be emitted by
* the resulting {@code Single}
* @return a {@code Single} that emits the item from the source {@link Future}
* @see ReactiveX operators documentation: From
*/
@CheckReturnValue
@SchedulerSupport(SchedulerSupport.NONE)
public static Single fromFuture(Future future) {
return toSingle(Flowable.fromFuture(future));
}
/**
* Converts a {@link Future} into a {@code Single}, with a timeout on the Future.
*
*
*
* You can convert any object that supports the {@link Future} interface into a {@code Single} that emits
* the return value of the {@link Future#get} method of that object, by passing the object into the
* {@code from} method.
*
* Important note: This {@code Single} is blocking; you cannot dispose it.
*
* - Scheduler:
* - {@code fromFuture} does not operate by default on a particular {@link Scheduler}.
*
*
* @param future
* the source {@link 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 {@link Future} returns, and also the type of item to be emitted by
* the resulting {@code Single}
* @return a {@code Single} that emits the item from the source {@link Future}
* @see ReactiveX operators documentation: From
*/
@CheckReturnValue
@SchedulerSupport(SchedulerSupport.NONE)
public static Single fromFuture(Future future, long timeout, TimeUnit unit) {
return toSingle(Flowable.fromFuture(future, timeout, unit));
}
/**
* Converts a {@link Future} into a {@code Single}, with a timeout on the Future.
*
*
*
* You can convert any object that supports the {@link Future} interface into a {@code Single} that emits
* the return value of the {@link Future#get} method of that object, by passing the object into the
* {@code from} method.
*
* Important note: This {@code Single} is blocking; you cannot dispose it.
*
* - Scheduler:
* - You specify the {@link Scheduler} where the blocking wait will happen.
*
*
* @param future
* the source {@link Future}
* @param timeout
* the maximum time to wait before calling {@code get}
* @param unit
* the {@link TimeUnit} of the {@code timeout} argument
* @param scheduler
* the Scheduler to use for the blocking wait
* @param
* the type of object that the {@link Future} returns, and also the type of item to be emitted by
* the resulting {@code Single}
* @return a {@code Single} that emits the item from the source {@link Future}
* @see ReactiveX operators documentation: From
*/
@CheckReturnValue
@SchedulerSupport(SchedulerSupport.CUSTOM)
public static Single fromFuture(Future future, long timeout, TimeUnit unit, Scheduler scheduler) {
return toSingle(Flowable.fromFuture(future, timeout, unit, scheduler));
}
/**
* Converts a {@link Future}, operating on a specified {@link Scheduler}, into a {@code Single}.
*
* 
*
* You can convert any object that supports the {@link Future} interface into a {@code Single} that emits
* the return value of the {@link Future#get} method of that object, by passing the object into the
* {@code from} method.
*
* - Scheduler:
* - You specify which {@link Scheduler} this operator will use.
*
*
* @param future
* the source {@link Future}
* @param scheduler
* the {@link Scheduler} to wait for the Future on. Use a Scheduler such as
* {@link Schedulers#io()} that can block and wait on the Future
* @param
* the type of object that the {@link Future} returns, and also the type of item to be emitted by
* the resulting {@code Single}
* @return a {@code Single} that emits the item from the source {@link Future}
* @see ReactiveX operators documentation: From
*/
@CheckReturnValue
@SchedulerSupport(SchedulerSupport.CUSTOM)
public static Single fromFuture(Future future, Scheduler scheduler) {
return toSingle(Flowable.fromFuture(future, scheduler));
}
/**
* Wraps a specific Publisher into a Single and signals its single element or error.
* If the source Publisher is empty, a NoSuchElementException is signalled. If
* the source has more than one element, an IndexOutOfBoundsException is signalled.
*
* The {@link Publisher} must follow the
* Reactive-Streams specification.
* Violating the specification may result in undefined behavior.
*
* If possible, use {@link #create(SingleOnSubscribe)} to create a
* source-like {@code Single} instead.
*
* Note that even though {@link Publisher} appears to be a functional interface, it
* is not recommended to implement it through a lambda as the specification requires
* state management that is not achievable with a stateless lambda.
*
* 
*
* - Backpressure:
* - The {@code publisher} is consumed in an unbounded fashion but will be cancelled
* if it produced more than one item.
* - Scheduler:
* - {@code fromPublisher} does not operate by default on a particular {@link Scheduler}.
*
* @param the value type
* @param publisher the source Publisher instance, not null
* @return the new Single instance
* @see #create(SingleOnSubscribe)
*/
@BackpressureSupport(BackpressureKind.UNBOUNDED_IN)
@CheckReturnValue
@NonNull
@SchedulerSupport(SchedulerSupport.NONE)
public static Single fromPublisher(final Publisher publisher) {
ObjectHelper.requireNonNull(publisher, "publisher is null");
return RxJavaPlugins.onAssembly(new SingleFromPublisher(publisher));
}
/**
* Wraps a specific ObservableSource into a Single and signals its single element or error.
* If the ObservableSource is empty, a NoSuchElementException is signalled.
* If the source has more than one element, an IndexOutOfBoundsException is signalled.
*
* 
*
* - Scheduler:
* - {@code fromObservable} does not operate by default on a particular {@link Scheduler}.
*
*
* @param observableSource the source Observable, not null
* @param
* the type of the item emitted by the {@link Single}.
* @return the new Single instance
*/
@CheckReturnValue
@NonNull
@SchedulerSupport(SchedulerSupport.NONE)
public static Single fromObservable(ObservableSource observableSource) {
ObjectHelper.requireNonNull(observableSource, "observableSource is null");
return RxJavaPlugins.onAssembly(new ObservableSingleSingle(observableSource, null));
}
/**
* Returns a {@code Single} that emits a specified item.
*
* 
*
* To convert any object into a {@code Single} 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 a {@code Single} that emits {@code item}
* @see ReactiveX operators documentation: Just
*/
@CheckReturnValue
@SchedulerSupport(SchedulerSupport.NONE)
@NonNull
public static Single just(final T item) {
ObjectHelper.requireNonNull(item, "item is null");
return RxJavaPlugins.onAssembly(new SingleJust(item));
}
/**
* Merges an Iterable sequence of SingleSource instances into a single Flowable sequence,
* running all SingleSources at once.
*
* 
*
* - Backpressure:
* - The returned {@code Flowable} honors the backpressure of the downstream consumer.
* - Scheduler:
* - {@code merge} does not operate by default on a particular {@link Scheduler}.
* - Error handling:
* - If any of the source {@code SingleSource}s signal a {@code Throwable} via {@code onError}, the resulting
* {@code Flowable} terminates with that {@code Throwable} and all other source {@code SingleSource}s are disposed.
* If more than one {@code SingleSource} 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
* {@code 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 {@code 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 SingleSource}s
* have completed or failed with an error.
*
*
* @param the common and resulting value type
* @param sources the Iterable sequence of SingleSource sources
* @return the new Flowable instance
* @since 2.0
* @see #mergeDelayError(Iterable)
*/
@CheckReturnValue
@NonNull
@BackpressureSupport(BackpressureKind.FULL)
@SchedulerSupport(SchedulerSupport.NONE)
public static Flowable merge(Iterable> sources) {
return merge(Flowable.fromIterable(sources));
}
/**
* Merges a Flowable sequence of SingleSource instances into a single Flowable sequence,
* running all SingleSources at once.
*
* 
*
* - Backpressure:
* - The returned {@code Flowable} honors the backpressure of the downstream consumer.
* - Scheduler:
* - {@code merge} does not operate by default on a particular {@link Scheduler}.
* - Error handling:
* - If any of the source {@code SingleSource}s signal a {@code Throwable} via {@code onError}, the resulting
* {@code Flowable} terminates with that {@code Throwable} and all other source {@code SingleSource}s are disposed.
* If more than one {@code SingleSource} 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
* {@code 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 {@code 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 SingleSource}s
* have completed or failed with an error.
*
*
* @param the common and resulting value type
* @param sources the Flowable sequence of SingleSource sources
* @return the new Flowable instance
* @see #mergeDelayError(Publisher)
* @since 2.0
*/
@CheckReturnValue
@NonNull
@BackpressureSupport(BackpressureKind.FULL)
@SchedulerSupport(SchedulerSupport.NONE)
@SuppressWarnings({ "unchecked", "rawtypes" })
public static Flowable merge(Publisher> sources) {
ObjectHelper.requireNonNull(sources, "sources is null");
return RxJavaPlugins.onAssembly(new FlowableFlatMapPublisher(sources, SingleInternalHelper.toFlowable(), false, Integer.MAX_VALUE, Flowable.bufferSize()));
}
/**
* Flattens a {@code Single} that emits a {@code Single} into a single {@code Single} that emits the item
* emitted by the nested {@code Single}, without any transformation.
*
* 
*
* - Scheduler:
* - {@code merge} does not operate by default on a particular {@link Scheduler}.
* - The resulting {@code Single} emits the outer source's or the inner {@code SingleSource}'s {@code Throwable} as is.
* Unlike the other {@code merge()} operators, this operator won't and can't produce a {@code CompositeException} because there is
* only one possibility for the outer or the inner {@code SingleSource} to emit an {@code onError} signal.
* Therefore, there is no need for a {@code mergeDelayError(SingleSource
>)} operator.
*
*
*
* @param the value type of the sources and the output
* @param source
* a {@code Single} that emits a {@code Single}
* @return a {@code Single} that emits the item that is the result of flattening the {@code Single} emitted
* by {@code source}
* @see ReactiveX operators documentation: Merge
*/
@CheckReturnValue
@NonNull
@SchedulerSupport(SchedulerSupport.NONE)
@SuppressWarnings({ "unchecked", "rawtypes" })
public static Single merge(SingleSource> source) {
ObjectHelper.requireNonNull(source, "source is null");
return RxJavaPlugins.onAssembly(new SingleFlatMap, T>(source, (Function)Functions.identity()));
}
/**
* Flattens two Singles into a single Flowable, without any transformation.
*
* 
*
* You can combine items emitted by multiple Singles so that they appear as a single Flowable, by
* using the {@code merge} method.
*
* - Backpressure:
* - The returned {@code Flowable} honors the backpressure of the downstream consumer.
* - Scheduler:
* - {@code merge} does not operate by default on a particular {@link Scheduler}.
* - Error handling:
* - If any of the source {@code SingleSource}s signal a {@code Throwable} via {@code onError}, the resulting
* {@code Flowable} terminates with that {@code Throwable} and all other source {@code SingleSource}s are disposed.
* If more than one {@code SingleSource} 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
* {@code 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 {@code 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(SingleSource, SingleSource)} to merge sources and terminate only when all source {@code SingleSource}s
* have completed or failed with an error.
*
*
*
* @param the common value type
* @param source1
* a SingleSource to be merged
* @param source2
* a SingleSource to be merged
* @return a Flowable that emits all of the items emitted by the source Singles
* @see ReactiveX operators documentation: Merge
* @see #mergeDelayError(SingleSource, SingleSource)
*/
@CheckReturnValue
@NonNull
@BackpressureSupport(BackpressureKind.FULL)
@SchedulerSupport(SchedulerSupport.NONE)
@SuppressWarnings("unchecked")
public static Flowable merge(
SingleSource source1, SingleSource source2
) {
ObjectHelper.requireNonNull(source1, "source1 is null");
ObjectHelper.requireNonNull(source2, "source2 is null");
return merge(Flowable.fromArray(source1, source2));
}
/**
* Flattens three Singles into a single Flowable, without any transformation.
*
* 
*
* You can combine items emitted by multiple Singles so that they appear as a single Flowable, by using
* the {@code merge} method.
*
* - Backpressure:
* - The returned {@code Flowable} honors the backpressure of the downstream consumer.
* - Scheduler:
* - {@code merge} does not operate by default on a particular {@link Scheduler}.
* - Error handling:
* - If any of the source {@code SingleSource}s signal a {@code Throwable} via {@code onError}, the resulting
* {@code Flowable} terminates with that {@code Throwable} and all other source {@code SingleSource}s are disposed.
* If more than one {@code SingleSource} 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
* {@code 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 {@code 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(SingleSource, SingleSource, SingleSource)} to merge sources and terminate only when all source {@code SingleSource}s
* have completed or failed with an error.
*
*
*
* @param the common value type
* @param source1
* a SingleSource to be merged
* @param source2
* a SingleSource to be merged
* @param source3
* a SingleSource to be merged
* @return a Flowable that emits all of the items emitted by the source Singles
* @see ReactiveX operators documentation: Merge
* @see #mergeDelayError(SingleSource, SingleSource, SingleSource)
*/
@CheckReturnValue
@NonNull
@BackpressureSupport(BackpressureKind.FULL)
@SchedulerSupport(SchedulerSupport.NONE)
@SuppressWarnings("unchecked")
public static Flowable merge(
SingleSource source1, SingleSource source2,
SingleSource source3
) {
ObjectHelper.requireNonNull(source1, "source1 is null");
ObjectHelper.requireNonNull(source2, "source2 is null");
ObjectHelper.requireNonNull(source3, "source3 is null");
return merge(Flowable.fromArray(source1, source2, source3));
}
/**
* Flattens four Singles into a single Flowable, without any transformation.
*
* 
*
* You can combine items emitted by multiple Singles so that they appear as a single Flowable, by using
* the {@code merge} method.
*
* - Backpressure:
* - The returned {@code Flowable} honors the backpressure of the downstream consumer.
* - Scheduler:
* - {@code merge} does not operate by default on a particular {@link Scheduler}.
* - Error handling:
* - If any of the source {@code SingleSource}s signal a {@code Throwable} via {@code onError}, the resulting
* {@code Flowable} terminates with that {@code Throwable} and all other source {@code SingleSource}s are disposed.
* If more than one {@code SingleSource} 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
* {@code 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 {@code 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(SingleSource, SingleSource, SingleSource, SingleSource)} to merge sources and terminate only when all source {@code SingleSource}s
* have completed or failed with an error.
*
*
*
* @param the common value type
* @param source1
* a SingleSource to be merged
* @param source2
* a SingleSource to be merged
* @param source3
* a SingleSource to be merged
* @param source4
* a SingleSource to be merged
* @return a Flowable that emits all of the items emitted by the source Singles
* @see ReactiveX operators documentation: Merge
* @see #mergeDelayError(SingleSource, SingleSource, SingleSource, SingleSource)
*/
@CheckReturnValue
@NonNull
@BackpressureSupport(BackpressureKind.FULL)
@SchedulerSupport(SchedulerSupport.NONE)
@SuppressWarnings("unchecked")
public static Flowable merge(
SingleSource source1, SingleSource source2,
SingleSource source3, SingleSource source4
) {
ObjectHelper.requireNonNull(source1, "source1 is null");
ObjectHelper.requireNonNull(source2, "source2 is null");
ObjectHelper.requireNonNull(source3, "source3 is null");
ObjectHelper.requireNonNull(source4, "source4 is null");
return merge(Flowable.fromArray(source1, source2, source3, source4));
}
/**
* Merges an Iterable sequence of SingleSource instances into a single Flowable sequence,
* running all SingleSources at once and delaying any error(s) until all sources succeed or fail.
*
* - Backpressure:
* - The returned {@code Flowable} honors the backpressure of the downstream consumer.
* - Scheduler:
* - {@code mergeDelayError} does not operate by default on a particular {@link Scheduler}.
*
* History: 2.1.9 - experimental
* @param the common and resulting value type
* @param sources the Iterable sequence of SingleSource sources
* @return the new Flowable instance
* @see #merge(Iterable)
* @since 2.2
*/
@CheckReturnValue
@NonNull
@BackpressureSupport(BackpressureKind.FULL)
@SchedulerSupport(SchedulerSupport.NONE)
public static Flowable mergeDelayError(Iterable> sources) {
return mergeDelayError(Flowable.fromIterable(sources));
}
/**
* Merges a Flowable sequence of SingleSource instances into a single Flowable sequence,
* running all SingleSources at once and delaying any error(s) until all sources succeed or fail.
*
* - Backpressure:
* - The returned {@code Flowable} honors the backpressure of the downstream consumer.
* - Scheduler:
* - {@code mergeDelayError} does not operate by default on a particular {@link Scheduler}.
*
* History: 2.1.9 - experimental
* @param the common and resulting value type
* @param sources the Flowable sequence of SingleSource sources
* @return the new Flowable instance
* @see #merge(Publisher)
* @since 2.2
*/
@CheckReturnValue
@NonNull
@BackpressureSupport(BackpressureKind.FULL)
@SchedulerSupport(SchedulerSupport.NONE)
@SuppressWarnings({ "unchecked", "rawtypes" })
public static Flowable mergeDelayError(Publisher> sources) {
ObjectHelper.requireNonNull(sources, "sources is null");
return RxJavaPlugins.onAssembly(new FlowableFlatMapPublisher(sources, SingleInternalHelper.toFlowable(), true, Integer.MAX_VALUE, Flowable.bufferSize()));
}
/**
* Flattens two Singles into a single Flowable, without any transformation, delaying
* any error(s) until all sources succeed or fail.
*
*
*
* You can combine items emitted by multiple Singles so that they appear as a single Flowable, by
* using the {@code mergeDelayError} method.
*
* - Backpressure:
* - The returned {@code Flowable} honors the backpressure of the downstream consumer.
* - Scheduler:
* - {@code mergeDelayError} does not operate by default on a particular {@link Scheduler}.
*
* History: 2.1.9 - experimental
* @param the common value type
* @param source1
* a SingleSource to be merged
* @param source2
* a SingleSource to be merged
* @return a Flowable that emits all of the items emitted by the source Singles
* @see ReactiveX operators documentation: Merge
* @see #merge(SingleSource, SingleSource)
* @since 2.2
*/
@CheckReturnValue
@NonNull
@BackpressureSupport(BackpressureKind.FULL)
@SchedulerSupport(SchedulerSupport.NONE)
@SuppressWarnings("unchecked")
public static Flowable mergeDelayError(
SingleSource source1, SingleSource source2
) {
ObjectHelper.requireNonNull(source1, "source1 is null");
ObjectHelper.requireNonNull(source2, "source2 is null");
return mergeDelayError(Flowable.fromArray(source1, source2));
}
/**
* Flattens three Singles into a single Flowable, without any transformation, delaying
* any error(s) until all sources succeed or fail.
*
*
*
* You can combine items emitted by multiple Singles so that they appear as a single Flowable, by using
* the {@code mergeDelayError} method.
*
* - Backpressure:
* - The returned {@code Flowable} honors the backpressure of the downstream consumer.
* - Scheduler:
* - {@code mergeDelayError} does not operate by default on a particular {@link Scheduler}.
*
* History: 2.1.9 - experimental
* @param the common value type
* @param source1
* a SingleSource to be merged
* @param source2
* a SingleSource to be merged
* @param source3
* a SingleSource to be merged
* @return a Flowable that emits all of the items emitted by the source Singles
* @see ReactiveX operators documentation: Merge
* @see #merge(SingleSource, SingleSource, SingleSource)
* @since 2.2
*/
@CheckReturnValue
@NonNull
@BackpressureSupport(BackpressureKind.FULL)
@SchedulerSupport(SchedulerSupport.NONE)
@SuppressWarnings("unchecked")
public static Flowable mergeDelayError(
SingleSource source1, SingleSource source2,
SingleSource source3
) {
ObjectHelper.requireNonNull(source1, "source1 is null");
ObjectHelper.requireNonNull(source2, "source2 is null");
ObjectHelper.requireNonNull(source3, "source3 is null");
return mergeDelayError(Flowable.fromArray(source1, source2, source3));
}
/**
* Flattens four Singles into a single Flowable, without any transformation, delaying
* any error(s) until all sources succeed or fail.
*
*
*
* You can combine items emitted by multiple Singles so that they appear as a single Flowable, by using
* the {@code mergeDelayError} method.
*
* - Backpressure:
* - The returned {@code Flowable} honors the backpressure of the downstream consumer.
* - Scheduler:
* - {@code mergeDelayError} does not operate by default on a particular {@link Scheduler}.
*
* History: 2.1.9 - experimental
* @param the common value type
* @param source1
* a SingleSource to be merged
* @param source2
* a SingleSource to be merged
* @param source3
* a SingleSource to be merged
* @param source4
* a SingleSource to be merged
* @return a Flowable that emits all of the items emitted by the source Singles
* @see ReactiveX operators documentation: Merge
* @see #merge(SingleSource, SingleSource, SingleSource, SingleSource)
* @since 2.2
*/
@CheckReturnValue
@NonNull
@BackpressureSupport(BackpressureKind.FULL)
@SchedulerSupport(SchedulerSupport.NONE)
@SuppressWarnings("unchecked")
public static Flowable mergeDelayError(
SingleSource source1, SingleSource source2,
SingleSource source3, SingleSource source4
) {
ObjectHelper.requireNonNull(source1, "source1 is null");
ObjectHelper.requireNonNull(source2, "source2 is null");
ObjectHelper.requireNonNull(source3, "source3 is null");
ObjectHelper.requireNonNull(source4, "source4 is null");
return mergeDelayError(Flowable.fromArray(source1, source2, source3, source4));
}
/**
* Returns a singleton instance of a never-signalling Single (only calls onSubscribe).
*
* 
*
* - Scheduler:
* - {@code never} does not operate by default on a particular {@link Scheduler}.
*
* @param the target value type
* @return the singleton never instance
* @since 2.0
*/
@CheckReturnValue
@SchedulerSupport(SchedulerSupport.NONE)
@SuppressWarnings("unchecked")
public static Single never() {
return RxJavaPlugins.onAssembly((Single) SingleNever.INSTANCE);
}
/**
* Signals success with 0L value after the given delay for each SingleObserver.
*
* 
*
* - Scheduler:
* - {@code timer} operates by default on the {@code computation} {@link Scheduler}.
*
* @param delay the delay amount
* @param unit the time unit of the delay
* @return the new Single instance
* @since 2.0
*/
@CheckReturnValue
@SchedulerSupport(SchedulerSupport.COMPUTATION)
public static Single timer(long delay, TimeUnit unit) {
return timer(delay, unit, Schedulers.computation());
}
/**
* Signals success with 0L value after the given delay for each SingleObserver.
*
* 
*
* - Scheduler:
* - you specify the {@link Scheduler} to signal on.
*
* @param delay the delay amount
* @param unit the time unit of the delay
* @param scheduler the scheduler where the single 0L will be emitted
* @return the new Single instance
* @throws NullPointerException
* if unit is null, or
* if scheduler is null
* @since 2.0
*/
@CheckReturnValue
@NonNull
@SchedulerSupport(SchedulerSupport.CUSTOM)
public static Single timer(final long delay, final TimeUnit unit, final Scheduler scheduler) {
ObjectHelper.requireNonNull(unit, "unit is null");
ObjectHelper.requireNonNull(scheduler, "scheduler is null");
return RxJavaPlugins.onAssembly(new SingleTimer(delay, unit, scheduler));
}
/**
* Compares two SingleSources and emits true if they emit the same value (compared via Object.equals).
*
* 
*
* - Scheduler:
* - {@code equals} does not operate by default on a particular {@link Scheduler}.
*
* @param the common value type
* @param first the first SingleSource instance
* @param second the second SingleSource instance
* @return the new Single instance
* @since 2.0
*/
@CheckReturnValue
@NonNull
@SchedulerSupport(SchedulerSupport.NONE)
public static Single equals(final SingleSource first, final SingleSource second) { // NOPMD
ObjectHelper.requireNonNull(first, "first is null");
ObjectHelper.requireNonNull(second, "second is null");
return RxJavaPlugins.onAssembly(new SingleEquals(first, second));
}
/**
* Advanced use only: creates a Single instance without
* any safeguards by using a callback that is called with a SingleObserver.
*
* - 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 SingleObserver
* @return the new Single instance
* @throws IllegalArgumentException if {@code source} is a subclass of {@code Single}; such
* instances don't need conversion and is possibly a port remnant from 1.x or one should use {@link #hide()}
* instead.
* @since 2.0
*/
@CheckReturnValue
@NonNull
@SchedulerSupport(SchedulerSupport.NONE)
public static Single unsafeCreate(SingleSource onSubscribe) {
ObjectHelper.requireNonNull(onSubscribe, "onSubscribe is null");
if (onSubscribe instanceof Single) {
throw new IllegalArgumentException("unsafeCreate(Single) should be upgraded");
}
return RxJavaPlugins.onAssembly(new SingleFromUnsafeSource(onSubscribe));
}
/**
* Allows using and disposing a resource while running a SingleSource instance generated from
* that resource (similar to a try-with-resources).
*
* - Scheduler:
* - {@code using} does not operate by default on a particular {@link Scheduler}.
*
* @param the value type of the SingleSource generated
* @param the resource type
* @param resourceSupplier the Callable called for each SingleObserver to generate a resource Object
* @param singleFunction the function called with the returned resource
* Object from {@code resourceSupplier} and should return a SingleSource instance
* to be run by the operator
* @param disposer the consumer of the generated resource that is called exactly once for
* that particular resource when the generated SingleSource terminates
* (successfully or with an error) or gets disposed.
* @return the new Single instance
* @since 2.0
*/
@CheckReturnValue
@SchedulerSupport(SchedulerSupport.NONE)
public static Single using(Callable resourceSupplier,
Function> singleFunction,
Consumer disposer) {
return using(resourceSupplier, singleFunction, disposer, true);
}
/**
* Allows using and disposing a resource while running a SingleSource instance generated from
* that resource (similar to a try-with-resources).
*
* - Scheduler:
* - {@code using} does not operate by default on a particular {@link Scheduler}.
*
* @param the value type of the SingleSource generated
* @param the resource type
* @param resourceSupplier the Callable called for each SingleObserver to generate a resource Object
* @param singleFunction the function called with the returned resource
* Object from {@code resourceSupplier} and should return a SingleSource instance
* to be run by the operator
* @param disposer the consumer of the generated resource that is called exactly once for
* that particular resource when the generated SingleSource terminates
* (successfully or with an error) or gets disposed.
* @param eager
* if true, the disposer is called before the terminal event is signalled
* if false, the disposer is called after the terminal event is delivered to downstream
* @return the new Single instance
* @since 2.0
*/
@CheckReturnValue
@NonNull
@SchedulerSupport(SchedulerSupport.NONE)
public static Single using(
final Callable resourceSupplier,
final Function> singleFunction,
final Consumer disposer,
final boolean eager) {
ObjectHelper.requireNonNull(resourceSupplier, "resourceSupplier is null");
ObjectHelper.requireNonNull(singleFunction, "singleFunction is null");
ObjectHelper.requireNonNull(disposer, "disposer is null");
return RxJavaPlugins.onAssembly(new SingleUsing(resourceSupplier, singleFunction, disposer, eager));
}
/**
* Wraps a SingleSource instance into a new Single instance if not already a Single
* 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 Single wrapper or the source cast to Single (if possible)
*/
@CheckReturnValue
@NonNull
@SchedulerSupport(SchedulerSupport.NONE)
public static Single wrap(SingleSource source) {
ObjectHelper.requireNonNull(source, "source is null");
if (source instanceof Single) {
return RxJavaPlugins.onAssembly((Single)source);
}
return RxJavaPlugins.onAssembly(new SingleFromUnsafeSource(source));
}
/**
* Waits until all SingleSource sources provided by the Iterable sequence signal a success
* value and calls a zipper function with an array of these values to return a result
* to be emitted to downstream.
*
* If the {@code Iterable} of {@link SingleSource}s is empty a {@link NoSuchElementException} error is signalled after subscription.
*
* 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 {@code ClassCastException}.
*
*
* 
*
* If any of the SingleSources signal an error, all other SingleSources get disposed and the
* error emitted to downstream immediately.
*
* - Scheduler:
* - {@code zip} does not operate by default on a particular {@link Scheduler}.
*
* @param the common value type
* @param the result value type
* @param sources the Iterable sequence of SingleSource instances. An empty sequence will result in an
* {@code onError} signal of {@link NoSuchElementException}.
* @param zipper the function that receives an array with values from each SingleSource
* and should return a value to be emitted to downstream
* @return the new Single instance
* @since 2.0
*/
@CheckReturnValue
@NonNull
@SchedulerSupport(SchedulerSupport.NONE)
public static Single zip(final Iterable> sources, Function zipper) {
ObjectHelper.requireNonNull(zipper, "zipper is null");
ObjectHelper.requireNonNull(sources, "sources is null");
return RxJavaPlugins.onAssembly(new SingleZipIterable(sources, zipper));
}
/**
* Returns a Single that emits the results of a specified combiner function applied to two items emitted by
* two other Singles.
*
* 
*
* - Scheduler:
* - {@code zip} does not operate by default on a particular {@link Scheduler}.
*
*
* @param the first source Single's value type
* @param the second source Single's value type
* @param the result value type
* @param source1
* the first source Single
* @param source2
* a second source Single
* @param zipper
* a function that, when applied to the item emitted by each of the source Singles, results in an
* item that will be emitted by the resulting Single
* @return a Single that emits the zipped results
* @see ReactiveX operators documentation: Zip
*/
@CheckReturnValue
@NonNull
@SchedulerSupport(SchedulerSupport.NONE)
@SuppressWarnings("unchecked")
public static Single zip(
SingleSource source1, SingleSource source2,
BiFunction zipper
) {
ObjectHelper.requireNonNull(source1, "source1 is null");
ObjectHelper.requireNonNull(source2, "source2 is null");
return zipArray(Functions.toFunction(zipper), source1, source2);
}
/**
* Returns a Single that emits the results of a specified combiner function applied to three items emitted
* by three other Singles.
*
*
*
* - Scheduler:
* - {@code zip} does not operate by default on a particular {@link Scheduler}.
*
*
* @param the first source Single's value type
* @param the second source Single's value type
* @param the third source Single's value type
* @param the result value type
* @param source1
* the first source Single
* @param source2
* a second source Single
* @param source3
* a third source Single
* @param zipper
* a function that, when applied to the item emitted by each of the source Singles, results in an
* item that will be emitted by the resulting Single
* @return a Single that emits the zipped results
* @see ReactiveX operators documentation: Zip
*/
@CheckReturnValue
@NonNull
@SchedulerSupport(SchedulerSupport.NONE)
@SuppressWarnings("unchecked")
public static Single zip(
SingleSource source1, SingleSource source2,
SingleSource source3,
Function3 zipper
) {
ObjectHelper.requireNonNull(source1, "source1 is null");
ObjectHelper.requireNonNull(source2, "source2 is null");
ObjectHelper.requireNonNull(source3, "source3 is null");
return zipArray(Functions.toFunction(zipper), source1, source2, source3);
}
/**
* Returns a Single that emits the results of a specified combiner function applied to four items
* emitted by four other Singles.
*
*
*
* - Scheduler:
* - {@code zip} does not operate by default on a particular {@link Scheduler}.
*
*
* @param the first source Single's value type
* @param the second source Single's value type
* @param the third source Single's value type
* @param the fourth source Single's value type
* @param the result value type
* @param source1
* the first source Single
* @param source2
* a second source Single
* @param source3
* a third source Single
* @param source4
* a fourth source Single
* @param zipper
* a function that, when applied to the item emitted by each of the source Singles, results in an
* item that will be emitted by the resulting Single
* @return a Single that emits the zipped results
* @see ReactiveX operators documentation: Zip
*/
@CheckReturnValue
@NonNull
@SchedulerSupport(SchedulerSupport.NONE)
@SuppressWarnings("unchecked")
public static Single zip(
SingleSource source1, SingleSource source2,
SingleSource source3, SingleSource source4,
Function4 zipper
) {
ObjectHelper.requireNonNull(source1, "source1 is null");
ObjectHelper.requireNonNull(source2, "source2 is null");
ObjectHelper.requireNonNull(source3, "source3 is null");
ObjectHelper.requireNonNull(source4, "source4 is null");
return zipArray(Functions.toFunction(zipper), source1, source2, source3, source4);
}
/**
* Returns a Single that emits the results of a specified combiner function applied to five items
* emitted by five other Singles.
*
*
*
* - Scheduler:
* - {@code zip} does not operate by default on a particular {@link Scheduler}.
*
*
* @param the first source Single's value type
* @param the second source Single's value type
* @param the third source Single's value type
* @param the fourth source Single's value type
* @param the fifth source Single's value type
* @param the result value type
* @param source1
* the first source Single
* @param source2
* a second source Single
* @param source3
* a third source Single
* @param source4
* a fourth source Single
* @param source5
* a fifth source Single
* @param zipper
* a function that, when applied to the item emitted by each of the source Singles, results in an
* item that will be emitted by the resulting Single
* @return a Single that emits the zipped results
* @see ReactiveX operators documentation: Zip
*/
@CheckReturnValue
@NonNull
@SchedulerSupport(SchedulerSupport.NONE)
@SuppressWarnings("unchecked")
public static Single zip(
SingleSource source1, SingleSource source2,
SingleSource source3, SingleSource source4,
SingleSource source5,
Function5 zipper
) {
ObjectHelper.requireNonNull(source1, "source1 is null");
ObjectHelper.requireNonNull(source2, "source2 is null");
ObjectHelper.requireNonNull(source3, "source3 is null");
ObjectHelper.requireNonNull(source4, "source4 is null");
ObjectHelper.requireNonNull(source5, "source5 is null");
return zipArray(Functions.toFunction(zipper), source1, source2, source3, source4, source5);
}
/**
* Returns a Single that emits the results of a specified combiner function applied to six items
* emitted by six other Singles.
*
*
*
* - Scheduler:
* - {@code zip} does not operate by default on a particular {@link Scheduler}.
*
*
* @param the first source Single's value type
* @param the second source Single's value type
* @param the third source Single's value type
* @param the fourth source Single's value type
* @param the fifth source Single's value type
* @param the sixth source Single's value type
* @param the result value type
* @param source1
* the first source Single
* @param source2
* a second source Single
* @param source3
* a third source Single
* @param source4
* a fourth source Single
* @param source5
* a fifth source Single
* @param source6
* a sixth source Single
* @param zipper
* a function that, when applied to the item emitted by each of the source Singles, results in an
* item that will be emitted by the resulting Single
* @return a Single that emits the zipped results
* @see ReactiveX operators documentation: Zip
*/
@CheckReturnValue
@NonNull
@SchedulerSupport(SchedulerSupport.NONE)
@SuppressWarnings("unchecked")
public static Single zip(
SingleSource source1, SingleSource source2,
SingleSource source3, SingleSource source4,
SingleSource source5, SingleSource source6,
Function6 zipper
) {
ObjectHelper.requireNonNull(source1, "source1 is null");
ObjectHelper.requireNonNull(source2, "source2 is null");
ObjectHelper.requireNonNull(source3, "source3 is null");
ObjectHelper.requireNonNull(source4, "source4 is null");
ObjectHelper.requireNonNull(source5, "source5 is null");
ObjectHelper.requireNonNull(source6, "source6 is null");
return zipArray(Functions.toFunction(zipper), source1, source2, source3, source4, source5, source6);
}
/**
* Returns a Single that emits the results of a specified combiner function applied to seven items
* emitted by seven other Singles.
*
*
*
* - Scheduler:
* - {@code zip} does not operate by default on a particular {@link Scheduler}.
*
*
* @param the first source Single's value type
* @param the second source Single's value type
* @param the third source Single's value type
* @param the fourth source Single's value type
* @param the fifth source Single's value type
* @param the sixth source Single's value type
* @param the seventh source Single's value type
* @param the result value type
* @param source1
* the first source Single
* @param source2
* a second source Single
* @param source3
* a third source Single
* @param source4
* a fourth source Single
* @param source5
* a fifth source Single
* @param source6
* a sixth source Single
* @param source7
* a seventh source Single
* @param zipper
* a function that, when applied to the item emitted by each of the source Singles, results in an
* item that will be emitted by the resulting Single
* @return a Single that emits the zipped results
* @see ReactiveX operators documentation: Zip
*/
@CheckReturnValue
@NonNull
@SchedulerSupport(SchedulerSupport.NONE)
@SuppressWarnings("unchecked")
public static Single zip(
SingleSource source1, SingleSource source2,
SingleSource source3, SingleSource source4,
SingleSource source5, SingleSource source6,
SingleSource source7,
Function7 zipper
) {
ObjectHelper.requireNonNull(source1, "source1 is null");
ObjectHelper.requireNonNull(source2, "source2 is null");
ObjectHelper.requireNonNull(source3, "source3 is null");
ObjectHelper.requireNonNull(source4, "source4 is null");
ObjectHelper.requireNonNull(source5, "source5 is null");
ObjectHelper.requireNonNull(source6, "source6 is null");
ObjectHelper.requireNonNull(source7, "source7 is null");
return zipArray(Functions.toFunction(zipper), source1, source2, source3, source4, source5, source6, source7);
}
/**
* Returns a Single that emits the results of a specified combiner function applied to eight items
* emitted by eight other Singles.
*
*
*
* - Scheduler:
* - {@code zip} does not operate by default on a particular {@link Scheduler}.
*
*
* @param the first source Single's value type
* @param the second source Single's value type
* @param the third source Single's value type
* @param the fourth source Single's value type
* @param the fifth source Single's value type
* @param the sixth source Single's value type
* @param the seventh source Single's value type
* @param the eighth source Single's value type
* @param the result value type
* @param source1
* the first source Single
* @param source2
* a second source Single
* @param source3
* a third source Single
* @param source4
* a fourth source Single
* @param source5
* a fifth source Single
* @param source6
* a sixth source Single
* @param source7
* a seventh source Single
* @param source8
* an eighth source Single
* @param zipper
* a function that, when applied to the item emitted by each of the source Singles, results in an
* item that will be emitted by the resulting Single
* @return a Single that emits the zipped results
* @see ReactiveX operators documentation: Zip
*/
@CheckReturnValue
@NonNull
@SchedulerSupport(SchedulerSupport.NONE)
@SuppressWarnings("unchecked")
public static Single zip(
SingleSource source1, SingleSource source2,
SingleSource source3, SingleSource source4,
SingleSource source5, SingleSource source6,
SingleSource source7, SingleSource source8,
Function8 zipper
) {
ObjectHelper.requireNonNull(source1, "source1 is null");
ObjectHelper.requireNonNull(source2, "source2 is null");
ObjectHelper.requireNonNull(source3, "source3 is null");
ObjectHelper.requireNonNull(source4, "source4 is null");
ObjectHelper.requireNonNull(source5, "source5 is null");
ObjectHelper.requireNonNull(source6, "source6 is null");
ObjectHelper.requireNonNull(source7, "source7 is null");
ObjectHelper.requireNonNull(source8, "source8 is null");
return zipArray(Functions.toFunction(zipper), source1, source2, source3, source4, source5, source6, source7, source8);
}
/**
* Returns a Single that emits the results of a specified combiner function applied to nine items
* emitted by nine other Singles.
*
*
*
* - Scheduler:
* - {@code zip} does not operate by default on a particular {@link Scheduler}.
*
*
* @param the first source Single's value type
* @param the second source Single's value type
* @param the third source Single's value type
* @param the fourth source Single's value type
* @param the fifth source Single's value type
* @param the sixth source Single's value type
* @param the seventh source Single's value type
* @param the eighth source Single's value type
* @param the ninth source Single's value type
* @param the result value type
* @param source1
* the first source Single
* @param source2
* a second source Single
* @param source3
* a third source Single
* @param source4
* a fourth source Single
* @param source5
* a fifth source Single
* @param source6
* a sixth source Single
* @param source7
* a seventh source Single
* @param source8
* an eighth source Single
* @param source9
* a ninth source Single
* @param zipper
* a function that, when applied to the item emitted by each of the source Singles, results in an
* item that will be emitted by the resulting Single
* @return a Single that emits the zipped results
* @see ReactiveX operators documentation: Zip
*/
@CheckReturnValue
@NonNull
@SchedulerSupport(SchedulerSupport.NONE)
@SuppressWarnings("unchecked")
public static Single zip(
SingleSource source1, SingleSource source2,
SingleSource source3, SingleSource source4,
SingleSource source5, SingleSource source6,
SingleSource source7, SingleSource source8,
SingleSource source9,
Function9 zipper
) {
ObjectHelper.requireNonNull(source1, "source1 is null");
ObjectHelper.requireNonNull(source2, "source2 is null");
ObjectHelper.requireNonNull(source3, "source3 is null");
ObjectHelper.requireNonNull(source4, "source4 is null");
ObjectHelper.requireNonNull(source5, "source5 is null");
ObjectHelper.requireNonNull(source6, "source6 is null");
ObjectHelper.requireNonNull(source7, "source7 is null");
ObjectHelper.requireNonNull(source8, "source8 is null");
ObjectHelper.requireNonNull(source9, "source9 is null");
return zipArray(Functions.toFunction(zipper), source1, source2, source3, source4, source5, source6, source7, source8, source9);
}
/**
* Waits until all SingleSource sources provided via an array signal a success
* value and calls a zipper function with an array of these values to return a result
* to be emitted to downstream.
*
* If the array of {@link SingleSource}s is empty a {@link NoSuchElementException} error is signalled immediately.
*
* 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 {@code ClassCastException}.
*
*
*
*
* If any of the SingleSources signal an error, all other SingleSources get disposed and the
* error emitted to downstream immediately.
*
* - Scheduler:
* - {@code zipArray} does not operate by default on a particular {@link Scheduler}.
*
* @param the common value type
* @param the result value type
* @param sources the array of SingleSource instances. An empty sequence will result in an
* {@code onError} signal of {@link NoSuchElementException}.
* @param zipper the function that receives an array with values from each SingleSource
* and should return a value to be emitted to downstream
* @return the new Single instance
* @since 2.0
*/
@CheckReturnValue
@NonNull
@SchedulerSupport(SchedulerSupport.NONE)
public static Single