rx

Class Single

java.lang.Object

rx.Single

Type Parameters:

T - the type of the item emitted by the Single

public class Single
extends java.lang.Object

The Single class implements the Reactive Pattern for a single value response. See Observable for the implementation of the Reactive Pattern for a stream or vector of values.

Single behaves the same as Observable except that it can only emit either a single successful value, or an error (there is no "onComplete" notification as there is for Observable)

Like an Observable, a Single is lazy, can be either "hot" or "cold", synchronous or asynchronous.

The documentation for this class makes use of marble diagrams. The following legend explains these diagrams:

For more information see the ReactiveX documentation.

Since:

1.2

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	Single.OnSubscribe<T> Invoked when Single.execute is called.
static interface	Single.Transformer<T,R> Convenience type that allows a function to fluently transform a Single into another Single via compose(rx.Single.Transformer).

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	Single(Observable.OnSubscribe<T> f) Deprecated. 1.2.1: Not recommended, use Single(OnSubscribe) to avoid wrapping and conversion between the Observable and Single protocols.
protected	Single(Single.OnSubscribe<T> f) Creates a Single with a Function to execute when it is subscribed to (executed).

Method Summary

Modifier and Type	Method and Description
Single<T>	cache() Returns a Single that subscribes to this Single lazily, caches its success or error event and replays it to all the downstream subscribers.
Single	cast(java.lang.Class klass) Casts the success value of the current Single into the target type or signals a ClassCastException if not compatible.
Single	compose(Single.TransformerT,? extends R> transformer) Transform a Single by applying a particular Transformer function to it.
static Observable	concat(Single t1, Single t2) Returns an Observable that emits the items emitted by two Singles, one after the other.
static Observable	concat(Single t1, Single t2, Single t3) Returns an Observable that emits the items emitted by three Singles, one after the other.
static Observable	concat(Single t1, Single t2, Single t3, Single t4) Returns an Observable that emits the items emitted by four Singles, one after the other.
static Observable	concat(Single t1, Single t2, Single t3, Single t4, Single t5) Returns an Observable that emits the items emitted by five Singles, one after the other.
static Observable	concat(Single t1, Single t2, Single t3, Single t4, Single t5, Single t6) Returns an Observable that emits the items emitted by six Singles, one after the other.
static Observable	concat(Single t1, Single t2, Single t3, Single t4, Single t5, Single t6, Single t7) Returns an Observable that emits the items emitted by seven Singles, one after the other.
static Observable	concat(Single t1, Single t2, Single t3, Single t4, Single t5, Single t6, Single t7, Single t8) Returns an Observable that emits the items emitted by eight Singles, one after the other.
static Observable	concat(Single t1, Single t2, Single t3, Single t4, Single t5, Single t6, Single t7, Single t8, Single t9) Returns an Observable that emits the items emitted by nine Singles, one after the other.
Observable<T>	concatWith(SingleT> t1) Returns an Observable that emits the item emitted by the source Single, then the item emitted by the specified Single.
static Single	create(Single.OnSubscribe f) Returns a Single that will execute the specified function when a SingleSubscriber executes it or a Subscriber subscribes to it.
static Single	defer(java.util.concurrent.Callable<Single> singleFactory) Returns a Single that calls a Single factory to create a Single for each new Observer that subscribes.
Single<T>	delay(long delay, java.util.concurrent.TimeUnit unit) Returns a Single that emits the items emitted by the source Single shifted forward in time by a specified delay.
Single<T>	delay(long delay, java.util.concurrent.TimeUnit unit, Scheduler scheduler) Returns a Single that emits the items emitted by the source Single shifted forward in time by a specified delay.
Single<T>	delaySubscription(Observable other) Returns a Single that delays the subscription to this Single until the Observable completes.
Single<T>	doAfterTerminate(Action0 action) Registers an Action0 to be called when this Single invokes either SingleSubscriber.onSuccess(Object) onSuccess} or onError.
Single<T>	doOnEach(Action1<NotificationT>> onNotification) Modifies the source Single so that it invokes an action when it calls onSuccess or onError.
Single<T>	doOnError(Action1 onError) Modifies the source Single so that it invokes an action if it calls onError.
Single<T>	doOnSubscribe(Action0 subscribe) Modifies the source Single so that it invokes the given action when it is subscribed from its subscribers.
Single<T>	doOnSuccess(Action1T> onSuccess) Modifies the source Single so that it invokes an action when it calls onSuccess.
Single<T>	doOnUnsubscribe(Action0 action) Modifies the source Single so that it invokes the given action when it is unsubscribed from its subscribers.
static Single	error(java.lang.Throwable exception) Returns a Single that invokes a subscriber's onError method when the subscriber subscribes to it.
Single	flatMap(Func1T,? extends Single> func) Returns a Single that is based on applying a specified function to the item emitted by the source Single, where that function returns a Single.
Completable	flatMapCompletable(Func1T,? extends Completable> func) Returns a Completable that completes based on applying a specified function to the item emitted by the source Completable, where that function returns a Completable.
Observable	flatMapObservable(Func1T,? extends Observable> func) Returns an Observable that emits items based on applying a specified function to the item emitted by the source Observable, where that function returns an Observable.
static Single	from(java.util.concurrent.Future future) Converts a Future into a Single.
static Single	from(java.util.concurrent.Future future, long timeout, java.util.concurrent.TimeUnit unit) Converts a Future into a Single, with a timeout on the Future.
static Single	from(java.util.concurrent.Future future, Scheduler scheduler) Converts a Future, operating on a specified Scheduler, into a Single.
static Single	fromCallable(java.util.concurrent.Callable func) Returns a Single that invokes passed function and emits its result for each new Observer that subscribes.
static Single	fromEmitter(Action1<SingleEmitter> producer) Provides an API (in a cold Single) that bridges the Single-reactive world with the callback-based world.
static Single	just(T value) Returns a Single that emits a specified item.
Single	lift(Observable.OperatorT> lift) Lifts a function to the current Single and returns a new Single that when subscribed to will pass the values of the current Single through the Operator function.
Single	map(Func1T,? extends R> func) Returns a Single that applies a specified function to the item emitted by the source Single and emits the result of this function application.
static Observable	merge(ObservableSingle> sources) Merges all Singles emitted by the Observable and runs them together until the source Observable and all inner Singles complete normally.
static Observable	merge(ObservableSingle> sources, int maxConcurrency) Merges the Singles emitted by the Observable and runs up to the given number of them together at a time, until the Observable and all inner Singles terminate.
static Single	merge(SingleSingle> source) Flattens a Single that emits a Single into a single Single that emits the item emitted by the nested Single, without any transformation.
static Observable	merge(Single t1, Single t2) Flattens two Singles into a single Observable, without any transformation.
static Observable	merge(Single t1, Single t2, Single t3) Flattens three Singles into a single Observable, without any transformation.
static Observable	merge(Single t1, Single t2, Single t3, Single t4) Flattens four Singles into a single Observable, without any transformation.
static Observable	merge(Single t1, Single t2, Single t3, Single t4, Single t5) Flattens five Singles into a single Observable, without any transformation.
static Observable	merge(Single t1, Single t2, Single t3, Single t4, Single t5, Single t6) Flattens six Singles into a single Observable, without any transformation.
static Observable	merge(Single t1, Single t2, Single t3, Single t4, Single t5, Single t6, Single t7) Flattens seven Singles into a single Observable, without any transformation.
static Observable	merge(Single t1, Single t2, Single t3, Single t4, Single t5, Single t6, Single t7, Single t8) Flattens eight Singles into a single Observable, without any transformation.
static Observable	merge(Single t1, Single t2, Single t3, Single t4, Single t5, Single t6, Single t7, Single t8, Single t9) Flattens nine Singles into a single Observable, without any transformation.
static Observable	mergeDelayError(ObservableSingle> sources) Merges all Singles emitted by the Observable and runs them together, delaying errors from them and the Observable, until the source Observable and all inner Singles complete normally.
static Observable	mergeDelayError(ObservableSingle> sources, int maxConcurrency) Merges the Singles emitted by the Observable and runs up to the given number of them together at a time, delaying errors from them and the Observable, until the Observable and all inner Singles terminate.
Observable<T>	mergeWith(SingleT> t1) Flattens this and another Single into a single Observable, without any transformation.
Single<T>	observeOn(Scheduler scheduler) Modifies a Single to emit its item (or notify of its error) on a specified Scheduler, asynchronously.
Single<T>	onErrorResumeNext(Func1SingleT>> resumeFunctionInCaseOfError) Instructs a Single to pass control to another Single rather than invoking Observer.onError(Throwable) if it encounters an error.
Single<T>	onErrorResumeNext(SingleT> resumeSingleInCaseOfError) Instructs a Single to pass control to another Single rather than invoking Observer.onError(Throwable) if it encounters an error.
Single<T>	onErrorReturn(Func1T> resumeFunction) Instructs a Single to emit an item (returned by a specified function) rather than invoking onError if it encounters an error.
Single<T>	retry() Returns a Single that mirrors the source Single, resubscribing to it if it calls onError (infinite retry count).
Single<T>	retry(Func2 predicate) Returns a Single that mirrors the source Single, resubscribing to it if it calls onError and the predicate returns true for that specific exception and retry count.
Single<T>	retry(long count) Returns a Single that mirrors the source Single, resubscribing to it if it calls onError up to a specified number of retries.
Single<T>	retryWhen(Func1<Observable,? extends Observable> notificationHandler) Returns a Single that emits the same values as the source Single with the exception of an onError.
Subscription	subscribe() Subscribes to a Single but ignore its emission or notification.
Subscription	subscribe(Action1T> onSuccess) Subscribes to a Single and provides a callback to handle the item it emits.
Subscription	subscribe(Action1T> onSuccess, Action1 onError) Subscribes to a Single and provides callbacks to handle the item it emits or any error notification it issues.
Subscription	subscribe(ObserverT> observer) Subscribes an Observer to this single and returns a Subscription that allows unsubscription.
Subscription	subscribe(SingleSubscriberT> te) Subscribes to a Single and provides a SingleSubscriber that implements functions to handle the item the Single emits or any error notification it issues.
Subscription	subscribe(SubscriberT> subscriber) Subscribes to a Single and provides a Subscriber that implements functions to handle the item the Single emits or any error notification it issues.
Single<T>	subscribeOn(Scheduler scheduler) Asynchronously subscribes subscribers to this Single on the specified Scheduler.
Single<T>	takeUntil(Completable other) Returns a Single that emits the item emitted by the source Single until a Completable terminates.
Single<T>	takeUntil(Observable other) Returns a Single that emits the item emitted by the source Single until an Observable emits an item.
Single<T>	takeUntil(Single other) Returns a Single that emits the item emitted by the source Single until a second Single emits an item.
AssertableSubscriber<T>	test() Creates an AssertableSubscriber that requests Long.MAX_VALUE and subscribes it to this Observable.
Single<T>	timeout(long timeout, java.util.concurrent.TimeUnit timeUnit) Returns a Single that mirrors the source Single but applies a timeout policy for its emitted item.
Single<T>	timeout(long timeout, java.util.concurrent.TimeUnit timeUnit, Scheduler scheduler) Returns a Single that mirrors the source Single but applies a timeout policy for its emitted item, where this policy is governed on a specified Scheduler.
Single<T>	timeout(long timeout, java.util.concurrent.TimeUnit timeUnit, SingleT> other) Returns a Single that mirrors the source Single but applies a timeout policy for its emitted item.
Single<T>	timeout(long timeout, java.util.concurrent.TimeUnit timeUnit, SingleT> other, Scheduler scheduler) Returns a Single that mirrors the source Single but applies a timeout policy for its emitted item, using a specified Scheduler.
R	to(Func1Single<T>,R> converter) Calls the specified converter function during assembly time and returns its resulting value.
BlockingSingle<T>	toBlocking() Converts a Single into a BlockingSingle (a Single with blocking operators).
Completable	toCompletable() Returns a Completable that discards result of the Single (similar to Observable.ignoreElements()) and calls onCompleted when this source Single calls onSuccess.
Observable<T>	toObservable() Converts this Single into an Observable.
Subscription	unsafeSubscribe(SubscriberT> subscriber) Subscribes to a Single and invokes the Single.OnSubscribe function without any contract protection, error handling, unsubscribe, or execution hooks.
Single<T>	unsubscribeOn(Scheduler scheduler) Returns a Single which makes sure when a subscriber cancels the subscription, the dispose is called on the specified scheduler
static Single	using(Func0 resourceFactory, Func1Single> singleFactory, Action1 disposeAction) Constructs a Single that creates a dependent resource object which is disposed of on unsubscription.
static Single	using(Func0 resourceFactory, Func1Single> singleFactory, Action1 disposeAction, boolean disposeEagerly) Constructs a Single that creates a dependent resource object which is disposed of just before termination if you have set disposeEagerly to true and unsubscription does not occur before termination.
static Single	zip(java.lang.IterableSingle> singles, FuncN zipFunction) Returns a Single that emits the result of specified combiner function applied to combination of items emitted, in sequence, by an Iterable of other Singles.
static Single	zip(Single s1, Single s2, Func2 zipFunction) Returns a Single that emits the results of a specified combiner function applied to two items emitted by two other Singles.
static Single	zip(Single s1, Single s2, Single s3, Func3 zipFunction) Returns a Single that emits the results of a specified combiner function applied to three items emitted by three other Singles.
static Single	zip(Single s1, Single s2, Single s3, Single s4, Func4 zipFunction) Returns an Observable that emits the results of a specified combiner function applied to four items emitted by four other Singles.
static Single	zip(Single s1, Single s2, Single s3, Single s4, Single s5, Func5 zipFunction) Returns an Observable that emits the results of a specified combiner function applied to five items emitted by five other Singles.
static Single	zip(Single s1, Single s2, Single s3, Single s4, Single s5, Single s6, Func6 zipFunction) Returns an Observable that emits the results of a specified combiner function applied to six items emitted by six other Singles.
static Single	zip(Single s1, Single s2, Single s3, Single s4, Single s5, Single s6, Single s7, Func7 zipFunction) Returns an Observable that emits the results of a specified combiner function applied to seven items emitted by seven other Singles.
static Single	zip(Single s1, Single s2, Single s3, Single s4, Single s5, Single s6, Single s7, Single s8, Func8 zipFunction) Returns an Observable that emits the results of a specified combiner function applied to eight items emitted by eight other Singles.
static Single	zip(Single s1, Single s2, Single s3, Single s4, Single s5, Single s6, Single s7, Single s8, Single s9, Func9 zipFunction) Returns an Observable that emits the results of a specified combiner function applied to nine items emitted by nine other Singles.
Single	zipWith(Single other, Func2T,? super T2,? extends R> zipFunction) Returns a Single that emits the result of applying a specified function to the pair of items emitted by the source Single and another specified Single.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Single

