Introduce minimal retry functionality as a core framework feature

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

@@ -0,0 +1,45 @@
+/*
+ * Copyright 2002-2025 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;
+
+/**
+ * Callback interface for a retryable piece of code. Used in conjunction with {@link RetryOperations}.
+ *
+ * @author Mahmoud Ben Hassine
+ * @since 7.0
+ * @param <R> the type of the result
+ * @see RetryOperations
+ */
+@FunctionalInterface
+public interface RetryCallback<R> {
+
+	/**
+	 * Method to execute and retry if needed.
+	 * @return the result of the callback
+	 * @throws Throwable if an error occurs during the execution of the callback
+	 */
+	R run() throws Throwable;
+
+	/**
+	 * A unique logical name for this callback to distinguish retries around
+	 * business operations.
+	 * @return the name of the callback. Defaults to the class name.
+	 */
+	default String getName() {
+		return getClass().getName();
+	}
+}

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

@@ -0,0 +1,50 @@
+/*
+ * Copyright 2002-2025 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.io.Serial;
+
+/**
+ * Exception class for exhausted retries.
+ *
+ * @author Mahmoud Ben Hassine
+ * @since 7.0
+ * @see RetryOperations
+ */
+public class RetryException extends Exception {
+
+	@Serial
+	private static final long serialVersionUID = 5439915454935047936L;
+
+	/**
+	 * Create a new exception with a message.
+	 * @param message the exception's message
+	 */
+	public RetryException(String message) {
+		super(message);
+	}
+
+	/**
+	 * Create a new exception with a message and a cause.
+	 * @param message the exception's message
+	 * @param cause the exception's cause
+	 */
+	public RetryException(String message, Throwable cause) {
+		super(message, cause);
+	}
+
+}

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

@@ -0,0 +1,36 @@
+/*
+ * Copyright 2002-2025 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;
+
+/**
+ * Strategy interface to define a retry execution.
+ *
+ * <p>Implementations may be stateful but do not need to be thread-safe.
+ *
+ * @author Mahmoud Ben Hassine
+ * @since 7.0
+ */
+public interface RetryExecution {
+
+	/**
+	 * Specify if the operation should be retried based on the given throwable.
+	 * @param throwable the exception that caused the operation to fail
+	 * @return {@code true} if the operation should be retried, {@code false} otherwise
+	 */
+	boolean shouldRetry(Throwable throwable);
+
+}

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

@@ -0,0 +1,64 @@
+/*
+ * Copyright 2002-2025 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 org.springframework.core.retry.support.CompositeRetryListener;
+
+/**
+ * An extension point that allows to inject code during key retry phases.
+ *
+ * <p>Typically registered in a {@link RetryTemplate}, and can be composed using
+ * a {@link CompositeRetryListener}.
+ *
+ * @author Mahmoud Ben Hassine
+ * @since 7.0
+ * @see CompositeRetryListener
+ */
+public interface RetryListener {
+
+	/**
+	 * Called before every retry attempt.
+	 * @param retryExecution the retry execution
+	 */
+	default void beforeRetry(RetryExecution retryExecution) {
+	}
+
+	/**
+	 * Called after the first successful retry attempt.
+	 * @param retryExecution the retry execution
+	 * @param result the result of the callback
+	 */
+	default void onRetrySuccess(RetryExecution retryExecution, Object result) {
+	}
+
+	/**
+	 * Called every time a retry attempt fails.
+	 * @param retryExecution the retry execution
+	 * @param throwable the throwable thrown by the callback
+	 */
+	default void onRetryFailure(RetryExecution retryExecution, Throwable throwable) {
+	}
+
+	/**
+	 * Called once the retry policy is exhausted.
+	 * @param retryExecution the retry execution
+	 * @param throwable the last throwable thrown by the callback
+	 */
+	default void onRetryPolicyExhaustion(RetryExecution retryExecution, Throwable throwable) {
+	}
+
+}

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

@@ -0,0 +1,45 @@
+/*
+ * Copyright 2002-2025 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 org.jspecify.annotations.Nullable;
+
+/**
+ * Main entry point to the core retry functionality. Defines a set of retryable operations.
+ *
+ * <p>Implemented by {@link RetryTemplate}. Not often used directly, but a useful
+ * option to enhance testability, as it can easily be mocked or stubbed.
+ *
+ * @author Mahmoud Ben Hassine
+ * @since 7.0
+ * @see RetryTemplate
+ */
+public interface RetryOperations {
+
+	/**
+	 * Retry the given callback (according to the retry policy configured at the implementation level)
+	 * until it succeeds or eventually throw an exception if the retry policy is exhausted.
+	 * @param retryCallback the callback to call initially and retry if needed
+	 * @param <R> the type of the callback's result
+	 * @return the callback's result
+	 * @throws RetryException thrown if the retry policy is exhausted. All attempt exceptions
+	 * should be added as suppressed exceptions to the final exception.
+	 */
+	<R extends @Nullable Object> R execute(RetryCallback<R> retryCallback) throws RetryException;
+
+}
+

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

@@ -0,0 +1,33 @@
+/*
+ * Copyright 2002-2025 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;
+
+/**
+ * Strategy interface to define a retry policy.
+ *
+ * @author Mahmoud Ben Hassine
+ * @since 7.0
+ */
+public interface RetryPolicy {
+
+	/**
+	 * Start a new retry execution.
+	 * @return a fresh {@link RetryExecution} ready to be used
+	 */
+	RetryExecution start();
+
+}