Aws Sdk Java V2 Core

AWS SDK for Java 2.x Core Patterns

Overview

Use this skill to set up AWS SDK for Java 2.x clients with production-safe defaults.

It focuses on the decisions that matter most:

• how credentials and region are resolved
• how to configure sync and async HTTP clients
• how to apply timeouts, retries, lifecycle management, and tests

Keep SKILL.md focused on setup and delivery flow. Use the references/ files for deeper API details and expanded examples.

When to Use

• Creating or hardening AWS SDK for Java 2.x service clients
• Wiring Spring Boot beans for AWS integration
• Debugging auth, region, or credential issues
• Choosing between sync (S3Client, DynamoDbClient) and async (S3AsyncClient, SqsAsyncClient) clients

Instructions

1. Select the service client type

• Sync clients (S3Client, DynamoDbClient) for request/response flows
• Async clients (S3AsyncClient, SqsAsyncClient) for concurrency, streaming, or backpressure
• Reuse one client per service and configuration profile

2. Configure credential and region resolution

Use DefaultCredentialsProvider with environment-aware defaults:

• local dev: shared AWS config, SSO, or environment variables
• CI/CD: web identity or injected environment variables
• AWS runtime: ECS task roles, EKS IRSA, or EC2 instance profiles

Override only for multi-account access, test isolation, or profile switching.

Verify: Call StsClient.getCallerIdentity() at startup to confirm credentials resolve.

3. Configure HTTP client, timeouts, and retries

Set production values explicitly:

• API call timeout and attempt timeout
• connection timeout and max connections or concurrency
• retry strategy aligned with service quotas and idempotency

Use ApacheHttpClient for sync and NettyNioAsyncHttpClient for async.

Verify: Confirm timeouts and retry behavior under failure conditions.

4. Wire clients as application-level dependencies

In Spring Boot:

• expose clients as @Bean singletons
• inject through constructors
• keep credential and region in configuration files

Verify: Check clients are not created inside hot execution paths.

Close custom HTTP clients and SDK clients during shutdown if lifecycle is not managed automatically.

5. Handle failures at integration boundaries

At the boundary layer:

• catch SdkException or service-specific exceptions
• distinguish retryable failures from auth, quota, and validation failures
• log request context, never secrets or raw credentials

6. Run integration tests before shipping

• verify region and caller identity in the target environment
• run tests against LocalStack, Testcontainers, or a sandbox account
• use @PostConstruct in Spring Boot configuration to fail fast on startup if credentials are missing

StsClient stsClient = StsClient.builder().build();
GetCallerIdentityResponse identity = stsClient.getCallerIdentity();
// Logs: Successfully authenticated as: {identity.arn()}

Examples

Example 1: Spring Boot sync client with explicit HTTP and timeout settings

@Configuration
public class AwsClientConfiguration {

    @Bean
    S3Client s3Client() {
        return S3Client.builder()
            .region(Region.of("eu-south-2"))
            .credentialsProvider(DefaultCredentialsProvider.create())
            .httpClientBuilder(ApacheHttpClient.builder()
                .maxConnections(100)
                .connectionTimeout(Duration.ofSeconds(3)))
            .overrideConfiguration(ClientOverrideConfiguration.builder()
                .apiCallAttemptTimeout(Duration.ofSeconds(10))
                .apiCallTimeout(Duration.ofSeconds(30))
                .build())
            .build();
    }
}

Example 2: Async client for high-concurrency workloads

SqsAsyncClient sqsAsyncClient = SqsAsyncClient.builder()
    .region(Region.US_EAST_1)
    .credentialsProvider(DefaultCredentialsProvider.create())
    .httpClientBuilder(NettyNioAsyncHttpClient.builder()
        .maxConcurrency(200)
        .connectionTimeout(Duration.ofSeconds(3))
        .readTimeout(Duration.ofSeconds(20)))
    .overrideConfiguration(ClientOverrideConfiguration.builder()
        .apiCallTimeout(Duration.ofSeconds(30))
        .build())
    .build();

