Introduce retry interceptor and annotation-based retry support

Based on RetryTemplate with ExponentialBackOff.
Includes optional jitter support in ExponentialBackOff.
Supports reactive methods through Reactor's RetryBackoffSpec.

Closes gh-34529

Author: jhoeller

spring-aop/src/main/java/org/springframework/aop/retry/AbstractRetryInterceptor.java

@@ -0,0 +1,161 @@
+/*
+ * 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.aop.retry;
+
+import java.lang.reflect.Method;
+import java.time.Duration;
+
+import org.aopalliance.intercept.MethodInterceptor;
+import org.aopalliance.intercept.MethodInvocation;
+import org.jspecify.annotations.Nullable;
+import org.reactivestreams.Publisher;
+import reactor.core.publisher.Flux;
+import reactor.core.publisher.Mono;
+import reactor.util.retry.Retry;
+
+import org.springframework.core.ReactiveAdapter;
+import org.springframework.core.ReactiveAdapterRegistry;
+import org.springframework.core.retry.RetryException;
+import org.springframework.core.retry.RetryPolicy;
+import org.springframework.core.retry.RetryTemplate;
+import org.springframework.core.retry.Retryable;
+import org.springframework.util.ClassUtils;
+import org.springframework.util.backoff.ExponentialBackOff;
+
+/**
+ * Abstract retry interceptor implementation, adapting a given
+ * retry specification to either {@link RetryTemplate} or Reactor.
+ *
+ * @author Juergen Hoeller
+ * @since 7.0
+ * @see #getRetrySpec
+ * @see RetryTemplate
+ * @see Mono#retryWhen
+ * @see Flux#retryWhen
+ */
+public abstract class AbstractRetryInterceptor implements MethodInterceptor {
+
+	/**
+	 * Reactive Streams API present on the classpath?
+	 */
+	private static final boolean reactiveStreamsPresent = ClassUtils.isPresent(
+			"org.reactivestreams.Publisher", AbstractRetryInterceptor.class.getClassLoader());
+
+	private final @Nullable ReactiveAdapterRegistry reactiveAdapterRegistry;
+
+
+	public AbstractRetryInterceptor() {
+		if (reactiveStreamsPresent) {
+			this.reactiveAdapterRegistry = ReactiveAdapterRegistry.getSharedInstance();
+		}
+		else {
+			this.reactiveAdapterRegistry = null;
+		}
+	}
+
+
+	@Override
+	public @Nullable Object invoke(MethodInvocation invocation) throws Throwable {
+		Method method = invocation.getMethod();
+		Object target = invocation.getThis();
+		MethodRetrySpec spec = getRetrySpec(method, (target != null ? target.getClass() : method.getDeclaringClass()));
+
+		if (spec == null) {
+			return invocation.proceed();
+		}
+
+		if (this.reactiveAdapterRegistry != null) {
+			ReactiveAdapter adapter = this.reactiveAdapterRegistry.getAdapter(method.getReturnType());
+			if (adapter != null) {
+				Object result = invocation.proceed();
+				if (result == null) {
+					return null;
+				}
+				return ReactorDelegate.adaptReactiveResult(result, adapter, spec, method);
+			}
+		}
+
+		RetryTemplate retryTemplate = new RetryTemplate();
+
+		RetryPolicy.Builder policyBuilder = RetryPolicy.builder();
+		for (Class<? extends Throwable> include : spec.includes()) {
+			policyBuilder.includes(include);
+		}
+		for (Class<? extends Throwable> exclude : spec.excludes()) {
+			policyBuilder.excludes(exclude);
+		}
+		policyBuilder.predicate(spec.predicate().forMethod(method));
+		policyBuilder.maxAttempts(spec.maxAttempts());
+		retryTemplate.setRetryPolicy(policyBuilder.build());
+
+		ExponentialBackOff backOff = new ExponentialBackOff();
+		backOff.setInitialInterval(spec.delay());
+		backOff.setJitter(spec.jitterDelay());
+		backOff.setMultiplier(spec.delayMultiplier());
+		backOff.setMaxInterval(spec.maxDelay());
+		backOff.setMaxAttempts(spec.maxAttempts());
+		retryTemplate.setBackOffPolicy(backOff);
+
+		try {
+			return retryTemplate.execute(new Retryable<>() {
+				@Override
+				public @Nullable Object execute() throws Throwable {
+					return invocation.proceed();
+				}
+				@Override
+				public String getName() {
+					Object target = invocation.getThis();
+					return ClassUtils.getQualifiedMethodName(method, (target != null ? target.getClass() : null));
+				}
+			});
+		}
+		catch (RetryException ex) {
+			Throwable cause = ex.getCause();
+			throw (cause != null ? cause : new IllegalStateException(ex.getMessage(), ex));
+		}
+	}
+
+	/**
+	 * Determine the retry specification for the given method on the given target.
+	 * @param method the currently executing method
+	 * @param targetClass the class of the current target object
+	 * @return the retry specification as a {@link MethodRetrySpec}
+	 */
+	protected abstract @Nullable MethodRetrySpec getRetrySpec(Method method, Class<?> targetClass);
+
+
+	/**
+	 * Inner class to avoid a hard dependency on Reactive Streams and Reactor at runtime.
+	 */
+	private static class ReactorDelegate {
+
+		public static Object adaptReactiveResult(
+				Object result, ReactiveAdapter adapter, MethodRetrySpec spec, Method method) {
+
+			Publisher<?> publisher = adapter.toPublisher(result);
+			Retry retry = Retry.backoff(spec.maxAttempts(), Duration.ofMillis(spec.delay()))
+					.jitter((double) spec.jitterDelay() / spec.delay())
+					.multiplier(spec.delayMultiplier())
+					.maxBackoff(Duration.ofMillis(spec.maxDelay()))
+					.filter(spec.combinedPredicate().forMethod(method));
+			publisher = (adapter.isMultiValue() ? Flux.from(publisher).retryWhen(retry) :
+					Mono.from(publisher).retryWhen(retry));
+			return adapter.fromPublisher(publisher);
+		}
+	}
+
+}

