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: