Interface Observer<T>

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<@NonNull T>
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(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:

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: