tessl/maven-com-amazonaws--aws-java-sdk-core

Core foundational library for AWS SDK for Java 1.x providing authentication, HTTP transport, regions, protocols, and shared utilities for all AWS service clients

—

Pending

Overview

Eval results

Files

Retry Policies & Error Handling

Name: tessl/maven-com-amazonaws--aws-java-sdk-core
Author: tessl

The AWS Java SDK Core provides comprehensive retry logic with configurable policies, backoff strategies, and adaptive retry mechanisms to handle transient failures and service throttling.

Core Retry Framework

Retry Policy Configuration

// Retry policy configuration
class RetryPolicy {
    public RetryPolicy(RetryCondition retryCondition, 
                      BackoffStrategy backoffStrategy, 
                      int maxErrorRetry, 
                      boolean honorMaxErrorRetryInClientConfig);
    
    public RetryCondition getRetryCondition();
    public BackoffStrategy getBackoffStrategy();
    public int getMaxErrorRetry();
    public boolean isMaxErrorRetryInClientConfigHonored();
    public boolean shouldRetry(AmazonWebServiceRequest originalRequest,
                              AmazonClientException exception,
                              int retriesAttempted);
    public long delayBeforeNextRetry(AmazonWebServiceRequest originalRequest,
                                   AmazonClientException exception,
                                   int retriesAttempted);
    
    // Retry condition interface
    interface RetryCondition {
        boolean shouldRetry(AmazonWebServiceRequest originalRequest,
                           AmazonClientException exception,
                           int retriesAttempted);
    }
    
    // Backoff strategy interface
    interface BackoffStrategy {
        long delayBeforeNextRetry(AmazonWebServiceRequest originalRequest,
                                 AmazonClientException exception,
                                 int retriesAttempted);
    }
}

// Predefined retry policies
class PredefinedRetryPolicies {
    public static final RetryPolicy DEFAULT;
    public static final RetryPolicy NO_RETRY_POLICY;
    public static final RetryPolicy DEFAULT_MAX_ERROR_RETRY;
    public static final int DEFAULT_MAX_ERROR_RETRY_COUNT = 3;
    
    public static RetryPolicy getDynamoDBDefaultRetryPolicy();
    public static RetryPolicy getDynamoDBDefaultRetryPolicyWithCustomMaxRetries(int maxRetries);
}

// Retry mode enumeration
enum RetryMode {
    LEGACY("legacy"),
    STANDARD("standard"),
    ADAPTIVE("adaptive");
    
    public String getName();
    public static RetryMode fromName(String name);
}

// Retry utilities
class RetryUtils {
    public static boolean isRetryableServiceException(AmazonServiceException exception);
    public static boolean isThrottlingException(AmazonServiceException exception);
    public static boolean isClockSkewException(AmazonServiceException exception);
    public static boolean isRequestEntityTooLargeException(AmazonServiceException exception);
    public static int getRetryDelayMillis(int retryAttempt, long baseDelayInMilliseconds);
}

// Retry policy adapter
class RetryPolicyAdapter {
    public RetryPolicyAdapter(com.amazonaws.retry.v2.RetryPolicy v2RetryPolicy);
    public boolean shouldRetry(AmazonWebServiceRequest originalRequest,
                              AmazonClientException exception,
                              int retriesAttempted);
    public long delayBeforeNextRetry(AmazonWebServiceRequest originalRequest,
                                   AmazonClientException exception,
                                   int retriesAttempted);
}

Built-in Retry Conditions and Strategies

// V2 compatible backoff strategy
class V2CompatibleBackoffStrategy implements RetryPolicy.BackoffStrategy {
    public V2CompatibleBackoffStrategy(com.amazonaws.retry.v2.BackoffStrategy v2BackoffStrategy);
    public long delayBeforeNextRetry(AmazonWebServiceRequest originalRequest,
                                   AmazonClientException exception,
                                   int retriesAttempted);
}

// Predefined backoff strategies
class PredefinedBackoffStrategies {
    public static final RetryPolicy.BackoffStrategy STANDARD;
    public static final RetryPolicy.BackoffStrategy FULL_JITTER;
    public static final RetryPolicy.BackoffStrategy EQUAL_JITTER;
    public static final RetryPolicy.BackoffStrategy EXPONENTIAL;
    
    public static RetryPolicy.BackoffStrategy createFixedDelayBackoffStrategy(long delayMillis);
    public static RetryPolicy.BackoffStrategy createExponentialBackoffStrategy(long baseDelayMillis, 
                                                                               long maxDelayMillis);
}

V2 Retry Framework

V2 Retry Policy

// V2 retry policy interface
interface RetryPolicy {
    RetryCondition getRetryCondition();
    BackoffStrategy getBackoffStrategy();
    int getMaxErrorRetry();
    
    // Builder for creating retry policies
    static Builder builder() {
        return new Builder();
    }
    
    class Builder {
        public Builder retryCondition(RetryCondition retryCondition);
        public Builder backoffStrategy(BackoffStrategy backoffStrategy);
        public Builder maxErrorRetry(int maxErrorRetry);
        public RetryPolicy build();
    }
}

// V2 retry condition interface
interface RetryCondition {
    boolean shouldRetry(RetryPolicyContext context);
}

// V2 backoff strategy interface
interface BackoffStrategy {
    long computeDelayBeforeNextRetry(RetryPolicyContext context);
}

// Retry policy context
class RetryPolicyContext {
    public static RetryPolicyContext builder();
    public RetryPolicyContext originalRequest(AmazonWebServiceRequest originalRequest);
    public RetryPolicyContext exception(AmazonClientException exception);
    public RetryPolicyContext retriesAttempted(int retriesAttempted);
    public RetryPolicyContext totalRequests(int totalRequests);
    
    public AmazonWebServiceRequest originalRequest();
    public AmazonClientException exception();
    public int retriesAttempted();
    public int totalRequests();
}

// Simple retry policy implementation
class SimpleRetryPolicy implements RetryPolicy {
    public SimpleRetryPolicy(RetryCondition retryCondition, 
                           BackoffStrategy backoffStrategy, 
                           int maxErrorRetry);
    
    public RetryCondition getRetryCondition();
    public BackoffStrategy getBackoffStrategy();
    public int getMaxErrorRetry();
}

V2 Retry Conditions

// OR combination of retry conditions
class OrRetryCondition implements RetryCondition {
    public OrRetryCondition(RetryCondition... retryConditions);
    public boolean shouldRetry(RetryPolicyContext context);
}

// AND combination of retry conditions
class AndRetryCondition implements RetryCondition {
    public AndRetryCondition(RetryCondition... retryConditions);
    public boolean shouldRetry(RetryPolicyContext context);
}

// Retry on specific exceptions
class RetryOnExceptionsCondition implements RetryCondition {
    public RetryOnExceptionsCondition(Set<Class<? extends Exception>> exceptionsToRetryOn);
    public boolean shouldRetry(RetryPolicyContext context);
}

// Retry on HTTP status codes
class RetryOnStatusCodeCondition implements RetryCondition {
    public RetryOnStatusCodeCondition(Set<Integer> statusCodesToRetryOn);
    public boolean shouldRetry(RetryPolicyContext context);
}

// Maximum retry attempts condition
class MaxNumberOfRetriesCondition implements RetryCondition {
    public MaxNumberOfRetriesCondition(int maxNumberOfRetries);
    public boolean shouldRetry(RetryPolicyContext context);
}

V2 Backoff Strategies

// Fixed delay backoff strategy
class FixedDelayBackoffStrategy implements BackoffStrategy {
    public FixedDelayBackoffStrategy(long delayInMilliseconds);
    public long computeDelayBeforeNextRetry(RetryPolicyContext context);
}

Usage Examples

Basic Retry Policy Configuration

import com.amazonaws.retry.*;
import com.amazonaws.ClientConfiguration;

// Use default retry policy
ClientConfiguration config = new ClientConfiguration()
    .withRetryPolicy(PredefinedRetryPolicies.DEFAULT);

// Use no retry policy
ClientConfiguration noRetryConfig = new ClientConfiguration()
    .withRetryPolicy(PredefinedRetryPolicies.NO_RETRY_POLICY);

// Use default with custom max retries
ClientConfiguration customRetryConfig = new ClientConfiguration()
    .withMaxErrorRetry(5)
    .withRetryPolicy(PredefinedRetryPolicies.DEFAULT_MAX_ERROR_RETRY);

Custom Retry Policy

import com.amazonaws.retry.*;
import com.amazonaws.*;

// Custom retry condition
RetryPolicy.RetryCondition customCondition = new RetryPolicy.RetryCondition() {
    @Override
    public boolean shouldRetry(AmazonWebServiceRequest originalRequest,
                              AmazonClientException exception,
                              int retriesAttempted) {
        // Retry on service exceptions with 5xx status codes
        if (exception instanceof AmazonServiceException) {
            AmazonServiceException ase = (AmazonServiceException) exception;
            return ase.getStatusCode() >= 500 && retriesAttempted < 5;
        }
        
        // Retry on specific client exceptions
        if (exception instanceof AmazonClientException) {
            String message = exception.getMessage().toLowerCase();
            return (message.contains("connection") || message.contains("timeout")) 
                   && retriesAttempted < 3;
        }
        
        return false;
    }
};

