0
# Client Management
1

2
Client management capabilities provide the foundation for connecting to and configuring Amazon SQS services. This includes client creation, configuration, authentication setup, and lifecycle management.
3

4
## Client Creation
5

6
### Standard Client Builder
7

8
Create synchronous SQS clients with fluent configuration.
9

10
```java { .api }
11
class AmazonSQSClientBuilder extends AwsSyncClientBuilder<AmazonSQSClientBuilder, AmazonSQS> {
12
    static AmazonSQSClientBuilder standard();
13
    static AmazonSQS defaultClient();
14
    AmazonSQS build();
15
}
16
```
17

18
**Usage Example:**
19

20
```java
21
// Using default configuration
22
AmazonSQS client = AmazonSQSClientBuilder.defaultClient();
23

24
// Custom configuration
25
AmazonSQS client = AmazonSQSClientBuilder.standard()
26
    .withRegion(Regions.US_WEST_2)
27
    .withCredentials(new ProfileCredentialsProvider())
28
    .build();
29
```
30

31
### Async Client Builder
32

33
Create asynchronous SQS clients for non-blocking operations.
34

35
```java { .api }
36
class AmazonSQSAsyncClientBuilder extends AwsAsyncClientBuilder<AmazonSQSAsyncClientBuilder, AmazonSQSAsync> {
37
    static AmazonSQSAsyncClientBuilder standard();
38
    static AmazonSQSAsync defaultClient();
39
    AmazonSQSAsync build();
40
}
41
```
42

43
**Usage Example:**
44

45
```java
46
// Default async client
47
AmazonSQSAsync asyncClient = AmazonSQSAsyncClientBuilder.defaultClient();
48

49
// Custom async client
50
AmazonSQSAsync asyncClient = AmazonSQSAsyncClientBuilder.standard()
51
    .withRegion(Regions.EU_WEST_1)
52
    .withExecutorFactory(() -> Executors.newFixedThreadPool(10))
53
    .build();
54
```
55

56
## Client Interfaces
57

58
### Synchronous Client Interface
59

60
Main interface for synchronous SQS operations.
61

62
```java { .api }
63
interface AmazonSQS {
64
    String ENDPOINT_PREFIX = "sqs";
65
    
66
    // Endpoint configuration (deprecated - use builders instead)
67
    void setEndpoint(String endpoint);
68
    void setRegion(Region region);
69
    
70
    // Client lifecycle
71
    void shutdown();
72
    ResponseMetadata getCachedResponseMetadata(AmazonWebServiceRequest request);
73
    
74
    // All SQS operations...
75
    CreateQueueResult createQueue(CreateQueueRequest request);
76
    SendMessageResult sendMessage(SendMessageRequest request);
77
    ReceiveMessageResult receiveMessage(ReceiveMessageRequest request);
78
    // ... (full operation list in respective capability docs)
79
}
80
```
81

82
### Asynchronous Client Interface
83

84
Interface extending synchronous operations with Future-based async methods.
85

86
```java { .api }
87
interface AmazonSQSAsync extends AmazonSQS {
88
    // All sync methods plus async variants with Future return types
89
    Future<CreateQueueResult> createQueueAsync(CreateQueueRequest request);
90
    Future<CreateQueueResult> createQueueAsync(CreateQueueRequest request,
91
        AsyncHandler<CreateQueueRequest, CreateQueueResult> asyncHandler);
92
    
93
    Future<SendMessageResult> sendMessageAsync(SendMessageRequest request);
94
    Future<SendMessageResult> sendMessageAsync(SendMessageRequest request,
95
        AsyncHandler<SendMessageRequest, SendMessageResult> asyncHandler);
96
    
97
    // ... async variants for all operations
98
}
99
```
100

101
## Client Implementations
102

103
### Standard Synchronous Client
104

105
Thread-safe implementation of the synchronous SQS interface.
106

107
```java { .api }
108
class AmazonSQSClient implements AmazonSQS {
109
    // Constructors (prefer using builders)
110
    AmazonSQSClient();
111
    AmazonSQSClient(AWSCredentials awsCredentials);
112
    AmazonSQSClient(AWSCredentialsProvider awsCredentialsProvider);
113
    AmazonSQSClient(ClientConfiguration clientConfiguration);
114
    // Additional constructor overloads...
115
}
116
```
117

118
### Standard Asynchronous Client
119

120
Thread-safe implementation of the asynchronous SQS interface.
121

