0
# Client Management
1

2
Core client creation, configuration, and lifecycle management functionality for AWS STS SDK. This includes synchronous and asynchronous client builders, endpoint configuration, region settings, and proper resource cleanup.
3

4
## Capabilities
5

6
### Synchronous Client Builder
7

8
Creates and configures synchronous STS clients using the builder pattern.
9

10
```java { .api }
11
/**
12
 * Builder for creating synchronous STS clients
13
 */
14
public class AWSSecurityTokenServiceClientBuilder 
15
    extends AwsClientBuilder<AWSSecurityTokenServiceClientBuilder, AWSSecurityTokenService> {
16
    
17
    /**
18
     * Create a new builder instance with default configuration
19
     * @return Builder instance for method chaining
20
     */
21
    public static AWSSecurityTokenServiceClientBuilder standard();
22
    
23
    /**
24
     * Create a client with default configuration  
25
     * @return Configured AWSSecurityTokenService client
26
     */
27
    public static AWSSecurityTokenService defaultClient();
28
}
29
```
30

31
**Usage Examples:**
32

33
```java
34
import com.amazonaws.services.securitytoken.AWSSecurityTokenService;
35
import com.amazonaws.services.securitytoken.AWSSecurityTokenServiceClientBuilder;
36
import com.amazonaws.regions.Regions;
37

38
// Create with default configuration
39
AWSSecurityTokenService stsClient = AWSSecurityTokenServiceClientBuilder.defaultClient();
40

41
// Create with custom configuration
42
AWSSecurityTokenService customClient = AWSSecurityTokenServiceClientBuilder.standard()
43
    .withRegion(Regions.US_WEST_2)
44
    .withCredentials(new DefaultAWSCredentialsProviderChain())
45
    .build();
46

47
// Create with custom endpoint
48
AWSSecurityTokenService regionalClient = AWSSecurityTokenServiceClientBuilder.standard()
49
    .withEndpointConfiguration(new EndpointConfiguration(
50
        "https://sts.us-west-2.amazonaws.com", 
51
        "us-west-2"
52
    ))
53
    .build();
54
```
55

56
### Asynchronous Client Builder
57

58
Creates and configures asynchronous STS clients for non-blocking operations.
59

60
```java { .api }
61
/**
62
 * Builder for creating asynchronous STS clients
63
 */
64
public class AWSSecurityTokenServiceAsyncClientBuilder 
65
    extends AwsAsyncClientBuilder<AWSSecurityTokenServiceAsyncClientBuilder, AWSSecurityTokenServiceAsync> {
66
    
67
    /**
68
     * Create a new async builder instance with default configuration
69
     * @return Async builder instance for method chaining
70
     */
71
    public static AWSSecurityTokenServiceAsyncClientBuilder standard();
72
    
73
    /**
74
     * Create an async client with default configuration
75
     * @return Configured AWSSecurityTokenServiceAsync client
76
     */
77
    public static AWSSecurityTokenServiceAsync defaultClient();
78
}
79
```
80

81
**Usage Examples:**
82

83
```java
84
import com.amazonaws.services.securitytoken.AWSSecurityTokenServiceAsync;
85
import com.amazonaws.services.securitytoken.AWSSecurityTokenServiceAsyncClientBuilder;
86
import java.util.concurrent.Future;
87

88
// Create async client with default configuration
89
AWSSecurityTokenServiceAsync asyncClient = AWSSecurityTokenServiceAsyncClientBuilder.defaultClient();
90

91
// Create with custom thread pool and configuration
92
AWSSecurityTokenServiceAsync customAsyncClient = AWSSecurityTokenServiceAsyncClientBuilder.standard()
93
    .withRegion(Regions.EU_WEST_1)
94
    .withExecutorFactory(() -> Executors.newFixedThreadPool(10))
95
    .build();
96

97
// Use async client
98
Future<GetCallerIdentityResult> future = asyncClient.getCallerIdentityAsync(
99
    new GetCallerIdentityRequest()
100
);
101
GetCallerIdentityResult result = future.get();
102
```
103

