Added the feature to retry a failed function

Author: Robert Winkler

README.adoc

@@ -1,12 +1,12 @@
 = CircuitBreaker for Java8
 :author: Robert Winkler
-:version: 0.1.3
+:version: 0.1.4
 :hardbreaks:
 
 image:https://travis-ci.org/RobWin/circuitbreaker-java8.svg?branch=master["Build Status", link="https://travis-ci.org/RobWin/circuitbreaker-java8"] image:https://coveralls.io/repos/RobWin/circuitbreaker-java8/badge.svg["Coverage Status", link="https://coveralls.io/r/RobWin/circuitbreaker-java8"] image:https://api.bintray.com/packages/robwin/maven/circuitbreaker-java8/images/download.svg[link="https://bintray.com/robwin/maven/circuitbreaker-java8/_latestVersion"] image:http://img.shields.io/badge/license-ASF2-blue.svg["Apache License 2", link="http://www.apache.org/licenses/LICENSE-2.0.txt"]
 
 This library is an easy-to-use implementation of the http://martinfowler.com/bliki/CircuitBreaker.html[CircuitBreaker pattern] optimized for Java 8 and functional programming in a multithreaded environment.
-The library provides several higher-order functions to decorate any `Supplier / Runnable / Function` or `CheckedSupplier / CheckedRunnable / CheckedFunction` with a Circuit Breaker. In the following I call the higher-order functions `decorators`. The decorators return an enhanced version of your function. Furthermore, the library provides decorators to measure runtime metrics of your functions by using https://dropwizard.github.io/metrics/[Dropwizard Metrics]. You can stack more than one decorator on any given function. That means, you can combine a Metrics decorator with a CircuitBreaker decorator. Any decorated function can be invoked synchronously or asynchronously.
+The library provides several higher-order functions to decorate any `Supplier / Runnable / Function` or `CheckedSupplier / CheckedRunnable / CheckedFunction` with a Circuit Breaker. In the following I call the higher-order functions `decorators`. The decorators return an enhanced version of your function. Furthermore, the library provides decorators to measure runtime metrics of your functions by using https://dropwizard.github.io/metrics/[Dropwizard Metrics] and decorators to retry a failed function. You can stack more than one decorator on any given function. That means, you can combine a Metrics decorator with a CircuitBreaker decorator. Any decorated function can be invoked synchronously or asynchronously.
 The project should be combined with a functional library for Java 8 like https://github.com/javaslang/javaslang[javaslang]. The project requires at least JDK 8.
 
 The CircuitBreaker is implemented via a finite state machine with three states: `CLOSED`, `OPEN` and `HALF_OPEN`. The CircuitBreaker does not know anything about the backend's state by itself, but uses the information provided by the decorators via `CircuitBreaker::recordSuccess()` and `CircuitBreaker::recordFailure(throwable)`. The decorators are pure functions. The result of a decorator depends solely on the input parameters. See example: 
@@ -20,16 +20,16 @@ static <T> Supplier<T> decorateSupplier(Supplier<T> supplier, CircuitBreaker cir
             T returnValue = supplier.get();
             circuitBreaker.recordSuccess();
             return returnValue;
-        } catch (Throwable throwable) {
-            circuitBreaker.recordFailure(throwable);
-            throw throwable;
+        } catch (Exception exception) {
+            circuitBreaker.recordFailure(exception);
+            throw exception;
         }
     };
 }
 ----
 
 The state of the CircuitBreaker changes from `CLOSED` to `OPEN` if a (configurable) number of call attempts have failed consecutively. Then, all access to the backend is blocked for a (configurable) time interval. `CircuitBreaker::isCallPermitted()` throws a `CircuitBreakerOpenException`, if the CircuitBreaker is `OPEN`.
-After the time interval has elapsed, the CircuitBreaker state changes to `HALF_CLOSED` and allows calls to see if the backend is still unavailable or has become available again. On success or failure, the state changes back to `CLOSED` or `OPEN`, respectively. `CircuitBreaker::recordFailure(throwable)` also checks if the type of exception should increase the number of failure attempts.
+After the time interval has elapsed, the CircuitBreaker state changes to `HALF_CLOSED` and allows calls to see if the backend is still unavailable or has become available again. On success or failure, the state changes back to `CLOSED` or `OPEN`, respectively. `CircuitBreaker::recordFailure(exception)` also checks if the type of exception should increase the number of failure attempts.
 
 == Usage guide
 
@@ -189,7 +189,7 @@ assertThat(result.isSuccess()).isTrue();
 assertThat(result.get()).isEqualTo("Hello Recovery");
 ----
 
