Top Description Fields Constructors Methods
com.oracle.bmc.retrier

public final Class Retriers

extends Object
Class Inheritance
Imports
java.io.IOException, .InputStream, java.util.Objects, .Optional, java.util.stream.Stream, jakarta.annotation.Nullable, .Nonnull, com.oracle.bmc.InternalSdk, com.oracle.bmc.requests.BmcRequest
Group of utility methods to configure the SDK retry behavior

Field Summary

Modifier and TypeField and Description
private static volatile RetryConfiguration
DEFAULT_RETRY_CONFIGURATION

private static final Logger
LOG

private static final String
OCI_SDK_DEFAULT_RETRY_ENABLED_ENV_VAR

The environment variable to control default retry behavior

private static volatile boolean
SEND_OPC_RETRY_TOKEN

Constructor Summary

AccessConstructor and Description
private
Retriers()

Method Summary

Modifier and TypeMethod and Description
public static BmcGenericRetrier

Returns:

The retrier based on the appropriate retry configuration
createPreferredRetrier(final RetryConfiguration
the retry configuration set on the request object
requestRetryConfiguration, final RetryConfiguration
the retry configuration set on the client object
clientRetryConfiguration)

Choose the desired retry configuration and use it to create the retrier.

public static BmcGenericRetrier

Returns:

The retrier based on the appropriate retry configuration
createPreferredRetrier(final RetryConfiguration
the retry configuration set on the request object
requestRetryConfiguration, final RetryConfiguration
the retry configuration set on the client object
clientRetryConfiguration, boolean
boolean value indicating if default retry is enabled via spec
specBasedDefaultRetryEnabled)

Choose the desired retry configuration and use it to create the retrier.

private static RetryConfiguration
envBasedRetryConfiguration()

public static RetryConfiguration

Returns:

the default RetryConfiguration set
getDefaultRetryConfiguration()

Getter for the default retry configuration.

public static RetryConfiguration

Returns:

The appropriate retry configuration
getPreferredRetryConfiguration(RetryConfiguration
the retry configuration set on the request object
requestRetryConfiguration, RetryConfiguration
the retry configuration set on the client object
clientRetryConfiguration, boolean
boolean value indicating if default retry is enabled via spec
specBasedDefaultRetryEnabled)

Choose the desired retry configuration.

public static void
setDefaultRetryConfiguration(final RetryConfiguration
the RetryConfiguration to use
retryConfiguration)

Setter for the default retry configuration used in the SDK.

public static boolean

Returns:

true if we should prepare for retries
shouldPrepareForRetryBecauseOfRetryConfiguration(RetryConfiguration
retry configuration
rc)

Returns true if the retry configuration indicates that we should prepare for retries.

public static void
shouldSendOpcRetryToken(boolean
if true, then the SDK will automatically send the opc-retry-token header
shouldSendOpcRetryToken)

Sets whether the SDK should automatically send the opc-retry-token header

public static boolean

Returns:

true if the SDK automatically sends the opc-retry-token header, else false
shouldSendOpcRetryToken()

Gets whether the SDK is automatically sending the opc-retry-token header

public static void
tryResetStreamForRetry(InputStream body)

Try to reset the InputStream for the next retry, if supported.

public static void
tryResetStreamForRetry(InputStream body, boolean
if true, fail if unsupported
failIfUnsupported)

Try to reset the InputStream for the next retry, if supported.

public static <
type of the request
T extends BmcRequest<InputStream>> T

Returns:

request with the input stream wrapped
wrapBodyInputStreamIfNecessary(T
request being handled
request, BmcRequest.Builder<T, InputStream>
builder for the request
builder, RetryConfiguration
the effective retry configuration for this request
retryConfiguration)

Wrap the input stream in the request so retries can work.

public static InputStream

Returns:

the input stream wrapped
wrapInputStreamForRetry(InputStream
input stream body
body)

Wrap the input stream so retries can work.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

DEFAULT_RETRY_CONFIGURATIONback to summary
private static volatile RetryConfiguration DEFAULT_RETRY_CONFIGURATION
LOGback to summary
private static final Logger LOG
OCI_SDK_DEFAULT_RETRY_ENABLED_ENV_VARback to summary
private static final String OCI_SDK_DEFAULT_RETRY_ENABLED_ENV_VAR

