RetryConfig

View as Markdown

RetryConfig

RetryConfig sets the retry behavior of the Java Management SDK for a request that fails with a transient HTTP status or a socket timeout. Use this class to

  • change the number of retries, or turn retries off
  • change the wait between retries, with a fixed delay or with RetryDelayOptions
  • choose which failures trigger a retry, with your own condition

Get a builder with RetryConfig.builder() or new RetryConfig.Builder(), set the values, and call build. defaultConfig returns the default configuration. Pass the configuration to the setRetryConfig method of Contentstack.Builder before you build the client. A RetryConfig object has no setters, so its values stay fixed after build.

NameTypeDescription
retryLimit int

retryLimit, getRetryLimit. Maximum number of retries after the first attempt.

retryDelay long

retryDelay, getRetryDelay. Fixed wait before each retry, in milliseconds.

retryCondition RetryCondition

retryCondition, getRetryCondition. Rule that decides which failures to retry.

retryDelayOptions RetryDelayOptions

retryDelayOptions, getRetryDelayOptions. Linear step or custom function for each wait.

build

build creates a RetryConfig object from the values set on the builder.

Returns: RetryConfig. A new retry configuration.

Validation

  • There is no client-side validation.
  • build does not throw.

Behavior

  • When the builder holds no retry condition, build sets the default condition, DefaultRetryCondition.
  • The new object copies the values from the builder. A later setter call on the builder does not change it.
  • RetryConfig has no setters, so its values stay fixed after build.
  • Pass the result to the setRetryConfig method of Contentstack.Builder before you call build() on that builder. A client keeps the configuration it receives at that point.

Example

Basic usage: build a configuration and create a client with it

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.core.RetryConfig;

public class BuildRetryConfig {
    public static void main(String[] args) {
        RetryConfig retryConfig = RetryConfig.builder()
                .retryLimit(2)
                .retryDelay(500)
                .build();
        Contentstack client = new Contentstack.Builder()
                .setRetryConfig(retryConfig)
                .build();
        System.out.println(client.getRetryConfig() == retryConfig); // true
    }
}

builder

builder creates a builder for a RetryConfig object, preset with the default values.

Returns: Builder. A new retry configuration builder.

Validation

  • There is no client-side validation.
  • builder does not throw.

Behavior

  • builder is a static method of RetryConfig. new RetryConfig.Builder() also returns a new builder with the same preset values.
  • The returned type is RetryConfig.Builder.
  • A new builder holds a retry limit of 3 and a fixed delay of 300 ms. It holds no retry condition and no delay options. build fills a missing retry condition with the default one.

Example

Basic usage: start a retry configuration

import com.contentstack.cms.core.RetryConfig;

public class StartRetryConfig {
    public static void main(String[] args) {
        RetryConfig.Builder builder = RetryConfig.builder();
        RetryConfig retryConfig = builder.retryLimit(5).build();
        System.out.println(retryConfig.getRetryLimit()); // 5
        System.out.println(retryConfig.getRetryDelay()); // 300, the default
    }
}

defaultConfig

defaultConfig creates a RetryConfig with the default values, the same configuration that every client starts with.

Returns: RetryConfig. A new retry configuration with the default values.

Validation

  • There is no client-side validation.
  • defaultConfig does not throw.

Behavior

  • defaultConfig is a static method of RetryConfig. It returns the same values as RetryConfig.builder().build().
  • The default values are a retry limit of 3, a fixed delay of 300 ms, the default retry condition and no delay options.
  • The default retry condition retries a socket timeout and the statuses 408, 429, 500, 502, 503 and 504.
  • Each call returns a new object.

Example

Basic usage: read the default values

import com.contentstack.cms.core.RetryConfig;

public class ReadDefaultRetryConfig {
    public static void main(String[] args) {
        RetryConfig retryConfig = RetryConfig.defaultConfig();
        System.out.println(retryConfig.getRetryLimit());          // 3
        System.out.println(retryConfig.getRetryDelay());          // 300
        System.out.println(retryConfig.getRetryDelayOptions());   // null
        System.out.println(retryConfig.getRetryCondition().shouldRetry(429, null)); // true
    }
}

getRetryCondition

getRetryCondition returns the rule that decides whether the SDK retries a failed request.

Returns: RetryCondition. The rule that decides which failures to retry.

Validation

  • There is no client-side validation.
  • getRetryCondition does not throw.

Behavior

  • Never returns null. Without a condition from the retryCondition method, it returns the shared DefaultRetryCondition instance.
  • Call shouldRetry(statusCode, error) on the result to check a status. Pass 0 and the exception for a socket timeout.

Example

Basic usage: check which statuses the SDK retries

import com.contentstack.cms.core.RetryCondition;
import com.contentstack.cms.core.RetryConfig;

public class CheckRetryCondition {
    public static void main(String[] args) {
        RetryCondition condition = RetryConfig.defaultConfig().getRetryCondition();
        int[] statuses = {200, 404, 408, 429, 500, 503};
        for (int status : statuses) {
            System.out.println(status + " retried: " + condition.shouldRetry(status, null));
        }
    }
}

getRetryDelay

getRetryDelay returns the fixed wait, in milliseconds, that the SDK uses when no delay options decide the wait.

Returns: long. The fixed wait between retries in milliseconds.

Validation

  • There is no client-side validation.
  • getRetryDelay does not throw.

Behavior

  • The default is 300.
  • The SDK ignores this value while the delay options hold a custom backoff function or a base greater than 0. Check with the getRetryDelayOptions method.

Example

Basic usage: read the fixed delay

import com.contentstack.cms.core.RetryConfig;

public class ReadRetryDelay {
    public static void main(String[] args) {
        System.out.println(RetryConfig.builder().retryDelay(1200).build().getRetryDelay()); // 1200
        System.out.println(RetryConfig.defaultConfig().getRetryDelay());                    // 300
    }
}

getRetryDelayOptions

getRetryDelayOptions returns the delay options that retryDelayOptions set.

Returns: RetryDelayOptions. The delay options, or null.

Validation

  • There is no client-side validation.
  • getRetryDelayOptions does not throw.

Behavior

Example

Basic usage: read the delay options

import com.contentstack.cms.core.RetryConfig;
import com.contentstack.cms.core.RetryDelayOptions;

public class ReadDelayOptions {
    public static void main(String[] args) {
        RetryConfig retryConfig = RetryConfig.builder()
                .retryDelayOptions(RetryDelayOptions.builder().base(250).build())
                .build();
        RetryDelayOptions delayOptions = retryConfig.getRetryDelayOptions();
        if (delayOptions != null) {
            System.out.println(delayOptions.getBase()); // 250
        }
        System.out.println(RetryConfig.defaultConfig().getRetryDelayOptions()); // null
    }
}

getRetryLimit

getRetryLimit returns the maximum number of times the SDK retries a failed request after the first attempt.

Returns: int. The maximum number of retries.

Validation

  • There is no client-side validation.
  • getRetryLimit does not throw.

Behavior

  • The default is 3. The SDK then sends up to four attempts.
  • The value is 0 or more, because the retryLimit method rejects a negative value.
  • 0 means the SDK retry is off.

Example

Basic usage: read the retry limit

import com.contentstack.cms.core.RetryConfig;

public class ReadRetryLimit {
    public static void main(String[] args) {
        System.out.println(RetryConfig.builder().retryLimit(6).build().getRetryLimit()); // 6
        System.out.println(RetryConfig.defaultConfig().getRetryLimit());                 // 3
    }
}

retryCondition

retryCondition sets your own rule that decides whether the SDK retries a failed request.

NameTypeDescription
retryCondition (required)RetryCondition

Rule that returns true to retry. Unset, the SDK uses DefaultRetryCondition.