104
### Client Configuration
105

106
Core client interface methods for endpoint configuration and resource management.
107

108
```java { .api }
109
/**
110
 * Main interface for accessing AWS STS
111
 */
112
public interface AWSSecurityTokenService {
113
    
114
    /**
115
     * Overrides the default endpoint for this client
116
     * @param endpoint The endpoint or full URL for AWS STS
117
     * @deprecated Use AwsClientBuilder.setEndpointConfiguration instead
118
     */
119
    @Deprecated
120
    void setEndpoint(String endpoint);
121
    
122
    /**
123
     * Sets the regional endpoint for this client's service calls
124
     * @param region The region this client will communicate with
125
     * @deprecated Use AwsClientBuilder.setRegion instead
126
     */
127
    @Deprecated
128
    void setRegion(Region region);
129
    
130
    /**
131
     * Shuts down this client object, releasing any resources that might be held open
132
     * This is an optional method, but recommended for explicit resource cleanup
133
     */
134
    void shutdown();
135
    
136
    /**
137
     * Returns additional metadata for a previously executed successful request
138
     * @param request The originally executed request
139
     * @return The response metadata for the specified request, or null if none available
140
     */
141
    ResponseMetadata getCachedResponseMetadata(AmazonWebServiceRequest request);
142
    
143
    /**
144
     * The region metadata service name for computing region endpoints
145
     */
146
    String ENDPOINT_PREFIX = "sts";
147
}
148
```
149

150
**Usage Examples:**
151

152
```java
153
import com.amazonaws.services.securitytoken.AWSSecurityTokenService;
154
import com.amazonaws.services.securitytoken.AWSSecurityTokenServiceClientBuilder;
155
import com.amazonaws.regions.Regions;
156

157
// Create client
158
AWSSecurityTokenService stsClient = AWSSecurityTokenServiceClientBuilder.standard()
159
    .withRegion(Regions.US_EAST_1)
160
    .build();
161

162
try {
163
    // Use client for operations
164
    GetCallerIdentityResult result = stsClient.getCallerIdentity(new GetCallerIdentityRequest());
165
    
166
    // Get response metadata for debugging
167
    ResponseMetadata metadata = stsClient.getCachedResponseMetadata(new GetCallerIdentityRequest());
168
    if (metadata != null) {
169
        System.out.println("Request ID: " + metadata.getRequestId());
170
    }
171
    
172
} finally {
173
    // Always shutdown client to release resources
174
    stsClient.shutdown();
175
}
176
```
177

178
### Thread Safety and Best Practices
179

180
All AWS STS clients are thread-safe and can be shared across multiple threads. It's recommended to:
181

182
1. **Reuse clients**: Create one client instance and reuse it across your application
183
2. **Proper shutdown**: Always call `shutdown()` when done with a client
184
3. **Regional clients**: Create separate clients for different AWS regions
185
4. **Connection pooling**: Clients automatically manage HTTP connection pooling
186
5. **Credential management**: Use credential providers rather than hard-coding credentials
187

188
**Best Practice Example:**
189

190
```java
191
@Component
192
public class STSService {
193
    private final AWSSecurityTokenService stsClient;
194
    
195
    public STSService() {
196
        this.stsClient = AWSSecurityTokenServiceClientBuilder.standard()
197
            .withRegion(Regions.US_EAST_1)
198
            .withCredentials(new DefaultAWSCredentialsProviderChain())
199
            .build();
200
    }
201
    
202
    public GetCallerIdentityResult getCallerIdentity() {
203
        return stsClient.getCallerIdentity(new GetCallerIdentityRequest());
204
    }
205
    
206
    @PreDestroy
207
    public void shutdown() {
208
        if (stsClient != null) {
209
            stsClient.shutdown();
210
        }
211
    }
212
}