Error Handling Operators

This section explains operators that handle errors and exceptions encountered by Observables.

• onErrorResumeNext( ) — instructs an Observable to continue emitting items after it encounters an error
• onErrorReturn( ) — instructs an Observable to emit a particular item when it encounters an error
• onExceptionResumeNext( ) — instructs an Observable to continue emitting items after it encounters an exception (but not another variety of throwable)
• retry( ) — if a source Observable emits an error, resubscribe to it in the hopes that it will complete without error

---

onErrorResumeNext( )

instructs an Observable to attempt to continue emitting items after it encounters an error

The onErrorResumeNext( ) method returns an Observable that mirrors the behavior of the source Observable, unless that Observable invokes onError( ) in which case, rather than propagating that error to the Subscriber, onErrorResumeNext( ) will instead begin mirroring a second, backup Observable, as shown in the following sample code:

def myObservable = Observable.create({ aSubscriber ->
  if(false == aSubscriber.isUnsubscribed()) aSubscriber.onNext('Three');
  if(false == aSubscriber.isUnsubscribed()) aSubscriber.onNext('Two');
  if(false == aSubscriber.isUnsubscribed()) aSubscriber.onNext('One');
  if(false == aSubscriber.isUnsubscribed()) aSubscriber.onError();
});
def myFallback = Observable.create({ aSubscriber ->
  if(false == aSubscriber.isUnsubscribed()) aSubscriber.onNext('0');
  if(false == aSubscriber.isUnsubscribed()) aSubscriber.onNext('1');
  if(false == aSubscriber.isUnsubscribed()) aSubscriber.onNext('2');
  if(false == aSubscriber.isUnsubscribed()) aSubscriber.onCompleted();
});

myObservable.onErrorResumeNext(myFallback).subscribe(
  { println(it); },                          // onNext
  { println("Error: " + it.getMessage()); }, // onError
  { println("Sequence complete"); }          // onCompleted
);

Three
Two
One
0
1
2
Sequence complete

see also:

• javadoc: onErrorResumeNext(throwable,function)
• javadoc: onErrorResumeNext(sequence)
• RxJS: onErrorResumeNext
• Linq: OnErrorResumeNext
• Introduction to Rx: OnErrorResumeNext

---

onErrorReturn( )

instructs an Observable to emit a particular item to a Subscriber’s onNext method when it encounters an error

The onErrorReturn( ) method returns an Observable that mirrors the behavior of the source Observable, unless that Observable invokes onError( ) in which case, rather than propagating that error to the Subscriber, onErrorReturn( ) will instead emit a specified item and invoke the Subscriber's onCompleted( ) method, as shown in the following sample code:

def myObservable = Observable.create({ aSubscriber ->
  if(false == aSubscriber.isUnsubscribed()) aSubscriber.onNext('Four');
  if(false == aSubscriber.isUnsubscribed()) aSubscriber.onNext('Three');
  if(false == aSubscriber.isUnsubscribed()) aSubscriber.onNext('Two');
  if(false == aSubscriber.isUnsubscribed()) aSubscriber.onNext('One');
  if(false == aSubscriber.isUnsubscribed()) aSubscriber.onError();
});

myObservable.onErrorReturn({ return('Blastoff!'); }).subscribe(
  { println(it); },                          // onNext
  { println("Error: " + it.getMessage()); }, // onError
  { println("Sequence complete"); }          // onCompleted
);

Four
Three
Two
One
Blastoff!
Sequence complete

see also:

• javadoc: onErrorReturn(func)

---

onExceptionResumeNext( )

instructs an Observable to continue emitting items after it encounters an exception (but not another variety of throwable)

Much like onErrorResumeNext( ) method, this returns an Observable that mirrors the behavior of the source Observable, unless that Observable invokes onError( ) in which case, if the Throwable passed to onError( ) is an Exception, rather than propagating that Exception to the Subscriber, onExceptionResumeNext( ) will instead begin mirroring a second, backup Observable. If the Throwable is not an Exception, the Observable returned by onExceptionResumeNext( ) will propagate it to its Subscriber's onError( ) method and will not invoke its backup Observable.

see also:

• javadoc: onExceptionResumeNext(observable)

---

retry( )

if a source Observable emits an error, resubscribe to it in the hopes that it will complete without error

The retry( ) method responds to an onError( ) call from the source Observable by not passing that call through to its Subscribers, but instead resubscribing to the source Observable and giving it another opportunity to complete its sequence without error. You can pass retry( ) a maximum number of retry-attempts, or you can pass nothing, in which case it will never stop retrying to get an error-free sequence. It always passes onNext( ) calls through to its Subscribers, even from sequences that terminate with an error, so this can cause duplicate emissions (as shown in the diagram above).

see also:

• javadoc: retry()
• javadoc: retry(count)
• RxJS: retry
• Linq: Retry
• Introduction to Rx: Retry