From ea94a9b7806fb10529e474f78d8b0265989e1e04 Mon Sep 17 00:00:00 2001 From: Lawrence Qiu Date: Tue, 18 Jul 2023 16:07:49 -0400 Subject: [PATCH 1/5] docs: Update RetrySettings to include LRO defaults --- .../api/gax/retrying/RetrySettings.java | 82 +++++++++++++++++++ 1 file changed, 82 insertions(+) diff --git a/gax-java/gax/src/main/java/com/google/api/gax/retrying/RetrySettings.java b/gax-java/gax/src/main/java/com/google/api/gax/retrying/RetrySettings.java index f5722f1ae9..7c21e0025f 100644 --- a/gax-java/gax/src/main/java/com/google/api/gax/retrying/RetrySettings.java +++ b/gax-java/gax/src/main/java/com/google/api/gax/retrying/RetrySettings.java @@ -66,6 +66,10 @@ *

Server streaming RPCs interpret RPC timeouts a bit differently. For server streaming RPCs, the * RPC timeout gets converted into a wait timeout {@link * com.google.api.gax.rpc.ApiCallContext#withStreamWaitTimeout(Duration)}. + * + *

In Cloud Client Libraries, Retry and LRO Retry Settings may be configured for each service and + * RPC. These values are set by the service teams and may be found by looking at the + * {Service}StubSettings.java file in each library. */ @AutoValue public abstract class RetrySettings implements Serializable { @@ -76,6 +80,9 @@ public abstract class RetrySettings implements Serializable { * TotalTimeout has ultimate control over how long the logic should keep trying the remote call * until it gives up completely. The higher the total timeout, the more retries can be attempted. * The default value is {@code Duration.ZERO}. + * + *

If there are no configurations, Retries have the default timeout value set above and LROs + * have a default total timeout value of {@code Duration.ofMillis(300000)} (5 minutes). */ public abstract Duration getTotalTimeout(); @@ -83,6 +90,10 @@ public abstract class RetrySettings implements Serializable { * InitialRetryDelay controls the delay before the first retry. Subsequent retries will use this * value adjusted according to the RetryDelayMultiplier. The default value is {@code * Duration.ZERO}. + * + *

If there are no configurations, Retries have the default initial retry delay value set above + * and LROs have a default initial poll delay value of {@code Duration.ofMillis(5000)} (5 + * seconds). */ public abstract Duration getInitialRetryDelay(); @@ -90,6 +101,9 @@ public abstract class RetrySettings implements Serializable { * RetryDelayMultiplier controls the change in retry delay. The retry delay of the previous call * is multiplied by the RetryDelayMultiplier to calculate the retry delay for the next call. The * default value is {@code 1.0}. + * + *

If there are no configurations, Retries have the default retry delay multiplier value set + * above and LROs have a default retry delay multiplier of {@code 1.5}. */ public abstract double getRetryDelayMultiplier(); @@ -97,6 +111,10 @@ public abstract class RetrySettings implements Serializable { * MaxRetryDelay puts a limit on the value of the retry delay, so that the RetryDelayMultiplier * can't increase the retry delay higher than this amount. The default value is {@code * Duration.ZERO}. + * + *

If there are no configurations, Retries have the default max retry delay value set above and + * LROs have a default max poll retry delay value of {@code Duration.ofMillis(45000)} (45 + * seconds). */ public abstract Duration getMaxRetryDelay(); @@ -104,6 +122,9 @@ public abstract class RetrySettings implements Serializable { * MaxAttempts defines the maximum number of attempts to perform. The default value is {@code 0}. * If this value is greater than 0, and the number of attempts reaches this limit, the logic will * give up retrying even if the total retry time is still lower than TotalTimeout. + * + *

If there are no configurations, Retries and LROs have the default max attempt value set + * above. LRO polling does not use this value by default. */ public abstract int getMaxAttempts(); @@ -125,6 +146,9 @@ public abstract class RetrySettings implements Serializable { * InitialRpcTimeout controls the timeout for the initial RPC. Subsequent calls will use this * value adjusted according to the RpcTimeoutMultiplier. The default value is {@code * Duration.ZERO}. + * + *

If there are no configurations, Retries have the default initial RPC timeout value set + * above. LRO polling does not use the Initial RPC Timeout value. */ public abstract Duration getInitialRpcTimeout(); @@ -132,6 +156,9 @@ public abstract class RetrySettings implements Serializable { * RpcTimeoutMultiplier controls the change in RPC timeout. The timeout of the previous call is * multiplied by the RpcTimeoutMultiplier to calculate the timeout for the next call. The default * value is {@code 1.0}. + * + *

If there are no configurations, Retries have the default RPC Timeout Multiplier value set + * above. LRO polling does not use the RPC Timeout Multiplier value. */ public abstract double getRpcTimeoutMultiplier(); @@ -139,6 +166,9 @@ public abstract class RetrySettings implements Serializable { * MaxRpcTimeout puts a limit on the value of the RPC timeout, so that the RpcTimeoutMultiplier * can't increase the RPC timeout higher than this amount. The default value is {@code * Duration.ZERO}. + * + *

If there are no configurations, Retries have the default Max RPC Timeout value set above. + * LRO polling does not use the Max RPC Timeout value. */ public abstract Duration getMaxRpcTimeout(); @@ -168,6 +198,9 @@ public abstract static class Builder { * TotalTimeout has ultimate control over how long the logic should keep trying the remote call * until it gives up completely. The higher the total timeout, the more retries can be * attempted. The default value is {@code Duration.ZERO}. + * + *

If there are no configurations, Retries have the default timeout value set above and LROs + * have a default total timeout value of {@code Duration.ofMillis(300000)} (5 minutes). */ public abstract Builder setTotalTimeout(Duration totalTimeout); @@ -175,6 +208,10 @@ public abstract static class Builder { * InitialRetryDelay controls the delay before the first retry. Subsequent retries will use this * value adjusted according to the RetryDelayMultiplier. The default value is {@code * Duration.ZERO}. + * + *

If there are no configurations, Retries have the default initial retry delay value set + * above and LROs have a default initial poll delay value of {@code Duration.ofMillis(5000)} (5 + * seconds). */ public abstract Builder setInitialRetryDelay(Duration initialDelay); @@ -182,6 +219,9 @@ public abstract static class Builder { * RetryDelayMultiplier controls the change in retry delay. The retry delay of the previous call * is multiplied by the RetryDelayMultiplier to calculate the retry delay for the next call. The * default value is {@code 1.0}. + * + *

If there are no configurations, Retries have the default retry delay multiplier value set + * above and LROs have a default retry delay multiplier of {@code 1.5}. */ public abstract Builder setRetryDelayMultiplier(double multiplier); @@ -189,6 +229,10 @@ public abstract static class Builder { * MaxRetryDelay puts a limit on the value of the retry delay, so that the RetryDelayMultiplier * can't increase the retry delay higher than this amount. The default value is {@code * Duration.ZERO}. + * + *

If there are no configurations, Retries have the default max retry delay value set above + * and LROs have a default max poll retry delay value of {@code Duration.ofMillis(45000)} (45 + * seconds). */ public abstract Builder setMaxRetryDelay(Duration maxDelay); @@ -196,6 +240,9 @@ public abstract static class Builder { * MaxAttempts defines the maximum number of attempts to perform. The default value is {@code * 0}. If this value is greater than 0, and the number of attempts reaches this limit, the logic * will give up retrying even if the total retry time is still lower than TotalTimeout. + * + *

If there are no configurations, Retries and LROs have the default max attempt value set + * above. LRO polling does not use this value by default. */ public abstract Builder setMaxAttempts(int maxAttempts); @@ -217,12 +264,18 @@ public abstract static class Builder { * InitialRpcTimeout controls the timeout for the initial RPC. Subsequent calls will use this * value adjusted according to the RpcTimeoutMultiplier. The default value is {@code * Duration.ZERO}. + * + *

If there are no configurations, Retries have the default initial RPC timeout value set + * above. LRO polling does not use the Initial RPC Timeout value. */ public abstract Builder setInitialRpcTimeout(Duration initialTimeout); /** * See the class documentation of {@link RetrySettings} for a description of what this value * does. The default value is {@code 1.0}. + * + *

If there are no configurations, Retries have the default RPC Timeout Multiplier value set + * above. LRO polling does not use the RPC Timeout Multiplier value. */ public abstract Builder setRpcTimeoutMultiplier(double multiplier); @@ -230,6 +283,9 @@ public abstract static class Builder { * MaxRpcTimeout puts a limit on the value of the RPC timeout, so that the RpcTimeoutMultiplier * can't increase the RPC timeout higher than this amount. The default value is {@code * Duration.ZERO}. + * + *

If there are no configurations, Retries have the default Max RPC Timeout value set above. + * LRO polling does not use the Max RPC Timeout value. */ public abstract Builder setMaxRpcTimeout(Duration maxTimeout); @@ -237,6 +293,9 @@ public abstract static class Builder { * TotalTimeout has ultimate control over how long the logic should keep trying the remote call * until it gives up completely. The higher the total timeout, the more retries can be * attempted. The default value is {@code Duration.ZERO}. + * + *

If there are no configurations, Retries have the default timeout value set above and LROs + * have a default total timeout value of {@code Duration.ofMillis(300000)} (5 minutes). */ public abstract Duration getTotalTimeout(); @@ -244,6 +303,10 @@ public abstract static class Builder { * InitialRetryDelay controls the delay before the first retry. Subsequent retries will use this * value adjusted according to the RetryDelayMultiplier. The default value is {@code * Duration.ZERO}. + * + *

If there are no configurations, Retries have the default initial retry delay value set + * above and LROs have a default initial poll delay value of {@code Duration.ofMillis(5000)} (5 + * seconds). */ public abstract Duration getInitialRetryDelay(); @@ -251,6 +314,9 @@ public abstract static class Builder { * RetryDelayMultiplier controls the change in retry delay. The retry delay of the previous call * is multiplied by the RetryDelayMultiplier to calculate the retry delay for the next call. The * default value is {@code 1.0}. + * + *

If there are no configurations, Retries have the default retry delay multiplier value set + * above and LROs have a default retry delay multiplier of {@code 1.5}. */ public abstract double getRetryDelayMultiplier(); @@ -258,6 +324,9 @@ public abstract static class Builder { * MaxAttempts defines the maximum number of attempts to perform. The default value is {@code * 0}. If this value is greater than 0, and the number of attempts reaches this limit, the logic * will give up retrying even if the total retry time is still lower than TotalTimeout. + * + *

If there are no configurations, Retries and LROs have the default max attempt value set + * above. LRO polling does not use this value by default. */ public abstract int getMaxAttempts(); @@ -275,6 +344,10 @@ public abstract static class Builder { * MaxRetryDelay puts a limit on the value of the retry delay, so that the RetryDelayMultiplier * can't increase the retry delay higher than this amount. The default value is {@code * Duration.ZERO}. + * + *

If there are no configurations, Retries have the default max retry delay value set above + * and LROs have a default max poll retry delay value of {@code Duration.ofMillis(45000)} (45 + * seconds). */ public abstract Duration getMaxRetryDelay(); @@ -282,18 +355,27 @@ public abstract static class Builder { * InitialRpcTimeout controls the timeout for the initial RPC. Subsequent calls will use this * value adjusted according to the RpcTimeoutMultiplier. The default value is {@code * Duration.ZERO}. + * + *

If there are no configurations, Retries have the default initial RPC timeout value set + * above. LRO polling does not use the Initial RPC Timeout value. */ public abstract Duration getInitialRpcTimeout(); /** * See the class documentation of {@link RetrySettings} for a description of what this value * does. The default value is {@code 1.0}. + * + *

If there are no configurations, Retries have the default RPC Timeout Multiplier value set + * above. LRO polling does not use the RPC Timeout Multiplier value. */ public abstract double getRpcTimeoutMultiplier(); /** * MaxRpcTimeout puts a limit on the value of the RPC timeout, so that the RpcTimeoutMultiplier * can't increase the RPC timeout higher than this amount. + * + *

If there are no configurations, Retries have the default Max RPC Timeout value set above. + * LRO polling does not use the Max RPC Timeout value. */ public abstract Duration getMaxRpcTimeout(); From bc419f7ae970458672d025ddeb5ae63a392b1af6 Mon Sep 17 00:00:00 2001 From: Lawrence Qiu Date: Tue, 18 Jul 2023 16:14:43 -0400 Subject: [PATCH 2/5] docs: Add poll verbiage to the docs --- .../api/gax/retrying/RetrySettings.java | 42 +++++++++---------- 1 file changed, 21 insertions(+), 21 deletions(-) diff --git a/gax-java/gax/src/main/java/com/google/api/gax/retrying/RetrySettings.java b/gax-java/gax/src/main/java/com/google/api/gax/retrying/RetrySettings.java index 7c21e0025f..7cf114fbe9 100644 --- a/gax-java/gax/src/main/java/com/google/api/gax/retrying/RetrySettings.java +++ b/gax-java/gax/src/main/java/com/google/api/gax/retrying/RetrySettings.java @@ -78,8 +78,8 @@ public abstract class RetrySettings implements Serializable { /** * TotalTimeout has ultimate control over how long the logic should keep trying the remote call - * until it gives up completely. The higher the total timeout, the more retries can be attempted. - * The default value is {@code Duration.ZERO}. + * until it gives up completely. The higher the total timeout, the more retries and polls can be + * attempted. The default value is {@code Duration.ZERO}. * *

If there are no configurations, Retries have the default timeout value set above and LROs * have a default total timeout value of {@code Duration.ofMillis(300000)} (5 minutes). @@ -87,8 +87,8 @@ public abstract class RetrySettings implements Serializable { public abstract Duration getTotalTimeout(); /** - * InitialRetryDelay controls the delay before the first retry. Subsequent retries will use this - * value adjusted according to the RetryDelayMultiplier. The default value is {@code + * InitialRetryDelay controls the delay before the first retry/ poll. Subsequent retries and polls + * will use this value adjusted according to the RetryDelayMultiplier. The default value is {@code * Duration.ZERO}. * *

If there are no configurations, Retries have the default initial retry delay value set above @@ -98,9 +98,9 @@ public abstract class RetrySettings implements Serializable { public abstract Duration getInitialRetryDelay(); /** - * RetryDelayMultiplier controls the change in retry delay. The retry delay of the previous call - * is multiplied by the RetryDelayMultiplier to calculate the retry delay for the next call. The - * default value is {@code 1.0}. + * RetryDelayMultiplier controls the change in delay before the next retry or poll. The retry + * delay of the previous call is multiplied by the RetryDelayMultiplier to calculate the retry + * delay for the next call. The default value is {@code 1.0}. * *

If there are no configurations, Retries have the default retry delay multiplier value set * above and LROs have a default retry delay multiplier of {@code 1.5}. @@ -196,7 +196,7 @@ public abstract static class Builder { /** * TotalTimeout has ultimate control over how long the logic should keep trying the remote call - * until it gives up completely. The higher the total timeout, the more retries can be + * until it gives up completely. The higher the total timeout, the more retries and polls can be * attempted. The default value is {@code Duration.ZERO}. * *

If there are no configurations, Retries have the default timeout value set above and LROs @@ -205,9 +205,9 @@ public abstract static class Builder { public abstract Builder setTotalTimeout(Duration totalTimeout); /** - * InitialRetryDelay controls the delay before the first retry. Subsequent retries will use this - * value adjusted according to the RetryDelayMultiplier. The default value is {@code - * Duration.ZERO}. + * InitialRetryDelay controls the delay before the first retry/ poll. Subsequent retries and + * polls will use this value adjusted according to the RetryDelayMultiplier. The default value + * is {@code Duration.ZERO}. * *

If there are no configurations, Retries have the default initial retry delay value set * above and LROs have a default initial poll delay value of {@code Duration.ofMillis(5000)} (5 @@ -216,9 +216,9 @@ public abstract static class Builder { public abstract Builder setInitialRetryDelay(Duration initialDelay); /** - * RetryDelayMultiplier controls the change in retry delay. The retry delay of the previous call - * is multiplied by the RetryDelayMultiplier to calculate the retry delay for the next call. The - * default value is {@code 1.0}. + * RetryDelayMultiplier controls the change in delay before the next retry or poll. The retry + * delay of the previous call is multiplied by the RetryDelayMultiplier to calculate the retry + * delay for the next call. The default value is {@code 1.0}. * *

If there are no configurations, Retries have the default retry delay multiplier value set * above and LROs have a default retry delay multiplier of {@code 1.5}. @@ -291,7 +291,7 @@ public abstract static class Builder { /** * TotalTimeout has ultimate control over how long the logic should keep trying the remote call - * until it gives up completely. The higher the total timeout, the more retries can be + * until it gives up completely. The higher the total timeout, the more retries and polls can be * attempted. The default value is {@code Duration.ZERO}. * *

If there are no configurations, Retries have the default timeout value set above and LROs @@ -300,9 +300,9 @@ public abstract static class Builder { public abstract Duration getTotalTimeout(); /** - * InitialRetryDelay controls the delay before the first retry. Subsequent retries will use this - * value adjusted according to the RetryDelayMultiplier. The default value is {@code - * Duration.ZERO}. + * InitialRetryDelay controls the delay before the first retry/ poll. Subsequent retries and + * polls will use this value adjusted according to the RetryDelayMultiplier. The default value + * is {@code Duration.ZERO}. * *

If there are no configurations, Retries have the default initial retry delay value set * above and LROs have a default initial poll delay value of {@code Duration.ofMillis(5000)} (5 @@ -311,9 +311,9 @@ public abstract static class Builder { public abstract Duration getInitialRetryDelay(); /** - * RetryDelayMultiplier controls the change in retry delay. The retry delay of the previous call - * is multiplied by the RetryDelayMultiplier to calculate the retry delay for the next call. The - * default value is {@code 1.0}. + * RetryDelayMultiplier controls the change in delay before the next retry or poll. The retry + * delay of the previous call is multiplied by the RetryDelayMultiplier to calculate the retry + * delay for the next call. The default value is {@code 1.0}. * *

If there are no configurations, Retries have the default retry delay multiplier value set * above and LROs have a default retry delay multiplier of {@code 1.5}. From 5df40aeabfb4bd221397eb5281540cae689b0b7f Mon Sep 17 00:00:00 2001 From: Lawrence Qiu Date: Tue, 18 Jul 2023 16:19:25 -0400 Subject: [PATCH 3/5] docs: Add info about Zero RPC timeout --- .../java/com/google/api/gax/retrying/RetrySettings.java | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/gax-java/gax/src/main/java/com/google/api/gax/retrying/RetrySettings.java b/gax-java/gax/src/main/java/com/google/api/gax/retrying/RetrySettings.java index 7cf114fbe9..0dc906b368 100644 --- a/gax-java/gax/src/main/java/com/google/api/gax/retrying/RetrySettings.java +++ b/gax-java/gax/src/main/java/com/google/api/gax/retrying/RetrySettings.java @@ -145,7 +145,8 @@ public abstract class RetrySettings implements Serializable { /** * InitialRpcTimeout controls the timeout for the initial RPC. Subsequent calls will use this * value adjusted according to the RpcTimeoutMultiplier. The default value is {@code - * Duration.ZERO}. + * Duration.ZERO}. RPC Timeout value of {@code Duration.ZERO} allows the RPC to continue + * indefinitely (until it hits a Connect Timeout or the connection has been terminated). * *

If there are no configurations, Retries have the default initial RPC timeout value set * above. LRO polling does not use the Initial RPC Timeout value. @@ -263,7 +264,8 @@ public abstract static class Builder { /** * InitialRpcTimeout controls the timeout for the initial RPC. Subsequent calls will use this * value adjusted according to the RpcTimeoutMultiplier. The default value is {@code - * Duration.ZERO}. + * Duration.ZERO}. RPC Timeout value of {@code Duration.ZERO} allows the RPC to continue + * indefinitely (until it hits a Connect Timeout or the connection has been terminated). * *

If there are no configurations, Retries have the default initial RPC timeout value set * above. LRO polling does not use the Initial RPC Timeout value. @@ -354,7 +356,8 @@ public abstract static class Builder { /** * InitialRpcTimeout controls the timeout for the initial RPC. Subsequent calls will use this * value adjusted according to the RpcTimeoutMultiplier. The default value is {@code - * Duration.ZERO}. + * Duration.ZERO}. RPC Timeout value of {@code Duration.ZERO} allows the RPC to continue + * indefinitely (until it hits a Connect Timeout or the connection has been terminated). * *

If there are no configurations, Retries have the default initial RPC timeout value set * above. LRO polling does not use the Initial RPC Timeout value. From 14973463983495c7eb386a0edfabfcac3fcf9359 Mon Sep 17 00:00:00 2001 From: Lawrence Qiu Date: Wed, 1 Nov 2023 17:01:28 -0400 Subject: [PATCH 4/5] docs: Update docs per PR feedback --- .../api/gax/retrying/RetrySettings.java | 218 ++++++++++-------- 1 file changed, 118 insertions(+), 100 deletions(-) diff --git a/gax-java/gax/src/main/java/com/google/api/gax/retrying/RetrySettings.java b/gax-java/gax/src/main/java/com/google/api/gax/retrying/RetrySettings.java index 0dc906b368..e592146ebc 100644 --- a/gax-java/gax/src/main/java/com/google/api/gax/retrying/RetrySettings.java +++ b/gax-java/gax/src/main/java/com/google/api/gax/retrying/RetrySettings.java @@ -79,52 +79,59 @@ public abstract class RetrySettings implements Serializable { /** * TotalTimeout has ultimate control over how long the logic should keep trying the remote call * until it gives up completely. The higher the total timeout, the more retries and polls can be - * attempted. The default value is {@code Duration.ZERO}. + * attempted. If this value is {@code Duration.ZERO}, then the logic will use the number of + * attempts to determine retries. In the event that both maxAttempts and TotalTimeout values are + * both 0, the logic will not retry. If this value is non-{@code Duration.ZERO}, and the retry + * duration has reaches the timeout value, the logic will give up retrying even the number of + * attempts is lower than the maxAttempts value. * - *

If there are no configurations, Retries have the default timeout value set above and LROs - * have a default total timeout value of {@code Duration.ofMillis(300000)} (5 minutes). + *

If there are no configurations, Retries have the default timeout value of {@code + * Duration.ZERO} and LROs have a default total timeout value of {@code Duration.ofMillis(300000)} + * (5 minutes). */ public abstract Duration getTotalTimeout(); /** * InitialRetryDelay controls the delay before the first retry/ poll. Subsequent retries and polls - * will use this value adjusted according to the RetryDelayMultiplier. The default value is {@code - * Duration.ZERO}. + * will use this value adjusted according to the RetryDelayMultiplier. * - *

If there are no configurations, Retries have the default initial retry delay value set above - * and LROs have a default initial poll delay value of {@code Duration.ofMillis(5000)} (5 - * seconds). + *

If there are no configurations, Retries have the default initial retry delay value of {@code + * Duration.ZERO} and LROs have a default initial poll delay value of {@code + * Duration.ofMillis(5000)} (5 seconds). */ public abstract Duration getInitialRetryDelay(); /** * RetryDelayMultiplier controls the change in delay before the next retry or poll. The retry * delay of the previous call is multiplied by the RetryDelayMultiplier to calculate the retry - * delay for the next call. The default value is {@code 1.0}. + * delay for the next call. * - *

If there are no configurations, Retries have the default retry delay multiplier value set - * above and LROs have a default retry delay multiplier of {@code 1.5}. + *

If there are no configurations, Retries have the default retry delay multiplier value of + * {@code 1.0} and LROs have a default retry delay multiplier of {@code 1.5}. */ public abstract double getRetryDelayMultiplier(); /** * MaxRetryDelay puts a limit on the value of the retry delay, so that the RetryDelayMultiplier - * can't increase the retry delay higher than this amount. The default value is {@code - * Duration.ZERO}. + * can't increase the retry delay higher than this amount. * - *

If there are no configurations, Retries have the default max retry delay value set above and - * LROs have a default max poll retry delay value of {@code Duration.ofMillis(45000)} (45 - * seconds). + *

If there are no configurations, Retries have the default max retry delay value of {@code + * Duration.ZERO} and LROs have a default max poll retry delay value of {@code + * Duration.ofMillis(45000)} (45 seconds). */ public abstract Duration getMaxRetryDelay(); /** - * MaxAttempts defines the maximum number of attempts to perform. The default value is {@code 0}. - * If this value is greater than 0, and the number of attempts reaches this limit, the logic will - * give up retrying even if the total retry time is still lower than TotalTimeout. + * MaxAttempts defines the maximum number of attempts to perform. If this value is set to 0, the + * logic will use the totalTimeout value to determine retries. In the event that both the + * maxAttempts and TotalTimeout values are both 0, the logic will not retry. If this value is + * greater than 0, and the number of attempts reaches this limit, the logic will give up retrying + * even if the total retry time is still lower than TotalTimeout. * - *

If there are no configurations, Retries and LROs have the default max attempt value set - * above. LRO polling does not use this value by default. + *

If there are no configurations, Retries and LROs have the default max attempt value of + * {@code 0}. LRO polling does not use this value by default. + * + *

The first attempt will be considered attempt #0. */ public abstract int getMaxAttempts(); @@ -144,32 +151,30 @@ public abstract class RetrySettings implements Serializable { /** * InitialRpcTimeout controls the timeout for the initial RPC. Subsequent calls will use this - * value adjusted according to the RpcTimeoutMultiplier. The default value is {@code - * Duration.ZERO}. RPC Timeout value of {@code Duration.ZERO} allows the RPC to continue - * indefinitely (until it hits a Connect Timeout or the connection has been terminated). + * value adjusted according to the RpcTimeoutMultiplier. RPC Timeout value of {@code + * Duration.ZERO} allows the RPC to continue indefinitely (until it hits a Connect Timeout or the + * connection has been terminated). * - *

If there are no configurations, Retries have the default initial RPC timeout value set - * above. LRO polling does not use the Initial RPC Timeout value. + *

If there are no configurations, Retries have the default initial RPC timeout value of {@code + * Duration.ZERO}. LRO polling does not use the Initial RPC Timeout value. */ public abstract Duration getInitialRpcTimeout(); /** * RpcTimeoutMultiplier controls the change in RPC timeout. The timeout of the previous call is - * multiplied by the RpcTimeoutMultiplier to calculate the timeout for the next call. The default - * value is {@code 1.0}. + * multiplied by the RpcTimeoutMultiplier to calculate the timeout for the next call. * - *

If there are no configurations, Retries have the default RPC Timeout Multiplier value set - * above. LRO polling does not use the RPC Timeout Multiplier value. + *

If there are no configurations, Retries have the default RPC Timeout Multiplier value of + * {@code 1.0}. LRO polling does not use the RPC Timeout Multiplier value. */ public abstract double getRpcTimeoutMultiplier(); /** * MaxRpcTimeout puts a limit on the value of the RPC timeout, so that the RpcTimeoutMultiplier - * can't increase the RPC timeout higher than this amount. The default value is {@code - * Duration.ZERO}. + * can't increase the RPC timeout higher than this amount. * - *

If there are no configurations, Retries have the default Max RPC Timeout value set above. - * LRO polling does not use the Max RPC Timeout value. + *

If there are no configurations, Retries have the default Max RPC Timeout value of {@code + * Duration.ZERO}. LRO polling does not use the Max RPC Timeout value. */ public abstract Duration getMaxRpcTimeout(); @@ -198,52 +203,59 @@ public abstract static class Builder { /** * TotalTimeout has ultimate control over how long the logic should keep trying the remote call * until it gives up completely. The higher the total timeout, the more retries and polls can be - * attempted. The default value is {@code Duration.ZERO}. + * attempted. If this value is {@code Duration.ZERO}, then the logic will use the number of + * attempts to determine retries. In the event that both maxAttempts and TotalTimeout values are + * both 0, the logic will not retry. If this value is non-{@code Duration.ZERO}, and the retry + * duration has reaches the timeout value, the logic will give up retrying even the number of + * attempts is lower than the maxAttempts value. * - *

If there are no configurations, Retries have the default timeout value set above and LROs - * have a default total timeout value of {@code Duration.ofMillis(300000)} (5 minutes). + *

If there are no configurations, Retries have the default timeout value of {@code + * Duration.ZERO} and LROs have a default total timeout value of {@code + * Duration.ofMillis(300000)} (5 minutes). */ public abstract Builder setTotalTimeout(Duration totalTimeout); /** * InitialRetryDelay controls the delay before the first retry/ poll. Subsequent retries and - * polls will use this value adjusted according to the RetryDelayMultiplier. The default value - * is {@code Duration.ZERO}. + * polls will use this value adjusted according to the RetryDelayMultiplier. * - *

If there are no configurations, Retries have the default initial retry delay value set - * above and LROs have a default initial poll delay value of {@code Duration.ofMillis(5000)} (5 - * seconds). + *

If there are no configurations, Retries have the default initial retry delay value of + * {@code Duration.ZERO} and LROs have a default initial poll delay value of {@code + * Duration.ofMillis(5000)} (5 seconds). */ public abstract Builder setInitialRetryDelay(Duration initialDelay); /** * RetryDelayMultiplier controls the change in delay before the next retry or poll. The retry * delay of the previous call is multiplied by the RetryDelayMultiplier to calculate the retry - * delay for the next call. The default value is {@code 1.0}. + * delay for the next call. * - *

If there are no configurations, Retries have the default retry delay multiplier value set - * above and LROs have a default retry delay multiplier of {@code 1.5}. + *

If there are no configurations, Retries have the default retry delay multiplier value of + * {@code 1.0} and LROs have a default retry delay multiplier of {@code 1.5}. */ public abstract Builder setRetryDelayMultiplier(double multiplier); /** * MaxRetryDelay puts a limit on the value of the retry delay, so that the RetryDelayMultiplier - * can't increase the retry delay higher than this amount. The default value is {@code - * Duration.ZERO}. + * can't increase the retry delay higher than this amount. * - *

If there are no configurations, Retries have the default max retry delay value set above - * and LROs have a default max poll retry delay value of {@code Duration.ofMillis(45000)} (45 - * seconds). + *

If there are no configurations, Retries have the default max retry delay value of {@code + * Duration.ZERO} and LROs have a default max poll retry delay value of {@code + * Duration.ofMillis(45000)} (45 seconds). */ public abstract Builder setMaxRetryDelay(Duration maxDelay); /** - * MaxAttempts defines the maximum number of attempts to perform. The default value is {@code - * 0}. If this value is greater than 0, and the number of attempts reaches this limit, the logic - * will give up retrying even if the total retry time is still lower than TotalTimeout. + * MaxAttempts defines the maximum number of attempts to perform. If this value is set to 0, the + * logic will use the totalTimeout value to determine retries. In the event that both the + * maxAttempts and TotalTimeout values are both 0, the logic will not retry. If this value is + * greater than 0, and the number of attempts reaches this limit, the logic will give up + * retrying even if the total retry time is still lower than TotalTimeout. + * + *

If there are no configurations, Retries and LROs have the default max attempt value of + * {@code 0}. LRO polling does not use this value by default. * - *

If there are no configurations, Retries and LROs have the default max attempt value set - * above. LRO polling does not use this value by default. + *

The first attempt will be considered attempt #0. */ public abstract Builder setMaxAttempts(int maxAttempts); @@ -263,72 +275,79 @@ public abstract static class Builder { /** * InitialRpcTimeout controls the timeout for the initial RPC. Subsequent calls will use this - * value adjusted according to the RpcTimeoutMultiplier. The default value is {@code - * Duration.ZERO}. RPC Timeout value of {@code Duration.ZERO} allows the RPC to continue - * indefinitely (until it hits a Connect Timeout or the connection has been terminated). + * value adjusted according to the RpcTimeoutMultiplier. RPC Timeout value of {@code + * Duration.ZERO} allows the RPC to continue indefinitely (until it hits a Connect Timeout or + * the connection has been terminated). * - *

If there are no configurations, Retries have the default initial RPC timeout value set - * above. LRO polling does not use the Initial RPC Timeout value. + *

If there are no configurations, Retries have the default initial RPC timeout value of + * {@code Duration.ZERO}. LRO polling does not use the Initial RPC Timeout value. */ public abstract Builder setInitialRpcTimeout(Duration initialTimeout); /** - * See the class documentation of {@link RetrySettings} for a description of what this value - * does. The default value is {@code 1.0}. + * RpcTimeoutMultiplier controls the change in RPC timeout. The timeout of the previous call is + * multiplied by the RpcTimeoutMultiplier to calculate the timeout for the next call. * - *

If there are no configurations, Retries have the default RPC Timeout Multiplier value set - * above. LRO polling does not use the RPC Timeout Multiplier value. + *

If there are no configurations, Retries have the default RPC Timeout Multiplier value of + * {@code 1.0}. LRO polling does not use the RPC Timeout Multiplier value. */ public abstract Builder setRpcTimeoutMultiplier(double multiplier); /** * MaxRpcTimeout puts a limit on the value of the RPC timeout, so that the RpcTimeoutMultiplier - * can't increase the RPC timeout higher than this amount. The default value is {@code - * Duration.ZERO}. + * can't increase the RPC timeout higher than this amount. * - *

If there are no configurations, Retries have the default Max RPC Timeout value set above. - * LRO polling does not use the Max RPC Timeout value. + *

If there are no configurations, Retries have the default Max RPC Timeout value of {@code + * Duration.ZERO}. LRO polling does not use the Max RPC Timeout value. */ public abstract Builder setMaxRpcTimeout(Duration maxTimeout); /** * TotalTimeout has ultimate control over how long the logic should keep trying the remote call * until it gives up completely. The higher the total timeout, the more retries and polls can be - * attempted. The default value is {@code Duration.ZERO}. + * attempted. If this value is {@code Duration.ZERO}, then the logic will use the number of + * attempts to determine retries. In the event that both maxAttempts and TotalTimeout values are + * both 0, the logic will not retry. If this value is non-{@code Duration.ZERO}, and the retry + * duration has reaches the timeout value, the logic will give up retrying even the number of + * attempts is lower than the maxAttempts value. * - *

If there are no configurations, Retries have the default timeout value set above and LROs - * have a default total timeout value of {@code Duration.ofMillis(300000)} (5 minutes). + *

If there are no configurations, Retries have the default timeout value of {@code + * Duration.ZERO} and LROs have a default total timeout value of {@code + * Duration.ofMillis(300000)} (5 minutes). */ public abstract Duration getTotalTimeout(); /** * InitialRetryDelay controls the delay before the first retry/ poll. Subsequent retries and - * polls will use this value adjusted according to the RetryDelayMultiplier. The default value - * is {@code Duration.ZERO}. + * polls will use this value adjusted according to the RetryDelayMultiplier. * - *

If there are no configurations, Retries have the default initial retry delay value set - * above and LROs have a default initial poll delay value of {@code Duration.ofMillis(5000)} (5 - * seconds). + *

If there are no configurations, Retries have the default initial retry delay value of + * {@code Duration.ZERO} and LROs have a default initial poll delay value of {@code + * Duration.ofMillis(5000)} (5 seconds). */ public abstract Duration getInitialRetryDelay(); /** * RetryDelayMultiplier controls the change in delay before the next retry or poll. The retry * delay of the previous call is multiplied by the RetryDelayMultiplier to calculate the retry - * delay for the next call. The default value is {@code 1.0}. + * delay for the next call. * - *

If there are no configurations, Retries have the default retry delay multiplier value set - * above and LROs have a default retry delay multiplier of {@code 1.5}. + *

If there are no configurations, Retries have the default retry delay multiplier value of + * {@code 1.0} and LROs have a default retry delay multiplier of {@code 1.5}. */ public abstract double getRetryDelayMultiplier(); /** - * MaxAttempts defines the maximum number of attempts to perform. The default value is {@code - * 0}. If this value is greater than 0, and the number of attempts reaches this limit, the logic - * will give up retrying even if the total retry time is still lower than TotalTimeout. + * MaxAttempts defines the maximum number of attempts to perform. If this value is set to 0, the + * logic will use the totalTimeout value to determine retries. In the event that both the + * maxAttempts and TotalTimeout values are both 0, the logic will not retry. If this value is + * greater than 0, and the number of attempts reaches this limit, the logic will give up + * retrying even if the total retry time is still lower than TotalTimeout. + * + *

If there are no configurations, Retries and LROs have the default max attempt value of + * {@code 0}. LRO polling does not use this value by default. * - *

If there are no configurations, Retries and LROs have the default max attempt value set - * above. LRO polling does not use this value by default. + *

The first attempt will be considered attempt #0. */ public abstract int getMaxAttempts(); @@ -344,32 +363,31 @@ public abstract static class Builder { /** * MaxRetryDelay puts a limit on the value of the retry delay, so that the RetryDelayMultiplier - * can't increase the retry delay higher than this amount. The default value is {@code - * Duration.ZERO}. + * can't increase the retry delay higher than this amount. * - *

If there are no configurations, Retries have the default max retry delay value set above - * and LROs have a default max poll retry delay value of {@code Duration.ofMillis(45000)} (45 - * seconds). + *

If there are no configurations, Retries have the default max retry delay value of {@code + * Duration.ZERO} and LROs have a default max poll retry delay value of {@code + * Duration.ofMillis(45000)} (45 seconds). */ public abstract Duration getMaxRetryDelay(); /** * InitialRpcTimeout controls the timeout for the initial RPC. Subsequent calls will use this - * value adjusted according to the RpcTimeoutMultiplier. The default value is {@code - * Duration.ZERO}. RPC Timeout value of {@code Duration.ZERO} allows the RPC to continue - * indefinitely (until it hits a Connect Timeout or the connection has been terminated). + * value adjusted according to the RpcTimeoutMultiplier. RPC Timeout value of {@code + * Duration.ZERO} allows the RPC to continue indefinitely (until it hits a Connect Timeout or + * the connection has been terminated). * - *

If there are no configurations, Retries have the default initial RPC timeout value set - * above. LRO polling does not use the Initial RPC Timeout value. + *

If there are no configurations, Retries have the default initial RPC timeout value of + * {@code Duration.ZERO}. LRO polling does not use the Initial RPC Timeout value. */ public abstract Duration getInitialRpcTimeout(); /** - * See the class documentation of {@link RetrySettings} for a description of what this value - * does. The default value is {@code 1.0}. + * RpcTimeoutMultiplier controls the change in RPC timeout. The timeout of the previous call is + * multiplied by the RpcTimeoutMultiplier to calculate the timeout for the next call. * - *

If there are no configurations, Retries have the default RPC Timeout Multiplier value set - * above. LRO polling does not use the RPC Timeout Multiplier value. + *

If there are no configurations, Retries have the default RPC Timeout Multiplier value of + * {@code 1.0}. LRO polling does not use the RPC Timeout Multiplier value. */ public abstract double getRpcTimeoutMultiplier(); @@ -377,8 +395,8 @@ public abstract static class Builder { * MaxRpcTimeout puts a limit on the value of the RPC timeout, so that the RpcTimeoutMultiplier * can't increase the RPC timeout higher than this amount. * - *

If there are no configurations, Retries have the default Max RPC Timeout value set above. - * LRO polling does not use the Max RPC Timeout value. + *

If there are no configurations, Retries have the default Max RPC Timeout value of {@code + * Duration.ZERO}. LRO polling does not use the Max RPC Timeout value. */ public abstract Duration getMaxRpcTimeout(); From 86bd288752d2782f2c7524f41a0084e3c0c07fcf Mon Sep 17 00:00:00 2001 From: Lawrence Qiu Date: Wed, 1 Nov 2023 18:08:23 -0400 Subject: [PATCH 5/5] docs: Update docs per PR feedback --- .../api/gax/retrying/RetrySettings.java | 73 ++++++++++--------- 1 file changed, 39 insertions(+), 34 deletions(-) diff --git a/gax-java/gax/src/main/java/com/google/api/gax/retrying/RetrySettings.java b/gax-java/gax/src/main/java/com/google/api/gax/retrying/RetrySettings.java index e592146ebc..caf25725dc 100644 --- a/gax-java/gax/src/main/java/com/google/api/gax/retrying/RetrySettings.java +++ b/gax-java/gax/src/main/java/com/google/api/gax/retrying/RetrySettings.java @@ -67,9 +67,11 @@ * RPC timeout gets converted into a wait timeout {@link * com.google.api.gax.rpc.ApiCallContext#withStreamWaitTimeout(Duration)}. * - *

In Cloud Client Libraries, Retry and LRO Retry Settings may be configured for each service and - * RPC. These values are set by the service teams and may be found by looking at the - * {Service}StubSettings.java file in each library. + *

In Cloud Client Libraries, Retry and LRO Retry Settings may be configured for each RPC in a + * service. These values are chosen by the service teams and may be found by looking at the + * {Service}StubSettings.java file in each library. The default values listed below for each + * configuration are the default values for the RetrySettings class if there are no RPC specific + * configurations from the Service Team. */ @AutoValue public abstract class RetrySettings implements Serializable { @@ -79,9 +81,9 @@ public abstract class RetrySettings implements Serializable { /** * TotalTimeout has ultimate control over how long the logic should keep trying the remote call * until it gives up completely. The higher the total timeout, the more retries and polls can be - * attempted. If this value is {@code Duration.ZERO}, then the logic will use the number of - * attempts to determine retries. In the event that both maxAttempts and TotalTimeout values are - * both 0, the logic will not retry. If this value is non-{@code Duration.ZERO}, and the retry + * attempted. If this value is {@code Duration.ZERO}, then the logic will instead use the number + * of attempts to determine retries. In the event that both maxAttempts and totalTimeout values + * are both 0, the logic will not retry. If this value is non-{@code Duration.ZERO}, and the retry * duration has reaches the timeout value, the logic will give up retrying even the number of * attempts is lower than the maxAttempts value. * @@ -122,16 +124,17 @@ public abstract class RetrySettings implements Serializable { public abstract Duration getMaxRetryDelay(); /** - * MaxAttempts defines the maximum number of attempts to perform. If this value is set to 0, the - * logic will use the totalTimeout value to determine retries. In the event that both the - * maxAttempts and TotalTimeout values are both 0, the logic will not retry. If this value is - * greater than 0, and the number of attempts reaches this limit, the logic will give up retrying - * even if the total retry time is still lower than TotalTimeout. + * MaxAttempts defines the maximum number of retry attempts to perform. If this value is set to 0, + * the logic will instead use the totalTimeout value to determine retries. In the event that both + * the maxAttempts and totalTimeout values are both 0, the logic will not retry. If this value is + * greater than 0, and the number of attempts exceeds this limit, the logic will give up retrying + * even if the total retry time is still lower than totalTimeout. * *

If there are no configurations, Retries and LROs have the default max attempt value of * {@code 0}. LRO polling does not use this value by default. * - *

The first attempt will be considered attempt #0. + *

The first RPC invocation will be considered attempt #0. Subsequent calls (retries) will + * increment the number of attempts and the number of attempts will not exceed this value. */ public abstract int getMaxAttempts(); @@ -203,11 +206,11 @@ public abstract static class Builder { /** * TotalTimeout has ultimate control over how long the logic should keep trying the remote call * until it gives up completely. The higher the total timeout, the more retries and polls can be - * attempted. If this value is {@code Duration.ZERO}, then the logic will use the number of - * attempts to determine retries. In the event that both maxAttempts and TotalTimeout values are - * both 0, the logic will not retry. If this value is non-{@code Duration.ZERO}, and the retry - * duration has reaches the timeout value, the logic will give up retrying even the number of - * attempts is lower than the maxAttempts value. + * attempted. If this value is {@code Duration.ZERO}, then the logic will instead use the number + * of attempts to determine retries. In the event that both maxAttempts and totalTimeout values + * are both 0, the logic will not retry. If this value is non-{@code Duration.ZERO}, and the + * retry duration has reaches the timeout value, the logic will give up retrying even the number + * of attempts is lower than the maxAttempts value. * *

If there are no configurations, Retries have the default timeout value of {@code * Duration.ZERO} and LROs have a default total timeout value of {@code @@ -246,16 +249,17 @@ public abstract static class Builder { public abstract Builder setMaxRetryDelay(Duration maxDelay); /** - * MaxAttempts defines the maximum number of attempts to perform. If this value is set to 0, the - * logic will use the totalTimeout value to determine retries. In the event that both the - * maxAttempts and TotalTimeout values are both 0, the logic will not retry. If this value is - * greater than 0, and the number of attempts reaches this limit, the logic will give up - * retrying even if the total retry time is still lower than TotalTimeout. + * MaxAttempts defines the maximum number of retry attempts to perform. If this value is set to + * 0, the logic will instead use the totalTimeout value to determine retries. In the event that + * both the maxAttempts and totalTimeout values are both 0, the logic will not retry. If this + * value is greater than 0, and the number of attempts exceeds this limit, the logic will give + * up retrying even if the total retry time is still lower than totalTimeout. * *

If there are no configurations, Retries and LROs have the default max attempt value of * {@code 0}. LRO polling does not use this value by default. * - *

The first attempt will be considered attempt #0. + *

The first RPC invocation will be considered attempt #0. Subsequent calls (retries) will + * increment the number of attempts and the number of attempts will not exceed this value. */ public abstract Builder setMaxAttempts(int maxAttempts); @@ -305,11 +309,11 @@ public abstract static class Builder { /** * TotalTimeout has ultimate control over how long the logic should keep trying the remote call * until it gives up completely. The higher the total timeout, the more retries and polls can be - * attempted. If this value is {@code Duration.ZERO}, then the logic will use the number of - * attempts to determine retries. In the event that both maxAttempts and TotalTimeout values are - * both 0, the logic will not retry. If this value is non-{@code Duration.ZERO}, and the retry - * duration has reaches the timeout value, the logic will give up retrying even the number of - * attempts is lower than the maxAttempts value. + * attempted. If this value is {@code Duration.ZERO}, then the logic will instead use the number + * of attempts to determine retries. In the event that both maxAttempts and totalTimeout values + * are both 0, the logic will not retry. If this value is non-{@code Duration.ZERO}, and the + * retry duration has reaches the timeout value, the logic will give up retrying even the number + * of attempts is lower than the maxAttempts value. * *

If there are no configurations, Retries have the default timeout value of {@code * Duration.ZERO} and LROs have a default total timeout value of {@code @@ -338,16 +342,17 @@ public abstract static class Builder { public abstract double getRetryDelayMultiplier(); /** - * MaxAttempts defines the maximum number of attempts to perform. If this value is set to 0, the - * logic will use the totalTimeout value to determine retries. In the event that both the - * maxAttempts and TotalTimeout values are both 0, the logic will not retry. If this value is - * greater than 0, and the number of attempts reaches this limit, the logic will give up - * retrying even if the total retry time is still lower than TotalTimeout. + * MaxAttempts defines the maximum number of retry attempts to perform. If this value is set to + * 0, the logic will instead use the totalTimeout value to determine retries. In the event that + * both the maxAttempts and totalTimeout values are both 0, the logic will not retry. If this + * value is greater than 0, and the number of attempts exceeds this limit, the logic will give + * up retrying even if the total retry time is still lower than totalTimeout. * *

If there are no configurations, Retries and LROs have the default max attempt value of * {@code 0}. LRO polling does not use this value by default. * - *

The first attempt will be considered attempt #0. + *

The first RPC invocation will be considered attempt #0. Subsequent calls (retries) will + * increment the number of attempts and the number of attempts will not exceed this value. */ public abstract int getMaxAttempts();