0
# AWS Java SDK Core
1

2
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.
3

4
## Package Information
5

6
```xml
7
<dependency>
8
    <groupId>com.amazonaws</groupId>
9
    <artifactId>aws-java-sdk-core</artifactId>
10
    <version>1.12.792-SNAPSHOT</version>
11
</dependency>
12
```
13

14
```gradle
15
implementation 'com.amazonaws:aws-java-sdk-core:1.12.792-SNAPSHOT'
16
```
17

18
## Core Imports
19

20
```java
21
// Core exceptions and base classes
22
import com.amazonaws.AmazonClientException;
23
import com.amazonaws.AmazonServiceException;
24
import com.amazonaws.AmazonWebServiceRequest;
25
import com.amazonaws.AmazonWebServiceResponse;
26
import com.amazonaws.ClientConfiguration;
27

28
// Authentication
29
import com.amazonaws.auth.AWSCredentials;
30
import com.amazonaws.auth.AWSCredentialsProvider;
31
import com.amazonaws.auth.DefaultAWSCredentialsProviderChain;
32

33
// Regions
34
import com.amazonaws.regions.Region;
35
import com.amazonaws.regions.Regions;
36
import com.amazonaws.regions.RegionUtils;
37

38
// HTTP and retry
39
import com.amazonaws.http.HttpMethodName;
40
import com.amazonaws.retry.PredefinedRetryPolicies;
41
import com.amazonaws.retry.RetryPolicy;
42
```
43

44
## Basic Usage
45

46
```java
47
import com.amazonaws.ClientConfiguration;
48
import com.amazonaws.auth.DefaultAWSCredentialsProviderChain;
49
import com.amazonaws.regions.Regions;
50
import com.amazonaws.retry.PredefinedRetryPolicies;
51

52
// Basic client configuration
53
ClientConfiguration config = new ClientConfiguration()
54
    .withMaxConnections(100)
55
    .withConnectionTimeout(5000)
56
    .withSocketTimeout(10000)
57
    .withRetryPolicy(PredefinedRetryPolicies.DEFAULT);
58

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

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

66
// Error handling pattern
67
try {
68
    // AWS service calls here
69
} catch (AmazonServiceException ase) {
70
    // Service-side error (4xx/5xx HTTP status)
71
    System.err.println("Service error: " + ase.getErrorCode());
72
    System.err.println("Status: " + ase.getStatusCode());
73
} catch (AmazonClientException ace) {
74
    // Client-side error (network, configuration, etc.)
75
    System.err.println("Client error: " + ace.getMessage());
76
}
77
```
78

79
## Architecture
80

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

83
### Core Foundation Layer
84
- **Base Classes**: `AmazonWebServiceRequest`, `AmazonWebServiceResponse`, `Request<T>`, `Response<T>`
85
- **Exception Hierarchy**: `AmazonClientException`, `AmazonServiceException`, `SdkClientException`
86
- **Configuration**: `ClientConfiguration`, `RequestConfig`, global SDK settings
87

88
### Authentication & Security Layer
89
- **Credential Providers**: Support for environment variables, profiles, IAM roles, instance profiles
90
- **Request Signers**: AWS Signature Version 4, Version 3, query string signing
91
- **Policy Framework**: IAM policy construction and validation
92

93
### Transport & Protocol Layer  
94
- **HTTP Client**: Apache HTTP Client integration with connection management
95
- **Protocol Marshallers**: JSON (AWS_JSON), CBOR (RPC v2), REST protocols
96
- **Request/Response Handling**: Streaming, retries, timeouts, SSL/TLS
97

98
### Regional & Endpoint Layer
99
- **Region Management**: Region enumeration, metadata, automatic discovery
100
- **Endpoint Resolution**: Service endpoint determination and customization
101

102
### Reliability Layer
103
- **Retry Policies**: Exponential backoff, adaptive retry, custom conditions
104
- **Waiters**: Polling-based state transition waiting
105
- **Circuit Breaking**: Client-side resilience patterns
106

107
## Capabilities
108

109
### Authentication & Credentials
110
Comprehensive credential management with automatic credential provider chains, IAM integration, and request signing.
111

