com.ksc.retry.RetryPolicy Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of ksyun-java-sdk-core Show documentation
The KSC SDK for Java - Core module holds the classes that is used by the individual service clients to interact with KSC Web Services. Users need to depend on KSC-java-sdk artifact for accessing individual client classes.
The newest version!
/*
 * Copyright 2010-2016 ksyun.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://ksyun.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.ksc.retry;

import org.apache.http.annotation.Immutable;

import com.ksc.KscClientException;
import com.ksc.KscWebServiceRequest;
import com.ksc.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
 */
@Immutable
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 {
        public static final RetryCondition NO_RETRY_CONDITION = new RetryCondition() {
            @Override
            public boolean shouldRetry(KscWebServiceRequest originalRequest,
                    KscClientException exception, int retriesAttempted) {
                return false;
            }
            
        };

        /**
         * 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:
         * 
         *    if it has already reached the max retry limit,
         *   
 if the request contains non-repeatable content,
         *   
 if any RuntimeException or Error is thrown when executing the request.
         * 
         * 
         * @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:
         *            
         *            AmazonServiceException (sub-class of
         *            AmazonClientException) indicating a service error
         *            
AmazonClientException caused by an IOException when
         *            executing the HTTP request.
         *            
         *            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(KscWebServiceRequest originalRequest,
                                   KscClientException exception,
                                   int retriesAttempted);
        
    }

    /**
     * The hook for providing custom back-off strategy to control the sleep time
     * between retries.
     */
    public static interface BackoffStrategy {
        public static final BackoffStrategy NO_DELAY = new BackoffStrategy() {
            @Override
            public long delayBeforeNextRetry(KscWebServiceRequest originalRequest,
                    KscClientException exception, int retriesAttempted) {
                return 0;
            }
        };
        
        /**
         * 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:
         *            
         *              AmazonServiceException (sub-class of
         *                  AmazonClientException) indicating a service error
         *              
AmazonClientException caused by an IOException when
         *                  executing the HTTP request.
         *            
         *            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(KscWebServiceRequest originalRequest,
                                         KscClientException exception,
                                         int retriesAttempted);
    }
}