CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/maven-com-amazonaws--aws-java-sdk-core

Core foundational library for AWS SDK for Java 1.x providing authentication, HTTP transport, regions, protocols, and shared utilities for all AWS service clients

—

Pending
Overview
Eval results
Files

regions-endpoints.mddocs/

Regions & Endpoint Resolution

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

Core Region Classes

Region Representation

// AWS region representation
class Region {
    public static Region getRegion(Regions region);
    public String getName();
    public String getDomain();
    public String getPartition();
    public boolean isServiceSupported(String serviceName);
    public String getServiceEndpoint(String serviceName);
    public boolean hasHttpsEndpoint(String serviceName);
    public boolean hasHttpEndpoint(String serviceName);
    public Collection<String> getAvailableEndpoints();
}

// Region enumeration with all AWS regions
enum Regions {
    // US regions
    US_EAST_1("us-east-1", "US East (N. Virginia)"),
    US_EAST_2("us-east-2", "US East (Ohio)"), 
    US_WEST_1("us-west-1", "US West (N. California)"),
    US_WEST_2("us-west-2", "US West (Oregon)"),
    
    // Europe regions
    EU_WEST_1("eu-west-1", "Europe (Ireland)"),
    EU_WEST_2("eu-west-2", "Europe (London)"),
    EU_WEST_3("eu-west-3", "Europe (Paris)"),
    EU_CENTRAL_1("eu-central-1", "Europe (Frankfurt)"),
    EU_NORTH_1("eu-north-1", "Europe (Stockholm)"),
    EU_SOUTH_1("eu-south-1", "Europe (Milan)"),
    
    // Asia Pacific regions
    AP_NORTHEAST_1("ap-northeast-1", "Asia Pacific (Tokyo)"),
    AP_NORTHEAST_2("ap-northeast-2", "Asia Pacific (Seoul)"),
    AP_NORTHEAST_3("ap-northeast-3", "Asia Pacific (Osaka)"),
    AP_SOUTHEAST_1("ap-southeast-1", "Asia Pacific (Singapore)"),
    AP_SOUTHEAST_2("ap-southeast-2", "Asia Pacific (Sydney)"),
    AP_SOUTH_1("ap-south-1", "Asia Pacific (Mumbai)"),
    
    // Other regions
    CA_CENTRAL_1("ca-central-1", "Canada (Central)"),
    SA_EAST_1("sa-east-1", "South America (São Paulo)"),
    AF_SOUTH_1("af-south-1", "Africa (Cape Town)"),
    ME_SOUTH_1("me-south-1", "Middle East (Bahrain)"),
    
    // China regions  
    CN_NORTH_1("cn-north-1", "China (Beijing)"),
    CN_NORTHWEST_1("cn-northwest-1", "China (Ningxia)"),
    
    // GovCloud regions
    US_GOV_EAST_1("us-gov-east-1", "AWS GovCloud (US-East)"),
    US_GOV_WEST_1("us-gov-west-1", "AWS GovCloud (US-West)");
    
    public String getName();
    public String getDescription();
    
    public static Regions fromName(String regionName);
    public static Regions getCurrentRegion();
}

// Region implementation interface
interface RegionImpl {
    String getName();
    String getDomain();  
    String getPartition();
    boolean isServiceSupported(String serviceName);
    String getServiceEndpoint(String serviceName);
    boolean hasHttpsEndpoint(String serviceName);
    boolean hasHttpEndpoint(String serviceName);
    Collection<String> getAvailableEndpoints();
}

// In-memory region implementation
class InMemoryRegionImpl implements RegionImpl {
    public InMemoryRegionImpl(String name, String domain);
    public String getName();
    public String getDomain();
    public String getPartition();
    public boolean isServiceSupported(String serviceName);
    public String getServiceEndpoint(String serviceName);
    public boolean hasHttpsEndpoint(String serviceName);
    public boolean hasHttpEndpoint(String serviceName);
    public Collection<String> getAvailableEndpoints();
}

Region Utilities