-=== Example of how to ignore exceptions
+=== Ignore exceptions example
 
 The following test cases shows how to add exceptions to the ignore list which must not trigger the CircuitBreaker.
 
@@ -222,7 +222,39 @@ assertThat(circuitBreaker.getState()).isEqualTo(CircuitBreaker.State.CLOSED);
 assertThat(result.failed().get()).isInstanceOf(IOException.class);
 ----
 
-=== Example with CompletableFuture
+=== Retry example
+
+You can also retry a failed function.
+
+[source,java]
+----
+// Given I have a HelloWorldService which throws an exception
+HelloWorldService  helloWorldService = mock(HelloWorldService.class);
+given(helloWorldService.sayHelloWorld()).willThrow(new WebServiceException("BAM!"));
+
+// Create a Retry with default configuration
+// (maxAttempts = 3, waitInterval = 500[ms], ignoredExceptions = empty)
+Retry retryContext = Retry.ofDefaults();
+// Decorate the invocation of the HelloWorldService
+Try.CheckedSupplier<String> retryableSupplier = Retry.retryableCheckedSupplier(helloWorldService::sayHelloWorld, retryContext);
+
+// When I invoke the function
+Try<String> result = Try.of(retryableSupplier).recover((throwable) -> "Hello world from recovery function");
+
+// Then the helloWorldService should be invoked 3 times
+BDDMockito.then(helloWorldService).should(times(3)).sayHelloWorld();
+// and the exception should be handled by the recovery function
+assertThat(result.get()).isEqualTo("Hello world from recovery function");
+----
+
+As an alternative you can create a custom `RetryContext`. In order to create a custom RetryContext, you can use the RetryContext builder. You can configure the maximum number of retry attempts and the wait interval [ms] between successive attempts. Furthermore, you can add exceptions to the ignore list which must not trigger a retry.
+
+[source,java]
+----
+Retry retryContext = Retry.custom().maxAttempts(2).ignoredException(WebServiceException.class).build();
+----
+
+=== CompletableFuture example
 
 You can also invoke a decorated function asynchronously and chain further functions.
 

RELEASENOTES.adoc

@@ -11,3 +11,6 @@
 
 == Version 0.1.3
 * Added a static factory method for the CircuitBreakerConfig builder
+
+== Version 0.1.4
+* Added the feature to retry a failed function

build.gradle

@@ -18,7 +18,7 @@ apply from: 'gradle/publishing.gradle'
 
 group = 'io.github.robwin'
 sourceCompatibility = 1.8
