Class RetrySettings (2.53.0)

Version 2.53.0

• 2.57.0 (latest)
• 2.55.0
• 2.54.1
• 2.53.0
• 2.52.0
• 2.51.0
• 2.50.0
• 2.49.0
• 2.48.1
• 2.47.0
• 2.46.1
• 2.45.0
• 2.43.0
• 2.42.0
• 2.41.0
• 2.39.0
• 2.38.0
• 2.37.0
• 2.36.0
• 2.35.0
• 2.34.1
• 2.33.0
• 2.32.1
• 2.31.1
• 2.30.1
• 2.24.0
• 2.23.3
• 2.22.0
• 2.21.0
• 2.20.1
• 2.19.6
• 2.18.7
• 2.17.0
• 2.16.0
• 2.15.0
• 2.14.0
• 2.13.0
• 2.12.2
• 2.11.0
• 2.10.0
• 2.9.0
• 2.8.1
• 2.7.1

public abstract class RetrySettings implements Serializable

Holds the parameters for retry or poll logic with jitter, timeout and exponential backoff. Actual implementation of the logic is elsewhere.

The intent of these settings is to be used with a call to a remote server, which could either fail (and return an error code) or not respond (and cause a timeout). When there is a failure or timeout, the logic should keep trying until the total timeout has passed.

The "total timeout" and "max attempts" settings have ultimate control over how long the logic should keep trying the remote call until it gives up completely. The remote call will be retried until one of those thresholds is crossed. To avoid unbounded rpc calls, it is required to configure one of those settings. If both are 0, then retries will be disabled. The other settings are considered more advanced.

Retry delay and timeout start at specific values, and are tracked separately from each other. The very first call (before any retries) will use the initial timeout.

If the last remote call is a failure, then the retrier will wait for the current retry delay before attempting another call, and then the retry delay will be multiplied by the retry delay multiplier for the next failure. The timeout will not be affected, except in the case where the timeout would result in a deadline past the total timeout; in that circumstance, a new timeout value is computed which will terminate the call when the total time is up.

If the last remote call is a timeout, then the retrier will compute a new timeout and make another call. The new timeout is computed by multiplying the current timeout by the timeout multiplier, but if that results in a deadline after the total timeout, then a new timeout value is computed which will terminate the call when the total time is up.

Server streaming RPCs interpret RPC timeouts a bit differently. For server streaming RPCs, the RPC timeout gets converted into a wait timeout com.google.api.gax.rpc.ApiCallContext#withStreamWaitTimeoutDuration(java.time.Duration).

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.

Inheritance

java.lang.Object > RetrySettings

Implements

Serializable

Inherited Members

Object.clone()

Object.equals(Object)

Object.finalize()

Object.getClass()

Object.hashCode()

Object.notify()

Object.notifyAll()

Object.toString()

Object.wait()

Object.wait(long)

Object.wait(long,int)

Static Methods

newBuilder()

public static RetrySettings.Builder newBuilder()

Returns
Type	Description
RetrySettings.Builder

Constructors

RetrySettings()

public RetrySettings()

Methods

getInitialRetryDelay()

public Duration getInitialRetryDelay()

Obsolete

Use getInitialRetryDelayDuration() instead

This feature is stable for usage in this major version, but may be deprecated in a future release.

This method is obsolete. Use #getInitialRetryDelayDuration() instead

Returns
Type	Description
org.threeten.bp.Duration

getInitialRetryDelayDuration()

public abstract Duration getInitialRetryDelayDuration()

InitialRetryDelay controls the delay before the first retry/ poll. Subsequent retries and polls will use this value adjusted according to the RetryDelayMultiplier.

If there are no configurations, Retries have the default initial retry delay value of Duration.ZERO and LROs have a default initial poll delay value of Duration.ofMillis(5000) (5 seconds).

Returns
Type	Description
Duration

getInitialRpcTimeout()

public final Duration getInitialRpcTimeout()

Obsolete

Use getInitialRpcTimeoutDuration() instead

This feature is stable for usage in this major version, but may be deprecated in a future release.

This method is obsolete. Use #getInitialRpcTimeoutDuration() instead

Returns
Type	Description
org.threeten.bp.Duration

getInitialRpcTimeoutDuration()

public abstract Duration getInitialRpcTimeoutDuration()

InitialRpcTimeout controls the timeout for the initial RPC. Subsequent calls will use this value adjusted according to the RpcTimeoutMultiplier. RPC Timeout value of Duration.ZERO allows the RPC to continue indefinitely (until it hits a Connect Timeout or the connection has been terminated).

#getTotalTimeout() caps how long the logic should keep trying the RPC until it gives up completely. If #getTotalTimeout() is set, initialRpcTimeout should be <= totalTimeout.

If there are no configurations, Retries have the default initial RPC timeout value of Duration.ZERO. LRO polling does not use the Initial RPC Timeout value.

Returns
Type	Description
Duration

getMaxAttempts()

public abstract int getMaxAttempts()

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 0. LRO polling does not use this value by default.

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.

Returns
Type	Description
int

getMaxRetryDelay()

public Duration getMaxRetryDelay()

Obsolete

Use getMaxRetryDelayDuration()

This feature is stable for usage in this major version, but may be deprecated in a future release.

This method is obsolete. Use #getMaxRetryDelayDuration() instead

Returns
Type	Description
org.threeten.bp.Duration

getMaxRetryDelayDuration()

public abstract Duration getMaxRetryDelayDuration()

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.

If there are no configurations, Retries have the default max retry delay value of Duration.ZERO and LROs have a default max poll retry delay value of Duration.ofMillis(45000) (45 seconds).

Returns
Type	Description
Duration

getMaxRpcTimeout()

public final Duration getMaxRpcTimeout()

Obsolete

Use getMaxRpcTimeoutDuration() instead

This feature is stable for usage in this major version, but may be deprecated in a future release.

This method is obsolete. Use #getMaxRpcTimeoutDuration() instead

Returns
Type	Description
org.threeten.bp.Duration

getMaxRpcTimeoutDuration()

public abstract Duration getMaxRpcTimeoutDuration()

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 of Duration.ZERO. LRO polling does not use the Max RPC Timeout value.

Returns
Type	Description
Duration

getRetryDelayMultiplier()

public abstract double getRetryDelayMultiplier()

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.

If there are no configurations, Retries have the default retry delay multiplier value of 1.0 and LROs have a default retry delay multiplier of 1.5.

Returns
Type	Description
double

getRpcTimeoutMultiplier()

public abstract double getRpcTimeoutMultiplier()

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 of 1.0. LRO polling does not use the RPC Timeout Multiplier value.

Returns
Type	Description
double

getTotalTimeout()

public Duration getTotalTimeout()

Obsolete

Use getTotalTimeoutDuration() instead

This feature is stable for usage in this major version, but may be deprecated in a future release.

This method is obsolete. Use #getTotalTimeoutDuration() instead

Returns
Type	Description
org.threeten.bp.Duration

getTotalTimeoutDuration()

public abstract Duration getTotalTimeoutDuration()

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 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-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 Duration.ZERO and LROs have a default total timeout value of Duration.ofMillis(300000) (5 minutes).

Returns
Type	Description
Duration

isJittered() (deprecated)

public abstract boolean isJittered()

Deprecated. Retries always jitter.

Jitter determines if the delay time should be randomized. In most cases, if jitter is set to true the actual delay time is calculated in the following way:

actualDelay = rand_between(0, min(maxRetryDelay, delay))

The default value is true.

Returns
Type	Description
boolean

toBuilder()

public abstract RetrySettings.Builder toBuilder()

Returns
Type	Description
RetrySettings.Builder