or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/maven-software-amazon-awssdk--apache-client

AWS Java SDK HTTP client implementation using Apache HttpComponents for robust HTTP communication with AWS services

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/software.amazon.awssdk/apache-client@2.32.x

To install, run

npx @tessl/cli install tessl/maven-software-amazon-awssdk--apache-client@2.32.0

index.mddocs/

Apache HTTP Client

AWS Java SDK HTTP client implementation using Apache HttpComponents for robust HTTP communication with AWS services. This library provides a full-featured synchronous HTTP client with support for connection pooling, SSL/TLS configuration, proxy authentication, and comprehensive metrics collection.

Note: This module is part of the AWS SDK for Java v2. It provides the Apache HttpComponents-based HTTP client implementation. For other AWS services, authentication, regions management, and the complete SDK functionality, you'll need additional AWS SDK modules. This documentation covers only the HTTP client transport layer.

Package Information

  • Package Name: apache-client
  • Package Type: maven
  • Group ID: software.amazon.awssdk
  • Module Name: software.amazon.awssdk.http.apache
  • Language: Java
  • Installation: 
    <dependency>
  <groupId>software.amazon.awssdk</groupId>
  <artifactId>apache-client</artifactId>
  <version>2.32.31</version>
</dependency>

Core Imports

import software.amazon.awssdk.http.apache.ApacheHttpClient;
import software.amazon.awssdk.http.apache.ProxyConfiguration;
import software.amazon.awssdk.http.SdkHttpClient;

Basic Usage

import software.amazon.awssdk.http.apache.ApacheHttpClient;
import software.amazon.awssdk.http.SdkHttpClient;
import java.time.Duration;

// Create client with default configuration
SdkHttpClient httpClient = ApacheHttpClient.create();

// Create client with custom configuration
SdkHttpClient customClient = ApacheHttpClient.builder()
    .socketTimeout(Duration.ofSeconds(30))
    .connectionTimeout(Duration.ofSeconds(10))
    .maxConnections(100)
    .build();

// Use with AWS SDK services (requires additional AWS SDK service modules)
// Example: aws-sdk-java-s3 module for S3Client
S3Client s3Client = S3Client.builder()
    .httpClient(customClient)
    .build();

// Always close the client when done
customClient.close();

Relationship to AWS SDK for Java v2

This apache-client module is one of several HTTP client implementations available in the AWS SDK for Java v2 ecosystem:

  • aws-sdk-java (BOM): Bill of Materials for managing all AWS SDK module versions
  • sdk-core: Core SDK functionality (request/response handling, signing, etc.)
  • regions: AWS regions and endpoints
  • auth: Authentication providers and credential chains
  • http-client-spi: HTTP client service provider interface
  • apache-client: This module - Apache HttpComponents HTTP client implementation
  • netty-nio-client: Async HTTP client using Netty (alternative to this module)
  • url-connection-client: Lightweight HTTP client using JDK URLConnection
  • s3, dynamodb, ec2, etc.: Individual AWS service clients (300+ available)

To use AWS services, you typically need:

  1. This HTTP client module (or an alternative)
  2. The specific AWS service client modules (e.g., s3, dynamodb)
  3. Core SDK modules (automatically included as dependencies)

Architecture

The Apache HTTP client is built around several key components:

  • ApacheHttpClient: Main client implementation that wraps Apache HttpComponents
  • Builder Pattern: Fluent configuration interface for all client settings
  • Connection Management: Automatic connection pooling and lifecycle management
  • Proxy Support: Comprehensive HTTP/HTTPS proxy configuration with authentication
  • Metrics Integration: Built-in metrics collection for monitoring and observability
  • Service Discovery: Automatic registration via Java Service Loader mechanism

Capabilities

HTTP Client Creation

Create and configure Apache HTTP client instances with various settings.

public static ApacheHttpClient.Builder builder()
public static SdkHttpClient create()
public static final String CLIENT_NAME = "Apache"

Client Configuration

The ApacheHttpClient.Builder interface provides comprehensive configuration options:

