com.oracle.bmc.retrier

Class Retriers

java.lang.Object

com.oracle.bmc.retrier.Retriers

public final class Retriers
extends Object

Group of utility methods to configure the SDK retry behavior

Method Summary

Modifier and Type	Method and Description
static BmcGenericRetrier	createPreferredRetrier(RetryConfiguration requestRetryConfiguration, RetryConfiguration clientRetryConfiguration) Choose the desired retry configuration and use it to create the retrier.
static BmcGenericRetrier	createPreferredRetrier(RetryConfiguration requestRetryConfiguration, RetryConfiguration clientRetryConfiguration, boolean specBasedDefaultRetryEnabled) Choose the desired retry configuration and use it to create the retrier.
static RetryConfiguration	getDefaultRetryConfiguration() Getter for the default retry configuration.
static RetryConfiguration	getPreferredRetryConfiguration(RetryConfiguration requestRetryConfiguration, RetryConfiguration clientRetryConfiguration, boolean specBasedDefaultRetryEnabled) Choose the desired retry configuration.
static void	setDefaultRetryConfiguration(RetryConfiguration retryConfiguration) Setter for the default retry configuration used in the SDK.
static boolean	shouldPrepareForRetryBecauseOfRetryConfiguration(RetryConfiguration rc) Returns true if the retry configuration indicates that we should prepare for retries.
static boolean	shouldSendOpcRetryToken() Gets whether the SDK is automatically sending the opc-retry-token header
static void	shouldSendOpcRetryToken(boolean shouldSendOpcRetryToken) Sets whether the SDK should automatically send the opc-retry-token header
static void	tryResetStreamForRetry(InputStream body) Try to reset the InputStream for the next retry, if supported.
static void	tryResetStreamForRetry(InputStream body, boolean failIfUnsupported) Try to reset the InputStream for the next retry, if supported.
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.
static InputStream	wrapInputStreamForRetry(InputStream body) Wrap the input stream so retries can work.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

setDefaultRetryConfiguration

public static void setDefaultRetryConfiguration(@Nonnull
                                                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 ClientConfiguration) or the request (via BmcRequest.setRetryConfiguration(RetryConfiguration))

Parameters:

retryConfiguration - the RetryConfiguration to use

getDefaultRetryConfiguration

public static RetryConfiguration getDefaultRetryConfiguration()

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

Returns:

the default RetryConfiguration set

shouldSendOpcRetryToken

public static void shouldSendOpcRetryToken(boolean shouldSendOpcRetryToken)

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

Parameters:

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

shouldSendOpcRetryToken

public static boolean shouldSendOpcRetryToken()

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

Returns:

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

createPreferredRetrier

public static BmcGenericRetrier createPreferredRetrier(@Nullable
                                                       RetryConfiguration requestRetryConfiguration,
                                                       @Nullable
                                                       RetryConfiguration clientRetryConfiguration)

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

Parameters:

requestRetryConfiguration - the retry configuration set on the request object

clientRetryConfiguration - the retry configuration set on the client object

Returns:

The retrier based on the appropriate retry configuration

createPreferredRetrier

public static BmcGenericRetrier createPreferredRetrier(@Nullable
                                                       RetryConfiguration requestRetryConfiguration,
                                                       @Nullable
                                                       RetryConfiguration clientRetryConfiguration,
                                                       boolean specBasedDefaultRetryEnabled)

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

Parameters:

requestRetryConfiguration - the retry configuration set on the request object

clientRetryConfiguration - the retry configuration set on the client object

specBasedDefaultRetryEnabled - boolean value indicating if default retry is enabled via spec

Returns:

The retrier based on the appropriate retry configuration

getPreferredRetryConfiguration

public static RetryConfiguration getPreferredRetryConfiguration(@Nullable
                                                                RetryConfiguration requestRetryConfiguration,
                                                                @Nullable
                                                                RetryConfiguration clientRetryConfiguration,
                                                                boolean specBasedDefaultRetryEnabled)

Choose the desired retry configuration.

Parameters:

requestRetryConfiguration - the retry configuration set on the request object

clientRetryConfiguration - the retry configuration set on the client object

specBasedDefaultRetryEnabled - boolean value indicating if default retry is enabled via spec

Returns:

The appropriate retry configuration

shouldPrepareForRetryBecauseOfRetryConfiguration

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 - retry configuration

Returns:

true if we should prepare for retries

tryResetStreamForRetry

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 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 KeepOpenInputStream directly, but users are not supposed to do that, since it's an internal class.

Parameters:

body -

Throws:

IllegalArgumentException - if stream does not support being reset

RuntimeException - if stream does support being reset, but the reset failed

tryResetStreamForRetry

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 BufferedInputStream before they are sent here.

Parameters:

body -

failIfUnsupported - if true, fail if unsupported

Throws:

IllegalArgumentException - if stream does not support being reset and failIfUnsupported is true

RuntimeException - if stream does support being reset, but the reset failed

wrapBodyInputStreamIfNecessary

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 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 KeepOpenInputStream.closeStream(InputStream).

Example:

try {
    request = Retriers.wrapBodyInputStreamIfNecessary(
        request, MyRequest.builder());
    ...
} finally {
    com.oracle.bmc.io.internal.KeepOpenInputStream.closeStream(
        request.getBody$());
}

Type Parameters:

T - type of the request

Parameters:

request - request being handled

builder - builder for the request

retryConfiguration - the effective retry configuration for this request

Returns:

request with the input stream wrapped

wrapInputStreamForRetry

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 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 KeepOpenInputStream.closeStream(InputStream).

Example:

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

Parameters:

body - input stream body

Returns:

the input stream wrapped