CtrlK
BlogDocsLog inGet started
Tessl Logo

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

client-builders.mddocs/

Client Builders & Configuration

The AWS Java SDK Core provides flexible client builder patterns for constructing AWS service clients with custom configurations, credential providers, and advanced options.

Core Builder Interfaces

Base Client Builder

// Base builder interface for all AWS clients
interface AwsClientBuilder<Subclass extends AwsClientBuilder, TypeToBuild> {
    Subclass withCredentials(AWSCredentialsProvider credentialsProvider);
    Subclass withRegion(Regions region);
    Subclass withRegion(String region);
    Subclass withEndpointConfiguration(EndpointConfiguration endpointConfiguration);
    Subclass withClientConfiguration(ClientConfiguration clientConfiguration);
    Subclass withMetricsCollector(RequestMetricCollector metricsCollector);
    
    TypeToBuild build();
}

// Synchronous client builder
interface AwsSyncClientBuilder<Subclass extends AwsSyncClientBuilder, TypeToBuild> 
    extends AwsClientBuilder<Subclass, TypeToBuild> {
    // Synchronous-specific builder methods
}

// Asynchronous client builder  
interface AwsAsyncClientBuilder<Subclass extends AwsAsyncClientBuilder, TypeToBuild>
    extends AwsClientBuilder<Subclass, TypeToBuild> {
    Subclass withExecutorFactory(ExecutorFactory executorFactory);
    // Asynchronous-specific builder methods
}

Endpoint Configuration

// Endpoint configuration for custom endpoints
class EndpointConfiguration {
    public EndpointConfiguration(String endpoint, String signingRegion);
    public String getEndpoint();
    public String getSigningRegion();
}

Client Configuration Factory

Configuration Factory

// Factory for creating client configurations
class ClientConfigurationFactory {
    public ClientConfiguration getConfig();
    protected ClientConfiguration getDefaultConfig();
    
    // Configuration with advanced options
    public ClientConfiguration getConfigWithRequestTimeout(int requestTimeout);
    public ClientConfiguration getConfigWithClientExecutionTimeout(int clientExecutionTimeout);
}

Predefined Configurations

// Predefined client configurations for common scenarios
class PredefinedClientConfigurations {
    // Configuration for default retry policy
    public static ClientConfiguration defaultConfig();
    
    // Configuration optimized for high throughput
    public static ClientConfiguration highThroughputConfig();
    
    // Configuration optimized for low latency
    public static ClientConfiguration lowLatencyConfig();
    
    // Configuration for mobile environments
    public static ClientConfiguration mobileConfig();
    
    // Configuration with no retry policy
    public static ClientConfiguration noRetryConfig();
}

Advanced Configuration Options

Advanced Config

// Advanced configuration options
class AdvancedConfig {
    public static final AdvancedConfig EMPTY;
    
    public static Builder builder();
    
    interface Builder {
        Builder putAdvancedOption(AdvancedConfigOptionKey<T> option, T value);
        AdvancedConfig build();
    }
    
    public <T> Optional<T> getAdvancedOption(AdvancedConfigurationKey<T> key);
}

// Advanced configuration option keys
class AdvancedConfigOptionKey<T> {
    public static final AdvancedConfigOptionKey<Boolean> ENABLE_DEFAULT_METRICS;
    public static final AdvancedConfigOptionKey<Boolean> USE_LEGACY_USER_AGENT;
    public static final AdvancedConfigOptionKey<Boolean> DISABLE_HOST_PREFIX_INJECTION;
}

Executor Factory

// Factory for creating custom executors for async clients
interface ExecutorFactory {
    Executor newExecutor();
}

// Cached thread pool executor factory
class CachedThreadPoolExecutorFactory implements ExecutorFactory {
    public CachedThreadPoolExecutorFactory();
    public Executor newExecutor();
}

// Fixed thread pool executor factory
class FixedThreadPoolExecutorFactory implements ExecutorFactory {
    public FixedThreadPoolExecutorFactory(int threadPoolSize);
    public Executor newExecutor();
}

Basic Usage Examples

Simple Client Construction

import com.amazonaws.auth.DefaultAWSCredentialsProviderChain;
import com.amazonaws.regions.Regions;
import com.amazonaws.services.s3.AmazonS3;
import com.amazonaws.services.s3.AmazonS3ClientBuilder;

// Simple S3 client with default configuration
AmazonS3 s3Client = AmazonS3ClientBuilder.standard()
    .withCredentials(DefaultAWSCredentialsProviderChain.getInstance())
    .withRegion(Regions.US_EAST_1)
    .build();

Custom Client Configuration

import com.amazonaws.ClientConfiguration;
import com.amazonaws.retry.PredefinedRetryPolicies;
import com.amazonaws.services.dynamodb.AmazonDynamoDB;
import com.amazonaws.services.dynamodb.AmazonDynamoDBClientBuilder;

// DynamoDB client with custom configuration
ClientConfiguration config = new ClientConfiguration()
    .withMaxConnections(50)
    .withConnectionTimeout(10000)
    .withSocketTimeout(30000)
    .withRetryPolicy(PredefinedRetryPolicies.DYNAMODB_DEFAULT);

AmazonDynamoDB dynamoClient = AmazonDynamoDBClientBuilder.standard()
    .withCredentials(DefaultAWSCredentialsProviderChain.getInstance())
    .withRegion(Regions.US_WEST_2)
    .withClientConfiguration(config)
    .build();