Default: Not applicable

Returns: Builder. The same builder, for chaining.

Validation

  • There is no client-side validation. retryCondition(null) does not throw, and build then uses the default condition.
  • An exception that your condition throws reaches your code from execute().

Behavior

  • RetryCondition is a functional interface in com.contentstack.cms.core with one method, boolean shouldRetry(int statusCode, Throwable error). The SDK passes the two arguments below:
    • statusCode: the HTTP status of the response, or 0 for a socket timeout.
    • error: the java.net.SocketTimeoutException for a socket timeout, otherwise null.
  • The SDK asks the condition only about a response or a socket timeout. Other network errors, such as a refused connection, reach your code as an IOException from execute() without a retry.
  • For a client without Open Authorization (OAuth), the SDK asks the condition about every response, including a successful one. Return false for a 2xx status, or the SDK sends a successful request again until it reaches the retry limit.
  • For a client that uses OAuth, the SDK asks the condition only about a response that is not 2xx. A 401 response with a refresh token available makes the SDK refresh the token and retry before it asks the condition.
  • Without a condition, the SDK uses DefaultRetryCondition, which returns true for 0, 408, 429, 500, 502, 503 and 504. Call DefaultRetryCondition.getInstance().shouldRetry(statusCode, error) inside your condition to keep those defaults.

Example

Basic usage: retry only rate limits and timeouts

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.core.RetryConfig;

public class RetryRateLimitsOnly {
    public static void main(String[] args) {
        RetryConfig retryConfig = RetryConfig.builder()
                // 0 is a socket timeout. Every other status, including 2xx, returns false.
                .retryCondition((statusCode, error) -> statusCode == 0 || statusCode == 429)
                .build();
        Contentstack client = new Contentstack.Builder()
                .setRetryConfig(retryConfig)
                .build();
        System.out.println(client.getRetryConfig().getRetryCondition().shouldRetry(503, null)); // false
    }
}

Extend the defaults: also retry a conflict response

import com.contentstack.cms.core.DefaultRetryCondition;
import com.contentstack.cms.core.RetryCondition;
import com.contentstack.cms.core.RetryConfig;

public class ExtendDefaultCondition {
    public static void main(String[] args) {
        RetryCondition condition = (statusCode, error) ->
                statusCode == 409 || DefaultRetryCondition.getInstance().shouldRetry(statusCode, error);
        RetryConfig retryConfig = RetryConfig.builder().retryCondition(condition).build();

        System.out.println(retryConfig.getRetryCondition().shouldRetry(409, null)); // true
        System.out.println(retryConfig.getRetryCondition().shouldRetry(200, null)); // false
    }
}

retryDelay

retryDelay sets the fixed wait, in milliseconds, before each retry when no delay options decide the wait.

NameTypeDescription
retryDelay (required)long

Fixed wait before each retry, in milliseconds. Unset, the builder holds 300.

Default: Not applicable

Returns: Builder. The same builder, for chaining.

Validation

  • Throws IllegalArgumentException if retryDelay is below 0, because a wait cannot be negative. The exception comes from retryDelay itself, at the call, and the builder keeps its previous value.
  • 0 is valid. The SDK then retries with no wait.

Behavior

  • The default is 300 ms.
  • The SDK uses this value only when no delay options decide the wait. Delay options decide it when they hold a custom backoff function or a base greater than 0. See the RetryDelayOptions class.
  • Every retry waits the same time. For a wait that grows on each retry, use the retryDelayOptions method.

Example

Basic usage: wait one second before each retry

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.core.RetryConfig;

public class FixedRetryDelay {
    public static void main(String[] args) {
        RetryConfig retryConfig = RetryConfig.builder()
                .retryLimit(3)
                .retryDelay(1000)
                .build();
        Contentstack client = new Contentstack.Builder()
                .setRetryConfig(retryConfig)
                .build();
        System.out.println(client.getRetryConfig().getRetryDelay()); // 1000
    }
}

