Observer (RxJava Javadoc 3.1.10) (original) (raw)

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 theObservableSource may call the Observer's onNext(T) method any number of times to provide notifications. A well-behavedObservableSource will call an Observer's onComplete() method exactly once or the Observer'sonError(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 anull 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 globalRxJavaPlugins.onError(Throwable) handler or the current thread'sThread.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 fromonNext(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).