// Region utility methods
class RegionUtils {
    // Get region by enum
    public static Region getRegion(Regions region);
    
    // Get region by name string
    public static Region getRegion(String regionName);
    
    // Get region from endpoint
    public static Region getRegionByEndpoint(String endpoint);
    
    // Get all available regions
    public static List<Region> getRegions();
    
    // Get regions for specific service
    public static List<Region> getRegionsForService(String serviceName);
    
    // Initialize regions from metadata
    public static void initializeFromRegionProvider(RegionMetadataProvider regionMetadataProvider);
    
    // Enable/disable region caching
    public static void enableInMemoryCaching();
}

Region Metadata

Region Metadata Classes

// Region metadata container
class RegionMetadata {
    public RegionMetadata(RegionMetadataProvider regionMetadataProvider);
    public Region getRegion(String regionName);
    public List<Region> getRegions();
    public List<Region> getRegionsForService(String serviceName);
    public String getPartitionForRegion(String regionName);
}

// Region metadata provider interface
interface RegionMetadataProvider {
    Collection<Region> getRegions();
    Region getRegion(String regionName);
    List<Region> getRegionsForService(String serviceName);
}

// Abstract region metadata provider
abstract class AbstractRegionMetadataProvider implements RegionMetadataProvider {
    public abstract Collection<Region> getRegions();
    public Region getRegion(String regionName);
    public List<Region> getRegionsForService(String serviceName);
}

// In-memory regions provider
class InMemoryRegionsProvider extends AbstractRegionMetadataProvider {
    public InMemoryRegionsProvider(Collection<Region> regions);
    public Collection<Region> getRegions();
}

// Region metadata factory
class RegionMetadataFactory {
    public static RegionMetadata create();
    public static RegionMetadata create(RegionMetadataProvider provider);
}

// Region metadata parser
class RegionMetadataParser {
    public static RegionMetadata parse(String json);
    public static RegionMetadata parse(InputStream inputStream);
    public static RegionMetadata parse(File file);
}

Legacy Region Support

// Legacy region XML metadata builder
class LegacyRegionXmlMetadataBuilder {
    public static void registerLegacyRegions();
    public static RegionMetadata build();
}

// Legacy region XML loading utilities
class LegacyRegionXmlLoadUtils {
    public static void load();
    public static void load(String resourcePath);
    public static void load(InputStream inputStream);
}

Region Providers

Region Provider Interface

// Base class for region providers
abstract class AwsRegionProvider {
    public abstract String getRegion() throws SdkClientException;
}

// Region provider chain
class AwsRegionProviderChain extends AwsRegionProvider {
    public AwsRegionProviderChain(AwsRegionProvider... providers);
    public String getRegion() throws SdkClientException;
}

// Default region provider chain
class DefaultAwsRegionProviderChain extends AwsRegionProviderChain {
    public static DefaultAwsRegionProviderChain getInstance();
    public String getRegion() throws SdkClientException;
}

Built-in Region Providers

// Environment variable region provider
class AwsEnvVarOverrideRegionProvider extends AwsRegionProvider {
    public String getRegion() throws SdkClientException;
    public String toString();
}

// System property region provider
class AwsSystemPropertyRegionProvider extends AwsRegionProvider {
    public String getRegion() throws SdkClientException;
    public String toString();
}

// AWS profile region provider
class AwsProfileRegionProvider extends AwsRegionProvider {
    public AwsProfileRegionProvider();
    public AwsProfileRegionProvider(String profileName);
    public AwsProfileRegionProvider(String profilesConfigFilePath, String profileName);
    public String getRegion() throws SdkClientException;
    public String toString();
}

// EC2 instance metadata region provider
class InstanceMetadataRegionProvider extends AwsRegionProvider {
    public static InstanceMetadataRegionProvider getInstance();
    public InstanceMetadataRegionProvider();
    public String getRegion() throws SdkClientException;
    public String toString();
}

Endpoint Resolution

Endpoint Utilities