122
```java { .api }
123
class AmazonSQSAsyncClient extends AmazonSQSClient implements AmazonSQSAsync {
124
    // Constructors (prefer using builders)
125
    AmazonSQSAsyncClient();
126
    AmazonSQSAsyncClient(AWSCredentials awsCredentials);
127
    AmazonSQSAsyncClient(AWSCredentialsProvider awsCredentialsProvider);
128
    // Additional constructor overloads...
129
}
130
```
131

132
## Client Configuration
133

134
### Authentication
135

136
Configure AWS credentials for API access:
137

138
```java
139
// Using default credential chain
140
AmazonSQS client = AmazonSQSClientBuilder.defaultClient();
141

142
// Using specific credential provider
143
AmazonSQS client = AmazonSQSClientBuilder.standard()
144
    .withCredentials(new ProfileCredentialsProvider("myprofile"))
145
    .build();
146

147
// Using access keys (not recommended for production)
148
AmazonSQS client = AmazonSQSClientBuilder.standard()
149
    .withCredentials(new AWSStaticCredentialsProvider(
150
        new BasicAWSCredentials("accessKey", "secretKey")))
151
    .build();
152
```
153

154
### Region Configuration
155

156
Set the AWS region for SQS operations:
157

158
```java
159
// Specific region
160
AmazonSQS client = AmazonSQSClientBuilder.standard()
161
    .withRegion(Regions.US_EAST_1)
162
    .build();
163

164
// Region from string
165
AmazonSQS client = AmazonSQSClientBuilder.standard()
166
    .withRegion("us-west-2")
167
    .build();
168

169
// Custom endpoint (for testing or special configurations)
170
AmazonSQS client = AmazonSQSClientBuilder.standard()
171
    .withEndpointConfiguration(new EndpointConfiguration(
172
        "https://sqs.us-west-2.amazonaws.com", "us-west-2"))
173
    .build();
174
```
175

176
### HTTP Configuration
177

178
Customize HTTP client settings:
179

180
```java
181
ClientConfiguration config = new ClientConfiguration()
182
    .withConnectionTimeout(5000)
183
    .withSocketTimeout(10000)
184
    .withMaxConnections(50)
185
    .withRetryPolicy(PredefinedRetryPolicies.DEFAULT_RETRY_POLICY);
186

187
AmazonSQS client = AmazonSQSClientBuilder.standard()
188
    .withClientConfiguration(config)
189
    .build();
190
```
191

192
## Client Lifecycle
193

194
### Shutdown
195

196
Properly close clients to release resources:
197

198
```java
199
// Synchronous shutdown
200
client.shutdown();
201

202
// For async clients, also shutdown executor if custom
203
if (asyncClient instanceof AmazonSQSAsyncClient) {
204
    asyncClient.shutdown();
205
}
206
```
207

208
### Response Metadata
209

210
Access diagnostic information about requests:
211

212
```java
213
SendMessageRequest request = new SendMessageRequest()
214
    .withQueueUrl(queueUrl)
215
    .withMessageBody("test message");
216

217
SendMessageResult result = client.sendMessage(request);
218

219
// Get response metadata
220
ResponseMetadata metadata = client.getCachedResponseMetadata(request);
221
String requestId = metadata.getRequestId();
222
Map<String, String> responseHeaders = metadata.getHttpHeaders();
223
```
224

225
## Error Handling
226

227
Common client-level exceptions and handling:
228

229
```java
230
try {
231
    AmazonSQS client = AmazonSQSClientBuilder.standard()
232
        .withRegion("invalid-region")
233
        .build();
234
} catch (AmazonClientException e) {
235
    // Client configuration or network errors
236
    System.err.println("Client error: " + e.getMessage());
237
} catch (AmazonServiceException e) {
238
    // Service-side errors
239
    System.err.println("Service error: " + e.getErrorCode() + " - " + e.getMessage());
240
}
241
```
242

243
## Thread Safety
244

245
All SQS client implementations are thread-safe and can be shared across multiple threads:
246

247
```java
248
// Single client instance can be used by multiple threads
249
AmazonSQS sharedClient = AmazonSQSClientBuilder.defaultClient();
250

251
// Use in multiple threads safely
252
Runnable task = () -> {
253
    try {
254
        ReceiveMessageResult result = sharedClient.receiveMessage(
255
            new ReceiveMessageRequest(queueUrl));
256
        // Process messages...
257
    } catch (Exception e) {
258
        // Handle per-thread errors
259
    }
260
};
261

262
// Submit to thread pool
263
ExecutorService executor = Executors.newFixedThreadPool(10);
264
for (int i = 0; i < 10; i++) {
265
    executor.submit(task);
266
}
267
```