Introduce RetryListener#onRetryableExecution callback with RetryState

Closes gh-35940

Author: jhoeller

spring-core/src/main/java/org/springframework/core/retry/RetryException.java

@@ -17,6 +17,9 @@
 package org.springframework.core.retry;
 
 import java.io.Serial;
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.List;
 import java.util.Objects;
 
 /**
@@ -27,21 +30,16 @@
  * any exceptions from previous attempts as {@linkplain #getSuppressed() suppressed
  * exceptions}.
  *
- * <p>However, if an {@link InterruptedException} is encountered while
- * {@linkplain Thread#sleep(long) sleeping} for the current
- * {@link org.springframework.util.backoff.BackOff BackOff} duration, a
- * {@code RetryException} will contain the {@code InterruptedException} as the
- * {@linkplain #getCause() cause} and any exceptions from previous invocations
- * of the {@code Retryable} operation as {@linkplain #getSuppressed() suppressed
- * exceptions}.
+ * <p>Implements the {@link RetryState} interface for exposing the final outcome,
+ * as a parameter of the terminal listener methods on {@link RetryListener}.
  *
  * @author Mahmoud Ben Hassine
  * @author Juergen Hoeller
  * @author Sam Brannen
  * @since 7.0
  * @see RetryOperations
  */
-public class RetryException extends Exception {
+public class RetryException extends Exception implements RetryState {
 
 @Serial
 private static final long serialVersionUID = 1L;
@@ -50,14 +48,26 @@ public class RetryException extends Exception {
 /**
  * Create a new {@code RetryException} for the supplied message and cause.
  * @param message the detail message
- * @param cause the last exception thrown by the {@link Retryable} operation,
- * or an {@link InterruptedException} thrown while sleeping for the current
- * {@code BackOff} duration
+ * @param cause the last exception thrown by the {@link Retryable} operation
  */
 public RetryException(String message, Throwable cause) {
 super(message, Objects.requireNonNull(cause, "cause must not be null"));
 }
 
+/**
+ * Create a new {@code RetryException} for the supplied message and state.
+ * @param message the detail message
+ * @param retryState the final retry state
+ * @since 7.0.2
+ */
+RetryException(String message, RetryState retryState) {
+super(message, retryState.getLastException());
+List<Throwable> exceptions = retryState.getExceptions();
+for (int i = 0; i < exceptions.size() - 1; i++) {
+addSuppressed(exceptions.get(i));
+}
+}
+
 
 /**
  * Get the last exception thrown by the {@link Retryable} operation, or an
@@ -73,8 +83,31 @@ public final Throwable getCause() {
  * Return the number of retry attempts, or 0 if no retry has been attempted
  * after the initial invocation at all.
  */
+@Override
 public int getRetryCount() {
 return getSuppressed().length;
 }
 
+/**
+ * Return all invocation exceptions encountered, in the order of occurrence.
+ * @since 7.0.2
+ */
+@Override
+public List<Throwable> getExceptions() {
+Throwable[] suppressed = getSuppressed();
+List<Throwable> exceptions = new ArrayList<>(suppressed.length + 1);
+Collections.addAll(exceptions, suppressed);
+exceptions.add(getCause());
+return Collections.unmodifiableList(exceptions);
+}
+
+/**
+ * Return the exception from the last invocation (also exposed as a cause).
+ * @since 7.0.2
+ */
+@Override
+public Throwable getLastException() {
+return getCause();
+}
+
 }

spring-core/src/main/java/org/springframework/core/retry/RetryListener.java

@@ -33,6 +33,8 @@
  */
 public interface RetryListener {
 
+// Interception callbacks for retry attempts (not covering the initial invocation)
+
 /**
  * Called before every retry attempt.
  * @param retryPolicy the {@link RetryPolicy}
@@ -59,15 +61,35 @@ default void onRetrySuccess(RetryPolicy retryPolicy, Retryable<?> retryable, @Nu
 default void onRetryFailure(RetryPolicy retryPolicy, Retryable<?> retryable, Throwable throwable) {
 }
 
+
+// Execution callbacks for all invocation attempts and terminal scenarios
+
+/**
+ * Called after every attempt, including the initial invocation.
+ * <p>The success of the attempt can be checked via {@link RetryState#isSuccessful()};
+ * if not successful, the current exception can be introspected via
+ * {@link RetryState#getLastException()}.
+ * @param retryPolicy the {@link RetryPolicy}
+ * @param retryable the {@link Retryable} operation
+ * @param retryState the current state of retry processing
+ * (this is a live instance reflecting the current state; not intended to be stored)
+ * @since 7.0.2
+ * @see RetryTemplate#execute(Retryable)
+ * @see RetryState#isSuccessful()
+ * @see RetryState#getLastException()
+ * @see RetryState#getRetryCount()
+ */
+default void onRetryableExecution(RetryPolicy retryPolicy, Retryable<?> retryable, RetryState retryState) {
+}
+
 /**
  * Called if the {@link RetryPolicy} is exhausted.
  * @param retryPolicy the {@code RetryPolicy}
  * @param retryable the {@link Retryable} operation
  * @param exception the resulting {@link RetryException}, with the last
  * exception thrown by the {@code Retryable} operation as the cause and any
  * exceptions from previous attempts as suppressed exceptions
- * @see RetryException#getCause()
- * @see RetryException#getSuppressed()
+ * @see RetryException#getExceptions()
  * @see RetryException#getRetryCount()
  */
 default void onRetryPolicyExhaustion(RetryPolicy retryPolicy, Retryable<?> retryable, RetryException exception) {
@@ -80,8 +102,7 @@ default void onRetryPolicyExhaustion(RetryPolicy retryPolicy, Retryable<?> retry
  * @param exception the resulting {@link RetryException}, with an
  * {@link InterruptedException} as the cause and any exceptions from previous
  * invocations of the {@code Retryable} operation as suppressed exceptions
- * @see RetryException#getCause()
- * @see RetryException#getSuppressed()
+ * @see RetryException#getExceptions()
  * @see RetryException#getRetryCount()
  */
 default void onRetryPolicyInterruption(RetryPolicy retryPolicy, Retryable<?> retryable, RetryException exception) {
@@ -96,8 +117,7 @@ default void onRetryPolicyInterruption(RetryPolicy retryPolicy, Retryable<?> ret
  * exception thrown by the {@code Retryable} operation as the cause and any
  * exceptions from previous attempts as suppressed exceptions
  * @since 7.0.2
- * @see RetryException#getCause()
- * @see RetryException#getSuppressed()
+ * @see RetryException#getExceptions()
  * @see RetryException#getRetryCount()
  */
 default void onRetryPolicyTimeout(RetryPolicy retryPolicy, Retryable<?> retryable, RetryException exception) {

spring-core/src/main/java/org/springframework/core/retry/RetryState.java

@@ -0,0 +1,69 @@
+/*
+ * Copyright 2002-present 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
+ *
+ * https://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 org.springframework.core.retry;
+
+import java.util.List;
+
+/**
+ * A representation of the current retry state, including the
+ * current retry count and the exceptions accumulated so far.
+ *
+ * <p>Used as a parameter for {@link RetryListener#onRetryableExecution}.
+ * Implemented by {@link RetryException} as well, exposing the final outcome in
+ * the terminal listener methods {@link RetryListener#onRetryPolicyExhaustion},
+ * {@link RetryListener#onRetryPolicyInterruption} and
+ * {@link RetryListener#onRetryPolicyTimeout}.
+ *
+ * @author Juergen Hoeller
+ * @since 7.0.2
+ */
+public interface RetryState {
+
+/**
+ * Return the current retry count: 0 indicates the initial invocation,
+ * 1 the first retry attempt, etc.
+ * <p>This may indicate the current attempt or the final number of
+ * retry attempts, depending on the time of the method call.
+ */
+int getRetryCount();
+
+/**
+ * Return the invocation exceptions accumulated so far,
+ * in the order of occurrence.
+ */
+List<Throwable> getExceptions();
+
+/**
+ * Return the recorded exception from the last invocation.
+ * @throws IllegalStateException if no exception has been recorded
+ */
+default Throwable getLastException() {
+List<Throwable> exceptions = getExceptions();
+if (exceptions.isEmpty()) {
+throw new IllegalStateException("No exception recorded");
+}
+return exceptions.get(exceptions.size() - 1);
+}
+
+/**
+ * Indicate whether a successful invocation has been accomplished.
+ */
+default boolean isSuccessful() {
+return getRetryCount() >= getExceptions().size();
+}
+
+}