or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

arn-support.mdauthentication.mdclient-builders.mdendpoint-discovery.mdexception-handling.mdhttp-transport.mdindex.mdmetrics-monitoring.mdprotocols.mdregions-endpoints.mdretry-policies.mdutilities.mdwaiters.md
tile.json

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

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/com.amazonaws/aws-java-sdk-core@1.12.x

To install, run

npx @tessl/cli install tessl/maven-com-amazonaws--aws-java-sdk-core@1.12.0

index.mddocs/

AWS Java SDK Core

The AWS SDK for Java Core module provides foundational functionality for all AWS service clients. This library contains 479 public API classes organized into comprehensive packages that handle authentication, HTTP transport, regions, protocol marshalling, retry logic, and utility functions.

Package Information

<dependency>
    <groupId>com.amazonaws</groupId>
    <artifactId>aws-java-sdk-core</artifactId>
    <version>1.12.792-SNAPSHOT</version>
</dependency>
implementation 'com.amazonaws:aws-java-sdk-core:1.12.792-SNAPSHOT'

Core Imports

// Core exceptions and base classes
import com.amazonaws.AmazonClientException;
import com.amazonaws.AmazonServiceException;
import com.amazonaws.AmazonWebServiceRequest;
import com.amazonaws.AmazonWebServiceResponse;
import com.amazonaws.ClientConfiguration;

// Authentication
import com.amazonaws.auth.AWSCredentials;
import com.amazonaws.auth.AWSCredentialsProvider;
import com.amazonaws.auth.DefaultAWSCredentialsProviderChain;

// Regions
import com.amazonaws.regions.Region;
import com.amazonaws.regions.Regions;
import com.amazonaws.regions.RegionUtils;

// HTTP and retry
import com.amazonaws.http.HttpMethodName;
import com.amazonaws.retry.PredefinedRetryPolicies;
import com.amazonaws.retry.RetryPolicy;

Basic Usage

import com.amazonaws.ClientConfiguration;
import com.amazonaws.auth.DefaultAWSCredentialsProviderChain;
import com.amazonaws.regions.Regions;
import com.amazonaws.retry.PredefinedRetryPolicies;

// Basic client configuration
ClientConfiguration config = new ClientConfiguration()
    .withMaxConnections(100)
    .withConnectionTimeout(5000)
    .withSocketTimeout(10000)
    .withRetryPolicy(PredefinedRetryPolicies.DEFAULT);

// Credential provider chain (automatically finds credentials)
AWSCredentialsProvider credentialsProvider = 
    DefaultAWSCredentialsProviderChain.getInstance();

// Region configuration
Region region = RegionUtils.getRegion("us-east-1");

// Error handling pattern
try {
    // AWS service calls here
} catch (AmazonServiceException ase) {
    // Service-side error (4xx/5xx HTTP status)
    System.err.println("Service error: " + ase.getErrorCode());
    System.err.println("Status: " + ase.getStatusCode());
} catch (AmazonClientException ace) {
    // Client-side error (network, configuration, etc.)
    System.err.println("Client error: " + ace.getMessage());
}

Architecture

The AWS Java SDK Core is organized around several key architectural components:

Core Foundation Layer

  • Base Classes: AmazonWebServiceRequest, AmazonWebServiceResponse, Request<T>, Response<T>
  • Exception Hierarchy: AmazonClientException, AmazonServiceException, SdkClientException
  • Configuration: ClientConfiguration, RequestConfig, global SDK settings

Authentication & Security Layer

  • Credential Providers: Support for environment variables, profiles, IAM roles, instance profiles
  • Request Signers: AWS Signature Version 4, Version 3, query string signing
  • Policy Framework: IAM policy construction and validation

Transport & Protocol Layer

  • HTTP Client: Apache HTTP Client integration with connection management
  • Protocol Marshallers: JSON (AWS_JSON), CBOR (RPC v2), REST protocols
  • Request/Response Handling: Streaming, retries, timeouts, SSL/TLS

Regional & Endpoint Layer

  • Region Management: Region enumeration, metadata, automatic discovery
  • Endpoint Resolution: Service endpoint determination and customization

Reliability Layer

  • Retry Policies: Exponential backoff, adaptive retry, custom conditions
  • Waiters: Polling-based state transition waiting
  • Circuit Breaking: Client-side resilience patterns

Capabilities

Authentication & Credentials

Comprehensive credential management with automatic credential provider chains, IAM integration, and request signing.

// Credential provider chain
interface AWSCredentialsProvider {
    AWSCredentials getCredentials();
    void refresh();
}