// Custom backoff strategy with exponential backoff and jitter
RetryPolicy.BackoffStrategy customBackoff = new RetryPolicy.BackoffStrategy() {
    @Override
    public long delayBeforeNextRetry(AmazonWebServiceRequest originalRequest,
                                   AmazonClientException exception,
                                   int retriesAttempted) {
        // Base delay: 100ms * 2^retryAttempt
        long baseDelay = 100 * (1L << retriesAttempted);
        
        // Add jitter (random delay up to 50% of base delay)
        long jitter = (long) (Math.random() * baseDelay * 0.5);
        
        // Cap at 10 seconds
        return Math.min(baseDelay + jitter, 10000);
    }
};

// Create custom retry policy
RetryPolicy customRetryPolicy = new RetryPolicy(
    customCondition,
    customBackoff,
    5,  // max retry attempts
    true // honor client config max retry
);

// Use custom retry policy
ClientConfiguration config = new ClientConfiguration()
    .withRetryPolicy(customRetryPolicy);

V2 Retry Framework Usage

import com.amazonaws.retry.v2.*;
import java.util.*;

// Create retry conditions
RetryCondition serviceErrorCondition = new RetryOnStatusCodeCondition(
    new HashSet<>(Arrays.asList(500, 502, 503, 504))
);

RetryCondition throttlingCondition = new RetryOnStatusCodeCondition(
    new HashSet<>(Arrays.asList(429))
);

RetryCondition maxRetriesCondition = new MaxNumberOfRetriesCondition(3);

// Combine conditions
RetryCondition combinedCondition = new AndRetryCondition(
    new OrRetryCondition(serviceErrorCondition, throttlingCondition),
    maxRetriesCondition
);

// Create backoff strategy
BackoffStrategy backoffStrategy = new FixedDelayBackoffStrategy(1000); // 1 second

// Create V2 retry policy
com.amazonaws.retry.v2.RetryPolicy v2RetryPolicy = 
    com.amazonaws.retry.v2.RetryPolicy.builder()
        .retryCondition(combinedCondition)
        .backoffStrategy(backoffStrategy)
        .maxErrorRetry(3)
        .build();

// Adapt to V1 retry policy
RetryPolicy v1RetryPolicy = new RetryPolicyAdapter(v2RetryPolicy);

// Use in client configuration
ClientConfiguration config = new ClientConfiguration()
    .withRetryPolicy(v1RetryPolicy);

DynamoDB-Specific Retry Configuration

import com.amazonaws.retry.*;

// Use DynamoDB default retry policy (handles throttling)
RetryPolicy dynamoRetryPolicy = PredefinedRetryPolicies.getDynamoDBDefaultRetryPolicy();

// DynamoDB with custom max retries
RetryPolicy dynamoCustomRetryPolicy = 
    PredefinedRetryPolicies.getDynamoDBDefaultRetryPolicyWithCustomMaxRetries(10);

ClientConfiguration dynamoConfig = new ClientConfiguration()
    .withRetryPolicy(dynamoRetryPolicy);

Retry Mode Configuration

import com.amazonaws.retry.RetryMode;
import com.amazonaws.SDKGlobalConfiguration;

// Set global retry mode
System.setProperty(SDKGlobalConfiguration.RETRY_MODE_SYSTEM_PROPERTY, 
                  RetryMode.ADAPTIVE.getName());

// Or set via environment variable: AWS_RETRY_MODE=adaptive

// Check current retry mode
String retryModeProperty = System.getProperty(SDKGlobalConfiguration.RETRY_MODE_SYSTEM_PROPERTY);
RetryMode currentMode = RetryMode.fromName(retryModeProperty);

Advanced Retry Scenarios

import com.amazonaws.retry.*;
import com.amazonaws.*;

// Retry policy for specific error codes
RetryPolicy.RetryCondition errorCodeCondition = new RetryPolicy.RetryCondition() {
    @Override
    public boolean shouldRetry(AmazonWebServiceRequest originalRequest,
                              AmazonClientException exception,
                              int retriesAttempted) {
        if (exception instanceof AmazonServiceException) {
            AmazonServiceException ase = (AmazonServiceException) exception;
            String errorCode = ase.getErrorCode();
            
            // Retry on specific error codes
            Set<String> retryableErrorCodes = new HashSet<>(Arrays.asList(
                "Throttling", "ThrottledException", "ServiceUnavailable", 
                "InternalError", "RequestTimeout"
            ));
            
            return retryableErrorCodes.contains(errorCode) && retriesAttempted < 5;
        }
        return false;
    }
};