Best Practices

• Default to DefaultCredentialsProvider unless a project requirement says otherwise.
• Keep region selection explicit for server-side services.
• Reuse SDK clients instead of constructing them per request.
• Tune retries with service quotas and idempotency in mind.
• Put business mapping on top of the SDK, not inside controllers.
• Keep integration tests close to the configuration that creates the clients.
• Move deep service-specific examples to dedicated skills such as S3, DynamoDB, Bedrock, or Secrets Manager.

Constraints and Warnings

• Do not embed access keys or session tokens in source code, examples, or configuration files.
• Static credentials are acceptable only for tightly scoped local tests.
• Missing region or invalid credential resolution often fails only at first call, so verify startup assumptions explicitly.
• Async clients require lifecycle management for the underlying HTTP resources.
• Excessive retries can amplify throttling and increase latency.
• Proxy, TLS, and metric publisher APIs can vary by chosen HTTP stack and SDK version; adapt examples to the versions already used by the project.

References

• references/api-reference.md
• references/best-practices.md
• references/developer-guide.md

Related Skills

• aws-sdk-java-v2-secrets-manager
• aws-sdk-java-v2-s3
• aws-sdk-java-v2-dynamodb
• aws-sdk-java-v2-bedrock

AWS SDK for Java 2.x API Reference

Core Client Classes

AwsClient

Base interface for all AWS service clients.

public interface AwsClient extends AutoCloseable {
    // Base client interface
}

SdkClient

Enhanced client interface with SDK-specific features.

public interface SdkClient extends AwsClient {
    // Enhanced client methods
}

Client Builders

ClientBuilder

Base builder interface for all AWS service clients.

Key Methods:

• region(Region region) - Set AWS region
• credentialsProvider(CredentialsProvider credentialsProvider) - Configure authentication
• overrideConfiguration(ClientOverrideConfiguration overrideConfiguration) - Override default settings
• httpClient(HttpClient httpClient) - Specify HTTP client implementation
• build() - Create client instance

Configuration Classes

ClientOverrideConfiguration

Controls client-level configuration including timeouts and metrics.

Key Properties:

• apiCallTimeout(Duration) - Total timeout for all retry attempts
• apiCallAttemptTimeout(Duration) - Timeout per individual attempt
• retryPolicy(RetryPolicy) - Retry behavior configuration
• metricPublishers(MetricPublisher...) - Enable metrics collection

Builder Example

ClientOverrideConfiguration config = ClientOverrideConfiguration.builder()
    .apiCallTimeout(Duration.ofSeconds(30))
    .apiCallAttemptTimeout(Duration.ofSeconds(10))
    .addMetricPublisher(CloudWatchMetricPublisher.create())
    .build();

HTTP Client Implementations

ApacheHttpClient

Synchronous HTTP client with advanced features.

Builder Configuration:

• maxConnections(Integer) - Maximum concurrent connections
• connectionTimeout(Duration) - Connection establishment timeout
• socketTimeout(Duration) - Socket read/write timeout
• connectionTimeToLive(Duration) - Connection lifetime
• proxyConfiguration(ProxyConfiguration) - Proxy settings

NettyNioAsyncHttpClient

Asynchronous HTTP client for high-performance applications.

Builder Configuration:

• maxConcurrency(Integer) - Maximum concurrent operations
• connectionTimeout(Duration) - Connection timeout
• readTimeout(Duration) - Read operation timeout
• writeTimeout(Duration) - Write operation timeout
• sslProvider(SslProvider) - SSL/TLS implementation

UrlConnectionHttpClient

Lightweight HTTP client using Java's URLConnection.

Builder Configuration:

• socketTimeout(Duration) - Socket timeout
• connectTimeout(Duration) - Connection timeout

Authentication and Credentials

Credential Providers

EnvironmentVariableCredentialsProvider

Reads credentials from environment variables.

