What is the difference between RetryOptions and RequestRetryOptions?

Question

I am working with the Azure SDK for Java and specifically with blob storage and I am using the SpecializedBlobClientBuilder.

My question is around the various retry options:

SpecializedBlobClientBuilder retryOptions(RequestRetryOptions retryOptions)
SpecializedBlobClientBuilder retryOptions(RetryOptions retryOptions)

Initially I set RetryOptions on my client, but it did not seem to take effect in the case of a network timeout. However when I set RequestRetryOptions instead it does get applied and I am having trouble understanding why, what is the difference between these retry options and in which cases does RetryOptions actually get applied?

Answer 1

SpecializedBlobClientBuilder class provides options for configuring retries when interacting with Azure Blob Storage using Java.

1. SpecializedBlobClientBuilder retryOptions(RequestRetryOptions retryOptions):

As mentioned in the MSDOC, RequestRetryOptions class allows to configure options specifically related to retrying individual HTTP requests made by SDK client.

• It is used for scenarios like network timeouts, connection failures, and other issues encountered while sending a request.

• If you set RequestRetryOptions on your client, it will affect the retry behavior of every request made through that particular client.

2. SpecializedBlobClientBuilder retryOptions(RetryOptions retryOptions)

As per MSDOC, this class is to configure retry policy for SDK client related to retrying higher-level operations and it handles retries at the operation level, which involve multiple HTTP requests

• If you set RetryOptions on your client, it will affect the retry behavior for higher-level operations.

---

• To configure the retry policy for HTTP requests made by the client, use the RequestRetryOptions class.
• To configure the retry policy for the client, use RetryOptions class.
• Both RequestRetryOptions and RetryOptions are mutually exclusive. So, it is better to consider both classes while configuring storage options.

References:

Refer to the github repo for sample code to understand SpecializedBlobClientBuilder, RetryOptions and RequestRetryOptions.

Answer 2

This is the relevant code that builds the retry policy in the Azure SDK:

    public static RequestRetryPolicy createRetryPolicy(
        RequestRetryOptions retryOptions, RetryOptions coreRetryOptions, ClientLogger logger) {
        if (retryOptions != null && coreRetryOptions != null) {
            throw logger.logExceptionAsWarning(
                new IllegalStateException(
                    "'retryOptions(RequestRetryOptions)' and 'retryOptions(RetryOptions)' cannot both be set"));
        }
        if (coreRetryOptions != null) {
            retryOptions = RequestRetryOptions.fromRetryOptions(coreRetryOptions, null, null);
        }
        if (retryOptions == null) {
            retryOptions = new RequestRetryOptions();
        }
        return new RequestRetryPolicy(retryOptions);
    }

You can see that the RequestRetryOptions seem to be the "master class" from which the retry policy gets built.

If instead the RetryOptions get passed, then from that the derived RequestRetryOptions is built, with some default values.

Based on this, if in doubt, I would use the RequestRetryOptions, because these are the options actually directly used in the retry policy.

But also looking at the Azure SDK code, I don't see anywhere anything that would suggest that the other options don't apply e.g. to network timeouts. Maybe that was some other effect that you observed, unrelated to the retry option config?