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 gh-35772

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

@@ -98,7 +98,7 @@ public class RetryAnnotationBeanPostProcessor extends AbstractBeanFactoryAwareAd
 			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 @@ public @interface Retryable {
 	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 abstract class AbstractRetryInterceptor implements MethodInterceptor {
 				.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 abstract class AbstractRetryInterceptor implements MethodInterceptor {
 				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 @@ import org.springframework.util.ExceptionTypeFilter;
  * @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);
 	}