Clarifies the meaning of a failure vs an exception

This commit clarifies the meaning of "failure" vs "exception". Unfortunately, "failure" has been very overloaded in Failsafe to mean an exception or something that a policy actually considers a failure, which may or may not be a particular exception.

This commit deprecates many of the fields that record or get "failures" where failure is really meant to mean an exception, and adds new methods with "exception" naming.

Author: jhalterman

core/src/main/java/dev/failsafe/AsyncExecution.java

@@ -38,13 +38,13 @@ public interface AsyncExecution<R> extends ExecutionContext<R> {
   boolean isComplete();
 
   /**
-   * Records an execution {@code result} or {@code failure} which triggers failure handling, if needed, by the
+   * Records an execution {@code result} or {@code exception} which triggers failure handling, if needed, by the
    * configured policies. If policy handling is not possible or already complete, the resulting {@link
    * CompletableFuture} is completed.
    *
    * @throws IllegalStateException if the most recent execution was already recorded or the execution is complete
    */
-  void record(R result, Throwable failure);
+  void record(R result, Throwable exception);
 
   /**
    * Records an execution {@code result} which triggers failure handling, if needed, by the configured policies. If
@@ -55,10 +55,16 @@ public interface AsyncExecution<R> extends ExecutionContext<R> {
   void recordResult(R result);
 
   /**
-   * Records an execution {@code failure} which triggers failure handling, if needed, by the configured policies. If
-   * policy handling is not possible or already complete, the resulting {@link CompletableFuture} is completed.
+   * Records an {@code exception} which triggers failure handling, if needed, by the configured policies. If policy
+   * handling is not possible or already complete, the resulting {@link CompletableFuture} is completed.
    *
    * @throws IllegalStateException if the most recent execution was already recorded or the execution is complete
    */
+  void recordException(Throwable exception);
+
+  /**
+   * @deprecated Use {@link #recordException(Throwable)} instead
+   */
+  @Deprecated
   void recordFailure(Throwable failure);
 }

core/src/main/java/dev/failsafe/AsyncExecutionImpl.java

@@ -85,15 +85,15 @@ public boolean isComplete() {
   }
 
   @Override
