0
# Regions & Endpoint Resolution
1

2
The AWS Java SDK Core provides comprehensive region and endpoint management capabilities, including region enumeration, automatic region detection, and service endpoint resolution.
3

4
## Core Region Classes
5

6
### Region Representation
7

8
```java { .api }
9
// AWS region representation
10
class Region {
11
    public static Region getRegion(Regions region);
12
    public String getName();
13
    public String getDomain();
14
    public String getPartition();
15
    public boolean isServiceSupported(String serviceName);
16
    public String getServiceEndpoint(String serviceName);
17
    public boolean hasHttpsEndpoint(String serviceName);
18
    public boolean hasHttpEndpoint(String serviceName);
19
    public Collection<String> getAvailableEndpoints();
20
}
21

22
// Region enumeration with all AWS regions
23
enum Regions {
24
    // US regions
25
    US_EAST_1("us-east-1", "US East (N. Virginia)"),
26
    US_EAST_2("us-east-2", "US East (Ohio)"), 
27
    US_WEST_1("us-west-1", "US West (N. California)"),
28
    US_WEST_2("us-west-2", "US West (Oregon)"),
29
    
30
    // Europe regions
31
    EU_WEST_1("eu-west-1", "Europe (Ireland)"),
32
    EU_WEST_2("eu-west-2", "Europe (London)"),
33
    EU_WEST_3("eu-west-3", "Europe (Paris)"),
34
    EU_CENTRAL_1("eu-central-1", "Europe (Frankfurt)"),
35
    EU_NORTH_1("eu-north-1", "Europe (Stockholm)"),
36
    EU_SOUTH_1("eu-south-1", "Europe (Milan)"),
37
    
38
    // Asia Pacific regions
39
    AP_NORTHEAST_1("ap-northeast-1", "Asia Pacific (Tokyo)"),
40
    AP_NORTHEAST_2("ap-northeast-2", "Asia Pacific (Seoul)"),
41
    AP_NORTHEAST_3("ap-northeast-3", "Asia Pacific (Osaka)"),
42
    AP_SOUTHEAST_1("ap-southeast-1", "Asia Pacific (Singapore)"),
43
    AP_SOUTHEAST_2("ap-southeast-2", "Asia Pacific (Sydney)"),
44
    AP_SOUTH_1("ap-south-1", "Asia Pacific (Mumbai)"),
45
    
46
    // Other regions
47
    CA_CENTRAL_1("ca-central-1", "Canada (Central)"),
48
    SA_EAST_1("sa-east-1", "South America (São Paulo)"),
49
    AF_SOUTH_1("af-south-1", "Africa (Cape Town)"),
50
    ME_SOUTH_1("me-south-1", "Middle East (Bahrain)"),
51
    
52
    // China regions  
53
    CN_NORTH_1("cn-north-1", "China (Beijing)"),
54
    CN_NORTHWEST_1("cn-northwest-1", "China (Ningxia)"),
55
    
56
    // GovCloud regions
57
    US_GOV_EAST_1("us-gov-east-1", "AWS GovCloud (US-East)"),
58
    US_GOV_WEST_1("us-gov-west-1", "AWS GovCloud (US-West)");
59
    
60
    public String getName();
61
    public String getDescription();
62
    
63
    public static Regions fromName(String regionName);
64
    public static Regions getCurrentRegion();
65
}
66

67
// Region implementation interface
68
interface RegionImpl {
69
    String getName();
70
    String getDomain();  
71
    String getPartition();
72
    boolean isServiceSupported(String serviceName);
73
    String getServiceEndpoint(String serviceName);
74
    boolean hasHttpsEndpoint(String serviceName);
75
    boolean hasHttpEndpoint(String serviceName);
76
    Collection<String> getAvailableEndpoints();
77
}
78

79
// In-memory region implementation
80
class InMemoryRegionImpl implements RegionImpl {
81
    public InMemoryRegionImpl(String name, String domain);
82
    public String getName();
83
    public String getDomain();
84
    public String getPartition();
85
    public boolean isServiceSupported(String serviceName);
86
    public String getServiceEndpoint(String serviceName);
87
    public boolean hasHttpsEndpoint(String serviceName);
88
    public boolean hasHttpEndpoint(String serviceName);
89
    public Collection<String> getAvailableEndpoints();
90
}
91
```
92