protected Single(Single.OnSubscribe<T> f)

Creates a Single with a Function to execute when it is subscribed to (executed).

Note: Use create(OnSubscribe) to create a Single, instead of this constructor, unless you specifically have a need for inheritance.

Parameters:

f - f to be executed when execute(SingleSubscriber) or subscribe(Subscriber) is called

Single

@Deprecated
protected Single(Observable.OnSubscribe<T> f)

Deprecated. 1.2.1: Not recommended, use Single(OnSubscribe) to avoid wrapping and conversion between the Observable and Single protocols.

Creates a Single with a Function to execute when it is subscribed to (executed).

Note: Use create(OnSubscribe) to create a Single, instead of this constructor, unless you specifically have a need for inheritance.

Parameters:

f - f to be executed when execute(SingleSubscriber) or subscribe(Subscriber) is called

Method Detail

create

public static  Single create(Single.OnSubscribe f)

Returns a Single that will execute the specified function when a SingleSubscriber executes it or a Subscriber subscribes to it.

Write the function you pass to create so that it behaves as a Single: It should invoke the SingleSubscriber onSuccess and/or onError methods appropriately.

A well-formed Single must invoke either the SingleSubscriber's onSuccess method exactly once or its onError method exactly once.

Scheduler:

create does not operate by default on a particular Scheduler.

Type Parameters:

T - the type of the item that this Single emits

Parameters:

f - a function that accepts an SingleSubscriber, and invokes its onSuccess or onError methods as appropriate

Returns:

a Single that, when a Subscriber subscribes to it, will execute the specified function

See Also:

ReactiveX operators documentation: Create

lift

public final  Single lift(Observable.OperatorT> lift)

Lifts a function to the current Single and returns a new Single that when subscribed to will pass the values of the current Single through the Operator function.

In other words, this allows chaining TaskExecutors together on a Single for acting on the values within the Single.

task.map(...).filter(...).lift(new OperatorA()).lift(new OperatorB(...)).subscribe()

If the operator you are creating is designed to act on the item emitted by a source Single, use lift. If your operator is designed to transform the source Single as a whole (for instance, by applying a particular set of existing RxJava operators to it) use compose(rx.Single.Transformer).

Scheduler:

lift does not operate by default on a particular Scheduler.

Type Parameters:

R - the downstream's value type (output)

Parameters:

lift - the Operator that implements the Single-operating function to be applied to the source Single

Returns:

a Single that is the result of applying the lifted Operator to the source Single

Since:

1.3

See Also:

RxJava wiki: Implementing Your Own Operators

compose

public  Single compose(Single.TransformerT,? extends R> transformer)

Transform a Single by applying a particular Transformer function to it.

This method operates on the Single itself whereas lift(rx.Observable.Operator) operates on the Single's Subscribers or Observers.

If the operator you are creating is designed to act on the individual item emitted by a Single, use lift(rx.Observable.Operator). If your operator is designed to transform the source Single as a whole (for instance, by applying a particular set of existing RxJava operators to it) use compose.

Scheduler:

compose does not operate by default on a particular Scheduler.

Type Parameters:

R - the value type of the single returned by the transformer function

Parameters:

transformer - implements the function that transforms the source Single

Returns:

the source Single, transformed by the transformer function

See Also:

RxJava wiki: Implementing Your Own Operators

cast

@Experimental
public final  Single cast(java.lang.Class klass)

Casts the success value of the current Single into the target type or signals a ClassCastException if not compatible.

Scheduler:

cast does not operate by default on a particular Scheduler.

Type Parameters:

R - the target type

Parameters:

klass - the type token to use for casting the success result from the current Single

Returns:

the new Single instance

Since:

1.3.1 - experimental

concat

public static  Observable concat(Single t1,
                                       Single t2)

Returns an Observable that emits the items emitted by two Singles, one after the other.

