Package com.oracle.bmc.retrier

Class Retriers

  • public final class Retriers
extends Object
    Group of utility methods to configure the SDK retry behavior

    • Method Detail

      • 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