112
```java { .api }
113
// Credential provider chain
114
interface AWSCredentialsProvider {
115
    AWSCredentials getCredentials();
116
    void refresh();
117
}
118

119
class DefaultAWSCredentialsProviderChain implements AWSCredentialsProvider {
120
    public static DefaultAWSCredentialsProviderChain getInstance();
121
    public AWSCredentials getCredentials();
122
}
123

124
// Basic credentials
125
class BasicAWSCredentials implements AWSCredentials {
126
    public BasicAWSCredentials(String accessKey, String secretKey);
127
    public String getAWSAccessKeyId();
128
    public String getAWSSecretKey();
129
}
130

131
// Session credentials with token
132
class BasicSessionCredentials implements AWSSessionCredentials {
133
    public BasicSessionCredentials(String accessKey, String secretKey, String sessionToken);
134
    public String getAWSAccessKeyId();
135
    public String getAWSSecretKey();
136
    public String getSessionToken();
137
}
138
```
139

140
**[Learn more about Authentication →](./authentication.md)**
141

142
### Regions & Endpoint Resolution
143
AWS region management and service endpoint resolution with automatic region detection and custom endpoint support.
144

145
```java { .api }
146
// Region enumeration
147
enum Regions {
148
    US_EAST_1("us-east-1"),
149
    US_WEST_2("us-west-2"),
150
    EU_WEST_1("eu-west-1");
151
    
152
    public String getName();
153
}
154

155
// Region utilities  
156
class RegionUtils {
157
    public static Region getRegion(String regionName);
158
    public static List<Region> getRegions();
159
    public static List<Region> getRegionsForService(String serviceName);
160
}
161

162
// Region provider chain
163
class DefaultAwsRegionProviderChain extends AwsRegionProviderChain {
164
    public static DefaultAwsRegionProviderChain getInstance();
165
    public String getRegion();
166
}
167
```
168

169
**[Learn more about Regions & Endpoints →](./regions-endpoints.md)**
170

171
### HTTP Transport & Client Configuration
172
Comprehensive HTTP client configuration with connection pooling, SSL/TLS support, and proxy configuration.
173

174
```java { .api }
175
// Client configuration
176
class ClientConfiguration {
177
    public ClientConfiguration withMaxConnections(int maxConnections);
178
    public ClientConfiguration withConnectionTimeout(int connectionTimeout);
179
    public ClientConfiguration withSocketTimeout(int socketTimeout);
180
    public ClientConfiguration withRetryPolicy(RetryPolicy retryPolicy);
181
    public ClientConfiguration withProxyHost(String proxyHost);
182
    public ClientConfiguration withProxyPort(int proxyPort);
183
}
184

185
// HTTP method enumeration
186
enum HttpMethodName {
187
    GET, POST, PUT, DELETE, HEAD, PATCH, OPTIONS
188
}
189
```
190

191
**[Learn more about HTTP Transport →](./http-transport.md)**
192

193
### Protocol Support & Marshalling
194
Support for multiple AWS protocols including JSON, CBOR, and REST with automatic marshalling and unmarshalling.
195

196
```java { .api }
197
// Protocol enumeration
198
enum Protocol {
199
    HTTP, HTTPS
200
}
201

202
// Marshalling information
203
class MarshallingInfo<T> {
204
    public static <T> MarshallingInfo<T> builder(MarshallingType<T> marshallingType);
205
    public MarshallingInfo<T> marshallLocation(MarshallLocation marshallLocation);
206
    public MarshallingInfo<T> locationName(String locationName);
207
}
208

209
// JSON protocol factory
210
class SdkJsonProtocolFactory {
211
    public SdkJsonProtocolFactory(JsonClientMetadata metadata);
212
    public <OrigRequest extends AmazonWebServiceRequest> ProtocolRequestMarshaller<OrigRequest> 
213
        createProtocolMarshaller(OperationInfo operationInfo);
214
}
215
```
216

217
**[Learn more about Protocols →](./protocols.md)**
218

219
### Retry Policies & Error Handling
220
Configurable retry logic with exponential backoff, adaptive retry modes, and custom retry conditions.
221

222
```java { .api }
223
// Retry policy configuration
224
class RetryPolicy {
225
    public RetryPolicy(RetryCondition retryCondition, 
226
                      BackoffStrategy backoffStrategy, 
227
                      int maxErrorRetry, 
228
                      boolean honorMaxErrorRetryInClientConfig);
229
    
230
    interface RetryCondition {
231
        boolean shouldRetry(AmazonWebServiceRequest originalRequest, 
232
                           AmazonClientException exception, 
233
                           int retriesAttempted);
234
    }
235
    
236
    interface BackoffStrategy {
237
        long delayBeforeNextRetry(AmazonWebServiceRequest originalRequest,
238
                                 AmazonClientException exception,
239
                                 int retriesAttempted);
240
    }
241
}
242

243
// Predefined policies
244
class PredefinedRetryPolicies {
245
    public static final RetryPolicy DEFAULT;
246
    public static final RetryPolicy NO_RETRY_POLICY;
247
    public static final RetryPolicy DEFAULT_MAX_ERROR_RETRY;
248
}
249
```
250

