From 3e5d8d184a3fe95e79cd8d5237930c05d974f5bf Mon Sep 17 00:00:00 2001
From: Juergen Hoeller <juergen.hoeller@broadcom.com>
Date: Fri, 9 Jan 2026 14:32:59 +0100
Subject: [PATCH] Clarify back-off attempts versus retries for BackOff
 maxAttempts setting

Closes gh-36119
---
 .../util/backoff/ExponentialBackOff.java      | 24 ++++++++++++-------
 .../util/backoff/FixedBackOff.java            | 12 +++++++---
 2 files changed, 24 insertions(+), 12 deletions(-)

diff --git a/spring-core/src/main/java/org/springframework/util/backoff/ExponentialBackOff.java b/spring-core/src/main/java/org/springframework/util/backoff/ExponentialBackOff.java
index c641f2887e0..8aefd231ea2 100644
--- a/spring-core/src/main/java/org/springframework/util/backoff/ExponentialBackOff.java
+++ b/spring-core/src/main/java/org/springframework/util/backoff/ExponentialBackOff.java
@@ -24,12 +24,12 @@ import org.springframework.util.Assert;
  * Implementation of {@link BackOff} that increases the back-off period for each attempt.
  * When the interval has reached the {@linkplain #setMaxInterval max interval}, it is no
  * longer increased. Stops once the {@linkplain #setMaxElapsedTime max elapsed time} or
- * {@linkplain #setMaxAttempts max attempts} has been reached.
+ * {@linkplain #setMaxAttempts max attempts} has been reached in back-off processing.
  *
  * <p>Example: The default interval is {@value #DEFAULT_INITIAL_INTERVAL} ms;
  * the default multiplier is {@value #DEFAULT_MULTIPLIER}; and the default max
- * interval is {@value #DEFAULT_MAX_INTERVAL}. For 10 attempts the sequence will be
- * as follows:
+ * interval is {@value #DEFAULT_MAX_INTERVAL}. For 10 back-off attempts, the
+ * sequence will be as follows:
  *
  * <pre>
  * request#     back-off
@@ -47,11 +47,13 @@ import org.springframework.util.Assert;
  * </pre>
  *
  * <p>Note that the default max elapsed time is {@link Long#MAX_VALUE}, and the
- * default maximum number of attempts is {@link Integer#MAX_VALUE}.
+ * default maximum number of back-off attempts is {@link Integer#MAX_VALUE}.
  * Use {@link #setMaxElapsedTime} to limit the length of time that an instance
- * should accumulate before returning {@link BackOffExecution#STOP}. Alternatively,
- * use {@link #setMaxAttempts} to limit the number of attempts. The execution
- * stops when either of those two limits is reached.
+ * should accumulate before returning {@link BackOffExecution#STOP}.
+ * Alternatively, use {@link #setMaxAttempts} to limit the number of back-off
+ * attempts (in a retry scenario, this is equivalent to the maximum number of
+ * retries in addition to the original invocation).
+ * The execution stops when either of those two limits is reached.
  *
  * @author Stephane Nicoll
  * @author Gary Russell
@@ -226,8 +228,10 @@ public class ExponentialBackOff implements BackOff {
 	}
 
 	/**
-	 * The maximum number of attempts after which a call to
+	 * The maximum number of back-off attempts after which a call to
 	 * {@link BackOffExecution#nextBackOff()} returns {@link BackOffExecution#STOP}.
+	 * <p>Note that in a retry scenario, this is equivalent to the maximum number
+	 * of retries in addition to the original invocation.
 	 * @param maxAttempts the maximum number of attempts
 	 * @since 6.1
 	 * @see #setMaxElapsedTime
@@ -237,8 +241,10 @@ public class ExponentialBackOff implements BackOff {
 	}
 
 	/**
-	 * Return the maximum number of attempts after which a call to
+	 * Return the maximum number of back-off attempts after which a call to
 	 * {@link BackOffExecution#nextBackOff()} returns {@link BackOffExecution#STOP}.
+	 * <p>Note that in a retry scenario, this is equivalent to the maximum number
+	 * of retries in addition to the original invocation.
 	 * @return the maximum number of attempts
 	 * @since 6.1
 	 * @see #getMaxElapsedTime()
diff --git a/spring-core/src/main/java/org/springframework/util/backoff/FixedBackOff.java b/spring-core/src/main/java/org/springframework/util/backoff/FixedBackOff.java
index e3197062b5a..33c16314034 100644
--- a/spring-core/src/main/java/org/springframework/util/backoff/FixedBackOff.java
+++ b/spring-core/src/main/java/org/springframework/util/backoff/FixedBackOff.java
@@ -18,7 +18,9 @@ package org.springframework.util.backoff;
 
 /**
  * A simple {@link BackOff} implementation that provides a fixed interval
- * between two attempts and a maximum number of retries.
+ * between two attempts and a maximum number of back-off attempts (in a
+ * retry scenario, this is equivalent to the maximum number of retries
+ * in addition to the original invocation).
  *
  * @author Stephane Nicoll
  * @author Sam Brannen
@@ -88,14 +90,18 @@ public class FixedBackOff implements BackOff {
 	}
 
 	/**
-	 * Set the maximum number of attempts.
+	 * Set the maximum number of back-off attempts.
+	 * <p>Note that in a retry scenario, this is equivalent to the maximum number
+	 * of retries in addition to the original invocation.
 	 */
 	public void setMaxAttempts(long maxAttempts) {
 		this.maxAttempts = maxAttempts;
 	}
 
 	/**
-	 * Return the maximum number of attempts.
+	 * Return the maximum number of back-off attempts.
+	 * <p>Note that in a retry scenario, this is equivalent to the maximum number
+	 * of retries in addition to the original invocation.
 	 */
 	public long getMaxAttempts() {
 		return this.maxAttempts;