93
### Region Utilities
94

95
```java { .api }
96
// Region utility methods
97
class RegionUtils {
98
    // Get region by enum
99
    public static Region getRegion(Regions region);
100
    
101
    // Get region by name string
102
    public static Region getRegion(String regionName);
103
    
104
    // Get region from endpoint
105
    public static Region getRegionByEndpoint(String endpoint);
106
    
107
    // Get all available regions
108
    public static List<Region> getRegions();
109
    
110
    // Get regions for specific service
111
    public static List<Region> getRegionsForService(String serviceName);
112
    
113
    // Initialize regions from metadata
114
    public static void initializeFromRegionProvider(RegionMetadataProvider regionMetadataProvider);
115
    
116
    // Enable/disable region caching
117
    public static void enableInMemoryCaching();
118
}
119
```
120

121
## Region Metadata
122

123
### Region Metadata Classes
124

125
```java { .api }
126
// Region metadata container
127
class RegionMetadata {
128
    public RegionMetadata(RegionMetadataProvider regionMetadataProvider);
129
    public Region getRegion(String regionName);
130
    public List<Region> getRegions();
131
    public List<Region> getRegionsForService(String serviceName);
132
    public String getPartitionForRegion(String regionName);
133
}
134

135
// Region metadata provider interface
136
interface RegionMetadataProvider {
137
    Collection<Region> getRegions();
138
    Region getRegion(String regionName);
139
    List<Region> getRegionsForService(String serviceName);
140
}
141

142
// Abstract region metadata provider
143
abstract class AbstractRegionMetadataProvider implements RegionMetadataProvider {
144
    public abstract Collection<Region> getRegions();
145
    public Region getRegion(String regionName);
146
    public List<Region> getRegionsForService(String serviceName);
147
}
148

149
// In-memory regions provider
150
class InMemoryRegionsProvider extends AbstractRegionMetadataProvider {
151
    public InMemoryRegionsProvider(Collection<Region> regions);
152
    public Collection<Region> getRegions();
153
}
154

155
// Region metadata factory
156
class RegionMetadataFactory {
157
    public static RegionMetadata create();
158
    public static RegionMetadata create(RegionMetadataProvider provider);
159
}
160

161
// Region metadata parser
162
class RegionMetadataParser {
163
    public static RegionMetadata parse(String json);
164
    public static RegionMetadata parse(InputStream inputStream);
165
    public static RegionMetadata parse(File file);
166
}
167
```
168

169
### Legacy Region Support
170

171
```java { .api }
172
// Legacy region XML metadata builder
173
class LegacyRegionXmlMetadataBuilder {
174
    public static void registerLegacyRegions();
175
    public static RegionMetadata build();
176
}
177

178
// Legacy region XML loading utilities
179
class LegacyRegionXmlLoadUtils {
180
    public static void load();
181
    public static void load(String resourcePath);
182
    public static void load(InputStream inputStream);
183
}
184
```
185

186
## Region Providers
187

188
### Region Provider Interface
189

190
```java { .api }
191
// Base class for region providers
192
abstract class AwsRegionProvider {
193
    public abstract String getRegion() throws SdkClientException;
194
}
195

196
// Region provider chain
197
class AwsRegionProviderChain extends AwsRegionProvider {
198
    public AwsRegionProviderChain(AwsRegionProvider... providers);
199
    public String getRegion() throws SdkClientException;
200
}
201

202
// Default region provider chain
203
class DefaultAwsRegionProviderChain extends AwsRegionProviderChain {
204
    public static DefaultAwsRegionProviderChain getInstance();
205
    public String getRegion() throws SdkClientException;
206
}
207
```
208

209
### Built-in Region Providers
210

