RxJava Ninja: Single, Maybe and Completable

“Single daisy blooms in a leafy green landscape” by Shane Rounce on Unsplash

This article is a part of the RxJava Ninja series. The complete list of the articles for this series can be found at the end of this article (and will be updated as more articles become available).

In this article, we will talk about special types of Observables. They still follow the observable contract but they are specialized for a specific purpose.

Single

Single is an observable that emits only a single item. The factory operators for Single is more or less similar with observables restricted to a single emission. The only noticeable difference is the observer definition. The SingleObserver class is defined below.

Notice that there is no more onNext and onComplete and a new notification onSuccess is defined. This makes sense because a Single only emits a single item, hence it can be interpreted as onNext and onComplete at the same time. Let’s see an example.

The example above creates a Single observable that emits hello. The onSuccess handler prints the item. The output will be

hello

Now, why is there a need to define a new type for this? Well, the answer lies on the communication of intention. Using Single can communicate, effectively I might add, the nature of the observable. For example, if you need to perform a one time network request, you can create it using Single and users of this observable does not need to look at the implementation details to know what to expect from this observable. Also, some operators just only return a single item so it is easier to express them this way. An example is the first operator which return the first item in the stream, a default value if there are no item in the observable source.

If there is a need for you to convert a Single to Observable, say for example you want to be notified on both onNext and onComplete, there is an operator just for that. You can use the toObservable. The opposite is also possible. singleOrError converts your Observable to a Single and if there are more than 1 item in the sequence, an exception will be thrown in the onError channel.

Maybe

Maybe is similar to Single but this time, it allows your observable the ability to not emit any item at all. The MaybeObserver is defined as follows.

There are 4 notifications again, the onComplete is back (to signify no items) and the onSuccess as a combination of onNext and onComplete.

The sample code above will output

onComplete
hello

The first one emits onComplete because no there is nothing to emit. The second one outputs the hello under the onSuccess channel and does not emit an onComplete after. Maybe is also used in many operators to also communicate intention. For example, the first operator requires you to pass a default value in case there is no item. But you can specify it as a Maybe since it can either be an observable with a single item, or no items at all. This is what firstElement does.

Same with Single, Maybe can also be converted to Observable via the toObservable operator. Unfortunately, there is no straightforward way to convert an Observable to Maybe (unless you are interested in just the firstElement). You can convert it to Single first though and then to Maybe using toMaybe.

Completable

This observable is only concerned about two things, if some action is executed or an error is encountered. Let’s check the definition of its observer.

There are only 2 events, onComplete and onError. This is useful for cases wherein you are only interested if something has executed properly, ignoring output or whatever.

Like the two above, Completable can be converted to an observable using toObservable. However, the reverse is also not straightforward. You can convert to a Single first and use ignoreElement, though if you want (toCompletable is deprecated).

That’s it for special observables. Next, we will discuss hot vs. cold observables.

1. Introduction to Reactive Programming
2. Building your first Observables and Observers
3. In Depth Observables and Observers
4. Marble Diagrams and Operators
5. Observable Factories Part 1
6. Observable Factories Part 2
7. Single, Maybe and Completable
8. Hot and Cold Observables
9. Filtering Operators Part 1
10. Filtering Operators Part 2