spring-aop/src/main/java/org/springframework/aop/retry/MethodRetryPredicate.java

@@ -0,0 +1,48 @@
+/*
+ * 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.aop.retry;
+
+import java.lang.reflect.Method;
+import java.util.function.Predicate;
+
+/**
+ * Predicate for retrying a {@link Throwable} from a specific {@link Method}.
+ *
+ * @author Juergen Hoeller
+ * @since 7.0
+ * @see MethodRetrySpec#predicate()
+ */
+@FunctionalInterface
+public interface MethodRetryPredicate {
+
+	/**
+	 * Determine whether the given {@code Method} should be retried after
+	 * throwing the given {@code Throwable}.
+	 * @param method the method to potentially retry
+	 * @param throwable the exception encountered
+	 */
+	boolean shouldRetry(Method method, Throwable throwable);
+
+	/**
+	 * Build a {@code Predicate} for testing exceptions from a given method.
+	 * @param method the method to build a predicate for
+	 */
+	default Predicate<Throwable> forMethod(Method method) {
+		return (t -> shouldRetry(method, t));
+	}
+
+}

spring-aop/src/main/java/org/springframework/aop/retry/MethodRetrySpec.java

@@ -0,0 +1,88 @@
+/*
+ * 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.aop.retry;
+
+import java.util.Collection;
+import java.util.Collections;
+
+/**
+ * A specification for retry attempts on a given method, combining common
+ * retry characteristics. This roughly matches the annotation attributes
+ * on {@link org.springframework.aop.retry.annotation.Retryable}.
+ *
+ * @author Juergen Hoeller
+ * @since 7.0
+ * @param includes applicable exceptions types to attempt a retry for
+ * @param excludes non-applicable exceptions types to avoid a retry for
+ * @param predicate a predicate for filtering exceptions from applicable methods
+ * @param maxAttempts the maximum number of retry attempts
+ * @param delay the base delay after the initial invocation (in milliseconds)
+ * @param jitterDelay a jitter delay for the next retry attempt (in milliseconds)
+ * @param delayMultiplier a multiplier for a delay for the next retry attempt
+ * @param maxDelay the maximum delay for any retry attempt (in milliseconds)
+ * @see AbstractRetryInterceptor#getRetrySpec
+ * @see SimpleRetryInterceptor#SimpleRetryInterceptor(MethodRetrySpec)
+ * @see org.springframework.aop.retry.annotation.Retryable
+ */
+public record MethodRetrySpec(
+		Collection<Class<? extends Throwable>> includes,
+		Collection<Class<? extends Throwable>> excludes,
+		MethodRetryPredicate predicate,
+		int maxAttempts,
+		long delay,
+		long jitterDelay,
+		double delayMultiplier,
+		long maxDelay) {
+
+	public MethodRetrySpec(MethodRetryPredicate predicate, int maxAttempts, long delay) {
+		this(predicate, maxAttempts, delay, 0,1.0, Integer.MAX_VALUE);
+	}
+
+	public MethodRetrySpec(MethodRetryPredicate predicate, int maxAttempts, long delay,
+			long jitterDelay, double delayMultiplier, long maxDelay) {
+
+		this(Collections.emptyList(), Collections.emptyList(), predicate, maxAttempts, delay,
+				jitterDelay, delayMultiplier, maxDelay);
+	}
+
+
+	MethodRetryPredicate combinedPredicate() {
+		return (method, throwable) -> {
+			if (!this.excludes.isEmpty()) {
+				for (Class<? extends Throwable> exclude : this.excludes) {
+					if (exclude.isInstance(throwable)) {
+						return false;
+					}
+				}
+			}
+			if (!this.includes.isEmpty()) {
+				boolean included = false;
+				for (Class<? extends Throwable> include : this.includes) {
+					if (include.isInstance(throwable)) {
+						included = true;
+						break;
+					}
+				}
+				if (!included) {
+					return false;
+				}
+			}
+			return this.predicate.shouldRetry(method, throwable);
+		};
+	}
+
+}