// Backoff with different strategies for different error types
RetryPolicy.BackoffStrategy adaptiveBackoff = new RetryPolicy.BackoffStrategy() {
    @Override
    public long delayBeforeNextRetry(AmazonWebServiceRequest originalRequest,
                                   AmazonClientException exception,
                                   int retriesAttempted) {
        if (exception instanceof AmazonServiceException) {
            AmazonServiceException ase = (AmazonServiceException) exception;
            
            // Longer delay for throttling
            if (RetryUtils.isThrottlingException(ase)) {
                return Math.min(1000 * (1L << retriesAttempted), 32000); // Cap at 32s
            }
            
            // Shorter delay for server errors
            if (ase.getStatusCode() >= 500) {
                return Math.min(200 * (1L << retriesAttempted), 5000); // Cap at 5s
            }
        }
        
        // Default exponential backoff
        return Math.min(100 * (1L << retriesAttempted), 10000); // Cap at 10s
    }
};

// Create adaptive retry policy
RetryPolicy adaptiveRetryPolicy = new RetryPolicy(
    errorCodeCondition,
    adaptiveBackoff,
    8, // Higher max retries for adaptive policy
    true
);

Retry Utilities Usage

import com.amazonaws.retry.RetryUtils;
import com.amazonaws.AmazonServiceException;

// Check if exception is retryable
public boolean handleException(AmazonServiceException exception) {
    if (RetryUtils.isRetryableServiceException(exception)) {
        System.out.println("Exception is retryable: " + exception.getErrorCode());
        
        if (RetryUtils.isThrottlingException(exception)) {
            System.out.println("Request was throttled");
            // Implement exponential backoff with jitter
        } else if (RetryUtils.isClockSkewException(exception)) {
            System.out.println("Clock skew detected");
            // Adjust system time or use server time
        } else if (RetryUtils.isRequestEntityTooLargeException(exception)) {
            System.out.println("Request payload too large");
            // Reduce request size or use multipart upload
        }
        
        return true;
    }
    
    return false;
}

// Calculate retry delay
public long calculateRetryDelay(int retryAttempt) {
    long baseDelay = 1000; // 1 second base delay
    return RetryUtils.getRetryDelayMillis(retryAttempt, baseDelay);
}

Exception-Specific Retry Logic

import com.amazonaws.retry.v2.*;
import java.util.*;

// Retry on connection exceptions
Set<Class<? extends Exception>> connectionExceptions = new HashSet<>();
connectionExceptions.add(java.net.ConnectException.class);
connectionExceptions.add(java.net.SocketTimeoutException.class);
connectionExceptions.add(java.net.UnknownHostException.class);

RetryCondition connectionRetryCondition = 
    new RetryOnExceptionsCondition(connectionExceptions);

// Retry on specific HTTP status codes
Set<Integer> retryableStatusCodes = new HashSet<>();
retryableStatusCodes.add(408); // Request Timeout
retryableStatusCodes.add(429); // Too Many Requests
retryableStatusCodes.add(500); // Internal Server Error
retryableStatusCodes.add(502); // Bad Gateway
retryableStatusCodes.add(503); // Service Unavailable
retryableStatusCodes.add(504); // Gateway Timeout

RetryCondition statusCodeRetryCondition = 
    new RetryOnStatusCodeCondition(retryableStatusCodes);

// Combine with max retries
RetryCondition finalCondition = new AndRetryCondition(
    new OrRetryCondition(connectionRetryCondition, statusCodeRetryCondition),
    new MaxNumberOfRetriesCondition(5)
);

Retry Best Practices

Use Appropriate Retry Policies: Start with predefined policies and customize only when necessary.
Implement Exponential Backoff: Use exponential backoff with jitter to avoid thundering herd problems.
Set Maximum Retry Limits: Always set reasonable maximum retry limits to prevent infinite loops.
Handle Different Error Types: Implement different retry logic for throttling vs server errors vs network errors.
Monitor Retry Metrics: Track retry attempts and success rates to tune retry policies.
Consider Circuit Breakers: For high-volume applications, consider implementing circuit breaker patterns.
Service-Specific Policies: Use service-specific retry policies (e.g., DynamoDB) when available.
Adaptive Retry: Consider using adaptive retry mode for applications with varying traffic patterns.
Timeout Configuration: Ensure retry timeouts are configured appropriately with overall request timeouts.
Error Logging: Log retry attempts with appropriate detail for debugging and monitoring.

The retry system provides comprehensive error handling and resilience capabilities, enabling applications to gracefully handle transient failures and service throttling with configurable retry logic and backoff strategies.

Install with Tessl CLI

npx tessl i tessl/maven-com-amazonaws--aws-java-sdk-core

docs

arn-support.md

authentication.md

client-builders.md

endpoint-discovery.md

exception-handling.md

http-transport.md

index.md

metrics-monitoring.md