The environment variable to control default retry behavior

SEND_OPC_RETRY_TOKENback to summary
private static volatile boolean SEND_OPC_RETRY_TOKEN

Constructor Detail

Retriersback to summary
private Retriers()

Method Detail

createPreferredRetrierback to summary
public static BmcGenericRetrier createPreferredRetrier(final RetryConfiguration requestRetryConfiguration, final RetryConfiguration clientRetryConfiguration)

Choose the desired retry configuration and use it to create the retrier.

Parameters
requestRetryConfiguration:RetryConfiguration

the retry configuration set on the request object

clientRetryConfiguration:RetryConfiguration

the retry configuration set on the client object

Returns:BmcGenericRetrier

The retrier based on the appropriate retry configuration

createPreferredRetrierback to summary
public static BmcGenericRetrier createPreferredRetrier(final RetryConfiguration requestRetryConfiguration, final RetryConfiguration clientRetryConfiguration, boolean specBasedDefaultRetryEnabled)

Choose the desired retry configuration and use it to create the retrier.

Parameters
requestRetryConfiguration:RetryConfiguration

the retry configuration set on the request object

clientRetryConfiguration:RetryConfiguration

the retry configuration set on the client object

specBasedDefaultRetryEnabled:boolean

boolean value indicating if default retry is enabled via spec

Returns:BmcGenericRetrier

The retrier based on the appropriate retry configuration

envBasedRetryConfigurationback to summary
private static RetryConfiguration envBasedRetryConfiguration()
getDefaultRetryConfigurationback to summary
public static RetryConfiguration getDefaultRetryConfiguration()

