0
# Core SDK APIs
1

2
The AWS SDK for Java 1.x core module (`aws-java-sdk-core`) provides fundamental APIs used by all AWS service clients. These include authentication, credential management, client configuration, region handling, and exception management.
3

4
## Package
5

6
**Core Package**: `com.amazonaws`
7
**Maven Artifact**: `aws-java-sdk-core` (usually a transitive dependency)
8

9
## Authentication and Credentials
10

11
### Credential Interfaces
12

13
```java { .api }
14
package com.amazonaws.auth;
15

16
// Basic credential interface
17
interface AWSCredentials {
18
    String getAWSAccessKeyId();
19
    String getAWSSecretKey();
20
}
21

22
// Session credentials with temporary token
23
interface AWSSessionCredentials extends AWSCredentials {
24
    String getSessionToken();
25
}
26

27
// Credential provider strategy
28
interface AWSCredentialsProvider {
29
    AWSCredentials getCredentials();
30
    void refresh();
31
}
32
```
33

34
### Credential Implementations
35

36
```java { .api }
37
package com.amazonaws.auth;
38

39
// Static credentials (for development/testing)
40
class BasicAWSCredentials implements AWSCredentials {
41
    BasicAWSCredentials(String accessKey, String secretKey);
42
    String getAWSAccessKeyId();
43
    String getAWSSecretKey();
44
}
45

46
// Session credentials with temporary token
47
class BasicSessionCredentials implements AWSSessionCredentials {
48
    BasicSessionCredentials(String accessKey, String secretKey, String sessionToken);
49
    String getAWSAccessKeyId();
50
    String getAWSSecretKey();
51
    String getSessionToken();
52
}
53

54
// Anonymous credentials (no authentication)
55
class AnonymousAWSCredentials implements AWSCredentials {
56
    AnonymousAWSCredentials();
57
}
58
```
59

60
### Credential Providers
61

62
```java { .api }
63
package com.amazonaws.auth;
64

65
// Static credential provider
66
class AWSStaticCredentialsProvider implements AWSCredentialsProvider {
67
    AWSStaticCredentialsProvider(AWSCredentials credentials);
68
    AWSCredentials getCredentials();
69
    void refresh();
70
}
71

72
// Default credential provider chain (RECOMMENDED)
73
// Searches: env vars -> system properties -> profile -> container -> EC2 instance
74
class DefaultAWSCredentialsProviderChain extends AWSCredentialsProviderChain {
75
    DefaultAWSCredentialsProviderChain();
76
    static DefaultAWSCredentialsProviderChain getInstance();
77
}
78

79
// Environment variable credentials
80
class EnvironmentVariableCredentialsProvider implements AWSCredentialsProvider {
81
    EnvironmentVariableCredentialsProvider();
82
    AWSCredentials getCredentials();
83
}
84

85
// System property credentials
86
class SystemPropertiesCredentialsProvider implements AWSCredentialsProvider {
87
    SystemPropertiesCredentialsProvider();
88
    AWSCredentials getCredentials();
89
}
90

91
// AWS profile credentials
92
class ProfileCredentialsProvider implements AWSCredentialsProvider {
93
    ProfileCredentialsProvider();
94
    ProfileCredentialsProvider(String profileName);
95
    AWSCredentials getCredentials();
96
}
97

98
// EC2 instance metadata credentials
99
class InstanceProfileCredentialsProvider implements AWSCredentialsProvider {
100
    InstanceProfileCredentialsProvider();
101
    InstanceProfileCredentialsProvider(boolean refreshCredentialsAsync);
102
    static InstanceProfileCredentialsProvider getInstance();
103
    AWSCredentials getCredentials();
104
}
105

106
// ECS/EKS container credentials
107
class ContainerCredentialsProvider implements AWSCredentialsProvider {
108
    ContainerCredentialsProvider();
109
    AWSCredentials getCredentials();
110
}
111

112
// Web identity token credentials (OIDC)
113
class WebIdentityTokenCredentialsProvider implements AWSCredentialsProvider {
114
    static WebIdentityTokenCredentialsProvider create();
115
    static Builder builder();
116

117
    interface Builder {
118
        Builder roleArn(String roleArn);
119
        Builder roleSessionName(String roleSessionName);
120
        Builder webIdentityTokenFile(String webIdentityTokenFile);
121
        WebIdentityTokenCredentialsProvider build();
122
    }
123
}
124

125
// Custom credential provider chain
126
class AWSCredentialsProviderChain implements AWSCredentialsProvider {
127
    AWSCredentialsProviderChain(AWSCredentialsProvider... credentialsProviders);
128
    AWSCredentials getCredentials();
129
    void refresh();
130
}
131
```
132

