io.reactivex

Interface Observer

Type Parameters:

T - the type of item the Observer expects to observe

All Known Implementing Classes:

AsyncSubject, BehaviorSubject, DefaultObserver, DisposableObserver, PublishSubject, ReplaySubject, ResourceObserver, SafeObserver, SerializedObserver, Subject, TestObserver, UnicastSubject

public interface Observer

Provides a mechanism for receiving push-based notifications.

When an Observer is subscribed to an ObservableSource through the ObservableSource.subscribe(Observer) method, the ObservableSource calls onSubscribe(Disposable) with a Disposable that allows disposing the sequence at any time, then the ObservableSource may call the Observer's onNext(T) method any number of times to provide notifications. A well-behaved ObservableSource will call an Observer's onComplete() method exactly once or the Observer's onError(java.lang.Throwable) method exactly once.

Calling the Observer's method must happen in a serialized fashion, that is, they must not be invoked concurrently by multiple threads in an overlapping fashion and the invocation pattern must adhere to the following protocol:

    onSubscribe onNext* (onError | onComplete)?

Subscribing an Observer to multiple ObservableSources is not recommended. If such reuse happens, it is the duty of the Observer implementation to be ready to receive multiple calls to its methods and ensure proper concurrent behavior of its business logic.

Calling onSubscribe(Disposable), onNext(Object) or onError(Throwable) with a null argument is forbidden.

The implementations of the onXXX methods should avoid throwing runtime exceptions other than the following cases (see Rule 2.13 of the Reactive Streams specification):

• If the argument is null, the methods can throw a NullPointerException. Note though that RxJava prevents nulls to enter into the flow and thus there is generally no need to check for nulls in flows assembled from standard sources and intermediate operators.
• If there is a fatal error (such as VirtualMachineError).

Violating Rule 2.13 results in undefined flow behavior. Generally, the following can happen:

• An upstream operator turns it into an onError(java.lang.Throwable) call.
• If the flow is synchronous, the ObservableSource.subscribe(Observer) throws instead of returning normally.
• If the flow is asynchronous, the exception propagates up to the component (Scheduler or Executor) providing the asynchronous boundary the code is running and either routes the exception to the global RxJavaPlugins.onError(Throwable) handler or the current thread's Thread.UncaughtExceptionHandler.uncaughtException(Thread, Throwable) handler.

From the Observable's perspective, an Observer is the end consumer thus it is the Observer's responsibility to handle the error case and signal it "further down". This means unreliable code in the onXXX methods should be wrapped into `try-catch`es, specifically in onError(Throwable) or onComplete(), and handled there (for example, by logging it or presenting the user with an error dialog). However, if the error would be thrown from onNext(Object), Rule 2.13 mandates the implementation calls Disposable.dispose() and signals the exception in a way that is adequate to the target context, for example, by calling onError(Throwable) on the same Observer instance.

If, for some reason, the Observer won't follow Rule 2.13, the Observable.safeSubscribe(Observer) can wrap it with the necessary safeguards and route exceptions thrown from onNext into onError and route exceptions thrown from onError and onComplete into the global error handler via RxJavaPlugins.onError(Throwable).

See Also:

ReactiveX documentation: Observable

Method Summary

Modifier and Type	Method and Description
void	onComplete() Notifies the Observer that the Observable has finished sending push-based notifications.
void	onError(Throwable e) Notifies the Observer that the Observable has experienced an error condition.
void	onNext(T t) Provides the Observer with a new item to observe.
void	onSubscribe(Disposable d) Provides the Observer with the means of cancelling (disposing) the connection (channel) with the Observable in both synchronous (from within onNext(Object)) and asynchronous manner.

Method Detail

onSubscribe

void onSubscribe(@NonNull
                 Disposable d)

Provides the Observer with the means of cancelling (disposing) the connection (channel) with the Observable in both synchronous (from within onNext(Object)) and asynchronous manner.

Parameters:

d - the Disposable instance whose Disposable.dispose() can be called anytime to cancel the connection

Since:

2.0

onNext

void onNext(@NonNull
            T t)

Provides the Observer with a new item to observe.

The Observable may call this method 0 or more times.

The Observable will not call this method again after it calls either onComplete() or onError(java.lang.Throwable).

Parameters:

t - the item emitted by the Observable

onError

void onError(@NonNull
             Throwable e)

Notifies the Observer that the Observable has experienced an error condition.

If the Observable calls this method, it will not thereafter call onNext(T) or onComplete().

Parameters:

e - the exception encountered by the Observable

onComplete

void onComplete()

Notifies the Observer that the Observable has finished sending push-based notifications.

The Observable will not call this method if it calls onError(java.lang.Throwable).