211
```java { .api }
212
// Environment variable region provider
213
class AwsEnvVarOverrideRegionProvider extends AwsRegionProvider {
214
    public String getRegion() throws SdkClientException;
215
    public String toString();
216
}
217

218
// System property region provider
219
class AwsSystemPropertyRegionProvider extends AwsRegionProvider {
220
    public String getRegion() throws SdkClientException;
221
    public String toString();
222
}
223

224
// AWS profile region provider
225
class AwsProfileRegionProvider extends AwsRegionProvider {
226
    public AwsProfileRegionProvider();
227
    public AwsProfileRegionProvider(String profileName);
228
    public AwsProfileRegionProvider(String profilesConfigFilePath, String profileName);
229
    public String getRegion() throws SdkClientException;
230
    public String toString();
231
}
232

233
// EC2 instance metadata region provider
234
class InstanceMetadataRegionProvider extends AwsRegionProvider {
235
    public static InstanceMetadataRegionProvider getInstance();
236
    public InstanceMetadataRegionProvider();
237
    public String getRegion() throws SdkClientException;
238
    public String toString();
239
}
240
```
241

242
## Endpoint Resolution
243

244
### Endpoint Utilities
245

246
```java { .api }
247
// Maps endpoints to regions
248
class EndpointToRegion {
249
    public static String guessRegionNameForEndpoint(String endpoint);
250
    public static String guessRegionNameForEndpoint(String endpoint, String serviceName);
251
}
252

253
// Region from endpoint metadata provider
254
class MetadataSupportedRegionFromEndpointProvider extends AwsRegionProvider {
255
    public MetadataSupportedRegionFromEndpointProvider();
256
    public String getRegion() throws SdkClientException;
257
}
258
```
259

260
## Usage Examples
261

262
### Basic Region Configuration
263

264
```java
265
import com.amazonaws.regions.*;
266

267
// Get region by enumeration
268
Region region = Region.getRegion(Regions.US_EAST_1);
269

270
// Get region by string name
271
Region regionByName = Region.getRegion("us-west-2");
272

273
// Get all available regions
274
List<Region> allRegions = RegionUtils.getRegions();
275

276
// Check if service is supported in region
277
boolean isSupported = region.isServiceSupported("s3");
278

279
// Get service endpoint for region
280
String s3Endpoint = region.getServiceEndpoint("s3");
281
```
282

283
### Automatic Region Detection
284

285
```java
286
import com.amazonaws.regions.*;
287

288
// Use default region provider chain
289
DefaultAwsRegionProviderChain regionProvider = 
290
    DefaultAwsRegionProviderChain.getInstance();
291

292
try {
293
    String regionName = regionProvider.getRegion();
294
    Region region = Region.getRegion(regionName);
295
    System.out.println("Detected region: " + regionName);
296
} catch (SdkClientException e) {
297
    System.err.println("Could not determine region: " + e.getMessage());
298
    // Fall back to default region
299
    Region region = Region.getRegion(Regions.US_EAST_1);
300
}
301
```
302

303
### Custom Region Provider Chain
304

305
```java
306
import com.amazonaws.regions.*;
307

308
// Create custom region provider chain
309
AwsRegionProviderChain customChain = new AwsRegionProviderChain(
310
    new AwsEnvVarOverrideRegionProvider(),           // Check AWS_REGION env var
311
    new AwsSystemPropertyRegionProvider(),           // Check aws.region system property  
312
    new AwsProfileRegionProvider("my-profile"),      // Check specific profile
313
    new InstanceMetadataRegionProvider()             // Check EC2 metadata
314
);
315

316
try {
317
    String regionName = customChain.getRegion();
318
    Region region = Region.getRegion(regionName);
319
} catch (SdkClientException e) {
320
    // Handle no region found
321
}
322
```
323

324
### Region from Endpoint
325

326
```java
327
import com.amazonaws.regions.*;
328

329
// Guess region from service endpoint
330
String endpoint = "s3.us-west-2.amazonaws.com";
331
String regionName = EndpointToRegion.guessRegionNameForEndpoint(endpoint, "s3");
332
Region region = Region.getRegion(regionName);
333

334
System.out.println("Detected region: " + regionName); // us-west-2
335
```
336

337
### Working with Service Endpoints
338