133
### Credential Provider Usage
134

135
```java
136
import com.amazonaws.auth.DefaultAWSCredentialsProviderChain;
137
import com.amazonaws.auth.AWSStaticCredentialsProvider;
138
import com.amazonaws.auth.BasicAWSCredentials;
139
import com.amazonaws.auth.ProfileCredentialsProvider;
140

141
// RECOMMENDED: Use default chain
142
DefaultAWSCredentialsProviderChain defaultChain =
143
    new DefaultAWSCredentialsProviderChain();
144

145
// The chain automatically searches in order:
146
// 1. Environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY)
147
// 2. System properties (aws.accessKeyId, aws.secretKey)
148
// 3. Web identity token from STS
149
// 4. Shared credentials file (~/.aws/credentials)
150
// 5. ECS container credentials
151
// 6. EC2 instance profile credentials
152

153
// Static credentials for development
154
AWSStaticCredentialsProvider staticProvider = new AWSStaticCredentialsProvider(
155
    new BasicAWSCredentials("AKIAIOSFODNN7EXAMPLE", "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY")
156
);
157

158
// Profile-based credentials
159
ProfileCredentialsProvider profileProvider = new ProfileCredentialsProvider("myprofile");
160
```
161

162
## Client Configuration
163

164
```java { .api }
165
package com.amazonaws;
166

167
// HTTP client configuration
168
class ClientConfiguration {
169
    // Constants
170
    int DEFAULT_CONNECTION_TIMEOUT;
171
    int DEFAULT_SOCKET_TIMEOUT;
172
    int DEFAULT_MAX_CONNECTIONS;
173

174
    // Constructor
175
    ClientConfiguration();
176
    ClientConfiguration(ClientConfiguration other);
177

178
    // Connection settings
179
    ClientConfiguration withMaxConnections(int maxConnections);
180
    ClientConfiguration withConnectionTimeout(int connectionTimeout);
181
    ClientConfiguration withSocketTimeout(int socketTimeout);
182
    ClientConfiguration withConnectionTTL(long connectionTTL);
183
    ClientConfiguration withConnectionMaxIdleMillis(long connectionMaxIdleMillis);
184

185
    // Timeout settings
186
    ClientConfiguration withRequestTimeout(int requestTimeout);
187
    ClientConfiguration withClientExecutionTimeout(int clientExecutionTimeout);
188

189
    // Proxy settings
190
    ClientConfiguration withProxyHost(String proxyHost);
191
    ClientConfiguration withProxyPort(int proxyPort);
192
    ClientConfiguration withProxyUsername(String proxyUsername);
193
    ClientConfiguration withProxyPassword(String proxyPassword);
194
    ClientConfiguration withProxyDomain(String proxyDomain);
195
    ClientConfiguration withProxyWorkstation(String proxyWorkstation);
196
    ClientConfiguration withNonProxyHosts(String nonProxyHosts);
197

198
    // Retry settings
199
    ClientConfiguration withRetryPolicy(RetryPolicy retryPolicy);
200
    ClientConfiguration withMaxErrorRetry(int maxErrorRetry);
201

202
    // User agent
203
    ClientConfiguration withUserAgentPrefix(String prefix);
204
    ClientConfiguration withUserAgentSuffix(String suffix);
205

206
    // Advanced
207
    ClientConfiguration withSignerOverride(String signerOverride);
208
    ClientConfiguration withProtocol(Protocol protocol);
209

210
    // Getters
211
    int getMaxConnections();
212
    int getConnectionTimeout();
213
    int getSocketTimeout();
214
    String getProxyHost();
215
    int getProxyPort();
216
    RetryPolicy getRetryPolicy();
217
}
218

219
// Protocol enum
220
enum Protocol {
221
    HTTP,
222
    HTTPS
223
}
224
```
225

