/*
* Copyright 2010-2016 Amazon.com, Inc. or its affiliates. All Rights Reserved.
*
* Licensed under the Apache License, Version 2.0 (the "License").
* You may not use this file except in compliance with the License.
* A copy of the License is located at
*
* http://aws.amazon.com/apache2.0
*
* or in the "license" file accompanying this file. This file is distributed
* on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
* express or implied. See the License for the specific language governing
* permissions and limitations under the License.
*/
package com.amazonaws.retry;
import com.amazonaws.AmazonClientException;
import com.amazonaws.AmazonWebServiceRequest;
import com.amazonaws.ClientConfiguration;
/**
* Retry policy that can be configured on a specific service client using
* {@link ClientConfiguration}. This class is immutable, therefore safe to be
* shared by multiple clients.
*
* @see ClientConfiguration
* @see PredefinedRetryPolicies
*/
public final class RetryPolicy {
/**
* Condition on whether a request should be retried. This field should not
* be null.
*/
private final RetryCondition retryCondition;
/**
* Back-off strategy to control the sleep time between retry attempts. This
* field should not be null.
*/
private final BackoffStrategy backoffStrategy;
/**
* Non-negative integer indicating the max retry count.
*/
private final int maxErrorRetry;
/**
* Whether this retry policy should honor the max error retry set in
* ClientConfiguration.
*
* @see ClientConfiguration#setMaxErrorRetry(int)
*/
private final boolean honorMaxErrorRetryInClientConfig;
/**
* Constructs a new retry policy. See {@link PredefinedRetryPolicies} for
* some pre-defined policy components, and also the default policies used by
* SDK.
*
* @param retryCondition Retry condition on whether a specific request and
* exception should be retried. If null value is specified, the
* SDK' default retry condition is used.
* @param backoffStrategy Back-off strategy for controlling how long the
* next retry should wait. If null value is specified, the SDK'
* default exponential back-off strategy is used.
* @param maxErrorRetry Maximum number of retry attempts for failed
* requests.
* @param honorMaxErrorRetryInClientConfig Whether this retry policy should
* honor the max error retry set by
* {@link ClientConfiguration#setMaxErrorRetry(int)}
* @see ClientConfiguration
* @see PredefinedRetryPolicies
*/
public RetryPolicy(RetryCondition retryCondition,
BackoffStrategy backoffStrategy,
int maxErrorRetry,
boolean honorMaxErrorRetryInClientConfig) {
if (retryCondition == null) {
retryCondition = PredefinedRetryPolicies.DEFAULT_RETRY_CONDITION;
}
if (backoffStrategy == null) {
backoffStrategy = PredefinedRetryPolicies.DEFAULT_BACKOFF_STRATEGY;
}
if (maxErrorRetry < 0) {
throw new IllegalArgumentException(
"Please provide a non-negative value for maxErrorRetry.");
}
this.retryCondition = retryCondition;
this.backoffStrategy = backoffStrategy;
this.maxErrorRetry = maxErrorRetry;
this.honorMaxErrorRetryInClientConfig = honorMaxErrorRetryInClientConfig;
};
/**
* Returns the retry condition included in this retry policy.
*
* @return The retry condition included in this retry policy.
*/
public RetryCondition getRetryCondition() {
return retryCondition;
}
/**
* Returns the back-off strategy included in this retry policy.
*
* @return The back-off strategy included in this retry policy.
*/
public BackoffStrategy getBackoffStrategy() {
return backoffStrategy;
}
/**
* Returns the maximum number of retry attempts.
*
* @return The maximum number of retry attempts.
*/
public int getMaxErrorRetry() {
return maxErrorRetry;
}
/**
* Returns whether this retry policy should honor the max error retry set in
* ClientConfiguration.
*
* @return Whether this retry policy should honor the max error retry set in
* ClientConfiguration
* @see ClientConfiguration#setMaxErrorRetry(int)
*/
public boolean isMaxErrorRetryInClientConfigHonored() {
return honorMaxErrorRetryInClientConfig;
}
/**
* The hook for providing custom condition on whether a failed request
* should be retried.
*/
public static interface RetryCondition {
/**
* Returns whether a failed request should be retried according to the
* given request context. In the following circumstances, the request
* will fail directly without consulting this method:
* <ul>
* <li>if it has already reached the max retry limit,
* <li>if the request contains non-repeatable content,
* <li>if any RuntimeException or Error is thrown when executing the
* request.
* </ul>
*
* @param originalRequest The original request object being executed.
* For performance reason, this object is not a defensive
* copy, and caller should not attempt to modify its data.
* @param exception The exception from the failed request, represented
* as an AmazonClientException object. There are two types of
* exception that will be passed to this method:
* <ul>
* <li>AmazonServiceException (sub-class of
* AmazonClientException) indicating a service error
* <li>AmazonClientException caused by an IOException when
* executing the HTTP request.
* </ul>
* Any other exceptions are regarded as unexpected failures
* and are thrown immediately without any retry. For
* performance reason, this object is not a defensive copy,
* and caller should not attempt to modify its data.
* @param retriesAttempted The number of times the current request has
* been attempted.
* @return True if the failed request should be retried.
*/
public boolean shouldRetry(AmazonWebServiceRequest originalRequest,
AmazonClientException exception,
int retriesAttempted);
}
/**
* The hook for providing custom back-off strategy to control the sleep time
* between retries.
*/
public static interface BackoffStrategy {
/**
* Returns the delay (in milliseconds) before next retry attempt.
*
* @param originalRequest The original request object being executed.
* For performance reason, this object is not a defensive
* copy, and caller should not attempt to modify its data.
* @param exception The exception from the failed request, represented
* as an AmazonClientException object. There are two types of
* exception that will be passed to this method:
* <ul>
* <li>AmazonServiceException (sub-class of
* AmazonClientException) indicating a service error
* <li>AmazonClientException caused by an IOException when
* executing the HTTP request.
* </ul>
* Any other exceptions are regarded as unexpected failures
* and are thrown immediately without any retry. For
* performance reason, this object is not a defensive copy,
* and caller should not attempt to modify its data.
* @param retriesAttempted The number of times the current request has
* been attempted (not including the next attempt after the
* delay).
* @return The delay (in milliseconds) before next retry attempt.
*/
public long delayBeforeNextRetry(AmazonWebServiceRequest originalRequest,
AmazonClientException exception,
int retriesAttempted);
}
}