From 30715238630d1db8d23187c75e94e3a61a458782 Mon Sep 17 00:00:00 2001 From: Chaitanya Bhorade Date: Tue, 18 Aug 2026 16:32:47 -0700 Subject: [PATCH 1/3] docs: clarify waitTimeout Javadoc in WaiterOverrideConfiguration.Builder Add a paragraph to WaiterOverrideConfiguration.Builder#waitTimeout(Duration) that explains the interaction between waitTimeout and maxAttempts. Customers frequently expect waitTimeout alone to extend a waiter's total wait time. Because services provide their own default maxAttempts (with no service default for waitTimeout), setting waitTimeout longer than the service-default budget (maxAttempts x delay-between-polls) causes the maxAttempts limit to terminate the waiter first (see #5838). The new paragraph: - explains that waitTimeout, when set, works alongside maxAttempts (which caps the number of polling attempts and has a service-provided default) - states that the waiter transitions to a failure state as soon as either limit is reached - directs customers wanting to extend the wait to override maxAttempts to increase the number of polling attempts or backoffStrategyV2 to lengthen the delay between polls The wording follows the "transitions to a failure state" phrasing already used in the sibling maxAttempts(Integer) Javadoc in the same file. No source-code / API changes. --- .../awssdk/core/waiters/WaiterOverrideConfiguration.java | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/core/sdk-core/src/main/java/software/amazon/awssdk/core/waiters/WaiterOverrideConfiguration.java b/core/sdk-core/src/main/java/software/amazon/awssdk/core/waiters/WaiterOverrideConfiguration.java index 8c3bab41fa6c..547479c60248 100644 --- a/core/sdk-core/src/main/java/software/amazon/awssdk/core/waiters/WaiterOverrideConfiguration.java +++ b/core/sdk-core/src/main/java/software/amazon/awssdk/core/waiters/WaiterOverrideConfiguration.java @@ -189,6 +189,11 @@ public Builder maxAttempts(Integer maxAttempts) { * timeout doesn't have strict guarantees on how quickly a request is aborted when the timeout is breached. The request * can timeout early if it is determined that the next retry will breach the max wait time. It's disabled by default. * + *