CredentialsProvider provider = EnvironmentVariableCredentialsProvider.create();

SystemPropertyCredentialsProvider

Reads credentials from Java system properties.

CredentialsProvider provider = SystemPropertyCredentialsProvider.create();

ProfileCredentialsProvider

Reads credentials from AWS configuration files.

CredentialsProvider provider = ProfileCredentialsProvider.create("profile-name");

StaticCredentialsProvider

Provides static credentials (not recommended for production).

AwsBasicCredentials credentials = AwsBasicCredentials.create("key", "secret");
CredentialsProvider provider = StaticCredentialsProvider.create(credentials);

DefaultCredentialsProvider

Implements the default credential provider chain.

CredentialsProvider provider = DefaultCredentialsProvider.create();

SSO Authentication

AwsSsoCredentialsProvider

Enables SSO-based authentication.

AwsSsoCredentialsProvider ssoProvider = AwsSsoCredentialsProvider.builder()
    .ssoProfile("my-sso-profile")
    .build();

Error Handling Classes

SdkClientException

Client-side exceptions (network, timeout, configuration issues).

try {
    awsOperation();
} catch (SdkClientException e) {
    // Handle client-side errors
}

SdkServiceException

Service-side exceptions (AWS service errors).

try {
    awsOperation();
} catch (SdkServiceException e) {
    // Handle service-side errors
    System.err.println("Error Code: " + e.awsErrorDetails().errorCode());
    System.err.println("Request ID: " + e.requestId());
}

S3Exception

S3-specific exceptions.

try {
    s3Operation();
} catch (S3Exception e) {
    // Handle S3-specific errors
    System.err.println("S3 Error: " + e.awsErrorDetails().errorMessage());
}

Metrics and Monitoring

CloudWatchMetricPublisher

Publishes metrics to AWS CloudWatch.

CloudWatchMetricPublisher publisher = CloudWatchMetricPublisher.create();

MetricPublisher

Base interface for custom metrics publishers.

public interface MetricPublisher {
    void publish(MetricCollection metricCollection);
}

Utility Classes

Duration and Time

Configure timeouts using Java Duration.

Duration apiTimeout = Duration.ofSeconds(30);
Duration attemptTimeout = Duration.ofSeconds(10);

Region

AWS regions for service endpoints.

Region region = Region.US_EAST_1;
Region regionEU = Region.EU_WEST_1;

URI

Endpoint configuration and proxy settings.

URI proxyUri = URI.create("http://proxy:8080");
URI endpointOverride = URI.create("http://localhost:4566");

Configuration Best Practices

Resource Management

Always close clients when no longer needed.

try (S3Client s3 = S3Client.builder().build()) {
    // Use client
} // Auto-closed

Connection Pooling

Reuse clients to avoid connection pool overhead.

@Service
public class AwsService {
    private final S3Client s3Client;

    public AwsService() {
        this.s3Client = S3Client.builder().build();
    }

    // Reuse s3Client throughout application
}

Error Handling

Implement comprehensive error handling for robust applications.

try {
    // AWS operation
} catch (SdkServiceException e) {
    // Handle service errors
} catch (SdkClientException e) {
    // Handle client errors
} catch (Exception e) {
    // Handle other errors
}

AWS SDK for Java 2.x Best Practices

Client Configuration

Timeout Configuration

Always configure both API call and attempt timeouts to prevent hanging requests.

ClientOverrideConfiguration config = ClientOverrideConfiguration.builder()
    .apiCallTimeout(Duration.ofSeconds(30))        // Total for all retries
    .apiCallAttemptTimeout(Duration.ofSeconds(10))  // Per-attempt timeout
    .build();

Best Practices:

• Set apiCallTimeout higher than apiCallAttemptTimeout
• Use appropriate timeouts based on your service's characteristics
• Consider network latency and service response times
• Monitor timeout metrics to adjust as needed

HTTP Client Selection

Choose the appropriate HTTP client for your use case.

For Synchronous Applications (Apache HttpClient)

