0
# AWS SDK for Java 1.x
1

2
The AWS SDK for Java 1.x is a comprehensive library that enables Java developers to easily work with Amazon Web Services and build scalable solutions. It provides Java APIs for over 370 AWS services including Amazon S3, Amazon DynamoDB, Amazon EC2, AWS Lambda, and hundreds more.
3

4
**Important**: This SDK is in maintenance mode as of July 31, 2024 and will reach end-of-support on December 31, 2025. AWS recommends migrating to the AWS SDK for Java 2.x for continued support and new features.
5

6
## Package Information
7

8
- **Package Name**: aws-java-sdk
9
- **Package Type**: maven
10
- **Group ID**: com.amazonaws
11
- **Language**: Java
12
- **Minimum Java Version**: Java 8+
13
- **License**: Apache 2.0
14
- **Version**: 1.12.793
15
- **Status**: Maintenance mode (end-of-support: December 31, 2025)
16
- **Migration Path**: AWS SDK for Java 2.x (`software.amazon.awssdk`)
17

18
## Installation
19

20
### Using Maven with BOM (Recommended)
21

22
```xml { .api }
23
<dependencyManagement>
24
  <dependencies>
25
    <dependency>
26
      <groupId>com.amazonaws</groupId>
27
      <artifactId>aws-java-sdk-bom</artifactId>
28
      <version>1.12.793</version>
29
      <type>pom</type>
30
      <scope>import</scope>
31
    </dependency>
32
  </dependencies>
33
</dependencyManagement>
34

35
<dependencies>
36
  <!-- Include only the services you need -->
37
  <dependency>
38
    <groupId>com.amazonaws</groupId>
39
    <artifactId>aws-java-sdk-s3</artifactId>
40
  </dependency>
41
  <dependency>
42
    <groupId>com.amazonaws</groupId>
43
    <artifactId>aws-java-sdk-dynamodb</artifactId>
44
  </dependency>
45
</dependencies>
46
```
47

48
### Using Gradle
49

50
```groovy { .api }
51
dependencies {
52
    implementation platform('com.amazonaws:aws-java-sdk-bom:1.12.793')
53
    implementation 'com.amazonaws:aws-java-sdk-s3'
54
    implementation 'com.amazonaws:aws-java-sdk-dynamodb'
55
}
56
```
57

58
## Core Imports
59

60
```java { .api }
61
// Core SDK classes
62
import com.amazonaws.auth.AWSCredentials;
63
import com.amazonaws.auth.AWSCredentialsProvider;
64
import com.amazonaws.auth.DefaultAWSCredentialsProviderChain;
65
import com.amazonaws.regions.Regions;
66
import com.amazonaws.ClientConfiguration;
67
import com.amazonaws.AmazonServiceException;
68
import com.amazonaws.SdkClientException;
69

70
// Service-specific imports (example: S3)
71
import com.amazonaws.services.s3.AmazonS3;
72
import com.amazonaws.services.s3.AmazonS3ClientBuilder;
73
import com.amazonaws.services.s3.model.*;
74

75
// Service-specific imports (example: DynamoDB)
76
import com.amazonaws.services.dynamodbv2.AmazonDynamoDB;
77
import com.amazonaws.services.dynamodbv2.AmazonDynamoDBClientBuilder;
78
import com.amazonaws.services.dynamodbv2.model.*;
79
```
80

81
## Basic Usage
82

83
### Creating a Service Client
84

85
```java
86
import com.amazonaws.auth.DefaultAWSCredentialsProviderChain;
87
import com.amazonaws.regions.Regions;
88
import com.amazonaws.services.s3.AmazonS3;
89
import com.amazonaws.services.s3.AmazonS3ClientBuilder;
90

91
// Create S3 client with default configuration
92
AmazonS3 s3Client = AmazonS3ClientBuilder.standard()
93
    .withRegion(Regions.US_WEST_2)
94
    .withCredentials(new DefaultAWSCredentialsProviderChain())
95
    .build();
96

97
// Use the client
98
s3Client.listBuckets().forEach(bucket -> {
99
    System.out.println("Bucket: " + bucket.getName());
100
});
101
```
102

103
### Working with Credentials
104

105
```java
106
import com.amazonaws.auth.DefaultAWSCredentialsProviderChain;
107
import com.amazonaws.auth.AWSStaticCredentialsProvider;
108
import com.amazonaws.auth.BasicAWSCredentials;
109

110
// Recommended: Use default credential provider chain
111
// Automatically searches: env vars -> system properties -> profile -> IAM role
112
DefaultAWSCredentialsProviderChain credentialsProvider =
113
    new DefaultAWSCredentialsProviderChain();
114

115
// For development/testing: Static credentials
116
AWSStaticCredentialsProvider staticCreds = new AWSStaticCredentialsProvider(
117
    new BasicAWSCredentials("accessKey", "secretKey")
118
);
119
```
120