Getter for the default retry configuration. This can be overriden by setting a retry configuration on the client (via com.oracle.bmc.ClientConfiguration) or the request (via com.oracle.bmc.requests.BmcRequest#setRetryConfiguration(RetryConfiguration))

Returns:RetryConfiguration

the default RetryConfiguration set

getPreferredRetryConfigurationback to summary
public static RetryConfiguration getPreferredRetryConfiguration(RetryConfiguration requestRetryConfiguration, RetryConfiguration clientRetryConfiguration, boolean specBasedDefaultRetryEnabled)

Choose the desired retry configuration.

Parameters
requestRetryConfiguration:RetryConfiguration

the retry configuration set on the request object

clientRetryConfiguration:RetryConfiguration

the retry configuration set on the client object

specBasedDefaultRetryEnabled:boolean

boolean value indicating if default retry is enabled via spec

Returns:RetryConfiguration

The appropriate retry configuration

setDefaultRetryConfigurationback to summary
public static void setDefaultRetryConfiguration(final RetryConfiguration retryConfiguration)

Setter for the default retry configuration used in the SDK. This can be overriden by setting a retry configuration on the client (via com.oracle.bmc.ClientConfiguration) or the request (via com.oracle.bmc.requests.BmcRequest#setRetryConfiguration(RetryConfiguration))

Parameters
retryConfiguration:RetryConfiguration

the RetryConfiguration to use

shouldPrepareForRetryBecauseOfRetryConfigurationback to summary
public static boolean shouldPrepareForRetryBecauseOfRetryConfiguration(RetryConfiguration rc)

Returns true if the retry configuration indicates that we should prepare for retries.

We don't need to prepare for retries if the retry configuration is null; or if there is no termination strategy; or if the termination strategy says to make exactly 1 attempt.

We do have to prepare for retries if there is a retry configuration and termination strategy, and: (a) the termination strategy is not count-based; or (b) the termination strategy is count-based and we are willing to make more than 1 attempt.

Parameters
rc:RetryConfiguration

retry configuration

Returns:boolean

true if we should prepare for retries

shouldSendOpcRetryTokenback to summary
public static void shouldSendOpcRetryToken(boolean shouldSendOpcRetryToken)

Sets whether the SDK should automatically send the opc-retry-token header

Parameters
shouldSendOpcRetryToken:boolean

if true, then the SDK will automatically send the opc-retry-token header

shouldSendOpcRetryTokenback to summary
public static boolean shouldSendOpcRetryToken()

Gets whether the SDK is automatically sending the opc-retry-token header

Returns:boolean

true if the SDK automatically sends the opc-retry-token header, else false

tryResetStreamForRetryback to summary
public static void tryResetStreamForRetry(InputStream body)

Try to reset the InputStream for the next retry, if supported.

If the stream supports InputStream#mark(int) and InputStream#reset(), we reset the stream so it starts at the beginning (or wherever the stream has been marked using InputStream#mark(int).

Note that this means that if the caller has used InputStream#mark(int) and the mark does not represent the place in the stream where retries should commence (if retries are requested and necessary), then incorrect data may be processed.

If the stream does not support InputStream#mark(int) and InputStream#reset(), then retries will not work. Therefore, those streams should be wrapped in a java.io.BufferedInputStream before they are sent here.

If the stream does not support being reset, this method throws an IllegalArgumentException. This is never the case using the auto-generated code, since streams are always wrapped and/or buffered appropriately. It could happen if someone sent in a com.oracle.bmc.io.internal.KeepOpenInputStream directly, but users are not supposed to do that, since it's an internal class.

Annotations
@InternalSdk
Exceptions
IllegalArgumentException:
if stream does not support being reset
RuntimeException:
if stream does support being reset, but the reset failed
tryResetStreamForRetryback to summary
public static void tryResetStreamForRetry(InputStream body, boolean failIfUnsupported)

Try to reset the InputStream for the next retry, if supported. If not supported, fail if requested.

If the stream supports InputStream#mark(int) and InputStream#reset(), we reset the stream so it starts at the beginning (or wherever the stream has been marked using InputStream#mark(int).

Note that this means that if the caller has used InputStream#mark(int) and the mark does not represent the place in the stream where retries should commence (if retries are requested and necessary), then incorrect data may be processed.

If the stream does not support InputStream#mark(int) and InputStream#reset(), then retries will not work. Therefore, those streams should be wrapped in a java.io.BufferedInputStream before they are sent here.

Parameters
failIfUnsupported:boolean

if true, fail if unsupported

Annotations
@InternalSdk
Exceptions
IllegalArgumentException:
if stream does not support being reset and failIfUnsupported is true
RuntimeException:
if stream does support being reset, but the reset failed
wrapBodyInputStreamIfNecessaryback to summary
public static <T extends BmcRequest<InputStream>> T wrapBodyInputStreamIfNecessary(T request, BmcRequest.Builder<T, InputStream> builder, RetryConfiguration retryConfiguration)

Wrap the input stream in the request so retries can work.

Note

The stream in the request may be wrapped in a com.oracle.bmc.io.internal.KeepOpenInputStream, which prevents a call to close() from actually closing the stream (this is necessary, since a closed stream would not be able to serve in a potentially required retry). If this method (wrapBodyInputStreamIfNecessary) is called on request with a stream, you have to enclose it in a try-finally block that calls com.oracle.bmc.io.internal.KeepOpenInputStream#closeStream(InputStream).

Example: 

try {
    request = Retriers.wrapBodyInputStreamIfNecessary(
        request, MyRequest.builder());
    ...
} finally {
    com.oracle.bmc.io.internal.KeepOpenInputStream.closeStream(
        request.getBody$());
}
Parameters
<T>
type of the request
request:T

request being handled

builder:BmcRequest.Builder<T, InputStream>

builder for the request

retryConfiguration:RetryConfiguration

the effective retry configuration for this request

Returns:T

request with the input stream wrapped

Annotations
@InternalSdk
wrapInputStreamForRetryback to summary
public static InputStream wrapInputStreamForRetry(InputStream body)

Wrap the input stream so retries can work.

Note

The stream in the request may be wrapped in a com.oracle.bmc.io.internal.KeepOpenInputStream, which prevents a call to close() from actually closing the stream (this is necessary, since a closed stream would not be able to serve in a potentially required retry).

After using this method, you now have to close the stream in a try-finally block that calls com.oracle.bmc.io.internal.KeepOpenInputStream#closeStream(InputStream).

Example: 

try {
    stream = Retriers.wrapInputStreamForRetry(stream);
    ...
} finally {
    com.oracle.bmc.io.internal.KeepOpenInputStream.closeStream(stream);
}
Parameters
body:InputStream

input stream body

Returns:InputStream

the input stream wrapped

Annotations
@InternalSdk