ApacheHttpClient httpClient = ApacheHttpClient.builder()
    .maxConnections(100)
    .connectionTimeout(Duration.ofSeconds(5))
    .socketTimeout(Duration.ofSeconds(30))
    .build();

Best Use Cases:

• Traditional synchronous applications
• Medium-throughput operations
• When blocking behavior is acceptable

For Asynchronous Applications (Netty NIO Client)

NettyNioAsyncHttpClient httpClient = NettyNioAsyncHttpClient.builder()
    .maxConcurrency(100)
    .connectionTimeout(Duration.ofSeconds(5))
    .readTimeout(Duration.ofSeconds(30))
    .writeTimeout(Duration.ofSeconds(30))
    .sslProvider(SslProvider.OPENSSL)
    .build();

Best Use Cases:

• High-throughput applications
• I/O-bound operations
• When non-blocking behavior is required
• For improved SSL performance

For Lightweight Applications (URL Connection Client)

UrlConnectionHttpClient httpClient = UrlConnectionHttpClient.builder()
    .socketTimeout(Duration.ofSeconds(30))
    .build();

Best Use Cases:

• Simple applications with low requirements
• When minimizing dependencies
• For basic operations

Authentication and Security

Credential Management

Default Provider Chain

// Use default chain (recommended)
S3Client s3Client = S3Client.builder().build();

Default Chain Order: 1. Java system properties (aws.accessKeyId, aws.secretAccessKey) 2. Environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY) 3. Web identity token from AWS_WEB_IDENTITY_TOKEN_FILE 4. Shared credentials file (~/.aws/credentials) 5. Config file (~/.aws/config) 6. Amazon ECS container credentials 7. Amazon EC2 instance profile credentials

Explicit Credential Provider

// Use specific credential provider
CredentialsProvider credentials = ProfileCredentialsProvider.create("my-profile");

S3Client s3Client = S3Client.builder()
    .credentialsProvider(credentials)
    .build();

IAM Roles (Preferred for Production)

// Use IAM role credentials
CredentialsProvider instanceProfile = InstanceProfileCredentialsProvider.create();

S3Client s3Client = S3Client.builder()
    .credentialsProvider(instanceProfile)
    .build();

Security Best Practices

1. Never hardcode credentials - Use credential providers or environment variables 2. Use IAM roles - Prefer over access keys when possible 3. Implement credential rotation - For long-lived access keys 4. Apply least privilege - Grant minimum required permissions 5. Enable SSL - Always use HTTPS (default behavior) 6. Monitor access - Enable AWS CloudTrail for auditing 7. Use SSO for human users - Instead of long-term credentials

Resource Management

Client Lifecycle

// Option 1: Try-with-resources (recommended)
try (S3Client s3 = S3Client.builder().build()) {
    // Use client
} // Auto-closed

// Option 2: Explicit close
S3Client s3 = S3Client.builder().build();
try {
    // Use client
} finally {
    s3.close();
}

Stream Handling

Close streams immediately to prevent connection pool exhaustion.

try (ResponseInputStream<GetObjectResponse> response =
        s3Client.getObject(GetObjectRequest.builder()
            .bucket(bucketName)
            .key(objectKey)
            .build())) {

    // Read and process data immediately
    byte[] data = response.readAllBytes();

} // Stream auto-closed, connection returned to pool

Performance Optimization

Connection Pooling

// Configure connection pooling
ApacheHttpClient httpClient = ApacheHttpClient.builder()
    .maxConnections(100)          // Adjust based on your needs
    .connectionTimeout(Duration.ofSeconds(5))
    .socketTimeout(Duration.ofSeconds(30))
    .connectionTimeToLive(Duration.ofMinutes(5))
    .build();

Best Practices:

• Set appropriate maxConnections based on expected load
• Consider connection time to live (TTL)
• Monitor connection pool metrics
• Use appropriate timeouts

SSL Optimization

Use OpenSSL with Netty for better SSL performance.