121
### Exception Handling
122

123
```java
124
import com.amazonaws.AmazonServiceException;
125
import com.amazonaws.SdkClientException;
126

127
try {
128
    s3Client.getObject("my-bucket", "my-key");
129
} catch (AmazonServiceException ase) {
130
    // Service-side error (4xx, 5xx HTTP status)
131
    System.err.println("Error Code: " + ase.getErrorCode());
132
    System.err.println("HTTP Status: " + ase.getStatusCode());
133
    System.err.println("Request ID: " + ase.getRequestId());
134
} catch (SdkClientException sce) {
135
    // Client-side error (network failure, etc.)
136
    System.err.println("Client error: " + sce.getMessage());
137
}
138
```
139

140
## Architecture
141

142
The AWS SDK for Java 1.x is organized as a modular Maven-based monorepo containing 371+ service modules. Each AWS service follows a consistent architectural pattern, making it easy to work with any service once you understand the core concepts.
143

144
### Module Organization
145

146
**Service Module Naming**: `aws-java-sdk-{service-name}`
147
- Examples: `aws-java-sdk-s3`, `aws-java-sdk-dynamodb`, `aws-java-sdk-ec2`
148

149
**Package Structure**: `com.amazonaws.services.{service-name}`
150

151
**Standard Classes Per Service**:
152
- Service Interface: `Amazon{Service}` or `AWS{Service}` (e.g., `AmazonS3`, `AmazonDynamoDB`)
153
- Service Client: `{Interface}Client` (e.g., `AmazonS3Client`)
154
- Client Builder: `{Interface}ClientBuilder` (e.g., `AmazonS3ClientBuilder`)
155
- Async Interface: `{Interface}Async` (optional, for async operations)
156
- Model Package: `model.*` containing request/result objects and domain models
157

158
### Key Design Patterns
159

160
1. **Builder Pattern**: All service clients use fluent builders for configuration
161
2. **Request/Response Pattern**: Every operation uses typed request and result objects
162
3. **Thread-Safe Clients**: Client instances are thread-safe and should be reused
163
4. **Credential Provider Chain**: Flexible credential resolution from multiple sources
164
5. **Consistent Exception Handling**: `AmazonServiceException` for service errors, `SdkClientException` for client errors
165

166
## Capabilities
167

168
### Core SDK Features
169

170
Fundamental APIs and patterns used across all AWS services, including authentication, credential management, client builders, region configuration, and exception handling.
171

172
```java { .api }
173
// Credential providers
174
interface AWSCredentialsProvider {
175
    AWSCredentials getCredentials();
176
    void refresh();
177
}
178

179
// Default credential chain
180
class DefaultAWSCredentialsProviderChain extends AWSCredentialsProviderChain {
181
    static DefaultAWSCredentialsProviderChain getInstance();
182
}
183

184
// Client builder base
185
abstract class AwsClientBuilder<Subclass, TypeToBuild> {
186
    Subclass withRegion(Regions region);
187
    Subclass withRegion(String region);
188
    Subclass withCredentials(AWSCredentialsProvider credentialsProvider);
189
    Subclass withClientConfiguration(ClientConfiguration config);
190
    TypeToBuild build();
191
}
192

193
// Exception hierarchy
194
class AmazonServiceException extends SdkClientException {
195
    String getErrorCode();
196
    int getStatusCode();
197
    String getRequestId();
198
}
199
```
200

201
[Core SDK APIs](./core-sdk.md)
202

203
### Amazon S3 APIs
204

205
Complete API for Amazon Simple Storage Service (S3), including bucket operations, object operations, multipart uploads, pre-signed URLs, access control, and the high-level Transfer Manager for efficient large file transfers.
206

207
```java { .api }
208
// S3 client builder
209
class AmazonS3ClientBuilder extends AwsSyncClientBuilder<AmazonS3ClientBuilder, AmazonS3> {
210
    static AmazonS3ClientBuilder standard();
211
    static AmazonS3 defaultClient();
212
}
213

214
// Main S3 interface
215
interface AmazonS3 {
216
    // Bucket operations
217
    Bucket createBucket(String bucketName);
218
    void deleteBucket(String bucketName);
219
    List<Bucket> listBuckets();
220

221
    // Object operations
222
    PutObjectResult putObject(String bucketName, String key, File file);
223
    S3Object getObject(String bucketName, String key);
224
    void deleteObject(String bucketName, String key);
225
    ObjectListing listObjects(String bucketName);
226

227
    // Pre-signed URLs
228
    URL generatePresignedUrl(String bucketName, String key, Date expiration);
229
}
230
```
231

232
[S3 Service APIs](./s3-service.md)
233

234
### Amazon DynamoDB APIs
235

236
Complete API for Amazon DynamoDB, including three levels of abstraction: low-level service client for direct table and item operations, Document API for simplified item handling, and Object Mapper for ORM-style POJO mapping with annotations.
237