-version = '0.1.3'
+version = '0.1.4'
 description = 'A CircuitBreaker pattern implementation for Java 8 and functional programming-'
 
 repositories {
@@ -32,6 +32,8 @@ dependencies {
     testCompile "org.assertj:assertj-core:3.0.0"
     testCompile "ch.qos.logback:logback-classic:0.9.26"
     testCompile "io.dropwizard.metrics:metrics-healthchecks:3.1.2"
+    testCompile "org.mockito:mockito-all:1.10.19"
+
 }
 
 task sourcesJar(type: Jar, dependsOn: classes) {

src/main/java/io/github/robwin/circuitbreaker/CircuitBreaker.java

@@ -44,9 +44,9 @@ public interface CircuitBreaker {
      * Records a backend failure.
      * This must be called if a call to a backend fails
      *
-     * @param throwable The throwable which must be recorded
+     * @param exception The exception which must be recorded
      */
-    void recordFailure(Throwable throwable);
+    void recordFailure(Exception exception);
 
      /**
       * Records success of a call to a backend.
@@ -90,9 +90,9 @@ static <T> Try.CheckedSupplier<T> decorateCheckedSupplier(Try.CheckedSupplier<T>
                 T returnValue = supplier.get();
                 circuitBreaker.recordSuccess();
                 return returnValue;
-            } catch (Throwable throwable) {
-                circuitBreaker.recordFailure(throwable);
-                throw throwable;
+            } catch (Exception exception) {
+                circuitBreaker.recordFailure(exception);
+                throw exception;
             }
         };
     }
@@ -103,9 +103,9 @@ static Try.CheckedRunnable decorateCheckedRunnable(Try.CheckedRunnable runnable,
             try{
                 runnable.run();
                 circuitBreaker.recordSuccess();
-            } catch (Throwable throwable){
-                circuitBreaker.recordFailure(throwable);
-                throw throwable;
+            } catch (Exception exception){
+                circuitBreaker.recordFailure(exception);
+                throw exception;
             }
         };
     }
@@ -117,9 +117,9 @@ static <T> Supplier<T> decorateSupplier(Supplier<T> supplier, CircuitBreaker cir
                 T returnValue = supplier.get();
                 circuitBreaker.recordSuccess();
                 return returnValue;
-            } catch (Throwable throwable) {
-                circuitBreaker.recordFailure(throwable);
-                throw throwable;
+            } catch (Exception exception) {
+                circuitBreaker.recordFailure(exception);
+                throw exception;
             }
         };
     }
@@ -130,9 +130,9 @@ static Runnable decorateRunnable(Runnable runnable, CircuitBreaker circuitBreake
             try{
                 runnable.run();
                 circuitBreaker.recordSuccess();
-            } catch (Throwable throwable){
-                circuitBreaker.recordFailure(throwable);
-                throw throwable;
+            } catch (Exception exception){
+                circuitBreaker.recordFailure(exception);
+                throw exception;
             }
         };
     }
@@ -144,9 +144,9 @@ static <T, R> Function<T, R> decorateFunction(Function<T, R> function, CircuitBr
                 R returnValue = function.apply(t);
                 circuitBreaker.recordSuccess();
                 return returnValue;
-            } catch (Throwable throwable){
-                circuitBreaker.recordFailure(throwable);
-                throw throwable;
+            } catch (Exception exception){
+                circuitBreaker.recordFailure(exception);
+                throw exception;
             }
         };
     }
@@ -158,9 +158,9 @@ static <T, R> Try.CheckedFunction<T, R> decorateCheckedFunction(Try.CheckedFunct
                 R returnValue = function.apply(t);
                 circuitBreaker.recordSuccess();
                 return returnValue;
-            } catch (Throwable throwable){
-                circuitBreaker.recordFailure(throwable);
-                throw throwable;
+            } catch (Exception exception){
+                circuitBreaker.recordFailure(exception);
+                throw exception;
             }
         };
     }

src/main/java/io/github/robwin/circuitbreaker/CircuitBreakerConfig.java

@@ -22,12 +22,16 @@
 import java.util.List;
 
 public class CircuitBreakerConfig {
+
+    private static final int DEFAULT_MAX_FAILURES = 3;
+    private static final int DEFAULT_WAIT_INTERVAL = 60000;
+
     // The maximum number of allowed failures
-    private int maxFailures;
+    private final int maxFailures;
     // The wait interval which specifies how long the CircuitBreaker should stay OPEN
-    private int waitInterval;
+    private final int waitInterval;
     // Exceptions which do not count as failures and thus not trigger the circuit breaker.
-    private List<Class<? extends Throwable>> ignoredExceptions;
+    private final List<Class<? extends Throwable>> ignoredExceptions;
 
     private CircuitBreakerConfig(int maxFailures, int waitInterval, List<Class<? extends Throwable>> ignoredExceptions){
         this.maxFailures = maxFailures;
@@ -52,26 +56,38 @@ public static CircuitBreakerConfig.Builder custom(){
     }
 
     public static class Builder {
-        private int maxFailures = 3;
-        private int waitInterval = 60000;
+        private int maxFailures = DEFAULT_MAX_FAILURES;
+        private int waitInterval = DEFAULT_WAIT_INTERVAL;
         private List<Class<? extends Throwable>> ignoredExceptions = new ArrayList<>();
 
         public Builder maxFailures(int maxFailures) {
+            if (maxFailures < 0) {
+                throw new IllegalArgumentException("maxFailures must be greater than or equal to 0");
+            }
             this.maxFailures = maxFailures;
             return this;
         }
 
         public Builder waitInterval(int waitInterval) {
+            if (waitInterval < 100) {
+                throw new IllegalArgumentException("waitInterval must be at least 100[ms]");
+            }
             this.waitInterval = waitInterval;
             return this;
         }
 
         public Builder ignoredException(Class<? extends Throwable> ignoredException) {
+            if (ignoredException == null) {
+                throw new IllegalArgumentException("ignoredException must not be null");
+            }
             ignoredExceptions.add(ignoredException);
             return this;
         }
 
         public Builder ignoredExceptions(List<Class<? extends Throwable>> ignoredExceptions) {
+            if (ignoredExceptions == null) {
+                throw new IllegalArgumentException("ignoredExceptions must not be null");
+            }
             this.ignoredExceptions = ignoredExceptions;
             return this;
         }

src/main/java/io/github/robwin/circuitbreaker/CircuitBreakerStateMachine.java

@@ -25,7 +25,7 @@
  * CircuitBreaker finite state machine.
  * This CircuitBreaker is implemented via a (timed) finite state machine. It does not have a way to know anything about the
  * backend's state by itself, but uses only the information provided by calls to {@link #recordSuccess()} and
- * {@link #recordFailure()}.
+ * {@link #recordFailure(java.lang.Exception)}.
  * The state of the CircuitBreaker changes from `CLOSED` to `OPEN` if a (configurable) number of call attempts have failed consecutively.
  * Then, all access to the backend is blocked for a (configurable) time interval. After that, the CircuitBreaker state changes to `HALF_CLOSED` tentatively, to see if the backend is still dead or has become available again.
  * On success or failure, the state changes back to `CLOSED` or `OPEN`, respectively.
@@ -66,9 +66,9 @@ public boolean isCallPermitted() {
      * Records a failure.
      */
     @Override
-    public void recordFailure(Throwable throwable) {
+    public void recordFailure(Exception exception) {
         if(circuitBreakerConfig.getIgnoredExceptions().stream()
-                .noneMatch(ignoredException -> ignoredException.isInstance(throwable))){
+                .noneMatch(ignoredException -> ignoredException.isInstance(exception))){
             stateReference.get().recordFailure();
         }
     }

src/main/java/io/github/robwin/retry/Retry.java

@@ -0,0 +1,110 @@
+package io.github.robwin.retry;
+
+import javaslang.control.Try;
+
+import java.util.function.Function;
+import java.util.function.Supplier;
+
+public interface Retry {
+
+    /**
+     * Checks if the call should be retried
+     *
+     * @return the maximum number of attempts
+     */
+    boolean isRetryAllowedAfterException() throws Exception;
+
+    /**
+     * Checks if the call should be retried
+     *
+     * @return the maximum number of attempts
+     */
+    boolean isRetryAllowedAfterRuntimeException();
+
+    /**
+     * Handles a checked exception
+     */
+    void handleException(Exception exception) throws Throwable;
+
+    /**
+     * Handles a runtime exception
+     */
+    void handleRuntimeException(RuntimeException runtimeException);
+
+    public static RetryContext.Builder custom(){
+        return new RetryContext.Builder();
+    }
+
+    public static Retry ofDefaults(){
+        return Retry.custom().build();
+    }
+
+    static <T> Try.CheckedSupplier<T> retryableCheckedSupplier(Try.CheckedSupplier<T> supplier, Retry retryContext){
+        return () -> {
+            do try {
+                return supplier.get();
+            } catch (Exception exception) {
+                retryContext.handleException(exception);
+            } while (retryContext.isRetryAllowedAfterException());
+            // Should never reach this code
+            return null;
+        };
+    }
+
+    static <T> Try.CheckedRunnable retryableCheckedRunnable(Try.CheckedRunnable runnable, Retry retryContext){
+        return () -> {
+            do try {
+                runnable.run();
+            } catch (Exception exception) {
+                retryContext.handleException(exception);
+            } while (retryContext.isRetryAllowedAfterException());
+        };
+    }
+
+    static <T, R> Try.CheckedFunction<T, R> retryableCheckedFunction(Try.CheckedFunction<T, R> function, Retry retryContext){
+        return (T t) -> {
+            do try {
+                return function.apply(t);
+            } catch (Exception exception) {
+                retryContext.handleException(exception);
+            } while (retryContext.isRetryAllowedAfterException());
+            // Should never reach this code
+            return null;
+        };
+    }
+
+    static <T> Supplier<T> retryableSupplier(Supplier<T> supplier, Retry retryContext){
+        return () -> {
+            do try {
+                return supplier.get();
+            } catch (RuntimeException runtimeException) {
+                retryContext.handleRuntimeException(runtimeException);
+            } while (retryContext.isRetryAllowedAfterRuntimeException());
+            // Should never reach this code
+            return null;
+        };
+    }
+
+    static <T> Runnable retryableRunnable(Runnable runnable, Retry retryContext){
+        return () -> {
+            do try {
+                runnable.run();
+            } catch (RuntimeException runtimeException) {
+                retryContext.handleRuntimeException(runtimeException);
+            } while (retryContext.isRetryAllowedAfterRuntimeException());
+        };
+    }
+
+    static <T, R> Function<T, R> retryableFunction(Function<T, R> function, Retry retryContext){
+        return (T t) -> {
+            do try {
+                return function.apply(t);
+            } catch (RuntimeException runtimeException) {
+                retryContext.handleRuntimeException(runtimeException);
+            } while (retryContext.isRetryAllowedAfterRuntimeException());
+            // Should never reach this code
+            return null;
+        };
+    }
+
+}