Rename maxAttempts to maxRetries in @⁠Retryable and RetryPolicy

Prior to this commit, the maximum number of retry attempts was
configured via @⁠Retryable(maxAttempts = ...),
RetryPolicy.withMaxAttempts(), and RetryPolicy.Builder.maxAttempts().
However, this led to confusion for developers who were unsure if
"max attempts" referred to the "total attempts" (i.e., initial attempt
plus retry attempts) or only the "retry attempts".

To improve the programming model, this commit renames maxAttempts to
maxRetries in @⁠Retryable and RetryPolicy.Builder and renames
RetryPolicy.withMaxAttempts() to RetryPolicy.withMaxRetries(). In
addition, this commit updates the documentation to consistently point
out that total attempts = 1 initial attempt + maxRetries attempts.

Closes spring-projectsgh-35772

Author: sbrannen

framework-docs/modules/ROOT/pages/core/resilience.adoc

@@ -23,8 +23,19 @@ public void sendNotification() {
 }
 ----
 
-By default, the method invocation will be retried for any exception thrown: with at most 3
-retry attempts after an initial failure, and a delay of 1 second between attempts.
+By default, the method invocation will be retried for any exception thrown: with at most
+3 retry attempts (`maxRetries = 3`) after an initial failure, and a delay of 1 second
+between attempts.
+
+[NOTE]
+====
+A `@Retryable` method will be invoked at least once and retried at most `maxRetries`
+times, where `maxRetries` is the maximum number of retry attempts. Specifically,
+`total attempts = 1 initial attempt + maxRetries attempts`.
+
+For example, if `maxRetries` is set to `4`, the `@Retryable` method will be invoked at
+least once and at most 5 times.
+====
 
 This can be specifically adapted for every method if necessary — for example, by narrowing
 the exceptions to retry via the `includes` and `excludes` attributes. The supplied
@@ -53,13 +64,13 @@ Custom predicates can be combined with `includes` and `excludes`; however, custo
 predicates will always be applied after `includes` and `excludes` have been applied.
 ====
 