238
```java { .api }
239
// DynamoDB client builder
240
class AmazonDynamoDBClientBuilder extends AwsSyncClientBuilder<AmazonDynamoDBClientBuilder, AmazonDynamoDB> {
241
    static AmazonDynamoDBClientBuilder standard();
242
    static AmazonDynamoDB defaultClient();
243
}
244

245
// Low-level DynamoDB interface
246
interface AmazonDynamoDB {
247
    PutItemResult putItem(String tableName, Map<String, AttributeValue> item);
248
    GetItemResult getItem(String tableName, Map<String, AttributeValue> key);
249
    QueryResult query(QueryRequest queryRequest);
250
    ScanResult scan(ScanRequest scanRequest);
251
}
252

253
// Document API
254
class DynamoDB {
255
    DynamoDB(AmazonDynamoDB client);
256
    Table getTable(String tableName);
257
}
258

259
// Object Mapper
260
class DynamoDBMapper {
261
    DynamoDBMapper(AmazonDynamoDB dynamoDB);
262
    <T> T load(Class<T> clazz, Object hashKey);
263
    <T> void save(T object);
264
    <T> PaginatedQueryList<T> query(Class<T> clazz, DynamoDBQueryExpression<T> queryExpression);
265
}
266
```
267

268
[DynamoDB Service APIs](./dynamodb-service.md)
269

270
### Common Patterns
271

272
Essential patterns used across all AWS services including client creation, credential configuration, pagination, async operations, exception handling, waiters, and batch operations.
273

274
```java { .api }
275
// Standard client creation pattern
276
AmazonS3 client = AmazonS3ClientBuilder.standard()
277
    .withRegion(Regions.US_WEST_2)
278
    .withCredentials(new DefaultAWSCredentialsProviderChain())
279
    .build();
280

281
// Pagination pattern for list operations
282
ListObjectsV2Request request = new ListObjectsV2Request()
283
    .withBucketName(bucketName)
284
    .withMaxKeys(1000);
285

286
ListObjectsV2Result result;
287
do {
288
    result = s3.listObjectsV2(request);
289
    // Process results
290
    request.setContinuationToken(result.getNextContinuationToken());
291
} while (result.isTruncated());
292

293
// Async operations with callback
294
asyncClient.putItemAsync(request, new AsyncHandler<PutItemRequest, PutItemResult>() {
295
    public void onSuccess(PutItemRequest req, PutItemResult result) { }
296
    public void onError(Exception exception) { }
297
});
298

299
// Waiter pattern for polling resource state
300
ec2.waiters().instanceRunning().run(
301
    new WaiterParameters<>(new DescribeInstancesRequest().withInstanceIds(instanceId))
302
);
303
```
304

305
[Common Patterns](./common-patterns.md)
306

307
## Other AWS Services
308

309
The SDK includes support for 371+ AWS services. While this documentation focuses on the most commonly used services (S3 and DynamoDB), all services follow the same architectural patterns:
310

311
**Major Service Categories**:
312
- **Compute**: EC2, Lambda, ECS, EKS, Batch, Elastic Beanstalk
313
- **Storage**: S3, Glacier, EFS, FSx, Storage Gateway
314
- **Database**: DynamoDB, RDS, Redshift, Neptune, DocumentDB, ElastiCache
315
- **Networking**: ELB, ALB/NLB, Route 53, API Gateway, Direct Connect
316
- **Messaging**: SQS, SNS, Kinesis, EventBridge, MQ
317
- **Security**: IAM, STS, Cognito, Secrets Manager, KMS, ACM
318
- **AI/ML**: Bedrock, SageMaker, Rekognition, Comprehend, Translate
319
- **Developer Tools**: CodeCommit, CodeBuild, CodeDeploy, CodePipeline
320
- **Management**: CloudFormation, CloudWatch, CloudTrail, Config
321

322
Each service module follows the pattern: `aws-java-sdk-{service-name}` with consistent client builder and interface patterns.
323

324
## Migration Information
325

326
**Maintenance Mode**: As of July 31, 2024, the AWS SDK for Java 1.x is in maintenance mode. It will reach end-of-support on December 31, 2025.
327

328
**Recommended Action**: Migrate to the AWS SDK for Java 2.x
329
- Package namespace: `software.amazon.awssdk`
330
- Improved performance with non-blocking I/O
331
- Better start-up performance
332
- Automatic pagination support
333
- Continued AWS support and new features
334

335
**Migration Guide**: https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/migration.html
336

337
## Additional Resources
338

339
- **Official Documentation**: https://docs.aws.amazon.com/sdk-for-java/v1/developer-guide/welcome.html
340
- **API Reference**: https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/index.html
341
- **GitHub Repository**: https://github.com/aws/aws-sdk-java
342
- **Migration Guide**: https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/migration.html
343