class DefaultAWSCredentialsProviderChain implements AWSCredentialsProvider {
    public static DefaultAWSCredentialsProviderChain getInstance();
    public AWSCredentials getCredentials();
}

// Basic credentials
class BasicAWSCredentials implements AWSCredentials {
    public BasicAWSCredentials(String accessKey, String secretKey);
    public String getAWSAccessKeyId();
    public String getAWSSecretKey();
}

// Session credentials with token
class BasicSessionCredentials implements AWSSessionCredentials {
    public BasicSessionCredentials(String accessKey, String secretKey, String sessionToken);
    public String getAWSAccessKeyId();
    public String getAWSSecretKey();
    public String getSessionToken();
}

Learn more about Authentication →

Regions & Endpoint Resolution

AWS region management and service endpoint resolution with automatic region detection and custom endpoint support.

// Region enumeration
enum Regions {
    US_EAST_1("us-east-1"),
    US_WEST_2("us-west-2"),
    EU_WEST_1("eu-west-1");
    
    public String getName();
}

// Region utilities  
class RegionUtils {
    public static Region getRegion(String regionName);
    public static List<Region> getRegions();
    public static List<Region> getRegionsForService(String serviceName);
}

// Region provider chain
class DefaultAwsRegionProviderChain extends AwsRegionProviderChain {
    public static DefaultAwsRegionProviderChain getInstance();
    public String getRegion();
}

Learn more about Regions & Endpoints →

HTTP Transport & Client Configuration

Comprehensive HTTP client configuration with connection pooling, SSL/TLS support, and proxy configuration.

// Client configuration
class ClientConfiguration {
    public ClientConfiguration withMaxConnections(int maxConnections);
    public ClientConfiguration withConnectionTimeout(int connectionTimeout);
    public ClientConfiguration withSocketTimeout(int socketTimeout);
    public ClientConfiguration withRetryPolicy(RetryPolicy retryPolicy);
    public ClientConfiguration withProxyHost(String proxyHost);
    public ClientConfiguration withProxyPort(int proxyPort);
}

// HTTP method enumeration
enum HttpMethodName {
    GET, POST, PUT, DELETE, HEAD, PATCH, OPTIONS
}

Learn more about HTTP Transport →

Protocol Support & Marshalling

Support for multiple AWS protocols including JSON, CBOR, and REST with automatic marshalling and unmarshalling.

// Protocol enumeration
enum Protocol {
    HTTP, HTTPS
}

// Marshalling information
class MarshallingInfo<T> {
    public static <T> MarshallingInfo<T> builder(MarshallingType<T> marshallingType);
    public MarshallingInfo<T> marshallLocation(MarshallLocation marshallLocation);
    public MarshallingInfo<T> locationName(String locationName);
}

// JSON protocol factory
class SdkJsonProtocolFactory {
    public SdkJsonProtocolFactory(JsonClientMetadata metadata);
    public <OrigRequest extends AmazonWebServiceRequest> ProtocolRequestMarshaller<OrigRequest> 
        createProtocolMarshaller(OperationInfo operationInfo);
}

Learn more about Protocols →

Retry Policies & Error Handling

Configurable retry logic with exponential backoff, adaptive retry modes, and custom retry conditions.

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

// Predefined policies
class PredefinedRetryPolicies {
    public static final RetryPolicy DEFAULT;
    public static final RetryPolicy NO_RETRY_POLICY;
    public static final RetryPolicy DEFAULT_MAX_ERROR_RETRY;
}

Learn more about Retry Policies →

Utility Classes & Helpers

Comprehensive utility classes for common operations including encoding, hashing, JSON processing, and validation.

// String utilities
class StringUtils {
    public static boolean isNullOrEmpty(String value);
    public static String join(String delimiter, String... strings);
    public static String trim(String value);
}

// IO utilities
class IOUtils {
    public static byte[] toByteArray(InputStream input) throws IOException;
    public static String toString(InputStream input) throws IOException;
    public static void closeQuietly(Closeable closeable);
}

// Binary utilities
class BinaryUtils {
    public static String toBase64(byte[] data);
    public static byte[] fromBase64(String b64Data);
    public static String toHex(byte[] data);
    public static byte[] fromHex(String hexData);
}

Learn more about Utilities →

Waiters & Polling

Polling-based state transition waiting with configurable strategies and timeout handling.

// Waiter interface
interface Waiter<Input> {
    void run(Input input) throws WaiterUnrecoverableException, WaiterTimedOutException;
    void run(Input input, WaiterHandler<Input> waiterHandler) 
        throws WaiterUnrecoverableException, WaiterTimedOutException;
}

