Added result type params and unified result types

Author: jhalterman

CHANGELOG.md

@@ -1,9 +1,17 @@
+# Next Minor Release
+
+### API Changes
+
+- Added a generic result type `R` to `ExecutionContext`, `Execution` and `AsyncExecution`. This ensures that result types are unified across the API. It does mean that there are a few minor breaking changes to the API:
+  - `ContextualSupplier` and `AsyncSupplier` now have an additional result type parameter `R`. Normally these types are used as lambda parameters where the type is inferred, so most users should not be impacted. But any explicit generic declaration of these types will not compile until the new parameter is added.
+  - `PolicyExecutor`, which is part of the SPI, now accepts an additional result type parameter `R`. This is only relevant for SPI users who are implementing their own Policies.
+
 # 2.4.3
 
 ### Bug Fixes
 
 - Fixed #289 - Binary imcompatibility with code that was compiled against previous Failsafe versions.
-
+  
 # 2.4.2
 
 ### Improvements

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

@@ -26,13 +26,13 @@
 /**
  * Common execution information.
  *
+ * @param <R> result type
  * @author Jonathan Halterman
  */
-@SuppressWarnings("WeakerAccess")
-public abstract class AbstractExecution extends ExecutionContext {
+public abstract class AbstractExecution<R> extends ExecutionContext<R> {
   final Scheduler scheduler;
-  final FailsafeExecutor<Object> executor;
-  final List<PolicyExecutor<Policy<Object>>> policyExecutors;
+  final FailsafeExecutor<R> executor;
+  final List<PolicyExecutor<R, Policy<R>>> policyExecutors;
 
   // Internally mutable state
   /* Whether the supplier is in progress */
@@ -53,13 +53,13 @@ public abstract class AbstractExecution extends ExecutionContext {
   /**
    * Creates a new AbstractExecution for the {@code executor}.
    */
-  AbstractExecution(Scheduler scheduler, FailsafeExecutor<Object> executor) {
+  AbstractExecution(Scheduler scheduler, FailsafeExecutor<R> executor) {
     this.scheduler = scheduler;
     this.executor = executor;
     policyExecutors = new ArrayList<>(executor.policies.size());
-    ListIterator<Policy<Object>> policyIterator = executor.policies.listIterator(executor.policies.size());
+    ListIterator<Policy<R>> policyIterator = executor.policies.listIterator(executor.policies.size());
     for (int i = 1; policyIterator.hasPrevious(); i++) {
-      PolicyExecutor<Policy<Object>> policyExecutor = policyIterator.previous().toExecutor(this);
+      PolicyExecutor<R, Policy<R>> policyExecutor = policyIterator.previous().toExecutor(this);
       policyExecutor.policyIndex = i;
       policyExecutors.add(policyExecutor);
     }
@@ -76,12 +76,13 @@ void record(ExecutionResult result) {
     record(result, false);
   }
 
+  @SuppressWarnings("unchecked")
   void record(ExecutionResult result, boolean timeout) {
     Assert.state(!completed, "Execution has already been completed");
     if (!interrupted) {
       recordAttempt();
       if (inProgress) {
-        lastResult = result.getResult();
+        lastResult = (R) result.getResult();
         lastFailure = result.getFailure();
         executions.incrementAndGet();
         if (!timeout)
@@ -126,7 +127,7 @@ boolean isAsyncExecution() {
   synchronized ExecutionResult postExecute(ExecutionResult result) {
     record(result);
     boolean allComplete = true;
-    for (PolicyExecutor<Policy<Object>> policyExecutor : policyExecutors) {
+    for (PolicyExecutor<R, Policy<R>> policyExecutor : policyExecutors) {
       result = policyExecutor.postExecute(result);
       allComplete = allComplete && result.isComplete();
     }

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

@@ -29,20 +29,19 @@
  * Tracks asynchronous executions and allows retries to be scheduled according to a {@link RetryPolicy}. May be
  * explicitly completed or made to retry.
  *
+ * @param <R> result type
  * @author Jonathan Halterman
  */
-@SuppressWarnings("WeakerAccess")
-public final class AsyncExecution extends AbstractExecution {
+public final class AsyncExecution<R> extends AbstractExecution<R> {
   private SettableSupplier<CompletableFuture<ExecutionResult>> innerExecutionSupplier;
   private Supplier<CompletableFuture<ExecutionResult>> outerExecutionSupplier;
-  final FailsafeFuture<Object> future;
+  final FailsafeFuture<R> future;
   private volatile boolean completeCalled;
   private volatile boolean retryCalled;
 
-  @SuppressWarnings("unchecked")
-  <T> AsyncExecution(Scheduler scheduler, FailsafeFuture<T> future, FailsafeExecutor<?> executor) {
-    super(scheduler, (FailsafeExecutor<Object>) executor);
-    this.future = (FailsafeFuture<Object>) future;
+  AsyncExecution(Scheduler scheduler, FailsafeFuture<R> future, FailsafeExecutor<R> executor) {
+    super(scheduler, executor);
+    this.future = future;
   }
 
   void inject(Supplier<CompletableFuture<ExecutionResult>> syncSupplier, boolean asyncExecution) {
@@ -52,7 +51,7 @@ void inject(Supplier<CompletableFuture<ExecutionResult>> syncSupplier, boolean a
       outerExecutionSupplier = innerExecutionSupplier = Functions.toSettableSupplier(syncSupplier);
     }
 
-    for (PolicyExecutor<Policy<Object>> policyExecutor : policyExecutors)
+    for (PolicyExecutor<R, Policy<R>> policyExecutor : policyExecutors)
       outerExecutionSupplier = policyExecutor.supplyAsync(outerExecutionSupplier, scheduler, this.future);
   }
 
@@ -71,7 +70,7 @@ public void complete() {
    *
    * @throws IllegalStateException if the execution is already complete
    */
-  public boolean complete(Object result) {
+  public boolean complete(R result) {
     postExecute(new ExecutionResult(result, null));
     return completed;
   }
@@ -86,7 +85,7 @@ public boolean complete(Object result) {
    *
    * @throws IllegalStateException if the execution is already complete
    */
-  public boolean complete(Object result, Throwable failure) {
+  public boolean complete(R result, Throwable failure) {
     postExecute(new ExecutionResult(result, failure));
     return completed;
   }
@@ -98,8 +97,9 @@ public boolean complete(Object result, Throwable failure) {
    *
    * @throws IllegalStateException if a retry method has already been called or the execution is already complete
    */
+  @SuppressWarnings("unchecked")
   public boolean retry() {
-    return retryFor(lastResult, lastFailure);
+    return retryFor((R) lastResult, lastFailure);
   }
 
   /**
@@ -109,7 +109,7 @@ public boolean retry() {
    *
    * @throws IllegalStateException if a retry method has already been called or the execution is already complete
    */
-  public boolean retryFor(Object result) {
+  public boolean retryFor(R result) {
     return retryFor(result, null);
   }
 
@@ -120,7 +120,7 @@ public boolean retryFor(Object result) {
    *
    * @throws IllegalStateException if a retry method has already been called or the execution is already complete
    */
-  public boolean retryFor(Object result, Throwable failure) {
+  public boolean retryFor(R result, Throwable failure) {
     Assert.state(!retryCalled, "Retry has already been called");
     retryCalled = true;
     return !completeOrHandle(result, failure);
@@ -198,7 +198,7 @@ void executeAsync(boolean asyncExecution) {
    *
    * @throws IllegalStateException if the execution is already complete
    */
-  boolean completeOrHandle(Object result, Throwable failure) {
+  boolean completeOrHandle(R result, Throwable failure) {
     synchronized (future) {
       ExecutionResult er = new ExecutionResult(result, failure).withWaitNanos(waitNanos);
       if (!completeCalled)

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

@@ -18,10 +18,11 @@
 /**
  * A PolicyExecutor that handles failures according to a {@link CircuitBreaker}.
  *
+ * @param <R> result type
  * @author Jonathan Halterman
  */
-class CircuitBreakerExecutor extends PolicyExecutor<CircuitBreaker> {
-  CircuitBreakerExecutor(CircuitBreaker circuitBreaker, AbstractExecution execution) {
+class CircuitBreakerExecutor<R> extends PolicyExecutor<R, CircuitBreaker<R>> {
+  CircuitBreakerExecutor(CircuitBreaker<R> circuitBreaker, AbstractExecution<R> execution) {
     super(circuitBreaker, execution);
   }
 

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

@@ -24,26 +24,26 @@
 /**
  * Tracks executions and determines when an execution can be performed for a {@link RetryPolicy}.
  *
+ * @param <R> result type
  * @author Jonathan Halterman
  */
 @SuppressWarnings("WeakerAccess")
-public class Execution extends AbstractExecution {
+public class Execution<R> extends AbstractExecution<R> {
   /**
    * Creates a new {@link Execution} that will use the {@code policies} to handle failures. Policies are applied in
    * reverse order, with the last policy being applied first.
    *
    * @throws NullPointerException if {@code policies} is null
    * @throws IllegalArgumentException if {@code policies} is empty
    */
-  @SuppressWarnings("unchecked")
-  public Execution(Policy... policies) {
+  @SafeVarargs
+  public Execution(Policy<R>... policies) {
     super(DelegatingScheduler.INSTANCE, new FailsafeExecutor<>(Arrays.asList(Assert.notNull(policies, "policies"))));
     preExecute();
   }
 
-  @SuppressWarnings("unchecked")
-  Execution(FailsafeExecutor<?> executor) {
-    super(DelegatingScheduler.INSTANCE, (FailsafeExecutor<Object>) executor);
+  Execution(FailsafeExecutor<R> executor) {
+    super(DelegatingScheduler.INSTANCE, executor);
   }
 
   /**
@@ -52,7 +52,7 @@ public Execution(Policy... policies) {
    *
    * @throws IllegalStateException if the execution is already complete
    */
-  public boolean canRetryFor(Object result) {
+  public boolean canRetryFor(R result) {
     preExecute();
     postExecute(new ExecutionResult(result, null));
     return !completed;
@@ -64,7 +64,7 @@ public boolean canRetryFor(Object result) {
    *
    * @throws IllegalStateException if the execution is already complete
    */
-  public boolean canRetryFor(Object result, Throwable failure) {
+  public boolean canRetryFor(R result, Throwable failure) {
     preExecute();
     postExecute(new ExecutionResult(result, failure));
     return !completed;
@@ -99,7 +99,7 @@ public void complete() {
    *
    * @throws IllegalStateException if the execution is already complete
    */
-  public boolean complete(Object result) {
+  public boolean complete(R result) {
     preExecute();
     postExecute(new ExecutionResult(result, null));
     return completed;
@@ -122,7 +122,7 @@ public boolean recordFailure(Throwable failure) {
    * Performs a synchronous execution.
    */
   ExecutionResult executeSync(Supplier<ExecutionResult> supplier) {
-    for (PolicyExecutor<Policy<Object>> policyExecutor : policyExecutors)
+    for (PolicyExecutor<R, Policy<R>> policyExecutor : policyExecutors)
       supplier = policyExecutor.supply(supplier, scheduler);
 
     ExecutionResult result = supplier.get();

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

@@ -21,9 +21,10 @@
 /**
  * Contextual execution information.
  *
+ * @param <R> result type
  * @author Jonathan Halterman
  */
-public class ExecutionContext {
+public class ExecutionContext<R> {
   volatile Duration startTime = Duration.ZERO;
   volatile Duration attemptStartTime = Duration.ZERO;
   // Number of execution attempts
@@ -34,13 +35,13 @@ public class ExecutionContext {
   // Internally mutable state
   // The index of a PolicyExecutor that cancelled the execution. 0 represents non-cancelled.
   volatile int cancelledIndex;
-  volatile Object lastResult;
+  volatile R lastResult;
   volatile Throwable lastFailure;
 
   ExecutionContext() {
   }
 
-  private ExecutionContext(ExecutionContext context) {
+  private ExecutionContext(ExecutionContext<R> context) {
     this.startTime = context.startTime;
     this.attemptStartTime = context.attemptStartTime;
     this.attempts = context.attempts;
@@ -93,17 +94,15 @@ public <T extends Throwable> T getLastFailure() {
   /**
    * Returns the last result that was recorded else {@code null}.
    */
-  @SuppressWarnings("unchecked")
-  public <T> T getLastResult() {
-    return (T) lastResult;
+  public R getLastResult() {
+    return lastResult;
   }
 
   /**
    * Returns the last result that was recorded else the {@code defaultValue}.
    */
-  @SuppressWarnings("unchecked")
-  public <T> T getLastResult(T defaultValue) {
-    return lastResult != null ? (T) lastResult : defaultValue;
+  public R getLastResult(R defaultValue) {
+    return lastResult != null ? lastResult : defaultValue;
   }
 
   /**
@@ -114,7 +113,7 @@ public Duration getStartTime() {
   }
 
   /**
-   * Returns whether the execution has ben cancelled. In this case the implementor should attempt to stop execution.
+   * Returns whether the execution has been cancelled. In this case the implementor should attempt to stop execution.
    */
   public boolean isCancelled() {
     return cancelledIndex != 0;
@@ -134,18 +133,18 @@ public boolean isRetry() {
     return attempts.get() > 0;
   }
 
-  public ExecutionContext copy() {
-    return new ExecutionContext(this);
+  public ExecutionContext<R> copy() {
+    return new ExecutionContext<>(this);
   }
 
-  static ExecutionContext ofResult(Object result) {
-    ExecutionContext context = new ExecutionContext();
+  static <R> ExecutionContext<R> ofResult(R result) {
+    ExecutionContext<R> context = new ExecutionContext<>();
     context.lastResult = result;
     return context;
   }
 
-  static ExecutionContext ofFailure(Throwable failure) {
-    ExecutionContext context = new ExecutionContext();
+  static <R> ExecutionContext<R> ofFailure(Throwable failure) {
+    ExecutionContext<R> context = new ExecutionContext<>();
     context.lastFailure = failure;
     return context;
   }