Custom Endpoint Configuration

import com.amazonaws.client.builder.AwsClientBuilder.EndpointConfiguration;
import com.amazonaws.services.s3.AmazonS3;
import com.amazonaws.services.s3.AmazonS3ClientBuilder;

// S3 client with custom endpoint (e.g., for localstack)
EndpointConfiguration endpointConfig = new EndpointConfiguration(
    "http://localhost:4566", // Custom endpoint URL
    "us-east-1"             // Signing region
);

AmazonS3 s3Client = AmazonS3ClientBuilder.standard()
    .withCredentials(DefaultAWSCredentialsProviderChain.getInstance())
    .withEndpointConfiguration(endpointConfig)
    .withPathStyleAccessEnabled(true)
    .build();

Asynchronous Client Construction

import com.amazonaws.client.builder.ExecutorFactory;
import com.amazonaws.services.s3.AmazonS3Async;
import com.amazonaws.services.s3.AmazonS3AsyncClientBuilder;
import java.util.concurrent.Executors;

// Custom executor factory for async operations
ExecutorFactory executorFactory = () -> Executors.newFixedThreadPool(10);

// Asynchronous S3 client
AmazonS3Async s3AsyncClient = AmazonS3AsyncClientBuilder.standard()
    .withCredentials(DefaultAWSCredentialsProviderChain.getInstance())
    .withRegion(Regions.US_EAST_1)
    .withExecutorFactory(executorFactory)
    .build();

Predefined Configurations

import com.amazonaws.ClientConfigurationFactory;
import com.amazonaws.PredefinedClientConfigurations;

// Using predefined configurations
ClientConfiguration highThroughputConfig = 
    PredefinedClientConfigurations.highThroughputConfig();

ClientConfiguration mobileConfig = 
    PredefinedClientConfigurations.mobileConfig();

// Using configuration factory
ClientConfigurationFactory configFactory = new ClientConfigurationFactory();
ClientConfiguration factoryConfig = configFactory.getConfig();

Advanced Configuration Patterns

Multiple Region Clients

import java.util.HashMap;
import java.util.Map;

// Creating clients for multiple regions
Map<Regions, AmazonS3> s3Clients = new HashMap<>();

for (Regions region : Arrays.asList(Regions.US_EAST_1, Regions.EU_WEST_1, Regions.AP_SOUTHEAST_1)) {
    AmazonS3 client = AmazonS3ClientBuilder.standard()
        .withCredentials(DefaultAWSCredentialsProviderChain.getInstance())  
        .withRegion(region)
        .build();
    s3Clients.put(region, client);
}

Configuration with Custom Metrics

import com.amazonaws.metrics.RequestMetricCollector;

// Custom metrics collector
RequestMetricCollector metricsCollector = new RequestMetricCollector() {
    @Override
    public void collectMetrics(Request<?> request, Response<?> response) {
        // Custom metrics collection logic
        System.out.println("Request completed: " + request.getServiceName());
    }
};

// Client with custom metrics
AmazonS3 s3Client = AmazonS3ClientBuilder.standard()
    .withCredentials(DefaultAWSCredentialsProviderChain.getInstance())
    .withRegion(Regions.US_EAST_1)
    .withMetricsCollector(metricsCollector)
    .build();

Best Practices

Resource Management

// Always close clients when done
try (AmazonS3 s3Client = AmazonS3ClientBuilder.standard()
        .withCredentials(DefaultAWSCredentialsProviderChain.getInstance())
        .withRegion(Regions.US_EAST_1)
        .build()) {
    
    // Use the client
    s3Client.listBuckets();
    
} // Client automatically closed

Error Handling in Builder Pattern

try {
    AmazonS3 s3Client = AmazonS3ClientBuilder.standard()
        .withCredentials(DefaultAWSCredentialsProviderChain.getInstance())
        .withRegion(Regions.US_EAST_1)
        .build();
        
} catch (SdkClientException e) {
    // Handle client configuration errors
    System.err.println("Failed to create S3 client: " + e.getMessage());
}

Thread Safety Considerations

// Clients are thread-safe and can be shared
private static final AmazonS3 S3_CLIENT = AmazonS3ClientBuilder.standard()
    .withCredentials(DefaultAWSCredentialsProviderChain.getInstance())
    .withRegion(Regions.US_EAST_1)
    .build();

// Safe to use from multiple threads
public void uploadFile(String key, File file) {
    S3_CLIENT.putObject("my-bucket", key, file);
}

Migration from Legacy Constructor Pattern

Before (Legacy Pattern)

// Old constructor-based approach (deprecated)
AmazonS3 s3Client = new AmazonS3Client(
    DefaultAWSCredentialsProviderChain.getInstance(),
    clientConfiguration
);
s3Client.setRegion(Region.getRegion(Regions.US_EAST_1));

After (Builder Pattern)

// New builder-based approach (recommended)
AmazonS3 s3Client = AmazonS3ClientBuilder.standard()
    .withCredentials(DefaultAWSCredentialsProviderChain.getInstance())
    .withClientConfiguration(clientConfiguration)
    .withRegion(Regions.US_EAST_1)
    .build();

The builder pattern provides better fluent API design, compile-time safety, and easier configuration management compared to the legacy constructor approach.

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

protocols.md

regions-endpoints.md

retry-policies.md

utilities.md

waiters.md

tile.json