226
### Client Configuration Usage
227

228
```java
229
import com.amazonaws.ClientConfiguration;
230
import com.amazonaws.Protocol;
231

232
ClientConfiguration config = new ClientConfiguration()
233
    .withMaxConnections(100)
234
    .withConnectionTimeout(10000)    // 10 seconds
235
    .withSocketTimeout(50000)         // 50 seconds
236
    .withRequestTimeout(0)            // Disabled
237
    .withProtocol(Protocol.HTTPS)
238
    .withMaxErrorRetry(3)
239
    .withUserAgentPrefix("MyApp/1.0");
240

241
// With proxy
242
ClientConfiguration proxyConfig = new ClientConfiguration()
243
    .withProxyHost("proxy.example.com")
244
    .withProxyPort(8080)
245
    .withProxyUsername("user")
246
    .withProxyPassword("pass");
247
```
248

249
## Client Builders
250

251
```java { .api }
252
package com.amazonaws.client.builder;
253

254
// Base builder for all service clients
255
abstract class AwsClientBuilder<Subclass extends AwsClientBuilder, TypeToBuild> {
256
    // Region configuration
257
    Subclass withRegion(Regions region);
258
    Subclass withRegion(String region);
259

260
    // Credentials
261
    Subclass withCredentials(AWSCredentialsProvider credentialsProvider);
262

263
    // Client configuration
264
    Subclass withClientConfiguration(ClientConfiguration clientConfiguration);
265

266
    // Endpoint configuration
267
    Subclass withEndpointConfiguration(EndpointConfiguration endpointConfiguration);
268

269
    // Request handlers
270
    Subclass withRequestHandlers(RequestHandler2... requestHandlers);
271

272
    // Metrics
273
    Subclass withMetricsCollector(RequestMetricCollector metricsCollector);
274

275
    // Build the client
276
    abstract TypeToBuild build();
277

278
    // Endpoint configuration class
279
    static class EndpointConfiguration {
280
        EndpointConfiguration(String serviceEndpoint, String signingRegion);
281
        String getServiceEndpoint();
282
        String getSigningRegion();
283
    }
284
}
285

286
// Synchronous client builder
287
abstract class AwsSyncClientBuilder<Subclass extends AwsSyncClientBuilder, TypeToBuild>
288
    extends AwsClientBuilder<Subclass, TypeToBuild> {
289
}
290

291
// Asynchronous client builder
292
abstract class AwsAsyncClientBuilder<Subclass extends AwsAsyncClientBuilder, TypeToBuild>
293
    extends AwsClientBuilder<Subclass, TypeToBuild> {
294

295
    Subclass withExecutorFactory(ExecutorFactory executorFactory);
296
    ExecutorService getExecutorService();
297
}
298
```
299

300
### Client Builder Usage
301

302
```java
303
import com.amazonaws.services.s3.AmazonS3;
304
import com.amazonaws.services.s3.AmazonS3ClientBuilder;
305
import com.amazonaws.regions.Regions;
306
import com.amazonaws.auth.DefaultAWSCredentialsProviderChain;
307
import com.amazonaws.ClientConfiguration;
308

309
// Simple default client
310
AmazonS3 s3 = AmazonS3ClientBuilder.defaultClient();
311

312
// Standard configuration
313
AmazonS3 s3 = AmazonS3ClientBuilder.standard()
314
    .withRegion(Regions.US_WEST_2)
315
    .withCredentials(new DefaultAWSCredentialsProviderChain())
316
    .build();
317

318
// With custom configuration
319
ClientConfiguration config = new ClientConfiguration()
320
    .withMaxConnections(100);
321

322
AmazonS3 s3 = AmazonS3ClientBuilder.standard()
323
    .withRegion(Regions.US_EAST_1)
324
    .withClientConfiguration(config)
325
    .build();
326

327
// With custom endpoint (for testing or special cases)
328
AmazonS3 s3 = AmazonS3ClientBuilder.standard()
329
    .withEndpointConfiguration(
330
        new AwsClientBuilder.EndpointConfiguration(
331
            "https://s3.us-west-2.amazonaws.com",
332
            "us-west-2"
333
        ))
334
    .build();
335
```
336

337
## Regions
338

