CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/maven-software-amazon-awssdk--url-connection-client

HTTP client implementation using Java's URLConnection for the AWS SDK for Java 2.0

Overview
Eval results
Files

http-client-configuration.mddocs/

HTTP Client Configuration

This document covers configuring the UrlConnectionHttpClient with various options including timeouts, TLS settings, and proxy configuration.

Creating HTTP Clients

Basic Client Creation

// Create with default settings
public static SdkHttpClient create();

// Create with custom connection factory
public static SdkHttpClient create(UrlConnectionFactory connectionFactory);

// Create via builder pattern
public static Builder builder();

Usage Examples

import software.amazon.awssdk.http.urlconnection.UrlConnectionHttpClient;
import software.amazon.awssdk.http.SdkHttpClient;
import java.net.HttpURLConnection;
import java.time.Duration;

// Default client
SdkHttpClient defaultClient = UrlConnectionHttpClient.create();

// Custom connection factory
SdkHttpClient customClient = UrlConnectionHttpClient.create(uri -> {
    HttpURLConnection connection = (HttpURLConnection) uri.toURL().openConnection();
    connection.setConnectTimeout(5000);
    return connection;
});

// Builder-configured client
SdkHttpClient builderClient = UrlConnectionHttpClient.builder()
    .connectionTimeout(Duration.ofSeconds(10))
    .socketTimeout(Duration.ofSeconds(30))
    .build();

Builder Configuration

The UrlConnectionHttpClient.Builder provides fluent configuration options:

public interface Builder extends SdkHttpClient.Builder<UrlConnectionHttpClient.Builder> {
    // Timeout configuration
    Builder socketTimeout(Duration socketTimeout);
    Builder connectionTimeout(Duration connectionTimeout);
    
    // TLS configuration
    Builder tlsKeyManagersProvider(TlsKeyManagersProvider tlsKeyManagersProvider);
    Builder tlsTrustManagersProvider(TlsTrustManagersProvider tlsTrustManagersProvider);
    
    // Proxy configuration
    Builder proxyConfiguration(ProxyConfiguration proxyConfiguration);
    Builder proxyConfiguration(Consumer<ProxyConfiguration.Builder> proxyConfigurationBuilderConsumer);
}

Timeout Configuration

import software.amazon.awssdk.http.urlconnection.UrlConnectionHttpClient;
import software.amazon.awssdk.http.SdkHttpClient;
import java.time.Duration;

SdkHttpClient client = UrlConnectionHttpClient.builder()
    .connectionTimeout(Duration.ofSeconds(5))   // Time to establish connection
    .socketTimeout(Duration.ofSeconds(30))      // Time to wait for data
    .build();

TLS Configuration

import software.amazon.awssdk.http.urlconnection.UrlConnectionHttpClient;
import software.amazon.awssdk.http.SdkHttpClient;
import software.amazon.awssdk.http.TlsKeyManagersProvider;
import software.amazon.awssdk.http.TlsTrustManagersProvider;
import java.nio.file.Paths;

SdkHttpClient client = UrlConnectionHttpClient.builder()
    .tlsKeyManagersProvider(TlsKeyManagersProvider.fileStore(
        Paths.get("client-keystore.p12"), "password"))
    .tlsTrustManagersProvider(TlsTrustManagersProvider.systemDefault())
    .build();

Proxy Configuration with Builder

import software.amazon.awssdk.http.urlconnection.UrlConnectionHttpClient;
import software.amazon.awssdk.http.SdkHttpClient;
import java.net.URI;

SdkHttpClient client = UrlConnectionHttpClient.builder()
    .proxyConfiguration(proxy -> proxy
        .endpoint(URI.create("http://proxy.example.com:8080"))
        .username("proxyuser")
        .password("proxypass"))
    .build();

Client Operations

public final class UrlConnectionHttpClient implements SdkHttpClient {
    // Request preparation
    public ExecutableHttpRequest prepareRequest(HttpExecuteRequest request);
    
    // Client identification
    public String clientName();
    
    // Resource cleanup (no-op for URLConnection)
    public void close();
}

Usage in AWS SDK

import software.amazon.awssdk.http.urlconnection.UrlConnectionHttpClient;
import software.amazon.awssdk.services.s3.S3Client;
import java.time.Duration;