public interface Builder extends SdkHttpClient.Builder<ApacheHttpClient.Builder> {
    Builder socketTimeout(Duration socketTimeout);
    Builder connectionTimeout(Duration connectionTimeout);
    Builder connectionAcquisitionTimeout(Duration connectionAcquisitionTimeout);
    Builder maxConnections(Integer maxConnections);
    Builder proxyConfiguration(ProxyConfiguration proxyConfiguration);
    Builder localAddress(InetAddress localAddress);
    Builder expectContinueEnabled(Boolean expectContinueEnabled);
    Builder connectionTimeToLive(Duration connectionTimeToLive);
    Builder connectionMaxIdleTime(Duration maxIdleConnectionTimeout);
    Builder useIdleConnectionReaper(Boolean useConnectionReaper);
    Builder dnsResolver(DnsResolver dnsResolver);
    Builder socketFactory(ConnectionSocketFactory socketFactory);
    Builder httpRoutePlanner(HttpRoutePlanner proxyConfiguration);
    Builder credentialsProvider(CredentialsProvider credentialsProvider);
    Builder tcpKeepAlive(Boolean keepConnectionAlive);
    Builder tlsKeyManagersProvider(TlsKeyManagersProvider tlsKeyManagersProvider);
    Builder tlsTrustManagersProvider(TlsTrustManagersProvider tlsTrustManagersProvider);
    Builder authSchemeProviderRegistry(Registry<AuthSchemeProvider> authSchemeProviderRegistry);
}

Usage Example:

SdkHttpClient client = ApacheHttpClient.builder()
    .socketTimeout(Duration.ofSeconds(60))
    .connectionTimeout(Duration.ofSeconds(10))
    .connectionAcquisitionTimeout(Duration.ofSeconds(5))
    .maxConnections(200)
    .connectionTimeToLive(Duration.ofMinutes(5))
    .connectionMaxIdleTime(Duration.ofMinutes(1))
    .useIdleConnectionReaper(true)
    .tcpKeepAlive(true)
    .build();

HTTP Request Execution

Execute HTTP requests with metrics collection and resource management.

public ExecutableHttpRequest prepareRequest(HttpExecuteRequest request)
public void close()
public String clientName()

Usage Example:

// Prepare and execute request
ExecutableHttpRequest executableRequest = client.prepareRequest(httpRequest);
try {
    HttpExecuteResponse response = executableRequest.call();
    // Process response
} catch (IOException e) {
    // Handle execution error
} finally {
    // Request cleanup is automatic
}

Proxy Configuration

Configure HTTP and HTTPS proxy settings with authentication support.

public final class ProxyConfiguration {
    public static ProxyConfiguration.Builder builder()
    
    public String host()
    public int port()
    public String scheme()
    public String username()
    public String password()
    public String ntlmDomain()
    public String ntlmWorkstation()
    public Set<String> nonProxyHosts()
    public Boolean preemptiveBasicAuthenticationEnabled()
    public String resolveScheme()
    public ProxyConfiguration.Builder toBuilder()
}
public interface Builder extends CopyableBuilder<Builder, ProxyConfiguration> {
    Builder endpoint(URI endpoint);
    Builder username(String username);
    Builder password(String password);
    Builder ntlmDomain(String proxyDomain);
    Builder ntlmWorkstation(String proxyWorkstation);
    Builder nonProxyHosts(Set<String> nonProxyHosts);
    Builder addNonProxyHost(String nonProxyHost);
    Builder preemptiveBasicAuthenticationEnabled(Boolean preemptiveBasicAuthenticationEnabled);
    Builder useSystemPropertyValues(Boolean useSystemPropertyValues);
    Builder useEnvironmentVariableValues(Boolean useEnvironmentVariableValues);
    Builder scheme(String scheme);
}

Usage Examples:

// Basic proxy configuration
ProxyConfiguration basicProxy = ProxyConfiguration.builder()
    .endpoint(URI.create("http://proxy.example.com:8080"))
    .build();

// Authenticated proxy with credentials
ProxyConfiguration authProxy = ProxyConfiguration.builder()
    .endpoint(URI.create("https://secure-proxy.example.com:3128"))
    .username("proxyuser")
    .password("proxypass")
    .preemptiveBasicAuthenticationEnabled(true)
    .build();

// NTLM proxy for Windows environments
ProxyConfiguration ntlmProxy = ProxyConfiguration.builder()
    .endpoint(URI.create("http://corporate-proxy.internal:8080"))
    .username("domain\\username")
    .password("password")
    .ntlmDomain("CORPORATE")
    .ntlmWorkstation("WORKSTATION01")
    .build();

// Proxy with non-proxy hosts
ProxyConfiguration selectiveProxy = ProxyConfiguration.builder()
    .endpoint(URI.create("http://proxy.example.com:8080"))
    .addNonProxyHost("localhost")
    .addNonProxyHost("*.internal.com")
    .addNonProxyHost("192.168.*")
    .build();

// Use proxy configuration with client
SdkHttpClient client = ApacheHttpClient.builder()
    .proxyConfiguration(authProxy)
    .build();

Service Registration

Automatic service discovery for AWS SDK integration.

public class ApacheSdkHttpService implements SdkHttpService {
    public SdkHttpClient.Builder createHttpClientBuilder()
}

The service is automatically registered via the Java Service Loader mechanism in META-INF/services/software.amazon.awssdk.http.SdkHttpService.

Types

Core Types