// Maps endpoints to regions
class EndpointToRegion {
    public static String guessRegionNameForEndpoint(String endpoint);
    public static String guessRegionNameForEndpoint(String endpoint, String serviceName);
}

// Region from endpoint metadata provider
class MetadataSupportedRegionFromEndpointProvider extends AwsRegionProvider {
    public MetadataSupportedRegionFromEndpointProvider();
    public String getRegion() throws SdkClientException;
}

Usage Examples

Basic Region Configuration

import com.amazonaws.regions.*;

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

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

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

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

// Get service endpoint for region
String s3Endpoint = region.getServiceEndpoint("s3");

Automatic Region Detection

import com.amazonaws.regions.*;

// Use default region provider chain
DefaultAwsRegionProviderChain regionProvider = 
    DefaultAwsRegionProviderChain.getInstance();

try {
    String regionName = regionProvider.getRegion();
    Region region = Region.getRegion(regionName);
    System.out.println("Detected region: " + regionName);
} catch (SdkClientException e) {
    System.err.println("Could not determine region: " + e.getMessage());
    // Fall back to default region
    Region region = Region.getRegion(Regions.US_EAST_1);
}

Custom Region Provider Chain

import com.amazonaws.regions.*;

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

try {
    String regionName = customChain.getRegion();
    Region region = Region.getRegion(regionName);
} catch (SdkClientException e) {
    // Handle no region found
}

Region from Endpoint

import com.amazonaws.regions.*;

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

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

Working with Service Endpoints

import com.amazonaws.regions.*;

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

// Check service support
if (region.isServiceSupported("dynamodb")) {
    String endpoint = region.getServiceEndpoint("dynamodb");
    boolean hasHttps = region.hasHttpsEndpoint("dynamodb");
    boolean hasHttp = region.hasHttpEndpoint("dynamodb");
    
    System.out.println("DynamoDB endpoint: " + endpoint);
    System.out.println("HTTPS supported: " + hasHttps);
    System.out.println("HTTP supported: " + hasHttp);
}

// Get all available service endpoints in region
Collection<String> availableServices = region.getAvailableEndpoints();
for (String serviceName : availableServices) {
    String endpoint = region.getServiceEndpoint(serviceName);
    System.out.println(serviceName + ": " + endpoint);
}

Custom Region Metadata

import com.amazonaws.regions.*;
import java.util.*;

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

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

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

// Use custom regions
Region customRegion = RegionUtils.getRegion("custom-region-1");

Environment Variables and System Properties

Environment Variables

  • AWS_REGION - The AWS region name
  • AWS_DEFAULT_REGION - Default region name (fallback)

System Properties

  • aws.region - The AWS region name

Profile Configuration

In ~/.aws/config:

[default]
region = us-west-2

[profile production]  
region = eu-west-1

[profile development]
region = us-east-1

Region Provider Chain Order

The DefaultAwsRegionProviderChain checks providers in this order:

  1. Environment Variables - AWS_REGION, AWS_DEFAULT_REGION
  2. System Properties - aws.region
  3. AWS Profile - Default profile or specified profile
  4. EC2 Instance Metadata - For EC2 instances

Partition Support

AWS has multiple partitions with different domain structures:

  • AWS Standard - amazonaws.com (most regions)
  • AWS China - amazonaws.com.cn (China regions)
  • AWS GovCloud - amazonaws.com (GovCloud regions)
import com.amazonaws.regions.*;

Region region = Region.getRegion(Regions.CN_NORTH_1);
String partition = region.getPartition(); // "aws-cn"
String domain = region.getDomain(); // "amazonaws.com.cn"

Best Practices

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

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

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

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

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

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

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

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

Install with Tessl CLI

npx tessl i tessl/maven-com-amazonaws--aws-java-sdk-core

docs

arn-support.md

authentication.md

client-builders.md

endpoint-discovery.md

exception-handling.md

http-transport.md

index.md

metrics-monitoring.md

protocols.md

regions-endpoints.md

retry-policies.md

utilities.md

waiters.md

tile.json