Scheduler:

concat does not operate by default on a particular Scheduler.

Type Parameters:

T - the common value type

Parameters:

t1 - a Single to be concatenated

t2 - a Single to be concatenated

Returns:

an Observable that emits items emitted by the two source Singles, one after the other.

See Also:

ReactiveX operators documentation: Concat

concat

public static  Observable concat(Single t1,
                                       Single t2,
                                       Single t3)

Returns an Observable that emits the items emitted by three Singles, one after the other.

Scheduler:

concat does not operate by default on a particular Scheduler.

Type Parameters:

T - the common value type

Parameters:

t1 - a Single to be concatenated

t2 - a Single to be concatenated

t3 - a Single to be concatenated

Returns:

an Observable that emits items emitted by the three source Singles, one after the other.

See Also:

ReactiveX operators documentation: Concat

concat

public static  Observable concat(Single t1,
                                       Single t2,
                                       Single t3,
                                       Single t4)

Returns an Observable that emits the items emitted by four Singles, one after the other.

Scheduler:

concat does not operate by default on a particular Scheduler.

Type Parameters:

T - the common value type

Parameters:

t1 - a Single to be concatenated

t2 - a Single to be concatenated

t3 - a Single to be concatenated

t4 - a Single to be concatenated

Returns:

an Observable that emits items emitted by the four source Singles, one after the other.

See Also:

ReactiveX operators documentation: Concat

concat

public static  Observable concat(Single t1,
                                       Single t2,
                                       Single t3,
                                       Single t4,
                                       Single t5)

Returns an Observable that emits the items emitted by five Singles, one after the other.

Scheduler:

concat does not operate by default on a particular Scheduler.

Type Parameters:

T - the common value type

Parameters:

t1 - a Single to be concatenated

t2 - a Single to be concatenated

t3 - a Single to be concatenated

t4 - a Single to be concatenated

t5 - a Single to be concatenated

Returns:

an Observable that emits items emitted by the five source Singles, one after the other.

See Also:

ReactiveX operators documentation: Concat

concat

public static  Observable concat(Single t1,
                                       Single t2,
                                       Single t3,
                                       Single t4,
                                       Single t5,
                                       Single t6)

Returns an Observable that emits the items emitted by six Singles, one after the other.

Scheduler:

concat does not operate by default on a particular Scheduler.

Type Parameters:

T - the common value type

Parameters:

t1 - a Single to be concatenated

t2 - a Single to be concatenated

t3 - a Single to be concatenated

t4 - a Single to be concatenated

t5 - a Single to be concatenated

t6 - a Single to be concatenated

Returns:

an Observable that emits items emitted by the six source Singles, one after the other.

See Also:

ReactiveX operators documentation: Concat

concat

public static  Observable concat(Single t1,
                                       Single t2,
                                       Single t3,
                                       Single t4,
                                       Single t5,
                                       Single t6,
                                       Single t7)

Returns an Observable that emits the items emitted by seven Singles, one after the other.

Scheduler:

concat does not operate by default on a particular Scheduler.

Type Parameters:

T - the common value type

Parameters:

t1 - a Single to be concatenated

t2 - a Single to be concatenated

t3 - a Single to be concatenated

t4 - a Single to be concatenated

t5 - a Single to be concatenated

t6 - a Single to be concatenated

t7 - a Single to be concatenated

Returns:

an Observable that emits items emitted by the seven source Singles, one after the other.

See Also:

ReactiveX operators documentation: Concat

concat

public static  Observable concat(Single t1,
                                       Single t2,
                                       Single t3,
                                       Single t4,
                                       Single t5,
                                       Single t6,
                                       Single t7,
                                       Single t8)

Returns an Observable that emits the items emitted by eight Singles, one after the other.

Scheduler:

concat does not operate by default on a particular Scheduler.

Type Parameters:

T - the common value type

Parameters:

t1 - a Single to be concatenated

t2 - a Single to be concatenated

t3 - a Single to be concatenated

t4 - a Single to be concatenated

t5 - a Single to be concatenated

t6 - a Single to be concatenated

t7 - a Single to be concatenated

t8 - a Single to be concatenated

Returns:

an Observable that emits items emitted by the eight source Singles, one after the other.

See Also:

ReactiveX operators documentation: Concat

concat

public static  Observable concat(Single t1,
                                       Single t2,
                                       Single t3,
                                       Single t4,
                                       Single t5,
                                       Single t6,
                                       Single t7,
                                       Single t8,
                                       Single t9)

Returns an Observable that emits the items emitted by nine Singles, one after the other.

Scheduler:

concat does not operate by default on a particular Scheduler.

Type Parameters:

T - the common value type

Parameters:

t1 - a Single to be concatenated

t2 - a Single to be concatenated

t3 - a Single to be concatenated

t4 - a Single to be concatenated

t5 - a Single to be concatenated

t6 - a Single to be concatenated

t7 - a Single to be concatenated

t8 - a Single to be concatenated

t9 - a Single to be concatenated

Returns:

an Observable that emits items emitted by the nine source Singles, one after the other.

See Also:

ReactiveX operators documentation: Concat

error

public static  Single error(java.lang.Throwable exception)

Returns a Single that invokes a subscriber's onError method when the subscriber subscribes to it.

Scheduler:

error does not operate by default on a particular Scheduler.

Type Parameters:

T - the type of the item (ostensibly) emitted by the Single

Parameters:

exception - the particular Throwable to pass to onError

Returns:

a Single that invokes the subscriber's onError method when the subscriber subscribes to it

See Also:

ReactiveX operators documentation: Throw

from

public static  Single from(java.util.concurrent.Future future)

Converts a Future into a Single.

You can convert any object that supports the Future interface into a Single that emits the return value of the Future.get() method of that object, by passing the object into the from method.

Important note: This Single is blocking; you cannot unsubscribe from it.

Scheduler:

from does not operate by default on a particular Scheduler.

Type Parameters:

T - the type of object that the Future returns, and also the type of item to be emitted by the resulting Single

Parameters:

future - the source Future

Returns:

a Single that emits the item from the source Future

See Also:

ReactiveX operators documentation: From

from

public static  Single from(java.util.concurrent.Future future,
                                 long timeout,
                                 java.util.concurrent.TimeUnit unit)

Converts a Future into a Single, with a timeout on the Future.

You can convert any object that supports the Future interface into a Single that emits the return value of the Future.get() method of that object, by passing the object into the from method.

Important note: This Single is blocking; you cannot unsubscribe from it.

Scheduler:

from does not operate by default on a particular Scheduler.

Type Parameters:

T - the type of object that the Future returns, and also the type of item to be emitted by the resulting Single

Parameters:

future - the source Future

timeout - the maximum time to wait before calling get

unit - the TimeUnit of the timeout argument

Returns:

a Single that emits the item from the source Future

See Also:

ReactiveX operators documentation: From

from

public static  Single from(java.util.concurrent.Future future,
                                 Scheduler scheduler)

Converts a Future, operating on a specified Scheduler, into a Single.

You can convert any object that supports the Future interface into a Single that emits the return value of the Future.get() method of that object, by passing the object into the from method.

Scheduler:

you specify which Scheduler this operator will use

Type Parameters:

T - the type of object that the Future returns, and also the type of item to be emitted by the resulting Single

Parameters:

future - the source Future

scheduler - the Scheduler to wait for the Future on. Use a Scheduler such as Schedulers.io() that can block and wait on the Future

Returns:

a Single that emits the item from the source Future

See Also:

ReactiveX operators documentation: From

fromCallable

public static  Single fromCallable(java.util.concurrent.Callable func)

Returns a Single that invokes passed function and emits its result for each new Observer that subscribes.

Allows you to defer execution of passed function until Observer subscribes to the Single. It makes passed function "lazy". Result of the function invocation will be emitted by the Single.

Scheduler:

fromCallable does not operate by default on a particular Scheduler.

Type Parameters:

T - the type of the item emitted by the Single.

Parameters:

func - function which execution should be deferred, it will be invoked when Observer will subscribe to the Single.

Returns:

a Single whose Observers' subscriptions trigger an invocation of the given function.

fromEmitter

public static  Single fromEmitter(Action1<SingleEmitter> producer)

Provides an API (in a cold Single) that bridges the Single-reactive world with the callback-based world.

The SingleEmitter allows registering a callback for cancellation/unsubscription of a resource.

Example:

 Single.fromEmitter(emitter -> {
     Callback listener = new Callback() {
         @Override
         public void onEvent(Event e) {
             emitter.onSuccess(e.getData());
         }

         @Override
         public void onFailure(Exception e) {
             emitter.onError(e);
         }
     };

     AutoCloseable c = api.someMethod(listener);

     emitter.setCancellation(c::close);

 });
 

All of the SingleEmitter's methods are thread-safe and ensure the Single's protocol are held.

History: 1.2.3 - experimental

Type Parameters:

T - the success value type

Parameters:

producer - the callback invoked for each incoming SingleSubscriber

Returns:

the new Single instance

Since:

1.3

just

public static  Single just(T value)

Returns a Single that emits a specified item.

To convert any object into a Single that emits that object, pass that object into the just method.

Scheduler:

just does not operate by default on a particular Scheduler.

Type Parameters:

T - the type of that item

Parameters:

value - the item to emit

Returns:

a Single that emits value

See Also:

ReactiveX operators documentation: Just

merge