-  public void record(R result, Throwable failure) {
+  public void record(R result, Throwable exception) {
     Assert.state(!recorded, "The most recent execution has already been recorded or completed");
     recorded = true;
 
     // Guard against race with a timeout expiring
     synchronized (future) {
       if (!attemptRecorded) {
         Assert.state(!completed, "Execution has already been completed");
-        record(new ExecutionResult<>(result, failure));
+        record(new ExecutionResult<>(result, exception));
       }
 
       // Proceed with handling the recorded result
@@ -107,8 +107,14 @@ public void recordResult(R result) {
   }
 
   @Override
+  public void recordException(Throwable exception) {
+    record(null, exception);
+  }
+
+  @Override
+  @Deprecated
   public void recordFailure(Throwable failure) {
-    record(null, failure);
+    recordException(failure);
   }
 
   @Override
@@ -154,7 +160,7 @@ private void complete(ExecutionResult<R> result, Throwable error) {
       else {
         if (error instanceof CompletionException)
           error = error.getCause();
-        future.completeResult(ExecutionResult.failure(error));
+        future.completeResult(ExecutionResult.exception(error));
       }
     }
   }

core/src/main/java/dev/failsafe/CircuitBreaker.java

@@ -112,7 +112,7 @@ enum State {
    * to the configured success or failure thresholding capacity.
    * @see #tryAcquirePermit()
    * @see #recordResult(Object)
-   * @see #recordFailure(Throwable)
+   * @see #recordException(Throwable)
    * @see #recordSuccess()
    * @see #recordFailure()
    */
@@ -126,7 +126,7 @@ default void acquirePermit() {
    * automatically released when a result or failure is recorded.
    *
    * @see #recordResult(Object)
-   * @see #recordFailure(Throwable)
+   * @see #recordException(Throwable)
    * @see #recordSuccess()
    * @see #recordFailure()
    */
@@ -229,8 +229,14 @@ default void acquirePermit() {
   void recordFailure();
 
   /**
-   * Records an execution {@code failure} as a success or failure based on the failure configuration.
+   * Records an {@code exception} as a success or failure based on the exception configuration.
    */
+  void recordException(Throwable exception);
+
+  /**
+   * @deprecated Use {@link #recordException(Throwable)} instead.
+   */
+  @Deprecated
   void recordFailure(Throwable failure);
 
   /**

core/src/main/java/dev/failsafe/CircuitBreakerBuilder.java

@@ -30,10 +30,10 @@
  * <ul>
  *   <li>By default, any exception is considered a failure and will be handled by the policy. You can override this by
  *   specifying your own {@code handle} conditions. The default exception handling condition will only be overridden by
- *   another condition that handles failure exceptions such as {@link #handle(Class)} or {@link #handleIf(CheckedBiPredicate)}.
+ *   another condition that handles exceptions such as {@link #handle(Class)} or {@link #handleIf(CheckedBiPredicate)}.
  *   Specifying a condition that only handles results, such as {@link #handleResult(Object)} or
  *   {@link #handleResultIf(CheckedPredicate)} will not replace the default exception handling condition.</li>
- *   <li>If multiple {@code handle} conditions are specified, any condition that matches an execution result or failure
+ *   <li>If multiple {@code handle} conditions are specified, any condition that matches an execution result or exception
  *   will trigger policy handling.</li>
  * </ul>
  * <p>

core/src/main/java/dev/failsafe/DelayablePolicyBuilder.java

@@ -63,7 +63,7 @@ public S withDelay(Duration delay) {
    * <li>Any configured jitter is still applied to DelayFunction provided values
    * <li>Any configured max duration is still applied to DelayFunction provided values
    * <li>The {@link ExecutionContext} that is provided to the {@code delayFunction} may be {@code null} if the prior execution
-   * failure was manually recorded outside of a Failsafe execution.</li>
+   * exception was manually recorded outside of a Failsafe execution.</li>
    * </ul>
    * </p>
    *
@@ -78,7 +78,7 @@ public S withDelayFn(ContextualSupplier<R, Duration> delayFunction) {
 
   /**
    * Sets the {@code delayFunction} that computes the next delay before allowing another execution. Delays will only
-   * occur for failures that are assignable from the {@code failure}.
+   * occur for exceptions that are assignable from the {@code exception}.
    * <p>
    * The {@code delayFunction} must complete quickly, not have side-effects, and always return the same result for the
    * same input. Exceptions thrown by the {@code delayFunction} method will <strong>not</strong> be handled and will
@@ -91,20 +91,20 @@ public S withDelayFn(ContextualSupplier<R, Duration> delayFunction) {
    * <li>Any configured jitter is still applied to DelayFunction provided values
    * <li>Any configured max duration is still applied to DelayFunction provided values
    * <li>The {@link ExecutionContext} that is provided to the {@code delayFunction} may be {@code null} if the prior execution
-   * failure was manually recorded outside of a Failsafe execution.</li>
+   * exception was manually recorded outside of a Failsafe execution.</li>
    * </ul>
    * </p>
    *
    * @param delayFunction the function to use to compute the delay before a next attempt
-   * @param failure the execution failure that is expected in order to trigger the delay
-   * @param <F> failure type
-   * @throws NullPointerException if {@code delayFunction} or {@code failure} are null
+   * @param exception the execution exception that is expected in order to trigger the delay
+   * @param <F> exception type
+   * @throws NullPointerException if {@code delayFunction} or {@code exception} are null
    */
   @SuppressWarnings("unchecked")
-  public <F extends Throwable> S withDelayFnOn(ContextualSupplier<R, Duration> delayFunction, Class<F> failure) {
+  public <F extends Throwable> S withDelayFnOn(ContextualSupplier<R, Duration> delayFunction, Class<F> exception) {
     withDelayFn(delayFunction);
-    Assert.notNull(failure, "failure");
-    config.delayFailure = failure;
+    Assert.notNull(exception, "exception");
+    config.delayException = exception;
     return (S) this;
   }
 
@@ -123,7 +123,7 @@ public <F extends Throwable> S withDelayFnOn(ContextualSupplier<R, Duration> del
    * <li>Any configured jitter is still applied to DelayFunction provided values
    * <li>Any configured max duration is still applied to DelayFunction provided values
    * <li>The {@link ExecutionContext} that is provided to the {@code delayFunction} may be {@code null} if the prior execution
-   * failure was manually recorded outside of a Failsafe execution.</li>
+   * exception was manually recorded outside of a Failsafe execution.</li>
    * </ul>
    * </p>
    *

core/src/main/java/dev/failsafe/DelayablePolicyConfig.java

@@ -28,7 +28,7 @@
 public abstract class DelayablePolicyConfig<R> extends FailurePolicyConfig<R> {
   Duration delay;
   R delayResult;
-  Class<? extends Throwable> delayFailure;
+  Class<? extends Throwable> delayException;
   ContextualSupplier<R, Duration> delayFn;
 
   protected DelayablePolicyConfig() {
@@ -38,7 +38,7 @@ protected DelayablePolicyConfig(DelayablePolicyConfig<R> config) {
     super(config);
     delay = config.delay;
     delayResult = config.delayResult;
-    delayFailure = config.delayFailure;
+    delayException = config.delayException;
     delayFn = config.delayFn;
   }
 
@@ -67,8 +67,8 @@ public ContextualSupplier<R, Duration> getDelayFn() {
    *
    * @see DelayablePolicyBuilder#withDelayFnOn(ContextualSupplier, Class)
    */
-  public Class<? extends Throwable> getDelayFailure() {
-    return delayFailure;
+  public Class<? extends Throwable> getDelayException() {
+    return delayException;
   }
 
   /**

core/src/main/java/dev/failsafe/Execution.java

@@ -59,12 +59,12 @@ static <R> Execution<R> of(Policy<R> outerPolicy, Policy<R>... policies) {
   Duration getDelay();
 
   /**
-   * Records an execution {@code result} or {@code failure} which triggers failure handling, if needed, by the
+   * Records an execution {@code result} or {@code exception} which triggers failure handling, if needed, by the
    * configured policies. If policy handling is not possible or completed, the execution is completed.
    *
    * @throws IllegalStateException if the execution is already complete
    */
-  void record(R result, Throwable failure);
+  void record(R result, Throwable exception);
 
   /**
    * Records an execution {@code result} which triggers failure handling, if needed, by the configured policies. If
@@ -75,10 +75,16 @@ static <R> Execution<R> of(Policy<R> outerPolicy, Policy<R>... policies) {
   void recordResult(R result);
 
   /**
-   * Records an execution {@code failure} which triggers failure handling, if needed, by the configured policies. If
-   * policy handling is not possible or completed, the execution is completed.
+   * Records an {@code exception} which triggers failure handling, if needed, by the configured policies. If policy
+   * handling is not possible or completed, the execution is completed.
    *
    * @throws IllegalStateException if the execution is already complete
    */
+  void recordException(Throwable exception);
+
+  /**
+   * @deprecated Use {@link #recordException(Throwable)} instead
+   */
+  @Deprecated
   void recordFailure(Throwable failure);
 }

core/src/main/java/dev/failsafe/ExecutionContext.java

@@ -48,8 +48,14 @@ public interface ExecutionContext<R> {
   int getExecutionCount();
 
   /**
-   * Returns the last failure that was recorded else {@code null}.
+   * Returns the last exception that was recorded else {@code null}.
    */
+  <T extends Throwable> T getLastException();
+
+  /**
+   * @deprecated Use {@link #getLastException()} instead
+   */
+  @Deprecated
   <T extends Throwable> T getLastFailure();
 
   /**

core/src/main/java/dev/failsafe/ExecutionImpl.java

@@ -195,9 +195,15 @@ public int getExecutionCount() {
 
   @Override
   @SuppressWarnings("unchecked")
-  public <T extends Throwable> T getLastFailure() {
+  public <T extends Throwable> T getLastException() {
     ExecutionResult<R> r = result != null ? result : previousResult;
-    return r == null ? null : (T) r.getFailure();
+    return r == null ? null : (T) r.getException();
+  }
+
+  @Override
+  @Deprecated
+  public <T extends Throwable> T getLastFailure() {
+    return getLastException();
   }
 
   @Override
@@ -230,6 +236,6 @@ public boolean isRetry() {
   @Override
   public String toString() {
     return "[" + "attempts=" + attempts + ", executions=" + executions + ", lastResult=" + getLastResult()
-      + ", lastFailure=" + getLastFailure() + ']';
+      + ", lastException=" + getLastException() + ']';
   }
 }

core/src/main/java/dev/failsafe/FailsafeExecutor.java

@@ -106,7 +106,7 @@ public <P extends Policy<R>> FailsafeExecutor<R> compose(P innerPolicy) {
    *
    * @throws NullPointerException if the {@code supplier} is null
    * @throws FailsafeException if the {@code supplier} fails with a checked Exception. {@link
-   * FailsafeException#getCause()} can be used to learn the checked exception that caused the failure.
+   * FailsafeException#getCause()} can be used to learn the underlying checked exception
    * @throws TimeoutExceededException if the execution fails because a {@link Timeout} is exceeded.
    * @throws CircuitBreakerOpenException if the execution fails because a {@link CircuitBreaker} is open.
    * @throws RateLimitExceededException if the execution fails because a {@link RateLimiter} is exceeded.
@@ -120,7 +120,7 @@ public <T extends R> T get(CheckedSupplier<T> supplier) {
    *
    * @throws NullPointerException if the {@code supplier} is null
    * @throws FailsafeException if the {@code supplier} fails with a checked Exception. {@link
-   * FailsafeException#getCause()} can be used to learn the checked exception that caused the failure.
+   * FailsafeException#getCause()} can be used to learn the underlying checked exception
    * @throws TimeoutExceededException if the execution fails because a {@link Timeout} is exceeded.
    * @throws CircuitBreakerOpenException if the execution fails because a {@link CircuitBreaker} is open.
    * @throws RateLimitExceededException if the execution fails because a {@link RateLimiter} is exceeded.
@@ -173,8 +173,8 @@ public <T extends R> CompletableFuture<T> getAsync(ContextualSupplier<T, T> supp
    * Executes the {@code runnable} asynchronously until a successful result is recorded or the configured policies are
    * exceeded. Executions must be recorded via one of the {@code AsyncExecution.record} methods which will trigger
    * failure handling, if needed, by the configured policies, else the resulting {@link CompletableFuture} will be
-   * completed. Any exception that is thrown from the {@code runnable} will automatically be recorded via {@code
-   * AsyncExecution.recordFailure}.
+   * completed. Any exception that is thrown from the {@code runnable} will automatically be recorded via {@link
+   * AsyncExecution#recordException(Throwable)}.
    * </p>
    * <ul>
    *   <li>If the execution fails because a {@link Timeout} is exceeded, the resulting future is completed exceptionally
@@ -241,7 +241,7 @@ public <T extends R> CompletableFuture<T> getStageAsync(
    *
    * @throws NullPointerException if the {@code runnable} is null
    * @throws FailsafeException if the {@code runnable} fails with a checked Exception. {@link
-   * FailsafeException#getCause()} can be used to learn the checked exception that caused the failure.
+   * FailsafeException#getCause()} can be used to learn the underlying checked exception
    * @throws TimeoutExceededException if the execution fails because a {@link Timeout} is exceeded.
    * @throws CircuitBreakerOpenException if the execution fails because a {@link CircuitBreaker} is open.
    * @throws RateLimitExceededException if the execution fails because a {@link RateLimiter} is exceeded.
@@ -255,7 +255,7 @@ public void run(CheckedRunnable runnable) {
    *
    * @throws NullPointerException if the {@code runnable} is null
    * @throws FailsafeException if the {@code runnable} fails with a checked Exception. {@link
-   * FailsafeException#getCause()} can be used to learn the checked exception that caused the failure.
+   * FailsafeException#getCause()} can be used to learn the underlying checked exception
    * @throws TimeoutExceededException if the execution fails because a {@link Timeout} is exceeded.
    * @throws CircuitBreakerOpenException if the execution fails because a {@link CircuitBreaker} is open.
    * @throws RateLimitExceededException if the execution fails because a {@link RateLimiter} is exceeded.
@@ -306,8 +306,8 @@ public CompletableFuture<Void> runAsync(ContextualRunnable<Void> runnable) {
    * Executes the {@code runnable} asynchronously until a successful result is recorded or the configured policies are
    * exceeded. Executions must be recorded via one of the {@code AsyncExecution.record} methods which will trigger
    * failure handling, if needed, by the configured policies, else the resulting {@link CompletableFuture} will be
-   * completed. Any exception that is thrown from the {@code runnable} will automatically be recorded via {@code
-   * AsyncExecution.recordFailure}.
+   * completed. Any exception that is thrown from the {@code runnable} will automatically be recorded via {@link
+   * AsyncExecution#recordException(Throwable)}.
    * </p>
    * <ul>
    *   <li>If the execution fails because a {@link Timeout} is exceeded, the resulting future is completed exceptionally
@@ -436,13 +436,13 @@ public FailsafeExecutor<R> with(Scheduler scheduler) {
   private <T> T call(ContextualSupplier<T, T> innerSupplier) {
     SyncExecutionImpl<T> execution = new SyncExecutionImpl(this, scheduler, Functions.get(innerSupplier, executor));
     ExecutionResult<T> result = execution.executeSync();
-    Throwable failure = result.getFailure();
-    if (failure != null) {
-      if (failure instanceof RuntimeException)
-        throw (RuntimeException) failure;
-      if (failure instanceof Error)
-        throw (Error) failure;
-      throw new FailsafeException(failure);
+    Throwable exception = result.getException();
+    if (exception != null) {
+      if (exception instanceof RuntimeException)
+        throw (RuntimeException) exception;
+      if (exception instanceof Error)
+        throw (Error) exception;
+      throw new FailsafeException(exception);
     }
     return result.getResult();
   }