<!-- Maven dependency -->
<dependency>
    <groupId>io.netty</groupId>
    <artifactId>netty-tcnative-boringssl-static</artifactId>
    <version>2.0.61.Final</version>
    <scope>runtime</scope>
</dependency>

// Use OpenSSL for async clients
NettyNioAsyncHttpClient httpClient = NettyNioAsyncHttpClient.builder()
    .sslProvider(SslProvider.OPENSSL)
    .build();

Async for I/O-Bound Operations

// Use async clients for I/O-bound operations
S3AsyncClient s3AsyncClient = S3AsyncClient.builder()
    .httpClient(httpClient)
    .build();

// Use CompletableFuture for non-blocking operations
CompletableFuture<PutObjectResponse> future = s3AsyncClient.putObject(request);
future.thenAccept(response -> {
    // Handle success
}).exceptionally(error -> {
    // Handle error
    return null;
});

Monitoring and Observability

Enable SDK Metrics

CloudWatchMetricPublisher publisher = CloudWatchMetricPublisher.create();

S3Client s3Client = S3Client.builder()
    .overrideConfiguration(b -> b
        .addMetricPublisher(publisher))
    .build();

CloudWatch Integration

Configure CloudWatch metrics publisher to collect SDK metrics.

CloudWatchMetricPublisher cloudWatchPublisher = CloudWatchMetricPublisher.builder()
    .namespace("MyApplication")
    .credentialProvider(credentials)
    .build();

Custom Metrics

Implement custom metrics for application-specific monitoring.

public class CustomMetricPublisher implements MetricPublisher {
    @Override
    public void publish(MetricCollection metrics) {
        // Implement custom metrics logic
        metrics.forEach(metric -> {
            System.out.println("Metric: " + metric.name() + " = " + metric.value());
        });
    }
}

Error Handling

Comprehensive Error Handling

try {
    awsOperation();
} catch (SdkServiceException e) {
    // Service-specific error
    System.err.println("AWS Service Error: " + e.awsErrorDetails().errorMessage());
    System.err.println("Error Code: " + e.awsErrorDetails().errorCode());
    System.err.println("Status Code: " + e.statusCode());
    System.err.println("Request ID: " + e.requestId());

} catch (SdkClientException e) {
    // Client-side error (network, timeout, etc.)
    System.err.println("Client Error: " + e.getMessage());

} catch (Exception e) {
    // Other errors
    System.err.println("Unexpected Error: " + e.getMessage());
}

Retry Configuration

RetryPolicy retryPolicy = RetryPolicy.builder()
    .numRetries(3)
    .retryCondition(RetryCondition.defaultRetryCondition())
    .backoffStrategy(BackoffStrategy.defaultStrategy())
    .build();

Testing Strategies

Local Testing with LocalStack

@TestConfiguration
public class LocalStackConfig {
    @Bean
    public S3Client s3Client() {
        return S3Client.builder()
            .endpointOverride(URI.create("http://localhost:4566"))
            .credentialsProvider(StaticCredentialsProvider.create(
                AwsBasicCredentials.create("test", "test")))
            .build();
    }
}

Testcontainers Integration

@Testcontainers
@SpringBootTest
public class AwsIntegrationTest {

    @Container
    static LocalStackContainer localstack = new LocalStackContainer(DockerImageName.parse("localstack/localstack:3.0"))
        .withServices(LocalStackContainer.Service.S3);

    @DynamicPropertySource
    static void configProperties(DynamicPropertyRegistry registry) {
        registry.add("aws.endpoint", () -> localstack.getEndpointOverride(LocalStackContainer.Service.S3));
    }
}

Configuration Templates

High-Throughput Configuration

ApacheHttpClient highThroughputClient = ApacheHttpClient.builder()
    .maxConnections(200)
    .connectionTimeout(Duration.ofSeconds(3))
    .socketTimeout(Duration.ofSeconds(30))
    .connectionTimeToLive(Duration.ofMinutes(10))
    .build();