339
```java
340
import com.amazonaws.regions.*;
341

342
Region region = Region.getRegion(Regions.EU_WEST_1);
343

344
// Check service support
345
if (region.isServiceSupported("dynamodb")) {
346
    String endpoint = region.getServiceEndpoint("dynamodb");
347
    boolean hasHttps = region.hasHttpsEndpoint("dynamodb");
348
    boolean hasHttp = region.hasHttpEndpoint("dynamodb");
349
    
350
    System.out.println("DynamoDB endpoint: " + endpoint);
351
    System.out.println("HTTPS supported: " + hasHttps);
352
    System.out.println("HTTP supported: " + hasHttp);
353
}
354

355
// Get all available service endpoints in region
356
Collection<String> availableServices = region.getAvailableEndpoints();
357
for (String serviceName : availableServices) {
358
    String endpoint = region.getServiceEndpoint(serviceName);
359
    System.out.println(serviceName + ": " + endpoint);
360
}
361
```
362

363
### Custom Region Metadata
364

365
```java
366
import com.amazonaws.regions.*;
367
import java.util.*;
368

369
// Create custom regions
370
Collection<Region> customRegions = new ArrayList<>();
371
customRegions.add(new InMemoryRegionImpl("custom-region-1", "custom.amazonaws.com"));
372
customRegions.add(new InMemoryRegionImpl("custom-region-2", "custom.amazonaws.com"));
373

374
// Create custom metadata provider
375
RegionMetadataProvider customProvider = new InMemoryRegionsProvider(customRegions);
376

377
// Initialize regions with custom provider
378
RegionUtils.initializeFromRegionProvider(customProvider);
379

380
// Use custom regions
381
Region customRegion = RegionUtils.getRegion("custom-region-1");
382
```
383

384
## Environment Variables and System Properties
385

386
### Environment Variables
387

388
- `AWS_REGION` - The AWS region name
389
- `AWS_DEFAULT_REGION` - Default region name (fallback)
390

391
### System Properties
392

393
- `aws.region` - The AWS region name
394

395
### Profile Configuration
396

397
In `~/.aws/config`:
398
```ini
399
[default]
400
region = us-west-2
401

402
[profile production]  
403
region = eu-west-1
404

405
[profile development]
406
region = us-east-1
407
```
408

409
## Region Provider Chain Order
410

411
The `DefaultAwsRegionProviderChain` checks providers in this order:
412

413
1. **Environment Variables** - `AWS_REGION`, `AWS_DEFAULT_REGION`
414
2. **System Properties** - `aws.region`
415
3. **AWS Profile** - Default profile or specified profile
416
4. **EC2 Instance Metadata** - For EC2 instances
417

418
## Partition Support
419

420
AWS has multiple partitions with different domain structures:
421

422
- **AWS Standard** - `amazonaws.com` (most regions)
423
- **AWS China** - `amazonaws.com.cn` (China regions)
424
- **AWS GovCloud** - `amazonaws.com` (GovCloud regions)
425

426
```java
427
import com.amazonaws.regions.*;
428

429
Region region = Region.getRegion(Regions.CN_NORTH_1);
430
String partition = region.getPartition(); // "aws-cn"
431
String domain = region.getDomain(); // "amazonaws.com.cn"
432
```
433

434
## Best Practices
435

436
1. **Use Default Region Provider Chain**: Start with `DefaultAwsRegionProviderChain.getInstance()` for automatic region detection.
437

438
2. **Environment-Based Configuration**: Use environment variables or profiles for different deployment environments.
439

440
3. **Region Validation**: Always check if a service is supported in your target region using `isServiceSupported()`.
441

442
4. **Fallback Strategy**: Have a fallback region in case automatic detection fails.
443

444
5. **Service Endpoints**: Use `getServiceEndpoint()` to get the correct endpoint for services in specific regions.
445

446
6. **Cross-Region Considerations**: Be aware of data transfer costs and latency when working across regions.
447

448
7. **Government and China Regions**: Special handling may be required for AWS GovCloud and China regions due to different partitions.
449

450
The region and endpoint resolution system provides flexible and automatic region detection, enabling applications to work seamlessly across different AWS regions and deployment environments.