// Configure S3 client with custom HTTP client
S3Client s3Client = S3Client.builder()
    .httpClient(UrlConnectionHttpClient.builder()
        .connectionTimeout(Duration.ofSeconds(10))
        .socketTimeout(Duration.ofSeconds(60))
        .build())
    .build();

Custom Connection Factory

For advanced use cases, you can provide a custom UrlConnectionFactory:

@FunctionalInterface
public interface UrlConnectionFactory {
    HttpURLConnection createConnection(URI uri);
}

Custom Factory Example

import software.amazon.awssdk.http.urlconnection.UrlConnectionHttpClient;
import software.amazon.awssdk.http.urlconnection.UrlConnectionFactory;
import software.amazon.awssdk.http.SdkHttpClient;
import java.net.HttpURLConnection; 
import java.net.URI;

UrlConnectionFactory customFactory = uri -> {
    HttpURLConnection connection = (HttpURLConnection) uri.toURL().openConnection();
    
    // Custom configuration
    connection.setConnectTimeout(5000);
    connection.setReadTimeout(30000);
    connection.setRequestProperty("User-Agent", "MyApp/1.0");
    
    return connection;
};

SdkHttpClient client = UrlConnectionHttpClient.create(customFactory);

Note: When using a custom connection factory, SDK defaults for timeouts and other configurations are ignored. You must configure the HttpURLConnection directly.

Exception Handling

The URL Connection HTTP Client can throw various exceptions during operation:

import software.amazon.awssdk.http.urlconnection.UrlConnectionHttpClient;
import software.amazon.awssdk.http.SdkHttpClient;
import java.io.IOException;
import java.io.UncheckedIOException;

try {
    SdkHttpClient client = UrlConnectionHttpClient.create();
    
    // HTTP operations can throw IOException
    ExecutableHttpRequest request = client.prepareRequest(httpRequest);
    HttpExecuteResponse response = request.call();
    
} catch (UncheckedIOException e) {
    // Wraps IOException from underlying URLConnection
    IOException cause = e.getCause();
    // Handle network errors, timeouts, etc.
} catch (IOException e) {
    // Direct IOException from HTTP operations
    // Handle connection errors, response reading errors, etc.
}

Common Exception Scenarios

  • Connection timeout: When connectionTimeout is exceeded during connection establishment
  • Read timeout: When socketTimeout is exceeded waiting for response data
  • Proxy authentication: When proxy credentials are invalid or missing
  • SSL/TLS errors: When certificate validation fails or SSL handshake problems occur
  • Expect 100-continue handling: URLConnection has limitations with Expect: 100-continue headers

Types

// HTTP client builder interface
public interface Builder extends SdkHttpClient.Builder<UrlConnectionHttpClient.Builder> {
    // Fluent builder methods
    Builder socketTimeout(Duration socketTimeout);
    Builder connectionTimeout(Duration connectionTimeout);
    Builder tlsKeyManagersProvider(TlsKeyManagersProvider tlsKeyManagersProvider);
    Builder tlsTrustManagersProvider(TlsTrustManagersProvider tlsTrustManagersProvider);
    Builder proxyConfiguration(ProxyConfiguration proxyConfiguration);
    Builder proxyConfiguration(Consumer<ProxyConfiguration.Builder> proxyConfigurationBuilderConsumer);
    
    // JavaBean setter methods (for framework integration)
    void setSocketTimeout(Duration socketTimeout);
    void setConnectionTimeout(Duration connectionTimeout);
    void setTlsKeyManagersProvider(TlsKeyManagersProvider tlsKeyManagersProvider);
    void setTlsTrustManagersProvider(TlsTrustManagersProvider tlsTrustManagersProvider);
    void setProxyConfiguration(ProxyConfiguration proxyConfiguration);
    
    // Build method
    SdkHttpClient buildWithDefaults(AttributeMap serviceDefaults);
}

// Connection factory interface
@FunctionalInterface
public interface UrlConnectionFactory {
    HttpURLConnection createConnection(URI uri);
}

Install with Tessl CLI

npx tessl i tessl/maven-software-amazon-awssdk--url-connection-client

docs

http-client-configuration.md

index.md

proxy-configuration.md

service-integration.md

tile.json