public static  Single merge(SingleSingle> source)

Flattens a Single that emits a Single into a single Single that emits the item emitted by the nested Single, without any transformation.

Scheduler:

merge does not operate by default on a particular Scheduler.

Type Parameters:

T - the value type of the sources and the output

Parameters:

source - a Single that emits a Single

Returns:

a Single that emits the item that is the result of flattening the Single emitted by source

See Also:

ReactiveX operators documentation: Merge

merge

public static  Observable merge(Single t1,
                                      Single t2)

Flattens two Singles into a single Observable, without any transformation.

You can combine items emitted by multiple Singles so that they appear as a single Observable, by using the merge method.

Scheduler:

merge does not operate by default on a particular Scheduler.

Type Parameters:

T - the common value type

Parameters:

t1 - a Single to be merged

t2 - a Single to be merged

Returns:

an Observable that emits all of the items emitted by the source Singles

See Also:

ReactiveX operators documentation: Merge

merge

public static  Observable merge(Single t1,
                                      Single t2,
                                      Single t3)

Flattens three Singles into a single Observable, without any transformation.

You can combine items emitted by multiple Singles so that they appear as a single Observable, by using the merge method.

Scheduler:

merge does not operate by default on a particular Scheduler.

Type Parameters:

T - the common value type

Parameters:

t1 - a Single to be merged

t2 - a Single to be merged

t3 - a Single to be merged

Returns:

an Observable that emits all of the items emitted by the source Singles

See Also:

ReactiveX operators documentation: Merge

merge

public static  Observable merge(Single t1,
                                      Single t2,
                                      Single t3,
                                      Single t4)

Flattens four Singles into a single Observable, without any transformation.

You can combine items emitted by multiple Singles so that they appear as a single Observable, by using the merge method.

Scheduler:

merge does not operate by default on a particular Scheduler.

Type Parameters:

T - the common value type

Parameters:

t1 - a Single to be merged

t2 - a Single to be merged

t3 - a Single to be merged

t4 - a Single to be merged

Returns:

an Observable that emits all of the items emitted by the source Singles

See Also:

ReactiveX operators documentation: Merge

merge

public static  Observable merge(Single t1,
                                      Single t2,
                                      Single t3,
                                      Single t4,
                                      Single t5)

Flattens five Singles into a single Observable, without any transformation.

You can combine items emitted by multiple Singles so that they appear as a single Observable, by using the merge method.

Scheduler:

merge does not operate by default on a particular Scheduler.

Type Parameters:

T - the common value type

Parameters:

t1 - a Single to be merged

t2 - a Single to be merged

t3 - a Single to be merged

t4 - a Single to be merged

t5 - a Single to be merged

Returns:

an Observable that emits all of the items emitted by the source Singles

See Also:

ReactiveX operators documentation: Merge

merge

public static  Observable merge(Single t1,
                                      Single t2,
                                      Single t3,
                                      Single t4,
                                      Single t5,
                                      Single t6)

Flattens six Singles into a single Observable, without any transformation.

You can combine items emitted by multiple Singles so that they appear as a single Observable, by using the merge method.

Scheduler:

merge does not operate by default on a particular Scheduler.

Type Parameters:

T - the common value type

Parameters:

t1 - a Single to be merged

t2 - a Single to be merged

t3 - a Single to be merged

t4 - a Single to be merged

t5 - a Single to be merged

t6 - a Single to be merged

Returns:

an Observable that emits all of the items emitted by the source Singles

See Also:

ReactiveX operators documentation: Merge

merge

public static  Observable merge(Single t1,
                                      Single t2,
                                      Single t3,
                                      Single t4,
                                      Single t5,
                                      Single t6,
                                      Single t7)

Flattens seven Singles into a single Observable, without any transformation.

You can combine items emitted by multiple Singles so that they appear as a single Observable, by using the merge method.

Scheduler:

merge does not operate by default on a particular Scheduler.

Type Parameters:

T - the common value type

Parameters:

t1 - a Single to be merged

t2 - a Single to be merged

t3 - a Single to be merged

t4 - a Single to be merged

t5 - a Single to be merged

t6 - a Single to be merged

t7 - a Single to be merged

Returns:

an Observable that emits all of the items emitted by the source Singles

See Also:

ReactiveX operators documentation: Merge

merge

public static  Observable merge(Single t1,
                                      Single t2,
                                      Single t3,
                                      Single t4,
                                      Single t5,
                                      Single t6,
                                      Single t7,
                                      Single t8)

Flattens eight Singles into a single Observable, without any transformation.

You can combine items emitted by multiple Singles so that they appear as a single Observable, by using the merge method.

Scheduler:

merge does not operate by default on a particular Scheduler.

Type Parameters:

T - the common value type

Parameters:

t1 - a Single to be merged

t2 - a Single to be merged

t3 - a Single to be merged

t4 - a Single to be merged

t5 - a Single to be merged

t6 - a Single to be merged

t7 - a Single to be merged

t8 - a Single to be merged

Returns:

an Observable that emits all of the items emitted by the source Singles

See Also:

ReactiveX operators documentation: Merge

merge

public static  Observable merge(Single t1,
                                      Single t2,
                                      Single t3,
                                      Single t4,
                                      Single t5,
                                      Single t6,
                                      Single t7,
                                      Single t8,
                                      Single t9)

Flattens nine Singles into a single Observable, without any transformation.

You can combine items emitted by multiple Singles so that they appear as a single Observable, by using the merge method.

Scheduler:

merge does not operate by default on a particular Scheduler.

Type Parameters:

T - the common value type

Parameters:

t1 - a Single to be merged

t2 - a Single to be merged

t3 - a Single to be merged

t4 - a Single to be merged

t5 - a Single to be merged

t6 - a Single to be merged

t7 - a Single to be merged

t8 - a Single to be merged

t9 - a Single to be merged

Returns:

an Observable that emits all of the items emitted by the source Singles

See Also:

ReactiveX operators documentation: Merge

merge

public static  Observable merge(ObservableSingle> sources)

Merges all Singles emitted by the Observable and runs them together until the source Observable and all inner Singles complete normally.

Backpressure:

The operator consumes items from the Observable in an unbounded manner and honors downstream backpressure.

Scheduler:

merge does not operate by default on a particular Scheduler.

History: 1.2.7 - experimental

Type Parameters:

T - the value type of the inner Singles and the resulting Observable

Parameters:

sources - the Observable that emits Singles to be merged

Returns:

the new Observable instance

Since:

1.3

See Also:

merge(Observable, int), mergeDelayError(Observable), mergeDelayError(Observable, int)

merge

public static  Observable merge(ObservableSingle> sources,
                                      int maxConcurrency)

Merges the Singles emitted by the Observable and runs up to the given number of them together at a time, until the Observable and all inner Singles terminate.

Backpressure:

The operator consumes at most maxConcurrent items from the Observable and one-by-one after as the inner Singles terminate. The operator ignores downstream backpressure as it doesn't emit items but only the terminal event.

Scheduler:

flatMapSingle does not operate by default on a particular Scheduler.

History: 1.2.7 - experimental

Type Parameters:

T - the value type of the inner Singles and the resulting Observable

Parameters:

sources - the Observable that emits Singles to be merged

maxConcurrency - the maximum number of inner Singles to run at a time

Returns:

the new Observable instance

Since:

1.3

mergeDelayError

public static  Observable mergeDelayError(ObservableSingle> sources)

Merges all Singles emitted by the Observable and runs them together, delaying errors from them and the Observable, until the source Observable and all inner Singles complete normally.

Backpressure:

The operator consumes items from the Observable in an unbounded manner and honors downstream backpressure.

Scheduler:

merge does not operate by default on a particular Scheduler.

History: 1.2.7 - experimental

Type Parameters:

T - the value type of the inner Singles and the resulting Observable

Parameters:

sources - the Observable that emits Singles to be merged

Returns:

the new Observable instance

Since:

1.3

See Also:

mergeDelayError(Observable, int), merge(Observable), merge(Observable, int)

mergeDelayError

public static  Observable mergeDelayError(ObservableSingle> sources,
                                                int maxConcurrency)

Merges the Singles emitted by the Observable and runs up to the given number of them together at a time, delaying errors from them and the Observable, until the Observable and all inner Singles terminate.

Backpressure:

The operator consumes at most maxConcurrent items from the Observable and one-by-one after as the inner Singles terminate. The operator ignores downstream backpressure as it doesn't emit items but only the terminal event.

Scheduler:

flatMapSingle does not operate by default on a particular Scheduler.

History: 1.2.7 - experimental

Type Parameters:

T - the value type of the inner Singles and the resulting Observable

Parameters:

sources - the Observable that emits Singles to be merged

maxConcurrency - the maximum number of inner Singles to run at a time

Returns:

the new Observable instance

Since:

1.3

zip

public static  Single zip(Single s1,
                                      Single s2,
                                      Func2 zipFunction)

Returns a Single that emits the results of a specified combiner function applied to two items emitted by two other Singles.

Scheduler:

zip does not operate by default on a particular Scheduler.

Type Parameters:

T1 - the first source Single's value type

T2 - the second source Single's value type

R - the result value type

Parameters:

s1 - the first source Single

s2 - a second source Single

zipFunction - 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

Returns:

a Single that emits the zipped results

See Also:

ReactiveX operators documentation: Zip

zip

