Class Single<T>
- Type Parameters:
T
- the type of the item emitted by the Single
- Direct Known Subclasses:
ScalarSynchronousSingle
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:
- (If this class graduates from "Experimental" replace this parenthetical with the release number)
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionstatic interface
Invoked when Single.execute is called.static interface
Transformer function used bycompose(rx.Single.Transformer<? super T, ? extends R>)
. -
Field Summary
Fields -
Constructor Summary
ConstructorsModifierConstructorDescriptionprivate
protected
Creates a Single with a Function to execute when it is subscribed to (executed). -
Method Summary
Modifier and TypeMethodDescriptionprivate static <T> Observable
<T> asObservable
(Single<T> t) <R> Single
<R> compose
(Single.Transformer<? super T, ? extends R> transformer) Transform a Single by applying a particular Transformer function to it.static <T> Observable
<T> Returns an Observable that emits the items emitted by two Singles, one after the other.static <T> Observable
<T> Returns an Observable that emits the items emitted by three Singles, one after the other.static <T> Observable
<T> concat
(Single<? extends T> t1, Single<? extends T> t2, Single<? extends T> t3, Single<? extends T> t4) Returns an Observable that emits the items emitted by four Singles, one after the other.static <T> Observable
<T> concat
(Single<? extends T> t1, Single<? extends T> t2, Single<? extends T> t3, Single<? extends T> t4, Single<? extends T> t5) Returns an Observable that emits the items emitted by five Singles, one after the other.static <T> Observable
<T> concat
(Single<? extends T> t1, Single<? extends T> t2, Single<? extends T> t3, Single<? extends T> t4, Single<? extends T> t5, Single<? extends T> t6) Returns an Observable that emits the items emitted by six Singles, one after the other.static <T> Observable
<T> concat
(Single<? extends T> t1, Single<? extends T> t2, Single<? extends T> t3, Single<? extends T> t4, Single<? extends T> t5, Single<? extends T> t6, Single<? extends T> t7) Returns an Observable that emits the items emitted by seven Singles, one after the other.static <T> Observable
<T> concat
(Single<? extends T> t1, Single<? extends T> t2, Single<? extends T> t3, Single<? extends T> t4, Single<? extends T> t5, Single<? extends T> t6, Single<? extends T> t7, Single<? extends T> t8) Returns an Observable that emits the items emitted by eight Singles, one after the other.static <T> Observable
<T> concat
(Single<? extends T> t1, Single<? extends T> t2, Single<? extends T> t3, Single<? extends T> t4, Single<? extends T> t5, Single<? extends T> t6, Single<? extends T> t7, Single<? extends T> t8, Single<? extends T> t9) Returns an Observable that emits the items emitted by nine Singles, one after the other.final Observable
<T> concatWith
(Single<? extends T> t1) Returns an Observable that emits the item emitted by the source Single, then the item emitted by the specified Single.static <T> Single
<T> create
(Single.OnSubscribe<T> f) Returns a Single that will execute the specified function when aSingleSubscriber
executes it or aSubscriber
subscribes to it.static <T> Single
<T> Returns an Single that emits the items emitted by the source Single shifted forward in time by a specified delay.Returns an Single that emits the items emitted by the source Single shifted forward in time by a specified delay.delaySubscription
(Observable<?> other) Returns a Single that delays the subscription to this Single until the Observable completes.doAfterTerminate
(Action0 action) Registers anAction0
to be called when thisSingle
invokes eitherSingleSubscriber.onSuccess(Object)
onSuccess} oronError
.Modifies the sourceSingle
so that it invokes an action if it callsonError
.doOnSubscribe
(Action0 subscribe) Modifies the sourceSingle
so that it invokes the given action when it is subscribed from its subscribers.doOnSuccess
(Action1<? super T> onSuccess) Modifies the sourceSingle
so that it invokes an action when it callsonSuccess
.doOnUnsubscribe
(Action0 action) Modifies the sourceSingle
so that it invokes the given action when it is unsubscribed from its subscribers.static <T> Single
<T> Returns a Single that invokes a subscriber'sonError
method when the subscriber subscribes to it.final <R> Single
<R> 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.final <R> Observable
<R> flatMapObservable
(Func1<? super T, ? extends Observable<? extends R>> 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 <T> Single
<T> Converts aFuture
into aSingle
.static <T> Single
<T> Converts aFuture
into aSingle
, with a timeout on the Future.static <T> Single
<T> static <T> Single
<T> fromCallable
(Callable<? extends T> func) Returns aSingle
that invokes passed function and emits its result for each new Observer that subscribes.(package private) static <T> Single<? extends T>[]
iterableToArray
(Iterable<? extends Single<? extends T>> singlesIterable) FOR INTERNAL USE ONLY.static <T> Single
<T> just
(T value) Returns aSingle
that emits a specified item.final <R> Single
<R> lift
(Observable.Operator<? extends R, ? super T> 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.final <R> Single
<R> 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 <T> Single
<T> Flattens aSingle
that emits aSingle
into a singleSingle
that emits the item emitted by the nestedSingle
, without any transformation.static <T> Observable
<T> Flattens two Singles into a single Observable, without any transformation.static <T> Observable
<T> Flattens three Singles into a single Observable, without any transformation.static <T> Observable
<T> merge
(Single<? extends T> t1, Single<? extends T> t2, Single<? extends T> t3, Single<? extends T> t4) Flattens four Singles into a single Observable, without any transformation.static <T> Observable
<T> merge
(Single<? extends T> t1, Single<? extends T> t2, Single<? extends T> t3, Single<? extends T> t4, Single<? extends T> t5) Flattens five Singles into a single Observable, without any transformation.static <T> Observable
<T> merge
(Single<? extends T> t1, Single<? extends T> t2, Single<? extends T> t3, Single<? extends T> t4, Single<? extends T> t5, Single<? extends T> t6) Flattens six Singles into a single Observable, without any transformation.static <T> Observable
<T> merge
(Single<? extends T> t1, Single<? extends T> t2, Single<? extends T> t3, Single<? extends T> t4, Single<? extends T> t5, Single<? extends T> t6, Single<? extends T> t7) Flattens seven Singles into a single Observable, without any transformation.static <T> Observable
<T> merge
(Single<? extends T> t1, Single<? extends T> t2, Single<? extends T> t3, Single<? extends T> t4, Single<? extends T> t5, Single<? extends T> t6, Single<? extends T> t7, Single<? extends T> t8) Flattens eight Singles into a single Observable, without any transformation.static <T> Observable
<T> merge
(Single<? extends T> t1, Single<? extends T> t2, Single<? extends T> t3, Single<? extends T> t4, Single<? extends T> t5, Single<? extends T> t6, Single<? extends T> t7, Single<? extends T> t8, Single<? extends T> t9) Flattens nine Singles into a single Observable, without any transformation.final Observable
<T> Flattens this and another Single into a single Observable, without any transformation.private Single
<Observable<T>> nest()
INTERNAL: Used with lift and operators.Modifies a Single to emit its item (or notify of its error) on a specifiedScheduler
, asynchronously.onErrorResumeNext
(Func1<Throwable, ? extends Single<? extends T>> resumeFunctionInCaseOfError) Instructs a Single to pass control to another Single rather than invokingObserver.onError(Throwable)
if it encounters an error.onErrorResumeNext
(Single<? extends T> resumeSingleInCaseOfError) Instructs a Single to pass control to another Single rather than invokingObserver.onError(Throwable)
if it encounters an error.onErrorReturn
(Func1<Throwable, ? extends T> resumeFunction) Instructs a Single to emit an item (returned by a specified function) rather than invokingonError
if it encounters an error.retry()
Returns a Single that mirrors the source Single, resubscribing to it if it callsonError
(infinite retry count).retry
(long count) Returns an Single that mirrors the source Single, resubscribing to it if it callsonError
up to a specified number of retries.Returns an Single that mirrors the source Single, resubscribing to it if it callsonError
and the predicate returns true for that specific exception and retry count.retryWhen
(Func1<Observable<? extends Throwable>, ? extends Observable<?>> notificationHandler) Returns a Single that emits the same values as the source Single with the exception of anonError
.final Subscription
Subscribes to a Single but ignore its emission or notification.final Subscription
Subscribes to a Single and provides a callback to handle the item it emits.final Subscription
Subscribes to a Single and provides callbacks to handle the item it emits or any error notification it issues.final Subscription
Subscribes an Observer to this single and returns a Subscription that allows unsubscription.final Subscription
subscribe
(SingleSubscriber<? super T> te) Subscribes to a Single and provides aSingleSubscriber
that implements functions to handle the item the Single emits or any error notification it issues.final Subscription
subscribe
(Subscriber<? super T> 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.subscribeOn
(Scheduler scheduler) Asynchronously subscribes subscribers to this Single on the specifiedScheduler
.takeUntil
(Completable other) Returns a Single that emits the item emitted by the source Single until a Completable terminates.takeUntil
(Observable<? extends E> other) Returns a Single that emits the item emitted by the source Single until an Observable emits an item.Returns a Single that emits the item emitted by the source Single until a second Single emits an item.Returns a Single that mirrors the source Single but applies a timeout policy for its emitted item.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.Returns a Single that mirrors the source Single but applies a timeout policy for its emitted item.Returns a Single that mirrors the source Single but applies a timeout policy for its emitted item, using a specified Scheduler.final BlockingSingle
<T> Converts a Single into aBlockingSingle
(a Single with blocking operators).final Completable
Returns aCompletable
that discards result of theSingle
(similar toObservable.ignoreElements()
) and callsonCompleted
when this sourceSingle
callsonSuccess
.final Observable
<T> Converts this Single into anObservable
.final Subscription
unsafeSubscribe
(Subscriber<? super T> subscriber) Subscribes to a Single and invokes theSingle.OnSubscribe
function without any contract protection, error handling, unsubscribe, or execution hooks.static <T,
Resource>
Single<T> using
(Func0<Resource> resourceFactory, Func1<? super Resource, ? extends Single<? extends T>> singleFactory, Action1<? super Resource> disposeAction) Constructs an Single that creates a dependent resource object which is disposed of on unsubscription.static <T,
Resource>
Single<T> using
(Func0<Resource> resourceFactory, Func1<? super Resource, ? extends Single<? extends T>> singleFactory, Action1<? super Resource> disposeAction, boolean disposeEagerly) Constructs an Single that creates a dependent resource object which is disposed of just before termination if you have setdisposeEagerly
totrue
and unsubscription does not occur before termination.static <R> Single
<R> 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 <T1,
T2, R>
Single<R> zip
(Single<? extends T1> s1, Single<? extends T2> s2, Func2<? super T1, ? super T2, ? extends R> zipFunction) Returns a Single that emits the results of a specified combiner function applied to two items emitted by two other Singles.static <T1,
T2, T3, R>
Single<R> zip
(Single<? extends T1> s1, Single<? extends T2> s2, Single<? extends T3> s3, Func3<? super T1, ? super T2, ? super T3, ? extends R> zipFunction) Returns a Single that emits the results of a specified combiner function applied to three items emitted by three other Singles.static <T1,
T2, T3, T4, R>
Single<R> zip
(Single<? extends T1> s1, Single<? extends T2> s2, Single<? extends T3> s3, Single<? extends T4> s4, Func4<? super T1, ? super T2, ? super T3, ? super T4, ? extends R> zipFunction) Returns an Observable that emits the results of a specified combiner function applied to four items emitted by four other Singles.static <T1,
T2, T3, T4, T5, R>
Single<R> zip
(Single<? extends T1> s1, Single<? extends T2> s2, Single<? extends T3> s3, Single<? extends T4> s4, Single<? extends T5> s5, Func5<? super T1, ? super T2, ? super T3, ? super T4, ? super T5, ? extends R> zipFunction) Returns an Observable that emits the results of a specified combiner function applied to five items emitted by five other Singles.static <T1,
T2, T3, T4, T5, T6, R>
Single<R> zip
(Single<? extends T1> s1, Single<? extends T2> s2, Single<? extends T3> s3, Single<? extends T4> s4, Single<? extends T5> s5, Single<? extends T6> s6, Func6<? super T1, ? super T2, ? super T3, ? super T4, ? super T5, ? super T6, ? extends R> zipFunction) Returns an Observable that emits the results of a specified combiner function applied to six items emitted by six other Singles.static <T1,
T2, T3, T4, T5, T6, T7, R>
Single<R> zip
(Single<? extends T1> s1, Single<? extends T2> s2, Single<? extends T3> s3, Single<? extends T4> s4, Single<? extends T5> s5, Single<? extends T6> s6, Single<? extends T7> s7, Func7<? super T1, ? super T2, ? super T3, ? super T4, ? super T5, ? super T6, ? super T7, ? extends R> zipFunction) Returns an Observable that emits the results of a specified combiner function applied to seven items emitted by seven other Singles.static <T1,
T2, T3, T4, T5, T6, T7, T8, R>
Single<R> zip
(Single<? extends T1> s1, Single<? extends T2> s2, Single<? extends T3> s3, Single<? extends T4> s4, Single<? extends T5> s5, Single<? extends T6> s6, Single<? extends T7> s7, Single<? extends T8> s8, Func8<? super T1, ? super T2, ? super T3, ? super T4, ? super T5, ? super T6, ? super T7, ? super T8, ? extends R> zipFunction) Returns an Observable that emits the results of a specified combiner function applied to eight items emitted by eight other Singles.static <T1,
T2, T3, T4, T5, T6, T7, T8, T9, R>
Single<R> zip
(Single<? extends T1> s1, Single<? extends T2> s2, Single<? extends T3> s3, Single<? extends T4> s4, Single<? extends T5> s5, Single<? extends T6> s6, Single<? extends T7> s7, Single<? extends T8> s8, Single<? extends T9> s9, Func9<? super T1, ? super T2, ? super T3, ? super T4, ? super T5, ? super T6, ? super T7, ? super T8, ? super T9, ? extends R> zipFunction) Returns an Observable that emits the results of a specified combiner function applied to nine items emitted by nine other Singles.final <T2,
R> Single <R> 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.
-
Field Details
-
onSubscribe
-
-
Constructor Details
-
Single
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
-OnExecute
to be executed whenexecute(SingleSubscriber)
orsubscribe(Subscriber)
is called
-
Single
-
-
Method Details
-
create
Returns a Single that will execute the specified function when aSingleSubscriber
executes it or aSubscriber
subscribes to it.Write the function you pass to
create
so that it behaves as a Single: It should invoke the SingleSubscriberonSuccess
and/oronError
methods appropriately.A well-formed Single must invoke either the SingleSubscriber's
onSuccess
method exactly once or itsonError
method exactly once.- Scheduler:
create
does not operate by default on a particularScheduler
.
- Type Parameters:
T
- the type of the item that this Single emits- Parameters:
f
- a function that accepts anSingleSubscriber<T>
, and invokes itsonSuccess
oronError
methods as appropriate- Returns:
- a Single that, when a
Subscriber
subscribes to it, will execute the specified function - See Also:
-
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) usecompose(rx.Single.Transformer<? super T, ? extends R>)
.- Scheduler:
lift
does not operate by default on a particularScheduler
.
- 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
- See Also:
-
compose
Transform a Single by applying a particular Transformer function to it.This method operates on the Single itself whereas
lift(rx.Observable.Operator<? extends R, ? super T>)
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<? extends R, ? super T>)
. 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) usecompose
.- Scheduler:
compose
does not operate by default on a particularScheduler
.
- 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:
-
asObservable
-
nest
INTERNAL: Used with lift and operators. Converts the sourceSingle<T>
into anSingle<Observable<T>>
that emits an Observable that emits the same emission as the source Single.- Scheduler:
nest
does not operate by default on a particularScheduler
.
- Returns:
- a Single that emits an Observable that emits the same item as the source Single
- See Also:
-
concat
Returns an Observable that emits the items emitted by two Singles, one after the other.- Scheduler:
concat
does not operate by default on a particularScheduler
.
- Type Parameters:
T
- the common value type- Parameters:
t1
- an Single to be concatenatedt2
- an Single to be concatenated- Returns:
- an Observable that emits items emitted by the two source Singles, one after the other.
- See Also:
-
concat
public static <T> Observable<T> concat(Single<? extends T> t1, Single<? extends T> t2, Single<? extends T> 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 particularScheduler
.
- Type Parameters:
T
- the common value type- Parameters:
t1
- a Single to be concatenatedt2
- a Single to be concatenatedt3
- a Single to be concatenated- Returns:
- an Observable that emits items emitted by the three source Singles, one after the other.
- See Also:
-
concat
public static <T> Observable<T> concat(Single<? extends T> t1, Single<? extends T> t2, Single<? extends T> t3, Single<? extends T> 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 particularScheduler
.
- Type Parameters:
T
- the common value type- Parameters:
t1
- a Single to be concatenatedt2
- a Single to be concatenatedt3
- a Single to be concatenatedt4
- a Single to be concatenated- Returns:
- an Observable that emits items emitted by the four source Singles, one after the other.
- See Also:
-
concat
public static <T> Observable<T> concat(Single<? extends T> t1, Single<? extends T> t2, Single<? extends T> t3, Single<? extends T> t4, Single<? extends T> 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 particularScheduler
.
- Type Parameters:
T
- the common value type- Parameters:
t1
- a Single to be concatenatedt2
- a Single to be concatenatedt3
- a Single to be concatenatedt4
- a Single to be concatenatedt5
- a Single to be concatenated- Returns:
- an Observable that emits items emitted by the five source Singles, one after the other.
- See Also:
-
concat
public static <T> Observable<T> concat(Single<? extends T> t1, Single<? extends T> t2, Single<? extends T> t3, Single<? extends T> t4, Single<? extends T> t5, Single<? extends T> 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 particularScheduler
.
- Type Parameters:
T
- the common value type- Parameters:
t1
- a Single to be concatenatedt2
- a Single to be concatenatedt3
- a Single to be concatenatedt4
- a Single to be concatenatedt5
- a Single to be concatenatedt6
- a Single to be concatenated- Returns:
- an Observable that emits items emitted by the six source Singles, one after the other.
- See Also:
-
concat
public static <T> Observable<T> concat(Single<? extends T> t1, Single<? extends T> t2, Single<? extends T> t3, Single<? extends T> t4, Single<? extends T> t5, Single<? extends T> t6, Single<? extends T> 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 particularScheduler
.
- Type Parameters:
T
- the common value type- Parameters:
t1
- a Single to be concatenatedt2
- a Single to be concatenatedt3
- a Single to be concatenatedt4
- a Single to be concatenatedt5
- a Single to be concatenatedt6
- a Single to be concatenatedt7
- a Single to be concatenated- Returns:
- an Observable that emits items emitted by the seven source Singles, one after the other.
- See Also:
-
concat
public static <T> Observable<T> concat(Single<? extends T> t1, Single<? extends T> t2, Single<? extends T> t3, Single<? extends T> t4, Single<? extends T> t5, Single<? extends T> t6, Single<? extends T> t7, Single<? extends T> 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 particularScheduler
.
- Type Parameters:
T
- the common value type- Parameters:
t1
- a Single to be concatenatedt2
- a Single to be concatenatedt3
- a Single to be concatenatedt4
- a Single to be concatenatedt5
- a Single to be concatenatedt6
- a Single to be concatenatedt7
- a Single to be concatenatedt8
- a Single to be concatenated- Returns:
- an Observable that emits items emitted by the eight source Singles, one after the other.
- See Also:
-
concat
public static <T> Observable<T> concat(Single<? extends T> t1, Single<? extends T> t2, Single<? extends T> t3, Single<? extends T> t4, Single<? extends T> t5, Single<? extends T> t6, Single<? extends T> t7, Single<? extends T> t8, Single<? extends T> 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 particularScheduler
.
- Type Parameters:
T
- the common value type- Parameters:
t1
- a Single to be concatenatedt2
- a Single to be concatenatedt3
- a Single to be concatenatedt4
- a Single to be concatenatedt5
- a Single to be concatenatedt6
- a Single to be concatenatedt7
- a Single to be concatenatedt8
- a Single to be concatenatedt9
- a Single to be concatenated- Returns:
- an Observable that emits items emitted by the nine source Singles, one after the other.
- See Also:
-
error
-
from
Converts aFuture
into aSingle
.You can convert any object that supports the
Future
interface into a Single that emits the return value of theFuture.get()
method of that object, by passing the object into thefrom
method.Important note: This Single is blocking; you cannot unsubscribe from it.
- Scheduler:
from
does not operate by default on a particularScheduler
.
-
from
Converts aFuture
into aSingle
, with a timeout on the Future.You can convert any object that supports the
Future
interface into aSingle
that emits the return value of theFuture.get()
method of that object, by passing the object into thefrom
method.Important note: This
Single
is blocking; you cannot unsubscribe from it.- Scheduler:
from
does not operate by default on a particularScheduler
.
- Type Parameters:
T
- the type of object that theFuture
returns, and also the type of item to be emitted by the resultingSingle
- Parameters:
future
- the sourceFuture
timeout
- the maximum time to wait before callingget
unit
- theTimeUnit
of thetimeout
argument- Returns:
- a
Single
that emits the item from the sourceFuture
- See Also:
-
from
Converts aFuture
, operating on a specifiedScheduler
, into aSingle
.You can convert any object that supports the
Future
interface into aSingle
that emits the return value of theFuture.get()
method of that object, by passing the object into thefrom
method.- Scheduler:
- you specify which
Scheduler
this operator will use
- Type Parameters:
T
- the type of object that theFuture
returns, and also the type of item to be emitted by the resultingSingle
- Parameters:
future
- the sourceFuture
scheduler
- theScheduler
to wait for the Future on. Use a Scheduler such asSchedulers.io()
that can block and wait on the Future- Returns:
- a
Single
that emits the item from the sourceFuture
- See Also:
-
fromCallable
Returns aSingle
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 theSingle
.- Scheduler:
fromCallable
does not operate by default on a particularScheduler
.
-
just
Returns aSingle
that emits a specified item.To convert any object into a
Single
that emits that object, pass that object into thejust
method.- Scheduler:
just
does not operate by default on a particularScheduler
.
- Type Parameters:
T
- the type of that item- Parameters:
value
- the item to emit- Returns:
- a
Single
that emitsvalue
- See Also:
-
merge
Flattens aSingle
that emits aSingle
into a singleSingle
that emits the item emitted by the nestedSingle
, without any transformation.- Scheduler:
merge
does not operate by default on a particularScheduler
.
- Type Parameters:
T
- the value type of the sources and the output- Parameters:
source
- aSingle
that emits aSingle
- Returns:
- a
Single
that emits the item that is the result of flattening theSingle
emitted bysource
- See Also:
-
merge
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 particularScheduler
.
- Type Parameters:
T
- the common value type- Parameters:
t1
- a Single to be mergedt2
- a Single to be merged- Returns:
- an Observable that emits all of the items emitted by the source Singles
- See Also:
-
merge
public static <T> Observable<T> merge(Single<? extends T> t1, Single<? extends T> t2, Single<? extends T> 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 particularScheduler
.
- Type Parameters:
T
- the common value type- Parameters:
t1
- a Single to be mergedt2
- a Single to be mergedt3
- a Single to be merged- Returns:
- an Observable that emits all of the items emitted by the source Singles
- See Also:
-
merge
public static <T> Observable<T> merge(Single<? extends T> t1, Single<? extends T> t2, Single<? extends T> t3, Single<? extends T> 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 particularScheduler
.
- Type Parameters:
T
- the common value type- Parameters:
t1
- a Single to be mergedt2
- a Single to be mergedt3
- a Single to be mergedt4
- a Single to be merged- Returns:
- an Observable that emits all of the items emitted by the source Singles
- See Also:
-
merge
public static <T> Observable<T> merge(Single<? extends T> t1, Single<? extends T> t2, Single<? extends T> t3, Single<? extends T> t4, Single<? extends T> 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 particularScheduler
.
- Type Parameters:
T
- the common value type- Parameters:
t1
- a Single to be mergedt2
- a Single to be mergedt3
- a Single to be mergedt4
- a Single to be mergedt5
- a Single to be merged- Returns:
- an Observable that emits all of the items emitted by the source Singles
- See Also:
-
merge
public static <T> Observable<T> merge(Single<? extends T> t1, Single<? extends T> t2, Single<? extends T> t3, Single<? extends T> t4, Single<? extends T> t5, Single<? extends T> 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 particularScheduler
.
- Type Parameters:
T
- the common value type- Parameters:
t1
- a Single to be mergedt2
- a Single to be mergedt3
- a Single to be mergedt4
- a Single to be mergedt5
- a Single to be mergedt6
- a Single to be merged- Returns:
- an Observable that emits all of the items emitted by the source Singles
- See Also:
-
merge
public static <T> Observable<T> merge(Single<? extends T> t1, Single<? extends T> t2, Single<? extends T> t3, Single<? extends T> t4, Single<? extends T> t5, Single<? extends T> t6, Single<? extends T> 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 particularScheduler
.
- Type Parameters:
T
- the common value type- Parameters:
t1
- a Single to be mergedt2
- a Single to be mergedt3
- a Single to be mergedt4
- a Single to be mergedt5
- a Single to be mergedt6
- a Single to be mergedt7
- a Single to be merged- Returns:
- an Observable that emits all of the items emitted by the source Singles
- See Also:
-
merge
public static <T> Observable<T> merge(Single<? extends T> t1, Single<? extends T> t2, Single<? extends T> t3, Single<? extends T> t4, Single<? extends T> t5, Single<? extends T> t6, Single<? extends T> t7, Single<? extends T> 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 particularScheduler
.
- Type Parameters:
T
- the common value type- Parameters:
t1
- a Single to be mergedt2
- a Single to be mergedt3
- a Single to be mergedt4
- a Single to be mergedt5
- a Single to be mergedt6
- a Single to be mergedt7
- a Single to be mergedt8
- a Single to be merged- Returns:
- an Observable that emits all of the items emitted by the source Singles
- See Also:
-
merge
public static <T> Observable<T> merge(Single<? extends T> t1, Single<? extends T> t2, Single<? extends T> t3, Single<? extends T> t4, Single<? extends T> t5, Single<? extends T> t6, Single<? extends T> t7, Single<? extends T> t8, Single<? extends T> 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 particularScheduler
.
- Type Parameters:
T
- the common value type- Parameters:
t1
- a Single to be mergedt2
- a Single to be mergedt3
- a Single to be mergedt4
- a Single to be mergedt5
- a Single to be mergedt6
- a Single to be mergedt7
- a Single to be mergedt8
- a Single to be mergedt9
- a Single to be merged- Returns:
- an Observable that emits all of the items emitted by the source Singles
- See Also:
-
zip
public static <T1,T2, Single<R> zipR> (Single<? extends T1> s1, Single<? extends T2> s2, Func2<? super T1, ? super T2, ? extends R> 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 particularScheduler
.
- Type Parameters:
T1
- the first source Single's value typeT2
- the second source Single's value typeR
- the result value type- Parameters:
s1
- the first source Singles2
- a second source SinglezipFunction
- 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:
-
zip
public static <T1,T2, Single<R> zipT3, R> (Single<? extends T1> s1, Single<? extends T2> s2, Single<? extends T3> s3, Func3<? super T1, ? super T2, ? super T3, ? extends R> 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 particularScheduler
.
- Type Parameters:
T1
- the first source Single's value typeT2
- the second source Single's value typeT3
- the third source Single's value typeR
- the result value type- Parameters:
s1
- the first source Singles2
- a second source Singles3
- a third source SinglezipFunction
- 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:
-
zip
public static <T1,T2, Single<R> zipT3, T4, R> (Single<? extends T1> s1, Single<? extends T2> s2, Single<? extends T3> s3, Single<? extends T4> s4, Func4<? super T1, ? super T2, ? super T3, ? super T4, ? extends R> 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 particularScheduler
.
- Type Parameters:
T1
- the first source Single's value typeT2
- the second source Single's value typeT3
- the third source Single's value typeT4
- the fourth source Single's value typeR
- the result value type- Parameters:
s1
- the first source Singles2
- a second source Singles3
- a third source Singles4
- a fourth source SinglezipFunction
- 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:
-
zip
public static <T1,T2, Single<R> zipT3, T4, T5, R> (Single<? extends T1> s1, Single<? extends T2> s2, Single<? extends T3> s3, Single<? extends T4> s4, Single<? extends T5> s5, Func5<? super T1, ? super T2, ? super T3, ? super T4, ? super T5, ? extends R> 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 particularScheduler
.
- Type Parameters:
T1
- the first source Single's value typeT2
- the second source Single's value typeT3
- the third source Single's value typeT4
- the fourth source Single's value typeT5
- the fifth source Single's value typeR
- the result value type- Parameters:
s1
- the first source Singles2
- a second source Singles3
- a third source Singles4
- a fourth source Singles5
- a fifth source SinglezipFunction
- 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:
-
zip
public static <T1,T2, Single<R> zipT3, T4, T5, T6, R> (Single<? extends T1> s1, Single<? extends T2> s2, Single<? extends T3> s3, Single<? extends T4> s4, Single<? extends T5> s5, Single<? extends T6> s6, Func6<? super T1, ? super T2, ? super T3, ? super T4, ? super T5, ? super T6, ? extends R> 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 particularScheduler
.
- Type Parameters:
T1
- the first source Single's value typeT2
- the second source Single's value typeT3
- the third source Single's value typeT4
- the fourth source Single's value typeT5
- the fifth source Single's value typeT6
- the sixth source Single's value typeR
- the result value type- Parameters:
s1
- the first source Singles2
- a second source Singles3
- a third source Singles4
- a fourth source Singles5
- a fifth source Singles6
- a sixth source SinglezipFunction
- 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:
-
zip
public static <T1,T2, Single<R> zipT3, T4, T5, T6, T7, R> (Single<? extends T1> s1, Single<? extends T2> s2, Single<? extends T3> s3, Single<? extends T4> s4, Single<? extends T5> s5, Single<? extends T6> s6, Single<? extends T7> s7, Func7<? super T1, ? super T2, ? super T3, ? super T4, ? super T5, ? super T6, ? super T7, ? extends R> 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 particularScheduler
.
- Type Parameters:
T1
- the first source Single's value typeT2
- the second source Single's value typeT3
- the third source Single's value typeT4
- the fourth source Single's value typeT5
- the fifth source Single's value typeT6
- the sixth source Single's value typeT7
- the seventh source Single's value typeR
- the result value type- Parameters:
s1
- the first source Singles2
- a second source Singles3
- a third source Singles4
- a fourth source Singles5
- a fifth source Singles6
- a sixth source Singles7
- a seventh source SinglezipFunction
- 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:
-
zip
public static <T1,T2, Single<R> zipT3, T4, T5, T6, T7, T8, R> (Single<? extends T1> s1, Single<? extends T2> s2, Single<? extends T3> s3, Single<? extends T4> s4, Single<? extends T5> s5, Single<? extends T6> s6, Single<? extends T7> s7, Single<? extends T8> s8, Func8<? super T1, ? super T2, ? super T3, ? super T4, ? super T5, ? super T6, ? super T7, ? super T8, ? extends R> 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 particularScheduler
.
- Type Parameters:
T1
- the first source Single's value typeT2
- the second source Single's value typeT3
- the third source Single's value typeT4
- the fourth source Single's value typeT5
- the fifth source Single's value typeT6
- the sixth source Single's value typeT7
- the seventh source Single's value typeT8
- the eigth source Single's value typeR
- the result value type- Parameters:
s1
- the first source Singles2
- a second source Singles3
- a third source Singles4
- a fourth source Singles5
- a fifth source Singles6
- a sixth source Singles7
- a seventh source Singles8
- an eighth source SinglezipFunction
- 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:
-
zip
public static <T1,T2, Single<R> zipT3, T4, T5, T6, T7, T8, T9, R> (Single<? extends T1> s1, Single<? extends T2> s2, Single<? extends T3> s3, Single<? extends T4> s4, Single<? extends T5> s5, Single<? extends T6> s6, Single<? extends T7> s7, Single<? extends T8> s8, Single<? extends T9> s9, Func9<? super T1, ? super T2, ? super T3, ? super T4, ? super T5, ? super T6, ? super T7, ? super T8, ? super T9, ? extends R> 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 particularScheduler
.
- Type Parameters:
T1
- the first source Single's value typeT2
- the second source Single's value typeT3
- the third source Single's value typeT4
- the fourth source Single's value typeT5
- the fifth source Single's value typeT6
- the sixth source Single's value typeT7
- the seventh source Single's value typeT8
- the eigth source Single's value typeT9
- the ninth source Single's value typeR
- the result value type- Parameters:
s1
- the first source Singles2
- a second source Singles3
- a third source Singles4
- a fourth source Singles5
- a fifth source Singles6
- a sixth source Singles7
- a seventh source Singles8
- an eighth source Singles9
- a ninth source SinglezipFunction
- 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:
-
zip
public static <R> Single<R> zip(Iterable<? extends Single<?>> singles, FuncN<? extends R> 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 particularScheduler
.
- Type Parameters:
R
- the result value type- Parameters:
singles
- an Iterable of source Singles. Should not be empty becauseSingle
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:
-
concatWith
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 particularScheduler
.
- 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:
-
flatMap
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 particularScheduler
.
- 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:
-
flatMapObservable
public final <R> Observable<R> flatMapObservable(Func1<? super T, ? extends Observable<? extends R>> 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 particularScheduler
.
- 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:
-
map
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 particularScheduler
.
- 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:
-
mergeWith
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 particularScheduler
.
- Parameters:
t1
- a Single to be merged- Returns:
- an Observable that emits all of the items emitted by the source Singles
- See Also:
-
observeOn
-
onErrorReturn
Instructs a Single to emit an item (returned by a specified function) rather than invokingonError
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. TheonErrorReturn
method changes this behavior. If you pass a function (resumeFunction
) to a Single'sonErrorReturn
method, if the original Single encounters an error, instead of invoking its subscriber'sObserver.onError(java.lang.Throwable)
method, it will instead emit the return value ofresumeFunction
.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 particularScheduler
.
- 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:
-
onErrorResumeNext
@Experimental public final Single<T> onErrorResumeNext(Single<? extends T> resumeSingleInCaseOfError) Instructs a Single to pass control to another Single rather than invokingObserver.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'sonError
method, and then quits without invoking any more of its Observer's methods. TheonErrorResumeNext
method changes this behavior. If you pass another Single (resumeSingleInCaseOfError
) to an Single'sonErrorResumeNext
method, if the original Single encounters an error, instead of invoking its Observer'sonError
method, it will instead relinquish control toresumeSingleInCaseOfError
which will invoke the Observer'sonNext
method if it is able to do so. In such a case, because no Single necessarily invokesonError
, 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 particularScheduler
.
- Parameters:
resumeSingleInCaseOfError
- a Single that will take control if source Single encounters an error.- Returns:
- the original Single, with appropriately modified behavior.
- Since:
- (if this graduates from Experimental/Beta to supported, replace this parenthetical with the release number)
- See Also:
-
onErrorResumeNext
@Experimental public final Single<T> onErrorResumeNext(Func1<Throwable, ? extends Single<? extends T>> resumeFunctionInCaseOfError) Instructs a Single to pass control to another Single rather than invokingObserver.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'sonError
method, and then quits without invoking any more of its Observer's methods. TheonErrorResumeNext
method changes this behavior. If you pass a function that will return another Single (resumeFunctionInCaseOfError
) to an Single'sonErrorResumeNext
method, if the original Single encounters an error, instead of invoking its Observer'sonError
method, it will instead relinquish control toresumeSingleInCaseOfError
which will invoke the Observer'sonNext
method if it is able to do so. In such a case, because no Single necessarily invokesonError
, 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 particularScheduler
.
- 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:
- (if this graduates from Experimental/Beta to supported, replace this parenthetical with the release number)
- See Also:
-
subscribe
Subscribes to a Single but ignore its emission or notification.- Scheduler:
subscribe
does not operate by default on a particularScheduler
.
- Returns:
- a
Subscription
reference can request theSingle
stop work. - Throws:
OnErrorNotImplementedException
- if the Single tries to callObserver.onError(java.lang.Throwable)
- See Also:
-
subscribe
Subscribes to a Single and provides a callback to handle the item it emits.- Scheduler:
subscribe
does not operate by default on a particularScheduler
.
- Parameters:
onSuccess
- theAction1<T>
you have designed to accept the emission from the Single- Returns:
- a
Subscription
reference can request theSingle
stop work. - Throws:
IllegalArgumentException
- ifonNext
is nullOnErrorNotImplementedException
- if the Single tries to callObserver.onError(java.lang.Throwable)
- See Also:
-
subscribe
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 particularScheduler
.
- Parameters:
onSuccess
- theAction1<T>
you have designed to accept the emission from the SingleonError
- theAction1<Throwable>
you have designed to accept any error notification from the Single- Returns:
- a
Subscription
reference can request theSingle
stop work. - Throws:
IllegalArgumentException
- ifonNext
is null, or ifonError
is null- See Also:
-
unsafeSubscribe
Subscribes to a Single and invokes theSingle.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, usesubscribe(Subscriber)
which ensures the Rx contract and other functionality.- Scheduler:
unsafeSubscribe
does not operate by default on a particularScheduler
.
- Parameters:
subscriber
- the Subscriber that will handle the emission or notification from the Single- Returns:
- the subscription that allows unsubscribing
-
subscribe
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
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:- It stores a reference to the Subscriber in a collection object, such as a
List<T>
object. - 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<T>
instance is responsible for accepting all subscriptions and notifying all Subscribers. Unless the documentation for a particularSingle<T>
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 particularScheduler
.
- Parameters:
subscriber
- theSubscriber
that will handle the emission or notification from the Single- Returns:
- a
Subscription
reference can request theSingle
stop work. - Throws:
IllegalStateException
- ifsubscribe
is unable to obtain anOnSubscribe<>
functionIllegalArgumentException
- if theSubscriber
provided as the argument tosubscribe
isnull
OnErrorNotImplementedException
- if theSubscriber
'sonError
method is nullRuntimeException
- if theSubscriber
'sonError
method itself threw aThrowable
- See Also:
- It stores a reference to the Subscriber in a collection object, such as a
-
subscribe
Subscribes to a Single and provides aSingleSubscriber
that implements functions to handle the item the Single emits or any error notification it issues.A typical implementation of
subscribe
does the following:- It stores a reference to the Subscriber in a collection object, such as a
List<T>
object. - 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<T>
instance is responsible for accepting all subscriptions and notifying all Subscribers. Unless the documentation for a particularSingle<T>
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 particularScheduler
.
- Parameters:
te
- theSingleSubscriber
that will handle the emission or notification from the Single- Returns:
- a
Subscription
reference can request theSingle
stop work. - Throws:
IllegalStateException
- ifsubscribe
is unable to obtain anOnSubscribe<>
functionIllegalArgumentException
- if theSingleSubscriber
provided as the argument tosubscribe
isnull
OnErrorNotImplementedException
- if theSingleSubscriber
'sonError
method is nullRuntimeException
- if theSingleSubscriber
'sonError
method itself threw aThrowable
- See Also:
- It stores a reference to the Subscriber in a collection object, such as a
-
subscribeOn
-
takeUntil
Returns a Single that emits the item emitted by the source Single until a Completable terminates. Upon termination ofother
, this will emit aCancellationException
rather than go toSingleSubscriber.onSuccess(Object)
.- Scheduler:
takeUntil
does not operate by default on a particularScheduler
.
- Parameters:
other
- the Completable whose termination will causetakeUntil
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:
-
takeUntil
Returns a Single that emits the item emitted by the source Single until an Observable emits an item. Upon emission of an item fromother
, this will emit aCancellationException
rather than go toSingleSubscriber.onSuccess(Object)
.- Scheduler:
takeUntil
does not operate by default on a particularScheduler
.
- Type Parameters:
E
- the type of items emitted byother
- Parameters:
other
- the Observable whose first emitted item will causetakeUntil
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:
-
takeUntil
Returns a Single that emits the item emitted by the source Single until a second Single emits an item. Upon emission of an item fromother
, this will emit aCancellationException
rather than go toSingleSubscriber.onSuccess(Object)
.- Scheduler:
takeUntil
does not operate by default on a particularScheduler
.
- Type Parameters:
E
- the type of item emitted byother
- Parameters:
other
- the Single whose emitted item will causetakeUntil
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:
-
toObservable
Converts this Single into anObservable
.- Returns:
- an
Observable
that emits a single item T.
-
toCompletable
Returns aCompletable
that discards result of theSingle
(similar toObservable.ignoreElements()
) and callsonCompleted
when this sourceSingle
callsonSuccess
. Error terminal event is propagated.- Scheduler:
toCompletable
does not operate by default on a particularScheduler
.
- Returns:
- a
Completable
that callsonCompleted
on it's subscriber when the sourceSingle
callsonSuccess
. - Since:
- (if this graduates from Experimental/Beta to supported, replace this parenthetical with the release number).
- See Also:
-
timeout
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 aTimeoutException
.- Scheduler:
- This version of
timeout
operates by default on thecomputation
Scheduler
.
- Parameters:
timeout
- maximum duration before the Single times outtimeUnit
- the unit of time that applies to thetimeout
argument.- Returns:
- the source Single modified to notify subscribers of a
TimeoutException
in case of a timeout - See Also:
-
timeout
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 aTimeoutException
.- Scheduler:
- you specify which
Scheduler
this operator will use
- Parameters:
timeout
- maximum duration before the Single times outtimeUnit
- the unit of time that applies to thetimeout
argumentscheduler
- 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:
-
timeout
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 thecomputation
Scheduler
.
- Parameters:
timeout
- maximum time before a timeout occurstimeUnit
- the unit of time that applies to thetimeout
argumentother
- 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:
-
timeout
public final Single<T> timeout(long timeout, TimeUnit timeUnit, Single<? extends T> 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 occurstimeUnit
- the unit of time that applies to thetimeout
argumentother
- the Single to use as the fallback in case of a timeoutscheduler
- theScheduler
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:
-
toBlocking
Converts a Single into aBlockingSingle
(a Single with blocking operators).- Scheduler:
toBlocking
does not operate by default on a particularScheduler
.
- Returns:
- a
BlockingSingle
version of this Single. - See Also:
-
zipWith
public final <T2,R> Single<R> zipWith(Single<? extends T2> other, Func2<? super T, ? 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 particularScheduler
.
- Type Parameters:
T2
- the type of items emitted by theother
SingleR
- the type of items emitted by the resulting Single- Parameters:
other
- the other ObservablezipFunction
- 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 ofzipFunction
applied to these pairs - See Also:
-
doOnError
Modifies the sourceSingle
so that it invokes an action if it callsonError
.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 particularScheduler
.
-
doOnSuccess
-
doOnSubscribe
Modifies the sourceSingle
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 sourceSingle
is reference counted, in which case the sourceSingle
will invoke the given action for the first subscription.- Scheduler:
doOnSubscribe
does not operate by default on a particularScheduler
.
- Parameters:
subscribe
- the action that gets called when an observer subscribes to thisSingle
- Returns:
- the source
Single
modified so as to call this Action when appropriate - See Also:
-
delay
Returns an 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 byunit
- the time unit ofdelay
scheduler
- theScheduler
to use for delaying- Returns:
- the source Single shifted in time by the specified delay
- See Also:
-
delay
Returns an 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 thecomputation
Scheduler
.
- Parameters:
delay
- the delay to shift the source byunit
- theTimeUnit
in whichperiod
is defined- Returns:
- the source Single shifted in time by the specified delay
- See Also:
-
defer
Returns aSingle
that calls aSingle
factory to create aSingle
for each new Observer that subscribes. That is, for each subscriber, the actualSingle
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 theSingle
. This allows anObserver
to easily obtain updates or a refreshed version of the sequence.- Scheduler:
defer
does not operate by default on a particularScheduler
.
- Type Parameters:
T
- the type of the items emitted by theSingle
.- Parameters:
singleFactory
- theSingle
factory function to invoke for eachObserver
that subscribes to the resultingSingle
.- Returns:
- a
Single
whoseObserver
s' subscriptions trigger an invocation of the givenSingle
factory function. - See Also:
-
doOnUnsubscribe
-
doAfterTerminate
Registers anAction0
to be called when thisSingle
invokes eitherSingleSubscriber.onSuccess(Object)
onSuccess} oronError
.- Scheduler:
doAfterTerminate
does not operate by default on a particularScheduler
.
-
iterableToArray
-
retry
Returns a Single that mirrors the source Single, resubscribing to it if it callsonError
(infinite retry count).If the source Single calls
SingleSubscriber.onError(java.lang.Throwable)
, this method will resubscribe to the source Single rather than propagating theonError
call.- Scheduler:
retry
operates by default on thetrampoline
Scheduler
.
- Returns:
- the source Single modified with retry logic
- See Also:
-
retry
Returns an Single that mirrors the source Single, resubscribing to it if it callsonError
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 ofcount
resubscriptions rather than propagating theonError
call.- Scheduler:
retry
operates by default on thetrampoline
Scheduler
.
- Parameters:
count
- number of retry attempts before failing- Returns:
- the source Single modified with retry logic
- See Also:
-
retry
Returns an Single that mirrors the source Single, resubscribing to it if it callsonError
and the predicate returns true for that specific exception and retry count.- Backpressure Support:
- This operator honors backpressure.
- Scheduler:
retry
operates by default on thetrampoline
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:
-
retryWhen
public final Single<T> retryWhen(Func1<Observable<? extends Throwable>, ? extends Observable<?>> notificationHandler) Returns a Single that emits the same values as the source Single with the exception of anonError
. AnonError
notification from the source will result in the emission of aThrowable
item to the Observable provided as an argument to thenotificationHandler
function.Emissions from the handler
Observable
is treated as follows:- If the handler
Observable
emits anonCompleted
theretryWhen
will callonError
withNoSuchElementException
on the child subscription. - If the handler
Observable
emits anonError
theretryWhen
will callonError
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 expects an emission of the exception to be matched by an event from the handler Observable.- Scheduler:
retryWhen
operates by default on thetrampoline
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:
- If the handler
-
using
@Experimental public static <T,Resource> Single<T> using(Func0<Resource> resourceFactory, Func1<? super Resource, ? extends Single<? extends T>> singleFactory, Action1<? super Resource> disposeAction) Constructs an Single that creates a dependent resource object which is disposed of on unsubscription.- Scheduler:
using
does not operate by default on a particularScheduler
.
- Type Parameters:
T
- the value type of the generated sourceResource
- the type of the per-subscriber resource- Parameters:
resourceFactory
- the factory function to create a resource object that depends on the SinglesingleFactory
- the factory function to create a SingledisposeAction
- the function that will dispose of the resource- Returns:
- the Single whose lifetime controls the lifetime of the dependent resource object
- See Also:
-
using
@Experimental public static <T,Resource> Single<T> using(Func0<Resource> resourceFactory, Func1<? super Resource, ? extends Single<? extends T>> singleFactory, Action1<? super Resource> disposeAction, boolean disposeEagerly) Constructs an Single that creates a dependent resource object which is disposed of just before termination if you have setdisposeEagerly
totrue
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 particularScheduler
.
- Type Parameters:
T
- the value type of the generated sourceResource
- the type of the per-subscriber resource- Parameters:
resourceFactory
- the factory function to create a resource object that depends on the SinglesingleFactory
- the factory function to create a SingledisposeAction
- the function that will dispose of the resourcedisposeEagerly
- iftrue
then disposal will happen either on unsubscription or just before emission of a terminal event (onComplete
oronError
).- Returns:
- the Single whose lifetime controls the lifetime of the dependent resource object
- Since:
- (if this graduates from Experimental/Beta to supported, replace this parenthetical with the release number)
- See Also:
-
delaySubscription
Returns a Single that delays the subscription to this Single until the Observable completes. In case theonError
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.
-