339
```java { .api }
340
package com.amazonaws.regions;
341

342
// Region metadata class
343
class Region {
344
    static Region getRegion(Regions region);
345

346
    String getName();
347
    String getDomain();
348
    String getPartition();
349
    String getServiceEndpoint(String serviceName);
350
    boolean isServiceSupported(String serviceName);
351
}
352

353
// Region enumeration
354
enum Regions {
355
    // US regions
356
    US_EAST_1,
357
    US_EAST_2,
358
    US_WEST_1,
359
    US_WEST_2,
360

361
    // Europe regions
362
    EU_WEST_1,
363
    EU_WEST_2,
364
    EU_WEST_3,
365
    EU_CENTRAL_1,
366
    EU_CENTRAL_2,
367
    EU_NORTH_1,
368
    EU_SOUTH_1,
369

370
    // Asia Pacific regions
371
    AP_EAST_1,
372
    AP_SOUTH_1,
373
    AP_SOUTHEAST_1,
374
    AP_SOUTHEAST_2,
375
    AP_SOUTHEAST_3,
376
    AP_NORTHEAST_1,
377
    AP_NORTHEAST_2,
378
    AP_NORTHEAST_3,
379

380
    // Other regions
381
    SA_EAST_1,
382
    CA_CENTRAL_1,
383
    ME_SOUTH_1,
384
    ME_CENTRAL_1,
385
    AF_SOUTH_1,
386

387
    // China regions
388
    CN_NORTH_1,
389
    CN_NORTHWEST_1,
390

391
    // GovCloud
392
    US_GOV_EAST_1,
393
    US_GOV_WEST_1;
394

395
    String getName();
396
    String getDescription();
397
}
398

399
// Region provider interface
400
interface AwsRegionProvider {
401
    String getRegion();
402
}
403

404
// Default region provider chain
405
class DefaultAwsRegionProviderChain extends AwsRegionProviderChain {
406
    DefaultAwsRegionProviderChain();
407
}
408

409
// Region utilities
410
class RegionUtils {
411
    static Region getRegion(String regionName);
412
    static List<Region> getRegions();
413
    static List<Region> getRegionsForService(String serviceAbbreviation);
414
}
415
```
416

417
### Region Usage
418

419
```java
420
import com.amazonaws.regions.Regions;
421
import com.amazonaws.regions.Region;
422

423
// Use region enum (recommended)
424
AmazonS3 s3 = AmazonS3ClientBuilder.standard()
425
    .withRegion(Regions.US_WEST_2)
426
    .build();
427

428
// Use region string
429
AmazonS3 s3 = AmazonS3ClientBuilder.standard()
430
    .withRegion("us-west-2")
431
    .build();
432

433
// Get current region (from environment/profile/metadata)
434
Region currentRegion = Regions.getCurrentRegion();
435
```
436

437
## Exception Handling
438

439
```java { .api }
440
package com.amazonaws;
441

442
// Base exception class
443
class SdkBaseException extends RuntimeException {
444
    SdkBaseException(String message);
445
    SdkBaseException(String message, Throwable cause);
446
}
447

448
// Client-side exception
449
class AmazonClientException extends SdkBaseException {
450
    AmazonClientException(String message);
451
    AmazonClientException(String message, Throwable cause);
452
    boolean isRetryable();
453
}
454

455
// Modern client exception (preferred)
456
class SdkClientException extends AmazonClientException {
457
    SdkClientException(String message);
458
    SdkClientException(String message, Throwable cause);
459
}
460

461
// Service-side exception
462
class AmazonServiceException extends SdkClientException {
463
    enum ErrorType {
464
        Client,    // 4xx errors
465
        Service,   // 5xx errors
466
        Unknown
467
    }
468

469
    AmazonServiceException(String errorMessage);
470
    AmazonServiceException(String errorMessage, Exception cause);
471

472
    String getErrorCode();
473
    int getStatusCode();
474
    String getRequestId();
475
    String getServiceName();
476
    ErrorType getErrorType();
477
    String getErrorMessage();
478
    Map<String, String> getHttpHeaders();
479
    String getRawResponseContent();
480
}
481

482
// Request aborted exception
483
class AbortedException extends SdkClientException {
484
    AbortedException(String message);
485
}
486
```
487

