Update event listener javadocs

Updates event listener javadocs to more clearly indicate that exceptions are suppressed, and that Fallbacks should be used to provide alternative results.

Author: jhalterman

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

@@ -35,7 +35,8 @@
  * <p>
  * Async executions are run by default on the {@link ForkJoinPool#commonPool()}. Alternative executors can be configured
  * via {@link #with(ScheduledExecutorService)} and similar methods. All async executions are cancellable and
- * interruptable via the returned CompletableFuture, even those run by a {@link ForkJoinPool} or {@link CompletionStage}.
+ * interruptable via the returned CompletableFuture, even those run by a {@link ForkJoinPool} or {@link
+ * CompletionStage}.
  *
  * @param <R> result type
  * @author Jonathan Halterman
@@ -292,7 +293,8 @@ public FailsafeExecutor<R> onComplete(CheckedConsumer<? extends ExecutionComplet
   /**
    * Registers the {@code listener} to be called when an execution fails. If multiple policies, are configured, this
    * handler is called when execution is complete and <i>any</i> policy fails.
-   * <p>Note: Any exceptions that are thrown from within the {@code listener} are ignored.</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>
    */
   @Override
   public FailsafeExecutor<R> onFailure(CheckedConsumer<? extends ExecutionCompletedEvent<R>> listener) {

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

@@ -36,6 +36,8 @@ public class PolicyListeners<S, R> {
    * Registers the {@code listener} to be called when a {@link Policy} fails to handle an execution. This means that not
    * only was the supplied execution considered a failure by the policy, but that the policy was unable to produce a
    * successful result.
+   * <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 S onFailure(CheckedConsumer<? extends ExecutionCompletedEvent<R>> listener) {
     failureListener = EventListener.of(Assert.notNull(listener, "listener"));
@@ -45,6 +47,7 @@ public S onFailure(CheckedConsumer<? extends ExecutionCompletedEvent<R>> listene
   /**
    * Registers the {@code listener} to be called when a {@link Policy} succeeds in handling an execution. This means
    * that the supplied execution either succeeded, or if it failed, the policy was able to produce a successful result.
+   * <p>Note: Any exceptions that are thrown from within the {@code listener} are ignored.</p>
    */
   public S onSuccess(CheckedConsumer<? extends ExecutionCompletedEvent<R>> listener) {
     successListener = EventListener.of(Assert.notNull(listener, "listener"));

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

@@ -223,7 +223,8 @@ public boolean isAbortable(R result, Throwable failure) {
 
   /**
    * 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.</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>
    */
   public RetryPolicy<R> onAbort(CheckedConsumer<? extends ExecutionCompletedEvent<R>> listener) {
     abortListener = EventListener.of(Assert.notNull(listener, "listener"));
@@ -234,7 +235,8 @@ public RetryPolicy<R> onAbort(CheckedConsumer<? extends ExecutionCompletedEvent<
    * Registers the {@code listener} to be called when an execution attempt fails. You can also use {@link
    * #onFailure(CheckedConsumer) 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.</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>
    */
   public RetryPolicy<R> onFailedAttempt(CheckedConsumer<? extends ExecutionAttemptedEvent<R>> listener) {
     failedAttemptListener = EventListener.ofAttempt(Assert.notNull(listener, "listener"));
@@ -244,7 +246,8 @@ public RetryPolicy<R> onFailedAttempt(CheckedConsumer<? extends ExecutionAttempt
   /**
    * Registers the {@code listener} to be called when an execution fails and the {@link RetryPolicy#withMaxRetries(int)
    * max retry attempts} or {@link RetryPolicy#withMaxDuration(Duration) max duration} are exceeded.
-   * <p>Note: Any exceptions that are thrown from within the {@code listener} are ignored.</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>
    */
   public RetryPolicy<R> onRetriesExceeded(CheckedConsumer<? extends ExecutionCompletedEvent<R>> listener) {
     retriesExceededListener = EventListener.of(Assert.notNull(listener, "listener"));
@@ -253,7 +256,8 @@ public RetryPolicy<R> onRetriesExceeded(CheckedConsumer<? extends ExecutionCompl
 
   /**
    * 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.</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>
    */
   public RetryPolicy<R> onRetry(CheckedConsumer<? extends ExecutionAttemptedEvent<R>> listener) {
     retryListener = EventListener.ofAttempt(Assert.notNull(listener, "listener"));
@@ -263,7 +267,8 @@ public RetryPolicy<R> onRetry(CheckedConsumer<? extends ExecutionAttemptedEvent<
   /**
    * Registers the {@code listener} to be called when a retry is about to be scheduled. A retry will actually be
    * performed after any scheduled delay.
-   * <p>Note: Any exceptions that are thrown from within the {@code listener} are ignored.</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>
    */
   public RetryPolicy<R> onRetryScheduled(CheckedConsumer<? extends ExecutionScheduledEvent<R>> listener) {
     retryScheduledListener = EventListener.ofScheduled(Assert.notNull(listener, "listener"));