public static  Single zip(Single s1,
                                         Single s2,
                                         Single s3,
                                         Func3 zipFunction)

Returns a Single that emits the results of a specified combiner function applied to three items emitted by three other Singles.

Scheduler:

zip does not operate by default on a particular Scheduler.

Type Parameters:

T1 - the first source Single's value type

T2 - the second source Single's value type

T3 - the third source Single's value type

R - the result value type

Parameters:

s1 - the first source Single

s2 - a second source Single

s3 - a third source Single

zipFunction - 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

Returns:

a Single that emits the zipped results

See Also:

ReactiveX operators documentation: Zip

zip

public static  Single zip(Single s1,
                                            Single s2,
                                            Single s3,
                                            Single s4,
                                            Func4 zipFunction)

Returns an Observable that emits the results of a specified combiner function applied to four items emitted by four other Singles.

Scheduler:

zip does not operate by default on a particular Scheduler.

Type Parameters:

T1 - the first source Single's value type

T2 - the second source Single's value type

T3 - the third source Single's value type

T4 - the fourth source Single's value type

R - the result value type

Parameters:

s1 - the first source Single

s2 - a second source Single

s3 - a third source Single

s4 - a fourth source Single

zipFunction - 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

Returns:

a Single that emits the zipped results

See Also:

ReactiveX operators documentation: Zip

zip

public static  Single zip(Single s1,
                                               Single s2,
                                               Single s3,
                                               Single s4,
                                               Single s5,
                                               Func5 zipFunction)

Returns an Observable that emits the results of a specified combiner function applied to five items emitted by five other Singles.

Scheduler:

zip does not operate by default on a particular Scheduler.

Type Parameters:

T1 - the first source Single's value type

T2 - the second source Single's value type

T3 - the third source Single's value type

T4 - the fourth source Single's value type

T5 - the fifth source Single's value type

R - the result value type

Parameters:

s1 - the first source Single

s2 - a second source Single

s3 - a third source Single

s4 - a fourth source Single

s5 - a fifth source Single

zipFunction - 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

Returns:

a Single that emits the zipped results

See Also:

ReactiveX operators documentation: Zip

zip

public static  Single zip(Single s1,
                                                  Single s2,
                                                  Single s3,
                                                  Single s4,
                                                  Single s5,
                                                  Single s6,
                                                  Func6 zipFunction)

Returns an Observable that emits the results of a specified combiner function applied to six items emitted by six other Singles.

Scheduler:

zip does not operate by default on a particular Scheduler.

Type Parameters:

T1 - the first source Single's value type

T2 - the second source Single's value type

T3 - the third source Single's value type

T4 - the fourth source Single's value type

T5 - the fifth source Single's value type

T6 - the sixth source Single's value type

R - the result value type

Parameters:

s1 - the first source Single

s2 - a second source Single

s3 - a third source Single

s4 - a fourth source Single

s5 - a fifth source Single

s6 - a sixth source Single

zipFunction - 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

Returns:

a Single that emits the zipped results

See Also:

ReactiveX operators documentation: Zip

zip

public static  Single zip(Single s1,
                                                     Single s2,
                                                     Single s3,
                                                     Single s4,
                                                     Single s5,
                                                     Single s6,
                                                     Single s7,
                                                     Func7 zipFunction)

Returns an Observable that emits the results of a specified combiner function applied to seven items emitted by seven other Singles.

Scheduler:

zip does not operate by default on a particular Scheduler.

Type Parameters:

T1 - the first source Single's value type

T2 - the second source Single's value type

T3 - the third source Single's value type

T4 - the fourth source Single's value type

T5 - the fifth source Single's value type

T6 - the sixth source Single's value type

T7 - the seventh source Single's value type

R - the result value type

Parameters:

s1 - the first source Single

s2 - a second source Single

s3 - a third source Single

s4 - a fourth source Single

s5 - a fifth source Single

s6 - a sixth source Single

s7 - a seventh source Single

zipFunction - 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

Returns:

a Single that emits the zipped results

See Also:

ReactiveX operators documentation: Zip

zip

public static  Single zip(Single s1,
                                                        Single s2,
                                                        Single s3,
                                                        Single s4,
                                                        Single s5,
                                                        Single s6,
                                                        Single s7,
                                                        Single s8,
                                                        Func8 zipFunction)

Returns an Observable that emits the results of a specified combiner function applied to eight items emitted by eight other Singles.

Scheduler:

zip does not operate by default on a particular Scheduler.

Type Parameters:

T1 - the first source Single's value type

T2 - the second source Single's value type

T3 - the third source Single's value type

T4 - the fourth source Single's value type

T5 - the fifth source Single's value type

T6 - the sixth source Single's value type

T7 - the seventh source Single's value type

T8 - the eighth source Single's value type

R - the result value type

Parameters:

s1 - the first source Single

s2 - a second source Single

s3 - a third source Single

s4 - a fourth source Single

s5 - a fifth source Single

s6 - a sixth source Single

s7 - a seventh source Single

s8 - an eighth source Single

zipFunction - 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

Returns:

a Single that emits the zipped results

See Also:

ReactiveX operators documentation: Zip

zip

public static  Single zip(Single s1,
                                                           Single s2,
                                                           Single s3,
                                                           Single s4,
                                                           Single s5,
                                                           Single s6,
                                                           Single s7,
                                                           Single s8,
                                                           Single s9,
                                                           Func9 zipFunction)

Returns an Observable that emits the results of a specified combiner function applied to nine items emitted by nine other Singles.

Scheduler:

zip does not operate by default on a particular Scheduler.

Type Parameters:

T1 - the first source Single's value type

T2 - the second source Single's value type

T3 - the third source Single's value type

T4 - the fourth source Single's value type

T5 - the fifth source Single's value type

T6 - the sixth source Single's value type

T7 - the seventh source Single's value type

T8 - the eighth source Single's value type

T9 - the ninth source Single's value type

R - the result value type

Parameters:

s1 - the first source Single

s2 - a second source Single

s3 - a third source Single

s4 - a fourth source Single

s5 - a fifth source Single

s6 - a sixth source Single

s7 - a seventh source Single

s8 - an eighth source Single

s9 - a ninth source Single

zipFunction - 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

Returns:

a Single that emits the zipped results

See Also:

ReactiveX operators documentation: Zip

zip

public static  Single zip(java.lang.IterableSingle> singles,
                                FuncN zipFunction)

Returns a Single that emits the result of specified combiner function applied to combination of items emitted, in sequence, by an Iterable of other Singles.

zip applies this function in strict sequence.

Scheduler:

zip does not operate by default on a particular Scheduler.

Type Parameters:

R - the result value type

Parameters:

singles - an Iterable of source Singles. Should not be empty because Single either emits result or error. NoSuchElementException will be emit as error if Iterable will be empty.

zipFunction - a function that, when applied to an item emitted by each of the source Singles, results in an item that will be emitted by the resulting Single

Returns:

a Single that emits the zipped results

See Also:

ReactiveX operators documentation: Zip

cache

public final Single<T> cache()

Returns a Single that subscribes to this Single lazily, caches its success or error event and replays it to all the downstream subscribers.

This is useful when you want a Single to cache its response and you can't control the subscribe/unsubscribe behavior of all the Subscribers.

The operator subscribes only when the first downstream subscriber subscribes and maintains a single subscription towards this Single. In contrast, the operator family of Observable.replay() that return a ConnectableObservable require an explicit call to ConnectableObservable.connect().

Note: You sacrifice the ability to unsubscribe from the origin when you use the cache Observer so be careful not to use this Observer on Observables that emit an infinite or very large number of items that will use up memory. A possible workaround is to apply `takeUntil` with a predicate or another source before (and perhaps after) the application of cache().

 AtomicBoolean shouldStop = new AtomicBoolean();

 source.takeUntil(v -> shouldStop.get())
       .cache()
       .takeUntil(v -> shouldStop.get())
       .subscribe(...);
 

Since the operator doesn't allow clearing the cached values either, the possible workaround is to forget all references to it via Observable.onTerminateDetach() applied along with the previous workaround:

 AtomicBoolean shouldStop = new AtomicBoolean();

 source.takeUntil(v -> shouldStop.get())
       .onTerminateDetach()
       .cache()
       .takeUntil(v -> shouldStop.get())
       .onTerminateDetach()
       .subscribe(...);
 

Backpressure:

The operator consumes this Single in an unbounded fashion but respects the backpressure of each downstream Subscriber individually.

Scheduler:

cache does not operate by default on a particular Scheduler.

Returns:

a Single that, when first subscribed to, caches its response for the benefit of subsequent subscribers

Since:

1.3

See Also:

ReactiveX operators documentation: Replay

concatWith

public final Observable<T> concatWith(SingleT> t1)

Returns an Observable that emits the item emitted by the source Single, then the item emitted by the specified Single.

Scheduler:

concat does not operate by default on a particular Scheduler.

Parameters:

t1 - a Single to be concatenated after the current

Returns:

an Observable that emits the item emitted by the source Single, followed by the item emitted by t1

See Also:

ReactiveX operators documentation: Concat

flatMap

public final  Single flatMap(Func1T,? extends Single> func)

Returns a Single that is based on applying a specified function to the item emitted by the source Single, where that function returns a Single.

Scheduler:

flatMap does not operate by default on a particular Scheduler.

Type Parameters:

R - the result value type

Parameters:

