RetryDelayOptions

View as Markdown

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.

NameTypeDescription
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.

NameTypeDescription
base (required)long

Step in milliseconds. Retry n waits base × n. Unset, the options hold null.

Default: Not applicable

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.

NameTypeDescription
customBackoff (required)CustomBackoff

Function that returns each wait in milliseconds. Unset, the options hold null.

Default: Not applicable

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");
            }
        }
    }
}