retryDelayOptions

retryDelayOptions attaches delay options that make the wait grow on each retry or follow your own function.

NameTypeDescription
retryDelayOptions (required)RetryDelayOptions

Linear step or custom function for each wait. Unset, the builder holds null.

Default: Not applicable

Returns: Builder. The same builder, for chaining.

Validation

  • There is no client-side validation. retryDelayOptions(null) removes earlier options, and every retry then waits the fixed delay.

Behavior

  • The SDK picks each wait from the first of the three rules below that matches:

1. The custom backoff function of the options, when set. 2. The base of the options × the retry number, when the base is greater than 0. The retry number starts at 1. 3. The fixed delay from the retryDelay method, 300 ms by default.

Example

Basic usage: grow the wait by 500 ms on each retry

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.core.RetryConfig;
import com.contentstack.cms.core.RetryDelayOptions;

public class LinearBackoffConfig {
    public static void main(String[] args) {
        RetryConfig retryConfig = RetryConfig.builder()
                .retryLimit(4)
                .retryDelayOptions(RetryDelayOptions.builder().base(500).build()) // 500, 1000, 1500, 2000 ms
                .build();
        Contentstack client = new Contentstack.Builder()
                .setRetryConfig(retryConfig)
                .build();
        System.out.println(client.getRetryConfig().getRetryDelayOptions().getBase()); // 500
    }
}

retryLimit

retryLimit sets the maximum number of times the SDK retries a failed request after the first attempt.

NameTypeDescription
retryLimit (required)int

Maximum retries after the first attempt. Unset, the builder holds 3.

Default: Not applicable

Returns: Builder. The same builder, for chaining.

Validation

  • Throws IllegalArgumentException if retryLimit is below 0, because a retry count cannot be negative. The exception comes from retryLimit itself, at the call, and the builder keeps its previous limit.
  • There is no upper limit. A high limit with a long wait can block the calling thread for a long time.

Behavior

  • The limit counts retries, not attempts. The SDK sends up to retryLimit + 1 attempts, so the default of 3 sends up to four attempts.
  • 0 turns the SDK retry off. The SDK then sends one attempt.
  • For a client that uses Open Authorization (OAuth), 0 also stops the SDK from refreshing the access token after a 401 response.
  • Known issue: In 1.16.0, a client that uses OAuth loses the body of an error response it does not retry, such as 404, while retries remain. The SDK closes the response before it returns it, so execute() throws an exception instead of returning the error response. To read error responses on such a client, set retryLimit(0) and retry in your own code.
  • The limit applies to every request that the client sends.

Example

Basic usage: allow five retries

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.core.RetryConfig;

public class AllowFiveRetries {
    public static void main(String[] args) {
        RetryConfig retryConfig = RetryConfig.builder().retryLimit(5).build();
        Contentstack client = new Contentstack.Builder()
                .setRetryConfig(retryConfig)
                .build();
        System.out.println(client.getRetryConfig().getRetryLimit()); // 5
    }
}

Error handling: reject a negative limit

import com.contentstack.cms.core.RetryConfig;

public class RejectRetryLimit {
    public static void main(String[] args) {
        RetryConfig.Builder builder = RetryConfig.builder();
        try {
            builder.retryLimit(-1);
        } catch (IllegalArgumentException e) {
            // Thrown at the call for a limit below 0
            System.out.println("Invalid retry limit: " + e.getMessage());
        }
        System.out.println(builder.build().getRetryLimit()); // 3, the default, unchanged
    }
}

Edge case: turn the SDK retry off

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.core.RetryConfig;

public class TurnRetryOff {
    public static void main(String[] args) {
        // One attempt per request, no retries
        Contentstack client = new Contentstack.Builder()
                .setRetryConfig(RetryConfig.builder().retryLimit(0).build())
                .build();
        System.out.println(client.getRetryConfig().getRetryLimit()); // 0
    }
}