func - a function that, when applied to the item emitted by the source Single, returns a Single

Returns:

the Single returned from func when applied to the item emitted by the source Single

See Also:

ReactiveX operators documentation: FlatMap

flatMapObservable

public final  Observable flatMapObservable(Func1T,? extends Observable> func)

Returns an Observable that emits items based on applying a specified function to the item emitted by the source Observable, where that function returns an Observable.

Scheduler:

flatMapObservable does not operate by default on a particular Scheduler.

Type Parameters:

R - the result value type

Parameters:

func - a function that, when applied to the item emitted by the source Single, returns an Observable

Returns:

the Observable returned from func when applied to the item emitted by the source Single

See Also:

ReactiveX operators documentation: FlatMap

flatMapCompletable

public final Completable flatMapCompletable(Func1T,? extends Completable> func)

Returns a Completable that completes based on applying a specified function to the item emitted by the source Completable, where that function returns a Completable.

Scheduler:

flatMapCompletable does not operate by default on a particular Scheduler.

Parameters:

func - a function that, when applied to the item emitted by the source Single, returns a Completable

Returns:

the Completable returned from func when applied to the item emitted by the source Single

Since:

1.3

See Also:

ReactiveX operators documentation: FlatMap

map

public final  Single map(Func1T,? extends R> func)

Returns a Single that applies a specified function to the item emitted by the source Single and emits the result of this function application.

Scheduler:

map does not operate by default on a particular Scheduler.

Type Parameters:

R - the result value type

Parameters:

func - a function to apply to the item emitted by the Single

Returns:

a Single that emits the item from the source Single, transformed by the specified function

See Also:

ReactiveX operators documentation: Map

mergeWith

public final Observable<T> mergeWith(SingleT> t1)

Flattens this and another Single into a single Observable, without any transformation.

You can combine items emitted by multiple Singles so that they appear as a single Observable, by using the mergeWith method.

Scheduler:

mergeWith does not operate by default on a particular Scheduler.

Parameters:

t1 - a Single to be merged

Returns:

an Observable that emits all of the items emitted by the source Singles

See Also:

ReactiveX operators documentation: Merge

observeOn

public final Single<T> observeOn(Scheduler scheduler)

Modifies a Single to emit its item (or notify of its error) on a specified Scheduler, asynchronously.

Scheduler:

you specify which Scheduler this operator will use

Parameters:

scheduler - the Scheduler to notify subscribers on

Returns:

the source Single modified so that its subscribers are notified on the specified Scheduler

See Also:

ReactiveX operators documentation: ObserveOn, RxJava Threading Examples, subscribeOn(rx.Scheduler)

onErrorReturn

public final Single<T> onErrorReturn(Func1T> resumeFunction)

Instructs a Single to emit an item (returned by a specified function) rather than invoking onError if it encounters an error.

By default, when a Single encounters an error that prevents it from emitting the expected item to its subscriber, the Single invokes its subscriber's Observer.onError(java.lang.Throwable) method, and then quits without invoking any more of its subscriber's methods. The onErrorReturn method changes this behavior. If you pass a function (resumeFunction) to a Single's onErrorReturn method, if the original Single encounters an error, instead of invoking its subscriber's Observer.onError(java.lang.Throwable) method, it will instead emit the return value of resumeFunction.

You can use this to prevent errors from propagating or to supply fallback data should errors be encountered.

Scheduler:

onErrorReturn does not operate by default on a particular Scheduler.

Parameters:

resumeFunction - a function that returns an item that the new Single will emit if the source Single encounters an error

Returns:

the original Single with appropriately modified behavior

See Also:

ReactiveX operators documentation: Catch

onErrorResumeNext

public final Single<T> onErrorResumeNext(SingleT> resumeSingleInCaseOfError)

Instructs a Single to pass control to another Single rather than invoking Observer.onError(Throwable) if it encounters an error.

By default, when a Single encounters an error that prevents it from emitting the expected item to its Observer, the Single invokes its Observer's onError method, and then quits without invoking any more of its Observer's methods. The onErrorResumeNext method changes this behavior. If you pass another Single (resumeSingleInCaseOfError) to a Single's onErrorResumeNext method, if the original Single encounters an error, instead of invoking its Observer's onError method, it will instead relinquish control to resumeSingleInCaseOfError which will invoke the Observer's onNext method if it is able to do so. In such a case, because no Single necessarily invokes onError, the Observer may never know that an error happened.

You can use this to prevent errors from propagating or to supply fallback data should errors be encountered.

Scheduler:

onErrorResumeNext does not operate by default on a particular Scheduler.

Parameters:

resumeSingleInCaseOfError - a Single that will take control if source Single encounters an error.

Returns:

the original Single, with appropriately modified behavior.

Since:

1.3

See Also:

ReactiveX operators documentation: Catch

onErrorResumeNext

public final Single<T> onErrorResumeNext(Func1SingleT>> resumeFunctionInCaseOfError)

Instructs a Single to pass control to another Single rather than invoking Observer.onError(Throwable) if it encounters an error.

By default, when a Single encounters an error that prevents it from emitting the expected item to its Observer, the Single invokes its Observer's onError method, and then quits without invoking any more of its Observer's methods. The onErrorResumeNext method changes this behavior. If you pass a function that will return another Single (resumeFunctionInCaseOfError) to a Single's onErrorResumeNext method, if the original Single encounters an error, instead of invoking its Observer's onError method, it will instead relinquish control to resumeSingleInCaseOfError which will invoke the Observer's onNext method if it is able to do so. In such a case, because no Single necessarily invokes onError, the Observer may never know that an error happened.

You can use this to prevent errors from propagating or to supply fallback data should errors be encountered.

Scheduler:

onErrorResumeNext does not operate by default on a particular Scheduler.

Parameters:

resumeFunctionInCaseOfError - a function that returns a Single that will take control if source Single encounters an error.

Returns:

the original Single, with appropriately modified behavior.

Since:

1.3

See Also:

ReactiveX operators documentation: Catch

subscribe

public final Subscription subscribe()

Subscribes to a Single but ignore its emission or notification.

Scheduler:

subscribe does not operate by default on a particular Scheduler.

Returns:

a Subscription reference can request the Single stop work.

Throws:

OnErrorNotImplementedException - if the Single tries to call Observer.onError(java.lang.Throwable)

See Also:

ReactiveX operators documentation: Subscribe

subscribe

public final Subscription subscribe(Action1T> onSuccess)

Subscribes to a Single and provides a callback to handle the item it emits.

Scheduler:

subscribe does not operate by default on a particular Scheduler.

Parameters:

onSuccess - the Action1 you have designed to accept the emission from the Single

Returns:

a Subscription reference can request the Single stop work.

Throws:

java.lang.IllegalArgumentException - if onNext is null

OnErrorNotImplementedException - if the Single tries to call Observer.onError(java.lang.Throwable)

See Also:

ReactiveX operators documentation: Subscribe

subscribe

public final Subscription subscribe(Action1T> onSuccess,
                                    Action1 onError)

Subscribes to a Single and provides callbacks to handle the item it emits or any error notification it issues.

Scheduler:

subscribe does not operate by default on a particular Scheduler.

Parameters:

onSuccess - the Action1 you have designed to accept the emission from the Single

onError - the Action1 you have designed to accept any error notification from the Single

Returns:

a Subscription reference can request the Single stop work.

Throws:

java.lang.IllegalArgumentException - if onNext is null, or if onError is null

See Also:

ReactiveX operators documentation: Subscribe

unsafeSubscribe

public final Subscription unsafeSubscribe(SubscriberT> subscriber)

Subscribes to a Single and invokes the Single.OnSubscribe function without any contract protection, error handling, unsubscribe, or execution hooks.

Use this only for implementing an Observable.Operator that requires nested subscriptions. For other purposes, use subscribe(Subscriber) which ensures the Rx contract and other functionality.

Scheduler:

unsafeSubscribe does not operate by default on a particular Scheduler.

Parameters:

subscriber - the Subscriber that will handle the emission or notification from the Single

Returns:

the subscription that allows unsubscribing

subscribe

public final Subscription subscribe(ObserverT> observer)

Subscribes an Observer to this single and returns a Subscription that allows unsubscription.

Parameters:

observer - the Observer to subscribe

Returns:

the Subscription that allows unsubscription

subscribe

public final Subscription subscribe(SubscriberT> subscriber)

Subscribes to a Single and provides a Subscriber that implements functions to handle the item the Single emits or any error notification it issues.

A typical implementation of subscribe does the following:

1. It stores a reference to the Subscriber in a collection object, such as a List object.
2. It returns a reference to the Subscription interface. This enables Subscribers to unsubscribe, that is, to stop receiving the item or notification before the Single completes.

A Single instance is responsible for accepting all subscriptions and notifying all Subscribers. Unless the documentation for a particular Single implementation indicates otherwise, Subscribers should make no assumptions about the order in which multiple Subscribers will receive their notifications.

For more information see the ReactiveX documentation.

Scheduler:

subscribe does not operate by default on a particular Scheduler.

Parameters:

subscriber - the Subscriber that will handle the emission or notification from the Single

Returns:

a Subscription reference can request the Single stop work.

Throws:

java.lang.IllegalStateException - if subscribe is unable to obtain an OnSubscribe<> function

java.lang.IllegalArgumentException - if the Subscriber provided as the argument to subscribe is null

OnErrorNotImplementedException - if the Subscriber's onError method is null