488
### Exception Handling Usage
489

490
```java
491
import com.amazonaws.AmazonServiceException;
492
import com.amazonaws.SdkClientException;
493

494
try {
495
    s3.getObject("my-bucket", "my-key");
496

497
} catch (AmazonServiceException ase) {
498
    // Service-side error (4xx, 5xx HTTP status codes)
499
    System.err.println("Service Error:");
500
    System.err.println("  Error Code: " + ase.getErrorCode());
501
    System.err.println("  Error Message: " + ase.getErrorMessage());
502
    System.err.println("  HTTP Status: " + ase.getStatusCode());
503
    System.err.println("  Request ID: " + ase.getRequestId());
504
    System.err.println("  Service: " + ase.getServiceName());
505
    System.err.println("  Error Type: " + ase.getErrorType());
506

507
    // Handle specific error codes
508
    if ("NoSuchKey".equals(ase.getErrorCode())) {
509
        // Object doesn't exist
510
    } else if ("AccessDenied".equals(ase.getErrorCode())) {
511
        // Permission denied
512
    }
513

514
} catch (SdkClientException sce) {
515
    // Client-side error (network failure, parsing error, etc.)
516
    System.err.println("Client Error: " + sce.getMessage());
517

518
    if (sce.isRetryable()) {
519
        // Error is retryable
520
    }
521
}
522
```
523

524
## Request and Response Base Classes
525

526
```java { .api }
527
package com.amazonaws;
528

529
// Base class for all service requests
530
abstract class AmazonWebServiceRequest implements Cloneable {
531
    // Credentials
532
    AWSCredentialsProvider getRequestCredentialsProvider();
533
    void setRequestCredentialsProvider(AWSCredentialsProvider credentialsProvider);
534
    <T extends AmazonWebServiceRequest> T withRequestCredentialsProvider(
535
        AWSCredentialsProvider credentialsProvider);
536

537
    // Timeouts
538
    Integer getSdkRequestTimeout();
539
    void setSdkRequestTimeout(int requestTimeout);
540
    <T extends AmazonWebServiceRequest> T withSdkRequestTimeout(int requestTimeout);
541

542
    Integer getSdkClientExecutionTimeout();
543
    void setSdkClientExecutionTimeout(int clientExecutionTimeout);
544
    <T extends AmazonWebServiceRequest> T withSdkClientExecutionTimeout(
545
        int clientExecutionTimeout);
546

547
    // Custom headers
548
    Map<String, String> getCustomRequestHeaders();
549
    String putCustomRequestHeader(String name, String value);
550

551
    // Custom query parameters
552
    Map<String, List<String>> getCustomQueryParameters();
553
    void putCustomQueryParameter(String name, String value);
554

555
    // Metrics
556
    RequestMetricCollector getRequestMetricCollector();
557
    void setRequestMetricCollector(RequestMetricCollector requestMetricCollector);
558

559
    // Cloning
560
    AmazonWebServiceRequest clone();
561
}
562

563
// Base class for all service responses
564
class AmazonWebServiceResult<T extends ResponseMetadata> {
565
    T getSdkResponseMetadata();
566
    AmazonWebServiceResult<T> setSdkResponseMetadata(T responseMetadata);
567

568
    SdkHttpMetadata getSdkHttpMetadata();
569
    AmazonWebServiceResult<T> setSdkHttpMetadata(SdkHttpMetadata httpMetadata);
570
}
571

572
// Response metadata
573
class ResponseMetadata {
574
    ResponseMetadata(Map<String, String> metadata);
575
    String getRequestId();
576
    String toString();
577
}
578
```
579

580
## Waiters
581

