Get rid of the separate policy listeners files for now.

Author: jhalterman

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

@@ -15,10 +15,10 @@
  */
 package dev.failsafe;
 
+import dev.failsafe.event.CircuitBreakerStateChangedEvent;
 import dev.failsafe.event.EventListener;
 import dev.failsafe.internal.CircuitBreakerImpl;
 import dev.failsafe.internal.util.Assert;
-import dev.failsafe.event.CircuitBreakerStateChangedEvent;
 
 import java.time.Duration;
 import java.util.function.BiPredicate;
@@ -51,7 +51,7 @@
  */
 public class CircuitBreakerBuilder<R>
   extends DelayablePolicyBuilder<CircuitBreakerBuilder<R>, CircuitBreakerConfig<R>, R>
-  implements CircuitBreakerListeners<CircuitBreakerBuilder<R>, R> {
+  implements PolicyListeners<CircuitBreakerBuilder<R>, R> {
 
   CircuitBreakerBuilder() {
     super(new CircuitBreakerConfig<>());
@@ -67,19 +67,34 @@ public CircuitBreaker<R> build() {
     return new CircuitBreakerImpl<>(new CircuitBreakerConfig<>(config));
   }
 
-  @Override
+  /**
+   * Calls the {@code listener} when the circuit is closed.
+   * <p>Note: Any exceptions that are thrown from within the {@code listener} are ignored.</p>
+   *
+   * @throws NullPointerException if {@code listener} is null
+   */
   public CircuitBreakerBuilder<R> onClose(EventListener<CircuitBreakerStateChangedEvent> listener) {
     config.closeListener = Assert.notNull(listener, "runnable");
     return this;
   }
 
-  @Override
+  /**
+   * Calls the {@code listener} when the circuit is half-opened.
+   * <p>Note: Any exceptions that are thrown within the {@code listener} are ignored.</p>
+   *
+   * @throws NullPointerException if {@code listener} is null
+   */
   public CircuitBreakerBuilder<R> onHalfOpen(EventListener<CircuitBreakerStateChangedEvent> listener) {
     config.halfOpenListener = Assert.notNull(listener, "runnable");
     return this;
   }
 
-  @Override
+  /**
+   * Calls the {@code listener} when the circuit is opened.
+   * <p>Note: Any exceptions that are thrown within the {@code listener} are ignored.</p>
+   *
+   * @throws NullPointerException if {@code listener} is null
+   */
   public CircuitBreakerBuilder<R> onOpen(EventListener<CircuitBreakerStateChangedEvent> listener) {
     config.openListener = Assert.notNull(listener, "listener");
     return this;

src/main/java/dev/failsafe/CircuitBreakerListeners.java

@@ -49,7 +49,7 @@
  * @see FallbackConfig
  */
 public class FallbackBuilder<R> extends FailurePolicyBuilder<FallbackBuilder<R>, FallbackConfig<R>, R>
-  implements FallbackListeners<FallbackBuilder<R>, R> {
+  implements PolicyListeners<FallbackBuilder<R>, R> {
 
   FallbackBuilder(CheckedFunction<ExecutionAttemptedEvent<R>, R> fallback,
     CheckedFunction<ExecutionAttemptedEvent<R>, CompletableFuture<R>> fallbackStage) {
@@ -65,7 +65,11 @@ public Fallback<R> build() {
     return new FallbackImpl<>(new FallbackConfig<>(config));
   }
 
-  @Override
+  /**
+   * Registers the {@code listener} to be called when the last execution attempt prior to the fallback failed. You can
+   * also use {@link #onFailure(EventListener) onFailure} to determine when the fallback attempt also fails.
+   * <p>Note: Any exceptions that are thrown from within the {@code listener} are ignored.</p>
+   */
   public FallbackBuilder<R> onFailedAttempt(EventListener<ExecutionAttemptedEvent<R>> listener) {
     config.failedAttemptListener = Assert.notNull(listener, "listener");
     return this;

src/main/java/dev/failsafe/FallbackBuilder.java

@@ -17,10 +17,10 @@
 
 import dev.failsafe.event.EventListener;
 import dev.failsafe.event.ExecutionAttemptedEvent;
-import dev.failsafe.internal.util.Assert;
 import dev.failsafe.event.ExecutionCompletedEvent;
 import dev.failsafe.event.ExecutionScheduledEvent;
 import dev.failsafe.internal.RetryPolicyImpl;
+import dev.failsafe.internal.util.Assert;
 
 import java.time.Duration;
 import java.time.temporal.ChronoUnit;
@@ -59,7 +59,7 @@
  * @see RetryPolicyConfig
  */
 public class RetryPolicyBuilder<R> extends DelayablePolicyBuilder<RetryPolicyBuilder<R>, RetryPolicyConfig<R>, R>
-  implements RetryPolicyListeners<RetryPolicyBuilder<R>, R> {
+  implements PolicyListeners<RetryPolicyBuilder<R>, R> {
 
   private static final int DEFAULT_MAX_RETRIES = 2;
 
@@ -159,31 +159,63 @@ public RetryPolicyBuilder<R> abortWhen(R result) {
     return this;
   }
 
-  @Override
+  /**
+   * Registers the {@code listener} to be called when an execution is aborted.
+   * <p>Note: Any exceptions that are thrown from within the {@code listener} are ignored. To provide an alternative
+   * result for a failed execution, use a {@link Fallback}.</p>
+   */
   public RetryPolicyBuilder<R> onAbort(EventListener<ExecutionCompletedEvent<R>> listener) {
     config.abortListener = Assert.notNull(listener, "listener");
     return this;
   }
 
-  @Override
+  /**
+   * Registers the {@code listener} to be called when an execution attempt fails. You can also use {@link
+   * #onFailure(EventListener) onFailure} to determine when the execution attempt fails <i>and</i> and all retries have
+   * failed.
+   * <p>Note: Any exceptions that are thrown from within the {@code listener} are ignored. To provide an alternative
+   * result for a failed execution, use a {@link Fallback}.</p>
+   */
   public RetryPolicyBuilder<R> onFailedAttempt(EventListener<ExecutionAttemptedEvent<R>> listener) {
     config.failedAttemptListener = Assert.notNull(listener, "listener");
     return this;
   }
 
-  @Override
+  /**
+   * Registers the {@code listener} to be called when an execution fails and the {@link
+   * RetryPolicyConfig#getMaxRetries() max retry attempts} or {@link RetryPolicyConfig#getMaxDuration() max duration}
+   * are exceeded.
+   * <p>Note: Any exceptions that are thrown from within the {@code listener} are ignored. To provide an alternative
+   * result for a failed execution, use a {@link Fallback}.</p>
+   */
   public RetryPolicyBuilder<R> onRetriesExceeded(EventListener<ExecutionCompletedEvent<R>> listener) {
     config.retriesExceededListener = Assert.notNull(listener, "listener");
     return this;
   }
 
-  @Override
+  /**
+   * Registers the {@code listener} to be called when a retry is about to be attempted.
+   * <p>Note: Any exceptions that are thrown from within the {@code listener} are ignored. To provide an alternative
+   * result for a failed execution, use a {@link Fallback}.</p>
+   *
+   * @see #onRetryScheduled(EventListener)
+   */
   public RetryPolicyBuilder<R> onRetry(EventListener<ExecutionAttemptedEvent<R>> listener) {
     config.retryListener = Assert.notNull(listener, "listener");
     return this;
   }
 
-  @Override
+  /**
+   * Registers the {@code listener} to be called when a retry for an async call is about to be scheduled. This method
+   * differs from {@link #onRetry(EventListener)} since it is called when a retry is initially scheduled but before any
+   * configured delay, whereas {@link #onRetry(EventListener) onRetry} is called after a delay, just before the retry
+   * attempt takes place.
+   * <p>
+   * <p>Note: Any exceptions that are thrown from within the {@code listener} are ignored. To provide an alternative
+   * result for a failed execution, use a {@link Fallback}.</p>
+   *
+   * @see #onRetry(EventListener)
+   */
   public RetryPolicyBuilder<R> onRetryScheduled(EventListener<ExecutionScheduledEvent<R>> listener) {
     config.retryScheduledListener = Assert.notNull(listener, "listener");
     return this;