java.lang.RuntimeException - if the Subscriber's onError method itself threw a Throwable

See Also:

ReactiveX operators documentation: Subscribe

subscribe

public final Subscription subscribe(SingleSubscriberT> te)

Subscribes to a Single and provides a SingleSubscriber that implements functions to handle the item the Single emits or any error notification it issues.

A typical implementation of subscribe does the following:

1. It stores a reference to the Subscriber in a collection object, such as a List object.
2. It returns a reference to the Subscription interface. This enables Subscribers to unsubscribe, that is, to stop receiving the item or notification before the Single completes.

A Single instance is responsible for accepting all subscriptions and notifying all Subscribers. Unless the documentation for a particular Single implementation indicates otherwise, Subscribers should make no assumptions about the order in which multiple Subscribers will receive their notifications.

For more information see the ReactiveX documentation.

Scheduler:

subscribe does not operate by default on a particular Scheduler.

Parameters:

te - the SingleSubscriber that will handle the emission or notification from the Single

Returns:

a Subscription reference can request the Single stop work.

Throws:

java.lang.IllegalStateException - if subscribe is unable to obtain an OnSubscribe<> function

java.lang.IllegalArgumentException - if the SingleSubscriber provided as the argument to subscribe is null

OnErrorNotImplementedException - if the SingleSubscriber's onError method is null

java.lang.RuntimeException - if the SingleSubscriber's onError method itself threw a Throwable

See Also:

ReactiveX operators documentation: Subscribe

subscribeOn

public final Single<T> subscribeOn(Scheduler scheduler)

Asynchronously subscribes subscribers to this Single on the specified Scheduler.

Scheduler:

you specify which Scheduler this operator will use

Parameters:

scheduler - the Scheduler to perform subscription actions on

Returns:

the source Single modified so that its subscriptions happen on the specified Scheduler

See Also:

ReactiveX operators documentation: SubscribeOn, RxJava Threading Examples, observeOn(rx.Scheduler)

takeUntil

public final Single<T> takeUntil(Completable other)

Returns a Single that emits the item emitted by the source Single until a Completable terminates. Upon termination of other, this will emit a CancellationException rather than go to SingleSubscriber.onSuccess(Object).

Scheduler:

takeUntil does not operate by default on a particular Scheduler.

Parameters:

other - the Completable whose termination will cause takeUntil to emit the item from the source Single

Returns:

a Single that emits the item emitted by the source Single until such time as other terminates.

See Also:

ReactiveX operators documentation: TakeUntil

takeUntil

public final  Single<T> takeUntil(Observable other)

Returns a Single that emits the item emitted by the source Single until an Observable emits an item. Upon emission of an item from other, this will emit a CancellationException rather than go to SingleSubscriber.onSuccess(Object).

Scheduler:

takeUntil does not operate by default on a particular Scheduler.

Type Parameters:

E - the type of items emitted by other

Parameters:

other - the Observable whose first emitted item will cause takeUntil to emit the item from the source Single

Returns:

a Single that emits the item emitted by the source Single until such time as other emits its first item

See Also:

ReactiveX operators documentation: TakeUntil

takeUntil

public final  Single<T> takeUntil(Single other)

Returns a Single that emits the item emitted by the source Single until a second Single emits an item. Upon emission of an item from other, this will emit a CancellationException rather than go to SingleSubscriber.onSuccess(Object).

Scheduler:

takeUntil does not operate by default on a particular Scheduler.

Type Parameters:

E - the type of item emitted by other

Parameters:

other - the Single whose emitted item will cause takeUntil to emit the item from the source Single

Returns:

a Single that emits the item emitted by the source Single until such time as other emits its item

See Also:

ReactiveX operators documentation: TakeUntil

to

public final  R to(Func1Single<T>,R> converter)

Calls the specified converter function during assembly time and returns its resulting value.

This allows fluent conversion to any other type.

Type Parameters:

R - the resulting object type

Parameters:

converter - the function that receives the current Single instance and returns a value

Returns:

the value returned by the function

Since:

1.3

toObservable

public final Observable<T> toObservable()

Converts this Single into an Observable.

Returns:

an Observable that emits a single item T.

toCompletable

public final Completable toCompletable()

Returns a Completable that discards result of the Single (similar to Observable.ignoreElements()) and calls onCompleted when this source Single calls onSuccess. Error terminal event is propagated.

Scheduler:

toCompletable does not operate by default on a particular Scheduler.

Returns:

a Completable that calls onCompleted on it's subscriber when the source Single calls onSuccess.

Since:

1.3

See Also:

ReactiveX documentation: Completable

timeout

public final Single<T> timeout(long timeout,
                               java.util.concurrent.TimeUnit timeUnit)

Returns a Single that mirrors the source Single but applies a timeout policy for its emitted item. If it is not emitted within the specified timeout duration, the resulting Single terminates and notifies subscribers of a TimeoutException.

Scheduler:

This version of timeout operates by default on the computation Scheduler.

Parameters:

timeout - maximum duration before the Single times out

timeUnit - the unit of time that applies to the timeout argument.

Returns:

the source Single modified to notify subscribers of a TimeoutException in case of a timeout

See Also:

ReactiveX operators documentation: Timeout

timeout

public final Single<T> timeout(long timeout,
                               java.util.concurrent.TimeUnit timeUnit,
                               Scheduler scheduler)

Returns a Single that mirrors the source Single but applies a timeout policy for its emitted item, where this policy is governed on a specified Scheduler. If the item is not emitted within the specified timeout duration, the resulting Single terminates and notifies subscribers of a TimeoutException.

Scheduler:

you specify which Scheduler this operator will use

Parameters:

timeout - maximum duration before the Single times out

timeUnit - the unit of time that applies to the timeout argument

scheduler - the Scheduler to run the timeout timers on

Returns:

the source Single modified to notify subscribers of a TimeoutException in case of a timeout

See Also:

ReactiveX operators documentation: Timeout

timeout

public final Single<T> timeout(long timeout,
                               java.util.concurrent.TimeUnit timeUnit,
                               SingleT> other)

Returns a Single that mirrors the source Single but applies a timeout policy for its emitted item. If it is not emitted within the specified timeout duration, the resulting Single instead mirrors a fallback Single.

Scheduler:

This version of timeout operates by default on the computation Scheduler.

Parameters:

timeout - maximum time before a timeout occurs

timeUnit - the unit of time that applies to the timeout argument

other - the fallback Single to use in case of a timeout

Returns:

the source Single modified to switch to the fallback Single in case of a timeout

See Also:

ReactiveX operators documentation: Timeout

timeout

public final Single<T> timeout(long timeout,
                               java.util.concurrent.TimeUnit timeUnit,
                               SingleT> other,
                               Scheduler scheduler)

Returns a Single that mirrors the source Single but applies a timeout policy for its emitted item, using a specified Scheduler. If the item isn't emitted within the specified timeout duration, the resulting Single instead mirrors a fallback Single.

Scheduler:

you specify which Scheduler this operator will use

Parameters:

timeout - maximum duration before a timeout occurs

timeUnit - the unit of time that applies to the timeout argument

other - the Single to use as the fallback in case of a timeout

scheduler - the Scheduler to run the timeout timers on

Returns:

the source Single modified so that it will switch to the fallback Single in case of a timeout

See Also:

ReactiveX operators documentation: Timeout

toBlocking

public final BlockingSingle<T> toBlocking()

Converts a Single into a BlockingSingle (a Single with blocking operators).

Scheduler:

toBlocking does not operate by default on a particular Scheduler.

Returns:

a BlockingSingle version of this Single.

Since:

1.3

See Also:

ReactiveX operators documentation: To

zipWith

public final  Single zipWith(Single other,
                                      Func2T,? super T2,? extends R> zipFunction)

Returns a Single that emits the result of applying a specified function to the pair of items emitted by the source Single and another specified Single.

Scheduler:

zipWith does not operate by default on a particular Scheduler.

Type Parameters:

T2 - the type of items emitted by the other Single

R - the type of items emitted by the resulting Single

Parameters:

other - the other Observable

zipFunction - a function that combines the pairs of items from the two Observables to generate the items to be emitted by the resulting Single

Returns:

an Observable that pairs up values from the source Observable and the other Observable and emits the results of zipFunction applied to these pairs

See Also:

ReactiveX operators documentation: Zip

doOnError

public final Single<T> doOnError(Action1 onError)

Modifies the source Single so that it invokes an action if it calls onError.

In case the onError action throws, the downstream will receive a composite exception containing the original exception and the exception thrown by onError.

Scheduler:

doOnError does not operate by default on a particular Scheduler.

Parameters:

onError - the action to invoke if the source Single calls onError

Returns:

the source Single with the side-effecting behavior applied

Since:

1.3

See Also:

ReactiveX operators documentation: Do

doOnEach

public final Single<T> doOnEach(Action1<NotificationT>> onNotification)

Modifies the source Single so that it invokes an action when it calls onSuccess or onError.

Scheduler:

doOnEach does not operate by default on a particular Scheduler.

Parameters:

onNotification - the action to invoke when the source Single calls onSuccess or onError.

Returns:

the source Single with the side-effecting behavior applied

Since:

1.3

See Also:

ReactiveX operators documentation: Do

doOnSuccess

public final Single<T> doOnSuccess(Action1T> onSuccess)

