Single

RxJava (and its derivatives like RxGroovy & RxScala) has developed an Observable variant called “Single.”

A Single is something like an Observable, but instead of emitting a series of values — anywhere from none at all to an infinite number — it always either emits one value or an error notification.

For this reason, instead of subscribing to a Single with the three methods you use to respond to notifications from an Observable (onNext, onError, and onCompleted), you only use two methods to subscribe:

onSuccess

a Single passes this method the sole item that the Single emits

onError

a Single passes this method the Throwable that caused the Single to be unable to emit an item

A Single will call only one of these methods, and will only call it once. Upon calling either method, the Single terminates and the subscription to it ends.

Composition via Single Operators

Like Observables, Singles can be manipulated by means of a variety of operators. Some operators also allow for an interface between the Observable world and the Single world so that you can mix the two varieties:

operator	returns	description
compose	Single	allows you create a custom operator
concat and concatWith	Observable	concatenates the items emitted by multiple Singles as Observable emissions
create	Single	create a Single from scratch by calling subscriber methods explicitly
delay	Single	move the emission of an item from a Single forward in time
doOnError	Single	returns a Single that also calls a method you specify when it calls onError
doOnSuccess	Single	returns a Single that also calls a method you specify when it calls onSuccess
error	Single	returns a Single that immediately notifies subscribers of an error
flatMap	Single	returns a Single that is the result of a function applied to an item emitted by a Single
flatMapObservable	Observable	returns an Observable that is the result of a function applied to an item emitted by a Single
from	Single	converts a Future into a Single
just	Single	returns a Single that emits a specified item
map	Single	returns a Single that emits the result of a function applied to the item emitted by the source Single
merge	Single	converts a Single that emits a second Single into a Single that emits the item emitted by the second Single
merge and mergeWith	Observable	merges the items emitted by multiple Singles as Observable emissions
observeOn	Single	instructs the Single to call the subscriber methods on a particular Scheduler
onErrorReturn	Single	converts a Single that makes an error notification into a Single that emits a specified item
subscribeOn	Single	instructs the Single to operate on a particular Scheduler
timeout	Single	returns a Single that makes an error notification if the source Single does not emit a value in a specified time period
toSingle	Single	converts an Observable that emits a single item into a Single that emits that item
toObservable	Observable	converts a Single into an Observable that emits the item emitted by the Single and then completes
zip and zipWith	Single	returns a Single that emits an item that is the result of a function applied to items emitted by two or more other Singles

The following sections of this page will give marble diagrams that explain these operators schematically. This diagram explains how Singles are represented in marble diagrams:

compose

concat and concatWith

There is also an instance version of this operator:

create

delay

There is also a version of this operator that allows you to perform the delay on a particular Scheduler:

doOnError

doOnSuccess

error

flatMap

flatMapObservable

from

There is also a variety that takes a Scheduler as an argument:

just

map

merge and mergeWith

One version of merge takes a Single that emits a second Single and converts it into a Single that emits the item emitted by that second Single:

Another version takes two or more Singles and merges them into an Observable that emits the items emitted by the source Singles (in an arbitrary order):

observeOn

onErrorReturn

subscribeOn

timeout

Timeout will cause a Single to abort with an error notification if it does not emit an item in a specified period of time after it is subscribed to. One version allows you to set this time out by means of a number of specified time units:

You can also specify a particular Scheduler for the timer to operate on:

A version of the timeout operator allows you to switch to a backup Single rather than sending an error notification if the timeout expires:

This, too, has a Scheduler-specific version:

toObservable

zip and zipWith