Skip to content

Commit fba8b61

Browse files
lorenzpahlakarnokd
lorenzpahl
authored and
akarnokd
committed
2.x: Update Error Handling Operators docs (#6266)
* Change document structure; update operator list * Add examples * Clarify which handler is invoked * Use consistent wording in the descriptions * Cleanup
1 parent feb6db7 commit fba8b61

File tree

1 file changed

+277
-7
lines changed

1 file changed

+277
-7
lines changed

‎docs/Error-Handling-Operators.md

+277-7
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,284 @@
1-
There are a variety of operators that you can use to react to or recover from `onError` notifications from Observables. For example, you might:
1+
There are a variety of operators that you can use to react to or recover from `onError` notifications from reactive sources, such as `Observable`s. For example, you might:
22

33
1. swallow the error and switch over to a backup Observable to continue the sequence
44
1. swallow the error and emit a default item
55
1. swallow the error and immediately try to restart the failed Observable
66
1. swallow the error and try to restart the failed Observable after some back-off interval
77

8-
The following pages explain these operators.
8+
# Outline
99

10-
* [**`onErrorResumeNext( )`**](http://reactivex.io/documentation/operators/catch.html) — instructs an Observable to emit a sequence of items if it encounters an error
11-
* [**`onErrorReturn( )`**](http://reactivex.io/documentation/operators/catch.html) — instructs an Observable to emit a particular item when it encounters an error
12-
* [**`onExceptionResumeNext( )`**](http://reactivex.io/documentation/operators/catch.html) — instructs an Observable to continue emitting items after it encounters an exception (but not another variety of throwable)
13-
* [**`retry( )`**](http://reactivex.io/documentation/operators/retry.html) — if a source Observable emits an error, resubscribe to it in the hopes that it will complete without error
14-
* [**`retryWhen( )`**](http://reactivex.io/documentation/operators/retry.html) — if a source Observable emits an error, pass that error to another Observable to determine whether to resubscribe to the source
10+
- [`doOnError`](#doonerror)
11+
- [`onErrorComplete`](#onerrorcomplete)
12+
- [`onErrorResumeNext`](#onerrorresumenext)
13+
- [`onErrorReturn`](#onerrorreturn)
14+
- [`onErrorReturnItem`](#onerrorreturnitem)
15+
- [`onExceptionResumeNext`](#onexceptionresumenext)
16+
- [`retry`](#retry)
17+
- [`retryUntil`](#retryuntil)
18+
- [`retryWhen`](#retrywhen)
19+
20+
## doOnError
21+
22+
**Available in:** ![image](https://raw.github.com/wiki/ReactiveX/RxJava/images/checkmark_on.png) `Flowable`, ![image](https://raw.github.com/wiki/ReactiveX/RxJava/images/checkmark_on.png) `Observable`, ![image](https://raw.github.com/wiki/ReactiveX/RxJava/images/checkmark_on.png) `Maybe`, ![image](https://raw.github.com/wiki/ReactiveX/RxJava/images/checkmark_on.png) `Single`, ![image](https://raw.github.com/wiki/ReactiveX/RxJava/images/checkmark_on.png) `Completable`
23+
24+
**ReactiveX documentation:** [http://reactivex.io/documentation/operators/do.html](http://reactivex.io/documentation/operators/do.html)
25+
26+
Instructs a reactive type to invoke the given `io.reactivex.functions.Consumer` when it encounters an error.
27+
28+
### doOnError example
29+
30+
```java
31+
Observable.error(new IOException("Something went wrong"))
32+
.doOnError(error -> System.err.println("The error message is: " + error.getMessage()))
33+
.subscribe(
34+
x -> System.out.println("onNext should never be printed!"),
35+
Throwable::printStackTrace,
36+
() -> System.out.println("onComplete should never be printed!"));
37+
```
38+
39+
## onErrorComplete
40+
41+
**Available in:** ![image](https://raw.github.com/wiki/ReactiveX/RxJava/images/checkmark_off.png) `Flowable`, ![image](https://raw.github.com/wiki/ReactiveX/RxJava/images/checkmark_off.png) `Observable`, ![image](https://raw.github.com/wiki/ReactiveX/RxJava/images/checkmark_on.png) `Maybe`, ![image](https://raw.github.com/wiki/ReactiveX/RxJava/images/checkmark_off.png) `Single`, ![image](https://raw.github.com/wiki/ReactiveX/RxJava/images/checkmark_on.png) `Completable`
42+
43+
**ReactiveX documentation:** [http://reactivex.io/documentation/operators/catch.html](http://reactivex.io/documentation/operators/catch.html)
44+
45+
Instructs a reactive type to swallow an error event and replace it by a completion event.
46+
47+
Optionally, a `io.reactivex.functions.Predicate` can be specified that gives more control over when an error event should be replaced by a completion event, and when not.
48+
49+
### onErrorComplete example
50+
51+
```java
52+
Completable.fromAction(() -> {
53+
throw new IOException();
54+
}).onErrorComplete(error -> {
55+
// Only ignore errors of type java.io.IOException.
56+
return error instanceof IOException;
57+
}).subscribe(
58+
() -> System.out.println("IOException was ignored"),
59+
error -> System.err.println("onError should not be printed!"));
60+
```
61+
62+
## onErrorResumeNext
63+
64+
**Available in:** ![image](https://raw.github.com/wiki/ReactiveX/RxJava/images/checkmark_on.png) `Flowable`, ![image](https://raw.github.com/wiki/ReactiveX/RxJava/images/checkmark_on.png) `Observable`, ![image](https://raw.github.com/wiki/ReactiveX/RxJava/images/checkmark_on.png) `Maybe`, ![image](https://raw.github.com/wiki/ReactiveX/RxJava/images/checkmark_on.png) `Single`, ![image](https://raw.github.com/wiki/ReactiveX/RxJava/images/checkmark_on.png) `Completable`
65+
66+
**ReactiveX documentation:** [http://reactivex.io/documentation/operators/catch.html](http://reactivex.io/documentation/operators/catch.html)
67+
68+
Instructs a reactive type to emit a sequence of items if it encounters an error.
69+
70+
### onErrorResumeNext example
71+
72+
```java
73+
Observable<Integer> numbers = Observable.generate(() -> 1, (state, emitter) -> {
74+
emitter.onNext(state);
75+
76+
return state + 1;
77+
});
78+
79+
numbers.scan(Math::multiplyExact)
80+
.onErrorResumeNext(Observable.empty())
81+
.subscribe(
82+
System.out::println,
83+
error -> System.err.println("onError should not be printed!"));
84+
85+
// prints:
86+
// 1
87+
// 2
88+
// 6
89+
// 24
90+
// 120
91+
// 720
92+
// 5040
93+
// 40320
94+
// 362880
95+
// 3628800
96+
// 39916800
97+
// 479001600
98+
```
99+
100+
## onErrorReturn
101+
102+
**Available in:** ![image](https://raw.github.com/wiki/ReactiveX/RxJava/images/checkmark_on.png) `Flowable`, ![image](https://raw.github.com/wiki/ReactiveX/RxJava/images/checkmark_on.png) `Observable`, ![image](https://raw.github.com/wiki/ReactiveX/RxJava/images/checkmark_on.png) `Maybe`, ![image](https://raw.github.com/wiki/ReactiveX/RxJava/images/checkmark_on.png) `Single`, ![image](https://raw.github.com/wiki/ReactiveX/RxJava/images/checkmark_off.png) `Completable`
103+
104+
**ReactiveX documentation:** [http://reactivex.io/documentation/operators/catch.html](http://reactivex.io/documentation/operators/catch.html)
105+
106+
Instructs a reactive type to emit the item returned by the specified `io.reactivex.functions.Function` when it encounters an error.
107+
108+
### onErrorReturn example
109+
110+
```java
111+
Single.just("2A")
112+
.map(v -> Integer.parseInt(v, 10))
113+
.onErrorReturn(error -> {
114+
if (error instanceof NumberFormatException) return 0;
115+
else throw new IllegalArgumentException();
116+
})
117+
.subscribe(
118+
System.out::println,
119+
error -> System.err.println("onError should not be printed!"));
120+
121+
// prints 0
122+
```
123+
124+
## onErrorReturnItem
125+
126+
**Available in:** ![image](https://raw.github.com/wiki/ReactiveX/RxJava/images/checkmark_on.png) `Flowable`, ![image](https://raw.github.com/wiki/ReactiveX/RxJava/images/checkmark_on.png) `Observable`, ![image](https://raw.github.com/wiki/ReactiveX/RxJava/images/checkmark_on.png) `Maybe`, ![image](https://raw.github.com/wiki/ReactiveX/RxJava/images/checkmark_on.png) `Single`, ![image](https://raw.github.com/wiki/ReactiveX/RxJava/images/checkmark_off.png) `Completable`
127+
128+
**ReactiveX documentation:** [http://reactivex.io/documentation/operators/catch.html](http://reactivex.io/documentation/operators/catch.html)
129+
130+
Instructs a reactive type to emit a particular item when it encounters an error.
131+
132+
### onErrorReturnItem example
133+
134+
```java
135+
Single.just("2A")
136+
.map(v -> Integer.parseInt(v, 10))
137+
.onErrorReturnItem(0)
138+
.subscribe(
139+
System.out::println,
140+
error -> System.err.println("onError should not be printed!"));
141+
142+
// prints 0
143+
```
144+
145+
## onExceptionResumeNext
146+
147+
**Available in:** ![image](https://raw.github.com/wiki/ReactiveX/RxJava/images/checkmark_on.png) `Flowable`, ![image](https://raw.github.com/wiki/ReactiveX/RxJava/images/checkmark_on.png) `Observable`, ![image](https://raw.github.com/wiki/ReactiveX/RxJava/images/checkmark_on.png) `Maybe`, ![image](https://raw.github.com/wiki/ReactiveX/RxJava/images/checkmark_off.png) `Single`, ![image](https://raw.github.com/wiki/ReactiveX/RxJava/images/checkmark_off.png) `Completable`
148+
149+
**ReactiveX documentation:** [http://reactivex.io/documentation/operators/catch.html](http://reactivex.io/documentation/operators/catch.html)
150+
151+
Instructs a reactive type to continue emitting items after it encounters an `java.lang.Exception`. Unlike [`onErrorResumeNext`](#onerrorresumenext), this one lets other types of `Throwable` continue through.
152+
153+
### onExceptionResumeNext example
154+
155+
```java
156+
Observable<String> exception = Observable.<String>error(IOException::new)
157+
.onExceptionResumeNext(Observable.just("This value will be used to recover from the IOException"));
158+
159+
Observable<String> error = Observable.<String>error(Error::new)
160+
.onExceptionResumeNext(Observable.just("This value will not be used"));
161+
162+
Observable.concat(exception, error)
163+
.subscribe(
164+
message -> System.out.println("onNext: " + message),
165+
err -> System.err.println("onError: " + err));
166+
167+
// prints:
168+
// onNext: This value will be used to recover from the IOException
169+
// onError: java.lang.Error
170+
```
171+
172+
## retry
173+
174+
**Available in:** ![image](https://raw.github.com/wiki/ReactiveX/RxJava/images/checkmark_on.png) `Flowable`, ![image](https://raw.github.com/wiki/ReactiveX/RxJava/images/checkmark_on.png) `Observable`, ![image](https://raw.github.com/wiki/ReactiveX/RxJava/images/checkmark_on.png) `Maybe`, ![image](https://raw.github.com/wiki/ReactiveX/RxJava/images/checkmark_on.png) `Single`, ![image](https://raw.github.com/wiki/ReactiveX/RxJava/images/checkmark_on.png) `Completable`
175+
176+
**ReactiveX documentation:** [http://reactivex.io/documentation/operators/retry.html](http://reactivex.io/documentation/operators/retry.html)
177+
178+
Instructs a reactive type to resubscribe to the source reactive type if it encounters an error in the hopes that it will complete without error.
179+
180+
### retry example
181+
182+
```java
183+
Observable<Long> source = Observable.interval(0, 1, TimeUnit.SECONDS)
184+
.flatMap(x -> {
185+
if (x >= 2) return Observable.error(new IOException("Something went wrong!"));
186+
else return Observable.just(x);
187+
});
188+
189+
source.retry((retryCount, error) -> retryCount < 3)
190+
.blockingSubscribe(
191+
x -> System.out.println("onNext: " + x),
192+
error -> System.err.println("onError: " + error.getMessage()));
193+
194+
// prints:
195+
// onNext: 0
196+
// onNext: 1
197+
// onNext: 0
198+
// onNext: 1
199+
// onNext: 0
200+
// onNext: 1
201+
// onError: Something went wrong!
202+
```
203+
204+
## retryUntil
205+
206+
**Available in:** ![image](https://raw.github.com/wiki/ReactiveX/RxJava/images/checkmark_on.png) `Flowable`, ![image](https://raw.github.com/wiki/ReactiveX/RxJava/images/checkmark_on.png) `Observable`, ![image](https://raw.github.com/wiki/ReactiveX/RxJava/images/checkmark_on.png) `Maybe`, ![image](https://raw.github.com/wiki/ReactiveX/RxJava/images/checkmark_off.png) `Single`, ![image](https://raw.github.com/wiki/ReactiveX/RxJava/images/checkmark_off.png) `Completable`
207+
208+
**ReactiveX documentation:** [http://reactivex.io/documentation/operators/retry.html](http://reactivex.io/documentation/operators/retry.html)
209+
210+
Instructs a reactive type to resubscribe to the source reactive type if it encounters an error until the given `io.reactivex.functions.BooleanSupplier` returns `true`.
211+
212+
### retryUntil example
213+
214+
```java
215+
LongAdder errorCounter = new LongAdder();
216+
Observable<Long> source = Observable.interval(0, 1, TimeUnit.SECONDS)
217+
.flatMap(x -> {
218+
if (x >= 2) return Observable.error(new IOException("Something went wrong!"));
219+
else return Observable.just(x);
220+
})
221+
.doOnError((error) -> errorCounter.increment());
222+
223+
source.retryUntil(() -> errorCounter.intValue() >= 3)
224+
.blockingSubscribe(
225+
x -> System.out.println("onNext: " + x),
226+
error -> System.err.println("onError: " + error.getMessage()));
227+
228+
// prints:
229+
// onNext: 0
230+
// onNext: 1
231+
// onNext: 0
232+
// onNext: 1
233+
// onNext: 0
234+
// onNext: 1
235+
// onError: Something went wrong!
236+
```
237+
238+
## retryWhen
239+
240+
**Available in:** ![image](https://raw.github.com/wiki/ReactiveX/RxJava/images/checkmark_on.png) `Flowable`, ![image](https://raw.github.com/wiki/ReactiveX/RxJava/images/checkmark_on.png) `Observable`, ![image](https://raw.github.com/wiki/ReactiveX/RxJava/images/checkmark_on.png) `Maybe`, ![image](https://raw.github.com/wiki/ReactiveX/RxJava/images/checkmark_on.png) `Single`, ![image](https://raw.github.com/wiki/ReactiveX/RxJava/images/checkmark_on.png) `Completable`
241+
242+
**ReactiveX documentation:** [http://reactivex.io/documentation/operators/retry.html](http://reactivex.io/documentation/operators/retry.html)
243+
244+
Instructs a reactive type to pass any error to another `Observable` or `Flowable` to determine whether to resubscribe to the source.
245+
246+
### retryWhen example
247+
248+
```java
249+
Observable<Long> source = Observable.interval(0, 1, TimeUnit.SECONDS)
250+
.flatMap(x -> {
251+
if (x >= 2) return Observable.error(new IOException("Something went wrong!"));
252+
else return Observable.just(x);
253+
});
254+
255+
source.retryWhen(errors -> {
256+
return errors.map(error -> 1)
257+
258+
// Count the number of errors.
259+
.scan(Math::addExact)
260+
261+
.doOnNext(errorCount -> System.out.println("No. of errors: " + errorCount))
262+
263+
// Limit the maximum number of retries.
264+
.takeWhile(errorCount -> errorCount < 3)
265+
266+
// Signal resubscribe event after some delay.
267+
.flatMapSingle(errorCount -> Single.timer(errorCount, TimeUnit.SECONDS));
268+
}).blockingSubscribe(
269+
x -> System.out.println("onNext: " + x),
270+
Throwable::printStackTrace,
271+
() -> System.out.println("onComplete"));
272+
273+
// prints:
274+
// onNext: 0
275+
// onNext: 1
276+
// No. of errors: 1
277+
// onNext: 0
278+
// onNext: 1
279+
// No. of errors: 2
280+
// onNext: 0
281+
// onNext: 1
282+
// No. of errors: 3
283+
// onComplete
284+
```

0 commit comments

Comments
 (0)