251
**[Learn more about Retry Policies →](./retry-policies.md)**
252

253
### Utility Classes & Helpers
254
Comprehensive utility classes for common operations including encoding, hashing, JSON processing, and validation.
255

256
```java { .api }
257
// String utilities
258
class StringUtils {
259
    public static boolean isNullOrEmpty(String value);
260
    public static String join(String delimiter, String... strings);
261
    public static String trim(String value);
262
}
263

264
// IO utilities
265
class IOUtils {
266
    public static byte[] toByteArray(InputStream input) throws IOException;
267
    public static String toString(InputStream input) throws IOException;
268
    public static void closeQuietly(Closeable closeable);
269
}
270

271
// Binary utilities
272
class BinaryUtils {
273
    public static String toBase64(byte[] data);
274
    public static byte[] fromBase64(String b64Data);
275
    public static String toHex(byte[] data);
276
    public static byte[] fromHex(String hexData);
277
}
278
```
279

280
**[Learn more about Utilities →](./utilities.md)**
281

282
### Waiters & Polling
283
Polling-based state transition waiting with configurable strategies and timeout handling.
284

285
```java { .api }
286
// Waiter interface
287
interface Waiter<Input> {
288
    void run(Input input) throws WaiterUnrecoverableException, WaiterTimedOutException;
289
    void run(Input input, WaiterHandler<Input> waiterHandler) 
290
        throws WaiterUnrecoverableException, WaiterTimedOutException;
291
}
292

293
// Waiter builder
294
class WaiterBuilder<Input, Output> {
295
    public static <Input, Output> WaiterBuilder<Input, Output> newBuilder();
296
    public WaiterBuilder<Input, Output> withSdkFunction(SdkFunction<Input, Output> sdkFunction);
297
    public WaiterBuilder<Input, Output> withAcceptors(WaiterAcceptor<Output>... acceptors);
298
    public WaiterBuilder<Input, Output> withDefaultPollingStrategy(PollingStrategy pollingStrategy);
299
    public Waiter<Input> build();
300
}
301
```
302

303
**[Learn more about Waiters →](./waiters.md)**
304

305
### Metrics & Monitoring
306
Client-side monitoring and metrics collection with support for custom metric collectors and JMX integration.
307

308
```java { .api }
309
// SDK metrics
310
class AwsSdkMetrics {
311
    public static boolean isDefaultMetricsEnabled();
312
    public static void setDefaultMetricsEnabled(boolean enabled);
313
    public static RequestMetricCollector getRequestMetricCollector();
314
    public static void setRequestMetricCollector(RequestMetricCollector requestMetricCollector);
315
}
316

317
// Request metric collector
318
interface RequestMetricCollector {
319
    void collectMetrics(Request<?> request, Response<?> response);
320
    void collectMetrics(Request<?> request, Response<?> response, Exception exception);
321
}
322

323
// Metric types
324
enum RequestMetricType implements MetricType {
325
    HttpClientRetryCount,
326
    HttpClientPoolAvailableCount,
327
    HttpClientPoolLeasedCount,
328
    HttpRequestTime,
329
    HttpResponseTime,
330
    ResponseProcessingTime,
331
    RequestExecutionTime
332
}
333
```
334

335
**[Learn more about Metrics & Monitoring →](./metrics-monitoring.md)**
336

337
### Client Builders & Configuration
338
Flexible client builder patterns for constructing AWS service clients with custom configurations, credential providers, and advanced options.
339

340
```java { .api }
341
// Base builder interface for all AWS clients
342
interface AwsClientBuilder<Subclass extends AwsClientBuilder, TypeToBuild> {
343
    Subclass withCredentials(AWSCredentialsProvider credentialsProvider);
344
    Subclass withRegion(Regions region);
345
    Subclass withEndpointConfiguration(EndpointConfiguration endpointConfiguration);
346
    Subclass withClientConfiguration(ClientConfiguration clientConfiguration);
347
    TypeToBuild build();
348
}
349

350
// Endpoint configuration for custom endpoints
351
class EndpointConfiguration {
352
    public EndpointConfiguration(String endpoint, String signingRegion);
353
    public String getEndpoint();
354
    public String getSigningRegion();
355
}
356
```
357

358
**[Learn more about Client Builders →](./client-builders.md)**
359