582
```java { .api }
583
package com.amazonaws.waiters;
584

585
// Waiter interface for polling resource state
586
interface Waiter<Input extends AmazonWebServiceRequest> {
587
    void run(WaiterParameters<Input> waiterParameters)
588
        throws WaiterUnrecoverableException, WaiterTimedOutException;
589

590
    Future<Void> runAsync(WaiterParameters<Input> waiterParameters,
591
                          WaiterHandler waiterHandler);
592
}
593

594
// Waiter parameters
595
class WaiterParameters<Input extends AmazonWebServiceRequest> {
596
    WaiterParameters();
597
    WaiterParameters(Input request);
598

599
    WaiterParameters<Input> withRequest(Input request);
600
    WaiterParameters<Input> withPollingStrategy(PollingStrategy pollingStrategy);
601

602
    Input getRequest();
603
    PollingStrategy getPollingStrategy();
604
}
605

606
// Waiter callback handler
607
interface WaiterHandler {
608
    void onWaitSuccess(AmazonWebServiceRequest request);
609
    void onWaitFailure(Exception e);
610
}
611

612
// No-op handler implementation
613
class NoOpWaiterHandler implements WaiterHandler {
614
    void onWaitSuccess(AmazonWebServiceRequest request);
615
    void onWaitFailure(Exception e);
616
}
617

618
// Waiter exceptions
619
class WaiterTimedOutException extends AmazonClientException {
620
    WaiterTimedOutException(String message);
621
}
622

623
class WaiterUnrecoverableException extends AmazonClientException {
624
    WaiterUnrecoverableException(String message);
625
}
626
```
627

628
### Waiter Usage
629

630
```java
631
import com.amazonaws.waiters.WaiterParameters;
632
import com.amazonaws.services.ec2.AmazonEC2;
633
import com.amazonaws.services.ec2.model.DescribeInstancesRequest;
634

635
AmazonEC2 ec2 = AmazonEC2ClientBuilder.defaultClient();
636

637
// Wait for EC2 instance to be running
638
try {
639
    ec2.waiters().instanceRunning().run(
640
        new WaiterParameters<>(
641
            new DescribeInstancesRequest().withInstanceIds("i-1234567890abcdef0")
642
        )
643
    );
644
    System.out.println("Instance is running");
645

646
} catch (WaiterTimedOutException e) {
647
    System.err.println("Timed out waiting for instance");
648
} catch (WaiterUnrecoverableException e) {
649
    System.err.println("Instance entered unrecoverable state");
650
}
651
```
652

653
## Other Core Types
654

655
```java { .api }
656
package com.amazonaws;
657

658
// HTTP methods
659
enum HttpMethod {
660
    GET,
661
    POST,
662
    PUT,
663
    DELETE,
664
    HEAD,
665
    PATCH,
666
    OPTIONS
667
}
668

669
// ARN (Amazon Resource Name) support
670
class Arn {
671
    static Arn fromString(String arnString);
672

673
    String getPartition();
674
    String getService();
675
    String getRegion();
676
    String getAccountId();
677
    ArnResource getResource();
678
}
679
```
680

681
### Request Handler
682

683
```java { .api }
684
package com.amazonaws.handlers;
685

686
// Request lifecycle handler
687
abstract class RequestHandler2 {
688
    void beforeRequest(Request<?> request);
689
    void afterResponse(Request<?> request, Response<?> response);
690
    void afterError(Request<?> request, Response<?> response, Exception e);
691
}
692
```
693

694
## Best Practices
695

696
### Credential Management
697

698
- **Use DefaultAWSCredentialsProviderChain**: Provides flexibility across environments (dev, staging, production)
699
- **Never hardcode credentials**: Use environment variables, IAM roles, or credential files
700
- **Use IAM roles**: For EC2 instances, ECS tasks, and Lambda functions
701
- **Rotate credentials**: Use temporary credentials when possible (STS AssumeRole)
702

703
### Client Lifecycle
704

705
- **Reuse client instances**: Clients are thread-safe and expensive to create
706
- **One client per service**: Create clients once and reuse across your application
707
- **Shutdown clients**: Call `shutdown()` when done to release resources (not usually needed for long-running applications)
708

709
### Configuration
710

711
- **Set appropriate timeouts**: Connection timeout, socket timeout, request timeout
712
- **Configure connection pooling**: Adjust `maxConnections` for high-throughput applications
713
- **Use retry policies**: Default retry policies handle transient errors automatically
714

715
### Exception Handling
716

717
- **Catch AmazonServiceException**: For service-side errors (wrong permissions, resource doesn't exist)
718
- **Catch SdkClientException**: For client-side errors (network failures, parsing errors)
719
- **Check error codes**: Use `getErrorCode()` to handle specific error conditions
720
- **Log request IDs**: Include `getRequestId()` when contacting AWS support
721