spring-aop/src/main/java/org/springframework/aop/retry/SimpleRetryInterceptor.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.aop.retry;
+
+import java.lang.reflect.Method;
+
+/**
+ * A simple concrete retry interceptor based on a given {@link MethodRetrySpec}.
+ *
+ * @author Juergen Hoeller
+ * @since 7.0
+ */
+public class SimpleRetryInterceptor extends AbstractRetryInterceptor {
+
+	private final MethodRetrySpec retrySpec;
+
+
+	/**
+	 * Create a {@code SimpleRetryInterceptor} for the given {@link MethodRetrySpec}.
+	 * @param retrySpec the specification to use for all method invocations
+	 */
+	public SimpleRetryInterceptor(MethodRetrySpec retrySpec) {
+		this.retrySpec = retrySpec;
+	}
+
+	@Override
+	protected MethodRetrySpec getRetrySpec(Method method, Class<?> targetClass) {
+		return this.retrySpec;
+	}
+
+}

spring-aop/src/main/java/org/springframework/aop/retry/annotation/RetryAnnotationBeanPostProcessor.java

@@ -0,0 +1,46 @@
+/*
+ * 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.aop.retry.annotation;
+
+import org.springframework.aop.Pointcut;
+import org.springframework.aop.framework.autoproxy.AbstractBeanFactoryAwareAdvisingPostProcessor;
+import org.springframework.aop.support.ComposablePointcut;
+import org.springframework.aop.support.DefaultPointcutAdvisor;
+import org.springframework.aop.support.annotation.AnnotationMatchingPointcut;
+import org.springframework.beans.factory.config.BeanPostProcessor;
+
+/**
+ * A convenient {@link BeanPostProcessor} that applies {@link RetryAnnotationInterceptor}
+ * to all bean methods annotated with {@link Retryable} annotations.
+ *
+ * @author Juergen Hoeller
+ * @since 7.0
+ */
+@SuppressWarnings("serial")
+public class RetryAnnotationBeanPostProcessor extends AbstractBeanFactoryAwareAdvisingPostProcessor {
+
+	public RetryAnnotationBeanPostProcessor() {
+		setBeforeExistingAdvisors(true);
+
+		Pointcut cpc = new AnnotationMatchingPointcut(Retryable.class, true);
+		Pointcut mpc = new AnnotationMatchingPointcut(null, Retryable.class, true);
+		this.advisor = new DefaultPointcutAdvisor(
+				new ComposablePointcut(cpc).union(mpc),
+				new RetryAnnotationInterceptor());
+	}
+
+}