When set, {@code waitTimeout} works alongside {@link #maxAttempts(Integer)}, which caps the number of polling + * attempts and has a service-provided default. The waiter transitions to a failure state as soon as either limit + * is reached. To wait longer than the service-provided default, override {@link #maxAttempts(Integer)} to increase + * the number of polling attempts or {@link #backoffStrategyV2(BackoffStrategy)} to lengthen the delay between polls. + * * @param waitTimeout The new waitTimeout value. * @return This object for method chaining. */ From a1066e9b0fcb87c47f282cd47701780ba0eda04c Mon Sep 17 00:00:00 2001 From: Chaitanya Bhorade Date: Wed, 19 Aug 2026 11:55:26 -0700 Subject: [PATCH 2/3] docs: address review nits on WaiterOverrideConfiguration Javadoc - waitTimeout: reframe as upper bound; add concrete #5838 example (maxAttempts=100 x 6s -> waiter terminates at ~10 min even with waitTimeout=30 min) - maxAttempts: add reciprocal interaction note so both setters describe the two-limit stop-condition behavior No source-code / API changes. --- .../waiters/WaiterOverrideConfiguration.java | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) diff --git a/core/sdk-core/src/main/java/software/amazon/awssdk/core/waiters/WaiterOverrideConfiguration.java b/core/sdk-core/src/main/java/software/amazon/awssdk/core/waiters/WaiterOverrideConfiguration.java index 547479c60248..6180ff9d6152 100644 --- a/core/sdk-core/src/main/java/software/amazon/awssdk/core/waiters/WaiterOverrideConfiguration.java +++ b/core/sdk-core/src/main/java/software/amazon/awssdk/core/waiters/WaiterOverrideConfiguration.java @@ -176,6 +176,9 @@ public Builder backoffStrategyV2(BackoffStrategy backoffStrategy) { /** * Define the maximum number of attempts to try before transitioning the waiter to a failure state. * + *

{@code maxAttempts} works alongside {@link #waitTimeout(Duration)}, which, when set, acts as an upper bound + * on the total wait time. The waiter transitions to a failure state as soon as either limit is reached. + * * @param maxAttempts The new maxAttempts value. * @return This object for method chaining. */ @@ -189,10 +192,15 @@ public Builder maxAttempts(Integer maxAttempts) { * timeout doesn't have strict guarantees on how quickly a request is aborted when the timeout is breached. The request * can timeout early if it is determined that the next retry will breach the max wait time. It's disabled by default. * - *

When set, {@code waitTimeout} works alongside {@link #maxAttempts(Integer)}, which caps the number of polling - * attempts and has a service-provided default. The waiter transitions to a failure state as soon as either limit - * is reached. To wait longer than the service-provided default, override {@link #maxAttempts(Integer)} to increase - * the number of polling attempts or {@link #backoffStrategyV2(BackoffStrategy)} to lengthen the delay between polls. + *

When set, {@code waitTimeout} is an upper bound on the total wait time and works alongside {@link #maxAttempts(Integer)}, + * which caps the number of polling attempts (with a service-provided default). The waiter transitions to a failure + * state as soon as either limit is reached — the waiter may error out at the attempt limit before {@code waitTimeout} + * elapses. For example, if a service defines a default {@code maxAttempts=100} with a 6-second delay between polls, + * setting only {@code waitTimeout(Duration.ofMinutes(30))} still terminates the waiter at ~10 minutes because + * {@code maxAttempts} is reached first. + * + *

To wait longer than the service-provided default, override {@link #maxAttempts(Integer)} to increase the number + * of polling attempts or {@link #backoffStrategyV2(BackoffStrategy)} to lengthen the delay between polls. * * @param waitTimeout The new waitTimeout value. * @return This object for method chaining. From e269839dad9c779cc5282f040a9c8bbfe8cd3c1d Mon Sep 17 00:00:00 2001 From: Chaitanya Bhorade Date: Wed, 19 Aug 2026 21:51:57 -0700 Subject: [PATCH 3/3] docs: fix checkstyle line-length violation in waitTimeout Javadoc No content change. --- .../core/waiters/WaiterOverrideConfiguration.java | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/core/sdk-core/src/main/java/software/amazon/awssdk/core/waiters/WaiterOverrideConfiguration.java b/core/sdk-core/src/main/java/software/amazon/awssdk/core/waiters/WaiterOverrideConfiguration.java index 6180ff9d6152..7d3762f389ed 100644 --- a/core/sdk-core/src/main/java/software/amazon/awssdk/core/waiters/WaiterOverrideConfiguration.java +++ b/core/sdk-core/src/main/java/software/amazon/awssdk/core/waiters/WaiterOverrideConfiguration.java @@ -192,12 +192,12 @@ public Builder maxAttempts(Integer maxAttempts) { * timeout doesn't have strict guarantees on how quickly a request is aborted when the timeout is breached. The request * can timeout early if it is determined that the next retry will breach the max wait time. It's disabled by default. * - *

When set, {@code waitTimeout} is an upper bound on the total wait time and works alongside {@link #maxAttempts(Integer)}, - * which caps the number of polling attempts (with a service-provided default). The waiter transitions to a failure - * state as soon as either limit is reached — the waiter may error out at the attempt limit before {@code waitTimeout} - * elapses. For example, if a service defines a default {@code maxAttempts=100} with a 6-second delay between polls, - * setting only {@code waitTimeout(Duration.ofMinutes(30))} still terminates the waiter at ~10 minutes because - * {@code maxAttempts} is reached first. + *

When set, {@code waitTimeout} is an upper bound on the total wait time and works alongside + * {@link #maxAttempts(Integer)}, which caps the number of polling attempts (with a service-provided default). The + * waiter transitions to a failure state as soon as either limit is reached — the waiter may error out at the + * attempt limit before {@code waitTimeout} elapses. For example, if a service defines a default {@code maxAttempts=100} + * with a 6-second delay between polls, setting only {@code waitTimeout(Duration.ofMinutes(30))} still terminates the + * waiter at ~10 minutes because {@code maxAttempts} is reached first. * *

To wait longer than the service-provided default, override {@link #maxAttempts(Integer)} to increase the number * of polling attempts or {@link #backoffStrategyV2(BackoffStrategy)} to lengthen the delay between polls.