Merge 57073c2 into 031f362

src/main/java/net/jodah/failsafe/AbstractExecution.java

@@ -20,6 +20,8 @@
 import net.jodah.failsafe.internal.util.Assert;
 import net.jodah.failsafe.util.Duration;
 
+import static net.jodah.failsafe.RetryPolicy.DelayFunction;
+
 abstract class AbstractExecution extends ExecutionContext {
   final FailsafeConfig<Object, ?> config;
   final RetryPolicy retryPolicy;
@@ -106,7 +108,26 @@ boolean complete(Object result, Throwable failure, boolean checkArgs) {
         circuitBreaker.recordSuccess();
     }
 
-    // Initialize or adjust the delay for backoffs
+    // If there's a delay function configured with the appropriate result and failure
+    // types and it returns a non-negative duration, use it to initialize the delay
+    // instead of the static delay value.
+    DelayFunction<?, ? extends Throwable> delayFunction = retryPolicy.getDelayFunction();
+    Class<?> resultType = retryPolicy.getDelayFunctionResultType();
+    Class<? extends Throwable> failureType = retryPolicy.getDelayFunctionFailureType();
+    if (delayFunction != null && (result == null || resultType.isInstance(result))
+            && (failure == null || failureType.isInstance(failure))) {
+        @SuppressWarnings("unchecked")
+        DelayFunction<Object, Throwable> f = (DelayFunction<Object, Throwable>) (DelayFunction) delayFunction;
+        Duration dynamicDelay = f.calculateDelay(result, failure, this);
+        if (dynamicDelay == null || dynamicDelay.toNanos() < 0)
+            delayNanos = -1;
+        else
+            delayNanos = dynamicDelay.toNanos();
+    }
+    // Initialize or adjust the delay for backoffs. Delay functions and backoff are
+    // mutually exclusive, so if the delay function above returns null or a negative
+    // duration, the delay will just be the fixed static delay value without any
+    // adjustments due to max delay or delay factor.
     if (delayNanos == -1)
       delayNanos = retryPolicy.getDelay().toNanos();
     else if (retryPolicy.getMaxDelay() != null)

src/main/java/net/jodah/failsafe/RetryPolicy.java

@@ -37,10 +37,37 @@
  * @author Jonathan Halterman
  */
 public class RetryPolicy {
+  /**
+   * A functional interface for dynamically computing delays between retries
+   * in conjunction with {@link #withDelay(DelayFunction)}.
+   */
+  @FunctionalInterface
+  public interface DelayFunction<R, F extends Throwable> {
+      /**
+       * Returns the amount of delay before the next retry based on
+       * the result or failure of the last attempt and the execution
+       * context (executions so far).
+       * This method must complete quickly and should not have side-effects.
+       * Unchecked exceptions thrown by this method will <strong>not</strong>
+       * be treated as part of the fail-safe processing and will instead abort
+       * that processing.
+       * @param result the result, if any, of the last attempt
+       * @param failure the {@link Throwable} thrown, if any, during the last attempt
+       * @param context the {@link ExecutionContext} that describes executions so far
+       * @return a non-negative duration to be used as the delay before next retry,
+       *         otherwise (null or negative duration) means fall back to the fixed
+       *         static delay for next retry
+       */
+      Duration calculateDelay(R result, F failure, ExecutionContext context);
+  }
+
   static final RetryPolicy NEVER = new RetryPolicy().withMaxRetries(0);
 
   private Duration delay;
   private double delayFactor;
+  private DelayFunction<?, ? extends Throwable> delayFunction;
+  private Class<?> delayFunctionResultType;
+  private Class<? extends Throwable> delayFunctionFailureType;
   private Duration jitter;
   private double jitterFactor;
   private Duration maxDelay;
@@ -226,6 +253,28 @@ public Duration getDelay() {
     return delay;
   }
 
+  /**
+   * Returns the function that determines the next delay given
+   * a failed attempt with the given {@link Throwable}.
+   */
+  public DelayFunction<?, ? extends Throwable> getDelayFunction() {
+    return delayFunction;
+  }
+
+  /**
+   * Returns the type of result expected by the delay function.
+   */
+  public Class<?> getDelayFunctionResultType() {
+      return delayFunctionResultType;
+  }
+
+  /**
+   * Returns the type of failure expected by the delay function.
+   */
+  public Class<? extends Throwable> getDelayFunctionFailureType() {
+      return delayFunctionFailureType;
+  }
+
   /**
    * Returns the delay factor for backoff retries.
    * 
@@ -372,7 +421,7 @@ public RetryPolicy retryWhen(Object result) {
    * 
    * @throws NullPointerException if {@code timeUnit} is null
    * @throws IllegalStateException if {@code delay} is >= the {@link RetryPolicy#withMaxDuration(long, TimeUnit)
-   *           maxDuration}
+   *           maxDuration}, or if a delay function has already been set
    * @throws IllegalArgumentException if {@code delay} is <= 0 or {@code delay} is >= {@code maxDelay}
    */
   public RetryPolicy withBackoff(long delay, long maxDelay, TimeUnit timeUnit) {
@@ -385,7 +434,7 @@ public RetryPolicy withBackoff(long delay, long maxDelay, TimeUnit timeUnit) {
    * 
    * @throws NullPointerException if {@code timeUnit} is null
    * @throws IllegalStateException if {@code delay} is >= the {@link RetryPolicy#withMaxDuration(long, TimeUnit)
-   *           maxDuration}
+   *           maxDuration}, or if a delay function has already been set
    * @throws IllegalArgumentException if {@code delay} <= 0, {@code delay} is >= {@code maxDelay}, or the
    *           {@code delayFactor} is <= 1
    */
@@ -394,6 +443,7 @@ public RetryPolicy withBackoff(long delay, long maxDelay, TimeUnit timeUnit, dou
     Assert.isTrue(timeUnit.toNanos(delay) > 0, "The delay must be greater than 0");
     Assert.state(maxDuration == null || timeUnit.toNanos(delay) < maxDuration.toNanos(),
         "delay must be less than the maxDuration");
+    Assert.state(delayFunction == null, "Delay function has already been set");
     Assert.isTrue(timeUnit.toNanos(delay) < timeUnit.toNanos(maxDelay), "delay must be less than the maxDelay");
     Assert.isTrue(delayFactor > 1, "delayFactor must be greater than 1");
     this.delay = new Duration(delay, timeUnit);
@@ -408,7 +458,7 @@ public RetryPolicy withBackoff(long delay, long maxDelay, TimeUnit timeUnit, dou
    * @throws NullPointerException if {@code timeUnit} is null
    * @throws IllegalArgumentException if {@code delay} <= 0
    * @throws IllegalStateException if {@code delay} is >= the {@link RetryPolicy#withMaxDuration(long, TimeUnit)
-   *           maxDuration}
+   *           maxDuration}, or if backoff delays have already been set
    */
   public RetryPolicy withDelay(long delay, TimeUnit timeUnit) {
     Assert.notNull(timeUnit, "timeUnit");
@@ -420,6 +470,37 @@ public RetryPolicy withDelay(long delay, TimeUnit timeUnit) {
     return this;
   }
 
+  /**
+   * Sets the function that determines the next delay before retrying.
+   * @param delayFunction the function to use to compute the delay before a next attempt
+   * @throws NullPointerException if {@code delayFunction} is null
+   * @throws IllegalStateException if backoff delays have already been set
+   */
+  public RetryPolicy withDelay(DelayFunction<Object, Throwable> delayFunction) {
+      return withDelay(delayFunction, Object.class, Throwable.class);
+  }
+
+  /**
+   * Sets the function that determines the next delay before retrying.
+   * @param delayFunction the function to use to compute the delay before a next attempt
+   * @param resultType the type of result from the previous attempt expected by the delay function
+   * @param failureType the type of failure from the previous attempt expected by the delay function
+   * @throws NullPointerException if {@code delayFunction} is null, {@code resultType} is null, or
+   *     {@code failureType} is null
+   * @throws IllegalStateException if backoff delays have already been set
+   */
+  public <R, F extends Throwable> RetryPolicy withDelay(DelayFunction<R, F> delayFunction,
+          Class<R> resultType, Class<F> failureType) {
+    Assert.notNull(delayFunction, "delayFunction");
+    Assert.notNull(resultType, "resultType");
+    Assert.notNull(failureType, "failureType");
+    Assert.state(maxDelay == null, "Backoff delays have already been set");
+    this.delayFunction = delayFunction;
+    this.delayFunctionResultType = resultType;
+    this.delayFunctionFailureType = failureType;
+    return this;
+  }
+
   /**
    * Sets the {@code jitterFactor} to randomly vary retry delays by. For each retry delay, a random portion of the delay
    * multiplied by the {@code jitterFactor} will be added or subtracted to the delay. For example: a retry delay of

src/test/java/net/jodah/failsafe/dyndelay/DynamicDelayTest.java

@@ -0,0 +1,195 @@
+/*
+ * Copyright 2016 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License
+ */
+package net.jodah.failsafe.dyndelay;
+
+import java.util.ArrayList;
+import java.util.List;
+
+import java.util.concurrent.TimeUnit;
+import java.util.concurrent.atomic.AtomicInteger;
+
+import net.jodah.failsafe.ExecutionContext;
+import net.jodah.failsafe.Failsafe;
+import net.jodah.failsafe.RetryPolicy;
+import net.jodah.failsafe.util.Duration;
+
+import org.testng.annotations.Test;
+
+import static org.testng.Assert.assertEquals;
+import static org.testng.Assert.assertTrue;
+import static org.testng.Assert.fail;
+
+public class DynamicDelayTest {
+
+    static class DynamicDelayException extends Exception {
+        final Duration duration;
+
+        DynamicDelayException(long time, TimeUnit unit) {
+            super(String.format("Dynamic delay of %s %s", time, unit));
+            this.duration = new Duration(time, unit);
+        }
+
+        public Duration getDuration() {
+            return duration;
+        }
+    }
+
+    static class UncheckedExpectedException extends RuntimeException {
+    }
+
+    static class DelayException extends UncheckedExpectedException {
+    }
+
+
+    @Test(expectedExceptions = NullPointerException.class)
+    public void testNullDelayFunction() {
+        RetryPolicy retryPolicy = new RetryPolicy()
+            .withDelay(null);
+        fail("Null delay function");
+    }
+
+    @Test(expectedExceptions = NullPointerException.class)
+    public void testNullResultType() {
+        RetryPolicy retryPolicy = new RetryPolicy()
+            .withDelay((result, failure, context) -> new Duration(1L, TimeUnit.SECONDS), null, Throwable.class);
+        fail("Null delay function result type");
+    }
+
+    @Test(expectedExceptions = NullPointerException.class)
+    public void testNullFailureType() {
+        RetryPolicy retryPolicy = new RetryPolicy()
+            .withDelay((result, failure, context) -> new Duration(1L, TimeUnit.SECONDS), Object.class, null);
+        fail("Null delay function failure type");
+    }
+
+    @Test
+    public void testDynamicDelay() {
+        long DELAY = TimeUnit.MILLISECONDS.toNanos(500);
+        long PAD = TimeUnit.MILLISECONDS.toNanos(25);
+
+        RetryPolicy retryPolicy = new RetryPolicy()
+            .withDelay((Object result, DynamicDelayException failure, ExecutionContext context) -> {
+                return failure == null ? null : failure.getDuration();
+            }, Object.class, DynamicDelayException.class)
+            .withMaxRetries(2);
+
+        List<Long> executionTimes = new ArrayList<>();
+
+        Failsafe.with(retryPolicy)
+            .run((ExecutionContext context) -> {
+                executionTimes.add(System.nanoTime());
+                if (context.getExecutions() == 0)
+                    throw new DynamicDelayException(DELAY, TimeUnit.NANOSECONDS);
+            });
+
+        assertEquals(executionTimes.size(), 2, "Should have exactly two executions");
+
+        long t0 = executionTimes.get(0);
+        long t1 = executionTimes.get(1);
+
+        //System.out.printf("actual delay %d, expected %d%n",
+        //    TimeUnit.NANOSECONDS.toMillis(t1 - t0),
+        //    TimeUnit.NANOSECONDS.toMillis(DELAY));
+
+        assertTrue(t1 - t0 > DELAY - PAD, "Time between executions less than expected");
+        assertTrue(t1 - t0 < DELAY + PAD, "Time between executions more than expected");
+    }
+
+
+    @Test(expectedExceptions = UncheckedExpectedException.class)
+    public void testUncheckedExceptionComputingDelay() {
+        RetryPolicy retryPolicy = new RetryPolicy()
+            .withDelay((result, failure, context) -> {
+                throw new UncheckedExpectedException();
+            });
+
+        Failsafe.with(retryPolicy)
+            .run((ExecutionContext context) -> {
+                throw new RuntimeException("try again");
+            });
+    }
+
+    @Test(expectedExceptions = IllegalStateException.class)
+    public void testSettingBackoffWhenDelayFunctionAlreadySet() {
+        RetryPolicy retryPolicy = new RetryPolicy()
+            .withDelay((result, failure, context) -> new Duration(1L, TimeUnit.SECONDS))
+            .withBackoff(1L, 3L, TimeUnit.SECONDS);
+        fail("Delay function already set");
+    }
+
+    @Test(expectedExceptions = IllegalStateException.class)
+    public void testSettingDelayFunctionWhenBackoffAlreadySet() {
+        RetryPolicy retryPolicy = new RetryPolicy()
+            .withBackoff(1L, 3L, TimeUnit.SECONDS)
+            .withDelay((result, failure, context) -> new Duration(1L, TimeUnit.SECONDS));
+        fail("Backoff delays already set");
+    }
+
+    @Test
+    public void testDelayOnMatchingReturnType() {
+        AtomicInteger delays = new AtomicInteger(0);
+        RetryPolicy retryPolicy = new RetryPolicy()
+            .retryIf(result -> true)
+            .withMaxRetries(4)
+            .withDelay((String r, Throwable f, ExecutionContext c) -> {
+                delays.incrementAndGet(); // side-effect for test purposes
+                return new Duration(1L, TimeUnit.MICROSECONDS);
+            }, String.class, Throwable.class);
+
+        AtomicInteger attempts = new AtomicInteger(0);
+        Object result = Failsafe.with(retryPolicy)
+            .withFallback(123)
+            .get(() -> {
+                int i = attempts.getAndIncrement();
+                switch (i) {
+                    case 0:
+                    case 3: return "" + i;
+                    default: return i;
+                }
+            });
+
+        assertEquals(result, 123, "Fallback should be used");
+        assertEquals(attempts.get(), 5, "Expecting five attempts (1 + 4 retries)");
+        assertEquals(delays.get(), 2, "Expecting two dynamic delays matching String result");
+    }
+
+    @Test
+    public void testDelayOnMatchingFailureType() {
+        AtomicInteger delays = new AtomicInteger(0);
+        RetryPolicy retryPolicy = new RetryPolicy()
+            .retryOn(UncheckedExpectedException.class)
+            .withMaxRetries(4)
+            .withDelay((Object r, DelayException f, ExecutionContext c) -> {
+                delays.incrementAndGet(); // side-effect for test purposes
+                return new Duration(1L, TimeUnit.MICROSECONDS);
+            }, Object.class, DelayException.class);
+
+        AtomicInteger attempts = new AtomicInteger(0);
+        int result = Failsafe.with(retryPolicy)
+            .withFallback(123)
+            .get(() -> {
+                int i = attempts.getAndIncrement();
+                switch (i) {
+                    case 0:
+                    case 2: throw new DelayException();
+                    default: throw new UncheckedExpectedException();
+                }
+            });
+        assertEquals(result, 123, "Fallback should be used");
+        assertEquals(attempts.get(), 5, "Expecting five attempts (1 + 4 retries)");
+        assertEquals(delays.get(), 2, "Expecting two dynamic delays matching DelayException failure");
+    }
+}