// Waiter builder
class WaiterBuilder<Input, Output> {
    public static <Input, Output> WaiterBuilder<Input, Output> newBuilder();
    public WaiterBuilder<Input, Output> withSdkFunction(SdkFunction<Input, Output> sdkFunction);
    public WaiterBuilder<Input, Output> withAcceptors(WaiterAcceptor<Output>... acceptors);
    public WaiterBuilder<Input, Output> withDefaultPollingStrategy(PollingStrategy pollingStrategy);
    public Waiter<Input> build();
}

Learn more about Waiters →

Metrics & Monitoring

Client-side monitoring and metrics collection with support for custom metric collectors and JMX integration.

// SDK metrics
class AwsSdkMetrics {
    public static boolean isDefaultMetricsEnabled();
    public static void setDefaultMetricsEnabled(boolean enabled);
    public static RequestMetricCollector getRequestMetricCollector();
    public static void setRequestMetricCollector(RequestMetricCollector requestMetricCollector);
}

// Request metric collector
interface RequestMetricCollector {
    void collectMetrics(Request<?> request, Response<?> response);
    void collectMetrics(Request<?> request, Response<?> response, Exception exception);
}

// Metric types
enum RequestMetricType implements MetricType {
    HttpClientRetryCount,
    HttpClientPoolAvailableCount,
    HttpClientPoolLeasedCount,
    HttpRequestTime,
    HttpResponseTime,
    ResponseProcessingTime,
    RequestExecutionTime
}

Learn more about Metrics & Monitoring →

Client Builders & Configuration

Flexible client builder patterns for constructing AWS service clients with custom configurations, credential providers, and advanced options.

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

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

Learn more about Client Builders →

ARN Support & Resource Management

Comprehensive ARN parsing, validation, and manipulation capabilities for working with AWS resources.

// Core ARN parsing and manipulation class
class Arn {
    public static Arn fromString(String arn);
    public static Builder builder();
    
    public String getPartition();
    public String getService();
    public String getRegion();
    public String getAccountId();
    public ArnResource getResource();
    
    public String toString();
}

// ARN resource component representation  
class ArnResource {
    public static ArnResource fromString(String resource);
    public String getResourceType();
    public String getResource();
    public String getQualifier();
    public boolean hasResourceType();
}

Learn more about ARN Support →

Endpoint Discovery

Automatic service endpoint discovery and optimization for improved connectivity and performance.

// Core endpoint discovery provider interface
interface EndpointDiscoveryProvider {
    boolean isEndpointDiscoveryEnabled();
    void refresh();
}

// Default endpoint discovery provider chain
class DefaultEndpointDiscoveryProviderChain extends EndpointDiscoveryProviderChain {
    public static DefaultEndpointDiscoveryProviderChain getInstance();
}

// Environment variable endpoint discovery provider
class EnvironmentVariableEndpointDiscoveryProvider extends BaseEndpointDiscoveryProvider {
    public static final String AWS_ENABLE_ENDPOINT_DISCOVERY = "AWS_ENABLE_ENDPOINT_DISCOVERY";
    public boolean isEndpointDiscoveryEnabled();
}

Learn more about Endpoint Discovery →

Exception Hierarchy

All AWS SDK operations can throw exceptions from this hierarchy:

// Base SDK exception class (extends RuntimeException)
class SdkBaseException extends RuntimeException {
    public SdkBaseException(String message);
    public SdkBaseException(String message, Throwable cause);
    public boolean isRetryable();
}

// Client-side exception (network, configuration, etc.)
class SdkClientException extends SdkBaseException {
    public SdkClientException(String message);
    public SdkClientException(String message, Throwable cause);
    public boolean isRetryable();
}

// Legacy client exception (for backward compatibility)
class AmazonClientException extends SdkBaseException {
    public AmazonClientException(String message);
    public AmazonClientException(String message, Throwable t);
    public AmazonClientException(Throwable cause);
    public boolean isRetryable();
}

// Service exception with error details
class AmazonServiceException extends SdkClientException {
    public String getErrorCode();
    public String getErrorMessage(); 
    public String getErrorType();
    public int getStatusCode();
    public String getServiceName();
    public String getRequestId();
}

Migration Notes

This documentation covers AWS SDK for Java v1.x. For new projects, consider AWS SDK for Java v2.x:

  • ClientConfiguration → ClientOverrideConfiguration (v2)
  • HTTP Settings → SdkHttpClient.Builder (v2)
  • Credentials → AwsCredentialsProvider (v2)
  • Regions → software.amazon.awssdk.regions.Region (v2)

See the AWS SDK Java Migration Guide for comprehensive migration information.

Learn more about Exception Handling →

Related Documentation

Core Functionality

Advanced Features

Utilities & Monitoring