Modifies the source Single so that it invokes an action when it calls onSuccess.

Scheduler:

doOnSuccess does not operate by default on a particular Scheduler.

Parameters:

onSuccess - the action to invoke when the source Single calls onSuccess

Returns:

the source Single with the side-effecting behavior applied

Since:

1.3

See Also:

ReactiveX operators documentation: Do

doOnSubscribe

public final Single<T> doOnSubscribe(Action0 subscribe)

Modifies the source Single so that it invokes the given action when it is subscribed from its subscribers. Each subscription will result in an invocation of the given action except when the source Single is reference counted, in which case the source Single will invoke the given action for the first subscription.

Scheduler:

doOnSubscribe does not operate by default on a particular Scheduler.

Parameters:

subscribe - the action that gets called when an observer subscribes to this Single

Returns:

the source Single modified so as to call this Action when appropriate

Since:

1.3

See Also:

ReactiveX operators documentation: Do

delay

public final Single<T> delay(long delay,
                             java.util.concurrent.TimeUnit unit,
                             Scheduler scheduler)

Returns a Single that emits the items emitted by the source Single shifted forward in time by a specified delay. Error notifications from the source Single are not delayed.

Scheduler:

you specify which Scheduler this operator will use

Parameters:

delay - the delay to shift the source by

unit - the time unit of delay

scheduler - the Scheduler to use for delaying

Returns:

the source Single shifted in time by the specified delay

Since:

1.3

See Also:

ReactiveX operators documentation: Delay

delay

public final Single<T> delay(long delay,
                             java.util.concurrent.TimeUnit unit)

Returns a Single that emits the items emitted by the source Single shifted forward in time by a specified delay. Error notifications from the source Observable are not delayed.

Scheduler:

This version of delay operates by default on the computation Scheduler.

Parameters:

delay - the delay to shift the source by

unit - the TimeUnit in which period is defined

Returns:

the source Single shifted in time by the specified delay

Since:

1.3

See Also:

ReactiveX operators documentation: Delay

defer

public static  Single defer(java.util.concurrent.Callable<Single> singleFactory)

Returns a Single that calls a Single factory to create a Single for each new Observer that subscribes. That is, for each subscriber, the actual Single that subscriber observes is determined by the factory function.

The defer Observer allows you to defer or delay emitting value from a Single until such time as an Observer subscribes to the Single. This allows an Observer to easily obtain updates or a refreshed version of the sequence.

Scheduler:

defer does not operate by default on a particular Scheduler.

Type Parameters:

T - the type of the items emitted by the Single.

Parameters:

singleFactory - the Single factory function to invoke for each Observer that subscribes to the resulting Single.

Returns:

a Single whose Observers' subscriptions trigger an invocation of the given Single factory function.

Since:

1.3

See Also:

ReactiveX operators documentation: Defer

doOnUnsubscribe

public final Single<T> doOnUnsubscribe(Action0 action)

Modifies the source Single so that it invokes the given action when it is unsubscribed from its subscribers.

Scheduler:

doOnUnsubscribe does not operate by default on a particular Scheduler.

Parameters:

action - the action that gets called when this Single is unsubscribed.

Returns:

the source Single modified so as to call this Action when appropriate.

Since:

1.3

See Also:

ReactiveX operators documentation: Do

doAfterTerminate

public final Single<T> doAfterTerminate(Action0 action)

Registers an Action0 to be called when this Single invokes either SingleSubscriber.onSuccess(Object) onSuccess} or onError.

Scheduler:

doAfterTerminate does not operate by default on a particular Scheduler.

Parameters:

action - an Action0 to be invoked when the source Single finishes.

Returns:

a Single that emits the same item or error as the source Single, then invokes the Action0

Since:

1.3

See Also:

ReactiveX operators documentation: Do

retry

public final Single<T> retry()

Returns a Single that mirrors the source Single, resubscribing to it if it calls onError (infinite retry count). If the source Single calls SingleSubscriber.onError(java.lang.Throwable), this method will resubscribe to the source Single rather than propagating the onError call.

Scheduler:

retry operates by default on the trampoline Scheduler.

Returns:

the source Single modified with retry logic

See Also:

ReactiveX operators documentation: Retry

retry

public final Single<T> retry(long count)

Returns a Single that mirrors the source Single, resubscribing to it if it calls onError up to a specified number of retries. If the source Single calls SingleSubscriber.onError(java.lang.Throwable), this method will resubscribe to the source Single for a maximum of count resubscriptions rather than propagating the onError call.

Scheduler:

retry operates by default on the trampoline Scheduler.

Parameters:

count - number of retry attempts before failing

Returns:

the source Single modified with retry logic

See Also:

ReactiveX operators documentation: Retry

retry

public final Single<T> retry(Func2 predicate)

Returns a Single that mirrors the source Single, resubscribing to it if it calls onError and the predicate returns true for that specific exception and retry count.

Backpressure Support:

This operator honors backpressure.

Scheduler:

retry operates by default on the trampoline Scheduler.

Parameters:

predicate - the predicate that determines if a resubscription may happen in case of a specific exception and retry count

Returns:

the source Single modified with retry logic

See Also:

retry(), ReactiveX operators documentation: Retry

retryWhen

public final Single<T> retryWhen(Func1<Observable,? extends Observable> notificationHandler)

Returns a Single that emits the same values as the source Single with the exception of an onError. An onError notification from the source will result in the emission of a Throwable item to the Observable provided as an argument to the notificationHandler function.

Emissions from the handler Observable is treated as follows:

• If the handler Observable emits an onCompleted the retryWhen will call onError with NoSuchElementException on the child subscription.
• If the handler Observable emits an onError the retryWhen will call onError with the same Throwable instance on the child subscription.
• Otherwise, the operator will resubscribe to the source Single.

The notificationHandler function is called for each subscriber individually. This allows per-Subscriber state to be added to the error notification sequence.

 single.retryWhen(error -> {
     AtomicInteger counter = new AtomicInteger();
     return error.takeWhile(e -> counter.incrementAndGet() < 3).map(e -> "retry");
 }).subscribe(...);
 

Note that you must compose over the input Observable provided in the function call because retryWhen(rx.functions.Func1, ? extends rx.Observable>) expects an emission of the exception to be matched by an event from the handler Observable.

Scheduler:

retryWhen operates by default on the trampoline Scheduler.

Parameters:

notificationHandler - receives an Observable of notifications with which a user can complete or error, aborting the retry

Returns:

the source Single modified with retry logic

See Also:

ReactiveX operators documentation: Retry

using

public static  Single using(Func0 resourceFactory,
                                           Func1Single> singleFactory,
                                           Action1 disposeAction)

Constructs a Single that creates a dependent resource object which is disposed of on unsubscription.

Scheduler:

using does not operate by default on a particular Scheduler.

Type Parameters:

T - the value type of the generated source

Resource - the type of the per-subscriber resource

Parameters:

resourceFactory - the factory function to create a resource object that depends on the Single

singleFactory - the factory function to create a Single

disposeAction - the function that will dispose of the resource

Returns:

the Single whose lifetime controls the lifetime of the dependent resource object

Since:

1.3

See Also:

ReactiveX operators documentation: Using

using

public static  Single using(Func0 resourceFactory,
                                           Func1Single> singleFactory,
                                           Action1 disposeAction,
                                           boolean disposeEagerly)

Constructs a Single that creates a dependent resource object which is disposed of just before termination if you have set disposeEagerly to true and unsubscription does not occur before termination. Otherwise resource disposal will occur on unsubscription. Eager disposal is particularly appropriate for a synchronous Single that reuses resources. disposeAction will only be called once per subscription.

Scheduler:

using does not operate by default on a particular Scheduler.

Type Parameters:

T - the value type of the generated source

Resource - the type of the per-subscriber resource

Parameters:

resourceFactory - the factory function to create a resource object that depends on the Single

singleFactory - the factory function to create a Single

disposeAction - the function that will dispose of the resource

disposeEagerly - if true then disposal will happen either on unsubscription or just before emission of a terminal event (onComplete or onError).

Returns:

the Single whose lifetime controls the lifetime of the dependent resource object

Since:

1.3

See Also:

ReactiveX operators documentation: Using

delaySubscription

public final Single<T> delaySubscription(Observable other)

Returns a Single that delays the subscription to this Single until the Observable completes. In case the onError of the supplied observer throws, the exception will be propagated to the downstream subscriber and will result in skipping the subscription of this Single.

Scheduler:

This method does not operate by default on a particular Scheduler.

Parameters:

other - the Observable that should trigger the subscription to this Single.

Returns:

a Single that delays the subscription to this Single until the Observable emits an element or completes normally.

Since:

1.3

unsubscribeOn

@Experimental
public final Single<T> unsubscribeOn(Scheduler scheduler)

Returns a Single which makes sure when a subscriber cancels the subscription, the dispose is called on the specified scheduler

Parameters:

scheduler - the target scheduler where to execute the cancellation

Returns:

the new Single instance

Since:

1.2.8 - experimental

test

public final AssertableSubscriber<T> test()

Creates an AssertableSubscriber that requests Long.MAX_VALUE and subscribes it to this Observable.

Backpressure:

The returned AssertableSubscriber consumes this Observable in an unbounded fashion.

Scheduler:

test does not operate by default on a particular Scheduler.

History: 1.2.3 - experimental

Returns:

the new AssertableSubscriber instance

Since:

1.3