360
### ARN Support & Resource Management
361
Comprehensive ARN parsing, validation, and manipulation capabilities for working with AWS resources.
362

363
```java { .api }
364
// Core ARN parsing and manipulation class
365
class Arn {
366
    public static Arn fromString(String arn);
367
    public static Builder builder();
368
    
369
    public String getPartition();
370
    public String getService();
371
    public String getRegion();
372
    public String getAccountId();
373
    public ArnResource getResource();
374
    
375
    public String toString();
376
}
377

378
// ARN resource component representation  
379
class ArnResource {
380
    public static ArnResource fromString(String resource);
381
    public String getResourceType();
382
    public String getResource();
383
    public String getQualifier();
384
    public boolean hasResourceType();
385
}
386
```
387

388
**[Learn more about ARN Support →](./arn-support.md)**
389

390
### Endpoint Discovery
391
Automatic service endpoint discovery and optimization for improved connectivity and performance.
392

393
```java { .api }
394
// Core endpoint discovery provider interface
395
interface EndpointDiscoveryProvider {
396
    boolean isEndpointDiscoveryEnabled();
397
    void refresh();
398
}
399

400
// Default endpoint discovery provider chain
401
class DefaultEndpointDiscoveryProviderChain extends EndpointDiscoveryProviderChain {
402
    public static DefaultEndpointDiscoveryProviderChain getInstance();
403
}
404

405
// Environment variable endpoint discovery provider
406
class EnvironmentVariableEndpointDiscoveryProvider extends BaseEndpointDiscoveryProvider {
407
    public static final String AWS_ENABLE_ENDPOINT_DISCOVERY = "AWS_ENABLE_ENDPOINT_DISCOVERY";
408
    public boolean isEndpointDiscoveryEnabled();
409
}
410
```
411

412
**[Learn more about Endpoint Discovery →](./endpoint-discovery.md)**
413

414
## Exception Hierarchy
415

416
All AWS SDK operations can throw exceptions from this hierarchy:
417

418
```java { .api }
419
// Base SDK exception class (extends RuntimeException)
420
class SdkBaseException extends RuntimeException {
421
    public SdkBaseException(String message);
422
    public SdkBaseException(String message, Throwable cause);
423
    public boolean isRetryable();
424
}
425

426
// Client-side exception (network, configuration, etc.)
427
class SdkClientException extends SdkBaseException {
428
    public SdkClientException(String message);
429
    public SdkClientException(String message, Throwable cause);
430
    public boolean isRetryable();
431
}
432

433
// Legacy client exception (for backward compatibility)
434
class AmazonClientException extends SdkBaseException {
435
    public AmazonClientException(String message);
436
    public AmazonClientException(String message, Throwable t);
437
    public AmazonClientException(Throwable cause);
438
    public boolean isRetryable();
439
}
440

441
// Service exception with error details
442
class AmazonServiceException extends SdkClientException {
443
    public String getErrorCode();
444
    public String getErrorMessage(); 
445
    public String getErrorType();
446
    public int getStatusCode();
447
    public String getServiceName();
448
    public String getRequestId();
449
}
450
```
451

452
## Migration Notes
453

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

456
- **ClientConfiguration** → **ClientOverrideConfiguration** (v2)
457
- **HTTP Settings** → **SdkHttpClient.Builder** (v2) 
458
- **Credentials** → **AwsCredentialsProvider** (v2)
459
- **Regions** → **software.amazon.awssdk.regions.Region** (v2)
460

461
See the [AWS SDK Java Migration Guide](https://docs.aws.amazon.com/sdk-for-java/latest/migration-guide/) for comprehensive migration information.
462

463
**[Learn more about Exception Handling →](./exception-handling.md)**
464

465
## Related Documentation
466

467
### Core Functionality
468
- [Authentication & Credentials](./authentication.md)
469
- [Client Builders & Configuration](./client-builders.md)
470
- [Exception Handling](./exception-handling.md)
471
- [Regions & Endpoints](./regions-endpoints.md)
472
- [HTTP Transport](./http-transport.md)
473

474
### Advanced Features  
475
- [ARN Support & Resource Management](./arn-support.md)
476
- [Endpoint Discovery](./endpoint-discovery.md)
477
- [Protocols](./protocols.md)
478
- [Retry Policies](./retry-policies.md)
479
- [Waiters](./waiters.md)
480

481
### Utilities & Monitoring
482
- [Utilities](./utilities.md)
483
- [Metrics & Monitoring](./metrics-monitoring.md)