RetryDelayOptions
RetryDelayOptions
RetryDelayOptions sets the wait of the Java Management SDK before each retry of a failed request. Use this class to
- make the wait grow by a fixed step on each retry, with base
- supply your own wait calculation, such as exponential backoff with jitter, with customBackoff
Get a builder with RetryDelayOptions.builder() or new RetryDelayOptions.Builder(), set the values, and call build. Pass the result to the retryDelayOptions method of RetryConfig.Builder, and pass that configuration to the setRetryConfig method of Contentstack.Builder. A RetryDelayOptions object has no setters, so its values stay fixed after build.
| Name | Type | Description |
|---|---|---|
| base | Long | base, getBase. Step of the linear backoff, in milliseconds. |
| customBackoff | CustomBackoff | customBackoff, getCustomBackoff. Your own wait calculation. |
base
base sets the step, in milliseconds, of a linear backoff, so each retry waits longer than the one before.
| Name | Type | Description |
|---|---|---|
| base (required) | long | Step in milliseconds. Retry n waits base × n. Unset, the options hold null. |
Returns: Builder. The same builder, for chaining.
Validation
- There is no client-side validation. base accepts 0 and negative values.
- A value of 0 or less does not throw. The SDK ignores it and uses the fixed delay of RetryConfig instead.
Behavior
- Before retry number n, starting at 1, the SDK waits base × n milliseconds. With base(1000) and the default retry limit of 3, the waits are 1000, 2000 and 3000 ms.
- A customBackoff function, when set, decides every wait and the SDK ignores base.
- Without base, every retry waits the fixed delay of the retryDelay method of RetryConfig.Builder, 300 ms by default.
- Calling base again replaces the earlier value.
Example
Basic usage: wait one second longer on each retry
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.core.RetryConfig;
import com.contentstack.cms.core.RetryDelayOptions;
public class LinearRetryDelay {
public static void main(String[] args) {
RetryDelayOptions delayOptions = RetryDelayOptions.builder()
.base(1000)
.build();
RetryConfig retryConfig = RetryConfig.builder()
.retryDelayOptions(delayOptions)
.build();
// Retries wait 1000, 2000 and 3000 ms
Contentstack client = new Contentstack.Builder()
.setRetryConfig(retryConfig)
.build();
System.out.println(client.getRetryConfig().getRetryDelayOptions().getBase()); // 1000
}
}build
build creates a RetryDelayOptions object from the values set on the builder.
Returns: RetryDelayOptions. New delay options.
Validation
- There is no client-side validation.
- build does not throw.
Behavior
- The new object copies the base and the custom backoff from the builder. A later setter call on the builder does not change it.
- RetryDelayOptions has no setters, so its values stay fixed after build.
- Pass the result to the retryDelayOptions method of RetryConfig.Builder.
Example
Basic usage: build the options and attach them to a retry configuration
import com.contentstack.cms.core.RetryConfig;
import com.contentstack.cms.core.RetryDelayOptions;
public class BuildDelayOptions {
public static void main(String[] args) {
RetryDelayOptions delayOptions = RetryDelayOptions.builder().base(750).build();
RetryConfig retryConfig = RetryConfig.builder()
.retryLimit(4)
.retryDelayOptions(delayOptions)
.build();
System.out.println(retryConfig.getRetryDelayOptions().getBase()); // 750
}
}builder
builder creates an empty builder for a RetryDelayOptions object.
Returns: Builder. A new delay options builder.
Validation
- There is no client-side validation.
- builder does not throw.
Behavior
- builder is a static method of RetryDelayOptions. new RetryDelayOptions.Builder() also returns a new, empty builder.
- The returned type is RetryDelayOptions.Builder.
- A new builder holds no base and no custom backoff. Calling build on it gives options that leave the fixed delay of RetryConfig in charge of every wait.
Example
Basic usage: start the delay options
import com.contentstack.cms.core.RetryDelayOptions;
public class StartDelayOptions {
public static void main(String[] args) {
RetryDelayOptions.Builder builder = RetryDelayOptions.builder();
RetryDelayOptions delayOptions = builder.base(500).build();
System.out.println(delayOptions.getBase()); // 500
}
}customBackoff
customBackoff sets your own function that returns the wait, in milliseconds, before each retry.
| Name | Type | Description |
|---|---|---|
| customBackoff (required) | CustomBackoff | Function that returns each wait in milliseconds. Unset, the options hold null. |
Returns: Builder. The same builder, for chaining.
Validation
- There is no client-side validation. customBackoff(null) removes an earlier function.
- A negative return value does not throw at this call. The SDK passes it to Thread.sleep, which throws IllegalArgumentException. That exception reaches your code from execute() on the request that the SDK was retrying.
Behavior
- The function decides every wait. While the options hold a function, the SDK ignores base and the fixed delay of RetryConfig.
- CustomBackoff is a functional interface in com.contentstack.cms.core with one method, long calculate(int retryCount, int statusCode, Throwable error). The SDK passes the three arguments below:
- retryCount: the number of the retry about to run, starting at 1.
- statusCode: the HTTP status that triggered the retry, or 0 for a socket timeout.
- error: always null in 1.16.0, including for a socket timeout.
- The SDK uses the return value as is, with no upper limit. Cap it in your function when you need a maximum wait.
- The SDK does not read the Retry-After response header, so your function cannot read it either.
- The function runs on the thread that waits: the calling thread for execute(), or an OkHttp background thread for enqueue().
Example
Basic usage: exponential backoff with jitter and a cap
import com.contentstack.cms.Contentstack;
import com.contentstack.cms.core.RetryConfig;
import com.contentstack.cms.core.RetryDelayOptions;
import java.util.concurrent.ThreadLocalRandom;
public class ExponentialRetryDelay {
public static void main(String[] args) {
RetryDelayOptions delayOptions = RetryDelayOptions.builder()
.customBackoff((retryCount, statusCode, error) -> {
long wait = 500L * (1L << (retryCount - 1)); // 500, 1000, 2000 ms
long jitter = ThreadLocalRandom.current().nextLong(100);
return Math.min(wait + jitter, 10000L); // never more than 10 seconds
})
.build();
Contentstack client = new Contentstack.Builder()
.setRetryConfig(RetryConfig.builder().retryDelayOptions(delayOptions).build())
.build();
System.out.println(client.getRetryConfig().getRetryDelayOptions().getCustomBackoff() != null); // true
}
}Status-based wait: wait longer after a rate limit
import com.contentstack.cms.core.CustomBackoff;
import com.contentstack.cms.core.RetryDelayOptions;
public class RateLimitRetryDelay {
public static void main(String[] args) {
CustomBackoff backoff = (retryCount, statusCode, error) ->
statusCode == 429 ? 2000L * retryCount : 300L;
RetryDelayOptions delayOptions = RetryDelayOptions.builder().customBackoff(backoff).build();
// Preview the waits the SDK would use
System.out.println(delayOptions.getCustomBackoff().calculate(1, 429, null)); // 2000
System.out.println(delayOptions.getCustomBackoff().calculate(1, 503, null)); // 300
}
}getBase
getBase returns the step of the linear backoff that base set.
Returns: Long. The linear backoff step in milliseconds, or null.
Validation
- There is no client-side validation.
- getBase does not throw.
Behavior
- Returns null when the builder never called base.
- getBase returns a value of 0 or less as given, but the SDK ignores that value and uses the fixed delay of RetryConfig.
- The SDK ignores this value while the options hold a custom backoff. Check with the getCustomBackoff method.
Example
Basic usage: read the step
import com.contentstack.cms.core.RetryDelayOptions;
public class ReadBase {
public static void main(String[] args) {
System.out.println(RetryDelayOptions.builder().base(1000).build().getBase()); // 1000
System.out.println(RetryDelayOptions.builder().build().getBase()); // null
}
}getCustomBackoff
getCustomBackoff returns the function that customBackoff set.
Returns: CustomBackoff. The custom backoff function, or null.
Validation
- There is no client-side validation.
- getCustomBackoff does not throw.
Behavior
- Returns null when the builder never called customBackoff.
- The returned object is the one you passed, so you can call its calculate method to preview the waits.
Example
Basic usage: preview the waits of a custom function
import com.contentstack.cms.core.CustomBackoff;
import com.contentstack.cms.core.RetryDelayOptions;
public class PreviewCustomBackoff {
public static void main(String[] args) {
RetryDelayOptions delayOptions = RetryDelayOptions.builder()
.customBackoff((retryCount, statusCode, error) -> 400L * retryCount)
.build();
CustomBackoff backoff = delayOptions.getCustomBackoff();
if (backoff != null) {
for (int retry = 1; retry <= 3; retry++) {
System.out.println("Retry " + retry + ": " + backoff.calculate(retry, 503, null) + " ms");
}
}
}
}