-Or for 5 retry attempts and an exponential back-off strategy with a bit of jitter:
+Or for 4 retry attempts and an exponential back-off strategy with a bit of jitter:
 
 [source,java,indent=0,subs="verbatim,quotes"]
 ----
 @Retryable(
   includes = MessageDeliveryException.class,
-  maxAttempts = 5,
+  maxRetries = 4,
   delay = 100,
   jitter = 10,
   multiplier = 2,
@@ -74,7 +85,7 @@ type, decorating the pipeline with Reactor's retry capabilities:
 
 [source,java,indent=0,subs="verbatim,quotes"]
 ----
-@Retryable(maxAttempts = 5, delay = 100)
+@Retryable(maxRetries = 4, delay = 100)
 public Mono<Void> sendNotification() {
     return Mono.from(...); // <1>
 }
@@ -168,20 +179,31 @@ configured {spring-framework-api}/core/retry/RetryPolicy.html[`RetryPolicy`].
 ----
 <1> Implicitly uses `RetryPolicy.withDefaults()`.
 
-By default, a retryable operation will be retried for any exception thrown: with at most 3
-retry attempts after an initial failure, and a delay of 1 second between attempts.
+By default, a retryable operation will be retried for any exception thrown: with at most
+3 retry attempts (`maxRetries = 3`) after an initial failure, and a delay of 1 second
+between attempts.
 
 If you only need to customize the number of retry attempts, you can use the
-`RetryPolicy.withMaxAttempts()` factory method as demonstrated below.
+`RetryPolicy.withMaxRetries()` factory method as demonstrated below.
+
+[NOTE]
+====
+A retryable operation will be executed at least once and retried at most `maxRetries`
+times, where `maxRetries` is the maximum number of retry attempts. Specifically,
+`total attempts = 1 initial attempt + maxRetries attempts`.
+
+For example, if `maxRetries` is set to `4`, the retryable operation will be invoked at
+least once and at most 5 times.
+====
 
 [source,java,indent=0,subs="verbatim,quotes"]
 ----
-    var retryTemplate = new RetryTemplate(RetryPolicy.withMaxAttempts(5)); // <1>
+    var retryTemplate = new RetryTemplate(RetryPolicy.withMaxRetries(4)); // <1>
 
     retryTemplate.execute(
             () -> jmsClient.destination("notifications").send(...));
 ----
-<1> Explicitly uses `RetryPolicy.withMaxAttempts(5)`.
+<1> Explicitly uses `RetryPolicy.withMaxRetries(4)`.
 
 If you need to narrow the types of exceptions to retry, that can be achieved via the
 `includes()` and `excludes()` builder methods. The supplied exception types will be
@@ -213,14 +235,14 @@ Custom predicates can be combined with `includes` and `excludes`; however, custo
 predicates will always be applied after `includes` and `excludes` have been applied.
 ====
 
-The following example demonstrates how to configure a `RetryPolicy` with 5 retry attempts
+The following example demonstrates how to configure a `RetryPolicy` with 4 retry attempts
 and an exponential back-off strategy with a bit of jitter.
 
 [source,java,indent=0,subs="verbatim,quotes"]
 ----
     var retryPolicy = RetryPolicy.builder()
             .includes(MessageDeliveryException.class)
-            .maxAttempts(5)
+            .maxRetries(4)
             .delay(Duration.ofMillis(100))
             .jitter(Duration.ofMillis(10))
             .multiplier(2)

spring-context/src/main/java/org/springframework/resilience/annotation/RetryAnnotationBeanPostProcessor.java

@@ -98,7 +98,7 @@ private class RetryAnnotationInterceptor extends AbstractRetryInterceptor {
 			retrySpec = new MethodRetrySpec(
 					Arrays.asList(retryable.includes()), Arrays.asList(retryable.excludes()),
 					instantiatePredicate(retryable.predicate()),
-					parseLong(retryable.maxAttempts(), retryable.maxAttemptsString()),
+					parseLong(retryable.maxRetries(), retryable.maxRetriesString()),
 					parseDuration(retryable.delay(), retryable.delayString(), timeUnit),
 					parseDuration(retryable.jitter(), retryable.jitterString(), timeUnit),
 					parseDouble(retryable.multiplier(), retryable.multiplierString()),

spring-context/src/main/java/org/springframework/resilience/annotation/Retryable.java

@@ -106,18 +106,21 @@
 	Class<? extends MethodRetryPredicate> predicate() default MethodRetryPredicate.class;
 
 	/**
-	 * The maximum number of retry attempts, in addition to the initial invocation.
+	 * The maximum number of retry attempts.
+	 * <p>Note that {@code total attempts = 1 initial attempt + maxRetries attempts}.
+	 * Thus, if {@code maxRetries} is set to 4, the annotated method will be invoked
+	 * at least once and at most 5 times.
 	 * <p>The default is 3.
 	 */
-	long maxAttempts() default 3;
+	long maxRetries() default 3;
 
 	/**
 	 * The maximum number of retry attempts, as a configurable String.
-	 * <p>A non-empty value specified here overrides the {@link #maxAttempts()} attribute.
+	 * <p>A non-empty value specified here overrides the {@link #maxRetries()} attribute.
 	 * <p>This supports Spring-style "${...}" placeholders as well as SpEL expressions.
-	 * @see #maxAttempts()
+	 * @see #maxRetries()
 	 */
-	String maxAttemptsString() default "";
+	String maxRetriesString() default "";
 
 	/**
 	 * The base delay after the initial invocation. If a multiplier is specified,

spring-context/src/main/java/org/springframework/resilience/retry/AbstractRetryInterceptor.java

@@ -93,7 +93,7 @@ public AbstractRetryInterceptor() {
 				.includes(spec.includes())
 				.excludes(spec.excludes())
 				.predicate(spec.predicate().forMethod(method))
-				.maxAttempts(spec.maxAttempts())
+				.maxRetries(spec.maxRetries())
 				.delay(spec.delay())
 				.jitter(spec.jitter())
 				.multiplier(spec.multiplier())
@@ -137,7 +137,7 @@ public static Object adaptReactiveResult(
 				Object result, ReactiveAdapter adapter, MethodRetrySpec spec, Method method) {
 
 			Publisher<?> publisher = adapter.toPublisher(result);
-			Retry retry = Retry.backoff(spec.maxAttempts(), spec.delay())
+			Retry retry = Retry.backoff(spec.maxRetries(), spec.delay())
 					.jitter(calculateJitterFactor(spec))
 					.multiplier(spec.multiplier())
 					.maxBackoff(spec.maxDelay())

spring-context/src/main/java/org/springframework/resilience/retry/MethodRetrySpec.java

@@ -32,7 +32,7 @@
  * @param includes applicable exception types to attempt a retry for
  * @param excludes non-applicable exception 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 maxRetries the maximum number of retry attempts
  * @param delay the base delay after the initial invocation
  * @param jitter a jitter value for the next retry attempt
  * @param multiplier a multiplier for a delay for the next retry attempt
@@ -45,20 +45,20 @@ public record MethodRetrySpec(
 		Collection<Class<? extends Throwable>> includes,
 		Collection<Class<? extends Throwable>> excludes,
 		MethodRetryPredicate predicate,
-		long maxAttempts,
+		long maxRetries,
 		Duration delay,
 		Duration jitter,
 		double multiplier,
 		Duration maxDelay) {
 
-	public MethodRetrySpec(MethodRetryPredicate predicate, long maxAttempts, Duration delay) {
-		this(predicate, maxAttempts, delay, Duration.ZERO, 1.0, Duration.ofMillis(Long.MAX_VALUE));
+	public MethodRetrySpec(MethodRetryPredicate predicate, long maxRetries, Duration delay) {
+		this(predicate, maxRetries, delay, Duration.ZERO, 1.0, Duration.ofMillis(Long.MAX_VALUE));
 	}
 
-	public MethodRetrySpec(MethodRetryPredicate predicate, long maxAttempts, Duration delay,
+	public MethodRetrySpec(MethodRetryPredicate predicate, long maxRetries, Duration delay,
 			Duration jitter, double multiplier, Duration maxDelay) {
 
-		this(Collections.emptyList(), Collections.emptyList(), predicate, maxAttempts, delay,
+		this(Collections.emptyList(), Collections.emptyList(), predicate, maxRetries, delay,
 				jitter, multiplier, maxDelay);
 	}
 

spring-context/src/test/java/org/springframework/resilience/ReactiveRetryInterceptorTests.java

@@ -189,15 +189,15 @@ void withPostProcessorForClassWithMethodLevelOverride() {
 
 	@Test
 	void adaptReactiveResultWithMinimalRetrySpec() {
-		// Test minimal retry configuration: maxAttempts=1, delay=0, jitter=0, multiplier=1.0, maxDelay=0
+		// Test minimal retry configuration: maxRetries=1, delay=0, jitter=0, multiplier=1.0, maxDelay=0
 		MinimalRetryBean target = new MinimalRetryBean();
 		ProxyFactory pf = new ProxyFactory();
 		pf.setTarget(target);
 		pf.addAdvice(new SimpleRetryInterceptor(
 				new MethodRetrySpec((m, t) -> true, 1, Duration.ZERO, Duration.ZERO, 1.0, Duration.ZERO)));
 		MinimalRetryBean proxy = (MinimalRetryBean) pf.getProxy();
 
-		// Should execute only 2 times, because maxAttempts=1 means 1 call + 1 retry
+		// Should execute only 2 times, because maxRetries=1 means 1 call + 1 retry
 		assertThatIllegalStateException()
 				.isThrownBy(() -> proxy.retryOperation().block())
 				.satisfies(isRetryExhaustedException())
@@ -209,15 +209,15 @@ void adaptReactiveResultWithMinimalRetrySpec() {
 
 	@Test
 	void adaptReactiveResultWithZeroAttempts() {
-		// Test minimal retry configuration: maxAttempts=1, delay=0, jitter=0, multiplier=1.0, maxDelay=0
+		// Test minimal retry configuration: maxRetries=1, delay=0, jitter=0, multiplier=1.0, maxDelay=0
 		MinimalRetryBean target = new MinimalRetryBean();
 		ProxyFactory pf = new ProxyFactory();
 		pf.setTarget(target);
 		pf.addAdvice(new SimpleRetryInterceptor(
 				new MethodRetrySpec((m, t) -> true, 0, Duration.ZERO, Duration.ZERO, 1.0, Duration.ZERO)));
 		MinimalRetryBean proxy = (MinimalRetryBean) pf.getProxy();
 
-		// Should execute only 1 time, because maxAttempts=0 means initial call only
+		// Should execute only 1 time, because maxRetries=0 means initial call only
 		assertThatIllegalStateException()
 				.isThrownBy(() -> proxy.retryOperation().block())
 				.satisfies(isRetryExhaustedException())
@@ -302,7 +302,7 @@ void adaptReactiveResultWithSuccessfulOperation() {
 
 	@Test
 	void adaptReactiveResultWithAlwaysFailingOperation() {
-		// Test "always fails" case, ensuring retry mechanism stops after maxAttempts (3)
+		// Test "always fails" case, ensuring retry mechanism stops after maxRetries (3)
 		AlwaysFailsBean target = new AlwaysFailsBean();
 		ProxyFactory pf = new ProxyFactory();
 		pf.setTarget(target);
@@ -356,7 +356,7 @@ static class AnnotatedMethodBean {
 
 		AtomicInteger counter = new AtomicInteger();
 
-		@Retryable(maxAttempts = 5, delay = 10)
+		@Retryable(maxRetries = 5, delay = 10)
 		public Mono<Object> retryOperation() {
 			return Mono.fromCallable(() -> {
 				counter.incrementAndGet();
@@ -411,7 +411,7 @@ public Mono<Object> arithmeticOperation() {
 			});
 		}
 
-		@Retryable(includes = IOException.class, maxAttempts = 1, delay = 10)
+		@Retryable(includes = IOException.class, maxRetries = 1, delay = 10)
 		public Flux<Object> overrideOperation() {
 			return Flux.from(Mono.fromCallable(() -> {
 				counter.incrementAndGet();

spring-context/src/test/java/org/springframework/resilience/RetryInterceptorTests.java

@@ -218,7 +218,7 @@ void withPostProcessorForClassWithStrings() {
 		props.setProperty("jitter", "5");
 		props.setProperty("multiplier", "2.0");
 		props.setProperty("maxDelay", "40");
-		props.setProperty("limitedAttempts", "1");
+		props.setProperty("limitedRetries", "1");
 
 		GenericApplicationContext ctx = new GenericApplicationContext();
 		ctx.getEnvironment().getPropertySources().addFirst(new PropertiesPropertySource("props", props));
@@ -246,7 +246,7 @@ void withPostProcessorForClassWithZeroAttempts() {
 		props.setProperty("jitter", "5");
 		props.setProperty("multiplier", "2.0");
 		props.setProperty("maxDelay", "40");
-		props.setProperty("limitedAttempts", "0");
+		props.setProperty("limitedRetries", "0");
 
 		GenericApplicationContext ctx = new GenericApplicationContext();
 		ctx.getEnvironment().getPropertySources().addFirst(new PropertiesPropertySource("props", props));
@@ -321,7 +321,7 @@ static class AnnotatedMethodBean {
 
 		int counter = 0;
 
-		@Retryable(maxAttempts = 5, delay = 10)
+		@Retryable(maxRetries = 5, delay = 10)
 		public void retryOperation() throws IOException {
 			counter++;
 			throw new IOException(Integer.toString(counter));
@@ -333,7 +333,7 @@ static class AnnotatedMethodBeanWithInterface implements AnnotatedInterface {
 
 		int counter = 0;
 
-		@Retryable(maxAttempts = 5, delay = 10)
+		@Retryable(maxRetries = 5, delay = 10)
 		@Override
 		public void retryOperation() throws IOException {
 			counter++;
@@ -344,7 +344,7 @@ public void retryOperation() throws IOException {
 
 	interface AnnotatedInterface {
 
-		@Retryable(maxAttempts = 5, delay = 10)
+		@Retryable(maxRetries = 5, delay = 10)
 		void retryOperation() throws IOException;
 	}
 
@@ -374,7 +374,7 @@ public void otherOperation() throws IOException {
 			throw new AccessDeniedException(Integer.toString(counter));
 		}
 
-		@Retryable(value = IOException.class, maxAttempts = 1, delay = 10)
+		@Retryable(value = IOException.class, maxRetries = 1, delay = 10)
 		public void overrideOperation() throws IOException {
 			counter++;
 			throw new AccessDeniedException(Integer.toString(counter));
@@ -403,7 +403,7 @@ public void otherOperation() throws IOException {
 			throw new AccessDeniedException(Integer.toString(counter));
 		}
 
-		@Retryable(value = IOException.class, maxAttemptsString = "${limitedAttempts}", delayString = "10ms")
+		@Retryable(value = IOException.class, maxRetriesString = "${limitedRetries}", delayString = "10ms")
 		public void overrideOperation() throws IOException {
 			counter++;
 			throw new AccessDeniedException(Integer.toString(counter));
@@ -422,7 +422,7 @@ static class ConcurrencyLimitAnnotatedBean {
 		volatile String lastThreadName;
 
 		@ConcurrencyLimit(1)
-		@Retryable(maxAttempts = 2, delay = 10)
+		@Retryable(maxRetries = 2, delay = 10)
 		public void retryOperation() throws IOException, InterruptedException {
 			if (current.incrementAndGet() > 1) {
 				throw new IllegalStateException();
@@ -443,7 +443,7 @@ static class AsyncAnnotatedBean {
 		AtomicInteger counter = new AtomicInteger();
 
 		@Async
-		@Retryable(maxAttempts = 2, delay = 10)
+		@Retryable(maxRetries = 2, delay = 10)
 		public CompletableFuture<Void> retryOperation() {
 			throw new IllegalStateException(Integer.toString(counter.incrementAndGet()));
 		}