3.3 Added retryWhen

Author: Froussios

Part 3 - Taming the sequence/3. Advanced error handling.md

@@ -126,6 +126,44 @@ Here. we've specified that we want to retry once. Our observable fails after two
 
 In this example, we have done something naughty: we have made our subscription stateful to demonstrate that the observable is restarted from the source. The observable produced different values the second time around. `retry` does not cache any elements like `replay`, nor would it make sense to do so. It will become apparent why this matters once we discuss the differences between hot and cold observables.
 
+### retryWhen
+
+`retry` will restart the subscription as soon as the failure happens. If we need more control over this, we can use `retryWhen`.
+
+```java
+public final Observable<T> retryWhen(Func1<? super Observable<? extends java.lang.Throwable>,? extends Observable<?>> notificationHandler)
+```
+
+The argument to `retryWhen` is a function that takes an observable and returns another. The input observable emits all the errors that `retryWhen` encounters. The resulting observable signals when to retry: 
+* if it emits a value, `retryWhen` will retry,
+* if it terminates, `retryWhen` will emit the error and not retry.
+Note that the type of the signaling obserable of the actual values emitted don't matter. The values are discarded and the observable is only used for timing.
+
+In the next example, we will construct a retrying policy where we wait 100ms before retrying.
+
+```java
+Observable<Integer> source = Observable.create(o -> {
+	o.onNext(1);
+	o.onNext(2);
+	o.onError(new Exception("Failed"));
+});
+	
+source.retryWhen((o) -> o.take(2).delay(100, TimeUnit.MILLISECONDS))
+	.timeInterval()
+	.subscribe(System.out::println);
+```
+Output
+```
+TimeInterval [intervalInMilliseconds=17, value=1]
+TimeInterval [intervalInMilliseconds=0, value=2]
+TimeInterval [intervalInMilliseconds=102, value=1]
+TimeInterval [intervalInMilliseconds=0, value=2]
+TimeInterval [intervalInMilliseconds=102, value=1]
+TimeInterval [intervalInMilliseconds=0, value=2]
+```
+
+Our source observable emits 2 values and immediately fails. When that happens, the observable of failures inside `retryWhen` emits the error. We delay that emission by 100ms and send it back to signal to retry. `take(2)` guarantees that our signaling observabe will terminate after we receive two errors. That means that `retryWhen` won't retry after 2 failures.
+
 ## using
 
 The `using` operator is for creating observables from resources that need to managed. It guarantees that your resources will be managed regardless of when and how subscriptions are terminated. If you were to just use `create`, you would have to do the managing in the traditional Java paradigm and inject it into Rx. `using` is a more natural way of managing you resources in Rx.