S3Client s3Client = S3Client.builder()
    .region(Region.US_EAST_1)
    .httpClient(highThroughputClient)
    .overrideConfiguration(b -> b
        .apiCallTimeout(Duration.ofSeconds(45))
        .apiCallAttemptTimeout(Duration.ofSeconds(15)))
    .build();

Low-Latency Configuration

ApacheHttpClient lowLatencyClient = ApacheHttpClient.builder()
    .maxConnections(50)
    .connectionTimeout(Duration.ofSeconds(2))
    .socketTimeout(Duration.ofSeconds(10))
    .build();

S3Client s3Client = S3Client.builder()
    .region(Region.US_EAST_1)
    .httpClient(lowLatencyClient)
    .overrideConfiguration(b -> b
        .apiCallTimeout(Duration.ofSeconds(15))
        .apiCallAttemptTimeout(Duration.ofSeconds(3)))
    .build();

AWS SDK for Java 2.x Developer Guide

Overview

The AWS SDK for Java 2.x provides a modern, type-safe API for AWS services. Built on Java 8+, it offers improved performance, better error handling, and enhanced security compared to v1.x.

Key Features

• Modern Architecture: Built on Java 8+ with reactive and async support
• Type Safety: Comprehensive type annotations and validation
• Performance Optimized: Connection pooling, async support, and SSL optimization
• Enhanced Security: Better credential management and security practices
• Extensive Coverage: Support for all AWS services with regular updates

Core Concepts

Service Clients

The primary interface for interacting with AWS services. All clients implement the SdkClient interface.

// S3Client example
S3Client s3 = S3Client.builder().region(Region.US_EAST_1).build();

Client Configuration

Configure behavior through builders supporting:

• Timeout settings
• HTTP client selection
• Authentication methods
• Monitoring and metrics

Credential Providers

Multiple authentication methods:

• Environment variables
• System properties
• Shared credential files
• IAM roles
• SSO integration

HTTP Clients

Choose from three HTTP implementations:

• Apache HttpClient (synchronous)
• Netty NIO Client (asynchronous)
• URL Connection Client (lightweight)

Migration from v1.x

The SDK 2.x is not backward compatible with v1.x. Key changes:

• Builder pattern for client creation
• Different package structure
• Enhanced error handling
• New credential system
• Improved resource management

Getting Started

Include the BOM (Bill of Materials) for version management:

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>software.amazon.awssdk</groupId>
            <artifactId>bom</artifactId>
            <version>2.25.0</version> // Use latest stable version
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

Add service-specific dependencies:

<dependencies>
    <!-- S3 Service -->
    <dependency>
        <groupId>software.amazon.awssdk</groupId>
        <artifactId>s3</artifactId>
    </dependency>

    <!-- Core SDK -->
    <dependency>
        <groupId>software.amazon.awssdk</groupId>
        <artifactId>sdk-core</artifactId>
    </dependency>
</dependencies>

Architecture Overview

AWS Service Client
├── Configuration Layer
│   ├── Client Override Configuration
│   └── HTTP Client Configuration
├── Authentication Layer
│   ├── Credential Providers
│   └── Security Context
├── Transport Layer
│   ├── HTTP Client (Apache/Netty/URLConn)
│   └── Connection Pool
└── Protocol Layer
    ├── Service Protocol Implementation
    └── Error Handling

Service Discovery

The SDK automatically discovers and registers all available AWS services through service interfaces and paginators.

Available Services

All AWS services are available through dedicated client interfaces:

• S3 (Simple Storage Service)
• DynamoDB (NoSQL Database)
• Lambda (Serverless Functions)
• EC2 (Compute Cloud)
• RDS (Managed Databases)
• And 200+ other services

For a complete list, see the AWS Service documentation.

Support and Community

• GitHub Issues: Report bugs and request features
• AWS Amplify: For mobile app developers
• Migration Guide: Available for v1.x users
• Changelog: Track changes on GitHub