// From AWS SDK Core
public interface SdkHttpClient extends Closeable {
    ExecutableHttpRequest prepareRequest(HttpExecuteRequest request);
    String clientName();
    void close();
}

public interface ExecutableHttpRequest {
    HttpExecuteResponse call() throws IOException;
    void abort();
}

Configuration Types

// From Apache HttpComponents
import org.apache.http.conn.DnsResolver;
import org.apache.http.conn.socket.ConnectionSocketFactory;
import org.apache.http.conn.routing.HttpRoutePlanner;
import org.apache.http.client.CredentialsProvider;
import org.apache.http.config.Registry;
import org.apache.http.auth.AuthSchemeProvider;

// From AWS SDK
import software.amazon.awssdk.http.TlsKeyManagersProvider;
import software.amazon.awssdk.http.TlsTrustManagersProvider;

Error Handling

The Apache HTTP client can throw various exceptions during operation:

  • IOException: Network connectivity issues, timeouts, or server errors
  • IllegalArgumentException: Invalid configuration parameters (e.g., conflicting proxy and route planner settings)
  • SSLInitializationException: SSL context setup failures
  • RuntimeException: Unexpected errors during client operation

Common Error Handling Pattern:

SdkHttpClient client = ApacheHttpClient.builder()
    .socketTimeout(Duration.ofSeconds(30))
    .build();

try {
    ExecutableHttpRequest request = client.prepareRequest(httpRequest);
    HttpExecuteResponse response = request.call();
    // Process successful response
} catch (IOException e) {
    // Handle network/timeout errors
    log.error("HTTP request failed", e);
} finally {
    client.close();
}

Complete AWS SDK Integration Example

// Complete example showing integration with AWS services
import software.amazon.awssdk.services.s3.S3Client;
import software.amazon.awssdk.services.s3.model.ListBucketsRequest;
import software.amazon.awssdk.services.s3.model.ListBucketsResponse;
import software.amazon.awssdk.http.apache.ApacheHttpClient;
import software.amazon.awssdk.http.apache.ProxyConfiguration;
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.http.SdkHttpClient;
import java.net.URI;
import java.time.Duration;

// 1. Configure the Apache HTTP client
SdkHttpClient httpClient = ApacheHttpClient.builder()
    .socketTimeout(Duration.ofSeconds(30))
    .connectionTimeout(Duration.ofSeconds(10))
    .maxConnections(50)
    .proxyConfiguration(ProxyConfiguration.builder()
        .endpoint(URI.create("http://proxy.example.com:8080"))
        .build())
    .build();

// 2. Create AWS service client using the HTTP client
S3Client s3Client = S3Client.builder()
    .region(Region.US_EAST_1)
    .httpClient(httpClient)
    .build();

try {
    // 3. Use the service client
    ListBucketsResponse response = s3Client.listBuckets(ListBucketsRequest.builder().build());
    response.buckets().forEach(bucket -> 
        System.out.println("Bucket: " + bucket.name()));
} finally {
    // 4. Clean up resources
    s3Client.close();
    httpClient.close();
}

This example demonstrates:

  • Configuring the Apache HTTP client with custom settings
  • Using the HTTP client with an AWS service (S3)
  • Proper resource management and cleanup

Required Dependencies:

<dependencies>
    <!-- HTTP Client Implementation -->
    <dependency>
        <groupId>software.amazon.awssdk</groupId>
        <artifactId>apache-client</artifactId>
        <version>2.32.31</version>
    </dependency>
    
    <!-- AWS Service Client (example: S3) -->
    <dependency>
        <groupId>software.amazon.awssdk</groupId>
        <artifactId>s3</artifactId>
        <version>2.32.31</version>
    </dependency>
</dependencies>

Advanced Configuration

Custom SSL Configuration

// Custom trust managers for SSL
TlsTrustManagersProvider customTrustProvider = () -> {
    // Return custom trust managers
    return new TrustManager[] { /* custom managers */ };
};

SdkHttpClient client = ApacheHttpClient.builder()
    .tlsTrustManagersProvider(customTrustProvider)
    .build();

Connection Pool Tuning

// High-throughput configuration
SdkHttpClient client = ApacheHttpClient.builder()
    .maxConnections(500)
    .connectionTimeToLive(Duration.ofMinutes(10))
    .connectionMaxIdleTime(Duration.ofMinutes(2))
    .useIdleConnectionReaper(true)
    .tcpKeepAlive(true)
    .build();

Custom DNS Resolution

import org.apache.http.conn.DnsResolver;

DnsResolver customResolver = hostname -> {
    // Custom DNS resolution logic
    return new InetAddress[] { /* resolved addresses */ };
};

SdkHttpClient client = ApacheHttpClient.builder()
    .dnsResolver(customResolver)
    .build();